@voodocs/cli 2.2.1 → 2.2.2

package/lib/darkarts/annotations/parser.py

@@ -763,50 +763,229 @@ class AnnotationParser:
         language: Language,
         darkarts_matches: List
     ) -> ParsedAnnotations:
-        """Parse @darkarts annotations and translate to Voodocs format."""
-        from .darkarts_parser import parse_darkarts
-        from .translator import DarkArtsTranslator
+        """Parse @darkarts annotations using two-pass approach.
         
-        # Parse all @darkarts annotations
-        translator = DarkArtsTranslator()
-        translated_annotations = []
+        Pass 1: Extract code structure using language-specific parser
+        Pass 2: Parse annotations and overlay them onto structure by line number
+        """
+        from .darkarts_parser import DarkArtsParser
+        
+        # PASS 1: Extract code structure using language-specific parser
+        if language == Language.PYTHON:
+            # For Python, extract structure using AST
+            structure = self._extract_python_structure(source_code, source_file)
+        elif language in (Language.TYPESCRIPT, Language.JAVASCRIPT):
+            # For TypeScript/JavaScript, use TypeScript parser
+            structure = self._extract_typescript_structure(source_file)
+        else:
+            # For other languages, create empty structure
+            structure = self._create_empty_structure(source_file, language)
+        
+        # PASS 2: Parse @darkarts annotations and match to structure
+        darkarts_parser = DarkArtsParser()
+        annotations_by_line = {}
         
         for match in darkarts_matches:
             darkarts_text = match.group(1)
+            line_number = source_code[:match.start()].count('\n') + 1
             
-            # Parse @darkarts annotation (parse_annotation expects just the content)
-            from .darkarts_parser import DarkArtsParser
-            parser = DarkArtsParser()
-            darkarts_annotation = parser.parse_annotation(darkarts_text)
-            
-            # Process the annotation
+            # Parse @darkarts annotation
+            darkarts_annotation = darkarts_parser.parse_annotation(darkarts_text)
             if darkarts_annotation:
-                # Convert DarkArtsAnnotation to dict for YAML generation
-                annotation_dict = {
-                    'module': darkarts_annotation.module,
-                    'dependencies': darkarts_annotation.dependencies,
-                    'assumptions': darkarts_annotation.assumptions,
-                    'invariants': darkarts_annotation.invariants,
-                    'security_model': darkarts_annotation.security,
-                    'performance': darkarts_annotation.performance,
-                }
+                annotations_by_line[line_number] = darkarts_annotation
+        
+        # PASS 3: Overlay annotations onto structure
+        return self._overlay_annotations(structure, annotations_by_line)
+    
+    def _extract_python_structure(self, source_code: str, source_file: str) -> ParsedAnnotations:
+        """Extract Python code structure using AST (without annotations)."""
+        try:
+            tree = ast.parse(source_code)
+        except SyntaxError:
+            return self._create_empty_structure(source_file, Language.PYTHON)
+        
+        module = ModuleAnnotation(
+            name=Path(source_file).stem,
+            source_file=source_file,
+            language=Language.PYTHON,
+        )
+        
+        # Extract functions and classes from AST
+        for node in ast.walk(tree):
+            if isinstance(node, ast.FunctionDef):
+                func = FunctionAnnotation(
+                    name=node.name,
+                    line_number=node.lineno,
+                )
+                module.functions.append(func)
+            elif isinstance(node, ast.ClassDef):
+                cls = ClassAnnotation(
+                    name=node.name,
+                    line_number=node.lineno,
+                )
+                # Extract methods
+                for item in node.body:
+                    if isinstance(item, ast.FunctionDef):
+                        method = FunctionAnnotation(
+                            name=item.name,
+                            line_number=item.lineno,
+                        )
+                        cls.methods.append(method)
+                module.classes.append(cls)
+        
+        return ParsedAnnotations(
+            module=module,
+            language=Language.PYTHON,
+            source_file=source_file,
+        )
+    
+    def _extract_typescript_structure(self, source_file: str) -> ParsedAnnotations:
+        """Extract TypeScript/JavaScript code structure using TypeScript parser."""
+        try:
+            check_parser_for_language('typescript')
+        except ParserNotBuiltError:
+            return self._create_empty_structure(source_file, Language.TYPESCRIPT)
+        
+        # Get the path to the TypeScript parser CLI
+        parser_dir = Path(__file__).parent.parent / 'parsers' / 'typescript'
+        parser_cli = parser_dir / 'dist' / 'cli.js'
+        
+        if not parser_cli.exists():
+            return self._create_empty_structure(source_file, Language.TYPESCRIPT)
+        
+        # Run the TypeScript parser
+        try:
+            result = subprocess.run(
+                ['node', str(parser_cli), source_file],
+                capture_output=True,
+                text=True,
+                check=True
+            )
+            data = json.loads(result.stdout)
+        except (subprocess.CalledProcessError, json.JSONDecodeError):
+            return self._create_empty_structure(source_file, Language.TYPESCRIPT)
+        
+        # Convert TypeScript parser output to our format
+        language = Language.TYPESCRIPT if data['language'] == 'typescript' else Language.JAVASCRIPT
+        
+        module = ModuleAnnotation(
+            name=Path(source_file).stem,
+            source_file=source_file,
+            language=language,
+        )
+        
+        # Extract classes
+        for cls_data in data.get('classes', []):
+            cls = ClassAnnotation(
+                name=cls_data['name'],
+                line_number=cls_data['line'],
+            )
+            # Extract methods
+            for method_data in cls_data.get('methods', []):
+                method = FunctionAnnotation(
+                    name=method_data['name'],
+                    line_number=method_data['line'],
+                )
+                cls.methods.append(method)
+            module.classes.append(cls)
+        
+        # Extract functions
+        for func_data in data.get('functions', []):
+            func = FunctionAnnotation(
+                name=func_data['name'],
+                line_number=func_data['line'],
+            )
+            module.functions.append(func)
+        
+        return ParsedAnnotations(
+            module=module,
+            language=language,
+            source_file=source_file,
+        )
+    
+    def _create_empty_structure(self, source_file: str, language: Language) -> ParsedAnnotations:
+        """Create empty structure for unsupported languages."""
+        module = ModuleAnnotation(
+            name=Path(source_file).stem,
+            source_file=source_file,
+            language=language,
+        )
+        return ParsedAnnotations(
+            module=module,
+            language=language,
+            source_file=source_file,
+        )
+    
+    def _overlay_annotations(self, structure: ParsedAnnotations, annotations_by_line: Dict[int, Any]) -> ParsedAnnotations:
+        """Overlay parsed annotations onto code structure by matching line numbers."""
+        # Match annotations to code elements by finding the closest following element
+        for line_num, annotation in annotations_by_line.items():
+            # Check if this is a module-level annotation (appears before any code)
+            if self._is_module_annotation(annotation):
+                self._apply_module_annotation_from_darkarts(structure.module, annotation)
+                continue
+            
+            # Find the closest function or class after this line
+            matched = False
+            
+            # Try to match to a function
+            for func in structure.module.functions:
+                if func.line_number >= line_num and func.line_number - line_num <= 5:
+                    self._apply_function_annotation_from_darkarts(func, annotation)
+                    matched = True
+                    break
+            
+            if matched:
+                continue
+            
+            # Try to match to a class
+            for cls in structure.module.classes:
+                if cls.line_number >= line_num and cls.line_number - line_num <= 5:
+                    self._apply_class_annotation_from_darkarts(cls, annotation)
+                    matched = True
+                    break
                 
-                # Convert to @voodocs YAML format
-                voodocs_yaml = self._darkarts_to_voodocs_yaml(annotation_dict)
+                # Try to match to a method within the class
+                for method in cls.methods:
+                    if method.line_number >= line_num and method.line_number - line_num <= 5:
+                        self._apply_function_annotation_from_darkarts(method, annotation)
+                        matched = True
+                        break
                 
