[typist] 🔤 Typist - Go Type Consistency Analysis

[github-actions[bot]]

Analysis of repository: github/gh-aw

Executive Summary

Good news first: this codebase is in excellent type-safety shape. I swept every non-test .go file under pkg/ (1,137 files, 637 production struct definitions) hunting for duplicated types and weakly-typed interface{}/any usages — and came away with almost nothing to complain about. There are zero genuine duplicate type definitions to consolidate, and production code has effectively migrated off interface{} entirely (the only literal interface{} matches are linter test fixtures and doc-comment text). Naming discipline is unusually strong: the ~30 distinct *Config structs, the many *Summary/*Diff/*Report types, etc. are genuinely different concepts, not collisions.

The one area worth a little polish is untyped string/numeric constants that form implicit enums. A handful of "enum-shaped" const groups (LLM providers, guard-policy error codes, URL policies, MCP status/argument kinds) still flow through the code as bare string/int instead of a named semantic type — even though the codebase already does this the right way elsewhere (EngineName, FeatureFlag, PermissionScope, ActionMode, ...). Adopting a named type for those groups would make switch sites exhaustive/greppable and prevent accidentally passing an arbitrary string where a provider or policy value is expected. None of this is urgent — these are refinements, not bug fixes.

Full Analysis Report

Duplicated Type Definitions

Summary Statistics

• Total struct definitions analyzed: 637 (production; _test.go and testdata/ excluded)
• Duplicate clusters found (genuine): 0
• Exact duplicates: 0
• Near duplicates: 0
• Semantic duplicates: 0
• Intentional same-name patterns (correctly not duplicates): 3 WASM build-variant pairs + 9 alias re-exports + 1 test fixture name

Every apparent same-name collision falls into one of three intentional, correct Go patterns. None should be changed.

1. WASM build-tag variants (leave as-is) — mutually-exclusive //go:build constraints; the compiler only ever sees one:

• ProgressBar — pkg/console/progress.go:31 / pkg/console/progress_wasm.go:7
• SpinnerWrapper — pkg/console/spinner.go:92 / pkg/console/spinner_wasm.go:10
• RepositoryFeatures — pkg/workflow/repository_features_validation.go:72 / pkg/workflow/repository_features_validation_wasm.go:5

2. Type-alias re-exports (already single-source-of-truth) — the second occurrence is type X = otherpkg.X, the idiomatic cross-package re-export:

• InputDefinition — real pkg/types/input_definition.go:15; alias pkg/workflow/inputs.go:18
• SanitizeOptions — real pkg/stringutil/sanitize.go:65; alias pkg/workflow/strings.go:95
• ToolCallInfo / LogMetrics — real pkg/workflow/metrics.go:16,26; alias pkg/cli/logs_models.go:94,90
• ActionYAMLInput / ActionPin / ActionPinsData / ContainerPin / SHAResolver — real pkg/actionpins/actionpins.go; alias pkg/workflow/action_pins.go

3. Test-fixture collision (out of scope) — Worker ×3, all under pkg/linters/*/testdata/src/..., unrelated concepts.

Verdict: no consolidation action recommended. The codebase is already well-factored on type names.

---

Untyped Usages (interface{} / any)

Summary Statistics

• Literal interface{} in production: 0 (17 total matches — 15 are linter testdata fixtures, 2 are []interface{} inside doc comments)
• any usages: 3,867 total, of which ~99% are idiomatic
  • map[string]any: ~2,300 (parse-boundary frontmatter/config)
  • []any: ~433 (YAML/JSON arrays)
  • func params/returns of bare any: ~262 lines (mostly map[string]any extractors + generic converters)
  • struct fields of bare any: 36 (documented polymorphic YAML/JSON unions)
  • generic [T any] type params: ~15 (idiomatic generics)
  • variadic ...any: a handful (logging/format)

