🔤 Typist Report: Go Type Consistency Analysis

[github-actions[bot]]

Executive Summary

Comprehensive analysis of 487 non-test Go files across the pkg/ directory reveals a codebase that has successfully migrated from interface{} to any, but still has significant opportunities for stronger typing. The analysis identified 417 struct types, 1,636 uses of the any type (primarily in map[string]any for YAML unmarshaling), and 225 untyped constants.

Key Findings:

• ✅ Complete interface{} elimination - Zero occurrences in production code
• ⚠️ High any usage - 1,060 map[string]any occurrences, primarily for dynamic YAML/config handling
• 📦 Type consolidation pattern - Good use of embedded BaseMCPServerConfig type
• 🎯 Partial strong typing - ParsedTools alongside map[string]any shows migration path
• 📝 225 untyped constants - Missing explicit type declarations

Full Analysis Report

Analysis Scope

• Total Non-Test Files Analyzed: 487
• Primary Focus Areas:
  • pkg/workflow/ (251 files)
  • pkg/cli/ (136 files)
  • Other packages (100 files)
• Analysis Date: 2026-01-30
• Detection Method: Serena semantic analysis + systematic pattern matching

---

Duplicated Type Definitions

Summary Statistics

• Total Struct Types: 417
• Total Interface Types: 13
• Type Aliases: 5
• Config Structs: 105+ types ending in *Config
• Duplicate Type Names: 3 identified cases

Cluster 1: MCPServerConfig - Embedded Pattern (Good Design!)

Type: Intentional duplication with embedded base type
Occurrences: 3 (base + 2 specialized)
Impact: Low - This is a positive pattern for code reuse

Locations:

1. pkg/types/mcp.go:6 - type BaseMCPServerConfig struct
2. pkg/parser/mcp.go:84 - type MCPServerConfig struct (embeds base)
3. pkg/workflow/tools_types.go:351 - type MCPServerConfig struct (embeds base)

Definition Comparison:

// pkg/types/mcp.go:6 - Shared base type
type BaseMCPServerConfig struct {
    Command      string
    Args         []string
    Env          map[string]string
    Type         string
    Version      string
    // ... common fields
}

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

// pkg/workflow/tools_types.go:351 - Workflow-specific extension
type MCPServerConfig struct {
    types.BaseMCPServerConfig  // Embeds common fields
    
    // Workflow-specific fields
    Mode         string         `yaml:"mode,omitempty"`
    Toolsets     []string       `yaml:"toolsets,omitempty"`
    CustomFields map[string]any `yaml:",inline"`
}

Assessment:

• ✅ Good pattern - Shared base prevents duplication of common fields
• ✅ Each package extends with domain-specific fields
• ✅ Clear separation of concerns

Recommendation: No action needed - This is best practice Go composition pattern.

---

Cluster 2: ProjectConfig - Name Collision (Potential Confusion)

Type: Same name, different purposes
Occurrences: 2
Impact: Medium - Potential confusion when reading code

Locations:

1. pkg/workflow/frontmatter_types.go:56 - Campaign/workflow project configuration (56 fields!)
2. pkg/cli/project_command.go:19 - CLI command configuration (different purpose)

Definition Comparison:

// pkg/workflow/frontmatter_types.go:56 - Campaign configuration
type ProjectConfig struct {
    URL                     string
    Scope                   []string
    MaxUpdates              int
    Workflows               []string
    MemoryPaths             []string
    // ... 50+ more campaign-specific fields
}

// pkg/cli/project_command.go:19 - CLI command config (different structure)
type ProjectConfig struct {
    // Different purpose - CLI command configuration
    // (exact structure not shown in overview)
}

Recommendation:

• Rename pkg/cli/project_command.go type to ProjectCommandConfig
• Or rename pkg/workflow/frontmatter_types.go type to CampaignProjectConfig
• Estimated effort: 1-2 hours
• Benefits: Eliminates naming ambiguity, clearer intent

---

Cluster 3: Type Aliases - Duplication Elimination (Excellent Pattern!)

Type: Type aliases to prevent duplication
Occurrences: Multiple
Impact: Positive - Reduces code duplication

Examples:

