[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: this codebase is already in strong shape on type safety. I scanned 1,112 non-test .go files under pkg/ (~850 exported type definitions) and found that the team has already done most of the heavy lifting — raw interface{} is effectively extinct in production code (only ~2 stray mentions, both in comments), shared base structs like BaseSafeOutputConfig, AggregatedSummaryBase, and BaseMCPServerConfig are already factored out, and pkg/constants establishes a clean typed-constant pattern (EngineName, JobName, MCPServerID, ...). So this is less "fix a mess" and more "a handful of spots that drifted from patterns you already use."

What's left falls into two buckets. On duplication, there are no exact cross-package clones to consolidate — the one true name collision is PolicyRule (a firewall ACL rule vs. an intent-governance rule, unrelated concepts), plus a few near-duplicates where a struct copy-pastes fields it could embed instead (most notably MCPFailureSummary, whose sibling types already embed the shared base — the base type's own doc comment even flags it). On weak typing, the real opportunity isn't interface{} at all — it's stringly-typed enums: struct fields and constants like LLMProvider, PermissionMode, and the various Mode string fields that hold a small closed set of values but are declared as bare string. Typing these (following the constants.EngineName pattern you already have) buys compile-time exhaustiveness on the switch statements that consume them. Nothing here is urgent; it's all low-risk polish that reduces copy-paste drift and magic strings.

Full Analysis Report

Duplicated Type Definitions

Summary Statistics

• Total types analyzed: ~850 exported type declarations (non-test)
• Duplicate clusters found: 6 actionable + 1 acceptable (build-tag)
• Exact duplicates: 0 (excluding intentional build-tag variants)
• Near duplicates: 3
• Semantic duplicates: 3

Note: Type aliases (type X = Y) and build-tag platform variants are not counted as duplication — they're correct single-source patterns. The repo uses them well (Tools = ToolsConfig, ActionPin = actionpins.ActionPin, the Close*Config alias family, etc.).

Cluster 1: MCPFailureSummary — inline fields instead of embedded base

Kind: Near duplicate • Impact: Medium

Locations:

1. pkg/cli/logs_models.go:174 — MCPFailureSummary re-declares Count, Workflows, WorkflowsDisplay, RunIDs inline
2. pkg/cli/logs_models.go:158 — AggregatedSummaryBase (the base that siblings embed)

Its siblings MissingToolSummary and MissingDataSummary embed AggregatedSummaryBase; MCPFailureSummary copy-pastes a subset instead. The base type's own doc comment already notes this.

