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

[github-actions[bot]]

🔤 Typist - Go Type Consistency Analysis

Analysis of repository: github/gh-aw

Executive Summary

I swept every non-test .go file under pkg/ — roughly 1,128 source files and ~740 exported type declarations — hunting for two things: types we've defined more than once, and places where we've reached for any/interface{} when a specific type would be safer. The good news up front: this codebase is already in remarkably good shape. There are essentially zero accidental name collisions — every same-name pair turned out to be a deliberate type X = Y alias — and the team has clearly been doing the hard consolidation work already (shared base structs like AnalysisBase, AggregatedSummaryBase, DiffEntryBase, and typed sidecar fields on FrontmatterConfig). So this isn't a rescue mission; it's a polish pass.

That said, I did find 8 structural duplication clusters (distinct type names carrying identical or near-identical field sets) and a handful of genuinely improvable weak-typing spots. The single highest-value win is tiny: a few GitHub run-ID fields typed as any (because the API returns string-or-number) could become one small StringOrNumber type and delete a scattering of runtime type assertions. Most of the ~2,290 map[string]any usages sit at the YAML/JSON boundary and are correctly left generic — I am not recommending a bulk rewrite there. Fixing the handful of real items below buys cleaner code and removes a little copy-paste drift risk, with almost no correctness exposure.

Full Analysis Report

Duplicated Type Definitions

Summary Statistics

• Total exported type definitions analyzed: ~740 (in-scope; excludes _test.go, testdata/, and _wasm.go build-tag variants)
• Accidental name collisions: 0 (all same-name pairs are intentional type X = Y aliases)
• Structural duplicate clusters found: 8
• Exact duplicates: 2 clusters (Cluster 2, Cluster 8)
• Near duplicates: 3 clusters (Cluster 1, Cluster 3, Cluster 7)
• Semantic duplicates: 3 clusters (Cluster 4, Cluster 5, Cluster 6)

Note on non-findings: Same-name types like ActionPin, SanitizeOptions, InputDefinition, LogMetrics, ToolCallInfo, and the Close*Config trio are intentional aliases across packages, not duplicates. Build-tag variants (RepositoryFeatures, SpinnerWrapper, ProgressBar in _wasm.go files) are also intentional. None of these are reported as problems.

---

Cluster 1: Run-analysis carrier structs

Type: Near duplicate • Occurrences: 3 • Impact: High (largest copy-paste block in pkg/cli)

Locations:

1. pkg/cli/logs_models.go:97 — ProcessedRun
2. pkg/cli/logs_models.go:213 — RunSummary
3. pkg/cli/logs_models.go:239 — DownloadResult

All three share the same ~16-field analysis core (Run, AwContext, TaskDomain, BehaviorFingerprint, AgenticAssessments, AccessAnalysis, FirewallAnalysis, RedactedDomainsAnalysis, MissingTools, MissingData, Noops, MCPFailures, MCPToolUsage, TokenUsage, GitHubRateLimitUsage, JobDetails). They differ only in tails: ProcessedRun adds PolicyAnalysis; RunSummary adds PolicyAnalysis + Metrics + persistence fields; DownloadResult adds Metrics + result fields and omits PolicyAnalysis.

Recommendation: Extract an embedded RunAnalysis base holding the shared core and embed it in all three.

• Estimated effort: Medium (touch construction sites; reconcile JSON tags for RunSummary)
• Benefits: Removes the biggest duplicated field block in the package; eliminates drift risk when a new analysis dimension is added.

---

Cluster 2: Identical safe-output config structs

Type: Exact duplicate • Occurrences: 6 (two sub-groups) • Impact: High, easy win

Sub-group 2a — embed set BaseSafeOutputConfig + SafeOutputTargetConfig + SafeOutputFilterConfig + SafeOutputAllowBlockConfig, byte-identical:

1. pkg/workflow/add_labels.go:10 — AddLabelsConfig
2. pkg/workflow/remove_labels.go:10 — RemoveLabelsConfig
3. pkg/workflow/unassign_from_user.go:10 — UnassignFromUserConfig
4. pkg/workflow/assign_to_user.go:10 — AssignToUserConfig (same 4 embeds + one extra UnassignFirst *string → near)

Sub-group 2b — embed set BaseSafeOutputConfig + SafeOutputTargetConfig + SafeOutputFilterConfig, byte-identical:

1. pkg/workflow/dismiss_pull_request_review.go:8 — DismissPullRequestReviewConfig
2. pkg/workflow/mark_pull_request_as_ready_for_review.go:10 — MarkPullRequestAsReadyForReviewConfig
3. pkg/workflow/resolve_pr_review_thread.go:12 — ResolvePullRequestReviewThreadConfig

