@voodocs/cli 0.1.0

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

@@ -0,0 +1,610 @@
+"""
+VooDocs Documentation Generator
+
+Translates @voodocs annotations (using the DarkArts language) into human-readable documentation.
+"""
+
+from typing import List, Optional, Dict
+from pathlib import Path
+import re
+
+from darkarts.annotations.types import (
+    ParsedAnnotations,
+    ModuleAnnotation,
+    ClassAnnotation,
+    FunctionAnnotation,
+    ComplexityAnnotation,
+)
+
+
+class DocumentationGenerator:
+    """Generates human-readable documentation from @voodocs annotations."""
+    
+    def __init__(self):
+        self.output_dir = Path("docs")
+        self._init_translation_tables()
+    
+    def _init_translation_tables(self):
+        """Initialize mathematical symbol translation tables."""
+        # Mathematical symbols to natural language
+        self.math_symbols = {
+            '∀': 'for all',
+            '∃': 'there exists',
+            '∈': 'in',
+            '∉': 'not in',
+            '⊆': 'subset of',
+            '⊂': 'proper subset of',
+            '∪': 'union',
+            '∩': 'intersection',
+            '∅': 'empty set',
+            '≥': 'greater than or equal to',
+            '≤': 'less than or equal to',
+            '≠': 'not equal to',
+            '≈': 'approximately equal to',
+            '⟹': 'implies',
+            '⟺': 'if and only if',
+            '⇒': 'implies',
+            '⇔': 'if and only if',
+            '→': 'leads to',
+            '∧': 'and',
+            '∨': 'or',
+            '¬': 'not',
+            'ℝ': 'real numbers',
+            'ℝ⁺': 'positive real numbers',
+            'ℝ⁻': 'negative real numbers',
+            'ℤ': 'integers',
+            'ℤ⁺': 'positive integers',
+            'ℕ': 'natural numbers',
+            'ℚ': 'rational numbers',
+            'ℂ': 'complex numbers',
+        }
+        
+        # Logical operators
+        self.logical_ops = {
+            '∧': 'and',
+            '∨': 'or',
+            '¬': 'not',
+            '⟹': 'implies that',
+            '⟺': 'if and only if',
+            '⇒': 'implies that',
+            '⇔': 'if and only if',
+        }
+    
+    def generate(self, parsed: ParsedAnnotations, output_file: Optional[str] = None) -> str:
+        """Generate Markdown documentation from parsed annotations."""
+        if not parsed.has_annotations():
+            return self._generate_basic_docs(parsed)
+        
+        sections = []
+        
+        # Title
+        module_name = parsed.module.name.replace("_", " ").title()
+        sections.append(f"# {module_name}\n")
+        
+        # Badges
+        badges = self._generate_badges(parsed)
+        if badges:
+            sections.append(badges)
+        
+        # Table of Contents
+        toc = self._generate_table_of_contents(parsed)
+        if toc:
+            sections.append(toc)
+        
+        # Module overview
+        if parsed.module.module_purpose or parsed.module.dependencies or parsed.module.assumptions:
+            sections.append(self._generate_module_section(parsed.module))
+        
+        # Classes
+        if parsed.module.classes:
+            sections.append(self._generate_classes_section(parsed.module.classes))
+        
+        # Functions
+        functions = parsed.get_all_functions()
+        if functions:
+            sections.append(self._generate_functions_section(functions))
+        
+        # Combine all sections
+        documentation = "\n".join(sections)
+        
+        # Write to file if specified
+        if output_file:
+            output_path = Path(output_file)
+            output_path.parent.mkdir(parents=True, exist_ok=True)
+            output_path.write_text(documentation, encoding='utf-8')
+        
+        return documentation
+    
+    def _generate_basic_docs(self, parsed: ParsedAnnotations) -> str:
+        """Generate basic documentation for code without @voodocs annotations."""
+        sections = []
+        
+        module_name = parsed.module.name.replace("_", " ").title()
+        sections.append(f"# {module_name}\n")
+        sections.append("*No @voodocs annotations found in this module.*\n")
+        sections.append("Consider adding @voodocs annotations to enable automatic documentation generation.\n")
+        
+        return "\n".join(sections)
+    
+    def _generate_module_section(self, module: ModuleAnnotation) -> str:
+        """Generate module overview section."""
+        lines = ["## Overview\n"]
+        
+        if module.module_purpose:
+            lines.append(f"{module.module_purpose}\n")
+        
+        if module.dependencies:
+            lines.append("### Dependencies\n")
+            for dep in module.dependencies:
+                lines.append(f"- {dep}")
+            lines.append("")
+        
+        if module.assumptions:
+            lines.append("### Assumptions\n")
+            lines.append("This module makes the following assumptions:\n")
+            for assumption in module.assumptions:
+                lines.append(f"- {assumption}")
+            lines.append("")
+        
+        if hasattr(module, 'security_model') and module.security_model:
+            lines.append("### Security Model\n")
+            lines.append(f"{module.security_model}\n")
+        
+        return "\n".join(lines)
+    
+    def _generate_classes_section(self, classes: List[ClassAnnotation]) -> str:
+        """Generate classes section."""
+        lines = ["## Classes\n"]
+        
+        for cls in classes:
+            lines.append(f"### `{cls.name}`\n")
+            
+            if cls.class_invariants:
+                lines.append("**Class Invariants**\n")
+                lines.append("The following properties must always hold true for instances of this class:\n")
+                for inv in cls.class_invariants:
+                    readable_inv = self._translate_to_natural_language(inv)
+                    lines.append(f"- {readable_inv}")
+                lines.append("")
+            
+            if cls.state_transitions:
+                lines.append("**State Transitions**\n")
+                lines.append("Valid state changes for this class:\n")
+                for st in cls.state_transitions:
+                    if hasattr(st, 'from_state'):
+                        lines.append(f"- **{st.from_state}** → **{st.to_state}**: {st.condition}")
+                    else:
+                        # Parse state transition string
+                        st_text = self._format_state_transition(str(st))
+                        lines.append(f"- {st_text}")
+                lines.append("")
+            
+            if hasattr(cls, 'thread_safety') and cls.thread_safety:
+                lines.append(f"**Thread Safety**: {cls.thread_safety}\n")
+            
+            # Methods
+            if cls.methods:
+                lines.append("#### Methods\n")
+                for method in cls.methods:
+                    lines.append(self._generate_function_doc(method, is_method=True))
+        
+        return "\n".join(lines)
+    
+    def _generate_functions_section(self, functions: List[FunctionAnnotation]) -> str:
+        """Generate functions section."""
+        lines = ["## Functions\n"]
+        
+        for func in functions:
+            lines.append(self._generate_function_doc(func, is_method=False))
+        
+        return "\n".join(lines)
+    
+    def _generate_function_doc(self, func: FunctionAnnotation, is_method: bool = False) -> str:
+        """Generate documentation for a single function."""
+        lines = []
+        
+        # Function signature
+        prefix = "####" if is_method else "###"
+        lines.append(f"{prefix} `{func.name}()`\n")
+        
+        # Purpose/solve
+        if func.solve:
+            lines.append(f"{func.solve}\n")
+        
+        # Preconditions
+        if func.preconditions:
+            lines.append("**Requirements**\n")
+            lines.append("The following conditions must be met before calling this function:\n")
+            for pre in func.preconditions:
+                readable_pre = self._translate_to_natural_language(pre)
+                lines.append(f"- {readable_pre}")
+            lines.append("")
+        
+        # Postconditions
+        if func.postconditions:
+            lines.append("**Guarantees**\n")
+            lines.append("After successful execution, the following conditions will be true:\n")
+            for post in func.postconditions:
+                readable_post = self._translate_to_natural_language(post)
+                lines.append(f"- {readable_post}")
+            lines.append("")
+        
+        # Invariants
+        if func.invariants:
+            lines.append("**Invariants**\n")
+            lines.append("The following properties remain unchanged throughout execution:\n")
+            for inv in func.invariants:
+                readable_inv = self._translate_to_natural_language(inv)
+                lines.append(f"- {readable_inv}")
+            lines.append("")
+        
+        # Side effects
+        if hasattr(func, 'side_effects') and func.side_effects:
+            lines.append("**Side Effects**\n")
+            for effect in func.side_effects:
+                lines.append(f"- {effect}")
+            lines.append("")
+        
+        # Security implications
+        if hasattr(func, 'security_implications') and func.security_implications:
+            lines.append("**⚠️ Security Considerations**\n")
+            for implication in func.security_implications:
+                lines.append(f"- {implication}")
+            lines.append("")
+        
+        # Error handling
+        if hasattr(func, 'error_handling') and func.error_handling:
+            lines.append(f"**Error Handling**: {func.error_handling}\n")
+        
+        # Optimization
+        if func.optimize:
+            readable_opt = self._translate_to_natural_language(func.optimize)
+            lines.append(f"**Optimization Goal**: {readable_opt}\n")
+        
+        # Complexity
+        if func.complexity:
+            complexity_text = self._format_complexity(func.complexity)
+            lines.append(f"**Performance**: {complexity_text}\n")
+        
+        # Error cases
+        if func.error_cases:
+            lines.append("**Error Cases**\n")
+            for error in func.error_cases:
+                if hasattr(error, 'condition'):
+                    lines.append(f"- **{error.error_type}**: {error.condition}")
+                else:
+                    lines.append(f"- {error}")
+            lines.append("")
+        
+        # Usage examples (generated from preconditions)
+        usage_example = self._generate_usage_example(func)
+        if usage_example:
+            lines.append("**Usage Example**\n")
+            lines.append("```python")
+            lines.append(usage_example)
+            lines.append("```\n")
+        
+        return "\n".join(lines)
+    
+    def _translate_to_natural_language(self, expression: str) -> str:
+        """
+        Translate mathematical notation to natural language.
+        
+        This method converts DarkArts mathematical expressions into readable English.
+        """
+        text = expression.strip()
+        
+        # Handle quantifiers (∀, ∃) specially
+        text = self._translate_quantifiers(text)
+        
+        # Handle logical operators
+        text = self._translate_logical_operators(text)
+        
+        # Handle mathematical symbols
+        for symbol, replacement in self.math_symbols.items():
+            if symbol in text:
+                text = text.replace(symbol, replacement)
+        
+        # Clean up extra spaces
+        text = re.sub(r'\s+', ' ', text)
+        
+        return text
+    
+    def _translate_quantifiers(self, text: str) -> str:
+        """Translate quantifiers (∀, ∃) into natural language."""
+        # Pattern: ∀ x ∈ S: P(x)
+        # Translation: For all x in S, P(x) holds
+        
+        # Universal quantifier
+        text = re.sub(
+            r'∀\s*(\w+)\s*∈\s*([^:]+):\s*(.+)',
+            r'For all \1 in \2, \3',
+            text
+        )
+        
+        # Existential quantifier
+        text = re.sub(
+            r'∃\s*(\w+)\s*∈\s*([^:]+):\s*(.+)',
+            r'There exists \1 in \2 such that \3',
+            text
+        )
+        
+        return text
+    
+    def _translate_logical_operators(self, text: str) -> str:
+        """Translate logical operators into natural language."""
+        # Handle compound expressions
+        # ⇔ (if and only if)
+        text = re.sub(r'\s*⇔\s*', ' if and only if ', text)
+        text = re.sub(r'\s*⟺\s*', ' if and only if ', text)
+        
+        # ⇒ (implies)
+        text = re.sub(r'\s*⇒\s*', ' implies ', text)
+        text = re.sub(r'\s*⟹\s*', ' implies ', text)
+        
+        # ∧ (and)
+        text = re.sub(r'\s*∧\s*', ' and ', text)
+        
+        # ∨ (or)
+        text = re.sub(r'\s*∨\s*', ' or ', text)
+        
+        # ¬ (not)
+        text = re.sub(r'¬\s*', 'not ', text)
+        
+        return text
+    
+    def _format_state_transition(self, transition: str) -> str:
+        """Format a state transition string for better readability."""
+        # Pattern: STATE1 → STATE2: condition
+        match = re.match(r'(.+?)\s*→\s*(.+?):\s*(.+)', transition)
+        if match:
+            from_state, to_state, condition = match.groups()
+            return f"**{from_state.strip()}** → **{to_state.strip()}**: {condition.strip()}"
+        return transition
+    
+    def _format_complexity(self, complexity: ComplexityAnnotation) -> str:
+        """Format complexity annotation into readable text."""
+        parts = []
+        
+        if complexity.time:
+            parts.append(f"Time complexity is {complexity.time}")
+        
+        if complexity.space:
+            parts.append(f"space complexity is {complexity.space}")
+        
+        if parts:
+            return ", ".join(parts) + "."
+        
+        return "Complexity not specified."
+    
+    def generate_api_reference(self, parsed: ParsedAnnotations, output_file: Optional[str] = None) -> str:
+        """Generate API reference documentation."""
+        sections = []
+        
+        # Title
+        module_name = parsed.module.name.replace("_", " ").title()
+        sections.append(f"# {module_name} API Reference\n")
+        
+        # Table of contents
+        sections.append("## Table of Contents\n")
+        
+        if parsed.module.classes:
+            sections.append("### Classes\n")
+            for cls in parsed.module.classes:
+                sections.append(f"- [{cls.name}](#{cls.name.lower()})")
+            sections.append("")
+        
+        functions = parsed.get_all_functions()
+        if functions:
+            sections.append("### Functions\n")
+            for func in functions:
+                sections.append(f"- [{func.name}](#{func.name.lower()})")
+            sections.append("")
+        
+        # Detailed API docs
+        sections.append("---\n")
+        
+        # Classes
+        if parsed.module.classes:
+            for cls in parsed.module.classes:
+                sections.append(f"## {cls.name}\n")
+                sections.append(f"*Defined at line {cls.line_number}*\n")
+                
+                if cls.class_invariants:
+                    sections.append("### Class Invariants\n")
+                    sections.append("```")
+                    for inv in cls.class_invariants:
+                        sections.append(inv)
+                    sections.append("```\n")
+                
+                if cls.methods:
+                    sections.append("### Methods\n")
+                    for method in cls.methods:
+                        sections.append(f"#### `{method.name}()`\n")
+                        sections.append(f"*Defined at line {method.line_number}*\n")
+                        
+                        if method.solve:
+                            sections.append(f"**Purpose:** {method.solve}\n")
+                        
+                        if method.preconditions:
+                            sections.append("**Preconditions:**")
+                            sections.append("```")
+                            for pre in method.preconditions:
+                                sections.append(pre)
+                            sections.append("```\n")
+                        
+                        if method.postconditions:
+                            sections.append("**Postconditions:**")
+                            sections.append("```")
+                            for post in method.postconditions:
+                                sections.append(post)
+                            sections.append("```\n")
+        
+        # Functions
+        if functions:
+            sections.append("## Functions\n")
+            for func in functions:
+                sections.append(f"### `{func.name}()`\n")
+                sections.append(f"*Defined at line {func.line_number}*\n")
+                
+                if func.solve:
+                    sections.append(f"**Purpose:** {func.solve}\n")
+                
+                if func.preconditions:
+                    sections.append("**Preconditions:**")
+                    sections.append("```")
+                    for pre in func.preconditions:
+                        sections.append(pre)
+                    sections.append("```\n")
+                
+                if func.postconditions:
+                    sections.append("**Postconditions:**")
+                    sections.append("```")
+                    for post in func.postconditions:
+                        sections.append(post)
+                    sections.append("```\n")
+                
+                if func.complexity:
+                    complexity_text = self._format_complexity(func.complexity)
+                    sections.append(f"**Performance:** {complexity_text}\n")
+        
+        documentation = "\n".join(sections)
+        
+        if output_file:
+            output_path = Path(output_file)
+            output_path.parent.mkdir(parents=True, exist_ok=True)
+            output_path.write_text(documentation, encoding='utf-8')
+        
+        return documentation
+
+    def _generate_usage_example(self, func: FunctionAnnotation) -> Optional[str]:
+        """Generate a usage example from function annotations."""
+        if not func.preconditions:
+            return None
+        
+        # Try to infer example values from preconditions
+        example_params = self._infer_example_params(func.preconditions)
+        
+        if not example_params:
+            return None
+        
+        # Build example code
+        lines = []
+        lines.append(f"# Example usage of {func.name}()")
+        
+        # Add variable assignments
+        for param, value in example_params.items():
+            lines.append(f"{param} = {value}")
+        
+        # Add function call
+        param_list = ", ".join(example_params.keys())
+        lines.append(f"result = {func.name}({param_list})")
+        
+        # Add postcondition check if available
+        if func.postconditions:
+            lines.append("")
+            lines.append("# Postconditions are guaranteed:")
+            for post in func.postconditions[:2]:  # Show first 2 postconditions
+                readable_post = self._translate_to_natural_language(post)
+                lines.append(f"# - {readable_post}")
+        
+        return "\n".join(lines)
+    
+    def _infer_example_params(self, preconditions: List[str]) -> Dict[str, str]:
+        """Infer example parameter values from preconditions."""
+        params = {}
+        
+        for pre in preconditions:
+            # Pattern: "x > 0" → x = 1
+            if match := re.match(r'(\w+)\s*>\s*(\d+)', pre):
+                var_name = match.group(1)
+                min_val = int(match.group(2))
+                params[var_name] = str(min_val + 1)
+            
+            # Pattern: "x >= 0" → x = 0
+            elif match := re.match(r'(\w+)\s*>=\s*(\d+)', pre):
+                var_name = match.group(1)
+                min_val = int(match.group(2))
+                params[var_name] = str(min_val)
+            
+            # Pattern: "x < 100" → x = 50
+            elif match := re.match(r'(\w+)\s*<\s*(\d+)', pre):
+                var_name = match.group(1)
+                max_val = int(match.group(2))
+                if var_name in params:
+                    # Combine with existing constraint
+                    current = int(params[var_name])
+                    params[var_name] = str(min(current, max_val - 1))
+                else:
+                    params[var_name] = str(max_val // 2)
+            
+            # Pattern: "x in [1, 2, 3]" → x = 1
+            elif match := re.match(r'(\w+)\s+in\s+\[(.+?)\]', pre):
+                var_name = match.group(1)
+                values = match.group(2).split(',')
+                params[var_name] = values[0].strip()
+            
+            # Pattern: "x is string" → x = "example"
+            elif match := re.search(r'(\w+).*(?:is|must be).*string', pre, re.IGNORECASE):
+                var_name = match.group(1)
+                params[var_name] = '"example"'
+            
+            # Pattern: "x is list" → x = [1, 2, 3]
+            elif match := re.search(r'(\w+).*(?:is|must be).*list', pre, re.IGNORECASE):
+                var_name = match.group(1)
+                params[var_name] = '[1, 2, 3]'
+            
+            # Pattern: "x is boolean" → x = True
+            elif match := re.search(r'(\w+).*(?:is|must be).*(?:bool|boolean)', pre, re.IGNORECASE):
+                var_name = match.group(1)
+                params[var_name] = 'True'
+        
+        return params
+
+    def _generate_badges(self, parsed: ParsedAnnotations) -> str:
+        """Generate status badges for the documentation."""
+        badges = []
+        
+        # Documentation coverage badge
+        total_items = len(parsed.module.classes) + len(parsed.get_all_functions())
+        annotated_items = sum(1 for _ in parsed.module.classes if _.invariants or _.state_transitions)
+        annotated_items += sum(1 for f in parsed.get_all_functions() if f.preconditions or f.postconditions)
+        
+        if total_items > 0:
+            coverage = int((annotated_items / total_items) * 100)
+            color = "green" if coverage >= 80 else "yellow" if coverage >= 50 else "red"
+            badges.append(f"![Documentation Coverage](https://img.shields.io/badge/docs-{coverage}%25-{color})")
+        
+        # VooDocs badge
+        badges.append("![VooDocs](https://img.shields.io/badge/documented_with-VooDocs-purple)")
+        
+        # Language badge
+        lang = parsed.language.value if hasattr(parsed.language, 'value') else str(parsed.language)
+        badges.append(f"![Language](https://img.shields.io/badge/language-{lang}-blue)")
+        
+        return " ".join(badges) + "\\n" if badges else ""
+    
+    def _generate_table_of_contents(self, parsed: ParsedAnnotations) -> str:
+        """Generate table of contents for the documentation."""
+        lines = []
+        lines.append("## Table of Contents\\n")
+        
+        # Module overview
+        if parsed.module.module_purpose or parsed.module.dependencies or parsed.module.assumptions:
+            lines.append("- [Overview](#overview)")
+        
+        # Classes
+        if parsed.module.classes:
+            lines.append("- [Classes](#classes)")
+            for cls in parsed.module.classes:
+                lines.append(f"  - [{cls.name}](#{cls.name.lower()})")
+        
+        # Functions
+        functions = parsed.get_all_functions()
+        if functions:
+            lines.append("- [Functions](#functions)")
+            for func in functions:
+                lines.append(f"  - [{func.name}](#{func.name.lower()})")
+        
+        lines.append("")
+        return "\\n".join(lines)