@voodocs/cli 0.3.1 → 0.4.0

package/lib/darkarts/context/diagram.py

@@ -1,4 +1,25 @@
-"""
+"""@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"
+
 Architecture Diagram Generator
 
 Generates visual diagrams from context files.

package/lib/darkarts/context/errors.py

@@ -0,0 +1,164 @@
+"""@darkarts
+⊢errors:context.helpful
+∂{darkarts.exceptions}
+⚠{users:unfamiliar,msg:actionable,emoji:readable}
+⊨{∀exc→inherit(VooDocsError),∀exc→msg:helpful,∀exc→suggest:recovery,msg:user-friendly∧¬jargon}
+🔒{no-implications}
+⚡{O(1)}
+
+Context System Exceptions
+
+Provides specific exception types for context system operations with
+helpful error messages and recovery suggestions.
+"""
+
+from pathlib import Path
+from typing import Optional
+
+
+# Import base exceptions
+from darkarts.exceptions import VooDocsError, ConfigurationError, ValidationError
+
+
+class ContextFileNotFoundError(ConfigurationError):
+    """Context file not found."""
+    
+    def __init__(self, path: str):
+        self.path = path
+        super().__init__(
+            f"Context file not found: {path}\n\n"
+            f"💡 To create a new context file, run:\n"
+            f"   voodocs context init"
+        )
+
+
+class InvalidContextError(ConfigurationError):
+    """Invalid context file."""
+    
+    def __init__(self, path: str, reason: str):
+        self.path = path
+        self.reason = reason
+        super().__init__(
+            f"Invalid context file: {path}\n"
+            f"Reason: {reason}\n\n"
+            f"💡 To validate your context file, run:\n"
+            f"   voodocs context validate"
+        )
+
+
+class GitNotAvailableError(ConfigurationError):
+    """Git is not available."""
+    
+    def __init__(self):
+        super().__init__(
+            f"Git is not available\n\n"
+            f"💡 Some VooDocs features require Git. Please install Git:\n"
+            f"   https://git-scm.com/downloads"
+        )
+
+
+class InvalidProjectNameError(ValidationError):
+    """Invalid project name."""
+    
+    def __init__(self, name: str, reason: str):
+        self.name = name
+        self.reason = reason
+        super().__init__(
+            f"Invalid project name: '{name}'\n"
+            f"Reason: {reason}\n\n"
+            f"💡 Project names must:\n"
+            f"   - Not be empty\n"
+            f"   - Be 100 characters or less\n"
+            f"   - Contain only letters, numbers, hyphens, and underscores"
+        )
+
+
+class InvalidVersionError(ValidationError):
+    """Invalid version number."""
+    
+    def __init__(self, version: str):
+        self.version = version
+        super().__init__(
+            f"Invalid version: '{version}'\n\n"
+            f"💡 Version must follow semantic versioning (e.g., 1.0.0, 2.1.3)\n"
+            f"   Format: MAJOR.MINOR.PATCH or MAJOR.MINOR"
+        )
+
+
+class InvalidPathError(ValidationError):
+    """Invalid file path."""
+    
+    def __init__(self, path: str, reason: str):
+        self.path = path
+        self.reason = reason
+        super().__init__(
+            f"Invalid path: '{path}'\n"
+            f"Reason: {reason}"
+        )
+
+
+class InvariantViolationError(VooDocsError):
+    """Invariant violation detected."""
+    
+    def __init__(self, file_path: str, invariant: str, line: int):
+        self.file_path = file_path
+        self.invariant = invariant
+        self.line = line
+        super().__init__(
+            f"Invariant violation in {file_path}:{line}\n"
+            f"Invariant: {invariant}\n\n"
+            f"💡 Review the code and update either:\n"
+            f"   - The code to satisfy the invariant\n"
+            f"   - The invariant if requirements changed"
+        )
+
+
+class AssumptionViolationError(VooDocsError):
+    """Assumption violation detected."""
+    
+    def __init__(self, file_path: str, assumption: str, line: int):
+        self.file_path = file_path
+        self.assumption = assumption
+        self.line = line
+        super().__init__(
+            f"Assumption violation in {file_path}:{line}\n"
+            f"Assumption: {assumption}\n\n"
+            f"💡 Review the code and update either:\n"
+            f"   - The code to satisfy the assumption\n"
+            f"   - The assumption if requirements changed"
+        )
+
+
+class UserInterruptError(VooDocsError):
+    """User interrupted operation."""
+    
+    def __init__(self, operation: str):
+        self.operation = operation
+        super().__init__(f"\nOperation cancelled by user: {operation}")
+
+
+class OutputDirectoryError(VooDocsError):
+    """Output directory error."""
+    
+    def __init__(self, path: str, reason: str):
+        self.path = path
+        self.reason = reason
+        super().__init__(
+            f"Output directory error: {path}\n"
+            f"Reason: {reason}"
+        )
+
+
+class ContextVersionMismatchError(ConfigurationError):
+    """Context version mismatch."""
+    
+    def __init__(self, current: str, required: str):
+        self.current = current
+        self.required = required
+        super().__init__(
+            f"Context version mismatch\n"
+            f"Current: {current}\n"
+            f"Required: {required}\n\n"
+            f"💡 Update your context file to the latest version:\n"
+            f"   voodocs context update"
+        )

package/lib/darkarts/context/models.py

@@ -1,4 +1,26 @@
-"""
+"""@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"
+
 Context System Data Models
 
 This module defines the data structures for the VooDocs context system.

package/lib/darkarts/context/module_utils.py

