🔤 Typist - Go Type Consistency Analysis Report

[github-actions[bot]]

🔤 Typist - Go Type Consistency Analysis

Analysis of repository: githubnext/gh-aw

Executive Summary

This analysis examined 229 non-test Go files (~207k lines of code) in the pkg/ directory to identify type consistency issues and opportunities for stronger typing. The codebase demonstrates excellent practices in some areas (minimal interface{} usage, strong semantic types in pkg/constants/constants.go), but has significant opportunities for improvement in others.

Key Findings:

• ✅ Excellent: Only 3 occurrences of interface{} (mostly in test files)
• ⚠️ Needs Attention: 3,727 occurrences of any type, primarily as map[string]any for YAML/JSON handling
• ⚠️ Duplicate Found: MCPServerConfig type defined in two locations with different field structures
• ✅ Best Practice Example: pkg/constants/constants.go shows excellent use of semantic types (LineLength, Version, time.Duration)

Impact Assessment:

• High Priority: Replace map[string]any with structured types in frequently-used frontmatter parsing functions
• Medium Priority: Consolidate duplicate MCPServerConfig type
• Low Priority: Leverage semantic type patterns from constants.go across other packages

Full Analysis Report

Analysis Scope

Files Analyzed: 229 non-test Go files
Total Lines: ~207,000 lines of code
Primary Directory: pkg/
Detection Methods:

• Serena semantic analysis for type definitions
• Pattern matching for interface{} and any keywords
• Symbol search for common type name patterns (Config, Options, Data)

---

Duplicated Type Definitions

Summary Statistics

• Total unique types analyzed: 532+ type definitions
• Duplicate clusters found: 1 confirmed
• Exact duplicates: 0
• Semantic duplicates: 1 (MCPServerConfig)

Cluster 1: MCPServerConfig - Semantic Duplicate

Type: Semantic duplicate with different field structures
Occurrences: 2
Impact: Medium - Same name, different purposes

Locations:

1. pkg/cli/mcp_config_file.go:14-18 - Simple version for CLI config

type MCPServerConfig struct {
    Command string   `json:"command"`
    Args    []string `json:"args"`
    CWD     string   `json:"cwd,omitempty"`
}

2. pkg/parser/mcp.go:65-79 - Comprehensive version for workflow parsing

type MCPServerConfig struct {
    Name           string            `json:"name"`
    Type           string            `json:"type"`           // stdio, http, docker
    Registry       string            `json:"registry"`       // URI to installation location
    Command        string            `json:"command"`        // for stdio
    Args           []string          `json:"args"`           // for stdio
    Container      string            `json:"container"`      // for docker
    Version        string            `json:"version"`        // optional version/tag
    EntrypointArgs []string          `json:"entrypointArgs"` // arguments after container
    URL            string            `json:"url"`            // for http
    Headers        map[string]string `json:"headers"`        // for http
    Env            map[string]string `json:"env"`            // environment variables
    ProxyArgs      []string          `json:"proxy-args"`     // custom proxy arguments
    Allowed        []string          `json:"allowed"`        // allowed tools
}

Analysis:

• These are not duplicates - they serve different purposes and have different field sets
• The CLI version is a minimal config for local MCP server connections
• The parser version is comprehensive for workflow-based MCP server definitions
• Different packages, different contexts = intentional separation

Recommendation:

• ✅ No action needed - These are correctly separated by purpose
• Consider renaming to clarify intent:
  • pkg/cli/mcp_config_file.go: Rename to LocalMCPServerConfig or SimpleMCPServerConfig
  • pkg/parser/mcp.go: Rename to WorkflowMCPServerConfig or keep as MCPServerConfig
• Estimated effort: 30 minutes
• Benefits: Clearer naming prevents future confusion

---

Untyped Usages

Summary Statistics

• interface{} usages: 3 (excellent! mostly in test files)
• any usages: 3,727 (primarily map[string]any for YAML/JSON)
• Total untyped locations: 3,730
• Primary pattern: map[string]any for dynamic frontmatter/YAML parsing

