[typist] 🔤 Typist — Go Type Consistency Analysis (2026-06-29)

[github-actions[bot]]

🔤 Typist — Go Type Consistency Analysis

Analysis of repository: github/gh-aw • 2026-06-29

Executive Summary

Good news up front: gh-aw is already a strongly-typed codebase. I swept every non-test .go file under pkg/ — 974 files, 709 type definitions (612 structs) — and the usual type-safety smells are mostly absent. interface{} has been all but eliminated from source (just 1 occurrence, inside a doc comment). The any keyword appears a lot, but the overwhelming majority are legitimate dynamic boundaries — JSON/YAML frontmatter, MCP payloads, and a purpose-built typeutil converter — exactly where any belongs. The team already embeds shared base structs (BaseSafeOutputConfig, UpdateEntityConfig) and uses named string enums (ActionMode, ShellType), so the idioms for closing the few remaining gaps are already in the codebase.

So this is less "we have a problem" and more "a handful of small, high-confidence hardening wins." The two best: name two untyped constant groups (SafeOutputsURLsPolicy, GuardPolicyErrorCode), and one low-effort struct consolidation (the repeated Allowed/Blocked pair across six safe-output configs). None of the 13 duplicate name collisions were real — every one is an intentional alias, build-tag platform variant, or linter testdata. Net: type safety is in great shape; below is polish, not rescue.

Full Analysis Report

Duplicated Type Definitions

Stats: 709 types analyzed (612 structs) • 4 genuine clusters • 1 exact, 2 near, 1 semantic • 13 name-collisions ruled out (all type X = Y re-export aliases, js/wasm build variants, or testdata/src fixtures — correct by design).

Cluster 1 — Safe-output allow/deny configs ⭐ best win — Near

6 occurrences • Impact: Medium (low-effort, mechanical)

Six configs each embed the same base trio and then repeat an Allowed []string / Blocked []string pair:

• pkg/workflow/add_labels.go:10 AddLabelsConfig (Allowed+Blocked)
• pkg/workflow/remove_labels.go:10 RemoveLabelsConfig (identical to AddLabels)
• pkg/workflow/assign_to_user.go:10 AssignToUserConfig (+UnassignFirst *string)
• pkg/workflow/unassign_from_user.go:10 UnassignFromUserConfig
• pkg/workflow/set_issue_type.go:10 SetIssueTypeConfig (Allowed only)
• pkg/workflow/assign_milestone.go:10 AssignMilestoneConfig (+AutoCreate bool)

Fix: extract SafeOutputAllowBlockConfig { Allowed, Blocked []string } and embed it inline (matching the existing base-embedding pattern); per-type extras stay local. ~1–2 h.

Cluster 2 — Transport vs Remote (MCP registry) — Exact

pkg/cli/mcp_registry_types.go:62 & :99 have identical field sets (only an omitempty tag differs). These mirror the upstream MCP Registry OpenAPI spec → flag only, collapse to type Remote = Transport only if the spec unifies them.

Cluster 3 — Update-entity configs — Near (low)

pkg/workflow/update_issue.go:13 UpdateIssuesConfig and update_pull_request.go:13 UpdatePullRequestsConfig already share UpdateEntityConfig; only the Title *bool/Body *bool/Footer *string trio repeats. Optional extract; field divergence is real → small payoff.

Cluster 4 — Position/location triples — Semantic (weak)

pkg/workflow/workflow_errors.go:38 WorkflowValidationError redeclares inline File/Line/Column (lines 47–49) despite already referencing FieldLocation (= console.ErrorPosition). Could embed FieldLocation; parser/import_error.go:15 ImportError likewise. Optional cleanup.

---

Untyped Usages

Stats: interface{} in source = 1 (doc comment) • any ≈350+ (vast majority idiomatic) • untyped-constant→named-type opportunities ≈5. The interface{}/any axis is clean; the real surface is enum-like constants.

