@voodocs/cli 0.1.0

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

@@ -0,0 +1,379 @@
+"""
+Code Documentation Plugin for DarkArts - Automated documentation generation.
+"""
+
+import ast
+import re
+from typing import Any, Dict, List, Optional
+from dataclasses import dataclass, field
+from darkarts.core import (
+    DarkArtsPlugin,
+    PluginMetadata,
+    PluginInput,
+    PluginOutput,
+    ParseError,
+)
+
+
+@dataclass
+class FunctionInfo:
+    """Information about a function."""
+    name: str
+    args: List[str]
+    returns: Optional[str]
+    docstring: Optional[str]
+    decorators: List[str] = field(default_factory=list)
+    lineno: int = 0
+    complexity: int = 0
+
+
+@dataclass
+class ClassInfo:
+    """Information about a class."""
+    name: str
+    bases: List[str]
+    docstring: Optional[str]
+    methods: List[FunctionInfo] = field(default_factory=list)
+    attributes: List[str] = field(default_factory=list)
+    lineno: int = 0
+
+
+@dataclass
+class CodeStructure:
+    """Parsed code structure."""
+    module_docstring: Optional[str]
+    imports: List[str]
+    functions: List[FunctionInfo]
+    classes: List[ClassInfo]
+    constants: List[str]
+    complexity_score: int = 0
+
+
+class VooDocsPlugin(DarkArtsPlugin):
+    """Plugin for automated code documentation generation."""
+    
+    def __init__(self):
+        """Initialize the code docs plugin."""
+        super().__init__()
+        self._metadata = PluginMetadata(
+            name="voodocs",
+            version="1.0.0",
+            description="Automated code documentation generation from Python source",
+            author="DarkArts Team",
+            dependencies=[],
+            capabilities=["parse", "analyze", "execute", "explain"],
+        )
+    
+    @property
+    def metadata(self) -> PluginMetadata:
+        """Return plugin metadata."""
+        return self._metadata
+    
+    def parse(self, input: PluginInput) -> CodeStructure:
+        """
+        Parse Python source code.
+        
+        Args:
+            input: The input containing Python source code
+            
+        Returns:
+            Parsed code structure
+            
+        Raises:
+            ParseError: If parsing fails
+        """
+        try:
+            tree = ast.parse(input.content)
+            return self._extract_structure(tree, input.content)
+        except SyntaxError as e:
+            raise ParseError(f"Syntax error in code: {e}")
+        except Exception as e:
+            raise ParseError(f"Failed to parse code: {e}")
+    
+    def analyze(self, parsed: CodeStructure) -> Dict[str, Any]:
+        """
+        Analyze code complexity and patterns.
+        
+        Args:
+            parsed: The parsed code structure
+            
+        Returns:
+            Analysis results
+        """
+        return {
+            "functions_count": len(parsed.functions),
+            "classes_count": len(parsed.classes),
+            "imports_count": len(parsed.imports),
+            "complexity": parsed.complexity_score,
+            "has_docstrings": self._check_docstrings(parsed),
+            "documentation_coverage": self._calculate_coverage(parsed),
+        }
+    
+    def execute(self, parsed: CodeStructure, analysis: Dict[str, Any]) -> PluginOutput:
+        """
+        Generate documentation.
+        
+        Args:
+            parsed: The parsed code structure
+            analysis: Analysis results
+            
+        Returns:
+            Plugin output with generated documentation
+        """
+        try:
+            docs = self._generate_markdown(parsed, analysis)
+            
+            return PluginOutput(
+                success=True,
+                result=docs,
+                explanation=self._generate_summary(parsed, analysis),
+                metadata=analysis,
+            )
+        except Exception as e:
+            return PluginOutput(
+                success=False,
+                result=None,
+                error=str(e),
+            )
+    
+    def explain(self, output: PluginOutput, level: str = "student") -> str:
+        """
+        Generate explanation of the documentation.
+        
+        Args:
+            output: The output to explain
+            level: Explanation level
+            
+        Returns:
+            Natural language explanation
+        """
+        if not output.success:
+            return f"Failed to generate documentation: {output.error}"
+        
+        if output.explanation:
+            return output.explanation
+        
+        return "Documentation generated successfully."
+    
+    def _extract_structure(self, tree: ast.AST, source: str) -> CodeStructure:
+        """Extract structure from AST."""
+        module_docstring = ast.get_docstring(tree)
+        imports = []
+        functions = []
+        classes = []
+        constants = []
+        
+        # Only iterate over top-level nodes
+        for node in tree.body:
+            if isinstance(node, (ast.Import, ast.ImportFrom)):
+                imports.append(ast.unparse(node))
+            
+            elif isinstance(node, ast.FunctionDef):
+                functions.append(self._extract_function(node))
+            
+            elif isinstance(node, ast.ClassDef):
+                classes.append(self._extract_class(node))
+            
+            elif isinstance(node, ast.Assign):
+                # Top-level constants (uppercase names)
+                for target in node.targets:
+                    if isinstance(target, ast.Name) and target.id.isupper():
+                        constants.append(target.id)
+        
+        # Calculate complexity
+        complexity = self._calculate_complexity(tree)
+        
+        return CodeStructure(
+            module_docstring=module_docstring,
+            imports=imports,
+            functions=functions,
+            classes=classes,
+            constants=constants,
+            complexity_score=complexity,
+        )
+    
+    def _extract_function(self, node: ast.FunctionDef) -> FunctionInfo:
+        """Extract function information."""
+        args = [arg.arg for arg in node.args.args]
+        returns = ast.unparse(node.returns) if node.returns else None
+        docstring = ast.get_docstring(node)
+        decorators = [ast.unparse(d) for d in node.decorator_list]
+        
+        # Calculate function complexity (simple metric)
+        complexity = sum(1 for _ in ast.walk(node) if isinstance(_, (ast.If, ast.For, ast.While, ast.Try)))
+        
+        return FunctionInfo(
+            name=node.name,
+            args=args,
+            returns=returns,
+            docstring=docstring,
+            decorators=decorators,
+            lineno=node.lineno,
+            complexity=complexity,
+        )
+    
+    def _extract_class(self, node: ast.ClassDef) -> ClassInfo:
+        """Extract class information."""
+        bases = [ast.unparse(base) for base in node.bases]
+        docstring = ast.get_docstring(node)
+        methods = []
+        attributes = []
+        
+        for item in node.body:
+            if isinstance(item, ast.FunctionDef):
+                methods.append(self._extract_function(item))
+            elif isinstance(item, ast.Assign):
+                for target in item.targets:
+                    if isinstance(target, ast.Name):
+                        attributes.append(target.id)
+        
+        return ClassInfo(
+            name=node.name,
+            bases=bases,
+            docstring=docstring,
+            methods=methods,
+            attributes=attributes,
+            lineno=node.lineno,
+        )
+    
+    def _calculate_complexity(self, tree: ast.AST) -> int:
+        """Calculate cyclomatic complexity."""
+        complexity = 1  # Base complexity
+        
+        for node in ast.walk(tree):
+            if isinstance(node, (ast.If, ast.While, ast.For, ast.ExceptHandler)):
+                complexity += 1
+            elif isinstance(node, ast.BoolOp):
+                complexity += len(node.values) - 1
+        
+        return complexity
+    
+    def _check_docstrings(self, structure: CodeStructure) -> bool:
+        """Check if code has docstrings."""
+        has_module_doc = structure.module_docstring is not None
+        has_function_docs = any(f.docstring for f in structure.functions)
+        has_class_docs = any(c.docstring for c in structure.classes)
+        
+        return has_module_doc or has_function_docs or has_class_docs
+    
+    def _calculate_coverage(self, structure: CodeStructure) -> float:
+        """Calculate documentation coverage percentage."""
+        total_items = 1 + len(structure.functions) + len(structure.classes)  # +1 for module
+        documented_items = 0
+        
+        if structure.module_docstring:
+            documented_items += 1
+        
+        documented_items += sum(1 for f in structure.functions if f.docstring)
+        documented_items += sum(1 for c in structure.classes if c.docstring)
+        
+        return (documented_items / total_items * 100) if total_items > 0 else 0
+    
+    def _generate_summary(self, structure: CodeStructure, analysis: Dict[str, Any]) -> str:
+        """Generate a summary of the documentation."""
+        summary = f"Generated documentation for:\n"
+        summary += f"- {analysis['functions_count']} functions\n"
+        summary += f"- {analysis['classes_count']} classes\n"
+        summary += f"- {analysis['imports_count']} imports\n"
+        summary += f"- Complexity score: {analysis['complexity']}\n"
+        summary += f"- Documentation coverage: {analysis['documentation_coverage']:.1f}%\n"
+        
+        return summary
+    
+    def _generate_markdown(self, structure: CodeStructure, analysis: Dict[str, Any]) -> str:
+        """Generate Markdown documentation."""
+        md = []
+        
+        # Module header
+        md.append("# Module Documentation\n")
+        
+        if structure.module_docstring:
+            md.append(f"{structure.module_docstring}\n")
+        
+        # Metrics
+        md.append("## Metrics\n")
+        md.append(f"- **Functions**: {analysis['functions_count']}")
+        md.append(f"- **Classes**: {analysis['classes_count']}")
+        md.append(f"- **Complexity**: {analysis['complexity']}")
+        md.append(f"- **Documentation Coverage**: {analysis['documentation_coverage']:.1f}%\n")
+        
+        # Imports
+        if structure.imports:
+            md.append("## Imports\n")
+            md.append("```python")
+            md.extend(structure.imports)
+            md.append("```\n")
+        
+        # Constants
+        if structure.constants:
+            md.append("## Constants\n")
+            for const in structure.constants:
+                md.append(f"- `{const}`")
+            md.append("")
+        
+        # Functions
+        if structure.functions:
+            md.append("## Functions\n")
+            for func in structure.functions:
+                md.append(f"### `{func.name}({', '.join(func.args)})`\n")
+                
+                if func.decorators:
+                    md.append(f"**Decorators**: {', '.join(f'`{d}`' for d in func.decorators)}\n")
+                
+                if func.returns:
+                    md.append(f"**Returns**: `{func.returns}`\n")
+                
+                if func.docstring:
+                    md.append(func.docstring)
+                else:
+                    md.append("*No documentation available.*")
+                
+                md.append(f"\n**Complexity**: {func.complexity}\n")
+        
+        # Classes
+        if structure.classes:
+            md.append("## Classes\n")
+            for cls in structure.classes:
+                md.append(f"### `class {cls.name}`\n")
+                
+                if cls.bases:
+                    md.append(f"**Inherits from**: {', '.join(f'`{b}`' for b in cls.bases)}\n")
+                
+                if cls.docstring:
+                    md.append(cls.docstring)
+                else:
+                    md.append("*No documentation available.*")
+                
+                md.append("")
+                
+                if cls.attributes:
+                    md.append("**Attributes**:")
+                    for attr in cls.attributes:
+                        md.append(f"- `{attr}`")
+                    md.append("")
+                
+                if cls.methods:
+                    md.append("**Methods**:\n")
+                    for method in cls.methods:
+                        md.append(f"#### `{method.name}({', '.join(method.args)})`\n")
+                        if method.docstring:
+                            md.append(method.docstring)
+                        else:
+                            md.append("*No documentation available.*")
+                        md.append("")
+        
+        return "\n".join(md)
+
+
+# Register plugin on import
+from darkarts.core import get_global_registry
+
+try:
+    registry = get_global_registry()
+    if not registry.has_plugin("voodocs"):
+        registry.register(VooDocsPlugin())
+except Exception:
+    pass  # Silently fail if registration fails
+
+
+__all__ = ["VooDocsPlugin"]

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

