@voodocs/cli 0.4.2 → 1.0.1

package/lib/darkarts/plugins/voodocs/documentation_generator.py

@@ -1,7 +1,20 @@
-"""
+"""@darkarts
+⊢doc-generator:plugins.translation
+∂{typing,pathlib,re,darkarts.annotations.types}
+⚠{python≥3.7,annotations:parsed,output-dir:writable}
+⊨{∀generate→markdown-docs,∀translate→natural-language,∀symbol→readable,¬modify-annotations,idempotent:same-input→same-output}
+🔒{read-only:annotations,write:docs-dir,¬network,¬exec}
+⚡{O(n)|n=annotations,translation:linear}
+
 VooDocs Documentation Generator
 
-Translates @voodocs annotations (using the DarkArts language) into human-readable documentation.
+Translates @voodocs annotations (DarkArts language) into human-readable documentation with:
+- Mathematical symbol translation (∀, ∃, ∈, → natural language)
+- Markdown generation (structured documentation)
+- Multi-section output (module, classes, functions)
+- Complexity notation explanation (Big-O → plain English)
+- Security model documentation (clear security implications)
+- Cross-reference generation (links between related items)
 """
 
 from typing import List, Optional, Dict

package/lib/darkarts/plugins/voodocs/html_exporter.py

@@ -1,7 +1,20 @@
-"""
+"""@darkarts
+⊢html-exporter:plugins.export
+∂{pathlib,typing}
+⚠{python≥3.7,markdown:optional,input-file:exists}
+⊨{∀export→html-file,∀markdown→html,¬modify-source,fallback:basic-conversion,styled:css-included}
+🔒{read:markdown-files,write:html-files,¬network,¬exec}
+⚡{O(n)|n=markdown-length,conversion:linear}
+
 VooDocs HTML Exporter
 
-Exports documentation to HTML format with styling.
+Markdown to HTML conversion with styling:
+- Markdown parsing (markdown library or fallback)
+- Syntax highlighting (code blocks with CodeHilite)
+- Table support (GitHub-flavored Markdown tables)
+- Responsive CSS (mobile-friendly styling)
+- Full HTML document wrapping (complete pages)
+- Graceful degradation (basic conversion if markdown lib unavailable)
 """
 
 from pathlib import Path

package/lib/darkarts/plugins/voodocs/instruction_generator.py

@@ -4,7 +4,7 @@
 ⚠{ai∈{cursor,claude,copilot,windsurf},format:markdown,@voodocs:taught}
 ⊨{∀gen→valid-format,∀gen→assistant-specific,∀gen→include-examples}
 🔒{write:config-files}
-⚡{O(1)|template-based}
+⚡{O(n):instruction-generation|template-based}
 
 VooDocs AI Instruction Generator
 

package/lib/darkarts/plugins/voodocs/pdf_exporter.py

@@ -1,7 +1,20 @@
-"""
+"""@darkarts
+⊢pdf-exporter:plugins.export
+∂{pathlib,typing,subprocess,weasyprint,darkarts.plugins.voodocs.html_exporter}
+⚠{python≥3.7,weasyprint|markdown-pdf:installed,input-file:exists}
+⊨{∀export→pdf-file,∀markdown→pdf,¬modify-source,fallback-chain:weasyprint→markdown-pdf,print-ready:formatted}
+🔒{read:markdown-files,write:pdf-files,¬network,¬exec}
+⚡{O(n)|n=markdown-length,pdf-rendering:depends-on-lib}
+
 VooDocs PDF Exporter
 
-Exports documentation to PDF format.
+Markdown to PDF conversion with print-ready formatting:
+- WeasyPrint support (HTML → PDF with CSS)
+- Markdown-PDF fallback (alternative PDF generation)
+- Print-optimized layout (page breaks, margins)
+- Embedded fonts and styling (professional appearance)
+- Multi-method fallback (tries multiple libraries)
+- Error handling (clear messages if dependencies missing)
 """
 
 from pathlib import Path

package/lib/darkarts/plugins/voodocs/test_generator.py

@@ -1,7 +1,20 @@
-"""
+"""@darkarts
+⊢test-generator:plugins.test-automation
+∂{typing,pathlib,re,darkarts.annotations.types}
+⚠{python≥3.7,annotations:parsed,framework:supported}
+⊨{∀generate→test-code,∀precondition→test-case,∀postcondition→assertion,¬modify-annotations,executable:valid-syntax}
+🔒{read-only:annotations,write:test-files,¬network,¬exec}
+⚡{O(n)|n=functions,codegen:linear}
+
 VooDocs Test Generator
 
-Generates automated test cases from @voodocs annotations, including property-based tests.
+Automatic test generation from @voodocs annotations with:
+- Precondition tests (validate inputs match declared constraints)
+- Postcondition tests (verify outputs satisfy guarantees)
+- Invariant tests (check state consistency)
+- Error case tests (ensure proper error handling)
+- Property-based tests (Hypothesis/QuickCheck-style)
+- Multi-framework support (pytest, unittest, jest, junit)
 """
 
 from typing import List, Optional, Dict, Any, Tuple

