[typist] Typist: Go type consistency analysis — 2 duplicate type clusters, 13 untyped-usage opportunities

[github-actions[bot]]

🔤 Typist - Go Type Consistency Analysis

Analysis of repository: github/gh-aw

Executive Summary

I scanned all 1,532 non-test .go files under pkg/ (1,534 top-level type definitions: struct/interface bodies, aliases, and named base types) looking for duplicated types and weakly-typed code. The codebase is in good shape overall — most apparent "duplicates" turned out to be intentional platform stub pairs ((go/redacted):build js || wasm) or a correct adapter pattern (per-scanner *Finding structs normalized into a shared scanfindings.Finding). After filtering those out, 2 real near-duplicate clusters survived, both caused by the same root issue: a producer package and a consumer package each independently re-declaring the shape of an on-disk artifact (a macro reference regex match, and a JSON manifest entry) instead of sharing one type.

On the untyped-usage side, interface{} itself is essentially unused (2 hits) since the codebase already follows the modern any convention — but any appears roughly 2,800 times, and a good chunk of those are genuine opportunities: a tools map[string]any signature repeated across 80 occurrences in 36 files in pkg/workflow (every engine renderer re-implements its own tools["x"].(map[string]any) lookups), two ID any JSON fields whose real domain (number-or-string) is already documented in a comment, and about a dozen untyped numeric/string constants representing ports, memory sizes, and closed-set modes that are currently indistinguishable from any other bare int/string at compile time. None of this is urgent, but the tools map[string]any pattern in particular is worth a shared type given how many call sites re-derive the same assertions.

Full Analysis Report

Duplicated Type Definitions

Summary Statistics

• Total types analyzed: 1,534 (1,432 structs/interfaces, 29 aliases, 73 named base types)
• Duplicate clusters found: 2
• Exact duplicates: 0
• Near duplicates: 2
• Semantic duplicates: 0

Three other name collisions were investigated and ruled out as intentional, not duplication:

• ValidationError — interface (pkg/validationerror/validationerror.go:49) vs. struct (pkg/parser/validation_error.go:12) that deliberately embeds the shared validationerror.Payload and implements the interface — this is the project's existing de-duplication mechanism.
• SpinnerWrapper (pkg/console/spinner.go:92 / spinner_wasm.go:12) and ProgressBar (pkg/console/progress.go:31 / progress_wasm.go:9) — (go/redacted):build js || wasm vs. !js && !wasm platform stub pairs.

Cluster 1: runtimeImportReference near-duplicate

Type: Near duplicate
Occurrences: 2
Impact: Medium

Locations:

1. pkg/parser/frontmatter_hash.go:572 — type runtimeImportReference struct { path string; startLine int; endLine int }
2. pkg/workflow/runtime_import_validation.go:38 — type runtimeImportReference struct { importPath string; startLine int; endLine int }

Both files also independently embed a byte-for-byte identical regex literal to extract the reference:

regexp.MustCompile(`\{\{#(?:runtime-import|import)\??(?:[ \t]+|[ \t]*:[ \t]*)([^{}]+?)\}\}`)

(pkg/parser/frontmatter_hash.go:579 and pkg/workflow/runtime_import_validation.go:33), and each package has its own extractRuntimeImportReferences function building it. A third file, pkg/workflow/compiler_yaml_prompt.go:407, consumes the pkg/workflow variant.

Recommendation:

• Pick one package (likely pkg/parser, since it already owns frontmatter/macro parsing) as the canonical owner of runtimeImportReference and its extraction regex/function.
• Have pkg/workflow import and reuse it instead of maintaining its own copy with a differently-named field (path vs importPath).
• Estimated effort: 1-2 hours
• Benefits: One regex to maintain — today a fix to the macro syntax in one file could silently diverge from the other.

---

Cluster 2: graderManifestEntry producer/consumer split

Type: Near duplicate (field subset)
Occurrences: 2
Impact: Medium

Locations:

1. pkg/workflow/compiler_yaml_graders.go:84 — write-side struct the compiler marshals into the GH_AW_GRADER_MANIFEST JSON consumed by the JS runtime: ID, Name, Description, Source string; Enabled bool; Unit, Direction string; Threshold, Max, Min *float64; Digest, Run, Inline string; Config map[string]any.
2. pkg/cli/audit_report_graders.go:67 — read-side struct used only to re-parse that same manifest for the audit report: ID string; Name string; Unit string; Direction string; Threshold *float64 (json tags id/name/unit/direction/threshold match the producer exactly).

