[typist] 🔤 Typist — Go Type Consistency Analysis

[github-actions[bot]]

🔤 Typist - Go Type Consistency Analysis

Analysis of repository: github/gh-aw

Executive Summary

Analysed ~817 type definitions across the non-test Go files under pkg/. Name-based duplicates are rare (mostly intentional re-export aliases or _wasm.go build-tag variants), but several structural / semantic clusters carry real maintenance cost — notably the CLI run-summary types in pkg/cli/logs_models.go and three near-identical error types in pkg/workflow/workflow_errors.go.

Untyped usage is the dominant problem: 877 interface{}/any parameters/returns across 333 files, 1,821 map[string]any occurrences across 275 files, and 556 .(map[string]any) assertions. The largest concentrations sit in three hot spots — the safe-output handler registry, MCP renderer entry points, and the import field extractor — where the upstream structures are already typed. Replacing the any hops there would remove dozens of unsafe assertions.

Full Analysis Report

Duplicated Type Definitions

Summary Statistics

• Total types analysed: ~817
• Duplicate clusters found: 7
• Exact duplicates: 1
• Near duplicates: 4
• Semantic duplicates: 2

Cluster 1: Source-location structs (EXACT)

Impact: medium

Locations

1. pkg/console/console_types.go:4 — ErrorPosition
2. pkg/workflow/workflow_errors.go:33 — FieldLocation

type ErrorPosition struct { File string; Line int; Column int }
type FieldLocation struct { File string; Line int; Column int }

Recommendation: keep console.ErrorPosition as the canonical type and alias workflow.FieldLocation to it, or move both to pkg/types/sourceloc.go. A single type simplifies the parser → workflow → console error-formatting bridge.

Cluster 2: RunSummary vs DownloadResult (NEAR)

Locations

• pkg/cli/logs_models.go:203 — RunSummary
• pkg/cli/logs_models.go:229 — DownloadResult

Both share 14+ identical fields: Run, Metrics, AwContext, TaskDomain, BehaviorFingerprint, AgenticAssessments, AccessAnalysis, FirewallAnalysis, RedactedDomainsAnalysis, MissingTools, MissingData, Noops, MCPFailures, MCPToolUsage, TokenUsage, GitHubRateLimitUsage, JobDetails. DownloadResult adds Error, Skipped, Cached, LogsPath; RunSummary adds CLIVersion, RunID, ProcessedAt, PolicyAnalysis, ArtifactsList.

Recommendation: extract an embedded RunAnalysis struct that both compose. Every new analysis field currently has to be added in two places.

Impact: high — these are the central CLI data carriers.

Cluster 3: *Report types (NEAR)

Locations: pkg/cli/logs_models.go:111-146

type MissingToolReport  { Tool, Reason, Alternatives, Timestamp, WorkflowName string; RunID int64 }
type MissingDataReport  { DataType, Reason, Context, Alternatives, Timestamp, WorkflowName string; RunID int64 }
type MCPFailureReport   { ServerName, Status, Timestamp, WorkflowName string; RunID int64 }
type NoopReport         { Message, Timestamp, WorkflowName string; RunID int64 }

All four share Timestamp, WorkflowName, RunID and the first two also share Reason / Alternatives.

Recommendation: introduce ReportBase { Timestamp string; WorkflowName string; RunID int64 } and embed it.

Impact: medium — keeps JSON tags from drifting across parallel report types.

Cluster 4: *Summary aggregations (NEAR)

Locations: pkg/cli/logs_models.go:148-177 — MissingToolSummary and MissingDataSummary differ only in Tool vs DataType; Count, Workflows, WorkflowsDisplay, FirstReason, FirstReasonDisplay, RunIDs are identical (same console tags too).

Recommendation: parameterise via a single AggregatedReportSummary with a Subject field, or share a base.

Impact: medium — aggregation code is duplicated in lock-step.

Cluster 5: Workflow error structs (NEAR)

Locations: pkg/workflow/workflow_errors.go:40,127,183

type WorkflowValidationError { Field, Value, Reason, Suggestion string; Timestamp time.Time; File string; Line, Column int }
type OperationError          { Operation, EntityType, EntityID string; Cause error; Suggestion string; Timestamp time.Time }
type ConfigurationError      { ConfigKey, Value, Reason, Suggestion string; Timestamp time.Time }

All three carry Reason (or Cause), Suggestion, Timestamp and have near-identical Error() formatters.

Recommendation: factor a baseWorkflowError { Reason, Suggestion string; Timestamp time.Time } with a shared formatTail() helper.

Impact: medium — three near-identical Error() implementations live in the same file.

Cluster 6: Tool-call statistics (SEMANTIC)

Locations

• pkg/workflow/metrics.go:16 — ToolCallInfo { Name; CallCount; MaxInputSize, MaxOutputSize int; MaxDuration time.Duration }
• pkg/cli/audit_report.go:169 — MCPToolSummary { ServerName, ToolName; CallCount; TotalInputSize, TotalOutputSize, MaxInputSize, MaxOutputSize int; AvgDuration, MaxDuration string; ErrorCount int }

