@voodocs/cli 1.0.2 → 1.0.4

package/CHANGELOG.md

@@ -1,3 +1,184 @@
+## v1.0.4 (2024-12-21)
+
+### 🐛 Critical Bug Fixes: Documentation Generation
+
+This release fixes critical bugs that prevented documentation generation for TypeScript, JavaScript, and Solidity files.
+
+---
+
+### Fixed
+
+#### Issue 1: Annotation Parsing Failure
+**Problem:** The generator failed to recognize valid `@voodocs` or `@darkarts` annotations in TypeScript/JavaScript files.
+
+**Root Cause:** The `_extract_annotation` function only looked for Python docstring format (`"""@darkarts`), not TypeScript/JavaScript block comments (`/**@voodocs` or `/**@darkarts`).
+
+**Fix:**
+- Added regex pattern matching for TypeScript/JavaScript block comments
+- Support both `/**@voodocs` and `/**@darkarts` tags
+- Support both Python (`"""`) and JS/TS (`/**`) comment styles
+
+#### Issue 2: File Discovery Limitations
+**Problem:** When running `voodocs generate . ./docs` in a directory, the tool reported "No Python files found to process" even when TypeScript or Solidity files were present.
+
+**Root Cause:** The file discovery logic only looked for `.py` files.
+
+**Fix:**
+- Extended file discovery to include: `.py`, `.ts`, `.js`, `.jsx`, `.tsx`, `.sol`
+- Updated error message to list all supported extensions
+
+#### Issue 3: Natural Language Format Parsing
+**Problem:** YAML-style annotations (e.g., `module_purpose: "..."`, `dependencies: []`) were not being parsed correctly.
+
+**Fix:**
+- Added support for natural language format alongside symbolic format
+- Properly handle YAML-style lists with `-` markers
+- Clean up formatting and remove trailing comment markers
+
+---
+
+### Improvements
+
+- **Multi-language Support:** Now works with TypeScript, JavaScript, Solidity, and Python
+- **Dual Format Support:** Accepts both natural language (`module_purpose:`) and symbolic (`⊢{}`) formats
+- **Better Error Messages:** Clear indication of supported file extensions
+
+---
+
+### Testing
+
+All reported issues have been tested and verified:
+
+| Test Case | Status |
+|-----------|--------|
+| TypeScript file with `/**@voodocs` | ✅ Pass |
+| TypeScript file with `/**@darkarts` | ✅ Pass |
+| Natural language format | ✅ Pass |
+| Symbolic format | ✅ Pass |
+| Directory discovery (`.ts` files) | ✅ Pass |
+| Multiple files in directory | ✅ Pass |
+
+---
+
+### Example: Now Working
+
+**File: test.ts**
+```typescript
+/**@voodocs
+module_purpose: Test module
+dependencies: []
+assumptions:
+  - Node.js environment
+*/
+export function hello(name: string): string {
+  return `Hello, ${name}`;
+}
+```
+
+**Command:**
+```bash
+voodocs generate ./test.ts ./docs
+```
+
+**Result:**
+```markdown
+# test.ts
+
+**Module:** `Test module`
+
+## Assumptions
+
+Node.js environment
+```
+
+---
+
+### Upgrade Notes
+
+No breaking changes. Simply upgrade:
+```bash
+npm install -g @voodocs/cli@1.0.4
+```
+
+All existing annotations continue to work. This release only adds support for previously unsupported file types and formats.
+
+## v1.0.3 (2024-12-21)
+
+### ✨ New Feature: AI Instruction Generation
+
+This release adds the `voodocs instruct` command to automatically generate AI-specific instructions for writing symbolic DarkArts annotations.
+
+---
+
+### Added
+
+#### `voodocs instruct` Command
+- **Auto-detects AI environment** (Cursor, Claude, Gemini, etc.)
+- **Generates tailored instructions** for each AI assistant
+- **Supports multiple output formats** (console or file)
+- **Lists available templates** with `--list-templates` flag
+
+**Usage:**
+```bash
+voodocs instruct                    # Auto-detect and print instructions
+voodocs instruct --ai cursor        # Generate for specific AI
+voodocs instruct --output .cursorrules  # Save to file
+voodocs instruct --list-templates   # List available templates
+```
+
+#### Updated Instruction Templates
+- **Symbolic DarkArts format** - All templates updated to use symbolic annotations
+- **Cursor template** - Tailored for Cursor AI
+- **Claude template** - Tailored for Claude AI
+- **Default template** - Generic instructions for any AI
+
+---
+
+### Improved
+
+- **AI Instructions** - Now guide AIs to write symbolic `@darkarts` annotations instead of natural language `@voodocs`
+- **Documentation** - Added comprehensive AI instruction guide
+
+---
+
+### What This Means
+
+With `voodocs instruct`, you can now:
+1. Run the command in your project
+2. Get AI-specific instructions
+3. Add them to your `.cursorrules` or Claude project settings
+4. Have your AI assistant automatically write correct symbolic annotations
+
+---
+
+### Example Workflow
+
+```bash
+# Initialize project
+voodocs init
+
+# Generate AI instructions
+voodocs instruct --output .cursorrules
+
+# Now your AI will automatically write symbolic annotations!
+# When you write code, your AI adds:
+/**@darkarts
+⊳{userId must be a valid UUID}
+⊲{Returns user object or null}
+⊨{Does ¬ modify database}
+⚡{O(1)}
+*/
+```
+
+---
+
+### Upgrade Notes
+
+No breaking changes. Simply upgrade:
+```bash
+npm install -g @voodocs/cli@1.0.3
+```
+
 ## v1.0.2 (2024-12-21)
 
 ### 🔧 Critical Bug Fixes