Recommendation:

• Move the canonical graderManifestEntry shape into a small shared package (e.g. pkg/graders or pkg/types) that both pkg/workflow (writer) and pkg/cli (reader) import.
• The pkg/cli reader can keep using only the fields it displays, but sharing the struct removes the risk that a json-tag rename in the writer silently stops populating the reader.
• Estimated effort: 1-2 hours
• Benefits: Single source of truth for the manifest schema; a test (pkg/workflow/graders_workflow_integration_test.go:78 already round-trips graderManifestEntry — this would also confirm cross-package parity).

---

Untyped Usages

Summary Statistics

• interface{} usages: ~2 (codebase already standardized on any)
• any usages: ~2,800
• Untyped constants flagged: 7 groups (~45 individual constants)
• Total untyped locations reported below: 13

Category 1: any in function parameters / struct fields

Impact: High — repeated type assertions, no compile-time shape guarantee

tools map[string]any across the engine layer

• Location: pkg/workflow/agentic_engine.go:253 (RenderMCPConfig(yaml *strings.Builder, tools map[string]any, mcpTools []string, workflowData *WorkflowData) error), repeated with the same shape in claude_mcp.go, codex_mcp.go, gemini_mcp.go, copilot_mcp.go, pi_mcp.go, agy_mcp.go, behavior_defined_engine.go, tools.go, tools_validation.go, and more.
• Actual usage: Verified via grep — 80 occurrences across 36 non-test files in pkg/workflow, all keyed by a fixed, known set of tool names (github, bash, edit, web-fetch, playwright, custom MCP server names) and accessed via tools["x"].(map[string]any).
• Suggested fix:

  type ToolsConfig map[string]any
  // or a struct with named fields for built-in tools plus Custom map[string]any for MCP servers
  func RenderMCPConfig(yaml *strings.Builder, tools ToolsConfig, mcpTools []string, workflowData *WorkflowData) error

• Benefits: A named type lets helper accessors (tools.GitHub(), tools.Bash()) replace scattered tools["x"].(map[string]any) assertions, and documents intent at every one of the 36 call sites.

ID any fields with a documented two-way domain

• Locations: pkg/cli/audit_report.go:169, pkg/cli/gateway_logs_types.go:221 and :232, pkg/cli/mcp_tools_privileged.go:456.
• Actual usage: pkg/cli/audit_report.go's own comment on isUnconstrainedSchema/fixCreatedItemIDSchema documents the field as either a numeric database ID (int64) or a string identifier (Jira/Linear) — the JSON Schema generator is patched after the fact specifically to narrow this field. gateway_logs_types.go's ID any is a JSON-RPC id, which per spec is number-or-string only.
• Suggested fix:

  type ItemID struct {
      Numeric  int64
      String   string
      IsString bool
  } // custom MarshalJSON/UnmarshalJSON

• Benefits: Makes the already-documented two-value contract visible to the compiler instead of being reconstructed by schema post-processing.

Category 2: Untyped constants

Impact: Medium — unit/enum confusion

Network ports

• Location: pkg/constants/constants.go:169 — DefaultMCPGatewayPort, DefaultMCPServerPort, MinNetworkPort, MaxNetworkPort, CodexLLMGatewayPort, etc. (bare int, explicitly re-cast with int(...) at several call sites in mcp_setup_gateway.go, mcp_gateway_config.go, awf_command_builder.go).
• Suggested fix: type Port uint16 with the constants typed accordingly, plus a Valid() method — removes the need for the existing re-casts and prevents a timeout/retry-count int from being passed where a port is expected.

Resource sizes mixing units

• Location: pkg/constants/constants.go:251 — DefaultCloudHypervisorMemoryMiB, DefaultNVXMemoryMiB, DefaultNVXMemoryMaxBytes (MiB and bytes, unmarked, sitting next to each other — DefaultNVXMemoryMiB (512) and DefaultNVXMemoryMaxBytes (536,870,912) encode the same quantity in two different units).
• Suggested fix: type MiB int64, type Bytes int64 to make the unit mismatch impossible to introduce silently.

