[typist] Typist: Go type consistency findings - duplicated types and untyped any/interface usage

[github-actions[bot]]

🔤 Typist - Go Type Consistency Analysis

Analysis of repository: github/gh-aw

Executive Summary

I scanned 1,380 non-test .go files under pkg/ (1,335 type definitions) for duplicated type definitions and untyped (interface{}/any) usage. The good news: the codebase is disciplined about the old interface{} spelling — production code has essentially none of it (33 hits, and every one is either linter testdata or a doc comment). The interesting findings are elsewhere: a handful of small, unexported structs quietly reimplemented in two packages, and a much bigger pattern where map[string]any is passed around as a stand-in for several genuinely-shaped config objects — including one case where a proper named type (MapToolConfig) already exists but is used in only 4 of the ~33 places that could use it.

Nothing here is an emergency; most of the any usage is deliberate (JSON Schema / YAML frontmatter is inherently dynamic before validation, and several fields are commented as "too dynamic to type"). But a few clusters — the Azure DevOps Target any field repeated across 5 structs, and the toolConfig/GuardPolicies maps threaded through 15+ files — are prime candidates for a shared named type that would remove a lot of repeated .(string)/.(map[string]any) assertions.

Full Analysis Report

Duplicated Type Definitions

Summary Statistics

• Total files analyzed: 1,380
• Total types analyzed: 1,335
• Duplicate clusters found: 4 (after discarding one false positive — see note below)
• Exact duplicates: 2
• Near duplicates: 1
• Semantic duplicates: 2

Note on a false positive: the automated pass initially flagged parser.ValidationError / validationerror.ValidationError as an exact duplicate. On inspection, validationerror.ValidationError is an interface and parser.ValidationError is a concrete struct that implements it (pkg/parser/validation_error.go:12) — the shared name is intentional (like io.Writer and a type named Writer), not a duplicate. Excluded from the findings below.

---

Cluster 1: runtimeImportReference — Exact Duplicate

Occurrences: 2
Impact: Low-medium — identical unexported struct, easy to consolidate

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
   }

Recommendation: Both track "an import reference found at a line range in markdown/frontmatter". Move a single RuntimeImportReference (exported) into pkg/types (which already centralizes shared cross-package types) and have both parser and workflow use it.
Estimated effort: 1 hour
Benefit: One definition to update if the shape needs to change; removes the risk of the two silently drifting.

---

Cluster 2: graderManifestEntry — Near Duplicate

Occurrences: 2
Impact: Medium — the cli copy is a strict subset of the workflow copy, read from the same JSON manifest file

Locations:

1. pkg/cli/audit_report_graders.go:67 — 5 fields (ID, Name, Unit, Direction, Threshold)
2. pkg/workflow/compiler_yaml_graders.go:86 — 13 fields (adds Description, Source, Enabled, Max, Min, Digest, Run, Inline, Config map[string]any)

Both carry json:"..." tags for the same manifest document that workflow writes and cli later reads back for reporting.

Recommendation: Export the workflow struct (or move it to pkg/types) and have cli/audit_report_graders.go decode into that same type instead of a hand-maintained subset. Today, adding a field in workflow silently does nothing in cli until someone remembers to mirror it.
Estimated effort: 1-2 hours
Benefit: Guarantees the CLI report never silently drops a field the compiler starts emitting.

---

Cluster 3: Log entry family — Semantic Duplicates

Occurrences: 4 (all in pkg/cli)
Impact: Low — different log sources, but heavily overlapping shape

• pkg/cli/access_log.go — AccessLogEntry (Timestamp, Duration, ClientIP, Status, Size, Method, URL, User, Hierarchy, Type — all string)
• pkg/cli/firewall_log.go — FirewallLogEntry (Timestamp, ClientIPPort, Domain, DestIPPort, Proto, Method, Status, Decision, URL, UserAgent)
• pkg/cli/gateway_logs_types.go — GatewayLogEntry (22 fields, superset-ish of the others plus MCP-specific fields)
• pkg/cli/firewall_policy.go — AuditLogEntry (Schema, Timestamp (float64, not string!), Client, Host, Dest, Method, Status (int), Decision, URL)

