[typist] Typist: Go type consistency analysis (duplicated types and untyped usages)

[github-actions[bot]]

🔤 Typist - Go Type Consistency Analysis

Analysis of repository: github/gh-aw

Executive Summary

I scanned all 1,258 non-test .go files under pkg/ (roughly 1,179 top-level type declarations) for two things: types that are defined more than once in slightly different shapes, and places where any/interface{} or bare untyped constants are standing in for a knowable concrete type. The good news is the codebase mostly avoids exact-name, exact-shape duplication — the few true twins are intentional (go/redacted):build wasm platform stubs. The real cost is in near-duplicates: the same field or field-group copy-pasted across many structs instead of being factored into a shared embed, and a family of six-plus independent "Finding" types (one per security-scanner integration) that each reinvent severity/location fields from scratch.

The single highest-leverage fix is mechanical: Footer *string, TargetRepoSlug/AllowedRepos, and CloseOlderKey are already copy-pasted verbatim across 10-12 safe-output config structs in pkg/workflow, even though a BaseSafeOutputConfig embed already exists and solves exactly this problem for other fields (Max, GitHubToken, Staged, ...) — it just wasn't extended to cover these three. On the untyped side, the codebase has fully migrated from interface{} to any (only 18 stray interface{} hits, mostly in linter testdata), but any itself is used ~14,000 times, with the highest-value targets being YAML-decoded config values (tools[toolName] any, needs: any) that are type-switched back into a small, already-known set of shapes at every call site — a pattern the codebase already solves correctly elsewhere (e.g. ActionMode string in pkg/workflow/action_mode.go), just not consistently.

Full Analysis Report

Duplicated Type Definitions

Summary Statistics

• Total types analyzed: ~1,179 (across 1,258 files)
• Duplicate clusters found: 12
• Exact duplicates: 2 clusters (both intentional wasm/native build-tag twins, plus 6 already-correct type aliases)
• Near duplicates: 6 clusters
• Semantic duplicates: 4 clusters

---

Cluster 1: Security-scanner Finding/Issue records (semantic, high impact)

Occurrences: 9 independently-declared structs

Locations:

1. pkg/cli/zizmor.go:24 — zizmorFinding{Ident, Desc, URL, Determinations.Severity, Locations[]}
2. pkg/cli/poutine.go:24 — poutineFinding{RuleID, Purl, Meta.Path, Meta.Line, Meta.Details}
3. pkg/cli/grype.go:53 — grypeFinding{Vulnerability.Severity, Artifact.Name/Version}
4. pkg/cli/runner_guard.go:22 — runnerGuardFinding{RuleID, Name, Severity, Description, Remediation, File, JobID, Line}
5. pkg/cli/yamllint.go:27 — yamllintIssue{File, Line, Column, Level, Message, Rule}
6. pkg/cli/grant.go:50 — grantPackageFinding{Name, Version, Decision, Licenses}
7. pkg/cli/audit_report.go:66 — Finding{Category, Severity, Title, Description, Impact}
8. pkg/workflow/markdown_security_scanner.go:57 — SecurityFinding{Category, Description, Line, Snippet}
9. pkg/cli/validation_issue.go:4 — ValidationIssue{Type, Message, Line, File}

Definition Comparison (shape, not literal code — each tool names its fields differently for the same concepts):

type <Tool>Finding struct {
    <RuleID/Ident/Name> string
    Severity            string // or Level string — bare string per tool, no shared enum
    <Message/Description/Desc> string
    File, Line, Column  ... // location shape differs per tool
}

Recommendation:

• Introduce a shared Finding{RuleID string, Severity SeverityLevel, Message string, File string, Line, Column int} type (e.g. in pkg/console or a new pkg/scanfindings), with a SeverityLevel enum shared across all 9 call sites.
• Give each tool integration a small adapter that maps its native JSON shape onto the shared Finding, rather than declaring a bespoke struct.
• Estimated effort: 4-6 hours (9 call sites, mostly mechanical mapping)
• Benefits: one severity vocabulary instead of nine, easier to add a new scanner integration, consistent rendering/sorting across tools

---

Cluster 2: Footer field copy-pasted across safe-output configs (near, high impact)

Occurrences: 11