// Verified identical (add_labels.go and remove_labels.go):
type AddLabelsConfig struct {
    BaseSafeOutputConfig       `yaml:",inline"`
    SafeOutputTargetConfig     `yaml:",inline"`
    SafeOutputFilterConfig     `yaml:",inline"`
    SafeOutputAllowBlockConfig `yaml:",inline"`
}

Recommendation: Define a single named base per embed set (e.g. LabelsMutationConfig, SimpleTargetedConfig) and either embed it or alias to it — the existing type CloseIssuesConfig = CloseEntityConfig pattern (pkg/workflow/close_entity_helpers.go:264-266) is the precedent.

• Estimated effort: Low
• Caveat: These are semantically distinct YAML routes; prefer a shared-base embed over a pure alias so each config keeps its own identity for future divergence.

---

Cluster 3: Two base structs for the same "request counts + domains" concept

Type: Near/Exact duplicate • Occurrences: 2 • Impact: Medium

Locations:

1. pkg/cli/logs_report_firewall.go:17 — FirewallSummaryBase (TotalRequests, AllowedRequests, BlockedRequests, AllowedDomains, BlockedDomains)
2. pkg/cli/domain_buckets.go:41 — AnalysisBase (embeds DomainBuckets{AllowedDomains, BlockedDomains} + TotalRequests, AllowedRequests, BlockedRequests)

Same five logical fields with identical JSON tags (total_requests/allowed_requests/blocked_requests/allowed_domains/blocked_domains); only the console: tags differ.

Recommendation: Have FirewallSummaryBase embed AnalysisBase (or at least DomainBuckets), or fold both into one shared base.

• Estimated effort: Low–Medium (reconcile console: tag placement)
• Benefits: Single source of truth for the firewall-counts shape.

---

Cluster 4: Per-server MCP stats across pipeline stages

Type: Semantic duplicate • Occurrences: 3 • Impact: Medium

Locations:

1. pkg/cli/gateway_logs_types.go:85 — GatewayServerMetrics
2. pkg/cli/audit_report.go:211 — MCPServerStats
3. pkg/cli/audit_expanded.go:90 — MCPServerHealthDetail

Shared identity core: ServerName, RequestCount, ToolCall(Count), ErrorCount. They diverge intentionally as raw-aggregation vs report-schema vs display view (float ms vs formatted strings).

Recommendation: Optional shared MCPServerCore embed for the 4 common fields; keep stage-specific fields separate. Don't force full unification — the transform boundaries justify some separation.

• Estimated effort: Medium • Value: Moderate

---

Cluster 5: Per-tool MCP metrics (raw vs report)

Type: Semantic duplicate • Occurrences: 2 • Impact: Low

Locations:

1. pkg/cli/gateway_logs_types.go:97 — GatewayToolMetrics
2. pkg/cli/audit_report.go:183 — MCPToolSummary

Overlap: ToolName, CallCount, ErrorCount, TotalInputSize, TotalOutputSize, AvgDuration, MaxDuration. Duration type differs (float64 ms vs formatted string) — a deliberate raw→display transform.

Recommendation: Low value; leave as-is unless the raw/display split is being reworked anyway.

---

Cluster 6: Diff "summary" overview structs

Type: Semantic duplicate • Occurrences: 3 (all pkg/cli/audit_diff.go) • Impact: Medium

Locations:

1. pkg/cli/audit_diff.go:55 — FirewallDiffSummary (NewDomainCount, RemovedDomainCount, StatusChangeCount, VolumeChangeCount, HasAnomalies, AnomalyCount)
2. pkg/cli/audit_diff.go:249 — MCPToolsDiffSummary (NewToolCount, RemovedToolCount, ChangedToolCount, HasAnomalies, AnomalyCount)
3. pkg/cli/audit_diff.go:308 — ToolCallsDiffSummary (NewToolCount, RemovedToolCount, ChangedToolCount, Run1TotalCalls, Run2TotalCalls)

Same "counts of new/removed/changed + anomaly flags" shape with domain-specific field names.

Recommendation: A shared DiffCountsSummary{ New, Removed, Changed int; HasAnomalies bool; AnomalyCount int } embed.

• Estimated effort: Low–Medium (field renames touch JSON schema/consumers) • Value: Moderate

---

Cluster 7: Typed before/after delta pair (generics candidate)

Type: Near duplicate • Occurrences: 2 • Impact: Low, clean win

Locations:

1. pkg/cli/audit_comparison.go:45 — AuditComparisonIntDelta (Before int, After int, Changed bool)
2. pkg/cli/audit_comparison.go:51 — AuditComparisonStringDelta (Before string, After string, Changed bool)

