@voodocs/cli 0.4.1 → 1.0.0

package/lib/darkarts/validation/semantic.py

@@ -0,0 +1,461 @@
+"""@darkarts
+⊢semantic-validator:validation.layer2
+∂{ast,re,pathlib,typing,dataclasses}
+⚠{python≥3.7,file:readable,annotation:parseable}
+⊨{∀validate→ValidationResult,∀import→detected,∀dependency→compared,¬modify-files,accurate:ast-based}
+🔒{read-only:files,¬write,¬network,¬exec}
+⚡{O(n)|n=file-size,ast-parsing:linear}
+
+Layer 2 Semantic Validation for @darkarts Annotations
+
+Validates that annotations accurately reflect the actual code:
+- Dependency validation (∂{} matches actual imports)
+- Import extraction (AST-based, handles all import styles)
+- Dependency parsing (extracts from annotation string)
+- Diff reporting (missing, extra, mismatched dependencies)
+- Batch validation (entire codebase at once)
+- Auto-fix suggestions (how to correct mismatches)
+"""
+
+import ast
+import re
+from pathlib import Path
+from typing import Set, List, Dict, Optional, Tuple
+from dataclasses import dataclass
+
+
+@dataclass
+class ValidationResult:
+    """Result of semantic validation."""
+    file_path: str
+    is_valid: bool
+    missing_deps: Set[str]  # In code but not in annotation
+    extra_deps: Set[str]    # In annotation but not in code
+    errors: List[str]
+    warnings: List[str]
+    suggestions: List[str]
+    
+    def __str__(self) -> str:
+        """Human-readable validation result."""
+        if self.is_valid:
+            return f"✅ {self.file_path}: Valid"
+        
+        lines = [f"❌ {self.file_path}: Invalid"]
+        
+        if self.missing_deps:
+            lines.append(f"  Missing from ∂{{}}: {', '.join(sorted(self.missing_deps))}")
+        
+        if self.extra_deps:
+            lines.append(f"  Extra in ∂{{}}: {', '.join(sorted(self.extra_deps))}")
+        
+        if self.errors:
+            for error in self.errors:
+                lines.append(f"  ERROR: {error}")
+        
+        if self.warnings:
+            for warning in self.warnings:
+                lines.append(f"  WARNING: {warning}")
+        
+        if self.suggestions:
+            lines.append("  Suggestions:")
+            for suggestion in self.suggestions:
+                lines.append(f"    • {suggestion}")
+        
+        return "\n".join(lines)
+
+
+class ImportExtractor(ast.NodeVisitor):
+    """AST visitor to extract all imports from a Python file."""
+    
+    def __init__(self, file_path: Optional[Path] = None):
+        self.imports: Set[str] = set()
+        self.from_imports: Dict[str, Set[str]] = {}
+        self.file_path = file_path
+        self.package_name = self._detect_package_name(file_path) if file_path else None
+    
+    def _detect_package_name(self, file_path: Path) -> Optional[str]:
+        """Detect the top-level package name from file path."""
+        # Look for common package indicators
+        parts = file_path.parts
+        
+        # Check for lib/darkarts pattern
+        if 'lib' in parts:
+            lib_idx = parts.index('lib')
+            if lib_idx + 1 < len(parts):
+                return parts[lib_idx + 1]
+        
+        # Check for src/package pattern
+        if 'src' in parts:
+            src_idx = parts.index('src')
+            if src_idx + 1 < len(parts):
+                return parts[src_idx + 1]
+        
+        # Look for setup.py or pyproject.toml in parent directories
+        current = file_path.parent
+        while current != current.parent:
+            if (current / 'setup.py').exists() or (current / 'pyproject.toml').exists():
+                # The directory name is likely the package
+                return current.name
+            current = current.parent
+        
+        return None
+    
+    def visit_Import(self, node: ast.Import):
+        """Handle 'import module' statements."""
+        for alias in node.names:
+            # Get the top-level module name
+            module = alias.name.split('.')[0]
+            self.imports.add(module)
+        self.generic_visit(node)
+    
+    def visit_ImportFrom(self, node: ast.ImportFrom):
+        """Handle 'from module import name' statements."""
+        if node.level > 0:
+            # Relative import (e.g., from ..parser.types import X)
+            # Convert to absolute import using package name
+            if self.package_name and node.module:
+                # Relative import with module (e.g., from ..parser.types)
+                module = node.module.split('.')[0]
+                self.imports.add(self.package_name)
+                
+                # Also track the submodule
+                if module not in self.from_imports:
+                    self.from_imports[module] = set()
+                for alias in node.names:
+                    self.from_imports[module].add(alias.name)
+            elif self.package_name:
+                # Relative import without module (e.g., from . import X)
+                self.imports.add(self.package_name)
+        elif node.module:
+            # Absolute import
+            # Get the top-level module name
+            module = node.module.split('.')[0]
+            self.imports.add(module)
+            
+            # Track what was imported from this module
+            if module not in self.from_imports:
+                self.from_imports[module] = set()
+            
+            for alias in node.names:
+                self.from_imports[module].add(alias.name)
+        
+        self.generic_visit(node)
+    
+    def get_all_imports(self) -> Set[str]:
+        """Get all unique top-level module names."""
+        return self.imports
+
+
+def extract_imports(file_path: Path) -> Set[str]:
+    """
+    Extract all imports from a Python file using AST parsing.
+    
+    Handles both absolute and relative imports.
+    
+    Args:
+        file_path: Path to the Python file
+    
+    Returns:
+        Set of top-level module names imported in the file
+    
+    Examples:
+        >>> extract_imports(Path("myfile.py"))
+        {'os', 'sys', 'pathlib', 'typing', 'darkarts'}
+    """
+    try:
+        content = file_path.read_text(encoding='utf-8')
+        tree = ast.parse(content, filename=str(file_path))
+        
+        extractor = ImportExtractor(file_path)
+        extractor.visit(tree)
+        
+        imports = extractor.get_all_imports()
+        
+        # Filter out standard library modules that are commonly omitted
+        # from annotations (optional - can be configured)
+        stdlib_to_keep = {
+            'typing', 'dataclasses', 'enum', 'abc', 'pathlib',
+            'datetime', 'json', 'yaml', 're', 'os', 'sys',
+            'time', 'uuid', 'collections', 'itertools', 'functools'
+        }
+        
+        # Keep all non-stdlib and explicitly listed stdlib modules
+        filtered_imports = {
+            imp for imp in imports
+            if not _is_stdlib_module(imp) or imp in stdlib_to_keep
+        }
+        
+        return filtered_imports
+    
+    except SyntaxError as e:
+        raise ValueError(f"Syntax error in {file_path}: {e}")
+    except Exception as e:
+        raise ValueError(f"Error parsing {file_path}: {e}")
+
+
+def _is_stdlib_module(module_name: str) -> bool:
+    """
+    Check if a module is part of Python's standard library.
+    
+    This is a heuristic - not 100% accurate but good enough.
+    """
+    # Common stdlib modules
+    stdlib = {
+        'abc', 'argparse', 'ast', 'asyncio', 'base64', 'bisect',
+        'collections', 'copy', 'csv', 'datetime', 'decimal', 'enum',
+        'functools', 'glob', 'hashlib', 'heapq', 'html', 'http',
+        'io', 'itertools', 'json', 'logging', 'math', 'operator',
+        'os', 'pathlib', 'pickle', 'platform', 'queue', 'random',
+        're', 'shutil', 'socket', 'sqlite3', 'string', 'struct',
+        'subprocess', 'sys', 'tempfile', 'threading', 'time',
+        'traceback', 'typing', 'unittest', 'urllib', 'uuid',
+        'warnings', 'weakref', 'xml', 'zipfile'
+    }
+    
+    return module_name in stdlib
+
+
+def parse_dependencies(annotation: str) -> Set[str]:
+    """
+    Parse the ∂{} section from a @darkarts annotation.
+    
+    Args:
+        annotation: The full @darkarts annotation string
+    
+    Returns:
+        Set of dependency module names
+    
+    Examples:
+        >>> annotation = '∂{os,sys,pathlib,typing,darkarts.core}'
+        >>> parse_dependencies(annotation)
+        {'os', 'sys', 'pathlib', 'typing', 'darkarts'}
+    """
+    # Find the ∂{...} section
+    pattern = r'∂\{([^}]*)\}'
+    match = re.search(pattern, annotation)
+    
+    if not match:
+        return set()
+    
+    deps_str = match.group(1)
+    
+    # Handle empty dependencies
+    if not deps_str.strip():
+        return set()
+    
+    # Split by comma and clean up
+    deps = set()
+    for dep in deps_str.split(','):
+        dep = dep.strip()
+        if dep:
+            # Extract top-level module name
+            # e.g., 'darkarts.core.plugin' -> 'darkarts'
+            top_level = dep.split('.')[0]
+            deps.add(top_level)
+    
+    return deps
+
+
+def extract_annotation(file_path: Path) -> Optional[str]:
+    """
+    Extract the @darkarts annotation from a Python file.
+    
+    Args:
+        file_path: Path to the Python file
+    
+    Returns:
+        The annotation string, or None if not found
+    """
+    try:
+        content = file_path.read_text(encoding='utf-8')
+        
+        # Check if file starts with @darkarts annotation
+        if not content.startswith('"""@darkarts'):
+            return None
+        
+        # Find the end of the docstring
+        end_idx = content.find('"""', 3)
+        if end_idx == -1:
+            return None
+        
+        annotation = content[3:end_idx]  # Skip opening """
+        return annotation
+    
+    except Exception as e:
+        raise ValueError(f"Error reading {file_path}: {e}")
+
+
+def validate_dependencies(file_path: Path, annotation: str) -> ValidationResult:
+    """
+    Validate that the ∂{} section matches actual imports in the file.
+    
+    Args:
+        file_path: Path to the Python file
+        annotation: The @darkarts annotation string
+    
+    Returns:
+        ValidationResult with detailed comparison
+    
+    Examples:
+        >>> result = validate_dependencies(Path("myfile.py"), annotation)
+        >>> if not result.is_valid:
+        ...     print(result)
+    """
+    errors = []
+    warnings = []
+    suggestions = []
+    
+    try:
+        # Extract actual imports from code
+        actual_imports = extract_imports(file_path)
+    except ValueError as e:
+        return ValidationResult(
+            file_path=str(file_path),
+            is_valid=False,
+            missing_deps=set(),
+            extra_deps=set(),
+            errors=[str(e)],
+            warnings=[],
+            suggestions=[]
+        )
+    
+    # Parse declared dependencies from annotation
+    try:
+        declared_deps = parse_dependencies(annotation)
+    except Exception as e:
+        return ValidationResult(
+            file_path=str(file_path),
+            is_valid=False,
+            missing_deps=set(),
+            extra_deps=set(),
+            errors=[f"Failed to parse dependencies: {e}"],
+            warnings=[],
+            suggestions=[]
+        )
+    
+    # Compare
+    missing_deps = actual_imports - declared_deps
+    extra_deps = declared_deps - actual_imports
+    
+    # Generate suggestions
+    if missing_deps:
+        suggestions.append(
+            f"Add to ∂{{}}: {', '.join(sorted(missing_deps))}"
+        )
+    
+    if extra_deps:
+        suggestions.append(
+            f"Remove from ∂{{}}: {', '.join(sorted(extra_deps))}"
+        )
+        warnings.append(
+            f"Declared dependencies not found in imports: {', '.join(sorted(extra_deps))}"
+        )
+    
+    # Check for common issues
+    if 'darkarts' in actual_imports and 'darkarts' not in declared_deps:
+        warnings.append(
+            "File imports from 'darkarts' package but doesn't declare it"
+        )
+    
+    is_valid = len(missing_deps) == 0 and len(extra_deps) == 0 and len(errors) == 0
+    
+    return ValidationResult(
+        file_path=str(file_path),
+        is_valid=is_valid,
+        missing_deps=missing_deps,
+        extra_deps=extra_deps,
+        errors=errors,
+        warnings=warnings,
+        suggestions=suggestions
+    )
+
+
+def validate_file(file_path: Path) -> ValidationResult:
+    """
+    Validate a single file's @darkarts annotation.
+    
+    Args:
+        file_path: Path to the Python file
+    
+    Returns:
+        ValidationResult
+    """
+    # Extract annotation
+    annotation = extract_annotation(file_path)
+    
+    if annotation is None:
+        return ValidationResult(
+            file_path=str(file_path),
+            is_valid=False,
+            missing_deps=set(),
+            extra_deps=set(),
+            errors=["No @darkarts annotation found"],
+            warnings=[],
+            suggestions=["Add @darkarts annotation to the file"]
+        )
+    
+    # Validate dependencies
+    return validate_dependencies(file_path, annotation)
+
+
+def validate_directory(directory: Path, recursive: bool = True) -> List[ValidationResult]:
+    """
+    Validate all Python files in a directory.
+    
+    Args:
+        directory: Path to the directory
+        recursive: Whether to search recursively
+    
+    Returns:
+        List of ValidationResult objects
+    """
+    results = []
+    
+    pattern = "**/*.py" if recursive else "*.py"
+    
+    for py_file in directory.glob(pattern):
+        if py_file.name.startswith('.'):
+            continue  # Skip hidden files
+        
+        result = validate_file(py_file)
+        results.append(result)
+    
+    return results
+
+
+def generate_fix_script(result: ValidationResult) -> str:
+    """
+    Generate a script to automatically fix dependency mismatches.
+    
+    Args:
+        result: ValidationResult with mismatches
+    
+    Returns:
+        Python code to fix the annotation
+    """
+    if result.is_valid:
+        return "# No fixes needed"
+    
+    script_lines = [
+        f"# Fix for {result.file_path}",
+        "",
+        "# Current issues:"
+    ]
+    
+    if result.missing_deps:
+        script_lines.append(f"# Missing: {', '.join(sorted(result.missing_deps))}")
+    
+    if result.extra_deps:
+        script_lines.append(f"# Extra: {', '.join(sorted(result.extra_deps))}")
+    
+    script_lines.extend([
+        "",
+        "# To fix, update the ∂{} section to:",
+        f"# ∂{{{', '.join(sorted(result.missing_deps | (parse_dependencies(extract_annotation(Path(result.file_path)) or '') - result.extra_deps)))}}}",
+    ])
+    
+    return "\n".join(script_lines)
+
+
+
+# CLI interface removed - use darkarts.validation API or voodocs CLI instead