Nearly all any sits at genuine YAML/JSON parse boundaries for polymorphic GitHub Actions config (RunsOn, On, Endpoint, Headers, Jobs, Permissions, raw frontmatter maps, step slices, JSON-RPC ID). These are correctly any — the accepted forms are documented in comments and there is no single concrete type. Do not flag these.

Genuine (modest) strong-typing opportunities

1. pkg/workflow/safe_outputs_config_types.go:105 — ReportFailureAsIssue any
Comment says "bool, templatable expression string, or []string categories," and the parsed results already live in adjacent typed fields (ReportFailureAsIssueCategories []string, ...ExcludedCategories []string). This raw any is transitional. A named type with a custom UnmarshalYAML that normalizes the three forms would encode the union contract in the type system and remove ad-hoc type switches at call sites.

2. pkg/cli/logs_models.go:323-324 — RunID any / RunNumber any
GitHub returns numbers, but aw_info.json inputs can be strings. If normalized at decode, these could become RunID int64 / RunNumber int, removing downstream type assertions. (Lower confidence — depends on whether both encodings really occur.)

3. pkg/console/console_types.go:50 — FormField.Value any
A generic form widget (flag.Value-style). If the four field kinds (input/password/confirm/select) all capture strings, Value *string removes an untyped pointer. (Verify no bool/int consumers first.)

---

Untyped Constants (the main opportunity)

Summary Statistics

• Untyped single-line string consts: ~90 (majority are paths/env-var-names/image-refs in pkg/constants/ — correctly plain strings, not enums)
• Untyped string consts in const (...) blocks: ~110 more (again mostly env-var namespaces — fine)
• Untyped numeric consts: ports, JSON-RPC error codes, scoring weights, limits
• High-value enum-shaped groups still untyped: 8

The codebase already models many enums correctly (EngineName, FeatureFlag, PermissionScope, PermissionLevel, ActionMode, GitHubMCPMode, GitHubIntegrityLevel). The groups below were missed and still flow as bare string/int.

String-enum candidates

★ 1. LLM provider (HIGH value) — pkg/workflow/llm_provider.go:13-17

const (
    LLMProviderGitHub    = "github"
    LLMProviderAnthropic = "anthropic"
    LLMProviderOpenAI    = "openai"
)

Flows through many signatures as bare provider string (normalizeLLMProvider, llmProviderProfileFor, llmProviderSecretNames, llmProviderGatewayBaseURL, normalizeEngineProvider, normalizeProviderForPricing, ...). type LLMProvider string mirrors the existing EngineName pattern and makes the switch sites exhaustive/greppable.

2. Objective labels + multi-label logic (HIGH value) — pkg/github/label_objective_mapping_constants.go:20-140
~30 label-name consts (one conceptual set) plus a clean 3-value logic enum (MultiLabelLogicMax/Sum/First) that selects branching behavior. Suggest type ObjectiveLabel string and type MultiLabelLogic string.

3. Safe-outputs URL policy — pkg/workflow/safe_outputs_validation.go:13-16
Two-value policy (allowed-only, allowed-or-code-region) compared in a switch against a bare-string config.URLs. type SafeOutputsURLsPolicy string ties the config field and validator together.

4. MCP registry status & argument type — pkg/cli/mcp_registry_types.go:107-116
StatusActive/Inactive and ArgumentTypePositional/Named; the struct fields are Status string / Type string. Suggest type ServerStatus string and type ArgumentType string.

5. Experiments storage backend — pkg/workflow/compiler_experiments.go:24-29
Two-value enum (cache, repo) selecting persistence. type ExperimentsStorage string clarifies intent.

Numeric-enum candidates

★ 6. Guard-policy JSON-RPC error codes (HIGH value) — pkg/cli/gateway_logs_types.go:61-68

const (
    guardPolicyErrorCodeAccessDenied      = -32001
    // ...through...
    guardPolicyErrorCodeIntegrityBelowMin = -32006
)

