@voodocs/cli 1.0.2 → 1.0.5

package/CHANGELOG.md

@@ -1,3 +1,223 @@
+## v1.0.5 (2024-12-21)
+
+### 🐛 Bug Fix: Instruct Command Import Error
+
+**Problem:** The `voodocs instruct` command failed with `ModuleNotFoundError: No module named 'darkarts.instruction_generator'` when trying to generate AI instructions.
+
+**Root Cause:** The instruct command was trying to import complex modules (`InstructionGenerator`, `AIEnvironment`) that had dependencies issues in the npm package.
+
+**Fix:** Simplified the instruct command to directly read template files without complex module dependencies.
+
+---
+
+### Changes
+
+- Rewrote `lib/cli/instruct.py` to be self-contained
+- Removed dependency on `darkarts.instruction_generator` and `darkarts.ai_detector`
+- Simplified AI environment detection
+- All functionality preserved
+
+---
+
+### Testing
+
+| Test Case | Status |
+|-----------|--------|
+| `voodocs instruct --list-templates` | ✅ Pass |
+| `voodocs instruct --ai cursor` | ✅ Pass |
+| `voodocs instruct --ai claude` | ✅ Pass |
+| `voodocs instruct --output .cursorrules` | ✅ Pass |
+| AI auto-detection | ✅ Pass |
+
+---
+
+### Upgrade
+
+```bash
+npm install -g @voodocs/cli@1.0.5
+```
+
+## 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.5"
 
 
 @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,129 @@
+"""@darkarts
+⊢{cli:instruct}
+∂{click,pathlib,os}
+⚠{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 os
+
+
+@click.command()
+@click.option(
+    '--ai',
+    type=click.Choice(['cursor', 'claude', 'default'], case_sensitive=False),
+    help='Target AI assistant (auto-detects if not specified)'
+)
+@click.option(
+    '--output',
+    '-o',
+    type=click.Path(),
+    help='Output file path (prints to console if not specified)'
+)
+@click.option(
+    '--list-templates',
+    is_flag=True,
+    help='List available instruction templates'
+)
+def instruct(ai, output, list_templates):
+    """
+    Generate AI-specific instructions for writing @darkarts annotations.
+    
+    This command generates tailored instructions for AI assistants to help them
+    write correct symbolic DarkArts annotations in your codebase.
+    
+    Examples:
+    
+        # Auto-detect AI and print instructions
+        voodocs instruct
+        
+        # Generate for Cursor and save to .cursorrules
+        voodocs instruct --ai cursor --output .cursorrules
+        
+        # Generate for Claude
+        voodocs instruct --ai claude
+        
+        # List available templates
+        voodocs instruct --list-templates
+    """
+    
+    # Get the instructions directory
+    cli_dir = Path(__file__).parent
+    instructions_dir = cli_dir.parent / 'darkarts' / 'instructions'
+    
+    if not instructions_dir.exists():
+        click.secho("Error: Instructions directory not found", fg='red')
+        click.echo(f"Expected at: {instructions_dir}")
+        return
+    
+    # List templates if requested
+    if list_templates:
+        click.echo("Available instruction templates:")
+        click.echo()
+        templates = list(instructions_dir.glob('*.md'))
+        for template in templates:
+            click.echo(f"  • {template.stem}")
+        click.echo()
+        click.echo(f"Total: {len(templates)} templates")
+        return
+    
+    # Auto-detect AI if not specified
+    if not ai:
+        ai = _detect_ai_environment()
+        if ai:
+            click.echo(f"Detected AI environment: {ai}")
+        else:
+            ai = 'default'
+            click.echo("Using default instructions (AI environment not detected)")
+        click.echo()
+    
+    # Load the appropriate template
+    template_file = instructions_dir / f"{ai}.md"
+    
+    if not template_file.exists():
+        click.secho(f"Warning: Template '{ai}.md' not found, using default", fg='yellow')
+        template_file = instructions_dir / "default.md"
+    
+    if not template_file.exists():
+        click.secho("Error: No instruction templates found", fg='red')
+        return
+    
+    # Read the template
+    instructions = template_file.read_text(encoding='utf-8')
+    
+    # Output the instructions
+    if output:
+        output_path = Path(output)
+        output_path.write_text(instructions, encoding='utf-8')
+        click.secho(f"✅ Instructions written to: {output_path}", fg='green')
+        click.echo()
+        click.echo("Your AI assistant will now write symbolic DarkArts annotations!")
+    else:
+        click.echo(instructions)
+
+
+def _detect_ai_environment():
+    """Detect which AI environment is being used."""
+    # Check for Cursor
+    if os.environ.get('CURSOR_USER') or os.path.exists('.cursorrules'):
+        return 'cursor'
+    
+    # Check for Claude
+    if os.environ.get('CLAUDE_API_KEY') or os.path.exists('.claude'):
+        return 'claude'
+    
+    # Check for other AI indicators
+    if os.environ.get('OPENAI_API_KEY'):
+        return 'default'
+    
+    return None

package/package.json

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