Identical shape; only the value type differs — a textbook generics case.

type Delta[T comparable] struct {
    Before  T
    After   T
    Changed bool
}

• Estimated effort: Low

---

Cluster 8: Un-consolidated aggregated summary (already flagged in-code)

Type: Exact/Near duplicate • Occurrences: 3 • Impact: Low, easy win

The code's own comment at pkg/cli/logs_models.go:156 already flags this. AggregatedSummaryBase (:159) is embedded by MissingToolSummary (:169) and MissingDataSummary (:184), but MCPFailureSummary (:175) re-declares Count, Workflows, WorkflowsDisplay, RunIDs inline instead of embedding the base — it just omits the two FirstReason* fields and uses different console headers.

Recommendation: Make MCPFailureSummary embed AggregatedSummaryBase (with the FirstReason* fields omitempty), or split a smaller shared base for the truly common tail.

• Estimated effort: Low

---

Untyped Usages

Summary Statistics

• Literal interface{} usages (production code): rare — ~5 non-test occurrences; the codebase overwhelmingly uses the any alias.
• any in function parameters: ~648 across 213 files — dominated by map[string]any frontmatter walkers; mostly idiomatic.
• any return types: 62 total → ~19 genuine (43 are func() any { return &XxxConfig{} } factory closures).
• any struct fields: ~33 across 17 files — mostly union-shaped YAML fields.
• map[string]interface{} / map[string]any values: ~2,290 across ~380 files — almost entirely at the YAML/JSON boundary; largely acceptable.
• Untyped constants: hundreds of string consts (env-var/file names — correct) + ~20 numeric consts carrying real units (the candidates).

Context that matters: the team is already mitigating weak typing. FrontmatterConfig (pkg/workflow/frontmatter_types.go:300) documents each any field and carries typed sidecar fields (RuntimesTyped, PermissionsTyped, CheckoutConfigs, ExperimentConfigs) populated after parse. So the honest recommendation for most of these buckets is: keep doing what you're doing, incrementally. No bulk rewrite.

---

Category 1: any in function parameters — mostly acceptable