package/lib/darkarts/validation/semantic_wrapper.py

@@ -0,0 +1,77 @@
+"""@darkarts
+⊢validation:semantic.wrapper
+∂{pathlib,typing}
+⚠{python≥3.7}
+⊨{∀method→delegates,¬state}
+🔒{read-only}
+⚡{O(1):creation,O(n):directory|n=files}
+"""
+
+"""
+Wrapper class for semantic validation functions.
+Provides object-oriented interface to functional validation code.
+"""
+
+from pathlib import Path
+from typing import List
+
+from . import semantic
+from .types import ValidationResult
+
+
+class SemanticValidator:
+    """
+    Semantic validator for @darkarts annotations.
+    
+    Validates that dependencies in ∂{} match actual imports.
+    
+    Usage:
+        validator = SemanticValidator()
+        result = validator.validate_file("myfile.py")
+        if not result.is_valid:
+            print(f"Validation failed: {result.errors}")
+    """
+    
+    def validate_file(self, file_path: str | Path) -> ValidationResult:
+        """
+        Validate a single file.
+        
+        Args:
+            file_path: Path to Python file to validate
+            
+        Returns:
+            ValidationResult with validation details
+        """
+        return semantic.validate_file(Path(file_path))
+    
+    def validate_directory(self, directory: str | Path, recursive: bool = True) -> List[ValidationResult]:
+        """
+        Validate all Python files in a directory.
+        
+        Args:
+            directory: Path to directory to validate
+            recursive: Whether to recurse into subdirectories
+            
+        Returns:
+            List of ValidationResult for each file
+        """
+        return semantic.validate_directory(Path(directory), recursive=recursive)
+    
+    def validate_path(self, path: str | Path, recursive: bool = False) -> List[ValidationResult]:
+        """
+        Validate a file or directory.
+        
+        Args:
+            path: Path to file or directory
+            recursive: Whether to recurse into subdirectories (for directories)
+            
+        Returns:
+            List of ValidationResult (single item for files)
+        """
+        path = Path(path)
+        if path.is_file():
+            return [self.validate_file(path)]
+        elif path.is_dir():
+            return self.validate_directory(path, recursive=recursive)
+        else:
+            raise ValueError(f"Path does not exist: {path}")

