@voodocs/cli 1.0.0 → 1.0.2

package/lib/cli/init.py

@@ -0,0 +1,228 @@
+"""@darkarts
+⊢{cli:init}
+∂{click,pathlib,json}
+⚠{write-access:cwd}
+⊨{idempotent:config-creation}
+🔒{read-write:filesystem}
+⚡{O(1):file-creation}
+"""
+
+"""
+VooDocs Init Command
+
+Initialize a new project with VooDocs configuration and example annotations.
+"""
+
+import click
+import json
+from pathlib import Path
+
+
+@click.command()
+@click.option(
+    '--format',
+    type=click.Choice(['voodocs', 'darkarts'], case_sensitive=False),
+    default='voodocs',
+    help='Annotation format to use (voodocs or darkarts symbolic)'
+)
+@click.option(
+    '--config-only',
+    is_flag=True,
+    help='Only create configuration file, skip example files'
+)
+def init(format, config_only):
+    """
+    Initialize a new project with VooDocs.
+    
+    Creates a .voodocs.json configuration file and optionally generates
+    example annotated files to help you get started.
+    
+    Examples:
+        voodocs init                    # Initialize with @voodocs format
+        voodocs init --format darkarts  # Initialize with symbolic @darkarts format
+        voodocs init --config-only      # Only create config file
+    """
+    cwd = Path.cwd()
+    config_path = cwd / '.voodocs.json'
+    
+    # Check if config already exists
+    if config_path.exists():
+        click.echo(click.style('⚠ .voodocs.json already exists', fg='yellow'))
+        if not click.confirm('Overwrite existing configuration?'):
+            click.echo('Aborted.')
+            return
+    
+    # Create default configuration
+    config = {
+        "version": "1.0",
+        "format": format,
+        "validation": {
+            "semantic": True,
+            "performance": True,
+            "strict": False
+        },
+        "generation": {
+            "output_format": "markdown",
+            "include_toc": True,
+            "include_examples": True
+        },
+        "exclude": [
+            "node_modules",
+            "dist",
+            "build",
+            "__pycache__",
+            ".git",
+            "*.min.js"
+        ]
+    }
+    
+    # Write configuration
+    with open(config_path, 'w') as f:
+        json.dump(config, f, indent=2)
+    
+    click.echo(click.style('✓ Created .voodocs.json', fg='green'))
+    
+    if not config_only:
+        # Create example files
+        examples_dir = cwd / 'voodocs-examples'
+        examples_dir.mkdir(exist_ok=True)
+        
+        if format == 'voodocs':
+            create_voodocs_example(examples_dir)
+        else:
+            create_darkarts_example(examples_dir)
+        
+        click.echo(click.style(f'✓ Created example files in {examples_dir}/', fg='green'))
+    
+    click.echo()
+    click.echo(click.style('🎉 VooDocs initialized successfully!', fg='green', bold=True))
+    click.echo()
+    click.echo('Next steps:')
+    click.echo('  1. Review .voodocs.json configuration')
+    click.echo('  2. Add annotations to your code')
+    click.echo('  3. Run: voodocs validate .')
+    click.echo('  4. Run: voodocs generate . ./docs')
+    click.echo()
+    click.echo('Documentation: https://voodocs.com/docs')
+
+
+def create_voodocs_example(examples_dir: Path):
+    """Create example files with @voodocs annotations."""
+    
+    # TypeScript example
+    ts_example = '''/**@voodocs
+module_purpose: "Example TypeScript module demonstrating @voodocs annotations"
+dependencies: []
+assumptions: ["TypeScript environment available"]
+*/
+
+/**@voodocs
+preconditions: [
+  "name must be a non-empty string",
+  "age must be a positive number"
+]
+postconditions: [
+  "Returns a greeting message",
+  "Message includes the provided name"
+]
+invariants: [
+  "Does not modify input parameters"
+]
+side_effects: []
+complexity: "O(1)"
+*/
+export function greet(name: string, age: number): string {
+  return `Hello, ${name}! You are ${age} years old.`;
+}
+'''
+    
+    (examples_dir / 'example.ts').write_text(ts_example)
+    
+    # Python example
+    py_example = '''"""@voodocs
+module_purpose: "Example Python module demonstrating @voodocs annotations"
+dependencies: []
+assumptions: ["Python 3.7+"]
+"""
+
+def calculate_total(prices: list[float], tax_rate: float) -> float:
+    """@voodocs
+    preconditions: [
+      "prices is a non-empty list of positive numbers",
+      "tax_rate is between 0 and 1"
+    ]
+    postconditions: [
+      "Returns the total with tax applied",
+      "Result is greater than or equal to sum of prices"
+    ]
+    invariants: [
+      "Does not modify the prices list"
+    ]
+    side_effects: []
+    complexity: "O(n) where n is the length of prices"
+    """
+    subtotal = sum(prices)
+    return subtotal * (1 + tax_rate)
+'''
+    
+    (examples_dir / 'example.py').write_text(py_example)
+
+
+def create_darkarts_example(examples_dir: Path):
+    """Create example files with symbolic @darkarts annotations."""
+    
+    # TypeScript example
+    ts_example = '''/**@darkarts
+⊢{Example TypeScript module demonstrating symbolic @darkarts annotations}
+∂{}
+⚠{TypeScript environment available}
+*/
+
+/**@darkarts
+⊳{
+  name must be a non-empty string
+  age must be a positive number
+}
+⊲{
+  Returns a greeting message
+  Message includes the provided name
+}
+⊨{
+  Does ¬ modify input parameters
+}
+⚡{}
+*/
+export function greet(name: string, age: number): string {
+  return `Hello, ${name}! You are ${age} years old.`;
+}
+'''
+    
+    (examples_dir / 'example.ts').write_text(ts_example)
+    
+    # Python example
+    py_example = '''"""@darkarts
+⊢{Example Python module demonstrating symbolic @darkarts annotations}
+∂{}
+⚠{Python 3.7+}
+"""
+
+def calculate_total(prices: list[float], tax_rate: float) -> float:
+    """@darkarts
+    ⊳{
+      prices is a non-empty list ∧ ∀ p ∈ prices: p > 0
+      tax_rate ∈ [0, 1]
+    }
+    ⊲{
+      Returns the total with tax applied
+      result ≥ sum(prices)
+    }
+    ⊨{
+      Does ¬ modify the prices list
+    }
+    ⚡{O(n) where n = len(prices)}
+    """
+    subtotal = sum(prices)
+    return subtotal * (1 + tax_rate)
+'''
+    
+    (examples_dir / 'example.py').write_text(py_example)

