@voodocs/cli 1.0.7 → 2.0.0
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 +57 -0
- package/README.md +171 -241
- package/lib/cli/__init__.py +4 -4
- package/lib/cli/generate.py +5 -5
- package/lib/cli/init.py +7 -34
- package/lib/darkarts/annotations/parser.py +10 -15
- package/package.json +15 -14
package/CHANGELOG.md
CHANGED
|
@@ -1,3 +1,60 @@
|
|
|
1
|
+
## [2.0.0] - 2024-12-21
|
|
2
|
+
|
|
3
|
+
### 🚨 BREAKING CHANGES
|
|
4
|
+
|
|
5
|
+
**VooDocs is now DarkArts-only!**
|
|
6
|
+
|
|
7
|
+
This major version removes support for natural language `@voodocs` annotations and focuses exclusively on the symbolic `@darkarts` format.
|
|
8
|
+
|
|
9
|
+
### Removed
|
|
10
|
+
- **Natural language format (`@voodocs`)** - No longer supported
|
|
11
|
+
- Parser no longer recognizes `@voodocs` tags
|
|
12
|
+
- Generator no longer processes natural language annotations
|
|
13
|
+
- Init wizard no longer offers format choice
|
|
14
|
+
|
|
15
|
+
### Changed
|
|
16
|
+
- **DarkArts symbolic format is now the only format**
|
|
17
|
+
- All annotations must use `@darkarts` tag
|
|
18
|
+
- All annotations must use symbolic notation (⊢, ∂, ⚠, ⊳, ⊲, ⊨, ⚡, 🔒)
|
|
19
|
+
- Init wizard automatically uses DarkArts format
|
|
20
|
+
- Example files use symbolic format only
|
|
21
|
+
|
|
22
|
+
### Why This Change?
|
|
23
|
+
|
|
24
|
+
1. **Clearer brand identity** - "The symbolic documentation language"
|
|
25
|
+
2. **Reduced maintenance** - One parser, one validator, one format
|
|
26
|
+
3. **Stronger patent position** - Unique innovation (VDA-004)
|
|
27
|
+
4. **Better AI optimization** - Symbols are more token-efficient
|
|
28
|
+
5. **Simplified user experience** - No format confusion
|
|
29
|
+
|
|
30
|
+
### Migration Guide
|
|
31
|
+
|
|
32
|
+
VooDocs v2.0.0 only supports `@darkarts` symbolic format. If you have existing `@voodocs` annotations, you'll need to manually update them:
|
|
33
|
+
|
|
34
|
+
**Before (v1.x):**
|
|
35
|
+
```typescript
|
|
36
|
+
/**@voodocs
|
|
37
|
+
module_purpose: "User service"
|
|
38
|
+
dependencies: ["database"]
|
|
39
|
+
*/
|
|
40
|
+
```
|
|
41
|
+
|
|
42
|
+
**After (v2.0):**
|
|
43
|
+
```typescript
|
|
44
|
+
/**@darkarts
|
|
45
|
+
⊢{User service}
|
|
46
|
+
∂{database}
|
|
47
|
+
*/
|
|
48
|
+
```
|
|
49
|
+
|
|
50
|
+
### Benefits
|
|
51
|
+
|
|
52
|
+
- ✅ **Concise** - Fewer characters, more meaning
|
|
53
|
+
- ✅ **Precise** - Mathematical notation eliminates ambiguity
|
|
54
|
+
- ✅ **AI-Optimized** - Fewer tokens = lower costs
|
|
55
|
+
- ✅ **Language-Independent** - Symbols transcend language barriers
|
|
56
|
+
- ✅ **Unique** - Patent-pending innovation
|
|
57
|
+
|
|
1
58
|
## [1.0.7] - 2024-12-21
|
|
2
59
|
|
|
3
60
|
### Added
|
package/README.md
CHANGED
|
@@ -1,18 +1,19 @@
|
|
|
1
|
-
# VooDocs - AI-Native Documentation
|
|
1
|
+
# VooDocs - AI-Native Symbolic Documentation
|
|
2
2
|
|
|
3
3
|
[](https://www.npmjs.com/package/@voodocs/cli)
|
|
4
4
|
[](https://voodocs.com/terms)
|
|
5
5
|
[](https://voodocs.com/support)
|
|
6
6
|
|
|
7
|
-
**VooDocs** is the
|
|
7
|
+
**VooDocs** is the world's first AI-native symbolic documentation system. Using mathematical notation and semantic validation, it creates documentation that's both human-readable and optimized for AI consumption.
|
|
8
8
|
|
|
9
9
|
## What Makes VooDocs Unique?
|
|
10
10
|
|
|
11
|
+
✅ **Symbolic Language** - Mathematical Unicode symbols (⊢, ∂, ⚠, ⊳, ⊲, ⊨, ⚡, 🔒) for concise, precise documentation
|
|
11
12
|
✅ **Semantic Validation** - Verifies that your documentation matches your code
|
|
12
13
|
✅ **Performance Validation** - Checks that complexity claims are accurate
|
|
13
14
|
✅ **Auto-Fix** - Automatically corrects common documentation errors
|
|
14
15
|
✅ **Benchmarking** - Validates performance claims with real execution data
|
|
15
|
-
✅ **
|
|
16
|
+
✅ **AI-Optimized** - Token-efficient format designed for LLM consumption
|
|
16
17
|
✅ **CI/CD Ready** - Strict mode with exit codes for continuous integration
|
|
17
18
|
|
|
18
19
|
---
|
|
@@ -29,348 +30,277 @@ npm install -g @voodocs/cli
|
|
|
29
30
|
|
|
30
31
|
### 2. Initialize Your Project
|
|
31
32
|
|
|
32
|
-
Navigate to your project directory and
|
|
33
|
+
Navigate to your project directory and run the interactive wizard:
|
|
33
34
|
|
|
34
35
|
```bash
|
|
35
36
|
voodocs init
|
|
36
37
|
```
|
|
37
38
|
|
|
38
|
-
This
|
|
39
|
+
This will:
|
|
40
|
+
- Create `.voodocs.json` configuration
|
|
41
|
+
- Generate AI instructions for your coding assistant
|
|
42
|
+
- Create example annotated files
|
|
43
|
+
- Configure privacy settings
|
|
39
44
|
|
|
40
|
-
### 3. Add Annotations to Your Code
|
|
45
|
+
### 3. Add DarkArts Annotations to Your Code
|
|
41
46
|
|
|
42
|
-
####
|
|
43
|
-
|
|
44
|
-
```typescript
|
|
45
|
-
/**@voodocs
|
|
46
|
-
module_purpose: "User authentication service with JWT token generation"
|
|
47
|
-
dependencies: [
|
|
48
|
-
"bcrypt: Password hashing",
|
|
49
|
-
"jsonwebtoken: JWT token generation"
|
|
50
|
-
]
|
|
51
|
-
assumptions: [
|
|
52
|
-
"Database connection is established",
|
|
53
|
-
"User model exists with email and password fields"
|
|
54
|
-
]
|
|
55
|
-
*/
|
|
56
|
-
|
|
57
|
-
/**@voodocs
|
|
58
|
-
preconditions: [
|
|
59
|
-
"email must be a valid email format",
|
|
60
|
-
"password must be at least 8 characters"
|
|
61
|
-
]
|
|
62
|
-
postconditions: [
|
|
63
|
-
"Returns a JWT token",
|
|
64
|
-
"User is authenticated in the database"
|
|
65
|
-
]
|
|
66
|
-
invariants: [
|
|
67
|
-
"Does not modify existing user records"
|
|
68
|
-
]
|
|
69
|
-
side_effects: [
|
|
70
|
-
"Creates a new session in the database"
|
|
71
|
-
]
|
|
72
|
-
complexity: "O(1)"
|
|
73
|
-
*/
|
|
74
|
-
export async function login(email: string, password: string): Promise<string> {
|
|
75
|
-
// ...
|
|
76
|
-
}
|
|
77
|
-
```
|
|
78
|
-
|
|
79
|
-
#### Symbolic Format (`@darkarts`)
|
|
47
|
+
#### TypeScript/JavaScript
|
|
80
48
|
|
|
81
49
|
```typescript
|
|
82
50
|
/**@darkarts
|
|
83
51
|
⊢{User authentication service with JWT token generation}
|
|
84
|
-
∂{
|
|
85
|
-
|
|
86
|
-
jsonwebtoken: JWT token generation
|
|
87
|
-
}
|
|
88
|
-
⚠{
|
|
89
|
-
Database connection is established
|
|
90
|
-
User model ∃ with email ∧ password fields
|
|
91
|
-
}
|
|
52
|
+
∂{bcrypt, jsonwebtoken}
|
|
53
|
+
⚠{Users must be stored ∈ database, Tokens expire after 24h}
|
|
92
54
|
*/
|
|
93
55
|
|
|
94
56
|
/**@darkarts
|
|
95
|
-
⊳{
|
|
96
|
-
|
|
97
|
-
|
|
98
|
-
}
|
|
99
|
-
|
|
100
|
-
Returns a JWT token
|
|
101
|
-
User is authenticated ∈ database
|
|
102
|
-
}
|
|
103
|
-
⊨{
|
|
104
|
-
Does ¬ modify existing user records
|
|
105
|
-
}
|
|
106
|
-
⚡{
|
|
107
|
-
Creates a new session ∈ database
|
|
108
|
-
}
|
|
57
|
+
⊳{userId must be a valid UUID, password must be ≥8 characters}
|
|
58
|
+
⊲{Returns JWT token ∨ null, Token contains {userId, email, role}}
|
|
59
|
+
⊨{Does ¬ modify database, Password is ¬ logged}
|
|
60
|
+
⚡{O(1)}
|
|
61
|
+
🔒{Password hashed with bcrypt, Token signed with secret}
|
|
109
62
|
*/
|
|
110
|
-
export async function
|
|
111
|
-
|
|
63
|
+
export async function authenticateUser(
|
|
64
|
+
userId: string,
|
|
65
|
+
password: string
|
|
66
|
+
): Promise<string | null> {
|
|
67
|
+
// Implementation
|
|
112
68
|
}
|
|
113
69
|
```
|
|
114
70
|
|
|
115
|
-
|
|
71
|
+
#### Python
|
|
116
72
|
|
|
117
|
-
|
|
118
|
-
|
|
119
|
-
|
|
120
|
-
|
|
73
|
+
```python
|
|
74
|
+
"""@darkarts
|
|
75
|
+
⊢{User authentication service with JWT token generation}
|
|
76
|
+
∂{bcrypt, jwt}
|
|
77
|
+
⚠{Users must be stored ∈ database, Tokens expire after 24h}
|
|
78
|
+
"""
|
|
79
|
+
|
|
80
|
+
"""@darkarts
|
|
81
|
+
⊳{user_id must be a valid UUID, password must be ≥8 characters}
|
|
82
|
+
⊲{Returns JWT token ∨ None, Token contains {user_id, email, role}}
|
|
83
|
+
⊨{Does ¬ modify database, Password is ¬ logged}
|
|
84
|
+
⚡{O(1)}
|
|
85
|
+
🔒{Password hashed with bcrypt, Token signed with secret}
|
|
86
|
+
"""
|
|
87
|
+
def authenticate_user(user_id: str, password: str) -> Optional[str]:
|
|
88
|
+
# Implementation
|
|
89
|
+
pass
|
|
121
90
|
```
|
|
122
91
|
|
|
123
|
-
|
|
124
|
-
- **Semantic validation**: Dependencies match imports
|
|
125
|
-
- **Performance validation**: Complexity claims are accurate
|
|
126
|
-
- **Consistency**: All required fields are present
|
|
92
|
+
---
|
|
127
93
|
|
|
128
|
-
|
|
94
|
+
## Symbolic Format Reference
|
|
129
95
|
|
|
130
|
-
|
|
96
|
+
### Module-Level Annotations
|
|
131
97
|
|
|
132
|
-
|
|
133
|
-
|
|
134
|
-
|
|
98
|
+
| Symbol | Field | Description | Example |
|
|
99
|
+
|--------|-------|-------------|---------|
|
|
100
|
+
| ⊢ | module_purpose | What this module does | `⊢{User authentication service}` |
|
|
101
|
+
| ∂ | dependencies | External dependencies | `∂{bcrypt, jsonwebtoken}` |
|
|
102
|
+
| ⚠ | assumptions | Preconditions for module | `⚠{Database is initialized}` |
|
|
135
103
|
|
|
136
|
-
###
|
|
104
|
+
### Function-Level Annotations
|
|
137
105
|
|
|
138
|
-
|
|
106
|
+
| Symbol | Field | Description | Example |
|
|
107
|
+
|--------|-------|-------------|---------|
|
|
108
|
+
| ⊳ | preconditions | Input requirements | `⊳{userId must be a valid UUID}` |
|
|
109
|
+
| ⊲ | postconditions | Output guarantees | `⊲{Returns user object ∨ null}` |
|
|
110
|
+
| ⊨ | invariants | Conditions that always hold | `⊨{Does ¬ modify database}` |
|
|
111
|
+
| ⚡ | complexity | Time/space complexity | `⚡{O(n log n)}` |
|
|
112
|
+
| 🔒 | security | Security implications | `🔒{Password hashed with bcrypt}` |
|
|
139
113
|
|
|
140
|
-
|
|
141
|
-
|
|
142
|
-
|
|
114
|
+
### Logic Operators
|
|
115
|
+
|
|
116
|
+
| Symbol | Meaning | Example |
|
|
117
|
+
|--------|---------|---------|
|
|
118
|
+
| ∧ | and | `x > 0 ∧ y > 0` |
|
|
119
|
+
| ∨ | or | `Returns user ∨ null` |
|
|
120
|
+
| ¬ | not | `¬ empty string` |
|
|
121
|
+
| ∈ | in/element of | `user ∈ database` |
|
|
122
|
+
| ∃ | exists | `∃ user: user.id = userId` |
|
|
123
|
+
| ∀ | for all | `∀ item ∈ array: item ≠ null` |
|
|
124
|
+
| ⇒ | implies | `x > 0 ⇒ result > 0` |
|
|
125
|
+
| ⇔ | if and only if | `valid ⇔ checksum matches` |
|
|
143
126
|
|
|
144
127
|
---
|
|
145
128
|
|
|
146
|
-
##
|
|
129
|
+
## Commands
|
|
147
130
|
|
|
148
131
|
### `voodocs init`
|
|
149
132
|
|
|
150
|
-
Initialize
|
|
133
|
+
Initialize VooDocs in your project with an interactive wizard:
|
|
151
134
|
|
|
152
135
|
```bash
|
|
153
|
-
voodocs init
|
|
154
|
-
voodocs init --
|
|
155
|
-
voodocs init --
|
|
136
|
+
voodocs init # Interactive setup
|
|
137
|
+
voodocs init --upgrade # Upgrade existing configuration
|
|
138
|
+
voodocs init --non-interactive # Use defaults
|
|
156
139
|
```
|
|
157
140
|
|
|
158
|
-
### `voodocs
|
|
141
|
+
### `voodocs instruct`
|
|
159
142
|
|
|
160
|
-
|
|
143
|
+
Generate AI instructions for your coding assistant:
|
|
161
144
|
|
|
162
145
|
```bash
|
|
163
|
-
voodocs
|
|
164
|
-
|
|
165
|
-
|
|
166
|
-
|
|
167
|
-
-s, --strict Exit with error code if validation fails
|
|
168
|
-
-f, --format <format> Output format: text, json, html (default: text)
|
|
169
|
-
--semantic-only Only run semantic validation
|
|
170
|
-
--performance-only Only run performance validation
|
|
146
|
+
voodocs instruct # Auto-detect AI environment
|
|
147
|
+
voodocs instruct --ai cursor # Generate for Cursor
|
|
148
|
+
voodocs instruct --output .cursorrules # Save to file
|
|
149
|
+
voodocs instruct --list-templates # List available templates
|
|
171
150
|
```
|
|
172
151
|
|
|
173
|
-
|
|
152
|
+
### `voodocs validate`
|
|
153
|
+
|
|
154
|
+
Validate annotations in your codebase:
|
|
155
|
+
|
|
174
156
|
```bash
|
|
175
|
-
voodocs validate ./src
|
|
157
|
+
voodocs validate ./src # Validate directory
|
|
158
|
+
voodocs validate ./src -r # Recursive
|
|
159
|
+
voodocs validate ./src --strict # Exit with error code on issues
|
|
160
|
+
voodocs validate ./src --json # JSON output
|
|
176
161
|
```
|
|
177
162
|
|
|
178
163
|
### `voodocs fix`
|
|
179
164
|
|
|
180
|
-
Automatically fix
|
|
181
|
-
|
|
182
|
-
```bash
|
|
183
|
-
voodocs fix <path> [options]
|
|
184
|
-
|
|
185
|
-
Options:
|
|
186
|
-
-r, --recursive Process directories recursively
|
|
187
|
-
-d, --dry-run Show what would be fixed without making changes
|
|
188
|
-
-b, --backup Create backup files before fixing
|
|
189
|
-
```
|
|
165
|
+
Automatically fix common annotation errors:
|
|
190
166
|
|
|
191
|
-
**Example:**
|
|
192
167
|
```bash
|
|
193
|
-
voodocs fix ./src
|
|
168
|
+
voodocs fix ./src # Fix directory
|
|
169
|
+
voodocs fix ./src -r # Recursive
|
|
170
|
+
voodocs fix ./src --dry-run # Preview changes
|
|
171
|
+
voodocs fix ./src --backup # Create backups
|
|
194
172
|
```
|
|
195
173
|
|
|
196
174
|
### `voodocs generate`
|
|
197
175
|
|
|
198
|
-
Generate documentation from annotations
|
|
176
|
+
Generate documentation from annotations:
|
|
199
177
|
|
|
200
178
|
```bash
|
|
201
|
-
voodocs generate
|
|
202
|
-
|
|
203
|
-
|
|
204
|
-
|
|
205
|
-
-f, --format <format> Output format: markdown, html (default: markdown)
|
|
206
|
-
-v, --validate Validate annotations before generating
|
|
207
|
-
--include-toc Include table of contents
|
|
208
|
-
```
|
|
209
|
-
|
|
210
|
-
**Example:**
|
|
211
|
-
```bash
|
|
212
|
-
voodocs generate ./src ./docs --recursive --validate
|
|
179
|
+
voodocs generate ./src ./docs # Generate docs
|
|
180
|
+
voodocs generate ./src ./docs -r # Recursive
|
|
181
|
+
voodocs generate ./src ./docs --validate # Validate first
|
|
182
|
+
voodocs generate ./src ./docs --format json # JSON output
|
|
213
183
|
```
|
|
214
184
|
|
|
215
185
|
### `voodocs benchmark`
|
|
216
186
|
|
|
217
|
-
|
|
187
|
+
Benchmark code and validate performance claims:
|
|
218
188
|
|
|
219
189
|
```bash
|
|
220
|
-
voodocs benchmark
|
|
221
|
-
|
|
222
|
-
|
|
223
|
-
|
|
224
|
-
-f, --format <format> Output format: text, json, html (default: text)
|
|
225
|
-
--iterations <n> Number of benchmark iterations (default: 100)
|
|
190
|
+
voodocs benchmark ./src # Benchmark directory
|
|
191
|
+
voodocs benchmark ./src -r # Recursive
|
|
192
|
+
voodocs benchmark ./src --json # JSON output
|
|
193
|
+
voodocs benchmark ./src --html # HTML report
|
|
226
194
|
```
|
|
227
195
|
|
|
228
|
-
**Example:**
|
|
229
|
-
```bash
|
|
230
|
-
voodocs benchmark ./src --recursive --format json
|
|
231
|
-
```
|
|
232
|
-
|
|
233
|
-
---
|
|
234
|
-
|
|
235
|
-
## Annotation Fields
|
|
236
|
-
|
|
237
|
-
### Module-Level Annotations
|
|
238
|
-
|
|
239
|
-
| Field | Symbol | Description |
|
|
240
|
-
|-------|--------|-------------|
|
|
241
|
-
| `module_purpose` | `⊢` | Concise statement of the module's responsibility |
|
|
242
|
-
| `dependencies` | `∂` | List of critical internal or external dependencies |
|
|
243
|
-
| `assumptions` | `⚠` | Key assumptions about environment or inputs |
|
|
244
|
-
| `invariants` | `⊨` | Properties that remain unchanged |
|
|
245
|
-
| `security_model` | `🔒` | Security considerations |
|
|
246
|
-
| `performance_model` | `⚡` | Performance characteristics |
|
|
247
|
-
|
|
248
|
-
### Function/Interface-Level Annotations
|
|
249
|
-
|
|
250
|
-
| Field | Symbol | Description |
|
|
251
|
-
|-------|--------|-------------|
|
|
252
|
-
| `preconditions` | `⊳` | Conditions that must be true before execution |
|
|
253
|
-
| `postconditions` | `⊲` | Conditions that will be true after execution |
|
|
254
|
-
| `invariants` | `⊨` | Properties that remain unchanged |
|
|
255
|
-
| `side_effects` | `⚡` | Observable effects outside the return value |
|
|
256
|
-
| `security_implications` | `🔒` | Security-related considerations |
|
|
257
|
-
| `complexity` | `⚡` | Computational complexity (e.g., O(n)) |
|
|
258
|
-
|
|
259
196
|
---
|
|
260
197
|
|
|
261
|
-
##
|
|
198
|
+
## Configuration
|
|
262
199
|
|
|
263
|
-
|
|
200
|
+
The `.voodocs.json` file configures VooDocs for your project:
|
|
264
201
|
|
|
265
|
-
|
|
266
|
-
|
|
267
|
-
|
|
268
|
-
|
|
269
|
-
|
|
270
|
-
|
|
271
|
-
|
|
272
|
-
|
|
273
|
-
|
|
274
|
-
|
|
202
|
+
```json
|
|
203
|
+
{
|
|
204
|
+
"name": "my-project",
|
|
205
|
+
"version": "1.0.0",
|
|
206
|
+
"format": "darkarts",
|
|
207
|
+
"repository": "https://github.com/user/my-project",
|
|
208
|
+
"private": true,
|
|
209
|
+
"exclude": [
|
|
210
|
+
"node_modules",
|
|
211
|
+
"dist",
|
|
212
|
+
"build"
|
|
213
|
+
]
|
|
214
|
+
}
|
|
215
|
+
```
|
|
275
216
|
|
|
276
217
|
---
|
|
277
218
|
|
|
278
219
|
## CI/CD Integration
|
|
279
220
|
|
|
280
|
-
|
|
221
|
+
Add VooDocs validation to your CI pipeline:
|
|
281
222
|
|
|
282
223
|
```yaml
|
|
283
|
-
# .github/workflows/validate
|
|
224
|
+
# .github/workflows/validate.yml
|
|
284
225
|
name: Validate Documentation
|
|
285
|
-
|
|
286
226
|
on: [push, pull_request]
|
|
287
|
-
|
|
288
227
|
jobs:
|
|
289
228
|
validate:
|
|
290
229
|
runs-on: ubuntu-latest
|
|
291
230
|
steps:
|
|
292
|
-
- uses: actions/checkout@
|
|
293
|
-
|
|
294
|
-
- name: Setup Node.js
|
|
295
|
-
uses: actions/setup-node@v2
|
|
231
|
+
- uses: actions/checkout@v3
|
|
232
|
+
- uses: actions/setup-node@v3
|
|
296
233
|
with:
|
|
297
234
|
node-version: '18'
|
|
298
|
-
|
|
299
|
-
-
|
|
300
|
-
run: npm install -g @voodocs/cli
|
|
301
|
-
|
|
302
|
-
- name: Validate Annotations
|
|
303
|
-
run: voodocs validate ./src --recursive --strict
|
|
235
|
+
- run: npm install -g @voodocs/cli
|
|
236
|
+
- run: voodocs validate ./src --strict --recursive
|
|
304
237
|
```
|
|
305
238
|
|
|
306
239
|
---
|
|
307
240
|
|
|
308
|
-
##
|
|
309
|
-
|
|
310
|
-
Create a `.voodocs.json` file in your project root:
|
|
241
|
+
## Why Symbolic Format?
|
|
311
242
|
|
|
312
|
-
|
|
313
|
-
|
|
314
|
-
|
|
315
|
-
|
|
316
|
-
|
|
317
|
-
|
|
318
|
-
|
|
319
|
-
|
|
320
|
-
|
|
321
|
-
|
|
322
|
-
"output_format": "markdown",
|
|
323
|
-
"include_toc": true,
|
|
324
|
-
"include_examples": true
|
|
325
|
-
},
|
|
326
|
-
"exclude": [
|
|
327
|
-
"node_modules",
|
|
328
|
-
"dist",
|
|
329
|
-
"build",
|
|
330
|
-
"__pycache__",
|
|
331
|
-
".git"
|
|
332
|
-
]
|
|
333
|
-
}
|
|
243
|
+
### 1. **Concise**
|
|
244
|
+
```
|
|
245
|
+
⊳{userId ∈ database ∧ password ≥8 chars}
|
|
246
|
+
```
|
|
247
|
+
vs.
|
|
248
|
+
```
|
|
249
|
+
preconditions: [
|
|
250
|
+
"userId must exist in database",
|
|
251
|
+
"password must be at least 8 characters"
|
|
252
|
+
]
|
|
334
253
|
```
|
|
335
254
|
|
|
336
|
-
|
|
255
|
+
### 2. **Precise**
|
|
256
|
+
Mathematical notation eliminates ambiguity
|
|
337
257
|
|
|
338
|
-
|
|
258
|
+
### 3. **AI-Optimized**
|
|
259
|
+
Fewer tokens = lower costs for AI processing
|
|
339
260
|
|
|
340
|
-
|
|
341
|
-
|
|
342
|
-
|
|
343
|
-
|
|
261
|
+
### 4. **Language-Independent**
|
|
262
|
+
Symbols transcend language barriers
|
|
263
|
+
|
|
264
|
+
### 5. **Unique**
|
|
265
|
+
Patent-pending innovation (VDA-004)
|
|
344
266
|
|
|
345
267
|
---
|
|
346
268
|
|
|
347
|
-
##
|
|
269
|
+
## Supported Languages
|
|
348
270
|
|
|
349
|
-
-
|
|
350
|
-
-
|
|
351
|
-
-
|
|
271
|
+
- TypeScript/JavaScript (`.ts`, `.tsx`, `.js`, `.jsx`)
|
|
272
|
+
- Python (`.py`)
|
|
273
|
+
- Java (`.java`)
|
|
274
|
+
- C++ (`.cpp`, `.cc`, `.h`)
|
|
275
|
+
- C# (`.cs`)
|
|
276
|
+
- Go (`.go`)
|
|
277
|
+
- Rust (`.rs`)
|
|
278
|
+
- Solidity (`.sol`)
|
|
352
279
|
|
|
353
280
|
---
|
|
354
281
|
|
|
355
|
-
##
|
|
282
|
+
## Documentation
|
|
356
283
|
|
|
357
|
-
|
|
284
|
+
- [User Guide](docs/darkarts/USER_GUIDE.md)
|
|
285
|
+
- [API Reference](docs/darkarts/API_REFERENCE.md)
|
|
286
|
+
- [Tutorials](docs/darkarts/TUTORIALS.md)
|
|
287
|
+
- [Symbolic Format Specification](lib/darkarts/annotations/DARKARTS_SYMBOLS.md)
|
|
358
288
|
|
|
359
289
|
---
|
|
360
290
|
|
|
361
|
-
##
|
|
291
|
+
## Support
|
|
292
|
+
|
|
293
|
+
- 📧 Email: support@voodocs.com
|
|
294
|
+
- 🌐 Website: https://voodocs.com
|
|
295
|
+
- 📝 Issues: https://github.com/3vilEnterprises/vooodooo-magic/issues
|
|
296
|
+
- 💬 Discord: https://discord.gg/voodocs
|
|
362
297
|
|
|
363
|
-
|
|
364
|
-
|
|
365
|
-
|
|
366
|
-
- ✅ Fixed annotation parsing for TypeScript files
|
|
367
|
-
- ✅ Standardized terminology (@voodocs and @darkarts both supported)
|
|
298
|
+
---
|
|
299
|
+
|
|
300
|
+
## License
|
|
368
301
|
|
|
369
|
-
|
|
370
|
-
- ✅ Better error messages
|
|
371
|
-
- ✅ Improved documentation
|
|
372
|
-
- ✅ Enhanced validation accuracy
|
|
302
|
+
Commercial License - See [LICENSE](LICENSE) for details.
|
|
373
303
|
|
|
374
304
|
---
|
|
375
305
|
|
|
376
|
-
**VooDocs - The
|
|
306
|
+
**VooDocs** - The world's first AI-native symbolic documentation system.
|
package/lib/cli/__init__.py
CHANGED
|
@@ -16,7 +16,7 @@ This module provides the command-line interface for VooDocs.
|
|
|
16
16
|
import click
|
|
17
17
|
from typing import Optional
|
|
18
18
|
|
|
19
|
-
__version__ = "
|
|
19
|
+
__version__ = "2.0.0"
|
|
20
20
|
|
|
21
21
|
|
|
22
22
|
@click.group()
|
|
@@ -24,11 +24,11 @@ __version__ = "1.0.7"
|
|
|
24
24
|
@click.pass_context
|
|
25
25
|
def cli(ctx):
|
|
26
26
|
"""
|
|
27
|
-
VooDocs - AI-Native Documentation
|
|
27
|
+
VooDocs - AI-Native Symbolic Documentation System
|
|
28
28
|
|
|
29
|
-
Generate and validate @
|
|
29
|
+
Generate and validate @darkarts symbolic annotations in your codebase.
|
|
30
30
|
|
|
31
|
-
|
|
31
|
+
Uses mathematical notation (⊢, ∂, ⚠, ⊳, ⊲, ⊨, ⚡, 🔒) for concise, precise documentation.
|
|
32
32
|
"""
|
|
33
33
|
ctx.ensure_object(dict)
|
|
34
34
|
|
package/lib/cli/generate.py
CHANGED
|
@@ -222,17 +222,17 @@ def _generate_doc_for_file(file_path: Path, format: str, include_private: bool)
|
|
|
222
222
|
|
|
223
223
|
|
|
224
224
|
def _extract_annotation(content: str) -> str:
|
|
225
|
-
"""Extract @darkarts
|
|
225
|
+
"""Extract @darkarts annotation from file content."""
|
|
226
226
|
import re
|
|
227
227
|
|
|
228
|
-
# Try Python docstring format
|
|
229
|
-
python_pattern = r'"""@
|
|
228
|
+
# Try Python docstring format ("""@darkarts)
|
|
229
|
+
python_pattern = r'"""@darkarts\s*(.*?)"""'
|
|
230
230
|
match = re.search(python_pattern, content, re.DOTALL)
|
|
231
231
|
if match:
|
|
232
232
|
return match.group(0)
|
|
233
233
|
|
|
234
|
-
# Try TypeScript/JavaScript block comment format (/**@darkarts
|
|
235
|
-
js_pattern = r'/\*\*@
|
|
234
|
+
# Try TypeScript/JavaScript block comment format (/**@darkarts)
|
|
235
|
+
js_pattern = r'/\*\*@darkarts\s*(.*?)\*/'
|
|
236
236
|
match = re.search(js_pattern, content, re.DOTALL)
|
|
237
237
|
if match:
|
|
238
238
|
return match.group(0)
|
package/lib/cli/init.py
CHANGED
|
@@ -128,40 +128,13 @@ def init(non_interactive, upgrade):
|
|
|
128
128
|
click.echo(click.style('✨ Step 2: Annotation Format', fg='blue', bold=True))
|
|
129
129
|
click.echo()
|
|
130
130
|
|
|
131
|
-
|
|
132
|
-
|
|
133
|
-
|
|
134
|
-
|
|
135
|
-
|
|
136
|
-
|
|
137
|
-
|
|
138
|
-
change_format = click.confirm('Change annotation format?', default=False)
|
|
139
|
-
if change_format:
|
|
140
|
-
click.echo()
|
|
141
|
-
click.echo('VooDocs supports two annotation formats:')
|
|
142
|
-
click.echo(' 1. Natural language (e.g., module_purpose: "...")')
|
|
143
|
-
click.echo(' 2. Symbolic DarkArts (e.g., ⊢{...}, ∂{...}, ⚠{...})')
|
|
144
|
-
click.echo()
|
|
145
|
-
format_choice = click.prompt(
|
|
146
|
-
'Choose format',
|
|
147
|
-
type=click.Choice(['voodocs', 'darkarts'], case_sensitive=False),
|
|
148
|
-
default=current_format
|
|
149
|
-
)
|
|
150
|
-
else:
|
|
151
|
-
format_choice = current_format
|
|
152
|
-
else:
|
|
153
|
-
click.echo('VooDocs supports two annotation formats:')
|
|
154
|
-
click.echo(' 1. Natural language (e.g., module_purpose: "...")')
|
|
155
|
-
click.echo(' 2. Symbolic DarkArts (e.g., ⊢{...}, ∂{...}, ⚠{...})')
|
|
156
|
-
click.echo()
|
|
157
|
-
if non_interactive:
|
|
158
|
-
format_choice = 'darkarts'
|
|
159
|
-
else:
|
|
160
|
-
format_choice = click.prompt(
|
|
161
|
-
'Choose format',
|
|
162
|
-
type=click.Choice(['voodocs', 'darkarts'], case_sensitive=False),
|
|
163
|
-
default='darkarts'
|
|
164
|
-
)
|
|
131
|
+
# DarkArts symbolic format only
|
|
132
|
+
format_choice = 'darkarts'
|
|
133
|
+
click.echo('Using DarkArts symbolic format:')
|
|
134
|
+
click.echo(' ⊢{...} module_purpose ∂{...} dependencies ⚠{...} assumptions')
|
|
135
|
+
click.echo(' ⊳{...} preconditions ⊲{...} postconditions ⊨{...} invariants')
|
|
136
|
+
click.echo(' ⚡{...} complexity 🔒{...} security')
|
|
137
|
+
click.echo(click.style(' ✓', fg='green') + ' AI-native symbolic annotations')
|
|
165
138
|
|
|
166
139
|
click.echo()
|
|
167
140
|
|
|
@@ -43,23 +43,18 @@ except ImportError:
|
|
|
43
43
|
|
|
44
44
|
|
|
45
45
|
class AnnotationParser:
|
|
46
|
-
"""Parser for DarkArts annotations."""
|
|
46
|
+
"""Parser for DarkArts symbolic annotations (@darkarts only)."""
|
|
47
47
|
|
|
48
|
-
#
|
|
49
|
-
PATTERNS = {
|
|
50
|
-
Language.PYTHON: r'"""@voodocs\s*(.*?)\s*"""',
|
|
51
|
-
}
|
|
52
|
-
|
|
53
|
-
# DarkArts patterns (symbolic annotations) - support both @voodocs and @darkarts
|
|
48
|
+
# DarkArts patterns (symbolic annotations)
|
|
54
49
|
DARKARTS_PATTERNS = {
|
|
55
|
-
Language.PYTHON: r'"""@
|
|
56
|
-
Language.TYPESCRIPT: r'/\*\*@
|
|
57
|
-
Language.JAVASCRIPT: r'/\*\*@
|
|
58
|
-
Language.JAVA: r'/\*\*@
|
|
59
|
-
Language.CPP: r'/\*\*@
|
|
60
|
-
Language.CSHARP: r'/\*\*@
|
|
61
|
-
Language.GO: r'/\*\*@
|
|
62
|
-
Language.RUST: r'/\*\*@
|
|
50
|
+
Language.PYTHON: r'"""@darkarts\s*(.*?)\s*"""',
|
|
51
|
+
Language.TYPESCRIPT: r'/\*\*@darkarts\s*(.*?)\s*\*/',
|
|
52
|
+
Language.JAVASCRIPT: r'/\*\*@darkarts\s*(.*?)\s*\*/',
|
|
53
|
+
Language.JAVA: r'/\*\*@darkarts\s*(.*?)\s*\*/',
|
|
54
|
+
Language.CPP: r'/\*\*@darkarts\s*(.*?)\s*\*/',
|
|
55
|
+
Language.CSHARP: r'/\*\*@darkarts\s*(.*?)\s*\*/',
|
|
56
|
+
Language.GO: r'/\*\*@darkarts\s*(.*?)\s*\*/',
|
|
57
|
+
Language.RUST: r'/\*\*@darkarts\s*(.*?)\s*\*/',
|
|
63
58
|
}
|
|
64
59
|
|
|
65
60
|
def __init__(self):
|
package/package.json
CHANGED
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@voodocs/cli",
|
|
3
|
-
"version": "
|
|
4
|
-
"description": "AI-Native Documentation System
|
|
3
|
+
"version": "2.0.0",
|
|
4
|
+
"description": "AI-Native Symbolic Documentation System - The world's first documentation tool using mathematical notation with semantic validation",
|
|
5
5
|
"main": "voodocs_cli.py",
|
|
6
6
|
"bin": {
|
|
7
7
|
"voodocs": "./voodocs_cli.py"
|
|
@@ -12,26 +12,27 @@
|
|
|
12
12
|
"build-ts-parser": "cd lib/darkarts/parsers/typescript && npm install && npm run build"
|
|
13
13
|
},
|
|
14
14
|
"keywords": [
|
|
15
|
+
"darkarts",
|
|
16
|
+
"symbolic-documentation",
|
|
17
|
+
"ai-native",
|
|
18
|
+
"mathematical-notation",
|
|
19
|
+
"semantic-validation",
|
|
15
20
|
"documentation",
|
|
16
21
|
"validation",
|
|
17
22
|
"ai",
|
|
18
|
-
"voodocs",
|
|
19
|
-
"darkarts",
|
|
20
23
|
"testing",
|
|
21
|
-
"
|
|
22
|
-
"
|
|
23
|
-
"
|
|
24
|
+
"performance-validation",
|
|
25
|
+
"benchmarking",
|
|
26
|
+
"auto-fix",
|
|
24
27
|
"ai-assistant",
|
|
25
28
|
"cursor",
|
|
26
29
|
"claude",
|
|
27
|
-
"property-based-testing",
|
|
28
|
-
"hypothesis",
|
|
29
30
|
"annotation-validation",
|
|
30
|
-
"
|
|
31
|
-
"
|
|
32
|
-
"
|
|
33
|
-
"
|
|
34
|
-
"
|
|
31
|
+
"ci-cd",
|
|
32
|
+
"code-documentation",
|
|
33
|
+
"api-documentation",
|
|
34
|
+
"typescript",
|
|
35
|
+
"python"
|
|
35
36
|
],
|
|
36
37
|
"author": "3vilEnterprises <contact@3vil.enterprises>",
|
|
37
38
|
"license": "Commercial",
|