@voodocs/cli 2.1.3 → 2.2.1

package/examples/instructions/VOODOCS_INSTRUCTIONS.md

@@ -1,16 +1,17 @@
-# VooDocs Instructions for Generic AI Assistant
+# Voodocs Instructions for Generic AI Assistant
 
-**Project**: VooDocs Example Project  
-**Generated**: Automatically by VooDocs  
+**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.
+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
@@ -22,7 +23,7 @@ As an AI coding assistant, you should add `@voodocs` annotations to **every sign
 
 ## Core Principles
 
-When writing code with VooDocs annotations, follow these 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
@@ -61,33 +62,33 @@ class ClassName:
 
 ### 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"]` |
+| 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"` |
+| 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"` |
+| 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
 
@@ -95,49 +96,49 @@ DarkArts is a mathematical notation language for precise specifications. Use the
 
 ### 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` |
+| 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` |
+| 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` |
+| 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` |
+| 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 ∈ ℝ` |
+| 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.
+**Tip**: You can use plain English too! Voodocs understands both mathematical notation and natural language. Mix them for clarity.
 
 ## Examples
 
@@ -167,7 +168,7 @@ def calculate_discount(price: float, discount_percent: float) -> float:
         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)
 ```
 
@@ -219,12 +220,12 @@ class BankAccount:
     ]
     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: [
@@ -314,7 +315,7 @@ complexity: "O(1)"
 """
 ```
 