Category 1 — any/interface{} — mostly acceptable ✅ (don't "fix")

Correctly generic, leave as-is: pkg/typeutil/convert.go (heterogeneous JSON/YAML converter), pkg/parser/tools_merger.go MergeTools(map[string]any), pkg/workflow/compiler_types.go WorkflowData.{Tools,Features,RawFrontmatter,...} map[string]any (open-schema YAML), pkg/cli/gateway_logs_types.go:148,159 JSON-RPC ID any (spec: string|number|null). Only note: pkg/cli/mcp_tools_privileged.go:259-260 RunID any deliberately accepts string-or-number — defensible. No high-impact any→concrete conversions exist.

Category 2 — Untyped constants → named enums ⭐ the real wins

Pattern already in repo (type ActionMode string), so these are low-risk:

2.1 — SafeOutputs URL policy (HIGH) pkg/workflow/safe_outputs_validation.go:12-15, field compiler_types.go:728

type SafeOutputsURLsPolicy string
const (
    SafeOutputsURLsPolicyAllowedOnly         SafeOutputsURLsPolicy = "allowed-only"
    SafeOutputsURLsPolicyAllowedOrCodeRegion SafeOutputsURLsPolicy = "allowed-or-code-region"
)
URLs SafeOutputsURLsPolicy `yaml:"urls,omitempty"` // was: string

Closed two-value enum with a dedicated validateSafeOutputsURLs switch — ideal candidate.

2.2 — Guard-policy JSON-RPC error codes (HIGH) pkg/cli/gateway_logs_types.go:61-68
Untyped const guardPolicyErrorCode... = -32001 ... -32006, consumed by isGuardPolicyErrorCode(int) and stored as GuardPolicyEvent.ErrorCode int. → type GuardPolicyErrorCode int with named consts. A closed protocol-code set; prevents mixing with arbitrary ints.

2.3 — Guard-policy reason strings (MEDIUM) gateway_logs_types.go:191-209 — guardPolicyReasonFromCode returns bare strings ("access_denied", ...) → type GuardPolicyReason string. Mostly display-facing.

2.4 — Domain cross-run status (MEDIUM) pkg/cli/audit_cross_run.go:106,113 — OverallStatus/Status string // "allowed","denied","mixed","absent" is a comment-documented enum → type DomainStatus string enables exhaustive handling.

2.5 — MCP transport type (LOW/MED) pkg/cli/mcp_registry_types.go:63,100 + transportType flag (mcp_add.go:22) — small known set ("stdio"/"http"/"sse"); type MCPTransportType string, keep open-string fallback for third-party registry JSON.

Already strong ✅

Timeout/retry magic numbers are typed (time.Duration via * time.Second, or named ints like maxRetries) in pkg/constants/constants.go:270-304, mcp_inspect_mcp.go:27-29, run_workflow_tracking.go:31-33. Metrics structs fully concretely typed.

---

🎯 Recommendations (impact-to-effort order)

Priority 1 — name two constant groups (HIGH). Convert 2.1 + 2.2. Add type X string/int, type the const block + consuming field + helpers, go build ./... finds every call site, run tests. ~1–2 h each.

Priority 2 — consolidate Cluster 1 (MED). Extract & embed SafeOutputAllowBlockConfig across the six configs. ~1–2 h mechanical.

Priority 3 — optional polish. Findings 2.3/2.4/2.5 (more enums) and Clusters 3/4 (embedding cleanups) — do opportunistically.

Checklist

• SafeOutputsURLsPolicy named type (2.1)
• GuardPolicyErrorCode named type (2.2)
• Extract & embed SafeOutputAllowBlockConfig (Cluster 1)
• Optional: GuardPolicyReason, DomainStatus, MCPTransportType; embed FieldLocation (Cluster 4)
• go build ./... + full test suite after each change

Metadata: 974 files • 709 types (612 structs) • 4 genuine clusters (9 collisions ruled out) • ~5 untyped opportunities • Method: Serena semantic analysis + ripgrep, every finding verified against source.

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

• expires on Jun 30, 2026, 4:59 AM UTC-08:00