package/lib/darkarts/annotations/parser.py

@@ -50,16 +50,16 @@ class AnnotationParser:
         Language.PYTHON: r'"""@voodocs\s*(.*?)\s*"""',
     }
     
-    # DarkArts patterns (symbolic annotations)
+    # DarkArts patterns (symbolic annotations) - support both @voodocs and @darkarts
     DARKARTS_PATTERNS = {
-        Language.PYTHON: r'"""@darkarts\s*(.*?)\s*"""',
-        Language.TYPESCRIPT: r'/\*@voodocs\s*(.*?)\s*\*/',
-        Language.JAVASCRIPT: r'/\*@voodocs\s*(.*?)\s*\*/',
-        Language.JAVA: r'/\*@voodocs\s*(.*?)\s*\*/',
-        Language.CPP: r'/\*@voodocs\s*(.*?)\s*\*/',
-        Language.CSHARP: r'/\*@voodocs\s*(.*?)\s*\*/',
-        Language.GO: r'/\*@voodocs\s*(.*?)\s*\*/',
-        Language.RUST: r'/\*@voodocs\s*(.*?)\s*\*/',
+        Language.PYTHON: r'"""@(?:darkarts|voodocs)\s*(.*?)\s*"""',
+        Language.TYPESCRIPT: r'/\*\*@(?:darkarts|voodocs)\s*(.*?)\s*\*/',
+        Language.JAVASCRIPT: r'/\*\*@(?:darkarts|voodocs)\s*(.*?)\s*\*/',
+        Language.JAVA: r'/\*\*@(?:darkarts|voodocs)\s*(.*?)\s*\*/',
+        Language.CPP: r'/\*\*@(?:darkarts|voodocs)\s*(.*?)\s*\*/',
+        Language.CSHARP: r'/\*\*@(?:darkarts|voodocs)\s*(.*?)\s*\*/',
+        Language.GO: r'/\*\*@(?:darkarts|voodocs)\s*(.*?)\s*\*/',
+        Language.RUST: r'/\*\*@(?:darkarts|voodocs)\s*(.*?)\s*\*/',
     }
     
     def __init__(self):

