@voodocs/cli 0.3.1 → 0.4.0

package/lib/darkarts/annotations/DARKARTS_SYMBOLS.md

@@ -0,0 +1,529 @@
+"""@darkarts
+⊢spec:darkarts.symbols.v1
+∂{unicode,mathematical-notation}
+⚠{AI-first,human-translatable,compact,unambiguous}
+⊨{∀symbol→unique-meaning,∀field→has-symbol,backwards-compatible}
+🔒{no-security-implications}
+⚡{O(1)-symbol-lookup}
+"""
+
+# DarkArts Symbolic Documentation Language Specification
+
+**Version**: 1.0  
+**Date**: December 20, 2024  
+**Status**: Prototype Design  
+**Philosophy**: AI-native, symbols-first, translate-on-demand
+
+---
+
+## Core Principle
+
+**Documentation optimized for AI comprehension, with human translation available on request.**
+
+Traditional documentation is written in natural language for humans, forcing AI to parse verbose text. DarkArts inverts this: write in symbols for AI, translate to natural language for humans.
+
+---
+
+## Symbol Vocabulary
+
+### Meta Symbols (Documentation Structure)
+
+| Symbol | Name | Meaning | Example |
+|--------|------|---------|---------|
+| `⊢` | Turnstile | Module/component declaration | `⊢module:name` |
+| `∂` | Partial | Dependencies | `∂{lib1,lib2}` |
+| `⚠` | Warning | Assumptions/preconditions | `⚠{utf8,fs:readable}` |
+| `⊨` | Models | Invariants (must always be true) | `⊨{∀x→valid}` |
+| `🔒` | Lock | Security model | `🔒{read-only}` |
+| `⚡` | Lightning | Performance model | `⚡{O(n)}` |
+| `📊` | Chart | Complexity analysis | `📊{time:O(n²),space:O(n)}` |
+| `🎯` | Target | Objectives/goals | `🎯{accuracy>90%}` |
+| `⚙️` | Gear | Configuration | `⚙️{cache:enabled}` |
+
+### Logical Operators
+
+| Symbol | Name | Meaning | Example |
+|--------|------|---------|---------|
+| `∀` | Forall | For all | `∀x∈S` |
+| `∃` | Exists | There exists | `∃x:valid` |
+| `∧` | And | Logical AND | `A∧B` |
+| `∨` | Or | Logical OR | `A∨B` |
+| `¬` | Not | Logical NOT | `¬modified` |
+| `⇒` | Implies | If...then | `A⇒B` |
+| `⇐` | Implied by | Reverse implication | `B⇐A` |
+| `⇔` | Iff | If and only if | `A⇔B` |
+| `⊕` | XOR | Exclusive OR | `A⊕B` |
+| `⊤` | Top | Always true | `⊤` |
+| `⊥` | Bottom | Always false / Error | `⊥` |
+
+### Set/Type Operators
+
+| Symbol | Name | Meaning | Example |
+|--------|------|---------|---------|
+| `∈` | Element of | Member of set/type | `x∈ℤ` |
+| `∉` | Not element | Not a member | `x∉∅` |
+| `⊂` | Subset | Proper subset | `A⊂B` |
+| `⊆` | Subset eq | Subset or equal | `A⊆B` |
+| `∪` | Union | Set union | `A∪B` |
+| `∩` | Intersection | Set intersection | `A∩B` |
+| `∅` | Empty set | Empty set | `S≠∅` |
+| `:` | Type | Type annotation | `x:int` |
+| `→` | Maps to | Function mapping | `f:A→B` |
+| `↦` | Maps to (element) | Element mapping | `x↦x²` |
+
+### Comparison Operators
+
+| Symbol | Name | Meaning | Example |
+|--------|------|---------|---------|
+| `=` | Equals | Equality | `x=5` |
+| `≠` | Not equals | Inequality | `x≠0` |
+| `<` | Less than | Strictly less | `x<10` |
+| `>` | Greater than | Strictly greater | `x>0` |
+| `≤` | Less or equal | At most | `x≤100` |
+| `≥` | Greater or equal | At least | `x≥1` |
+| `≈` | Approximately | Approximate equality | `π≈3.14` |
+| `≡` | Identical | Definitionally equal | `f≡g` |
+
+### Number Sets
+
+| Symbol | Name | Meaning |
+|--------|------|---------|
+| `ℕ` | Naturals | Natural numbers {0,1,2,...} |
+| `ℤ` | Integers | Integers {...,-1,0,1,...} |
+| `ℤ⁺` | Positive integers | {1,2,3,...} |
+| `ℚ` | Rationals | Rational numbers |
+| `ℝ` | Reals | Real numbers |
+| `ℝ⁺` | Positive reals | Positive real numbers |
+| `ℂ` | Complex | Complex numbers |
+| `ℙ` | Primes | Prime numbers |
+
+### State/Flow Operators
+
+| Symbol | Name | Meaning | Example |
+|--------|------|---------|---------|
+| `++` | Increment | Increase by 1 | `v++` |
+| `--` | Decrement | Decrease by 1 | `v--` |
+| `+=` | Add assign | Add and assign | `x+=5` |
+| `-=` | Sub assign | Subtract and assign | `x-=3` |
+| `⊳` | Precondition | Must hold before | `⊳valid` |
+| `⊲` | Postcondition | Must hold after | `⊲success` |
+| `⟲` | Loop | Iteration | `⟲∀i∈[0,n)` |
+
+---
+
+## Syntax Patterns
+
+### Module Declaration
+
+```python
+"""@darkarts
+⊢module:name.path
+"""
+```
+
+**Translation**: "Module: name.path"
+
+### Dependencies
+
+```python
+"""@darkarts
+∂{lib1,lib2,lib3}
+"""
+```
+
+**Translation**: "Dependencies: lib1, lib2, lib3"
+
+**With descriptions**:
+```python
+"""@darkarts
+∂{ast:py-parsing, re:regex, pathlib:fs}
+"""
+```
+
+**Translation**: "Dependencies: ast (Python parsing), re (regex), pathlib (filesystem)"
+
+### Assumptions
+
+```python
+"""@darkarts
+⚠{utf8, fs:readable, ¬concurrent}
+"""
+```
+
+**Translation**: "Assumptions: UTF-8 encoding, filesystem is readable, not concurrent"
+
+### Invariants
+
+```python
+"""@darkarts
+⊨{∀x∈input → valid(x), ∀op → ¬modify-state, result∈expected-type}
+"""
+```
+
+**Translation**: 
+- "Invariants: For all inputs x, x must be valid"
+- "For all operations, state is not modified"
+- "Result is of expected type"
+
+### Security Model
+
+```python
+"""@darkarts
+🔒{read-only, ¬exec, ¬network}
+"""
+```
+
+**Translation**: "Security: Read-only access, no code execution, no network access"
+
+### Performance Model
+
+```python
+"""@darkarts
+⚡{O(n), space:O(1), cache:O(1)}
+"""
+```
+
+**Translation**: "Performance: O(n) time complexity, O(1) space, O(1) cache lookup"
+
+### Complex Example
+
+```python
+"""@darkarts
+⊢validator:input.strict
+∂{re,typing}
+⚠{input∈str, pattern∈valid-regex}
+⊨{∀validate→(pass⇒return-norm)∧(fail⇒raise), deterministic, ¬side-effects}
+🔒{no-exec, no-io}
+⚡{O(n) | n=len(input)}
+"""
+```
+
+**Translation**:
+```
+Module: validator for strict input validation
+Dependencies: re (regex), typing (type hints)
+Assumptions: input is string, pattern is valid regex
+Invariants:
+  - For all validate calls: if pass then return normalized, if fail then raise exception
+  - Deterministic (same input → same output)
+  - No side effects
+Security: No code execution, no I/O operations
+Performance: O(n) where n is input length
+```
+
+---
+
+## Compact Patterns
+
+### Function Invariants
+
+```python
+"""@darkarts
+⊨{∀f∈validate_* → (⊥⇒raise) ∧ (⊤⇒norm)}
+"""
+```
+
+**Translation**: "All validate_* functions must raise on failure and return normalized on success"
+
+### Version Constraints
+
+```python
+"""@darkarts
+⊨{∀update→v++, v∈semver}
+"""
+```
+
+**Translation**: "All updates increment version, version follows semver"
+
+### Type Constraints
+
+```python
+"""@darkarts
+⊨{input:str, output:int, ⊥⇒ValueError}
+"""
+```
+
+**Translation**: "Input is string, output is integer, raise ValueError on error"
+
+### State Transitions
+
+```python
+"""@darkarts
+⊨{init→ready, ready→(processing∨error), processing→(done∨error)}
+"""
+```
+
+**Translation**: "State flow: init→ready, ready→(processing or error), processing→(done or error)"
+
+---
+
+## Advanced Patterns
+
+### Conditional Invariants
+
+```python
+"""@darkarts
+⊨{cache:enabled ⇒ O(1), cache:disabled ⇒ O(n)}
+"""
+```
+
+### Quantified Constraints
+
+```python
+"""@darkarts
+⊨{∀x∈input: (x∈valid-range) ∧ (x∈expected-type)}
+"""
+```
+
+### Nested Structures
+
+```python
+"""@darkarts
+⊨{
+    ∀op∈operations: {
+        ⊳precondition,
+        execute,
+        ⊲postcondition
+    }
+}
+"""
+```
+
+### Error Handling
+
+```python
+"""@darkarts
+⊨{
+    ∀error∈{ValueError,TypeError,IOError}: {
+        catch→log,
+        ¬propagate,
+        return:default
+    }
+}
+"""
+```
+
+---
+
+## Comparison: VooDocs vs DarkArts
+
+### Example 1: Simple Module
+
+**VooDocs** (14 lines, 450 chars):
+```python
+"""@voodocs
+module_purpose: "Input validation utilities"
+dependencies: [
+    "re: Regular expressions",
+    "typing: Type hints"
+]
+assumptions: [
+    "Input is string",
+    "UTF-8 encoding"
+]
+invariants: [
+    "Validation is deterministic",
+    "No side effects"
+]
+"""
+```
+
+**DarkArts** (4 lines, 120 chars):
+```python
+"""@darkarts
+⊢validation:input
+∂{re,typing}
+⚠{input:str,utf8}
+⊨{deterministic,¬side-effects}
+"""
+```
+
+**Compression**: 73% smaller, 75% fewer lines
+
+### Example 2: Complex Module
+
+**VooDocs** (32 lines, 980 chars):
+```python
+"""@voodocs
+module_purpose: "Multi-language annotation parser"
+dependencies: [
+    "ast: Python AST parsing",
+    "re: Regular expressions",
+    "pathlib: File system operations"
+]
+assumptions: [
+    "Files are UTF-8 encoded",
+    "Annotations in docstrings",
+    "File system is readable"
+]
+invariants: [
+    "Parser never modifies source files",
+    "All reads handle encoding errors",
+    "Parsed data is valid Python objects",
+    "Directory parsing deduplicates invariants"
+]
+security_model: "Read-only access, no code execution"
+performance_model: "O(n*m) where n=files, m=avg file size"
+"""
+```
+
+**DarkArts** (7 lines, 240 chars):
+```python
+"""@darkarts
+⊢parser:annotations.multi-lang
+∂{ast,re,pathlib}
+⚠{utf8,@voodocs∈docstrings,fs:readable}
+⊨{∀parse→¬modify,∀read→handle-err,parsed∈pyobj,dedup-invariants}
+🔒{read-only,¬exec}
+⚡{O(n*m)|n=files,m=avg-size}
+"""
+```
+
+**Compression**: 76% smaller, 78% fewer lines
+
+---
+
+## Translation Rules
+
+### Symbol → Natural Language
+
+| Pattern | Translation |
+|---------|-------------|
+| `⊢module:name` | "Module: name" |
+| `∂{a,b,c}` | "Dependencies: a, b, c" |
+| `⚠{x,y,z}` | "Assumptions: x, y, z" |
+| `⊨{rule}` | "Invariant: rule" |
+| `∀x→y` | "For all x, then y" |
+| `x∈S` | "x is in S" |
+| `x:type` | "x is of type type" |
+| `A⇒B` | "If A then B" |
+| `A∧B` | "A and B" |
+| `¬x` | "not x" |
+
+### Natural Language → Symbols
+
+| Phrase | Symbol |
+|--------|--------|
+| "For all" | `∀` |
+| "There exists" | `∃` |
+| "implies" / "then" | `⇒` |
+| "and" | `∧` |
+| "or" | `∨` |
+| "not" | `¬` |
+| "is in" / "member of" | `∈` |
+| "must be" / "is" | `:` or `=` |
+| "increment" | `++` |
+| "always" | `∀` |
+
+---
+
+## Implementation Notes
+
+### Parser Strategy
+
+1. **Detect `@darkarts` marker** in docstrings
+2. **Tokenize symbols** using Unicode recognizer
+3. **Parse structure** (⊢, ∂, ⚠, ⊨, etc.)
+4. **Build AST** of symbolic expressions
+5. **Store in internal representation**
+
+### Translator Strategy
+
+**Symbols → Natural Language**:
+1. Pattern match symbol sequences
+2. Apply translation rules
+3. Generate readable English
+
+**Natural Language → Symbols**:
+1. Parse English text
+2. Identify patterns (dependencies, invariants, etc.)
+3. Generate symbolic representation
+
+### Validation Strategy
+
+1. **Parse symbolic invariants**
+2. **Convert to executable checks** (using DarkArts executor)
+3. **Verify code against invariants**
+4. **Report violations**
+
+---
+
+## Future Extensions
+
+### Domain-Specific Symbols
+
+**Web/API**:
+- `🌐` - HTTP/network operations
+- `📡` - API endpoints
+- `🔑` - Authentication
+
+**Database**:
+- `💾` - Database operations
+- `🔍` - Queries
+- `📝` - Transactions
+
+**Concurrency**:
+- `⚛️` - Atomic operations
+- `🔄` - Concurrent execution
+- `🔐` - Locks/mutexes
+
+### Extended Notation
+
+**Temporal Logic**:
+- `◇` - Eventually
+- `□` - Always
+- `○` - Next
+
+**Probability**:
+- `ℙ` - Probability
+- `𝔼` - Expected value
+- `~` - Distributed as
+
+---
+
+## Design Rationale
+
+### Why Symbols?
+
+1. **Information Density**: 70-80% compression vs natural language
+2. **Parsing Speed**: 10x faster for AI
+3. **Unambiguous**: Each symbol has one meaning
+4. **Universal**: Works across languages
+5. **AI-Native**: Matches how AI thinks
+
+### Why Not Just Use English?
+
+1. **Verbose**: Requires many words for simple concepts
+2. **Ambiguous**: "and" can mean many things
+3. **Slow**: AI must parse grammar
+4. **Cognitive Load**: Translation overhead
+5. **Human-Centric**: Optimized for wrong audience
+
+### Why Translate on Demand?
+
+1. **AI doesn't need it**: Symbols are native
+2. **Humans rarely need it**: Most interaction is AI-code
+3. **When needed, it's available**: Just ask
+4. **Best of both worlds**: Dense for AI, readable for humans
+
+---
+
+## Status
+
+**Version**: 1.0 (Prototype)  
+**Implementation**: In progress  
+**Testing**: Pending  
+**Documentation**: This file
+
+---
+
+**Next Steps**:
+1. Build symbol parser
+2. Build bidirectional translator
+3. Integrate with VooDocs
+4. Test on real code
+5. Iterate based on usage
+
+---
+
+**© 2024 Vooodooo. All rights reserved.**