@voodocs/cli 2.5.2 → 3.0.0

package/lib/darkarts/darkarts_parser_v3.py

@@ -0,0 +1,486 @@
+"""@darkarts
+⊢{darkarts:parser-v3}
+∂{re,typing,dataclasses}
+⚠{@darkarts∈docstrings,unicode-support}
+⊨{∀parse→structured-output,¬modify-src,handle-errors}
+⊕{validates annotations}
+⚡{O(n)|n=annotation-length}
+🔒{read-only}
+"""
+
+"""
+DarkArts v3.0.0 - Enhanced Parser
+
+Parses @darkarts symbolic annotations with support for:
+- Pattern shortcuts (:uuid, :email, ≥N, etc.)
+- Enhanced abbreviations (200+ terms)
+- New symbols (⇄, ⊕, ⊗, ≈, ∴, ∀, ∃)
+- Better validation and error messages
+"""
+
+import re
+from typing import Dict, List, Optional, Any, Tuple
+from dataclasses import dataclass, field
+
+from .darkarts_symbols import (
+    ALL_SYMBOLS,
+    get_symbol_name,
+    get_symbol_description,
+    is_valid_symbol,
+    get_symbol_rules,
+)
+from .darkarts_patterns import (
+    compress_pattern,
+    expand_pattern,
+    validate_pattern,
+)
+from .darkarts_abbreviations import (
+    compress,
+    expand,
+)
+
+
+@dataclass
+class DarkArtsAnnotation:
+    """Parsed DarkArts annotation with v3.0.0 features."""
+    
+    # Core fields (v2.x)
+    purpose: Optional[str] = None  # ⊢
+    dependencies: List[str] = field(default_factory=list)  # ∂
+    assumptions: List[str] = field(default_factory=list)  # ⚠
+    preconditions: List[str] = field(default_factory=list)  # ⊳
+    postconditions: List[str] = field(default_factory=list)  # ⊲
+    invariants: List[str] = field(default_factory=list)  # ⊨
+    complexity: Optional[str] = None  # ⚡
+    security: List[str] = field(default_factory=list)  # 🔒
+    
+    # New fields (v3.0.0)
+    bidirectional: List[str] = field(default_factory=list)  # ⇄
+    side_effects: List[str] = field(default_factory=list)  # ⊕
+    forbidden: List[str] = field(default_factory=list)  # ⊗
+    approximation: List[str] = field(default_factory=list)  # ≈
+    consequence: List[str] = field(default_factory=list)  # ∴
+    universal: List[str] = field(default_factory=list)  # ∀
+    existential: List[str] = field(default_factory=list)  # ∃
+    
+    # Metadata
+    raw_text: str = ""
+    line_number: int = 0
+    validation_errors: List[str] = field(default_factory=list)
+    validation_warnings: List[str] = field(default_factory=list)
+    
+    def to_dict(self) -> Dict[str, Any]:
+        """Convert to dictionary."""
+        return {
+            'purpose': self.purpose,
+            'dependencies': self.dependencies,
+            'assumptions': self.assumptions,
+            'preconditions': self.preconditions,
+            'postconditions': self.postconditions,
+            'invariants': self.invariants,
+            'complexity': self.complexity,
+            'security': self.security,
+            'bidirectional': self.bidirectional,
+            'side_effects': self.side_effects,
+            'forbidden': self.forbidden,
+            'approximation': self.approximation,
+            'consequence': self.consequence,
+            'universal': self.universal,
+            'existential': self.existential,
+        }
+    
+    def has_errors(self) -> bool:
+        """Check if annotation has validation errors."""
+        return len(self.validation_errors) > 0
+    
+    def has_warnings(self) -> bool:
+        """Check if annotation has validation warnings."""
+        return len(self.validation_warnings) > 0
+
+
+class DarkArtsParserV3:
+    """
+    Enhanced parser for DarkArts v3.0.0 annotations.
+    
+    Features:
+    - Pattern shortcuts (:uuid, :email, ≥N, etc.)
+    - Enhanced abbreviations (200+ terms)
+    - New symbols (⇄, ⊕, ⊗, ≈, ∴, ∀, ∃)
+    - Better validation and error messages
+    """
+    
+    # Pattern to match @darkarts annotations
+    PATTERN = r'/\*\*@darkarts\s*(.*?)\s*\*/'
+    PATTERN_MULTILINE = r'"""@darkarts\s*(.*?)\s*"""'
+    
+    # Symbol to field mapping
+    SYMBOL_FIELDS = {
+        '⊢': 'purpose',
+        '∂': 'dependencies',
+        '⚠': 'assumptions',
+        '⊳': 'preconditions',
+        '⊲': 'postconditions',
+        '⊨': 'invariants',
+        '⚡': 'complexity',
+        '🔒': 'security',
+        '⇄': 'bidirectional',
+        '⊕': 'side_effects',
+        '⊗': 'forbidden',
+        '≈': 'approximation',
+        '∴': 'consequence',
+        '∀': 'universal',
+        '∃': 'existential',
+    }
+    
+    def __init__(self, enable_compression: bool = False, enable_validation: bool = True):
+        """
+        Initialize parser.
+        
+        Args:
+            enable_compression: Enable abbreviation compression
+            enable_validation: Enable validation checks
+        """
+        self.enable_compression = enable_compression
+        self.enable_validation = enable_validation
+    
+    def parse(self, source_code: str) -> List[DarkArtsAnnotation]:
+        """
+        Parse all @darkarts annotations from source code.
+        
+        Args:
+            source_code: Source code containing @darkarts annotations
+            
+        Returns:
+            List of parsed annotations
+        """
+        annotations = []
+        
+        # Try both patterns (JavaScript-style and Python-style)
+        patterns = [
+            (self.PATTERN, re.DOTALL),
+            (self.PATTERN_MULTILINE, re.DOTALL),
+        ]
+        
+        for pattern, flags in patterns:
+            matches = re.finditer(pattern, source_code, flags)
+            
+            for match in matches:
+                annotation_text = match.group(1)
+                line_number = source_code[:match.start()].count('\n') + 1
+                annotation = self.parse_annotation(annotation_text, line_number)
+                annotations.append(annotation)
+        
+        return annotations
+    
+    def parse_annotation(self, text: str, line_number: int = 0) -> DarkArtsAnnotation:
+        """
+        Parse a single @darkarts annotation.
+        
+        Args:
+            text: Annotation text (without @darkarts marker)
+            line_number: Line number in source file
+            
+        Returns:
+            Parsed annotation
+        """
+        annotation = DarkArtsAnnotation(raw_text=text, line_number=line_number)
+        
+        # Split into lines
+        lines = text.strip().split('\n')
+        
+        # Track which symbols we've seen
+        seen_symbols = set()
+        
+        for line_idx, line in enumerate(lines):
+            line = line.strip()
+            if not line:
+                continue
+            
+            # Find symbol at start of line
+            symbol = self._extract_symbol(line)
+            
+            if symbol:
+                # Validate symbol
+                if not is_valid_symbol(symbol):
+                    annotation.validation_errors.append(
+                        f"Line {line_number + line_idx}: Unknown symbol '{symbol}'"
+                    )
+                    continue
+                
+                # Check for duplicate symbols (if not allowed)
+                rules = get_symbol_rules(symbol)
+                if not rules.get('multiple', False) and symbol in seen_symbols:
+                    annotation.validation_errors.append(
+                        f"Line {line_number + line_idx}: Duplicate symbol '{symbol}'. "
+                        f"Only one {get_symbol_name(symbol)} allowed."
+                    )
+                
+                seen_symbols.add(symbol)
+                
+                # Extract content after symbol
+                content = line[len(symbol):].strip()
+                
+                # Remove surrounding braces if present
+                if content.startswith('{') and content.endswith('}'):
+                    content = content[1:-1]
+                
+                # Parse field
+                self._parse_field(annotation, symbol, content, line_number + line_idx)
+        
+        # Validate annotation
+        if self.enable_validation:
+            self._validate_annotation(annotation)
+        
+        return annotation
+    
+    def _extract_symbol(self, line: str) -> Optional[str]:
+        """Extract symbol from start of line."""
+        for symbol in ALL_SYMBOLS.keys():
+            if line.startswith(symbol):
+                return symbol
+        return None
+    
+    def _parse_field(self, annotation: DarkArtsAnnotation, symbol: str, 
+                     content: str, line_number: int):
+        """
+        Parse a field and update annotation.
+        
+        Args:
+            annotation: Annotation to update
+            symbol: Symbol (⊢, ∂, etc.)
+            content: Content to parse
+            line_number: Line number for error messages
+        """
+        field_name = self.SYMBOL_FIELDS.get(symbol)
+        if not field_name:
+            return
+        
+        # Apply compression if enabled
+        if self.enable_compression:
+            content = compress(content)
+        
+        # Parse based on field type
+        if field_name == 'purpose':
+            annotation.purpose = content
+        
+        elif field_name == 'complexity':
+            annotation.complexity = content
+        
+        elif field_name in ['dependencies', 'assumptions', 'preconditions', 
+                           'postconditions', 'invariants', 'security',
+                           'bidirectional', 'side_effects', 'forbidden',
+                           'approximation', 'consequence', 'universal', 'existential']:
+            # Parse as list
+            items = self._parse_list(content)
+            
+            # Validate patterns in preconditions
+            if field_name == 'preconditions' and self.enable_validation:
+                for item in items:
+                    # Check if item contains a pattern
+                    if ':' in item or any(op in item for op in ['≥', '≤', '>', '<', '∈', '[']):
+                        is_valid, error = validate_pattern(item)
+                        if not is_valid:
+                            annotation.validation_errors.append(
+                                f"Line {line_number}: {error}"
+                            )
+            
+            setattr(annotation, field_name, items)
+    
+    def _parse_list(self, content: str) -> List[str]:
+        """
+        Parse comma-separated list.
+        
+        Args:
+            content: Content like "a,b,c" or "{a,b,c}"
+            
+        Returns:
+            List of items
+        """
+        # Split by comma, respecting nested braces
+        items = []
+        current = []
+        depth = 0
+        
+        for char in content:
+            if char == '{':
+                depth += 1
+            elif char == '}':
+                depth -= 1
+            elif char == ',' and depth == 0:
+                item = ''.join(current).strip()
+                if item:
+                    items.append(item)
+                current = []
+                continue
+            
+            current.append(char)
+        
+        # Add last item
+        item = ''.join(current).strip()
+        if item:
+            items.append(item)
+        
+        return items
+    
+    def _validate_annotation(self, annotation: DarkArtsAnnotation):
+        """
+        Validate annotation and add warnings/errors.
+        
+        Args:
+            annotation: Annotation to validate
+        """
+        # Check required fields
+        if not annotation.purpose:
+            annotation.validation_errors.append(
+                f"Line {annotation.line_number}: Missing required purpose (⊢)"
+            )
+        
+        # Check for contradictions
+        self._check_contradictions(annotation)
+        
+        # Check for missing common fields
+        self._check_missing_fields(annotation)
+    
+    def _check_contradictions(self, annotation: DarkArtsAnnotation):
+        """Check for logical contradictions."""
+        # Check invariants vs side effects
+        if annotation.invariants and annotation.side_effects:
+            for invariant in annotation.invariants:
+                if 'no db mod' in invariant or 'no modification' in invariant:
+                    for effect in annotation.side_effects:
+                        if 'db' in effect or 'database' in effect:
+                            annotation.validation_errors.append(
+                                f"Line {annotation.line_number}: Contradiction - "
+                                f"invariant says no db modification, but side effect modifies db"
+                            )
+        
+        # Check forbidden vs side effects
+        if annotation.forbidden and annotation.side_effects:
+            for forbidden in annotation.forbidden:
+                for effect in annotation.side_effects:
+                    # Simple overlap check
+                    forbidden_words = set(forbidden.lower().split())
+                    effect_words = set(effect.lower().split())
+                    if forbidden_words & effect_words:
+                        annotation.validation_warnings.append(
+                            f"Line {annotation.line_number}: Possible contradiction - "
+                            f"forbidden operation '{forbidden}' but side effect '{effect}'"
+                        )
+    
+    def _check_missing_fields(self, annotation: DarkArtsAnnotation):
+        """Check for commonly missing fields."""
+        # If has side effects, should probably have security considerations
+        if annotation.side_effects and not annotation.security:
+            annotation.validation_warnings.append(
+                f"Line {annotation.line_number}: Side effects present but no security considerations"
+            )
+        
+        # If has dependencies, should probably have assumptions
+        if annotation.dependencies and not annotation.assumptions:
+            annotation.validation_warnings.append(
+                f"Line {annotation.line_number}: Dependencies present but no assumptions about their availability"
+            )
+    
+    def expand_annotation(self, annotation: DarkArtsAnnotation) -> DarkArtsAnnotation:
+        """
+        Expand abbreviated annotation to full form.
+        
+        Args:
+            annotation: Annotation with abbreviations
+            
+        Returns:
+            Annotation with expanded text
+        """
+        expanded = DarkArtsAnnotation(
+            raw_text=annotation.raw_text,
+            line_number=annotation.line_number,
+        )
+        
+        # Expand purpose
+        if annotation.purpose:
+            expanded.purpose = expand(annotation.purpose)
+        
+        # Expand lists
+        for field_name in ['dependencies', 'assumptions', 'preconditions',
+                          'postconditions', 'invariants', 'security',
+                          'bidirectional', 'side_effects', 'forbidden',
+                          'approximation', 'consequence', 'universal', 'existential']:
+            items = getattr(annotation, field_name)
+            if items:
+                expanded_items = [expand(item) for item in items]
+                # Also expand patterns in preconditions
+                if field_name == 'preconditions':
+                    expanded_items = [expand_pattern(item) for item in expanded_items]
+                setattr(expanded, field_name, expanded_items)
+        
+        # Copy complexity as-is
+        expanded.complexity = annotation.complexity
+        
+        return expanded
+    
+    def format_annotation(self, annotation: DarkArtsAnnotation, 
+                         expanded: bool = False) -> str:
+        """
+        Format annotation back to DarkArts notation.
+        
+        Args:
+            annotation: Annotation to format
+            expanded: Use expanded form (no abbreviations)
+            
+        Returns:
+            Formatted annotation string
+        """
+        if expanded:
+            annotation = self.expand_annotation(annotation)
+        
+        lines = []
+        
+        # Add purpose (required)
+        if annotation.purpose:
+            lines.append(f'⊢{{{annotation.purpose}}}')
+        
+        # Add other fields if present
+        if annotation.dependencies:
+            lines.append(f'∂{{{",".join(annotation.dependencies)}}}')
+        
+        if annotation.assumptions:
+            lines.append(f'⚠{{{",".join(annotation.assumptions)}}}')
+        
+        if annotation.preconditions:
+            lines.append(f'⊳{{{",".join(annotation.preconditions)}}}')
+        
+        if annotation.postconditions:
+            lines.append(f'⊲{{{",".join(annotation.postconditions)}}}')
+        
+        if annotation.invariants:
+            lines.append(f'⊨{{{",".join(annotation.invariants)}}}')
+        
+        if annotation.complexity:
+            lines.append(f'⚡{{{annotation.complexity}}}')
+        
+        if annotation.security:
+            lines.append(f'🔒{{{",".join(annotation.security)}}}')
+        
+        # v3.0.0 fields
+        if annotation.bidirectional:
+            lines.append(f'⇄{{{",".join(annotation.bidirectional)}}}')
+        
+        if annotation.side_effects:
+            lines.append(f'⊕{{{",".join(annotation.side_effects)}}}')
+        
+        if annotation.forbidden:
+            lines.append(f'⊗{{{",".join(annotation.forbidden)}}}')
+        
+        if annotation.approximation:
+            lines.append(f'≈{{{",".join(annotation.approximation)}}}')
+        
+        if annotation.consequence:
+            lines.append(f'∴{{{",".join(annotation.consequence)}}}')
+        
+        if annotation.universal:
+            lines.append(f'∀{{{",".join(annotation.universal)}}}')
+        
+        if annotation.existential:
+            lines.append(f'∃{{{",".join(annotation.existential)}}}')
+        
+        return '\n'.join(lines)