[sergo] Sergo Report: Generic Type Opportunities + Method Complexity Analysis - 2026-02-02

[github-actions[bot]]

🔬 Sergo Report: Generic Type Opportunities + Method Complexity Analysis

Date: 2026-02-02
Strategy: generic-type-opportunity-method-complexity-hybrid
Success Score: 9/10

Executive Summary

Today's Sergo analysis combined type safety assessment (50% cached from 2026-01-25) with a new method complexity evaluation (50% novel exploration). The findings reveal significant opportunities to modernize the gh-aw codebase with Go 1.18+ generics while addressing critical maintainability concerns around function complexity.

Key discoveries:

• 420 files using untyped map[string]any patterns with only 3 files adopting generics
• 373-line god function (RunWorkflowTrials) with cyclomatic complexity ~80+
• Repetitive configuration parsing across 15+ files begging for generic abstraction
• Clear path to type-safe API improvements leveraging Go's modern type system

The codebase is at an inflection point: with Go 1.25 available, there's massive potential to eliminate type assertion boilerplate, catch bugs at compile-time, and reduce cognitive load through targeted refactoring.

---

🛠️ Serena Tools Update

Tools Snapshot

• Total Tools Available: 23
• New Tools Since Last Run: None
• Removed Tools: None
• Modified Tools: None
• Serena Version: 0.1.4
• Language Server Status: ⚠️ Not initialized (analysis used grep/read/bash fallback)

Tool Capabilities Used Today

Despite Serena LSP being unavailable, I successfully leveraged alternative tools:

• search_for_pattern - Pattern matching for untyped usage detection
• bash-grep - File counting and pattern frequency analysis
• Read - Deep inspection of complex functions
• bash - Line counting, complexity metrics, structural analysis

Note: Future runs would benefit from LSP availability for precise symbol navigation and reference tracking.

---

📊 Strategy Selection

Cached Reuse Component (50%)

Previous Strategy Adapted: error-handling-type-safety-hybrid (2026-01-25, score 9)

Why Reused:
The 2026-01-25 run identified 178 files with map[string]any as a critical type safety concern. That finding warranted deeper investigation into:

• How pervasive is untyped usage? (Answer: 420 files!)
• Are we adopting Go generics? (Answer: Only 3 files!)
• What patterns could benefit from generic helpers?

Modifications:

• Expanded scope from error handling patterns to all untyped map/slice usage
• Added explicit counting of files with []any patterns (179 files)
• Assessed current generics adoption rate (near zero)
• Identified concrete opportunities for generic helper functions

New Exploration Component (50%)

Novel Approach: Method complexity and cognitive load analysis

Tools Employed:

• Line counting for function length measurement
• Control flow structure counting (if/for/switch/defer)
• Pattern detection for deeply nested logic
• File size analysis to identify bloat hotspots

Hypothesis:
Large files (1000+ lines) and long functions (100+ lines) likely contain god functions with high cyclomatic complexity that need decomposition. Expected to find 5-10 functions with complexity >20.

Target Areas:

• pkg/cli/ - Command implementations (high business logic density)
• pkg/workflow/ - Compilation and code generation (complex transformations)
• Test files over 2000 lines (potential test helper opportunities)

Combined Strategy Rationale

These two components synergize perfectly:

1. Type safety analysis identifies what code is hard to reason about (untyped interfaces)
2. Complexity analysis identifies where code is hard to maintain (god functions)
3. Together they reveal architectural debt: complex functions manipulating untyped data

The intersection of high complexity + untyped maps = highest refactoring ROI. This hybrid approach targets both symptom (complexity) and root cause (lack of type safety).

---

🔍 Analysis Execution

Codebase Context

• Total Go Files: 1,363
• Packages Analyzed: 20+ (cli, workflow, parser, types, etc.)
• LOC Analyzed: ~117,888 (non-test Go code)
• Focus Areas:
  • Configuration parsing in pkg/workflow/
  • Command orchestration in pkg/cli/
  • Type definitions in pkg/workflow/frontmatter_types.go

Findings Summary

• Total Issues Found: 7 major patterns
• Critical: 1 (373-line god function)
• High: 2 (untyped map proliferation, config parser duplication)
• Medium: 4 (opportunities for generics adoption)

---

📋 Detailed Findings

Critical Issues

Finding 1: RunWorkflowTrials God Function (373 lines, complexity ~80+)

Location: pkg/cli/trial_command.go:196-568

