[typist] 🔤 Typist — Go Type Consistency Analysis (pkg/)

[github-actions[bot]]

🔤 Typist — Go Type Consistency Analysis

Analysis of repository: github/gh-aw

Executive Summary

Good news first: gh-aw is in genuinely healthy shape. I swept all 873 non-test Go files under pkg/ (≈610 struct/interface definitions) and found zero real cross-package duplicate type names. The three names that appear twice (ProgressBar, SpinnerWrapper, RepositoryFeatures) are all legitimate //go:build wasm vs. native variants in the same package — the pattern you want, not duplication.

The findings worth acting on are two small structural near-duplicates and a recurring habit of modeling the same semantic concept as untyped any in several places (RunsOn, On, Headers, GuardPolicies, Stats). One nice thing: the codebase has fully migrated off interface{} (0 occurrences) to the any alias. The win here is turning a handful of repeated any fields into small shared named types — deleting scattered assertions and documenting intent. None of this is urgent; treat it as a friendly polish pass.

Full Analysis Report

Duplicated Type Definitions

Summary

• Files analyzed: 873 (pkg/, excl. *_test.go + testdata/) · Type defs: ~610
• Exact cross-package duplicate names: 0
• Build-tag variants (not real dups): 3 · Structural near-dup clusters: 2

Cluster 1: AntigravityResponse ≈ GeminiResponse — structural duplicate

Identical field set, same workflow package:

• pkg/workflow/antigravity_logs.go:13
• pkg/workflow/gemini_logs.go:13

// both, byte-for-byte apart from the name:
type AntigravityResponse struct {
    Response string         `json:"response"`
    Stats    map[string]any `json:"stats"`
}

Fix: one shared type EngineJSONResponse struct { Response string; Stats map[string]any }; both ParseLogMetrics paths unmarshal into it. Few refs, all in-file. Effort ~1h. This also covers the repeated Stats field below.

---

Cluster 2: TrialArtifacts ⊂ WorkflowTrialResult — embed candidate

WorkflowTrialResult reproduces all three TrialArtifacts fields verbatim (down to the same commented-out AgentStdioLogs line):

• pkg/cli/trial_support.go:19 — TrialArtifacts
• pkg/cli/trial_types.go:6 — WorkflowTrialResult

// duplicated block in both:
SafeOutputs         map[string]any `json:"safe_outputs"`
AgenticRunInfo      map[string]any `json:"agentic_run_info,omitempty"`
AdditionalArtifacts map[string]any `json:"additional_artifacts,omitempty"`

Fix: embed TrialArtifacts inside WorkflowTrialResult so the shared fields live in one place. Effort ~1h (confirm the embedded JSON layout matches consumers).

---

Build-tag variants — reviewed, NOT flagged

Correct platform-specific implementations, no action:

• ProgressBar — console/progress.go:31 + progress_wasm.go:7
• SpinnerWrapper — console/spinner.go:92 + spinner_wasm.go:10
• RepositoryFeatures — workflow/repository_features_validation.go:58 + ..._wasm.go:5

---

Untyped Usages

Summary

• interface{}: 0 (all any — good) · any tokens: ~3,450 · map[...]any: ~2,078
• Bare-any struct fields: 31 · map[string]any struct fields: 72 · func sigs w/ any: ~866

Most any use is legitimate polymorphic frontmatter (the code even notes too dynamic to type). I only flag concepts modeled as any in multiple places.

Category 1: Repeated polymorphic fields deserving a named type

• RunsOn any (GitHub Actions runs-on; string/array/object) — workflow/safe_jobs.go:20, workflow/frontmatter_types.go:329, cli/copilot_setup.go:150. → shared type RunsOn any (optionally with UnmarshalYAML).
• On any (workflow on: trigger) — cli/status_command.go:35, cli/jsonworkflow_to_markdown.go:38, cli/copilot_setup.go:158, cli/list_workflows_command.go:25. → one shared trigger type so the four CLI display paths agree.
• Headers any (HTTP headers) — workflow/frontmatter_types.go:208 & :238, parser/import_field_extractor.go:764. → map[string]string (or map[string][]string, like http.Header) removes the assertions.
• GuardPolicies map[string]any — workflow/mcp_renderer_types.go:84 & :111, workflow/tools_types.go:427, workflow/mcp_config_types.go:54 (+ WriteSinkGuardPolicies at mcp_renderer_types.go:21). → shared type GuardPolicies map[string]any to hang validation on.
• Stats map[string]any — workflow/antigravity_logs.go:15, gemini_logs.go:15, pi_logs.go:36. → folded into EngineJSONResponse (Cluster 1).

Category 2: String-or-number JSON IDs

Accept either a JSON string or number, forcing per-site assertions / fmt.Sprintf:

• cli/gateway_logs_types.go:148 & :159 — ID any
• cli/logs_models.go:304-305 — RunID / RunNumber any
• cli/mcp_tools_privileged.go:254-255 — RunID / RunIDOrURL any

Fix: a small type FlexInt int64 (or StringOrInt) with custom UnmarshalJSON accepting both forms; consumers get a real value, no assertions.

Category 3: Untyped constants

Go untyped constants are idiomatic, so blanket-typing is not recommended — and I found none whose lack of a type creates a correctness risk. Only add a named type (e.g. type Seconds int) where a unit is genuinely ambiguous at call sites, not mechanically.

Recommendations (by priority)

1. Structural dups (highest value, lowest risk, ~2h): add EngineJSONResponse (replaces AntigravityResponse+GeminiResponse); embed TrialArtifacts in WorkflowTrialResult.
2. Name repeated concepts (~3-4h): introduce RunsOn, On, GuardPolicies (and optionally Headers) types/aliases; adopt at listed sites.
3. String-or-number IDs (~2h): add FlexInt/StringOrInt + custom UnmarshalJSON; adopt at ID/RunID/RunNumber.

After each step run go build ./... and the test suite to confirm no breakage.

Metadata

• Files: 873 · Type defs: ~610 · Cross-pkg dup names: 0 · Near-dup clusters: 2 · interface{}: 0
• Detection: Serena project activation + deterministic AST-shape pattern extraction across pkg/
• Date: 2026-06-11

References: §27347015436

Generated by ✍️ Typist - Go Type Analysis · 305 AIC · ⌖ 8.13 AIC · ⊞ 9.2K · ◷

• expires on Jun 12, 2026, 4:46 AM UTC-08:00