@voodocs/cli 2.1.3 → 2.2.1
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/CHANGELOG.md +215 -38
- package/LICENSE +1 -1
- package/PRIVACY.md +10 -10
- package/README.md +39 -35
- package/USAGE.md +50 -27
- package/examples/.cursorrules +9 -9
- package/examples/instructions/.claude/instructions.md +77 -65
- package/examples/instructions/.cursorrules +9 -9
- package/examples/instructions/.windsurfrules +9 -9
- package/examples/instructions/VOODOCS_INSTRUCTIONS.md +74 -62
- package/examples/math_example.py +1 -1
- package/examples/phase2_test.py +1 -1
- package/examples/test_function_invariants.py +1 -1
- package/lib/cli/__init__.py +3 -3
- package/lib/cli/benchmark.py +3 -3
- package/lib/cli/context.py +1 -1
- package/lib/cli/fix.py +1 -1
- package/lib/cli/generate.py +60 -1
- package/lib/cli/init.py +10 -10
- package/lib/cli/instruct.py +1 -1
- package/lib/cli/validate.py +3 -3
- package/lib/darkarts/annotations/DARKARTS_SYMBOLS.md +110 -95
- package/lib/darkarts/annotations/TRANSFORMATION_EXAMPLES.md +29 -27
- package/lib/darkarts/annotations/parser.py +1 -1
- package/lib/darkarts/cli_darkarts.py +5 -5
- package/lib/darkarts/context/ai_instructions.py +12 -12
- package/lib/darkarts/context/ai_integrations.py +16 -16
- package/lib/darkarts/context/commands.py +4 -4
- package/lib/darkarts/context/errors.py +1 -1
- package/lib/darkarts/context/models.py +1 -1
- package/lib/darkarts/context/ui.py +4 -4
- package/lib/darkarts/context/yaml_utils.py +3 -3
- package/lib/darkarts/core/loader.py +1 -1
- package/lib/darkarts/documentation/__init__.py +10 -0
- package/lib/darkarts/documentation/categorizer.py +137 -0
- package/lib/darkarts/documentation/consolidator.py +303 -0
- package/lib/darkarts/exceptions.py +3 -3
- package/lib/darkarts/plugins/voodocs/ai_native_plugin.py +1 -1
- package/lib/darkarts/plugins/voodocs/annotation_validator.py +2 -2
- package/lib/darkarts/plugins/voodocs/documentation_generator.py +3 -3
- package/lib/darkarts/plugins/voodocs/html_exporter.py +4 -4
- package/lib/darkarts/plugins/voodocs/instruction_generator.py +10 -10
- package/lib/darkarts/plugins/voodocs/pdf_exporter.py +1 -1
- package/lib/darkarts/plugins/voodocs/test_generator.py +1 -1
- package/lib/darkarts/telemetry.py +5 -5
- package/lib/darkarts/validation/README.md +6 -3
- package/package.json +2 -1
- package/requirements.txt +2 -2
- package/templates/ci/github-actions.yml +64 -64
- package/templates/ci/pre-commit-hook.sh +4 -4
- package/voodocs_cli.py +1 -1
|
@@ -28,86 +28,86 @@ Traditional documentation is written in natural language for humans, forcing AI
|
|
|
28
28
|
|
|
29
29
|
### Meta Symbols (Documentation Structure)
|
|
30
30
|
|
|
31
|
-
| Symbol | Name
|
|
32
|
-
|
|
33
|
-
| `⊢`
|
|
34
|
-
| `∂`
|
|
35
|
-
| `⚠`
|
|
36
|
-
| `⊨`
|
|
37
|
-
| `🔒`
|
|
38
|
-
| `⚡`
|
|
39
|
-
| `📊`
|
|
40
|
-
| `🎯`
|
|
41
|
-
| `⚙️`
|
|
31
|
+
| Symbol | Name | Meaning | Example |
|
|
32
|
+
| ------ | --------- | -------------------------------- | --------------------------- |
|
|
33
|
+
| `⊢` | Turnstile | Module/component declaration | `⊢module:name` |
|
|
34
|
+
| `∂` | Partial | Dependencies | `∂{lib1,lib2}` |
|
|
35
|
+
| `⚠` | Warning | Assumptions/preconditions | `⚠{utf8,fs:readable}` |
|
|
36
|
+
| `⊨` | Models | Invariants (must always be true) | `⊨{∀x→valid}` |
|
|
37
|
+
| `🔒` | Lock | Security model | `🔒{read-only}` |
|
|
38
|
+
| `⚡` | Lightning | Performance model | `⚡{O(n)}` |
|
|
39
|
+
| `📊` | Chart | Complexity analysis | `📊{time:O(n²),space:O(n)}` |
|
|
40
|
+
| `🎯` | Target | Objectives/goals | `🎯{accuracy>90%}` |
|
|
41
|
+
| `⚙️` | Gear | Configuration | `⚙️{cache:enabled}` |
|
|
42
42
|
|
|
43
43
|
### Logical Operators
|
|
44
44
|
|
|
45
|
-
| Symbol | Name
|
|
46
|
-
|
|
47
|
-
| `∀`
|
|
48
|
-
| `∃`
|
|
49
|
-
| `∧`
|
|
50
|
-
| `∨`
|
|
51
|
-
| `¬`
|
|
52
|
-
| `⇒`
|
|
53
|
-
| `⇐`
|
|
54
|
-
| `⇔`
|
|
55
|
-
| `⊕`
|
|
56
|
-
| `⊤`
|
|
57
|
-
| `⊥`
|
|
45
|
+
| Symbol | Name | Meaning | Example |
|
|
46
|
+
| ------ | ---------- | -------------------- | ----------- |
|
|
47
|
+
| `∀` | Forall | For all | `∀x∈S` |
|
|
48
|
+
| `∃` | Exists | There exists | `∃x:valid` |
|
|
49
|
+
| `∧` | And | Logical AND | `A∧B` |
|
|
50
|
+
| `∨` | Or | Logical OR | `A∨B` |
|
|
51
|
+
| `¬` | Not | Logical NOT | `¬modified` |
|
|
52
|
+
| `⇒` | Implies | If...then | `A⇒B` |
|
|
53
|
+
| `⇐` | Implied by | Reverse implication | `B⇐A` |
|
|
54
|
+
| `⇔` | Iff | If and only if | `A⇔B` |
|
|
55
|
+
| `⊕` | XOR | Exclusive OR | `A⊕B` |
|
|
56
|
+
| `⊤` | Top | Always true | `⊤` |
|
|
57
|
+
| `⊥` | Bottom | Always false / Error | `⊥` |
|
|
58
58
|
|
|
59
59
|
### Set/Type Operators
|
|
60
60
|
|
|
61
|
-
| Symbol | Name
|
|
62
|
-
|
|
63
|
-
| `∈`
|
|
64
|
-
| `∉`
|
|
65
|
-
| `⊂`
|
|
66
|
-
| `⊆`
|
|
67
|
-
| `∪`
|
|
68
|
-
| `∩`
|
|
69
|
-
| `∅`
|
|
70
|
-
| `:`
|
|
71
|
-
| `→`
|
|
72
|
-
| `↦`
|
|
61
|
+
| Symbol | Name | Meaning | Example |
|
|
62
|
+
| ------ | ----------------- | ------------------ | ------- |
|
|
63
|
+
| `∈` | Element of | Member of set/type | `x∈ℤ` |
|
|
64
|
+
| `∉` | Not element | Not a member | `x∉∅` |
|
|
65
|
+
| `⊂` | Subset | Proper subset | `A⊂B` |
|
|
66
|
+
| `⊆` | Subset eq | Subset or equal | `A⊆B` |
|
|
67
|
+
| `∪` | Union | Set union | `A∪B` |
|
|
68
|
+
| `∩` | Intersection | Set intersection | `A∩B` |
|
|
69
|
+
| `∅` | Empty set | Empty set | `S≠∅` |
|
|
70
|
+
| `:` | Type | Type annotation | `x:int` |
|
|
71
|
+
| `→` | Maps to | Function mapping | `f:A→B` |
|
|
72
|
+
| `↦` | Maps to (element) | Element mapping | `x↦x²` |
|
|
73
73
|
|
|
74
74
|
### Comparison Operators
|
|
75
75
|
|
|
76
|
-
| Symbol | Name
|
|
77
|
-
|
|
78
|
-
| `=`
|
|
79
|
-
| `≠`
|
|
80
|
-
| `<`
|
|
81
|
-
| `>`
|
|
82
|
-
| `≤`
|
|
83
|
-
| `≥`
|
|
84
|
-
| `≈`
|
|
85
|
-
| `≡`
|
|
76
|
+
| Symbol | Name | Meaning | Example |
|
|
77
|
+
| ------ | ---------------- | -------------------- | -------- |
|
|
78
|
+
| `=` | Equals | Equality | `x=5` |
|
|
79
|
+
| `≠` | Not equals | Inequality | `x≠0` |
|
|
80
|
+
| `<` | Less than | Strictly less | `x<10` |
|
|
81
|
+
| `>` | Greater than | Strictly greater | `x>0` |
|
|
82
|
+
| `≤` | Less or equal | At most | `x≤100` |
|
|
83
|
+
| `≥` | Greater or equal | At least | `x≥1` |
|
|
84
|
+
| `≈` | Approximately | Approximate equality | `π≈3.14` |
|
|
85
|
+
| `≡` | Identical | Definitionally equal | `f≡g` |
|
|
86
86
|
|
|
87
87
|
### Number Sets
|
|
88
88
|
|
|
89
|
-
| Symbol | Name
|
|
90
|
-
|
|
91
|
-
| `ℕ`
|
|
92
|
-
| `ℤ`
|
|
93
|
-
| `ℤ⁺`
|
|
94
|
-
| `ℚ`
|
|
95
|
-
| `ℝ`
|
|
96
|
-
| `ℝ⁺`
|
|
97
|
-
| `ℂ`
|
|
98
|
-
| `ℙ`
|
|
89
|
+
| Symbol | Name | Meaning |
|
|
90
|
+
| ------ | ----------------- | --------------------------- |
|
|
91
|
+
| `ℕ` | Naturals | Natural numbers {0,1,2,...} |
|
|
92
|
+
| `ℤ` | Integers | Integers {...,-1,0,1,...} |
|
|
93
|
+
| `ℤ⁺` | Positive integers | {1,2,3,...} |
|
|
94
|
+
| `ℚ` | Rationals | Rational numbers |
|
|
95
|
+
| `ℝ` | Reals | Real numbers |
|
|
96
|
+
| `ℝ⁺` | Positive reals | Positive real numbers |
|
|
97
|
+
| `ℂ` | Complex | Complex numbers |
|
|
98
|
+
| `ℙ` | Primes | Prime numbers |
|
|
99
99
|
|
|
100
100
|
### State/Flow Operators
|
|
101
101
|
|
|
102
|
-
| Symbol | Name
|
|
103
|
-
|
|
104
|
-
| `++`
|
|
105
|
-
| `--`
|
|
106
|
-
| `+=`
|
|
107
|
-
| `-=`
|
|
108
|
-
| `⊳`
|
|
109
|
-
| `⊲`
|
|
110
|
-
| `⟲`
|
|
102
|
+
| Symbol | Name | Meaning | Example |
|
|
103
|
+
| ------ | ------------- | ------------------- | ----------- |
|
|
104
|
+
| `++` | Increment | Increase by 1 | `v++` |
|
|
105
|
+
| `--` | Decrement | Decrease by 1 | `v--` |
|
|
106
|
+
| `+=` | Add assign | Add and assign | `x+=5` |
|
|
107
|
+
| `-=` | Sub assign | Subtract and assign | `x-=3` |
|
|
108
|
+
| `⊳` | Precondition | Must hold before | `⊳valid` |
|
|
109
|
+
| `⊲` | Postcondition | Must hold after | `⊲success` |
|
|
110
|
+
| `⟲` | Loop | Iteration | `⟲∀i∈[0,n)` |
|
|
111
111
|
|
|
112
112
|
---
|
|
113
113
|
|
|
@@ -134,6 +134,7 @@ Traditional documentation is written in natural language for humans, forcing AI
|
|
|
134
134
|
**Translation**: "Dependencies: lib1, lib2, lib3"
|
|
135
135
|
|
|
136
136
|
**With descriptions**:
|
|
137
|
+
|
|
137
138
|
```python
|
|
138
139
|
"""@darkarts
|
|
139
140
|
∂{ast:py-parsing, re:regex, pathlib:fs}
|
|
@@ -160,7 +161,8 @@ Traditional documentation is written in natural language for humans, forcing AI
|
|
|
160
161
|
"""
|
|
161
162
|
```
|
|
162
163
|
|
|
163
|
-
**Translation**:
|
|
164
|
+
**Translation**:
|
|
165
|
+
|
|
164
166
|
- "Invariants: For all inputs x, x must be valid"
|
|
165
167
|
- "For all operations, state is not modified"
|
|
166
168
|
- "Result is of expected type"
|
|
@@ -199,6 +201,7 @@ Traditional documentation is written in natural language for humans, forcing AI
|
|
|
199
201
|
```
|
|
200
202
|
|
|
201
203
|
**Translation**:
|
|
204
|
+
|
|
202
205
|
```
|
|
203
206
|
Module: validator for strict input validation
|
|
204
207
|
Dependencies: re (regex), typing (type hints)
|
|
@@ -223,7 +226,7 @@ Performance: O(n) where n is input length
|
|
|
223
226
|
"""
|
|
224
227
|
```
|
|
225
228
|
|
|
226
|
-
**Translation**: "All
|
|
229
|
+
**Translation**: "All validate\_\* functions must raise on failure and return normalized on success"
|
|
227
230
|
|
|
228
231
|
### Version Constraints
|
|
229
232
|
|
|
@@ -305,11 +308,12 @@ Performance: O(n) where n is input length
|
|
|
305
308
|
|
|
306
309
|
---
|
|
307
310
|
|
|
308
|
-
## Comparison:
|
|
311
|
+
## Comparison: Voodocs vs DarkArts
|
|
309
312
|
|
|
310
313
|
### Example 1: Simple Module
|
|
311
314
|
|
|
312
|
-
**
|
|
315
|
+
**Voodocs** (14 lines, 450 chars):
|
|
316
|
+
|
|
313
317
|
```python
|
|
314
318
|
"""@voodocs
|
|
315
319
|
module_purpose: "Input validation utilities"
|
|
@@ -329,6 +333,7 @@ invariants: [
|
|
|
329
333
|
```
|
|
330
334
|
|
|
331
335
|
**DarkArts** (4 lines, 120 chars):
|
|
336
|
+
|
|
332
337
|
```python
|
|
333
338
|
"""@darkarts
|
|
334
339
|
⊢validation:input
|
|
@@ -342,7 +347,8 @@ invariants: [
|
|
|
342
347
|
|
|
343
348
|
### Example 2: Complex Module
|
|
344
349
|
|
|
345
|
-
**
|
|
350
|
+
**Voodocs** (32 lines, 980 chars):
|
|
351
|
+
|
|
346
352
|
```python
|
|
347
353
|
"""@voodocs
|
|
348
354
|
module_purpose: "Multi-language annotation parser"
|
|
@@ -368,6 +374,7 @@ performance_model: "O(n*m) where n=files, m=avg file size"
|
|
|
368
374
|
```
|
|
369
375
|
|
|
370
376
|
**DarkArts** (7 lines, 240 chars):
|
|
377
|
+
|
|
371
378
|
```python
|
|
372
379
|
"""@darkarts
|
|
373
380
|
⊢parser:annotations.multi-lang
|
|
@@ -387,33 +394,33 @@ performance_model: "O(n*m) where n=files, m=avg file size"
|
|
|
387
394
|
|
|
388
395
|
### Symbol → Natural Language
|
|
389
396
|
|
|
390
|
-
| Pattern
|
|
391
|
-
|
|
392
|
-
| `⊢module:name` | "Module: name"
|
|
393
|
-
| `∂{a,b,c}`
|
|
394
|
-
| `⚠{x,y,z}`
|
|
395
|
-
| `⊨{rule}`
|
|
396
|
-
| `∀x→y`
|
|
397
|
-
| `x∈S`
|
|
398
|
-
| `x:type`
|
|
399
|
-
| `A⇒B`
|
|
400
|
-
| `A∧B`
|
|
401
|
-
| `¬x`
|
|
397
|
+
| Pattern | Translation |
|
|
398
|
+
| -------------- | ----------------------- |
|
|
399
|
+
| `⊢module:name` | "Module: name" |
|
|
400
|
+
| `∂{a,b,c}` | "Dependencies: a, b, c" |
|
|
401
|
+
| `⚠{x,y,z}` | "Assumptions: x, y, z" |
|
|
402
|
+
| `⊨{rule}` | "Invariant: rule" |
|
|
403
|
+
| `∀x→y` | "For all x, then y" |
|
|
404
|
+
| `x∈S` | "x is in S" |
|
|
405
|
+
| `x:type` | "x is of type type" |
|
|
406
|
+
| `A⇒B` | "If A then B" |
|
|
407
|
+
| `A∧B` | "A and B" |
|
|
408
|
+
| `¬x` | "not x" |
|
|
402
409
|
|
|
403
410
|
### Natural Language → Symbols
|
|
404
411
|
|
|
405
|
-
| Phrase
|
|
406
|
-
|
|
407
|
-
| "For all"
|
|
408
|
-
| "There exists"
|
|
409
|
-
| "implies" / "then"
|
|
410
|
-
| "and"
|
|
411
|
-
| "or"
|
|
412
|
-
| "not"
|
|
413
|
-
| "is in" / "member of" | `∈`
|
|
414
|
-
| "must be" / "is"
|
|
415
|
-
| "increment"
|
|
416
|
-
| "always"
|
|
412
|
+
| Phrase | Symbol |
|
|
413
|
+
| --------------------- | ---------- |
|
|
414
|
+
| "For all" | `∀` |
|
|
415
|
+
| "There exists" | `∃` |
|
|
416
|
+
| "implies" / "then" | `⇒` |
|
|
417
|
+
| "and" | `∧` |
|
|
418
|
+
| "or" | `∨` |
|
|
419
|
+
| "not" | `¬` |
|
|
420
|
+
| "is in" / "member of" | `∈` |
|
|
421
|
+
| "must be" / "is" | `:` or `=` |
|
|
422
|
+
| "increment" | `++` |
|
|
423
|
+
| "always" | `∀` |
|
|
417
424
|
|
|
418
425
|
---
|
|
419
426
|
|
|
@@ -430,11 +437,13 @@ performance_model: "O(n*m) where n=files, m=avg file size"
|
|
|
430
437
|
### Translator Strategy
|
|
431
438
|
|
|
432
439
|
**Symbols → Natural Language**:
|
|
440
|
+
|
|
433
441
|
1. Pattern match symbol sequences
|
|
434
442
|
2. Apply translation rules
|
|
435
443
|
3. Generate readable English
|
|
436
444
|
|
|
437
445
|
**Natural Language → Symbols**:
|
|
446
|
+
|
|
438
447
|
1. Parse English text
|
|
439
448
|
2. Identify patterns (dependencies, invariants, etc.)
|
|
440
449
|
3. Generate symbolic representation
|
|
@@ -453,16 +462,19 @@ performance_model: "O(n*m) where n=files, m=avg file size"
|
|
|
453
462
|
### Domain-Specific Symbols
|
|
454
463
|
|
|
455
464
|
**Web/API**:
|
|
465
|
+
|
|
456
466
|
- `🌐` - HTTP/network operations
|
|
457
467
|
- `📡` - API endpoints
|
|
458
468
|
- `🔑` - Authentication
|
|
459
469
|
|
|
460
470
|
**Database**:
|
|
471
|
+
|
|
461
472
|
- `💾` - Database operations
|
|
462
473
|
- `🔍` - Queries
|
|
463
474
|
- `📝` - Transactions
|
|
464
475
|
|
|
465
476
|
**Concurrency**:
|
|
477
|
+
|
|
466
478
|
- `⚛️` - Atomic operations
|
|
467
479
|
- `🔄` - Concurrent execution
|
|
468
480
|
- `🔐` - Locks/mutexes
|
|
@@ -470,11 +482,13 @@ performance_model: "O(n*m) where n=files, m=avg file size"
|
|
|
470
482
|
### Extended Notation
|
|
471
483
|
|
|
472
484
|
**Temporal Logic**:
|
|
485
|
+
|
|
473
486
|
- `◇` - Eventually
|
|
474
487
|
- `□` - Always
|
|
475
488
|
- `○` - Next
|
|
476
489
|
|
|
477
490
|
**Probability**:
|
|
491
|
+
|
|
478
492
|
- `ℙ` - Probability
|
|
479
493
|
- `𝔼` - Expected value
|
|
480
494
|
- `~` - Distributed as
|
|
@@ -518,9 +532,10 @@ performance_model: "O(n*m) where n=files, m=avg file size"
|
|
|
518
532
|
---
|
|
519
533
|
|
|
520
534
|
**Next Steps**:
|
|
535
|
+
|
|
521
536
|
1. Build symbol parser
|
|
522
537
|
2. Build bidirectional translator
|
|
523
|
-
3. Integrate with
|
|
538
|
+
3. Integrate with Voodocs
|
|
524
539
|
4. Test on real code
|
|
525
540
|
5. Iterate based on usage
|
|
526
541
|
|
|
@@ -6,15 +6,15 @@
|
|
|
6
6
|
🎯{demonstrate-value,validate-design}
|
|
7
7
|
"""
|
|
8
8
|
|
|
9
|
-
#
|
|
9
|
+
# Voodocs → DarkArts Transformation Examples
|
|
10
10
|
|
|
11
|
-
Real examples from the vooodooo-magic codebase showing the transformation from verbose
|
|
11
|
+
Real examples from the vooodooo-magic codebase showing the transformation from verbose Voodocs annotations to compact DarkArts symbols.
|
|
12
12
|
|
|
13
13
|
---
|
|
14
14
|
|
|
15
15
|
## Example 1: validation.py
|
|
16
16
|
|
|
17
|
-
### Original
|
|
17
|
+
### Original Voodocs (21 lines, 625 chars)
|
|
18
18
|
|
|
19
19
|
```python
|
|
20
20
|
"""@voodocs
|
|
@@ -59,7 +59,7 @@ performance_model: "O(1) for all validations - regex matching is fast for short
|
|
|
59
59
|
|
|
60
60
|
## Example 2: ui.py
|
|
61
61
|
|
|
62
|
-
### Original
|
|
62
|
+
### Original Voodocs (19 lines, 540 chars)
|
|
63
63
|
|
|
64
64
|
```python
|
|
65
65
|
"""@voodocs
|
|
@@ -103,16 +103,16 @@ performance_model: "O(1) for all UI operations - negligible overhead"
|
|
|
103
103
|
|
|
104
104
|
## Example 3: errors.py
|
|
105
105
|
|
|
106
|
-
### Original
|
|
106
|
+
### Original Voodocs (16 lines, 480 chars)
|
|
107
107
|
|
|
108
108
|
```python
|
|
109
109
|
"""@voodocs
|
|
110
110
|
module_purpose: "Context system specific exceptions with helpful error messages and recovery suggestions"
|
|
111
111
|
dependencies: [
|
|
112
|
-
"darkarts.exceptions: Base
|
|
112
|
+
"darkarts.exceptions: Base Voodocs exception classes"
|
|
113
113
|
]
|
|
114
114
|
assumptions: [
|
|
115
|
-
"Users may not be familiar with
|
|
115
|
+
"Users may not be familiar with Voodocs",
|
|
116
116
|
"Error messages should be actionable",
|
|
117
117
|
"Emojis improve readability (✅ ❌ 💡)"
|
|
118
118
|
]
|
|
@@ -146,7 +146,7 @@ performance_model: "O(1) - exception creation is negligible"
|
|
|
146
146
|
|
|
147
147
|
## Example 4: annotations/parser.py
|
|
148
148
|
|
|
149
|
-
### Original
|
|
149
|
+
### Original Voodocs (24 lines, 780 chars)
|
|
150
150
|
|
|
151
151
|
```python
|
|
152
152
|
"""@voodocs
|
|
@@ -194,7 +194,7 @@ performance_model: "O(n*m/c) where n=files with annotations, m=average file size
|
|
|
194
194
|
|
|
195
195
|
## Example 5: context/commands.py
|
|
196
196
|
|
|
197
|
-
### Original
|
|
197
|
+
### Original Voodocs (21 lines, 650 chars)
|
|
198
198
|
|
|
199
199
|
```python
|
|
200
200
|
"""@voodocs
|
|
@@ -243,13 +243,13 @@ performance_model: "O(n) where n=number of source files for scanning operations"
|
|
|
243
243
|
|
|
244
244
|
## Example 6: Complex Function Annotation
|
|
245
245
|
|
|
246
|
-
### Original
|
|
246
|
+
### Original Voodocs (18 lines, 520 chars)
|
|
247
247
|
|
|
248
248
|
```python
|
|
249
249
|
def validate_project_name(name: str) -> str:
|
|
250
250
|
"""
|
|
251
251
|
Validate and normalize project name.
|
|
252
|
-
|
|
252
|
+
|
|
253
253
|
@voodocs
|
|
254
254
|
preconditions: [
|
|
255
255
|
"name is a string",
|
|
@@ -285,7 +285,7 @@ def validate_project_name(name: str) -> str:
|
|
|
285
285
|
|
|
286
286
|
## Example 7: State Machine
|
|
287
287
|
|
|
288
|
-
### Original
|
|
288
|
+
### Original Voodocs (25 lines, 680 chars)
|
|
289
289
|
|
|
290
290
|
```python
|
|
291
291
|
"""@voodocs
|
|
@@ -332,7 +332,7 @@ transitions{uninit→init:cmd, init→valid:cmd, valid→gen:cmd}
|
|
|
332
332
|
|
|
333
333
|
## Example 8: Performance-Critical Module
|
|
334
334
|
|
|
335
|
-
### Original
|
|
335
|
+
### Original Voodocs (22 lines, 720 chars)
|
|
336
336
|
|
|
337
337
|
```python
|
|
338
338
|
"""@voodocs
|
|
@@ -380,17 +380,17 @@ performance_model: {
|
|
|
380
380
|
|
|
381
381
|
## Summary Statistics
|
|
382
382
|
|
|
383
|
-
| Example
|
|
384
|
-
|
|
385
|
-
| validation.py | 625 chars
|
|
386
|
-
| ui.py
|
|
387
|
-
| errors.py
|
|
388
|
-
| parser.py
|
|
389
|
-
| commands.py
|
|
390
|
-
| Function
|
|
391
|
-
| State Machine | 680 chars
|
|
392
|
-
| Cache
|
|
393
|
-
| **Average**
|
|
383
|
+
| Example | Voodocs | DarkArts | Compression | Line Reduction |
|
|
384
|
+
| ------------- | ------------- | ------------- | ----------- | -------------- |
|
|
385
|
+
| validation.py | 625 chars | 180 chars | 71% | 67% |
|
|
386
|
+
| ui.py | 540 chars | 165 chars | 69% | 63% |
|
|
387
|
+
| errors.py | 480 chars | 155 chars | 68% | 56% |
|
|
388
|
+
| parser.py | 780 chars | 210 chars | 73% | 71% |
|
|
389
|
+
| commands.py | 650 chars | 195 chars | 70% | 67% |
|
|
390
|
+
| Function | 520 chars | 140 chars | 73% | 67% |
|
|
391
|
+
| State Machine | 680 chars | 185 chars | 73% | 68% |
|
|
392
|
+
| Cache | 720 chars | 175 chars | 76% | 68% |
|
|
393
|
+
| **Average** | **624 chars** | **176 chars** | **72%** | **66%** |
|
|
394
394
|
|
|
395
395
|
---
|
|
396
396
|
|
|
@@ -398,11 +398,11 @@ performance_model: {
|
|
|
398
398
|
|
|
399
399
|
### Compression Ratio
|
|
400
400
|
|
|
401
|
-
**Average compression: 72%** - DarkArts uses less than 1/3 the characters of
|
|
401
|
+
**Average compression: 72%** - DarkArts uses less than 1/3 the characters of Voodocs
|
|
402
402
|
|
|
403
403
|
### Line Count Reduction
|
|
404
404
|
|
|
405
|
-
**Average reduction: 66%** - DarkArts uses 1/3 the lines of
|
|
405
|
+
**Average reduction: 66%** - DarkArts uses 1/3 the lines of Voodocs
|
|
406
406
|
|
|
407
407
|
### Information Density
|
|
408
408
|
|
|
@@ -423,6 +423,7 @@ performance_model: {
|
|
|
423
423
|
### Example: validation.py
|
|
424
424
|
|
|
425
425
|
**Symbolic**:
|
|
426
|
+
|
|
426
427
|
```python
|
|
427
428
|
"""@darkarts
|
|
428
429
|
⊢validation:ctx.comprehensive
|
|
@@ -435,6 +436,7 @@ performance_model: {
|
|
|
435
436
|
```
|
|
436
437
|
|
|
437
438
|
**Human Translation** (when requested):
|
|
439
|
+
|
|
438
440
|
```
|
|
439
441
|
Module: Input validation for context system (comprehensive)
|
|
440
442
|
|
|
@@ -471,7 +473,7 @@ Performance:
|
|
|
471
473
|
3. ⏳ Build parser for @darkarts annotations
|
|
472
474
|
4. ⏳ Build bidirectional translator
|
|
473
475
|
5. ⏳ Test on real codebase
|
|
474
|
-
6. ⏳ Integrate with
|
|
476
|
+
6. ⏳ Integrate with Voodocs
|
|
475
477
|
|
|
476
478
|
---
|
|
477
479
|
|
|
@@ -763,7 +763,7 @@ class AnnotationParser:
|
|
|
763
763
|
language: Language,
|
|
764
764
|
darkarts_matches: List
|
|
765
765
|
) -> ParsedAnnotations:
|
|
766
|
-
"""Parse @darkarts annotations and translate to
|
|
766
|
+
"""Parse @darkarts annotations and translate to Voodocs format."""
|
|
767
767
|
from .darkarts_parser import parse_darkarts
|
|
768
768
|
from .translator import DarkArtsTranslator
|
|
769
769
|
|
|
@@ -52,7 +52,7 @@ def cmd_darkarts_translate(args):
|
|
|
52
52
|
|
|
53
53
|
try:
|
|
54
54
|
if to_symbols:
|
|
55
|
-
# Natural language → Symbols (
|
|
55
|
+
# Natural language → Symbols (Voodocs → DarkArts)
|
|
56
56
|
parser = AnnotationParser()
|
|
57
57
|
annotations = parser.parse_file(str(path))
|
|
58
58
|
|
|
@@ -91,7 +91,7 @@ def cmd_darkarts_translate(args):
|
|
|
91
91
|
|
|
92
92
|
def cmd_darkarts_convert(args):
|
|
93
93
|
"""
|
|
94
|
-
Convert files between
|
|
94
|
+
Convert files between Voodocs and DarkArts formats.
|
|
95
95
|
|
|
96
96
|
Usage:
|
|
97
97
|
voodocs darkarts convert <files> [--in-place]
|
|
@@ -121,7 +121,7 @@ def cmd_darkarts_convert(args):
|
|
|
121
121
|
try:
|
|
122
122
|
content = path.read_text()
|
|
123
123
|
|
|
124
|
-
# Parse
|
|
124
|
+
# Parse Voodocs annotations
|
|
125
125
|
parser = AnnotationParser()
|
|
126
126
|
annotations = parser.parse_file(str(path))
|
|
127
127
|
language = parser.detect_language(str(path))
|
|
@@ -412,7 +412,7 @@ def cmd_darkarts_validate(args):
|
|
|
412
412
|
|
|
413
413
|
def add_darkarts_subcommands(subparsers):
|
|
414
414
|
"""
|
|
415
|
-
Add DarkArts subcommands to
|
|
415
|
+
Add DarkArts subcommands to Voodocs CLI.
|
|
416
416
|
|
|
417
417
|
Args:
|
|
418
418
|
subparsers: Argparse subparsers object
|
|
@@ -446,7 +446,7 @@ def add_darkarts_subcommands(subparsers):
|
|
|
446
446
|
# darkarts convert
|
|
447
447
|
convert_parser = darkarts_subparsers.add_parser(
|
|
448
448
|
"convert",
|
|
449
|
-
help="Convert
|
|
449
|
+
help="Convert Voodocs annotations to DarkArts"
|
|
450
450
|
)
|
|
451
451
|
convert_parser.add_argument(
|
|
452
452
|
"files",
|
|
@@ -6,10 +6,10 @@
|
|
|
6
6
|
🔒{no-implications}
|
|
7
7
|
⚡{O(1)|template-generation}
|
|
8
8
|
|
|
9
|
-
AI instruction templates for
|
|
9
|
+
AI instruction templates for Voodocs Context System.
|
|
10
10
|
|
|
11
11
|
This module provides templates for generating AI assistant instructions
|
|
12
|
-
that teach them how to use the
|
|
12
|
+
that teach them how to use the Voodocs context system effectively.
|
|
13
13
|
"""
|
|
14
14
|
|
|
15
15
|
from typing import Dict, Optional
|
|
@@ -26,14 +26,14 @@ def generate_cursorrules(project_name: str, project_purpose: str) -> str:
|
|
|
26
26
|
Returns:
|
|
27
27
|
Content for .cursorrules file
|
|
28
28
|
"""
|
|
29
|
-
return f"""# {project_name} -
|
|
29
|
+
return f"""# {project_name} - Voodocs Context System
|
|
30
30
|
|
|
31
31
|
## Project Overview
|
|
32
32
|
{project_purpose}
|
|
33
33
|
|
|
34
|
-
##
|
|
34
|
+
## Voodocs Context System (v0.2.0+)
|
|
35
35
|
|
|
36
|
-
This project uses
|
|
36
|
+
This project uses Voodocs with the Context System for intelligent documentation and validation.
|
|
37
37
|
|
|
38
38
|
### Context File Location
|
|
39
39
|
- **Context file**: `.voodocs.context` (YAML format)
|
|
@@ -222,7 +222,7 @@ voodocs context diagram --type all --output docs/arch
|
|
|
222
222
|
|
|
223
223
|
---
|
|
224
224
|
|
|
225
|
-
**
|
|
225
|
+
**Voodocs Context System** - AI-native documentation that keeps code and context in sync.
|
|
226
226
|
"""
|
|
227
227
|
|
|
228
228
|
|
|
@@ -237,20 +237,20 @@ def generate_context_guide(project_name: str, project_purpose: str) -> str:
|
|
|
237
237
|
Returns:
|
|
238
238
|
Content for VOODOCS_CONTEXT_GUIDE.md file
|
|
239
239
|
"""
|
|
240
|
-
return f"""#
|
|
240
|
+
return f"""# Voodocs Context System Guide - {project_name}
|
|
241
241
|
|
|
242
242
|
## Project Overview
|
|
243
243
|
|
|
244
244
|
**Name**: {project_name}
|
|
245
245
|
**Purpose**: {project_purpose}
|
|
246
246
|
|
|
247
|
-
This project uses the **
|
|
247
|
+
This project uses the **Voodocs Context System** (v0.2.0+) for intelligent documentation, validation, and architecture management.
|
|
248
248
|
|
|
249
249
|
---
|
|
250
250
|
|
|
251
251
|
## What is the Context System?
|
|
252
252
|
|
|
253
|
-
The
|
|
253
|
+
The Voodocs Context System is an AI-native documentation framework that:
|
|
254
254
|
|
|
255
255
|
1. **Auto-generates** project context from code annotations
|
|
256
256
|
2. **Validates** code against documented invariants
|
|
@@ -620,7 +620,7 @@ jobs:
|
|
|
620
620
|
steps:
|
|
621
621
|
- uses: actions/checkout@v2
|
|
622
622
|
|
|
623
|
-
- name: Install
|
|
623
|
+
- name: Install Voodocs
|
|
624
624
|
run: npm install -g @voodocs/cli
|
|
625
625
|
|
|
626
626
|
- name: Validate Context
|
|
@@ -703,7 +703,7 @@ Or add `module_purpose` to @voodocs annotations and regenerate.
|
|
|
703
703
|
|
|
704
704
|
## Summary
|
|
705
705
|
|
|
706
|
-
The
|
|
706
|
+
The Voodocs Context System is your **single source of truth** for:
|
|
707
707
|
- ✅ Project understanding
|
|
708
708
|
- ✅ Architecture documentation
|
|
709
709
|
- ✅ Code validation
|
|
@@ -714,7 +714,7 @@ The VooDocs Context System is your **single source of truth** for:
|
|
|
714
714
|
|
|
715
715
|
---
|
|
716
716
|
|
|
717
|
-
**
|
|
717
|
+
**Voodocs v0.2.0+** - AI-native documentation that keeps code and context in sync.
|
|
718
718
|
"""
|
|
719
719
|
|
|
720
720
|
|