[typist] 🔤 Typist — Go Type Consistency Analysis

[github-actions[bot]]

Analysis of repository: github/gh-aw

Executive Summary

Good news first: this codebase is already in strong shape on type safety. Across ~290 non-test Go files and ~510 named type definitions in pkg/, most shared shapes are already consolidated through base-type embedding (BaseMCPServerConfig, BaseSafeOutputConfig, BaseEngine, FirewallSummaryBase, TokenCoreMetrics), and the code consistently uses semantic named types (ActionMode, EngineName, GitHubMCPMode, WorkflowID, LineLength) instead of bare strings and ints. Empty interface is effectively unused as a real type — the code has standardized on any, and the vast majority of any usage is legitimate map[string]any for arbitrary YAML/JSON frontmatter and template data.

So this is not a the code is a mess report — it is a short, high-signal punch list. The genuine opportunities cluster in two places: (1) a handful of near-duplicate report DTOs in pkg/cli where the logs pipeline and the audit pipeline independently grew parallel structs (for example JobStep and JobStepData are defined byte-for-byte identically in the same package), and (2) a handful of mode/policy string constants that should become named string types to match the pattern the codebase already uses elsewhere. Fixing the top few removes real type-assertion churn and one literally-duplicated definition.

Full Analysis Report

Duplicated Type Definitions

Summary Statistics

• Total type definitions analyzed: ~510
• Files analyzed (non-test, pkg/): ~290
• Duplicate clusters worth acting on: 6
• Exact duplicates: 1 (JobStep/JobStepData)
• Near duplicates: 3
• Semantic duplicates: 2
• Reviewed and confirmed intentional: build-tag _wasm.go variants, data-vs-display DTO projections, coincidental PolicyRule name collision

---

Cluster 1: JobStep / JobStepData — exact duplicate

Kind: Exact · Occurrences: 2 · Impact: High (zero-risk)

Locations: pkg/cli/logs_models.go:272 · pkg/cli/audit_report.go:127

Both declare three string fields — Name (json tag name), Status (json tag status,omitempty), Conclusion (json tag conclusion,omitempty) — in the same package cli. JobStepData is byte-identical to JobStep.

Recommendation: Delete JobStepData and use JobStep everywhere, or add type JobStepData = JobStep as a transitional alias. Effort: ~15 min · Benefit: single source of truth, no downside.

---

Cluster 2: JobInfo / JobData — near duplicate

Kind: Near · Occurrences: 2 · Impact: High

Locations: pkg/cli/logs_models.go:262 · pkg/cli/audit_report.go:118

JobInfo (logs) has Name/Status/Conclusion strings, StartedAt/CompletedAt time.Time, Steps []JobStep. JobData (audit) has Name/Status/Conclusion/Duration strings with console: display tags, Steps []JobStepData. Same concept: a workflow job with steps; the only real difference is raw timestamps vs a precomputed Duration string plus render tags.

Recommendation: Add the console: tags (and a derived Duration or render-time formatting) to JobInfo, then drop JobData. Effort: 1–2 h.

---

Cluster 3: MCPToolUsageData / MCPToolUsageSummary — near duplicate

Kind: Near · Occurrences: 2 · Impact: Medium

Locations: pkg/cli/audit_report.go:174 · pkg/cli/logs_models.go:188

Four shared fields (Summary, Servers, ToolCalls, FilteredEvents) are element-type identical; MCPToolUsageData additionally has an optional GuardPolicySummary pointer.

Recommendation: Consolidate to the superset (MCPToolUsageData); leave GuardPolicySummary optional and nil on the aggregated path. Effort: 1–2 h.

---

Cluster 4: ToolUsageSummary / ToolUsageInfo — near duplicate

Kind: Near · Occurrences: 2 · Impact: Medium

Locations: pkg/cli/logs_report_tools.go:13 · pkg/cli/audit_report.go:163

Both are per-tool aggregate stat rows overlapping on Name, a calls count, MaxOutputSize, MaxDuration; each adds a couple of unique fields (Runs/TotalCalls vs MaxInputSize/OutputSample).

Recommendation: Merge into one ToolUsage stat struct with the superset of fields and omitempty. Effort: 1–2 h.