Impact: Low (the type genuinely isn't statically known)

Nearly all are map[string]any frontmatter walkers or raw any type-switch extractors operating on freshly-unmarshalled YAML (e.g. pkg/cli/outcome_eval_review.go:272-433, pkg/parser/mcp.go, pkg/workflow/engine.go). pkg/typeutil/convert.go is a deliberately-generic conversion utility. No bulk action recommended — the type isn't knowable at these call sites.

---

Category 2: any struct fields — one strong win

Impact: High for the run-ID case; Low for the rest

Most are union-shaped frontmatter fields where a comment already documents the allowed shapes and a TemplatableXxx or typed sidecar mitigates it (e.g. frontmatter_types.go:311 Engine any, :356 RunsOn any, :369 Imports any, :413 Checkout any; step_types.go:28 ContinueOnError any; types/input_definition.go:18 Default any). These are fine as-is.

The strongest single recommendation in this whole report — GitHub-API id fields typed as any purely because the API returns string-or-number:

• pkg/cli/logs_models.go:323-324 — RunID any / RunNumber any
• pkg/cli/gateway_logs_types.go:148,159 — ID any
• pkg/cli/mcp_tools_privileged.go:299-300 — RunID any / RunIDOrURL any

A dedicated type removes the scattered ad-hoc assertions:

// StringOrNumber accepts JSON string-or-number id fields (GitHub API) and
// normalizes access, replacing runtime any-assertions with one code path.
type StringOrNumber struct{ s string }

func (v *StringOrNumber) UnmarshalJSON(b []byte) error {
    b = bytes.TrimSpace(b)
    if len(b) > 0 && b[0] == '"' {
        return json.Unmarshal(b, &v.s)
    }
    v.s = string(b) // numeric literal
    return nil
}
func (v StringOrNumber) String() string { return strings.Trim(v.s, `"`) }

• Benefits: Compile-time clarity, one canonical accessor, fewer .(string)/.(float64) assertions that can panic.
• Estimated effort: Low

Secondary: ContinueOnError any (step_types.go:28) could become a TemplatableBool, mirroring the existing TemplatableInt32 / TemplatableBoolOrInt in pkg/workflow/templatables.go.

---

Category 3: map[string]any values — leave the boundary alone

Impact: Low (bulk); Medium (a few fixed-key-set maps)

The ~2,290 occurrences are almost entirely YAML frontmatter, JSON parsing, codemod tree-rewriting, and GitHub API responses. Heaviest files: pkg/workflow/safe_outputs_handler_registry.go, pkg/workflow/workflow_builder.go, pkg/workflow/observability_otlp.go, pkg/workflow/tools.go. The team already demonstrates the preferred migration (FrontmatterConfig.Tools *ToolsConfig, SafeOutputs *SafeOutputsConfig, Network *NetworkPermissions replaced former maps).

Recommendation: Continue the case-by-case typed-struct migration only for maps with a fixed, known key set (e.g. DevcontainerFeatures merges in pkg/cli/devcontainer.go:314). Do not attempt a bulk change — most of these are legitimately dynamic.

---

Category 4: Untyped constants — nice-to-have semantic types

Impact: Low (documentation / misuse-prevention, not correctness)

Most pkg/constants/ consts are env-var names and filenames as bare string — correct. The numeric ones carrying real units are the candidates:

• Ports (pkg/constants/constants.go:105-135): DefaultMCPGatewayPort = 8080, MinNetworkPort = 1, MaxNetworkPort = 65535, ClaudeLLMGatewayPort = 10000.
• Counts/thresholds: engine_constants.go:410 DefaultMaxToolDenials = 5; logs_models.go:28 BatchSize = 100, :44 RateLimitThreshold = 10.
• Byte sizes: pkg/workflow/compiler.go:25 MaxLockFileSize = 512000, :30 MaxExpressionSize = 21000, :34 MaxPromptChunkSize = 20000.
• Minutes: pkg/workflow/time_delta.go:501 MaxTimeDeltaMinutes = 525600.

type Port int      // constrain to 1..65535; used by *GatewayPort, *ServerPort
type Bytes int     // MaxLockFileSize, MaxExpressionSize, MaxPromptChunkSize
type Minutes int   // MaxTimeDeltaMinutes, timeout-minutes fields

• Benefits: Prevents unit confusion, self-documenting APIs. • Estimated effort: Low • Priority: Low

---

🎯 What Should We Do About This?

Prioritized by impact-vs-effort. The top two are quick, low-risk wins:

Priority 1: Quick wins (Low effort, high clarity)

• Cluster 2 — collapse the 6 identical safe-output config structs onto shared named bases (embed, don't pure-alias).
• Cluster 8 — make MCPFailureSummary embed AggregatedSummaryBase (the code already has a TODO comment for this).
• Cluster 7 — replace the two AuditComparison*Delta structs with a generic Delta[T comparable].

Priority 2: Highest type-safety win (Low effort)

• Introduce a StringOrNumber type for GitHub run-ID fields (logs_models.go:323-324, gateway_logs_types.go:148,159, mcp_tools_privileged.go:299-300) and delete the ad-hoc assertions.

Priority 3: Structural consolidation (Medium effort)

• Cluster 1 — extract an embedded RunAnalysis base for ProcessedRun/RunSummary/DownloadResult.
• Cluster 3 — unify FirewallSummaryBase and AnalysisBase.
• Cluster 6 — shared DiffCountsSummary embed.

Priority 4: Optional / leave-as-is

• Clusters 4 & 5 (semantic; transform boundaries justify separation).
• Semantic const types (Port, Bytes, Minutes) — nice-to-have.
• Do NOT bulk-convert the ~2,290 map[string]any values or the frontmatter union any fields — they live at the YAML/JSON boundary and are already documented and mitigated.

---

Implementation Checklist

• Collapse Cluster 2 safe-output configs onto shared bases
• Fix Cluster 8 (MCPFailureSummary embeds AggregatedSummaryBase)
• Genericize Cluster 7 deltas → Delta[T comparable]
• Add StringOrNumber for GitHub run-ID fields; remove ad-hoc assertions
• Extract RunAnalysis base (Cluster 1)
• Unify firewall-counts base (Cluster 3)
• Run full test suite after each change

Analysis Metadata

• Total Go source files (pkg/, non-test): ~1,128
• Total exported type definitions analyzed: ~740
• Structural duplicate clusters: 8 (2 exact, 3 near, 3 semantic)
• Accidental name collisions: 0
• Literal interface{} in production: ~5
• map[string]any values: ~2,290 (mostly acceptable YAML/JSON boundary)
• Detection method: Serena semantic analysis + ripgrep pattern matching + manual verification of every reported cluster
• Analysis date: 2026-07-22

Generated by ✍️ Typist - Go Type Analysis · age00 606.8 AIC · ⌖ 36.3 AIC · ⊞ 8.6K · ◷

• expires on Jul 23, 2026, 4:11 AM UTC-08:00

[github-actions[bot]]

This discussion has been marked as outdated by Typist - Go Type Analysis.

A newer discussion is available at Discussion #47564.