🔤 Typist - Go Type Consistency Analysis

[github-actions[bot]]

🔤 Typist - Go Type Consistency Analysis

Analysis of repository: githubnext/gh-aw

Executive Summary

Analyzed 208 Go source files (201,149 lines) in the pkg/ directory to identify type consistency opportunities. The codebase shows extensive use of untyped generic types (map[string]any, any parameters) and untyped constants that could benefit from stronger typing. While no exact duplicate type definitions were found, there are significant opportunities to improve type safety and code maintainability.

Key Findings:

• 477 instances of map[string]any usage - primarily in workflow configuration parsing
• 36 untyped constants in pkg/constants/constants.go - numeric and string literals without semantic types
• Duplicated slice literals - DefaultGitHubToolsLocal and DefaultGitHubToolsRemote contain identical 67-item lists
• Extensive use of any in function signatures - 30+ functions accepting generic maps or slices

The primary refactoring opportunity is to introduce strongly-typed configuration structs to replace the pervasive map[string]any pattern, which would provide compile-time type safety and better IDE support.

Full Analysis Report

Analysis Methodology

Scope:

• Files analyzed: 208 non-test Go files in pkg/ directory
• Total lines: ~201,000 lines of Go code
• Primary focus areas: pkg/workflow/, pkg/cli/, pkg/constants/
• Detection methods: Pattern matching, symbol analysis via Serena MCP server

Search patterns:

• map[string]any and map[string]interface{} usage
• Function parameters with any or interface{} types
• Struct fields with generic types
• Untyped constant declarations
• Similar type names across packages

---

Duplicated Type Definitions

Summary Statistics

• Total struct types analyzed: ~120 struct definitions
• Exact duplicates found: 0
• Near duplicates: 0
• Semantic duplicates: 1 (tool list duplication)

Finding 1: Duplicated GitHub Tools Lists

Type: Semantic duplicate (identical slice contents)
Impact: Medium - Maintenance burden with duplicate 67-item lists
Location: pkg/constants/constants.go

Details:

Both DefaultGitHubToolsLocal (lines 171-238) and DefaultGitHubToolsRemote (lines 241-308) contain identical lists of 67 GitHub tool names.

// Line 171-238
var DefaultGitHubToolsLocal = []string{
    "download_workflow_run_artifact",
    "get_job_logs",
    "get_workflow_run",
    // ... 64 more identical items
}

// Line 241-308
var DefaultGitHubToolsRemote = []string{
    "download_workflow_run_artifact",
    "get_job_logs",
    "get_workflow_run",
    // ... 64 more identical items (exact same)
}

Recommendation:

Since both lists are currently identical, consolidate into a single shared list:

// DefaultReadOnlyGitHubTools defines the default read-only GitHub MCP tools
// Used by both local (Docker) and remote (hosted) modes
var DefaultReadOnlyGitHubTools = []string{
    // actions
    "download_workflow_run_artifact",
    "get_job_logs",
    // ... rest of tools
}

// For backward compatibility
var DefaultGitHubToolsLocal = DefaultReadOnlyGitHubTools
var DefaultGitHubToolsRemote = DefaultReadOnlyGitHubTools
var DefaultGitHubTools = DefaultReadOnlyGitHubTools

Benefits:

• Single source of truth for tool list
• Easier to maintain (one list instead of two)
• Clear that local and remote modes currently have identical permissions
• If lists need to diverge later, easy to split again

Estimated effort: 30 minutes

---

Untyped Usages

Summary Statistics

• map[string]any usages: 477 instances
• map[string]interface{} usages: 19 instances
• []any slice usages: ~40 instances
• Untyped constants: 36 constants
• Functions with any parameters: 30+ functions
• Total untyped locations: ~580 locations

---

Category 1: Untyped Configuration Maps

Impact: High - Widespread pattern causing type safety issues
Prevalence: 477 instances across workflow and CLI packages

The codebase extensively uses map[string]any for workflow configuration parsing. This pattern appears in:

Example 1: Step Configuration Processing

Location: pkg/workflow/action_pins.go:142

