@voodocs/cli 0.1.2 → 0.2.0

package/lib/darkarts/context/diagram.py

@@ -0,0 +1,300 @@
+"""
+Architecture Diagram Generator
+
+Generates visual diagrams from context files.
+"""
+
+import subprocess
+from pathlib import Path
+from typing import Dict, List, Optional, Any
+
+
+class DiagramGenerator:
+    """Generates architecture diagrams from context."""
+    
+    def __init__(self):
+        pass
+    
+    def generate_module_diagram(
+        self, 
+        context_data: Dict[str, Any],
+        format: str = 'mermaid'
+    ) -> str:
+        """
+        Generate a module architecture diagram.
+        
+        Args:
+            context_data: Context file data
+            format: Output format ('mermaid' or 'd2')
+        
+        Returns:
+            Diagram source code
+        """
+        architecture = context_data.get('architecture', {})
+        modules = architecture.get('modules', {})
+        
+        if not modules:
+            return "# No modules found in context"
+        
+        if format == 'mermaid':
+            return self._generate_mermaid_modules(modules)
+        elif format == 'd2':
+            return self._generate_d2_modules(modules)
+        else:
+            raise ValueError(f"Unsupported format: {format}")
+    
+    def generate_dependency_diagram(
+        self,
+        context_data: Dict[str, Any],
+        format: str = 'mermaid'
+    ) -> str:
+        """
+        Generate a dependency diagram.
+        
+        Args:
+            context_data: Context file data
+            format: Output format ('mermaid' or 'd2')
+        
+        Returns:
+            Diagram source code
+        """
+        dependencies = context_data.get('dependencies', {})
+        
+        if not dependencies:
+            return "# No dependencies found in context"
+        
+        if format == 'mermaid':
+            return self._generate_mermaid_dependencies(dependencies)
+        elif format == 'd2':
+            return self._generate_d2_dependencies(dependencies)
+        else:
+            raise ValueError(f"Unsupported format: {format}")
+    
+    def generate_flow_diagram(
+        self,
+        context_data: Dict[str, Any],
+        format: str = 'mermaid'
+    ) -> str:
+        """
+        Generate a critical path flow diagram.
+        
+        Args:
+            context_data: Context file data
+            format: Output format ('mermaid' or 'd2')
+        
+        Returns:
+            Diagram source code
+        """
+        critical_paths = context_data.get('critical_paths', [])
+        
+        if not critical_paths:
+            return "# No critical paths found in context"
+        
+        if format == 'mermaid':
+            return self._generate_mermaid_flows(critical_paths)
+        elif format == 'd2':
+            return self._generate_d2_flows(critical_paths)
+        else:
+            raise ValueError(f"Unsupported format: {format}")
+    
+    def _generate_mermaid_modules(self, modules: Dict[str, Any]) -> str:
+        """Generate Mermaid diagram for modules."""
+        lines = ["graph TD"]
+        
+        # Create nodes for each module
+        for i, (module_name, module_info) in enumerate(modules.items()):
+            node_id = f"M{i}"
+            purpose = module_info.get('purpose', 'No description')
+            
+            # Truncate long purposes
+            if len(purpose) > 40:
+                purpose = purpose[:37] + "..."
+            
+            lines.append(f"    {node_id}[\"{module_name}<br/>{purpose}\"]")
+        
+        # Add dependencies as edges
+        for i, (module_name, module_info) in enumerate(modules.items()):
+            node_id = f"M{i}"
+            deps = module_info.get('dependencies', [])
+            
+            if isinstance(deps, list):
+                for dep in deps:
+                    # Find the dependency module
+                    for j, (dep_name, _) in enumerate(modules.items()):
+                        if dep_name == dep or dep in dep_name:
+                            dep_id = f"M{j}"
+                            lines.append(f"    {node_id} --> {dep_id}")
+        
+        return "\n".join(lines)
+    
+    def _generate_d2_modules(self, modules: Dict[str, Any]) -> str:
+        """Generate D2 diagram for modules."""
+        lines = []
+        
+        # Create nodes for each module
+        for module_name, module_info in modules.items():
+            purpose = module_info.get('purpose', 'No description')
+            lines.append(f"{module_name}: {{")
+            lines.append(f"  label: \"{purpose}\"")
+            lines.append("}")
+        
+        # Add dependencies as edges
+        for module_name, module_info in modules.items():
+            deps = module_info.get('dependencies', [])
+            
+            if isinstance(deps, list):
+                for dep in deps:
+                    # Find the dependency module
+                    if dep in modules:
+                        lines.append(f"{module_name} -> {dep}")
+        
+        return "\n".join(lines)
+    
+    def _generate_mermaid_dependencies(self, dependencies: Dict[str, Any]) -> str:
+        """Generate Mermaid diagram for dependencies."""
+        lines = ["graph LR"]
+        
+        project = "Project"
+        lines.append(f"    {project}[\"Project\"]")
+        
+        # Add external dependencies
+        external_deps = dependencies.get('external', [])
+        if isinstance(external_deps, list):
+            for i, dep in enumerate(external_deps):
+                dep_id = f"D{i}"
+                if isinstance(dep, dict):
+                    dep_name = dep.get('name', 'Unknown')
+                    dep_version = dep.get('version', '')
+                    label = f"{dep_name} {dep_version}".strip()
+                else:
+                    label = str(dep)
+                
+                lines.append(f"    {dep_id}[\"{label}\"]")
+                lines.append(f"    {project} --> {dep_id}")
+        
+        return "\n".join(lines)
+    
+    def _generate_d2_dependencies(self, dependencies: Dict[str, Any]) -> str:
+        """Generate D2 diagram for dependencies."""
+        lines = ["Project"]
+        
+        # Add external dependencies
+        external_deps = dependencies.get('external', [])
+        if isinstance(external_deps, list):
+            for dep in external_deps:
+                if isinstance(dep, dict):
+                    dep_name = dep.get('name', 'Unknown')
+                    dep_version = dep.get('version', '')
+                    label = f"{dep_name} {dep_version}".strip()
+                else:
+                    label = str(dep)
+                
+                lines.append(f"Project -> {label}")
+        
+        return "\n".join(lines)
+    
+    def _generate_mermaid_flows(self, critical_paths: List[Dict[str, Any]]) -> str:
+        """Generate Mermaid diagram for critical paths."""
+        lines = ["graph TD"]
+        
+        for path_idx, path in enumerate(critical_paths):
+            path_name = path.get('name', f'Path {path_idx + 1}')
+            steps = path.get('steps', [])
+            
+            # Add path title
+            lines.append(f"    subgraph \"{path_name}\"")
+            
+            # Add steps
+            for step_idx, step in enumerate(steps):
+                node_id = f"P{path_idx}S{step_idx}"
+                
+                # Truncate long steps
+                step_text = str(step)
+                if len(step_text) > 40:
+                    step_text = step_text[:37] + "..."
+                
+                lines.append(f"        {node_id}[\"{step_text}\"]")
+                
+                # Connect to previous step
+                if step_idx > 0:
+                    prev_id = f"P{path_idx}S{step_idx - 1}"
+                    lines.append(f"        {prev_id} --> {node_id}")
+            
+            lines.append("    end")
+        
+        return "\n".join(lines)
+    
+    def _generate_d2_flows(self, critical_paths: List[Dict[str, Any]]) -> str:
+        """Generate D2 diagram for critical paths."""
+        lines = []
+        
+        for path_idx, path in enumerate(critical_paths):
+            path_name = path.get('name', f'Path {path_idx + 1}')
+            steps = path.get('steps', [])
+            
+            # Add path container
+            lines.append(f"{path_name}: {{")
+            
+            # Add steps
+            for step_idx, step in enumerate(steps):
+                node_id = f"step{step_idx + 1}"
+                step_text = str(step)
+                lines.append(f"  {node_id}: \"{step_text}\"")
+                
+                # Connect to previous step
+                if step_idx > 0:
+                    prev_id = f"step{step_idx}"
+                    lines.append(f"  {prev_id} -> {node_id}")
+            
+            lines.append("}")
+        
+        return "\n".join(lines)
+    
+    def render_to_png(self, diagram_source: str, output_path: Path, format: str = 'mermaid') -> bool:
+        """
+        Render diagram source to PNG using manus-render-diagram.
+        
+        Args:
+            diagram_source: Diagram source code
+            output_path: Output PNG file path
+            format: Diagram format ('mermaid' or 'd2')
+        
+        Returns:
+            True if successful, False otherwise
+        """
+        # Determine file extension
+        if format == 'mermaid':
+            ext = '.mmd'
+        elif format == 'd2':
+            ext = '.d2'
+        else:
+            raise ValueError(f"Unsupported format: {format}")
+        
+        # Create temporary source file
+        temp_source = output_path.parent / f"{output_path.stem}{ext}"
+        temp_source.write_text(diagram_source)
+        
+        try:
+            # Render using manus-render-diagram
+            result = subprocess.run(
+                ['manus-render-diagram', str(temp_source), str(output_path)],
+                capture_output=True,
+                text=True,
+                check=True
+            )
+            
+            return True
+        
+        except subprocess.CalledProcessError as e:
+            print(f"Error rendering diagram: {e.stderr}")
+            return False
+        
+        except FileNotFoundError:
+            print("Error: manus-render-diagram not found")
+            print("This utility should be available in the Manus sandbox")
+            return False
+        
+        finally:
+            # Clean up temporary file
+            if temp_source.exists():
+                temp_source.unlink()

