@voodocs/cli 2.5.3 → 3.0.1

package/lib/darkarts/companion_files.py

@@ -22,6 +22,11 @@ File naming convention:
 import re
 from pathlib import Path
 from typing import Dict, List, Optional, Tuple
+import sys
+
+# Import expansion functionality
+sys.path.insert(0, str(Path(__file__).parent))
+from companion_files_expansion import expand_symbol_content, expand_companion_content
 
 
 class CompanionFileScanner:
@@ -137,9 +142,10 @@ class CompanionFileScanner:
             # Extract ⊢{} notation
             purpose_symbol = re.search(r'⊢\{([^}]+)\}', purpose_text)
             if purpose_symbol:
-                sections['purpose'] = purpose_symbol.group(1).strip()
+                # Expand abbreviations for human readability
+                sections['purpose'] = expand_symbol_content(purpose_symbol.group(1).strip())
             else:
-                sections['purpose'] = purpose_text
+                sections['purpose'] = expand_companion_content(purpose_text)
         
         # Extract Architecture section
         arch_match = re.search(r'##\s+Architecture\s*\n(.*?)(?=\n##|\Z)', content, re.DOTALL)
@@ -272,28 +278,75 @@ class CompanionFileScanner:
         
         template = f"""# {stem}.voodocs.md
 
+Companion documentation for `{filename}` using DarkArts v3.0.0 mathematical notation.
+
 ## Purpose
-⊢{{[Describe the module's primary purpose and responsibilities]}}
+⊢{{[Describe module's primary purpose - use abbreviations like 'svc', 'auth', 'db']}}
+
+## Dependencies
+∂{{[List external dependencies - e.g., bcrypt,jsonwebtoken,db]}}
 
 ## Architecture
-- **Depends On**: [List dependencies]
+- **Depends On**: [List internal module dependencies]
 - **Depended By**: [List modules that depend on this]
 - **Storage**: [Data storage information if applicable]
 
+## Preconditions
+⊳{{[Input validation - use patterns like email:email, pw≥8, id:uuid]}}
+
+## Postconditions
+⊲{{[Output guarantees - e.g., ret JWT tok|null]}}
+
 ## Invariants
-⊨{{[Invariant 1: Describe a condition that must always hold]}}
+⊨{{[Invariant 1: Condition that must always hold - e.g., no pw log]}}
 ⊨{{[Invariant 2: Another invariant]}}
 
+## Side Effects
+⊕{{[Side effects - e.g., logs auth, updates last_login]}}
+
+## Forbidden Operations
+⊗{{[Operations that must not happen - e.g., no pw in logs]}}
+
+## Security
+🔒{{[Security requirements - e.g., pw:hash, tok:enc]}}
+
+## Complexity
+⚡{{[Time/space complexity - e.g., O(1), O(n)]}}
+
+## Bidirectional Relationships
+⇄{{[Related operations - e.g., login↔logout]}}
+
+## Logical Consequences
+∴{{[Implications - e.g., invalid→null]}}
+
+## Universal Quantifiers
+∀{{[Statements that apply to all - e.g., users have unique email]}}
+
+## Existential Quantifiers
+∃{{[Existence requirements - e.g., admin required]}}
+
+## Approximations
+≈{{[Performance targets - e.g., ~50ms]}}
+
 ## Assumptions
-⊲{{[Assumption 1: Describe assumptions about inputs, environment, etc.]}}
+⚠{{[Environmental assumptions - e.g., db conn established]}}
 
 ## Critical Sections
 - `functionName()` - [Description of why this is critical]
 
-## Security Considerations
-⊨{{[Security-specific invariant or requirement]}}
-
 ## Notes
 [Any additional notes, diagrams, or references]
+
+---
+
+**DarkArts v3.0.0 Symbols:**
+- ⊢ Purpose | ∂ Dependencies | ⊳ Preconditions | ⊲ Postconditions
+- ⊨ Invariants | ⊕ Side Effects | ⊗ Forbidden | 🔒 Security
+- ⚡ Complexity | ⇄ Bidirectional | ∴ Consequences | ∀ Universal
+- ∃ Existential | ≈ Approximation | ⚠ Assumptions
+
+**Pattern Shortcuts:**
+- :uuid, :email, :url, :json, :jwt, :hash, :enc
+- ≥N, ≤N, >N, <N, [N,M], ∈{{...}}
 """
         return template

package/lib/darkarts/companion_files_expansion.py

