[typist] 🔤 Typist — Go Type Consistency Analysis

[github-actions[bot]]

Analysis of repository: github/gh-aw · scope: non-test .go files under pkg/

Executive Summary

I scanned all 1,542 non-test Go files under pkg/ for duplicated type definitions and untyped (interface{}/any) usage. The good news first: interface{} is basically extinct here — only 2 real occurrences remain, the rest of the codebase has already migrated to any. The bigger story is that any itself is everywhere (map[string]any alone shows up 3,262 times across 516 files), almost entirely at the YAML/JSON frontmatter-parsing boundary. That's largely an intentional architectural pattern rather than scattered carelessness, but a few spots — especially pkg/workflow/tools_parser.go and the MCP audit-tool input types — would benefit from real structs with UnmarshalYAML/UnmarshalJSON instead of manual type assertions.

On the duplication side, I found 7 clusters worth a look. Two are genuinely interesting: a three-way ValidationError/WorkflowValidationError/Payload split across parser, workflow, and validationerror that already shares a base type but still models "a validation error" three separate ways, and a pair of graderManifestEntry structs in cli and workflow with only ~36% field overlap that look like a reader/writer schema split worth documenting (or unifying) explicitly. A couple of others (bare Config, LogParser) are same-name-coincidence rather than real duplication — flagged but low priority. I also found a handful of untyped constants (DefaultMaxRuns, DefaultRateLimitMax/Window, and one string-typed numeric constant DefaultMaxDailyAICredits = "5000") sitting right next to already-typed siblings in the same file, which is the cheapest fix in this whole report.

Full Analysis Report

Duplicated Type Definitions

Summary Statistics

• Total files analyzed: 1,542 (exhaustive file count; deep field-level inspection performed on a targeted subset of ~20 files likely to hold domain types — config/options/result/info/validation/MCP)
• Total type declarations (approx., grep-based): 1,667
• Duplicate clusters found: 7
• Exact duplicates: 5
• Near duplicates: 1
• Semantic duplicates: 1

Cluster 1: ValidationError family — semantic duplicate

Impact: Medium — three packages model the same concept independently

Locations:

1. pkg/validationerror/validationerror.go — Payload struct: Field string, Value string, Reason string, Suggestion string
2. pkg/parser/validation_error.go — ValidationError struct embedding validationerror.Payload
3. pkg/workflow/workflow_errors.go — WorkflowValidationError struct embedding validationerror.Payload plus Severity, Category, Timestamp, File, Line, Column

Recommendation: The shared Payload base is a good pattern already in place — the duplication is in having three different named wrapper types for essentially the same error concept. Consider whether workflow.WorkflowValidationError's extra fields (severity/category/location) could be folded into a single richer validationerror.ValidationError concrete type used everywhere, collapsing three types into one.
Estimated effort: 3-4 hours (touches error-handling call sites in parser and workflow)

---

Cluster 2: MCPServerConfig variants — near duplicate (already partially addressed)

Impact: Low — base type already factored out

Locations:

1. pkg/types/mcp.go — BaseMCPServerConfig (12 shared fields: Command, Args, Env, Type, Version, URL, Headers, Auth, Container, Entrypoint, EntrypointArgs, Mounts)
2. pkg/parser/mcp.go — RegistryMCPServerConfig embeds BaseMCPServerConfig + registry-specific fields
3. pkg/workflow/tools_types.go — MCPServerConfig embeds BaseMCPServerConfig + workflow-specific fields

Recommendation: No action needed — comments already explain this split exists "to eliminate duplication." Listed here for completeness since the near-duplicate name-matching rule caught it.

---

Cluster 3: runtimeImportReference — exact duplicate

Impact: Medium — identical concept, independently reimplemented

Locations:

1. pkg/parser/frontmatter_hash.go — {path string, startLine int, endLine int}
2. pkg/workflow/runtime_import_validation.go — {importPath string, startLine int, endLine int}