package/lib/darkarts/context/models.py

@@ -0,0 +1,200 @@
+"""
+Context System Data Models
+
+This module defines the data structures for the VooDocs context system.
+"""
+
+from dataclasses import dataclass, field, asdict
+from typing import List, Dict, Optional, Any
+from datetime import date
+
+
+@dataclass
+class Versioning:
+    """Version information for code and context."""
+    code_version: str
+    context_version: str
+    last_updated: str  # ISO 8601 date (YYYY-MM-DD)
+
+
+@dataclass
+class Project:
+    """Project overview information."""
+    name: str
+    purpose: str
+    repository: Optional[str] = None
+    homepage: Optional[str] = None
+    license: Optional[str] = None
+
+
+@dataclass
+class ArchitectureDecision:
+    """An architectural decision record."""
+    decision: str
+    rationale: str
+    alternatives_considered: List[str] = field(default_factory=list)
+    tradeoffs: Optional[str] = None
+    date: Optional[str] = None
+    author: Optional[str] = None
+
+
+@dataclass
+class Module:
+    """A module in the system architecture."""
+    description: str
+    path: Optional[str] = None
+    language: Optional[str] = None
+    dependencies: List[str] = field(default_factory=list)
+    public_api: List[str] = field(default_factory=list)
+
+
+@dataclass
+class Architecture:
+    """Architecture information."""
+    decisions: List[ArchitectureDecision] = field(default_factory=list)
+    modules: Dict[str, Module] = field(default_factory=dict)
+    tech_stack: Dict[str, List[str]] = field(default_factory=dict)
+
+
+@dataclass
+class CriticalPath:
+    """A critical workflow or data flow."""
+    name: str
+    steps: List[str]
+    description: Optional[str] = None
+    entry_point: Optional[str] = None
+    exit_point: Optional[str] = None
+
+
+@dataclass
+class KnownIssue:
+    """A known bug or limitation."""
+    issue: str
+    impact: str
+    workaround: Optional[str] = None
+    priority: str = "medium"  # low, medium, high, critical
+    tracking: Optional[str] = None
+    discovered: Optional[str] = None
+
+
+@dataclass
+class Assumption:
+    """An assumption the system makes."""
+    assumption: str
+    rationale: Optional[str] = None
+    risk_if_false: Optional[str] = None
+
+
+@dataclass
+class Change:
+    """A change to the codebase or context."""
+    type: str  # feat, fix, docs, refactor, test, context
+    description: str
+    date: str
+    commit: Optional[str] = None
+    author: Optional[str] = None
+    context_version: Optional[str] = None
+    code_version: Optional[str] = None
+
+
+@dataclass
+class RoadmapItem:
+    """A planned feature or improvement."""
+    feature: str
+    priority: str = "medium"  # low, medium, high
+    target_version: Optional[str] = None
+    estimated_effort: Optional[str] = None
+
+
+@dataclass
+class ContextFile:
+    """Complete context file structure."""
+    versioning: Versioning
+    project: Project
+    invariants: Dict[str, Any] = field(default_factory=dict)
+    architecture: Architecture = field(default_factory=Architecture)
+    critical_paths: List[CriticalPath] = field(default_factory=list)
+    known_issues: List[KnownIssue] = field(default_factory=list)
+    assumptions: List[Assumption] = field(default_factory=list)
+    changes: List[Change] = field(default_factory=list)
+    roadmap: List[RoadmapItem] = field(default_factory=list)
+    performance: Dict[str, Any] = field(default_factory=dict)
+    security: Dict[str, Any] = field(default_factory=dict)
+    dependencies: Dict[str, Any] = field(default_factory=dict)
+    testing: Dict[str, Any] = field(default_factory=dict)
+    deployment: Dict[str, Any] = field(default_factory=dict)
+    team: Dict[str, Any] = field(default_factory=dict)
+    custom: Dict[str, Any] = field(default_factory=dict)
+
+    def to_dict(self) -> Dict[str, Any]:
+        """Convert to dictionary, excluding empty sections."""
+        data = asdict(self)
+        
+        # Remove empty optional sections
+        optional_sections = [
+            'performance', 'security', 'dependencies', 'testing',
+            'deployment', 'team', 'custom'
+        ]
+        
+        for section in optional_sections:
+            if not data.get(section):
+                del data[section]
+        
+        # Remove empty lists (except changes which is always kept)
+        for key, value in list(data.items()):
+            if isinstance(value, list) and len(value) == 0 and key != 'changes':
+                del data[key]
+        
+        return data
+
+
+def create_minimal_context(
+    project_name: str,
+    project_purpose: str,
+    code_version: str,
+    repository: Optional[str] = None,
+    license: Optional[str] = None
+) -> ContextFile:
+    """
+    Create a minimal context file with required fields only.
+    
+    Args:
+        project_name: Name of the project
+        project_purpose: One-sentence description of the project
+        code_version: Current code version (e.g., "1.0.0")
+        repository: Optional repository URL
+        license: Optional license identifier
+    
+    Returns:
+        ContextFile with minimal required data
+    """
+    today = date.today().isoformat()
+    
+    # Extract major version for context version
+    major_version = code_version.split('.')[0]
+    context_version = f"{major_version}.0"
+    
+    return ContextFile(
+        versioning=Versioning(
+            code_version=code_version,
+            context_version=context_version,
+            last_updated=today
+        ),
+        project=Project(
+            name=project_name,
+            purpose=project_purpose,
+            repository=repository,
+            license=license
+        ),
+        invariants={
+            "global": []
+        },
+        changes=[
+            Change(
+                type="context",
+                description="Initial context created",
+                date=today,
+                context_version=context_version
+            )
+        ]
+    )