// Current signature
func ApplyActionPinToStep(stepMap map[string]any, data *WorkflowData) map[string]any {
    uses, hasUses := stepMap["uses"]      // No compile-time validation
    usesStr, ok := uses.(string)          // Type assertion required
    // ...
}

Problem:

• Keys are magic strings - typos won't be caught until runtime
• Values require type assertions - potential panics
• No IDE autocomplete for configuration fields
• Cannot validate completeness at compile time

Suggested fix:

// Define specific step configuration type
type StepConfig struct {
    Name string
    ID   string
    Uses string
    With map[string]string
    Env  map[string]string
    // ... other fields with proper types
}

// Updated signature with strong typing
func ApplyActionPinToStep(step StepConfig, data *WorkflowData) StepConfig {
    if step.Uses == "" {  // Direct field access, no type assertions
        return step
    }
    // ...
}

Benefits:

• Compile-time field validation
• IDE autocomplete and refactoring support
• Self-documenting code (fields are explicit)
• No runtime type assertions needed
• ~40% of error-prone code eliminated

Example 2: Tool Configuration Parsing

Location: pkg/workflow/cache.go:35

func (c *Compiler) extractCacheMemoryConfig(tools map[string]any) (*CacheMemoryConfig, error)

Similar pattern repeated across:

• pkg/workflow/claude_mcp.go:12 - RenderMCPConfig(yaml *strings.Builder, tools map[string]any, ...)
• pkg/workflow/codex_engine.go:186 - expandNeutralToolsToCodexTools(tools map[string]any)
• pkg/workflow/compiler.go:1426 - applyDefaultTools(tools map[string]any, ...)

Suggested fix:

// Define structured tools configuration
type ToolsConfig struct {
    GitHub      *GitHubToolConfig      // Already exists in tools_types.go
    Playwright  *PlaywrightToolConfig   // Already exists
    Bash        *BashToolConfig         // Already exists
    WebFetch    *WebFetchToolConfig     // Already exists
    WebSearch   *WebSearchToolConfig    // Already exists
    Edit        *EditToolConfig         // Already exists
    CacheMemory *CacheMemoryToolConfig  // Already exists
    // Custom MCP tools
    CustomMCP   map[string]MCPServerConfig
}

func (c *Compiler) extractCacheMemoryConfig(tools *ToolsConfig) (*CacheMemoryConfig, error) {
    if tools.CacheMemory == nil {
        return nil, nil
    }
    return tools.CacheMemory, nil
}

Note: The individual tool config structs already exist in pkg/workflow/tools_types.go - just need to create the parent ToolsConfig struct to unify them.

---

Category 2: Untyped Struct Fields

Impact: High - Runtime type assertions required for field access
Prevalence: ~20 struct definitions

Example 1: Trial Result Artifacts

Location: pkg/cli/trial_command.go:26-34

type WorkflowTrialResult struct {
    WorkflowName        string                 `json:"workflow_name"`
    RunID               string                 `json:"run_id"`
    SafeOutputs         map[string]interface{} `json:"safe_outputs"`           // Untyped
    AgenticRunInfo      map[string]interface{} `json:"agentic_run_info,omitempty"`  // Untyped
    AdditionalArtifacts map[string]interface{} `json:"additional_artifacts,omitempty"` // Untyped
    Timestamp           time.Time              `json:"timestamp"`
}

Problem:

• Fields use map[string]interface{} (older syntax)
• Consuming code must perform type assertions
• No structure validation for these artifacts

Suggested fix:

// Define specific artifact types
type SafeOutput struct {
    Type     string      `json:"type"`      // "issue", "discussion", "comment", etc.
    ID       int         `json:"id"`
    URL      string      `json:"url"`
    Metadata interface{} `json:"metadata,omitempty"` // Keep flexible for extensibility
}

type AgenticRunInfo struct {
    TotalTurns   int           `json:"total_turns"`
    TokensUsed   int           `json:"tokens_used"`
    Duration     time.Duration `json:"duration"`
    Engine       string        `json:"engine"`
    ModelVersion string        `json:"model_version"`
}