---

Cluster 5: GitHub Action / workflow input definition — semantic duplicate

Kind: Semantic · Occurrences: 3 · Impact: Medium

Locations: pkg/types/input_definition.go:15 (InputDefinition) · pkg/cli/generate_action_metadata_command.go:46 (ActionInput) · pkg/actionpins/actionpins.go:31 (ActionYAMLInput)

All three model a GitHub Action/workflow input. ActionYAMLInput is a strict subset of ActionInput (minus Name); InputDefinition is the richest (Default any + Type + Options) and lives in shared pkg/types.

Recommendation: Have ActionYAMLInput/ActionInput share a common {Description, Required, Default} base. A full merge with types.InputDefinition is harder (Default any vs string), so treat as a base-embedding opportunity. Effort: 2–3 h.

---

Cluster 6: AuditComparisonIntDelta / AuditComparisonStringDelta — semantic duplicate

Kind: Semantic · Occurrences: 2 · Impact: Low (clean generics win)

Location: pkg/cli/audit_comparison.go:45 and :51. Both are {Before; After; Changed bool} parameterized only by value type (int vs string).

Recommendation: Replace with a single generic Delta[T comparable] holding Before, After, and a Changed bool. Effort: ~1 h.

---

Confirmed intentional — reviewed, no action needed

