[typist] Typist - Go Type Consistency Analysis

[github-actions[bot]]

🔤 Typist - Go Type Consistency Analysis

Analysis of repository: github/gh-aw — 917 non-test .go files under pkg/

Executive Summary

Good news first: this codebase has strong type discipline. I scanned all 917 non-test Go files under pkg/ (≈941 type definitions) looking for the same type defined in two places and for interface{}/any that could be tightened up. I found no problematic cross-package duplicate type definitions — the only repeated type names are intentional //go:build js || wasm variants (same package, mutually-exclusive build tags) and linter testdata fixtures, neither of which should be consolidated. The team also already maintains shared pkg/types, pkg/typeutil, and pkg/jsonutil homes, which is exactly where consolidation belongs.

On the untyped side, there's a lot of any (≈2,095 non-test lines touch map[string]any, plus ~1,600 type assertions), but the overwhelming majority is legitimate: YAML/JSON frontmatter parsing, codemod transformations over dynamic trees, and genuine union types like on: / runs-on: that GitHub Actions allows to be a string or array or object — shapes Go can't express without any. So rather than a sweeping "type everything" recommendation, I've isolated a handful of small, high-signal opportunities that are worth the effort: a recurring "string-or-number ID" pattern, repeated Headers any, and one near-duplicate struct pair. Fixing these centralizes a few ad-hoc type assertions without fighting the YAML-driven design.

Full Analysis Report

Duplicated Type Definitions

Summary Statistics

• Total non-test files analyzed: 917
• Total type definitions: ≈941 (830 structs/interfaces + ~111 aliases)
• Problematic exact duplicates (distinct real packages): 0
• Build-tag variant pairs (intentional, not duplicates): 3
• Near-duplicate struct pairs worth review: 1

Cluster 1: Build-tag variants — NOT a problem (informational)

Type: Exact name, intentional
Impact: None — do not consolidate

These three type names each appear twice, but every pair is a wasm/non-wasm implementation of the same type in the same package, guarded by mutually-exclusive build constraints. This is the correct Go pattern for platform-specific code.

Locations:

• SpinnerWrapper: pkg/console/spinner.go:92 (//go:build !js && !wasm) vs pkg/console/spinner_wasm.go:10 (//go:build js || wasm)
• ProgressBar: pkg/console/progress.go:31 vs pkg/console/progress_wasm.go:7
• RepositoryFeatures: pkg/workflow/repository_features_validation.go:58 vs pkg/workflow/repository_features_validation_wasm.go:5

Recommendation: None. Leave as-is. (Listed only so a future run doesn't re-flag them.)

---

Cluster 2: WorkflowListItem ⊂ WorkflowStatus — near-duplicate (low/medium)

Type: Near duplicate (structural subset)
Occurrences: 2
Impact: Low–Medium — WorkflowListItem is essentially a prefix of WorkflowStatus

// pkg/cli/list_workflows_command.go:20
type WorkflowListItem struct {
    Workflow string   `json:"workflow"`
    EngineID string   `json:"engine_id"`
    Compiled string   `json:"compiled"`
    Labels   []string `json:"labels,omitempty"`
    On       any      `json:"on,omitempty"`
}

// pkg/cli/status_command.go (WorkflowStatus) — same 5 fields plus status data
type WorkflowStatus struct {
    Workflow      string
    EngineID      string
    Compiled      string
    Status        string
    TimeRemaining string
    Labels        []string
    Dependencies  []string
    On            any
    RunStatus     string
    RunConclusion string
}

Recommendation: Optional. Extract the shared identity fields (Workflow, EngineID, Compiled, Labels, On) into an embedded WorkflowIdentity struct that both embed. Same-package, so this is a quick, safe refactor.

• Estimated effort: 1–2 hours
• Benefits: One source of truth for the shared columns; the two structs can't drift on tags/types.

---

Untyped Usages

Summary Statistics

• map[string]any / map[string]interface{} (non-test lines): ≈2,095 — mostly justified (YAML/JSON frontmatter + codemod trees)
• Type assertions x.(T) (non-test lines): ≈1,599 — concentrated in the same dynamic-tree code
• Function signatures taking any/interface{}: ~350+, concentrated in pkg/parser (import_field_extractor.go 37, mcp.go 25) and pkg/cli codemods — mostly justified
• Genuine union-type struct fields (On, RunsOn, RunsOnSlim, ContinueOnError, Checkout, Imports, Include, DeduplicateByTitle, ...): pervasive — justified; Go has no sum types
• Actionable, narrowly-scoped opportunities: 2 (below)

Why most of this is fine: gh-aw is a workflow compiler. It reads arbitrary GitHub Actions / agentic frontmatter (YAML→map[string]any) and rewrites it via codemods. Strongly typing a tree you must traverse generically would fight the design and add brittle struct churn for every new frontmatter key. The any fields that mirror GitHub Actions schema (on: can be string|array|map) are documented with comments stating the allowed shapes — that's the idiomatic Go workaround for union types. I am not recommending a blanket conversion of these.

Opportunity 1: Recurring "string-or-number ID" typed as any (medium value, low effort)

Impact: Medium — the same polymorphic-ID idea is re-implemented ad hoc in several places, each forcing a local type assertion / sprintf.

The GitHub API returns run/job IDs that may arrive as a JSON number or a string, so several structs declare them any:

Locations (8 fields across 5 files; the ID-shaped ones):

1. pkg/cli/mcp_tools_privileged.go:253 — RunID any (“Accepts run ID or run/job URL... String or number.”)
2. pkg/cli/gateway_logs_types.go:148 — ID any
3. pkg/cli/gateway_logs_types.go:159 — ID any
4. pkg/cli/logs_models.go:304 — RunID any
5. pkg/cli/logs_models.go:305 — RunNumber any

Suggested fix: Add one shared type in pkg/types (which already exists) with custom JSON unmarshalling, and reuse it:

// pkg/types/flexid.go
type FlexID string // accepts JSON string or number, normalizes to string

func (f *FlexID) UnmarshalJSON(b []byte) error {
    s := strings.TrimSpace(string(b))
    *f = FlexID(strings.Trim(s, `"`)) // numbers and strings both land here
    return nil
}

Then RunID FlexID, ID FlexID, etc. Each call site drops its .(string) / fmt.Sprintf("%v", id) dance.

• Estimated effort: 2–3 hours
• Benefits: One parsing rule, compile-time field type, fewer scattered assertions.

Opportunity 2: Repeated Headers any (low/medium)

Impact: Low–Medium — HTTP/MCP headers are modeled as any in 3 spots, then asserted on use.

Locations:

• pkg/parser/import_field_extractor.go:764 — Headers any
• pkg/workflow/frontmatter_types.go:208 — Headers any
• pkg/workflow/frontmatter_types.go:238 — Headers any

Suggested fix: If the source is consistently a string→string map, declare a named type and use it everywhere:

type Headers map[string]string

If headers can legitimately hold non-string values from raw YAML, leave as any — verify before changing.

• Estimated effort: 1–2 hours (plus call-site verification)
• Benefits: Self-documenting, removes per-use assertions.

Note: intentionally left alone

The following are any on purpose and should not be "fixed" without a sum-type need: On, RunsOn, RunsOnSlim, Checkout, Imports, Include, Engine, Endpoint, ContinueOnError, DeduplicateByTitle, Default, Ports, Raw, and the map[string]any codemod/frontmatter trees. Each represents a YAML value with multiple legal shapes; the existing comments documenting those shapes are the right call.

---

Refactoring Recommendations

Priority 1: Low-effort, real win — shared FlexID type

1. Add pkg/types/flexid.go with UnmarshalJSON.
2. Replace the 5 ID-shaped any fields (Opportunity 1) with FlexID.
3. Simplify the now-redundant assertions at call sites.
4. Run go test ./pkg/cli/....

Effort: 2–3 h · Impact: Medium (centralizes a repeated pattern)

Priority 2: Optional cleanup — WorkflowIdentity embed

1. Extract shared fields into an embedded struct.
2. Update WorkflowListItem and WorkflowStatus to embed it.
3. Run go test ./pkg/cli/....

Effort: 1–2 h · Impact: Low–Medium (prevents drift)

Priority 3: Verify-then-type Headers

1. Confirm header values are always string→string.
2. Introduce type Headers map[string]string and apply.

Effort: 1–2 h · Impact: Low–Medium

Explicitly NOT recommended

• Mass-converting map[string]any frontmatter/codemod trees to structs.
• Typing the GitHub Actions union fields (on, runs-on, ...) — keep any + doc comments.

---

Implementation Checklist

• Add pkg/types/FlexID and migrate the 5 ID any fields
• (Optional) Extract WorkflowIdentity shared embed
• Verify and (if safe) introduce type Headers map[string]string
• go test ./...
• Leave union-type any fields and dynamic frontmatter maps as-is

Analysis Metadata

• Total non-test Go files analyzed: 917
• Total type definitions: ≈941
• Problematic duplicate clusters: 0 (3 build-tag pairs + 1 near-dup subset noted)
• Untyped locations reviewed: ≈2,095 map[string]any lines, ~350 any signatures, ≈1,599 assertions
• Net actionable items: 3 (1 medium, 2 low–medium)
• Detection method: Serena project activation + ripgrep pattern analysis over pkg/
• Analysis date: 2026-06-16

Generated by ✍️ Typist - Go Type Analysis · 246.4 AIC · ⌖ 16.1 AIC · ⊞ 8.2K · ◷

• expires on Jun 17, 2026, 5:12 AM UTC-08:00

[github-actions[bot]]

This discussion has been marked as outdated by Typist - Go Type Analysis.

A newer discussion is available at Discussion #39788.