Typist: Go Type Consistency Analysis — github/gh-aw

[github-actions[bot]]

Analyzed 614 non-test Go files across pkg/ for duplicated type definitions and untyped usages. The codebase demonstrates strong type-safety awareness — a pkg/types/ shared package exists, FrontmatterConfig provides structured YAML parsing, and EngineName/LineLength custom types are used throughout. The analysis surfaces 3 duplicate clusters (all with clear rationale) and 7 concrete untyped usage opportunities, quantified below.

Full Analysis Report

Duplicated Type Definitions

Summary Statistics

• Total type definitions analyzed: 578
• Duplicate clusters found: 3
• Build-tag platform stubs (intentional): 2 clusters
• Name collision — different abstractions: 1 cluster
• Already-resolved shared-base pattern: 1 (MCPServerConfig)

---

Cluster 1: WASM Build-Tag Stubs (Intentional — No Action Needed)

Types: SpinnerWrapper, ProgressBar, RepositoryFeatures
Pattern: Idiomatic Go platform-specific implementation via build tags

Type	Primary implementation	WASM stub
SpinnerWrapper	pkg/console/spinner.go:96	pkg/console/spinner_wasm.go:10
ProgressBar	pkg/console/progress.go:31	pkg/console/progress_wasm.go:7
RepositoryFeatures	pkg/workflow/repository_features_validation.go:57	pkg/workflow/repository_features_validation_wasm.go:5

The WASM stubs carry //go:build js || wasm and provide no-op implementations. This is the correct Go pattern for platform-specific behaviour. No refactoring needed.

---

Cluster 2: MCPServerConfig — Shared-Base Pattern (Already Resolved ✓)

Types: parser.MCPServerConfig, workflow.MCPServerConfig
Status: ✅ Already uses types.BaseMCPServerConfig embedding

Both types embed types.BaseMCPServerConfig from pkg/types/mcp.go and add domain-specific fields:

// pkg/parser/mcp.go:35 — parser-specific fields
type MCPServerConfig struct {
    types.BaseMCPServerConfig
    Name      string   // Server name/identifier
    Registry  string   // URI from registry
    ProxyArgs []string // Custom proxy arguments
    Allowed   []string // Allowed tools
}

// pkg/workflow/tools_types.go:493 — workflow-specific fields
type MCPServerConfig struct {
    types.BaseMCPServerConfig
    Mode          string         // stdio/http/remote/local
    Toolsets      []string       // Toolsets to enable
    GuardPolicies map[string]any // Access control policies
    CustomFields  map[string]any `yaml:",inline"`
}

The shared BaseMCPServerConfig correctly captures common fields. No further action needed.

---

Cluster 3: Name Collisions — Different Abstractions (Rename Consideration)

Types: FileTracker, LogParser, LogMetrics appearing in both pkg/cli and pkg/workflow

Name	pkg/cli	pkg/workflow	Relationship
FileTracker	Concrete struct — git-staging tracker (file_tracker.go:18)	Interface — compiler file creation tracking (compiler_types.go:51)	Different concepts, same name
LogParser	Generic function type func(logPath string, verbose bool) (T, error) (log_aggregation.go:30)	Interface with broader contract (agentic_engine.go:169)	Different abstractions
LogMetrics	Type alias = workflow.LogMetrics (logs_models.go:67)	Actual struct (metrics.go:24)	Intentional re-export alias ✓

Recommendation for FileTracker: The interface in pkg/workflow/compiler_types.go is narrow (only TrackCreated). Renaming it to FileCreationTracker would avoid confusion with the full-featured CLI struct and clarify the interface's narrower contract.

Recommendation for LogParser: The CLI generic function type and workflow interface serve different call sites. Renaming the workflow interface to LogAnalyzer or LogProcessor would remove the naming ambiguity.

• Estimated effort: 1 hour each (two renames, update call sites)
• Benefits: Eliminates reader confusion, clearer mental model

---

Untyped Usages

Summary Statistics

• interface{} usages: 0 (none found — codebase uses modern any alias exclusively ✓)
• any struct fields: 8 locations
• map[string]any struct fields (non-frontmatter): 6 locations
• Untyped numeric constants: 4 locations
• Total untyped locations: 18

---

Category 1: any-Typed Struct Fields