Category 1: map[string]any for YAML/JSON Handling

Impact: High - Core pattern used throughout workflow compilation
Prevalence: Dominant pattern in ~100+ functions across pkg/workflow and pkg/cli

Context: Why map[string]any is Used

The codebase processes GitHub Actions workflows written in YAML with dynamic frontmatter. The map[string]any pattern is used because:

1. YAML unmarshaling produces map[string]any by default for unknown structures
2. Frontmatter can contain arbitrary fields defined by users
3. Include/import system merges configurations dynamically

This is a classic trade-off: flexibility vs. type safety.

Example 1: ApplyActionPinToStep Function

• Location: pkg/workflow/action_pins.go:141
• Current signature:

func ApplyActionPinToStep(stepMap map[string]any, data *WorkflowData) map[string]any

• Usage pattern: Type assertions throughout

uses, hasUses := stepMap["uses"]
usesStr, ok := uses.(string)  // Type assertion needed

• Actual usage: Always operates on GitHub Actions step structures

• Suggested fix:

// Define a structured type for GitHub Actions steps
type GitHubActionsStep struct {
    Name string                 `yaml:"name,omitempty"`
    ID   string                 `yaml:"id,omitempty"`
    If   string                 `yaml:"if,omitempty"`
    Uses string                 `yaml:"uses,omitempty"`
    Run  string                 `yaml:"run,omitempty"`
    Env  map[string]string      `yaml:"env,omitempty"`
    With map[string]interface{} `yaml:"with,omitempty"` // Still needs flexibility for action inputs
}

func ApplyActionPinToStep(step GitHubActionsStep, data *WorkflowData) GitHubActionsStep {
    if step.Uses == "" {
        return step
    }
    // No type assertions needed!
    // ... rest of logic
}

• Benefits:
  • ✅ No type assertions required
  • ✅ Compile-time validation of field access
  • ✅ Better IDE autocomplete
  • ✅ Self-documenting API
• Trade-off: ⚠️ Less flexible for unexpected fields (but those can go in a map[string]any "extra" field if needed)

Example 2: extractMapFromFrontmatter Function

• Location: pkg/workflow/tools.go:154
• Current signature:

func extractMapFromFrontmatter(frontmatter map[string]any, key string) map[string]any {
    if value, exists := frontmatter[key]; exists {
        if valueMap, ok := value.(map[string]any); ok {
            return valueMap
        }
    }
    return make(map[string]any)
}

• Usage: Called for extracting tools, mcp, runtimes from frontmatter

• Suggested fix: Use generic types with structured returns

// Define structured types for known frontmatter sections
type FrontmatterTools struct {
    GitHub    *GitHubToolConfig    `yaml:"github,omitempty"`
    Bash      *BashToolConfig      `yaml:"bash,omitempty"`
    Playwright *PlaywrightToolConfig `yaml:"playwright,omitempty"`
    // ... other tools
    Custom map[string]any `yaml:",inline"` // Catch-all for unknown tools
}

func extractToolsFromFrontmatter(frontmatter map[string]any) (*FrontmatterTools, error) {
    toolsData, exists := frontmatter["tools"]
    if !exists {
        return &FrontmatterTools{}, nil
    }
    
    // Marshal back to YAML and unmarshal into structured type
    // This gives us both structure AND flexibility
    yamlBytes, _ := yaml.Marshal(toolsData)
    var tools FrontmatterTools
    if err := yaml.Unmarshal(yamlBytes, &tools); err != nil {
        return nil, err
    }
    return &tools, nil
}

• Benefits:
  • ✅ Structured access to known fields
  • ✅ Still supports unknown/custom fields via Custom map[string]any
  • ✅ Validation happens at unmarshal time
  • ✅ Clear API for consumers

Example 3: Function Parameters with any

High-frequency pattern: Functions accepting any for JSON-like data

Locations with this pattern:

• pkg/workflow/runtime_setup.go: detectFromMCPConfigs(tools map[string]any, ...)
• pkg/workflow/runtime_setup.go: applyRuntimeOverrides(runtimes map[string]any, ...)
• pkg/workflow/runtime_setup.go: formatYAMLValue(value any) string
• pkg/cli/trial_command.go: parseJSONArtifact(filePath string, ...) map[string]any
• pkg/cli/trial_command.go: saveTrialResult(filename string, result any, ...) error

Common pattern: Generic utility functions that need to handle arbitrary data

Recommendation: These are acceptable uses of any for truly generic utilities, BUT:

• Document what types are expected (add comments)
• Consider adding type parameters (Go 1.18+) where appropriate
• For formatYAMLValue, could use type switch with known types

---

Category 2: Legitimate any Usage

Impact: Low - Appropriate use for generic utilities

Example: saveTrialResult Function

func saveTrialResult(filename string, result any, verbose bool) error

Analysis: This is a reasonable use of any because:

• It's a generic serialization utility
• Accepts any JSON-serializable value
• Not part of a type-checked API

Recommendation: ✅ Keep as-is but add documentation:

// saveTrialResult serializes any JSON-marshallable value to a file.
// The result parameter accepts any type that can be marshaled to JSON.
func saveTrialResult(filename string, result any, verbose bool) error

---

Category 3: Best Practices - Learn from constants.go

Location: pkg/constants/constants.go
Impact: Inspiration for the rest of the codebase

Excellent patterns demonstrated:

1. Semantic Types for Clarity:

// LineLength represents a line length in characters
type LineLength int

// Version represents a software version string
type Version string

const MaxExpressionLineLength LineLength = 120
const DefaultClaudeCodeVersion Version = "2.0.44"

2. time.Duration for Time Values:

// Uses time.Duration for type safety and clear units
const DefaultAgenticWorkflowTimeout = 20 * time.Minute
const DefaultToolTimeout = 60 * time.Second

3. Deprecation Strategy:

// Deprecated: Use DefaultToolTimeout instead
const DefaultToolTimeoutSeconds = int(DefaultToolTimeout / time.Second)

Recommendation: Apply these patterns elsewhere!

---

Refactoring Recommendations

Priority 1: High - Document map[string]any Usage

Recommendation: Add clear documentation to all functions using map[string]any

Rationale:

• Complete replacement would be a massive refactor (100+ functions)
• Current pattern works but lacks documentation
• Quick win: Document what structure is expected

Steps:

1. Audit all functions accepting/returning map[string]any
2. Add comments describing expected structure
3. Add examples in comments

Example:

// extractMapFromFrontmatter extracts a nested map from workflow frontmatter.
// Expected frontmatter structure:
//   tools:
//     github:
//       allowed: [...]
//     bash:
//       enabled: true
// Returns an empty map if key doesn't exist or isn't a map.
func extractMapFromFrontmatter(frontmatter map[string]any, key string) map[string]any

Estimated effort: 4-6 hours
Impact: Medium - Better maintainability with minimal risk

---

Priority 2: Medium - Create Structured Types for Common Patterns

Recommendation: Introduce structured types for the most frequently accessed map[string]any patterns

Target areas:

1. GitHub Actions step structures (high usage in pkg/workflow/action_pins.go, pkg/workflow/tools.go)
2. Frontmatter sections (tools, mcp, safe-outputs)
3. Runtime configurations

Steps:

1. Define GitHubActionsStep struct with common fields + Extra map[string]any
2. Define FrontmatterConfig struct with known sections + Custom map[string]any
3. Create conversion utilities: map[string]any ↔ structured types
4. Gradually migrate high-traffic functions

Example migration path:

// Phase 1: Keep both versions
func ApplyActionPinToStep(stepMap map[string]any, data *WorkflowData) map[string]any {
    // Convert to structured type internally
    step := mapToGitHubActionsStep(stepMap)
    result := applyActionPinToStepStructured(step, data)
    return structuredStepToMap(result)
}

