@voodocs/cli 0.3.2 → 0.4.0

package/lib/darkarts/annotations/symbols.py

@@ -0,0 +1,244 @@
+"""@darkarts
+⊢symbols:darkarts.vocabulary
+∂{typing,enum}
+⚠{unicode-support,symbols-unique}
+⊨{∀symbol→unique-meaning,bidirectional-mapping}
+🔒{no-implications}
+⚡{O(1)-lookup}
+
+DarkArts Symbol Vocabulary
+
+Defines all symbols used in DarkArts documentation language.
+"""
+
+from typing import Dict, List, Optional, Set
+from enum import Enum
+from dataclasses import dataclass
+
+
+class SymbolCategory(Enum):
+    """Categories of DarkArts symbols."""
+    META = "meta"  # Documentation structure (⊢, ∂, ⚠, ⊨)
+    LOGIC = "logic"  # Logical operators (∀, ∃, ∧, ∨, ¬, ⇒)
+    SET = "set"  # Set theory (∈, ⊂, ∪, ∩, ∅)
+    COMPARISON = "comparison"  # Comparisons (=, ≠, <, >, ≤, ≥)
+    NUMBER_SET = "number_set"  # Number sets (ℕ, ℤ, ℝ, ℂ)
+    STATE = "state"  # State/flow (++, --, ⊳, ⊲)
+    ARROW = "arrow"  # Arrows (→, ←, ⇒, ⇔)
+
+
+@dataclass
+class Symbol:
+    """Represents a DarkArts symbol."""
+    unicode: str  # Unicode character
+    name: str  # Human-readable name
+    category: SymbolCategory
+    meaning: str  # What it means
+    ascii: Optional[str] = None  # ASCII equivalent (if any)
+    
+    def __repr__(self) -> str:
+        return f"{self.unicode} ({self.name})"
+
+
+class DarkArtsVocabulary:
+    """
+    Complete vocabulary of DarkArts symbols.
+    
+    Provides bidirectional mapping between symbols and meanings.
+    """
+    
+    def __init__(self):
+        """Initialize the symbol vocabulary."""
+        self.symbols: Dict[str, Symbol] = {}
+        self.by_category: Dict[SymbolCategory, List[Symbol]] = {}
+        self.by_name: Dict[str, Symbol] = {}
+        
+        self._init_meta_symbols()
+        self._init_logic_symbols()
+        self._init_set_symbols()
+        self._init_comparison_symbols()
+        self._init_number_sets()
+        self._init_state_symbols()
+        self._init_arrow_symbols()
+    
+    def _add_symbol(self, unicode: str, name: str, category: SymbolCategory, 
+                    meaning: str, ascii: Optional[str] = None):
+        """Add a symbol to the vocabulary."""
+        symbol = Symbol(unicode, name, category, meaning, ascii)
+        self.symbols[unicode] = symbol
+        self.by_name[name] = symbol
+        
+        if category not in self.by_category:
+            self.by_category[category] = []
+        self.by_category[category].append(symbol)
+    
+    def _init_meta_symbols(self):
+        """Initialize meta/documentation structure symbols."""
+        self._add_symbol('⊢', 'turnstile', SymbolCategory.META, 
+                        'Module/component declaration', '|-')
+        self._add_symbol('∂', 'partial', SymbolCategory.META,
+                        'Dependencies', 'd')
+        self._add_symbol('⚠', 'warning', SymbolCategory.META,
+                        'Assumptions/preconditions', '!')
+        self._add_symbol('⊨', 'models', SymbolCategory.META,
+                        'Invariants (must always be true)', '|=')
+        self._add_symbol('🔒', 'lock', SymbolCategory.META,
+                        'Security model', '[lock]')
+        self._add_symbol('⚡', 'lightning', SymbolCategory.META,
+                        'Performance model', '[perf]')
+        self._add_symbol('📊', 'chart', SymbolCategory.META,
+                        'Complexity analysis', '[chart]')
+        self._add_symbol('🎯', 'target', SymbolCategory.META,
+                        'Objectives/goals', '[goal]')
+        self._add_symbol('⚙️', 'gear', SymbolCategory.META,
+                        'Configuration', '[config]')
+    
+    def _init_logic_symbols(self):
+        """Initialize logical operator symbols."""
+        self._add_symbol('∀', 'forall', SymbolCategory.LOGIC,
+                        'For all', 'forall')
+        self._add_symbol('∃', 'exists', SymbolCategory.LOGIC,
+                        'There exists', 'exists')
+        self._add_symbol('∧', 'and', SymbolCategory.LOGIC,
+                        'Logical AND', 'and')
+        self._add_symbol('∨', 'or', SymbolCategory.LOGIC,
+                        'Logical OR', 'or')
+        self._add_symbol('¬', 'not', SymbolCategory.LOGIC,
+                        'Logical NOT', 'not')
+        self._add_symbol('⇒', 'implies', SymbolCategory.LOGIC,
+                        'Implies (if...then)', '=>')
+        self._add_symbol('⇐', 'implied_by', SymbolCategory.LOGIC,
+                        'Implied by', '<=')
+        self._add_symbol('⇔', 'iff', SymbolCategory.LOGIC,
+                        'If and only if', '<=>') 
+        self._add_symbol('⊕', 'xor', SymbolCategory.LOGIC,
+                        'Exclusive OR', 'xor')
+        self._add_symbol('⊤', 'top', SymbolCategory.LOGIC,
+                        'Always true / Success', 'true')
+        self._add_symbol('⊥', 'bottom', SymbolCategory.LOGIC,
+                        'Always false / Error', 'false')
+    
+    def _init_set_symbols(self):
+        """Initialize set theory symbols."""
+        self._add_symbol('∈', 'in', SymbolCategory.SET,
+                        'Element of / Member of', 'in')
+        self._add_symbol('∉', 'notin', SymbolCategory.SET,
+                        'Not element of', 'notin')
+        self._add_symbol('⊂', 'subset', SymbolCategory.SET,
+                        'Proper subset', 'subset')
+        self._add_symbol('⊃', 'supset', SymbolCategory.SET,
+                        'Proper superset', 'supset')
+        self._add_symbol('⊆', 'subseteq', SymbolCategory.SET,
+                        'Subset or equal', 'subseteq')
+        self._add_symbol('⊇', 'supseteq', SymbolCategory.SET,
+                        'Superset or equal', 'supseteq')
+        self._add_symbol('∪', 'union', SymbolCategory.SET,
+                        'Set union', 'union')
+        self._add_symbol('∩', 'intersect', SymbolCategory.SET,
+                        'Set intersection', 'intersect')
+        self._add_symbol('∅', 'emptyset', SymbolCategory.SET,
+                        'Empty set', 'emptyset')
+    
+    def _init_comparison_symbols(self):
+        """Initialize comparison operator symbols."""
+        self._add_symbol('=', 'equals', SymbolCategory.COMPARISON,
+                        'Equals', '=')
+        self._add_symbol('≠', 'ne', SymbolCategory.COMPARISON,
+                        'Not equals', '!=')
+        self._add_symbol('<', 'lt', SymbolCategory.COMPARISON,
+                        'Less than', '<')
+        self._add_symbol('>', 'gt', SymbolCategory.COMPARISON,
+                        'Greater than', '>')
+        self._add_symbol('≤', 'le', SymbolCategory.COMPARISON,
+                        'Less than or equal', '<=')
+        self._add_symbol('≥', 'ge', SymbolCategory.COMPARISON,
+                        'Greater than or equal', '>=')
+        self._add_symbol('≈', 'approx', SymbolCategory.COMPARISON,
+                        'Approximately equal', '~=')
+        self._add_symbol('≡', 'equiv', SymbolCategory.COMPARISON,
+                        'Identical / Definitionally equal', '==')
+    
+    def _init_number_sets(self):
+        """Initialize number set symbols."""
+        self._add_symbol('ℕ', 'naturals', SymbolCategory.NUMBER_SET,
+                        'Natural numbers', 'N')
+        self._add_symbol('ℤ', 'integers', SymbolCategory.NUMBER_SET,
+                        'Integers', 'Z')
+        self._add_symbol('ℚ', 'rationals', SymbolCategory.NUMBER_SET,
+                        'Rational numbers', 'Q')
+        self._add_symbol('ℝ', 'reals', SymbolCategory.NUMBER_SET,
+                        'Real numbers', 'R')
+        self._add_symbol('ℂ', 'complex', SymbolCategory.NUMBER_SET,
+                        'Complex numbers', 'C')
+        self._add_symbol('ℙ', 'primes', SymbolCategory.NUMBER_SET,
+                        'Prime numbers', 'P')
+    
+    def _init_state_symbols(self):
+        """Initialize state/flow operator symbols."""
+        self._add_symbol('++', 'increment', SymbolCategory.STATE,
+                        'Increment by 1', '++')
+        self._add_symbol('--', 'decrement', SymbolCategory.STATE,
+                        'Decrement by 1', '--')
+        self._add_symbol('+=', 'add_assign', SymbolCategory.STATE,
+                        'Add and assign', '+=')
+        self._add_symbol('-=', 'sub_assign', SymbolCategory.STATE,
+                        'Subtract and assign', '-=')
+        self._add_symbol('⊳', 'precondition', SymbolCategory.STATE,
+                        'Precondition (must hold before)', '|>')
+        self._add_symbol('⊲', 'postcondition', SymbolCategory.STATE,
+                        'Postcondition (must hold after)', '<|')
+    
+    def _init_arrow_symbols(self):
+        """Initialize arrow symbols."""
+        self._add_symbol('→', 'arrow_right', SymbolCategory.ARROW,
+                        'Maps to / Leads to', '->')
+        self._add_symbol('←', 'arrow_left', SymbolCategory.ARROW,
+                        'Comes from', '<-')
+        self._add_symbol('↔', 'arrow_both', SymbolCategory.ARROW,
+                        'Bidirectional', '<->')
+        self._add_symbol('↦', 'mapsto', SymbolCategory.ARROW,
+                        'Element maps to', '|->')
+    
+    def get_symbol(self, unicode: str) -> Optional[Symbol]:
+        """Get symbol by Unicode character."""
+        return self.symbols.get(unicode)
+    
+    def get_by_name(self, name: str) -> Optional[Symbol]:
+        """Get symbol by name."""
+        return self.by_name.get(name)
+    
+    def get_category(self, category: SymbolCategory) -> List[Symbol]:
+        """Get all symbols in a category."""
+        return self.by_category.get(category, [])
+    
+    def is_symbol(self, char: str) -> bool:
+        """Check if character is a DarkArts symbol."""
+        return char in self.symbols
+    
+    def get_all_symbols(self) -> List[Symbol]:
+        """Get all symbols."""
+        return list(self.symbols.values())
+    
+    def get_meta_symbols(self) -> Set[str]:
+        """Get set of meta symbols (⊢, ∂, ⚠, ⊨, etc.)."""
+        return {s.unicode for s in self.get_category(SymbolCategory.META)}
+
+
+# Global vocabulary instance
+VOCABULARY = DarkArtsVocabulary()
+
+
+# Convenience functions
+def get_symbol(unicode: str) -> Optional[Symbol]:
+    """Get symbol by Unicode character."""
+    return VOCABULARY.get_symbol(unicode)
+
+
+def is_darkarts_symbol(char: str) -> bool:
+    """Check if character is a DarkArts symbol."""
+    return VOCABULARY.is_symbol(char)
+
+
+def get_meta_symbols() -> Set[str]:
+    """Get set of meta symbols."""
+    return VOCABULARY.get_meta_symbols()