Example 1: AwInfo.RunID and AwInfo.RunNumber

• Location: pkg/cli/logs_models.go:275-276
• Current definition:

  type AwInfo struct {
      // ...
      RunID      any    `json:"run_id,omitempty"`
      RunNumber  any    `json:"run_number,omitempty"`
  }

• Context: AwInfo represents aw_info.json files. The any type accommodates GitHub Actions sending either a string or integer for these fields across different versions. All other RunID fields in the codebase are int64.
• Suggested fix: Use json.Number which safely represents both string-form and numeric JSON values without type assertion:

  import "encoding/json"
  
  type AwInfo struct {
      // ...
      RunID      json.Number `json:"run_id,omitempty"`
      RunNumber  json.Number `json:"run_number,omitempty"`
  }

• Benefits: Eliminates silent any marshaling, callers can use .Int64() or .String() explicitly, no more silent type assertion failures

Example 2: WorkflowListItem.On and WorkflowStatus.On

• Locations:
  • pkg/cli/list_workflows_command.go:25 — On any
  • pkg/cli/status_command.go:31 — On any
• Current definitions:

  // list_workflows_command.go
  type WorkflowListItem struct {
      Workflow string   `json:"workflow"`
      On       any      `json:"on,omitempty" console:"-"`
  }
  
  // status_command.go
  type WorkflowStatus struct {
      Workflow string   `json:"workflow"`
      On       any      `json:"on,omitempty" console:"-"`
  }

• Context: The GitHub Actions on: field is intentionally polymorphic (string, []string, or map[string]any). The any type is accurate for the raw YAML value. However, both structs share this identical polymorphic field with console:"-" (hidden from output).
• Observation: Both structs mark On as console:"-" — it is never displayed, only used for programmatic filtering (labelsField lookup at list_workflows_command.go:183). Consider whether this field needs to be present in the serialized struct at all, or whether a helper method for label extraction would be cleaner.

Example 3: JSON-RPC ID Fields

• Locations: pkg/cli/gateway_logs.go:140,151
• Current definition:

  type rpcRequestPayload struct {
      Method string          `json:"method"`
      ID     any             `json:"id"`
      Params json.RawMessage `json:"params"`
  }

• Context: The JSON-RPC 2.0 spec requires id to be a string, number, or null — any is correct here. No action needed.

Example 4: WorkflowStep.ContinueOnError

• Location: pkg/workflow/step_types.go:25
• Current: ContinueOnError any — GitHub Actions allows this to be a boolean literal OR a string expression ($\{\{ ... }}).
• Context: Intentional polymorphism matching the GitHub Actions schema. No action needed.

---

Category 2: map[string]any Struct Fields

Example 1: FrontmatterConfig Legacy Fields

• Location: pkg/workflow/frontmatter_types.go:154-157
• Current definition:

  type FrontmatterConfig struct {
      // ...
      MCPServers    map[string]any  `json:"mcp-servers,omitempty"` // Legacy field, use Tools instead
      Runtimes      map[string]any  `json:"runtimes,omitempty"`    // Deprecated: use RuntimesTyped
      Jobs          map[string]any  `json:"jobs,omitempty"`        // Custom workflow jobs (too dynamic to type)
  }

• Context: MCPServers and Runtimes are deprecated — documentation says to use Tools and RuntimesTyped instead. These fields remain for backward compatibility. Jobs is documented as "too dynamic to type".
• Recommendation: Add deprecation tracking. For MCPServers specifically, since parser.MCPServerConfig and workflow.MCPServerConfig already exist, typing this as map[string]workflow.MCPServerConfig could be feasible but would require migration logic. Low priority given deprecation path.

Example 2: Trial Result Fields

• Location: pkg/cli/trial_command.go:32-35
• Current:

  type TrialResult struct {
      SafeOutputs         map[string]any `json:"safe_outputs"`
      AgenticRunInfo      map[string]any `json:"agentic_run_info,omitempty"`
      AdditionalArtifacts map[string]any `json:"additional_artifacts,omitempty"`
  }

• Context: TrialResult is a JSON output capturing dynamic workflow execution data. The map[string]any accurately represents dynamically-shaped output. Acceptable as-is, but a typed SafeOutputs struct would improve programmatic use.

Example 3: MapToolConfig

