@voodocs/cli 2.2.1 → 2.2.2

package/lib/darkarts/annotations/DARKARTS_SYMBOLS.md

@@ -28,86 +28,86 @@ Traditional documentation is written in natural language for humans, forcing AI
 
 ### 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}`         |
+| 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 | `⊥`         |
+| 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²`  |
+| 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`    |
+| 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               |
+| 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)` |
+| 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)` |
 
 ---
 
@@ -134,7 +134,6 @@ Traditional documentation is written in natural language for humans, forcing AI
 **Translation**: "Dependencies: lib1, lib2, lib3"
 
 **With descriptions**:
-
 ```python
 """@darkarts
 ∂{ast:py-parsing, re:regex, pathlib:fs}
@@ -161,8 +160,7 @@ Traditional documentation is written in natural language for humans, forcing AI
 """
 ```
 
-**Translation**:
-
+**Translation**: 
 - "Invariants: For all inputs x, x must be valid"
 - "For all operations, state is not modified"
 - "Result is of expected type"
@@ -201,7 +199,6 @@ Traditional documentation is written in natural language for humans, forcing AI
 ```
 
 **Translation**:
-
 ```
 Module: validator for strict input validation
 Dependencies: re (regex), typing (type hints)
@@ -226,7 +223,7 @@ Performance: O(n) where n is input length
 """
 ```
 
-**Translation**: "All validate\_\* functions must raise on failure and return normalized on success"
+**Translation**: "All validate_* functions must raise on failure and return normalized on success"
 
 ### Version Constraints
 
@@ -308,12 +305,11 @@ Performance: O(n) where n is input length
 
 ---
 
-## Comparison: Voodocs vs DarkArts
+## Comparison: VooDocs vs DarkArts
 
 ### Example 1: Simple Module
 
-**Voodocs** (14 lines, 450 chars):
-
+**VooDocs** (14 lines, 450 chars):
 ```python
 """@voodocs
 module_purpose: "Input validation utilities"
