@voodocs/cli 0.1.0

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

@@ -0,0 +1,706 @@
+"""
+VooDocs AI Instruction Generator
+
+Generates instruction files that teach AI coding assistants (Cursor, Claude Code, etc.)
+how to use @voodocs annotations while writing code.
+"""
+
+from typing import Optional, Dict, List
+from pathlib import Path
+import json
+
+
+class InstructionGenerator:
+    """Generates AI assistant instruction files for VooDocs."""
+    
+    # Supported AI assistants
+    ASSISTANTS = {
+        "cursor": {
+            "name": "Cursor",
+            "config_file": ".cursorrules",
+            "format": "markdown"
+        },
+        "claude": {
+            "name": "Claude Code / Cline",
+            "config_file": ".claude/instructions.md",
+            "format": "markdown"
+        },
+        "copilot": {
+            "name": "GitHub Copilot",
+            "config_file": ".github/copilot-instructions.md",
+            "format": "markdown"
+        },
+        "windsurf": {
+            "name": "Windsurf",
+            "config_file": ".windsurfrules",
+            "format": "markdown"
+        },
+        "generic": {
+            "name": "Generic AI Assistant",
+            "config_file": "VOODOCS_INSTRUCTIONS.md",
+            "format": "markdown"
+        }
+    }
+    
+    def __init__(self, assistant: str = "generic", project_name: str = "Your Project"):
+        """
+        Initialize instruction generator.
+        
+        Args:
+            assistant: AI assistant type ("cursor", "claude", "copilot", "windsurf", "generic")
+            project_name: Name of the project for personalization
+        """
+        if assistant not in self.ASSISTANTS:
+            raise ValueError(f"Unsupported assistant: {assistant}. Choose from: {list(self.ASSISTANTS.keys())}")
+        
+        self.assistant = assistant
+        self.assistant_info = self.ASSISTANTS[assistant]
+        self.project_name = project_name
+    
+    def generate(self, output_file: Optional[str] = None, language: str = "python") -> str:
+        """
+        Generate instruction file for the AI assistant.
+        
+        Args:
+            output_file: Optional output file path (defaults to assistant's config file)
+            language: Primary programming language ("python", "typescript", "javascript")
+        
+        Returns:
+            Generated instruction content
+        """
+        instructions = self._generate_instructions(language)
+        
+        # Determine output file
+        if output_file is None:
+            output_file = self.assistant_info["config_file"]
+        
+        # Write to file
+        output_path = Path(output_file)
+        output_path.parent.mkdir(parents=True, exist_ok=True)
+        output_path.write_text(instructions, encoding='utf-8')
+        
+        return instructions
+    
+    def _generate_instructions(self, language: str) -> str:
+        """Generate the instruction content."""
+        sections = []
+        
+        # Header
+        sections.append(self._generate_header())
+        
+        # Overview
+        sections.append(self._generate_overview())
+        
+        # Core principles
+        sections.append(self._generate_core_principles())
+        
+        # Annotation syntax
+        sections.append(self._generate_annotation_syntax(language))
+        
+        # Annotation fields
+        sections.append(self._generate_annotation_fields())
+        
+        # DarkArts language guide
+        sections.append(self._generate_darkarts_guide())
+        
+        # Examples
+        sections.append(self._generate_examples(language))
+        
+        # Workflow integration
+        sections.append(self._generate_workflow())
+        
+        # Best practices
+        sections.append(self._generate_best_practices())
+        
+        # Footer
+        sections.append(self._generate_footer())
+        
+        return "\n\n".join(sections)
+    
+    def _generate_header(self) -> str:
+        """Generate instruction header."""
+        return f"""# VooDocs Instructions for {self.assistant_info['name']}
+
+**Project**: {self.project_name}  
+**Generated**: Automatically by VooDocs  
+**Purpose**: Guide AI assistants to document code using @voodocs annotations
+
+---"""
+    
+    def _generate_overview(self) -> str:
+        """Generate overview section."""
+        return """## Overview
+
+VooDocs is an AI-native documentation system that allows you to document code in **DarkArts language** - a mathematical and logical notation that AI naturally understands. Your annotations will be automatically translated into human-readable documentation, property-based tests, and API specifications.
+
+**Key Benefits:**
+- Document in AI's native language (mathematical notation)
+- Automatic generation of comprehensive tests
+- Property-based testing with Hypothesis
+- OpenAPI/GraphQL spec generation
+- Human-readable documentation output
+
+**Your Role:**
+As an AI coding assistant, you should add `@voodocs` annotations to **every significant function, class, and module** you write. Think of it as "documentation-driven development" where you specify the contract first."""
+    
+    def _generate_core_principles(self) -> str:
+        """Generate core principles section."""
+        return """## Core Principles
+
+When writing code with VooDocs annotations, follow these principles:
+
+1. **Annotate as you code** - Add `@voodocs` annotations immediately when creating functions/classes
+2. **Be precise** - Use mathematical notation for exact specifications
+3. **Think in contracts** - Define preconditions, postconditions, and invariants
+4. **Specify complexity** - Always include time/space complexity
+5. **Document security** - Note security implications and assumptions
+6. **Fail-safe design** - Specify error cases and how they're handled"""
+    
+    def _generate_annotation_syntax(self, language: str) -> str:
+        """Generate annotation syntax section."""
+        if language == "python":
+            return """## Annotation Syntax (Python)
+
+Place `@voodocs` annotations in docstrings:
+
+```python
+def function_name(param1: type, param2: type) -> return_type:
+    \"\"\"@voodocs
+    preconditions: ["param1 > 0", "param2 is not None"]
+    postconditions: ["result >= param1"]
+    complexity: "O(n)"
+    \"\"\"
+    # Implementation
+    pass
+```
+
+For classes:
+
+```python
+class ClassName:
+    \"\"\"@voodocs
+    class_invariants: ["∀ item ∈ self.items: item.is_valid()"]
+    state_transitions: ["IDLE → PROCESSING", "PROCESSING → COMPLETE"]
+    \"\"\"
+    pass
+```"""
+        
+        elif language in ["typescript", "javascript"]:
+            return """## Annotation Syntax (TypeScript/JavaScript)
+
+Place `@voodocs` annotations in JSDoc-style comments:
+
+```typescript
+/**@voodocs
+preconditions: ["amount > 0", "account.isActive()"]
+postconditions: ["account.balance decreased by amount"]
+complexity: "O(1)"
+security_implications: ["Requires authentication", "Validates account ownership"]
+*/
+function withdraw(account: Account, amount: number): boolean {
+    // Implementation
+}
+```
+
+For classes:
+
+```typescript
+/**@voodocs
+class_invariants: ["this.balance >= 0", "this.transactions.length >= 0"]
+state_transitions: ["PENDING → ACTIVE", "ACTIVE → SUSPENDED", "SUSPENDED → CLOSED"]
+*/
+class BankAccount {
+    // Implementation
+}
+```"""
+        
+        else:
+            return """## Annotation Syntax
+
+Use language-appropriate comment syntax with `@voodocs` marker."""
+    
+    def _generate_annotation_fields(self) -> str:
+        """Generate annotation fields reference."""
+        return """## Annotation Fields Reference
+
+### For Functions/Methods
+
+| Field | Required | Description | Example |
+|-------|----------|-------------|---------|
+| `preconditions` | Recommended | Conditions that must be true before execution | `["x > 0", "user is authenticated"]` |
+| `postconditions` | Recommended | Conditions guaranteed after execution | `["result > 0", "database updated"]` |
+| `complexity` | Recommended | Time/space complexity | `"O(n log n)"` or `"O(n)"` |
+| `invariants` | Optional | Properties that remain unchanged | `["∀ x: x ∈ original_set ⇒ x ∈ result_set"]` |
+| `error_cases` | Optional | Error conditions and exceptions | `["x < 0 → ValueError", "file not found → FileNotFoundError"]` |
+| `side_effects` | Optional | External changes made | `["Writes to database", "Sends email"]` |
+| `security_implications` | Optional | Security considerations | `["Requires admin role", "Rate limited"]` |
+| `assumptions` | Optional | Environmental assumptions | `["Database is available", "Network is stable"]` |
+
+### For Classes
+
+| Field | Description | Example |
+|-------|-------------|---------|
+| `class_invariants` | Properties that always hold | `["∀ item ∈ queue: item.status ∈ VALID_STATUSES"]` |
+| `state_transitions` | Valid state changes | `["IDLE → PROCESSING", "PROCESSING → COMPLETE"]` |
+| `thread_safety` | Concurrency safety | `"Thread-safe with mutex"` or `"Not thread-safe"` |
+
+### For Modules
+
+| Field | Description | Example |
+|-------|-------------|---------|
+| `module_purpose` | High-level module description | `"User authentication and authorization"` |
+| `dependencies` | External dependencies | `["@supabase/supabase-js", "bcrypt"]` |
+| `assumptions` | Module-level assumptions | `["Database schema v2.0", "Redis available"]` |
+| `security_model` | Overall security approach | `"Defense in depth - fails closed"` |"""
+    
+    def _generate_darkarts_guide(self) -> str:
+        """Generate DarkArts language guide."""
+        return """## DarkArts Language Guide
+
+DarkArts is a mathematical notation language for precise specifications. Use these symbols:
+
+### Logical Operators
+
+| Symbol | Meaning | Example |
+|--------|---------|---------|
+| `∧` | AND | `x > 0 ∧ y > 0` |
+| `∨` | OR | `x = 0 ∨ y = 0` |
+| `¬` | NOT | `¬(x < 0)` |
+| `⇒` | IMPLIES | `x > 0 ⇒ result > 0` |
+| `⇔` | IF AND ONLY IF | `result = true ⇔ user.isAdmin` |
+
+### Quantifiers
+
+| Symbol | Meaning | Example |
+|--------|---------|---------|
+| `∀` | FOR ALL | `∀ x ∈ items: x > 0` |
+| `∃` | THERE EXISTS | `∃ x ∈ items: x = target` |
+
+### Set Operations
+
+| Symbol | Meaning | Example |
+|--------|---------|---------|
+| `∈` | IN / ELEMENT OF | `x ∈ valid_values` |
+| `∉` | NOT IN | `x ∉ blacklist` |
+| `⊆` | SUBSET OF | `result ⊆ input` |
+| `∪` | UNION | `result = set1 ∪ set2` |
+| `∩` | INTERSECTION | `common = set1 ∩ set2` |
+
+### Comparisons
+
+| Symbol | Meaning | Example |
+|--------|---------|---------|
+| `≥` | GREATER THAN OR EQUAL | `x ≥ 0` |
+| `≤` | LESS THAN OR EQUAL | `x ≤ 100` |
+| `≠` | NOT EQUAL | `x ≠ 0` |
+| `≈` | APPROXIMATELY EQUAL | `result ≈ expected` |
+
+### Number Sets
+
+| Symbol | Meaning | Example |
+|--------|---------|---------|
+| `ℕ` | Natural numbers (0, 1, 2, ...) | `n ∈ ℕ` |
+| `ℤ` | Integers (..., -1, 0, 1, ...) | `x ∈ ℤ` |
+| `ℝ` | Real numbers | `x ∈ ℝ` |
+
+**Tip**: You can use plain English too! VooDocs understands both mathematical notation and natural language. Mix them for clarity."""
+    
+    def _generate_examples(self, language: str) -> str:
+        """Generate example annotations."""
+        if language == "python":
+            return """## Examples
+
+### Example 1: Simple Function
+
+```python
+def calculate_discount(price: float, discount_percent: float) -> float:
+    \"\"\"@voodocs
+    preconditions: [
+        "price > 0",
+        "discount_percent >= 0",
+        "discount_percent <= 100"
+    ]
+    postconditions: [
+        "result >= 0",
+        "result <= price",
+        "result = price * (1 - discount_percent/100)"
+    ]
+    complexity: "O(1)"
+    error_cases: [
+        "price <= 0 → ValueError",
+        "discount_percent < 0 → ValueError",
+        "discount_percent > 100 → ValueError"
+    ]
+    \"\"\"
+    if price <= 0:
+        raise ValueError("Price must be positive")
+    if not 0 <= discount_percent <= 100:
+        raise ValueError("Discount must be between 0 and 100")
+    
+    return price * (1 - discount_percent / 100)
+```
+
+### Example 2: Function with Security
+
+```python
+def delete_user(user_id: str, admin_token: str) -> bool:
+    \"\"\"@voodocs
+    preconditions: [
+        "user_id is valid UUID",
+        "admin_token is valid JWT",
+        "admin has 'delete_user' permission"
+    ]
+    postconditions: [
+        "returns true ⇔ user deleted successfully",
+        "returns false ⇔ user not found ∨ permission denied"
+    ]
+    security_implications: [
+        "Requires admin authentication",
+        "Logs deletion for audit trail",
+        "Soft delete - data retained for 30 days"
+    ]
+    side_effects: [
+        "Writes to audit log",
+        "Sends notification email",
+        "Invalidates user sessions"
+    ]
+    complexity: "O(1)"
+    \"\"\"
+    # Implementation
+    pass
+```
+
+### Example 3: Class with Invariants
+
+```python
+class BankAccount:
+    \"\"\"@voodocs
+    class_invariants: [
+        "self.balance >= 0",
+        "len(self.transactions) >= 0",
+        "∀ tx ∈ self.transactions: tx.amount ≠ 0"
+    ]
+    state_transitions: [
+        "PENDING → ACTIVE: when KYC verified",
+        "ACTIVE → FROZEN: when suspicious activity detected",
+        "FROZEN → ACTIVE: when investigation cleared",
+        "ACTIVE → CLOSED: when user requests closure"
+    ]
+    thread_safety: "Thread-safe with account-level mutex"
+    \"\"\"
+    
+    def __init__(self, account_id: str):
+        self.balance = 0.0
+        self.transactions = []
+        self.status = "PENDING"
+    
+    def deposit(self, amount: float) -> bool:
+        \"\"\"@voodocs
+        preconditions: [
+            "amount > 0",
+            "self.status = ACTIVE"
+        ]
+        postconditions: [
+            "self.balance = old(self.balance) + amount",
+            "len(self.transactions) = old(len(self.transactions)) + 1"
+        ]
+        invariants: [
+            "self.balance >= 0"
+        ]
+        complexity: "O(1)"
+        \"\"\"
+        # Implementation
+        pass
+```
+
+### Example 4: Algorithm with Complexity
+
+```python
+def quicksort(arr: list[int]) -> list[int]:
+    \"\"\"@voodocs
+    preconditions: [
+        "arr is list of integers"
+    ]
+    postconditions: [
+        "len(result) = len(arr)",
+        "∀ i, j: i < j ⇒ result[i] <= result[j]",
+        "result contains same elements as arr (permutation)"
+    ]
+    complexity: "O(n log n)"
+    invariants: [
+        "Partition maintains: ∀ x ∈ left: x <= pivot",
+        "∀ x ∈ right: x > pivot"
+    ]
+    \"\"\"
+    # Implementation
+    pass
+```"""
+        
+        else:  # TypeScript/JavaScript
+            return """## Examples
+
+### Example 1: API Route Handler
+
+```typescript
+/**@voodocs
+preconditions: [
+    "request.user is authenticated",
+    "request.body.amount > 0",
+    "request.body.recipientId exists in database"
+]
+postconditions: [
+    "returns 200 ⇔ transfer successful",
+    "returns 400 ⇔ invalid input",
+    "returns 403 ⇔ insufficient funds",
+    "sender.balance decreased by amount",
+    "recipient.balance increased by amount"
+]
+security_implications: [
+    "Requires authentication",
+    "Rate limited to 10 transfers/minute",
+    "Validates account ownership"
+]
+side_effects: [
+    "Updates database (2 accounts)",
+    "Creates transaction record",
+    "Sends notification emails"
+]
+complexity: "O(1)"
+*/
+async function transferMoney(
+    request: Request,
+    response: Response
+): Promise<void> {
+    // Implementation
+}
+```
+
+### Example 2: React Component
+
+```typescript
+/**@voodocs
+preconditions: [
+    "props.items is non-empty array",
+    "props.onSelect is function"
+]
+postconditions: [
+    "renders list with props.items.length elements",
+    "clicking item calls props.onSelect with item"
+]
+assumptions: [
+    "items have unique 'id' property",
+    "items have 'name' property for display"
+]
+complexity: "O(n) where n = props.items.length"
+*/
+function ItemList({ items, onSelect }: ItemListProps) {
+    // Implementation
+}
+```"""
+    
+    def _generate_workflow(self) -> str:
+        """Generate workflow integration section."""
+        return """## Workflow Integration
+
+### When to Add Annotations
+
+Add `@voodocs` annotations in these scenarios:
+
+1. **New Functions** - Annotate immediately after writing the function signature
+2. **New Classes** - Annotate class and all public methods
+3. **API Endpoints** - Always annotate with security and side effects
+4. **Complex Logic** - Annotate algorithms with complexity and invariants
+5. **Security-Critical Code** - Always annotate with security implications
+
+### Annotation Workflow
+
+```
+1. Write function signature
+   ↓
+2. Add @voodocs annotation with preconditions/postconditions
+   ↓
+3. Implement function body
+   ↓
+4. Verify implementation matches postconditions
+   ↓
+5. Run `voodocs generate` to create tests and docs
+```
+
+### Generated Outputs
+
+When you annotate code with `@voodocs`, the following are automatically generated:
+
+1. **Property-Based Tests** - Hypothesis tests with inferred strategies
+2. **Documentation** - Human-readable Markdown docs
+3. **API Specs** - OpenAPI 3.0 or GraphQL schemas
+4. **Type Hints** - Enhanced type information
+
+### Example Generation
+
+Given this annotation:
+
+```python
+\"\"\"@voodocs
+preconditions: ["x > 0", "y > 0"]
+postconditions: ["result > x", "result > y"]
+complexity: "O(1)"
+\"\"\"
+```
+
+VooDocs generates:
+
+```python
+# Generated test
+@given(x=st.integers(min_value=1), y=st.integers(min_value=1))
+def test_property_based_add(x, y):
+    assume(x > 0)
+    assume(y > 0)
+    result = add(x, y)
+    assert result > x
+    assert result > y
+```"""
+    
+    def _generate_best_practices(self) -> str:
+        """Generate best practices section."""
+        return """## Best Practices
+
+### 1. Be Specific with Preconditions
+
+**Good:**
+```python
+preconditions: [
+    "amount > 0",
+    "amount <= account.balance",
+    "account.status = ACTIVE"
+]
+```
+
+**Avoid:**
+```python
+preconditions: ["valid input"]  # Too vague
+```
+
+### 2. Use Mathematical Notation for Precision
+
+**Good:**
+```python
+postconditions: [
+    "∀ x ∈ result: x ∈ input",  # All results are from input
+    "len(result) ≤ len(input)"   # Result is subset
+]
+```
+
+**Avoid:**
+```python
+postconditions: ["returns filtered list"]  # Imprecise
+```
+
+### 3. Always Specify Complexity
+
+**Good:**
+```python
+complexity: "O(n log n)"
+```
+
+**Also Good:**
+```python
+complexity: "O(n)"  # VooDocs infers space as O(1)
+```
+
+### 4. Document Security Implications
+
+**Good:**
+```python
+security_implications: [
+    "Requires admin role",
+    "Rate limited to 100 requests/hour",
+    "Validates CSRF token"
+]
+```
+
+### 5. Specify Error Cases
+
+**Good:**
+```python
+error_cases: [
+    "amount <= 0 → ValueError",
+    "insufficient funds → InsufficientFundsError",
+    "account frozen → AccountFrozenError"
+]
+```
+
+### 6. Use Invariants for Loops and Recursion
+
+**Good:**
+```python
+invariants: [
+    "∀ iteration: 0 <= i < len(arr)",
+    "sorted(arr[0:i])"  # First i elements are sorted
+]
+```
+
+### 7. Document Side Effects
+
+**Good:**
+```python
+side_effects: [
+    "Writes to database",
+    "Sends email notification",
+    "Updates cache"
+]
+```
+
+**Avoid:**
+```python
+side_effects: ["Does stuff"]  # Too vague
+```"""
+    
+    def _generate_footer(self) -> str:
+        """Generate footer section."""
+        return """---
+
+## Summary
+
+**Remember**: Every time you write a function or class, ask yourself:
+
+1. What must be true before this runs? → **preconditions**
+2. What will be true after this runs? → **postconditions**
+3. How fast is this? → **complexity**
+4. What can go wrong? → **error_cases**
+5. Is this security-sensitive? → **security_implications**
+
+By documenting in DarkArts language, you're not just writing comments - you're creating a **formal specification** that generates tests, documentation, and API specs automatically.
+
+**Generated by VooDocs** - AI-native documentation for modern development."""
+    
+    def detect_assistant(self) -> Optional[str]:
+        """
+        Detect which AI assistant is being used based on environment or config files.
+        
+        Returns:
+            Assistant name or None if not detected
+        """
+        # Check for config files in current directory
+        for assistant, info in self.ASSISTANTS.items():
+            config_path = Path(info["config_file"])
+            if config_path.exists():
+                return assistant
+        
+        return None
+    
+    @staticmethod
+    def list_assistants() -> List[Dict[str, str]]:
+        """
+        List all supported AI assistants.
+        
+        Returns:
+            List of assistant info dictionaries
+        """
+        return [
+            {
+                "id": assistant_id,
+                "name": info["name"],
+                "config_file": info["config_file"]
+            }
+            for assistant_id, info in InstructionGenerator.ASSISTANTS.items()
+        ]