package/lib/darkarts/annotations/translator.py

@@ -0,0 +1,386 @@
+"""@darkarts
+⊢translator:darkarts↔natural-lang
+∂{re,typing,symbols,darkarts_parser}
+⚠{bidirectional,preserves-meaning}
+⊨{∀translate→reversible,readable,accurate}
+🔒{no-implications}
+⚡{O(n)|n=text-length}
+
+DarkArts Bidirectional Translator
+
+Translates between DarkArts symbolic notation and natural language.
+"""
+
+import re
+from typing import Dict, List, Optional
+from .symbols import VOCABULARY
+from .darkarts_parser import DarkArtsAnnotation, DarkArtsParser
+
+
+class DarkArtsTranslator:
+    """
+    Bidirectional translator between DarkArts symbols and natural language.
+    
+    Supports:
+    - Symbols → Natural Language (for humans)
+    - Natural Language → Symbols (for writing)
+    """
+    
+    def __init__(self):
+        """Initialize the translator."""
+        self.vocab = VOCABULARY
+        
+        # Symbol → English mappings
+        self.symbol_to_english = {
+            '⊢': 'Module',
+            '∂': 'Dependencies',
+            '⚠': 'Assumptions',
+            '⊨': 'Invariants',
+            '🔒': 'Security Model',
+            '⚡': 'Performance',
+            '📊': 'Complexity',
+            '🎯': 'Objectives',
+            '⚙️': 'Configuration',
+            '∀': 'for all',
+            '∃': 'there exists',
+            '∧': 'and',
+            '∨': 'or',
+            '¬': 'not',
+            '⇒': 'implies',
+            '⇐': 'implied by',
+            '⇔': 'if and only if',
+            '∈': 'in',
+            '∉': 'not in',
+            '⊂': 'subset of',
+            '⊆': 'subset or equal to',
+            '∪': 'union',
+            '∩': 'intersection',
+            '∅': 'empty set',
+            '→': 'leads to',
+            '←': 'comes from',
+            '↔': 'bidirectional',
+            '⊤': 'success',
+            '⊥': 'failure',
+            '≤': 'less than or equal to',
+            '≥': 'greater than or equal to',
+            '≠': 'not equal to',
+            '≈': 'approximately',
+            '≡': 'identical to',
+            '++': 'increment',
+            '--': 'decrement',
+            '⊳': 'precondition',
+            '⊲': 'postcondition',
+            'ℕ': 'natural numbers',
+            'ℤ': 'integers',
+            'ℚ': 'rationals',
+            'ℝ': 'real numbers',
+            'ℂ': 'complex numbers',
+            'ℙ': 'prime numbers',
+        }
+        
+        # English → Symbol mappings (reverse)
+        self.english_to_symbol = {v: k for k, v in self.symbol_to_english.items()}
+        
+        # Add common variations
+        self.english_to_symbol.update({
+            'for every': '∀',
+            'for each': '∀',
+            'exists': '∃',
+            'then': '⇒',
+            'if': '⇒',
+            'iff': '⇔',
+            'element of': '∈',
+            'member of': '∈',
+            'not element of': '∉',
+            'true': '⊤',
+            'false': '⊥',
+            'error': '⊥',
+            'less or equal': '≤',
+            'greater or equal': '≥',
+            'not equal': '≠',
+            'approximately equal': '≈',
+            'equal': '=',
+        })
+    
+    def symbols_to_natural(self, annotation: DarkArtsAnnotation) -> str:
+        """
+        Translate DarkArts annotation to natural language.
+        
+        Args:
+            annotation: Parsed DarkArts annotation
+            
+        Returns:
+            Natural language description
+        """
+        lines = []
+        
+        # Module
+        if annotation.module:
+            lines.append(f"**Module**: {annotation.module}")
+            lines.append("")
+        
+        # Dependencies
+        if annotation.dependencies:
+            lines.append("**Dependencies**:")
+            for dep in annotation.dependencies:
+                # Check if dep has description (format: "name:description")
+                if ':' in dep:
+                    name, desc = dep.split(':', 1)
+                    lines.append(f"  - {name}: {desc}")
+                else:
+                    lines.append(f"  - {dep}")
+            lines.append("")
+        
+        # Assumptions
+        if annotation.assumptions:
+            lines.append("**Assumptions**:")
+            for assumption in annotation.assumptions:
+                translated = self._translate_expression(assumption)
+                lines.append(f"  - {translated}")
+            lines.append("")
+        
+        # Invariants
+        if annotation.invariants:
+            lines.append("**Invariants**:")
+            for invariant in annotation.invariants:
+                translated = self._translate_expression(invariant)
+                lines.append(f"  - {translated}")
+            lines.append("")
+        
+        # Security
+        if annotation.security:
+            lines.append(f"**Security Model**: {self._translate_expression(annotation.security)}")
+            lines.append("")
+        
+        # Performance
+        if annotation.performance:
+            lines.append(f"**Performance**: {self._translate_expression(annotation.performance)}")
+            lines.append("")
+        
+        # Complexity
+        if annotation.complexity:
+            lines.append(f"**Complexity**: {self._translate_expression(annotation.complexity)}")
+            lines.append("")
+        
+        # Objectives
+        if annotation.objectives:
+            lines.append(f"**Objectives**: {self._translate_expression(annotation.objectives)}")
+            lines.append("")
+        
+        # Configuration
+        if annotation.configuration:
+            lines.append(f"**Configuration**: {self._translate_expression(annotation.configuration)}")
+            lines.append("")
+        
+        return '\n'.join(lines).strip()
+    
+    def _translate_expression(self, expr: str) -> str:
+        """
+        Translate a symbolic expression to natural language.
+        
+        Args:
+            expr: Symbolic expression
+            
+        Returns:
+            Natural language translation
+        """
+        result = expr
+        
+        # Replace symbols with English
+        for symbol, english in self.symbol_to_english.items():
+            result = result.replace(symbol, f" {english} ")
+        
+        # Clean up spacing
+        result = re.sub(r'\s+', ' ', result).strip()
+        
+        # Capitalize first letter
+        if result:
+            result = result[0].upper() + result[1:]
+        
+        return result
+    
+    def natural_to_symbols(self, text: str) -> str:
+        """
+        Translate natural language to DarkArts symbols.
+        
+        Args:
+            text: Natural language description
+            
+        Returns:
+            Symbolic notation
+        """
+        result = text.lower()
+        
+        # Replace English phrases with symbols
+        # Sort by length (longest first) to avoid partial matches
+        phrases = sorted(self.english_to_symbol.items(), 
+                        key=lambda x: len(x[0]), reverse=True)
+        
+        for english, symbol in phrases:
+            result = result.replace(english, symbol)
+        
+        return result
+    
+    def translate_file(self, file_path: str, to_natural: bool = True) -> str:
+        """
+        Translate all @darkarts annotations in a file.
+        
+        Args:
+            file_path: Path to source file
+            to_natural: If True, translate to natural language; 
+                       if False, translate to symbols
+            
+        Returns:
+            Translated content
+        """
+        parser = DarkArtsParser()
+        annotations = parser.parse_file(file_path)
+        
+        if to_natural:
+            # Translate to natural language
+            results = []
+            for i, annotation in enumerate(annotations, 1):
+                results.append(f"## Annotation {i}\n")
+                results.append(self.symbols_to_natural(annotation))
+                results.append("\n---\n")
+            return '\n'.join(results)
+        else:
+            # Already in symbols, just return raw text
+            return '\n\n'.join(a.raw_text for a in annotations)
+    
+    def translate_annotation_text(self, text: str) -> str:
+        """
+        Translate a @darkarts annotation text to natural language.
+        
+        Args:
+            text: Annotation text (without @darkarts marker)
+            
+        Returns:
+            Natural language translation
+        """
+        parser = DarkArtsParser()
+        annotation = parser.parse_annotation(text)
+        return self.symbols_to_natural(annotation)
+    
+    def create_darkarts_from_voodocs(self, voodocs_dict: Dict) -> str:
+        """
+        Create @darkarts annotation from @voodocs dictionary.
+        
+        Args:
+            voodocs_dict: Dictionary with keys like 'module_purpose', 
+                         'dependencies', 'assumptions', 'invariants', etc.
+            
+        Returns:
+            DarkArts annotation text
+        """
+        lines = ['"""@darkarts']
+        
+        # Module
+        if 'module_purpose' in voodocs_dict:
+            purpose = voodocs_dict['module_purpose']
+            # Extract key parts (simplified)
+            lines.append(f"⊢{purpose}")
+        
+        # Dependencies
+        if 'dependencies' in voodocs_dict:
+            deps = voodocs_dict['dependencies']
+            if isinstance(deps, list):
+                # Simplify dependencies
+                simplified = []
+                for dep in deps:
+                    if ':' in dep:
+                        name, _ = dep.split(':', 1)
+                        simplified.append(name.strip())
+                    else:
+                        simplified.append(dep.strip())
+                lines.append(f"∂{{{','.join(simplified)}}}")
+        
+        # Assumptions
+        if 'assumptions' in voodocs_dict:
+            assumptions = voodocs_dict['assumptions']
+            if isinstance(assumptions, list):
+                # Simplify assumptions
+                simplified = [self._simplify_assumption(a) for a in assumptions]
+                lines.append(f"⚠{{{','.join(simplified)}}}")
+        
+        # Invariants
+        if 'invariants' in voodocs_dict:
+            invariants = voodocs_dict['invariants']
+            if isinstance(invariants, list):
+                # Convert to symbolic notation
+                symbolic = [self._convert_invariant(inv) for inv in invariants]
+                lines.append(f"⊨{{{','.join(symbolic)}}}")
+        
+        # Security
+        if 'security_model' in voodocs_dict:
+            security = self._simplify_text(voodocs_dict['security_model'])
+            lines.append(f"🔒{{{security}}}")
+        
+        # Performance
+        if 'performance_model' in voodocs_dict:
+            perf = voodocs_dict['performance_model']
+            lines.append(f"⚡{{{perf}}}")
+        
+        lines.append('"""')
+        return '\n'.join(lines)
+    
+    def _simplify_assumption(self, assumption: str) -> str:
+        """Simplify an assumption to compact form."""
+        # Remove common prefixes
+        assumption = assumption.lower()
+        for prefix in ['assume', 'assumes', 'assuming', 'we assume']:
+            if assumption.startswith(prefix):
+                assumption = assumption[len(prefix):].strip()
+        
+        # Convert to symbolic notation where possible
+        assumption = self.natural_to_symbols(assumption)
+        
+        return assumption
+    
+    def _convert_invariant(self, invariant: str) -> str:
+        """Convert an invariant to symbolic notation."""
+        # Convert "must" patterns
+        invariant = invariant.lower()
+        
+        # "all X must Y" → "∀X→Y"
+        invariant = re.sub(r'all (\w+) must (\w+)', r'∀\1→\2', invariant)
+        
+        # "X must Y" → "X→Y"
+        invariant = re.sub(r'(\w+) must (\w+)', r'\1→\2', invariant)
+        
+        # Convert common phrases to symbols
+        invariant = self.natural_to_symbols(invariant)
+        
+        return invariant
+    
+    def _simplify_text(self, text: str) -> str:
+        """Simplify text to compact form."""
+        # Remove articles
+        text = re.sub(r'\b(a|an|the)\b', '', text, flags=re.IGNORECASE)
+        
+        # Remove extra spaces
+        text = re.sub(r'\s+', ' ', text).strip()
+        
+        # Convert to symbols
+        text = self.natural_to_symbols(text)
+        
+        return text
+
+
+# Convenience functions
+def translate_to_natural(annotation: DarkArtsAnnotation) -> str:
+    """Translate DarkArts annotation to natural language."""
+    translator = DarkArtsTranslator()
+    return translator.symbols_to_natural(annotation)
+
+
+def translate_to_symbols(text: str) -> str:
+    """Translate natural language to DarkArts symbols."""
+    translator = DarkArtsTranslator()
+    return translator.natural_to_symbols(text)
+
+
+def convert_voodocs_to_darkarts(voodocs_dict: Dict) -> str:
+    """Convert @voodocs dictionary to @darkarts annotation."""
+    translator = DarkArtsTranslator()
+    return translator.create_darkarts_from_voodocs(voodocs_dict)

package/lib/darkarts/context/ai_instructions.py

@@ -1,4 +1,11 @@
-"""
+"""@darkarts
+⊢ai-instructions:ctx.templates
+∂{typing}
+⚠{ai:cursor∨claude,project:voodocs-enabled,templates:markdown}
+⊨{∀gen→valid-markdown,∀gen→include-cmds,∀gen→teach-best-practices}
+🔒{no-implications}
+⚡{O(1)|template-generation}
+
 AI instruction templates for VooDocs Context System.
 
 This module provides templates for generating AI assistant instructions