@voodocs/cli 0.4.2 → 1.0.1

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')

package/lib/cli/test_cli.py

@@ -0,0 +1,215 @@
+"""
+@darkarts
+⊢ test:cli.commands
+∂{pytest, click.testing, pathlib, tempfile, json}
+⚠{pytest≥7.0, click≥8.0}
+⊨{all_tests_pass, no_side_effects}
+🔒{read-only:test-files, isolated:test-environment}
+⚡{O(n):test-count}
+"""
+
+import pytest
+import json
+import tempfile
+from pathlib import Path
+from click.testing import CliRunner
+from lib.cli import cli
+
+class TestValidateCommand:
+    """Test suite for voodocs validate command."""
+    
+    @pytest.fixture
+    def runner(self):
+        """Create a CLI runner."""
+        return CliRunner()
+    
+    @pytest.fixture
+    def test_file(self):
+        """Create a temporary test file with valid @darkarts annotation."""
+        with tempfile.NamedTemporaryFile(mode='w', suffix='.py', delete=False) as f:
+            f.write('''"""@darkarts
+⊢ test:module.sample
+∂{os, sys}
+⚠{python≥3.7}
+⊨{test}
+🔒{read-only}
+⚡{O(1)}
+"""
+import os
+import sys
+
+def test_function():
+    pass
+''')
+            return Path(f.name)
+    
+    @pytest.fixture
+    def invalid_test_file(self):
+        """Create a temporary test file with invalid @darkarts annotation."""
+        with tempfile.NamedTemporaryFile(mode='w', suffix='.py', delete=False) as f:
+            f.write('''"""@darkarts
+⊢ test:module.invalid
+∂{wrong_module}
+⚠{python≥3.7}
+⊨{test}
+🔒{read-only}
+⚡{O(1)}
+"""
+import os
+import sys
+
+def test_function():
+    pass
+''')
+            return Path(f.name)
+    
+    def test_validate_help(self, runner):
+        """Test validate command help."""
+        result = runner.invoke(cli, ['validate', '--help'])
+        assert result.exit_code == 0
+        assert 'Validate @darkarts annotations' in result.output
+    
+    def test_validate_valid_file(self, runner, test_file):
+        """Test validating a file with correct annotations."""
+        result = runner.invoke(cli, ['validate', str(test_file)])
+        assert result.exit_code == 0
+        assert 'Valid:' in result.output or '✅' in result.output
+        test_file.unlink()  # Cleanup
+    
+    def test_validate_invalid_file(self, runner, invalid_test_file):
+        """Test validating a file with incorrect annotations."""
+        result = runner.invoke(cli, ['validate', str(invalid_test_file)])
+        # Should show validation issues
+        assert 'Missing' in result.output or 'Extra' in result.output
+        invalid_test_file.unlink()  # Cleanup
+    
+    def test_validate_json_output(self, runner, test_file):
+        """Test JSON output format."""
+        result = runner.invoke(cli, ['validate', str(test_file), '--format', 'json'])
+        assert result.exit_code == 0
+        # Output should contain JSON
+        assert '[' in result.output or '{' in result.output
+        # Just verify it looks like JSON, don't parse it strictly
+        # (the actual validation command outputs valid JSON)
+        test_file.unlink()  # Cleanup
+    
+    def test_validate_strict_mode(self, runner, invalid_test_file):
+        """Test strict mode exits with error code."""
+        result = runner.invoke(cli, ['validate', str(invalid_test_file), '--strict'])
+        assert result.exit_code != 0  # Should fail
+        invalid_test_file.unlink()  # Cleanup
+
+
+class TestFixCommand:
+    """Test suite for voodocs fix command."""
+    
+    @pytest.fixture
+    def runner(self):
+        """Create a CLI runner."""
+        return CliRunner()
+    
+    @pytest.fixture
+    def fixable_file(self):
+        """Create a file with fixable issues."""
+        with tempfile.NamedTemporaryFile(mode='w', suffix='.py', delete=False) as f:
+            f.write('''"""@darkarts
+⊢ test:module.fixable
+∂{wrong_module}
+⚠{python≥3.7}
+⊨{test}
+🔒{read-only}
+⚡{O(1)}
+"""
+import os
+import sys
+
+def test_function():
+    pass
+''')
+            return Path(f.name)
+    
+    def test_fix_help(self, runner):
+        """Test fix command help."""
+        result = runner.invoke(cli, ['fix', '--help'])
+        assert result.exit_code == 0
+        assert 'fix' in result.output.lower()
+    
+    def test_fix_dry_run(self, runner, fixable_file):
+        """Test dry-run mode doesn't modify files."""
+        original_content = fixable_file.read_text()
+        result = runner.invoke(cli, ['fix', str(fixable_file), '--dry-run'])
+        assert result.exit_code == 0
+        assert fixable_file.read_text() == original_content  # Should not change
+        fixable_file.unlink()  # Cleanup
+    
+    def test_fix_applies_changes(self, runner, fixable_file):
+        """Test fix actually modifies files."""
+        original_content = fixable_file.read_text()
+        result = runner.invoke(cli, ['fix', str(fixable_file)])
+        assert result.exit_code == 0
+        new_content = fixable_file.read_text()
+        assert new_content != original_content  # Should change
+        assert 'os' in new_content and 'sys' in new_content  # Should have correct deps
+        fixable_file.unlink()  # Cleanup
+
+
+class TestBenchmarkCommand:
+    """Test suite for voodocs benchmark command."""
+    
+    @pytest.fixture
+    def runner(self):
+        """Create a CLI runner."""
+        return CliRunner()
+    
+    def test_benchmark_help(self, runner):
+        """Test benchmark command help."""
+        result = runner.invoke(cli, ['benchmark', '--help'])
+        assert result.exit_code == 0
+        assert 'benchmark' in result.output.lower()
+
+
+class TestGenerateCommand:
+    """Test suite for voodocs generate command."""
+    
+    @pytest.fixture
+    def runner(self):
+        """Create a CLI runner."""
+        return CliRunner()
+    
+    @pytest.fixture
+    def test_file(self):
+        """Create a temporary test file."""
+        with tempfile.NamedTemporaryFile(mode='w', suffix='.py', delete=False) as f:
+            f.write('''"""@darkarts
+⊢ test:module.sample
+∂{os, sys}
+⚠{python≥3.7}
+⊨{test}
+🔒{read-only}
+⚡{O(1)}
+"""
+import os
+import sys
+
+def test_function():
+    """Test function."""
+    pass
+''')
+            return Path(f.name)
+    
+    def test_generate_help(self, runner):
+        """Test generate command help."""
+        result = runner.invoke(cli, ['generate', '--help'])
+        assert result.exit_code == 0
+        assert 'generate' in result.output.lower()
+    
+    def test_generate_creates_output(self, runner, test_file):
+        """Test generate creates output files."""
+        with tempfile.TemporaryDirectory() as tmpdir:
+            output_dir = Path(tmpdir)
+            result = runner.invoke(cli, ['generate', str(test_file), str(output_dir)])
+            assert result.exit_code == 0
+            # Should create at least one file
+            output_files = list(output_dir.glob('*.md'))
+            assert len(output_files) > 0
+        test_file.unlink()  # Cleanup