@voodocs/cli 1.0.0 → 1.0.2

package/README.md

@@ -1,28 +1,27 @@
-# Voodocs - AI-Native Documentation System
+# VooDocs - AI-Native Documentation with Validation
 
 [![NPM Version](https://img.shields.io/npm/v/@voodocs/cli.svg)](https://www.npmjs.com/package/@voodocs/cli)
 [![License](https://img.shields.io/npm/l/@voodocs/cli.svg)](https://voodocs.com/terms)
 [![Support](https://img.shields.io/badge/support-priority-blue.svg)](https://voodocs.com/support)
 
-**Voodocs** is a revolutionary AI-native documentation system that transforms how software is documented, tested, and specified. It teaches AI coding assistants (like Cursor and Claude Code) to write precise, machine-readable specifications in `@voodocs` annotations using the **DarkArtsAI language** - the mathematical and logical notation that AI naturally understands. These annotations are then automatically translated into human-readable documentation, automated tests, and API specifications.
+**VooDocs** is the only documentation tool that validates your annotations and guarantees accuracy. It combines AI-native symbolic documentation with semantic validation, performance verification, and automatic error correction.
 
-This is the future of software development: **AI documents your code in its native language, Voodocs translates it for humans.**
+## What Makes VooDocs Unique?
 
-## How It Works
+✅ **Semantic Validation** - Verifies that your documentation matches your code  
+✅ **Performance Validation** - Checks that complexity claims are accurate  
+✅ **Auto-Fix** - Automatically corrects common documentation errors  
+✅ **Benchmarking** - Validates performance claims with real execution data  
+✅ **Two Formats** - Natural language (`@voodocs`) or symbolic (`@darkarts`)  
+✅ **CI/CD Ready** - Strict mode with exit codes for continuous integration
 
-1.  **Install**: Add Voodocs to your project with `npm install -g @voodocs/cli`
-2.  **Instruct**: Run `voodocs instruct` to generate AI instructions for your coding assistant
-3.  **Code**: Your AI assistant (Cursor, Claude Code, etc.) automatically adds `@voodocs` annotations as it writes code
-4.  **Generate**: Run `voodocs generate` to produce:
-    - **Markdown Documentation**: Beautiful, human-readable docs
-    - **Automated Tests**: Comprehensive test suites (pytest, unittest, Jest)
-    - **API Specifications**: OpenAPI 3.0 and GraphQL schemas
+---
 
 ## Quick Start
 
 ### 1. Installation
 
-Install the CLI globally using `npm` or `pnpm`:
+Install the CLI globally using `npm`:
 
 ```bash
 npm install -g @voodocs/cli
@@ -30,179 +29,348 @@ npm install -g @voodocs/cli
 
 ### 2. Initialize Your Project
 
-Navigate to your project directory and initialize Voodocs:
+Navigate to your project directory and initialize VooDocs:
 
 ```bash
 voodocs init
 ```
 
-This will prompt you for your API key and set up the configuration.
-
-### 3. Generate AI Instructions
-
-Create instructions for your AI coding assistant:
-
-```bash
-voodocs instruct
-```
-
-This creates a `VOODOCS_INSTRUCTIONS.md` file. Provide this to your AI assistant (add to `.cursorrules`, Claude project instructions, etc.).
+This creates a `.voodocs.json` configuration file and example annotated files.
 
-### 4. Let AI Document Your Code
+### 3. Add Annotations to Your Code
 
-As you code with your AI assistant, it will automatically add `@voodocs` annotations:
+#### Natural Language Format (`@voodocs`)
 
 ```typescript
 /**@voodocs
 module_purpose: "User authentication service with JWT token generation"
 dependencies: [
-    "bcrypt: Password hashing",
-    "jsonwebtoken: JWT token generation"
+  "bcrypt: Password hashing",
+  "jsonwebtoken: JWT token generation"
 ]
 assumptions: [
-    "Database connection is established",
-    "User model exists with email and password fields"
+  "Database connection is established",
+  "User model exists with email and password fields"
+]
+*/
+
+/**@voodocs
+preconditions: [
+  "email must be a valid email format",
+  "password must be at least 8 characters"
+]
+postconditions: [
+  "Returns a JWT token",
+  "User is authenticated in the database"
 ]
-security_model: "Passwords hashed with bcrypt, tokens expire in 24h"
+invariants: [
+  "Does not modify existing user records"
+]
+side_effects: [
+  "Creates a new session in the database"
+]
+complexity: "O(1)"
+*/
+export async function login(email: string, password: string): Promise<string> {
+  // ...
+}
+```
+
+#### Symbolic Format (`@darkarts`)
+
+```typescript
+/**@darkarts
+⊢{User authentication service with JWT token generation}
+∂{
+  bcrypt: Password hashing
+  jsonwebtoken: JWT token generation
+}
+⚠{
+  Database connection is established
+  User model ∃ with email ∧ password fields
+}
+*/
+
+/**@darkarts
+⊳{
+  email must be a valid email format
+  password.length ≥ 8
+}
+⊲{
+  Returns a JWT token
+  User is authenticated ∈ database
+}
+⊨{
+  Does ¬ modify existing user records
+}
+⚡{
+  Creates a new session ∈ database
+}
 */
+export async function login(email: string, password: string): Promise<string> {
+  // ...
+}
+```
+
+### 4. Validate Your Annotations
+
+Run validation to ensure your documentation is accurate:
+
+```bash
+voodocs validate ./src --recursive
 ```
 
-### 5. Generate Documentation
+This checks:
+- **Semantic validation**: Dependencies match imports
+- **Performance validation**: Complexity claims are accurate
+- **Consistency**: All required fields are present
 
-Run the generate command to create documentation, tests, and API specs:
+### 5. Auto-Fix Issues
+
+Automatically fix common errors:
 
 ```bash
-# Generate everything
-voodocs generate ./src
+voodocs fix ./src --recursive
+```
 
-# Generate only documentation
-voodocs generate ./src --docs-only
+### 6. Generate Documentation
 
-# Generate only tests
-voodocs generate ./src --tests-only
+Create beautiful documentation from your annotations:
+
+```bash
+voodocs generate ./src ./docs --recursive
 ```
 
+---
+
 ## Core Commands
 
-### Documentation & Generation
-- `voodocs init`: Initialize VooDocs in your project
-- `voodocs instruct`: Generate instructions for your AI assistant
-- `voodocs generate <path>`: Generate docs, tests, and API specs from annotations
-- `voodocs status`: Check project status and statistics
-
-### Context System (Enhanced in v0.3.0)
-- `voodocs context init`: Initialize project context file
-- `voodocs context generate`: Auto-generate context from code annotations
-- `voodocs context check`: Validate code against documented invariants
-- `voodocs context diagram`: Generate architecture diagrams
-- `voodocs context validate`: Validate context file with smart suggestions
-- `voodocs context query`: Query context like a database
-- `voodocs context view`: View context as Markdown
-
-### AI Integration (NEW in v0.3.0)
-
-VooDocs now **natively integrates** with 5+ AI assistants! When you run `voodocs context init`, it automatically:
-- Detects existing AI configurations (Claude, Cursor, Copilot, etc.)
-- Prompts you to select your AI assistant(s)
-- Generates native configuration files for each AI
-
-**Supported AI Assistants:**
-- **Claude Code** - `.claude/skills/voodocs-context/SKILL.md`
-- **Cursor** - `.cursor/rules/voodocs-context.mdc`
-- **GitHub Copilot** - `.github/copilot-instructions.md`
-- **Windsurf** - `.windsurfrules`
-- **Cline** - `.clinerules`
-
-Your AI will automatically understand the VooDocs context system and:
-- Check context before making changes
-- Respect documented invariants
-- Update context when adding features
-- Generate architecture diagrams
-- Follow best practices
-
-## The DarkArts Language
-
-Voodocs uses the **DarkArts language** - a mathematical and logical notation system that represents how AI naturally thinks about code. Instead of forcing AI to write verbose human documentation, Voodocs lets AI express concepts precisely using:
-
-- **Mathematical notation**: ∀, ∃, ∈, ⇒, ⇔
-- **Formal logic**: Preconditions, postconditions, invariants
-- **Declarative relationships**: What IS, not what to DO
-- **Conditional reasoning**: Case-based specifications
-
-Voodocs then translates this precise, machine-readable format into natural language documentation that humans can easily understand.
-
-## What's New in v0.2.0
-
-### 🔍 Invariant Checking
-Automatically validate that your code respects documented invariants:
+### `voodocs init`
+
+Initialize a new project with VooDocs configuration and example files.
+
 ```bash
-voodocs context check
+voodocs init                    # Initialize with @voodocs format
+voodocs init --format darkarts  # Initialize with symbolic @darkarts format
+voodocs init --config-only      # Only create config file
 ```
-Detects security issues like SQL injection, unhashed passwords, and logged secrets.
 
-### 📊 Architecture Diagrams
-Auto-generate visual diagrams from your context:
+### `voodocs validate`
+
+Validate annotations against your code.
+
 ```bash
-voodocs context diagram --type modules --output arch.png --png
+voodocs validate <path> [options]
+
+Options:
+  -r, --recursive          Process directories recursively
+  -s, --strict             Exit with error code if validation fails
+  -f, --format <format>    Output format: text, json, html (default: text)
+  --semantic-only          Only run semantic validation
+  --performance-only       Only run performance validation
 ```
-Supports module diagrams, dependency diagrams, and flow diagrams.
 
-### ✅ Enhanced Validation
-Smart validation with actionable suggestions:
+**Example:**
 ```bash
-voodocs context validate --check-invariants
+voodocs validate ./src --recursive --strict
 ```
-Provides completeness checks, quality suggestions, and consistency validation.
 
-## Why Voodocs?
+### `voodocs fix`
 
-- **AI-First Workflow**: Designed for modern AI-assisted development. Your AI documents as it codes.
-- **Single Source of Truth**: Code annotations drive docs, tests, and specs - always in sync.
-- **Massive Time Savings**: Eliminate manual documentation work entirely.
-- **Higher Code Quality**: Formal specifications lead to more robust and reliable code.
-- **Precision**: Mathematical notation is unambiguous - no more vague documentation.
-- **Verification**: Automatically check that code respects documented invariants (v0.2.0)
-- **Visualization**: Generate architecture diagrams from context (v0.2.0)
+Automatically fix validation errors.
 
-## Example Annotation
+```bash
+voodocs fix <path> [options]
 
-```typescript
-/**@voodocs
-preconditions: [
-    "user must be authenticated",
-    "user must have 'admin' role",
-    "Database connection must be active"
-]
-postconditions: [
-    "returns true ⇔ user is admin ∧ MFA enabled",
-    "returns false ⇔ user lacks admin role ∨ MFA disabled ∨ any error",
-    "∀ errors: function returns false (fail-safe behavior)"
-]
-security_implications: [
-    "CRITICAL: Gates all admin functionality",
-    "Fail-safe design: errors → deny access"
-]
-complexity: "O(1) - Single database query with indexed lookup"
-*/
-export async function isAdmin(userId: string): Promise<boolean> {
-  // implementation
+Options:
+  -r, --recursive          Process directories recursively
+  -d, --dry-run            Show what would be fixed without making changes
+  -b, --backup             Create backup files before fixing
+```
+
+**Example:**
+```bash
+voodocs fix ./src --recursive --backup
+```
+
+### `voodocs generate`
+
+Generate documentation from annotations.
+
+```bash
+voodocs generate <input> <output> [options]
+
+Options:
+  -r, --recursive          Process directories recursively
+  -f, --format <format>    Output format: markdown, html (default: markdown)
+  -v, --validate           Validate annotations before generating
+  --include-toc            Include table of contents
+```
+
+**Example:**
+```bash
+voodocs generate ./src ./docs --recursive --validate
+```
+
+### `voodocs benchmark`
+
+Run performance benchmarks to validate complexity claims.
+
+```bash
+voodocs benchmark <path> [options]
+
+Options:
+  -r, --recursive          Process directories recursively
+  -f, --format <format>    Output format: text, json, html (default: text)
+  --iterations <n>         Number of benchmark iterations (default: 100)
+```
+
+**Example:**
+```bash
+voodocs benchmark ./src --recursive --format json
+```
+
+---
+
+## Annotation Fields
+
+### Module-Level Annotations
+
+| Field | Symbol | Description |
+|-------|--------|-------------|
+| `module_purpose` | `⊢` | Concise statement of the module's responsibility |
+| `dependencies` | `∂` | List of critical internal or external dependencies |
+| `assumptions` | `⚠` | Key assumptions about environment or inputs |
+| `invariants` | `⊨` | Properties that remain unchanged |
+| `security_model` | `🔒` | Security considerations |
+| `performance_model` | `⚡` | Performance characteristics |
+
+### Function/Interface-Level Annotations
+
+| Field | Symbol | Description |
+|-------|--------|-------------|
+| `preconditions` | `⊳` | Conditions that must be true before execution |
+| `postconditions` | `⊲` | Conditions that will be true after execution |
+| `invariants` | `⊨` | Properties that remain unchanged |
+| `side_effects` | `⚡` | Observable effects outside the return value |
+| `security_implications` | `🔒` | Security-related considerations |
+| `complexity` | `⚡` | Computational complexity (e.g., O(n)) |
+
+---
+
+## Symbolic Format Reference
+
+### Logic Symbols
+
+| Symbol | Meaning | Example |
+|--------|---------|---------|
+| `∧` | and | `authenticated ∧ hasPermission` |
+| `∨` | or | `isAdmin ∨ isOwner` |
+| `¬` | not | `¬isGuest` |
+| `∈` | in | `userId ∈ validIds` |
+| `∃` | exists | `∃ user: user.id = userId` |
+| `∀` | for all | `∀ item: item.price > 0` |
+| `⇒` | implies | `isLoggedIn ⇒ hasSession` |
+| `⇔` | if and only if | `isActive ⇔ lastLogin < 24h` |
+
+---
+
+## CI/CD Integration
+
+Use VooDocs in your continuous integration pipeline:
+
+```yaml
+# .github/workflows/validate-docs.yml
+name: Validate Documentation
+
+on: [push, pull_request]
+
+jobs:
+  validate:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v2
+      
+      - name: Setup Node.js
+        uses: actions/setup-node@v2
+        with:
+          node-version: '18'
+      
+      - name: Install VooDocs
+        run: npm install -g @voodocs/cli
+      
+      - name: Validate Annotations
+        run: voodocs validate ./src --recursive --strict
+```
+
+---
+
+## Configuration
+
+Create a `.voodocs.json` file in your project root:
+
+```json
+{
+  "version": "1.0",
+  "format": "voodocs",
+  "validation": {
+    "semantic": true,
+    "performance": true,
+    "strict": false
+  },
+  "generation": {
+    "output_format": "markdown",
+    "include_toc": true,
+    "include_examples": true
+  },
+  "exclude": [
+    "node_modules",
+    "dist",
+    "build",
+    "__pycache__",
+    ".git"
+  ]
 }
 ```
 
-## Licensing
+---
 
-Voodocs is a commercial product. A valid API key is required to use the software. We offer:
+## Documentation
 
-- **Free Tier**: For hobbyists and students
-- **Pro Plan**: For professional developers
-- **Enterprise**: For teams and organizations
+- **User Guide**: [docs/darkarts/USER_GUIDE.md](docs/darkarts/USER_GUIDE.md)
+- **API Reference**: [docs/darkarts/API_REFERENCE.md](docs/darkarts/API_REFERENCE.md)
+- **Tutorials**: [docs/darkarts/TUTORIALS.md](docs/darkarts/TUTORIALS.md)
+- **Symbolic Format Guide**: [docs/darkarts/DARKARTS_SYMBOLIC_GUIDE.md](docs/darkarts/DARKARTS_SYMBOLIC_GUIDE.md)
 
-For more details, see our [Pricing Page](https://voodocs.com/pricing).
+---
 
 ## Support
 
-Need help? Visit our [Support Center](https://voodocs.com/support) or email us at [support@voodocs.com](mailto:support@voodocs.com).
+- **Issues**: [GitHub Issues](https://github.com/3vilEnterprises/vooodooo-magic/issues)
+- **Email**: contact@3vil.enterprises
+- **Website**: [voodocs.com](https://voodocs.com)
+
+---
+
+## License
+
+Commercial - See [LICENSE](LICENSE) for details.
+
+---
+
+## What's New in v1.0.1
+
+### Bug Fixes
+- ✅ Fixed CLI entry point (ModuleNotFoundError)
+- ✅ Added missing `init` command
+- ✅ Fixed annotation parsing for TypeScript files
+- ✅ Standardized terminology (@voodocs and @darkarts both supported)
+
+### Improvements
+- ✅ Better error messages
+- ✅ Improved documentation
+- ✅ Enhanced validation accuracy
 
 ---
 
-**DarkArt Intelligence** 🚀
+**VooDocs - The only documentation tool that validates your annotations and guarantees accuracy.**

package/lib/cli/__init__.py

@@ -16,7 +16,7 @@ This module provides the command-line interface for VooDocs.
 import click
 from typing import Optional
 
-__version__ = "1.0.0"
+__version__ = "1.0.2"
 
 
 @click.group()
@@ -26,18 +26,22 @@ def cli(ctx):
     """
     VooDocs - AI-Native Documentation Generator with Validation
     
-    Generate and validate @darkarts annotations in your codebase.
+    Generate and validate @voodocs and @darkarts annotations in your codebase.
+    
+    Supports both natural language (@voodocs) and symbolic (@darkarts) formats.
     """
     ctx.ensure_object(dict)
 
 
 # Import subcommands
+from .init import init
 from .validate import validate
 from .generate import generate
 from .benchmark import benchmark
 from .fix import fix
 
 # Register commands
+cli.add_command(init)
 cli.add_command(validate)
 cli.add_command(generate)
 cli.add_command(benchmark)