package/lib/darkarts/annotations/translator.py

@@ -209,7 +209,7 @@ class DarkArtsTranslator:
         Returns:
             Symbolic notation
         """
-        result = text.lower()
+        result = text
         
         # Replace English phrases with symbols
         # Sort by length (longest first) to avoid partial matches
@@ -217,7 +217,14 @@ class DarkArtsTranslator:
                         key=lambda x: len(x[0]), reverse=True)
         
         for english, symbol in phrases:
-            result = result.replace(english, symbol)
+            # Use word boundaries to avoid mid-word replacements
+            # This prevents "or" in "authenticated" from being replaced
+            pattern = r'\b' + re.escape(english) + r'\b'
+            try:
+                result = re.sub(pattern, symbol, result, flags=re.IGNORECASE)
+            except re.error:
+                # Fallback for patterns that don't work with word boundaries
+                pass
         
         return result
     
@@ -311,15 +318,35 @@ class DarkArtsTranslator:
                 symbolic = [self._convert_invariant(inv) for inv in invariants]
                 lines.append(f"⊨{{{','.join(symbolic)}}}")
         
+        # Preconditions
+        if 'preconditions' in voodocs_dict:
+            preconditions = voodocs_dict['preconditions']
+            if isinstance(preconditions, list):
+                symbolic = [self._convert_invariant(pre) for pre in preconditions]
+                lines.append(f"⊳{{{','.join(symbolic)}}}")
+        
+        # Postconditions
+        if 'postconditions' in voodocs_dict:
+            postconditions = voodocs_dict['postconditions']
+            if isinstance(postconditions, list):
+                symbolic = [self._convert_invariant(post) for post in postconditions]
+                lines.append(f"⊲{{{','.join(symbolic)}}}")
+        
         # Security
-        if 'security_model' in voodocs_dict:
-            security = self._simplify_text(voodocs_dict['security_model'])
+        if 'security_model' in voodocs_dict or 'security_implications' in voodocs_dict:
+            security = voodocs_dict.get('security_model') or voodocs_dict.get('security_implications')
+            if isinstance(security, list):
+                security = ', '.join(security)
+            security = self._simplify_text(str(security))
             lines.append(f"🔒{{{security}}}")
         
-        # Performance
+        # Performance/Complexity
         if 'performance_model' in voodocs_dict:
             perf = voodocs_dict['performance_model']
             lines.append(f"⚡{{{perf}}}")
+        elif 'complexity' in voodocs_dict:
+            complexity = voodocs_dict['complexity']
+            lines.append(f"⚡{{{complexity}}}")
         
         lines.append('"""')
         return '\n'.join(lines)

package/lib/darkarts/annotations/types.py

@@ -15,7 +15,7 @@ Data structures for parsed @darkarts/@voodocs annotations with:
 - State transitions (from_state → to_state with conditions)
 - Error cases (condition, error_type, description)
 - Structured representations (FunctionAnnotation, ClassAnnotation, ModuleAnnotation)
-""""
+"""
 
 from dataclasses import dataclass, field
 from typing import List, Dict, Optional, Any

package/lib/darkarts/cli_darkarts.py