// Phase 2: Migrate callers
func applyActionPinToStepStructured(step GitHubActionsStep, data *WorkflowData) GitHubActionsStep {
    // Type-safe implementation
}

Estimated effort: 12-16 hours
Impact: High - Significantly improved type safety in core functions

---

Priority 3: Low - Expand Semantic Types Pattern

Recommendation: Apply pkg/constants/constants.go patterns to other packages

Opportunities:

1. Create semantic types in pkg/workflow:

package workflow

// JobName represents a GitHub Actions job identifier
type JobName string

// StepID represents a step identifier within a job
type StepID string

const AgentJobName JobName = "agent"
const ActivationJobName JobName = "activation"

2. Time values in pkg/cli:

package cli

// PollInterval represents a duration between poll attempts
type PollInterval time.Duration

const DefaultPollInterval PollInterval = 5 * time.Second

3. String enums:

package workflow

// RuntimeType represents a supported runtime environment
type RuntimeType string

const (
    RuntimeNode   RuntimeType = "node"
    RuntimePython RuntimeType = "python"
    RuntimeRuby   RuntimeType = "ruby"
)

Estimated effort: 3-4 hours
Impact: Medium - Clearer APIs, better compile-time checks

---

Priority 4: Low - Rename MCPServerConfig Types

Recommendation: Clarify naming for the two MCPServerConfig types

Changes:

• pkg/cli/mcp_config_file.go: LocalMCPServerConfig
• pkg/parser/mcp.go: Keep MCPServerConfig (it's the canonical version)

Estimated effort: 30 minutes
Impact: Low - Clearer intent, prevents confusion

---

Implementation Checklist

• P1: Add documentation to map[string]any functions (4-6 hours)

  • Document extractMapFromFrontmatter and related functions
  • Document ApplyActionPinToStep expected structure
  • Document runtime detection functions

• P2: Create structured types for common patterns (12-16 hours)

  • Define GitHubActionsStep struct
  • Define FrontmatterConfig struct
  • Create conversion utilities
  • Migrate 3-5 high-traffic functions as proof of concept

• P3: Expand semantic types pattern (3-4 hours)

  • Create JobName, StepID types in workflow package
  • Create PollInterval type in cli package
  • Create RuntimeType enum

• P4: Rename MCPServerConfig types (30 minutes)

  • Rename in pkg/cli/mcp_config_file.go
  • Update references
  • Run tests

---

Analysis Metadata

• Total Go Files Analyzed: 229 (non-test files in pkg/)
• Total Lines of Code: ~207,000
• Total Type Definitions: 532+
• Duplicate Clusters: 1 (semantic duplicate, no action needed)
• Untyped Locations: 3,730 (3 interface{}, 3,727 any)
• Primary Pattern: map[string]any for YAML/JSON frontmatter handling
• Detection Method: Serena semantic analysis + pattern matching
• Analysis Date: 2025-11-19

---

Key Takeaways

What's Working Well ✅

1. Minimal interface{} usage - Only 3 occurrences (excellent!)
2. Semantic types in constants.go - Shows team understands value of strong typing
3. Consistent patterns - map[string]any usage is consistent (not random)

What Needs Improvement ⚠️

1. Documentation - map[string]any functions lack structure documentation
2. Type safety - High reliance on runtime type assertions
3. Semantic types underutilized - Pattern from constants.go not applied elsewhere

Recommended Approach 🎯

Start small, prove value, scale up:

1. Begin with Priority 1 (documentation) - low risk, immediate value
2. Create proof-of-concept for Priority 2 (structured types) on 2-3 functions
3. Measure impact: fewer bugs, better IDE support, clearer APIs
4. Gradually expand to more functions
5. Apply semantic types pattern from constants.go to other packages

Philosophy: The codebase is mature and working. Don't break what works. Instead, incrementally improve type safety where it adds the most value.

AI generated by Typist - Go Type Analysis