@voodocs/cli 1.0.6 → 2.0.0

package/CHANGELOG.md

@@ -1,3 +1,81 @@
+## [2.0.0] - 2024-12-21
+
+### 🚨 BREAKING CHANGES
+
+**VooDocs is now DarkArts-only!**
+
+This major version removes support for natural language `@voodocs` annotations and focuses exclusively on the symbolic `@darkarts` format.
+
+### Removed
+- **Natural language format (`@voodocs`)** - No longer supported
+- Parser no longer recognizes `@voodocs` tags
+- Generator no longer processes natural language annotations
+- Init wizard no longer offers format choice
+
+### Changed
+- **DarkArts symbolic format is now the only format**
+- All annotations must use `@darkarts` tag
+- All annotations must use symbolic notation (⊢, ∂, ⚠, ⊳, ⊲, ⊨, ⚡, 🔒)
+- Init wizard automatically uses DarkArts format
+- Example files use symbolic format only
+
+### Why This Change?
+
+1. **Clearer brand identity** - "The symbolic documentation language"
+2. **Reduced maintenance** - One parser, one validator, one format
+3. **Stronger patent position** - Unique innovation (VDA-004)
+4. **Better AI optimization** - Symbols are more token-efficient
+5. **Simplified user experience** - No format confusion
+
+### Migration Guide
+
+VooDocs v2.0.0 only supports `@darkarts` symbolic format. If you have existing `@voodocs` annotations, you'll need to manually update them:
+
+**Before (v1.x):**
+```typescript
+/**@voodocs
+module_purpose: "User service"
+dependencies: ["database"]
+*/
+```
+
+**After (v2.0):**
+```typescript
+/**@darkarts
+⊢{User service}
+∂{database}
+*/
+```
+
+### Benefits
+
+- ✅ **Concise** - Fewer characters, more meaning
+- ✅ **Precise** - Mathematical notation eliminates ambiguity
+- ✅ **AI-Optimized** - Fewer tokens = lower costs
+- ✅ **Language-Independent** - Symbols transcend language barriers
+- ✅ **Unique** - Patent-pending innovation
+
+## [1.0.7] - 2024-12-21
+
+### Added
+- **Enhanced Init Wizard**: Complete interactive setup experience
+  - Auto-detects project details (name, version, repository)
+  - Generates AI instructions automatically
+  - Configures privacy settings (.gitignore)
+  - Creates example annotated files
+  - **Rerunnable for upgrades**: Detects existing config and adds missing features
+  - Smart defaults for non-interactive mode
+  - Beautiful CLI interface with status icons and summaries
+
+### Changed
+- `voodocs init` now includes full wizard experience
+- Wizard supports both fresh install and upgrade scenarios
+- Auto-detection of AI environment (Cursor, Claude)
+
+### Fixed
+- Init command now properly integrates with instruct command
+- Upgrade path for users installing new versions
+
 ## v1.0.6 (2024-12-21)
 
 ### 🐛 Bug Fix: Missing Instructions Directory in npm Package

package/README.md