-                line_number = source_code[:match.start()].count('\n') + 1
-                translated_annotations.append({
-                    'text': voodocs_yaml,
-                    'line': line_number,
-                    'start': match.start(),
-                    'end': match.end(),
-                })
-        
-        # Parse as if they were @voodocs
-        if language == Language.PYTHON:
-            return self._parse_python(source_code, source_file, translated_annotations)
-        else:
-            return self._parse_generic(source_code, source_file, language, translated_annotations)
+                if matched:
+                    break
+        
+        return structure
+    
+    def _is_module_annotation(self, annotation: Any) -> bool:
+        """Check if annotation is module-level."""
+        return hasattr(annotation, 'module') and annotation.module
+    
+    def _apply_module_annotation_from_darkarts(self, module: ModuleAnnotation, annotation: Any):
+        """Apply @darkarts annotation to module."""
+        if hasattr(annotation, 'module') and annotation.module:
+            module.module_purpose = f"Module {{{annotation.module}}}"
+        if hasattr(annotation, 'dependencies') and annotation.dependencies:
+            module.dependencies = annotation.dependencies
+        if hasattr(annotation, 'assumptions') and annotation.assumptions:
+            module.assumptions = annotation.assumptions
+    
+    def _apply_function_annotation_from_darkarts(self, func: FunctionAnnotation, annotation: Any):
+        """Apply @darkarts annotation to function."""
+        if hasattr(annotation, 'preconditions') and annotation.preconditions:
+            func.preconditions = annotation.preconditions
+        if hasattr(annotation, 'postconditions') and annotation.postconditions:
+            func.postconditions = annotation.postconditions
+        if hasattr(annotation, 'invariants') and annotation.invariants:
+            func.invariants = annotation.invariants
+        if hasattr(annotation, 'performance') and annotation.performance:
+            if isinstance(annotation.performance, dict) and 'complexity' in annotation.performance:
+                func.complexity = annotation.performance['complexity']
+    
+    def _apply_class_annotation_from_darkarts(self, cls: ClassAnnotation, annotation: Any):
+        """Apply @darkarts annotation to class."""
+        if hasattr(annotation, 'invariants') and annotation.invariants:
+            cls.invariants = annotation.invariants
     
     def _darkarts_to_voodocs_yaml(self, annotation_dict: Dict[str, Any]) -> str:
         """Convert DarkArts annotation dict to YAML format (legacy)."""

package/lib/darkarts/cli_darkarts.py

@@ -52,7 +52,7 @@ def cmd_darkarts_translate(args):
         
         try:
             if to_symbols:
-                # Natural language → Symbols (Voodocs → DarkArts)
+                # Natural language → Symbols (VooDocs → DarkArts)
                 parser = AnnotationParser()
                 annotations = parser.parse_file(str(path))
                 
@@ -91,7 +91,7 @@ def cmd_darkarts_translate(args):
 
 def cmd_darkarts_convert(args):
     """
-    Convert files between Voodocs and DarkArts formats.
+    Convert files between VooDocs and DarkArts formats.
     
     Usage:
         voodocs darkarts convert <files> [--in-place]
@@ -121,7 +121,7 @@ def cmd_darkarts_convert(args):
         try:
             content = path.read_text()
             
-            # Parse Voodocs annotations
+            # Parse VooDocs annotations
             parser = AnnotationParser()
             annotations = parser.parse_file(str(path))
             language = parser.detect_language(str(path))
@@ -412,7 +412,7 @@ def cmd_darkarts_validate(args):
 
 def add_darkarts_subcommands(subparsers):
     """
-    Add DarkArts subcommands to Voodocs CLI.
+    Add DarkArts subcommands to VooDocs CLI.
     
     Args:
         subparsers: Argparse subparsers object
