[typist] Typist: Go type consistency findings in pkg/ (duplicate types & untyped constants)

[github-actions[bot]]

🔤 Typist - Go Type Consistency Analysis

Analysis of repository: github/gh-aw

Executive Summary

Scanned 1,798 non-test .go files under pkg/ (1,848 type definitions collected via Serena semantic analysis). The codebase has already fully migrated off bare interface{} in production code — only 2 occurrences remain, both inside comments — so the untyped-usage opportunity is narrower than usual: it's a handful of string-constant clusters that behave like unenforced enums, not raw interface{}/any misuse (the ~22,700 any usages found are overwhelmingly legitimate, mirroring genuinely polymorphic GitHub Actions/YAML schema fields such as on:, needs:, permissions:).

On the duplication side, an initial automated clustering pass over 1,848 types surfaced several same-named types; after manual verification, 3 are genuine structural duplicates/near-duplicates worth consolidating, and 5 independently-reinvented "Finding/Diagnostic" shapes across different static-analysis subsystems stand out as the highest-value consolidation target. Several other same-name matches (e.g. ValidationError, LogParser, SourceLocation) turned out on inspection to be unrelated types that merely share a name, and are called out below as false positives rather than real duplication.

Full Analysis Report

Duplicated Type Definitions

Summary Statistics

• Go files analyzed (pkg/, non-test): 1,798
• Type definitions collected: 1,848
• Verified duplicate clusters: 4
• Exact duplicates: 1 (StepID)
• Near duplicates: 2 (runtimeImportReference, graderManifestEntry)
• Semantic duplicates: 1 cluster of 5 types (the "Finding/Diagnostic" family)
• False positives discarded after verification: ValidationError (interface vs. struct), LogParser (generic func type vs. interface), SourceLocation (completely unrelated field sets — name-only collision)

Cluster 1: StepID — Exact Duplicate

Impact: Low-Medium — two unrelated string types share a name and shape; nothing stops a value typed for one package being silently reused where the other is expected.

Locations:

1. pkg/constants/job_constants.go:31 — type StepID string (plus a String() method)
2. pkg/workflow/actions/ids.go:9 — type StepID string (declared alongside sibling JobID/OutputName)

Recommendation: Pick one canonical StepID (likely pkg/workflow/actions, since it already groups JobID/StepID/OutputName as a family) and have the other package import/alias it instead of redeclaring.
Estimated effort: ~1 hour. Benefit: removes a confusing same-name/same-shape type that could mask an accidental cross-package mix-up.

---

Cluster 2: runtimeImportReference — Near Duplicate

Impact: Low (both unexported, package-local) but a clear case of copy-paste drift.

Locations:

1. pkg/parser/frontmatter_hash.go:569 — struct { path string; startLine int; endLine int }
2. pkg/workflow/runtime_import_validation.go:38 — struct { importPath string; startLine int; endLine int }

Identical shape (one string + two ints describing a source-line span for an import reference); only the first field's name differs (path vs importPath).

Recommendation: Factor into one small shared type (e.g. in pkg/parser or a tiny shared helper package both already depend on) and have pkg/workflow consume it.
Estimated effort: ~1 hour.

---

Cluster 3: graderManifestEntry — Near Duplicate

Impact: Medium — this is a schema used both at compile time and at audit/report time; if one copy gains a field the other doesn't, the manifest format can silently diverge between the two.

Locations:

1. pkg/cli/audit_report_graders.go:67 — ID, Name, Unit, Direction, Threshold
2. pkg/workflow/compiler_yaml_graders.go:13 — ID, Name, Description, Source, Enabled, Unit, Direction, Threshold

The cli version is a strict subset of the workflow version's fields.

