[typist] Typist: Go Type Consistency Analysis (pkg/)

[github-actions[bot]]

🔤 Typist — Go Type Consistency Analysis

Analysis of repository: github/gh-aw · scope: pkg/**/*.go, excluding _test.go

Executive Summary

I scanned roughly 1,480 non-test type declarations under pkg/ and found 11 duplicate/near-duplicate type clusters (10 real candidates for consolidation, 1 that turned out to be an intentional wasm-build-tag split). The clearest win is pkg/cli/mcp_schema.go, which has independently hand-copied at least five "wire" structs (domainAnalysisWireSchema, mcpServerHealthDetailWire, mcpServerCrossRunHealthWire, mcpFailureSummaryWire, toolUsageSummaryWire) that already exist as real types or anonymous MarshalJSON structs elsewhere in the same package — any field added to the real type silently won't show up in the schema doc, and vice versa.

On the untyped-usage side, the good news is the codebase has already migrated off interface{} almost entirely (16 hits total, nearly all in linter testdata fixtures, not production code). The real opportunity is a map[string]any/any pattern used for a handful of closed-shape config fields (Engine, RunsOn, RunsOnSlim, Checkout, Imports in pkg/workflow/frontmatter_types.go) whose comments already document the exact 2-3 accepted shapes — these are strong candidates for dedicated sum types with custom UnmarshalYAML. I also found a couple of untyped numeric constants (DefaultRateLimitWindow, workflowCompletionWaitTimeoutMinutes) that encode a time unit only in their comment/identifier rather than their type, which is exactly the kind of thing time.Duration exists to prevent.

Serena's semantic reference tracing (find_referencing_symbols) could not run for this analysis — the sandbox has no Go toolchain installed, so Serena's gopls-backed language server failed to initialize. Findings below were cross-checked with targeted grep-based reference searches instead, which confirmed the flagged duplicate structs are each self-contained (no shared references between the two copies), i.e. genuinely independent, drift-prone definitions rather than one referencing the other.

Full Analysis Report

Duplicated Type Definitions

Summary Statistics

• Type declarations sampled: ~1,480
• Duplicate clusters found: 11 (10 actionable, 1 intentional build-tag split)
• Exact duplicates: 1
• Near duplicates: 9
• Semantic duplicates: 1

Cluster 1: runtimeImportReference — near duplicate

Occurrences: 2 · Impact: Medium

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

