Typist - Go Type Consistency Analysis

[github-actions[bot]]

Analysis of repository: github/gh-aw · Workflow run: §22221833584

Executive Summary

546 non-test Go source files across 18 packages were analyzed for type consistency. The codebase demonstrates strong typing discipline overall — pkg/constants makes excellent use of named string/int types (ModelName, Version, URL, FeatureFlag, etc.), and the pkg/types/mcp.go shared base type pattern already eliminates one major duplication. The primary findings are: (1) 5 residual interface{} uses that should be updated to the modern any alias for consistency, (2) several any-typed struct fields that appear in parallel locations representing the same semantic concept, and (3) build-tag-separated struct duplicates that are intentional but worth annotating.

The codebase's pervasive use of map[string]any in YAML/config processing is largely idiomatic given the dynamic nature of the data (YAML frontmatter, trigger maps, GitHub Actions step configs), and most usages are intentional. Refactoring recommendations are ordered by impact and effort.

Full Analysis Report

Duplicated Type Definitions

Summary Statistics

• Total non-test Go files analyzed: 546
• Total struct types: 428
• Total interface types: 13
• Total named/alias types: 51
• Duplicate clusters found: 4
• Exact build-tag duplicates: 3 (intentional, platform-specific)
• Cross-package semantic duplicates: 1 (already partially resolved via BaseMCPServerConfig)

---

Cluster 1: RepositoryFeatures (Build-Tag Duplicate)

Type: Exact duplicate separated by //go:build js || wasm
Impact: Low — intentional platform split, but struct is undocumented as shared

Locations:

1. pkg/workflow/repository_features_validation.go:58
2. pkg/workflow/repository_features_validation_wasm.go:5

Definition Comparison:

// Both files define the exact same struct:
type RepositoryFeatures struct {
    HasDiscussions bool
    HasIssues      bool
}

The WASM version provides a no-op stub (validateRepositoryFeatures returns nil) while the non-WASM version has the full sync.Map-cached implementation. The struct itself is identical.

Recommendation:

• The struct definition could be extracted to a separate non-build-tagged file (e.g., repository_features_types.go) to make the shared contract explicit.
• Add a comment linking the two build-tag files together.
• Effort: Low (15 min) — move struct to shared file, adjust imports.

---

Cluster 2: ProgressBar (Build-Tag Duplicate)

Type: Near-duplicate separated by //go:build js || wasm
Impact: Low — intentional WASM stub, different field sets

Locations:

1. pkg/console/progress.go:30
2. pkg/console/progress_wasm.go:7

Definition Comparison:

// Non-WASM (full implementation):
type ProgressBar struct {
    progress      progress.Model  // TUI dependency - absent in WASM
    total         int64
    current       int64
    indeterminate bool
    updateCount   int64
}

// WASM (stub — no TUI dependency):
type ProgressBar struct {
    total         int64
    current       int64
    indeterminate bool
    updateCount   int64
}

Recommendation:

• This is a deliberate and acceptable pattern. A comment in each file cross-referencing the other would improve maintainability.
• Effort: Negligible (comments only).

---

Cluster 3: SpinnerWrapper (Build-Tag Duplicate)

Type: Structural duplicate separated by //go:build js || wasm
Impact: Low — intentional WASM no-op

Locations:

1. pkg/console/spinner.go:93
2. pkg/console/spinner_wasm.go:10

Definition Comparison:

// Non-WASM (full Bubble Tea implementation):
type SpinnerWrapper struct {
    program *tea.Program
    enabled bool
    running bool
    mu      sync.Mutex
    wg      sync.WaitGroup
}

// WASM (no-op stub):
type SpinnerWrapper struct {
    enabled bool
}

Recommendation: Same as ProgressBar — cross-reference comments only. This is idiomatic Go.

---

Cluster 4: MCPServerConfig (Cross-Package — Already Partially Resolved)

Type: Semantic split with shared base type
Impact: Medium — partially resolved, but CustomFields map[string]any in the workflow variant warrants attention

Locations:

1. pkg/parser/mcp.go:84 — JSON-tagged, parser-domain fields
2. pkg/workflow/tools_types.go:351 — YAML-tagged, workflow-domain fields
3. pkg/types/mcp.go:6 — BaseMCPServerConfig (shared base, already extracted)

Comparison:

// pkg/types/mcp.go — shared base (well-designed):
type BaseMCPServerConfig struct {
    Command        string            `json:"..." yaml:"..."`
    Args           []string          `json:"..." yaml:"..."`
    Env            map[string]string `json:"..." yaml:"..."`
    Type           string            `json:"..." yaml:"..."`
    Version        string            `json:"..." yaml:"..."`
    URL            string            `json:"..." yaml:"..."`
    Headers        map[string]string `json:"..." yaml:"..."`
    Container      string            `json:"..." yaml:"..."`
    Entrypoint     string            `json:"..." yaml:"..."`
    EntrypointArgs []string          `json:"..." yaml:"..."`
    Mounts         []string          `json:"..." yaml:"..."`
}

// pkg/parser/mcp.go — parser-specific:
type MCPServerConfig struct {
    types.BaseMCPServerConfig
    Name      string   `json:"name"`
    Registry  string   `json:"registry"`
    ProxyArgs []string `json:"proxy-args"`
    Allowed   []string `json:"allowed"`
}

// pkg/workflow/tools_types.go — workflow-specific:
type MCPServerConfig struct {
    types.BaseMCPServerConfig
    Mode         string         `yaml:"mode,omitempty"`
    Toolsets     []string       `yaml:"toolsets,omitempty"`
    CustomFields map[string]any `yaml:",inline"` // catch-all for dynamic config
}

Recommendation:

• The base type extraction is already well-done. The CustomFields map[string]any escape hatch in the workflow variant is acceptable for truly dynamic server-specific config, but could be audited to check if any fields have solidified and should be promoted to explicit typed fields.
• Effort: Low-to-medium (audit CustomFields usage patterns to identify promotable fields).

---

Untyped Usages

Summary Statistics

• interface{} uses (legacy): 5 across 2 files
• any in struct fields: ~16 instances with various justifications
• map[string]any in struct fields/function params: 400+ occurrences (mostly YAML processing — largely justified)
• []any usages: 150+ occurrences (YAML step sequences — largely justified)
• Untyped constants: ~30 additional untyped numeric/string constants

---

Category 1: Legacy interface{} — Should Be any

Impact: Low — stylistic inconsistency with rest of codebase
Files affected: 2

Go 1.18 introduced any as an alias for interface{}. The entire codebase uses any, except for 5 residual occurrences.

Location 1: pkg/workflow/gemini_logs.go:15

// Current (legacy):
type GeminiResponse struct {
    Response string                 `json:"response"`
    Stats    map[string]interface{} `json:"stats"`  // ← should be map[string]any
}