A closed set of magic ints compared against GuardPolicyEvent.ErrorCode int (line 77). type GuardPolicyErrorCode int on both the consts and the struct field documents the -32001...-32006 range and prevents comparing against an unrelated int.

7. Network / LLM-gateway ports — pkg/constants/constants.go:100-140
DefaultMCPGatewayPort, ClaudeLLMGatewayPort, ... all untyped int, and there's already a validation range (MinNetworkPort/MaxNetworkPort). type NetworkPort int is a natural fit (values are passed into gatewayPort int and formatted into URLs).

8. Objective scoring weights — pkg/github/label_objective_mapping_constants.go
~25 untyped ObjectiveValue* ints ("objective scores" combined by MultiLabelLogic). type ObjectiveScore int pairs naturally with ObjectiveLabel (#2).

Notable inconsistency worth flagging

In pkg/constants/constants.go the AI-credits guardrails mix representations for one concept:

• DefaultMaxAICredits int64 = 1000, DefaultDetectionMaxAICredits int64 = 400 (typed int64)
• DefaultMaxDailyAICredits = "5000" (line 333) — a string
• DefaultMaxRuns = 500, DefaultMaxTurnCacheMisses = 5, DefaultMaxToolDenials = 5 (untyped int)

A shared type AICredits int64 (and normalizing the string one) removes the ambiguity and the string/number split.

Correctly untyped (skipped)

pkg/constants/ paths/dirs/mounts/env-var names/image refs, pkg/cli/docker_images.go image refs, artifact/file-name and step-output-key labels — namespaced string labels by design, not enumerations.

---

🎯 What Should We Do About This?

Because there are no duplicates and no real weak-typing debt, the action plan is short and low-risk. Start with the two highest-leverage typed enums.

Priority 1: High-value typed enums (safety + clarity)

• Introduce type LLMProvider string (rejig docs #1) and type GuardPolicyErrorCode int (add cli flag to guard dropping a agentic workflow instructinos file #6) — these flow through the most signatures / struct fields.
• Steps: define the named type, retype the existing consts, update the relevant signatures and struct fields, run go build ./... && go test ./....
• Estimated effort: 1–2 hours each. Impact: exhaustive/greppable switches; prevents string/int mixups.

Priority 2: Remaining enum-shaped groups

• MultiLabelLogic, SafeOutputsURLsPolicy, MCP ServerStatus/ArgumentType, ExperimentsStorage, NetworkPort, ObjectiveLabel/ObjectiveScore.
• Estimated effort: ~30 min each. Impact: medium — clearer intent, cheap validation hooks.

Priority 3: Consistency cleanup

• Normalize the AI-credits constants to one representation (type AICredits int64).
• Optionally revisit the 3 modest any refinements (ReportFailureAsIssue, RunID/RunNumber, FormField.Value).
• Estimated effort: 1–2 hours total. Impact: low/medium.

Implementation Checklist

• type LLMProvider string + retype consts/signatures (Priority 1)
• type GuardPolicyErrorCode int + retype GuardPolicyEvent.ErrorCode (Priority 1)
• Remaining enum groups (Priority 2)
• Normalize AI-credits constants (Priority 3)
• go build ./... && go test ./... after each change
• No duplicate-type or interface{} work needed — none found

Analysis Metadata

• Total Go files scanned: 1,137 (pkg/, non-_test.go)
• Total struct definitions: 637 (production)
• Genuine duplicate clusters: 0
• Literal interface{} in production: 0
• any usages: 3,867 (~99% idiomatic parse-boundary)
• Untyped enum-shaped const groups flagged: 8 (+1 consistency issue, +3 modest any refinements)
• Detection method: Serena semantic analysis + pattern matching, with per-finding manual verification
• Analysis date: 2026-07-23

Generated by ✍️ Typist - Go Type Analysis · age00 453.1 AIC · ⌖ 36 AIC · ⊞ 8.6K · ◷

• expires on Jul 24, 2026, 4:08 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 #47781.