Same unexported name in two packages, same 3-field shape (only the path field is renamed). Both files also independently maintain their own regex for parsing {{#runtime-import ...}} macros — this looks like the whole macro-reference parsing logic was copy-pasted between pkg/parser and pkg/workflow.

Recommendation: extract a shared RuntimeImportReference type (and its parsing regex) into a common package (e.g. pkg/parser if pkg/workflow already depends on it, or a new small shared package) and have both call sites use it.

---

Cluster 2: graderManifestEntry — near duplicate (schema drift risk)

Occurrences: 2 · Impact: High

• pkg/workflow/compiler_yaml_graders.go:86 — 13 fields (ID, Name, Description, Source, Enabled, Unit, Direction, Threshold, Max, Min, Digest, Run, Config)
• pkg/cli/audit_report_graders.go:67 — 5 fields (ID, Name, Unit, Direction, Threshold)

The pkg/cli copy is a hand-maintained subset of the manifest struct that pkg/workflow writes to disk. Confirmed via grep: neither file imports the other's type, so these are two independently maintained mirrors of the same on-disk JSON schema.

Recommendation: move the canonical graderManifestEntry definition to a shared location (e.g. pkg/workflow exports it, or both import from a small pkg/graders/pkg/types package) so the reader can't silently fall out of sync with the writer.

---

Cluster 3: domainAnalysisWire / domainAnalysisWireSchema — exact duplicate

Occurrences: 2, same package · Impact: High

• pkg/cli/access_log.go:44 — domainAnalysisWire (real MarshalJSON output type)
• pkg/cli/mcp_schema.go:213 — domainAnalysisWireSchema (hand-copied twin for schema docs)

Field-for-field, tag-for-tag identical, both in pkg/cli. Confirmed via grep: the two names appear in disjoint files with no cross-reference.

Recommendation: have mcp_schema.go reference domainAnalysisWire directly (or generate the schema doc struct from it) instead of maintaining a byte-for-byte copy.

---

Clusters 4–6 & 10: the mcp_schema.go "wire twin" pattern

Occurrences: 4 separate instances of the same pattern · Impact: High (systemic)

pkg/cli/mcp_schema.go repeatedly re-declares a private struct that duplicates an anonymous struct literal used inline in another file's MarshalJSON/UnmarshalJSON:

Wire-schema copy (mcp_schema.go)	Real anonymous struct
mcpServerHealthDetailWire (:185)	MCPServerHealthDetail.MarshalJSON, pkg/cli/audit_expanded.go:102
mcpServerCrossRunHealthWire (:196)	MCPServerCrossRunHealth.MarshalJSON, pkg/cli/audit_cross_run.go:96
mcpFailureSummaryWire (:206)	MCPFailureSummary.MarshalJSON, pkg/cli/logs_models.go:226
toolUsageSummaryWire (:177)	ToolUsageSummary (built on shared ToolUsageStatsBase), pkg/cli/logs_report_tools.go:46

Recommendation: this is the single highest-leverage fix in the report. Either (a) have each ...MarshalJSON method use a package-level named struct instead of an anonymous literal, and point mcp_schema.go at that same named type, or (b) generate mcp_schema.go's doc types from the real types via reflection/codegen so the two can never diverge.

---

Cluster 7: MCPToolCall / cachedLogsJSONLMCPToolCall — near duplicate

Occurrences: 2, same package · Impact: Medium

• pkg/cli/audit_report.go:212 — 10 fields including Error
• pkg/cli/logs_cached_json.go:69 — same 9 fields, missing Error

Recommendation: embed MCPToolCall in the cache struct (or reuse it directly) rather than re-declaring 9 of its 10 fields.

---

Cluster 8: JobInfo / cachedLogsJSONLJobData — near duplicate

Occurrences: 2, same package · Impact: Medium

cachedLogsJSONLJobData (pkg/cli/logs_cached_json.go:54) is a manually trimmed subset of JobInfo (pkg/cli/logs_models.go:316) redefined for the on-disk cache format.

Recommendation: embed JobInfo (or the subset of fields as a shared sub-struct) instead of hand-copying field names/types.

---

Cluster 9: AuditLogEntry / FirewallLogEntry / AccessLogEntry / GatewayLogEntry — semantic duplicates

Occurrences: 4, same package (pkg/cli) · Impact: Medium

• pkg/cli/firewall_policy.go:50, pkg/cli/firewall_log.go:118, pkg/cli/access_log.go:21, pkg/cli/gateway_logs_types.go:18

Four independently hand-rolled structs, each representing "one parsed line of a *.jsonl/log file describing a network or tool request." Each has its own Timestamp, a Status, a Method/Type, an outcome field (Decision), and a destination field (URL/Host/Domain) — different log sources (audit log, firewall proxy log, access log, gateway log) but similar enough shape that a shared base could plausibly be factored out, similar to the existing ToolUsageStatsBase/AnalysisBase pattern already used elsewhere in pkg/cli.

Recommendation: lower priority than clusters 3–6/10 since these are genuinely different log sources — but worth a LogRecordBase{ Timestamp, Status, Decision } embed if these types grow more fields in the future.

---

Cluster 11: WasmStyle/SpinnerWrapper/ProgressBar — not a real duplicate

Same type name declared twice in the same package, gated by (go/redacted):build wasm vs. default build tags (pkg/console/spinner.go + spinner_wasm.go, progress.go + progress_wasm.go, pkg/styles/theme_wasm.go). This is the standard, idiomatic Go platform-split pattern, not a bug — flagged here only for completeness/transparency, no action needed.

---

Untyped Usages

Summary Statistics

• Literal interface{} usages: 16 total, almost all in pkg/linters/**/testdata/ fixtures rather than production code — the codebase has already migrated to any
• any-typed params/returns/fields/map-values flagged as improvable: ~18 (listed below)
• Untyped constants flagged: 5 representative examples (out of an estimated several hundred const X = ... declarations repo-wide; most are fine as-is, these stood out as unit-ambiguous)

Category 1: Closed-shape config fields typed any (highest value)

pkg/workflow/frontmatter_types.go has several fields whose doc comments already spell out a closed set of 2–3 accepted YAML shapes, making them ideal candidates for a custom sum type with UnmarshalYAML instead of any + runtime type assertions at every call site:

Field	Location	Documented shapes	Suggested type
Engine	frontmatter_types.go:356	string engine name, or config object	EngineSetting{ Name string; Config *EngineSettingObject }
RunsOn / RunsOnSlim	frontmatter_types.go:409	string / array / object	RunsOnValue sum type
Checkout	frontmatter_types.go:465	false / object / array	CheckoutValue sum type
Imports	frontmatter_types.go:422	string or array	reuse the existing ad hoc helper normalizeStringOrStringSlice (frontmatter_trigger_helpers.go:37) as a real StringOrStringSlice type
RawPermissions	pkg/workflow/safe_jobs.go:27	"write-all"/"read-all" or map[string]string	PermissionsValue, mirroring FrontmatterConfig.Permissions
ID (JSON-RPC)	pkg/cli/gateway_logs_types.go:179,190	string, number, or null	RPCID per JSON-RPC 2.0 convention
RunID / RunIDOrURL	pkg/cli/mcp_tools_privileged.go:430	string or number (id or URL)	RunIdentifier{ ID int64; URL string } with custom UnmarshalJSON

Category 2: any params/returns used only for a fixed set of concrete kinds

• pkg/typeutil/convert.go:49,96,121 — ParseIntValue/ConvertToInt/ConvertToFloat all take any but only ever handle YAML-decoded int/int64/float64/string; a type-switch helper over a named constraint would make the accepted set explicit.
• pkg/workflow/engine_config_parser.go:160 — decodeEngineConfig(config map[string]any, target any) error re-marshals into target; a Go generic func decodeEngineConfig[T any](config map[string]any, target *T) error gives callers a compile-time-checked destination.
• pkg/workflow/observability_otlp.go:303,316 — normalizeOTLPIfMissingMode/getOTLPIfMissingMode normalize into exactly "warn"/"ignore"/"", compared with == later in the same file; a type OTLPIfMissingMode string enum would replace the string-literal comparisons.
• pkg/workflow/sandbox_validation.go:433 and frontmatter_trigger_helpers.go:15 — getFeatureValueCaseInsensitive/extractOnTriggerValue return (any, bool) for values that are really always bool/string or string/map/nil.

Category 3: map[string]any used where a decode-to-struct would remove hand-written extraction code

• pkg/workflow/cache_config.go:129 (parseCacheMemoryEntry) and 6 sibling functions in the same file manually pull known keys (id, description, retention-days, scope, allowed-extensions, restore-only) out of a raw map — a single yaml.Unmarshal into a tagged struct would replace all 7 extraction functions.
• pkg/workflow/evals_config.go:139 (parseEvalDefinition) — same pattern; EvalDefinition already exists as the typed result, so decoding directly into it (or a raw mirror struct) is a small change.
• pkg/workflow/role_checks.go:259 (extractRateLimitInt + friends) — pkg/constants/job_constants.go already defines DefaultRateLimitMax/DefaultRateLimitWindow as the defaults for this exact config; a RateLimitConfig{ Max, Window int } struct would unify the constants with the map-based parsing.

Category 4: Untyped constants missing a semantic unit

// pkg/constants/job_constants.go:306-307 (current)
const DefaultRateLimitMax = 5     // Default maximum runs per time window
const DefaultRateLimitWindow = 60 // Default time window in minutes (1 hour)

// suggested
const DefaultRateLimitMax int = 5
const DefaultRateLimitWindow time.Duration = time.Hour

// pkg/cli/run_workflow_execution.go:25 (current)
const workflowCompletionWaitTimeoutMinutes = 6 * 60

// suggested - the unit no longer needs to live in the identifier
const workflowCompletionWaitTimeout time.Duration = 6 * time.Hour

Similarly, pkg/cli/add_interactive_engine.go:238 (authMethodCopilotRequests/authMethodPAT) and pkg/constants/constants.go:316 (AWFDefaultLogLevel) are small closed enums (auth method, log level) currently expressed as bare string constants — a named string type (type AuthMethod string, type LogLevel string) would let function signatures reject unknown values at compile time rather than accepting arbitrary strings.

What I deliberately did not flag

• deepCopyAny(v any) any (pkg/workflow/behavior_defined_engine.go:881) and recursivelyOrderYAMLValue(value any) any (pkg/workflow/yaml.go:398) — generic recursive tree operations over already-parsed arbitrary YAML, idiomatic use of any.
• Default any (pkg/workflow/mcp_scripts_parser.go:70) — mirrors JSON-Schema's polymorphic default keyword, whose shape is dictated by a sibling typed Type MCPParamType field.
• Value any (pkg/console/console_types.go:50) — a reflect-style generic destination pointer, similar to flag.Value.
• The bulk of map[string]any usage across pkg/workflow's frontmatter/tools parsing and pkg/cli's codemod files — this is the standard, defensible Go pattern for ingesting loosely-typed YAML/JSON before conversion to typed structs; only the specific closed-shape fields above are called out as worth tightening.

---

Recommendations, prioritized

Priority 1 — pkg/cli/mcp_schema.go wire-type duplication (Clusters 3–6, 10)
Consolidate the 5 duplicated "wire" structs to reference the real types/named structs instead of hand-copying them. Highest risk of silent drift since these back user-facing schema docs. Estimated effort: 3-4 hours (mostly mechanical).

Priority 2 — Cross-package near-duplicates (Clusters 1, 2, 7, 8)
Share runtimeImportReference between pkg/parser/pkg/workflow; share/embed graderManifestEntry, MCPToolCall, JobInfo between the write side and the cache/read side in pkg/cli. Estimated effort: 2-3 hours each.

Priority 3 — Closed-shape any fields in frontmatter parsing
Introduce sum types with custom UnmarshalYAML for Engine, RunsOn/RunsOnSlim, Checkout, Imports, RawPermissions. These are documented today only in code comments; making them real types moves that contract into the compiler. Estimated effort: 4-6 hours (touches several call sites per field).

Priority 4 — Unit-bearing constants
Convert DefaultRateLimitWindow and workflowCompletionWaitTimeoutMinutes to time.Duration; add AuthMethod/LogLevel string types. Estimated effort: 1-2 hours.

Implementation Checklist

• Consolidate mcp_schema.go wire-twin structs onto the real types (Priority 1)
• Share runtimeImportReference between pkg/parser and pkg/workflow (Priority 2)
• Share/embed graderManifestEntry, MCPToolCall, JobInfo instead of re-declaring subsets (Priority 2)
• Add sum types + UnmarshalYAML for the closed-shape frontmatter fields (Priority 3)
• Convert unit-ambiguous constants to time.Duration / named enum string types (Priority 4)
• Re-run this analysis after changes to confirm clusters are resolved

Analysis Metadata

• Scope: pkg/**/*.go, excluding _test.go
• Type declarations sampled: ~1,480
• Duplicate clusters: 11 (10 actionable, 1 intentional build-tag split)
• Untyped-usage findings: ~23 (18 any usages + 5 constants), plus 16 raw interface{} hits (mostly testdata)
• Detection method: grep-based enumeration + targeted Read comparison, cross-checked with grep-based reference search (Serena's Go semantic reference tracing was unavailable - no Go toolchain in this sandbox)
• Analysis date: 2026-09-11

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 · 450.7 AIC · ⌖ 9.31 AIC · ⊞ 10K · ◷

• expires on Sep 12, 2026, 3:39 AM UTC-08:00

[github-actions[bot]]

This discussion was automatically closed because it expired on 2026-09-12T11:39:50.112Z.

Closed by Workflow