🔤 Typist - Go Type Consistency Analysis

[github-actions[bot]]

🔤 Typist - Go Type Consistency Analysis

Analysis of repository: githubnext/gh-aw

Executive Summary

This analysis examined 223 Go source files (excluding tests) in the pkg/ directory to identify type consistency opportunities. The codebase demonstrates excellent type discipline in many areas, particularly with semantic types like LineLength and Version in pkg/constants/constants.go. However, there are significant opportunities to improve type safety in the YAML/frontmatter parsing layer, where map[string]any is heavily used (521 occurrences).

Key Findings:

• ✅ Strong foundation: Zero uses of interface{}, excellent semantic types for constants
• ⚠️ Primary opportunity: 521 occurrences of map[string]any in YAML parsing code
• ⚠️ Secondary opportunity: 110 occurrences of []any for dynamic slices
• 📊 Total types analyzed: 232 struct/interface definitions
• 🎯 Focus areas: pkg/workflow/ directory (68 functions using map[string]any)

The most impactful improvements would come from introducing strongly-typed frontmatter structures to replace generic map[string]any usage in the workflow compiler and related YAML parsing code.

Full Analysis Report

Analysis Methodology

Files Analyzed: 223 non-test Go files in pkg/ directory

Detection Approach:

1. Pattern matching for interface{}, any, map[string]any, and []any
2. Symbol analysis using Serena semantic tools
3. Type definition clustering by name and structure
4. Manual review of high-impact files

Key Statistics:

• interface{} usages: 0 (excellent!)
• any keyword occurrences: ~845
• map[string]any occurrences: 521
• []any occurrences: 110
• Functions using map[string]any: 117
• Struct/interface type definitions: 232

---

Part 1: Type Definition Analysis

Summary Statistics

• Total type definitions: 232 structs and interfaces
• Config-related types: 48 types with names containing "Config", "Option", or "Setting"
• Duplicate clusters found: 0 significant duplicates
• Assessment: ✅ Excellent - No problematic duplication detected

Key Finding: Well-Organized Type Structure

The codebase demonstrates excellent organization with no significant type duplication. Config types are well-scoped:

Example: Well-Organized Config Types (pkg/workflow/tools_types.go)

// Each tool has its own distinct configuration type
type GitHubToolConfig struct { ... }
type PlaywrightToolConfig struct { ... }
type BashToolConfig struct { ... }
type WebFetchToolConfig struct { ... }
type WebSearchToolConfig struct { ... }
type EditToolConfig struct { ... }
type AgenticWorkflowsToolConfig struct { ... }
type CacheMemoryToolConfig struct { ... }

These types are intentionally distinct and serve different purposes. No consolidation is recommended.

Example: Appropriate Config Specialization

// pkg/workflow/compiler.go
type BaseSafeOutputConfig struct { ... }
type SafeOutputsConfig struct { ... }     // Extends base config
type SecretMaskingConfig struct { ... }   // Specialized purpose

// pkg/workflow/safe_outputs.go
type GitHubScriptStepConfig struct { ... }
type SafeOutputJobConfig struct { ... }

Each configuration type serves a specific domain and has distinct fields. The naming clearly indicates their scope and purpose.

Recommendation: Type Duplication

Status: ✅ No action needed

The codebase has excellent type organization. No duplicate consolidation is recommended.

---

Part 2: Untyped Usage Analysis

Summary Statistics

• interface{} usages: 0 ✅ (excellent!)
• any usages: ~845 total
  • map[string]any: 521 occurrences ⚠️
  • []any: 110 occurrences ⚠️
  • Other any usages: ~214
• Impact: Medium-High - Primarily affects YAML/frontmatter parsing layer

---

Category 1: map[string]any in Frontmatter Parsing

Impact: ⚠️ High - Core workflow compiler uses untyped maps extensively

Problem Statement

The workflow compiler parses YAML frontmatter into map[string]any and passes it through many functions. This creates:

• Runtime type assertions throughout the codebase
• No compile-time validation of frontmatter structure
• Difficult to understand what fields are expected
• Easy to introduce bugs with typos in field names