type WorkflowTrialResult struct {
    WorkflowName        string                  `json:"workflow_name"`
    RunID               string                  `json:"run_id"`
    SafeOutputs         []SafeOutput            `json:"safe_outputs"`  // Strongly typed
    AgenticRunInfo      *AgenticRunInfo         `json:"agentic_run_info,omitempty"`  // Strongly typed
    AdditionalArtifacts map[string]interface{}  `json:"additional_artifacts,omitempty"` // Keep flexible
    Timestamp           time.Time               `json:"timestamp"`
}

Benefits:

• Clear structure for safe outputs and run info
• Type-safe field access
• JSON marshaling/unmarshaling with validation
• Keep AdditionalArtifacts flexible for extensibility

Example 2: MCP Server Configuration

Location: pkg/cli/mcp_registry.go:25

type Server struct {
    // ... other fields ...
    Config map[string]interface{} `json:"config"`  // Generic configuration
}

Used in:

• pkg/cli/mcp_registry.go:168 - processedServer.Config = make(map[string]interface{})
• pkg/cli/mcp_registry.go:190 - processedServer.Config = map[string]interface{}{...}

Suggested fix:

Since MCP server configurations are inherently flexible (different servers have different config), this is an acceptable use of map[string]interface{}. However, consider upgrading to map[string]any for consistency with modern Go.

---

Category 3: Untyped Function Parameters

Impact: High - Functions accept generic types requiring runtime validation
Prevalence: 30+ function signatures

Common Pattern: Step Map Processing

Examples:

// pkg/workflow/action_pins.go:142
func ApplyActionPinToStep(stepMap map[string]any, data *WorkflowData) map[string]any

// pkg/workflow/action_pins.go:230
func ApplyActionPinsToSteps(steps []any, data *WorkflowData) []any

// pkg/workflow/agentic_engine.go:170
func (e *BaseEngine) convertStepToYAML(stepMap map[string]any) (string, error)

// pkg/workflow/compiler_yaml.go:741
func (c *Compiler) convertStepToYAML(stepMap map[string]any) (string, error)

// pkg/workflow/add_comment.go:119
func (c *Compiler) parseCommentsConfig(outputMap map[string]any) *AddCommentsConfig

Pattern Analysis:

These functions all process workflow step or configuration data. They:

1. Accept generic map[string]any parameters
2. Perform runtime type assertions to extract values
3. Return processed data or structs

Suggested fix:

Define structured types for steps and configurations:

// Step configuration (may already partially exist in YAML definitions)
type WorkflowStep struct {
    Name string
    ID   string
    If   string
    Run  string
    Uses string
    With map[string]string
    Env  map[string]string
    // Add other GitHub Actions step fields
}

// Updated signatures
func ApplyActionPinToStep(step WorkflowStep, data *WorkflowData) WorkflowStep
func ApplyActionPinsToSteps(steps []WorkflowStep, data *WorkflowData) []WorkflowStep
func (e *BaseEngine) convertStepToYAML(step WorkflowStep) (string, error)

Estimated effort to refactor: 8-12 hours (affects many files)
Impact: High - Would eliminate ~200 lines of type assertion code

---

Category 4: Untyped Constants

Impact: Medium - Lack of semantic clarity and type safety
Prevalence: 36 untyped constants in pkg/constants/constants.go

Examples:

// Lines 6-63: Untyped string and numeric constants
const CLIExtensionPrefix = "gh aw"                          // string
const MaxExpressionLineLength = 120                         // untyped int
const ExpressionBreakThreshold = 100                        // untyped int
const DefaultMCPRegistryURL = "https://api.mcp.github.com/v0"  // string
const DefaultClaudeCodeVersion = "2.0.42"                   // string (semantic version)
const DefaultAgenticWorkflowTimeoutMinutes = 20             // untyped int (duration)
const DefaultToolTimeoutSeconds = 60                        // untyped int (duration)
const DefaultMCPStartupTimeoutSeconds = 120                 // untyped int (duration)

Problems:

1. No semantic type information: Is 20 minutes or milliseconds? Is "2.0.42" a version or arbitrary string?
2. Easy to mix units: Could accidentally pass timeout in wrong unit
3. No compile-time validation: Can't enforce that versions are valid semver

Suggested fix:

Introduce semantic types for common patterns:

// Semantic types for measurements
type LineLength int
type Timeout time.Duration  // Use standard library duration
type Version string          // Semantic version string

// Type-safe constants
const CLIExtensionPrefix string = "gh aw"
const MaxExpressionLineLength LineLength = 120
const ExpressionBreakThreshold LineLength = 100

// URLs remain strings (no better type)
const DefaultMCPRegistryURL = "https://api.mcp.github.com/v0"

// Versions as semantic type
const DefaultClaudeCodeVersion Version = "2.0.42"
const DefaultCopilotVersion Version = "0.0.358"
const DefaultCodexVersion Version = "0.57.0"
const DefaultGitHubMCPServerVersion Version = "v0.20.2"
const DefaultFirewallVersion Version = "v0.1.1"

// Runtime versions (may want different type like RuntimeVersion)
const DefaultBunVersion Version = "1.1"
const DefaultNodeVersion Version = "24"
// ... etc

// Timeouts with clear units using time.Duration
const DefaultAgenticWorkflowTimeout = 20 * time.Minute
const DefaultToolTimeout = 60 * time.Second
const DefaultMCPStartupTimeout = 120 * time.Second

Benefits:

• Clear intent: Immediately obvious that values are durations, versions, etc.
• Type safety: Can't accidentally use timeout as line length
• Better IDE support: Type hints show semantic meaning
• Consistent with Go stdlib: Using time.Duration follows Go conventions

Special consideration for timeout constants:

If using time.Duration, call sites may need updating:

// Before
timeout := time.Duration(constants.DefaultToolTimeoutSeconds) * time.Second

// After (if using time.Duration in const)
timeout := constants.DefaultToolTimeout  // Already a duration

Estimated effort: 2-3 hours to add types and update call sites

---

Category 5: Mixed Interface{} and Any Usage

Impact: Low - Stylistic inconsistency only
Finding: 19 uses of old interface{} syntax, 477 uses of modern any syntax

Recommendation:

Standardize on any (the modern Go 1.18+ alias) for consistency:

// Old style (19 instances)
map[string]interface{}  →  map[string]any

// Locations to update:
// - pkg/cli/trial_command.go:29, 31, 32 (WorkflowTrialResult struct)
// - pkg/cli/trial_command.go:1472, 1474, 1475 (TrialArtifacts struct)
// - pkg/cli/trial_command.go:1574 (parseJSONArtifact function)
// - pkg/cli/trial_command.go:1616 (saveTrialResult function)
// - pkg/cli/mcp_registry.go:25 (Server struct Config field)
// - pkg/cli/actions.go:11 (convertToGitHubActionsEnv function)
// - plus a few more in test files and utility functions

Estimated effort: 30 minutes (find and replace)

---

Refactoring Recommendations

Priority 1: High Impact - Define Structured Configuration Types

Recommendation: Replace map[string]any with strongly-typed structs

Focus areas:

