[typist] Type Consistency Analysis: zero duplicate types, a few enum-typing opportunities

[github-actions[bot]]

🔤 Typist — Go Type Consistency Analysis

Repository: github/gh-aw · 880 non-test .go files under pkg/ (~682 type definitions) · 2026-06-05

Executive Summary

Good news first: gh-aw is already a remarkably type-disciplined codebase. I swept every non-test Go file under pkg/ hunting for copy-pasted types and weak interface{} plumbing — and the obvious problems simply aren't there. There are zero genuine cross-package duplicate struct definitions: every type name that shows up in two packages is a deliberate alias (type X = pkg.X), a build-tag (WASM vs native) variant, or one unrelated name collision. The MCP config types already share a base via embedding (types.BaseMCPServerConfig) rather than copy-paste.

The untyped story is similar. There is no interface{} debt in production code (the only hits live in linter test fixtures), and the ~3,300 any usages are overwhelmingly legitimate — JSON/YAML frontmatter parsing, recursive marshalling, and reflection registries that should stay dynamic. So instead of a long refactor list, the real opportunities are a tight, high-confidence set: a handful of untyped string-enum constants that deserve named types, plus a few fixed-schema map[string]any frontmatter fields that would read better as structs. Low-risk polish, not firefighting. Nicely done, team. 👏

Full Analysis Report

Duplicated Type Definitions

Genuine cross-package duplicate clusters: 0 (13 cross-directory name matches inspected — all benign).

• Type aliases (correct sharing, one canonical body): ActionPin/ActionPinsData/SHAResolver etc. (pkg/actionpins/actionpins.go → aliased in pkg/workflow/action_pins.go); InputDefinition (pkg/types/input_definition.go:15 → pkg/workflow/inputs.go:18, pkg/parser/import_processor.go:89); LogMetrics/ToolCallInfo (pkg/workflow/metrics.go → pkg/cli/logs_models.go); SanitizeOptions (pkg/stringutil/sanitize.go:53 → pkg/workflow/strings.go:97).
• Build-tag variants (same package, mutually exclusive native vs WASM): RepositoryFeatures, SpinnerWrapper (pkg/console/spinner.go:96 / spinner_wasm.go:10), ProgressBar (pkg/console/progress.go:31 / progress_wasm.go:7).
• Unrelated collision: LogParser — an interface in pkg/workflow/agentic_engine.go:182 vs a generic func type in pkg/cli/log_aggregation.go:37. No consolidation possible.
• MCP config family — already de-duplicated via embedding: pkg/types/mcp.go:6 BaseMCPServerConfig is embedded by pkg/parser/mcp.go:38 RegistryMCPServerConfig; the pkg/workflow and pkg/cli variants are domain-specific and don't copy its fields.

Out of scope (low value): pkg/cli has several same-package report/summary structs with similar shapes but distinct serialization (e.g. ToolUsageSummary, MCPToolUsageSummary, MCPToolUsageData). Same-package, cosmetic — leave as-is.

Untyped Usages

Counts: interface{} in production = 0 (5 hits only in pkg/linters/uncheckedtypeassertion/testdata/) · any ≈ 3,334 (mostly idiomatic) · map[string]any ≈ 1,986 (mostly correct frontmatter).

Category 1 — any in signatures: essentially nothing to fix

Almost every any parameter is genuinely polymorphic and should stay any: pkg/typeutil/convert.go:48,95,133 (accept int/float/string from JSON/YAML), pkg/parser/frontmatter_hash.go:46 (recursive canonicaliser), pkg/workflow/safe_output_handlers.go:17 (func() any reflection registry), pkg/logger/slog_adapter.go:86 (slog contract). The only mechanical any → concrete candidates are three sync.Map cast sites (pkg/parser/virtual_fs.go:75,96 → *FrontmatterResult; pkg/workflow/repository_features_validation.go:185,216 → *RepositoryFeatures) — all forced by the stdlib sync.Map API, so idiomatic as written. No action required.

Category 2 — map[string]any that could be structs: 5 fixed-schema frontmatter fields