High-Impact Files

pkg/workflow/compiler.go: 33 occurrences of map[string]any
pkg/workflow/tools.go: 22 occurrences of map[string]any
pkg/workflow/runtime_setup.go: 10 occurrences of map[string]any

Example 1: WorkflowData with Untyped Fields

Location: pkg/workflow/compiler.go:190-243

Current Implementation:

type WorkflowData struct {
    Name                string
    Description         string
    Source              string
    // ... many fields ...
    Tools               map[string]any        // ⚠️ Untyped!
    CommandOtherEvents  map[string]any        // ⚠️ Untyped!
    Jobs                map[string]any        // ⚠️ Untyped!
    Runtimes            map[string]any        // ⚠️ Untyped!
    // ... more fields ...
}

Analysis: WorkflowData mixes strongly-typed fields (good!) with untyped map fields (problematic). The struct demonstrates the codebase's transition toward better typing but isn't complete.

Example 2: Frontmatter Extraction Functions

Pattern: Many functions accept frontmatter map[string]any parameter

Locations:

• pkg/workflow/frontmatter_extraction.go - 15+ functions
• pkg/workflow/engine.go:42 - ExtractEngineConfig(frontmatter map[string]any)
• pkg/workflow/filters.go - Multiple filter functions
• pkg/workflow/manual_approval.go - Approval extraction
• pkg/workflow/tools.go - Tool configuration parsing

Current Pattern:

// pkg/workflow/frontmatter_extraction.go
func (c *Compiler) extractYAMLValue(frontmatter map[string]any, key string) string {
    if value, exists := frontmatter[key]; exists {
        // Type assertion required
        if strValue, ok := value.(string); ok {
            return strValue
        }
    }
    return ""
}

// pkg/workflow/tools.go
func extractToolsFromFrontmatter(frontmatter map[string]any) map[string]any {
    if value, exists := frontmatter["tools"]; exists {
        if valueMap, ok := value.(map[string]any); ok {
            return valueMap
        }
    }
    return make(map[string]any)
}

Problem: Every access requires:

1. Check if key exists
2. Type assertion with ok-check
3. Default value handling
4. Risk of runtime panics if type assumption is wrong

Example 3: Function Signatures Throughout Workflow Package

Sample from analysis:

// pkg/workflow/compiler_jobs.go:762
func (c *Compiler) extractJobsFromFrontmatter(frontmatter map[string]any) map[string]any

// pkg/workflow/engine.go:42
func (c *Compiler) ExtractEngineConfig(frontmatter map[string]any) (string, *EngineConfig)

// pkg/workflow/manual_approval.go
func (c *Compiler) extractManualApprovalFromOn(frontmatter map[string]any) (string, error)
func (c *Compiler) processManualApprovalConfiguration(frontmatter map[string]any, workflowData *WorkflowData) error

// pkg/workflow/filters.go
func (c *Compiler) applyPullRequestDraftFilter(data *WorkflowData, frontmatter map[string]any)
func (c *Compiler) applyPullRequestForkFilter(data *WorkflowData, frontmatter map[string]any)
func (c *Compiler) applyLabelFilter(data *WorkflowData, frontmatter map[string]any)

Count: 68 functions in pkg/workflow/ accept map[string]any parameters, primarily for frontmatter parsing.

Suggested Improvement: Frontmatter Type

Recommendation: Create a strongly-typed Frontmatter struct to replace map[string]any

Proposed Solution:

// pkg/workflow/frontmatter_types.go (NEW FILE)