Recommendation: Define the richer workflow shape once in a shared location and have pkg/cli/audit_report_graders.go embed it (or import it directly) rather than redeclaring a trimmed-down copy.
Estimated effort: 2-3 hours (touches both packages' JSON (de)serialization call sites). Benefit: single source of truth for the grader manifest schema.

---

Cluster 4: The "Finding/Diagnostic" shape, reinvented 5 times (Semantic Duplicates)

Impact: Medium-High — this is the biggest real opportunity found. Five different packages each independently define a "located static-analysis result" type, with no shared base:

1. pkg/scanfindings/scanfindings.go:107 Finding — RuleID, Severity, Message, File, Line, Column (+Context)
2. pkg/workflow/taint/taint.go:43 Finding — RuleID, Site, Sources
3. pkg/workflow/gradershell/check.go:14 Finding — Line, Message
4. pkg/workflow/actionslanguageservice/workflow.go:49 Diagnostic — File, Line, Column, Message
5. pkg/workflow/lint/lint.go:62 Diagnostic — RuleID, ThreatRuleID, Severity, Path, Line, Message

All five represent a rule violation located in a file, and the common fields (Line/Message in all five; File/Path, RuleID, Severity in most) have already started drifting — only 2 of the 5 carry a Severity, and the location field is named inconsistently (File vs Path).

Recommendation: Introduce one small shared Location{File, Line, Column} and BaseFinding{RuleID, Severity, Message, Location} (a natural home is the existing pkg/scanfindings package), and have the other four embed it while keeping their package-specific extra fields (Site/Sources for taint, ThreatRuleID for lint). This does not force a single universal type — it just stops the common quad (RuleID/location/Message) from being retyped five times.
Estimated effort: 4-6 hours (touches 5 packages and their call sites). Benefit: new fields (e.g. an "end line" or a normalized Severity enum) get added once instead of being forgotten in 4 of 5 places.

Lower-confidence notes (same name, likely intentionally separate — not recommended for merging, flagged for awareness only):

• lint.Rule vs taint.Rule: same name, but one is a whole-AST Check(Input) ([]Diagnostic, error) function and the other is a dataflow source/sink/filter predicate set — different analysis paradigms, probably correct to keep separate.
• workflow.Job/workflow.Workflow vs actions.Job/actions.Workflow: the former is the compiler's flat emission model (plain strings), the latter is a richer typed AST-like model (JobID, Expression, Step) used by the generic Actions-YAML tooling in pkg/workflow/actions. Likely correct to keep as two layers, but the identical naming under the same pkg/workflow/* tree is a readability risk worth a doc comment pointing each at the other.
• A few "Report ⇄ Summary" pairs in pkg/cli/logs_models.go (MissingToolReport/MissingToolSummary, MissingDataReport/MissingDataSummary, MCPFailureReport/MCPFailureSummary) looked like duplicates at a glance but are actually a consistent, deliberate detail-vs-aggregate pattern — not flagged as an issue.

---

Untyped Usages

Summary Statistics

• interface{} usages in non-test pkg/ code: 2, both inside comments (pkg/cli/mcp_schema.go:121, pkg/workflow/behavior_defined_engine.go:917) — production code has fully migrated to the any alias.
• any usages: ~22,700 occurrences across 1,557 of 1,798 files — the overwhelming majority are legitimate generic handling of YAML/JSON-decoded workflow frontmatter and GitHub Actions schema fields that are themselves polymorphic (map[string]any, []any), plus explicitly-documented generic numeric/string conversion helpers (pkg/typeutil/convert.go). Per the what-to-skip guidance, these are not flagged.
• Untyped constant clusters flagged: 3 (out of hundreds of plain string/int constants, most of which are ordinary fixed identifiers/paths/messages and not a type-safety concern)

Category 1: Job-output name constants acting as an unenforced enum

Impact: Low-Medium — 10 of these constants are consumed as plain string by 3 call sites (pkg/workflow/known_needs_expressions.go, pkg/workflow/compiler_pre_activation_job.go, pkg/workflow/compiler_activation_outputs.go), so an arbitrary string literal is accepted anywhere one of these is expected.

Location: pkg/constants/job_constants.go:326-337

const IsTeamMemberOutput = "is_team_member"
const StopTimeOkOutput = "stop_time_ok"
const SkipCheckOkOutput = "skip_check_ok"
// ... 7 more ...
const ActivatedOutput = "activated"

Suggested fix:

type JobOutputName string

const (
    IsTeamMemberOutput JobOutputName = "is_team_member"
    StopTimeOkOutput   JobOutputName = "stop_time_ok"
    // ...
    ActivatedOutput    JobOutputName = "activated"
)

Estimated effort: 1-2 hours.

Category 2: Mismatch-reason string constants

Impact: Low.

Location: pkg/cli/token_usage_types.go:309-311

const modelMismatchReasonTokenUsageMissing = "TOKEN_USAGE_MISSING"
const modelMismatchReasonModelNotObserved = "REQUESTED_MODEL_NOT_OBSERVED"
const modelMismatchReasonSubagentFailed = "SUBAGENT_FAILED"

Three mutually-exclusive reason codes, indistinguishable at the type level from the unrelated event-name constants declared two lines below them.

Suggested fix: type ModelMismatchReason string, applied to all three.
Estimated effort: <1 hour.

Category 3: Auth-method string constants

Impact: Low (package-private, only 2 values) — included as a clean, minimal example of the pattern.

Location: pkg/cli/add_interactive_engine.go:238-239

const authMethodCopilotRequests = "copilot-requests"
const authMethodPAT = "pat"

Compared via == against a plain-string wizard selection at lines 291, 324 and 331.

Suggested fix: type authMethod string, typing the wizard value accordingly so a typo'd literal can't silently fail the comparison.
Estimated effort: <1 hour.

Note on things intentionally not flagged: struct fields explicitly typed any for documented polymorphism were checked and excluded, e.g. observabilityImportEndpoint.Headers any (pkg/parser/import_observability.go:18, commented as kept as any so the workflow package can later normalise both supported forms), On any/Needs any in pkg/cli/list_workflows_command.go and pkg/cli/runner_guard_activation_gate.go (mirroring GitHub Actions' own polymorphic on:/needs: schema), and the registry/audit map[string]any metadata bags — all correctly generic, not refactor candidates.

---

Refactoring Recommendations

Priority 1: Medium-High — Unify the "Finding/Diagnostic" family

Recommendation: Introduce a shared Location/BaseFinding type in pkg/scanfindings and have taint.Finding, gradershell.Finding, actionslanguageservice.Diagnostic, and lint.Diagnostic embed it.
Estimated effort: 4-6 hours. Impact: stops the same 5 fields from drifting independently across 5 static-analysis subsystems.

Priority 2: Medium — Single source of truth for the grader manifest entry

Recommendation: Keep one graderManifestEntry definition (the richer pkg/workflow/compiler_yaml_graders.go version) and have pkg/cli/audit_report_graders.go reuse it instead of redeclaring a subset.
Estimated effort: 2-3 hours.

Priority 3: Low — Remove the StepID/runtimeImportReference duplicates

Recommendation: Consolidate StepID into one package (pkg/workflow/actions is the natural home) and factor runtimeImportReference into one shared struct.
Estimated effort: ~2 hours combined.

Priority 4: Low — Add semantic types to the 3 constant clusters identified

Recommendation: Introduce JobOutputName, ModelMismatchReason, and authMethod string types for the clusters above.
Estimated effort: ~2-3 hours combined.

---

Implementation Checklist

• Consolidate StepID into a single package
• Factor runtimeImportReference into one shared struct
• Make graderManifestEntry a single shared definition (pkg/cli reuses the pkg/workflow shape)
• Introduce Location/BaseFinding in pkg/scanfindings and embed it in taint.Finding, gradershell.Finding, actionslanguageservice.Diagnostic, lint.Diagnostic
• Add JobOutputName type to the 12 job-output constants in pkg/constants/job_constants.go
• Add ModelMismatchReason type to the 3 reason constants in pkg/cli/token_usage_types.go
• Add authMethod type to the 2 constants in pkg/cli/add_interactive_engine.go
• Run full test suite after each consolidation step

Analysis Metadata

• Total Go files analyzed: 1,798 (pkg/, non-test)
• Total type definitions collected: 1,848
• Verified duplicate clusters: 4 (1 exact, 2 near, 1 semantic cluster of 5 types)
• Untyped constant clusters flagged: 3
• Detection method: Serena semantic analysis (get_symbols_overview, find_symbol) + targeted pattern search, with manual verification of every reported cluster before inclusion
• Analysis date: 2026-10-30

Generated by ✍️ Typist - Go Type Analysis · claude · agent · ~166 AIC · ⌖ ~1 AIC · ⊞ 4.5K · ◷

• expires on Oct 31, 2026, 3:34 AM UTC-08:00

[github-actions[bot]]

This discussion was automatically closed because it expired on 2026-10-31T11:34:24.984Z.

Closed by Workflow