[typist] 🔤 Typist — Go Type Consistency Analysis (github/gh-aw)

[github-actions[bot]]

🔤 Typist — Go Type Consistency Analysis

Analysis of repository: github/gh-aw

Executive Summary

Good news first: this codebase is already in excellent shape on type consistency. I swept every non-test .go file under pkg/ — 1,061 files, ~633 struct/interface definitions — and found essentially zero copy-paste type duplication across packages. The only same-name type defined in two different packages is PolicyRule, and even that turns out to be two genuinely different concepts that happen to share a name (an intent-governance rule vs. a firewall ACL rule). Most repeated names I saw were either intentional WASM build-tag pairs (ProgressBar, SpinnerWrapper, RepositoryFeatures) or type X = pkg.X re-export aliases — both legitimate, neither a problem.

On the "untyped usage" front, the story is similarly healthy. Literal interface{} is effectively extinct (1 occurrence in the whole tree) — the code consistently uses any. And the ~2,300 map[string]any sites plus ~2,200 type assertions are overwhelmingly concentrated in YAML/JSON frontmatter and JSON-Schema handling, where generic decoding is the idiomatic Go choice, not a smell. The team already reaches for semantic types where it counts: EngineName, FeatureFlag, WorkflowID, LineLength, fs.FileMode, time.Duration. So rather than a big list of "fix your interface{}" nags, what follows is a short, high-signal set of small, safe, targeted improvements — a naming collision worth renaming, a handful of Type string/Status string fields whose own comments already spell out a fixed enum, a family of untyped network-port ints, and one genuine type inconsistency (an AI-credit budget stored as a string while its siblings are int64).

⚙️ Method note: Serena's LSP find_symbol/find_referencing_symbols calls repeatedly hit context deadline exceeded (60s) on this large repo, so semantic reference-tracing was not fully usable here. Findings below were instead extracted by pattern scan and verified by reading each actual definition — every file:line cited was opened and confirmed.

Full Analysis Report

Duplicated Type Definitions

Summary Statistics

