@voodocs/cli 0.3.1 → 0.4.0

package/lib/darkarts/annotations/darkarts_parser.py

@@ -0,0 +1,238 @@
+"""@darkarts
+⊢parser:darkarts.annotations
+∂{re,typing,symbols}
+⚠{@darkarts∈docstrings,unicode-support}
+⊨{∀parse→structured-output,¬modify-src,handle-errors}
+🔒{read-only}
+⚡{O(n)|n=annotation-length}
+
+DarkArts Annotation Parser
+
+Parses @darkarts symbolic annotations from source code.
+"""
+
+import re
+from typing import Dict, List, Optional, Any
+from dataclasses import dataclass, field
+
+from .symbols import VOCABULARY, get_meta_symbols
+
+
+@dataclass
+class DarkArtsAnnotation:
+    """Parsed DarkArts annotation."""
+    module: Optional[str] = None  # From ⊢
+    dependencies: List[str] = field(default_factory=list)  # From ∂
+    assumptions: List[str] = field(default_factory=list)  # From ⚠
+    invariants: List[str] = field(default_factory=list)  # From ⊨
+    security: Optional[str] = None  # From 🔒
+    performance: Optional[str] = None  # From ⚡
+    complexity: Optional[str] = None  # From 📊
+    objectives: Optional[str] = None  # From 🎯
+    configuration: Optional[str] = None  # From ⚙️
+    raw_text: str = ""  # Original annotation text
+    
+    def to_dict(self) -> Dict[str, Any]:
+        """Convert to dictionary."""
+        return {
+            'module': self.module,
+            'dependencies': self.dependencies,
+            'assumptions': self.assumptions,
+            'invariants': self.invariants,
+            'security': self.security,
+            'performance': self.performance,
+            'complexity': self.complexity,
+            'objectives': self.objectives,
+            'configuration': self.configuration,
+        }
+
+
+class DarkArtsParser:
+    """
+    Parser for DarkArts symbolic annotations.
+    
+    Extracts and parses @darkarts annotations from source code.
+    """
+    
+    # Pattern to match @darkarts annotations
+    PATTERN = r'"""@darkarts\s*(.*?)\s*"""'
+    
+    # Meta symbol mappings
+    META_SYMBOLS = {
+        '⊢': 'module',
+        '∂': 'dependencies',
+        '⚠': 'assumptions',
+        '⊨': 'invariants',
+        '🔒': 'security',
+        '⚡': 'performance',
+        '📊': 'complexity',
+        '🎯': 'objectives',
+        '⚙️': 'configuration',
+    }
+    
+    def __init__(self):
+        """Initialize the parser."""
+        self.meta_symbols = get_meta_symbols()
+    
+    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 = []
+        
+        # Find all @darkarts blocks
+        matches = re.finditer(self.PATTERN, source_code, re.DOTALL)
+        
+        for match in matches:
+            annotation_text = match.group(1)
+            annotation = self.parse_annotation(annotation_text)
+            annotations.append(annotation)
+        
+        return annotations
+    
+    def parse_annotation(self, text: str) -> DarkArtsAnnotation:
+        """
+        Parse a single @darkarts annotation.
+        
+        Args:
+            text: Annotation text (without @darkarts marker)
+            
+        Returns:
+            Parsed annotation
+        """
+        annotation = DarkArtsAnnotation(raw_text=text)
+        
+        # Split into lines
+        lines = text.strip().split('\n')
+        
+        for line in lines:
+            line = line.strip()
+            if not line:
+                continue
+            
+            # Check for meta symbols
+            for symbol, field_name in self.META_SYMBOLS.items():
+                if line.startswith(symbol):
+                    # Extract content after symbol
+                    content = line[len(symbol):].strip()
+                    self._parse_field(annotation, field_name, content)
+                    break
+        
+        return annotation
+    
+    def _parse_field(self, annotation: DarkArtsAnnotation, field_name: str, content: str):
+        """
+        Parse a field and update annotation.
+        
+        Args:
+            annotation: Annotation to update
+            field_name: Name of field (module, dependencies, etc.)
+            content: Content to parse
+        """
+        if field_name == 'module':
+            annotation.module = content
+        
+        elif field_name == 'dependencies':
+            annotation.dependencies = self._parse_set(content)
+        
+        elif field_name == 'assumptions':
+            annotation.assumptions = self._parse_set(content)
+        
+        elif field_name == 'invariants':
+            annotation.invariants = self._parse_set(content)
+        
+        elif field_name == 'security':
+            annotation.security = content
+        
+        elif field_name == 'performance':
+            annotation.performance = content
+        
+        elif field_name == 'complexity':
+            annotation.complexity = content
+        
+        elif field_name == 'objectives':
+            annotation.objectives = content
+        
+        elif field_name == 'configuration':
+            annotation.configuration = content
+    
+    def _parse_set(self, content: str) -> List[str]:
+        """
+        Parse a set notation {a,b,c} into a list.
+        
+        Args:
+            content: Content like "{a,b,c}" or "a,b,c"
+            
+        Returns:
+            List of items
+        """
+        # Remove braces if present
+        content = content.strip()
+        if content.startswith('{') and content.endswith('}'):
+            content = content[1:-1]
+        
+        # Split by comma
+        items = []
+        current = []
+        depth = 0
+        in_string = False
+        
+        for char in content:
+            if char == '{' and not in_string:
+                depth += 1
+            elif char == '}' and not in_string:
+                depth -= 1
+            elif char == '"':
+                in_string = not in_string
+            elif char == ',' and depth == 0 and not in_string:
+                item = ''.join(current).strip()
+                if item:
+                    items.append(item)
+                current = []
+                continue
+            
+            current.append(char)
+        
+        # Add last item
+        if current:
+            item = ''.join(current).strip()
+            if item:
+                items.append(item)
+        
+        return items
+    
+    def parse_file(self, file_path: str) -> List[DarkArtsAnnotation]:
+        """
+        Parse @darkarts annotations from a file.
+        
+        Args:
+            file_path: Path to source file
+            
+        Returns:
+            List of parsed annotations
+        """
+        with open(file_path, 'r', encoding='utf-8') as f:
+            source_code = f.read()
+        
+        return self.parse(source_code)
+
+
+# Convenience function
+def parse_darkarts(source_code: str) -> List[DarkArtsAnnotation]:
+    """
+    Parse @darkarts annotations from source code.
+    
+    Args:
+        source_code: Source code containing @darkarts annotations
+        
+    Returns:
+        List of parsed annotations
+    """
+    parser = DarkArtsParser()
+    return parser.parse(source_code)

