@voodocs/cli 0.1.1 → 0.2.0

package/lib/darkarts/context/yaml_utils.py

@@ -0,0 +1,342 @@
+"""
+YAML Utilities for Context Files
+
+Handles reading, writing, and formatting of .voodocs.context YAML files.
+"""
+
+import yaml
+from pathlib import Path
+from typing import Dict, Any, Optional
+from .models import ContextFile, Versioning, Project, Architecture, Change
+
+
+class ContextYAMLDumper(yaml.SafeDumper):
+    """Custom YAML dumper with better formatting for context files."""
+    
+    def increase_indent(self, flow=False, indentless=False):
+        return super().increase_indent(flow, False)
+
+
+def _represent_none(self, _):
+    """Represent None as empty string instead of 'null'."""
+    return self.represent_scalar('tag:yaml.org,2002:null', '')
+
+
+# Register custom representers
+ContextYAMLDumper.add_representer(type(None), _represent_none)
+
+
+def write_context_yaml(context: ContextFile, file_path: Path) -> None:
+    """
+    Write a ContextFile to a YAML file with proper formatting.
+    
+    Args:
+        context: The ContextFile object to write
+        file_path: Path to the .voodocs.context file
+    """
+    data = context.to_dict()
+    
+    # Create file with header comment
+    with open(file_path, 'w', encoding='utf-8') as f:
+        # Write header
+        f.write("# VooDocs Context File\n")
+        f.write("# This file contains structured project context for AI assistants and developers.\n")
+        f.write("# Format: YAML (DSL for machines, use 'voodocs context view' for human-readable Markdown)\n")
+        f.write("# Version: {}\n".format(context.versioning.context_version))
+        f.write("# Last Updated: {}\n".format(context.versioning.last_updated))
+        f.write("\n")
+        
+        # Write YAML content
+        yaml.dump(
+            data,
+            f,
+            Dumper=ContextYAMLDumper,
+            default_flow_style=False,
+            allow_unicode=True,
+            sort_keys=False,
+            width=100,
+            indent=2
+        )
+
+
+def read_context_yaml(file_path: Path) -> Optional[Dict[str, Any]]:
+    """
+    Read a .voodocs.context YAML file.
+    
+    Args:
+        file_path: Path to the .voodocs.context file
+    
+    Returns:
+        Dictionary containing the context data, or None if file doesn't exist
+    """
+    if not file_path.exists():
+        return None
+    
+    with open(file_path, 'r', encoding='utf-8') as f:
+        return yaml.safe_load(f)
+
+
+def parse_context_file(data: Dict[str, Any]) -> ContextFile:
+    """
+    Parse a context dictionary into a ContextFile object.
+    
+    Args:
+        data: Dictionary loaded from YAML
+    
+    Returns:
+        ContextFile object
+    """
+    # Parse versioning
+    versioning_data = data.get('versioning', {})
+    versioning = Versioning(
+        code_version=versioning_data.get('code_version', '0.0.0'),
+        context_version=versioning_data.get('context_version', '0.0'),
+        last_updated=versioning_data.get('last_updated', '')
+    )
+    
+    # Parse project
+    project_data = data.get('project', {})
+    project = Project(
+        name=project_data.get('name', ''),
+        purpose=project_data.get('purpose', ''),
+        repository=project_data.get('repository'),
+        homepage=project_data.get('homepage'),
+        license=project_data.get('license')
+    )
+    
+    # Parse changes
+    changes_data = data.get('changes', [])
+    changes = []
+    for change_dict in changes_data:
+        from .models import Change
+        changes.append(Change(
+            type=change_dict.get('type', 'context'),
+            description=change_dict.get('description', ''),
+            date=change_dict.get('date', ''),
+            context_version=change_dict.get('context_version'),
+            code_version=change_dict.get('code_version'),
+            commit=change_dict.get('commit'),
+            author=change_dict.get('author')
+        ))
+    
+    # Parse architecture
+    arch_data = data.get('architecture', {})
+    architecture = Architecture(
+        decisions=arch_data.get('decisions', []),
+        modules=arch_data.get('modules', {}),
+        tech_stack=arch_data.get('tech_stack', {})
+    )
+    
+    # Parse assumptions
+    assumptions_data = data.get('assumptions', [])
+    assumptions = []
+    for assumption in assumptions_data:
+        if isinstance(assumption, dict):
+            from .models import Assumption
+            assumptions.append(Assumption(
+                assumption=assumption.get('description', assumption.get('assumption', '')),
+                rationale=assumption.get('rationale'),
+                risk_if_false=assumption.get('risk_if_false')
+            ))
+        elif isinstance(assumption, str):
+            from .models import Assumption
+            assumptions.append(Assumption(assumption=assumption))
+    
+    # Parse known issues
+    issues_data = data.get('known_issues', [])
+    known_issues = []
+    for issue in issues_data:
+        if isinstance(issue, dict):
+            from .models import KnownIssue
+            known_issues.append(KnownIssue(
+                description=issue.get('description', ''),
+                severity=issue.get('severity'),
+                workaround=issue.get('workaround'),
+                tracking_id=issue.get('tracking_id')
+            ))
+        elif isinstance(issue, str):
+            from .models import KnownIssue
+            known_issues.append(KnownIssue(description=issue))
+    
+    # Parse critical paths
+    paths_data = data.get('critical_paths', [])
+    critical_paths = []
+    for path in paths_data:
+        if isinstance(path, dict):
+            from .models import CriticalPath
+            critical_paths.append(CriticalPath(
+                name=path.get('name', ''),
+                description=path.get('description', ''),
+                entry_point=path.get('entry_point'),
+                steps=path.get('steps', [])
+            ))
+    
+    # Parse roadmap
+    roadmap_data = data.get('roadmap', [])
+    roadmap = []
+    for item in roadmap_data:
+        if isinstance(item, dict):
+            from .models import RoadmapItem
+            roadmap.append(RoadmapItem(
+                version=item.get('version', ''),
+                description=item.get('description', ''),
+                status=item.get('status'),
+                target_date=item.get('target_date')
+            ))
+    
+    # Create context file
+    context = ContextFile(
+        versioning=versioning,
+        project=project,
+        invariants=data.get('invariants', {}),
+        architecture=architecture,
+        critical_paths=critical_paths,
+        known_issues=known_issues,
+        assumptions=assumptions,
+        changes=changes,
+        roadmap=roadmap,
+        performance=data.get('performance', {}),
+        security=data.get('security', {}),
+        dependencies=data.get('dependencies', {}),
+        testing=data.get('testing', {}),
+        deployment=data.get('deployment', {}),
+        team=data.get('team', {}),
+        custom=data.get('custom', {})
+    )
+    
+    return context
+
+
+def add_to_gitignore(project_root: Path) -> bool:
+    """
+    Add .voodocs.context to .gitignore if not already present.
+    
+    Args:
+        project_root: Root directory of the project
+    
+    Returns:
+        True if added, False if already present or error
+    """
+    gitignore_path = project_root / '.gitignore'
+    context_entry = '.voodocs.context'
+    
+    # Check if .gitignore exists
+    if gitignore_path.exists():
+        with open(gitignore_path, 'r', encoding='utf-8') as f:
+            content = f.read()
+        
+        # Check if entry already exists
+        if context_entry in content:
+            return False
+        
+        # Add entry
+        with open(gitignore_path, 'a', encoding='utf-8') as f:
+            # Ensure there's a newline before our section
+            if not content.endswith('\n'):
+                f.write('\n')
+            f.write('\n# VooDocs Context File (contains internal project details)\n')
+            f.write(f'{context_entry}\n')
+        
+        return True
+    else:
+        # Create .gitignore with entry
+        with open(gitignore_path, 'w', encoding='utf-8') as f:
+            f.write('# VooDocs Context File (contains internal project details)\n')
+            f.write(f'{context_entry}\n')
+        
+        return True
+
+
+def format_context_as_markdown(context: ContextFile) -> str:
+    """
+    Convert a ContextFile to human-readable Markdown.
+    
+    Args:
+        context: The ContextFile object
+    
+    Returns:
+        Formatted Markdown string
+    """
+    lines = []
+    
+    # Header
+    lines.append(f"# {context.project.name} Context")
+    lines.append("")
+    lines.append(f"**Version:** {context.versioning.context_version}")
+    lines.append(f"**Last Updated:** {context.versioning.last_updated}")
+    lines.append("")
+    lines.append("---")
+    lines.append("")
+    
+    # Project Overview
+    lines.append("## 🎯 Project Overview")
+    lines.append("")
+    lines.append(f"**Purpose:** {context.project.purpose}")
+    lines.append("")
+    if context.project.repository:
+        lines.append(f"**Repository:** {context.project.repository}")
+    if context.project.license:
+        lines.append(f"**License:** {context.project.license}")
+    lines.append("")
+    lines.append("---")
+    lines.append("")
+    
+    # Global Invariants
+    if context.invariants.get('global'):
+        lines.append("## ⚖️ Global Invariants")
+        lines.append("")
+        for invariant in context.invariants['global']:
+            lines.append(f"- `{invariant}`")
+        lines.append("")
+        lines.append("---")
+        lines.append("")
+    
+    # Architecture
+    if context.architecture.decisions:
+        lines.append("## 🏛️ Architecture Decisions")
+        lines.append("")
+        for decision in context.architecture.decisions:
+            lines.append(f"### {decision.decision}")
+            lines.append("")
+            lines.append(f"**Rationale:** {decision.rationale}")
+            if decision.alternatives_considered:
+                lines.append("")
+                lines.append("**Alternatives Considered:**")
+                for alt in decision.alternatives_considered:
+                    lines.append(f"- {alt}")
+            lines.append("")
+        lines.append("---")
+        lines.append("")
+    
+    # Critical Paths
+    if context.critical_paths:
+        lines.append("## 🔄 Critical Paths")
+        lines.append("")
+        for path in context.critical_paths:
+            lines.append(f"### {path.name}")
+            lines.append("")
+            if path.description:
+                lines.append(path.description)
+                lines.append("")
+            for i, step in enumerate(path.steps, 1):
+                lines.append(f"{i}. {step}")
+            lines.append("")
+        lines.append("---")
+        lines.append("")
+    
+    # Known Issues
+    if context.known_issues:
+        lines.append("## ⚠️ Known Issues")
+        lines.append("")
+        for issue in context.known_issues:
+            lines.append(f"### {issue.issue}")
+            lines.append("")
+            lines.append(f"**Impact:** {issue.impact}")
+            if issue.workaround:
+                lines.append(f"**Workaround:** {issue.workaround}")
+            lines.append(f"**Priority:** {issue.priority}")
+            lines.append("")
+        lines.append("---")
+        lines.append("")
+    
+    return '\n'.join(lines)

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