// Frontmatter represents the structured YAML frontmatter of a workflow file
type Frontmatter struct {
    // Workflow metadata
    Name        string            `yaml:"name"`
    Description string            `yaml:"description"`
    Source      string            `yaml:"source"`
    Campaign    string            `yaml:"campaign"`
    
    // Trigger configuration
    On          OnConfiguration   `yaml:"on"`
    If          string            `yaml:"if"`
    
    // Execution configuration
    Permissions PermissionsConfig `yaml:"permissions"`
    Network     NetworkConfig     `yaml:"network"`
    Concurrency string            `yaml:"concurrency"`
    RunName     string            `yaml:"run-name"`
    Env         EnvConfig         `yaml:"env"`
    
    // Tool configuration
    Tools       ToolsConfiguration `yaml:"tools"`
    Runtimes    RuntimesConfig     `yaml:"runtimes"`
    
    // Job configuration
    Jobs        JobsConfiguration  `yaml:"jobs"`
    
    // Import configuration
    Imports     []string          `yaml:"imports"`
    
    // Agent configuration
    AI          string            `yaml:"ai"`
    Engine      EngineConfig      `yaml:"engine"`
    
    // Safety and permissions
    Roles       []string          `yaml:"roles"`
    StopAfter   string            `yaml:"stop-after"`
    
    // Advanced configuration
    Features    map[string]bool   `yaml:"features"`
    SafeOutputs SafeOutputsConfig `yaml:"safe-outputs"`
    
    // Filtering
    Filters     FiltersConfig     `yaml:"filters"`
}

// OnConfiguration represents the workflow trigger configuration
type OnConfiguration struct {
    // Can be string (single event) or complex event configuration
    // Needs custom unmarshaler for flexibility
    Events map[string]EventConfig
}

// ToolsConfiguration represents the tools section of frontmatter
type ToolsConfiguration struct {
    GitHub     interface{} `yaml:"github"`      // Can be string, []string, or GitHubToolConfig
    Bash       interface{} `yaml:"bash"`        // Can be string, []string, or BashToolConfig
    Playwright interface{} `yaml:"playwright"`  // Can be PlaywrightToolConfig
    WebFetch   interface{} `yaml:"web-fetch"`   // Can be WebFetchToolConfig
    WebSearch  interface{} `yaml:"web-search"`  // Can be WebSearchToolConfig
    Edit       interface{} `yaml:"edit"`        // Can be EditToolConfig
    // Add MCP servers and other tools
}

// RuntimesConfig represents runtime version overrides
type RuntimesConfig struct {
    Node    string `yaml:"node"`
    Python  string `yaml:"python"`
    Bun     string `yaml:"bun"`
    Ruby    string `yaml:"ruby"`
    DotNet  string `yaml:"dotnet"`
    Java    string `yaml:"java"`
    Elixir  string `yaml:"elixir"`
    Haskell string `yaml:"haskell"`
    Deno    string `yaml:"deno"`
}

// JobsConfiguration represents custom job definitions
type JobsConfiguration map[string]JobDefinition

type JobDefinition struct {
    Name        string                 `yaml:"name"`
    RunsOn      string                 `yaml:"runs-on"`
    Needs       interface{}            `yaml:"needs"` // string or []string
    If          string                 `yaml:"if"`
    Permissions map[string]string      `yaml:"permissions"`
    Environment string                 `yaml:"environment"`
    Steps       []map[string]any       `yaml:"steps"` // Keep as any for now, could be further typed
}

// FiltersConfig represents workflow filtering configuration  
type FiltersConfig struct {
    PullRequest PullRequestFilters `yaml:"pull-request"`
    Labels      LabelFilters       `yaml:"labels"`
}

type PullRequestFilters struct {
    IgnoreDrafts bool `yaml:"ignore-drafts"`
    IgnoreForks  bool `yaml:"ignore-forks"`
}

type LabelFilters struct {
    Include []string `yaml:"include"`
    Exclude []string `yaml:"exclude"`
}

Migration Strategy:

Phase 1: Introduce Frontmatter type alongside existing code

// pkg/parser/frontmatter.go - Add new parsing function
func ParseTypedFrontmatter(content string) (*Frontmatter, error) {
    var fm Frontmatter
    err := yaml.Unmarshal([]byte(content), &fm)
    if err != nil {
        return nil, fmt.Errorf("failed to parse frontmatter: %w", err)
    }
    return &fm, nil
}

Phase 2: Update WorkflowData to use typed frontmatter

// Before:
func (c *Compiler) ParseWorkflowFile(markdownPath string) (*WorkflowData, error) {
    // ... parsing code ...
    frontmatter := result.Frontmatter // map[string]any
    // ...
}