@@ -1,18 +1,19 @@
-# VooDocs - AI-Native Documentation with Validation
+# VooDocs - AI-Native Symbolic Documentation
 
 [![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 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.
+**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.
 
 ## What Makes VooDocs Unique?
 
+✅ **Symbolic Language** - Mathematical Unicode symbols (⊢, ∂, ⚠, ⊳, ⊲, ⊨, ⚡, 🔒) for concise, precise documentation  
 ✅ **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`)  
+✅ **AI-Optimized** - Token-efficient format designed for LLM consumption  
 ✅ **CI/CD Ready** - Strict mode with exit codes for continuous integration
 
 ---
@@ -29,348 +30,277 @@ npm install -g @voodocs/cli
 
 ### 2. Initialize Your Project
 
-Navigate to your project directory and initialize VooDocs:
+Navigate to your project directory and run the interactive wizard:
 
 ```bash
 voodocs init
 ```
 
-This creates a `.voodocs.json` configuration file and example annotated files.
+This will:
+- Create `.voodocs.json` configuration
+- Generate AI instructions for your coding assistant
+- Create example annotated files
+- Configure privacy settings
 
-### 3. Add Annotations to Your Code
+### 3. Add DarkArts Annotations to Your Code
 
-#### Natural Language Format (`@voodocs`)
-
-```typescript
-/**@voodocs
-module_purpose: "User authentication service with JWT token generation"
-dependencies: [
-  "bcrypt: Password hashing",
-  "jsonwebtoken: JWT token generation"
-]
-assumptions: [
-  "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"
-]
-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/JavaScript
 
 ```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
-}
+∂{bcrypt, jsonwebtoken}
+⚠{Users must be stored ∈ database, Tokens expire after 24h}
 */
 
 /**@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
-}
+⊳{userId must be a valid UUID, password must be ≥8 characters}
+⊲{Returns JWT token ∨ null, Token contains {userId, email, role}}
+⊨{Does ¬ modify database, Password is ¬ logged}
+⚡{O(1)}
+🔒{Password hashed with bcrypt, Token signed with secret}
 */
-export async function login(email: string, password: string): Promise<string> {
-  // ...
+export async function authenticateUser(
+  userId: string,
+  password: string
+): Promise<string | null> {
+  // Implementation
 }
 ```
 
-### 4. Validate Your Annotations
+#### Python
 
-Run validation to ensure your documentation is accurate:
-
-```bash
-voodocs validate ./src --recursive
+```python
+"""@darkarts
+⊢{User authentication service with JWT token generation}
+∂{bcrypt, jwt}
+⚠{Users must be stored ∈ database, Tokens expire after 24h}
+"""
+
+"""@darkarts
+⊳{user_id must be a valid UUID, password must be ≥8 characters}
+⊲{Returns JWT token ∨ None, Token contains {user_id, email, role}}
+⊨{Does ¬ modify database, Password is ¬ logged}
+⚡{O(1)}
+🔒{Password hashed with bcrypt, Token signed with secret}
+"""
+def authenticate_user(user_id: str, password: str) -> Optional[str]:
+    # Implementation
+    pass
 ```
 
-This checks:
-- **Semantic validation**: Dependencies match imports
-- **Performance validation**: Complexity claims are accurate
-- **Consistency**: All required fields are present
+---
 
-### 5. Auto-Fix Issues
+## Symbolic Format Reference
 
-Automatically fix common errors:
+### Module-Level Annotations
 
-```bash
-voodocs fix ./src --recursive
-```
+| Symbol | Field | Description | Example |
+|--------|-------|-------------|---------|
+| ⊢ | module_purpose | What this module does | `⊢{User authentication service}` |
+| ∂ | dependencies | External dependencies | `∂{bcrypt, jsonwebtoken}` |
+| ⚠ | assumptions | Preconditions for module | `⚠{Database is initialized}` |
 
-### 6. Generate Documentation
+### Function-Level Annotations
 
-Create beautiful documentation from your annotations:
+| Symbol | Field | Description | Example |
+|--------|-------|-------------|---------|
+| ⊳ | preconditions | Input requirements | `⊳{userId must be a valid UUID}` |
+| ⊲ | postconditions | Output guarantees | `⊲{Returns user object ∨ null}` |
+| ⊨ | invariants | Conditions that always hold | `⊨{Does ¬ modify database}` |
+| ⚡ | complexity | Time/space complexity | `⚡{O(n log n)}` |
+| 🔒 | security | Security implications | `🔒{Password hashed with bcrypt}` |
 
-```bash
-voodocs generate ./src ./docs --recursive
-```
+### Logic Operators
+
+| Symbol | Meaning | Example |
+|--------|---------|---------|
+| ∧ | and | `x > 0 ∧ y > 0` |
+| ∨ | or | `Returns user ∨ null` |
+| ¬ | not | `¬ empty string` |
+| ∈ | in/element of | `user ∈ database` |
+| ∃ | exists | `∃ user: user.id = userId` |
+| ∀ | for all | `∀ item ∈ array: item ≠ null` |
+| ⇒ | implies | `x > 0 ⇒ result > 0` |
+| ⇔ | if and only if | `valid ⇔ checksum matches` |
 
 ---
 
-## Core Commands
+## Commands
 
 ### `voodocs init`
 
-Initialize a new project with VooDocs configuration and example files.
+Initialize VooDocs in your project with an interactive wizard:
 
 ```bash
-voodocs init                    # Initialize with @voodocs format
-voodocs init --format darkarts  # Initialize with symbolic @darkarts format
-voodocs init --config-only      # Only create config file
+voodocs init              # Interactive setup
+voodocs init --upgrade    # Upgrade existing configuration
+voodocs init --non-interactive  # Use defaults
 ```
 
-### `voodocs validate`
+### `voodocs instruct`
 
-Validate annotations against your code.
+Generate AI instructions for your coding assistant:
 
 ```bash
-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
+voodocs instruct                    # Auto-detect AI environment
+voodocs instruct --ai cursor        # Generate for Cursor
+voodocs instruct --output .cursorrules  # Save to file
+voodocs instruct --list-templates   # List available templates
 ```
 
-**Example:**
+### `voodocs validate`
+
+Validate annotations in your codebase:
+
 ```bash
-voodocs validate ./src --recursive --strict
+voodocs validate ./src              # Validate directory
+voodocs validate ./src -r           # Recursive
+voodocs validate ./src --strict     # Exit with error code on issues
+voodocs validate ./src --json       # JSON output
 ```
 
 ### `voodocs fix`
 
-Automatically fix validation errors.
-
-```bash
-voodocs fix <path> [options]
-
-Options:
-  -r, --recursive          Process directories recursively
-  -d, --dry-run            Show what would be fixed without making changes
-  -b, --backup             Create backup files before fixing
-```
+Automatically fix common annotation errors:
 
-**Example:**
 ```bash
-voodocs fix ./src --recursive --backup
+voodocs fix ./src                   # Fix directory
+voodocs fix ./src -r                # Recursive
+voodocs fix ./src --dry-run         # Preview changes
+voodocs fix ./src --backup          # Create backups
 ```
 
 ### `voodocs generate`
 
-Generate documentation from annotations.
+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 generate ./src ./docs       # Generate docs
+voodocs generate ./src ./docs -r    # Recursive
+voodocs generate ./src ./docs --validate  # Validate first
+voodocs generate ./src ./docs --format json  # JSON output
 ```
 
 ### `voodocs benchmark`
 
-Run performance benchmarks to validate complexity claims.
+Benchmark code and validate performance 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)
+voodocs benchmark ./src             # Benchmark directory
+voodocs benchmark ./src -r          # Recursive
+voodocs benchmark ./src --json      # JSON output
+voodocs benchmark ./src --html      # HTML report
 ```
 
-**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
+## Configuration
 
-### Logic Symbols
+The `.voodocs.json` file configures VooDocs for your project:
 
-| 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` |
+```json
+{
+  "name": "my-project",
+  "version": "1.0.0",
+  "format": "darkarts",
+  "repository": "https://github.com/user/my-project",
+  "private": true,
+  "exclude": [
+    "node_modules",
+    "dist",
+    "build"
+  ]
+}
+```
 
 ---
 
 ## CI/CD Integration
 
-Use VooDocs in your continuous integration pipeline:
+Add VooDocs validation to your CI pipeline:
 
 ```yaml
-# .github/workflows/validate-docs.yml
+# .github/workflows/validate.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
+      - uses: actions/checkout@v3
+      - uses: actions/setup-node@v3
         with:
           node-version: '18'
-      
-      - name: Install VooDocs
-        run: npm install -g @voodocs/cli
-      
-      - name: Validate Annotations
-        run: voodocs validate ./src --recursive --strict
+      - run: npm install -g @voodocs/cli
+      - run: voodocs validate ./src --strict --recursive
 ```
 
 ---
 
-## Configuration
-
-Create a `.voodocs.json` file in your project root:
+## Why Symbolic Format?
 
-```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"
-  ]
-}
+### 1. **Concise**
+```
+⊳{userId ∈ database ∧ password ≥8 chars}
+```
+vs.
+```
+preconditions: [
+  "userId must exist in database",
+  "password must be at least 8 characters"
+]
 ```
 
----
+### 2. **Precise**
+Mathematical notation eliminates ambiguity
 
-## Documentation
+### 3. **AI-Optimized**
+Fewer tokens = lower costs for AI processing
 
-- **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)
+### 4. **Language-Independent**
+Symbols transcend language barriers
+
+### 5. **Unique**
+Patent-pending innovation (VDA-004)
 
 ---
 
