🔤 Typist - Go Type Consistency Analysis

[github-actions[bot]]

Executive Summary

Analyzed 398 Go source files in the pkg/ directory of the githubnext/gh-aw repository to identify type consistency issues. The analysis revealed:

• 2 exact duplicate type definitions with identical names but different structures
• 150+ struct types with potential naming pattern inconsistencies (e.g., *Config, *Error, *Data)
• Extensive use of []any and map[string]any (200+ occurrences) that could benefit from strong typing
• Limited use of interface{} (primarily in test files, which is acceptable)

High-Impact Findings:

1. ValidationError type is duplicated in two packages with incompatible structures
2. Heavy reliance on []any for tool configurations and workflow data structures
3. Inconsistent configuration type patterns across packages

Full Analysis Report

Duplicated Type Definitions

Summary Statistics

• Total Go files analyzed: 398
• Struct types found: 150+
• Exact duplicates: 2
• Near duplicates: Several -Config and -Error patterns

Cluster 1: ValidationError - Exact Name Collision

Type: Exact duplicate name, incompatible structures
Occurrences: 2
Impact: High - Same type name with different purposes causes confusion

Locations:

1. pkg/workflow/error_helpers.go:10 - Workflow validation error
2. pkg/cli/compile_config.go:53 - Compilation validation error

Definition Comparison:

// Location 1: pkg/workflow/error_helpers.go:10
type ValidationError struct {
    Field      string
    Value      string
    Reason     string
    Suggestion string
    Timestamp  time.Time
}

// Location 2: pkg/cli/compile_config.go:53
type ValidationError struct {
    Type    string `json:"type"`
    Message string `json:"message"`
    Line    int    `json:"line,omitempty"`
}

Analysis: These are fundamentally different error types serving different purposes:

• The workflow version focuses on field-level validation with suggestions
• The CLI version represents JSON output for compilation errors with line numbers

Recommendation:

• Rename to be more specific: WorkflowValidationError and CompileValidationError
• Or consolidate if they could share a common interface
• Estimated effort: 1-2 hours
• Benefits: Eliminates naming confusion, clearer intent

---

Cluster 2: Configuration Type Proliferation

Type: Semantic pattern duplication
Occurrences: 50+ *Config structs
Impact: Medium - Scattered configuration types without clear patterns

Sample Locations (selected examples):

• pkg/workflow/firewall.go:14 - FirewallConfig
• pkg/workflow/engine.go:14 - EngineConfig
• pkg/workflow/sandbox.go:37 - SandboxConfig
• pkg/workflow/tools_types.go:63 - ToolsConfig
• pkg/cli/compile_config.go:11 - CompileConfig
• pkg/cli/fix_command.go:19 - FixConfig

Analysis: While these serve different purposes, there's no consistent pattern for:

• Required vs optional fields
• Validation methods
• Configuration merging
• Default value handling

Recommendation:

• Consider defining a Config interface with common methods
• Document configuration patterns in architecture docs
• Estimated effort: Medium (architectural decision)
• Benefits: Consistent configuration handling across packages

---

Cluster 3: Error Type Patterns

Type: Multiple error types with similar patterns
Occurrences: 5+ error types
Impact: Low-Medium - Could benefit from standardization

Sample Locations:

• pkg/workflow/error_helpers.go:10 - ValidationError
• pkg/workflow/error_helpers.go:55 - OperationError
• pkg/workflow/error_helpers.go:107 - ConfigurationError
• pkg/workflow/shared_workflow_error.go:16 - SharedWorkflowError
• pkg/workflow/github_toolset_validation_error.go:15 - GitHubToolsetValidationError
• pkg/parser/import_error.go:14 - ImportError
• pkg/cli/compile_config.go:53 - ValidationError (duplicate name)

Pattern Analysis: All error types implement similar patterns:

• Custom Error() method
• Context fields (file, line, message)
• Some implement Unwrap() for error chains

Recommendation:

• Consider a common error interface or base struct
• Standardize error formatting patterns
• Estimated effort: 3-4 hours
• Benefits: Consistent error handling and debugging experience

---

Untyped Usages

Summary Statistics

• interface{} usages: ~30 (mostly in test files - acceptable)
• any as type parameter: 70+ function parameters
• []any slice usage: 200+ occurrences
• map[string]any usage: 150+ occurrences
• Total untyped locations: 400+

Category 1: []any for Configuration Arrays

Impact: High - Type assertions required throughout codebase

Primary Pattern: Tool and workflow configuration uses []any extensively

Examples:

Example 1: Bash tool commands

• Locations: Throughout pkg/workflow/ (e.g., tools_parser.go, claude_engine.go, copilot_engine.go)
• Current pattern:

  "bash": []any{"echo", "ls", "git status"}
  
  // Later requires type assertions:
  if bashCommands, ok := bashTool.([]any); ok {
      for _, cmd := range bashCommands {
          if cmdStr, ok := cmd.(string); ok {
              // Use cmdStr
          }
      }
  }

• Suggested fix:

  type BashCommand string
  type BashCommands []BashCommand
  
  "bash": BashCommands{"echo", "ls", "git status"}
  
  // No type assertions needed:
  for _, cmd := range bashCommands {
      // cmd is already BashCommand (string)
  }

• Benefits: Compile-time type safety, no runtime type assertions, clearer API

Example 2: GitHub tool allowed list

• Locations: pkg/workflow/tools_parser.go:171, pkg/workflow/claude_tools.go:310
• Current pattern:

  "github": map[string]any{
      "allowed": []any{"issue_read", "create_issue", "list_commits"}
  }
  
  if allowedSlice, ok := allowed.([]any); ok {
      for _, tool := range allowedSlice {
          if toolName, ok := tool.(string); ok {
              // Use toolName
          }
      }
  }

• Suggested fix:

  type GitHubToolName string
  type GitHubAllowedTools []GitHubToolName
  
  type GitHubToolConfig struct {
      Allowed GitHubAllowedTools
  }
  
  // No type assertions needed
  for _, toolName := range config.Allowed {
      // toolName is already GitHubToolName
  }

• Benefits: Type-safe, self-documenting, IDE autocomplete support

Example 3: Workflow steps array

• Locations: pkg/workflow/step_types.go:187, pkg/workflow/action_pins.go:378
• Current usage: []any for flexible step definitions
• Analysis: The codebase already has WorkflowStep struct and conversion functions SliceToSteps and StepsToSlice
• Suggested improvement: Use []*WorkflowStep as the primary type instead of []any
• Benefits: Type safety, better validation at compile time

---

Category 2: map[string]any for Configuration Objects

Impact: High - Difficult to understand expected structure

Examples:

Example 1: Tool configuration parsing

• Location: Throughout pkg/workflow/tools_parser.go
• Current pattern:

  func parseGitHubTool(val any) *GitHubToolConfig {
      configMap, ok := val.(map[string]any)
      if !ok {
          return nil
      }
      // Extract fields with type assertions...
  }

• Suggested fix:

  // Define proper struct tags for YAML unmarshaling
  type GitHubToolRawConfig struct {
      Allowed   []string          `yaml:"allowed"`
      Toolsets  []string          `yaml:"toolsets"`
      Args      []string          `yaml:"args"`
      Token     string            `yaml:"token"`
      ReadOnly  bool              `yaml:"read-only"`
  }
  
  func parseGitHubTool(val any) (*GitHubToolConfig, error) {
      var raw GitHubToolRawConfig
      // Use proper YAML unmarshaling
      return &raw, nil
  }

• Benefits: Schema validation, clearer documentation, IDE support

Example 2: MCP server configuration

• Location: pkg/parser/mcp.go, pkg/workflow/mcp-config-types.go
• Current usage: Heavy use of map[string]any for flexible MCP config
• Analysis: Some typed structs exist (MCPServerConfig, MCPServerInfo) but parsing still uses map[string]any
• Suggested improvement: Complete the typed configuration structs and use proper YAML unmarshaling
• Benefits: Validation at parse time, clearer API