Closed-set string "enums"

• Locations: pkg/cli/mcp_registry_types.go:108 (StatusActive/StatusInactive), :114 (ArgumentTypePositional/ArgumentTypeNamed), pkg/workflow/behavior_defined_engine.go:20 (behaviorSecretStrategy*, behaviorProviderEnvMode*, behaviorConfigMergeJSON).
• Suggested fix: type ServerStatus string, type ArgumentType string, type SecretStrategy string, etc. — each is a 2-4 value closed set currently compared with plain ==/!= against a bare string, so a YAML/API typo compiles cleanly and only fails at runtime.

Category 3: Recurring untyped recursive-walk pattern (informational)

Not a direct replacement candidate — Options map[string]any on EngineDefinition (pkg/workflow/mcp_registry.go:592) is genuinely open-ended per-engine config — but the switch v := v.(type) { case map[string]any: ...; case []any: ... } walk that processes it is duplicated verbatim across at least 6 files (behavior_defined_engine.go, pkg/parser/yaml_import.go, schema_suggestions.go, tools_merger.go, schema_deprecation.go, pkg/workqueue/identity.go). A shared YAMLValue sum-type alias plus one shared walk helper would cut the duplicated assertion logic without changing the underlying dynamism.

---

Refactoring Recommendations

Priority 1: Medium — Consolidate the two near-duplicate types

Recommendation: Share runtimeImportReference and graderManifestEntry between their producer/consumer packages instead of maintaining parallel copies.

Steps:

1. Pick the owning package for each type (pkg/parser for the import-reference regex/struct; a new small shared package for the grader manifest entry).
2. Update the other package's imports and field references.
3. Run make test-unit to confirm no behavior change.

Estimated effort: 2-4 hours combined
Impact: Medium — removes two spots where the two packages could silently drift.

---

Priority 2: High-value, low-risk — Type the tools map[string]any signature

Recommendation: Introduce a ToolsConfig named type (even a plain alias) for the 80-occurrence tools map[string]any pattern in pkg/workflow.

Steps:

1. Define type ToolsConfig map[string]any (or a struct) in pkg/workflow.
2. Swap the parameter/field type across the 36 affected files — no behavior change since map[string]any is the underlying type.
3. Incrementally add accessor methods where call sites currently do manual type assertions.

Estimated effort: 3-5 hours (mechanical signature change) + incremental follow-up for accessors
Impact: High — this is the single most duplicated untyped pattern in the codebase by call-site count.

---

Priority 3: Low — Type the closed-set constants

Recommendation: Add named types to the port, resource-size, and string-enum constant groups in pkg/constants/constants.go, pkg/cli/mcp_registry_types.go, and pkg/workflow/behavior_defined_engine.go.

Steps:

1. Define Port, MiB/Bytes, ServerStatus, ArgumentType, SecretStrategy types.
2. Update the const blocks and the handful of struct fields/comparisons that reference them.
3. Run make fmt and make test-unit.

Estimated effort: 2-3 hours
Impact: Low-medium — mostly prevents future unit/typo mistakes rather than fixing an active bug.

---

Implementation Checklist

• Consolidate runtimeImportReference into one owning package
• Share graderManifestEntry between pkg/workflow (writer) and pkg/cli (reader)
• Introduce ToolsConfig type for the 80-occurrence tools map[string]any pattern
• Add a typed ItemID/JSON-RPC id wrapper for the two ID any fields
• Type the network-port, resource-size, and closed-set string constants
• Run make test-unit after each change

Analysis Metadata

• Total Go Files Analyzed: 1,532 (non-test, under pkg/)
• Total Type Definitions: 1,534
• Duplicate Clusters: 2 (both "near")
• Untyped Usage Locations Reported: 13 (from ~2,800 raw any hits, triaged for genuine impact)
• Detection Method: Parallel sub-agent pattern scan (ripgrep/Grep) + manual grep-based cross-reference tracing (Serena's language-server backends were unavailable in this sandbox — Go/Node not installed — so semantic reference-finding fell back to text search)
• Analysis Date: 2026-10-13

References: §38390786472

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

• expires on Oct 14, 2026, 3:41 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 #68675.