package/lib/darkarts/annotations/parser.py

@@ -1,4 +1,11 @@
-"""
+"""@darkarts
+⊢parser:annotations.multi-lang
+∂{re,ast,pathlib,types}
+⚠{src:utf8,@voodocs∈docstrings,yaml-lists,fs:readable}
+⊨{∀parse→¬modify-src,∀read→handle-encoding,parsed∈pyobj,dedup-invariants,lang-detect:accurate}
+🔒{read-only,¬exec}
+⚡{O(n'*m/c)|n'=files-with-annotations,m=avg-file-size,c=cache-constant,speedup=5-10x}
+
 DarkArts Annotation Parser
 
 Extracts DarkArts annotations from source code in multiple languages.
@@ -8,8 +15,10 @@ import re
 import ast
 import json
 import subprocess
+import os
 from typing import List, Optional, Dict, Any
 from pathlib import Path
+from functools import lru_cache
 
 from .types import (
     ParsedAnnotations,
@@ -39,6 +48,11 @@ class AnnotationParser:
     # Regex patterns for different languages
     PATTERNS = {
         Language.PYTHON: r'"""@voodocs\s*(.*?)\s*"""',
+    }
+    
+    # DarkArts patterns (symbolic annotations)
+    DARKARTS_PATTERNS = {
+        Language.PYTHON: r'"""@darkarts\s*(.*?)\s*"""',
         Language.TYPESCRIPT: r'/\*@voodocs\s*(.*?)\s*\*/',
         Language.JAVASCRIPT: r'/\*@voodocs\s*(.*?)\s*\*/',
         Language.JAVA: r'/\*@voodocs\s*(.*?)\s*\*/',
@@ -75,7 +89,35 @@ class AnnotationParser:
         return mapping.get(ext, Language.PYTHON)
     
     def parse_file(self, source_file: str) -> ParsedAnnotations:
-        """Parse annotations from a source file."""
+        """
+        Parse annotations from a source file.
+        
+        Phase 1 Optimization: Cache results based on file modification time.
+        """
+        # Get file modification time for cache key
+        try:
+            mtime = os.path.getmtime(source_file)
+        except OSError:
+            mtime = 0
+        
+        # Use cached version if available
+        return self._parse_file_cached(source_file, mtime)
+    
+    @lru_cache(maxsize=1000)
+    def _parse_file_cached(self, source_file: str, mtime: float) -> ParsedAnnotations:
+        """
+        Parse annotations from a source file with caching.
+        
+        Phase 1 Optimization: LRU cache with mtime as key.
+        Cache invalidates when file is modified (mtime changes).
+        
+        Args:
+            source_file: Path to the source file
+            mtime: File modification time (used as cache key)
+        
+        Returns:
+            ParsedAnnotations object
+        """
         with open(source_file, 'r', encoding='utf-8') as f:
             source_code = f.read()
         
@@ -92,9 +134,22 @@ class AnnotationParser:
         if language is None:
             language = self.detect_language(source_file)
         
-        # Extract all annotation blocks
-        pattern = self.PATTERNS[language]
-        matches = re.finditer(pattern, source_code, re.DOTALL)
+        # Extract all annotation blocks (VooDocs and DarkArts)
+        pattern = self.PATTERNS.get(language, self.PATTERNS[Language.PYTHON])
+        darkarts_pattern = self.DARKARTS_PATTERNS.get(language, self.DARKARTS_PATTERNS[Language.PYTHON])
+        
+        # Try VooDocs first
+        voodocs_matches = list(re.finditer(pattern, source_code, re.DOTALL))
+        
+        # Also check for DarkArts
+        darkarts_matches = list(re.finditer(darkarts_pattern, source_code, re.DOTALL))
+        
+        # If we found DarkArts annotations, translate them to VooDocs format
+        if darkarts_matches and not voodocs_matches:
+            return self._parse_darkarts_annotations(source_code, source_file, language, darkarts_matches)
+        
+        # Use VooDocs annotations
+        matches = voodocs_matches
         
         annotations = []
         for match in matches:
@@ -628,10 +683,35 @@ class AnnotationParser:
         if 'side_effects' in annotations:
             func.side_effects = annotations['side_effects'] if isinstance(annotations['side_effects'], list) else [annotations['side_effects']]
 
+    @staticmethod
+    def _has_annotations(file_path: Path) -> bool:
+        """
+        Quick check if a file contains @voodocs annotations.
+        
+        Phase 1 Optimization: Pre-filter files before full parsing.
+        Reads only first 10KB to check for @voodocs marker.
+        
+        Args:
+            file_path: Path to the file to check
+        
+        Returns:
+            True if file likely contains annotations, False otherwise
+        """
+        try:
+            with open(file_path, 'r', encoding='utf-8', errors='ignore') as f:
+                # Read first 10KB (enough for module-level annotations)
+                preview = f.read(10000)
+                return '@voodocs' in preview
+        except Exception:
+            # If we can't read it, skip it
+            return False
+    
     def parse_directory(self, directory: Path) -> List[ParsedAnnotations]:
         """
         Parse all source files in a directory recursively.
         
+        Phase 1 Optimization: Pre-filter files before parsing.
+        
         Args:
             directory: Path to the directory to scan
         
@@ -662,6 +742,10 @@ class AnnotationParser:
             if path.suffix.lower() not in extensions:
                 continue
             
+            # Phase 1 Optimization: Pre-filter files without annotations
+            if not self._has_annotations(path):
+                continue
+            
             try:
                 # Parse the file
                 parsed = self.parse_file(str(path))
@@ -680,3 +764,100 @@ class AnnotationParser:
                 continue
         
         return results
+    
+    def _parse_darkarts_annotations(
+        self,
+        source_code: str,
+        source_file: str,
+        language: Language,
+        darkarts_matches: List
+    ) -> ParsedAnnotations:
+        """Parse @darkarts annotations and translate to VooDocs format."""
+        from .darkarts_parser import parse_darkarts
+        from .translator import DarkArtsTranslator
+        
+        # Parse all @darkarts annotations
+        translator = DarkArtsTranslator()
+        translated_annotations = []
+        
+        for match in darkarts_matches:
+            darkarts_text = match.group(1)
+            
+            # Parse @darkarts annotation (parse_annotation expects just the content)
+            from .darkarts_parser import DarkArtsParser
+            parser = DarkArtsParser()
+            darkarts_annotation = parser.parse_annotation(darkarts_text)
+            
+            # Process the annotation
+            if darkarts_annotation:
+                # Convert DarkArtsAnnotation to dict for YAML generation
+                annotation_dict = {
+                    'module': darkarts_annotation.module,
+                    'dependencies': darkarts_annotation.dependencies,
+                    'assumptions': darkarts_annotation.assumptions,
+                    'invariants': darkarts_annotation.invariants,
+                    'security_model': darkarts_annotation.security,
+                    'performance': darkarts_annotation.performance,
+                }
+                
+                # Convert to @voodocs YAML format
+                voodocs_yaml = self._darkarts_to_voodocs_yaml(annotation_dict)
+                
+                line_number = source_code[:match.start()].count('\n') + 1
+                translated_annotations.append({
+                    'text': voodocs_yaml,
+                    'line': line_number,
+                    'start': match.start(),
+                    'end': match.end(),
+                })
+        
+        # Parse as if they were @voodocs
+        if language == Language.PYTHON:
+            return self._parse_python(source_code, source_file, translated_annotations)
+        else:
+            return self._parse_generic(source_code, source_file, language, translated_annotations)
+    
+    def _darkarts_to_voodocs_yaml(self, annotation_dict: Dict[str, Any]) -> str:
+        """Convert DarkArts annotation dict to @voodocs YAML format."""
+        lines = []
+        
+        # Module name becomes module_purpose (just use the identifier)
+        if annotation_dict.get('module'):
+            lines.append(f'module_purpose: "Module {annotation_dict["module"]}"')
+        
+        # Dependencies - keep as-is
+        if annotation_dict.get('dependencies'):
+            lines.append('dependencies: [')
+            for dep in annotation_dict['dependencies']:
+                lines.append(f'    "{dep}",')
+            lines.append(']')
+        
+        # Assumptions - keep as-is
+        if annotation_dict.get('assumptions'):
+            lines.append('assumptions: [')
+            for assumption in annotation_dict['assumptions']:
+                lines.append(f'    "{assumption}",')
+            lines.append(']')
+        
+        # Invariants - keep as-is
+        if annotation_dict.get('invariants'):
+            lines.append('invariants: [')
+            for invariant in annotation_dict['invariants']:
+                lines.append(f'    "{invariant}",')
+            lines.append(']')
+        
+        # Security model
+        if annotation_dict.get('security_model'):
+            sec = annotation_dict['security_model']
+            if isinstance(sec, list):
+                sec = ', '.join(sec)
+            lines.append(f'security_model: "{sec}"')
+        
+        # Performance
+        if annotation_dict.get('performance'):
+            perf = annotation_dict['performance']
+            if isinstance(perf, dict):
+                perf = str(perf)
+            lines.append(f'performance_model: "{perf}"')
+        
+        return '\n'.join(lines)