AI-Native Symbolic Documentation System - The world's first documentation tool using mathematical notation with semantic validation
npm install @voodocs/cliThe world's first documentation system designed exclusively for AI.
DarkArts is a mathematical notation system for documenting code that is optimized for AI understanding, not human reading. It achieves 79% token reduction compared to traditional comments while providing more precise semantic information.
DarkArts is for AI, not humans.
- AI writes it - Using assistants like Claude, Cursor, GitHub Copilot
- AI reads it - LLMs parse it instantly with mathematical precision
- Humans don't touch it - Use generated docs or companion files instead
DarkArts uses Unicode mathematical symbols for maximum precision and token efficiency:
| Symbol | Meaning | Example |
|--------|---------|---------|
| β’ | Purpose | β’{u auth svc} |
| β | Dependencies | β{bcrypt,db} |
| β | Assumptions | β {u exists in db} |
| β³ | Preconditions | β³{id:uuid,pwβ₯8} |
| β² | Postconditions | β²{ret tok\|null} |
| β¨ | Invariants | β¨{no db mod} |
| β‘ | Complexity | β‘{O(1)} |
| π | Security | π{pw:hash} |
| Symbol | Meaning | Example |
|--------|---------|---------|
| β | Bidirectional | β{encβdec} |
| β | Side Effects | β{writes db} |
| β | Forbidden | β{no pw log} |
| β | Approximation | β{Β±0.001} |
| β΄ | Consequence | β΄{failβnull} |
| β | Universal | β{users have email} |
| β | Existential | β{admin required} |
79% reduction compared to traditional comments:
``typescript
// Traditional (140 tokens)
/**
* User authentication service with JWT token generation.
* Dependencies: bcrypt, jsonwebtoken, database
* Preconditions: identifier must be valid UUID, password β₯8 chars
* Postconditions: returns JWT token or null
* Invariants: does not modify database
* Security: password hashed, token encrypted
*/
// DarkArts v3.0.0 (30 tokens)
/**@darkarts
β’{u auth svc w/ JWT tok gen}
β{bcrypt,jsonwebtoken,db}
β³{id:uuid,pwβ₯8}
β²{ret JWT tok|null}
β¨{no db mod}
π{pw:hash,tok:enc}
*/
`
`bash`
npm install -g @voodocs/cli@3.0.0
`bash`
voodocs init
Use your AI assistant (Claude, Cursor, etc.) to generate DarkArts annotations:
``
Prompt: "Add DarkArts v3.0.0 annotations to this function"
`bash`
voodocs validate src/ -r
`bash`
voodocs generate src/
Use shorthand for common validations:
`typescript`
/**@darkarts
β³{id:uuid, email:email, pwβ₯8, age[18,65]}
*/
Available patterns:
- :uuid - valid UUID:email
- - valid email format:url
- - valid URL:json
- - valid JSON:jwt
- - valid JWT token:hash
- - hashed value:enc
- - encrypted valueβ₯N
- , β€N, >N,
- [N,M] - range notationβ{...}
- - set membership
200+ abbreviations for maximum compression:
Core:
- u = user, pw = password, auth = authenticationtok
- = token, sess = session, svc = service
Web/API:
- ep = endpoint, rt = route, mw = middlewarereq
- = request, res = response, hdl = handler
Security:
- enc = encryption, dec = decryption, sig = signaturecert
- = certificate, perm = permission
Data:
- db = database, tbl = table, rec = recordidx
- = index, sch = schema, coll = collection
[See full list in documentation]
Seven new symbols for richer semantics:
`typescript`
/**@darkarts
β’{data enc/dec svc}
β{encβdec} // Bidirectional operations
β{writes cache} // Side effects
β{no pw log} // Forbidden operations
β{Β±0.001 precision} // Approximation
β΄{if failβretry 3x} // Logical consequences
β{all data:enc} // Universal properties
β{valid key required} // Existential properties
*/
Enhanced parser with semantic validation:
`bash
$ voodocs validate src/auth.ts
Error in @darkarts annotation at line 42:
β³{id:uuuid}
^^^^^
Unknown pattern ':uuuid'. Did you mean ':uuid'?
Available patterns: :uuid, :email, :url, :json, :jwt, :hash, :enc
Error at line 45:
Contradiction - invariant says no db modification,
but side effect writes to database
`
`bashInitialize project
voodocs init
π§ Context System
DarkArts integrates with AI context management:
`bash
Initialize context
voodocs context initGenerate context from annotations
voodocs generate src/ -rView context
voodocs context view
`Context files (
.voodocs/context.json) provide structured information for AI assistants.π Companion Files
For compiled languages (Solidity, Rust, etc.), use companion files:
`bash
Create .voodocs.md files alongside source
voodocs companion contracts/ -r
`Example:
`
contracts/
Registry.sol
Registry.sol.voodocs.md β Human-readable documentation
`π For Humans
Humans should never manually write or read DarkArts annotations. Instead:
1. Use AI to generate annotations
2. Read generated docs (HTML, Markdown)
3. Use companion files for human-readable documentation
π¬ Research & Patents
DarkArts is based on peer-reviewed research and protected by patents:
- Patent 1: Context-Augmented AI Systems
- Patent 2: Multi-Dimensional Quality Categorization
- Patent 3: Invariant-Guided Code Generation
- Patent 4: Token-Efficient Context Management
Portfolio Value: $50M-180M
π Benchmarks
Real-world performance validation:
| Metric | Improvement |
|--------|-------------|
| Token Reduction | 79% |
| Quality Score | +42% |
| Time Reduction | 43% |
| Bug Detection | +67% |
| Cost Savings | $12.2K/year per developer |
π Ecosystem
- ESLint Plugin:
eslint-plugin-voodocs
- TypeScript Support: Built-in parser
- Python Support: Built-in parser
- Solidity Support: Via companion filesπ Documentation
- User Guide
- API Reference
- Tutorials
- Examples
π€ Contributing
DarkArts is commercial software. For enterprise licensing:
- Email: contact@3vil.enterprises
- Website: https://voodocs.com
π License
Commercial License - Β© 2025 3vilEnterprises
π What's New in v3.0.0
$3
- Removed
@darkarts-lite - Only mathematical notation supported
- New symbols - Old parsers won't recognize β, β, β, β, β΄, β, β$3
- β
Pattern shortcuts (
:uuid, :email, β₯N`, etc.)No migration needed! v3.0.0 is backward compatible with v2.x annotations. New features are optional enhancements.
---
DarkArts v3.0.0 - The AI-Native Mathematical Language for Code