// After:
func (c *Compiler) ParseWorkflowFile(markdownPath string) (*WorkflowData, error) {
    // ... parsing code ...
    typedFrontmatter, err := ParseTypedFrontmatter(result.FrontmatterYAML)
    if err != nil {
        return nil, err
    }
    // Now use typed frontmatter instead of map[string]any
    // ...
}

Phase 3: Gradually migrate functions

// Before:
func (c *Compiler) extractYAMLValue(frontmatter map[string]any, key string) string {
    if value, exists := frontmatter[key]; exists {
        if strValue, ok := value.(string); ok {
            return strValue
        }
    }
    return ""
}

// After:
func (c *Compiler) extractName(frontmatter *Frontmatter) string {
    return frontmatter.Name // Direct access, no type assertion!
}

Benefits:

• ✅ Compile-time validation of field names (typos caught at compile time)
• ✅ No runtime type assertions needed
• ✅ Clear documentation of expected frontmatter structure
• ✅ IDE autocomplete for frontmatter fields
• ✅ Easier to add new fields (update struct, not string constants)
• ✅ Better error messages when parsing fails

Estimated Effort: Large (2-3 weeks)

• Define comprehensive Frontmatter struct: 2-3 days
• Add custom unmarshalers for complex fields (On, Tools): 2-3 days
• Migrate WorkflowData creation: 1-2 days
• Update 68 functions to use typed frontmatter: 1-2 weeks
• Testing and validation: 2-3 days

Impact: High

• Eliminates majority of map[string]any usage
• Significantly improves type safety in workflow compilation
• Makes frontmatter structure self-documenting
• Reduces runtime errors

---

Category 2: []any for Dynamic Steps/Lists

Impact: ⚠️ Medium - YAML unmarshaling creates dynamic slices

Problem Statement

YAML unmarshaling produces []any for arrays, requiring type assertions when processing. This affects:

• Step lists from YAML
• Needs dependencies
• Label lists
• Command lists

Example 1: Dynamic Step Processing

Location: pkg/workflow/compiler.go:830-1110

Current Pattern:

// Parsing steps from frontmatter
var importedSteps []any
err := yaml.Unmarshal([]byte(importedStepsYAML), &importedSteps)

// Later processing requires type assertion
if mainSteps, ok := mainStepsVal.([]any); ok {
    for _, stepVal := range mainSteps {
        if stepMap, ok := stepVal.(map[string]any); ok {
            // Process step
        }
    }
}

Problem: Every step is any, requiring assertion to map[string]any before use.

Example 2: Action Pin Application

Location: pkg/workflow/action_pins.go:206-213

Current Pattern:

// ApplyActionPinsToSteps applies action pins to a slice of steps
func ApplyActionPinsToSteps(steps []any, data *WorkflowData) []any {
    result := make([]any, len(steps))
    for i, step := range steps {
        if stepMap, ok := step.(map[string]any); ok {
            result[i] = ApplyActionPinToStep(stepMap, data)
        } else {
            result[i] = step
        }
    }
    return result
}

Problem: Function signature uses []any for steps, requiring type assertion for each element.

Example 3: Needs and Labels Processing

Location: pkg/workflow/compiler_jobs.go

Current Pattern:

if needsList, ok := needs.([]any); ok {
    // Process needs as list
}

// pkg/workflow/config_helpers.go
if labelsArray, ok := labels.([]any); ok {
    for _, label := range labelsArray {
        if labelStr, ok := label.(string); ok {
            // Process label
        }
    }
}

Suggested Improvement: Step Type

Recommendation: Create a Step type to replace map[string]any for steps

Proposed Solution:

// pkg/workflow/step_types.go (NEW FILE)

