@voodocs/cli 0.1.0

package/examples/instructions/.cursorrules

@@ -0,0 +1,437 @@
+# VooDocs Instructions for Cursor
+
+**Project**: VooDocs Example Project  
+**Generated**: Automatically by VooDocs  
+**Purpose**: Guide AI assistants to document code using @voodocs annotations
+
+---
+
+## 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.
+
+## 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
+
+## 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
+```
+
+## 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"` |
+
+## 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.
+
+## 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
+```
+
+## 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
+```
+
+## 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
+```
+
+---
+
+## 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.