Recommendation: Not a "merge them all" situation — these represent genuinely different log formats. But Timestamp/Method/URL/Status/Decision recur in 3-4 of them with inconsistent types (string vs float64 timestamp, string vs int status). Worth a shared type CommonLogFields struct{ Timestamp string; Method string; URL string } embed for the fields that really are the same concept, and picking one representation (probably time.Time/RFC3339 string) for timestamps across all four.
Estimated effort: 2-3 hours
Benefit: Removes a source of "which log has Status as a string vs an int" bugs when writing shared formatting/filtering helpers.

---

Cluster 4: SourcePosition-shaped types — Semantic Duplicates

Occurrences: 2
Impact: Low

1. pkg/console/console_types.go — ErrorPosition{ File string; Line int; Column int }
2. pkg/parser/json_path_locator.go — JSONPathLocation{ Line int; Column int; Found bool }

Recommendation: Both represent "a place in a source file". Low priority since the field sets aren't identical (File/Found differ), but a shared pkg/types.SourcePosition{Line, Column int} embedded in both would remove the duplicated Line/Column pair.
Estimated effort: 30-60 minutes
Benefit: Minor clarity gain; do this only if touching either file for other reasons.

---

Untyped Usages

Summary Statistics

• interface{} usages (production code): 0 — the only 33 hits repo-wide are in linter testdata fixtures (which intentionally test for old-style interface{}) and one doc comment (pkg/cli/mcp_schema.go:121). No action needed here; the codebase has already standardized on any.
• any usages: hundreds of legitimate type-position uses after filtering out the English word "any" in comments/strings. The categories below are the ones worth typing more strongly.
• Untyped constants: scanned const X = "..." across pkg/ — the ~80 hits are all path/URL/flag-name/env-var literals (e.g. GhAwRootDir, DefaultAlpineImage), which is the idiomatic Go pattern for this kind of value. No untyped-constant cluster worth flagging.

---

Category 1: toolConfig map[string]any — parameter type used instead of an existing named type

Impact: High — a named type (MapToolConfig) already exists with helper methods, but is bypassed almost everywhere

pkg/workflow/mcp_config_types.go:70 defines:

type MapToolConfig map[string]any

func (m MapToolConfig) GetString(key string) (string, bool) { ... }

But MapToolConfig is referenced in only 4 files (mcp_config_custom.go, mcp_config_types.go, its test, and the README), while the raw map[string]any spelling for the same "MCP tool config" concept is used as a parameter type in 29 places across 14 files, including:

• pkg/parser/mcp.go (5 functions: buildExpandedLinearBuiltinConfig, buildLinearAllowedTools, appendBuiltinAllowedTools, applyGitHubBuiltinOverrides, parseMCPStdioTypeConfig, ...)
• pkg/workflow/codex_mcp.go, copilot_mcp.go, mcp_github_config.go, mcp_property_validation.go, mcp_manifest.go, args.go
• pkg/cli/mcp_add.go, mcp_secrets.go