// pkg/workflow/close_entity_helpers.go:180-182
type CloseIssuesConfig = CloseEntityConfig
type ClosePullRequestsConfig = CloseEntityConfig
type CloseDiscussionsConfig = CloseEntityConfig

// pkg/workflow/tools_types.go:90
type Tools = ToolsConfig

// pkg/cli/logs_models.go:66
type LogMetrics = workflow.LogMetrics

Assessment: ✅ Excellent pattern - Using type aliases to provide semantic names while avoiding duplication.

Recommendation: No action needed - Continue this pattern elsewhere.

---

Cluster 4: Config Struct Proliferation (Organizational Issue)

Type: Many similarly-named Config structs
Occurrences: 105+ structs ending in *Config
Impact: Medium - Difficult to navigate, no single source of truth

Sample of Config Types:

• CompileConfig, FixConfig, HealthConfig, UpgradeConfig
• ToolsConfig, SafeOutputsConfig, SafeInputsConfig
• SandboxConfig, AgentSandboxConfig, SandboxRuntimeConfig
• RuntimeConfig, RuntimesConfig, PermissionsConfig
• ProjectConfig, CampaignGovernanceConfig, CampaignBootstrapConfig
• EngineConfig, EngineNetworkConfig, EngineInstallConfig
• GitHubToolConfig, PlaywrightToolConfig, SerenaToolConfig
• 30+ safe-output configs: CreateIssuesConfig, UpdateIssuesConfig, etc.

Recommendation:

• Consider consolidating related configs into nested structs within parent types
• Create a pkg/config/ package for shared configuration types
• Document config organization in architecture documentation
• Estimated effort: 8-16 hours (large refactoring)
• Benefits: Easier navigation, clearer relationships between configs

---

Untyped Usages

Summary Statistics

• interface{} usages in non-test files: 0 ✅
• any usages in non-test files: 1,636
• Files with map[string]any: 418 files
• Total map[string]any occurrences: 1,060
• []any usages: 163
• Untyped constants: 225

---

Category 1: map[string]any for Dynamic Configuration

Impact: High - Makes code harder to understand and maintain
Rationale: Used extensively for YAML unmarshaling and dynamic config

Example 1: WorkflowData Core Type

Location: pkg/workflow/compiler_types.go:374-419

Current Implementation:

type WorkflowData struct {
    // Line 374: Import inputs for substitution
    ImportInputs        map[string]any
    
    // Line 389-390: Tools - partial strong typing!
    Tools               map[string]any
    ParsedTools         *Tools  // Structured version (migration pattern)
    
    // Line 401: Command event configuration
    CommandOtherEvents  map[string]any
    
    // Line 404: Custom jobs (very dynamic)
    Jobs                map[string]any
    
    // Line 415: Runtime overrides
    Runtimes            map[string]any
    
    // Line 419: Feature flags
    Features            map[string]any
}

Analysis:

• The codebase is actively migrating toward strong typing (see ParsedTools alongside Tools)
• Some fields like Jobs are inherently dynamic (user-defined custom jobs)
• Other fields like Features could potentially be typed

Suggested Approach:

// Step 1: Define strongly-typed structures
type ImportInputsConfig struct {
    Values map[string]string
    // Add typed fields as patterns emerge
}

type RuntimeOverrides struct {
    Node   string `yaml:"node,omitempty"`
    Python string `yaml:"python,omitempty"`
    Docker string `yaml:"docker,omitempty"`
    // Add more as needed
}

type FeaturesConfig struct {
    EnableX bool   `yaml:"enable-x,omitempty"`
    ModeY   string `yaml:"mode-y,omitempty"`
    // Document known features
}

// Step 2: Update WorkflowData to use typed versions
type WorkflowData struct {
    ImportInputs        *ImportInputsConfig  // Typed!
    Tools               map[string]any       // Keep for backward compat
    ParsedTools         *Tools               // Already migrated
    CommandOtherEvents  map[string]any       // Inherently dynamic
    Jobs                map[string]any       // Inherently dynamic (user-defined)
    Runtimes            *RuntimeOverrides    // Typed!
    Features            *FeaturesConfig      // Typed!
}

Benefits:

• Compile-time validation of common configurations
• Better IDE autocomplete
• Clearer documentation of supported options
• Easier to maintain backward compatibility

Estimated effort: 6-10 hours (requires careful migration)

---

Example 2: FrontmatterConfig Type

Location: pkg/workflow/frontmatter_types.go:144-196

Current Implementation:

type FrontmatterConfig struct {
    MCPServers   map[string]any     // Line 157
    Runtimes     map[string]any     // Line 159
    Jobs         map[string]any     // Line 160
    On           map[string]any     // Line 167
    Permissions  map[string]any     // Line 168
    Concurrency  map[string]any     // Line 169
    Features     map[string]any     // Line 177
    Secrets      map[string]any     // Line 179
    Environment  map[string]any     // Line 186
    Container    map[string]any     // Line 187
    Services     map[string]any     // Line 188
    Cache        map[string]any     // Line 189
    Steps        []any              // Line 184
    PostSteps    []any              // Line 185
    Metadata     map[string]string  // Line 196 - Already typed!
}

Analysis:

• Metadata is already strongly typed (good!)
• Many of these map directly to GitHub Actions workflow schema
• Could leverage existing GitHub Actions type definitions

Suggested Approach:

// Define types matching GitHub Actions schema
type PermissionsConfig struct {
    Actions      string `yaml:"actions,omitempty"`
    Contents     string `yaml:"contents,omitempty"`
    Issues       string `yaml:"issues,omitempty"`
    PullRequests string `yaml:"pull-requests,omitempty"`
    // ... more standard GitHub permissions
}

type ConcurrencyConfig struct {
    Group            string `yaml:"group"`
    CancelInProgress bool   `yaml:"cancel-in-progress,omitempty"`
}

type Step struct {
    Name string         `yaml:"name,omitempty"`
    Uses string         `yaml:"uses,omitempty"`
    Run  string         `yaml:"run,omitempty"`
    With map[string]any `yaml:"with,omitempty"` // Keep flexible for step params
    If   string         `yaml:"if,omitempty"`
    // ... more step fields
}

// Update FrontmatterConfig
type FrontmatterConfig struct {
    Permissions  *PermissionsConfig  // Typed!
    Concurrency  *ConcurrencyConfig  // Typed!
    Steps        []Step              // Typed!
    PostSteps    []Step              // Typed!
    Metadata     map[string]string   // Already typed
    // Keep dynamic for truly variable configs
    Jobs         map[string]any      // User-defined custom jobs
    Features     map[string]any      // Extension point
}

Benefits:

• Aligns with GitHub Actions standard schema
• Enables validation at compile time
• Easier for developers to understand structure

Estimated effort: 8-12 hours

---

Example 3: Function Parameters with map[string]any

Current Pattern:

// pkg/workflow/tools.go
func (c *Compiler) mergeToolsAndMCPServers(
    topTools, mcpServers map[string]any, 
    includedTools string
) (map[string]any, error)

// pkg/workflow/compiler_jobs.go
func (c *Compiler) referencesCustomJobOutputs(
    condition string, 
    customJobs map[string]any
) bool

// pkg/cli/dependency_graph.go:159
func (g *DependencyGraph) extractImportsFromFrontmatter(
    workflowPath string, 
    frontmatter map[string]any
) []string

Suggested Approach:

// Define intermediate types for common map structures
type ToolsMap map[string]*ToolConfig
type MCPServersMap map[string]*MCPServerConfig
type JobsMap map[string]*JobConfig

// Update function signatures
func (c *Compiler) mergeToolsAndMCPServers(
    topTools ToolsMap, 
    mcpServers MCPServersMap, 
    includedTools string
) (ToolsMap, error)

func (c *Compiler) referencesCustomJobOutputs(
    condition string, 
    customJobs JobsMap
) bool

func (g *DependencyGraph) extractImportsFromFrontmatter(
    workflowPath string, 
    frontmatter *FrontmatterConfig  // Use typed struct
) []string

Benefits:

• Type safety at function boundaries
• Clear documentation of expected structure
• Easier to refactor

Estimated effort: 12-16 hours (touches many call sites)

---

Category 2: Untyped Constants

Impact: Medium - Lack of semantic clarity, no type safety

Example 1: Path Constants

