@voodocs/cli 2.5.2 → 3.0.0

package/lib/darkarts/darkarts_patterns.py

@@ -0,0 +1,249 @@
+"""@darkarts
+⊢{darkarts:pattern-shortcuts}
+∂{typing,re}
+⚠{patterns≥15-types}
+⊨{bidirectional:expand↔compress}
+⚡{O(1):lookup}
+🔒{read-only:patterns}
+"""
+
+"""
+DarkArts v3.0.0 - Pattern Shortcuts
+
+This module provides pattern shortcuts for common validations and constraints.
+Designed for maximum token efficiency in preconditions and postconditions.
+
+Pattern types:
+- Type patterns (:uuid, :email, :url, :json, :jwt, :hash, :enc)
+- Comparison operators (≥, ≤, >, <)
+- Range notation ([N,M])
+- Set membership (∈{...})
+"""
+
+import re
+from typing import Dict, Optional, Tuple
+
+# Pattern shortcuts
+PATTERN_SHORTCUTS: Dict[str, str] = {
+    ':uuid': 'valid UUID',
+    ':email': 'valid email format',
+    ':url': 'valid URL',
+    ':uri': 'valid URI',
+    ':json': 'valid JSON',
+    ':jwt': 'valid JWT token',
+    ':hash': 'hashed value',
+    ':enc': 'encrypted value',
+    ':hex': 'hexadecimal value',
+    ':b64': 'base64 encoded',
+    ':iso': 'ISO format',
+    ':rfc': 'RFC compliant',
+}
+
+# Reverse mapping
+PATTERN_EXPANSIONS: Dict[str, str] = {v: k for k, v in PATTERN_SHORTCUTS.items()}
+
+# Comparison operators (Unicode mathematical symbols)
+COMPARISON_OPERATORS: Dict[str, str] = {
+    '≥': 'greater than or equal to',
+    '≤': 'less than or equal to',
+    '>': 'greater than',
+    '<': 'less than',
+    '=': 'equal to',
+    '≠': 'not equal to',
+    '≈': 'approximately equal to',
+}
+
+# Reverse mapping
+COMPARISON_EXPANSIONS: Dict[str, str] = {v: k for k, v in COMPARISON_OPERATORS.items()}
+
+
+def compress_pattern(text: str) -> str:
+    """
+    Compress text using pattern shortcuts.
+    
+    Examples:
+        "valid UUID" → ":uuid"
+        "valid email format" → ":email"
+        "greater than or equal to 8" → "≥8"
+    """
+    result = text
+    
+    # Replace pattern expansions with shortcuts
+    for expansion, shortcut in PATTERN_EXPANSIONS.items():
+        result = result.replace(expansion, shortcut)
+    
+    # Replace comparison operators
+    for expansion, operator in COMPARISON_EXPANSIONS.items():
+        # Handle "X greater than or equal to N" → "X≥N"
+        pattern = rf'(\w+)\s+{re.escape(expansion)}\s+(\d+)'
+        result = re.sub(pattern, rf'\1{operator}\2', result)
+        
+        # Handle "greater than or equal to N" → "≥N"
+        pattern = rf'{re.escape(expansion)}\s+(\d+)'
+        result = re.sub(pattern, rf'{operator}\1', result)
+    
+    return result
+
+
+def expand_pattern(text: str) -> str:
+    """
+    Expand pattern shortcuts to full text.
+    
+    Examples:
+        ":uuid" → "valid UUID"
+        ":email" → "valid email format"
+        "≥8" → "greater than or equal to 8"
+    """
+    result = text
+    
+    # Replace pattern shortcuts with expansions
+    for shortcut, expansion in PATTERN_SHORTCUTS.items():
+        result = result.replace(shortcut, expansion)
+    
+    # Replace comparison operators
+    for operator, expansion in COMPARISON_OPERATORS.items():
+        # Handle "X≥N" → "X greater than or equal to N"
+        pattern = rf'(\w+){re.escape(operator)}(\d+)'
+        result = re.sub(pattern, rf'\1 {expansion} \2', result)
+        
+        # Handle "≥N" → "greater than or equal to N"
+        pattern = rf'{re.escape(operator)}(\d+)'
+        result = re.sub(pattern, rf'{expansion} \1', result)
+    
+    return result
+
+
+def parse_range(text: str) -> Optional[Tuple[int, int]]:
+    """
+    Parse range notation [N,M].
+    
+    Example:
+        "[18,65]" → (18, 65)
+    """
+    match = re.match(r'\[(\d+),(\d+)\]', text)
+    if match:
+        return (int(match.group(1)), int(match.group(2)))
+    return None
+
+
+def parse_set_membership(text: str) -> Optional[list]:
+    """
+    Parse set membership ∈{...}.
+    
+    Example:
+        "∈{active,pending,completed}" → ["active", "pending", "completed"]
+    """
+    match = re.match(r'∈\{([^}]+)\}', text)
+    if match:
+        return [item.strip() for item in match.group(1).split(',')]
+    return None
+
+
+def compress_range(min_val: int, max_val: int) -> str:
+    """
+    Compress range to notation.
+    
+    Example:
+        (18, 65) → "[18,65]"
+    """
+    return f'[{min_val},{max_val}]'
+
+
+def compress_set_membership(items: list) -> str:
+    """
+    Compress set membership to notation.
+    
+    Example:
+        ["active", "pending"] → "∈{active,pending}"
+    """
+    return f'∈{{{",".join(items)}}}'
+
+
+def validate_pattern(pattern: str) -> Tuple[bool, Optional[str]]:
+    """
+    Validate a pattern shortcut.
+    
+    Returns:
+        (is_valid, error_message)
+    """
+    # Check if it contains a type pattern (var:type format)
+    if ':' in pattern and not pattern.startswith(':'):
+        # Extract the pattern part after the colon
+        parts = pattern.split(':')
+        if len(parts) == 2:
+            pattern_type = ':' + parts[1]
+            if pattern_type not in PATTERN_SHORTCUTS:
+                similar = _find_similar_pattern(pattern_type)
+                if similar:
+                    return (False, f"Unknown pattern '{pattern_type}'. Did you mean '{similar}'?")
+                return (False, f"Unknown pattern '{pattern_type}'. Available patterns: {', '.join(PATTERN_SHORTCUTS.keys())}")
+    
+    # Check if it's a standalone pattern shortcut
+    if pattern.startswith(':'):
+        if pattern not in PATTERN_SHORTCUTS:
+            similar = _find_similar_pattern(pattern)
+            if similar:
+                return (False, f"Unknown pattern '{pattern}'. Did you mean '{similar}'?")
+            return (False, f"Unknown pattern '{pattern}'. Available patterns: {', '.join(PATTERN_SHORTCUTS.keys())}")
+    
+    # Check if it's a comparison with number
+    for operator in COMPARISON_OPERATORS.keys():
+        if operator in pattern:
+            # Extract number after operator
+            match = re.search(rf'{re.escape(operator)}(\d+)', pattern)
+            if not match:
+                return (False, f"Invalid comparison '{pattern}'. Expected format: 'var{operator}N' where N is a number")
+    
+    # Check if it's a range
+    if '[' in pattern:
+        range_val = parse_range(pattern)
+        if range_val is None:
+            return (False, f"Invalid range '{pattern}'. Expected format: '[N,M]' where N and M are numbers")
+        if range_val[0] >= range_val[1]:
+            return (False, f"Invalid range '{pattern}'. Minimum must be less than maximum")
+    
+    # Check if it's set membership
+    if '∈' in pattern:
+        set_val = parse_set_membership(pattern)
+        if set_val is None:
+            return (False, f"Invalid set membership '{pattern}'. Expected format: '∈{{item1,item2,...}}'")
+        if len(set_val) == 0:
+            return (False, f"Invalid set membership '{pattern}'. Set must contain at least one item")
+    
+    return (True, None)
+
+
+def _find_similar_pattern(pattern: str) -> Optional[str]:
+    """Find similar pattern using simple edit distance."""
+    pattern_lower = pattern.lower()
+    
+    for known_pattern in PATTERN_SHORTCUTS.keys():
+        # Simple similarity check
+        if len(pattern_lower) >= 3 and known_pattern.startswith(pattern_lower[:3]):
+            return known_pattern
+    
+    return None
+
+
+# Common pattern combinations
+COMMON_PATTERNS = {
+    'id': ':uuid',
+    'identifier': ':uuid',
+    'email': ':email',
+    'url': ':url',
+    'link': ':url',
+    'token': ':jwt',
+    'password': ':hash',
+    'data': ':json',
+}
+
+
+def suggest_pattern(field_name: str) -> Optional[str]:
+    """
+    Suggest a pattern based on field name.
+    
+    Example:
+        "id" → ":uuid"
+        "email" → ":email"
+    """
+    return COMMON_PATTERNS.get(field_name.lower())

