nexus/skills/code_complexity_analysis.py

"""Code Complexity Analysis Skill - Phân tích độ phức tạp.

Tính Cyclomatic (McCabe) và Cognitive Complexity (SonarSource),
với example calculation cho từng loại.

Author: Hieu Louis (2026)
"""
from __future__ import annotations

from typing import Dict, List

from .base import Skill, SkillContext, SkillCategory, SkillPriority, SkillResult


class CodeComplexitySkill(Skill):
    """Tính cyclomatic + cognitive complexity, suggest refactors."""

    category = SkillCategory.CODE
    priority = SkillPriority.MEDIUM
    keywords: List[str] = [
        "cyclomatic complexity", "cognitive complexity", "complexity",
        "mccabe", "code complexity", "độ phức tạp",
        "function complexity", "branch complexity",
        "too complex", "complex function",
    ]
    examples = [
        "Calculate cyclomatic complexity of this function",
        "Why is this function rated 'complex' by SonarQube?",
        "Reduce cognitive complexity of this method",
    ]

    @property
    def name(self) -> str:
        return "code_complexity"

    @property
    def description(self) -> str:
        return (
            "Tính cyclomatic (McCabe) + cognitive (SonarSource) complexity. "
            "Suggest refactors: extract method, guard clauses, polymorphism."
        )

    def can_handle(self, prompt: str, context: SkillContext = None) -> float:
        prompt_lower = prompt.lower()
        score = 0.0
        for kw in self.keywords:
            if kw in prompt_lower:
                score += 0.18
        if "def " in prompt or "function " in prompt:
            score += 0.1
        return min(1.0, score)

    def execute(self, context: SkillContext) -> SkillResult:
        return SkillResult(
            success=True,
            output="[CodeComplexity] McCabe + cognitive complexity calculator ready.",
            artifacts=[
                {"path": "complexity/calculator.py", "content": _COMPLEXITY_CALCULATOR},
                {"path": "complexity/example.md", "content": _EXAMPLE_CALCULATION},
            ],
            metadata={
                "skill": self.name,
                "metrics": {
                    "cyclomatic": {
                        "definition": "M = E - N + 2P (Edges - Nodes + 2*Connected Components)",
                        "shortcut": "M = decision_points + 1",
                        "decision_points": ["if", "elif", "for", "while", "except", "and", "or",
                                            "ternary", "case/default"],
                        "thresholds": {
                            "low": "<= 5",
                            "moderate": "6 - 10",
                            "high": "11 - 20",
                            "very_high": "21 - 50",
                            "untestable": "> 50",
                        },
                    },
                    "cognitive": {
                        "definition": "SonarSource metric — penalizes nesting + recursion + breaks",
                        "increments": [
                            "+1 per if/else/for/while/except/case",
                            "+1 per nesting level (compound cost)",
                            "+1 per boolean op (and/or/not)",
                            "+1 per jump (break/continue/return inside loop)",
                            "+1 per recursion (caller == callee)",
                            "+1 per goto-like pattern",
                        ],
                        "thresholds": {
                            "low": "<= 5",
                            "moderate": "6 - 10",
                            "high": "11 - 20",
                            "very_high": "21 - 30",
                            "untestable": "> 30",
                        },
                    },
                    "halstead": "Difficulty / Effort / Volume (rarely used in practice)",
                    "npath": "Number of independent paths — exponential in branches",
                },
                "refactor_patterns": [
                    "Extract Method (split large function)",
                    "Replace Conditional with Polymorphism (if-elif ladder -> strategy)",
                    "Decompose Conditional (long boolean expr -> named predicate)",
                    "Guard Clauses (early return replaces nested if-else)",
                    "Replace Nested Conditionals with State/Strategy",
                    "Compose Method (sequence of intention-revealing calls)",
                ],
                "tooling": {
                    "python": "radon cc (cyclomatic), radon mi (maintainability), xenon (CI)",
                    "javascript": "escomplex, typhonjs-escomplex",
                    "java": "PMD, SonarQube",
                    "go": "gocyclo (cyclomatic only)",
                    "rust": "rust-code-analysis (both metrics)",
                },
                "ci_thresholds": {
                    "block_pr": "cyclomatic > 15 OR cognitive > 20",
                    "warn": "cyclomatic > 10 OR cognitive > 15",
                    "trend": "Track average per file; fail regression > 10%",
                },
            },
            suggestions=[
                "Specify which metric (cyclomatic / cognitive / both)",
                "Provide code in fenced block for accurate analysis",
                "Ask for refactor suggestions if complexity > threshold",
            ],
        )


