[typist] 🔤 Typist — Go Type Consistency Analysis

[github-actions[bot]]

🔤 Typist - Go Type Consistency Analysis

Analysis of repository: github/gh-aw

Executive Summary

This codebase is remarkably disciplined about typing for its size. I analyzed 1,140 non-test .go files under pkg/ (~1,095 type definitions, ~730 const sites) and found zero accidental exact-name type collisions in production code. The team already leans on named string types (EngineName, FeatureFlag, PermissionScope, PermissionLevel, ActionMode, AttributionStatus) and single-source re-export aliases (type X = pkg.X).

So this is less "a mess" and more "a handful of clean, high-leverage tidy-ups." Standouts: a byte-identical experiment state struct defined twice in the same cli package (a ~15-min fix), a parallel models.dev catalog parser in pkg/cli that re-declares structs its own package already imports from pkg/modelsdev, and a three-value LLMProvider enum threaded through ~8 functions as a bare string that drives secret selection and gateway routing. Almost all ~4,000 any usages are idiomatic (parsed Actions YAML, JSON-Schema walking, go/analysis signatures), so I filtered aggressively and surface only the handful worth touching.

Full Analysis Report

Duplicated Type Definitions

Stats: ~1,095 types analyzed · 5 real actionable clusters (1 exact, 4 near) · build-tag *_wasm.go pairs and linter testdata fixtures excluded as intentional.

Cluster 1 — ExperimentState vs experimentStateJSON · Exact duplicate ⭐ Top pick

• pkg/cli/experiments_command.go:35 — ExperimentState (+ ExperimentRunRecord at :41)
• pkg/cli/audit_report_experiments.go:35 — experimentStateJSON (+ experimentRunRecord at :42)

Both are byte-identical (Counts map[string]map[string]int; Runs []...RunRecord), both in package cli. experimentStateJSON is used in exactly one place (audit_report_experiments.go:92). Fix: delete the unexported pair, reuse the exported types at that single site. ~15 min.

Cluster 2 — models.dev catalog parse structs · Near duplicate

• pkg/cli/model_costs.go:20 — modelsCatalogData/modelsCatalogProvider/modelCostEntry (Cost map[string]string)
• pkg/modelsdev/catalog.go:32 — rawCatalog/rawProvider/rawModel (Cost map[string]json.RawMessage)

Same 3-level Catalog→Provider→Model{Cost} JSON shape. model_costs.go:12 already imports pkg/modelsdev yet re-parses the catalog with its own structs. Fix: consume pkg/modelsdev’s types; unify the Cost leaf. ~1-2 h.

Cluster 3 — Firewall / domain aggregation bases · Near duplicate (mid-refactor)

• pkg/cli/logs_report_firewall.go:17 — FirewallSummaryBase
• pkg/cli/domain_buckets.go:41 — AnalysisBase (embeds DomainBuckets at :13)
• pkg/cli/access_log.go:44 — domainAnalysisWire (legacy allowed_count/blocked_count json tags)

All hold {TotalRequests, Allowed*, Blocked* int, AllowedDomains, BlockedDomains []string}. Fix: make FirewallSummaryBase reuse AnalysisBase; keep domainAnalysisWire only as a MarshalJSON shim. ~1-2 h.

Cluster 4 — rateLimitResponse vs orgRateLimitResponse · Near duplicate

pkg/cli/logs_rate_limit.go:39 and pkg/cli/update_org.go:48 both wrap Resources.Core rateLimitResource; the org variant only adds Search. Fix: one struct with both Core and Search. ~30 min. (Low.)

Not duplication (single source of truth): re-export aliases LogMetrics, ToolCallInfo, SanitizeOptions, InputDefinition, actionpins.*.

Excluded as intentional (do NOT refactor)