package/lib/darkarts/darkarts_symbols.py

@@ -0,0 +1,276 @@
+"""@darkarts
+⊢{darkarts:symbol-definitions}
+∂{typing}
+⚠{symbols≥15-types}
+⊨{∀symbol→unique-meaning}
+⚡{O(1):lookup}
+🔒{read-only:symbols}
+"""
+
+"""
+DarkArts v3.0.0 - Mathematical Symbol Definitions
+
+This module defines all mathematical symbols used in DarkArts notation.
+
+Symbol categories:
+- Core symbols (v2.x): ⊢, ∂, ⚠, ⊳, ⊲, ⊨, ⚡, 🔒
+- New symbols (v3.0.0): ⇄, ⊕, ⊗, ≈, ∴, ∀, ∃
+"""
+
+from typing import Dict, List
+
+# Core Symbols (v2.x)
+CORE_SYMBOLS: Dict[str, str] = {
+    '⊢': 'purpose',
+    '∂': 'dependencies',
+    '⚠': 'assumptions',
+    '⊳': 'preconditions',
+    '⊲': 'postconditions',
+    '⊨': 'invariants',
+    '⚡': 'complexity',
+    '🔒': 'security',
+}
+
+# New Symbols (v3.0.0)
+NEW_SYMBOLS: Dict[str, str] = {
+    '⇄': 'bidirectional',      # Bidirectional relationships
+    '⊕': 'side_effects',       # Side effects
+    '⊗': 'forbidden',          # Forbidden operations
+    '≈': 'approximation',      # Approximation/tolerance
+    '∴': 'consequence',        # Logical consequence
+    '∀': 'universal',          # Universal quantifier
+    '∃': 'existential',        # Existential quantifier
+}
+
+# All Symbols
+ALL_SYMBOLS: Dict[str, str] = {**CORE_SYMBOLS, **NEW_SYMBOLS}
+
+# Reverse mapping (name to symbol)
+SYMBOL_NAMES: Dict[str, str] = {v: k for k, v in ALL_SYMBOLS.items()}
+
+# Symbol descriptions
+SYMBOL_DESCRIPTIONS: Dict[str, str] = {
+    '⊢': 'Purpose - What the function/module does',
+    '∂': 'Dependencies - External packages/modules required',
+    '⚠': 'Assumptions - Conditions assumed to be true',
+    '⊳': 'Preconditions - Conditions that must be true before execution',
+    '⊲': 'Postconditions - Conditions guaranteed after execution',
+    '⊨': 'Invariants - Properties that remain unchanged',
+    '⚡': 'Complexity - Time/space complexity (Big O notation)',
+    '🔒': 'Security - Security considerations and protections',
+    '⇄': 'Bidirectional - Bidirectional relationships or inverse operations',
+    '⊕': 'Side Effects - Operations that modify external state',
+    '⊗': 'Forbidden - Operations that must NOT happen',
+    '≈': 'Approximation - Acceptable error margins or tolerances',
+    '∴': 'Consequence - Logical implications and consequences',
+    '∀': 'Universal - Properties that apply to all elements',
+    '∃': 'Existential - Properties that must exist',
+}
+
+# Symbol examples
+SYMBOL_EXAMPLES: Dict[str, List[str]] = {
+    '⊢': [
+        '⊢{u auth svc}',
+        '⊢{calc total price}',
+        '⊢{fetch u data from db}',
+    ],
+    '∂': [
+        '∂{bcrypt,jsonwebtoken,db}',
+        '∂{express,cors,helmet}',
+        '∂{react,redux,axios}',
+    ],
+    '⚠': [
+        '⚠{u exists in db}',
+        '⚠{db conn available}',
+        '⚠{valid sess}',
+    ],
+    '⊳': [
+        '⊳{id:uuid,pw≥8}',
+        '⊳{email:email,age≥18}',
+        '⊳{amt>0,currency∈{USD,EUR}}',
+    ],
+    '⊲': [
+        '⊲{ret JWT tok|null}',
+        '⊲{ret u obj|err}',
+        '⊲{ret bool}',
+    ],
+    '⊨': [
+        '⊨{no db mod}',
+        '⊨{no state change}',
+        '⊨{idempotent}',
+    ],
+    '⚡': [
+        '⚡{O(1)}',
+        '⚡{O(n)}',
+        '⚡{O(log n)}',
+    ],
+    '🔒': [
+        '🔒{pw:hash,tok:enc}',
+        '🔒{rate limit:100/min}',
+        '🔒{auth required}',
+    ],
+    '⇄': [
+        '⇄{enc↔dec}',
+        '⇄{ser↔deser}',
+        '⇄{compress↔decompress}',
+    ],
+    '⊕': [
+        '⊕{writes db}',
+        '⊕{sends email}',
+        '⊕{logs to file}',
+    ],
+    '⊗': [
+        '⊗{no pw log}',
+        '⊗{no network calls}',
+        '⊗{no db writes}',
+    ],
+    '≈': [
+        '≈{±0.001}',
+        '≈{~99.9% accuracy}',
+        '≈{<1ms latency}',
+    ],
+    '∴': [
+        '∴{if auth fails→ret null}',
+        '∴{if cache miss→fetch db}',
+        '∴{if invalid→throw err}',
+    ],
+    '∀': [
+        '∀{users have email}',
+        '∀{tokens expire 1h}',
+        '∀{pw≥8}',
+    ],
+    '∃': [
+        '∃{admin required}',
+        '∃{valid sess}',
+        '∃{active conn}',
+    ],
+}
+
+# Symbol categories
+SYMBOL_CATEGORIES: Dict[str, List[str]] = {
+    'core': list(CORE_SYMBOLS.keys()),
+    'new': list(NEW_SYMBOLS.keys()),
+    'required': ['⊢'],  # Only purpose is truly required
+    'optional': [s for s in ALL_SYMBOLS.keys() if s != '⊢'],
+}
+
+
+def get_symbol_name(symbol: str) -> str:
+    """Get the name of a symbol."""
+    return ALL_SYMBOLS.get(symbol, 'unknown')
+
+
+def get_symbol_description(symbol: str) -> str:
+    """Get the description of a symbol."""
+    return SYMBOL_DESCRIPTIONS.get(symbol, 'Unknown symbol')
+
+
+def get_symbol_examples(symbol: str) -> List[str]:
+    """Get examples for a symbol."""
+    return SYMBOL_EXAMPLES.get(symbol, [])
+
+
+def is_valid_symbol(symbol: str) -> bool:
+    """Check if a symbol is valid."""
+    return symbol in ALL_SYMBOLS
+
+
+def get_symbol_by_name(name: str) -> str:
+    """Get symbol by its name."""
+    return SYMBOL_NAMES.get(name, '')
+
+
+def list_symbols(category: str = 'all') -> List[str]:
+    """
+    List symbols by category.
+    
+    Categories: 'all', 'core', 'new', 'required', 'optional'
+    """
+    if category == 'all':
+        return list(ALL_SYMBOLS.keys())
+    return SYMBOL_CATEGORIES.get(category, [])
+
+
+# Symbol validation rules
+SYMBOL_RULES: Dict[str, Dict] = {
+    '⊢': {
+        'required': True,
+        'multiple': False,
+        'format': 'Single sentence describing purpose',
+    },
+    '∂': {
+        'required': False,
+        'multiple': False,
+        'format': 'Comma-separated list of dependencies',
+    },
+    '⚠': {
+        'required': False,
+        'multiple': True,
+        'format': 'Comma-separated list of assumptions',
+    },
+    '⊳': {
+        'required': False,
+        'multiple': True,
+        'format': 'Comma-separated list of preconditions',
+    },
+    '⊲': {
+        'required': False,
+        'multiple': True,
+        'format': 'Comma-separated list of postconditions',
+    },
+    '⊨': {
+        'required': False,
+        'multiple': True,
+        'format': 'Comma-separated list of invariants',
+    },
+    '⚡': {
+        'required': False,
+        'multiple': False,
+        'format': 'Big O notation (e.g., O(1), O(n))',
+    },
+    '🔒': {
+        'required': False,
+        'multiple': True,
+        'format': 'Comma-separated list of security measures',
+    },
+    '⇄': {
+        'required': False,
+        'multiple': True,
+        'format': 'Bidirectional relationships (e.g., enc↔dec)',
+    },
+    '⊕': {
+        'required': False,
+        'multiple': True,
+        'format': 'Comma-separated list of side effects',
+    },
+    '⊗': {
+        'required': False,
+        'multiple': True,
+        'format': 'Comma-separated list of forbidden operations',
+    },
+    '≈': {
+        'required': False,
+        'multiple': True,
+        'format': 'Approximation or tolerance (e.g., ±0.001)',
+    },
+    '∴': {
+        'required': False,
+        'multiple': True,
+        'format': 'Logical implications (e.g., if X→Y)',
+    },
+    '∀': {
+        'required': False,
+        'multiple': True,
+        'format': 'Universal properties (e.g., all users have email)',
+    },
+    '∃': {
+        'required': False,
+        'multiple': True,
+        'format': 'Existential properties (e.g., admin required)',
+    },
+}
+
+
+def get_symbol_rules(symbol: str) -> Dict:
+    """Get validation rules for a symbol."""
+    return SYMBOL_RULES.get(symbol, {})

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

