[typist] 🔤 Typist — Go Type Consistency Analysis

[github-actions[bot]]

🔤 Typist — Go Type Consistency Analysis

Analysis of repository: github/gh-aw

Executive Summary

Good news first: gh-aw is already an unusually well-typed Go codebase. I scanned 920 non-test .go files under pkg/ (~740 named types) and found zero raw interface{} literals in production code — the project uniformly uses any, and the large majority of its ~2,850 any occurrences are genuinely dynamic (YAML frontmatter, GitHub/GraphQL JSON, MCP/JSON-RPC, generic conversion helpers). Plenty of domain enums already exist (PermissionLevel, EngineName, OutcomeStatus, ShellType). So this is a polish pass, not a rescue.

That said, the wins are real: one exact duplicate (AntigravityResponse/GeminiResponse, byte-for-byte identical), 9 near-duplicate structs (clustered in CLI logs/audit and the action-pinning manifest, where the same data is modeled twice), and a pattern of implicit string-enum constants — plain string fields switched against a fixed literal set. The three highest-value enum fixes (console.CompilerError.Type, cli.ArgumentType, github.MultiLabelLogic) each harden a field that is actively dispatched on, so a typo like "warn" silently hits a default branch today.

Full Analysis Report

Duplicated Type Definitions

Stats: ~740 types · 13 clusters reported (1 exact, 9 near, 3 semantic; 3 more excluded as intentional).

Cluster 1 — CLI-response struct (EXACT, High): pkg/workflow/antigravity_logs.go:13 AntigravityResponse is identical to pkg/workflow/gemini_logs.go:13 GeminiResponse — same {Response string; Stats map[string]any} incl. json tags. Fix: one shared CLIJSONResponse + shared ParseLogMetrics helper. ~1h.

Cluster 2 — Action-pinning manifest (NEAR, High): actionpins/actionpins.go ContainerPin(:46)/ResolutionFailure(:74)/ActionPin(:38) duplicated by workflow/safe_update_manifest.go GHAWManifestContainer(:32)/GHAWManifestResolutionFailure(:40)/GHAWManifestAction(:23). Fix: reuse actionpins types, convert at JSON boundary. 2–3h.

Cluster 3 — MCP tool-usage container (NEAR, High): cli/audit_report.go:163 MCPToolUsageData vs cli/logs_models.go:178 MCPToolUsageSummary — same slices, former adds optional *GuardPolicySummary. Fix: merge with omitempty. 1–2h.

Cluster 4 — Domain/firewall analysis (NEAR, High): cli/access_log.go:33 DomainAnalysis vs cli/firewall_log.go:131 FirewallAnalysis — both embed DomainBuckets + total + allowed/blocked pair, near-identical AddMetrics. Fix: shared embedded base; firewall keeps RequestsByDomain. 2–3h.

Clusters 5–13 (medium / low)

• 5 (Near, med) cli/logs_report_firewall.go:12 AccessLogSummary vs :22 FirewallLogSummary — collapse once Cluster 4 is unified.
• 6 (Near, med) cli/access_log.go:19 AccessLogEntry vs cli/firewall_log.go:116 FirewallLogEntry — overlapping string proxy-log records; OK to keep separate given distinct formats.
• 7 (Near, med) cli/logs_models.go:148 MissingToolSummary vs :167 MissingDataSummary — identical but the key field. Extract embedded base; MCPFailureSummary (:158) shares a subset.
• 8 (Near, med) cli/logs_models.go:110/119/127/138 (MissingToolReport,NoopReport,MissingDataReport,MCPFailureReport) share Timestamp,WorkflowName string; RunID int64. Extract ReportProvenance.
• 9 (Near, med) cli/audit_report.go:200 MCPServerStats, cli/audit_expanded.go:89 MCPServerHealthDetail, cli/audit_cross_run.go:81 MCPServerCrossRunHealth — 3 projections of per-server health; define canonical metric type.
• 10 (Near, med) workflow/compiler_types.go:431 SkipIfMatchConfig vs :438 SkipIfNoMatchConfig — differ only Max/Min; shared {Query,Scope} base.
• 11 (Near, low) workflow/update_entity_helpers.go:100 UpdateEntityJobParams vs workflow/close_entity_helpers.go:90 CloseEntityJobParams — share 5 fields; extract base.
• 12 (Semantic, low) cli/audit_comparison.go:44 AuditComparisonIntDelta vs :50 AuditComparisonStringDelta — replace with generic Delta[T comparable].
• 13 (Semantic, low) intent/resolver.go:49 PullRequestData, cli/pr_command.go:27 PRInfo, cli/pr_automerge.go:21 PullRequest — 3 PR models; OK but worth a shared DTO audit.
• Excluded (intentional): WASM build-tag alternates (RepositoryFeatures,SpinnerWrapper,ProgressBar); MCP config already consolidated around types.BaseMCPServerConfig.

