@voodocs/cli 0.4.2 → 1.0.0

package/lib/cli/fix.py

@@ -0,0 +1,244 @@
+"""@darkarts
+⊢cli:fix
+∂{click,pathlib,typing,sys}
+⚠{python≥3.7,click≥8.0}
+⊨{∀fix→executed,∀backup→created}
+🔒{write:files,read:files}
+⚡{O(n*m)|n=files,m=file-size}
+"""
+
+"""
+VooDocs CLI - Fix Command
+
+Automatically fixes validation issues in @darkarts annotations.
+"""
+
+import sys
+import click
+from pathlib import Path
+from typing import List, Dict, Any
+
+import sys
+from pathlib import Path as PathLib
+sys.path.insert(0, str(PathLib(__file__).parent.parent))
+from darkarts.validation.autofix import AutoFixer
+
+
+@click.command()
+@click.argument('path', type=click.Path(exists=True))
+@click.option('-r', '--recursive', is_flag=True, help='Recursively fix all files')
+@click.option('--dry-run', is_flag=True, help='Preview changes without applying')
+@click.option('--no-backup', is_flag=True, help='Skip creating backup files')
+@click.option('--deps-only', is_flag=True, help='Only fix dependency issues')
+@click.option('--perf-only', is_flag=True, help='Only fix performance issues')
+@click.option('--exclude', multiple=True, help='Exclude patterns (can be used multiple times)')
+@click.option('--format', type=click.Choice(['text', 'json']), default='text', help='Output format')
+@click.option('--strict', is_flag=True, help='Exit with error code if fixes needed')
+def fix(
+    path: str,
+    recursive: bool,
+    dry_run: bool,
+    no_backup: bool,
+    deps_only: bool,
+    perf_only: bool,
+    exclude: tuple,
+    format: str,
+    strict: bool
+):
+    """
+    Automatically fix validation issues in @darkarts annotations.
+    
+    Fixes include:
+    - Update ∂{} to match actual imports
+    - Update ⚡{} to match detected complexity
+    - Add missing annotation sections
+    
+    Examples:
+    
+        # Preview fixes for a file
+        voodocs fix myfile.py --dry-run
+        
+        # Apply fixes to a file
+        voodocs fix myfile.py
+        
+        # Fix all files in directory (with backup)
+        voodocs fix lib/ -r
+        
+        # Fix without backup
+        voodocs fix lib/ -r --no-backup
+        
+        # Only fix dependencies
+        voodocs fix lib/ -r --deps-only
+        
+        # Only fix performance claims
+        voodocs fix lib/ -r --perf-only
+        
+        # JSON output
+        voodocs fix lib/ -r --format json
+    """
+    
+    if format == 'text':
+        click.echo(f"Fixing: {path}")
+        if dry_run:
+            click.secho("(Dry run - no changes will be made)", fg='yellow')
+        click.echo()
+    
+    # Collect files to fix
+    path_obj = Path(path)
+    files_to_fix: List[Path] = []
+    
+    if path_obj.is_file():
+        files_to_fix = [path_obj]
+    elif path_obj.is_dir():
+        pattern = "**/*.py" if recursive else "*.py"
+        files_to_fix = [
+            f for f in path_obj.glob(pattern)
+            if f.is_file() and not _should_exclude(f, exclude)
+        ]
+    
+    if not files_to_fix:
+        if format == 'text':
+            click.secho("No Python files found to fix.", fg='yellow')
+        else:
+            click.echo('{"files": [], "fixed": 0, "errors": 0}')
+        sys.exit(0)
+    
+    # Initialize auto-fix
+    autofix = AutoFixer(dry_run=dry_run)
+    
+    # Track results
+    results = {
+        'files': [],
+        'fixed': 0,
+        'errors': 0,
+        'skipped': 0
+    }
+    
+    # Process each file
+    for file_path in files_to_fix:
+        try:
+            # Create backup if needed
+            if not dry_run and not no_backup:
+                try:
+                    autofix.create_backup(file_path)
+                except Exception as e:
+                    if format == 'text':
+                        click.secho(f"⚠️  Warning: Could not create backup for {file_path}: {e}", fg='yellow')
+            
+            # Run auto-fix
+            fix_result = autofix.fix_file(file_path)
+            
+            # Track result
+            changes = []
+            if fix_result.success:
+                if fix_result.original_deps != fix_result.fixed_deps:
+                    changes.append(f"Updated ∂{{}} from {fix_result.original_deps} to {fix_result.fixed_deps}")
+            
+            file_result = {
+                'file': str(file_path),
+                'fixed': fix_result.success and len(changes) > 0,
+                'changes': changes,
+                'error': fix_result.error if not fix_result.success else None
+            }
+            results['files'].append(file_result)
+            
+            if file_result['fixed']:
+                results['fixed'] += 1
+            elif file_result['error']:
+                results['errors'] += 1
+            else:
+                results['skipped'] += 1
+            
+            # Display result (text mode)
+            if format == 'text':
+                _display_file_result(file_path, file_result, dry_run)
+        
+        except Exception as e:
+            results['errors'] += 1
+            results['files'].append({
+                'file': str(file_path),
+                'fixed': False,
+                'error': str(e)
+            })
+            
+            if format == 'text':
+                click.secho(f"❌ {file_path}", fg='red')
+                click.secho(f"   Error: {e}", fg='red')
+    
+    # Display summary
+    if format == 'text':
+        _display_summary(results, dry_run, strict)
+    else:
+        import json
+        click.echo(json.dumps(results, indent=2))
+    
+    # Exit code
+    if strict and results['fixed'] > 0:
+        sys.exit(1)
+    elif results['errors'] > 0:
+        sys.exit(1)
+    else:
+        sys.exit(0)
+
+
+def _should_exclude(file_path: Path, exclude_patterns: tuple) -> bool:
+    """Check if file should be excluded based on patterns."""
+    file_str = str(file_path)
+    for pattern in exclude_patterns:
+        if pattern in file_str:
+            return True
+    return False
+
+
+def _display_file_result(file_path: Path, result: Dict[str, Any], dry_run: bool):
+    """Display result for a single file."""
+    if result.get('error'):
+        click.secho(f"❌ {file_path}", fg='red')
+        click.secho(f"   Error: {result['error']}", fg='red')
+    elif result.get('fixed'):
+        action = "Would fix" if dry_run else "Fixed"
+        click.secho(f"✅ {file_path}", fg='green')
+        changes = result.get('changes', [])
+        for change in changes:
+            click.echo(f"   • {change}")
+    else:
+        click.secho(f"⚪ {file_path}", fg='white')
+        click.echo(f"   No fixes needed")
+
+
+def _display_summary(results: Dict[str, Any], dry_run: bool, strict: bool):
+    """Display summary of fix results."""
+    total = len(results['files'])
+    fixed = results['fixed']
+    errors = results['errors']
+    skipped = results['skipped']
+    
+    click.echo()
+    click.echo("━" * 60)
+    click.echo(f"Total files: {total}")
+    
+    if dry_run:
+        click.secho(f"Would fix: {fixed}", fg='yellow')
+    else:
+        click.secho(f"Fixed: {fixed}", fg='green' if fixed > 0 else 'white')
+    
+    click.echo(f"No changes needed: {skipped}")
+    
+    if errors > 0:
+        click.secho(f"Errors: {errors}", fg='red')
+    
+    click.echo("━" * 60)
+    
+    if dry_run and fixed > 0:
+        click.echo()
+        click.secho("💡 Run without --dry-run to apply fixes", fg='cyan')
+    elif not dry_run and fixed > 0:
+        click.echo()
+        click.secho("✅ All fixes applied!", fg='green')
+    elif fixed == 0 and errors == 0:
+        click.echo()
+        click.secho("✅ All files are already valid!", fg='green')
+    
+    if strict and fixed > 0:
+        click.echo()
+        click.secho("⚠️  Strict mode: Exiting with error code (fixes were needed)", fg='yellow')