---

Category 3: any Function Parameters

Impact: Medium - API clarity and type safety

Examples:

Example 1: Configuration parsing helpers

• Locations: pkg/workflow/config_helpers.go:322, pkg/workflow/tools_parser.go:148+
• Pattern: Functions accepting any for flexible parsing

  func parseGitHubTool(val any) *GitHubToolConfig
  func parseBashTool(val any) *BashToolConfig
  func parsePlaywrightTool(val any) *PlaywrightToolConfig
  // ... many more

• Analysis: These functions accept any because they're called from YAML unmarshaling which produces map[string]any
• Suggested approach: Use proper YAML unmarshaling with struct tags instead of any + type assertions
• Benefits: Validation at unmarshal time, clearer error messages

Example 2: Value conversion utilities

• Locations: pkg/workflow/metrics.go:211, pkg/workflow/map_helpers.go:35
• Functions: ConvertToInt(val any), ConvertToFloat(val any), parseIntValue(value any)
• Analysis: These are genuinely polymorphic utilities that need any
• Recommendation: Keep as-is - appropriate use of any for generic utilities

---

Category 4: interface{} Usage

Impact: Low - Mostly in test files (acceptable)

Analysis: Found ~30 usages of interface{}, primarily in:

• Test files for unmarshaling YAML (acceptable)
• Comparison functions in tests (acceptable)
• Legacy code that hasn't been migrated to any

Recommendation:

• Low priority - most uses are appropriate
• Consider migrating interface{} → any for consistency with Go 1.18+ idioms

---

Refactoring Recommendations

Priority 1: Critical - Resolve ValidationError Name Collision

Recommendation: Rename one or both ValidationError types to be package-specific

Steps:

1. Choose new names: WorkflowValidationError and CompileValidationError
2. Update type definitions in both files
3. Update all references (use find_referencing_symbols)
4. Run tests to verify

Estimated effort: 1-2 hours
Impact: High - Eliminates naming ambiguity

Affected files:

• pkg/workflow/error_helpers.go
• pkg/cli/compile_config.go
• All files that import these packages

---

Priority 2: High - Introduce Typed Configuration Slices

Recommendation: Replace []any with typed slices for tool configurations

Steps:

1. Define semantic types:

   type BashCommand string
   type GitHubToolName string
   type PlaywrightDomain string

2. Update configuration structs to use these types
3. Update parsing functions to work with typed slices
4. Update test fixtures
5. Run tests

Estimated effort: 8-12 hours
Impact: High - Eliminates ~200 type assertions

Key areas:

• pkg/workflow/tools_types.go - Tool configuration types
• pkg/workflow/tools_parser.go - Parsing logic
• pkg/workflow/claude_tools.go, pkg/workflow/copilot_engine_tools.go - Engine-specific tool handling

---

Priority 3: Medium - Type MCP Configuration Structures

Recommendation: Complete the typed MCP configuration system

Steps:

1. Define complete typed structs for all MCP server types
2. Add YAML struct tags for proper unmarshaling
3. Replace map[string]any parsing with structured unmarshaling
4. Update validation logic
5. Run tests

Estimated effort: 6-8 hours
Impact: Medium - Improves MCP configuration safety

Key areas:

• pkg/parser/mcp.go
• pkg/workflow/mcp-config-types.go
• pkg/workflow/mcp_servers.go

---

Priority 4: Low - Standardize Error Types

Recommendation: Consider a common error interface or base pattern

Steps:

1. Define a common error interface:

   type ContextualError interface {
       error
       Context() map[string]string
       Location() (file string, line int)
   }

2. Update error types to implement this interface
3. Document error handling patterns

Estimated effort: 4-6 hours
Impact: Low-Medium - Improves error consistency

---

Priority 5: Low - Replace interface{} with any

