@voodocs/cli 0.4.2 → 1.0.0

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

package/lib/darkarts/core/registry.py

@@ -1,6 +1,21 @@
-"""
+"""@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
 from .plugin import DarkArtsPlugin, PluginMetadata, PluginError

package/lib/darkarts/exceptions.py

@@ -1,8 +1,22 @@
-"""
+"""@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)
+""""
 
 
 class VooDocsError(Exception):

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,10 +1,21 @@
-"""
+"""@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 (
     DarkArtsPlugin,

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

@@ -1,8 +1,21 @@
-"""
+"""@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
 from darkarts.annotations.types import ParsedAnnotations, FunctionAnnotation, ClassAnnotation

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

@@ -1,8 +1,21 @@
-"""
+"""@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
 from pathlib import Path

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

@@ -1,8 +1,21 @@
-"""
+"""@darkarts
+⊢doc-generator:plugins.translation
+∂{typing,pathlib,re,darkarts.annotations.types}
+⚠{python≥3.7,annotations:parsed,output-dir:writable}
+⊨{∀generate→markdown-docs,∀translate→natural-language,∀symbol→readable,¬modify-annotations,idempotent:same-input→same-output}
+🔒{read-only:annotations,write:docs-dir,¬network,¬exec}
+⚡{O(n)|n=annotations,translation:linear}
+
 VooDocs Documentation Generator
 
-Translates @voodocs annotations (using the DarkArts language) into human-readable documentation.
-"""
+Translates @voodocs annotations (DarkArts language) into human-readable documentation with:
+- Mathematical symbol translation (∀, ∃, ∈, → natural language)
+- Markdown generation (structured documentation)
+- Multi-section output (module, classes, functions)
+- 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

@@ -1,8 +1,21 @@
-"""
+"""@darkarts
+⊢html-exporter:plugins.export
+∂{pathlib,typing}
+⚠{python≥3.7,markdown:optional,input-file:exists}
+⊨{∀export→html-file,∀markdown→html,¬modify-source,fallback:basic-conversion,styled:css-included}
+🔒{read:markdown-files,write:html-files,¬network,¬exec}
+⚡{O(n)|n=markdown-length,conversion:linear}
+
 VooDocs HTML Exporter
 
-Exports documentation to HTML format with styling.
-"""
+Markdown to HTML conversion with styling:
+- Markdown parsing (markdown library or fallback)
+- Syntax highlighting (code blocks with CodeHilite)
+- Table support (GitHub-flavored Markdown tables)
+- 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/instruction_generator.py

@@ -4,7 +4,7 @@
 ⚠{ai∈{cursor,claude,copilot,windsurf},format:markdown,@voodocs:taught}
 ⊨{∀gen→valid-format,∀gen→assistant-specific,∀gen→include-examples}
 🔒{write:config-files}
-⚡{O(1)|template-based}
+⚡{O(n):instruction-generation|template-based}
 
 VooDocs AI Instruction Generator
 

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

@@ -1,8 +1,21 @@
-"""
+"""@darkarts
+⊢pdf-exporter:plugins.export
+∂{pathlib,typing,subprocess,weasyprint,darkarts.plugins.voodocs.html_exporter}
+⚠{python≥3.7,weasyprint|markdown-pdf:installed,input-file:exists}
+⊨{∀export→pdf-file,∀markdown→pdf,¬modify-source,fallback-chain:weasyprint→markdown-pdf,print-ready:formatted}
+🔒{read:markdown-files,write:pdf-files,¬network,¬exec}
+⚡{O(n)|n=markdown-length,pdf-rendering:depends-on-lib}
+
 VooDocs PDF Exporter
 
-Exports documentation to PDF format.
-"""
+Markdown to PDF conversion with print-ready formatting:
+- WeasyPrint support (HTML → PDF with CSS)
+- Markdown-PDF fallback (alternative PDF generation)
+- Print-optimized layout (page breaks, margins)
+- 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

@@ -1,8 +1,21 @@
-"""
+"""@darkarts
+⊢test-generator:plugins.test-automation
+∂{typing,pathlib,re,darkarts.annotations.types}
+⚠{python≥3.7,annotations:parsed,framework:supported}
+⊨{∀generate→test-code,∀precondition→test-case,∀postcondition→assertion,¬modify-annotations,executable:valid-syntax}
+🔒{read-only:annotations,write:test-files,¬network,¬exec}
+⚡{O(n)|n=functions,codegen:linear}
+
 VooDocs Test Generator
 
-Generates automated test cases from @voodocs annotations, including property-based tests.
-"""
+Automatic test generation from @voodocs annotations with:
+- Precondition tests (validate inputs match declared constraints)
+- Postcondition tests (verify outputs satisfy guarantees)
+- Invariant tests (check state consistency)
+- 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

@@ -1,8 +1,21 @@
-"""
+"""@darkarts
+⊢telemetry:analytics.privacy-first
+∂{os,sys,json,uuid,platform,datetime,pathlib,typing,urllib}
+⚠{python≥3.7,network:optional,config-dir:writable}
+⊨{∀track→async-send,∀event:anonymous,∀user:opt-out-respected,¬pii,fail-silent:network-errors}
+🔒{⚠️NETWORK:supabase-api,write:config-dir,¬sensitive-data,anonymous-only}
+⚡{O(1):event-creation,network:async-non-blocking}
+
 VooDocs Telemetry Client
 
-Privacy-respecting anonymous telemetry for usage analytics.
-"""
+Privacy-respecting anonymous usage analytics with:
+- Anonymous session IDs (UUID-based, no PII)
+- Opt-out support (VOODOCS_TELEMETRY_DISABLED env var)
+- Event tracking (command usage, errors, performance)
+- 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