Both track per-tool call statistics; they differ in units (time.Duration vs pre-formatted string) and granularity. pkg/cli/logs_models.go:87 already re-exports ToolCallInfo = workflow.ToolCallInfo.

Recommendation: unify into a single ToolCallStats in pkg/types/ with internal time.Duration; format only at render time.

Impact: medium — duplicate aggregation paths in workflow/ and cli/.

Cluster 7: Validation results (SEMANTIC)

Locations: pkg/cli/compile_config.go:49 ValidationResult, pkg/workflow/permissions_validation.go:18 PermissionsValidationResult, pkg/parser/frontmatter_content.go:19 FrontmatterResult. Different shapes, but all represent “a checked thing plus errors/warnings.”

Recommendation: keep separate concrete types but introduce a tiny HasIssues interface (Errors() []..., HasErrors() bool) so CLI aggregation isn’t branching on concrete types.

Impact: low.

Intentionally excluded (NOT duplicates)

• ProgressBar, SpinnerWrapper, RepositoryFeatures — same name across *_wasm.go files; required for build-tag variants.
• ActionPin, ContainerPin, SHAResolver, SanitizeOptions, etc. — declared as type X = pkg.X re-export aliases.
• BaseMCPServerConfig in pkg/types/mcp.go is already embedded by parser.RegistryMCPServerConfig and workflow.MCPServerConfig — positive precedent for the consolidations above.
• LogParser (interface in pkg/workflow, generic func type in pkg/cli) — different concepts despite the shared name.

---

Untyped Usages

Summary Statistics

• interface{} / any in function signatures: 877 hits across 333 files
• map[string]any / map[string]interface{}: 1,821 occurrences across 275 files
• .(map[string]any) assertions: 556
• .(string) assertions: 612
• Untyped semantic constants flagged: ~17 hot spots in 13 files

Category 1: any parameters that always receive one concrete type (HIGH)

Example 1: GitHub tool accessors

• Locations: pkg/workflow/mcp_github_config.go:84,138,163,182,194,204,264,284,414,532 and pkg/workflow/mcp_renderer_github.go:17,110
• Current:

  func getGitHubType(githubTool any) string {
      if toolConfig, ok := githubTool.(map[string]any); ok { ... }
  }

• Actual shape: *GitHubToolConfig exists in pkg/workflow/tools_types.go and is the parsed form.
• Suggested: take *GitHubToolConfig directly; remove ~10 type assertions.
• Impact: high.

Example 2: MCP renderer entry points

• pkg/workflow/mcp_renderer_builtin.go:13 — RenderPlaywrightMCP(yaml, playwrightTool any) immediately calls parsePlaywrightTool(playwrightTool) to obtain *PlaywrightToolConfig. The caller already has the parsed struct.
• Suggested: RenderPlaywrightMCP(yaml, cfg *PlaywrightToolConfig).
• Impact: high (same pattern repeats across renderers).

Example 3: safeOutputHandlerDescriptor.NewConfig func() any

• pkg/workflow/safe_output_handlers.go — 41 entries of NewConfig: func() any { return &SomeConfig{} }. Each handler returns a distinct concrete *XxxConfig.
• Suggested: introduce a small SafeOutputConfig interface (or a generic Handler[T]) so the factory return type is checked at compile time.
• Impact: high — eliminates the assertion chain that follows every NewConfig() call.

Category 2: map[string]any in function signatures (MEDIUM-HIGH)

Example 4: Handler builder pattern

• pkg/workflow/compiler_safe_outputs_handlers.go — 46 handler entries each build a map[string]any field by field. Each handler has a known JSON schema.
• Suggested: typed handler-config structs marshalled to JSON at the boundary.
• Impact: medium-high (also enforces schema).

Example 5: MergeTools / MergeMCPServers / MergeFeatures / MergeEnv

• pkg/parser/imports.go:20,63,184,549,589 — all accept map[string]any on both sides. The top side is already typed (*Tools); imported side could deserialise into the same struct.
• Impact: medium.

Example 6: Frontmatter / import field extractor

• pkg/parser/import_field_extractor.go — 13 any signatures plus ~17 nested .(map[string]any) ladders (lines 301, 628-630, 724, 752, 843, 851, 921, 938, 969, 977, 989, 1058, 1085, 1096, 1114, 1153). The whole structure could deserialise into a typed ImportSchema via yaml.Unmarshal.
• Impact: high (worst assertion density in the codebase).

Category 3: Untyped constants with semantic meaning (MEDIUM)

Example 7: Rate-limit constants mix units

• pkg/constants/job_constants.go:220-221:

  const DefaultRateLimitMax = 5     // runs per time window
  const DefaultRateLimitWindow = 60 // minutes

• The same file uses time.Duration at lines 251-269 — the inconsistency invites unit bugs.
• Suggested: const DefaultRateLimitWindow = 60 * time.Minute.
• Impact: medium.

Example 8: Byte-size constants