@@ -567,7 +567,7 @@ class DocumentationGenerator:
         
         # Documentation coverage badge
         total_items = len(parsed.module.classes) + len(parsed.get_all_functions())
-        annotated_items = sum(1 for _ in parsed.module.classes if _.invariants or _.state_transitions)
+        annotated_items = sum(1 for _ in parsed.module.classes if _.class_invariants or _.state_transitions)
         annotated_items += sum(1 for f in parsed.get_all_functions() if f.preconditions or f.postconditions)
         
         if total_items > 0:

package/lib/darkarts/telemetry.py

@@ -20,7 +20,7 @@ SUPABASE_URL = os.getenv("VOODOCS_SUPABASE_URL", "https://sjatkayudkbkmipubhfy.s
 SUPABASE_ANON_KEY = os.getenv("VOODOCS_SUPABASE_ANON_KEY", "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiJzdXBhYmFzZSIsInJlZiI6InNqYXRrYXl1ZGtia21pcHViaGZ5Iiwicm9sZSI6ImFub24iLCJpYXQiOjE3NjYxNjE0MTMsImV4cCI6MjA4MTczNzQxM30.Wj3dbokjKPsmWTgbPw77aPnCoZCsE5hrFfIH-R_ErzI")
 
 # VooDocs version
-VERSION = "0.1.1"
+VERSION = "0.1.2"
 
 class TelemetryClient:
     """Anonymous telemetry client for VooDocs CLI."""

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@voodocs/cli",
-  "version": "0.1.1",
+  "version": "0.2.0",
   "description": "AI-Native Documentation System - Generate docs, tests, and API specs from @voodocs annotations using the DarkArts language",
   "main": "cli.py",
   "bin": {
@@ -46,6 +46,7 @@
   "files": [
     "cli.py",
     "lib/darkarts/annotations/",
+    "lib/darkarts/context/",
     "lib/darkarts/core/",
     "lib/darkarts/exceptions.py",
     "lib/darkarts/telemetry.py",

package/templates/CONTEXT_TEMPLATE.md

@@ -0,0 +1,152 @@
+# [Project Name] Context
+
+**Version:** [current version]  
+**Last Updated:** [YYYY-MM-DD]
+
+---
+
+## 🎯 Project Overview
+
+@voodocs
+module_purpose: "[One-sentence description of what this project does and why it exists]"
+
+---
+
+## ⚖️ Global Invariants
+
+These properties must hold true across the entire codebase.
+
+@voodocs
+global_invariants: [
+  "[Property that must always be true, e.g., 'user.balance >= 0']",
+  "[Another invariant, e.g., '∀ transaction: transaction.amount > 0']",
+  "[System-wide constraint, e.g., 'database connections <= max_pool_size']"
+]
+
+---
+
+## 🏛️ Architecture & Key Decisions
+
+@voodocs
+architecture_decisions: [
+  {
+    decision: "[What was decided]",
+    rationale: "[Why this decision was made]",
+    alternatives_considered: ["[Option A]", "[Option B]"],
+    tradeoffs: "[What was sacrificed or gained]"
+  }
+]
+
+modules: {
+  "[module_name]": "[Brief description of what this module does]",
+  "[another_module]": "[Description]"
+}
+
+tech_stack: {
+  "languages": ["[Language 1]", "[Language 2]"],
+  "frameworks": ["[Framework 1]"],
+  "databases": ["[Database type]"],
+  "infrastructure": ["[Cloud provider or hosting]"]
+}
+
+---
+
+## 🔄 Critical Paths & User Workflows
+
+@voodocs
+critical_paths: [
+  {
+    name: "[Workflow name, e.g., 'User Registration']",
+    steps: ["[Step 1]", "[Step 2]", "[Step 3]"]
+  },
+  {
+    name: "[Another workflow, e.g., 'Payment Processing']",
+    steps: ["[Step 1]", "[Step 2]", "[Step 3]"]
+  }
+]
+
+---
+
+## ⚠️ Known Issues & Assumptions
+
+@voodocs
+known_issues: [
+  {
+    issue: "[Description of the issue]",
+    impact: "[What breaks or degrades]",
+    workaround: "[How to work around it]",
+    priority: "[low|medium|high|critical]"
+  }
+]
+
+assumptions: [
+  "[Assumption 1, e.g., 'Users have internet access']",
+  "[Assumption 2, e.g., 'Database is always available']",
+  "[Assumption 3, e.g., 'Input data is validated by frontend']"
+]
+
+---
+
+## 🗓️ Recent Changes
+
+@voodocs
+changes: [
+  {
+    type: "[fix|feat|docs|refactor|test]",
+    description: "[What changed]",
+    date: "[YYYY-MM-DD]",
+    commit: "[commit hash]"
+  }
+]
+
+---
+
+## 🔮 Future Vision
+
+@voodocs
+roadmap: [
+  "[Feature or improvement planned for next version]",
+  "[Another planned feature]",
+  "[Long-term goal]"
+]
+
+---
+
+## 📚 Additional Context
+
+### Performance Characteristics
+
+@voodocs
+performance: {
+  "typical_response_time": "[e.g., '< 100ms']",
+  "max_throughput": "[e.g., '1000 requests/sec']",
+  "bottlenecks": ["[Known bottleneck 1]", "[Known bottleneck 2]"]
+}
+
+### Security Considerations
+
+@voodocs
+security: {
+  "authentication": "[How users are authenticated]",
+  "authorization": "[How permissions are enforced]",
+  "data_protection": "[How sensitive data is protected]",
+  "known_vulnerabilities": ["[CVE or issue description]"]
+}
+
+### Dependencies & Integrations
+
+@voodocs
+dependencies: {
+  "external_services": ["[Service 1]", "[Service 2]"],
+  "third_party_apis": ["[API 1]", "[API 2]"],
+  "critical_libraries": ["[Library 1]", "[Library 2]"]
+}
+
+---
+
+**Note:** This context file should be updated whenever:
+- Architecture decisions are made
+- Global invariants change
+- New modules are added
+- Critical issues are discovered
+- Major features are shipped