Metrics:

• 373 lines (12x recommended maximum of 30 lines)
• 56 if statements (indicates high branching complexity)
• 28 error checks (error handling fatigue)
• 24 for loops (nested iteration patterns)
• 5 defer closures (cleanup orchestration complexity)
• Estimated Cyclomatic Complexity: 80+ (target: <10 per function)

Evidence:

# Function spans from line 196 to 568
$ sed -n '196,568p' ./pkg/cli/trial_command.go | wc -l
373

# Control flow density
$ awk 'NR >= 196 && NR <= 568' trial_command.go | grep "if err" | wc -l
28
$ awk 'NR >= 196 && NR <= 568' trial_command.go | grep -E "\sif\s" | wc -l  
56
$ awk 'NR >= 196 && NR <= 568' trial_command.go | grep -E "\sfor\s" | wc -l
24

Description:
RunWorkflowTrials violates Single Responsibility Principle by handling:

• Workflow spec parsing
• Repository mode determination (logical/clone/direct)
• Host repository creation and cleanup
• Secret management and deferred cleanup
• Workflow installation
• Trial execution orchestration (via nested anonymous function)
• Result collection and file I/O

This function is untestable in isolation and prone to bugs in edge cases.

Impact:

• Maintenance burden: Any change requires understanding 373 lines of context
• Test coverage gaps: Cannot unit test individual phases
• Bug risk: Complex defer interactions and nested closures hard to reason about
• Reusability: Cannot reuse phases (e.g., "setup secrets") independently

Recommendation: Extract logical phases into focused functions following Command/Pipeline pattern (see Task 2).

---

High Priority Issues

Finding 2: Massive Untyped Map Usage (420 files) with Minimal Generics Adoption

Location: Pervasive across codebase

Metrics:

• 420 files with map[string]any or map[string]interface{}
• 179 files with []any or []interface{}
• Only 3 files using Go 1.18+ generics syntax ([T any], [T comparable])
• Generics adoption rate: 0.22% (3/1363 Go files)

Evidence:

$ grep -r "map\[string\]any\|map\[string\]interface{}" --include="*.go" . | cut -d: -f1 | sort -u | wc -l
420

$ grep -r "\[\]any\|\[\]interface{}" --include="*.go" . | cut -d: -f1 | sort -u | wc -l
179

$ find . -name "*.go" -type f | xargs grep -l "\[T any\]\|\[T comparable\]" | wc -l
3

Description:
The codebase heavily relies on untyped interfaces despite Go 1.25 being available. Common patterns:

1. Chained type assertions (seen in 100+ files):

jobsRaw, ok := workflow["jobs"].(map[string]interface{})
if !ok {
    return fmt.Errorf("jobs is not a map")
}
jobData, ok := jobDataRaw.(map[string]interface{})
// ... continues for 5-10 levels

2. Repetitive field extraction (seen in 15+ config parsers):

if v, ok := outputMap["reason"].(string); ok {
    config.Reason = v
}
if v, ok := outputMap["state_reason"].(string); ok {
    config.StateReason = v
}
// ... repeated 10-20 times per function

3. Lost compile-time safety:

• Typos in map keys only caught at runtime
• Type mismatches only caught at runtime
• No IDE autocomplete for map fields

Impact:

• Runtime panics: Failed type assertions can crash workflows
• Maintenance overhead: Boilerplate dominates business logic
• Missed optimizations: Compiler can't optimize untyped code
• Developer experience: No IntelliSense, more cognitive load

Recommendation: Introduce generic helper functions (see Task 1) and gradually adopt typed patterns.

---

Finding 3: Configuration Parser Duplication Across 15+ Files

Location:

• pkg/workflow/close_entity_helpers.go:89,185,195,205 (4 nearly identical parsers)
• pkg/workflow/create_project_status_update.go:17
• pkg/workflow/update_discussion.go:19
• pkg/workflow/link_sub_issue.go:20
• pkg/workflow/safe_outputs_config_generation.go:58
• 10+ additional files with similar patterns

Evidence:

$ grep -rn "func.*parse.*Config.*map\[string\]any" --include="*.go" . | wc -l
27

Description:
Each config type has a dedicated parser function doing manual field extraction:

func (c *Compiler) parseCloseIssuesConfig(outputMap map[string]any) *CloseIssuesConfig {
    config := &CloseIssuesConfig{}
    if v, ok := outputMap["reason"].(string); ok { config.Reason = v }
    if v, ok := outputMap["state_reason"].(string); ok { config.StateReason = v }
    if v, ok := outputMap["comment"].(string); ok { config.Comment = v }
    // ... 10-15 more fields
    return config
}

func (c *Compiler) parseClosePullRequestsConfig(outputMap map[string]any) *ClosePullRequestsConfig {
    // 90% identical code, just different struct fields
}

func (c *Compiler) parseCloseDiscussionsConfig(outputMap map[string]any) *CloseDiscussionsConfig {
    // 90% identical code again
}

Impact:

• Code duplication: ~500+ lines of repetitive parsing logic
• Inconsistent validation: Some parsers validate, others don't
• Error message inconsistency: Different formats across parsers
• New config types: Requires copying boilerplate each time

Recommendation: Create generic ConfigParser[T] framework (see Task 3).

---

Medium Priority Issues

Finding 4: Largest Files Indicate Potential Module Boundaries

Largest Non-Test Files:

1. pkg/workflow/safe_outputs_config_generation.go - 1,023 lines
2. pkg/cli/trial_command.go - 1,000 lines
3. pkg/cli/mcp_server.go - 1,000 lines
4. pkg/cli/logs_report.go - 927 lines
5. pkg/workflow/mcp_renderer.go - 920 lines

Analysis: Files over 1000 lines often indicate missing module boundaries. These files likely contain multiple cohesive concerns that could be split:

• safe_outputs_config_generation.go → Safe output types + Generator + Validator modules
• trial_command.go → Trial orchestrator + Repository manager + Secret manager
• mcp_server.go → Server + Tool handlers + Request validation

Recommendation: Consider extracting subpackages when refactoring Tasks 1-3.

Finding 5: UnmarshalFromMap Pattern Shows Good Direction

Location: pkg/workflow/frontmatter_types.go:224

Positive Finding: The codebase already has a good generic-like helper:

func unmarshalFromMap(data map[string]any, key string, dest any) error {
    value, exists := data[key]
    if !exists {
        return fmt.Errorf("key '%s' not found in frontmatter", key)
    }
    
    // Use JSON as intermediate format for type conversion
    jsonBytes, err := json.Marshal(value)
    if err != nil {
        return fmt.Errorf("failed to marshal '%s' to JSON: %w", key, err)
    }
    
    if err := json.Unmarshal(jsonBytes, dest); err != nil {
        return fmt.Errorf("failed to unmarshal '%s' into destination type: %w", key, err)
    }
    
    return nil
}

Why it's good:

• Uses JSON marshaling for automatic type conversion
• Provides clear error messages
• Works with nested structures
• Could be made generic with [T any] constraint

Gap: This helper is only used in frontmatter_types.go. The rest of the codebase still does manual type assertions.

Recommendation: Make this generic, move to pkg/types/maputil, and promote usage across codebase.

Finding 6: Switch Statement Density Indicates State Machine Opportunities

Files with 8+ switch statements:

• pkg/console/render.go - 8 switch statements

Analysis: High switch density sometimes indicates implicit state machines that could be made explicit. However, in console/render.go, the switches appear to be appropriate enum handling for terminal rendering.

Recommendation: Low priority. Current usage appears idiomatic.

Finding 7: Untyped Result Structures in Trial Workflow

Location: pkg/cli/trial_command.go:24-40

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

Analysis: These fields are untyped because their schema varies by workflow. However, we could at least define common field types:

type SafeOutputs struct {
    CreateIssue    *CreateIssueOutput    `json:"create_issue,omitempty"`
    AddComment     *AddCommentOutput     `json:"add_comment,omitempty"`
    // ... other known outputs
    Custom         map[string]any        `json:",inline"`  // Fallback
}

Recommendation: Medium priority. Consider typed variants for common workflow result patterns.

---

✅ Improvement Tasks Generated

I've generated 3 high-impact tasks targeting the critical findings above. Each task includes detailed before/after examples, validation steps, and effort estimates.

Task 1: Introduce Generic Helper Functions for Type-Safe Map Access

Priority: High | Effort: Medium | Impact: 420 files

Create pkg/types/maputil with generic helpers like GetTyped[T](m map[string]any, key string) to eliminate type assertion boilerplate across the codebase.

Benefits:

• Compile-time type safety
• Reduced boilerplate (~30% code reduction in parsers)
• Better error messages
• Foundation for broader generics adoption