// Step represents a GitHub Actions workflow step
type Step struct {
    // Common fields
    Name string            `yaml:"name,omitempty"`
    ID   string            `yaml:"id,omitempty"`
    If   string            `yaml:"if,omitempty"`
    
    // Action step fields
    Uses string            `yaml:"uses,omitempty"`
    With map[string]string `yaml:"with,omitempty"`
    
    // Script step fields
    Run    string            `yaml:"run,omitempty"`
    Shell  string            `yaml:"shell,omitempty"`
    
    // Environment
    Env map[string]string `yaml:"env,omitempty"`
    
    // Other fields
    ContinueOnError bool   `yaml:"continue-on-error,omitempty"`
    TimeoutMinutes  int    `yaml:"timeout-minutes,omitempty"`
    
    // Allow additional fields for extensibility
    Additional map[string]any `yaml:",inline"`
}

// StepList represents a list of steps
type StepList []Step

// ParseSteps parses YAML step content into typed steps
func ParseSteps(yamlContent string) (StepList, error) {
    var steps StepList
    err := yaml.Unmarshal([]byte(yamlContent), &steps)
    if err != nil {
        return nil, fmt.Errorf("failed to parse steps: %w", err)
    }
    return steps, nil
}

// ToMap converts a Step back to map[string]any for YAML generation
func (s *Step) ToMap() map[string]any {
    result := make(map[string]any)
    
    // Add defined fields
    if s.Name != "" {
        result["name"] = s.Name
    }
    if s.ID != "" {
        result["id"] = s.ID
    }
    // ... add other fields ...
    
    // Merge additional fields
    for k, v := range s.Additional {
        result[k] = v
    }
    
    return result
}

Migration Example:

// Before:
func ApplyActionPinsToSteps(steps []any, data *WorkflowData) []any {
    result := make([]any, len(steps))
    for i, step := range steps {
        if stepMap, ok := step.(map[string]any); ok {
            result[i] = ApplyActionPinToStep(stepMap, data)
        }
    }
    return result
}

// After:
func ApplyActionPinsToSteps(steps StepList, data *WorkflowData) StepList {
    result := make(StepList, len(steps))
    for i, step := range steps {
        result[i] = ApplyActionPinToStep(step, data)
    }
    return result
}

func ApplyActionPinToStep(step Step, data *WorkflowData) Step {
    // Direct field access instead of map lookups!
    if step.Uses == "" {
        return step
    }
    
    // Extract action repo
    actionRepo := extractActionRepo(step.Uses)
    
    // Look up pin
    if pin, hasPins := data.ActionCache.GetPin(actionRepo); hasPins {
        step.Uses = pin.PinnedRef
    }
    
    return step
}

Benefits:

• ✅ Type-safe step field access
• ✅ No type assertions in step processing loops
• ✅ Clear step structure documentation
• ✅ IDE autocomplete for step fields
• ✅ Easier to add step validation

Estimated Effort: Medium (1-2 weeks)

• Define Step type with all fields: 1-2 days
• Add ToMap/FromMap conversion helpers: 1 day
• Migrate step processing functions: 3-5 days
• Update tests: 2-3 days

Impact: Medium-High

• Eliminates ~110 []any usages
• Improves step processing code clarity
• Makes step structure self-documenting

---

Category 3: Constants - Excellent Type Discipline

Impact: ✅ Already Excellent - No action needed

Finding: Strong Semantic Types Already in Use

Location: pkg/constants/constants.go:11-72

Excellent Examples:

// Semantic type definitions
type LineLength int
type Version string

// Constants with explicit types
const MaxExpressionLineLength LineLength = 120
const ExpressionBreakThreshold LineLength = 100

const DefaultClaudeCodeVersion Version = "2.0.42"
const DefaultCopilotVersion Version = "0.0.358"
const DefaultGitHubMCPServerVersion Version = "v0.20.2"
const DefaultFirewallVersion Version = "v0.1.1"

// Using time.Duration for type safety
const DefaultAgenticWorkflowTimeout = 20 * time.Minute
const DefaultToolTimeout = 60 * time.Second
const DefaultMCPStartupTimeout = 120 * time.Second

Assessment: This is exemplary Go code! The codebase already follows best practices for constant typing:

✅ Semantic types (LineLength, Version) provide meaning beyond primitive types
✅ Time durations use time.Duration with explicit units
✅ Clear naming conventions
✅ Backwards compatibility handled with deprecated constants