package/lib/darkarts/telemetry.py

@@ -1,7 +1,20 @@
-"""
+"""@darkarts
+⊢telemetry:analytics.privacy-first
+∂{os,sys,json,uuid,platform,datetime,pathlib,typing,urllib}
+⚠{python≥3.7,network:optional,config-dir:writable}
+⊨{∀track→async-send,∀event:anonymous,∀user:opt-out-respected,¬pii,fail-silent:network-errors}
+🔒{⚠️NETWORK:supabase-api,write:config-dir,¬sensitive-data,anonymous-only}
+⚡{O(1):event-creation,network:async-non-blocking}
+
 VooDocs Telemetry Client
 
-Privacy-respecting anonymous telemetry for usage analytics.
+Privacy-respecting anonymous usage analytics with:
+- Anonymous session IDs (UUID-based, no PII)
+- Opt-out support (VOODOCS_TELEMETRY_DISABLED env var)
+- Event tracking (command usage, errors, performance)
+- Supabase backend (anonymous data storage)
+- Fail-silent network (no impact on user experience if offline)
+- First-run notice (transparent disclosure to users)
 """
 
 import os

package/lib/darkarts/validation/README.md

@@ -0,0 +1,147 @@
+# DarkArts Validation Module
+
+**Phase 1: Foundation - Complete** ✅
+
+This module provides validation tools for @darkarts annotations.
+
+## Overview
+
+The validation module ensures that @darkarts annotations are accurate and up-to-date by:
+- **Semantic Validation**: Verifying dependencies match actual imports
+- **Performance Validation**: Checking complexity claims match code structure  
+- **Benchmarking**: Measuring actual performance to validate claims
+- **Auto-fix**: Automatically correcting validation issues
+
+## Installation
+
+The validation module is part of the VooDocs package:
+
+```bash
+pip install voodocs
+```
+
+## Usage
+
+### Semantic Validation
+
+```python
+from darkarts.validation import SemanticValidator
+
+validator = SemanticValidator()
+
+# Validate a single file
+result = validator.validate_file("myfile.py")
+if not result.is_valid:
+    print(f"Missing dependencies: {result.missing_deps}")
+    print(f"Extra dependencies: {result.extra_deps}")
+
+# Validate a directory
+results = validator.validate_directory("lib/", recursive=True)
+valid_count = sum(1 for r in results if r.is_valid)
+print(f"Valid: {valid_count}/{len(results)}")
+```
+
+### Performance Validation
+
+```python
+from darkarts.validation import PerformanceTracker
+
+tracker = PerformanceTracker()
+
+# Analyze a file
+result = tracker.analyze_file("myfile.py")
+print(f"Claimed: {result.claimed_complexity}")
+print(f"Actual: {result.actual_complexity}")
+print(f"Valid: {result.is_valid}")
+```
+
+### Benchmarking
+
+```python
+from darkarts.validation import BenchmarkSuite
+
+suite = BenchmarkSuite()
+
+# Run benchmarks
+config = {
+    "critical_paths": ["mymodule.core.process"],
+    "sizes": [10, 100, 1000],
+}
+results = suite.run_benchmarks(config)
+```
+
+## API Reference
+
+### SemanticValidator
+
+- `validate_file(file_path)` - Validate a single file
+- `validate_directory(directory, recursive=True)` - Validate all files in directory
+- `validate_path(path, recursive=False)` - Validate file or directory
+
+### PerformanceTracker
+
+- `analyze_file(file_path)` - Analyze a single file
+- `analyze_directory(directory, recursive=True)` - Analyze all files in directory
+
+### BenchmarkSuite
+
+- `run_benchmarks(config)` - Run benchmarks based on configuration
+
+## Module Structure
+
+```
+validation/
+├── __init__.py              # Public API
+├── semantic.py              # Semantic validation (functional)
+├── semantic_wrapper.py      # SemanticValidator class
+├── performance.py           # Performance tracking (functional)
+├── performance_wrapper.py   # PerformanceTracker class
+├── benchmark.py             # Benchmarking (functional)
+├── benchmark_wrapper.py     # BenchmarkSuite class
+├── autofix.py               # Auto-fix functionality
+├── config.py                # Configuration management
+├── watch.py                 # Watch mode
+├── types.py                 # Shared type definitions
+├── test_validation.py       # Unit tests
+└── README.md                # This file
+```
+
+## Design Principles
+
+1. **Functional Core**: Core validation logic is functional (pure functions)
+2. **OOP Wrapper**: Object-oriented API for ease of use
+3. **No CLI**: CLI removed - use `voodocs` CLI instead
+4. **Lazy Loading**: Modules loaded on-demand for fast startup
+5. **Type Safety**: Full type hints for better IDE support
+
+## Next Steps
+
+**Phase 2**: CLI Integration (Week 2)
+- Integrate into `voodocs` CLI
+- Add `voodocs validate` command
+- Add `--validate` flag to `voodocs generate`
+
+**Phase 3**: Advanced Features (Week 3)
+- Watch mode integration
+- Configuration file support
+- HTML/JSON reports
+
+## Testing
+
+Run tests:
+
+```bash
+# Unit tests
+python3 -m pytest lib/darkarts/validation/test_validation.py
+
+# With coverage
+python3 -m pytest lib/darkarts/validation/test_validation.py --cov=darkarts.validation
+```
+
+## Contributing
+
+See `../../docs/darkarts/CODE_REVIEW_PROCESS.md` for contribution guidelines.
+
+## License
+
+Part of VooDocs - see repository root for license.

package/lib/darkarts/validation/__init__.py

@@ -0,0 +1,91 @@
+"""@darkarts
+⊢ validation:api
+∂{typing}
+⚠{
+  - Python ≥3.7
+  - Validation modules available
+}
+⊨{
+  - Public API is stable
+  - All validators are importable
+  - Version compatibility maintained
+}
+🔒{
+  - Read-only validation operations
+  - No side effects except file writes in fix mode
+  - Safe for concurrent use
+}
+⚡{O(n):import-time|n=lazy-loaded-modules}
+"""
+
+"""
+DarkArts Validation Module
+
+This module provides validation tools for @darkarts annotations:
+- SemanticValidator: Validates dependencies match imports
+- PerformanceTracker: Validates complexity claims
+- BenchmarkSuite: Benchmarks performance with real data
+- AutoFix: Automatically fixes validation issues
+- Config: Configuration management
+
+Public API:
+    from darkarts.validation import (
+        SemanticValidator,
+        PerformanceTracker,
+        BenchmarkSuite,
+        AutoFix,
+        Config,
+    )
+"""
+
+from typing import TYPE_CHECKING
+
+__version__ = "1.0.0"
+__all__ = [
+    "SemanticValidator",
+    "PerformanceTracker",
+    "BenchmarkSuite",
+    "AutoFix",
+    "Config",
+    "ValidationResult",
+    "PerformanceResult",
+    "BenchmarkResult",
+]
+
+# Lazy imports to avoid circular dependencies and improve startup time
+if TYPE_CHECKING:
+    from .semantic import SemanticValidator
+    from .performance import PerformanceTracker
+    from .benchmark import BenchmarkSuite
+    from .autofix import AutoFix
+    from .config import Config
+    from .types import ValidationResult, PerformanceResult, BenchmarkResult
+
+
+def __getattr__(name: str):
+    """Lazy import for better startup performance."""
+    if name == "SemanticValidator":
+        from .semantic_wrapper import SemanticValidator
+        return SemanticValidator
+    elif name == "PerformanceTracker":
+        from .performance_wrapper import PerformanceTracker
+        return PerformanceTracker
+    elif name == "BenchmarkSuite":
+        from .benchmark_wrapper import BenchmarkSuite
+        return BenchmarkSuite
+    elif name == "AutoFix":
+        from .autofix import AutoFix
+        return AutoFix
+    elif name == "Config":
+        from .config import Config
+        return Config
+    elif name == "ValidationResult":
+        from .types import ValidationResult
+        return ValidationResult
+    elif name == "PerformanceResult":
+        from .types import PerformanceResult
+        return PerformanceResult
+    elif name == "BenchmarkResult":
+        from .types import BenchmarkResult
+        return BenchmarkResult
+    raise AttributeError(f"module {__name__!r} has no attribute {name!r}")

package/lib/darkarts/validation/autofix.py

@@ -0,0 +1,297 @@
+"""@darkarts
+⊢autofix:validation.automatic-repair
+∂{re,pathlib,typing,semantic_validator}
+⚠{python≥3.7,file:writable,backup:recommended}
+⊨{∀fix→annotation-updated,∀backup→created,¬data-loss,idempotent:safe-to-rerun}
+🔒{read-write:files,write:backups,¬network,¬exec}
+⚡{O(n)|n=file-size,file-io:linear}
+
+Auto-fix Mode for @darkarts Annotations
+
+Automatically updates ∂{} sections to match actual imports with:
+- Safe updates (creates backups before modifying)
+- Dry-run mode (preview changes without applying)
+- Selective fixing (fix only specific issues)
+- Rollback support (restore from backups)
+- Batch operations (fix entire directories)
+- Validation after fix (ensure correctness)
+"""
+
+import re
+from pathlib import Path
+from typing import Optional, List, Set, Tuple
+from dataclasses import dataclass
+from datetime import datetime
+
+from . import semantic
+from .types import ValidationResult
+
+
+@dataclass
+class FixResult:
+    """Result of an auto-fix operation."""
+    file_path: str
+    success: bool
+    original_deps: Set[str]
+    fixed_deps: Set[str]
+    backup_path: Optional[str]
+    error: Optional[str] = None
+    
+    def __str__(self) -> str:
+        if not self.success:
+            return f"❌ {self.file_path}: {self.error}"
+        
+        added = self.fixed_deps - self.original_deps
+        removed = self.original_deps - self.fixed_deps
+        
+        lines = [f"✅ {self.file_path}: Fixed"]
+        if added:
+            lines.append(f"  Added: {', '.join(sorted(added))}")
+        if removed:
+            lines.append(f"  Removed: {', '.join(sorted(removed))}")
+        if self.backup_path:
+            lines.append(f"  Backup: {self.backup_path}")
+        
+        return "\n".join(lines)
+
+
+class AutoFixer:
+    """Automatically fixes @darkarts annotation dependencies."""
+    
+    def __init__(self, backup_dir: Optional[Path] = None, dry_run: bool = False):
+        """
+        Initialize the auto-fixer.
+        
+        Args:
+            backup_dir: Directory to store backups (default: .backups/)
+            dry_run: If True, preview changes without applying them
+        """
+        self.backup_dir = backup_dir or Path(".backups")
+        self.dry_run = dry_run
+        
+        if not dry_run:
+            self.backup_dir.mkdir(parents=True, exist_ok=True)
+    
+    def create_backup(self, file_path: Path) -> Path:
+        """
+        Create a backup of the file before modifying.
+        
+        Args:
+            file_path: Path to the file to backup
+        
+        Returns:
+            Path to the backup file
+        """
+        timestamp = datetime.now().strftime("%Y%m%d_%H%M%S")
+        backup_name = f"{file_path.name}.{timestamp}.bak"
+        backup_path = self.backup_dir / backup_name
+        
+        content = file_path.read_text(encoding='utf-8')
+        backup_path.write_text(content, encoding='utf-8')
+        
+        return backup_path
+    
+    def extract_annotation_section(self, content: str) -> Tuple[str, int, int]:
+        """
+        Extract the @darkarts annotation section from file content.
+        
+        Args:
+            content: File content
+        
+        Returns:
+            Tuple of (annotation_text, start_index, end_index)
+        
+        Raises:
+            ValueError: If no annotation found
+        """
+        if not content.startswith('"""@darkarts'):
+            raise ValueError("No @darkarts annotation found")
+        
+        # Find the end of the docstring
+        end_idx = content.find('"""', 3)
+        if end_idx == -1:
+            raise ValueError("Malformed annotation: no closing quotes")
+        
+        annotation = content[3:end_idx]  # Skip opening """
+        return annotation, 3, end_idx
+    
+    def update_dependencies_section(self, annotation: str, new_deps: Set[str]) -> str:
+        """
+        Update the ∂{} section in an annotation.
+        
+        Args:
+            annotation: The annotation text
+            new_deps: New set of dependencies
+        
+        Returns:
+            Updated annotation text
+        """
+        # Format dependencies (sorted for consistency)
+        deps_str = ','.join(sorted(new_deps)) if new_deps else ''
+        new_deps_section = f"∂{{{deps_str}}}"
+        
+        # Replace existing ∂{} section
+        pattern = r'∂\{[^}]*\}'
+        
+        if re.search(pattern, annotation):
+            # Replace existing section
+            updated = re.sub(pattern, new_deps_section, annotation)
+        else:
+            # Add new section after ⊢ line
+            lines = annotation.split('\n')
+            for i, line in enumerate(lines):
+                if line.startswith('⊢'):
+                    lines.insert(i + 1, new_deps_section)
+                    break
+            updated = '\n'.join(lines)
+        
+        return updated
+    
+    def fix_file(self, file_path: Path) -> FixResult:
+        """
+        Fix the dependencies in a single file.
+        
+        Args:
+            file_path: Path to the file to fix
+        
+        Returns:
+            FixResult with details of the fix
+        """
+        try:
+            # Validate first to see what needs fixing
+            validation = semantic.validate_file(file_path)
+            
+            if validation.is_valid:
+                return FixResult(
+                    file_path=str(file_path),
+                    success=True,
+                    original_deps=set(),
+                    fixed_deps=set(),
+                    backup_path=None,
+                    error="Already valid (no fix needed)"
+                )
+            
+            # Read file content
+            content = file_path.read_text(encoding='utf-8')
+            
+            # Extract annotation
+            annotation, start_idx, end_idx = self.extract_annotation_section(content)
+            
+            # Get current and correct dependencies
+            original_deps = semantic.parse_dependencies(annotation)
+            correct_deps = semantic.extract_imports(file_path)
+            
+            # Update annotation
+            updated_annotation = self.update_dependencies_section(annotation, correct_deps)
+            
+            # Reconstruct file content
+            updated_content = (
+                content[:start_idx] +
+                updated_annotation +
+                content[end_idx:]
+            )
+            
+            # Create backup and write (unless dry-run)
+            backup_path = None
+            if not self.dry_run:
+                backup_path = self.create_backup(file_path)
+                file_path.write_text(updated_content, encoding='utf-8')
+            
+            return FixResult(
+                file_path=str(file_path),
+                success=True,
+                original_deps=original_deps,
+                fixed_deps=correct_deps,
+                backup_path=str(backup_path) if backup_path else None
+            )
+        
+        except Exception as e:
+            return FixResult(
+                file_path=str(file_path),
+                success=False,
+                original_deps=set(),
+                fixed_deps=set(),
+                backup_path=None,
+                error=str(e)
+            )
+    
+    def fix_directory(self, directory: Path, recursive: bool = True) -> List[FixResult]:
+        """
+        Fix all Python files in a directory.
+        
+        Args:
+            directory: Path to the directory
+            recursive: Whether to search recursively
+        
+        Returns:
+            List of FixResult 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 = self.fix_file(py_file)
+            results.append(result)
+        
+        return results
+    
+    def rollback(self, backup_path: Path, original_path: Path) -> bool:
+        """
+        Restore a file from backup.
+        
+        Args:
+            backup_path: Path to the backup file
+            original_path: Path to restore to
+        
+        Returns:
+            True if successful, False otherwise
+        """
+        try:
+            content = backup_path.read_text(encoding='utf-8')
+            original_path.write_text(content, encoding='utf-8')
+            return True
+        except Exception as e:
+            print(f"Rollback failed: {e}")
+            return False
+
+
+def preview_fix(file_path: Path) -> str:
+    """
+    Preview what would be changed without actually modifying the file.
+    
+    Args:
+        file_path: Path to the file
+    
+    Returns:
+        Human-readable preview of changes
+    """
+    fixer = AutoFixer(dry_run=True)
+    result = fixer.fix_file(file_path)
+    
+    if not result.success:
+        return f"❌ Cannot fix: {result.error}"
+    
+    if not result.original_deps and not result.fixed_deps:
+        return "✅ No changes needed (already valid)"
+    
+    lines = [f"Preview for {file_path}:"]
+    lines.append(f"  Current: ∂{{{','.join(sorted(result.original_deps))}}}")
+    lines.append(f"  Fixed:   ∂{{{','.join(sorted(result.fixed_deps))}}}")
+    
+    added = result.fixed_deps - result.original_deps
+    removed = result.original_deps - result.fixed_deps
+    
+    if added:
+        lines.append(f"  + Add: {', '.join(sorted(added))}")
+    if removed:
+        lines.append(f"  - Remove: {', '.join(sorted(removed))}")
+    
+    return "\n".join(lines)
+
+
+
+# CLI interface removed - use darkarts.validation API or voodocs CLI instead