[typist] Typist - Go Type Consistency Analysis

[github-actions[bot]]

🔤 Typist — Go Type Consistency Analysis

Analysis of repository: github/gh-aw · run §32477322358

Executive Summary

I scanned all 1,275 non-test .go files under pkg/ (~1,225 top-level type declarations) for duplicated types and untyped usage. The good news: this codebase has already done real type-safety work — there's a documented migration history (scratchpad/go-type-patterns.md) covering engine names, workflow IDs, tool names, and PAT types, and the bulk of any/map[string]any usage (~4,283 occurrences) is legitimately justified dynamic YAML/JSON frontmatter parsing, not laziness.

That said, I found a handful of concrete, worthwhile opportunities: the sharpest one is in pkg/cli itself, where two nearly-identical outcome enums (OutcomeResult and OutcomeStatus) live in the same package and are both embedded in the same OutcomeReport struct — a duplicate that's easy to consolidate and a good first PR. There's also a second, hand-rolled GitHub Actions workflow/step model in pkg/cli/copilot_setup.go that duplicates pkg/workflow's existing WorkflowStep/Job types, three overlapping "network log entry" structs with inconsistent field types (Status as string in two, int in a third), and a few enum-shaped string constants (reaction types, safe-outputs URL policy, MCP param types) still declared as bare string instead of named types. None of this is urgent, but each item below is a small, low-risk, high-clarity fix.

Full Analysis Report

Duplicated Type Definitions

Summary Statistics

