@voodocs/cli 2.5.2 → 3.0.0

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