hanuscode 1.0.0__py3-none-any.whl

hanus/analysis/__init__.py

@@ -0,0 +1,5 @@
+# hanus/analysis/__init__.py
+"""Code analysis tools for HanusCode."""
+from .dependencies import DependencyAnalyzer, DependencyGraph, DependencyNode
+
+__all__ = ["DependencyAnalyzer", "DependencyGraph", "DependencyNode"]

hanus/analysis/debt.py

@@ -0,0 +1,702 @@
+# hanus/analysis/debt.py
+"""
+Análisis de deuda técnica.
+
+Detecta código muerto, complejidad ciclomática,
+score de mantenibilidad y sugiere refactors.
+"""
+from __future__ import annotations
+import ast
+import re
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Dict, List, Optional, Any, Set, Tuple
+from enum import Enum
+from collections import defaultdict
+
+
+class DebtType(Enum):
+    """Tipo de deuda técnica."""
+    CODE_DUPLICATION = "code_duplication"
+    DEAD_CODE = "dead_code"
+    HIGH_COMPLEXITY = "high_complexity"
+    LONG_FUNCTION = "long_function"
+    DEEP_NESTING = "deep_nesting"
+    TOO_MANY_PARAMETERS = "too_many_parameters"
+    MISSING_TESTS = "missing_tests"
+    UNUSED_IMPORTS = "unused_imports"
+    UNUSED_VARIABLES = "unused_variables"
+    MAGIC_NUMBERS = "magic_numbers"
+    TODO_COMMENTS = "todo_comments"
+    HARDCODED_VALUES = "hardcoded_values"
+    GOD_CLASS = "god_class"
+    FEATURE_ENVY = "feature_envy"
+    LONG_PARAMETER_LIST = "long_parameter_list"
+
+
+class DebtSeverity(Enum):
+    """Severidad de la deuda."""
+    LOW = 1
+    MEDIUM = 2
+    HIGH = 3
+    CRITICAL = 4
+
+
+@dataclass
+class DebtIssue:
+    """Un problema de deuda técnica detectado."""
+    id: str
+    type: DebtType
+    severity: DebtSeverity
+    file_path: str
+    line_start: int
+    line_end: int
+    description: str
+    suggestion: str
+    effort_minutes: int  # Estimación de esfuerzo para arreglar
+    metadata: Dict[str, Any] = field(default_factory=dict)
+
+    def to_dict(self) -> Dict:
+        return {
+            "id": self.id,
+            "type": self.type.value,
+            "severity": self.severity.value,
+            "file_path": self.file_path,
+            "line_start": self.line_start,
+            "line_end": self.line_end,
+            "description": self.description,
+            "suggestion": self.suggestion,
+            "effort_minutes": self.effort_minutes,
+        }
+
+
+@dataclass
+class FileMetrics:
+    """Métricas de un archivo."""
+    file_path: str
+    lines_of_code: int
+    cyclomatic_complexity: float
+    cognitive_complexity: float
+    maintainability_index: float  # 0-100, higher is better
+    function_count: int
+    class_count: int
+    comment_ratio: float
+    duplication_ratio: float
+    issues: List[DebtIssue] = field(default_factory=list)
+
+    def to_dict(self) -> Dict:
+        return {
+            "file_path": self.file_path,
+            "lines_of_code": self.lines_of_code,
+            "cyclomatic_complexity": round(self.cyclomatic_complexity, 2),
+            "cognitive_complexity": round(self.cognitive_complexity, 2),
+            "maintainability_index": round(self.maintainability_index, 2),
+            "function_count": self.function_count,
+            "class_count": self.class_count,
+            "comment_ratio": round(self.comment_ratio, 2),
+            "duplication_ratio": round(self.duplication_ratio, 2),
+            "issue_count": len(self.issues),
+        }
+
+
+@dataclass
+class DebtReport:
+    """Reporte completo de deuda técnica."""
+    project_root: str
+    files_analyzed: int
+    total_issues: int
+    total_effort_hours: float
+    maintainability_score: float  # 0-100, higher is better
+    metrics_by_file: Dict[str, FileMetrics] = field(default_factory=dict)
+    issues: List[DebtIssue] = field(default_factory=list)
+
+    def get_summary(self) -> Dict:
+        """Obtiene resumen ejecutivo."""
+        by_severity = defaultdict(int)
+        by_type = defaultdict(int)
+
+        for issue in self.issues:
+            by_severity[issue.severity.name] += 1
+            by_type[issue.type.value] += 1
+
+        return {
+            "files_analyzed": self.files_analyzed,
+            "total_issues": self.total_issues,
+            "total_effort_hours": round(self.total_effort_hours, 1),
+            "maintainability_score": round(self.maintainability_score, 1),
+            "by_severity": dict(by_severity),
+            "by_type": dict(by_type),
+        }
+
+
+class DebtAnalyzer:
+    """
+    Analiza deuda técnica en un proyecto.
+
+    Métricas:
+    - Complejidad ciclomática
+    - Líneas por función
+    - Profundidad de anidación
+    - Duplicación de código
+    - Imports no usados
+    """
+
+    # Umbrales configurables
+    MAX_FUNCTION_LINES = 50
+    MAX_FUNCTION_PARAMS = 5
+    MAX_NESTING_DEPTH = 4
+    MAX_CLASS_METHODS = 15
+    MAX_CYCLOMATIC_COMPLEXITY = 10
+    MIN_MAINTAINABILITY_INDEX = 20
+
+    def __init__(self, project_root: Path):
+        self.project_root = project_root
+        self._issue_counter = 0
+
+    def analyze_project(
+        self,
+        include_patterns: List[str] = None,
+        exclude_patterns: List[str] = None
+    ) -> DebtReport:
+        """
+        Analiza todo el proyecto.
+
+        Args:
+            include_patterns: Patrones de archivos a incluir
+            exclude_patterns: Patrones a excluir
+
+        Returns:
+            DebtReport con el análisis completo
+        """
+        include_patterns = include_patterns or ["*.py", "*.js", "*.ts"]
+        exclude_patterns = exclude_patterns or [
+            "node_modules", "__pycache__", ".git", "venv", "env",
+            "dist", "build", "test", "tests"
+        ]
+
+        report = DebtReport(
+            project_root=str(self.project_root),
+            files_analyzed=0,
+            total_issues=0,
+            total_effort_hours=0,
+            maintainability_score=100,
+        )
+
+        # Recolectar archivos
+        files = self._collect_files(include_patterns, exclude_patterns)
+
+        # Analizar cada archivo
+        for file_path in files:
+            metrics = self.analyze_file(file_path)
+            report.metrics_by_file[str(file_path)] = metrics
+            report.issues.extend(metrics.issues)
+            report.files_analyzed += 1
+
+        # Calcular totales
+        report.total_issues = len(report.issues)
+        report.total_effort_hours = sum(i.effort_minutes for i in report.issues) / 60
+
+        # Calcular score de mantenibilidad promedio
+        if report.metrics_by_file:
+            report.maintainability_score = sum(
+                m.maintainability_index for m in report.metrics_by_file.values()
+            ) / len(report.metrics_by_file)
+
+        return report
+
+    def analyze_file(self, file_path: Path) -> FileMetrics:
+        """
+        Analiza un archivo específico.
+
+        Args:
+            file_path: Ruta del archivo
+
+        Returns:
+            FileMetrics con el análisis
+        """
+        ext = file_path.suffix.lower()
+
+        try:
+            content = file_path.read_text(encoding="utf-8", errors="replace")
+        except Exception:
+            return FileMetrics(
+                file_path=str(file_path),
+                lines_of_code=0,
+                cyclomatic_complexity=0,
+                cognitive_complexity=0,
+                maintainability_index=0,
+                function_count=0,
+                class_count=0,
+                comment_ratio=0,
+                duplication_ratio=0,
+            )
+
+        lines = content.split('\n')
+        loc = len([l for l in lines if l.strip() and not l.strip().startswith('#')])
+
+        if ext == '.py':
+            return self._analyze_python(file_path, content, lines, loc)
+        elif ext in ('.js', '.ts', '.jsx', '.tsx'):
+            return self._analyze_javascript(file_path, content, lines, loc)
+
+        return FileMetrics(
+            file_path=str(file_path),
+            lines_of_code=loc,
+            cyclomatic_complexity=0,
+            cognitive_complexity=0,
+            maintainability_index=50,
+            function_count=0,
+            class_count=0,
+            comment_ratio=0,
+            duplication_ratio=0,
+        )
+
+    # ══════════════════════════════════════════════════════════════════════════
+    # ANÁLISIS PYTHON
+    # ══════════════════════════════════════════════════════════════════════════
+
+    def _analyze_python(
+        self,
+        file_path: Path,
+        content: str,
+        lines: List[str],
+        loc: int
+    ) -> FileMetrics:
+        """Analiza código Python."""
+        issues = []
+        function_count = 0
+        class_count = 0
+        total_complexity = 0
+        total_cognitive = 0
+
+        try:
+            tree = ast.parse(content)
+        except SyntaxError:
+            return FileMetrics(
+                file_path=str(file_path),
+                lines_of_code=loc,
+                cyclomatic_complexity=0,
+                cognitive_complexity=0,
+                maintainability_index=0,
+                function_count=0,
+                class_count=0,
+                comment_ratio=0,
+                duplication_ratio=0,
+            )
+
+        # Analizar imports no usados
+        imports = set()
+        for node in ast.walk(tree):
+            if isinstance(node, ast.Import):
+                for alias in node.names:
+                    imports.add(alias.asname or alias.name.split('.')[0])
+            elif isinstance(node, ast.ImportFrom):
+                for alias in node.names:
+                    imports.add(alias.asname or alias.name)
+
+        # Encontrar nombres usados
+        used_names = set()
+        for node in ast.walk(tree):
+            if isinstance(node, ast.Name):
+                used_names.add(node.id)
+
+        unused_imports = imports - used_names
+        for imp in unused_imports:
+            issues.append(self._create_issue(
+                DebtType.UNUSED_IMPORTS,
+                DebtSeverity.LOW,
+                str(file_path),
+                1, 1,
+                f"Unused import: {imp}",
+                f"Remove import: {imp}",
+                2
+            ))
+
+        # Analizar clases y funciones
+        for node in ast.iter_child_nodes(tree):
+            if isinstance(node, ast.ClassDef):
+                class_count += 1
+                issues.extend(self._analyze_class(node, str(file_path)))
+
+            elif isinstance(node, (ast.FunctionDef, ast.AsyncFunctionDef)):
+                function_count += 1
+                complexity = self._calculate_complexity(node)
+                cognitive = self._calculate_cognitive_complexity(node)
+                total_complexity += complexity
+                total_cognitive += cognitive
+
+                issues.extend(self._analyze_function(node, str(file_path), complexity))
+
+        # Detectar código duplicado (simplificado)
+        duplication = self._detect_duplication(lines)
+        if duplication > 0.1:
+            issues.append(self._create_issue(
+                DebtType.CODE_DUPLICATION,
+                DebtSeverity.MEDIUM,
+                str(file_path),
+                1, loc,
+                f"Code duplication detected ({duplication:.0%})",
+                "Refactor duplicated code into reusable functions",
+                int(duplication * loc * 2)
+            ))
+
+        # Detectar TODOs
+        for i, line in enumerate(lines, 1):
+            if 'TODO' in line or 'FIXME' in line:
+                issues.append(self._create_issue(
+                    DebtType.TODO_COMMENTS,
+                    DebtSeverity.LOW,
+                    str(file_path),
+                    i, i,
+                    "TODO/FIXME comment found",
+                    "Implement or remove TODO",
+                    15
+                ))
+
+        # Calcular métricas
+        avg_complexity = total_complexity / function_count if function_count > 0 else 0
+        avg_cognitive = total_cognitive / function_count if function_count > 0 else 0
+
+        # Maintainability Index (simplificado)
+        # MI = 171 - 5.2 * ln(V) - 0.23 * G - 16.2 * ln(LOC)
+        # Simplificado para este análisis
+        mi = max(0, min(100, 100 - avg_complexity * 5 - (loc / 100) * 5))
+
+        # Comment ratio
+        comment_lines = len([l for l in lines if l.strip().startswith('#')])
+        comment_ratio = comment_lines / loc if loc > 0 else 0
+
+        return FileMetrics(
+            file_path=str(file_path),
+            lines_of_code=loc,
+            cyclomatic_complexity=avg_complexity,
+            cognitive_complexity=avg_cognitive,
+            maintainability_index=mi,
+            function_count=function_count,
+            class_count=class_count,
+            comment_ratio=comment_ratio,
+            duplication_ratio=duplication,
+            issues=issues,
+        )
+
+    def _analyze_class(self, node: ast.ClassDef, file_path: str) -> List[DebtIssue]:
+        """Analiza una clase."""
+        issues = []
+
+        # God Class: demasiados métodos
+        methods = [n for n in node.body if isinstance(n, (ast.FunctionDef, ast.AsyncFunctionDef))]
+        if len(methods) > self.MAX_CLASS_METHODS:
+            issues.append(self._create_issue(
+                DebtType.GOD_CLASS,
+                DebtSeverity.HIGH,
+                file_path,
+                node.lineno, node.end_lineno or node.lineno,
+                f"Class '{node.name}' has {len(methods)} methods (max {self.MAX_CLASS_METHODS})",
+                "Split class into smaller, focused classes",
+                len(methods) * 5
+            ))
+
+        # Verificar métodos individuales
+        for method in methods:
+            issues.extend(self._analyze_function(method, file_path, 0, parent_class=node.name))
+
+        return issues
+
+    def _analyze_function(
+        self,
+        node: ast.FunctionDef,
+        file_path: str,
+        complexity: int,
+        parent_class: str = None
+    ) -> List[DebtIssue]:
+        """Analiza una función/método."""
+        issues = []
+        func_name = f"{parent_class}.{node.name}" if parent_class else node.name
+
+        # Líneas de código
+        func_lines = (node.end_lineno or node.lineno) - node.lineno + 1
+
+        # Función larga
+        if func_lines > self.MAX_FUNCTION_LINES:
+            issues.append(self._create_issue(
+                DebtType.LONG_FUNCTION,
+                DebtSeverity.MEDIUM,
+                file_path,
+                node.lineno, node.end_lineno or node.lineno,
+                f"Function '{func_name}' has {func_lines} lines (max {self.MAX_FUNCTION_LINES})",
+                "Break into smaller functions",
+                func_lines // 10
+            ))
+
+        # Muchos parámetros
+        param_count = len(node.args.args) + len(node.args.kwonlyargs)
+        if node.args.vararg:
+            param_count += 1
+        if node.args.kwarg:
+            param_count += 1
+
+        if param_count > self.MAX_FUNCTION_PARAMS:
+            issues.append(self._create_issue(
+                DebtType.TOO_MANY_PARAMETERS,
+                DebtSeverity.MEDIUM,
+                file_path,
+                node.lineno, node.lineno,
+                f"Function '{func_name}' has {param_count} parameters (max {self.MAX_FUNCTION_PARAMS})",
+                "Use parameter object or refactor",
+                param_count * 3
+            ))
+
+        # Alta complejidad ciclomática
+        if complexity > self.MAX_CYCLOMATIC_COMPLEXITY:
+            issues.append(self._create_issue(
+                DebtType.HIGH_COMPLEXITY,
+                DebtSeverity.HIGH,
+                file_path,
+                node.lineno, node.end_lineno or node.lineno,
+                f"Function '{func_name}' has complexity {complexity} (max {self.MAX_CYCLOMATIC_COMPLEXITY})",
+                "Simplify control flow, extract methods",
+                complexity * 5
+            ))
+
+        # Profundidad de anidación
+        max_depth = self._calculate_nesting_depth(node)
+        if max_depth > self.MAX_NESTING_DEPTH:
+            issues.append(self._create_issue(
+                DebtType.DEEP_NESTING,
+                DebtSeverity.MEDIUM,
+                file_path,
+                node.lineno, node.end_lineno or node.lineno,
+                f"Function '{func_name}' has nesting depth {max_depth} (max {self.MAX_NESTING_DEPTH})",
+                "Extract nested logic into separate functions",
+                max_depth * 10
+            ))
+
+        # Números mágicos
+        for child in ast.walk(node):
+            if isinstance(child, ast.Constant) and isinstance(child.value, (int, float)):
+                # Ignorar 0, 1, -1 y otros comunes
+                if child.value not in (0, 1, -1, 2, 10, 100, 1000, True, False):
+                    issues.append(self._create_issue(
+                        DebtType.MAGIC_NUMBERS,
+                        DebtSeverity.LOW,
+                        file_path,
+                        child.lineno, child.lineno,
+                        f"Magic number {child.value} in function '{func_name}'",
+                        "Define as named constant",
+                        2
+                    ))
+
+        return issues
+
+    # ══════════════════════════════════════════════════════════════════════════
+    # ANÁLISIS JAVASCRIPT
+    # ══════════════════════════════════════════════════════════════════════════
+
+    def _analyze_javascript(
+        self,
+        file_path: Path,
+        content: str,
+        lines: List[str],
+        loc: int
+    ) -> FileMetrics:
+        """Analiza código JavaScript."""
+        issues = []
+        function_count = 0
+        class_count = 0
+
+        # Contar funciones
+        func_pattern = r'(?:export\s+)?(?:async\s+)?function\s+(\w+)'
+        function_count = len(re.findall(func_pattern, content))
+
+        # Contar clases
+        class_pattern = r'(?:export\s+)?class\s+(\w+)'
+        class_count = len(re.findall(class_pattern, content))
+
+        # Detectar var (debería usar let/const)
+        var_pattern = r'\bvar\s+\w+'
+        for i, line in enumerate(lines, 1):
+            if re.search(var_pattern, line):
+                issues.append(self._create_issue(
+                    DebtType.DEPRECATED_USAGE,
+                    DebtSeverity.LOW,
+                    str(file_path),
+                    i, i,
+                    "Use of 'var' - prefer 'let' or 'const'",
+                    "Replace 'var' with 'let' or 'const'",
+                    2
+                ))
+
+        # Detectar console.log
+        for i, line in enumerate(lines, 1):
+            if 'console.log' in line:
+                issues.append(self._create_issue(
+                    DebtType.DEAD_CODE,
+                    DebtSeverity.LOW,
+                    str(file_path),
+                    i, i,
+                    "console.log statement found",
+                    "Remove or replace with proper logging",
+                    1
+                ))
+
+        # TODOs
+        for i, line in enumerate(lines, 1):
+            if 'TODO' in line or 'FIXME' in line:
+                issues.append(self._create_issue(
+                    DebtType.TODO_COMMENTS,
+                    DebtSeverity.LOW,
+                    str(file_path),
+                    i, i,
+                    "TODO/FIXME comment found",
+                    "Implement or remove TODO",
+                    15
+                ))
+
+        # Estimar complejidad (simplificado)
+        complexity = len(re.findall(r'\b(if|for|while|switch|catch|&&|\|\|)\b', content))
+
+        return FileMetrics(
+            file_path=str(file_path),
+            lines_of_code=loc,
+            cyclomatic_complexity=complexity / function_count if function_count > 0 else 0,
+            cognitive_complexity=0,
+            maintainability_index=max(0, min(100, 100 - complexity)),
+            function_count=function_count,
+            class_count=class_count,
+            comment_ratio=0,
+            duplication_ratio=0,
+            issues=issues,
+        )
+
+    # ══════════════════════════════════════════════════════════════════════════
+    # MÉTODOS PRIVADOS
+    # ══════════════════════════════════════════════════════════════════════════
+
+    def _calculate_complexity(self, node: ast.FunctionDef) -> int:
+        """Calcula complejidad ciclomática."""
+        complexity = 1
+
+        for child in ast.walk(node):
+            if isinstance(child, (ast.If, ast.While, ast.For, ast.ExceptHandler)):
+                complexity += 1
+            elif isinstance(child, ast.BoolOp):
+                complexity += len(child.values) - 1
+            elif isinstance(child, ast.comprehension):
+                complexity += 1
+                complexity += len(child.ifs)
+
+        return complexity
+
+    def _calculate_cognitive_complexity(self, node: ast.FunctionDef) -> int:
+        """Calcula complejidad cognitiva."""
+        complexity = 0
+        nesting = 0
+
+        def visit(n, depth=0):
+            nonlocal complexity, nesting
+
+            if isinstance(n, (ast.If, ast.While, ast.For)):
+                complexity += depth + 1
+                for child in ast.iter_child_nodes(n):
+                    visit(child, depth + 1)
+            elif isinstance(n, ast.ExceptHandler):
+                complexity += depth + 1
+                for child in ast.iter_child_nodes(n):
+                    visit(child, depth + 1)
+            else:
+                for child in ast.iter_child_nodes(n):
+                    visit(child, depth)
+
+        visit(node)
+        return complexity
+
+    def _calculate_nesting_depth(self, node: ast.FunctionDef) -> int:
+        """Calcula profundidad máxima de anidación."""
+        max_depth = 0
+
+        def visit(n, depth=0):
+            nonlocal max_depth
+
+            if isinstance(n, (ast.If, ast.While, ast.For, ast.With, ast.Try)):
+                max_depth = max(max_depth, depth + 1)
+                for child in ast.iter_child_nodes(n):
+                    visit(child, depth + 1)
+            else:
+                for child in ast.iter_child_nodes(n):
+                    visit(child, depth)
+
+        visit(node)
+        return max_depth
+
+    def _detect_duplication(self, lines: List[str]) -> float:
+        """Detecta duplicación de código (simplificado)."""
+        if len(lines) < 10:
+            return 0
+
+        # Buscar líneas idénticas
+        line_counts = defaultdict(int)
+        for line in lines:
+            stripped = line.strip()
+            if stripped and not stripped.startswith('#'):
+                line_counts[stripped] += 1
+
+        duplicated = sum(count - 1 for count in line_counts.values() if count > 1)
+        return duplicated / len(lines) if lines else 0
+
+    def _collect_files(
+        self,
+        include_patterns: List[str],
+        exclude_patterns: List[str]
+    ) -> List[Path]:
+        """Recolecta archivos del proyecto."""
+        files = []
+
+        for pattern in include_patterns:
+            for file_path in self.project_root.rglob(pattern):
+                # Verificar exclusiones
+                rel_path = str(file_path.relative_to(self.project_root))
+                if any(exc in rel_path for exc in exclude_patterns):
+                    continue
+                files.append(file_path)
+
+        return files
+
+    def _create_issue(
+        self,
+        type: DebtType,
+        severity: DebtSeverity,
+        file_path: str,
+        line_start: int,
+        line_end: int,
+        description: str,
+        suggestion: str,
+        effort_minutes: int
+    ) -> DebtIssue:
+        """Crea un issue de deuda técnica."""
+        self._issue_counter += 1
+        return DebtIssue(
+            id=f"debt_{self._issue_counter}",
+            type=type,
+            severity=severity,
+            file_path=file_path,
+            line_start=line_start,
+            line_end=line_end,
+            description=description,
+            suggestion=suggestion,
+            effort_minutes=effort_minutes,
+        )
+
+
+# ══════════════════════════════════════════════════════════════════════════════
+# INSTANCIA GLOBAL
+# ══════════════════════════════════════════════════════════════════════════════
+
+_analyzer_instance: Optional[DebtAnalyzer] = None
+
+
+def get_debt_analyzer(project_root: Path = None) -> DebtAnalyzer:
+    """Obtiene la instancia global del analizador de deuda."""
+    global _analyzer_instance
+    if _analyzer_instance is None or (project_root and _analyzer_instance.project_root != project_root):
+        _analyzer_instance = DebtAnalyzer(project_root or Path.cwd())
+    return _analyzer_instance