// And at lines 54, 56, 68:
if models, ok := response.Stats["models"].(map[string]interface{}); ok {  // ← map[string]any
    for _, modelStats := range models {
        if stats, ok := modelStats.(map[string]interface{}); ok {         // ← map[string]any
        ...
if tools, ok := response.Stats["tools"].(map[string]interface{}); ok {   // ← map[string]any

// Suggested fix:
type GeminiResponse struct {
    Response string         `json:"response"`
    Stats    map[string]any `json:"stats"`
}
// Update all type assertions to use map[string]any

Location 2: pkg/console/layout_wasm.go:16

// Current (legacy — the parameter is ignored in the implementation):
func LayoutEmphasisBox(content string, color interface{}) string {
    marker := strings.Repeat("!", len(content)+4)
    return marker + "\n  " + content + "\n" + marker
}

// Suggested fix:
func LayoutEmphasisBox(content string, color any) string {
    // Or, since color is unused in the WASM stub, consider removing the parameter
    // to match whatever the non-WASM signature would look like

Effort: Trivial (5 min, simple text replacement).

---

Category 2: Parallel RunsOn any Fields

Impact: Medium — same semantic concept (runs-on YAML field) typed as any in multiple disconnected structs

Locations:

1. pkg/workflow/safe_jobs.go:19 — RunsOn any
2. pkg/cli/copilot_setup.go:123 — RunsOn any in CopilotWorkflowStep

The runs-on value in GitHub Actions can be a string ("ubuntu-latest"), an array (["self-hosted", "linux"]), or a complex expression. This polymorphism is the actual reason for any — but having a shared named type would make the intent clearer.

Example:

// Currently spread across files:
// pkg/workflow/safe_jobs.go:
type SafeJobConfig struct {
    RunsOn  any      `yaml:"runs-on,omitempty"`
    ...
}

// pkg/cli/copilot_setup.go:
type CopilotWorkflowStep struct {
    RunsOn any `yaml:"runs-on,omitempty"`
    ...
}

// Suggested: define a shared alias in pkg/types or pkg/workflow:
// type RunsOnValue any   // Can be string, []string, or expression

// Or document with a comment:
// RunsOn can be string ("ubuntu-latest"), []string (["self-hosted", "linux"]), or expression
type SafeJobConfig struct {
    RunsOn any `yaml:"runs-on,omitempty"` // string | []string | expression

Recommendation: At minimum, add consistent comments. If a shared type package is created, a RunsOnValue type alias documents intent.

---

Category 3: Parallel On any Fields

Impact: Low-medium — same concept (GitHub trigger map) in multiple CLI structs

Locations:

1. pkg/cli/copilot_setup.go:131 — On any in Workflow
2. pkg/cli/list_workflows_command.go:25 — On any in WorkflowListItem
3. pkg/cli/status_command.go:30 — On any in WorkflowStatus

The on: key in GitHub Actions workflows is highly polymorphic (can be string, array, or map). The any type is technically required here, but the pattern is repeated without cross-referencing.

Recommendation: These structs could share a GitHubWorkflowOn type alias (type GitHubWorkflowOn any) with documentation, or simply add consistent comments.

---

Category 4: Default any in Input Definitions

Impact: Medium — same field concept in two similar structs

Locations:

1. pkg/workflow/inputs.go:22 — Default any with comment "Can be string, number, or boolean"
2. pkg/workflow/safe_inputs_parser.go:46 — Default any
3. pkg/parser/import_processor.go:59 — Default any with comment "dynamic type from YAML"

These all represent the default: field of a workflow input, which can be string, number, boolean, or null per the GitHub Actions spec.

Suggested fix:

// Could define a shared type alias in pkg/types:
// type InputDefaultValue any // string | bool | float64 | nil per YAML spec

// At minimum, add consistent documentation:
type InputDefinition struct {
    Default any `yaml:"default,omitempty"` // string | bool | float64 | nil
    ...
}

---

Category 5: handlerBuilder Returns map[string]any

Impact: Medium — 50+ handler functions in compiler_safe_outputs_config.go all return untyped config maps

Location: pkg/workflow/compiler_safe_outputs_config.go:123

type handlerBuilder func(*SafeOutputsConfig) map[string]any

Every safe output handler (create_issue, add_comment, close_issue, etc.) returns a map[string]any representing YAML-ready step configuration. This is a large surface area of untyped data.

Current pattern:

// Example handler (simplified):
func buildCreateIssueConfig(cfg *SafeOutputsConfig) map[string]any {
    b := newHandlerConfigBuilder()
    b.AddDefault("title", cfg.Messages.IssueTitle)
    b.AddDefault("body", cfg.Messages.IssueBody)
    return b.Build()  // returns map[string]any
}

Alternative consideration:

// A typed step config struct (higher effort, higher payoff):
type GitHubScriptStepConfig struct {
    Script     string            `yaml:"script"`
    GithubToken string           `yaml:"github-token,omitempty"`
    ResultEncoding string        `yaml:"result-encoding,omitempty"`
    // ...
}

Note: GitHubScriptStepConfig already exists at pkg/workflow/safe_outputs_steps.go:99 — the handler builders could potentially use it rather than raw maps. However, this is a significant refactoring effort given the volume (50+ handlers).

Recommendation: Consider a phased approach — first add type documentation comments, then migrate high-traffic handlers to typed structs.

---

Category 6: Untyped Constants Missing Semantic Types

Impact: Low-medium — reduces discoverability and prevents type-safe usage

Selected examples of constants that lack explicit types:

File	Constant	Value	Suggested Type
pkg/workflow/expression_validation.go:62	maxFuzzyMatchSuggestions = 7	7	int
pkg/cli/secret_set_command.go:33	publicKeySize = 32	32	int
pkg/workflow/engine_output.go:13	RedactedURLsLogPath = "/tmp/..."	string	string
pkg/workflow/safe_inputs_parser.go:55	SafeInputsDirectory = "/opt/..."	string	string
pkg/workflow/copilot_engine.go:24	logsFolder = "/tmp/..."	string	string

Contrast with the well-typed constants in pkg/constants/constants.go which explicitly use Version, URL, ModelName etc.:

const DefaultClaudeCodeVersion Version = "2.1.47"  // ✅ typed
const RedactedURLsLogPath = "/tmp/gh-aw/..."       // ❌ untyped

Recommendation: Low priority — explicit types on package-level constants improve safety but local/private constants are lower risk. Focus on exported constants first.

---

Refactoring Recommendations

Priority 1: Trivial — Replace interface{} with any

Files: pkg/workflow/gemini_logs.go, pkg/console/layout_wasm.go
Steps:

1. Replace map[string]interface{} → map[string]any in gemini_logs.go (lines 15, 54, 56, 68)
2. Replace color interface{} → color any in layout_wasm.go (line 16)
3. Verify build passes

Estimated effort: 5 minutes
Benefits: Codebase consistency, removes only legacy interface{} usage

---

Priority 2: Low — Extract Shared RepositoryFeatures Struct

Files: pkg/workflow/repository_features_validation.go, pkg/workflow/repository_features_validation_wasm.go
Steps:

1. Create pkg/workflow/repository_features_types.go with the struct definition
2. Remove duplicate struct from both original files
3. Add cross-reference comments to the build-tag files

Estimated effort: 15 minutes
Benefits: Single source of truth for the struct, easier to add fields later

---

Priority 3: Medium — Audit MCPServerConfig.CustomFields for Promotable Fields

File: pkg/workflow/tools_types.go:351
Steps:

1. Search for all places CustomFields is read/written
2. Identify any keys that are consistently present and could be typed fields
3. Promote identified keys to explicit struct fields with proper YAML tags

Estimated effort: 2-4 hours
Benefits: Stronger typing, better IDE support, compile-time field validation

---

Priority 4: Medium — Add Semantic Type Aliases for Polymorphic YAML Fields

Scope: RunsOn any, On any, Default any across multiple structs
Steps:

1. Define type aliases in a shared location (e.g., pkg/workflow/yaml_types.go):

   // RunsOnValue represents the GitHub Actions runs-on field.
   // Can be: string ("ubuntu-latest"), []string (["self-hosted", "linux"])
   type RunsOnValue = any
   
   // WorkflowTrigger represents the GitHub Actions on: field.
   // Can be: string, []string, or map[string]any
   type WorkflowTrigger = any
   
   // InputDefaultValue represents a workflow input default.
   // Can be: string, bool, float64, or nil
   type InputDefaultValue = any

2. Update all struct fields to use these aliases
3. Benefit is documentation, not compile-time enforcement (type aliases to any are still any)

Estimated effort: 1-2 hours
Benefits: Documents intent, makes polymorphism explicit, improves code searchability

---

Priority 5: Long-term — Typed Step Config Structs for Safe Output Handlers

Scope: pkg/workflow/compiler_safe_outputs_config.go (50+ handlers returning map[string]any)
Steps:

1. Define a StepConfig interface or concrete struct for each output type
2. Migrate handlers from map[string]any to typed structs
3. Add a YAML marshaling step at the boundary

Estimated effort: 10-20 hours
Benefits: Full compile-time safety for step configuration, IDE autocomplete, prevents silent config errors

---

Implementation Checklist

• Replace interface{} with any in gemini_logs.go and layout_wasm.go (5 min)
• Extract shared RepositoryFeatures struct to separate file (15 min)
• Add cross-reference comments to all wasm/non-wasm duplicate files (15 min)
• Audit MCPServerConfig.CustomFields for promotable fields (2-4 hrs)
• Add semantic type aliases for RunsOn, On, Default polymorphic fields (1-2 hrs)
• Consider typed step configs for safe output handlers (long-term)

---

Analysis Metadata

• Total Go Files Analyzed: 546 (non-test, pkg/ directory)
• Packages: 18 (cli, console, constants, envutil, fileutil, gitutil, logger, mathutil, parser, repoutil, sliceutil, stringutil, styles, testutil, timeutil, tty, types, workflow)
• Total Struct Types: 428 | Interface Types: 13 | Named/Alias Types: 51
• Duplicate Clusters: 4 (3 build-tag-separated, 1 cross-package with shared base)
• interface{} Uses (legacy): 5 across 2 files
• any Uses: 400+ (majority justified by YAML/JSON polymorphism)
• Detection Method: Serena semantic analysis + grep/find pattern matching
• Analysis Date: 2026-02-20

References:

• §22221833584

AI generated by Typist - Go Type Analysis

• expires on Feb 27, 2026, 11:23 AM UTC