@@ -0,0 +1,151 @@
+"""
+AI-Native VooDocs Plugin for DarkArts
+
+Enhanced version that supports both:
+1. Traditional code documentation (AST-based)
+2. AI-native documentation (@voodocs annotations)
+"""
+
+from darkarts.core import (
+    DarkArtsPlugin,
+    PluginMetadata,
+    PluginInput,
+    PluginOutput,
+)
+from darkarts.annotations import AnnotationParser
+from .documentation_generator import DocumentationGenerator
+from .test_generator import TestGenerator
+from .api_spec_generator import APISpecGenerator
+
+
+class AIVooDocsPlugin(DarkArtsPlugin):
+    """Enhanced plugin for AI-native code documentation."""
+    
+    def __init__(self):
+        super().__init__()
+        self._metadata = PluginMetadata(
+            name="ai_voodocs",
+            version="2.0.0",
+            description="AI-native documentation system with automatic test and API generation from @voodocs annotations",
+            author="DarkArts Team",
+            dependencies=[],
+            capabilities=["parse", "analyze", "execute", "explain"],
+        )
+        
+        # Initialize generators
+        self.parser = AnnotationParser()
+        self.doc_generator = DocumentationGenerator()
+        self.test_generator = TestGenerator()
+        self.api_generator = APISpecGenerator()
+    
+    @property
+    def metadata(self) -> PluginMetadata:
+        return self._metadata
+    
+    def parse(self, input: PluginInput) -> dict:
+        """Parse source code and extract @voodocs annotations."""
+        source_code = input.content
+        source_file = input.metadata.get('source_file', '<string>')
+        
+        # Parse annotations
+        parsed = self.parser.parse_source(source_code, source_file)
+        
+        return {
+            'parsed_annotations': parsed,
+            'has_annotations': parsed.has_annotations(),
+            'source_code': source_code,
+            'source_file': source_file,
+        }
+    
+    def analyze(self, parsed: dict) -> dict:
+        """Analyze the parsed annotations."""
+        annotations = parsed['parsed_annotations']
+        
+        return {
+            'module_name': annotations.module.name,
+            'has_module_annotations': bool(
+                annotations.module.module_purpose or 
+                annotations.module.dependencies or 
+                annotations.module.assumptions
+            ),
+            'classes_count': len(annotations.module.classes),
+            'functions_count': len(annotations.get_all_functions()),
+            'has_annotations': parsed['has_annotations'],
+        }
+    
+    def execute(self, parsed: dict, analysis: dict) -> PluginOutput:
+        """Generate documentation, tests, and API specs."""
+        try:
+            annotations = parsed['parsed_annotations']
+            
+            # Generate all outputs
+            documentation = self.doc_generator.generate(annotations)
+            tests = self.test_generator.generate(annotations)
+            api_spec = self.api_generator.generate(annotations)
+            
+            result = {
+                'documentation': documentation,
+                'tests': tests,
+                'api_spec': api_spec,
+                'module': analysis['module_name'],
+            }
+            
+            return PluginOutput(
+                success=True,
+                result=result,
+                explanation=self._generate_explanation(analysis, result),
+                metadata=analysis,
+            )
+        
+        except Exception as e:
+            return PluginOutput(
+                success=False,
+                result=None,
+                error=str(e),
+            )
+    
+    def explain(self, output: PluginOutput, level: str = "student") -> str:
+        """Explain the AI-native documentation generation."""
+        if not output.success:
+            return f"Failed to generate documentation: {output.error}"
+        
+        if output.explanation:
+            return output.explanation
+        
+        return "AI-native documentation generated successfully."
+    
+    def _generate_explanation(self, analysis: dict, result: dict) -> str:
+        """Generate explanation of the process."""
+        lines = []
+        
+        lines.append("# AI-Native Documentation System")
+        lines.append("")
+        lines.append(f"**Module**: {analysis['module_name']}")
+        lines.append(f"**Has DarkArts Annotations**: {analysis['has_annotations']}")
+        lines.append("")
+        
+        lines.append("## Statistics")
+        lines.append(f"- Classes: {analysis['classes_count']}")
+        lines.append(f"- Functions: {analysis['functions_count']}")
+        lines.append(f"- Module Annotations: {'Yes' if analysis['has_module_annotations'] else 'No'}")
+        lines.append("")
+        
+        lines.append("## Generated Outputs")
+        lines.append("✅ **Documentation**: Human-readable Markdown from DarkArts annotations")
+        lines.append("✅ **Tests**: Automated test cases from preconditions/postconditions")
+        lines.append("✅ **API Spec**: OpenAPI specification from function contracts")
+        lines.append("")
+        
+        lines.append("## How It Works")
+        lines.append("1. **AI writes** precise mathematical/logical specifications in @voodocs annotations")
+        lines.append("2. **Parser extracts** annotations from source code")
+        lines.append("3. **Generators translate** annotations into:")
+        lines.append("   - Human-readable documentation (Markdown)")
+        lines.append("   - Automated test cases (pytest/unittest/jest)")
+        lines.append("   - API specifications (OpenAPI/GraphQL)")
+        
+        return "\n".join(lines)
+
+
+# Export
+__all__ = ['AIVooDocsPlugin']