@voodocs/cli 2.2.3 → 2.4.0

package/README.md

@@ -91,6 +91,160 @@ def authenticate_user(user_id: str, password: str) -> Optional[str]:
 
 ---
 
+## VooDocs Lite: Ultra-Compact Format
+
+**NEW in v2.4.0!** VooDocs Lite is an ultra-compact symbolic notation that reduces token count by **~30%** while maintaining all semantic information.
+
+### Why VooDocs Lite?
+
+- **Token Efficient**: 27-30% fewer tokens for AI context
+- **More Scannable**: Single-character symbols easier to read
+- **Same Information**: Zero semantic loss
+- **Bidirectional**: Convert between Standard and Lite freely
+
+### Format Comparison
+
+**Standard VooDocs:**
+```typescript
+/**@darkarts
+⊢{User authentication service with JWT token generation}
+∂{bcrypt, jsonwebtoken, database}
+⚠{Users must be stored in database}
+⊳{userId must be a valid UUID, password must be ≥8 characters}
+⊲{Returns JWT token ∨ null}
+⊨{Does ¬ modify database, Password is ¬ logged}
+⚡{O(1)}
+🔒{Password hashed with bcrypt, Token signed with secret}
+*/
+```
+**114 tokens**
+
+**VooDocs Lite:**
+```typescript
+/**@darkarts-lite
+>u auth svc w/ JWT tok gen
+@bcrypt,jsonwebtoken,database
+!us stored in db
+<id valid UUID, pw>=8 characters
+>ret JWT tok|N
+=!mod db, pw !logged
+~O(1)
+#pw hashed w/ bcrypt, tok signed w/ secret
+*/
+```
+**83 tokens** (27% reduction)
+
+### Symbol Mapping
+
+| Standard | Lite | Meaning |
+|----------|------|----------|
+| `⊢{}` | `>` | Purpose |
+| `∂{}` | `@` | Dependencies |
+| `⚠{}` | `!` | Assumptions |
+| `⊳{}` | `<` | Preconditions |
+| `⊲{}` | `>` | Postconditions |
+| `⊨{}` | `=` | Invariants |
+| `⚡{}` | `~` | Complexity |
+| `🔒{}` | `#` | Security |
+
+### Convert Between Formats
+
+```bash
+# Convert Standard to Lite
+voodocs convert src/ --to lite -r
+
+# Convert Lite to Standard
+voodocs convert src/ --to standard -r
+
+# Preview conversion
+voodocs convert src/ --to lite --dry-run
+
+# Modify files in-place
+voodocs convert src/ --to lite --in-place
+```
+
+---
+
+## Companion Files for Compiled Languages
+
+**NEW in v2.3.0!** For compiled languages like Solidity, Rust, or C++ where inline annotations may interfere with compilation, VooDocs supports **companion documentation files**.
+
+### What are Companion Files?
+
+Companion files are `.voodocs.md` files that live alongside your source files, containing rich documentation without modifying the source code.
+
+```
+contracts/
+├── SubdomainRegistry.sol           ← Source code
+├── SubdomainRegistry.voodocs.md    ← Companion documentation
+├── DomainMarketplace.sol           ← Source code
+├── DomainMarketplace.voodocs.md    ← Companion documentation
+```
+
+### Creating Companion Files
+
+Use the `companion` command to generate templates:
+
+```bash
+# Create companion file for a single file
+voodocs companion contracts/Registry.sol
+
+# Create companion files for all Solidity files
+voodocs companion contracts/ -r
+
+# Preview what would be created
+voodocs companion contracts/ -r --dry-run
+```
+
+### Companion File Format
+
+Companion files use Markdown with VooDocs symbolic notation:
+
+```markdown
+# SubdomainRegistry.voodocs.md
+
+## Purpose
+⊢{4-level naming hierarchy with tiered subdomain allocation}
+
+## Architecture
+- **Depends On**: IPricingEngine, IERC721
+- **Depended By**: ThreeNSFacet, DomainMarketplace
+- **Storage**: PostgreSQL (cache), L1 (source of truth)
+
+## Invariants
+⊨{L1 is always the source of truth}
+⊨{Personal names destroyed on subdomain transfer}
+⊨{resolve() must check expiration before returning owner}
+
+## Assumptions
+⊲{Block timestamp is reliable for expiration checks}
+⊲{Gas costs are acceptable for array operations}
+
+## Critical Sections
+- `_burnPersonalNames()` - Must be called before any transfer
+- `resolve()` - Must check expiration before returning owner
+
+## Security Considerations
+⊨{Reentrancy protection on all external calls}
+⊨{Owner validation before subdomain operations}
+```
+
+### Generating Documentation with Companion Files
+
+```bash
+voodocs generate contracts/ docs/ --companion-files
+```
+
+### Benefits
+
+✅ **No Compilation Issues** - Documentation lives in separate files  
+✅ **Rich Markdown** - Use tables, diagrams, code examples, links  
+✅ **Version Control** - Track documentation changes alongside code  
+✅ **IDE Friendly** - View source and docs side-by-side  
+✅ **AI-Ready** - Same context quality as inline annotations
+
+---
+
 ## Symbolic Format Reference
 
 ### Module-Level Annotations
