[typist] Type Consistency Analysis — A (Mostly) Clean Bill of Health

[github-actions[bot]]

🔤 Typist — Go Type Consistency Analysis

Analysis of repository: github/gh-aw · 2026-06-09

Executive Summary

Good news first: this is a well-typed codebase. I swept every non-test .go file under pkg/ (~894 files, ~682 distinct named type definitions) looking for duplicated type definitions and weakly-typed code, and I came away impressed rather than alarmed. There are no genuine exact-duplicate type definitions — the only repeated struct names (SpinnerWrapper, ProgressBar, RepositoryFeatures) are intentional _wasm.go build-tag variants, which is exactly how you are supposed to do it. The team has also already migrated essentially 100% off interface{} (only 7 occurrences remain, all inside linter test fixtures) and maintains a healthy set of 44 named scalar types (EngineName, ModelName, PermissionLevel, ...). That is real discipline.

That said, I did find a few concrete, low-risk opportunities worth a look: one textbook generics candidate (two structurally-identical delta types), a small cluster of the same untyped field re-declared across packages (On/RunsOn), and a large but mostly-justified population of map[string]any driven by GitHub Actions YAML emission. None of these are fires — think of them as tidy-up wins, prioritized below.

Full Analysis Report

Duplicated Type Definitions

Summary Statistics

• Distinct named types analyzed: ~682
• Exact-name duplicate clusters: 3 — all build-tag variants (not actionable)
• Structural (semantic) near-duplicate clusters: 1 actionable

Cluster 1: AuditComparisonIntDelta / AuditComparisonStringDelta — structural duplicates

Type: Near/semantic duplicate (identical shape, differing field type)
Occurrences: 2 type definitions, same file
Impact: Low-risk, moderate value — references are contained to one file (buildAuditComparison)

Locations:

1. pkg/cli/audit_comparison.go:44 — type AuditComparisonIntDelta struct
2. pkg/cli/audit_comparison.go:50 — type AuditComparisonStringDelta struct

Definition comparison — identical except Before/After element type:

type AuditComparisonIntDelta struct {
    Before  int  `json:"before"`
    After   int  `json:"after"`
    Changed bool `json:"changed"`
}
type AuditComparisonStringDelta struct {
    Before  string `json:"before"`
    After   string `json:"after"`
    Changed bool   `json:"changed"`
}

Recommendation — unify with a generic type:

type ComparisonDelta[T comparable] struct {
    Before  T    `json:"before"`
    After   T    `json:"after"`
    Changed bool `json:"changed"`
}
// AuditComparisonIntDelta    -> ComparisonDelta[int]
// AuditComparisonStringDelta -> ComparisonDelta[string]

• Estimated effort: ~30 min (references live only in pkg/cli/audit_comparison.go)
• Benefits: single source of truth for the before/after/changed shape; future delta value-types (float, duration) come for free.
• Note: the outer name AuditComparisonDelta is already taken by the aggregate struct, so pick e.g. ComparisonDelta[T].

Why there is nothing else here

The build-tag pairs below are correct Go idiom, not duplication — please do not consolidate them:

Type	Files
SpinnerWrapper	pkg/console/spinner.go + spinner_wasm.go
ProgressBar	pkg/console/progress.go + progress_wasm.go
RepositoryFeatures	pkg/workflow/repository_features_validation.go + _wasm.go

---

Untyped Usages

Summary Statistics

• interface{} occurrences: 7 — all in pkg/linters/.../testdata/ fixtures (intentional; ignore)
• any word-occurrences: ~3541
• map[string]any: 2034 (concentrated: pkg/workflow 219 files, pkg/cli 104, pkg/parser 19)
• []any: 393
• Functions taking an any parameter: 760 (only 3 variadic)
• Struct fields typed bare any: ~30

Category 1: Repeated untyped fields for the same concept (best opportunity)

Impact: Medium — the same GitHub Actions field is independently re-declared as any in multiple structs across two packages. This is both an untyped usage and a near-duplicate.

On any (4 sites) and RunsOn any (3 sites):

pkg/cli/status_command.go:35            On      any
pkg/cli/list_workflows_command.go:25    On      any
pkg/cli/jsonworkflow_to_markdown.go:38  On      any
pkg/cli/copilot_setup.go:157            On      any
pkg/workflow/safe_jobs.go:20            RunsOn  any
pkg/workflow/frontmatter_types.go:329   RunsOn  any
pkg/cli/copilot_setup.go:149            RunsOn  any

Context: these mirror the GitHub Actions schema where on: / runs-on: legitimately accept string | array | object. Go cannot express that union, so any is defensible — but the concept is currently undocumented and re-invented per struct.