Locations: pkg/workflow/create_issue.go:28, create_discussion.go:28, create_pull_request.go, update_issue.go:18, update_pull_request.go:21, update_discussion.go, update_release.go, submit_pr_review.go, reply_to_pr_review_comment.go, comment_memory.go, add_comment.go

Definition Comparison:

// Identical in all 11 structs:
Footer *string `yaml:"footer,omitempty"` // Controls whether AI-generated footer is added...

Recommendation:

• pkg/workflow/safe_outputs_config_types.go:22 already defines BaseSafeOutputConfig{Max, GitHubToken, GitHubApp, Staged, IssueIntent, NormalizeClosingKeywords, Samples} and is embedded by these same structs — but Footer was never added to it.
• Move Footer *string into BaseSafeOutputConfig and delete the 11 duplicate declarations.
• Estimated effort: 1-2 hours
• Benefits: single source of truth, no risk of one config type's footer behavior drifting from the others

---

Cluster 3: TargetRepoSlug / AllowedRepos cross-repo fields (near, high impact)

Occurrences: 12

Locations: create_issue.go:21-22, create_discussion.go:21-22, create_pull_request.go, create_pr_review_comment.go, create_code_scanning_alert.go, create_agent_session.go, update_project.go, comment_memory.go, add_comment.go, dispatch_workflow.go, push_to_pull_request_branch.go, safe_outputs_parser.go

Definition Comparison:

TargetRepoSlug string   `yaml:"target-repo,omitempty"`
AllowedRepos   []string `yaml:"allowed-repos,omitempty"`

Recommendation:

• Extract a CrossRepoConfig{TargetRepoSlug string, AllowedRepos []string} embeddable struct in pkg/workflow/safe_outputs_config_types.go, alongside the existing BaseSafeOutputConfig, and embed it in the 12 structs currently redeclaring both fields.
• Estimated effort: 2-3 hours (verify parsing code references the embedded fields correctly)
• Benefits: single source of truth for cross-repo targeting rules, one place to add validation

---

Cluster 4: CloseOlder* / CloseOlderKey dedup-key fields (near, medium impact)

Occurrences: 4 (create_issue.go, create_discussion.go, create_pull_request.go, safe_outputs_handler_registry.go)

Definition Comparison:

CloseOlder<Entity> *string `yaml:"close-older-<entity>,omitempty"`
CloseOlderKey       string  `yaml:"close-older-key,omitempty"`

Recommendation: Unify with a CloseOlderConfig{Enabled *string, Key string} embeddable type, mirroring the CloseEntityConfig alias pattern already used correctly in close_entity_helpers.go (see Cluster 9 below).
Estimated effort: 1-2 hours

---

Cluster 5: GitHubMCPDockerOptions vs GitHubMCPRemoteOptions (near, medium impact)

Location: pkg/workflow/mcp_renderer_types.go:67 and :101

8 fields (ReadOnly, Lockdown, LockdownFromStep, GuardPoliciesFromStep, Toolsets, Features, AllowedTools []string, GuardPolicies map[string]any) are identical between the two structs; only the transport-specific fields differ (CustomArgs/DockerImageVersion vs AuthorizationValue).

Recommendation: Factor the 8 shared fields into a GitHubMCPCommonOptions struct embedded by both. Estimated effort: 1 hour.

---

Cluster 6: workflow_errors.go error type family (near, medium impact)

WorkflowValidationError, OperationError, and ConfigurationError (all in pkg/workflow/workflow_errors.go:38/98/154) share Reason, Suggestion, Timestamp plus varying identity fields (Field+location+Severity/Category vs Operation/EntityType/EntityID vs ConfigKey).

Recommendation: Share a baseError{Reason, Suggestion string; Timestamp time.Time} embed with a custom Error() per type, rather than repeating the three common fields three times. Estimated effort: 1-2 hours.

---

Cluster 7: LockMetadata vs AgentMetadataInfo (near, medium impact)

pkg/workflow/lock_schema.go:35 (LockMetadata) and :52 (AgentMetadataInfo) — AgentMetadataInfo's 7 fields (AgentID, AgentModel, DetectionAgentID, DetectionAgentModel, EngineBaseURLCustomized, EngineVersions, AgentImageRunner) are a verbatim subset of LockMetadata's fields, in the same file.