Recommendation: Migrate legacy interface{} to any for Go 1.18+ consistency

Steps:

1. Search for remaining interface{} usages
2. Replace with any where appropriate
3. Run tests

Estimated effort: 1-2 hours
Impact: Low - Modernizes code style

---

Implementation Checklist

• P1: Rename ValidationError types to eliminate name collision
• P2: Define typed command/tool name types (e.g., BashCommand, GitHubToolName)
• P2: Update tool configuration structs to use typed slices
• P2: Update parsing functions to work with typed configurations
• P2: Update all test fixtures and test cases
• P3: Complete MCP configuration type definitions
• P3: Replace map[string]any parsing with structured unmarshaling
• P4: Define and document error interface patterns
• P5: Replace interface{} with any for consistency
• Run full test suite after each priority level
• Update documentation with new type patterns

---

Analysis Methodology

Detection Methods:

1. Pattern matching: Used regex search for type.*struct, interface{}, []any, map[string]any
2. Semantic analysis: Leveraged Serena LSP tooling for symbol-level analysis
3. Cross-reference: Identified duplicate names and similar structural patterns
4. Code reading: Examined specific files to understand usage context

Files Analyzed: 398 Go source files (excluding *_test.go files from primary analysis)

Analysis Coverage:

• ✅ All struct type definitions collected
• ✅ Duplicate type names identified
• ✅ []any usage patterns cataloged
• ✅ map[string]any usage patterns cataloged
• ✅ Function parameter types analyzed
• ✅ Configuration patterns documented

---

Analysis Metadata

• Total Go Files Analyzed: 398
• Total Struct Definitions: 150+
• Duplicate Names Found: 2 exact
• Untyped Slice Occurrences: 200+
• Untyped Map Occurrences: 150+
• Function Parameters with any: 70+
• Detection Method: Serena semantic analysis + regex pattern matching
• Analysis Date: 2026-01-20
• Repository: githubnext/gh-aw
• Branch: main (commit 5001fbb)

---

Next Steps: Review findings with the team and prioritize refactoring based on development roadmap and available resources. The ValidationError name collision should be addressed immediately to prevent confusion.

AI generated by Typist - Go Type Analysis

• expires on Jan 27, 2026, 11:13 AM UTC

[pelikhan]

/plan

[github-actions[bot]]

🎉 Yo ho ho! Plan Command found the treasure and completed successfully! ⚓💰

[github-actions[bot]]

Plan Summary

The type consistency analysis from discussion #10816 has been broken down into 5 actionable sub-issues for implementation:

Created Issues

1. Resolve ValidationError type name collision (P1 - Critical)

   • Eliminates ambiguous duplicate type names in pkg/workflow and pkg/cli
   • Renames to WorkflowValidationError and CompileValidationError

2. Replace []any with typed slices for bash tool commands (P2 - High)

   • Introduces BashCommand and BashCommands types
   • Eliminates ~50+ type assertions in bash tool handling

3. Replace []any with typed slices for GitHub tool configuration (P2 - High)

   • Introduces GitHubToolName, GitHubAllowedTools, GitHubToolset types
   • Removes type assertions from GitHub tool validation

4. Type Playwright tool configuration arrays (P2 - High)

   • Introduces PlaywrightDomain and related types
   • Improves Playwright tool configuration safety

5. Document type pattern guidelines and complete migration (P5 - Low)

   • Updates specs/go-type-patterns.md with examples
   • Completes interface{} → any migration for consistency

Implementation Order

The issues should be implemented in order (1→5), as later issues depend on patterns established by earlier ones. Each issue includes specific file locations, acceptance criteria, and requires make agent-finish validation before committing.

Expected Impact

• Eliminates 200+ runtime type assertions
• Improves compile-time type safety for tool configurations
• Establishes patterns for future configuration additions
• Resolves critical naming ambiguity

The analysis identified additional medium-priority items (MCP configuration typing, error type standardization) that can be addressed in a future planning cycle if needed.