package/lib/cli/__init__.py

@@ -16,7 +16,7 @@ This module provides the command-line interface for VooDocs.
 import click
 from typing import Optional
 
-__version__ = "1.0.2"
+__version__ = "1.0.4"
 
 
 @click.group()
@@ -35,6 +35,7 @@ def cli(ctx):
 
 # Import subcommands
 from .init import init
+from .instruct import instruct
 from .validate import validate
 from .generate import generate
 from .benchmark import benchmark
@@ -42,6 +43,7 @@ from .fix import fix
 
 # Register commands
 cli.add_command(init)
+cli.add_command(instruct)
 cli.add_command(validate)
 cli.add_command(generate)
 cli.add_command(benchmark)

package/lib/cli/generate.py

@@ -78,11 +78,19 @@ def generate(
     if source_path.is_file():
         files_to_process = [source_path]
     elif source_path.is_dir():
-        pattern = "**/*.py" if recursive else "*.py"
-        files_to_process = [f for f in source_path.glob(pattern) if f.is_file()]
+        # Support multiple file extensions
+        extensions = ['*.py', '*.ts', '*.js', '*.jsx', '*.tsx', '*.sol']
+        files_to_process = []
+        
+        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 Python files found to process.", fg='yellow')
+        click.secho("No files found to process. Supported extensions: .py, .ts, .js, .jsx, .tsx, .sol", fg='yellow')
         sys.exit(1)
     
     click.echo(f"Found {len(files_to_process)} files to process")
@@ -214,20 +222,58 @@ def _generate_doc_for_file(file_path: Path, format: str, include_private: bool)
 
 
 def _extract_annotation(content: str) -> str:
-    """Extract @darkarts annotation from file content."""
-    if '"""@darkarts' in content:
-        start = content.index('"""@darkarts')
-        end = content.index('"""', start + 3) + 3
-        return content[start:end]
+    """Extract @darkarts or @voodocs annotation from file content."""
+    import re
+    
+    # Try Python docstring format first ("""@darkarts or """@voodocs)
+    python_pattern = r'"""@(?:darkarts|voodocs)\s*(.*?)"""'
+    match = re.search(python_pattern, content, re.DOTALL)
+    if match:
+        return match.group(0)
+    
+    # Try TypeScript/JavaScript block comment format (/**@darkarts or /**@voodocs)
+    js_pattern = r'/\*\*@(?:darkarts|voodocs)\s*(.*?)\*/'
+    match = re.search(js_pattern, content, re.DOTALL)
+    if match:
+        return match.group(0)
+    
     return ""
 
 
 def _extract_section(annotation: str, symbol: str) -> str:
-    """Extract a specific section from annotation."""
+    """Extract a specific section from annotation (supports both symbolic and natural language)."""
+    import re
+    
+    # Map symbols to natural language keys
+    symbol_to_key = {
+        '⊢': 'module_purpose',
+        '∂': 'dependencies',
+        '⚠': 'assumptions',
+        '⊨': 'invariants',
+        '🔒': 'security',
+        '⚡': 'complexity'
+    }
+    
+    # Try symbolic format first
     lines = annotation.split('\n')
     for line in lines:
         if line.strip().startswith(symbol):
             return line.strip()[len(symbol):].strip('{}')
+    
+    # Try natural language format
+    key = symbol_to_key.get(symbol)
+    if key:
+        # Match key: value or key: [list]
+        pattern = rf'{key}\s*:\s*(.+?)(?=\n[a-z_]+\s*:|\*/|$)'
+        match = re.search(pattern, annotation, re.DOTALL | re.IGNORECASE)
+        if match:
+            value = match.group(1).strip()
+            # Clean up list formatting and remove trailing comment markers
+            value = value.strip('[]').strip()
+            # Remove YAML list markers and join lines
+            lines = [line.strip().lstrip('-').strip() for line in value.split('\n') if line.strip()]
+            return ', '.join(lines)
+    
     return ""
 
 

package/lib/cli/instruct.py

@@ -0,0 +1,108 @@
+"""@darkarts
+⊢{cli:instruct}
+∂{click,pathlib,darkarts.instruction_generator,darkarts.ai_detector}
+⚠{write-access:cwd}
+⊨{idempotent:instruction-generation}
+🔒{read-write:filesystem}
+⚡{O(1):file-creation}
+"""
+
+"""
+VooDocs Instruct Command
+
+Generate AI-specific instructions for writing @darkarts annotations.
+"""
+
+import click
+from pathlib import Path
+import sys
+from pathlib import Path
+
+# Add parent directory to path for imports
+parent_dir = Path(__file__).parent.parent
+sys.path.insert(0, str(parent_dir))
+
+from darkarts.instruction_generator import InstructionGenerator
+from darkarts.ai_detector import AIEnvironment, detect_ai_environment
+
+
+@click.command()
+@click.option(
+    '--ai',
+    type=click.Choice([e.value for e in AIEnvironment], case_sensitive=False),
+    default=None,
+    help='Specify the AI environment (e.g., cursor, claude, gemini). Auto-detects if not provided.'
+)
+@click.option(
+    '--output',
+    type=click.Path(dir_okay=False, writable=True),
+    default=None,
+    help='Output file path. Prints to console if not provided.'
+)
+@click.option(
+    '--list-templates',
+    is_flag=True,
+    help='List all available AI instruction templates.'
+)
+def instruct(ai, output, list_templates):
+    """
+    Generate AI instructions for writing symbolic @darkarts annotations.
+    
+    Detects the AI environment (Cursor, Claude, etc.) and generates tailored
+    instructions to guide the AI in writing correct symbolic annotations.
+    
+    Examples:
+        voodocs instruct                  # Auto-detect AI and print instructions
+        voodocs instruct --ai cursor      # Generate instructions for Cursor
+        voodocs instruct --output .cursorrules # Save to .cursorrules file
+        voodocs instruct --list-templates # List available templates
+    """
+    generator = InstructionGenerator()
+    
+    if list_templates:
+        templates = generator.list_available_templates()
+        if not templates:
+            click.echo(click.style('No instruction templates found.', fg='yellow'))
+            return
+        
+        click.echo(click.style('Available AI instruction templates:', fg='green', bold=True))
+        for template in templates:
+            click.echo(f'- {template}')
+        return
+    
+    # Determine AI environment
+    if ai:
+        try:
+            environment = AIEnvironment(ai.lower())
+        except ValueError:
+            click.echo(click.style(f'Error: Invalid AI environment "{ai}"', fg='red'))
+            click.echo(f'Available options: {[e.value for e in AIEnvironment]}')
+            return
+    else:
+        environment = detect_ai_environment()
+        click.echo(click.style(f'Auto-detected AI environment: {environment.value}', fg='cyan'))
+    
+    # Generate instructions
+    try:
+        instructions = generator.generate(environment)
+    except FileNotFoundError:
+        click.echo(click.style(f'Error: No instruction template found for {environment.value}', fg='red'))
+        click.echo(f'Defaulting to generic instructions...')
+        environment = AIEnvironment.DEFAULT
+        instructions = generator.generate(environment)
+    
+    # Output instructions
+    if output:
+        output_path = Path(output)
+        output_path.parent.mkdir(parents=True, exist_ok=True)
+        output_path.write_text(instructions, encoding='utf-8')
+        click.echo(click.style(f'✓ Instructions saved to {output_path}', fg='green'))
+    else:
+        click.echo('\n' + '-'*20 + ' AI Instructions ' + '-'*20 + '\n')
+        click.echo(instructions)
+        click.echo('\n' + '-'*58 + '\n')
+    
+    if environment == AIEnvironment.CURSOR and not output:
+        click.echo(click.style('Tip: Save these instructions to a .cursorrules file in your project root.', fg='yellow'))
+    elif environment == AIEnvironment.CLAUDE and not output:
+        click.echo(click.style('Tip: Add these instructions to your Claude project settings.', fg='yellow'))

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@voodocs/cli",
-  "version": "1.0.2",
+  "version": "1.0.4",
   "description": "AI-Native Documentation System with Validation - The only documentation tool that validates your annotations and guarantees accuracy",
   "main": "voodocs_cli.py",
   "bin": {