@voodocs/cli 0.4.1 → 1.0.0

package/lib/darkarts/cli_darkarts.py

@@ -0,0 +1,385 @@
+"""@darkarts
+⊢cli:darkarts.commands
+∂{argparse,pathlib,annotations}
+⚠{files-exist,valid-paths}
+⊨{∀cmd→exit∈{0,1},user-friendly-errors}
+🔒{read-write-files}
+⚡{O(n³)|n=files,11-loops,depth=4}
+
+DarkArts CLI Commands
+
+Provides CLI commands for DarkArts symbolic documentation.
+"""
+
+import sys
+from pathlib import Path
+from typing import List, Optional
+
+from darkarts.annotations import (
+    parse_darkarts,
+    DarkArtsParser,
+    DarkArtsTranslator,
+    convert_voodocs_to_darkarts,
+)
+from darkarts.annotations.parser import AnnotationParser
+
+
+def cmd_darkarts_translate(args):
+    """
+    Translate DarkArts annotations to natural language or vice versa.
+    
+    Usage:
+        voodocs darkarts translate <files> [--to-symbols]
+    """
+    print("🔮 DarkArts Translation")
+    print("=" * 60)
+    print()
+    
+    translator = DarkArtsTranslator()
+    to_symbols = args.to_symbols if hasattr(args, 'to_symbols') else False
+    
+    for file_path in args.files:
+        path = Path(file_path)
+        
+        if not path.exists():
+            print(f"❌ File not found: {file_path}")
+            continue
+        
+        print(f"📄 {path.name}")
+        print("-" * 60)
+        
+        try:
+            if to_symbols:
+                # Natural language → Symbols (VooDocs → DarkArts)
+                parser = AnnotationParser()
+                annotations = parser.parse_file(str(path))
+                
+                if annotations.module:
+                    # Convert module annotation
+                    voodocs_dict = {
+                        'module_purpose': annotations.module.module_purpose,
+                        'dependencies': annotations.module.dependencies,
+                        'assumptions': annotations.module.assumptions,
+                    }
+                    
+                    darkarts = convert_voodocs_to_darkarts(voodocs_dict)
+                    print(darkarts)
+                else:
+                    print("⚠️  No @voodocs annotations found")
+            else:
+                # Symbols → Natural language (DarkArts → Human)
+                darkarts_annotations = parse_darkarts(path.read_text())
+                
+                if darkarts_annotations:
+                    for i, ann in enumerate(darkarts_annotations, 1):
+                        if len(darkarts_annotations) > 1:
+                            print(f"\n## Annotation {i}\n")
+                        natural = translator.symbols_to_natural(ann)
+                        print(natural)
+                else:
+                    print("⚠️  No @darkarts annotations found")
+        
+        except Exception as e:
+            print(f"❌ Error: {e}")
+        
+        print()
+    
+    return 0
+
+
+def cmd_darkarts_convert(args):
+    """
+    Convert files between VooDocs and DarkArts formats.
+    
+    Usage:
+        voodocs darkarts convert <files> [--in-place]
+    """
+    print("🔄 DarkArts Conversion")
+    print("=" * 60)
+    print()
+    
+    translator = DarkArtsTranslator()
+    in_place = args.in_place if hasattr(args, 'in_place') else False
+    
+    for file_path in args.files:
+        path = Path(file_path)
+        
+        if not path.exists():
+            print(f"❌ File not found: {file_path}")
+            continue
+        
+        print(f"📄 {path.name}")
+        
+        try:
+            content = path.read_text()
+            
+            # Parse VooDocs annotations
+            parser = AnnotationParser()
+            annotations = parser.parse_file(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,
+            }
+            
+            darkarts = convert_voodocs_to_darkarts(voodocs_dict)
+            
+            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"""', '')
+                )
+                path.write_text(new_content)
+                print("  ✅ Converted in place")
+            else:
+                # Print to console
+                print(darkarts)
+        
+        except Exception as e:
+            print(f"  ❌ Error: {e}")
+        
+        print()
+    
+    return 0
+
+
+def cmd_darkarts_stats(args):
+    """
+    Show statistics about DarkArts annotations.
+    
+    Usage:
+        voodocs darkarts stats <paths>
+    """
+    print("📊 DarkArts Statistics")
+    print("=" * 60)
+    print()
+    
+    total_files = 0
+    files_with_darkarts = 0
+    total_annotations = 0
+    total_symbols = 0
+    symbol_counts = {}
+    
+    paths = args.paths if hasattr(args, 'paths') else ['.']
+    
+    for path_str in paths:
+        path = Path(path_str)
+        
+        if path.is_file():
+            files = [path]
+        elif path.is_dir():
+            files = list(path.rglob('*.py'))
+        else:
+            continue
+        
+        for file_path in files:
+            total_files += 1
+            
+            try:
+                content = file_path.read_text()
+                annotations = parse_darkarts(content)
+                
+                if annotations:
+                    files_with_darkarts += 1
+                    total_annotations += len(annotations)
+                    
+                    # Count symbols
+                    for ann in annotations:
+                        for char in ann.raw_text:
+                            if char in ['⊢', '∂', '⚠', '⊨', '🔒', '⚡', '∀', '∃', '∧', '∨', '¬', '⇒', '∈']:
+                                symbol_counts[char] = symbol_counts.get(char, 0) + 1
+                                total_symbols += 1
+            
+            except Exception:
+                pass
+    
+    # Print statistics
+    print(f"Total files scanned: {total_files}")
+    print(f"Files with @darkarts: {files_with_darkarts}")
+    print(f"Total annotations: {total_annotations}")
+    print(f"Total symbols used: {total_symbols}")
+    
+    if symbol_counts:
+        print("\nMost used symbols:")
+        sorted_symbols = sorted(symbol_counts.items(), key=lambda x: x[1], reverse=True)
+        for symbol, count in sorted_symbols[:10]:
+            print(f"  {symbol} : {count}")
+    
+    if total_files > 0:
+        coverage = (files_with_darkarts / total_files) * 100
+        print(f"\nCoverage: {coverage:.1f}%")
+    
+    print()
+    return 0
+
+
+def cmd_darkarts_validate(args):
+    """
+    Validate DarkArts annotations.
+    
+    Usage:
+        voodocs darkarts validate <files>
+    """
+    print("✅ DarkArts Validation")
+    print("=" * 60)
+    print()
+    
+    all_valid = True
+    
+    for file_path in args.files:
+        path = Path(file_path)
+        
+        if not path.exists():
+            print(f"❌ File not found: {file_path}")
+            all_valid = False
+            continue
+        
+        print(f"📄 {path.name}")
+        
+        try:
+            content = path.read_text()
+            annotations = parse_darkarts(content)
+            
+            if not annotations:
+                print("  ⚠️  No @darkarts annotations found")
+                continue
+            
+            for i, ann in enumerate(annotations, 1):
+                # Basic validation
+                issues = []
+                
+                if not ann.module:
+                    issues.append("Missing module declaration (⊢)")
+                
+                if not ann.dependencies:
+                    issues.append("Missing dependencies (∂)")
+                
+                if not ann.invariants:
+                    issues.append("Missing invariants (⊨)")
+                
+                if issues:
+                    print(f"  ⚠️  Annotation {i}:")
+                    for issue in issues:
+                        print(f"     - {issue}")
+                    all_valid = False
+                else:
+                    print(f"  ✅ Annotation {i}: Valid")
+        
+        except Exception as e:
+            print(f"  ❌ Error: {e}")
+            all_valid = False
+        
+        print()
+    
+    return 0 if all_valid else 1
+
+
+def add_darkarts_subcommands(subparsers):
+    """
+    Add DarkArts subcommands to VooDocs CLI.
+    
+    Args:
+        subparsers: Argparse subparsers object
+    """
+    # darkarts command group
+    darkarts_parser = subparsers.add_parser(
+        "darkarts",
+        help="DarkArts symbolic documentation tools"
+    )
+    darkarts_subparsers = darkarts_parser.add_subparsers(
+        dest="darkarts_action",
+        help="DarkArts actions"
+    )
+    
+    # darkarts translate
+    translate_parser = darkarts_subparsers.add_parser(
+        "translate",
+        help="Translate between symbols and natural language"
+    )
+    translate_parser.add_argument(
+        "files",
+        nargs="+",
+        help="Files to translate"
+    )
+    translate_parser.add_argument(
+        "--to-symbols",
+        action="store_true",
+        help="Translate from natural language to symbols (default: symbols to natural)"
+    )
+    
+    # darkarts convert
+    convert_parser = darkarts_subparsers.add_parser(
+        "convert",
+        help="Convert VooDocs annotations to DarkArts"
+    )
+    convert_parser.add_argument(
+        "files",
+        nargs="+",
+        help="Files to convert"
+    )
+    convert_parser.add_argument(
+        "--in-place",
+        action="store_true",
+        help="Modify files in place (default: print to console)"
+    )
+    
+    # darkarts stats
+    stats_parser = darkarts_subparsers.add_parser(
+        "stats",
+        help="Show DarkArts usage statistics"
+    )
+    stats_parser.add_argument(
+        "paths",
+        nargs="*",
+        default=["."],
+        help="Paths to analyze (default: current directory)"
+    )
+    
+    # darkarts validate
+    validate_parser = darkarts_subparsers.add_parser(
+        "validate",
+        help="Validate DarkArts annotations"
+    )
+    validate_parser.add_argument(
+        "files",
+        nargs="+",
+        help="Files to validate"
+    )
+    
+    return darkarts_parser
+
+
+def dispatch_darkarts_command(args):
+    """
+    Dispatch DarkArts subcommands.
+    
+    Args:
+        args: Parsed command-line arguments
+        
+    Returns:
+        Exit code (0 for success, 1 for error)
+    """
+    if not hasattr(args, 'darkarts_action') or not args.darkarts_action:
+        print("Error: No DarkArts action specified")
+        print("Use 'voodocs darkarts --help' for usage")
+        return 1
+    
+    if args.darkarts_action == "translate":
+        return cmd_darkarts_translate(args)
+    elif args.darkarts_action == "convert":
+        return cmd_darkarts_convert(args)
+    elif args.darkarts_action == "stats":
+        return cmd_darkarts_stats(args)
+    elif args.darkarts_action == "validate":
+        return cmd_darkarts_validate(args)
+    else:
+        print(f"Error: Unknown DarkArts action: {args.darkarts_action}")
+        return 1

package/lib/darkarts/context/__init__.py

@@ -1,9 +1,17 @@
-"""
-VooDocs Context System
+"""@darkarts
+⊢init:context.package
+∂{}
+⚠{python≥3.7}
+⊨{∀import→exports-available,namespace:clean,¬side-effects-on-import}
+🔒{pure-init,¬io,¬network,¬exec}
+⚡{O(1):import-time}
+
+Package initialization for context.
 
-A structured, machine-readable knowledge base for software projects.
+Module exports and namespace configuration.
 """
 
