@voodocs/cli 0.4.2 → 1.0.1

package/lib/darkarts/cli_darkarts.py

@@ -4,7 +4,7 @@
 ⚠{files-exist,valid-paths}
 ⊨{∀cmd→exit∈{0,1},user-friendly-errors}
 🔒{read-write-files}
-⚡{O(n)|n=files}
+⚡{O(n³)|n=files,11-loops,depth=4}
 
 DarkArts CLI Commands
 
@@ -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/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,5 +1,19 @@
-"""
+"""@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

package/lib/darkarts/core/loader.py

@@ -1,5 +1,20 @@
-"""
+"""@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

package/lib/darkarts/core/plugin.py

@@ -1,7 +1,20 @@
-"""
+"""@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

package/lib/darkarts/core/registry.py

@@ -1,5 +1,20 @@
-"""
+"""@darkarts
+⊢registry:core.plugin-management
+∂{typing,darkarts.core.plugin}
+⚠{python≥3.7,plugins:valid-metadata}
+⊨{∀register→unique-name|PluginError,∀get→plugin|None,∀unregister→removed,¬duplicate-names,∀deps→satisfied-before-register,thread-safe:dict-ops}
+🔒{read-write:registry-only,¬file-io,¬network,in-memory-only}
+⚡{O(1):register-get-unregister,O(n):list|n=plugin-count,dict-based}
+
 Plugin registry for managing and discovering plugins.
+
+Central registry for plugin lifecycle management with:
+- Plugin registration with uniqueness enforcement
+- Dependency validation (plugins must register dependencies first)
+- Plugin lookup by name or capability
+- Plugin enumeration and discovery
+- Thread-safe operations (dict-based)
+- Global singleton registry pattern
 """
 
 from typing import Dict, List, Optional

package/lib/darkarts/exceptions.py

@@ -1,7 +1,21 @@
-"""
+"""@darkarts
+⊢exceptions:errors.hierarchy
+∂{}
+⚠{python≥3.7}
+⊨{∀exception:VooDocsError-subclass,∀error→informative-message,hierarchy:base→specific,catchable:by-type}
+🔒{pure-exceptions,¬io,¬side-effects,¬exec}
+⚡{O(1):exception-creation}
+
 VooDocs Custom Exceptions
 
-Provides specific exception types for better error handling and user feedback.
+Structured exception hierarchy for error handling with:
+- Base exception (VooDocsError for all VooDocs errors)
+- Parser errors (ParserError, ParserNotBuiltError, AnnotationError)
+- Validation errors (InvalidAnnotationError, ValidationError)
+- Generator errors (GeneratorError)
+- Configuration errors (ConfigurationError)
+- File errors (FileNotFoundError)
+- Informative messages (clear guidance for users)
 """
 
 

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

@@ -1,6 +1,16 @@
+"""@darkarts
+⊢init:plugins.voodocs.package
+∂{}
+⚠{python≥3.7}
+⊨{∀import→exports-available,namespace:clean,¬side-effects-on-import}
+🔒{pure-init,¬io,¬network,¬exec}
+⚡{O(n²):plugin-initialization|10-loops,depth=2}
+
+Package initialization for plugins.voodocs.
+
+Module exports and namespace configuration.
 """
-Code Documentation Plugin for DarkArts - Automated documentation generation.
-"""
+
 
 import ast
 import re

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

@@ -1,9 +1,20 @@
-"""
+"""@darkarts
+⊢ai-voodocs-plugin:plugins.documentation
+∂{darkarts.core,darkarts.annotations,darkarts.plugins.voodocs.documentation_generator,darkarts.plugins.voodocs.test_generator,darkarts.plugins.voodocs.api_spec_generator}
+⚠{python≥3.7,source-code:parseable,annotations:@voodocs-format}
+⊨{∀parse→annotations-extracted,∀execute→docs-generated,∀analyze→insights,¬modify-source,idempotent:same-input→same-output}
+🔒{read-only:source,write:docs-output,¬network,¬arbitrary-exec}
+⚡{O(n)|n=source-lines,ast-parsing:linear}
+
 AI-Native VooDocs Plugin for DarkArts
 
-Enhanced version that supports both:
-1. Traditional code documentation (AST-based)
-2. AI-native documentation (@voodocs annotations)
+Enhanced documentation plugin supporting:
+- @voodocs annotation parsing (AI-native documentation)
+- Traditional AST-based documentation (fallback)
+- Automatic documentation generation (Markdown, HTML, PDF)
+- Test generation from annotations (preconditions/postconditions → tests)
+- API specification generation (OpenAPI from annotations)
+- Multi-format output (docs, tests, specs)
 """
 
 from darkarts.core import (

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

@@ -1,7 +1,20 @@
-"""
+"""@darkarts
+⊢validator:plugins.quality-assurance
+∂{typing,darkarts.annotations.types,re}
+⚠{python≥3.7,annotations:parsed}
+⊨{∀validate→issues-list,∀issue:categorized,∀severity:error|warning|info,¬modify-annotations,comprehensive:all-rules-checked}
+🔒{read-only:annotations,¬file-io,¬network,¬exec}
+⚡{O(n)|n=annotations,validation:linear}
+
 VooDocs Annotation Validator
 
-Validates @voodocs annotations for correctness and quality.
+Quality assurance for @voodocs annotations with:
+- Syntax validation (correct format and structure)
+- Completeness checking (required fields present)
+- Consistency verification (invariants don't contradict postconditions)
+- 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

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

@@ -1,7 +1,20 @@
-"""
+"""@darkarts
+⊢api-spec-generator:plugins.api-documentation
+∂{typing,pathlib,json,yaml,darkarts.annotations.types}
+⚠{python≥3.7,annotations:parsed,format:supported}
+⊨{∀generate→api-spec,∀function→endpoint,∀annotation→schema,¬modify-annotations,valid-spec:parseable}
+🔒{read-only:annotations,write:spec-files,¬network,¬exec}
+⚡{O(n)|n=functions,spec-generation:linear}
+
 DarkArts API Specification Generator
 
-Generates OpenAPI/Swagger specifications from DarkArts annotations.
+Automatic API specification generation from @voodocs annotations with:
+- OpenAPI 3.0 generation (industry-standard REST API specs)
+- Swagger support (compatible with Swagger UI)
+- GraphQL schema generation (type-safe API definitions)
+- Parameter extraction (from preconditions)
+- Response schema generation (from postconditions)
+- Error documentation (from error_cases)
 """
 
 from typing import List, Optional, Dict, Any