Recommendation: Embed AgentMetadataInfo inside LockMetadata instead of maintaining both independently. Estimated effort: < 1 hour.

---

Cluster 8: Ad-hoc status/severity/level enums, no shared vocabulary (semantic, medium impact)

ErrorSeverity int (pkg/workflow/error_recovery.go:23), AttributionStatus string (pkg/intent/resolver.go:7), CheckState string (pkg/cli/checks_command.go:23), OutcomeStatus string (pkg/cli/outcome_evaluation.go:12), PermissionLevel string (pkg/workflow/permissions.go:46), GitHubIntegrityLevel string (pkg/workflow/tools_types.go:287), plus the bare Severity/Level string fields in Cluster 1.

Recommendation: Not urgent to merge across domains, but a shared convention (or a common pkg/enums pattern) would stop every package from hand-rolling its own status/severity vocabulary. Lower priority than Clusters 1-4.

---

Cluster 9: "Metadata" name reused for 5 unrelated concepts (semantic, low impact)

Metadata (pagination, pkg/cli/mcp_registry_types.go:14), WorkflowMCPMetadata, ActionMetadata, LockMetadata, commandsHeaderMetadata — structurally unrelated, no merge needed, but the bare Metadata name in pkg/cli/mcp_registry_types.go makes grep/navigation harder. Consider renaming to RegistryPageMetadata.

---

Cluster 10: Six independent *Status structs (semantic, low impact)

WorkflowStatus, WorkflowFileStatus, LockFileStatus, DomainRunStatus, PRCommitStatus, GuardrailStatus — each represents a genuinely different concept (git state vs. lock file vs. CI check). No merge recommended; flagged only so a 7th isn't added without checking for overlap first.

---

Cluster 11: Per-tool *ToolConfig types under tools_types.go (near, low impact)

9 types (GitHubToolConfig, BoundedQueriesConfig, PlaywrightToolConfig, BashToolConfig, WebFetchToolConfig, WebSearchToolConfig, EditToolConfig, AgenticWorkflowsToolConfig, CacheMemoryToolConfig) — mostly legitimate per-tool variance, but worth a pass to confirm each needs a distinct type vs. a shared ToolConfig{Enabled bool, Args map[string]any} with tool-specific extension fields.

---

Cluster 12: Already-correct patterns (no action needed)

• Type aliases: CloseIssuesConfig = CloseEntityConfig, ClosePullRequestsConfig = CloseEntityConfig, CloseDiscussionsConfig = CloseEntityConfig (close_entity_helpers.go:263-265), MissingDataConfig/MissingToolConfig/ReportIncompleteConfig = IssueReportingConfig (missing_issue_reporting.go:26-42) — this is the pattern Clusters 2-4 should move toward.
• Build-tag twins: SpinnerWrapper (console/spinner.go vs spinner_wasm.go), ProgressBar (console/progress.go vs progress_wasm.go), RepositoryFeatures (repository_features_validation.go vs _wasm.go) — intentional (go/redacted):build js || wasm stubs, correctly duplicated for platform parity.

---

Untyped Usages

Summary Statistics

• any usages (repo-wide, pkg/): ~14,149 (rough grep count including legitimate generic/JSON/reflection use — see notes below)
• Stray interface{} usages: 18 (mostly in linter testdata — the codebase has already migrated to any)
• Untyped semantic constants flagged: ~620 candidates, narrowed to the highest-impact examples below

Note: the vast majority of any usage is legitimate (JSON unmarshal targets, generic containers, reflection). The categories below are the subset judged to be a "lazy" substitute for an already-knowable concrete type.

---

Category 1: any in function parameters for YAML-decoded config values (high impact)

Example 1: Frontmatter scalar coercion, repeated per call site

• Location: pkg/workflow/engine_config_parser.go:29 (parseMaxRunsValue), plus parseMaxAICreditsValue, parseMaxTurnsValue, parseHarnessMaxRetriesValue, parseMaxToolDenialsValue
• Current: func parseMaxRunsValue(raw any) int — each function re-implements the same int/int64/uint64/float64/string type-switch
• Actual usage: raw always comes from a decoded YAML frontmatter map[string]any
• Suggested fix: route through the existing pkg/typeutil.ParseIntValue(raw) helper instead of re-implementing the switch per call site
• Benefit: one coercion path instead of 5+ near-identical ones

