[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: this codebase is already in strong shape on type consistency. I analyzed ~820 top-level type definitions across 947 non-test .go files under pkg/, and there are zero exact cross-package duplicate structs needing a merge. Where a name repeats across packages it's almost always an intentional type X = pkg.Y alias (~20 of them, e.g. ActionPin, LogMetrics, SanitizeOptions, InputDefinition) or a //go:build js || wasm platform stub — exactly the pattern you want.

So this is a friendly nudge on a few small holdovers, not a big cleanup. On duplication I found 4 near-duplicate and 3 semantic-duplicate clusters, mostly in pkg/cli log/audit reporting where parallel structs drifted in field naming. On typing, interface{}/any usage is idiomatic everywhere (YAML/JSON frontmatter, the analysis.Pass framework signature, generics) — nothing fixable. The real quick wins are 3 string-const groups that are implicit enums but aren't named string types yet, mildly inconsistent given the codebase already does this well (ActionMode, UniversalLLMBackend).

Full Analysis Report

Duplicated Type Definitions

• Total types analyzed: ~820 (non-test) · Clusters: 7 · Exact: 0 · Near: 4 · Semantic: 3
• Already deduplicated via aliases: ~20 declarations (correctly factored — not flagged)
• Every cluster was verified by reading actual field lists, not matched by name.

Cluster 1: MCPToolUsageSummary vs MCPToolUsageData (near) — highest value, lowest risk

Same package, near-identical: pkg/cli/logs_models.go:178 and pkg/cli/audit_report.go:163.

type MCPToolUsageSummary struct { Summary []MCPToolSummary; Servers []MCPServerStats; ToolCalls []MCPToolCall; FilteredEvents []DifcFilteredEvent }
// audit_report.go:163 — identical element types + one extra optional pointer
type MCPToolUsageData struct { Summary []MCPToolSummary; ToolCalls []MCPToolCall; Servers []MCPServerStats; FilteredEvents []DifcFilteredEvent; GuardPolicySummary *GuardPolicySummary }

Recommendation: Collapse to one canonical type (add the optional GuardPolicySummary), alias the other. No import churn. ~1 hour.

Cluster 2: DomainAnalysis vs FirewallAnalysis (near)

pkg/cli/access_log.go:34 (AllowedCount, BlockedCount) vs pkg/cli/firewall_log.go:131 (AllowedRequests, BlockedRequests + RequestsByDomain). Both embed DomainBuckets; counters differ only by name. Same divergence in AccessLogSummary (logs_report_firewall.go:12) and FirewallLogSummary (:22). Recommendation: Unify counter names, extract a shared base. 2-3 hours.

Cluster 3: Diff count summaries (near) — all in pkg/cli/audit_diff.go

FirewallDiffSummary (:50), MCPToolsDiffSummary (:240), ToolCallsDiffSummary (:299) repeat a "new/removed/changed counts + anomaly flags" shape. Recommendation: Extract DiffCountsSummary{ New, Removed, Changed int; HasAnomalies bool; AnomalyCount int } and embed. 2 hours.

Clusters 4-6 (semantic, low priority — leave as-is)

• Proxy log entries: AccessLogEntry (access_log.go:20) vs FirewallLogEntry (firewall_log.go:116) — different log formats; merging adds empty fields.
• GitHub PR models: PRInfo (pr_command.go:27), PullRequest (pr_automerge.go:21), PullRequestData (intent/resolver.go:49) — minimal projections of distinct gh --json calls.
• Workflow-run models: WorkflowRunInfo (run_workflow_tracking.go:19, 5 fields) is a strict subset of WorkflowRun (logs_models.go:50, 28 fields). Slim struct intentional for the poll path.

Untyped Usages

• interface{}: ~1 real (rest are linter fixtures) — 0 fixable
• any: idiomatic everywhere (YAML/JSON boundary, analysis.Pass signature, generics) — 0 fixable
• Implicit string-const enums: 3 quick-win groups + 3 struct fields
• .(map[string]any) assertions: 34 across 15 files — idiomatic frontmatter walking, already mitigated by pkg/typeutil/convert.go

Category 1: interface{} / any — nothing to fix

Correct Go at the serialization boundary: map[string]any for decoded frontmatter, func run(*analysis.Pass) (any, error) mandated by golang.org/x/tools/go/analysis, generics. By-design polymorphic cases like ParseVersionValue(version any) (stringutil/stringutil.go:54) and ReportFailureAsIssue any (workflow/compiler_types.go:736, holds bool or []string) are appropriate. pkg/typeutil/convert.go is the well-designed typed boundary. No recommendations.

Category 2: Untyped string consts that are really enums — the real wins

These are implicit enums declared as untyped string, while the codebase already models the same shape as named types (ActionMode, UniversalLLMBackend).

• LLM provider — pkg/workflow/llm_provider.go:11-13: LLMProviderGitHub = "github" etc. → type LLMProvider string. Note universal_llm_consumer_engine.go:15 already does this with type UniversalLLMBackend string for the same names — worth resolving.
• Safe-outputs URL policy — pkg/workflow/safe_outputs_validation.go:13-14: "allowed-only" / "allowed-or-code-region" → type SafeOutputsURLsPolicy string + IsValid() (validated via a switch at line 23).
• MCP scripts mode — pkg/workflow/mcp_scripts_parser.go:65: "http" → type MCPScriptsMode string.

Higher-impact stringly-typed struct fields in pkg/workflow/engine.go:

• :46 EngineConfig.ID string — compared against "copilot", "codex", "claude", "custom" in 8+ sites (e.g. permissions_compiler_validator.go:212, mcp_setup_generator.go:116, threat_detection.go:290). A type EngineID string removes scattered magic strings. Highest-value fix.
• :49 .LLMProvider string (comment documents github|anthropic|openai) → use LLMProvider.
• :50 .PermissionMode string ("acceptEdits", "plan" per claude_engine.go:237) → candidate type PermissionMode string.

Not recommended: port consts in constants/constants.go:105-139 flow into fmt.Sprintf("%d")/net APIs — a type Port int forces pervasive conversions for little gain.

Category 3: Type assertions — idiomatic

~34 .(map[string]any) assertions walk decoded frontmatter YAML. Inherent shape of dynamic config; safe helpers already factored into pkg/typeutil/convert.go (LookupMap, LookupString, ParseBool). A nil-safety cleanup, not a missing-type problem. No new type warranted.

Refactoring Recommendations

1. High — consolidate pkg/cli reporting near-duplicates: Cluster 1 then Cluster 2. ~3-4h, removes drift.
2. Medium — name implicit string enums: LLMProvider, SafeOutputsURLsPolicy, MCPScriptsMode, ideally EngineID. ~2-4h, improves switch exhaustiveness/grep-ability.
3. Low — extract DiffCountsSummary base (Cluster 3). ~2h.

Implementation Checklist

• Collapse MCPToolUsageSummary/MCPToolUsageData (Cluster 1)
• Unify DomainAnalysis/FirewallAnalysis counter names + shared base (Cluster 2)
• Extract DiffCountsSummary base (Cluster 3)
• Add type LLMProvider string; retype consts + EngineConfig.LLMProvider
• Add type SafeOutputsURLsPolicy string + IsValid()
• Add type MCPScriptsMode string
• (Stretch) type EngineID string replacing magic engine-ID literals
• Run full test suite

Analysis Metadata

• Files analyzed: 947 (non-test, pkg/) · Type definitions: ~820 · Duplicate clusters: 7 (0 exact, 4 near, 3 semantic) · Untyped findings: 3 const-enum wins + 3 struct fields
• Method: Serena semantic analysis + pattern matching, field-level verification · Date: 2026-06-24

Generated by ✍️ Typist - Go Type Analysis · 427.3 AIC · ⌖ 16.6 AIC · ⊞ 8.8K · ◷

• expires on Jun 25, 2026, 4:21 AM UTC-08:00