@voodocs/cli 0.1.0

package/examples/instructions/.claude/instructions.md

@@ -0,0 +1,372 @@
+# VooDocs Instructions for Claude Code / Cline
+
+**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 (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
+}
+```
+
+## 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: 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
+}
+```
+
+## 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.