Recommendation: Constants

Status: ✅ No action needed - Continue current practices

The constants package demonstrates the type discipline that the rest of the codebase should aspire to. Use this as a model for other packages.

---

Part 3: Refactoring Recommendations

Priority 1: High Impact - Introduce Frontmatter Type

Recommendation: Create strongly-typed Frontmatter struct to replace map[string]any in workflow parsing

Rationale:

• Addresses 521 occurrences of map[string]any
• Affects 68+ functions across workflow package
• Highest impact on type safety and code clarity
• Makes frontmatter structure self-documenting

Implementation Steps:

1. Create pkg/workflow/frontmatter_types.go with comprehensive Frontmatter struct
2. Implement custom YAML unmarshalers for complex fields (On, Tools)
3. Add parsing function: ParseTypedFrontmatter(content string) (*Frontmatter, error)
4. Update WorkflowData creation to use typed frontmatter
5. Migrate extraction functions one-by-one to use typed frontmatter
6. Update all 68+ functions to accept *Frontmatter instead of map[string]any
7. Add comprehensive tests for frontmatter parsing

Estimated Effort: 2-3 weeks

Impact: High

• Eliminates majority of untyped map usage
• Compile-time field name validation
• Better IDE support and documentation
• Reduced runtime errors

Risk: Medium - Large refactoring affecting core compiler logic

---

Priority 2: Medium Impact - Introduce Step Type

Recommendation: Create Step type to replace map[string]any for workflow steps

Rationale:

• Addresses 110 occurrences of []any
• Simplifies step processing code
• Removes type assertions in loops
• Makes step structure clear

Implementation Steps:

1. Create pkg/workflow/step_types.go with Step struct
2. Implement ToMap() and FromMap() conversion methods
3. Add step parsing: ParseSteps(yamlContent string) (StepList, error)
4. Update step processing functions to use Step type
5. Migrate action pin application to use typed steps
6. Update runtime setup step filtering

Estimated Effort: 1-2 weeks

Impact: Medium-High

• Cleaner step processing code
• No type assertions in hot paths
• Self-documenting step structure

Risk: Low-Medium - More localized changes than Priority 1

---

Priority 3: Low Priority - Documentation

Recommendation: Document current any usage patterns and when they're appropriate

Rationale:

• Some any usage is legitimate (YAML flexibility)
• Help developers understand when to use typed vs untyped approaches
• Prevent regression to untyped patterns

Implementation Steps:

1. Add architecture documentation explaining frontmatter typing goals
2. Document when map[string]any is acceptable (e.g., truly dynamic configuration)
3. Add examples of typed vs untyped approaches
4. Include in contributor guidelines

Estimated Effort: 2-3 days

Impact: Low-Medium (Long-term quality)

Risk: None

---

Part 4: Implementation Roadmap

Phase 1: Foundation (Week 1-2)

Goal: Define typed structures without breaking existing code

• Create pkg/workflow/frontmatter_types.go with Frontmatter struct
• Create pkg/workflow/step_types.go with Step struct
• Implement YAML unmarshaling for new types
• Add conversion helpers (ToMap, FromMap)
• Write comprehensive unit tests for new types
• Document new type structures

Deliverable: New types available but not yet used by main code

---

Phase 2: Frontmatter Migration (Week 3-4)

Goal: Migrate workflow compiler to use typed frontmatter

• Update ParseWorkflowFile to create typed frontmatter
• Migrate extractYAMLValue and related helper functions
• Update ExtractEngineConfig to use typed frontmatter
• Migrate filter functions (applyPullRequestDraftFilter, etc.)
• Update manual approval extraction
• Migrate tools extraction
• Update jobs extraction
• Update all compiler methods one-by-one

Deliverable: Core compiler uses typed frontmatter, all tests pass

---

Phase 3: Step Type Migration (Week 5-6)

Goal: Migrate step processing to use typed steps

• Update ApplyActionPinsToSteps to use StepList
• Migrate runtime setup step filtering
• Update secret masking step processing
• Migrate custom step parsing
• Update post-steps processing