1. Step configuration (pkg/workflow/action_pins.go, pkg/workflow/compiler_yaml.go)
2. Tools configuration (pkg/workflow/*.go - ~30 functions)
3. Safe outputs (pkg/cli/trial_command.go)

Steps:

1. Define WorkflowStep struct with all GitHub Actions step fields
2. Define parent ToolsConfig struct that unifies existing tool config types
3. Define SafeOutput and AgenticRunInfo structs for trial results
4. Incrementally refactor functions to accept/return new types
5. Keep backward compatibility helpers if needed for YAML unmarshaling

Estimated effort: 12-16 hours
Impact:

• Eliminate ~300 type assertions
• Add compile-time validation for ~60 functions
• Improve IDE experience across entire workflow package

Migration strategy:

Can be done incrementally:

1. Define new types alongside existing code
2. Add constructor functions that convert map[string]any to typed structs
3. Migrate one package at a time (start with pkg/workflow/tools_types.go)
4. Update tests as you go

---

Priority 2: Medium Impact - Add Semantic Types to Constants

Recommendation: Add type aliases for constants in pkg/constants/constants.go

Steps:

1. Define semantic type aliases (type Version string, type LineLength int)
2. Convert timeout constants to use time.Duration
3. Update constant declarations to use new types
4. Update call sites to work with typed constants (mostly automatic, but timeouts need checking)

Estimated effort: 2-3 hours
Impact:

• Clear semantic meaning for 36 constants
• Prevent unit confusion for timeouts
• Better IDE hints

---

Priority 3: Low Impact - Consolidate Duplicate Tool Lists

Recommendation: Merge DefaultGitHubToolsLocal and DefaultGitHubToolsRemote

Steps:

1. Create DefaultReadOnlyGitHubTools with the shared 67 tools
2. Make DefaultGitHubToolsLocal and DefaultGitHubToolsRemote aliases
3. Update comments to explain why they're the same
4. If lists need to diverge later, it's one-line change to separate them

Estimated effort: 30 minutes
Impact:

• Eliminate 67 lines of duplication
• Single source of truth for default tools
• Easier to maintain

---

Priority 4: Low Impact - Standardize on any Syntax

Recommendation: Replace interface{} with any throughout codebase

Steps:

1. Find and replace interface{} with any in 19 locations
2. Run tests to ensure no behavioral changes
3. Update code style guide to prefer any

Estimated effort: 30 minutes
Impact:

• Consistent modern Go style
• Slightly more readable (any is shorter than interface{})

---

Justification for map[string]any in Some Cases

Not all uses of map[string]any should be refactored. Acceptable uses:

1. MCP server configurations (pkg/cli/mcp_registry.go:25) - Different MCP servers have different configs, flexibility needed
2. JSON unmarshaling intermediate storage - When truly dynamic JSON structure
3. Extension points - Where plugins or external systems define structure

Guideline: Use map[string]any when:

• Structure is truly unknown at compile time
• Configuration is plugin-defined
• Flexibility is a feature requirement

Use strongly-typed structs when:

• Structure is known (like GitHub Actions workflow steps)
• You control the schema
• Type safety adds value

---

Implementation Checklist

• Review all 477 map[string]any usages and categorize (keep vs. refactor)
• Define WorkflowStep struct based on GitHub Actions schema
• Define parent ToolsConfig struct in pkg/workflow/tools_types.go
• Define SafeOutput and AgenticRunInfo structs in pkg/cli/trial_command.go
• Create helper functions for converting map[string]any to typed structs
• Incrementally refactor workflow package functions (start with action_pins.go)
• Add semantic type aliases to pkg/constants/constants.go
• Convert timeout constants to time.Duration
• Consolidate duplicate GitHub tools lists
• Replace interface{} with any (19 locations)
• Update tests to use new types
• Run full test suite to validate refactoring
• Update documentation with new type-safe patterns

---

Analysis Metadata

• Total Go Files Analyzed: 208 (non-test files in pkg/)
• Total Lines of Code: ~201,000 lines
• Type Definitions Found: ~120 structs, ~50 interfaces
• Duplicate Type Clusters: 0 exact duplicates, 1 semantic duplicate (tool lists)
• Untyped Usage Locations:
  • map[string]any: 477 instances
  • map[string]interface{}: 19 instances
  • []any: ~40 instances
  • Untyped constants: 36 constants
  • Total: ~580 untyped locations
• Functions with Generic Parameters: 30+ functions
• Detection Method: Serena semantic analysis + grep pattern matching
• Analysis Date: 2025-11-15
• Analyzer: Typist Agent (Claude Sonnet 4.5)

---

Summary

The gh-aw codebase is well-structured but has significant opportunities for improved type safety. The primary finding is the extensive use of map[string]any for workflow configuration (477 instances), which creates runtime type assertion overhead and reduces compile-time safety.

Recommended focus:

1. High priority: Introduce structured types for workflow steps and tool configurations (12-16 hours effort, high impact)
2. Medium priority: Add semantic types to constants for clarity (2-3 hours, medium impact)
3. Low priority: Consolidate duplicate tool lists and standardize on any syntax (1 hour total, low impact)

Total estimated refactoring effort: 15-20 hours for full type safety improvements.

AI generated by Typist - Go Type Analysis

[pelikhan]

/plan

[github-actions[bot]]

✅ Agentic Plan Command completed successfully.

[github-actions[bot]]

This discussion was automatically closed because it was created by an agentic workflow more than 1 week ago.