@@ -0,0 +1,198 @@
+"""@darkarts
+⊢module_utils:context.extraction
+∂{pathlib,typing}
+⚠{annotations:parsed,paths:relative,extensions:standard}
+⊨{∀extract→complete-module,language:detected,api:extracted}
+🔒{read-only,¬modify-annotations}
+⚡{O(1)}
+
+Module Extraction Utilities
+
+Helper functions for extracting module information from parsed annotations.
+"""
+
+from pathlib import Path
+from typing import Dict, Any, Optional, List
+
+
+def detect_language(file_path: str) -> Optional[str]:
+    """
+    Detect programming language from file extension.
+    
+    Args:
+        file_path: Path to the source file
+    
+    Returns:
+        Language name or None if unknown
+    
+    Examples:
+        >>> detect_language("main.py")
+        'Python'
+        >>> detect_language("app.js")
+        'JavaScript'
+        >>> detect_language("unknown.xyz")
+        None
+    """
+    ext_map = {
+        '.py': 'Python',
+        '.js': 'JavaScript',
+        '.jsx': 'JavaScript',
+        '.ts': 'TypeScript',
+        '.tsx': 'TypeScript',
+        '.java': 'Java',
+        '.go': 'Go',
+        '.rs': 'Rust',
+        '.cpp': 'C++',
+        '.cc': 'C++',
+        '.cxx': 'C++',
+        '.c': 'C',
+        '.h': 'C/C++',
+        '.hpp': 'C++',
+        '.cs': 'C#',
+        '.rb': 'Ruby',
+        '.php': 'PHP',
+        '.swift': 'Swift',
+        '.kt': 'Kotlin',
+        '.scala': 'Scala',
+        '.r': 'R',
+        '.m': 'Objective-C',
+        '.sh': 'Shell',
+        '.bash': 'Bash',
+        '.zsh': 'Zsh',
+    }
+    
+    ext = Path(file_path).suffix.lower()
+    return ext_map.get(ext)
+
+
+def extract_public_api(parsed) -> List[str]:
+    """
+    Extract public API from parsed annotations.
+    
+    Collects:
+    - Public functions (not starting with _)
+    - Public classes
+    - Explicitly marked public APIs
+    
+    Args:
+        parsed: ParsedAnnotations object
+    
+    Returns:
+        List of public API names
+    
+    Examples:
+        >>> # parsed.module.functions = [func1, func2, _private]
+        >>> extract_public_api(parsed)
+        ['func1', 'func2']
+    """
+    public_api = []
+    
+    # From module annotation
+    module_ann = parsed.module
+    if hasattr(module_ann, 'public_api') and module_ann.public_api:
+        public_api.extend(module_ann.public_api)
+    
+    # From function annotations (if not already in public_api)
+    if hasattr(module_ann, 'functions'):
+        for func in module_ann.functions:
+            func_name = getattr(func, 'name', None)
+            if func_name and not func_name.startswith('_') and func_name not in public_api:
+                public_api.append(func_name)
+    
+    # From class annotations
+    if hasattr(module_ann, 'classes'):
+        for cls in module_ann.classes:
+            cls_name = getattr(cls, 'name', None)
+            if cls_name and not cls_name.startswith('_') and cls_name not in public_api:
+                public_api.append(cls_name)
+    
+    return public_api
+
+
+def extract_module_info(parsed, scan_path: Path) -> Optional[Dict[str, Any]]:
+    """
+    Extract complete module information from parsed annotations.
+    
+    Creates a dict compatible with the Module dataclass:
+    - description: Module purpose/description
+    - path: Relative path to source file
+    - language: Detected programming language
+    - dependencies: List of dependencies
+    - public_api: List of public API names
+    
+    Args:
+        parsed: ParsedAnnotations object
+        scan_path: Base path for calculating relative paths
+    
+    Returns:
+        Module info dict or None if no module_purpose
+    
+    Examples:
+        >>> module_info = extract_module_info(parsed, Path('/project'))
+        >>> module_info['description']
+        'User authentication module'
+        >>> module_info['language']
+        'Python'
+    """
+    module_ann = parsed.module
+    
+    # Check if module has a purpose/description
+    if not hasattr(module_ann, 'module_purpose') or not module_ann.module_purpose:
+        return None
+    
+    # Calculate relative path
+    try:
+        rel_path = Path(parsed.source_file).relative_to(scan_path).as_posix()
+    except ValueError:
+        # If file is not under scan_path, use absolute path
+        rel_path = Path(parsed.source_file).as_posix()
+    
+    # Detect language from file extension
+    language = detect_language(parsed.source_file)
+    
+    # Extract dependencies
+    dependencies = []
+    if hasattr(module_ann, 'dependencies') and module_ann.dependencies:
+        dependencies = list(module_ann.dependencies)
+    
+    # Extract public API
+    public_api = extract_public_api(parsed)
+    
+    # Build module info dict (matches Module dataclass fields)
+    return {
+        'description': module_ann.module_purpose,
+        'path': rel_path,
+        'language': language,
+        'dependencies': dependencies,
+        'public_api': public_api
+    }
+
+
+def extract_modules_from_results(results: List, scan_path: Path) -> Dict[str, Dict[str, Any]]:
+    """
+    Extract module information from all parsed annotation results.
+    
+    Args:
+        results: List of ParsedAnnotations objects
+        scan_path: Base path for calculating relative paths
+    
+    Returns:
+        Dict mapping file paths to module info dicts
+    
+    Examples:
+        >>> results = parser.parse_directory(Path('/project'))
+        >>> modules = extract_modules_from_results(results, Path('/project'))
+        >>> len(modules)
+        5
+        >>> modules['lib/auth.py']['language']
+        'Python'
+    """
+    modules_info = {}
+    
+    for parsed in results:
+        module_info = extract_module_info(parsed, scan_path)
+        if module_info:
+            # Use path as key
+            modules_info[module_info['path']] = module_info
+    
+    return modules_info