Deliverable: Step processing uses typed steps, no []any for steps

---

Phase 4: Cleanup and Documentation (Week 7)

Goal: Remove dead code and document new patterns

• Remove unused map[string]any helper functions
• Update developer documentation
• Add architecture decision record (ADR) for typing approach
• Add migration guide for contributors
• Final integration testing
• Performance benchmarking

Deliverable: Clean codebase with documented typing patterns

---

Part 5: Migration Checklist

Use this checklist to track migration progress:

Frontmatter Type Introduction

• Define Frontmatter struct with all fields
• Implement custom unmarshalers for complex fields
• Add ParseTypedFrontmatter function
• Write tests for frontmatter parsing

WorkflowData Integration

• Update WorkflowData to store typed frontmatter
• Update ParseWorkflowFile to create typed frontmatter
• Update CompileWorkflow to use typed frontmatter
• Update CompileWorkflowData to use typed frontmatter

Function Migration (68 functions)

pkg/workflow/frontmatter_extraction.go:

• Migrate extractYAMLValue
• Migrate extractTopLevelYAMLSection
• Migrate extractPermissions
• Migrate extractIfCondition
• Migrate extractFeatures
• Migrate extractDescription
• Migrate extractSource
• Migrate extractCampaign
• Migrate remaining 7+ extraction functions

pkg/workflow/engine.go:

• Migrate ExtractEngineConfig

pkg/workflow/filters.go:

• Migrate applyPullRequestDraftFilter
• Migrate applyPullRequestForkFilter
• Migrate applyLabelFilter

pkg/workflow/manual_approval.go:

• Migrate extractManualApprovalFromOn
• Migrate processManualApprovalConfiguration

pkg/workflow/tools.go:

• Migrate extractMapFromFrontmatter
• Migrate extractToolsFromFrontmatter
• Migrate extractMCPServersFromFrontmatter
• Migrate extractRuntimesFromFrontmatter
• Migrate mergeToolsAndMCPServers
• Migrate mergeRuntimes

pkg/workflow/compiler_jobs.go:

• Migrate extractJobsFromFrontmatter

pkg/workflow/secret_masking.go:

• Migrate extractSecretMaskingConfig

Step Type Migration

• Define Step struct
• Implement ToMap and FromMap conversion
• Add ParseSteps function
• Migrate ApplyActionPinsToSteps
• Migrate ApplyActionPinToStep
• Migrate runtime setup step filtering
• Migrate secret masking step processing
• Migrate custom step parsing

Testing and Validation

• All existing unit tests pass
• Add tests for new typed structures
• Integration tests pass
• Performance regression testing
• Manual testing of workflow compilation

---

Analysis Metadata

• Total Go Files Analyzed: 223 (excluding tests)
• Total Type Definitions: 232 structs and interfaces
• Duplicate Clusters: 0 (excellent organization)
• interface{} Usages: 0 ✅
• map[string]any Usages: 521 ⚠️
• []any Usages: 110 ⚠️
• Functions Using map[string]any: 117
• Primary Focus: pkg/workflow/ directory
• Detection Method: Pattern matching + Serena semantic analysis
• Analysis Date: 2025-11-17

---

Conclusion

The githubnext/gh-aw codebase demonstrates excellent type discipline in many areas, particularly in the constants package which serves as an exemplary model. The primary opportunity for improvement lies in the workflow compilation layer, where YAML parsing produces untyped map[string]any structures that propagate through the codebase.

Key Strengths:

• ✅ Zero interface{} usage (modern Go practices)
• ✅ Semantic types for constants (LineLength, Version)
• ✅ Well-organized configuration types with no duplication
• ✅ Use of time.Duration for type-safe timeouts

Key Opportunities:

• ⚠️ 521 occurrences of map[string]any in frontmatter parsing
• ⚠️ 110 occurrences of []any in step processing
• 🎯 High-impact refactoring: Introduce typed Frontmatter struct

The recommended refactoring would significantly improve type safety, code clarity, and maintainability while building on the strong typing foundation already present in the codebase.

AI generated by Typist - Go Type Analysis

[github-actions[bot]]

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