Recommendation: Embed AggregatedSummaryBase in MCPFailureSummary (the two extra base fields it doesn't need are harmless with omitempty). Removes copy-paste drift risk. Effort: ~1 hour.

---

Cluster 2: Create*Config safe-output family — second-tier field duplication

Kind: Near duplicate • Impact: Medium

Locations:

1. pkg/workflow/create_issue.go:12 — CreateIssuesConfig
2. pkg/workflow/create_discussion.go:14 — CreateDiscussionsConfig
3. pkg/workflow/create_pull_request.go:33 — CreatePullRequestsConfig

These already share BaseSafeOutputConfig, but a second tier of ~8 entity-creation fields (TitlePrefix, Labels, AllowedLabels, TargetRepoSlug, AllowedRepos, CloseOlderKey, Expires, Footer) is copy-pasted with identical yaml tags across all three.

Recommendation: Extract a CreateEntityBaseConfig (embedding BaseSafeOutputConfig + the shared entity fields) and embed it. Cuts the drift surface for future field additions. Effort: 2–3 hours (mechanical, plus test verification).

---

Cluster 3: PolicyRule — name collision across packages

Kind: Semantic (name-only) • Impact: Low

Locations:

1. pkg/cli/firewall_policy.go:36 — firewall ACL rule (ID, Order, Action, ACLName, Protocol, Domains, ...)
2. pkg/intent/policy.go:46 — intent execution-policy rule (ID, Scope, When, Set)

Same name, unrelated concepts, sharing only ID. Not a merge candidate.

Recommendation: Rename one for clarity (e.g. FirewallPolicyRule) to avoid cross-package confusion in reviews/search. Effort: <1 hour.

---

Clusters 4–6: lower-priority audit-diff shape repetition

Cluster 4: *DiffSummary trio

Kind: Semantic • Impact: Low • all in pkg/cli/audit_diff.go

• FirewallDiffSummary:50, MCPToolsDiffSummary:246, ToolCallsDiffSummary:305
• Repeat the new/removed/changed-count + HasAnomalies/AnomalyCount shape with differing prefixes.
• Recommendation: optional shared DiffCountsSummary{New, Removed, Changed int; HasAnomalies bool; AnomalyCount int} embed. Low priority — JSON field names intentionally diverge.

Cluster 5: *DiffEntry trio

Kind: Semantic • Impact: Low • all in pkg/cli/audit_diff.go

• DomainDiffEntry:24, MCPToolDiffEntry:224, ToolCallDiffEntry:282
• All follow the run1-vs-run2 pattern (Status + Run1X/Run2X + XChange + IsAnomaly/AnomalyNote).
• Recommendation: a DiffEntryBase{Status string; IsAnomaly bool; AnomalyNote string} embed removes the repeated anomaly-flagging fields; count pairs stay type-specific.

Cluster 6: RedactedDomains*

Kind: Near • Impact: Low • pkg/cli/redacted_domains.go

• RedactedDomainsLogSummary:29 duplicates TotalDomains + Domains (identical tags) from RedactedDomainsAnalysis:21, which it already references via ByWorkflow.
• Recommendation: embed RedactedDomainsAnalysis to keep the field sets in sync.

Acceptable (no action): build-tag variants

SpinnerWrapper (console/spinner.go + spinner_wasm.go), ProgressBar (console/progress.go + progress_wasm.go), and RepositoryFeatures (workflow/repository_features_validation.go + _wasm.go) are intentional wasm-vs-native build-tag pairs — not duplication.

---

Untyped Usages

Summary Statistics

• interface{} literals in production code: ~2 (both in comments) — effectively eliminated ✅
• any occurrences: ~1,800, of which ~1,720 are idiomatic YAML/JSON frontmatter decoding (map[string]any from yaml.Unmarshal) — acceptable
• Untyped-constant / stringly-typed-enum opportunities: ~10 high-value spots
• Detection: the weak typing here is not interface{} — it's bare string fields/constants that model closed enums

Category 1: Stringly-typed enum fields & constants (the real opportunity)

The repo already defines named string types for enums (constants.EngineName, workflow.GitHubMCPMode, workflow.AuthStrategy). These spots hold a small closed value set but were left as bare string, so the consuming switch statements get no compile-time exhaustiveness.

Example 1: LLMProvider — highest value

• Locations: pkg/workflow/llm_provider.go:13 (constants) + pkg/workflow/engine.go:49 (field)
• Current:

  const ( LLMProviderGitHub = "github"; LLMProviderAnthropic = "anthropic"; LLMProviderOpenAI = "openai" )
  // EngineConfig:
  LLMProvider string // Inference provider override

• Actual usage: closed 3-value enum, validated via a normalizeLLMProvider switch and threaded through ~8 helpers (llmProviderProfileFor, ...SecretNames, ...GatewayBaseURL, ...), all taking a plain string.
• Suggested fix:

  type LLMProvider string
  const ( LLMProviderGitHub LLMProvider = "github"; /* ... */ )
  // EngineConfig.LLMProvider LLMProvider, helper signatures use LLMProvider

• Benefits: compile-time exhaustiveness on the provider switches; mirrors the existing constants.EngineName pattern.

Example 2: PermissionMode (Claude CLI permission modes)

• Location: pkg/workflow/engine.go:50 — PermissionMode string
• Actual usage: enum of "acceptEdits", "auto", ... hardcoded as magic strings at claude_engine.go:230-233; zero named constants exist today.
• Suggested fix: type PermissionMode string + named constants for each literal.
• Impact: Medium — removes undocumented magic strings.

Example 3: SafeOutputsURLsPolicy

• Locations: pkg/workflow/safe_outputs_validation.go:13 (constants) + safe_outputs_config_types.go:92 (field URLs string)
• Actual usage: 2-value closed enum (allowed-only, allowed-or-code-region) switched on in validateSafeOutputsURLs.
• Suggested fix: type SafeOutputsURLsPolicy string; type the URLs field.

Additional enum-typing candidates (lower priority)

Location	Current	Suggested type
pkg/workflow/tools_types.go:441	Mode string // stdio/http/remote/local	type MCPServerMode string
pkg/workflow/tools_types.go:384	Mode string // mcp/cli (Playwright)	type PlaywrightMode string
pkg/workflow/engine_definition.go:200	SecretStrategy string	type SecretStrategy string
pkg/workflow/engine_definition.go:184	ProviderEnvMode string	type ProviderEnvMode string
pkg/workflow/mcp_scripts_parser.go:63	MCPScriptsModeHTTP = "http" (untyped)	type MCPScriptsMode string

Pattern to follow: type AuthStrategy string already exists in engine_definition.go:44.

Category 2: any fields with a knowable concrete type

Impact: Low — these sit at JSON boundaries but accept a narrower set than any implies.

Example 1: run identifiers

• Location: pkg/cli/logs_models.go:322 — RunID any, RunNumber any
• Actual: GitHub run id/number from aw_info.json — always numeric (or numeric-string); only ever coerced to string/int.
• Suggested fix: json.Number (or string) to constrain the accepted representations.

Example 2: observability headers

• Location: pkg/parser/import_observability.go:18 — Headers any
• Actual: HTTP headers, logically map[string]string; switched on []any at line 56 only to flatten, no scalar case.
• Suggested fix: map[string]string (verify no scalar form is accepted first).

Category 3: map[string]any for structured records

Impact: Low (borderline — acceptable if upstream schema is unstable)

Example: token usage records

• Location: pkg/cli/token_usage.go:570 — extractUsageRecord(value any) map[string]any + usageNumericValue(...) string-key lookups
• Actual: usage records have a fixed key set (input/output/cache tokens, model, cost).
• Suggested fix: a typed UsageRecord struct decoded at the boundary — removes stringly-typed key access and per-key coercion helpers.

Explicitly NOT flagged: the pervasive map[string]any used for YAML frontmatter (yaml.Unmarshal targets, template data) — that's genuinely generic and idiomatic. Same for pkg/constants env-var-name/path string constants (AnthropicAPIKey = "ANTHROPIC_API_KEY"), which are intentionally bare strings.

---

🎯 What Should We Do About This?

Prioritized by value-per-effort. Everything here is low-risk — no behavioral changes, just tighter types.

Priority 1 (Medium) — Kill copy-paste drift in the two near-duplicate structs

• Embed AggregatedSummaryBase in MCPFailureSummary (Cluster 1).
• Extract CreateEntityBaseConfig for the Create*Config family (Cluster 2).
• Effort: ~3–4 hours total • Benefit: future field edits happen once, not N times.

Priority 2 (Medium/High) — Type the enum strings

• Start with LLMProvider (highest leverage), then PermissionMode and SafeOutputsURLsPolicy.
• Follow the existing constants.EngineName / AuthStrategy pattern.
• Effort: ~1–2 hours per enum • Benefit: compile-time exhaustiveness, no more magic strings.

Priority 3 (Low) — Cleanups

• Rename cli.PolicyRule → FirewallPolicyRule (Cluster 3).
• Optional DiffEntryBase / DiffCountsSummary embeds (Clusters 4–5).
• Tighten RunID/RunNumber/Headers any fields (Category 2).

Implementation Checklist

• Embed AggregatedSummaryBase in MCPFailureSummary
• Extract CreateEntityBaseConfig for the create-entity safe-output family
• Introduce type LLMProvider string + typed constants and field
• Add type PermissionMode string + named constants (currently zero exist)
• Add type SafeOutputsURLsPolicy string
• Rename cli.PolicyRule → FirewallPolicyRule
• (Optional) shared DiffEntryBase / DiffCountsSummary in audit_diff.go
• Run go build ./... + full test suite after each change

Analysis Metadata

• Total Go Files Analyzed: 1,112 (non-test, pkg/)
• Total Type Definitions: ~850 exported
• Duplicate Clusters: 6 actionable (0 exact / 3 near / 3 semantic) + 1 acceptable build-tag group
• Untyped Usage Opportunities: ~10 (dominated by stringly-typed enums, not interface{})
• Detection Method: Serena semantic analysis + pattern matching, findings verified by reading definitions/call sites
• Analysis Date: 2026-07-20

Generated by ✍️ Typist - Go Type Analysis · 372.9 AIC · ⌖ 41.2 AIC · ⊞ 8.6K · ◷

• expires on Jul 21, 2026, 4:14 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 #47070.