Example 2: Per-tool config parsers, 10+ near-identical signatures

• Location: pkg/workflow/tools_parser.go:190-689 — parseGitHubTool(val any), parseBashTool(val any), and 8+ siblings
• Actual usage: val is always tools[toolName] from a decoded map[string]any; each function asserts to map[string]any or bool internally (the implicit contract is bool | map[string]any)
• Suggested fix: a small ToolValue wrapper with .AsMap()/.AsBool() accessors shared by all parseXTool functions
• Benefit: makes the bool-or-map contract explicit and centralizes the failure path

Example 3: GitHub Actions needs: field

• Location: pkg/cli/runner_guard_activation_gate.go:19 — Needs any, consumed by jobNeeds(needs any) []string (line 221), type-switching string / []any / []string
• Suggested fix: type JobNeeds any (documented union) with a custom UnmarshalYAML that normalizes to []string once
• Benefit: this exact 3-branch switch likely recurs anywhere needs: is parsed — centralizing avoids drift

---

Category 2: any / map[string]any struct fields with a known, finite shape (high impact)

Example 1: InputDefinition.Default

• Location: pkg/types/input_definition.go:18 — Default any with a comment "Can be string, number, or boolean"
• Actual usage: GetDefaultAsString() (same file, line 24) type-switches string/bool/int/int64/float64 with a silent %v fallback (lines 48-49) that can produce surprising output for unexpected types
• Suggested fix: a small tagged union (DefaultValue{Str, Num, Bool, Kind}) — the comment already documents the exact 3 legal types
• Benefit: removes the silent fallback path, compile-time exhaustiveness

Example 2: GuardPolicies map[string]any

• Location: pkg/workflow/tools_types.go:530 — comment already enumerates known variants ("For GitHub: policies are represented via GitHubAllowOnlyPolicy...")
• Suggested fix: map[string]json.RawMessage or a typed union keyed by server kind
• Benefit: the code already knows the finite set of policy shapes per server; the field just doesn't reflect it

Example 3: Duplicated trial-result blobs

• Location: pkg/cli/trial_types.go:9-12 and pkg/cli/trial_support.go:20-23 — SafeOutputs map[string]any, AgenticRunInfo map[string]any, AdditionalArtifacts map[string]any, declared near-identically in two files
• Actual usage: SafeOutputs's shape actually mirrors the already-typed workflow.SafeOutputsConfig
• Suggested fix: reuse workflow.SafeOutputsConfig instead of re-decoding into map[string]any in two parallel structs
• Benefit: removes a duplicate type definition and restores type safety

---

Category 3: any as return type where the concrete type is already known (medium impact)

• Location: pkg/parser/schema_suggestions.go:386/395/405/417 — generateStringExample(...) any, generateNumberExample(...) any, generateArrayExample(...) any, generateObjectExample(...) any always return string, float64, []any, map[string]any respectively (only the top-level dispatcher generateExampleFromSchema at line 273 genuinely needs any, since JSON-schema type is dynamic).
• Suggested fix: give each helper its real concrete return type; callers currently re-assert a type that was already statically known from the function name.

---

Category 4: Untyped string-enum constants (medium impact)

Example 1: Run-phase constants

• Location: pkg/workflow/run_phase.go:7-11 — runPhaseAgent = "agent", runPhaseDetection = "detection", runPhaseEvals = "evals", compared with == across 6 engine files (claude_engine.go, codex_engine.go, gemini_engine.go, pi_engine.go, copilot_engine_execution.go) and written into env["GH_AW_PHASE"]
• Suggested fix: type RunPhase string with typed constants — mirrors the ActionMode string pattern already used correctly one file over, in pkg/workflow/action_mode.go:16-24
• Benefit: the fix pattern already exists in the same package; applying it here prevents a stray literal from silently breaking phase comparisons in 5+ files

Example 2: Default-model constants mixed into an unrelated const block

• Location: pkg/constants/engine_constants.go:300-316 — CopilotBYOKDefaultModel, CodexDefaultModel, AgentDefaultModel, SonnetDefaultModel sit in the same untyped const block as ~30 *EnvVar name constants
• Suggested fix: type ModelName string for the *DefaultModel group so it isn't accidentally type-compatible with unrelated env-var-name strings in the same block