Suggested fix — centralize one named, documented type in a shared package (e.g. pkg/types):

// RunsOnValue is a GitHub Actions runner spec: string, []string, or a group object.
type RunsOnValue = any   // alias keeps marshaling behavior, adds intent + a single doc site

• Benefits: one documented home for the union, greppable, a natural place to later hang UnmarshalYAML validation.

Category 2: Polymorphic schema fields (mostly leave as-is)

Impact: Low — these are genuine string|array|object|bool YAML/JSON fields. Strong typing would require union types Go lacks; any is idiomatic here. Listed for transparency, not flagged for change:

View the ~30 bare-any struct fields

pkg/workflow/frontmatter_types.go  Engine, RunsOn, Imports, Include, Checkout, Headers(x2), Endpoint
pkg/workflow/step_types.go:28      ContinueOnError   // bool or string expression
pkg/workflow/create_issue.go:20    DeduplicateByTitle // bool or int
pkg/workflow/service_ports.go:50   Ports
pkg/workflow/safe_jobs.go:20       RunsOn
pkg/workflow/tools_types.go        Raw (x2), repo_memory.go Raw  // raw passthrough
pkg/types/input_definition.go:18   Default  // string|number|bool input default
pkg/console/console_types.go:46    Value    // generic result pointer for a form field

One narrow win in this set — JSON-RPC / run identifiers declared any to accept "string or number":

pkg/cli/gateway_logs_types.go:148  ID         any
pkg/cli/logs_models.go:304         RunID      any
pkg/cli/logs_models.go:305         RunNumber  any

These could use json.Number (or a tiny StringOrNumber type) to make the "string-or-number" contract explicit and avoid downstream switch v := id.(type) assertions. Low priority, but cleaner.

Category 3: Untyped constants

I deliberately did not flag Go's ordinary untyped constants (const MaxRetries = 5) — that is idiomatic Go, and mechanically typing all of them would add noise, not safety. The codebase already promotes meaningful enums to named string/int types (44 of them), which is the right pattern. No action recommended here.

Category 4: map[string]any volume

2034 occurrences sounds scary but is largely legitimate: this is a workflow compiler that parses arbitrary frontmatter and emits GitHub Actions YAML, where dynamic maps are unavoidable at the boundary. The concentration (pkg/workflow, pkg/cli, pkg/parser) matches exactly the YAML/JSON serialization layer. Recommend leaving these alone except where a known, fixed schema is being passed around internally (case-by-case, not a sweep).

---

Recommendations (prioritized)

Priority 1 — Unify the delta structs with generics

• Replace AuditComparisonIntDelta + AuditComparisonStringDelta with ComparisonDelta[T comparable].
• Effort: ~30 min · Impact: removes the only real structural duplicate · Risk: minimal (single file).

Priority 2 — Centralize the On / RunsOn union

• Introduce one documented RunsOnValue / OnValue alias in a shared types package and reference it from the 7 sites.
• Effort: 1-2 h · Impact: documents intent, kills the cross-package re-declaration · Risk: low (alias preserves marshaling).

Priority 3 — Tighten string-or-number identifiers

• Swap the ID / RunID / RunNumber any fields to json.Number or a small StringOrNumber type.
• Effort: 1-2 h · Impact: explicit contract, fewer type assertions · Risk: low-medium (verify all decode paths).

Implementation checklist

• P1: introduce ComparisonDelta[T], update buildAuditComparison, run pkg/cli tests
• P2: add RunsOnValue/OnValue to shared types, repoint 7 fields
• P3: evaluate json.Number for ID/RunID/RunNumber
• Leave build-tag _wasm.go pairs untouched
• Leave boundary map[string]any / polymorphic schema fields untouched
• go build ./... && go test ./pkg/cli/... ./pkg/workflow/...

Analysis Metadata

• Go files analyzed: ~894 (non-test, pkg/)
• Distinct named types: ~682 · named scalar types: 44
• Exact duplicate clusters: 0 actionable (3 build-tag variants) · structural near-dups: 1
• interface{}: 7 (all test fixtures) · any: ~3541 · map[string]any: 2034
• Detection method: Serena LSP (project activation, find_referencing_symbols) + pattern matching
• Analysis date: 2026-06-09

References: §27205569285

Generated by ✍️ Typist - Go Type Analysis · 275.6 AIC · ⌖ 15.6 AIC · ⊞ 9.3K · ◷

• expires on Jun 10, 2026, 4:30 AM UTC-08:00

[github-actions[bot]]

This discussion was automatically closed because it expired on 2026-06-10T12:30:59.531Z.

Closed by Workflow