• Total type declarations found: ~1,225 (≈1,160 structs/interfaces + ~65 enum-like types) across 1,275 files
• Duplicate clusters found: 10 (2 near-duplicate structural clusters flagged low-priority as expected Go idioms)
• Exact duplicates: 0 (Go's compiler prevents same-name/same-package collisions; findings are cross-package)
• Near duplicates: 7
• Semantic duplicates: 3

Cluster 1: OutcomeResult vs OutcomeStatus — same package, parallel enums

Type: Near-duplicate | Occurrences: 2 | Impact: High — same concept, two competing enums in one package

Locations:

1. pkg/cli/outcome_eval.go:27 — type OutcomeResult string (accepted, rejected, ignored, pending, unknown, lifecycle, lifecycle_close, error)
2. pkg/cli/outcome_evaluation.go:12 — type OutcomeStatus string (accepted, rejected, pending, ignored, skipped, unknown, lifecycle, lifecycle_close)

7 of 8 values are shared verbatim; only error vs skipped differ. Worse, OutcomeReport (outcome_eval.go:41) embeds OutcomeEvaluation (which carries OutcomeStatus) and has its own Result OutcomeResult field — the same struct carries both parallel enums simultaneously.

Recommendation: Merge into one classification enum (add a skipped/error value to whichever wins) and drop the other. Estimated effort: 1-2 hours. Benefit: removes ambiguity about which enum a given OutcomeReport field actually reflects.

---

Cluster 2: Network/audit "log entry" structs

Type: Near-duplicate | Occurrences: 3 | Impact: Medium — overlapping fields, inconsistent types

Locations:

1. pkg/cli/access_log.go:21 — AccessLogEntry{Timestamp, Duration, ClientIP, Status, Size, Method, URL, User, Hierarchy, Type string}
2. pkg/cli/firewall_log.go:118 — FirewallLogEntry{Timestamp, ClientIPPort, Domain, DestIPPort, Proto, Method, Status, Decision, URL, UserAgent string}
3. pkg/cli/firewall_policy.go:50 — AuditLogEntry{Schema, Client, Host, Dest, Method string, Status int, Decision, URL string}

Three independently-parsed "one network request line" records with overlapping fields (Timestamp/Client*/Method/Status/URL/Decision), but Status is string in two and int in the third, and ClientIP vs ClientIPPort vs Client name the same thing differently.

Recommendation: Extract a common NetworkLogEntry base (mirroring the AnalysisBase/FirewallSummaryBase pattern the same files already use one level up) and embed it. Estimated effort: 2-3 hours.

---

Cluster 3: ToolUsageSummary vs ToolUsageInfo

Type: Near-duplicate | Occurrences: 2 | Impact: Medium

• pkg/cli/logs_report_tools.go:13 — ToolUsageSummary{Name, TotalCalls, Runs, MaxOutputSize, MaxDuration}
• pkg/cli/audit_report.go:155 — ToolUsageInfo{Name, CallCount, MaxInputSize, MaxOutputSize, MaxDuration, OutputSample}

Same per-tool aggregation concept, computed twice for two different reports (logs vs audit) with different field names (TotalCalls vs CallCount).

Recommendation: Unify into one ToolUsageStats type with optional fields, shared by both report builders. Estimated effort: 1-2 hours.

---

Cluster 4: Duplicate GitHub Actions workflow model (cli vs workflow)

Type: Semantic duplicate | Occurrences: 2 | Impact: High — a second bespoke Actions-YAML model

• pkg/workflow/step_types.go:17 — WorkflowStep{Name, ID, If, Uses, Run, WorkingDirectory, Shell, With, Env, ContinueOnError, TimeoutMinutes}
• pkg/cli/copilot_setup.go:356,365,372 — CopilotWorkflowStep{Name, Uses, Run, With, Env} + WorkflowJob{RunsOn, Permissions, Steps} + Workflow{Name, On, Jobs}

pkg/cli re-implements a second, smaller "GitHub Actions workflow file" object model from scratch just to scaffold copilot-setup-steps.yml, instead of reusing pkg/workflow's existing step/job types.

Recommendation: Reuse workflow.WorkflowStep/workflow.Job (or extract a minimal shared actionsyaml package). Estimated effort: 2-4 hours. Benefit: one source of truth for "what a GitHub Actions step/job looks like."

---

Cluster 5: MCP server config family — mostly deduped, one straggler

Type: Semantic duplicate | Occurrences: 4 | Impact: Low

• pkg/types/mcp.go:6 — BaseMCPServerConfig (shared base, already embedded by the next two — good pattern)
• pkg/parser/mcp.go:39 — RegistryMCPServerConfig{types.BaseMCPServerConfig; ...}
• pkg/workflow/tools_types.go:519 — MCPServerConfig{types.BaseMCPServerConfig; ...}
• pkg/cli/mcp_config_file.go:22 — VSCodeMCPServer{Type, Command, Args, Tools, CWD} — does not embed BaseMCPServerConfig despite 3/4 fields overlapping

Recommendation: Low priority — VSCodeMCPServer mirrors an external VS Code JSON schema, so full unification isn't required, but consider embedding BaseMCPServerConfig for the shared subset.

---

Clusters 6-10 (lower priority — noted for completeness)

• Wire-format shims: DomainAnalysis/FirewallAnalysis both embed AnalysisBase but each hand-rolls its own MarshalJSON/wire struct — worth consolidating the shim logic, not the types. Informational only.
• Recommendation vs AuditComparisonRecommendation: same word, subset of fields (pkg/cli/audit_report.go:75 vs pkg/cli/audit_comparison.go:68); a naming pass (AuditComparisonAction) would reduce confusion — low priority.
• Outcome* naming family is large: OutcomeResult, OutcomeStatus, OutcomeReport, OutcomeSummary, OutcomeEvaluation, OutcomesData, OutcomesConfig, OutcomesHistoryConfig — recommend a naming/consolidation pass alongside fixing Cluster 1.
• "Status" fields inconsistently typed across domains: bare string in some structs, bare int in AuditLogEntry, and a proper enum (WorkflowStatus, pkg/cli/status_command.go:31) elsewhere — one canonical enum per domain (network status vs. GH Actions run status) would remove several stringly-typed fields.
• ProgressBar/SpinnerWrapper build-tag pairs (pkg/console/progress.go + progress_wasm.go, spinner.go + spinner_wasm.go): expected native/wasm platform split under build tags — not a refactor target, included only to confirm it was checked and correctly skipped.

---

Untyped Usages

Summary Statistics

• interface{} occurrences: 16 (all confined to pkg/linters/*/testdata/*.go fixtures — not real code, skip)
• any occurrences: ~4,283 (dominant pattern map[string]any for dynamic YAML/JSON — mostly justified and already documented project policy)
• map[string]any/map[string]interface{}: 2,541
• []any/[]interface{}: 469
• Flagged as genuine opportunities: ~9

The project's own scratchpad/go-type-patterns.md documents its any-usage philosophy and prior migrations (EngineName, WorkflowID, GitHubToolName, GitHubAllowedTools, etc.), so most bulk any usage below was deliberately excluded as justified dynamic parsing. The items below are the residual, genuine opportunities.

Category 1: Struct fields that are secretly fixed-value enums

Impact: Medium — these are implicit enums hiding behind bare string, validated only at runtime

1. Safe-outputs URL policy — pkg/workflow/safe_outputs_validation.go:16-17 defines SafeOutputsURLsPolicyAllowedOnly = "allowed-only" and ...AllowedOrCodeRegion = "allowed-or-code-region" as untyped bare consts, used in a switch config.URLs where URLs string (pkg/workflow/safe_outputs_config_types.go).

   // Suggested
   type SafeOutputsURLsPolicy string
   const (
       SafeOutputsURLsPolicyAllowedOnly         SafeOutputsURLsPolicy = "allowed-only"
       SafeOutputsURLsPolicyAllowedOrCodeRegion  SafeOutputsURLsPolicy = "allowed-or-code-region"
   )

   Benefit: the compiler rejects a typo like "allow-only" instead of only failing validation at runtime.

2. Reaction types — pkg/workflow/reactions.go:12-21 has validReactions map[string]bool with 8 literal keys (+1, -1, laugh, confused, heart, hooray, rocket, eyes), consumed via AIReaction string (pkg/workflow/workflow_data.go:118).
   Suggested: type ReactionType string + named consts, validReactions map[ReactionType]bool.

3. MCP param type — pkg/workflow/mcp_scripts_parser.go:60: MCPScriptParam.Type string // JSON schema type (string, number, boolean, array, object) — the comment enumerates exactly 5 legal values but the field stays a bare string.
   Suggested: type MCPParamType string with 5 named consts — enables exhaustive switch-based codegen and rejects typos in tool-schema authoring.

Category 2: Mixed-type ID field (JSON number-or-string)

Impact: Medium — real runtime ambiguity, not just style

4. pkg/cli/logs_models.go:358-359 — RunID any / RunNumber any on the aw_info.json-derived struct, while sibling structs in the same file type RunID int64 (:123, :280) or string (:329). This stems from ${{ github.run_id }} serializing as either a JSON number or a templated string depending on producer.
   Suggested: a small NumericID type with a custom UnmarshalJSON that accepts both forms and normalizes to int64, removing the scattered %v/fmt.Sprintf formatting at call sites.

Category 3: Untyped constants that will need to become enums

Impact: Low-Medium — pre-emptive, avoids future untyped→typed churn

5. pkg/workflow/frontmatter_types.go:10 — const RunnerTopologyArcDind = "arc-dind", compared via switch config.Topology (pkg/workflow/runner_config.go:46). Only one legal value exists today, but the switch/error-message pattern ("unsupported runner.topology value %q; supported values: %q") signals it's meant to grow. Suggested: introduce type RunnerTopology string now, before a second value arrives.

6. pkg/workflow/behavior_defined_engine.go:19-21 — behaviorSecretStrategyUniversalLLMConsumer and behaviorProviderEnvModeUniversalLLMConsumer are two conceptually distinct bare-string consts that happen to share the literal value "universal-llm-consumer". If one changes, the other silently diverges. Suggested: give each its own named type (BehaviorSecretStrategy, BehaviorProviderEnvMode) even while they share a value today.

Minor/low-priority mentions

• pkg/console/console_types.go:50 — FormField.Value any: zero constructors/usages found anywhere in pkg/ except form_wasm.go; likely dead or JS-bridge-only code, worth a dead-code check rather than a type fix.
• pkg/console/layout_wasm.go:16 — func LayoutEmphasisBox(content string, color any) string: color is unused in the function body and there's no non-wasm counterpart; likely an orphaned parameter worth deleting.
• pkg/workflow/step_shell_validator.go:118 — func checkStepGHToken(step any, ...): technically justified since a workflow step can be a string shorthand or a map, but worth an explicit doc comment.

Explicitly reviewed and judged JUSTIFIED (skip)

• deepCopyAny(v any) any (pkg/workflow/behavior_defined_engine.go:872) — textbook recursive deep-copy helper over arbitrary yaml.Unmarshal output.
• ID any on JSON-RPC payload structs (pkg/cli/gateway_logs_types.go:179,190) — JSON-RPC 2.0 spec allows id to be string, number, or null; standard protocol pattern.
• Engine any, RunsOn any, Checkout any, Imports any, Evals any in pkg/workflow/frontmatter_types.go — each already carries a doc comment justifying the union-of-YAML-shapes rationale.
• Dozens of (value any)/map[string]any helpers in pkg/parser/mcp.go, pkg/parser/tools_merger.go, pkg/parser/schema_suggestions.go operating on raw parsed YAML/JSON Schema before validation — the core "dynamic data" pattern the project's style guide explicitly endorses.

---

Refactoring Recommendations

Priority 1: Consolidate the two outcome enums (Cluster 1)

Steps: 1) Pick a winner between OutcomeResult/OutcomeStatus (or merge into one enum with all 9 distinct values). 2) Update OutcomeReport to carry a single field. 3) Update all switch statements and comparisons. 4) Run tests.
Estimated effort: 1-2 hours. Impact: High — removes ambiguity in a package that's actively used for outcome evaluation.

Priority 2: Reuse pkg/workflow step/job types in copilot_setup.go (Cluster 4)

Steps: 1) Check whether workflow.WorkflowStep/Job can serialize to the subset copilot-setup-steps.yml needs. 2) Replace CopilotWorkflowStep/WorkflowJob/Workflow with the existing types (or a thin shared package). 3) Update the scaffold-generation call sites. 4) Run tests.
Estimated effort: 2-4 hours. Impact: High — removes a full duplicate object model.

Priority 3: Merge overlapping log-entry structs (Cluster 2) and tool-usage structs (Cluster 3)

Steps: extract common base structs, normalize Status to a single type, run tests.
Estimated effort: 3-5 hours combined. Impact: Medium.

Priority 4: Type the implicit enums (Untyped Usages Categories 1 & 3)

Steps: introduce SafeOutputsURLsPolicy, ReactionType, MCPParamType, RunnerTopology, BehaviorSecretStrategy/BehaviorProviderEnvMode as named string types with consts; update field types and switch statements.
Estimated effort: 3-4 hours combined. Impact: Medium — mostly compile-time safety wins on validation logic that already exists.

Priority 5 (optional cleanup): Investigate two likely-dead any fields

FormField.Value and LayoutEmphasisBox's unused color parameter — confirm dead/orphaned and remove, or document why they're needed.

---

Implementation Checklist

• Merge OutcomeResult/OutcomeStatus into one enum (Priority 1)
• Replace copilot_setup.go's bespoke workflow model with pkg/workflow types (Priority 2)
• Extract a shared NetworkLogEntry base for AccessLogEntry/FirewallLogEntry/AuditLogEntry (Priority 3)
• Unify ToolUsageSummary/ToolUsageInfo into one ToolUsageStats type (Priority 3)
• Add named types for SafeOutputsURLsPolicy*, ReactionType, MCPParamType, RunnerTopology, behavior-strategy consts (Priority 4)
• Add a NumericID type with custom UnmarshalJSON for RunID/RunNumber in logs_models.go
• Confirm and remove/document FormField.Value and LayoutEmphasisBox's unused color param
• Run full test suite after each change

Analysis Metadata

• Total Go files analyzed: 1,275 (non-test, pkg/ only)
• Total type declarations found: ~1,225
• Duplicate clusters: 10 (5 actionable, 5 low-priority/informational)
• Untyped usage locations flagged as opportunities: ~9 (out of ~4,283 total any occurrences, the vast majority justified)
• Detection method: Serena/grep-based semantic + pattern analysis across two parallel analysis passes, cross-referenced
• Analysis date: 2026-08-21

References:

• §32477322358

Generated by ✍️ Typist - Go Type Analysis · agent · 226.2 AIC · ⌖ 9.95 AIC · ⊞ 9.1K · ◷

• expires on Aug 22, 2026, 3:40 AM UTC-08:00

[github-actions[bot]]

This discussion was automatically closed because it expired on 2026-08-22T11:40:33.251Z.

Closed by Workflow