package/lib/cli/generate.py

@@ -0,0 +1,310 @@
+"""@darkarts
+⊢cli:generate
+∂{click,pathlib,typing,sys}
+⚠{python≥3.7,click≥8.0}
+⊨{∀generation→executed,∀validation→passed-if-enabled}
+🔒{read:files,write:documentation}
+⚡{O(n*m)|n=files,m=file-size}
+"""
+
+"""
+VooDocs CLI - Generate Command
+
+Generates documentation from @darkarts annotations.
+"""
+
+import sys
+import click
+from pathlib import Path
+from typing import List
+
+import sys
+from pathlib import Path as PathLib
+sys.path.insert(0, str(PathLib(__file__).parent.parent))
+from darkarts.validation.semantic_wrapper import SemanticValidator
+from darkarts.validation.performance_wrapper import PerformanceTracker
+
+
+@click.command()
+@click.argument('source', type=click.Path(exists=True))
+@click.argument('output', type=click.Path())
+@click.option('-r', '--recursive', is_flag=True, help='Recursively process all files')
+@click.option('--validate', is_flag=True, help='Validate annotations before generating')
+@click.option('--strict', is_flag=True, help='Fail if validation fails')
+@click.option('--format', type=click.Choice(['markdown', 'html', 'json']), default='markdown', help='Output format')
+@click.option('--include-private', is_flag=True, help='Include private members in documentation')
+def generate(
+    source: str,
+    output: str,
+    recursive: bool,
+    validate: bool,
+    strict: bool,
+    format: str,
+    include_private: bool
+):
+    """
+    Generate documentation from @darkarts annotations.
+    
+    Reads @darkarts annotations from Python files and generates
+    comprehensive documentation in various formats.
+    
+    Examples:
+    
+        # Generate markdown docs
+        voodocs generate lib/ docs/
+        
+        # Generate with validation
+        voodocs generate lib/ docs/ --validate
+        
+        # Strict mode (fail if validation fails)
+        voodocs generate lib/ docs/ --validate --strict
+        
+        # HTML format
+        voodocs generate lib/ docs/ --format html
+        
+        # Recursive processing
+        voodocs generate lib/ docs/ -r
+    """
+    
+    click.echo(f"Generating documentation from: {source}")
+    click.echo(f"Output directory: {output}")
+    click.echo(f"Format: {format}")
+    click.echo()
+    
+    # Collect source files
+    source_path = Path(source)
+    files_to_process: List[Path] = []
+    
+    if source_path.is_file():
+        files_to_process = [source_path]
+    elif source_path.is_dir():
+        pattern = "**/*.py" if recursive else "*.py"
+        files_to_process = [f for f in source_path.glob(pattern) if f.is_file()]
+    
+    if not files_to_process:
+        click.secho("No Python files found to process.", fg='yellow')
+        sys.exit(1)
+    
+    click.echo(f"Found {len(files_to_process)} files to process")
+    
+    # Validate if requested
+    if validate:
+        click.echo()
+        click.secho("Validating annotations...", fg='cyan')
+        
+        validator = SemanticValidator()
+        tracker = PerformanceTracker()
+        
+        validation_failed = False
+        for file_path in files_to_process:
+            try:
+                # Semantic validation
+                sem_result = validator.validate_file(file_path)
+                
+                # Performance validation
+                perf_result = tracker.analyze_file(file_path)
+                
+                if not (sem_result and perf_result):
+                    validation_failed = True
+                    click.secho(f"❌ {file_path}", fg='red')
+            except Exception as e:
+                validation_failed = True
+                click.secho(f"❌ {file_path}: {e}", fg='red')
+        
+        if validation_failed:
+            click.echo()
+            click.secho("⚠️  Validation failed!", fg='red')
+            if strict:
+                click.echo("Strict mode enabled - aborting documentation generation")
+                sys.exit(1)
+            else:
+                click.echo("Continuing with documentation generation (use --strict to abort on validation failure)")
+        else:
+            click.echo()
+            click.secho("✅ All annotations validated successfully!", fg='green')
+    
+    # Create output directory
+    output_path = Path(output)
+    output_path.mkdir(parents=True, exist_ok=True)
+    
+    # Generate documentation
+    click.echo()
+    click.secho("Generating documentation...", fg='cyan')
+    
+    generated_files = []
+    for file_path in files_to_process:
+        try:
+            # Generate documentation for this file
+            doc_content = _generate_doc_for_file(file_path, format, include_private)
+            
+            # Determine output filename
+            if source_path.is_dir():
+                relative_path = file_path.relative_to(source_path)
+                output_filename = relative_path.with_suffix(f".{_get_extension(format)}")
+            else:
+                output_filename = Path(file_path.stem + f".{_get_extension(format)}")
+            output_file = output_path / output_filename
+            
+            # Create parent directories if needed
+            output_file.parent.mkdir(parents=True, exist_ok=True)
+            
+            # Write documentation
+            output_file.write_text(doc_content, encoding='utf-8')
+            generated_files.append(output_file)
+            
+            click.echo(f"✅ {file_path} → {output_file}")
+        
+        except Exception as e:
+            click.secho(f"❌ {file_path}: {e}", fg='red')
+    
+    # Summary
+    click.echo()
+    click.echo("━" * 60)
+    click.echo(f"Total files processed: {len(files_to_process)}")
+    click.secho(f"Documentation generated: {len(generated_files)}", fg='green')
+    click.echo(f"Output directory: {output_path}")
+    click.echo("━" * 60)
+    
+    if len(generated_files) == len(files_to_process):
+        click.echo()
+        click.secho("✅ Documentation generation complete!", fg='green')
+        sys.exit(0)
+    else:
+        click.echo()
+        click.secho("⚠️  Some files failed to generate documentation", fg='yellow')
+        sys.exit(1)
+
+
+def _generate_doc_for_file(file_path: Path, format: str, include_private: bool) -> str:
+    """Generate documentation for a single file."""
+    content = file_path.read_text(encoding='utf-8')
+    
+    # Extract @darkarts annotation
+    annotation = _extract_annotation(content)
+    
+    if not annotation:
+        return f"# {file_path.name}\n\nNo @darkarts annotation found.\n"
+    
+    # Parse annotation sections
+    module_id = _extract_section(annotation, '⊢')
+    dependencies = _extract_section(annotation, '∂')
+    assumptions = _extract_section(annotation, '⚠')
+    invariants = _extract_section(annotation, '⊨')
+    security = _extract_section(annotation, '🔒')
+    performance = _extract_section(annotation, '⚡')
+    
+    # Generate documentation based on format
+    if format == 'markdown':
+        return _generate_markdown(file_path, module_id, dependencies, assumptions, invariants, security, performance)
+    elif format == 'html':
+        return _generate_html(file_path, module_id, dependencies, assumptions, invariants, security, performance)
+    elif format == 'json':
+        import json
+        return json.dumps({
+            'file': str(file_path),
+            'module': module_id,
+            'dependencies': dependencies,
+            'assumptions': assumptions,
+            'invariants': invariants,
+            'security': security,
+            'performance': performance
+        }, indent=2)
+    else:
+        return ""
+
+
+def _extract_annotation(content: str) -> str:
+    """Extract @darkarts annotation from file content."""
+    if '"""@darkarts' in content:
+        start = content.index('"""@darkarts')
+        end = content.index('"""', start + 3) + 3
+        return content[start:end]
+    return ""
+
+
+def _extract_section(annotation: str, symbol: str) -> str:
+    """Extract a specific section from annotation."""
+    lines = annotation.split('\n')
+    for line in lines:
+        if line.strip().startswith(symbol):
+            return line.strip()[len(symbol):].strip('{}')
+    return ""
+
+
+def _generate_markdown(file_path, module_id, dependencies, assumptions, invariants, security, performance) -> str:
+    """Generate Markdown documentation."""
+    md = f"# {file_path.name}\n\n"
+    
+    if module_id:
+        md += f"**Module:** `{module_id}`\n\n"
+    
+    if dependencies:
+        md += f"## Dependencies\n\n`{dependencies}`\n\n"
+    
+    if assumptions:
+        md += f"## Assumptions\n\n{assumptions}\n\n"
+    
+    if invariants:
+        md += f"## Invariants\n\n{invariants}\n\n"
+    
+    if security:
+        md += f"## Security\n\n{security}\n\n"
+    
+    if performance:
+        md += f"## Performance\n\n**Complexity:** `{performance}`\n\n"
+    
+    return md
+
+
+def _generate_html(file_path, module_id, dependencies, assumptions, invariants, security, performance) -> str:
+    """Generate HTML documentation."""
+    html = f"""<!DOCTYPE html>
+<html>
+<head>
+    <title>{file_path.name}</title>
+    <style>
+        body {{ font-family: Arial, sans-serif; margin: 40px; }}
+        h1 {{ color: #333; }}
+        h2 {{ color: #666; margin-top: 30px; }}
+        code {{ background: #f4f4f4; padding: 2px 6px; border-radius: 3px; }}
+        .section {{ margin: 20px 0; }}
+    </style>
+</head>
+<body>
+    <h1>{file_path.name}</h1>
+"""
+    
+    if module_id:
+        html += f"<div class='section'><strong>Module:</strong> <code>{module_id}</code></div>"
+    
+    if dependencies:
+        html += f"<h2>Dependencies</h2><div class='section'><code>{dependencies}</code></div>"
+    
+    if assumptions:
+        html += f"<h2>Assumptions</h2><div class='section'>{assumptions}</div>"
+    
+    if invariants:
+        html += f"<h2>Invariants</h2><div class='section'>{invariants}</div>"
+    
+    if security:
+        html += f"<h2>Security</h2><div class='section'>{security}</div>"
+    
+    if performance:
+        html += f"<h2>Performance</h2><div class='section'><strong>Complexity:</strong> <code>{performance}</code></div>"
+    
+    html += """
+</body>
+</html>
+"""
+    
+    return html
+
+
+def _get_extension(format: str) -> str:
+    """Get file extension for format."""
+    extensions = {
+        'markdown': 'md',
+        'html': 'html',
+        'json': 'json'
+    }
+    return extensions.get(format, 'txt')