[typist] Type Consistency Analysis: Codebase Already Well-Consolidated, 3 Minor Opportunities

[github-actions[bot]]

🔤 Typist — Go Type Consistency Analysis

Repository: github/gh-aw · 2026-06-04

Executive Summary

Good news first: this codebase is in unusually good shape on type consistency. I swept all 853 non-test .go files under pkg/ (excluding *_test.go and pkg/linters/*/testdata/ fixtures), covering 867 type declarations, and found zero genuine cross-package type-name collisions that need deduplicating. Every repeated type name is either a build-tag variant inside the same package (ProgressBar, SpinnerWrapper, RepositoryFeatures — native vs. _wasm.go stub) or already deliberately consolidated.

The interesting part is how the duplication was already removed: the team consistently reaches for Go's two idiomatic tools — type aliases (type X = pkg.Y) and struct embedding. The MCP config family embeds types.BaseMCPServerConfig; the safe-output *Config family embeds BaseSafeOutputConfig; InputDefinition, SanitizeOptions, LogMetrics, and the actionpins types are single-source structs re-exported via aliases. That's exactly what a "consolidate duplicates" refactor produces, so there's little left to do.

So this report is short on "fix this duplicate" and longer on a few small, high-confidence opportunities. Net impact is low-to-medium — polish, not rescue.

Full Analysis Report

Duplicated Type Definitions

Summary Statistics

• Non-test source files analyzed: 853 (excl. testdata/)
• Type declarations analyzed: 867
• Genuine exact cross-package duplicates: 0
• Same-name build-tag variants (not duplicates): 3
• Conceptual clusters already consolidated via alias/embedding: ~10
• Remaining opportunity: 1 (pkg/cli/audit_report.go)

Cluster 1: MCP stat structs — the one real opportunity

Near-duplicate, single package · 3 occurrences · Impact: Low–Medium

All in pkg/cli/audit_report.go:

• :170 type MCPToolSummary struct
• :184 type MCPToolCall struct
• :198 type MCPServerStats struct

All three repeat the cluster ServerName, input/output sizes, AvgDuration, ErrorCount. MCPToolSummary and MCPServerStats share ~70–80% of the smaller struct's fields.

Recommendation (with caveat): extract an embedded base (TotalInputSize, TotalOutputSize int, AvgDuration string, ErrorCount int). Caveat: the three carry different json: and console: struct tags (e.g. console:"header:Total Input,format:number"), so per-struct column headers must be verified before/after — that's likely why it wasn't already factored out. Effort 1–2 h · Risk Low (tag-sensitive).

Already-consolidated clusters (no action — listed so reviewers don't "re-fix")

View 10 already-consolidated clusters

Concept	Canonical	Shared via	#
MCP server config	types.BaseMCPServerConfig	embedding (workflow, parser)	3
Engine wrappers	BaseEngine/UniversalLLMConsumerEngine	embedding (8 engines)	~8
Close-entity config	CloseEntityConfig	alias (Issues/PRs/Discussions)	4
Issue-reporting config	IssueReportingConfig	alias (MissingData/Tool/ReportIncomplete)	4
Input definition	types.InputDefinition	alias (parser, workflow)	3
Log metrics	workflow.LogMetrics/ToolCallInfo	alias (cli)	4
Error position	console.ErrorPosition	alias workflow.FieldLocation	2
Sanitize options	stringutil.SanitizeOptions	alias (workflow)	2
Action pins	actionpins.* (5 types)	alias (workflow)	5
Add-comment config	AddCommentsConfig	alias AddCommentConfig	2

Pattern to keep: define once in the lowest-level package (pkg/types, pkg/console, pkg/stringutil), alias/embed upward.

Untyped Usages

Summary Statistics (non-test source)

• map[string]any / map[string]interface{}: ~2,062 across 332 files
• []any / []interface{}: ~386
• Polymorphic any struct fields (YAML unions): ~15
• Untyped numeric constants worth a semantic type: ~10 (network ports)

Category 1: map[string]any at the YAML/JSON boundary — mostly idiomatic, don't chase

The dominant pattern (~2,000 sites) is map[string]any from YAML frontmatter and JSON log parsing — ParseFrontmatterConfig, MergeTools, ExtractJSONTokenUsage. This is largely correct Go: at an arbitrary-YAML boundary there's no honest stronger type until you inspect the keys. The codebase already parses these maps into concrete structs early (FrontmatterConfig, EngineAuthConfig, RequestShape, TokenWeights) and centralizes scalar coercion in pkg/typeutil. No mass refactor. Only watch for maps passed through several layers before being typed.

Category 2: Polymorphic any struct fields (YAML unions) — semi-intentional

A few fields are any because the YAML genuinely accepts multiple shapes:

Field	Location	Accepts
On any	cli/status_command.go:35, cli/list_workflows_command.go:25	string/list/map
ContinueOnError any	workflow/step_types.go:28	bool or expr
Ports any	workflow/service_ports.go:50	int or list
DeduplicateByTitle any	workflow/create_issue.go:19	bool or int N
Default any	types/input_definition.go:18	string/number/bool

These are real union types, so any is defensible. A custom type with UnmarshalYAML would move the type switch into one place instead of scattering .(bool)/.(string) across call sites. Low priority — worth it only for fields read in 3+ places (On, ContinueOnError).

Category 3: Untyped network-port constants — clean, low-effort win

pkg/constants/constants.go declares ports as untyped constants (DefaultMCPGatewayPort = 8080, MinNetworkPort = 1, MaxNetworkPort = 65535, the four *LLMGatewayPort, ...). A type Port int would make the domain explicit and let the valid range be type-checked.

Caveat (Go idiom): untyped constants are deliberately flexible — 8080 assigns to int/int32/a field without a cast. type Port int means consumers passing these to int params or to strconv/fmt may need conversions. Judgement call: clarity + typed range vs. boundary casts. Effort 2–3 h · Impact Medium clarity.

Not flagged (correct as-is)

error; any in generic helpers (typeutil, console.RenderStruct(v any), sliceutil); map[string]any at parse boundaries; *_test.go and testdata/ (out of scope).

Recommendations (prioritized)

There is no Priority-1 "critical" item — the codebase lacks the duplicated-Config-everywhere problem this analysis usually hunts. The below is optional polish by value/effort.

1. Share a base for the MCP stat structs (pkg/cli/audit_report.go). Verify json/console tags render identically. Effort 1–2 h · Risk Low.
2. Add a semantic Port type for the pkg/constants port block; fix boundary conversions. Effort 2–3 h · Risk Low–Medium.
3. Custom UnmarshalYAML union types for the most-read fields (On, ContinueOnError) only. Effort 2–4 h each · Risk Medium.

Keep doing (no work item): "define once in the lowest package, alias/embed upward" and "parse map[string]any into a typed struct early."

Implementation Checklist

• P1 — Extract shared base for MCPToolSummary/MCPServerStats/MCPToolCall; verify rendering
• P2 — Introduce type Port int; retype port constants; fix conversions; run build
• P3 — Add UnmarshalYAML unions for On and ContinueOnError (optional)
• Run go test ./... and project linters after each change
• No action for the ~10 already-consolidated clusters

Analysis Metadata

• Files analyzed: 853 (pkg/, excl. testdata/) · Type declarations: 867
• Genuine cross-package duplicate clusters: 0 · Already-consolidated: ~10 · Remaining: 1
• map[string]any usages (non-test): ~2,062
• Method: duplicate-type-finder sub-agent + Serena activation + ripgrep cross-check
• Date: 2026-06-04

References: §26951325683

Generated by ✍️ Typist - Go Type Analysis · opus48 21.4M · ◷

• expires on Jun 5, 2026, 12:34 PM UTC

[github-actions[bot]]

Smoke beast was here. Tiny boots in dust. Test fire still warm.

Warning

Firewall blocked 6 domains

The following domains were blocked by the firewall during workflow execution:

• accounts.google.com
• android.clients.google.com
• clients2.google.com
• contentautofill.googleapis.com
• safebrowsingohttpgateway.googleapis.com
• www.google.com

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

network:
  allowed:
    - defaults
    - "accounts.google.com"
    - "android.clients.google.com"
    - "clients2.google.com"
    - "contentautofill.googleapis.com"
    - "safebrowsingohttpgateway.googleapis.com"
    - "www.google.com"

See Network Configuration for more information.

📰 BREAKING: Report filed by Smoke Copilot · gpt54 7.5M · ◷