• PolicyRule (pkg/cli/firewall_policy.go:36 vs pkg/intent/policy.go:46) — same name, entirely different concepts (firewall ACL rule vs intent-governance policy). Coincidental collision.
• WASM build-tag variants — RepositoryFeatures, SpinnerWrapper, ProgressBar defined once for the normal build and once in _wasm.go stubs behind build tags. Correct platform separation.
• Data-vs-display DTO projections — OverviewData/OverviewDisplay, PolicyAnalysis/PolicySummaryDisplay, ModelTokenUsage/ModelTokenUsageRow. Each *Display/*Row is a deliberately narrowed, console:-tagged projection; merging would couple JSON schema to console output.

---

Untyped Usages

Summary Statistics

• Empty interface as a real type: ~0 in non-test code — standardized on any
• any occurrences: ~4600, but overwhelmingly intentional (map[string]any frontmatter, template data, decoded-node coercion helpers)
• Untyped mode/policy constants worth typing: 7
• Total high-signal locations flagged: ~15

The headline is not 4600 problems. It is ~15 realistic conversions, concentrated in pkg/workflow/tools_types.go, pkg/workflow/safe_outputs_config_types.go, pkg/workflow/safe_outputs_validation.go, pkg/workflow/mcp_renderer_types.go, pkg/cli/mcp_registry_types.go, and pkg/github/label_objective_mapping*.go.

---

Category 1: Untyped mode/policy constants → named string types (highest value, lowest risk)

The codebase already establishes this exact pattern with ActionMode, EngineName, and GitHubMCPMode.

Example 1 — safe-outputs URLs policy · pkg/workflow/safe_outputs_validation.go:13. Bare consts SafeOutputsURLsPolicyAllowedOnly = allowed-only and SafeOutputsURLsPolicyAllowedOrCodeRegion = allowed-or-code-region, validated in a switch against SafeOutputsConfig.URLs (plain string). Suggest a named SafeOutputsURLsPolicy string type with an IsValid() method and retype the field.

Example 2 — multi-label logic · pkg/github/label_objective_mapping_constants.go:136 (field ObjectiveMapping.MultiLabelLogic string). Consts max/sum/first. Suggest a named MultiLabelLogic string type.

Example 3 — MCP registry status / argument type · pkg/cli/mcp_registry_types.go:107. Consts active/inactive and positional/named. Suggest named ServerStatus and ArgumentType string types (use ArgumentType for Argument.Type).

Examples 4 and 5 — MCP / Playwright transport modes · pkg/workflow/tools_types.go:384 (Playwright mcp/cli) and :441 (MCP server stdio/http/remote/local). Suggest named PlaywrightMode and MCPServerMode string types — same idiom as the neighboring GitHubMCPMode.

---

Category 2: any struct fields with a known two-shape union → concrete types

ReportFailureAsIssue any · pkg/workflow/safe_outputs_config_types.go:105 — bool | templatable expression string | []string categories (already parsed into sibling typed fields). Suggest a tagged type or reuse *TemplatableBool + the typed category slices.

GitHubReposScope any · pkg/workflow/tools_types.go:302 (AllowedRepos, Repos) — a string (all/public) OR []any of repo patterns. Suggest a concrete struct with a Keyword string and Patterns []string, populated at parse time.

PrivateToPublicFlows any · pkg/workflow/tools_types.go:375 — the string allow OR []string of MCP server IDs. Suggest a struct with an AllowAll bool and ExemptServers []string.

Steps []any · pkg/workflow/safe_outputs_config_types.go:110 — each element is a GitHub Actions step (map[string]any); sibling fields already use []map[string]any. Suggest Steps []map[string]any.

---

Category 3: any in function params / map values → existing concrete types

Playwright renderer callback · pkg/workflow/mcp_renderer_types.go:36 — the RenderPlaywright callback takes playwrightTool as any. The concrete *PlaywrightToolConfig already exists; pass it instead of any.

Guard-policy maps · pkg/workflow/mcp_renderer_types.go (GuardPolicies map[string]any) and pkg/workflow/tools_types.go:448 — compiler-constructed payload with fixed keys built from strongly-typed GitHubToolConfig guard fields. Suggest a shared GuardPolicyConfig struct.

Reviewed and confirmed intentional any — do NOT change

• pkg/workflow/dependabot.go:557,584 — dependabotToAnySlice/dependabotToStringAnyMap are generic YAML-node coercion primitives.
• Samples []map[string]any, SecretMaskingConfig.Steps, WorkflowTrialResult map fields (pkg/cli/trial_types.go) — genuine arbitrary JSON/YAML containers.
• The bulk of the ~4600 any occurrences are map[string]any frontmatter/decoding — idiomatic, out of scope.

---

Refactoring Recommendations

Priority 1 — Critical, zero-risk: delete JobStepData, use JobStep (or a transitional alias). ~15 min.

Priority 2 — High: named string types for the mode/policy constants (SafeOutputsURLsPolicy, MultiLabelLogic, ServerStatus/ArgumentType, PlaywrightMode, MCPServerMode) with IsValid(). Matches the existing ActionMode/EngineName/GitHubMCPMode idiom; JSON/YAML decoding stays compatible. 3–4 h.

Priority 3 — High/Medium: unify the pkg/cli report DTOs (JobInfo/JobData, MCPToolUsage*, ToolUsage*) across the logs and audit pipelines. 4–6 h.

Priority 4 — Medium: replace known-shape any fields with concrete types (ReportFailureAsIssue, GitHubReposScope, PrivateToPublicFlows, Steps []any, GuardPolicies, RenderPlaywright). 4–6 h.

Priority 5 — Low: a generic Delta[T] for the audit deltas; a shared base for ActionInput/ActionYAMLInput. 2–3 h.

---

Implementation Checklist

• P1 Delete JobStepData; point everything at JobStep
• P2 Add named string types for the 5 mode/policy constant groups (+ IsValid())
• P3 Unify JobInfo/JobData, MCPToolUsage*, ToolUsage* across logs+audit
• P4 Replace known-shape any fields with concrete/tagged types
• P5 Introduce a generic Delta[T]; share an input-definition base
• Run go build over all packages and the full test suite after each priority
• Leave the confirmed-intentional cases untouched

---

Analysis Metadata

• Total Go files analyzed (non-test, pkg/): ~290 of 1102
• Total type definitions: ~510
• Actionable duplicate clusters: 6 (1 exact, 3 near, 2 semantic)
• Actionable untyped locations: ~15 (7 constants, ~8 fields/params/maps)
• Detection method: Serena semantic analysis + pattern matching, findings verified by reading definitions
• Analysis date: 2026-07-17

References: §29577956282

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

• expires on Jul 18, 2026, 4:10 AM UTC-08:00

[github-actions[bot]]

This discussion was automatically closed because it expired on 2026-07-18T12:10:58.032Z.

Closed by Workflow