@@ -20,6 +20,7 @@ Translates @voodocs annotations (DarkArts language) into human-readable document
 from typing import List, Optional, Dict
 from pathlib import Path
 import re
+import sys
 
 from darkarts.annotations.types import (
     ParsedAnnotations,
@@ -29,6 +30,10 @@ from darkarts.annotations.types import (
     ComplexityAnnotation,
 )
 
+# Import abbreviation expansion for v3.0.0
+sys.path.insert(0, str(Path(__file__).parent.parent.parent))
+from darkarts.companion_files_expansion import expand_abbreviations, expand_pattern_shortcuts
+
 
 class DocumentationGenerator:
     """Generates human-readable documentation from @voodocs annotations."""
@@ -41,8 +46,24 @@ class DocumentationGenerator:
         """Initialize mathematical symbol translation tables."""
         # Mathematical symbols to natural language
         self.math_symbols = {
+            # Core DarkArts symbols
+            '⊢': 'purpose',
+            '∂': 'dependencies',
+            '⊳': 'preconditions',
+            '⊲': 'postconditions',
+            '⊨': 'invariants',
+            '⚠': 'assumptions',
+            '⚡': 'complexity',
+            '🔒': 'security',
+            # v3.0.0 new symbols
+            '⇄': 'bidirectional relationship',
+            '⊕': 'side effects',
+            '⊗': 'forbidden operations',
+            '≈': 'approximately',
+            '∴': 'therefore',
             '∀': 'for all',
             '∃': 'there exists',
+            # Standard mathematical symbols
             '∈': 'in',
             '∉': 'not in',
             '⊆': 'subset of',
@@ -53,12 +74,13 @@ class DocumentationGenerator:
             '≥': 'greater than or equal to',
             '≤': 'less than or equal to',
             '≠': 'not equal to',
-            '≈': 'approximately equal to',
             '⟹': 'implies',
             '⟺': 'if and only if',
             '⇒': 'implies',
             '⇔': 'if and only if',
             '→': 'leads to',
+            '←': 'comes from',
+            '↔': 'corresponds to',
             '∧': 'and',
             '∨': 'or',
             '¬': 'not',
@@ -303,10 +325,17 @@ class DocumentationGenerator:
         """
         Translate mathematical notation to natural language.
         
-        This method converts DarkArts mathematical expressions into readable English.
+        This method converts DarkArts mathematical expressions into readable English,
+        including v3.0.0 abbreviation expansion.
         """
         text = expression.strip()
         
+        # Expand v3.0.0 abbreviations first (e.g., "u auth svc" -> "user authentication service")
+        text = expand_abbreviations(text)
+        
+        # Expand pattern shortcuts (e.g., ":uuid" -> "must be valid UUID")
+        text = expand_pattern_shortcuts(text)
+        
         # Handle quantifiers (∀, ∃) specially
         text = self._translate_quantifiers(text)