@@ -171,6 +325,29 @@ voodocs fix ./src --dry-run         # Preview changes
 voodocs fix ./src --backup          # Create backups
 ```
 
+### `voodocs companion`
+
+Create companion documentation files for source files:
+
+```bash
+voodocs companion contracts/        # Create for single file
+voodocs companion contracts/ -r     # Recursive
+voodocs companion contracts/ --dry-run  # Preview changes
+voodocs companion contracts/ --force    # Overwrite existing
+```
+
+### `voodocs convert`
+
+Convert between Standard and Lite VooDocs formats:
+
+```bash
+voodocs convert src/ --to lite      # Convert to Lite format
+voodocs convert src/ --to standard  # Convert to Standard format
+voodocs convert src/ --to lite -r   # Recursive conversion
+voodocs convert src/ --to lite --dry-run  # Preview changes
+voodocs convert src/ --to lite --in-place # Modify files in-place
+```
+
 ### `voodocs generate`
 
 Generate documentation from annotations:
@@ -179,6 +356,7 @@ Generate documentation from annotations:
 voodocs generate ./src ./docs       # Generate docs
 voodocs generate ./src ./docs -r    # Recursive
 voodocs generate ./src ./docs --validate  # Validate first
+voodocs generate ./src ./docs --companion-files  # Use companion files
 voodocs generate ./src ./docs --format json  # JSON output
 ```
 

package/USAGE.md