@@ -333,7 +329,6 @@ invariants: [
 ```
 
 **DarkArts** (4 lines, 120 chars):
-
 ```python
 """@darkarts
 ⊢validation:input
@@ -347,8 +342,7 @@ invariants: [
 
 ### Example 2: Complex Module
 
-**Voodocs** (32 lines, 980 chars):
-
+**VooDocs** (32 lines, 980 chars):
 ```python
 """@voodocs
 module_purpose: "Multi-language annotation parser"
@@ -374,7 +368,6 @@ performance_model: "O(n*m) where n=files, m=avg file size"
 ```
 
 **DarkArts** (7 lines, 240 chars):
-
 ```python
 """@darkarts
 ⊢parser:annotations.multi-lang
@@ -394,33 +387,33 @@ performance_model: "O(n*m) where n=files, m=avg file size"
 
 ### 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"                 |
+| 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"              | `∀`        |
+| Phrase | Symbol |
+|--------|--------|
+| "For all" | `∀` |
+| "There exists" | `∃` |
+| "implies" / "then" | `⇒` |
+| "and" | `∧` |
+| "or" | `∨` |
+| "not" | `¬` |
+| "is in" / "member of" | `∈` |
+| "must be" / "is" | `:` or `=` |
+| "increment" | `++` |
+| "always" | `∀` |
 
 ---
 
@@ -437,13 +430,11 @@ performance_model: "O(n*m) where n=files, m=avg file size"
 ### 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
@@ -462,19 +453,16 @@ performance_model: "O(n*m) where n=files, m=avg file size"
 ### Domain-Specific Symbols
 
 **Web/API**:
-
 - `🌐` - HTTP/network operations
 - `📡` - API endpoints
 - `🔑` - Authentication
 
 **Database**:
-
 - `💾` - Database operations
 - `🔍` - Queries
 - `📝` - Transactions
 
 **Concurrency**:
-
 - `⚛️` - Atomic operations
 - `🔄` - Concurrent execution
 - `🔐` - Locks/mutexes
@@ -482,13 +470,11 @@ performance_model: "O(n*m) where n=files, m=avg file size"
 ### Extended Notation
 
 **Temporal Logic**:
-
 - `◇` - Eventually
 - `□` - Always
 - `○` - Next
 
 **Probability**:
-
 - `ℙ` - Probability
 - `𝔼` - Expected value
 - `~` - Distributed as
@@ -532,10 +518,9 @@ performance_model: "O(n*m) where n=files, m=avg file size"
 ---
 
 **Next Steps**:
-
 1. Build symbol parser
 2. Build bidirectional translator
-3. Integrate with Voodocs
+3. Integrate with VooDocs
 4. Test on real code
 5. Iterate based on usage
 

package/lib/darkarts/annotations/TRANSFORMATION_EXAMPLES.md

@@ -6,15 +6,15 @@
 🎯{demonstrate-value,validate-design}
 """
 
-# Voodocs → DarkArts Transformation Examples
+# VooDocs → DarkArts Transformation Examples
 
-Real examples from the vooodooo-magic codebase showing the transformation from verbose Voodocs annotations to compact DarkArts symbols.
+Real examples from the vooodooo-magic codebase showing the transformation from verbose VooDocs annotations to compact DarkArts symbols.
 
 ---
 
 ## Example 1: validation.py
 
-### Original Voodocs (21 lines, 625 chars)
+### Original VooDocs (21 lines, 625 chars)
 
 ```python
 """@voodocs
@@ -59,7 +59,7 @@ performance_model: "O(1) for all validations - regex matching is fast for short
 
 ## Example 2: ui.py
 
-### Original Voodocs (19 lines, 540 chars)
+### Original VooDocs (19 lines, 540 chars)
 
 ```python
 """@voodocs
@@ -103,16 +103,16 @@ performance_model: "O(1) for all UI operations - negligible overhead"
 
 ## Example 3: errors.py
 
-### Original Voodocs (16 lines, 480 chars)
+### Original VooDocs (16 lines, 480 chars)
 
 ```python
 """@voodocs
 module_purpose: "Context system specific exceptions with helpful error messages and recovery suggestions"
 dependencies: [
-    "darkarts.exceptions: Base Voodocs exception classes"
+    "darkarts.exceptions: Base VooDocs exception classes"
 ]
 assumptions: [
-    "Users may not be familiar with Voodocs",
+    "Users may not be familiar with VooDocs",
     "Error messages should be actionable",
     "Emojis improve readability (✅ ❌ 💡)"
 ]
@@ -146,7 +146,7 @@ performance_model: "O(1) - exception creation is negligible"
 
 ## Example 4: annotations/parser.py
 
-### Original Voodocs (24 lines, 780 chars)
+### Original VooDocs (24 lines, 780 chars)
 
 ```python
 """@voodocs
@@ -194,7 +194,7 @@ performance_model: "O(n*m/c) where n=files with annotations, m=average file size
 
 ## Example 5: context/commands.py
 
-### Original Voodocs (21 lines, 650 chars)
+### Original VooDocs (21 lines, 650 chars)
 
 ```python
 """@voodocs
@@ -243,13 +243,13 @@ performance_model: "O(n) where n=number of source files for scanning operations"
 
 ## Example 6: Complex Function Annotation
 
-### Original Voodocs (18 lines, 520 chars)
+### Original VooDocs (18 lines, 520 chars)
 
 ```python
 def validate_project_name(name: str) -> str:
     """
     Validate and normalize project name.
-
+    
     @voodocs
     preconditions: [
         "name is a string",
@@ -285,7 +285,7 @@ def validate_project_name(name: str) -> str:
 
 ## Example 7: State Machine
 
-### Original Voodocs (25 lines, 680 chars)
+### Original VooDocs (25 lines, 680 chars)
 
 ```python
 """@voodocs
@@ -332,7 +332,7 @@ transitions{uninit→init:cmd, init→valid:cmd, valid→gen:cmd}
 
 ## Example 8: Performance-Critical Module
 
-### Original Voodocs (22 lines, 720 chars)
+### Original VooDocs (22 lines, 720 chars)
 
 ```python
 """@voodocs
@@ -380,17 +380,17 @@ performance_model: {
 
 ## Summary Statistics
 
-| Example       | Voodocs       | DarkArts      | Compression | Line Reduction |
-| ------------- | ------------- | ------------- | ----------- | -------------- |
-| validation.py | 625 chars     | 180 chars     | 71%         | 67%            |
-| ui.py         | 540 chars     | 165 chars     | 69%         | 63%            |
-| errors.py     | 480 chars     | 155 chars     | 68%         | 56%            |
-| parser.py     | 780 chars     | 210 chars     | 73%         | 71%            |
-| commands.py   | 650 chars     | 195 chars     | 70%         | 67%            |
-| Function      | 520 chars     | 140 chars     | 73%         | 67%            |
-| State Machine | 680 chars     | 185 chars     | 73%         | 68%            |
-| Cache         | 720 chars     | 175 chars     | 76%         | 68%            |
-| **Average**   | **624 chars** | **176 chars** | **72%**     | **66%**        |
+| Example | VooDocs | DarkArts | Compression | Line Reduction |
+|---------|---------|----------|-------------|----------------|
+| validation.py | 625 chars | 180 chars | 71% | 67% |
+| ui.py | 540 chars | 165 chars | 69% | 63% |
+| errors.py | 480 chars | 155 chars | 68% | 56% |
+| parser.py | 780 chars | 210 chars | 73% | 71% |
+| commands.py | 650 chars | 195 chars | 70% | 67% |
+| Function | 520 chars | 140 chars | 73% | 67% |
+| State Machine | 680 chars | 185 chars | 73% | 68% |
+| Cache | 720 chars | 175 chars | 76% | 68% |
+| **Average** | **624 chars** | **176 chars** | **72%** | **66%** |
 
 ---
 
@@ -398,11 +398,11 @@ performance_model: {
 
 ### Compression Ratio
 
-**Average compression: 72%** - DarkArts uses less than 1/3 the characters of Voodocs
+**Average compression: 72%** - DarkArts uses less than 1/3 the characters of VooDocs
 
 ### Line Count Reduction
 
-**Average reduction: 66%** - DarkArts uses 1/3 the lines of Voodocs
+**Average reduction: 66%** - DarkArts uses 1/3 the lines of VooDocs
 
 ### Information Density
 
@@ -423,7 +423,6 @@ performance_model: {
 ### Example: validation.py
 
 **Symbolic**:
-
 ```python
 """@darkarts
 ⊢validation:ctx.comprehensive
@@ -436,7 +435,6 @@ performance_model: {
 ```
 
 **Human Translation** (when requested):
-
 ```
 Module: Input validation for context system (comprehensive)
 
@@ -473,7 +471,7 @@ Performance:
 3. ⏳ Build parser for @darkarts annotations
 4. ⏳ Build bidirectional translator
 5. ⏳ Test on real codebase
-6. ⏳ Integrate with Voodocs
+6. ⏳ Integrate with VooDocs
 
 ---