@voodocs/cli 0.4.1 → 1.0.0

package/lib/darkarts/validation/performance.py

@@ -0,0 +1,412 @@
+"""@darkarts
+⊢performance:validation.complexity-tracking
+∂{time,pathlib,typing,dataclasses,json,re,ast,statistics}
+⚠{python≥3.7,file:readable,executable:for-benchmarking}
+⊨{∀track→metrics-collected,∀validate→complexity-verified,∀benchmark→accurate,non-invasive:no-code-modification}
+🔒{read-only:source,write:metrics,¬network,exec:isolated-subprocess}
+⚡{O(n*m)|n=file-size,m=benchmark-iterations}
+
+Performance Tracking and Complexity Validation
+
+Validates performance claims in @darkarts annotations with:
+- Complexity extraction (parse ⚡{} section)
+- Static analysis (count loops, recursion, operations)
+- Runtime benchmarking (measure actual performance)
+- Complexity verification (compare claimed vs actual)
+- Performance regression detection (track over time)
+- Optimization suggestions (identify bottlenecks)
+"""
+
+import time
+import ast
+import re
+import json
+import statistics
+from pathlib import Path
+from typing import Dict, List, Optional, Tuple, Any
+from dataclasses import dataclass, field
+from datetime import datetime
+
+
+@dataclass
+class ComplexityInfo:
+    """Complexity information from annotation."""
+    claimed: str  # e.g., "O(n)", "O(n*d)", "O(1)"
+    variables: Dict[str, str]  # e.g., {"n": "file-size", "d": "depth"}
+    notes: List[str]  # Additional notes like "worst-case:O(2^n)"
+    
+    def __str__(self) -> str:
+        return self.claimed
+
+
+@dataclass
+class PerformanceMetrics:
+    """Performance metrics from benchmarking."""
+    execution_times: List[float]  # Multiple runs
+    mean_time: float
+    median_time: float
+    std_dev: float
+    min_time: float
+    max_time: float
+    
+    def __str__(self) -> str:
+        return f"μ={self.mean_time:.4f}s σ={self.std_dev:.4f}s"
+
+
+@dataclass
+class ComplexityAnalysis:
+    """Static complexity analysis results."""
+    loop_count: int
+    nested_loop_depth: int
+    recursion_detected: bool
+    function_calls: int
+    estimated_complexity: str
+    
+    def __str__(self) -> str:
+        return f"{self.estimated_complexity} (loops={self.loop_count}, depth={self.nested_loop_depth})"
+
+
+@dataclass
+class PerformanceResult:
+    """Complete performance validation result."""
+    file_path: str
+    claimed_complexity: Optional[ComplexityInfo]
+    static_analysis: ComplexityAnalysis
+    benchmarks: Optional[PerformanceMetrics]
+    is_valid: bool
+    warnings: List[str] = field(default_factory=list)
+    suggestions: List[str] = field(default_factory=list)
+    
+    def __str__(self) -> str:
+        lines = [f"Performance Analysis: {self.file_path}"]
+        
+        if self.claimed_complexity:
+            lines.append(f"  Claimed: {self.claimed_complexity}")
+        
+        lines.append(f"  Static: {self.static_analysis}")
+        
+        if self.benchmarks:
+            lines.append(f"  Benchmarks: {self.benchmarks}")
+        
+        if not self.is_valid:
+            lines.append("  ❌ Complexity claim may be inaccurate")
+        else:
+            lines.append("  ✅ Complexity claim validated")
+        
+        if self.warnings:
+            for warning in self.warnings:
+                lines.append(f"  ⚠️  {warning}")
+        
+        if self.suggestions:
+            for suggestion in self.suggestions:
+                lines.append(f"  💡 {suggestion}")
+        
+        return "\n".join(lines)
+
+
+class ComplexityAnalyzer(ast.NodeVisitor):
+    """Analyzes code complexity using AST."""
+    
+    def __init__(self):
+        self.loop_count = 0
+        self.max_nested_depth = 0
+        self.current_depth = 0
+        self.recursion_detected = False
+        self.function_calls = 0
+        self.function_names = set()
+        self.current_function = None
+    
+    def visit_For(self, node: ast.For):
+        """Visit for loops."""
+        self.loop_count += 1
+        self.current_depth += 1
+        self.max_nested_depth = max(self.max_nested_depth, self.current_depth)
+        self.generic_visit(node)
+        self.current_depth -= 1
+    
+    def visit_While(self, node: ast.While):
+        """Visit while loops."""
+        self.loop_count += 1
+        self.current_depth += 1
+        self.max_nested_depth = max(self.max_nested_depth, self.current_depth)
+        self.generic_visit(node)
+        self.current_depth -= 1
+    
+    def visit_FunctionDef(self, node: ast.FunctionDef):
+        """Visit function definitions."""
+        old_function = self.current_function
+        self.current_function = node.name
+        self.function_names.add(node.name)
+        self.generic_visit(node)
+        self.current_function = old_function
+    
+    def visit_Call(self, node: ast.Call):
+        """Visit function calls."""
+        self.function_calls += 1
+        
+        # Check for recursion
+        if isinstance(node.func, ast.Name):
+            if node.func.id == self.current_function:
+                self.recursion_detected = True
+        
+        self.generic_visit(node)
+    
+    def estimate_complexity(self) -> str:
+        """Estimate Big-O complexity from static analysis."""
+        if self.recursion_detected:
+            return "O(2^n)"  # Exponential (worst case for recursion)
+        
+        if self.max_nested_depth >= 3:
+            return "O(n^3)"
+        elif self.max_nested_depth == 2:
+            return "O(n^2)"
+        elif self.max_nested_depth == 1 or self.loop_count > 0:
+            return "O(n)"
+        else:
+            return "O(1)"
+
+
+def parse_complexity_annotation(annotation: str) -> Optional[ComplexityInfo]:
+    """
+    Parse the ⚡{} section from an annotation.
+    
+    Args:
+        annotation: The @darkarts annotation string
+    
+    Returns:
+        ComplexityInfo if found, None otherwise
+    """
+    # Find the ⚡{...} section
+    pattern = r'⚡\{([^}]+)\}'
+    match = re.search(pattern, annotation)
+    
+    if not match:
+        return None
+    
+    complexity_str = match.group(1)
+    
+    # Parse complexity (e.g., "O(n*d)|n=file-size,d=depth")
+    parts = complexity_str.split('|')
+    claimed = parts[0].strip()
+    
+    variables = {}
+    notes = []
+    
+    if len(parts) > 1:
+        # Parse variable definitions and notes
+        for part in parts[1:]:
+            if '=' in part:
+                key, value = part.split('=', 1)
+                variables[key.strip()] = value.strip()
+            else:
+                notes.append(part.strip())
+    
+    return ComplexityInfo(
+        claimed=claimed,
+        variables=variables,
+        notes=notes
+    )
+
+
+def analyze_complexity(file_path: Path) -> ComplexityAnalysis:
+    """
+    Perform static complexity analysis on a Python file.
+    
+    Args:
+        file_path: Path to the Python file
+    
+    Returns:
+        ComplexityAnalysis results
+    """
+    try:
+        content = file_path.read_text(encoding='utf-8')
+        tree = ast.parse(content, filename=str(file_path))
+        
+        analyzer = ComplexityAnalyzer()
+        analyzer.visit(tree)
+        
+        return ComplexityAnalysis(
+            loop_count=analyzer.loop_count,
+            nested_loop_depth=analyzer.max_nested_depth,
+            recursion_detected=analyzer.recursion_detected,
+            function_calls=analyzer.function_calls,
+            estimated_complexity=analyzer.estimate_complexity()
+        )
+    
+    except Exception as e:
+        return ComplexityAnalysis(
+            loop_count=0,
+            nested_loop_depth=0,
+            recursion_detected=False,
+            function_calls=0,
+            estimated_complexity="Unknown"
+        )
+
+
+def benchmark_file(file_path: Path, iterations: int = 10) -> Optional[PerformanceMetrics]:
+    """
+    Benchmark a Python file by importing and measuring execution time.
+    
+    Note: This is a simplified benchmark. Real benchmarking would need
+    to call specific functions with test data.
+    
+    Args:
+        file_path: Path to the Python file
+        iterations: Number of benchmark iterations
+    
+    Returns:
+        PerformanceMetrics if successful, None otherwise
+    """
+    # This is a placeholder - real benchmarking would be more sophisticated
+    # and would need test data and function identification
+    
+    execution_times = []
+    
+    for _ in range(iterations):
+        start = time.perf_counter()
+        
+        try:
+            # Simple import timing (not a real benchmark)
+            # In practice, you'd want to call specific functions
+            with open(file_path, 'r') as f:
+                content = f.read()
+                compile(content, str(file_path), 'exec')
+        except Exception:
+            return None
+        
+        end = time.perf_counter()
+        execution_times.append(end - start)
+    
+    return PerformanceMetrics(
+        execution_times=execution_times,
+        mean_time=statistics.mean(execution_times),
+        median_time=statistics.median(execution_times),
+        std_dev=statistics.stdev(execution_times) if len(execution_times) > 1 else 0.0,
+        min_time=min(execution_times),
+        max_time=max(execution_times)
+    )
+
+
+def validate_complexity(
+    claimed: ComplexityInfo,
+    static: ComplexityAnalysis
+) -> Tuple[bool, List[str], List[str]]:
+    """
+    Validate claimed complexity against static analysis.
+    
+    Args:
+        claimed: Claimed complexity from annotation
+        static: Static analysis results
+    
+    Returns:
+        Tuple of (is_valid, warnings, suggestions)
+    """
+    warnings = []
+    suggestions = []
+    is_valid = True
+    
+    # Extract claimed complexity class
+    claimed_str = claimed.claimed.upper()
+    estimated_str = static.estimated_complexity.upper()
+    
+    # Simple validation (could be more sophisticated)
+    if "O(1)" in claimed_str and static.loop_count > 0:
+        warnings.append(f"Claims O(1) but has {static.loop_count} loops")
+        is_valid = False
+        suggestions.append(f"Consider updating to {static.estimated_complexity}")
+    
+    if "O(N)" in claimed_str and static.nested_loop_depth > 1:
+        warnings.append(f"Claims O(n) but has nested loops (depth={static.nested_loop_depth})")
+        is_valid = False
+        suggestions.append(f"Consider updating to {static.estimated_complexity}")
+    
+    if static.recursion_detected and "2^N" not in claimed_str and "EXPONENTIAL" not in claimed_str:
+        warnings.append("Recursion detected but not reflected in complexity claim")
+        suggestions.append("Consider adding worst-case exponential complexity note")
+    
+    return is_valid, warnings, suggestions
+
+
+def track_performance(file_path: Path, benchmark: bool = False) -> PerformanceResult:
+    """
+    Complete performance tracking for a file.
+    
+    Args:
+        file_path: Path to the Python file
+        benchmark: Whether to run benchmarks (can be slow)
+    
+    Returns:
+        PerformanceResult with complete analysis
+    """
+    # Extract annotation
+    try:
+        content = file_path.read_text(encoding='utf-8')
+        if content.startswith('"""@darkarts'):
+            end_idx = content.find('"""', 3)
+            if end_idx != -1:
+                annotation = content[3:end_idx]
+                claimed = parse_complexity_annotation(annotation)
+            else:
+                claimed = None
+        else:
+            claimed = None
+    except Exception:
+        claimed = None
+    
+    # Static analysis
+    static = analyze_complexity(file_path)
+    
+    # Benchmarks (optional)
+    benchmarks = None
+    if benchmark:
+        benchmarks = benchmark_file(file_path)
+    
+    # Validation
+    if claimed:
+        is_valid, warnings, suggestions = validate_complexity(claimed, static)
+    else:
+        is_valid = True
+        warnings = ["No complexity annotation found"]
+        suggestions = [f"Consider adding: ⚡{{{static.estimated_complexity}}}"]
+    
+    return PerformanceResult(
+        file_path=str(file_path),
+        claimed_complexity=claimed,
+        static_analysis=static,
+        benchmarks=benchmarks,
+        is_valid=is_valid,
+        warnings=warnings,
+        suggestions=suggestions
+    )
+
+
+def save_metrics(result: PerformanceResult, output_path: Path):
+    """Save performance metrics to JSON file."""
+    data = {
+        'file_path': result.file_path,
+        'timestamp': datetime.now().isoformat(),
+        'claimed_complexity': result.claimed_complexity.claimed if result.claimed_complexity else None,
+        'static_analysis': {
+            'loop_count': result.static_analysis.loop_count,
+            'nested_loop_depth': result.static_analysis.nested_loop_depth,
+            'recursion_detected': result.static_analysis.recursion_detected,
+            'estimated_complexity': result.static_analysis.estimated_complexity
+        },
+        'is_valid': result.is_valid,
+        'warnings': result.warnings,
+        'suggestions': result.suggestions
+    }
+    
+    if result.benchmarks:
+        data['benchmarks'] = {
+            'mean_time': result.benchmarks.mean_time,
+            'median_time': result.benchmarks.median_time,
+            'std_dev': result.benchmarks.std_dev
+        }
+    
+    with open(output_path, 'w') as f:
+        json.dump(data, f, indent=2)
+
+
+
+# CLI interface removed - use darkarts.validation API or voodocs CLI instead

package/lib/darkarts/validation/performance_wrapper.py

@@ -0,0 +1,37 @@
+"""@darkarts
+⊢validation:performance.wrapper
+∂{pathlib,typing}
+⚠{python≥3.7}
+⊨{∀method→delegates,¬state}
+🔒{read-only}
+⚡{O(n):directory-analysis|n=files,O(1):single-file}
+"""
+
+from pathlib import Path
+from typing import List
+
+from . import performance
+from .types import PerformanceResult
+
+
+class PerformanceTracker:
+    """Performance tracker for @darkarts annotations."""
+    
+    def analyze_file(self, file_path: str | Path) -> PerformanceResult:
+        """Analyze a single file."""
+        return performance.track_performance(Path(file_path), benchmark=False)
+    
+    def analyze_directory(self, directory: str | Path, recursive: bool = True) -> List[PerformanceResult]:
+        """Analyze all files in a directory."""
+        results = []
+        path = Path(directory)
+        pattern = "**/*.py" if recursive else "*.py"
+        for file_path in path.glob(pattern):
+            if file_path.is_file():
+                try:
+                    result = self.analyze_file(file_path)
+                    results.append(result)
+                except Exception:
+                    # Skip files that can't be analyzed
+                    pass
+        return results