+
 from .models import (
     ContextFile,
     Versioning,

package/lib/darkarts/context/ai_integrations.py

@@ -1,24 +1,10 @@
-"""@voodocs
-module_purpose: "Native AI assistant integrations (Claude, Cursor, Copilot, Windsurf, Cline)"
-dependencies: [
-    "pathlib: File path handling",
-    "typing: Type hints"
-]
-assumptions: [
-    "AI config directories follow standard conventions (.claude/skills/, .cursor/rules/, etc.)",
-    "Project root is current working directory",
-    "File system allows directory creation",
-    "UTF-8 encoding is supported"
-]
-invariants: [
-    "All generated configs must be valid for their respective AIs",
-    "Detection must not modify any files",
-    "Generated content must be UTF-8 encoded",
-    "File paths must use forward slashes for cross-platform compatibility",
-    "Each AI integration must return Dict[str, str] mapping paths to content"
-]
-security_model: "Read-only detection, write only when explicitly called by user commands"
-performance_model: "O(1) for detection, O(k) for generation where k=number of AI assistants"
+"""@darkarts
+⊢ai-integrations:context.ai-native
+∂{pathlib,typing}
+⚠{ai-dirs:standard-conventions,cwd:project-root,fs:writable,encoding:utf8}
+⊨{∀config→valid-for-ai,∀detect→¬modify-files,∀content:utf8,∀path:forward-slash,∀integration→Dict[str,str]}
+🔒{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.
 

package/lib/darkarts/context/commands.py

@@ -4,7 +4,7 @@
 ⚠{.voodocs.context∈root,git:available,py≥3.11,cwd=root}
 ⊨{ctx:yaml,v∈semver,exit∈{0,1},∀update→v++,files:utf8}
 🔒{read:ctx,write⊳confirm}
-⚡{O(1)|most-cmds,O(n)|generate:n=src-files}
+⚡{O(n³):typical-nested-loops,worst-case:O(2^n):recursion-detected|32-loops,depth=3}
 
 Context System Commands
 

package/lib/darkarts/context/diagram.py

@@ -1,28 +1,14 @@
-"""@voodocs
-module_purpose: "Architecture diagram generation from context (Mermaid and D2 formats)"
-dependencies: [
-    "subprocess: External diagram rendering (manus-render-diagram)",
-    "pathlib: File path handling",
-    "typing: Type hints"
-]
-assumptions: [
-    "Context file contains architecture.modules section",
-    "manus-render-diagram utility is available for PNG rendering",
-    "Output directory is writable",
-    "Mermaid/D2 syntax is valid"
-]
-invariants: [
-    "Generated diagrams must be valid Mermaid or D2 syntax",
-    "Module names must be sanitized for diagram syntax",
-    "Diagram generation must not modify context file",
-    "PNG rendering is optional and fails gracefully if utility unavailable"
-]
-security_model: "Read context file, write diagram files to user-specified paths"
-performance_model: "O(n) where n=number of modules, O(n^2) for dependency graphs"
+"""@darkarts
+⊢diagram:context.visualization
+∂{subprocess,pathlib,typing}
+⚠{context:has-architecture-modules,manus-render-diagram:available,output-dir:writable,syntax:valid-mermaid-d2}
+⊨{∀diagram→valid-syntax,∀module-name:sanitized,¬modify-context,∀png-render→graceful-fail}
+🔒{read:context-file,write:diagram-files}
+⚡{O(n³):dependency-graph-generation|13-loops,depth=3}
 
 Architecture Diagram Generator
 
-Generates visual diagrams from context files.
+Generates visual diagrams from context files in Mermaid and D2 formats.
 """
 
 import subprocess

package/lib/darkarts/context/models.py

@@ -1,25 +1,10 @@
-"""@voodocs
-module_purpose: "Data structures for VooDocs context system (dataclasses for all context entities)"
-dependencies: [
-    "dataclasses: Python dataclass decorator",
-    "typing: Type hints for optional and complex types",
-    "datetime: Date handling"
-]
-assumptions: [
-    "Python 3.7+ with dataclasses support",
-    "All dates are ISO 8601 format (YYYY-MM-DD)",
-    "Version strings follow semver (major.minor)",
-    "All text fields are UTF-8 strings"
-]
-invariants: [
-    "All dataclasses must be immutable (frozen=False but should not be mutated)",
-    "Optional fields must have None as default",
-    "List fields must use field(default_factory=list)",
-    "Dict fields must use field(default_factory=dict)",
-    "All models must be serializable to dict via asdict()"
-]
-security_model: "Pure data structures, no I/O or side effects"
-performance_model: "O(1) for all operations, lightweight dataclasses"
+"""@darkarts
+⊢models:context.data-structures
+∂{dataclasses,typing,datetime}
+⚠{python≥3.7,dates:iso8601,versions:semver,text:utf8}
+⊨{∀dataclass:quasi-immutable,∀optional→None-default,∀list:default-factory,∀dict:default-factory,∀model→serializable-asdict}
+🔒{pure-data,¬io,¬side-effects}
+⚡{O(n):iteration-serialization|dataclass-operations}
 
 Context System Data Models
 

package/lib/darkarts/context/module_utils.py

@@ -4,7 +4,7 @@
 ⚠{annotations:parsed,paths:relative,extensions:standard}
 ⊨{∀extract→complete-module,language:detected,api:extracted}
 🔒{read-only,¬modify-annotations}
-⚡{O(1)}
+⚡{O(n):module-utilities|3-loops}
 
 Module Extraction Utilities
 

package/lib/darkarts/context/ui.py

@@ -4,7 +4,7 @@
 ⚠{term:ansi,tqdm:installed,users:visual-feedback}
 ⊨{colors→reset,progress→close,confirm→bool,∀output→safe}
 🔒{no-implications}
-⚡{O(1)}
+⚡{O(n²):ui-rendering|4-loops,depth=2}
 
 User Interface Utilities
 

package/lib/darkarts/context/validation.py

@@ -4,7 +4,7 @@
 ⚠{name∈fs-safe,v∈semver,path∈rel∨abs}
 ⊨{∀validate_*→(⊥⇒raise)∧(⊤⇒norm),deterministic,msg:actionable}
 🔒{validate-input,¬injection,¬fs-attack}
-⚡{O(1)|regex-fast-on-short-str}
+⚡{O(n):validation|regex-on-input-strings}
 
 Input Validation Utilities
 

package/lib/darkarts/context/yaml_utils.py

@@ -1,29 +1,14 @@
-"""@voodocs
-module_purpose: "YAML parsing, serialization, and formatting for .voodocs.context files"
-dependencies: [
-    "yaml: PyYAML library for YAML parsing",
-    "pathlib: File path handling",
-    "models: ContextFile and related dataclasses"
-]
-assumptions: [
-    "PyYAML is installed and available",
-    "Files are UTF-8 encoded",
-    "YAML files follow .voodocs.context schema",
-    "File system is readable and writable"
-]
-invariants: [
-    "All YAML output must be valid and parseable",
-    "None values must be represented as empty strings, not 'null'",
-    "Indentation must be 2 spaces",
-    "Dict keys must preserve insertion order",
-    "Architecture decisions and modules must be converted to proper objects"
-]
-security_model: "Read/write context files only, no arbitrary file access"
-performance_model: "O(n/c) for parsing where n=file size, c=10x speedup from LibYAML. Phase 3 optimizations: LibYAML C loader (10x), LRU caching (100x on cache hits), streamlined conversion (3x). Combined: 10-300x faster."
+"""@darkarts
+⊢yaml-utils:context.serialization
+∂{yaml,pathlib,models}
+⚠{pyyaml:installed,encoding:utf8,schema:voodocs-context,fs:read-write}
+⊨{∀yaml-output→valid-parseable,∀None→empty-string,indent:2-spaces,∀dict:preserve-order,∀arch→proper-objects}
+🔒{read-write:context-files-only,¬arbitrary-file-access}
+⚡{O(n/c):parse|n=file-size,c=10x-libyaml,cache:100x-hits,combined:10-300x}
 
 YAML Utilities for Context Files
 
-Handles reading, writing, and formatting of .voodocs.context YAML files.
+Handles reading, writing, and formatting of .voodocs.context YAML files with LibYAML C backend optimization.
 """
 
 import yaml

package/lib/darkarts/core/__init__.py

@@ -1,6 +1,16 @@
+"""@darkarts
+⊢init:core.package
+∂{}
+⚠{python≥3.7}
+⊨{∀import→exports-available,namespace:clean,¬side-effects-on-import}
+🔒{pure-init,¬io,¬network,¬exec}
+⚡{O(1):import-time}
+
+Package initialization for core.
+
+Module exports and namespace configuration.
 """
-DarkArts Core - Domain-agnostic reasoning engine.
-"""
+
 
 from .plugin import (
     DarkArtsPlugin,

package/lib/darkarts/core/interface.py

@@ -1,6 +1,20 @@
-"""
+"""@darkarts
+⊢interface:core.api
+∂{typing,darkarts.core.plugin,darkarts.core.registry,darkarts.core.loader}
+⚠{python≥3.7,plugins:registered,registry:initialized}
+⊨{∀solve→PluginOutput,∀plugin-call→routed-correctly,∀error→PluginError,auto-detect:best-effort,¬modify-registry-during-solve}
+🔒{delegates-to-plugins,plugin-security-dependent,¬direct-file-io}
+⚡{O(1):dispatch,O(p):plugin-execution|p=plugin-complexity}
+
 Unified interface to the DarkArts platform.
-"""
+
+Provides high-level API for problem solving with automatic plugin routing:
+- Problem solving with plugin selection (manual or auto-detect)
+- Plugin management (list, get, register, load)
+- 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

@@ -1,6 +1,21 @@
-"""
+"""@darkarts
+⊢loader:core.plugin-discovery
+∂{importlib,os,sys,pathlib,typing,darkarts.core.plugin,darkarts.core.registry}
+⚠{python≥3.7,fs:readable,modules:importable,plugins:valid-subclass}
+⊨{∀load→DarkArtsPlugin|PluginError,∀register→registry-updated,∀discovery→finds-all-valid,¬modify-source}
+🔒{⚠️EXEC-CODE:import-plugins,read:plugin-dirs,¬network,¬arbitrary-file-write}
+⚡{O(n)|n=plugins,import-overhead:per-plugin}
+
 Plugin loader for discovering and loading plugins.
-"""
+
+Dynamic plugin discovery and loading system with support for:
+- Module-based loading (importlib)
+- File-based loading (from .py files)
+- Directory scanning (auto-discovery)
+- Built-in plugin detection
+- Automatic registry integration
+- Plugin validation and error handling
+""""
 
 import importlib
 import importlib.util

package/lib/darkarts/core/plugin.py

@@ -1,8 +1,21 @@
-"""
+"""@darkarts
+⊢plugin:core.extensibility
+∂{abc,dataclasses,enum,typing}
+⚠{python≥3.7,subclass:implements-abstract-methods}
+⊨{∀plugin:DarkArtsPlugin-subclass,∀metadata:valid-schema,∀input→PluginInput,∀output→PluginOutput,∀abstract-method:must-implement,lifecycle:init→execute→cleanup}
+🔒{interface-only,security:plugin-dependent,¬direct-io}
+⚡{O(1):interface-dispatch,O(p):plugin-implementation|p=plugin-complexity}
+
 Core plugin system for DarkArts.
 
-This module defines the base classes and interfaces for the DarkArts plugin system.
-"""
+Defines the base classes and interfaces for the DarkArts plugin system with:
+- Abstract plugin interface (DarkArtsPlugin base class)
+- Plugin capabilities (parse, analyze, execute, explain, learn, multi-step)
+- Standardized input/output (PluginInput, PluginOutput dataclasses)
+- 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