_COMPLEXITY_CALCULATOR = '''"""Cyclomatic + Cognitive Complexity calculator.

Author: Hieu Louis (2026)
"""
from __future__ import annotations
import ast
from dataclasses import dataclass


@dataclass
class ComplexityResult:
    cyclomatic: int
    cognitive: int
    decision_points: int
    nesting_max: int
    rating: str            # "low" | "moderate" | "high" | "very_high" | "untestable"


def analyze(func: ast.FunctionDef) -> ComplexityResult:
    visitor = _ComplexityVisitor(func.name)
    visitor.visit(func)
    cyclo = visitor.decision_points + 1
    cognitive = visitor.cognitive
    nesting_max = visitor.max_nesting
    rating = _rate(cyclo, cognitive)
    return ComplexityResult(
        cyclomatic=cyclo,
        cognitive=cognitive,
        decision_points=visitor.decision_points,
        nesting_max=nesting_max,
        rating=rating,
    )


# Cyclomatic: count decision points
# Cognitive: SonarSource algorithm (penalize nesting + recursion + jumps)


class _ComplexityVisitor(ast.NodeVisitor):
    DECISION_NODES = (
        ast.If, ast.For, ast.AsyncFor, ast.While,
        ast.ExceptHandler, ast.BoolOp, ast.IfExp,
    )

    def __init__(self, func_name: str) -> None:
        self.func_name = func_name
        self.decision_points = 0
        self.cognitive = 0
        self.nesting = 0
        self.max_nesting = 0
        self.in_loop = False

    def _visit_decision(self, node):
        self.decision_points += 1
        self.cognitive += self.nesting + 1
        self.nesting += 1
        self.max_nesting = max(self.max_nesting, self.nesting)
        self.generic_visit(node)
        self.nesting -= 1

    def visit_BoolOp(self, node: ast.BoolOp) -> None:
        # Each additional operand in `and`/`or` is +1
        self.decision_points += max(0, len(node.values) - 1)
        self.cognitive += max(0, len(node.values) - 1)
        self.generic_visit(node)

    visit_If = _visit_decision
    visit_For = _visit_decision
    visit_AsyncFor = _visit_decision
    visit_While = _visit_decision
    visit_ExceptHandler = _visit_decision

    def visit_IfExp(self, node: ast.IfExp) -> None:
        self.decision_points += 1
        self.cognitive += 1
        self.generic_visit(node)

    def visit_Break(self, node: ast.Break) -> None:
        if self.in_loop:
            self.cognitive += 1
        self.generic_visit(node)

    def visit_Continue(self, node: ast.Continue) -> None:
        if self.in_loop:
            self.cognitive += 1
        self.generic_visit(node)

    def visit_FunctionDef(self, node: ast.FunctionDef) -> None:
        if node.name == self.func_name:
            self.cognitive += 1   # recursion penalty
        else:
            self._visit_decision(node)

    visit_AsyncFunctionDef = visit_FunctionDef


def _rate(cyclo: int, cognitive: int) -> str:
    if cyclo <= 5 and cognitive <= 5:
        return "low"
    if cyclo <= 10 and cognitive <= 10:
        return "moderate"
    if cyclo <= 20 and cognitive <= 20:
        return "high"
    if cyclo <= 50 and cognitive <= 30:
        return "very_high"
    return "untestable"
'''


_EXAMPLE_CALCULATION = '''# Example: Cyclomatic + Cognitive Complexity Calculation

## Sample Code
```python
def process(items, flag):
    result = []
    for item in items:                       # cyclomatic +1, cognitive +1
        if item.is_valid and flag:           # cyclomatic +1 (if) +1 (and), cognitive +2 (nested) +1 (and)
            if item.priority > 5:             # cyclomatic +1, cognitive +3 (doubly nested)
                result.append(item)
            else:
                continue                     # cognitive +1 (jump in loop)
        elif item.is_optional:               # cyclomatic +1 (elif), cognitive +2
            result.append(item)
    return result
```

## Cyclomatic Complexity (McCabe)
Decision points counted:
- `for` ... 1
- `if` ... 1
- `and` ... 1
- `if` (nested) ... 1
- `elif` ... 1
Total decision_points = 5

`M = decision_points + 1 = 6`

Rating: **moderate**

## Cognitive Complexity (SonarSource)
- `for` at nesting 0: +1 (nesting 0 + base 1)
- `if` at nesting 1: +2 (nesting 1 + base 1)
- `and` operand: +1
- nested `if` at nesting 2: +3 (nesting 2 + base 1)
- `continue` (jump in loop): +1
- `elif` at nesting 1: +2 (nesting 1 + base 1)
Total cognitive = 1 + 2 + 1 + 3 + 1 + 2 = **10**

Rating: **moderate** (close to high boundary 11)

## Refactor Suggestions
1. **Extract Method**: pull nested `if item.priority > 5` into `_should_include(item)`.
2. **Guard Clause**: replace `elif` with early `continue` to flatten structure.
3. **Replace Conditional with Strategy** if `flag`/`priority` combos grow.

## Refactored (target: cyclo <= 4, cognitive <= 5)
```python
def process(items, flag):
    return [it for it in items if _should_keep(it, flag)]

def _should_keep(item, flag):
    if not (item.is_valid and flag):
        return item.is_optional
    return item.priority > 5
```
- `process`: cyclo=1, cognitive=1
- `_should_keep`: cyclo=2, cognitive=3
'''