[typist] 🔤 Typist: Go Type Consistency Analysis — 8 duplicate clusters + enum-typing opportunities

[github-actions[bot]]

🔤 Typist - Go Type Consistency Analysis

Analysis of repository: github/gh-aw

Executive Summary

I swept every non-test Go file under pkg/ (1,099 files, ~937 type definitions) looking for two things: types we've modeled more than once, and places where we lean on untyped values that could be strongly typed. The good news up front — this codebase is already in strong shape on typing hygiene. There are zero real interface{} declarations in production pkg/ code, and the ~3,781 any / ~2,235 map[string]any occurrences are overwhelmingly legitimate: parsed YAML frontmatter, polymorphic GitHub Actions config (on/runs-on/with/permissions can each be string, array, or object), JSON decode targets, reflection, and the required go/analysis run(pass) (any, error) signature (~50×). So there's no interface{}-cleanup crusade to run here.

Where the real opportunities live is narrower and higher-signal: 8 duplicate/near-duplicate type clusters (the standout being an Experiment state pair that's byte-identical within pkg/cli), and a handful of enum-like string const groups and struct fields that lack a named type — inconsistent with the 40+ type X string enums this repo already defines. Fixing these is mostly low-risk consolidation that removes copy-paste drift and turns a few stringly-typed comparisons into compiler-checked ones. Nice, bounded wins.

Full Analysis Report

Duplicated Type Definitions

Summary Statistics

• Total types analyzed: ~937 (in-scope; excludes _test.go and pkg/linters/*/testdata/)
• Duplicate clusters found: 8
• Exact duplicates: 2 clusters
• Near duplicates: 4 clusters
• Semantic duplicates: 2 clusters

Deliberately excluded as intentional: build-tag twins (ProgressBar, SpinnerWrapper, RepositoryFeatures), already-aliased config types (Close*Config, Missing*/ReportIncompleteConfig, AddCommentConfig), MCP configs that already share types.BaseMCPServerConfig via embedding, genuinely-different same-name types across packages (PolicyRule in cli/firewall vs intent), and external-tool JSON DTOs (zizmorFinding, poutineFinding, runnerGuardFinding).

---

Cluster 1: Experiment state — ExperimentState / experimentStateJSON

Kind: Exact duplicate · Occurrences: 2 · Impact: High (single source of truth, both in pkg/cli)

Locations:

1. pkg/cli/experiments_command.go:35 — type ExperimentState struct { ... }
2. pkg/cli/audit_report_experiments.go:35 — type experimentStateJSON struct { ... }

The exported ExperimentState and the private experimentStateJSON are field- and tag-identical (they both mirror the state.json written by pick_experiment.cjs). The audit file keeps its own lowercase copy instead of reusing the exported type in the same package.

// Both, identical:
type ExperimentState struct {
    Counts map[string]map[string]int `json:"counts"`
    Runs   []ExperimentRunRecord     `json:"runs,omitempty"`
}

Recommendation: Delete experimentStateJSON and use ExperimentState (same package, no import needed). Effort: ~30 min · Benefit: one schema, no drift between the writer and the auditor.

---

Cluster 2: Experiment run record — ExperimentRunRecord / experimentRunRecord

Kind: Exact duplicate · Occurrences: 2 · Impact: High

Locations:

1. pkg/cli/experiments_command.go:41
2. pkg/cli/audit_report_experiments.go:42

// Both, byte-identical fields + json tags:
type ExperimentRunRecord struct {
    RunID       string            `json:"run_id"`
    Timestamp   string            `json:"timestamp"`
    Assignments map[string]string `json:"assignments"`
}

Recommendation: Same fix as Cluster 1 — drop the private experimentRunRecord, reuse ExperimentRunRecord. These two clusters are one PR. Effort: rolls into Cluster 1.

---

Cluster 3: AuditComparisonIntDelta / AuditComparisonStringDelta

Kind: Near duplicate · Occurrences: 2 · Impact: Medium

Locations:

1. pkg/cli/audit_comparison.go:45
2. pkg/cli/audit_comparison.go:51

Same {Before, After, Changed} shape; the only difference is the element type (int vs string). Textbook case for a generic type.

type Delta[T any] struct {
    Before  T    `json:"before"`
    After   T    `json:"after"`
    Changed bool `json:"changed"`
}
// AuditComparisonIntDelta -> Delta[int], AuditComparisonStringDelta -> Delta[string]

Effort: ~1 hr · Benefit: one implementation, trivially extends to other element types.

---

Cluster 4: AccessLogSummary / FirewallLogSummary

Kind: Near duplicate (~80% overlap) · Occurrences: 2 · Impact: Medium

Locations:

1. pkg/cli/logs_report_firewall.go:11
2. pkg/cli/logs_report_firewall.go:21

Both carry TotalRequests, allowed/blocked counters, AllowedDomains, BlockedDomains, ByWorkflow. They differ only in field naming (AllowedCount/BlockedCount vs AllowedRequests/BlockedRequests) and one extra RequestsByDomain map on the firewall variant.

Recommendation: Extract a shared base struct and embed it, aligning the counter field names. Effort: 1–2 hr.

---

Cluster 5: DomainAnalysis / FirewallAnalysis

Kind: Near duplicate · Occurrences: 2 · Impact: Medium

Locations:

1. pkg/cli/access_log.go:34
2. pkg/cli/firewall_log.go:133

Both embed DomainBuckets + TotalRequests + allowed/blocked counts and implement AddMetrics(LogAnalysis); FirewallAnalysis only adds RequestsByDomain. A shared analysis base would remove the parallel maintenance. Effort: 1–2 hr.

---

Cluster 6: MCPFailureSummary should embed AggregatedSummaryBase

Kind: Near duplicate · Occurrences: 2 · Impact: Medium (self-documented drift)

Locations:

1. pkg/cli/logs_models.go:173 — MCPFailureSummary
2. pkg/cli/logs_models.go:157 — AggregatedSummaryBase

MCPFailureSummary re-declares 4 of AggregatedSummaryBase's fields (Count, Workflows, WorkflowsDisplay, RunIDs) instead of embedding it — and the base's own doc comment already flags that sibling types should embed it. MissingToolSummary/MissingDataSummary already do.

Recommendation: Embed AggregatedSummaryBase in MCPFailureSummary. Effort: ~30 min · Benefit: kills copy-paste drift, matches the established pattern.

---

Cluster 7: Per-server MCP metrics (semantic, 4×)

Kind: Semantic duplicate · Occurrences: 4 · Impact: Medium (larger refactor)

Locations:

1. pkg/cli/audit_report.go:211 — MCPServerStats
2. pkg/cli/gateway_logs_types.go:85 — GatewayServerMetrics
3. pkg/cli/audit_cross_run.go:81 — MCPServerCrossRunHealth
4. pkg/cli/audit_expanded.go:90 — MCPServerHealthDetail

Four separate per-MCP-server stat structs, all keyed on ServerName, all with overlapping RequestCount / ToolCallCount (TotalCalls) / ErrorCount plus error-rate/latency/size variants. Same concept modeled four times across the audit/gateway reports.

Recommendation: Extract a shared mcpServerMetricsCore and embed it in each report-specific struct. Bigger surface — do it only if these reports keep evolving together. Effort: 3–4 hr.

---

Cluster 8: Token-usage metrics family (semantic, 4×)

Kind: Semantic duplicate · Occurrences: 4 · Impact: Medium

Locations:

1. pkg/cli/copilot_events_jsonl.go:100 — copilotUsageMetrics
2. pkg/cli/token_usage.go:75 — ModelTokenUsage
3. pkg/cli/token_usage.go:90 — ModelTokenUsageRow
4. pkg/cli/token_usage.go:27 — TokenUsageEntry

The {InputTokens, OutputTokens, CacheReadTokens, CacheWriteTokens} quartet (plus Effective/Reasoning) repeats across all four. Note the json-tag inconsistency: copilotUsageMetrics uses camelCase while the token_usage.go trio uses snake_case; ModelTokenUsage vs ModelTokenUsageRow are themselves a flattened near-dup.

Recommendation: Extract a shared tokenCounts embed. Reconcile the json tags carefully (they're on the wire). Effort: 3–4 hr.

---

Untyped Usages

Summary Statistics

• Real interface{} declarations (non-test pkg): 0 (the one hit is a doc-comment reference)
• any occurrences: ~3,781 — overwhelmingly idiomatic (YAML/Actions config, JSON decode, reflection, go/analysis)
• map[string]any occurrences: ~2,235 — overwhelmingly idiomatic polymorphic config; not recommended for typing
• Enum-like const groups / string fields worth a named type: ~8 high-value

The headline here is a non-finding: there is no interface{} problem to fix. The improvable surface is almost entirely enum-shaped string consts/fields — inconsistent with the 40+ type X string enums the repo already defines.

---

Category 1: Enum-like string const groups missing a named type

Impact: Medium — turns comment-documented "closed sets" into compiler-enforced ones and makes switch statements exhaustively checkable.

#	Location	Current	Suggested	Benefit
1	pkg/workflow/llm_provider.go:13	const ( LLMProviderGitHub = "github"; ...Anthropic; ...OpenAI )	type LLMProvider string + typed consts; use for normalizeLLMProvider param/return and EngineConfig.LLMProvider	5+ switches become exhaustive; provider typos caught at compile time
2	pkg/workflow/safe_outputs_validation.go:13	SafeOutputsURLsPolicyAllowedOnly = "allowed-only"; ...AllowedOrCodeRegion	type SafeOutputsURLsPolicy string; type the config field	validated policy field gains compile-time value constraints
3	pkg/github/label_objective_mapping_constants.go:136	MultiLabelLogicMax/Sum/First = "max"/"sum"/"first"	type MultiLabelLogic string; type field at label_objective_mapping.go:27	bare string field (defaults "max") documents its closed set
4	pkg/cli/mcp_registry_types.go:107	StatusActive/Inactive = "active"/"inactive"	type ServerStatus string	two-value enum stops accepting arbitrary strings
5	pkg/cli/mcp_registry_types.go:113	ArgumentTypePositional/Named	type ArgumentType string	closed enum for argument kind
6	pkg/workflow/mcp_scripts_parser.go:63	MCPScriptsModeHTTP = "http"	type MCPScriptsMode string (comment already says "transport modes")	future transport modes constrained to one type

The strongest three are #1 LLMProvider, #2 SafeOutputsURLsPolicy, and #3 MultiLabelLogic, since they're validated/switched-on values flowing through several functions.

Example: LLMProvider — before / after

// BEFORE (pkg/workflow/llm_provider.go)
const (
    LLMProviderGitHub    = "github"
    LLMProviderAnthropic = "anthropic"
    LLMProviderOpenAI    = "openai"
)
func normalizeLLMProvider(provider string) string { ... }

// AFTER
type LLMProvider string
const (
    LLMProviderGitHub    LLMProvider = "github"
    LLMProviderAnthropic LLMProvider = "anthropic"
    LLMProviderOpenAI    LLMProvider = "openai"
)
func normalizeLLMProvider(provider string) LLMProvider { ... }
// EngineConfig.LLMProvider LLMProvider  // was: string

---

Category 2: string struct fields whose comment already declares an enum

Impact: Medium — the closed set exists only in a // comment today; a named type + consts makes it real.

Location	Current	Suggested
pkg/cli/run_workflow_execution.go:52	Status string // "triggered", "dry_run", "error"	type RunStatus string + named consts
pkg/cli/audit_cross_run.go:106 (& :113)	OverallStatus string // "allowed","denied","mixed"	type DomainStatus string (allowed/denied/mixed/absent)
pkg/cli/gateway_logs_timeline.go:91	Status string // "success" or "error"	type TimelineStatus string (file already defines TimelineEventSource/Kind enums)

---

Category 3: Small any struct-field cleanups

Impact: Low–Medium.

• pkg/cli/logs_models.go:321-322 — RunID any / RunNumber any. The same fields are typed int64 elsewhere (run_workflow_execution.go:53, audit_cross_run.go:112). Candidates for int64 — but verify the aw_info.json source shape first, since any may have been chosen to tolerate string-vs-number JSON; if so, keep any or add an explicit json.Number decode.
• pkg/workflow/mcp_scripts_generator.go:21 — InputSchema map[string]any. The paired MCPScriptParam (mcp_scripts_parser.go:56) already models each field, so a typed JSON-schema struct is possible — but borderline, since JSON-schema shapes are open-ended. Low priority.

Not recommended for typing (idiomatic, leave as-is): frontmatter On/Permissions/Concurrency/Jobs, workflow_data.go Tools/Features/Runtimes, copilot_setup With/Env/Permissions, devcontainer Settings, and runtime_definitions.go ExtraFields. Their comments explicitly say the shapes are too dynamic to type — they model polymorphic GitHub Actions / YAML config.

---

Refactoring Recommendations (prioritized)

Priority 1 — Quick, unambiguous consolidation (Clusters 1, 2, 6)

Delete experimentStateJSON + experimentRunRecord (reuse the exported types), and embed AggregatedSummaryBase in MCPFailureSummary. All same-package, no API changes. ~1.5 hr total, high value.

Priority 2 — Named enum types (Category 1, top 3)

Introduce type LLMProvider string, type SafeOutputsURLsPolicy string, type MultiLabelLogic string and thread them through their consts/fields/switches. Low risk, aligns with 40+ existing enums. ~3–4 hr.

Priority 3 — Structural near-dup consolidation (Clusters 3, 4, 5)

Generic Delta[T], shared log-summary base, shared analysis base. Mechanical but touches more sites. ~4–5 hr.

Priority 4 — Larger semantic families (Clusters 7, 8) + Category 2/3

Shared MCP-server-metrics and token-counts embeds; enum types for comment-documented status fields; the RunID/RunNumber cleanup after verifying the JSON source. Optional / as those areas evolve.

---

Implementation Checklist

• Consolidate ExperimentState/ExperimentRunRecord duplicates (drop private copies)
• Embed AggregatedSummaryBase in MCPFailureSummary
• Introduce LLMProvider, SafeOutputsURLsPolicy, MultiLabelLogic named types
• Add named types for the remaining enum const groups (Category 1 Add workflow: githubnext/agentics/weekly-research #4–6)
• Generic Delta[T] for the audit-comparison deltas
• Extract shared bases for log-summary / analysis / MCP-server-metrics / token-counts families
• Verify aw_info.json shape before typing RunID/RunNumber
• Run full test suite (make test) after each consolidation

---

Analysis Metadata

• Total Go files analyzed: 1,099 (non-test, under pkg/)
• Total type definitions: ~937 in-scope
• Duplicate clusters: 8 (2 exact, 4 near, 2 semantic)
• Real interface{} declarations: 0
• Enum-shaped untyped locations flagged: ~9
• Detection method: Serena semantic analysis + ripgrep pattern matching, findings verified by reading sources
• Analysis date: 2026-07-16

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

• expires on Jul 17, 2026, 4:12 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 #46240.