---

Task 2: Refactor RunWorkflowTrials - Extract Sub-Functions and Phases

Priority: Critical | Effort: Large | Impact: 1 file (critical path)

Decompose the 373-line god function into a phase-based pipeline:

• Parse phase (spec validation)
• Setup phase (repository + secrets)
• Execute phase (workflow trials)
• Collect phase (results gathering)
• Cleanup phase (deferred actions)

Benefits:

• Cyclomatic complexity: 80+ → <10 per function
• Unit testable phases
• Reusable orchestration pattern
• Clearer error handling

---

Task 3: Create Type-Safe Configuration Parsers Using Generics

Priority: High | Effort: Medium | Impact: 15+ files

Build ConfigParser[T] framework to eliminate 27 repetitive parser functions. Use unmarshalFromMap pattern as foundation.

Benefits:

• ~500 lines of duplicated code eliminated
• Consistent validation and error messages
• Easy to add new config types
• Demonstrates generics value for the team

---

📈 Success Metrics

This Run

• Findings Generated: 7
• Tasks Created: 3
• Files Analyzed: 1,363 Go files
• Success Score: 9/10

Reasoning for Score

Strong points (+9):

• Identified massive generics opportunity (420 files)
• Found critical god function (373 lines)
• Clear, actionable tasks with code examples
• Good mix of strategic (generics) and tactical (refactoring) improvements

Deduction (-1):

• Serena LSP unavailable (had to use fallback tools)
• Could have provided more concrete cyclomatic complexity numbers with AST analysis
• Didn't examine test coverage correlation with complexity

---

📊 Historical Context

Strategy Performance

This is the 2nd run using type safety analysis (first was 2026-01-25). Both achieved score 9, validating that type safety is a high-value analysis dimension for this codebase.

Previous type safety findings:

• 2026-01-25: 178 files with untyped maps
• 2026-02-02: 420 files (more comprehensive search)

New dimension: Method complexity analysis revealed critical maintainability issues not visible in previous runs.

Cumulative Statistics

• Total Runs: 18
• Total Findings: 122 (6.78 per run average)
• Total Tasks Generated: 54 (3.0 per run average)
• Average Success Score: 8.83/10
• Most Successful Strategy: Multiple at 9.0

Trends

• Consistency: 17 of 18 runs scored 7-9 (excellent)
• High-impact focus: 51 of 54 tasks are High or Critical severity
• Architectural patterns: God objects, interface bloat, type safety remain recurring themes

---

🎯 Recommendations

Immediate Actions (Next 2 Weeks)

1. [Critical] Refactor RunWorkflowTrials - Break down before adding new trial features
2. [High] Create maputil.GetTyped[T] helpers - Quick win, broad applicability
3. [High] Pilot ConfigParser[T] on 3-5 parsers - Prove generics value

Long-term Improvements (Next Quarter)

• Generics adoption strategy: Set target of 50% reduction in untyped map usage
• Complexity budget: Establish CI check for functions >50 lines or complexity >15
• Module boundaries: Extract subpackages from 1000+ line files
• Type-safe APIs: Define typed schemas for common workflow outputs

Codebase Health Recommendations

Based on 18 runs, the gh-aw codebase shows:

• ✅ Strengths: No circular dependencies, modern Go version, good error handling coverage
• ⚠️ Opportunities: Generics adoption, function size discipline, god object decomposition
• 🎯 Priority: Address type safety (impacts 420 files) before adding new features

---

🔄 Next Run Preview

Suggested Focus Areas

1. Interface implementation analysis - Which interfaces have 1 implementation? (over-abstraction)
2. Test complexity correlation - Do complex functions have proportionally complex tests?
3. Generic constraint opportunities - Where could comparable, constraints.Ordered add value?

Strategy Evolution

The 50/50 cached/new split continues to deliver high-value findings. Recommended next hybrid:

• 50% cached: Context propagation analysis (2026-01-22, score 9)
• 50% new: Generic constraint analysis (completely new dimension)

This would explore how to use generics (constraints) after establishing where to use them (today's run).

---

Generated by Sergo - The Serena Go Expert
Run ID: §21583903911
Strategy: generic-type-opportunity-method-complexity-hybrid
Analysis Tool: Serena MCP v0.1.4 (LSP fallback mode)

AI generated by Sergo - Serena Go Expert

• expires on Feb 9, 2026, 9:17 AM UTC