@@ -12,6 +12,7 @@ Provides CLI commands for DarkArts symbolic documentation.
 """
 
 import sys
+import re
 from pathlib import Path
 from typing import List, Optional
 
@@ -22,6 +23,7 @@ from darkarts.annotations import (
     convert_voodocs_to_darkarts,
 )
 from darkarts.annotations.parser import AnnotationParser
+from darkarts.annotations.types import Language
 
 
 def cmd_darkarts_translate(args):
@@ -93,6 +95,12 @@ def cmd_darkarts_convert(args):
     
     Usage:
         voodocs darkarts convert <files> [--in-place]
+    
+    Improvements:
+    - Supports Python, TypeScript, JavaScript
+    - Preserves ALL annotation fields (not just module-level)
+    - Fixed symbol conversion (no mid-word replacements)
+    - Working --in-place flag for all languages
     """
     print("🔄 DarkArts Conversion")
     print("=" * 60)
@@ -116,41 +124,161 @@ def cmd_darkarts_convert(args):
             # Parse VooDocs annotations
             parser = AnnotationParser()
             annotations = parser.parse_file(str(path))
+            language = parser.detect_language(str(path))
             
             if not annotations.module:
                 print("  ⚠️  No @voodocs annotations found")
                 continue
             
-            # Convert to DarkArts
-            voodocs_dict = {
-                'module_purpose': annotations.module.module_purpose,
-                'dependencies': annotations.module.dependencies,
-                'assumptions': annotations.module.assumptions,
-            }
+            # Convert module-level annotation
+            converted_annotations = []
             
-            darkarts = convert_voodocs_to_darkarts(voodocs_dict)
+            if annotations.module:
+                module_dict = {}
+                
+                # Include ALL fields
+                if hasattr(annotations.module, 'module_purpose') and annotations.module.module_purpose:
+                    module_dict['module_purpose'] = annotations.module.module_purpose
+                if hasattr(annotations.module, 'dependencies') and annotations.module.dependencies:
+                    module_dict['dependencies'] = annotations.module.dependencies
+                if hasattr(annotations.module, 'assumptions') and annotations.module.assumptions:
+                    module_dict['assumptions'] = annotations.module.assumptions
+                if hasattr(annotations.module, 'invariants') and annotations.module.invariants:
+                    module_dict['invariants'] = annotations.module.invariants
+                if hasattr(annotations.module, 'security_model') and annotations.module.security_model:
+                    module_dict['security_model'] = annotations.module.security_model
+                if hasattr(annotations.module, 'performance_model') and annotations.module.performance_model:
+                    module_dict['performance_model'] = annotations.module.performance_model
+                
+                if module_dict:
+                    darkarts = convert_voodocs_to_darkarts(module_dict)
+                    converted_annotations.append(('module', darkarts, 0))
+            
+            # Convert function-level annotations
+            for func in annotations.module.functions:
+                func_dict = {}
+                
+                if hasattr(func, 'preconditions') and func.preconditions:
+                    func_dict['preconditions'] = func.preconditions
+                if hasattr(func, 'postconditions') and func.postconditions:
+                    func_dict['postconditions'] = func.postconditions
+                if hasattr(func, 'invariants') and func.invariants:
+                    func_dict['invariants'] = func.invariants
+                if hasattr(func, 'security_implications') and func.security_implications:
+                    func_dict['security_implications'] = func.security_implications
+                if hasattr(func, 'complexity') and func.complexity:
+                    # Convert ComplexityAnnotation to string
+                    if hasattr(func.complexity, 'time'):
+                        func_dict['complexity'] = func.complexity.time
+                    else:
+                        func_dict['complexity'] = str(func.complexity)
+                
+                if func_dict:
+                    darkarts = convert_voodocs_to_darkarts(func_dict)
+                    converted_annotations.append(('function', darkarts, func.line_number if hasattr(func, 'line_number') else 0))
+            
+            # Convert class-level annotations
+            for cls in annotations.module.classes:
+                cls_dict = {}
+                
+                if hasattr(cls, 'invariants') and cls.invariants:
+                    cls_dict['invariants'] = cls.invariants
+                if hasattr(cls, 'assumptions') and cls.assumptions:
+                    cls_dict['assumptions'] = cls.assumptions
+                
+                if cls_dict:
+                    darkarts = convert_voodocs_to_darkarts(cls_dict)
+                    converted_annotations.append(('class', darkarts, cls.line_number if hasattr(cls, 'line_number') else 0))
+            
+            if not converted_annotations:
+                print("  ⚠️  No convertible annotations found")
+                continue
             
             if in_place:
                 # Replace @voodocs with @darkarts in file
