feat: Add complexity analyzer tool

[nnennandukwe]

Summary

Add a complexity_analysis tool that measures code complexity metrics and identifies overly complex code that should be refactored. Uses Astroid for accurate analysis of Python-specific constructs.

Parent Epic

Part of: #40 - Evolve into Python Code Quality MCP

Depends On

• refactor: extract shared Astroid utilities into core module #41 - Refactor shared Astroid utilities into core module

Metrics to Calculate

Cyclomatic Complexity

Count of linearly independent paths through the code:

• +1 for each if, elif, for, while, except, with, assert
• +1 for each and, or in conditions
• +1 for each comprehension
• +1 for each ternary expression

Thresholds:

• 1-10: Simple, low risk
• 11-20: Moderate complexity
• 21-50: High complexity, consider refactoring
• 50+: Very high risk, refactor immediately

Cognitive Complexity

Measures how hard code is to understand (Sonar's metric):

• Increments for breaks in linear flow (if, loops, etc.)
• Nesting penalty (nested structures add more)
• No increment for shorthand structures

Function Length

• Lines of code per function
• Threshold: 50+ lines is a warning

Parameter Count

• Number of parameters per function
• Threshold: 5+ parameters is a warning

Nesting Depth

• Maximum nesting level in a function
• Threshold: 4+ levels is a warning

Class Metrics

• Methods per class
• Inheritance depth
• Coupling between classes (imports/dependencies)

MCP Tool Interface

{
  "name": "complexity_analysis",
  "description": "Analyze code complexity metrics and identify overly complex code",
  "inputSchema": {
    "type": "object",
    "properties": {
      "file_path": {"type": "string"},
      "source_code": {"type": "string"},
      "cyclomatic_threshold": {"type": "integer", "default": 10},
      "cognitive_threshold": {"type": "integer", "default": 15},
      "max_function_length": {"type": "integer", "default": 50}
    }
  }
}

Example Output

{
  "issues": [
    {
      "tool": "complexity",
      "category": "high_cyclomatic_complexity",
      "severity": "warning",
      "message": "Function 'process_data' has cyclomatic complexity of 25 (threshold: 10)",
      "line": 45,
      "function": "process_data",
      "metrics": {
        "cyclomatic": 25,
        "cognitive": 18,
        "lines": 87,
        "params": 3,
        "nesting_depth": 5
      },
      "suggestion": "Consider breaking this function into smaller, focused functions"
    }
  ],
  "file_metrics": {
    "total_functions": 12,
    "average_complexity": 8.5,
    "max_complexity": 25,
    "complex_functions": 3
  }
}

Implementation

1. Create src/workshop_mcp/tools/complexity_analysis/
2. Implement cyclomatic complexity calculator
3. Implement cognitive complexity calculator
4. Add function/class metric collectors
5. Register tool in MCP server

Acceptance Criteria

• Calculates cyclomatic complexity accurately
• Calculates cognitive complexity accurately
• Reports function length, parameter count, nesting depth
• Configurable thresholds
• File-level summary statistics
• Uses shared core Astroid utilities