[C4.3] Add code complexity metrics to ARCHITECTURE.md

[yusufkaraaslan]

Problem

ARCHITECTURE.md currently provides structural information (patterns, examples, directory layout) but lacks quantitative metrics about code quality and complexity.

Missing insights:

• How complex is this codebase? (beginner vs expert)
• What's the average function length?
• How deeply nested is the code?
• What's the test coverage estimation?
• Which files are most complex (need refactoring)?

Proposed Solution

Add Section 9: Code Quality Metrics to ARCHITECTURE.md with 5 key metrics:

1. Cyclomatic Complexity

What: Measures code decision paths (if/else/for/while)
Why: Indicates testing difficulty and potential bugs

def calculate_cyclomatic_complexity(file_path):
    # Count decision points: if, elif, while, for, except, with
    complexity = 1  # Base complexity
    complexity += code.count('if ')
    complexity += code.count('elif ')
    complexity += code.count('while ')
    # ... etc
    return complexity

Output:

**Cyclomatic Complexity:**
- Average: 4.2 (Low - maintainable)
- Median: 3
- Max: 18 (in src/parser.py:152)
- Distribution: 85% simple (1-5), 12% moderate (6-10), 3% complex (11+)

2. Lines of Code (LoC) Distribution

What: Average function/class size
Why: Indicates code modularity

**Code Size Metrics:**
- Average function length: 12 lines
- Average class length: 85 lines
- Largest function: 156 lines (needs refactoring)
- Functions > 50 lines: 8 (5% of total)

3. Nesting Depth

What: Maximum indentation levels
Why: Deep nesting = harder to understand

**Nesting Depth:**
- Average: 2.1 levels
- Max: 6 levels (in src/validator.py - consider refactoring)

4. Test Coverage Estimation

What: Ratio of test files to source files
Why: Indicates testing rigor

**Test Coverage Estimation:**
- Test files: 178
- Source files: 361
- Test-to-source ratio: 0.49 (Good - near 1:1)
- Estimated coverage: ~70-80% (based on file ratio)

5. Code Duplication Detection

What: Similar code blocks across files
Why: Indicates need for abstraction

**Code Duplication:**
- Duplicate blocks found: 12
- Duplication ratio: 3.2%
- Largest duplicate: 45 lines across 3 files

Implementation

Core Function

# In codebase_scraper.py
def analyze_code_metrics(directory: Path) -> Dict[str, Any]:
    metrics = {
        'complexity': [],
        'function_lengths': [],
        'nesting_depths': [],
        'duplicates': []
    }
    
    for file in source_files:
        # Parse with AST (Python) or regex (others)
        ast_tree = ast.parse(file.read_text())
        
        # Calculate metrics
        metrics['complexity'].append(calculate_complexity(ast_tree))
        metrics['function_lengths'].append(get_function_sizes(ast_tree))
        metrics['nesting_depths'].append(max_nesting_depth(ast_tree))
    
    return {
        'avg_complexity': statistics.mean(metrics['complexity']),
        'avg_function_length': statistics.mean(metrics['function_lengths']),
        # ... etc
    }

Integration with ARCHITECTURE.md

# In unified_skill_builder.py
def _generate_architecture_overview():
    # ... existing sections 1-8 ...
    
    # Section 9: Code Quality Metrics (NEW)
    if c3_data.get('code_metrics'):
        f.write("## 9. Code Quality Metrics\n\n")
        self._write_code_metrics(f, c3_data['code_metrics'])

Supported Languages

Phase 1 (AST-based):

• Python (using ast module)

Phase 2 (Heuristic-based):

• JavaScript/TypeScript (regex + indentation counting)
• Java, C++, Go (regex patterns)

Success Criteria

• ✅ Calculates all 5 metrics for Python codebases
• ✅ Performance: < 500ms for 500 files
• ✅ Accuracy: Within 10% of established tools (pylint, radon)
• ✅ Section 9 adds 20-30 lines to ARCHITECTURE.md
• ✅ Helps developers identify refactoring targets

Priority

Medium - Nice-to-have enhancement, not critical

Related

• Part of C4 (Codebase Analysis Enhancements)
• Complements [C4.1] Add framework detection to architectural pattern analysis #239 (framework detection) and [C4.2] Improve confidence thresholds for pattern detection #240 (pattern confidence)
• Adds quantitative data to ARCHITECTURE.md

[yusufkaraaslan]

Status Check

Verified that complexity metrics are NOT currently implemented. This is a genuine enhancement request.

Current Status

❌ Not implemented - No complexity calculation in codebase
✅ Issue is valid - Would be valuable addition to ARCHITECTURE.md
✅ This is a new feature - Not a bug fix or existing feature improvement

What Exists Now

ARCHITECTURE.md currently includes:

• Architectural patterns (MVC, Service Layer, etc.)
• Framework detection (when working)
• Pattern evidence and examples
• Directory structure analysis

Missing (this issue requests):

• Cyclomatic complexity metrics
• Lines of code distribution
• Nesting depth analysis
• Test coverage estimation
• Complexity hotspots identification

Implementation Scope

Required work:

1. Add complexity analyzer module (complexity_metrics.py)
2. Implement 5 metrics:
   • Cyclomatic complexity (decision points)
   • LoC distribution (function/class sizes)
   • Nesting depth (code indentation)
   • Cognitive complexity (mental load)
   • Maintainability index (composite score)
3. Integrate into ARCHITECTURE.md generation
4. Add visualizations (distribution charts)

Priority

Medium - Nice-to-have enhancement that provides useful insights but not critical for core functionality.

Estimated Effort

4-6 hours:

• 2h: Complexity calculation algorithms
• 2h: Integration with existing analysis pipeline
• 1h: ARCHITECTURE.md formatting
• 1h: Testing with various codebases

Related Issues

• Depends on [C4.1] Add framework detection to architectural pattern analysis #239 fix (need working file analysis)
• Part of C4 series (Codebase Analysis Enhancements)