-## Support
+## Supported Languages
 
-- **Issues**: [GitHub Issues](https://github.com/3vilEnterprises/vooodooo-magic/issues)
-- **Email**: contact@3vil.enterprises
-- **Website**: [voodocs.com](https://voodocs.com)
+- TypeScript/JavaScript (`.ts`, `.tsx`, `.js`, `.jsx`)
+- Python (`.py`)
+- Java (`.java`)
+- C++ (`.cpp`, `.cc`, `.h`)
+- C# (`.cs`)
+- Go (`.go`)
+- Rust (`.rs`)
+- Solidity (`.sol`)
 
 ---
 
-## License
+## Documentation
 
-Commercial - See [LICENSE](LICENSE) for details.
+- [User Guide](docs/darkarts/USER_GUIDE.md)
+- [API Reference](docs/darkarts/API_REFERENCE.md)
+- [Tutorials](docs/darkarts/TUTORIALS.md)
+- [Symbolic Format Specification](lib/darkarts/annotations/DARKARTS_SYMBOLS.md)
 
 ---
 
-## What's New in v1.0.1
+## Support
+
+- 📧 Email: support@voodocs.com
+- 🌐 Website: https://voodocs.com
+- 📝 Issues: https://github.com/3vilEnterprises/vooodooo-magic/issues
+- 💬 Discord: https://discord.gg/voodocs
 
-### Bug Fixes
-- ✅ Fixed CLI entry point (ModuleNotFoundError)
-- ✅ Added missing `init` command
-- ✅ Fixed annotation parsing for TypeScript files
-- ✅ Standardized terminology (@voodocs and @darkarts both supported)
+---
+
+## License
 
-### Improvements
-- ✅ Better error messages
-- ✅ Improved documentation
-- ✅ Enhanced validation accuracy
+Commercial License - See [LICENSE](LICENSE) for details.
 
 ---
 
-**VooDocs - The only documentation tool that validates your annotations and guarantees accuracy.**
+**VooDocs** - The world's first AI-native symbolic documentation system.

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.6"
+__version__ = "2.0.0"
 
 
 @click.group()
@@ -24,11 +24,11 @@ __version__ = "1.0.6"
 @click.pass_context
 def cli(ctx):
     """
-    VooDocs - AI-Native Documentation Generator with Validation
+    VooDocs - AI-Native Symbolic Documentation System
     
-    Generate and validate @voodocs and @darkarts annotations in your codebase.
+    Generate and validate @darkarts symbolic annotations in your codebase.
     
-    Supports both natural language (@voodocs) and symbolic (@darkarts) formats.
+    Uses mathematical notation (⊢, ∂, ⚠, ⊳, ⊲, ⊨, ⚡, 🔒) for concise, precise documentation.
     """
     ctx.ensure_object(dict)
 

package/lib/cli/generate.py

@@ -222,17 +222,17 @@ def _generate_doc_for_file(file_path: Path, format: str, include_private: bool)
 
 
 def _extract_annotation(content: str) -> str:
-    """Extract @darkarts or @voodocs annotation from file content."""
+    """Extract @darkarts annotation from file content."""
     import re
     
-    # Try Python docstring format first ("""@darkarts or """@voodocs)
-    python_pattern = r'"""@(?:darkarts|voodocs)\s*(.*?)"""'
+    # Try Python docstring format ("""@darkarts)
+    python_pattern = r'"""@darkarts\s*(.*?)"""'
     match = re.search(python_pattern, content, re.DOTALL)
     if match:
         return match.group(0)
     
-    # Try TypeScript/JavaScript block comment format (/**@darkarts or /**@voodocs)
-    js_pattern = r'/\*\*@(?:darkarts|voodocs)\s*(.*?)\*/'
+    # Try TypeScript/JavaScript block comment format (/**@darkarts)
+    js_pattern = r'/\*\*@darkarts\s*(.*?)\*/'
     match = re.search(js_pattern, content, re.DOTALL)
     if match:
         return match.group(0)