• Location: pkg/workflow/mcp_config_types.go:66
• Current: type MapToolConfig map[string]any
• Context: Named type alias provides some semantic clarity. Comment in tools_types.go:13 notes this is a "structured alternative to the pervasive map[string]any pattern" — the documentation acknowledges the trade-off. Acceptable.

---

Category 3: Untyped Numeric Constants

• Location: pkg/constants/constants.go
• Current:

  const DefaultRateLimitMax    = 5     // Default maximum runs per time window
  const DefaultRateLimitWindow = 60    // Default time window in minutes (1 hour)
  const DefaultMCPGatewayPayloadSizeThreshold = 524288  // bytes
  const MaxSymlinkDepth = 5

• Issue: DefaultRateLimitWindow = 60 — the comment says "minutes" but the value is unitless. DefaultMCPGatewayPayloadSizeThreshold = 524288 lacks unit context in the name.
• Suggested fix:

  // Option A: type aliases for semantic clarity
  type RateLimitCount int
  type WindowMinutes int
  type ByteSize int
  
  const DefaultRateLimitMax    RateLimitCount = 5
  const DefaultRateLimitWindow WindowMinutes  = 60
  const DefaultMCPGatewayPayloadSizeThreshold ByteSize = 524288 // 512KB
  
  // Option B (simpler): rename to embed units
  const DefaultRateLimitWindowMinutes = 60
  const DefaultMCPGatewayPayloadSizeBytes = 524288

• Estimated effort: 30 minutes
• Benefits: Eliminates unit confusion (minutes vs seconds), prevents accidental cross-assignment

---

Refactoring Recommendations

Priority 1: Medium — json.Number for AwInfo.RunID/RunNumber

Recommendation: Replace any with json.Number in AwInfo

Steps:

1. Change field types in pkg/cli/logs_models.go:275-276
2. Update any callers that type-assert on these fields
3. Run tests

Estimated effort: 1-2 hours
Impact: Medium — improves serialization safety for aw_info.json parsing

---

Priority 2: Low — Rename Ambiguous Interface/Type Names

Recommendation: Rename workflow.FileTracker interface to FileCreationTracker

Steps:

1. Rename interface in pkg/workflow/compiler_types.go:51
2. Update all references (the concrete cli.FileTracker struct is unaffected)
3. Run tests

Estimated effort: 30-60 minutes
Impact: Low — code clarity improvement, no behavioral change

---

Priority 3: Low — Add Units to Numeric Constants

Recommendation: Rename DefaultRateLimitWindow to DefaultRateLimitWindowMinutes

Steps:

1. Update constant name in pkg/constants/constants.go:766
2. Update all references
3. Run tests

Estimated effort: 30 minutes
Impact: Low — prevents unit confusion in future development

---

Implementation Checklist

• Replace AwInfo.RunID/RunNumber any with json.Number (pkg/cli/logs_models.go)
• Rename workflow.FileTracker interface → FileCreationTracker for clarity
• Optionally rename LogParser interface in pkg/workflow to avoid collision with CLI generic type
• Rename DefaultRateLimitWindow → DefaultRateLimitWindowMinutes in constants
• Consider renaming DefaultMCPGatewayPayloadSizeThreshold to include unit (Bytes)
• Review WorkflowListItem.On any — if only used for label extraction, consider replacing with a helper method

---

Analysis Metadata

Metric	Value
Total non-test Go files analyzed	614
Total type definitions	578
Duplicate clusters	3 (2 intentional WASM stubs, 1 name collision)
interface{} usages	0
any struct field locations	8
map[string]any struct fields	6
Untyped numeric constants	4
Detection method	Serena LSP + grep pattern matching
Analysis date	2026-03-25

Recommendations

The codebase is in good shape overall — it already uses pkg/types/mcp.go for shared types, FrontmatterConfig for structured YAML, and typed constants for most semantic values. The highest-value change is replacing AwInfo.RunID/RunNumber any with json.Number to improve JSON marshaling safety. Renaming the workflow.FileTracker interface and ambiguous LogParser type would reduce reader confusion at low cost.

References:

• §23538262165

AI generated by Typist - Go Type Analysis · history

• expires on Mar 26, 2026, 11:24 AM UTC

[github-actions[bot]]

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

A newer discussion is available at Discussion #23095.