@voodocs/cli 2.2.2 → 2.3.0

package/lib/darkarts/companion_files.py

@@ -0,0 +1,299 @@
+"""
+⊢companion_files:scanner
+∂{pathlib,typing,re}
+⚠{python≥3.7}
+⊨{∀companion_file→matches_source_file}
+🔒{read:files}
+⚡{O(n)|n=files}
+"""
+
+"""
+VooDocs - Companion File Scanner
+
+Scans for .voodocs.md companion documentation files alongside source files.
+Particularly useful for compiled languages like Solidity where inline annotations
+may interfere with compilation.
+
+File naming convention:
+    contracts/SubdomainRegistry.sol → contracts/SubdomainRegistry.voodocs.md
+    src/auth.service.ts → src/auth.service.voodocs.md
+"""
+
+import re
+from pathlib import Path
+from typing import Dict, List, Optional, Tuple
+
+
+class CompanionFileScanner:
+    """
+    Scans for companion documentation files (.voodocs.md) alongside source files.
+    """
+    
+    COMPANION_EXTENSION = '.voodocs.md'
+    
+    @staticmethod
+    def find_companion_file(source_file: Path) -> Optional[Path]:
+        """
+        Find the companion documentation file for a given source file.
+        
+        Args:
+            source_file: Path to source code file
+            
+        Returns:
+            Path to companion file if it exists, None otherwise
+            
+        Example:
+            >>> scanner = CompanionFileScanner()
+            >>> source = Path('contracts/Registry.sol')
+            >>> companion = scanner.find_companion_file(source)
+            >>> print(companion)  # contracts/Registry.voodocs.md
+        """
+        companion_path = source_file.parent / f"{source_file.stem}{CompanionFileScanner.COMPANION_EXTENSION}"
+        return companion_path if companion_path.exists() else None
+    
+    @staticmethod
+    def scan_directory(directory: Path, recursive: bool = True) -> Dict[Path, Optional[Path]]:
+        """
+        Scan a directory for source files and their companion files.
+        
+        Args:
+            directory: Directory to scan
+            recursive: Whether to scan subdirectories
+            
+        Returns:
+            Dictionary mapping source files to their companion files (or None)
+            
+        Example:
+            >>> scanner = CompanionFileScanner()
+            >>> mapping = scanner.scan_directory(Path('contracts/'))
+            >>> for source, companion in mapping.items():
+            ...     print(f"{source} → {companion}")
+        """
+        extensions = ['*.py', '*.ts', '*.js', '*.jsx', '*.tsx', '*.sol']
+        source_files = []
+        
+        if recursive:
+            for ext in extensions:
+                source_files.extend([f for f in directory.glob(f"**/{ext}") if f.is_file()])
+        else:
+            for ext in extensions:
+                source_files.extend([f for f in directory.glob(ext) if f.is_file()])
+        
+        mapping = {}
+        for source_file in source_files:
+            companion = CompanionFileScanner.find_companion_file(source_file)
+            mapping[source_file] = companion
+        
+        return mapping
+    
+    @staticmethod
+    def parse_companion_file(companion_file: Path) -> Dict[str, str]:
+        """
+        Parse a companion documentation file and extract structured sections.
+        
+        Expected format:
+            # FileName.voodocs.md
+            
+            ## Purpose
+            ⊢{Module purpose description}
+            
+            ## Architecture
+            - **Depends On**: Dep1, Dep2
+            - **Depended By**: Parent1, Parent2
+            
+            ## Invariants
+            ⊨{Invariant 1}
+            ⊨{Invariant 2}
+            
+            ## Assumptions
+            ⊲{Assumption 1}
+            
+            ## Critical Sections
+            - functionName() - Description
+        
+        Args:
+            companion_file: Path to companion .voodocs.md file
+            
+        Returns:
+            Dictionary with sections: purpose, architecture, invariants, assumptions, critical_sections
+        """
+        content = companion_file.read_text(encoding='utf-8')
+        
+        sections = {
+            'purpose': '',
+            'architecture': '',
+            'invariants': [],
+            'assumptions': [],
+            'critical_sections': [],
+            'security': [],
+            'dependencies': [],
+            'depended_by': []
+        }
+        
+        # Extract Purpose section
+        purpose_match = re.search(r'##\s+Purpose\s*\n(.*?)(?=\n##|\Z)', content, re.DOTALL)
+        if purpose_match:
+            purpose_text = purpose_match.group(1).strip()
+            # Extract ⊢{} notation
+            purpose_symbol = re.search(r'⊢\{([^}]+)\}', purpose_text)
+            if purpose_symbol:
+                sections['purpose'] = purpose_symbol.group(1).strip()
+            else:
+                sections['purpose'] = purpose_text
+        
+        # Extract Architecture section
+        arch_match = re.search(r'##\s+Architecture\s*\n(.*?)(?=\n##|\Z)', content, re.DOTALL)
+        if arch_match:
+            arch_text = arch_match.group(1).strip()
+            sections['architecture'] = arch_text
+            
+            # Extract dependencies
+            deps_match = re.search(r'\*\*Depends On\*\*:\s*(.+)', arch_text)
+            if deps_match:
+                deps = [d.strip() for d in deps_match.group(1).split(',')]
+                sections['dependencies'] = deps
+            
+            # Extract dependents
+            depended_match = re.search(r'\*\*Depended By\*\*:\s*(.+)', arch_text)
+            if depended_match:
+                dependents = [d.strip() for d in depended_match.group(1).split(',')]
+                sections['depended_by'] = dependents
+        
+        # Extract Invariants section
+        inv_match = re.search(r'##\s+Invariants\s*\n(.*?)(?=\n##|\Z)', content, re.DOTALL)
+        if inv_match:
+            inv_text = inv_match.group(1).strip()
+            # Find all ⊨{} notations
+            invariants = re.findall(r'⊨\{([^}]+)\}', inv_text)
+            sections['invariants'] = [inv.strip() for inv in invariants]
+            
+            # Also capture plain list items
+            if not invariants:
+                list_items = re.findall(r'^[-*]\s+(.+)$', inv_text, re.MULTILINE)
+                sections['invariants'] = [item.strip() for item in list_items]
+        
+        # Extract Assumptions section
+        assume_match = re.search(r'##\s+Assumptions\s*\n(.*?)(?=\n##|\Z)', content, re.DOTALL)
+        if assume_match:
+            assume_text = assume_match.group(1).strip()
+            # Find all ⊲{} notations
+            assumptions = re.findall(r'⊲\{([^}]+)\}', assume_text)
+            sections['assumptions'] = [a.strip() for a in assumptions]
+            
+            # Also capture plain list items
+            if not assumptions:
+                list_items = re.findall(r'^[-*]\s+(.+)$', assume_text, re.MULTILINE)
+                sections['assumptions'] = [item.strip() for item in list_items]
+        
+        # Extract Critical Sections
+        critical_match = re.search(r'##\s+Critical Sections\s*\n(.*?)(?=\n##|\Z)', content, re.DOTALL)
+        if critical_match:
+            critical_text = critical_match.group(1).strip()
+            list_items = re.findall(r'^[-*]\s+(.+)$', critical_text, re.MULTILINE)
+            sections['critical_sections'] = [item.strip() for item in list_items]
+        
+        # Extract Security Considerations
+        security_match = re.search(r'##\s+Security(?:\s+Considerations)?\s*\n(.*?)(?=\n##|\Z)', content, re.DOTALL)
+        if security_match:
+            security_text = security_match.group(1).strip()
+            # Find all ⊨{} notations
+            security_items = re.findall(r'⊨\{([^}]+)\}', security_text)
+            sections['security'] = [s.strip() for s in security_items]
+            
+            # Also capture plain list items
+            if not security_items:
+                list_items = re.findall(r'^[-*]\s+(.+)$', security_text, re.MULTILINE)
+                sections['security'] = [item.strip() for item in list_items]
+        
+        return sections
+    
+    @staticmethod
+    def merge_with_source(source_annotations: Dict, companion_data: Dict) -> Dict:
+        """
+        Merge companion file data with source file annotations.
+        
+        Companion file data takes precedence for documentation-specific fields
+        (purpose, invariants, assumptions), while source file provides code structure.
+        
+        Args:
+            source_annotations: Annotations extracted from source code
+            companion_data: Data parsed from companion file
+            
+        Returns:
+            Merged annotation dictionary
+        """
+        merged = source_annotations.copy()
+        
+        # Override/enhance with companion file data
+        if companion_data.get('purpose'):
+            merged['module_id'] = companion_data['purpose']
+        
+        if companion_data.get('dependencies'):
+            merged['dependencies'] = ', '.join(companion_data['dependencies'])
+        
+        if companion_data.get('invariants'):
+            # Merge invariants from both sources
+            existing_invs = merged.get('invariants', '').split('\n') if merged.get('invariants') else []
+            all_invs = existing_invs + companion_data['invariants']
+            merged['invariants'] = '\n'.join(filter(None, all_invs))
+        
+        if companion_data.get('assumptions'):
+            existing_assumes = merged.get('assumptions', '').split('\n') if merged.get('assumptions') else []
+            all_assumes = existing_assumes + companion_data['assumptions']
+            merged['assumptions'] = '\n'.join(filter(None, all_assumes))
+        
+        if companion_data.get('security'):
+            existing_sec = merged.get('security', '').split('\n') if merged.get('security') else []
+            all_sec = existing_sec + companion_data['security']
+            merged['security'] = '\n'.join(filter(None, all_sec))
+        
+        # Add companion-specific fields
+        if companion_data.get('critical_sections'):
+            merged['critical_sections'] = '\n'.join(companion_data['critical_sections'])
+        
+        if companion_data.get('architecture'):
+            merged['architecture'] = companion_data['architecture']
+        
+        return merged
+    
+    @staticmethod
+    def create_template(source_file: Path) -> str:
+        """
+        Create a template companion file for a given source file.
+        
+        Args:
+            source_file: Path to source file
+            
+        Returns:
+            Template content as string
+        """
+        filename = source_file.name
+        stem = source_file.stem
+        
+        template = f"""# {stem}.voodocs.md
+
+## Purpose
+⊢{{[Describe the module's primary purpose and responsibilities]}}
+
+## Architecture
+- **Depends On**: [List dependencies]
+- **Depended By**: [List modules that depend on this]
+- **Storage**: [Data storage information if applicable]
+
+## Invariants
+⊨{{[Invariant 1: Describe a condition that must always hold]}}
+⊨{{[Invariant 2: Another invariant]}}
+
+## Assumptions
+⊲{{[Assumption 1: Describe assumptions about inputs, environment, etc.]}}
+
+## Critical Sections
+- `functionName()` - [Description of why this is critical]
+
+## Security Considerations
+⊨{{[Security-specific invariant or requirement]}}
+
+## Notes
+[Any additional notes, diagrams, or references]
+"""
+        return template

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@voodocs/cli",
-  "version": "2.2.2",
+  "version": "2.3.0",
   "description": "AI-Native Symbolic Documentation System - The world's first documentation tool using mathematical notation with semantic validation",
   "main": "voodocs_cli.py",
   "bin": {
@@ -63,6 +63,7 @@
     "lib/darkarts/documentation/",
     "lib/darkarts/exceptions.py",
     "lib/darkarts/telemetry.py",
+    "lib/darkarts/companion_files.py",
     "lib/darkarts/parsers/typescript/dist/",
     "lib/darkarts/parsers/typescript/src/",
     "lib/darkarts/parsers/typescript/package.json",