• pkg/constants/constants.go:195 — const DefaultMCPGatewayPayloadSizeThreshold = 524288 (no unit; comment says bytes).
• pkg/cli/gateway_logs_types.go:15 — const maxScannerBufferSize = 1024 * 1024.
• Suggested: a Bytes typed alias, or at minimum the KiB * 1024 style throughout.
• Impact: low (cosmetic).

Example 9: Threshold percentages

• pkg/cli/audit_diff.go:21 — const volumeChangeThresholdPercent = 100.0 (untyped).
• pkg/cli/audit_cross_run.go:14,18 — *RateThreshold constants.
• Suggested: explicit float64 typed Percent alias.
• Impact: low.

Category 4: Type-assertion-heavy code (HIGH)

556 .(map[string]any) assertions and 612 .(string) assertions are concentrated in YAML/frontmatter parsers. Most assertion ladders trace back to an any parameter that could be a typed struct.

Hot files (highest interface{} / any density)

1. pkg/workflow/safe_output_handlers.go — 42 interface{} + 41 func() any factory entries
2. pkg/workflow/compiler_safe_outputs_handlers.go — 46 hits
3. pkg/workflow/role_checks.go — 20 hits
4. pkg/workflow/tools_parser.go — 15 (mostly legitimate boundary parsing)
5. pkg/parser/import_field_extractor.go — 13 signatures + the worst assertion density in the repo

Intentional any usage — leave alone

• parseGitHubTool(val any) etc. in pkg/workflow/tools_parser.go — accept YAML polymorphism (bool / object / array) at the parse boundary.
• pkg/typeutil/convert.go — generic numeric helpers.
• pkg/logger/logger.go Printf(..., args ...any) — matches fmt.Printf.
• MapToolConfig.GetAny in pkg/workflow/mcp_config_types.go — explicit untyped accessor by design.

---

Refactoring Recommendations

Priority 1: High — Replace any in handler/renderer entry points

Targets: pkg/workflow/mcp_github_config.go, pkg/workflow/mcp_renderer_*.go, pkg/workflow/safe_output_handlers.go.

Steps

1. Change accessor signatures to take the already-parsed concrete configs (*GitHubToolConfig, *PlaywrightToolConfig, ...).
2. For safeOutputHandlerDescriptor, define a SafeOutputConfig interface (or a generic descriptor) so NewConfig returns a typed value.
3. Delete the downstream .(map[string]any) assertion sites that the change makes obsolete.

Impact: removes ~50+ unsafe assertions; compile-time safety on the safe-outputs registry.

Priority 2: High — Consolidate RunSummary / DownloadResult

Target: pkg/cli/logs_models.go.

Steps

1. Extract a RunAnalysis struct holding the 14 shared fields.
2. Embed it in both RunSummary and DownloadResult.
3. Update producers/consumers; JSON tags survive embedding.

Impact: single source of truth for run-analysis fields; ends per-field double-edits.

Priority 3: Medium — Typed import schema

Target: pkg/parser/import_field_extractor.go.

Steps

1. Define a typed ImportSchema mirroring the YAML.
2. yaml.Unmarshal into it once at the entry point.
3. Replace the nested .(map[string]any) ladders with field access.

Impact: largest assertion-removal win in the codebase; safer error messages.

Priority 4: Medium — Shared error/report bases

Targets

• pkg/workflow/workflow_errors.go — baseWorkflowError { Reason, Suggestion string; Timestamp time.Time }.
• pkg/cli/logs_models.go — ReportBase { Timestamp string; WorkflowName string; RunID int64 } and AggregatedReportSummary.

Impact: removes cross-type drift; JSON tags stay aligned.

Priority 5: Low — Typed semantic constants

Targets: pkg/constants/job_constants.go (use time.Duration consistently); pkg/cli/audit_diff.go, pkg/cli/audit_cross_run.go (typed Percent); byte-size constants.

---

Implementation Checklist

• Replace any in MCP renderer entry points with concrete tool configs
• Introduce SafeOutputConfig interface for the safe-output handler registry
• Extract embedded RunAnalysis from RunSummary / DownloadResult
• Add ReportBase / AggregatedReportSummary and embed in pkg/cli/logs_models.go
• Factor baseWorkflowError and shared formatTail() in pkg/workflow/workflow_errors.go
• Unify ToolCallInfo / MCPToolSummary into a single ToolCallStats
• Define typed ImportSchema for pkg/parser/import_field_extractor.go
• Switch DefaultRateLimitWindow to time.Duration
• Run full test suite and go vet ./... after each batch

Analysis Metadata

• Total Go files analysed: 825 non-test files under pkg/
• Total type definitions: ~817
• Duplicate clusters: 7 (1 exact, 4 near, 2 semantic)
• Untyped usage locations: 877 signatures + 1,821 map[string]any + 556 + 612 assertions
• Detection method: ripgrep enumeration + targeted reads + semantic comparison
• Analysis date: 2026-05-22

Generated by ✍️ Typist - Go Type Analysis · ● 30.6M · ◷

• expires on May 23, 2026, 12:17 PM UTC

[github-actions[bot]]

This discussion was automatically closed because it expired on 2026-05-23T12:17:48.367Z.

Closed by Workflow