@voodocs/cli 0.4.1 → 1.0.0

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

package/lib/darkarts/validation/README.md

@@ -0,0 +1,147 @@
+# DarkArts Validation Module
+
+**Phase 1: Foundation - Complete** ✅
+
+This module provides validation tools for @darkarts annotations.
+
+## Overview
+
+The validation module ensures that @darkarts annotations are accurate and up-to-date by:
+- **Semantic Validation**: Verifying dependencies match actual imports
+- **Performance Validation**: Checking complexity claims match code structure  
+- **Benchmarking**: Measuring actual performance to validate claims
+- **Auto-fix**: Automatically correcting validation issues
+
+## Installation
+
+The validation module is part of the VooDocs package:
+
+```bash
+pip install voodocs
+```
+
+## Usage
+
+### Semantic Validation
+
+```python
+from darkarts.validation import SemanticValidator
+
+validator = SemanticValidator()
+
+# Validate a single file
+result = validator.validate_file("myfile.py")
+if not result.is_valid:
+    print(f"Missing dependencies: {result.missing_deps}")
+    print(f"Extra dependencies: {result.extra_deps}")
+
+# Validate a directory
+results = validator.validate_directory("lib/", recursive=True)
+valid_count = sum(1 for r in results if r.is_valid)
+print(f"Valid: {valid_count}/{len(results)}")
+```
+
+### Performance Validation
+
+```python
+from darkarts.validation import PerformanceTracker
+
+tracker = PerformanceTracker()
+
+# Analyze a file
+result = tracker.analyze_file("myfile.py")
+print(f"Claimed: {result.claimed_complexity}")
+print(f"Actual: {result.actual_complexity}")
+print(f"Valid: {result.is_valid}")
+```
+
+### Benchmarking
+
+```python
+from darkarts.validation import BenchmarkSuite
+
+suite = BenchmarkSuite()
+
+# Run benchmarks
+config = {
+    "critical_paths": ["mymodule.core.process"],
+    "sizes": [10, 100, 1000],
+}
+results = suite.run_benchmarks(config)
+```
+
+## API Reference
+
+### SemanticValidator
+
+- `validate_file(file_path)` - Validate a single file
+- `validate_directory(directory, recursive=True)` - Validate all files in directory
+- `validate_path(path, recursive=False)` - Validate file or directory
+
+### PerformanceTracker
+
+- `analyze_file(file_path)` - Analyze a single file
+- `analyze_directory(directory, recursive=True)` - Analyze all files in directory
+
+### BenchmarkSuite
+
+- `run_benchmarks(config)` - Run benchmarks based on configuration
+
+## Module Structure
+
+```
+validation/
+├── __init__.py              # Public API
+├── semantic.py              # Semantic validation (functional)
+├── semantic_wrapper.py      # SemanticValidator class
+├── performance.py           # Performance tracking (functional)
+├── performance_wrapper.py   # PerformanceTracker class
+├── benchmark.py             # Benchmarking (functional)
+├── benchmark_wrapper.py     # BenchmarkSuite class
+├── autofix.py               # Auto-fix functionality
+├── config.py                # Configuration management
+├── watch.py                 # Watch mode
+├── types.py                 # Shared type definitions
+├── test_validation.py       # Unit tests
+└── README.md                # This file
+```
+
+## Design Principles
+
+1. **Functional Core**: Core validation logic is functional (pure functions)
+2. **OOP Wrapper**: Object-oriented API for ease of use
+3. **No CLI**: CLI removed - use `voodocs` CLI instead
+4. **Lazy Loading**: Modules loaded on-demand for fast startup
+5. **Type Safety**: Full type hints for better IDE support
+
+## Next Steps
+
+**Phase 2**: CLI Integration (Week 2)
+- Integrate into `voodocs` CLI
+- Add `voodocs validate` command
+- Add `--validate` flag to `voodocs generate`
+
+**Phase 3**: Advanced Features (Week 3)
+- Watch mode integration
+- Configuration file support
+- HTML/JSON reports
+
+## Testing
+
+Run tests:
+
+```bash
+# Unit tests
+python3 -m pytest lib/darkarts/validation/test_validation.py
+
+# With coverage
+python3 -m pytest lib/darkarts/validation/test_validation.py --cov=darkarts.validation
+```
+
+## Contributing
+
+See `../../docs/darkarts/CODE_REVIEW_PROCESS.md` for contribution guidelines.
+
+## License
+
+Part of VooDocs - see repository root for license.

package/lib/darkarts/validation/__init__.py

@@ -0,0 +1,91 @@
+"""@darkarts
+⊢ validation:api
+∂{typing}
+⚠{
+  - Python ≥3.7
+  - Validation modules available
+}
+⊨{
+  - Public API is stable
+  - All validators are importable
+  - Version compatibility maintained
+}
+🔒{
+  - Read-only validation operations
+  - No side effects except file writes in fix mode
+  - Safe for concurrent use
+}
+⚡{O(n):import-time|n=lazy-loaded-modules}
+"""
+
+"""
+DarkArts Validation Module
+
+This module provides validation tools for @darkarts annotations:
+- SemanticValidator: Validates dependencies match imports
+- PerformanceTracker: Validates complexity claims
+- BenchmarkSuite: Benchmarks performance with real data
+- AutoFix: Automatically fixes validation issues
+- Config: Configuration management
+
+Public API:
+    from darkarts.validation import (
+        SemanticValidator,
+        PerformanceTracker,
+        BenchmarkSuite,
+        AutoFix,
+        Config,
+    )
+"""
+
+from typing import TYPE_CHECKING
+
+__version__ = "1.0.0"
+__all__ = [
+    "SemanticValidator",
+    "PerformanceTracker",
+    "BenchmarkSuite",
+    "AutoFix",
+    "Config",
+    "ValidationResult",
+    "PerformanceResult",
+    "BenchmarkResult",
+]
+
+# Lazy imports to avoid circular dependencies and improve startup time
+if TYPE_CHECKING:
+    from .semantic import SemanticValidator
+    from .performance import PerformanceTracker
+    from .benchmark import BenchmarkSuite
+    from .autofix import AutoFix
+    from .config import Config
+    from .types import ValidationResult, PerformanceResult, BenchmarkResult
+
+
+def __getattr__(name: str):
+    """Lazy import for better startup performance."""
+    if name == "SemanticValidator":
+        from .semantic_wrapper import SemanticValidator
+        return SemanticValidator
+    elif name == "PerformanceTracker":
+        from .performance_wrapper import PerformanceTracker
+        return PerformanceTracker
+    elif name == "BenchmarkSuite":
+        from .benchmark_wrapper import BenchmarkSuite
+        return BenchmarkSuite
+    elif name == "AutoFix":
+        from .autofix import AutoFix
+        return AutoFix
+    elif name == "Config":
+        from .config import Config
+        return Config
+    elif name == "ValidationResult":
+        from .types import ValidationResult
+        return ValidationResult
+    elif name == "PerformanceResult":
+        from .types import PerformanceResult
+        return PerformanceResult
+    elif name == "BenchmarkResult":
+        from .types import BenchmarkResult
+        return BenchmarkResult
+    raise AttributeError(f"module {__name__!r} has no attribute {name!r}")