package/lib/darkarts/validation/test_validation.py

@@ -0,0 +1,160 @@
+"""@darkarts
+⊢validation:tests
+∂{unittest,pathlib,tempfile,typing}
+⚠{python≥3.7,pytest:optional}
+⊨{∀test→isolated,∀test→repeatable}
+🔒{read-only:tests}
+⚡{O(n)|n=test-count}
+"""
+
+"""
+Unit tests for validation module.
+"""
+
+import unittest
+import tempfile
+from pathlib import Path
+from typing import List
+
+# Import validation modules
+try:
+    from .semantic import SemanticValidator
+    from .performance import PerformanceTracker
+    from .types import ValidationResult, PerformanceResult
+except ImportError:
+    # Fallback for direct execution
+    import sys
+    sys.path.insert(0, str(Path(__file__).parent))
+    from semantic import SemanticValidator
+    from performance import PerformanceTracker
+    from types import ValidationResult, PerformanceResult
+
+
+class TestSemanticValidator(unittest.TestCase):
+    """Test semantic validation."""
+    
+    def setUp(self):
+        """Set up test fixtures."""
+        self.validator = SemanticValidator()
+        self.temp_dir = tempfile.mkdtemp()
+    
+    def test_validator_creation(self):
+        """Test validator can be created."""
+        self.assertIsNotNone(self.validator)
+    
+    def test_validate_simple_file(self):
+        """Test validation of a simple file."""
+        # Create a test file
+        test_file = Path(self.temp_dir) / "test.py"
+        test_file.write_text('''"""@darkarts
+⊢test:module
+∂{os,sys}
+⚠{}
+⊨{}
+🔒{}
+⚡{O(1)}
+"""
+import os
+import sys
+
+def main():
+    print("Hello")
+''')
+        
+        # Validate
+        result = self.validator.validate_file(test_file)
+        
+        # Check result
+        self.assertIsInstance(result, ValidationResult)
+        self.assertTrue(result.is_valid)
+        self.assertEqual(len(result.missing_deps), 0)
+        self.assertEqual(len(result.extra_deps), 0)
+    
+    def test_validate_missing_dependency(self):
+        """Test detection of missing dependency."""
+        test_file = Path(self.temp_dir) / "test_missing.py"
+        test_file.write_text('''"""@darkarts
+⊢test:module
+∂{os}
+⚠{}
+⊨{}
+🔒{}
+⚡{O(1)}
+"""
+import os
+import sys
+
+def main():
+    print("Hello")
+''')
+        
+        # Validate
+        result = self.validator.validate_file(test_file)
+        
+        # Check result
+        self.assertFalse(result.is_valid)
+        self.assertIn('sys', result.missing_deps)
+
+
+class TestPerformanceTracker(unittest.TestCase):
+    """Test performance tracking."""
+    
+    def setUp(self):
+        """Set up test fixtures."""
+        self.tracker = PerformanceTracker()
+        self.temp_dir = tempfile.mkdtemp()
+    
+    def test_tracker_creation(self):
+        """Test tracker can be created."""
+        self.assertIsNotNone(self.tracker)
+    
+    def test_analyze_simple_file(self):
+        """Test analysis of a simple file."""
+        test_file = Path(self.temp_dir) / "test.py"
+        test_file.write_text('''"""@darkarts
+⊢test:module
+∂{}
+⚠{}
+⊨{}
+🔒{}
+⚡{O(1)}
+"""
+
+def simple_function():
+    return 42
+''')
+        
+        # Analyze
+        result = self.tracker.analyze_file(test_file)
+        
+        # Check result
+        self.assertIsInstance(result, PerformanceResult)
+        self.assertTrue(result.is_valid)
+
+
+class TestValidationTypes(unittest.TestCase):
+    """Test validation type definitions."""
+    
+    def test_validation_result_creation(self):
+        """Test ValidationResult can be created."""
+        result = ValidationResult(
+            file_path="test.py",
+            is_valid=True,
+        )
+        self.assertEqual(result.file_path, "test.py")
+        self.assertTrue(result.is_valid)
+    
+    def test_validation_result_to_dict(self):
+        """Test ValidationResult can be serialized."""
+        result = ValidationResult(
+            file_path="test.py",
+            is_valid=True,
+        )
+        data = result.to_dict()
+        self.assertIsInstance(data, dict)
+        self.assertEqual(data["file_path"], "test.py")
+        self.assertTrue(data["is_valid"])
+
+
+if __name__ == "__main__":
+    unittest.main()