-                # This is a simple replacement - in production would be more sophisticated
-                new_content = content.replace(
-                    '"""@voodocs',
-                    darkarts.replace('"""@darkarts\n', '').replace('\n"""', '')
-                )
+                new_content = _replace_annotations_in_file(content, converted_annotations, language)
                 path.write_text(new_content)
-                print("  ✅ Converted in place")
+                print(f"  ✅ Converted {len(converted_annotations)} annotation(s) in place")
             else:
                 # Print to console
-                print(darkarts)
+                for ann_type, darkarts, line_num in converted_annotations:
+                    print(f"\n  {ann_type.capitalize()} annotation (line {line_num}):")
+                    print(f"  {darkarts}")
         
         except Exception as e:
             print(f"  ❌ Error: {e}")
+            import traceback
+            traceback.print_exc()
         
         print()
     
     return 0
 
 
+
+from darkarts.annotations.types import Language
+
+
+def _replace_annotations_in_file(content: str, converted_annotations: list, language: Language) -> str:
+    """
+    Replace @voodocs annotations with @darkarts in file content.
+    
+    Args:
+        content: Original file content
+        converted_annotations: List of (type, darkarts_text, line_num) tuples
+        language: Programming language
+        
+    Returns:
+        Modified content with @darkarts annotations
+    """
+    # Determine comment syntax based on language
+    if language == Language.PYTHON:
+        voodocs_pattern = r'"""@voodocs\s*(.*?)\s*"""'
+        
+        def create_darkarts(darkarts_text):
+            # darkarts_text already has """@darkarts format
+            return darkarts_text
+    
+    else:  # TypeScript, JavaScript, etc.
+        voodocs_pattern = r'/\*\*@voodocs\s*(.*?)\s*\*/'
+        
+        def create_darkarts(darkarts_text):
+            # Convert Python-style to JS-style
+            lines = darkarts_text.strip().split('\n')
+            if lines and lines[0] == '"""@darkarts':
+                lines[0] = '/**@darkarts'
+            if lines and lines[-1] == '"""':
+                lines[-1] = '*/'
+            return '\n'.join(lines)
+    
+    # Find all @voodocs annotations
+    matches = list(re.finditer(voodocs_pattern, content, re.DOTALL))
+    
+    if not matches:
+        return content
+    
+    # Replace each annotation
+    result = content
+    offset = 0
+    
+    for i, match in enumerate(matches):
+        if i < len(converted_annotations):
+            _, darkarts_text, _ = converted_annotations[i]
+            darkarts_formatted = create_darkarts(darkarts_text)
+            
+            # Calculate positions with offset
+            start = match.start() + offset
+            end = match.end() + offset
+            
+            # Replace
+            result = result[:start] + darkarts_formatted + result[end:]
+            
+            # Update offset
+            offset += len(darkarts_formatted) - (end - start)
+    
+    return result
+
+
 def cmd_darkarts_stats(args):
     """
     Show statistics about DarkArts annotations.

package/lib/darkarts/core/interface.py

@@ -14,7 +14,7 @@ Provides high-level API for problem solving with automatic plugin routing:
 - Explanation generation for solutions
 - Learning mode for pattern recognition
 - Built-in plugin discovery and loading
-""""
+"""
 
 from typing import Any, Dict, List, Optional
 from .plugin import DarkArtsPlugin, PluginInput, PluginOutput, PluginMetadata, PluginError

package/lib/darkarts/core/loader.py

@@ -15,7 +15,7 @@ Dynamic plugin discovery and loading system with support for:
 - Built-in plugin detection
 - Automatic registry integration
 - Plugin validation and error handling
-""""
+"""
 
 import importlib
 import importlib.util

package/lib/darkarts/core/plugin.py

@@ -15,7 +15,7 @@ Defines the base classes and interfaces for the DarkArts plugin system with:
 - Plugin metadata (name, version, description, dependencies, capabilities)
 - Exception hierarchy (ParseError, ExecutionError, PluginError)
 - Lifecycle management (initialization, execution, cleanup)
-""""
+"""
 
 from abc import ABC, abstractmethod
 from dataclasses import dataclass, field

package/lib/darkarts/core/registry.py

@@ -15,7 +15,7 @@ Central registry for plugin lifecycle management with:
 - Plugin enumeration and discovery
 - Thread-safe operations (dict-based)
 - Global singleton registry pattern
-""""
+"""
 
 from typing import Dict, List, Optional
 from .plugin import DarkArtsPlugin, PluginMetadata, PluginError

package/lib/darkarts/exceptions.py

@@ -16,7 +16,7 @@ Structured exception hierarchy for error handling with:
 - Configuration errors (ConfigurationError)
 - File errors (FileNotFoundError)
 - Informative messages (clear guidance for users)
-""""
+"""
 
 
 class VooDocsError(Exception):

package/lib/darkarts/plugins/voodocs/ai_native_plugin.py

@@ -15,7 +15,7 @@ Enhanced documentation plugin supporting:
 - Test generation from annotations (preconditions/postconditions → tests)
 - API specification generation (OpenAPI from annotations)
 - Multi-format output (docs, tests, specs)
-""""
+"""
 
 from darkarts.core import (
     DarkArtsPlugin,

package/lib/darkarts/plugins/voodocs/annotation_validator.py

@@ -15,7 +15,7 @@ Quality assurance for @voodocs annotations with:
 - Complexity notation validation (Big-O format)
 - Security model checking (valid security declarations)
 - Best practice recommendations (suggestions for improvement)
-""""
+"""
 
 from typing import List, Dict, Any, Optional
 from darkarts.annotations.types import ParsedAnnotations, FunctionAnnotation, ClassAnnotation

package/lib/darkarts/plugins/voodocs/api_spec_generator.py

@@ -15,7 +15,7 @@ Automatic API specification generation from @voodocs annotations with:
 - Parameter extraction (from preconditions)
 - Response schema generation (from postconditions)
 - Error documentation (from error_cases)
-""""
+"""
 
 from typing import List, Optional, Dict, Any
 from pathlib import Path

package/lib/darkarts/plugins/voodocs/documentation_generator.py

@@ -15,7 +15,7 @@ Translates @voodocs annotations (DarkArts language) into human-readable document
 - Complexity notation explanation (Big-O → plain English)
 - Security model documentation (clear security implications)
 - Cross-reference generation (links between related items)
-""""
+"""
 
 from typing import List, Optional, Dict
 from pathlib import Path

package/lib/darkarts/plugins/voodocs/html_exporter.py

@@ -15,7 +15,7 @@ Markdown to HTML conversion with styling:
 - Responsive CSS (mobile-friendly styling)
 - Full HTML document wrapping (complete pages)
 - Graceful degradation (basic conversion if markdown lib unavailable)
-""""
+"""
 
 from pathlib import Path
 from typing import Optional

package/lib/darkarts/plugins/voodocs/pdf_exporter.py

@@ -15,7 +15,7 @@ Markdown to PDF conversion with print-ready formatting:
 - Embedded fonts and styling (professional appearance)
 - Multi-method fallback (tries multiple libraries)
 - Error handling (clear messages if dependencies missing)
-""""
+"""
 
 from pathlib import Path
 from typing import Optional

package/lib/darkarts/plugins/voodocs/test_generator.py

@@ -15,7 +15,7 @@ Automatic test generation from @voodocs annotations with:
 - Error case tests (ensure proper error handling)
 - Property-based tests (Hypothesis/QuickCheck-style)
 - Multi-framework support (pytest, unittest, jest, junit)
-""""
+"""
 
 from typing import List, Optional, Dict, Any, Tuple
 from pathlib import Path

package/lib/darkarts/telemetry.py

@@ -15,7 +15,7 @@ Privacy-respecting anonymous usage analytics with:
 - Supabase backend (anonymous data storage)
 - Fail-silent network (no impact on user experience if offline)
 - First-run notice (transparent disclosure to users)
-""""
+"""
 
 import os
 import sys

package/package.json

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