• Build-tag pairs (!js && !wasm vs js || wasm): RepositoryFeatures, SpinnerWrapper, ProgressBar (each native .go / _wasm.go).
• Linter testdata fixtures in isolated testdata/src/* packages: Worker, fakeOS, myString/myBytes.

---

Untyped Usages

Stats: interface{} = 18 (nearly all linter testdata/comments) · any ~4,051 (map values 2,406 · slices 436 · params 241 · returns 134 · fields 35) · ~9 actionable · 8 untyped enum groups · 2 ambiguous numeric.

Idiomatic note: ~95%+ of any is unavoidable — parsed Actions YAML/JSON frontmatter (map[string]any/[]any), JSON-Schema walking, generic marshal/print helpers, and func(pass *analysis.Pass) (any, error) across pkg/linters. Filtered out.

Struct fields with a knowable type:

• pkg/cli/logs_models.go:323-324 — RunID any / RunNumber any → int64 / int (or json.Number). Self-produced aw_info.json fields; removes downstream type switches. (Medium)
• pkg/console/console_types.go:50 — Value any (always *string/*bool) → make FormField generic (FormField[T any] with Value *T). (Medium)

Slice elements that are always objects:

• pkg/workflow/frontmatter_types.go:324,359-362 — PreSteps/Steps/PreAgentSteps/PostSteps/Skills []any → []map[string]any (steps are always mappings; drops per-element assertions). (Medium)

Return types with a known root shape:

• pkg/parser/schema_compiler.go:101 (+ fields :57,:61) — getParsedSchemaDoc(...) (any, error) → (map[string]any, error); a schema root is always an object. (Medium)

Lower-impact any opportunities (optional)

• pkg/cli/mcp_tools_privileged.go:299-300 — RunID any/RunIDOrURL any → json.Number + typed URL string.
• pkg/parser/remote_client.go:47 — fetchRemoteFileContent(..., fileContent any) (one caller) → generic or concrete struct.
• pkg/workflow/pi_logs.go:29 — Parameters any → map[string]any.
• pkg/workflow/mcp_scripts_parser.go:60 — Default any (mirrors types/input_definition.go:18) → scalar accessor.
• pkg/parser/schema_suggestions.go:267,380-411 — give leaf generate*Example helpers concrete returns; keep composed root any.

Untyped string-enum constant groups:

LLMProvider · High ⭐ — pkg/workflow/llm_provider.go:13:

// Current: bare strings threaded through ~8 funcs as provider string
const ( LLMProviderGitHub = "github"; LLMProviderAnthropic = "anthropic"; LLMProviderOpenAI = "openai" )
// Suggested
type LLMProvider string
const ( LLMProviderGitHub LLMProvider = "github"; LLMProviderAnthropic LLMProvider = "anthropic"; LLMProviderOpenAI LLMProvider = "openai" )

Drives normalizeLLMProvider, resolveEngineLLMProvider, llmProviderProfileFor, llmProviderSecretNames/Expression, gateway/docs URL helpers, and EngineConfig.LLMProvider. Provider selection controls secret resolution and gateway routing — best safety-per-line in the report.

MCP registry enums · Medium (exported) — pkg/cli/mcp_registry_types.go:107: StatusActive/Inactive → type ServerStatus string; ArgumentTypePositional/Named → type ArgumentType string.

More enum groups (medium/low)

• pkg/workflow/safe_outputs_validation.go:13 — SafeOutputsURLsPolicy (allowed-only/allowed-or-code-region); type config.URLs too. (medium)
• pkg/github/label_objective_mapping_constants.go:137 — MultiLabelLogic (max/sum/first). (medium)
• pkg/cli/env_command.go:25 — DefaultsScope (repo/org/ent). (medium)
• pkg/workflow/run_phase.go:3 — RunPhase (agent/detection/evals). (low)
• pkg/cli/outcomes_history.go:23 — HistorySource (issues/prs/all). (low)

Ambiguous numeric constants:

• pkg/cli/gateway_logs_types.go:61 — guard-policy JSON-RPC codes -32001..-32006 as bare int → type GuardPolicyErrorCode int (+ a String()). (medium)
• pkg/constants/constants.go:126-135 — gateway ports; already grouped int, a NetworkPort type is marginal. (low)

---

Prioritized Recommendations

• P1 (quick wins): (1) delete experimentStateJSON/experimentRunRecord, reuse exported types (~15 min); (2) add type LLMProvider string and thread through helpers + EngineConfig.LLMProvider (~1-2 h, best payoff).
• P2 (consolidate structs): (3) reuse pkg/modelsdev catalog types in model_costs.go; (4) finish firewall/domain-buckets base consolidation; (5) merge rate-limit responses.
• P3 (strengthen any): (6) RunID/RunNumber → int64/int; (7) step slices → []map[string]any; (8) getParsedSchemaDoc → map[string]any.
• P4 (enums as touched): add named types for ServerStatus, ArgumentType, SafeOutputsURLsPolicy, MultiLabelLogic, DefaultsScope, GuardPolicyErrorCode.

Run go build ./... + the full test suite after each change.

Metadata: files scanned 1,140 · type defs ~1,095 · real duplicate clusters 5 · any/interface{} ~4,069 (~95%+ idiomatic; 9 actionable) · const sites ~730 (8 enum groups, 2 numeric) · method: Serena semantic analysis + pattern matching, verified against source · date 2026-07-24.

Generated by ✍️ Typist - Go Type Analysis · age00 · 744.4 AIC · ⌖ 35 AIC · ⊞ 8.6K · ◷

• expires on Jul 25, 2026, 4:18 AM UTC-08:00

[github-actions[bot]]

This discussion was automatically closed because it expired on 2026-07-25T12:18:10.320Z.

Closed by Workflow