Current Implementation:

// pkg/workflow/bundler_file_mode.go
const ScriptsBasePath = "/opt/gh-aw/actions"                // Line 40
const SetupActionDestination = "/opt/gh-aw/actions"         // Line 43

// pkg/workflow/safe_inputs_parser.go
const SafeInputsDirectory = "/opt/gh-aw/safe-inputs"        // Line 55

// pkg/workflow/engine_output.go
const RedactedURLsLogPath = "/tmp/gh-aw/redacted-urls.log"  // Line 13

// pkg/workflow/copilot_engine.go
const logsFolder = "/tmp/gh-aw/sandbox/agent/logs/"         // Line 25

Suggested Fix:

// Define semantic type
type FilePath string

// Add explicit types to constants
const ScriptsBasePath FilePath = "/opt/gh-aw/actions"
const SetupActionDestination FilePath = "/opt/gh-aw/actions"
const SafeInputsDirectory FilePath = "/opt/gh-aw/safe-inputs"
const RedactedURLsLogPath FilePath = "/tmp/gh-aw/redacted-urls.log"
const logsFolder FilePath = "/tmp/gh-aw/sandbox/agent/logs/"

Benefits:

• Type safety (can't accidentally pass wrong type)
• Semantic clarity (it's a file path, not just a string)
• Easier to add validation functions on the type

Estimated effort: 2-3 hours

---

Example 2: Label/Identifier Constants

Current Implementation:

// pkg/constants/constants.go
const AgenticCampaignLabel = "agentic-campaign"             // Line 248
const CampaignLabelPrefix = "z_campaign_"                   // Line 253
const SafeOutputArtifactName = "safe-output"                // Line 488
const AgentOutputArtifactName = "agent-output"              // Line 489
const AgentOutputFilename = "agent_output.json"             // Line 492

Suggested Fix:

// Define semantic types
type Label string
type ArtifactName string
type FileName string

// Add explicit types
const AgenticCampaignLabel Label = "agentic-campaign"
const CampaignLabelPrefix Label = "z_campaign_"
const SafeOutputArtifactName ArtifactName = "safe-output"
const AgentOutputArtifactName ArtifactName = "agent-output"
const AgentOutputFilename FileName = "agent_output.json"

Benefits:

• Prevents mixing different string categories
• Self-documenting code
• Type-safe function parameters

Estimated effort: 2-3 hours

---

Example 3: Good Pattern - Already Typed Constants!

Current Implementation (keep this pattern!):

// pkg/constants/constants.go - Already properly typed!
const DefaultAgenticWorkflowTimeout = 20 * time.Minute      // Line 397 ✅
const DefaultToolTimeout = 60 * time.Second                 // Line 400 ✅
const DefaultMCPStartupTimeout = 120 * time.Second          // Line 403 ✅

Assessment: ✅ Excellent! These constants use Go's time.Duration type properly.

Recommendation: Apply this same pattern to other constants.

---

Refactoring Recommendations

Priority 1: Critical - Continue map[string]any Migration

Current State: Codebase shows active migration with ParsedTools pattern alongside map[string]any

Recommendation: Continue the migration pattern for high-impact types

Target Types:

1. WorkflowData.ImportInputs → typed ImportInputsConfig
2. WorkflowData.Runtimes → typed RuntimeOverrides
3. WorkflowData.Features → typed FeaturesConfig
4. FrontmatterConfig.Permissions → typed PermissionsConfig
5. FrontmatterConfig.Concurrency → typed ConcurrencyConfig
6. FrontmatterConfig.Steps → typed []Step

Migration Strategy:

1. Define new typed structs
2. Add new typed fields alongside existing map[string]any fields
3. Create helper functions to parse from map[string]any to typed structs
4. Gradually migrate code to use typed versions
5. Deprecate map[string]any fields in future version

Estimated effort: 20-30 hours (phased approach over multiple PRs)
Impact: High - Significantly improves type safety and code clarity

---

Priority 2: High - Add Types to Constants

Recommendation: Add explicit types to all 225 untyped constants

Approach:

1. Create semantic type aliases (type FilePath string, type Label string, etc.)
2. Update constant declarations to use explicit types
3. Update function signatures to use semantic types

Target Categories:

• Path constants (50+) → type FilePath string
• Label constants (30+) → type Label string
• Artifact name constants (20+) → type ArtifactName string
• Domain/URL constants (40+) → type DomainName string
• Container image constants (15+) → type ContainerImage string

Estimated effort: 6-8 hours
Impact: Medium - Improved type safety and code clarity

---

Priority 3: Medium - Resolve ProjectConfig Name Collision

Recommendation: Rename conflicting ProjectConfig types

Options:

1. pkg/cli/project_command.go → ProjectCommandConfig
2. pkg/workflow/frontmatter_types.go → CampaignProjectConfig or WorkflowProjectConfig

Estimated effort: 1-2 hours
Impact: Low - Eliminates potential confusion

---

Priority 4: Low - Consider Config Package Consolidation

Recommendation: Evaluate consolidating related configs into a pkg/config/ package

Rationale: 105+ *Config types scattered across packages makes navigation difficult

Approach:

1. Create pkg/config/ package
2. Move shared config types to new package
3. Keep domain-specific configs in their packages
4. Document config organization

Estimated effort: 16-24 hours (large refactoring, low priority)
Impact: Medium - Improved code organization

---

Implementation Checklist

Phase 1: Quick Wins (8-10 hours)

• Add explicit types to constants (Priority 2)
• Rename ProjectConfig to eliminate collision (Priority 3)
• Document current migration pattern (ParsedTools approach)

Phase 2: Type Safety Improvements (20-30 hours)

• Migrate WorkflowData.Runtimes to typed struct
• Migrate WorkflowData.Features to typed struct
• Migrate FrontmatterConfig.Permissions to typed struct
• Migrate FrontmatterConfig.Concurrency to typed struct
• Migrate FrontmatterConfig.Steps to typed slice

Phase 3: Comprehensive Migration (40-60 hours)

• Continue migration of remaining map[string]any fields
• Update function signatures to use typed structs
• Add validation functions on typed structs
• Deprecate old map[string]any fields

Phase 4: Long-term Improvements (Optional)

• Consider config package consolidation
• Document type architecture decisions
• Create developer guide for adding new config types

---

Positive Patterns Observed

✅ Excellent Patterns to Continue:

1. Type Embedding Pattern

   type BaseMCPServerConfig struct { /* common fields */ }
   type MCPServerConfig struct {
       BaseMCPServerConfig  // Embed base
       // Package-specific extensions
   }

2. Type Alias Pattern

   type CloseIssuesConfig = CloseEntityConfig
   type ClosePullRequestsConfig = CloseEntityConfig

3. Parallel Migration Pattern

   type WorkflowData struct {
       Tools       map[string]any  // Old: keep for compatibility
       ParsedTools *Tools          // New: strongly typed
   }

4. Typed Time Constants

   const DefaultTimeout = 20 * time.Minute

---

Analysis Metadata

• Total Go Files Analyzed: 487 non-test files
• Total Type Definitions: 435 (417 structs + 13 interfaces + 5 aliases)
• Duplicate Type Names: 3 cases (2 intentional, 1 collision)
• Total any Usages: 1,636 occurrences
• map[string]any Occurrences: 1,060
• interface{} in Production Code: 0 ✅
• Untyped Constants: 225
• Analysis Method: Serena semantic analysis + systematic pattern search
• Repository: githubnext/gh-aw
• Analysis Date: 2026-01-30

---

Conclusion

The gh-aw codebase demonstrates a strong commitment to type safety with the complete elimination of interface{} in production code. The presence of the parallel migration pattern (Tools + ParsedTools) shows active ongoing work to strengthen types. The primary opportunity is to continue this migration pattern for the ~1,060 map[string]any occurrences, focusing on high-impact types like WorkflowData and FrontmatterConfig.

The analysis reveals a well-structured codebase with thoughtful use of type embedding and aliases to reduce duplication. With targeted refactoring efforts totaling 40-60 hours of work, the codebase could achieve significantly stronger type safety while maintaining backward compatibility through parallel field migration.

References:

• §21513776826

AI generated by Typist - Go Type Analysis

• expires on Feb 6, 2026, 11:21 AM UTC