@@ -13,6 +13,7 @@ This guide provides a comprehensive overview of VooDocs, its commands, and best
 - [CLI Commands](#cli-commands)
   - [init](#init)
   - [instruct](#instruct)
+  - [companion](#companion)
   - [generate](#generate)
   - [status](#status)
   - [watch](#watch)
@@ -98,13 +99,81 @@ voodocs instruct [--assistant <name>] [--output <file>]
 - `--assistant`: The AI assistant to generate instructions for (`cursor`, `claude`, `copilot`, `windsurf`, `generic`).
 - `--output`: The output file path (defaults to `.cursorrules`, `.claude/instructions.md`, etc.).
 
+### `companion`
+
+**NEW in v2.3.0!** Create companion documentation files (`.voodocs.md`) for source files. Useful for compiled languages like Solidity, Rust, or C++ where inline annotations may interfere with compilation.
+
+**Usage**:
+```bash
+voodocs companion <source> [options]
+```
+
+**Arguments**:
+- `<source>`: Source file or directory to create companion files for.
+
+**Options**:
+- `-r, --recursive`: Recursively process all files in subdirectories.
+- `--force`: Overwrite existing companion files.
+- `--dry-run`: Show what would be created without creating files.
+
+**Examples**:
+```bash
+# Create companion file for a single Solidity contract
+voodocs companion contracts/Registry.sol
+
+# Create companion files for all Solidity contracts
+voodocs companion contracts/ -r
+
+# Preview what would be created
+voodocs companion contracts/ -r --dry-run
+
+# Force overwrite existing companion files
+voodocs companion contracts/ -r --force
+```
+
+**Companion File Format**:
+
+Companion files use Markdown with structured sections:
+
+```markdown
+# FileName.voodocs.md
+
+## Purpose
+⊢{Module purpose description}
+
+## Architecture
+- **Depends On**: Dependency1, Dependency2
+- **Depended By**: Parent1, Parent2
+- **Storage**: Storage information
+
+## Invariants
+⊨{Invariant 1}
+⊨{Invariant 2}
+
+## Assumptions
+⊲{Assumption 1}
+
+## Critical Sections
+- `functionName()` - Description
+
+## Security Considerations
+⊨{Security requirement}
+```
+
+**Benefits**:
+- ✅ No compilation interference
+- ✅ Rich Markdown formatting (tables, diagrams, links)
+- ✅ Version control alongside source files
+- ✅ IDE-friendly (side-by-side viewing)
+- ✅ Same AI context quality as inline annotations
+
 ### `generate`
 
 Generate docs, tests, and API specs from annotations.
 
 **Usage**:
 ```bash
-voodocs generate <path> [--output <dir>] [--docs-only] [--tests-only] [--api-only] [--verbose]
+voodocs generate <path> [--output <dir>] [--docs-only] [--tests-only] [--api-only] [--companion-files] [--verbose]
 ```
 
 **Arguments**:
@@ -113,8 +182,21 @@ voodocs generate <path> [--output <dir>] [--docs-only] [--tests-only] [--api-onl
 - `--docs-only`: Generate only documentation.
 - `--tests-only`: Generate only tests.
 - `--api-only`: Generate only API specs.
+- `--companion-files`: **NEW in v2.3.0!** Scan for and use `.voodocs.md` companion files alongside source files.
 - `--verbose`: Show detailed output.
 
+**Examples**:
+```bash
+# Generate documentation from inline annotations
+voodocs generate src/ docs/
+
+# Generate documentation using companion files (for Solidity, Rust, etc.)
+voodocs generate contracts/ docs/ --companion-files
+
+# Generate with validation
+voodocs generate src/ docs/ --validate
+```
+
 ### `status`
 
 Show project status and statistics.
@@ -318,7 +400,61 @@ class BankAccount:
         self.balance += amount
 ```
 
-See the `examples/` directory for more complete examples in Python and TypeScript.
+### Solidity Contract with Companion File
+
+**NEW in v2.3.0!** For compiled languages, use companion files:
+
+**contracts/SubdomainRegistry.sol**:
+```solidity
+// SPDX-License-Identifier: MIT
+pragma solidity ^0.8.0;
+
+contract SubdomainRegistry {
+    mapping(uint256 => address) public owners;
+    mapping(uint256 => uint256) public expirations;
+    
+    function register(uint256 nameId, address owner, uint256 duration) public {
+        require(owners[nameId] == address(0), "Already registered");
+        owners[nameId] = owner;
+        expirations[nameId] = block.timestamp + duration;
+    }
+    
+    function resolve(uint256 nameId) public view returns (address) {
+        require(block.timestamp < expirations[nameId], "Expired");
+        return owners[nameId];
+    }
+}
+```
+
+**contracts/SubdomainRegistry.voodocs.md**:
+```markdown
+# SubdomainRegistry.voodocs.md
+
+## Purpose
+⊢{Subdomain registry with expiration management}
+
+## Invariants
+⊨{Only one owner per subdomain}
+⊨{resolve() must check expiration before returning owner}
+⊨{Expired subdomains cannot be resolved}
+
+## Assumptions
+⊲{Block timestamp is reliable for expiration checks}
+⊲{nameId is unique and generated off-chain}
+
+## Security Considerations
+⊨{Owner validation before subdomain operations}
+⊨{Zero address checks for all owner parameters}
+⊨{Expiration checks prevent stale data}
+```
+
+**Generate documentation**:
+```bash
+voodocs companion contracts/ -r
+voodocs generate contracts/ docs/ --companion-files
+```
+
+See the `examples/` directory for more complete examples in Python, TypeScript, and Solidity.
 
 ---
 

package/lib/cli/companion.py

@@ -0,0 +1,137 @@
+"""
+⊢cli:companion
+∂{click,pathlib,typing}
+⚠{python≥3.7,click≥8.0}
+⊨{∀template→valid_markdown}
+🔒{write:files}
+⚡{O(n)|n=files}
+"""
+
+"""
+VooDocs CLI - Companion Command
+
+Creates .voodocs.md companion files for source files.
+"""
+
+import sys
+import click
+from pathlib import Path
+from typing import List
+
+sys.path.insert(0, str(Path(__file__).parent.parent))
+from darkarts.companion_files import CompanionFileScanner
+
+
+@click.command()
+@click.argument('source', type=click.Path(exists=True), required=True)
+@click.option('-r', '--recursive', is_flag=True, help='Recursively process all files')
+@click.option('--force', is_flag=True, help='Overwrite existing companion files')
+@click.option('--dry-run', is_flag=True, help='Show what would be created without creating files')
+def companion(
+    source: str,
+    recursive: bool,
+    force: bool,
+    dry_run: bool
+):
+    """
+    Create .voodocs.md companion files for source files.
+    
+    Companion files allow you to add rich documentation alongside source files
+    without modifying the source code. This is especially useful for compiled
+    languages like Solidity where inline annotations may interfere with compilation.
+    
+    Examples:
+    
+        # Create companion file for a single file
+        voodocs companion contracts/Registry.sol
+        
+        # Create companion files for all Solidity files
+        voodocs companion contracts/ -r
+        
+        # Preview what would be created
+        voodocs companion contracts/ -r --dry-run
+        
+        # Overwrite existing companion files
+        voodocs companion contracts/ -r --force
+    """
+    
+    source_path = Path(source)
+    
+    # Collect source files
+    files_to_process: List[Path] = []
+    
+    if source_path.is_file():
+        files_to_process = [source_path]
+    elif source_path.is_dir():
+        extensions = ['*.py', '*.ts', '*.js', '*.jsx', '*.tsx', '*.sol']
+        
+        if recursive:
+            for ext in extensions:
+                files_to_process.extend([f for f in source_path.glob(f"**/{ext}") if f.is_file()])
+        else:
+            for ext in extensions:
+                files_to_process.extend([f for f in source_path.glob(ext) if f.is_file()])
+    
+    if not files_to_process:
+        click.secho("No source files found.", fg='yellow')
+        sys.exit(1)
+    
+    click.echo(f"Found {len(files_to_process)} source file(s)")
+    click.echo()
+    
+    if dry_run:
+        click.secho("DRY RUN MODE - No files will be created", fg='cyan')
+        click.echo()
+    
+    created_count = 0
+    skipped_count = 0
+    
+    for file_path in files_to_process:
+        companion_path = file_path.parent / f"{file_path.stem}{CompanionFileScanner.COMPANION_EXTENSION}"
+        
+        if companion_path.exists() and not force:
+            click.echo(f"⏭️  {file_path.name} (companion already exists)")
+            skipped_count += 1
+            continue
+        
+        if dry_run:
+            if companion_path.exists():
+                click.echo(f"🔄 {file_path.name} → {companion_path.name} (would overwrite)")
+            else:
+                click.echo(f"✨ {file_path.name} → {companion_path.name} (would create)")
+            created_count += 1
+        else:
+            template = CompanionFileScanner.create_template(file_path)
+            companion_path.write_text(template, encoding='utf-8')
+            
+            if force and companion_path.exists():
+                click.echo(f"🔄 {file_path.name} → {companion_path.name} (overwritten)")
+            else:
+                click.echo(f"✨ {file_path.name} → {companion_path.name}")
+            
+            created_count += 1
+    
+    click.echo()
+    click.echo("━" * 60)
+    
+    if dry_run:
+        click.echo(f"Would create: {created_count}")
+        click.echo(f"Would skip: {skipped_count}")
+    else:
+        click.secho(f"Created: {created_count}", fg='green')
+        click.echo(f"Skipped: {skipped_count}")
+    
+    click.echo("━" * 60)
+    
+    if not dry_run and created_count > 0:
+        click.echo()
+        click.secho("✅ Companion files created!", fg='green')
+        click.echo()
+        click.echo("Next steps:")
+        click.echo("  1. Edit the .voodocs.md files to add documentation")
+        click.echo("  2. Run: voodocs generate --companion-files")
+        click.echo()
+        click.echo("Tip: Companion files support:")
+        click.echo("  • Rich Markdown formatting (tables, diagrams, links)")
+        click.echo("  • VooDocs symbolic notation (⊢{}, ⊨{}, ⊲{})")
+        click.echo("  • Version control alongside source files")

package/lib/cli/generate.py

@@ -33,6 +33,7 @@ from darkarts.validation.performance_wrapper import PerformanceTracker
 @click.option('--strict', is_flag=True, help='Fail if validation fails')
 @click.option('--format', type=click.Choice(['markdown', 'html', 'json']), default='markdown', help='Output format')
 @click.option('--include-private', is_flag=True, help='Include private members in documentation')
+@click.option('--companion-files', is_flag=True, help='Scan for .voodocs.md companion files alongside source files')
 def generate(
     source: str,
     output: str,
@@ -40,7 +41,8 @@ def generate(
     validate: bool,
     strict: bool,
     format: str,
-    include_private: bool
+    include_private: bool,
+    companion_files: bool
 ):
     """
     Generate documentation from @darkarts annotations.
@@ -132,6 +134,29 @@ def generate(
     
     click.echo(f"Found {len(files_to_process)} files to process")
     
+    # Scan for companion files if requested
+    companion_mapping = {}
+    if companion_files:
+        click.echo()
+        click.secho("Scanning for companion files (.voodocs.md)...", fg='cyan')
+        from darkarts.companion_files import CompanionFileScanner
+        
+        companion_count = 0
+        for file_path in files_to_process:
+            companion = CompanionFileScanner.find_companion_file(file_path)
+            if companion:
+                companion_mapping[file_path] = companion
+                companion_count += 1
+                click.echo(f"  📄 {file_path.name} → {companion.name}")
+        
+        click.echo()
+        if companion_count > 0:
+            click.secho(f"✅ Found {companion_count} companion file(s)", fg='green')
+        else:
+            click.secho("⚠️  No companion files found", fg='yellow')
+            click.echo("   Tip: Create .voodocs.md files alongside your source files")
+            click.echo("   Example: contracts/Registry.sol → contracts/Registry.voodocs.md")
+    
     # Validate if requested
     if validate:
         click.echo()
@@ -179,8 +204,14 @@ def generate(
     generated_files = []
     for file_path in files_to_process:
         try:
+            # Parse companion file if available
+            companion_data = None
+            if companion_files and file_path in companion_mapping:
+                from darkarts.companion_files import CompanionFileScanner
+                companion_data = CompanionFileScanner.parse_companion_file(companion_mapping[file_path])
+            
             # Generate documentation for this file
-            doc_content = _generate_doc_for_file(file_path, format, include_private)
+            doc_content = _generate_doc_for_file(file_path, format, include_private, companion_data)
             
             # Determine output filename
             if source_path.is_dir():
@@ -291,7 +322,7 @@ def generate(
         sys.exit(1)
 
 
-def _generate_doc_for_file(file_path: Path, format: str, include_private: bool) -> str:
+def _generate_doc_for_file(file_path: Path, format: str, include_private: bool, companion_data: dict = None) -> str:
     """Generate documentation for a single file."""
     content = file_path.read_text(encoding='utf-8')
     
@@ -309,6 +340,25 @@ def _generate_doc_for_file(file_path: Path, format: str, include_private: bool)
     security = _extract_section(annotation, '🔒')
     performance = _extract_section(annotation, '⚡')
     
+    # Merge with companion file data if available
+    if companion_data:
+        if companion_data.get('purpose'):
+            module_id = companion_data['purpose']
+        if companion_data.get('dependencies'):
+            dependencies = ', '.join(companion_data['dependencies'])
+        if companion_data.get('invariants'):
+            inv_list = invariants.split('\n') if invariants else []
+            inv_list.extend(companion_data['invariants'])
+            invariants = '\n'.join(filter(None, inv_list))
+        if companion_data.get('assumptions'):
+            assume_list = assumptions.split('\n') if assumptions else []
+            assume_list.extend(companion_data['assumptions'])
+            assumptions = '\n'.join(filter(None, assume_list))
+        if companion_data.get('security'):
+            sec_list = security.split('\n') if security else []
+            sec_list.extend(companion_data['security'])
+            security = '\n'.join(filter(None, sec_list))
+    
     # Generate documentation based on format
     if format == 'markdown':
         return _generate_markdown(file_path, module_id, dependencies, assumptions, invariants, security, performance)