Recommendation: Both represent a parsed {{#runtime-import ...}} macro occurrence. Move to a shared pkg/types (or similar) package as a single RuntimeImportReference type.
Estimated effort: 1-2 hours

---

Cluster 4: graderManifestEntry — exact name, partial field overlap

Impact: Medium — reader/writer schema split, undocumented

Locations:

1. pkg/cli/audit_report_graders.go — 5 fields (ID, Name, Unit, Direction, Threshold)
2. pkg/workflow/compiler_yaml_graders.go — 14 fields (adds Description, Source, Enabled, Max, Min, Digest, Run, Inline, Config, ...)

Recommendation: cli's version looks like a read-side subset of workflow's write-side struct (~36% field overlap). Either document explicitly that this is an intentional reader/writer split, or share one type with optional fields.
Estimated effort: 2 hours (verify no JSON tag mismatches before unifying)

---

Cluster 5: LogParser — exact name, unrelated kinds

Impact: Low — naming collision, not structural duplication

Locations:

1. pkg/workflow/agentic_engine.go — LogParser interface
2. pkg/cli/log_aggregation.go — LogParser[T MutableLogAnalysis] generic function type

Recommendation: No structural fix needed, but the shared name across an interface and a generic func type in sibling packages is a readability trap for grep-based navigation. Consider renaming one (e.g. cli.LogParseFunc[T]).

---

Cluster 6: bare Config — coincidental exact-name match

Impact: Low — unrelated domains (log-drain tuning vs. linter config)

Locations:

1. pkg/agentdrain/types.go — Config (Depth, SimThreshold, MaxChildren, ...)
2. pkg/linters/internal/resourcetracker/resourcetracker.go — Config[K comparable] (static-analysis linter config)

Recommendation: No action — flagged only because of the exact-name clustering rule; zero field overlap, unrelated purposes.

---

Untyped Usages

Summary Statistics

• interface{} usages: 2 (effectively migrated away from; rest of 79 raw grep hits are test fixtures/analyzer testdata, excluded)
• any usages (Go-syntax): several thousand; map[string]any alone = 3,262 occurrences / 516 files
• Untyped constants: ~1,344 raw grep hits across 385 files (broad pattern); curated domain-meaningful subset below

Category 1: interface{}/any in function parameters

Impact: High in a few hot spots, acceptable elsewhere (generic utility packages)

• pkg/workflow/tools_parser.go:112 — func NewTools(toolsMap map[string]any) *Tools, the YAML→typed boundary for all tool configs, followed by 50+ guarded .(string)/.(bool)/.(int) assertions through the file (e.g. lines 183, 213, 236-416). Suggested fix: give each XToolConfig its own UnmarshalYAML, so parseXTool takes a typed value instead of any + manual assertions.
• pkg/workflow/compiler_pre_activation_job.go:690,721,749,819,857,881,897,921 — same map-of-any YAML boundary pattern (validatePreActivationJobConfig, extractOnSteps, ...); a FrontmatterOn struct (partially modeled already in frontmatter_types.go) could replace several of these.
• pkg/cli/mcp_tools_privileged.go:468 — normalizeAuditRunInput(input any, fieldName string) switches on nil/string/float64/int/int64. Suggested fix: a type RunIDValue with custom UnmarshalJSON accepting string-or-number, used as the field type directly (see struct-fields section) — moves validation from runtime to deserialization time.
• pkg/workflow/service_ports.go:185 — parsePortSpec(spec any) switches on int/string; genuine multi-shape GitHub Actions value, acceptable.
• pkg/typeutil/convert.go and pkg/typeutil/lookup.go — documented generic JSON/YAML coercion helpers (ParseIntValue, ConvertToInt, LookupMap, ...). Acceptable as-is — this is the intended generic-utility package.

Category 2: interface{}/any in return types

Impact: Mostly acceptable (genuinely heterogeneous JSON/schema values)

• pkg/parser/schema_suggestions.go — generateExampleFromSchema(schema map[string]any) any and siblings building JSON-schema example values; inherently heterogeneous, acceptable, though the externally-called top-level function could return a small ExampleValue sum type with a .JSON() method.
• pkg/importinpututil/import_input.go:17,42 — ResolvePathValue(...) (any, bool) feeding straight into FormatResolvedValue(value any). Candidate: a small discriminated ResolvedValue struct instead of any + a second formatter function.
• pkg/workqueue/codec.go — hand-rolled strict JSON decoder returning any; genuine generic JSON AST, same shape as encoding/json. Acceptable.
• pkg/cli/jsonworkflow_to_markdown.go:373,394 — produce GH Actions on: value (string|list|map by spec). Acceptable, mirrors the struct-field case below.

Category 3: interface{}/any in struct fields

Impact: High for one clear candidate, low/acceptable for the rest

• Best fixable candidate — pkg/cli/mcp_tools_privileged.go:454-455 — auditArgs.RunID any, RunIDOrURL any, paired directly with the normalizeAuditRunInput type-switch above. A StringOrNumber type with UnmarshalJSON would also make the generated MCP tool JSON schema clearer (currently falls back to an untyped schema per the comment at pkg/cli/mcp_schema.go:121).
• pkg/cli/audit_report.go:169 — CreatedItemReport.ID any (holds a numeric GitHub ID or occasionally a string SHA). Worth checking call sites — likely reducible to string if producers already stringify, or a small EntityID wrapper otherwise.
• pkg/cli/gateway_logs_types.go:221,232 — rpcRequestPayload.ID any / rpcResponsePayload.ID any — this is the correct shape per the JSON-RPC 2.0 spec (id is string|number|null); a named type JSONRPCID any would self-document intent but isn't urgent.
• pkg/workflow/workflow_file.go:10,16 (On any, RunsOn any), pkg/cli/list_workflows_command.go:29 (On any), pkg/cli/runner_guard_activation_gate.go:19 (Needs any) — all mirror GitHub Actions' own multi-shape YAML fields (string or list or map). Acceptable; Needs any lacks a doc comment unlike its sibling Ports any field — worth adding one for consistency.
• pkg/workflow/frontmatter_types.go:356,480,485 — Engine any, Evals any, Graders any, all already comment-documented as multi-shape YAML. Acceptable, but a sum-type with custom UnmarshalYAML would let call sites in engine_config_parser.go/evals_config.go stop re-deriving the shape via scattered assertions.
• pkg/workflow/tools_types.go — PrivateToPublicFlows any and three Raw any fields (tagged yaml:"-"), well-commented deferred-parsing pattern. Acceptable.
• pkg/parser/import_observability.go:18 — Headers any; likely always map[string]string in practice — worth confirming via call sites and narrowing.

Category 4: map[string]interface{}/any

Impact: Architectural pattern, not scattered bugs

map[string]interface{} is fully gone (0 occurrences). map[string]any at 3,262 occurrences / 516 files is overwhelmingly the YAML/JSON frontmatter-parsing boundary:

• pkg/workflow/tools_parser.go — heaviest concentration (50+ assertions in one file); best lever is per-tool UnmarshalYAML, not chasing individual sites.
• pkg/cli/codemod_*.go (20+ files) — one-shot migration scripts doing generic YAML tree surgery. Acceptable by nature.
• pkg/workqueue/*.go — JSON-Schema-validated queue protocol (commitSchema validates shape before typed decode). Schema-enforced, not loosely typed. Acceptable.
• pkg/typeutil/lookup.go — intentional generic accessor library. Acceptable.

Category 5: Untyped Constants

Impact: Medium — cheap fix, and the codebase already proves the convention works

pkg/constants/constants.go and job_constants.go already define semantic wrapper types (CommandPrefix, FilePath, LineLength, JobName, StepID, MCPServerID) and apply them to most constants in those same files — these are the untyped stragglers that break that established local convention:

• pkg/constants/constants.go:329 — const DefaultMCPGatewayPayloadSizeThreshold = 524288 → untyped int byte-size threshold; type as int64 (or a semantic ByteSize), matching the LineLength-style convention a few lines away.
• pkg/constants/constants.go:432 — const DefaultMaxRuns = 500 → untyped int; compare to DefaultMaxAICredits int64 = 1000 nearby, which is typed.
• pkg/constants/constants.go:429 — const DefaultMaxDailyAICredits = "5000" → highest-risk finding: a numeric value stored as an untyped string constant; any arithmetic use needs a parse step with no compile-time guarantee it's numeric. Recommend int64.
• pkg/constants/constants.go:435 — const DefaultMaxTurnCacheMisses = 5 → untyped int count/threshold.
• pkg/constants/constants.go:738 — const MaxSymlinkDepth = 5 → untyped int recursion/traversal limit.
• pkg/constants/job_constants.go:309-310 — DefaultRateLimitMax = 5, DefaultRateLimitWindow = 60 → untyped ints; the window is documented as minutes in a comment but nothing enforces the unit. Recommend time.Duration for the window (60 * time.Minute).
• pkg/workqueue/codec.go:26-27 — maxParseBytes = 80 << 20, maxLineBytes = 8 << 20 → untyped int byte-size limits compared against len([]byte); add explicit int/int64 type annotations.
• pkg/cli/token_usage_types.go:289-291 — modelMismatchReasonTokenUsageMissing/ModelNotObserved/SubagentFailed → three untyped string constants forming an enum family with no named type tying them together. Recommend type ModelMismatchReason string.
• pkg/constants/constants.go:315 — const AWFDefaultLogLevel = "info" → untyped string, enum-like log-level domain; candidate for a LogLevel type if other level literals ("debug", "warn") appear elsewhere (worth a follow-up grep before committing).

---

Recommendations, Prioritized

Priority 1 — Untyped constants (cheapest, highest clarity win)

Apply the existing pkg/constants semantic-type convention to the stragglers: DefaultMaxRuns, DefaultMaxDailyAICredits (string→int64 — the riskiest one), DefaultMaxTurnCacheMisses, MaxSymlinkDepth, DefaultRateLimitMax/Window, and the two workqueue/codec.go byte-size constants. Also introduce type ModelMismatchReason string for the three token_usage_types.go enum constants.
Estimated effort: 2-3 hours · Impact: Medium (clarity, near-zero risk)

Priority 2 — RunID/RunIDOrURL typed union (best interface{}/any fix)

Replace any with a StringOrNumber-style type (custom UnmarshalJSON) for auditArgs.RunID/RunIDOrURL in pkg/cli/mcp_tools_privileged.go, removing the runtime type-switch in normalizeAuditRunInput and producing a clearer generated MCP schema.
Estimated effort: 2-3 hours · Impact: Medium-High (public MCP tool input surface)

Priority 3 — tools_parser.go per-tool UnmarshalYAML

Shrink the map[string]any + manual-assertion boundary in pkg/workflow/tools_parser.go by giving each XToolConfig its own UnmarshalYAML. Highest density of assertions in the repo; biggest single-file win, but also the biggest effort.
Estimated effort: 1-2 days · Impact: High (maintainability of the densest parsing file in the codebase)

Priority 4 — Consolidate ValidationError family

Fold workflow.WorkflowValidationError's extra fields into a single richer validationerror type, or clearly document why three wrapper types exist around the shared Payload.
Estimated effort: 3-4 hours · Impact: Medium (touches error-handling call sites across two packages)

Lower priority / cleanup

• Move runtimeImportReference to a shared location (1-2 hours).
• Document or unify the graderManifestEntry reader/writer split (2 hours).
• Rename cli.LogParser[T] to avoid the naming collision with workflow.LogParser (30 min).

Implementation Checklist

• Type the untyped constants in pkg/constants/constants.go and job_constants.go (Priority 1)
• Fix DefaultMaxDailyAICredits string→typed-numeric constant specifically (highest risk item)
• Introduce ModelMismatchReason type in pkg/cli/token_usage_types.go
• Add a typed RunID/RunIDOrURL union for the MCP audit tool input (Priority 2)
• Evaluate per-tool UnmarshalYAML refactor for pkg/workflow/tools_parser.go (Priority 3)
• Decide on consolidating or documenting the ValidationError family (Priority 4)
• Relocate runtimeImportReference to a shared package
• Document or unify graderManifestEntry cli/workflow split
• Run full test suite after any of the above changes

Analysis Metadata

• Total Go files analyzed (non-test, pkg/): 1,542
• Total type declarations (grep-based estimate): 1,667
• Duplicate clusters: 7 (5 exact, 1 near, 1 semantic)
• Untyped usage locations curated: ~25 (interface{}/any) + 9 (constants), out of thousands of raw grep hits
• Detection method: Serena semantic analysis (get_symbols_overview) + targeted grep + manual call-site review
• Analysis date: 2026-10-14

Generated by ✍️ Typist - Go Type Analysis · claude · agent · 345.9 AIC · ⊞ 6.6K · ◷

• expires on Oct 15, 2026, 3:41 AM UTC-08:00

[github-actions[bot]]

This discussion was automatically closed because it expired on 2026-10-15T11:41:19.037Z.

Closed by Workflow