-VooDocs generates:
+Voodocs generates:
 
 ```python
 # Generated test
@@ -332,6 +333,7 @@ def test_property_based_add(x, y):
 ### 1. Be Specific with Preconditions
 
 **Good:**
+
 ```python
 preconditions: [
     "amount > 0",
@@ -341,6 +343,7 @@ preconditions: [
 ```
 
 **Avoid:**
+
 ```python
 preconditions: ["valid input"]  # Too vague
 ```
@@ -348,6 +351,7 @@ preconditions: ["valid input"]  # Too vague
 ### 2. Use Mathematical Notation for Precision
 
 **Good:**
+
 ```python
 postconditions: [
     "∀ x ∈ result: x ∈ input",  # All results are from input
@@ -356,6 +360,7 @@ postconditions: [
 ```
 
 **Avoid:**
+
 ```python
 postconditions: ["returns filtered list"]  # Imprecise
 ```
@@ -363,18 +368,21 @@ 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)
+complexity: "O(n)"  # Voodocs infers space as O(1)
 ```
 
 ### 4. Document Security Implications
 
 **Good:**
+
 ```python
 security_implications: [
     "Requires admin role",
@@ -386,6 +394,7 @@ security_implications: [
 ### 5. Specify Error Cases
 
 **Good:**
+
 ```python
 error_cases: [
     "amount <= 0 → ValueError",
@@ -397,6 +406,7 @@ error_cases: [
 ### 6. Use Invariants for Loops and Recursion
 
 **Good:**
+
 ```python
 invariants: [
     "∀ iteration: 0 <= i < len(arr)",
@@ -407,6 +417,7 @@ invariants: [
 ### 7. Document Side Effects
 
 **Good:**
+
 ```python
 side_effects: [
     "Writes to database",
@@ -416,6 +427,7 @@ side_effects: [
 ```
 
 **Avoid:**
+
 ```python
 side_effects: ["Does stuff"]  # Too vague
 ```
@@ -434,4 +446,4 @@ side_effects: ["Does stuff"]  # Too vague
 
 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.
+**Generated by Voodocs** - AI-native documentation for modern development.

package/examples/math_example.py

@@ -1,5 +1,5 @@
 """
-Example module demonstrating VooDocs annotations and generated tests.
+Example module demonstrating Voodocs annotations and generated tests.
 """
 
 def add_positive(x: int, y: int) -> int:

package/examples/phase2_test.py

@@ -1,5 +1,5 @@
 """
-Test file for VooDocs Phase 2 improvements.
+Test file for Voodocs Phase 2 improvements.
 """
 
 def fully_annotated_function(a: int, b: int) -> int:

package/examples/test_function_invariants.py

@@ -1,5 +1,5 @@
 """
-Example demonstrating function-level invariants in VooDocs.
+Example demonstrating function-level invariants in Voodocs.
 
 This file shows how to use invariants at the function level to document
 properties that must hold throughout the function's execution.

package/lib/cli/__init__.py

@@ -8,9 +8,9 @@
 """
 
 """
-VooDocs CLI - Main entry point
+Voodocs CLI - Main entry point
 
-This module provides the command-line interface for VooDocs.
+This module provides the command-line interface for Voodocs.
 """
 
 import click
@@ -24,7 +24,7 @@ __version__ = "2.1.3"
 @click.pass_context
 def cli(ctx):
     """
-    VooDocs - AI-Native Symbolic Documentation System
+    Voodocs - AI-Native Symbolic Documentation System
     
     Generate and validate @darkarts symbolic annotations in your codebase.
     

package/lib/cli/benchmark.py

@@ -8,7 +8,7 @@
 """
 
 """
-VooDocs CLI - Benchmark Command
+Voodocs CLI - Benchmark Command
 
 Runs performance benchmarks to validate complexity claims in @darkarts annotations.
 """
@@ -222,7 +222,7 @@ def _generate_html_report(results: Dict[str, Any]) -> str:
     html = f"""<!DOCTYPE html>
 <html>
 <head>
-    <title>VooDocs Benchmark Report</title>
+    <title>Voodocs Benchmark Report</title>
     <style>
         body {{ font-family: Arial, sans-serif; margin: 40px; background: #f5f5f5; }}
         .container {{ max-width: 1200px; margin: 0 auto; background: white; padding: 30px; border-radius: 8px; box-shadow: 0 2px 4px rgba(0,0,0,0.1); }}
@@ -242,7 +242,7 @@ def _generate_html_report(results: Dict[str, Any]) -> str:
 </head>
 <body>
     <div class="container">
-        <h1>📊 VooDocs Benchmark Report</h1>
+        <h1>📊 Voodocs Benchmark Report</h1>
         
         <div class="summary">
             <div class="metric">

package/lib/cli/context.py

@@ -8,7 +8,7 @@
 """
 
 """
-VooDocs CLI - Context Command
+Voodocs CLI - Context Command
 
 Manages AI context files generated from @darkarts annotations.
 """

package/lib/cli/fix.py

@@ -8,7 +8,7 @@
 """
 
 """
-VooDocs CLI - Fix Command
+Voodocs CLI - Fix Command
 
 Automatically fixes validation issues in @darkarts annotations.
 """

package/lib/cli/generate.py

@@ -8,7 +8,7 @@
 """
 
 """
-VooDocs CLI - Generate Command
+Voodocs CLI - Generate Command
 
 Generates documentation from @darkarts annotations.
 """
@@ -202,6 +202,65 @@ def generate(
         except Exception as e:
             click.secho(f"❌ {file_path}: {e}", fg='red')
     
+    # Generate consolidated documentation
+    click.echo()
+    click.secho("📚 Generating consolidated documentation...", fg='cyan')
+    try:
+        from darkarts.documentation import DocumentationConsolidator, DocumentedItem, AnnotationCategorizer
+        
+        consolidator = DocumentationConsolidator(
+            project_name=config.get('project', {}).get('name', 'Project') if config else 'Project'
+        )
+        
+        # Add all processed files to consolidator
+        for file_path in files_to_process:
+            try:
+                content = file_path.read_text(encoding='utf-8')
+                annotation = _extract_annotation(content)
+                
+                if annotation:
+                    # Parse annotations
+                    annotations_dict = {
+                        'module_id': _extract_section(annotation, '⊢'),
+                        'dependencies': _extract_section(annotation, '∂'),
+                        'assumptions': _extract_section(annotation, '⚠'),
+                        'invariants': _extract_section(annotation, '⊨'),
+                        'security': _extract_section(annotation, '🔒'),
+                        'complexity': _extract_section(annotation, '⚡'),
+                    }
+                    
+                    # Create documented item
+                    item = DocumentedItem(
+                        name=AnnotationCategorizer.extract_name(str(file_path)),
+                        file_path=str(file_path.relative_to(source_path)),
+                        item_type=AnnotationCategorizer.detect_type(str(file_path), annotations_dict),
+                        content=_generate_doc_for_file(file_path, 'markdown', include_private),
+                        annotations=annotations_dict,
+                    )
+                    
+                    # Detect categories
+                    item.domains = AnnotationCategorizer.detect_domains(str(file_path), annotations_dict)
+                    item.concerns = AnnotationCategorizer.detect_concerns(annotations_dict)
+                    item.layers = AnnotationCategorizer.detect_layers(str(file_path), annotations_dict)
+                    
+                    consolidator.add_item(item)
+            except Exception as e:
+                click.secho(f"  ⚠️  Failed to consolidate {file_path}: {e}", fg='yellow')
+        
+        # Generate all consolidated docs
+        consolidated_docs = consolidator.generate_all()
+        
+        # Write consolidated docs
+        for doc_path, doc_content in consolidated_docs.items():
+            full_path = output_path / doc_path
+            full_path.parent.mkdir(parents=True, exist_ok=True)
+            full_path.write_text(doc_content, encoding='utf-8')
+            click.echo(f"  ✓ {doc_path}")
+        
+        click.secho(f"  ✓ Generated {len(consolidated_docs)} consolidated documents", fg='green')
+    except Exception as e:
+        click.secho(f"  ⚠️  Consolidated documentation failed: {e}", fg='yellow')
+    
     # Summary
     click.echo()
     click.echo("━" * 60)

package/lib/cli/init.py

@@ -8,9 +8,9 @@
 """
 
 """
-VooDocs Init Command
+Voodocs Init Command
 
-Interactive wizard to initialize or upgrade a project with VooDocs.
+Interactive wizard to initialize or upgrade a project with Voodocs.
 Re-runnable to add missing features after upgrades.
 """
 
@@ -35,7 +35,7 @@ from typing import Optional, Dict, Any
 )
 def init(non_interactive, upgrade):
     """
-    Initialize or upgrade a project with VooDocs.
+    Initialize or upgrade a project with Voodocs.
     
     This interactive wizard will:
     - Set up your project configuration
@@ -70,14 +70,14 @@ def init(non_interactive, upgrade):
     click.echo()
     if is_upgrade:
         click.echo(click.style('╔══════════════════════════════════════════╗', fg='yellow', bold=True))
-        click.echo(click.style('║   🔄 VooDocs Upgrade Wizard             ║', fg='yellow', bold=True))
+        click.echo(click.style('║   🔄 Voodocs Upgrade Wizard             ║', fg='yellow', bold=True))
         click.echo(click.style('╚══════════════════════════════════════════╝', fg='yellow', bold=True))
         click.echo()
         click.echo(click.style('Existing configuration detected!', fg='yellow'))
         click.echo('This wizard will help you add any missing features.')
     else:
         click.echo(click.style('╔══════════════════════════════════════════╗', fg='cyan', bold=True))
-        click.echo(click.style('║   🎉 Welcome to VooDocs Setup Wizard   ║', fg='cyan', bold=True))
+        click.echo(click.style('║   🎉 Welcome to Voodocs Setup Wizard   ║', fg='cyan', bold=True))
         click.echo(click.style('╚══════════════════════════════════════════╝', fg='cyan', bold=True))
     click.echo()
     
@@ -361,11 +361,11 @@ def init(non_interactive, upgrade):
     click.echo()
     if is_upgrade:
         click.echo(click.style('╔══════════════════════════════════════════╗', fg='green', bold=True))
-        click.echo(click.style('║   ✅ VooDocs Upgrade Complete!         ║', fg='green', bold=True))
+        click.echo(click.style('║   ✅ Voodocs Upgrade Complete!         ║', fg='green', bold=True))
         click.echo(click.style('╚══════════════════════════════════════════╝', fg='green', bold=True))
     else:
         click.echo(click.style('╔══════════════════════════════════════════╗', fg='green', bold=True))
-        click.echo(click.style('║   🎉 VooDocs Setup Complete!           ║', fg='green', bold=True))
+        click.echo(click.style('║   🎉 Voodocs Setup Complete!           ║', fg='green', bold=True))
         click.echo(click.style('╚══════════════════════════════════════════╝', fg='green', bold=True))
     click.echo()
     click.echo(click.style('Next steps:', fg='cyan', bold=True))
@@ -532,7 +532,7 @@ def _add_to_gitignore(cwd: Path, entry: str):
     
     if content and not content.endswith('\n'):
         content += '\n'
-    content += f'\n# VooDocs\n{entry}\n'
+    content += f'\n# Voodocs\n{entry}\n'
     
     gitignore.write_text(content)
 
@@ -648,10 +648,10 @@ def _install_git_hooks(cwd: Path):
     pre_commit_hook = hooks_dir / 'pre-commit'
     
     hook_content = '''#!/bin/sh
-# VooDocs auto-update hook
+# Voodocs auto-update hook
 # Updates context files before commit
 
-echo "🔄 Updating VooDocs context..."
+echo "🔄 Updating Voodocs context..."
 voodocs generate --quiet 2>&1 || true
 git add context/
 

package/lib/cli/instruct.py

@@ -8,7 +8,7 @@
 """
 
 """
-VooDocs Instruct Command
+Voodocs Instruct Command
 
 Generate AI-specific instructions for writing @darkarts annotations.
 """

package/lib/cli/validate.py

@@ -8,7 +8,7 @@
 """
 
 """
-VooDocs CLI - Validate Command
+Voodocs CLI - Validate Command
 
 Validates @darkarts annotations in Python files.
 """
@@ -309,7 +309,7 @@ def display_html_results(
 <!DOCTYPE html>
 <html>
 <head>
-    <title>VooDocs Validation Report</title>
+    <title>Voodocs Validation Report</title>
     <style>
         body { font-family: Arial, sans-serif; margin: 20px; }
         h1 { color: #333; }
@@ -319,7 +319,7 @@ def display_html_results(
     </style>
 </head>
 <body>
-    <h1>VooDocs Validation Report</h1>
+    <h1>Voodocs Validation Report</h1>
     
     <h2>Semantic Validation</h2>
 """