• Total files analyzed: 1,061 (non-test .go under pkg/)
• Total type definitions scanned: ~633 (struct/interface, excluding aliases, WASM pairs, linter testdata)
• Genuine cross-package name collisions: 1 (PolicyRule, semantic-only)
• Structural near-duplicate clusters (same package, different names): 3
• Exact duplicates: 0
• Excluded as intentional: WASM build-tag pairs, type X = pkg.X re-export aliases, pkg/linters/*/testdata/ fixtures

---

Cluster 1: PolicyRule — same name, two packages, unrelated meaning

Type: Semantic collision (not a true duplicate)
Occurrences: 2
Impact: Low-Medium — no consolidation possible, but the shared name is a readability/import-confusion hazard.

Locations:

1. pkg/intent/policy.go:46 — intent-governance rule (ID, Scope, When PolicyCondition, Set ExecutionPolicy)
2. pkg/cli/firewall_policy.go:36 — firewall ACL rule (ID, Order, Action, ACLName, Protocol, Domains, Description)

Definition Comparison:

// pkg/intent/policy.go — pairs a match condition with a policy fragment
type PolicyRule struct {
    ID    string
    Scope string          // "organization" | "repository" | "intent" | "workflow"
    When  PolicyCondition
    Set   ExecutionPolicy
}

// pkg/cli/firewall_policy.go — a single firewall manifest rule
type PolicyRule struct {
    ID          string
    Order       int
    Action      string   // "allow" | "deny"
    ACLName     string
    Protocol    string   // "both" | "http" | "https"
    Domains     []string
    Description string
}

They share only ID string. Recommendation: do not merge — instead rename one for clarity, e.g. cli.FirewallPolicyRule (or cli.ACLRule) and/or intent.GovernancePolicyRule, so a reader/importer is never ambiguous about which PolicyRule is in scope. Effort: ~30 min. Benefit: eliminates import-alias confusion; documents intent.

---

Cluster 2: AccessLogSummary ↔ FirewallLogSummary (near-duplicate, pkg/cli)

Type: Near duplicate
Occurrences: 2 (both in pkg/cli/logs_report_firewall.go:11 and :21)
Impact: Medium — parallel structures that drift independently.

Both are per-run network aggregation summaries. ~5 fields are identical (TotalRequests, AllowedDomains [], BlockedDomains [], ByWorkflow map), and the counters differ only by the Count vs. Requests synonym (AllowedCount/BlockedCount vs. AllowedRequests/BlockedRequests). FirewallLogSummary adds RequestsByDomain.

Recommendation: extract a shared type NetworkRequestCounts struct { Total, Allowed, Blocked int } (or embed a common base), so the two summaries share the counter triple and only differ in their extras. Effort: 1-2 h. Benefit: one place to evolve counter semantics.

---

Cluster 3: DomainAnalysis ↔ FirewallAnalysis (near-duplicate, pkg/cli)

Type: Near duplicate
Occurrences: 2 — pkg/cli/access_log.go:34, pkg/cli/firewall_log.go:133
Impact: Medium.

Both embed DomainBuckets, carry the same TotalRequests + Allowed/Blocked counter pair (again Count vs. Requests synonym), expose AddMetrics(LogAnalysis), and both implement the LogAnalysis interface. FirewallAnalysis adds RequestsByDomain.

Recommendation: since both already satisfy LogAnalysis and embed DomainBuckets, promote the shared counter fields into DomainBuckets (or a new embedded RequestCounters) and keep only the deltas per type. Effort: 1-2 h.

---

Cluster 4: AccessLogEntry / FirewallLogEntry / AuditLogEntry (3-way semantic)

Type: Semantic duplicate
Occurrences: 3 — pkg/cli/access_log.go:20, pkg/cli/firewall_log.go:118, pkg/cli/firewall_policy.go:50
Impact: Low-Medium — different wire formats, so not trivially mergeable.

All three model one conceptual thing — a single proxy/firewall request log line — but parsed from three source formats (Squid access log, firewall log, audit.jsonl). They overlap on Timestamp, Method, Status, URL, Decision/client/host, but field types diverge (e.g. Timestamp is string in two, float64 in the third; Status is string vs. int). Recommendation: define one canonical RequestLogRecord and give each parser a toRequestLogRecord() mapper, rather than three near-parallel record types flowing through the reporting code. This is the largest of the four and best treated as a deliberate refactor, not a quick win. Effort: 3-5 h.

---

Untyped Usages

Summary Statistics

• Literal interface{} occurrences: 1 (pkg/workflow/safe_outputs_config_types.go) — the codebase standardized on any
• map[string]any occurrences: ~2,321 (dominant pattern; mostly legitimate YAML/JSON decode)
• Type assertions (.(T)): ~2,248 (concentrated in frontmatter/schema parsing)
• Verdict: the vast majority is idiomatic generic decoding, not a typing defect. Below are the genuine opportunities only.

Top files by any/interface usage (mostly legitimate frontmatter/schema code)

File	Count
pkg/workflow/workflow_builder.go	59
pkg/workflow/safe_outputs_handler_registry.go	54
pkg/workflow/safe_output_handlers.go	45
pkg/parser/schema_suggestions.go	44
pkg/workflow/tools_parser.go	44
pkg/parser/mcp.go	40
pkg/workflow/role_checks.go	38
pkg/workflow/tools.go	37
pkg/workflow/observability_otlp.go	36
pkg/workflow/compiler_custom_jobs.go	34

These are overwhelmingly map[string]any YAML/JSON frontmatter handling — leave as-is unless a full typed-frontmatter refactor is on the table.

---

Category 1: Type string / Status string fields that are really enums

Impact: Medium — the fixed value set already lives in a doc comment; promoting it to a named type makes the compiler enforce it and enables exhaustive handling.

Examples (each verified; the enumerated values are copied from the field's own comment):

• pkg/types/mcp.go:13 — BaseMCPServerConfig.Type string // stdio, http, local, remote → type MCPServerType string
• pkg/types/mcp.go:33 — MCPAuthConfig.Type string // currently only github-oidc → type MCPAuthType string
• pkg/types/input_definition.go:19 — InputDefinition.Type string // string, choice, boolean, number, environment → type InputType string
• pkg/cli/audit_cross_run.go:106,113 — OverallStatus string / Status string // allowed, denied, mixed, absent → type AuditStatus string
• pkg/parser/json_path_locator.go:235 — Type string // key or index → type PathNodeKind string
• pkg/intent/policy.go:48 / pkg/cli/firewall_policy.go:39,41 — Scope, Action, Protocol string fields with enumerated comments

Suggested shape:

type MCPServerType string
const (
    MCPServerStdio  MCPServerType = "stdio"
    MCPServerHTTP   MCPServerType = "http"
    MCPServerLocal  MCPServerType = "local"
    MCPServerRemote MCPServerType = "remote"
)

Benefit: compile-time checking, discoverable value set, safer switch handling.

---

Category 2: Untyped network-port constant family

Impact: Medium — a whole family of related ints that flow through validation as bare int.

Location: pkg/constants/constants.go:100-139 — DefaultMCPGatewayPort = 8080, DefaultMCPServerPort, DefaultMCPInspectorPort, DefaultCopilotSDKPort, MinNetworkPort, MaxNetworkPort, and the *LLMGatewayPort group.

// Suggested
type Port int
const (
    DefaultMCPGatewayPort Port = 8080
    MinNetworkPort        Port = 1
    MaxNetworkPort        Port = 65535
    // ...
)

Benefit: a func validatePort(p Port) signature can't be accidentally handed an arbitrary int; documents intent. Effort: ~1 h. Note: only worthwhile if the ports are passed around enough to benefit — low risk either way.

---

Category 3: Real type inconsistency — AI-credit budgets

Impact: Medium (correctness/consistency) — sibling constants disagree on type.

pkg/constants/constants.go:300-307:

const DefaultMaxAICredits          int64  = 1000   // typed
const DefaultDetectionMaxAICredits int64  = 400    // typed
const DefaultMaxDailyAICredits             = "5000" // <-- untyped STRING for the same concept!

DefaultMaxDailyAICredits is a numeric budget stored as an untyped string, while its two siblings are int64. Recommendation: make it int64 (or introduce type AICredits int64 for all three) and adjust the one call site that consumes it. Effort: ~30 min. Benefit: removes a string→int parse and a genuine inconsistency.

---

Category 4: Struct fields typed any — opportunities vs. legitimate

Most any fields are legitimately polymorphic (YAML defaults, JSON-RPC IDs, GitHub Actions with: maps). A few are worth tightening:

• pkg/workflow/step_types.go:28 — Step.ContinueOnError any // "can be bool or string expression" → a type BoolOrExpr string wrapper removes downstream assertions. (opportunity)
• pkg/workflow/tools_types.go:375 — PrivateToPublicFlows any \yaml:"-"`//yaml:"-"` means it's set in Go, never decoded — so a concrete type is knowable here. (opportunity)
• pkg/cli/logs_models.go:321 — RunID any / RunNumber any // GitHub run id/number are integers; any only tolerates JSON number-or-string → json.Number or a custom-unmarshal int64. (opportunity)

Left as legitimate (do not change): InputDefinition.Default any, Step.With map[string]any, JSON-RPC ID any (pkg/cli/gateway_logs_types.go:148), tools.raw map[string]any, and the recursive merge/equality helpers in pkg/parser/tools_merger.go.

---

Refactoring Recommendations

Priority 1: High-value, low-effort — enum types + fix the string budget

1. Convert the Type string/Status string/Action/Protocol fields in Category 1 to named string types with consts.
2. Fix DefaultMaxDailyAICredits to int64 to match its siblings (Category 3).

Effort: 2-3 h total. Impact: compile-time safety on real enums + removes a genuine inconsistency.

Priority 2: Rename the PolicyRule collision

Rename cli.PolicyRule → cli.FirewallPolicyRule (and/or intent.PolicyRule → intent.GovernancePolicyRule). Effort: ~30 min. Impact: kills the only cross-package name clash.

Priority 3: Consolidate the pkg/cli firewall/access-log near-duplicates

Extract a shared counter triple for Clusters 2 & 3; consider a canonical RequestLogRecord for Cluster 4 (larger, do deliberately). Effort: 4-8 h combined. Impact: fewer parallel structures that drift.

Explicitly NOT recommended

• Mass-replacing map[string]any in frontmatter/schema parsing — idiomatic and correct as-is.
• Typing every any field — several are genuinely polymorphic (YAML/JSON-RPC).

---

Implementation Checklist

• Add named enum types for the 6 Type/Status/Scope/Action/Protocol fields (Category 1)
• Change DefaultMaxDailyAICredits to int64 and update its call site (Category 3)
• Rename cli.PolicyRule to disambiguate from intent.PolicyRule (Cluster 1)
• (Optional) Introduce type Port int for the port constant family (Category 2)
• (Optional) Extract shared counter triple for *LogSummary / *Analysis (Clusters 2-3)
• (Larger) Canonical RequestLogRecord for the 3 log-entry types (Cluster 4)
• Run go build ./... + full test suite after each change

Analysis Metadata

• Total Go files analyzed: 1,061 (non-test, under pkg/)
• Total type definitions scanned: ~633
• Genuine duplicate clusters: 1 cross-package name collision + 3 same-package near-dups
• interface{} literals: 1 · map[string]any: ~2,321 · type assertions: ~2,248
• High-signal typing opportunities: 6 enum candidates, 1 port family, 1 string→int inconsistency, 3 any fields
• Detection method: pattern scan + direct definition reads (Serena LSP timed out on repo size)
• Analysis date: 2026-07-13

Generated by ✍️ Typist - Go Type Analysis · 562.6 AIC · ⌖ 18.3 AIC · ⊞ 8.6K · ◷

• expires on Jul 14, 2026, 4:34 AM UTC-08:00