Category 5: Untyped numeric constants (medium impact)

• Location: pkg/constants/constants.go:105-135 — DefaultMCPGatewayPort = 8080, DefaultMCPServerPort = 3000, MinNetworkPort = 1, MaxNetworkPort = 65535, ClaudeLLMGatewayPort, CodexLLMGatewayPort, all plain untyped int
• Suggested fix: type Port int with a (p Port) Valid() bool method using the existing Min/Max constants
• Benefit: prevents a port constant from being accidentally compared/assigned against an unrelated int (byte size, retry count) elsewhere in the package

---

Refactoring Recommendations

Priority 1: Critical — Extend BaseSafeOutputConfig (Clusters 2-4)

Steps:

1. Add Footer *string to BaseSafeOutputConfig in pkg/workflow/safe_outputs_config_types.go; delete the 11 duplicate declarations.
2. Add a new embeddable CrossRepoConfig{TargetRepoSlug, AllowedRepos} and embed it in the 12 structs that redeclare both fields.
3. Add a CloseOlderConfig{Enabled *string, Key string} for the 4 close-older duplicates.
4. Run go build ./... and the existing test suite to confirm no YAML-tag or JSON-shape regressions.

Estimated effort: 4-6 hours combined
Impact: High — removes ~27 duplicate field declarations across pkg/workflow, single source of truth for the safe-output config surface

---

Priority 2: High — Consolidate the security-scanner Finding family (Cluster 1)

Steps:

1. Define a shared Finding{RuleID, Severity SeverityLevel, Message, File string, Line, Column int} and a SeverityLevel enum.
2. Add a mapping function per integration (zizmor, poutine, grype, runner-guard, yamllint, grant) from its native JSON shape to the shared type.
3. Update rendering/sorting code to consume the shared type.

Estimated effort: 4-6 hours
Impact: High — one severity vocabulary instead of nine, easier to onboard a new scanner integration

---

Priority 3: Medium — Replace YAML-decoded any parameters with documented union types (Category 1-2)

Steps:

1. Route the frontmatter scalar parsers (engine_config_parser.go) through the existing pkg/typeutil.ParseIntValue helper instead of re-implementing the switch.
2. Introduce a ToolValue wrapper (.AsMap()/.AsBool()) for the 10+ parseXTool(val any) functions in tools_parser.go.
3. Apply the ActionMode-style typed-string pattern to run_phase.go's phase constants and runner_guard_activation_gate.go's Needs/JobNeeds.

Estimated effort: 6-8 hours
Impact: Medium-High — centralizes several independently-drifting coercion paths

---

Priority 4: Low — Typed constants for ports/models, cleanup of small near-duplicates (Clusters 5-7, Category 4-5)

Steps: Add Port, ModelName, RunPhase named types; merge GitHubMCPDockerOptions/RemoteOptions shared fields; embed AgentMetadataInfo inside LockMetadata; share a baseError embed across the workflow_errors.go family.

Estimated effort: 4-5 hours
Impact: Low-Medium — clarity and safety, not urgent

---

Implementation Checklist

• Extend BaseSafeOutputConfig with Footer, CrossRepoConfig, CloseOlderConfig (Priority 1)
• Consolidate the 9 scanner Finding types into a shared Finding + SeverityLevel (Priority 2)
• Route frontmatter/tool-value coercion through shared helpers instead of per-call-site type-switches (Priority 3)
• Apply ActionMode-style typed strings to run_phase.go and needs: parsing (Priority 3)
• Add Port/ModelName typed constants, merge small structural near-duplicates (Priority 4)
• Run go build ./... and full test suite after each consolidation step
• Re-run this analysis after Priority 1-2 land to confirm the clusters are resolved

Analysis Metadata

• Total Go Files Analyzed: 1,258 (pkg/, excluding _test.go)
• Total Type Definitions Scanned: ~1,179
• Duplicate Clusters: 12 (2 no-action-needed, 6 near, 4 semantic)
• Untyped Usage Categories: 5
• Detection Method: ripgrep-based structural sweep (via Grep tool) + targeted Serena/manual verification of top clusters
• Analysis Date: 2026-08-20

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

• expires on Aug 21, 2026, 3:41 AM UTC-08:00