@@ -446,7 +446,7 @@ def add_darkarts_subcommands(subparsers):
     # darkarts convert
     convert_parser = darkarts_subparsers.add_parser(
         "convert",
-        help="Convert Voodocs annotations to DarkArts"
+        help="Convert VooDocs annotations to DarkArts"
     )
     convert_parser.add_argument(
         "files",

package/lib/darkarts/context/ai_instructions.py

@@ -6,10 +6,10 @@
 🔒{no-implications}
 ⚡{O(1)|template-generation}
 
-AI instruction templates for Voodocs Context System.
+AI instruction templates for VooDocs Context System.
 
 This module provides templates for generating AI assistant instructions
-that teach them how to use the Voodocs context system effectively.
+that teach them how to use the VooDocs context system effectively.
 """
 
 from typing import Dict, Optional
@@ -26,14 +26,14 @@ def generate_cursorrules(project_name: str, project_purpose: str) -> str:
     Returns:
         Content for .cursorrules file
     """
-    return f"""# {project_name} - Voodocs Context System
+    return f"""# {project_name} - VooDocs Context System
 
 ## Project Overview
 {project_purpose}
 
-## Voodocs Context System (v0.2.0+)
+## VooDocs Context System (v0.2.0+)
 
-This project uses Voodocs with the Context System for intelligent documentation and validation.
+This project uses VooDocs with the Context System for intelligent documentation and validation.
 
 ### Context File Location
 - **Context file**: `.voodocs.context` (YAML format)
@@ -222,7 +222,7 @@ voodocs context diagram --type all --output docs/arch
 
 ---
 
-**Voodocs Context System** - AI-native documentation that keeps code and context in sync.
+**VooDocs Context System** - AI-native documentation that keeps code and context in sync.
 """
 
 
@@ -237,20 +237,20 @@ def generate_context_guide(project_name: str, project_purpose: str) -> str:
     Returns:
         Content for VOODOCS_CONTEXT_GUIDE.md file
     """
-    return f"""# Voodocs Context System Guide - {project_name}
+    return f"""# VooDocs Context System Guide - {project_name}
 
 ## Project Overview
 
 **Name**: {project_name}  
 **Purpose**: {project_purpose}
 
-This project uses the **Voodocs Context System** (v0.2.0+) for intelligent documentation, validation, and architecture management.
+This project uses the **VooDocs Context System** (v0.2.0+) for intelligent documentation, validation, and architecture management.
 
 ---
 
 ## What is the Context System?
 
-The Voodocs Context System is an AI-native documentation framework that:
+The VooDocs Context System is an AI-native documentation framework that:
 
 1. **Auto-generates** project context from code annotations
 2. **Validates** code against documented invariants
@@ -620,7 +620,7 @@ jobs:
     steps:
       - uses: actions/checkout@v2
       
-      - name: Install Voodocs
+      - name: Install VooDocs
         run: npm install -g @voodocs/cli
       
       - name: Validate Context
@@ -703,7 +703,7 @@ Or add `module_purpose` to @voodocs annotations and regenerate.
 
 ## Summary
 
-The Voodocs Context System is your **single source of truth** for:
+The VooDocs Context System is your **single source of truth** for:
 - ✅ Project understanding
 - ✅ Architecture documentation
 - ✅ Code validation
@@ -714,7 +714,7 @@ The Voodocs Context System is your **single source of truth** for:
 
 ---
 
-**Voodocs v0.2.0+** - AI-native documentation that keeps code and context in sync.
+**VooDocs v0.2.0+** - AI-native documentation that keeps code and context in sync.
 """
 
 

package/lib/darkarts/context/ai_integrations.py

@@ -6,7 +6,7 @@
 🔒{read-only:detect,write:explicit-user-command}
 ⚡{O(n²):detect-with-analysis,O(k):generate|k=ai-count}
 
-AI-specific integration templates for Voodocs Context System.
+AI-specific integration templates for VooDocs Context System.
 
 This module provides native integration with different AI assistants:
 - Claude Code (skills)
@@ -23,7 +23,7 @@ from pathlib import Path
 
 def generate_claude_skill(project_name: str, project_purpose: str) -> Dict[str, str]:
     """
-    Generate Claude Code skill for Voodocs context system.
+    Generate Claude Code skill for VooDocs context system.
     
     Args:
         project_name: Name of the project
@@ -34,15 +34,15 @@ def generate_claude_skill(project_name: str, project_purpose: str) -> Dict[str,
     """
     skill_md = f"""---
 name: voodocs-context
-description: Access and query the Voodocs context system for project understanding, invariants, and architecture
+description: Access and query the VooDocs context system for project understanding, invariants, and architecture
 ---
 
-# Voodocs Context System Skill
+# VooDocs Context System Skill
 
 ## Project: {project_name}
 {project_purpose}
 
-This skill provides access to the Voodocs context system for understanding project architecture, invariants, and assumptions.
+This skill provides access to the VooDocs context system for understanding project architecture, invariants, and assumptions.
 
 ## Available Commands
 
@@ -152,7 +152,7 @@ voodocs context check
 
 def generate_cursor_rules(project_name: str, project_purpose: str) -> Dict[str, str]:
     """
-    Generate Cursor rules for Voodocs context system.
+    Generate Cursor rules for VooDocs context system.
     
     Args:
         project_name: Name of the project
@@ -162,12 +162,12 @@ def generate_cursor_rules(project_name: str, project_purpose: str) -> Dict[str,
         Dictionary mapping file paths to content
     """
     
-    main_rule = f"""# Voodocs Context System
+    main_rule = f"""# VooDocs Context System
 
 ## Project: {project_name}
 {project_purpose}
 
-This project uses the Voodocs Context System (v0.2.0+) for documentation and validation.
+This project uses the VooDocs Context System (v0.2.0+) for documentation and validation.
 
 ## Context File
 - **Location**: `.voodocs.context`
@@ -283,7 +283,7 @@ voodocs context query "module-name" --section architecture
 
 def generate_copilot_instructions(project_name: str, project_purpose: str) -> Dict[str, str]:
     """
-    Generate GitHub Copilot instructions for Voodocs context system.
+    Generate GitHub Copilot instructions for VooDocs context system.
     
     Args:
         project_name: Name of the project
@@ -298,9 +298,9 @@ def generate_copilot_instructions(project_name: str, project_purpose: str) -> Di
 ## Project Overview
 {project_purpose}
 
-## Voodocs Context System
+## VooDocs Context System
 
-This project uses Voodocs Context System (v0.2.0+) for documentation and validation.
+This project uses VooDocs Context System (v0.2.0+) for documentation and validation.
 
 ### Context File
 - **Location**: `.voodocs.context` (YAML format)
@@ -400,7 +400,7 @@ voodocs context diagram --type modules
 
 def generate_windsurf_rules(project_name: str, project_purpose: str) -> Dict[str, str]:
     """
-    Generate Windsurf rules for Voodocs context system.
+    Generate Windsurf rules for VooDocs context system.
     
     Args:
         project_name: Name of the project
@@ -415,9 +415,9 @@ def generate_windsurf_rules(project_name: str, project_purpose: str) -> Dict[str
 ## Project
 {project_purpose}
 
-## Voodocs Context System
+## VooDocs Context System
 
-This project uses Voodocs (v0.2.0+) for context management.
+This project uses VooDocs (v0.2.0+) for context management.
 
 ### Context Commands
 
@@ -478,7 +478,7 @@ invariants: ["rules"]
 
 def generate_cline_rules(project_name: str, project_purpose: str) -> Dict[str, str]:
     """
-    Generate Cline rules for Voodocs context system.
+    Generate Cline rules for VooDocs context system.
     
     Args:
         project_name: Name of the project
@@ -493,7 +493,7 @@ def generate_cline_rules(project_name: str, project_purpose: str) -> Dict[str, s
 ## Project
 {project_purpose}
 
-## Voodocs Context System
+## VooDocs Context System
 
 Context file: `.voodocs.context` (YAML)
 

package/lib/darkarts/context/commands.py

@@ -210,7 +210,7 @@ def cmd_context_init(force: bool = False) -> int:
         Exit code (0 for success, 1 for error)
     """
     try:
-        print_header("Voodocs Context Initialization")
+        print_header("VooDocs Context Initialization")
         
         # Check if context file already exists
         context_path = get_context_file_path()
@@ -224,7 +224,7 @@ def cmd_context_init(force: bool = False) -> int:
             if not confirm(f"Overwrite existing context file at {context_path}?", default=False):
                 raise UserInterruptError("Initialization")
         
-        step("Initializing Voodocs context...")
+        step("Initializing VooDocs context...")
         print()
         
         # Detect project information
@@ -375,7 +375,7 @@ def cmd_context_init(force: bool = False) -> int:
                     
                     print()
                     print("🤖 AI integration complete!")
-                    print(f"   Your {ai_type} assistant will now understand the Voodocs context system.")
+                    print(f"   Your {ai_type} assistant will now understand the VooDocs context system.")
                     
                 except Exception as e:
                     print(f"⚠️  Warning: Failed to generate AI integration: {e}")
@@ -1368,7 +1368,7 @@ def cmd_context_generate(source_dir: Optional[str] = None, update_existing: bool
         return 1
     except ImportError as e:
         error(f"Failed to import annotation parser: {e}")
-        warning("Make sure Voodocs is properly installed")
+        warning("Make sure VooDocs is properly installed")
         return 1
     except Exception as e:
         error(f"Failed to generate context: {e}")

package/lib/darkarts/context/errors.py

@@ -52,7 +52,7 @@ class GitNotAvailableError(ConfigurationError):
     def __init__(self):
         super().__init__(
             f"Git is not available\n\n"
-            f"💡 Some Voodocs features require Git. Please install Git:\n"
+            f"💡 Some VooDocs features require Git. Please install Git:\n"
             f"   https://git-scm.com/downloads"
         )
 

package/lib/darkarts/context/models.py

@@ -8,7 +8,7 @@
 
 Context System Data Models
 
-This module defines the data structures for the Voodocs context system.
+This module defines the data structures for the VooDocs context system.
 """
 
 from dataclasses import dataclass, field, asdict

package/lib/darkarts/context/ui.py

@@ -119,8 +119,8 @@ def step(message: str) -> None:
         message: Step message to display
         
     Example:
-        >>> step("Initializing Voodocs context...")
-        ▶️  Initializing Voodocs context...
+        >>> step("Initializing VooDocs context...")
+        ▶️  Initializing VooDocs context...
     """
     print(f"{Colors.CYAN}▶️  {message}{Colors.RESET}")
 
@@ -243,10 +243,10 @@ def print_header(title: str) -> None:
         title: Header title
         
     Example:
-        >>> print_header("Voodocs Context System")
+        >>> print_header("VooDocs Context System")
         
         ═══════════════════════════════════════════════════════════════
-        Voodocs Context System
+        VooDocs Context System
         ═══════════════════════════════════════════════════════════════
     """
     width = 80

package/lib/darkarts/context/yaml_utils.py

@@ -56,7 +56,7 @@ def write_context_yaml(context: ContextFile, file_path: Path) -> None:
     # Create file with header comment
     with open(file_path, 'w', encoding='utf-8') as f:
         # Write header
-        f.write("# Voodocs Context File\n")
+        f.write("# VooDocs Context File\n")
         f.write("# This file contains structured project context for AI assistants and developers.\n")
         f.write("# Format: YAML (DSL for machines, use 'voodocs context view' for human-readable Markdown)\n")
         f.write("# Version: {}\n".format(context.versioning.context_version))
@@ -333,14 +333,14 @@ def add_to_gitignore(project_root: Path) -> bool:
             # Ensure there's a newline before our section
             if not content.endswith('\n'):
                 f.write('\n')
-            f.write('\n# Voodocs Context File (contains internal project details)\n')
+            f.write('\n# VooDocs Context File (contains internal project details)\n')
             f.write(f'{context_entry}\n')
         
         return True
     else:
         # Create .gitignore with entry
         with open(gitignore_path, 'w', encoding='utf-8') as f:
-            f.write('# Voodocs Context File (contains internal project details)\n')
+            f.write('# VooDocs Context File (contains internal project details)\n')
             f.write(f'{context_entry}\n')
         
         return True

package/lib/darkarts/core/loader.py

@@ -199,7 +199,7 @@ class PluginLoader:
             plugin = self.load_from_module("darkarts.plugins.voodocs", "VooDocsPlugin")
             plugins.append(plugin)
         except PluginError:
-            pass  # Voodocs plugin not yet implemented
+            pass  # VooDocs plugin not yet implemented
         
         return plugins
     

package/lib/darkarts/exceptions.py

@@ -6,10 +6,10 @@
 🔒{pure-exceptions,¬io,¬side-effects,¬exec}
 ⚡{O(1):exception-creation}
 
-Voodocs Custom Exceptions
+VooDocs Custom Exceptions
 
 Structured exception hierarchy for error handling with:
-- Base exception (VooDocsError for all Voodocs errors)
+- Base exception (VooDocsError for all VooDocs errors)
 - Parser errors (ParserError, ParserNotBuiltError, AnnotationError)
 - Validation errors (InvalidAnnotationError, ValidationError)
 - Generator errors (GeneratorError)
@@ -20,7 +20,7 @@ Structured exception hierarchy for error handling with:
 
 
 class VooDocsError(Exception):
-    """Base exception for all Voodocs errors."""
+    """Base exception for all VooDocs errors."""
     pass