[typist] 🔤 Typist — Go Type Consistency Analysis

[github-actions[bot]]

Repository: github/gh-aw · 910 non-test .go files under pkg/ · ~795 type definitions

Executive Summary

Good news first: this codebase is in genuinely good shape on type discipline. Most of the "obvious" duplication targets have already been consolidated — MCP server configs embed a shared pkg/types.BaseMCPServerConfig, the 25+ safe-output configs embed BaseSafeOutputConfig, and production code has standardized on any over interface{} (literal interface{} survives only in linter testdata).

That said, I found a handful of real, verified opportunities. The standout: a pair of byte-identical struct definitions for the experiment state.json format in two files of the same pkg/cli package — a textbook "delete one, reuse the other" win. There's also a cluster of near-identical report structs in logs_models.go, two MCP-metrics types that disagree on whether a duration is a string or float64, a missing GitHubMCPMode string enum, and the githubTool any cluster in mcp_github_config.go (~19 params that always immediately assert to map[string]any). None are emergencies — this is polish.

Full Analysis Report

Duplicated Type Definitions

Stats: 11 verified clusters (field bodies compared, not just names) — 2 exact, 7 near, 2 semantic. A shared name alone was not treated as a duplicate; many same-named Config types are legitimately distinct and are not reported.

🔴 Cluster 1 & 2 (exact): experiment state.json types

ExperimentState/experimentStateJSON and ExperimentRunRecord/experimentRunRecord are byte-identical structs (same fields, same JSON tags) that both deserialize the state.json written by pick_experiment.cjs, in the same package.

• pkg/cli/experiments_command.go:32,38 vs pkg/cli/audit_report_experiments.go:35,42
• Fix: delete the unexported experimentStateJSON/experimentRunRecord, reuse the exported pair. No new import. ~30 min. Removes silent schema-drift between the two copies.

🟠 Cluster 3 (near): MissingToolSummary / MissingDataSummary

6 of 7 fields identical (only Tool vs DataType differs). pkg/cli/logs_models.go:148,168.

• Fix: extract a missingItemAggregation base struct, embed in both. ~1h. The aggregation/display logic is duplicated alongside them.

🟡 Cluster 4 (near): MissingToolReport / MissingDataReport / NoopReport / MCPFailureReport

All four share the provenance trailer Timestamp, WorkflowName, RunID int64. pkg/cli/logs_models.go:110,120,128,139.

• Fix: embed a shared RunProvenance struct. ~1h.

🟡 Clusters 5 & 6 (near): MCP metrics modeled twice

MCPServerStats/GatewayServerMetrics (audit_report.go:199 vs gateway_logs_types.go:85) and MCPToolSummary/GatewayToolMetrics (audit_report.go:171 vs gateway_logs_types.go:97) — same per-server/per-tool MCP metrics from two pipelines that disagree on duration typing (string vs float64).

• Fix: converge on one representation (numeric internally, format to string at render). ~2-3h. Removes a string-vs-float unit-bug hazard.

Lower-priority clusters 7–11

• 🟡 7 AccessLogSummary/FirewallLogSummary (logs_report_firewall.go:12,22) — ~5 shared count/domain fields; extract a DomainTrafficSummary base.
• 🟢 8 DomainAnalysis/FirewallAnalysis (access_log.go:33, firewall_log.go:131) — both embed DomainBuckets; partly consolidated already.
• 🟢 9 updateFailure/actionUpdateFailure/imageFailure (update_types.go:11,17, update_container_pins.go:25) — all {identifier, reason} pairs; tiny and local.
• 🟢 10 AuditComparisonIntDelta/AuditComparisonStringDelta (audit_comparison.go:44,50) — identical shape differing only in element type; candidate for a generic Delta[T].
• 🟢 11 SourceSpec/RepoSpec (spec.go:26,19) — overlapping repo+ref(+path) specs; align to reduce conversion glue.

---