Most map[string]any is correct dynamic frontmatter (the team annotates the dynamic ones, e.g. On/Jobs carry "too dynamic to type"). The exceptions in pkg/workflow/frontmatter_types.go map to fixed GitHub Actions schemas:

File:line	Field	Suggested struct
frontmatter_types.go:311	Concurrency	*ConcurrencyConfig{ Group string; CancelInProgress bool }
frontmatter_types.go:332	Container	*ContainerConfig{ Image string; Env map[string]string; Ports/Volumes []string; Options string }
frontmatter_types.go:333	Services	map[string]ContainerConfig
frontmatter_types.go:334	Cache	*CacheConfig{ Key string; Path/RestoreKeys []string }
frontmatter_types.go:331	Environment	*EnvironmentConfig{ Name string; URL string }

Leave as-is (correctly dynamic): On, Jobs, Features, Secrets, Experiments, ImportSchema, and var x map[string]any unmarshal targets.

Category 3 — Untyped constants carrying semantic meaning (the richest category)

A few closed string enums are declared as bare string:

// pkg/cli/mcp_registry_types.go:106-116  (BEFORE → AFTER)
const ( StatusActive = "active"; StatusInactive = "inactive" )   // bare strings
const ( ArgumentTypePositional = "positional"; ArgumentTypeNamed = "named" )
type Argument struct { Type string `json:"type"` /* line 71 */ }

type ServerStatus string
const ( StatusActive ServerStatus = "active"; StatusInactive ServerStatus = "inactive" )
type ArgumentType string
const ( ArgumentTypePositional ArgumentType = "positional"; ArgumentTypeNamed ArgumentType = "named" )
type Argument struct { Type ArgumentType `json:"type"` }   // bounded to the enum

File:line	Current	Suggested type
pkg/cli/mcp_registry_types.go:108-109	StatusActive/StatusInactive bare strings (compared at mcp_registry.go:135)	type ServerStatus string
pkg/cli/mcp_registry_types.go:114-115 + Argument.Type (:71)	bare strings + string field	type ArgumentType string
pkg/workflow/mcp_scripts_parser.go:64	MCPScriptsModeHTTP = "http"	type MCPScriptsMode string
pkg/workflow/mcp_scripts_parser.go:56	MCPScriptParam.Type string // string,number,boolean,array,object	type JSONSchemaType string + 5 consts

Optional (correct as ints, but typing prevents range/unit mix-ups): type Port uint16 for the network ports in pkg/constants/constants.go:105-135; time.Duration/TimeUnit for the mixed-unit caps in pkg/workflow/time_delta.go:486-498; self-documenting byte-size literals (512 * 1000, 1 << 20) in pkg/workflow/compiler.go:25-38.

🎯 Recommendations

• Priority 1 — type the closed string enums (~1-2 hrs, high value): ServerStatus + ArgumentType in pkg/cli/mcp_registry_types.go (retype Argument.Type, update comparison at mcp_registry.go:135); MCPScriptsMode + JSONSchemaType in pkg/workflow/mcp_scripts_parser.go. Benefit: compile-time validation, no stray values.
• Priority 2 — struct-ify fixed-schema frontmatter maps (~3-4 hrs): convert Concurrency/Container/Services/Cache/Environment in frontmatter_types.go; keep the dynamic fields as-is.
• Priority 3 — optional semantic numeric types: type Port uint16, normalized byte-size literals — only when touching nearby code.

Checklist

• P1: ServerStatus / ArgumentType named types (+ retype Argument.Type, update comparisons)
• P1: MCPScriptsMode / JSONSchemaType named types
• P2: struct-ify the 5 fixed-schema frontmatter fields
• P3 (optional): type Port uint16; normalize byte-size literals
• go build ./... + full test suite after each change

Detection: ripgrep extraction + per-type body inspection + Serena project context, manually verified.

References: §27014455894

Generated by ✍️ Typist - Go Type Analysis · 530.5 AIC · ◷

• expires on Jun 6, 2026, 12:33 PM UTC

[github-actions[bot]]

This discussion was automatically closed because it expired on 2026-06-06T12:33:19.888Z.

Closed by Workflow