Suggested fix: Switch these signatures from toolConfig map[string]any to toolConfig MapToolConfig (it's a defined map type, so this is typically a zero-cost, mostly mechanical rename — call sites passing a map[string]any literal convert implicitly). Then replace ad hoc .(string) assertions in those functions with the existing GetString helper.
Estimated effort: 3-4 hours (mechanical, but touches many files — good candidate for a single focused PR)
Benefit: One place to add new accessors (GetBool, GetStringSlice, ...) instead of every call site re-deriving the assertion pattern; makes "this is MCP tool config" visible in every signature instead of "this is a map".

---

Category 2: Target any repeated across 5 Azure DevOps safe-output configs

Impact: Medium — same field, same YAML tag, same (implicit) semantics, defined 5 times

pkg/workflow/safe_outputs_azure_devops.go:

type UpdateWorkItemConfig struct { ...; Target any `yaml:"target,omitempty"`; ... }          // line 40
type CommentOnWorkItemConfig struct { ...; Target any `yaml:"target,omitempty"` }             // line 52
type AssignWorkItemConfig struct { ...; Target any `yaml:"target,omitempty"`; ... }           // line 57
type LinkWorkItemsConfig struct { ...; Target any `yaml:"target,omitempty"`; ... }            // line 64
type UploadWorkItemAttachmentConfig struct { ...; Target any `yaml:"target,omitempty"`; ... } // line 70

All five accept the same shape at parse time (a work-item ID as string or number, based on comments elsewhere in the file), but the type gives no hint of that to a reader or to whatever code eventually consumes Target.

Suggested fix: Introduce a small AzureDevOpsTarget type (e.g. one that unmarshals string-or-int and exposes a normalized accessor), and either give it a single field name via an embedded type TargetableConfig struct { Target AzureDevOpsTarget } mixed into all 5 structs, or at minimum change all 5 fields to the same named type instead of bare any.
Estimated effort: 2 hours
Benefit: Whatever code currently type-switches on Target (string vs int) only has to do it once; new work-item config types get the right shape by construction.

---

Category 3: GuardPolicies map[string]any — same field name/shape, 4 different structs

Impact: Medium

• pkg/workflow/tools_types.go:513
• pkg/workflow/mcp_renderer_types.go:21 (WriteSinkGuardPolicies), :92, :129
• pkg/workflow/mcp_config_types.go:54

All in pkg/workflow, all representing the same "per-tool guard policy" concept threaded through the MCP tool pipeline.

Suggested fix: Define type GuardPolicyMap map[string]any (or a more specific shape if the policy structure is known) once in mcp_config_types.go and reuse it for all 4 fields.
Estimated effort: 1 hour
Benefit: Signals intent at each use site; a future refactor to a real GuardPolicy struct only needs to change one type definition.

---

Category 4: RunsOn / RunsOnSlim any — polymorphic GitHub Actions runner value

Impact: Medium — appears in pkg/workflow/workflow_file.go:16, frontmatter_types.go:409-410, and is unmarshaled twice (near-identically) in runs_on_unmarshal.go:16,38

Comments already document the intended shape: "Supports string, array, or object GitHub Actions runner forms." That's a textbook case for a small custom type with its own UnmarshalYAML/UnmarshalJSON, rather than leaking any to every consumer and re-deriving the same type switch in runs_on_unmarshal.go twice.

Suggested fix: type RunsOnValue struct { /* normalized form */ } with custom (un)marshaling, used consistently instead of any + ad hoc unmarshal shims.
Estimated effort: 3-4 hours (touches the unmarshal logic, which needs care)
Benefit: Removes the duplicated unmarshal-shim logic and gives downstream code a real API instead of a type switch.

---

Category 5: Frontmatter map[string]any duplicated across packages

Impact: Low-medium

• pkg/parser/frontmatter_content.go:20
• pkg/cli/mcp_workflow_scanner.go:21

Both represent "parsed YAML frontmatter of a workflow file" as a bare map. Since pkg/parser already owns frontmatter parsing, pkg/cli re-declaring its own map[string]any-typed field for the same concept is a missed reuse opportunity (whether or not it's the exact same struct).

Suggested fix: Have the cli struct reference/alias the parser package's frontmatter map type (or the eventual typed frontmatter struct, if one exists) instead of independently declaring map[string]any.
Estimated effort: 30-60 minutes
Benefit: One less place where "frontmatter" means something different by convention only.

---

Category 6: Config map[string]any for grader/tool config, duplicated across cli and workflow

Impact: Low-medium

• pkg/cli/mcp_registry.go:28, pkg/cli/graders_run.go:60
• pkg/workflow/compiler_yaml_graders.go:100, pkg/workflow/graders_config.go:79 (commented "arbitrary config passed to grader at runtime")

Same pattern as Category 3 but for grader/registry config rather than guard policies — reinforces that map[string]any is being used as the de facto "arbitrary config bag" type across the whole compiler/CLI boundary, with no shared name tying the occurrences together.

Suggested fix: A single type RawConfig = map[string]any (type alias, not a new named type, to avoid conversion churn) in pkg/types, imported everywhere this pattern appears — mostly a documentation/searchability win rather than a type-safety one, but makes grepping for "everywhere we still have an arbitrary config bag" trivial going forward.
Estimated effort: 1 hour
Benefit: Cheap, low-risk first step; makes the remaining "should this be a real struct" work easier to scope later.

---

What Should We Do About This?

Prioritized by impact-to-effort ratio:

Priority 1 — Use the type you already wrote

Recommendation: Migrate the 29 toolConfig map[string]any parameters to the existing MapToolConfig type (Category 1).
Steps:

1. Change parameter/field types from map[string]any to MapToolConfig in the 14 identified files.
2. Replace manual .(string) assertions with MapToolConfig.GetString/new accessors as needed.
3. go build ./... — conversions should be implicit; fix any explicit map[string]any{...} literals that need a cast.
4. Run the existing test suite.

Estimated effort: 3-4 hours | Impact: High

Priority 2 — Consolidate the two exact/near-duplicate structs

Recommendation: Merge runtimeImportReference (Cluster 1) and align graderManifestEntry (Cluster 2) on a single shared type in pkg/types.

Estimated effort: 2-3 hours combined | Impact: Medium — prevents silent drift between packages that read/write the same data.

Priority 3 — Name the repeated any fields

Recommendation: Introduce AzureDevOpsTarget, GuardPolicyMap, and RunsOnValue types (Categories 2-4).

Estimated effort: 6-8 hours combined | Impact: Medium — mostly clarity and future-proofing, not urgent.

Priority 4 — Cheap documentation-level wins

Recommendation: RawConfig alias (Category 6), shared Frontmatter type (Category 5), SourcePosition (Cluster 4).

Estimated effort: 2-3 hours combined | Impact: Low, good "while you're in the area" cleanups.

---

Implementation Checklist

• Migrate toolConfig map[string]any call sites to MapToolConfig
• Consolidate runtimeImportReference into a shared exported type
• Align cli.graderManifestEntry with workflow.graderManifestEntry (single source of truth)
• Introduce AzureDevOpsTarget type for the 5 Target any fields
• Introduce GuardPolicyMap for the 4 GuardPolicies/WriteSinkGuardPolicies fields
• Design a RunsOnValue type with custom (un)marshaling
• Share the Frontmatter map type between pkg/parser and pkg/cli
• Add a RawConfig alias for the recurring "arbitrary config bag" pattern
• Run full test suite after each change

Analysis Metadata

• Total Go Files Analyzed: 1,380 (non-test, under pkg/)
• Total Type Definitions Surveyed: 1,335
• Duplicate Clusters Reported: 4 (1 false positive excluded — see note above)
• Untyped Usage Categories Reported: 6
• Detection Method: Serena semantic analysis (get_symbols_overview, find_referencing_symbols) + targeted pattern search
• Analysis Date: 2026-09-24

Warning

Firewall blocked 1 domain

The following domain was blocked by the firewall during workflow execution:

• api.anthropic.com

To allow these domains, add them to the network.allowed list in your workflow frontmatter:

network:
  allowed:
    - defaults
    - "api.anthropic.com"

See Network Configuration for more information.

Generated by ✍️ Typist - Go Type Analysis · claude · agent · 522.5 AIC · ⌖ 9.01 AIC · ⊞ 10.2K · ◷

• expires on Sep 25, 2026, 3:45 AM UTC-08:00

[github-actions[bot]]

This discussion was automatically closed because it expired on 2026-09-25T11:45:54.309Z.

Closed by Workflow