Untyped Usages

Stats: raw interface{} in production = 0 · any ~2,850 (mostly legit-dynamic, excluded) · 16 implicit-enum/const opportunities.

gh-aw correctly uses any for dynamic data (frontmatter, GitHub/GraphQL JSON, MCP/JSON-RPC, generic helpers) — not flagged. Opportunities are string-enum constants and the fields they back.

Category 1 — stringly-typed fields actively switched on (High):

• pkg/console/console_types.go:13 CompilerError.Type string (error/warning/info) becomes type ErrorSeverity string. Dispatched at console.go:42, console_wasm.go:19; set raw in ~6 sites. Prevents typo to silent default.
• pkg/cli/mcp_registry_types.go:71 Argument.Type string (consts at :113-116) becomes type ArgumentType string. Compared at mcp_registry.go:171,180.
• pkg/github/label_objective_mapping.go:27 MultiLabelLogic string (sum/max/first; consts at constants.go:136-140) becomes type MultiLabelLogic string; switched at :65-94; replace literal default at :62.

Category 2 — implicit string-enum const groups (Medium):

• cli/outcomes_history.go:19-23 historySource{Issues,PRs,All} → type HistorySource string
• cli/env_command.go:24-28 defaultsScope{Repo,Org,Ent} → type DefaultsScope string
• parser/json_path_locator.go:226 PathSegment.Type (key/index, verified closed) → type PathSegmentKind string
• workflow/mcp_scripts_parser.go:36-38 Mode (http/stdio) → type MCPScriptsMode string
• cli/mcp_registry_types.go:107-110 Status{Active,Inactive} → type ServerStatus string

Category 3 — lower-impact (8)

• console/console_types.go:42 FormField.Type → type FormFieldType string
• cli/logs_safe_output_chains.go:15-19 temporaryIDMapStatus → type TemporaryIDMapStatus string
• parser/mcp.go:179 safeOutputToolName 10-literal switch → type SafeOutputToolName string (boundary values)
• cli/gateway_logs_types.go:61-68 guardPolicyErrorCode -32001..-32006 → type GuardPolicyErrorCode int
• parser/import_field_extractor.go:1097 declared-type switch → type InputType string (field stays string, dynamic YAML)
• workflow/safe_jobs_needs_validation.go:174-178 unvisited/visiting/visited → type visitState int + iota
• cli/import_url_fetcher.go:204-209 segment labels mixed with a count → split type urlSegment string
• parser/remote_fetch.go:914 fetchRemoteFileContent(... any) → *remoteFileContent struct (sole call site passes concrete; marginal, mirrors api.RESTClient.Get)

Refactoring Recommendations (prioritized)

1. Quick win — merge AntigravityResponse/GeminiResponse into CLIJSONResponse. ~1h, low risk.
2. High/correctness — add ErrorSeverity/ArgumentType/MultiLabelLogic named types + update call sites. 2–4h.
3. Medium — collapse the pkg/cli logs/audit near-duplicates via shared embedded bases (ReportProvenance, domain-analysis base, per-server metric) and merge MCPToolUsage*. ~1 day.
4. Medium/clarity — type the Category 2/3 const groups opportunistically. 2–3h.

Implementation Checklist

• Merge AntigravityResponse+GeminiResponse into CLIJSONResponse
• Add ErrorSeverity/ArgumentType/MultiLabelLogic types + update fields/call sites
• Unify DomainAnalysis/FirewallAnalysis (+ summaries) via shared base
• Merge MCPToolUsageData/MCPToolUsageSummary
• Extract ReportProvenance for the four agentic report records
• Reuse actionpins types in workflow manifest code
• Type Category 2/3 const groups opportunistically
• go build ./... + full test suite after each refactor

Metadata: 920 files · ~740 types · 13 duplicate clusters · 16 untyped findings · 0 raw interface{} · Serena semantic analysis + structural matching + reference tracing · 2026-06-17

References: §27689495906

Generated by ✍️ Typist - Go Type Analysis · ◷

• expires on Jun 18, 2026, 4:55 AM UTC-08:00