@@ -0,0 +1,138 @@
+"""
+⊢companion_files:expansion
+∂{re,typing}
+⚠{python≥3.7}
+⊨{∀abbrev→expanded}
+🔒{read-only}
+⚡{O(n)|n=text-length}
+"""
+
+"""
+DarkArts v3.0.0 - Abbreviation Expansion for Companion Files
+
+Expands abbreviated text in companion files to full human-readable form.
+"""
+
+import re
+from typing import Dict
+
+# Import abbreviation dictionary from v3.0.0
+import sys
+from pathlib import Path
+sys.path.insert(0, str(Path(__file__).parent))
+from darkarts_abbreviations import ABBREVIATIONS
+
+
+def expand_abbreviations(text: str) -> str:
+    """
+    Expand abbreviations in text to full human-readable form.
+    
+    Args:
+        text: Text containing abbreviations (e.g., "u auth svc w/ JWT tok gen")
+    
+    Returns:
+        Expanded text (e.g., "user authentication service with JWT token generation")
+    
+    Examples:
+        >>> expand_abbreviations("u auth svc")
+        'user authentication service'
+        >>> expand_abbreviations("ret JWT tok|null")
+        'return JWT token or null'
+    """
+    # Sort by length (longest first) to avoid partial matches
+    sorted_abbrevs = sorted(ABBREVIATIONS.keys(), key=len, reverse=True)
+    
+    expanded = text
+    for abbrev in sorted_abbrevs:
+        full = ABBREVIATIONS[abbrev]
+        # Use word boundaries to avoid partial replacements
+        pattern = r'\b' + re.escape(abbrev) + r'\b'
+        expanded = re.sub(pattern, full, expanded, flags=re.IGNORECASE)
+    
+    return expanded
+
+
+def expand_pattern_shortcuts(text: str) -> str:
+    """
+    Expand pattern shortcuts to human-readable descriptions.
+    
+    Args:
+        text: Text containing pattern shortcuts (e.g., "id:uuid, pw≥8")
+    
+    Returns:
+        Expanded text (e.g., "id must be valid UUID, password must be at least 8 characters")
+    
+    Examples:
+        >>> expand_pattern_shortcuts("email:email")
+        'email must be valid email address'
+        >>> expand_pattern_shortcuts("pw≥8")
+        'password must be at least 8 characters'
+    """
+    pattern_expansions = {
+        r':uuid': ' must be valid UUID',
+        r':email': ' must be valid email address',
+        r':url': ' must be valid URL',
+        r':json': ' must be valid JSON',
+        r':jwt': ' must be valid JWT token',
+        r':hash': ' must be cryptographic hash',
+        r':enc': ' must be encrypted',
+        r'≥(\d+)': r' must be at least \1 characters',
+        r'≤(\d+)': r' must be at most \1 characters',
+        r'>(\d+)': r' must be greater than \1',
+        r'<(\d+)': r' must be less than \1',
+        r'\[(\d+),(\d+)\]': r' must be between \1 and \2',
+        r'∈\{([^}]+)\}': r' must be one of: \1'
+    }
+    
+    expanded = text
+    for pattern, replacement in pattern_expansions.items():
+        expanded = re.sub(pattern, replacement, expanded)
+    
+    return expanded
+
+
+def expand_companion_content(content: str, expand_patterns: bool = True, expand_abbrevs: bool = True) -> str:
+    """
+    Expand all abbreviations and patterns in companion file content.
+    
+    Args:
+        content: Raw companion file content
+        expand_patterns: Whether to expand pattern shortcuts
+        expand_abbrevs: Whether to expand abbreviations
+    
+    Returns:
+        Fully expanded human-readable content
+    
+    Examples:
+        >>> content = "⊢{u auth svc}\\n⊳{email:email,pw≥8}"
+        >>> expand_companion_content(content)
+        '⊢{user authentication service}\\n⊳{email must be valid email address, password must be at least 8 characters}'
+    """
+    expanded = content
+    
+    if expand_patterns:
+        expanded = expand_pattern_shortcuts(expanded)
+    
+    if expand_abbrevs:
+        expanded = expand_abbreviations(expanded)
+    
+    return expanded
+
+
+def expand_symbol_content(symbol_text: str) -> str:
+    """
+    Expand content within a specific symbol notation (e.g., ⊢{...}, ∂{...}).
+    
+    Args:
+        symbol_text: Text inside symbol braces
+    
+    Returns:
+        Expanded text
+    
+    Examples:
+        >>> expand_symbol_content("u auth svc w/ JWT tok gen")
+        'user authentication service with JWT token generation'
+    """
+    expanded = expand_abbreviations(symbol_text)
+    expanded = expand_pattern_shortcuts(expanded)
+    return expanded