Untyped Usages

Stats: literal interface{} in production = 0 ✅ · any params ~208 (103 files) · any returns 13 · any fields 31 · map[string]any 2,111 (350 files) · constants mostly typed well ✅.

Context: gh-aw is a YAML-frontmatter → GitHub Actions compiler. map[string]any/any at the parse boundary are the correct shape for schema-validated dynamic data. The bar for "should be typed" is: the real type is knowable and consistent at that site.

🟠 Cat 1 — any params (the top fix): githubTool any

~19 occurrences across 7 files (pkg/workflow/mcp_github_config.go:85,139,164,183,205,584,... + callers in mcp_renderer_github.go, mcp_setup_generator.go, compiler_difc_proxy.go). Every getter immediately does githubTool.(map[string]any); the value always comes from data.Tools["github"] (either false or a map).

• Fix: type GitHubToolConfig map[string]any (disabled → nil); retype the getters. Removes ~19 repeated assertions.
• Also: role_checks.go:136,180,186 re-implement a "string | []any | []string → []string" union ~5×; one shared helper shrinks the surface (the any stays — real YAML union).
• Leave alone: unmarshalConfig (config_helpers.go:172), marshalEnvValue, formatYAMLValue, pkg/typeutil/convert.go, pkg/logger varargs — legitimately generic.

✅ Cat 2 — any return types (13): all genuine sum types at the schema/YAML layer (schema_suggestions.go, schema_compiler.go:217, trigger_parser.go:721, templatables.go:118). No action.

🟡 Cat 3 — any struct fields (mixed)

• Keep (documented YAML unions): frontmatter_types.go:329,342,344,382 (RunsOn/Imports/Include/Checkout), step_types.go:28, pkg/types/input_definition.go:18.
• Improve (string-or-number from GitHub API): mcp_tools_privileged.go:253-254 (RunID, RunIDOrURL), logs_models.go:304-305 (RunID, RunNumber) → use json.Number or a small StringOrInt.

✅ Cat 4 — map[string]any (2,111): idiomatic frontmatter/output-tree handling, schema-validated in pkg/parser/schema_*.go. No action (flagged so the count isn't mistaken for debt).

🟢 Cat 5 — one real constant gap: missing GitHubMCPMode enum

constants.go already types durations (time.Duration) and credit limits (int64) well. But transport/mode values are compared as raw string literals: mcp_github_config.go:110-114,130 ("local"/"remote"/"gh-proxy"/"cli"), mcp_scripts_parser.go:64. Define type GitHubMCPMode string with named constants so the compiler catches typos that today fail silently as false.

---

Recommendations (prioritized)

1. 🔴 P1 — Delete the exact state.json duplicates (Clusters 1&2), reuse exported types. ~30 min. High.
2. 🟠 P2 — Introduce GitHubToolConfig, retype the ~19 mcp_github_config.go getters. ~3-4h. High.
3. 🟡 P3 — Extract RunProvenance + missingItemAggregation bases in logs_models.go (Clusters 3&4). ~2h. Medium.
4. 🟡 P4 — Reconcile MCP metric duration typing (Clusters 5&6); share a metrics core. ~2-3h. Medium.
5. 🟢 P5 — Add the GitHubMCPMode string enum + type the GitHub-API RunID/RunNumber fields. ~1h. Low-Med.

After each: go build ./... and go test ./.... Clusters 7–11 are optional cleanup-of-opportunity.

Metadata

910 files · ~795 types · 11 clusters (2 exact / 7 near / 2 semantic) · any params ~208, returns 13, fields 31, map[string]any 2,111 · method: ripgrep extraction + field-body verification + Serena spot checks · 2026-06-12.

References: §27415555013

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

• expires on Jun 13, 2026, 4:47 AM UTC-08:00

[github-actions[bot]]

This discussion was automatically closed because it expired on 2026-06-13T12:47:37.464Z.

Closed by Workflow