@voodocs/cli 2.1.3 → 2.2.1

package/lib/darkarts/documentation/consolidator.py

@@ -0,0 +1,303 @@
+"""
+Documentation Consolidator
+
+Generates human-readable consolidated documentation from @darkarts annotations.
+Organizes content by multiple categorization schemes for better readability.
+"""
+
+from typing import Dict, List, Set, Any
+from pathlib import Path
+from dataclasses import dataclass, field
+
+
+@dataclass
+class DocumentedItem:
+    """Represents a single documented code item."""
+    name: str
+    file_path: str
+    item_type: str  # component, function, module, api, etc.
+    content: str
+    annotations: Dict[str, Any] = field(default_factory=dict)
+    
+    # Categorization metadata
+    domains: Set[str] = field(default_factory=set)  # auth, billing, admin, etc.
+    concerns: Set[str] = field(default_factory=set)  # business_logic, security, etc.
+    layers: Set[str] = field(default_factory=set)  # frontend, backend, database
+    
+
+class DocumentationConsolidator:
+    """Consolidates scattered documentation into organized, readable documents."""
+    
+    def __init__(self, project_name: str = "Project"):
+        self.project_name = project_name
+        self.items: List[DocumentedItem] = []
+        
+    def add_item(self, item: DocumentedItem):
+        """Add a documented item to the consolidator."""
+        self.items.append(item)
+        
+    def categorize_items(self):
+        """Automatically categorize all items."""
+        for item in self.items:
+            self._categorize_by_type(item)
+            self._categorize_by_path(item)
+            self._categorize_by_annotations(item)
+            
+    def _categorize_by_type(self, item: DocumentedItem):
+        """Categorize by code type."""
+        # Determine layer from file extension and path
+        path_lower = item.file_path.lower()
+        
+        if any(x in path_lower for x in ['component', 'ui', 'view', '.tsx', '.jsx']):
+            item.layers.add('frontend')
+        if any(x in path_lower for x in ['api', 'server', 'backend', 'route']):
+            item.layers.add('backend')
+        if any(x in path_lower for x in ['schema', 'model', 'database', 'db']):
+            item.layers.add('database')
+            
+    def _categorize_by_path(self, item: DocumentedItem):
+        """Categorize by file path patterns."""
+        path_parts = Path(item.file_path).parts
+        
+        # Extract domain from path
+        domain_keywords = {
+            'auth': 'authentication',
+            'billing': 'billing',
+            'subscription': 'billing',
+            'admin': 'admin',
+            'user': 'user_management',
+            'account': 'user_management',
+            'api': 'api',
+            'payment': 'billing',
+            'analytics': 'analytics',
+            'marketplace': 'marketplace',
+        }
+        
+        for part in path_parts:
+            part_lower = part.lower()
+            for keyword, domain in domain_keywords.items():
+                if keyword in part_lower:
+                    item.domains.add(domain)
+                    
+    def _categorize_by_annotations(self, item: DocumentedItem):
+        """Categorize by @darkarts annotation content."""
+        annotations = item.annotations
+        
+        # Check for security concerns
+        if 'security' in annotations or '🔒' in str(annotations):
+            item.concerns.add('security')
+            
+        # Check for business logic
+        if 'business_logic' in annotations:
+            item.concerns.add('business_logic')
+            
+        # Check for performance
+        if 'complexity' in annotations or '⚡' in str(annotations):
+            item.concerns.add('performance')
+            
+        # Check for integrations
+        dependencies = annotations.get('dependencies', [])
+        if any(dep for dep in dependencies if not dep.startswith('.')):
+            item.concerns.add('integrations')
+            
+    def generate_by_type(self) -> Dict[str, str]:
+        """Generate documentation organized by type."""
+        categories = {
+            'component': [],
+            'function': [],
+            'module': [],
+            'api': [],
+            'data': [],
+        }
+        
+        for item in self.items:
+            item_type = item.item_type.lower()
+            if item_type in categories:
+                categories[item_type].append(item)
+            else:
+                categories.setdefault('other', []).append(item)
+                
+        docs = {}
+        for category, items in categories.items():
+            if items:
+                docs[f'by-type/{category.upper()}.md'] = self._generate_category_doc(
+                    f"{category.title()}s",
+                    items,
+                    f"All {category}s in the project"
+                )
+        return docs
+        
+    def generate_by_domain(self) -> Dict[str, str]:
+        """Generate documentation organized by domain."""
+        domain_items = {}
+        
+        for item in self.items:
+            for domain in item.domains:
+                domain_items.setdefault(domain, []).append(item)
+                
+        docs = {}
+        for domain, items in domain_items.items():
+            docs[f'by-domain/{domain.upper()}.md'] = self._generate_category_doc(
+                domain.replace('_', ' ').title(),
+                items,
+                f"All code related to {domain.replace('_', ' ')}"
+            )
+        return docs
+        
+    def generate_by_concern(self) -> Dict[str, str]:
+        """Generate documentation organized by concern."""
+        concern_items = {}
+        
+        for item in self.items:
+            for concern in item.concerns:
+                concern_items.setdefault(concern, []).append(item)
+                
+        docs = {}
+        for concern, items in concern_items.items():
+            docs[f'by-concern/{concern.upper()}.md'] = self._generate_category_doc(
+                concern.replace('_', ' ').title(),
+                items,
+                f"Code with {concern.replace('_', ' ')} considerations"
+            )
+        return docs
+        
+    def generate_by_layer(self) -> Dict[str, str]:
+        """Generate documentation organized by layer."""
+        layer_items = {}
+        
+        for item in self.items:
+            for layer in item.layers:
+                layer_items.setdefault(layer, []).append(item)
+                
+        docs = {}
+        for layer, items in layer_items.items():
+            docs[f'by-layer/{layer.upper()}.md'] = self._generate_category_doc(
+                f"{layer.title()} Layer",
+                items,
+                f"All {layer} code"
+            )
+        return docs
+        
+    def generate_master_readme(self, all_docs: Dict[str, str]) -> str:
+        """Generate master README with overview and navigation."""
+        sections = []
+        
+        # Header
+        sections.append(f"# {self.project_name} Documentation\n")
+        sections.append(f"*Generated by Voodocs from @darkarts annotations*\n")
+        sections.append(f"**Total Items Documented:** {len(self.items)}\n")
+        sections.append("---\n")
+        
+        # Quick Navigation
+        sections.append("## 📚 Documentation Categories\n")
+        sections.append("### By Type")
+        for doc_path in sorted(all_docs.keys()):
+            if doc_path.startswith('by-type/'):
+                name = doc_path.replace('by-type/', '').replace('.md', '')
+                sections.append(f"- [{name}]({doc_path})")
+        sections.append("")
+        
+        sections.append("### By Domain")
+        for doc_path in sorted(all_docs.keys()):
+            if doc_path.startswith('by-domain/'):
+                name = doc_path.replace('by-domain/', '').replace('.md', '')
+                sections.append(f"- [{name}]({doc_path})")
+        sections.append("")
+        
+        sections.append("### By Concern")
+        for doc_path in sorted(all_docs.keys()):
+            if doc_path.startswith('by-concern/'):
+                name = doc_path.replace('by-concern/', '').replace('.md', '')
+                sections.append(f"- [{name}]({doc_path})")
+        sections.append("")
+        
+        sections.append("### By Layer")
+        for doc_path in sorted(all_docs.keys()):
+            if doc_path.startswith('by-layer/'):
+                name = doc_path.replace('by-layer/', '').replace('.md', '')
+                sections.append(f"- [{name}]({doc_path})")
+        sections.append("")
+        
+        sections.append("---\n")
+        
+        # Statistics
+        sections.append("## 📊 Project Statistics\n")
+        
+        type_counts = {}
+        for item in self.items:
+            type_counts[item.item_type] = type_counts.get(item.item_type, 0) + 1
+        sections.append("### By Type")
+        for item_type, count in sorted(type_counts.items()):
+            sections.append(f"- **{item_type.title()}**: {count}")
+        sections.append("")
+        
+        # Domain distribution
+        domain_counts = {}
+        for item in self.items:
+            for domain in item.domains:
+                domain_counts[domain] = domain_counts.get(domain, 0) + 1
+        if domain_counts:
+            sections.append("### By Domain")
+            for domain, count in sorted(domain_counts.items(), key=lambda x: x[1], reverse=True):
+                sections.append(f"- **{domain.replace('_', ' ').title()}**: {count}")
+            sections.append("")
+        
+        sections.append("---\n")
+        
+        # Index
+        sections.append("## 🔍 Complete Index\n")
+        for item in sorted(self.items, key=lambda x: x.name):
+            sections.append(f"- **{item.name}** ({item.item_type}) - `{item.file_path}`")
+        
+        return "\n".join(sections)
+        
+    def _generate_category_doc(self, title: str, items: List[DocumentedItem], description: str) -> str:
+        """Generate documentation for a specific category."""
+        sections = []
+        
+        sections.append(f"# {title}\n")
+        sections.append(f"*{description}*\n")
+        sections.append(f"**Items in this category:** {len(items)}\n")
+        sections.append("---\n")
+        
+        # Table of contents
+        sections.append("## Table of Contents\n")
+        for item in sorted(items, key=lambda x: x.name):
+            sections.append(f"- [{item.name}](#{item.name.lower().replace(' ', '-')})")
+        sections.append("\n---\n")
+        
+        # Items
+        for item in sorted(items, key=lambda x: x.name):
+            sections.append(f"## {item.name}\n")
+            sections.append(f"**Type:** {item.item_type}  ")
+            sections.append(f"**File:** `{item.file_path}`\n")
+            
+            if item.domains:
+                sections.append(f"**Domains:** {', '.join(sorted(item.domains))}  ")
+            if item.concerns:
+                sections.append(f"**Concerns:** {', '.join(sorted(item.concerns))}  ")
+            if item.layers:
+                sections.append(f"**Layers:** {', '.join(sorted(item.layers))}  ")
+            sections.append("")
+            
+            sections.append(item.content)
+            sections.append("\n---\n")
+            
+        return "\n".join(sections)
+        
+    def generate_all(self) -> Dict[str, str]:
+        """Generate all consolidated documentation."""
+        # Categorize all items first
+        self.categorize_items()
+        
+        # Generate all category docs
+        all_docs = {}
+        all_docs.update(self.generate_by_type())
+        all_docs.update(self.generate_by_domain())
+        all_docs.update(self.generate_by_concern())
+        all_docs.update(self.generate_by_layer())
+        
+        # Generate master README
+        all_docs['README.md'] = self.generate_master_readme(all_docs)
+        
+        return all_docs

package/lib/darkarts/exceptions.py

@@ -6,10 +6,10 @@
 🔒{pure-exceptions,¬io,¬side-effects,¬exec}
 ⚡{O(1):exception-creation}
 
-VooDocs Custom Exceptions
+Voodocs Custom Exceptions
 
 Structured exception hierarchy for error handling with:
-- Base exception (VooDocsError for all VooDocs errors)
+- Base exception (VooDocsError for all Voodocs errors)
 - Parser errors (ParserError, ParserNotBuiltError, AnnotationError)
 - Validation errors (InvalidAnnotationError, ValidationError)
 - Generator errors (GeneratorError)
@@ -20,7 +20,7 @@ Structured exception hierarchy for error handling with:
 
 
 class VooDocsError(Exception):
-    """Base exception for all VooDocs errors."""
+    """Base exception for all Voodocs errors."""
     pass
 
 

package/lib/darkarts/plugins/voodocs/ai_native_plugin.py

@@ -6,7 +6,7 @@
 🔒{read-only:source,write:docs-output,¬network,¬arbitrary-exec}
 ⚡{O(n)|n=source-lines,ast-parsing:linear}
 
-AI-Native VooDocs Plugin for DarkArts
+AI-Native Voodocs Plugin for DarkArts
 
 Enhanced documentation plugin supporting:
 - @voodocs annotation parsing (AI-native documentation)

package/lib/darkarts/plugins/voodocs/annotation_validator.py

@@ -6,7 +6,7 @@
 🔒{read-only:annotations,¬file-io,¬network,¬exec}
 ⚡{O(n)|n=annotations,validation:linear}
 
-VooDocs Annotation Validator
+Voodocs Annotation Validator
 
 Quality assurance for @voodocs annotations with:
 - Syntax validation (correct format and structure)
@@ -40,7 +40,7 @@ class ValidationIssue:
 
 
 class AnnotationValidator:
-    """Validates VooDocs annotations."""
+    """Validates Voodocs annotations."""
     
     VALID_FIELDS = {
         "module_purpose", "dependencies", "assumptions", "security_model",

package/lib/darkarts/plugins/voodocs/documentation_generator.py

@@ -6,7 +6,7 @@
 🔒{read-only:annotations,write:docs-dir,¬network,¬exec}
 ⚡{O(n)|n=annotations,translation:linear}
 
-VooDocs Documentation Generator
+Voodocs Documentation Generator
 
 Translates @voodocs annotations (DarkArts language) into human-readable documentation with:
 - Mathematical symbol translation (∀, ∃, ∈, → natural language)
@@ -588,8 +588,8 @@ class DocumentationGenerator:
             color = "green" if coverage >= 80 else "yellow" if coverage >= 50 else "red"
             badges.append(f"![Documentation Coverage](https://img.shields.io/badge/docs-{coverage}%25-{color})")
         
-        # VooDocs badge
-        badges.append("![VooDocs](https://img.shields.io/badge/documented_with-VooDocs-purple)")
+        # Voodocs badge
+        badges.append("![Voodocs](https://img.shields.io/badge/documented_with-Voodocs-purple)")
         
         # Language badge
         lang = parsed.language.value if hasattr(parsed.language, 'value') else str(parsed.language)

package/lib/darkarts/plugins/voodocs/html_exporter.py

@@ -6,7 +6,7 @@
 🔒{read:markdown-files,write:html-files,¬network,¬exec}
 ⚡{O(n)|n=markdown-length,conversion:linear}
 
-VooDocs HTML Exporter
+Voodocs HTML Exporter
 
 Markdown to HTML conversion with styling:
 - Markdown parsing (markdown library or fallback)
@@ -102,7 +102,7 @@ class HTMLExporter:
 <head>
     <meta charset="UTF-8">
     <meta name="viewport" content="width=device-width, initial-scale=1.0">
-    <title>{title} - VooDocs Documentation</title>
+    <title>{title} - Voodocs Documentation</title>
     <style>
 {self.css}
     </style>
@@ -111,13 +111,13 @@ class HTMLExporter:
     <div class="container">
         <header>
             <h1 class="voodocs-title">{title}</h1>
-            <p class="voodocs-subtitle">Generated by VooDocs</p>
+            <p class="voodocs-subtitle">Generated by Voodocs</p>
         </header>
         <main>
 {content}
         </main>
         <footer>
-            <p>Documentation generated with <a href="https://voodocs.dev">VooDocs</a></p>
+            <p>Documentation generated with <a href="https://voodocs.dev">Voodocs</a></p>
         </footer>
     </div>
 </body>

package/lib/darkarts/plugins/voodocs/instruction_generator.py

@@ -6,7 +6,7 @@
 🔒{write:config-files}
 ⚡{O(n):instruction-generation|template-based}
 
-VooDocs AI Instruction Generator
+Voodocs AI Instruction Generator
 
 Generates instruction files that teach AI coding assistants (Cursor, Claude Code, etc.)
 how to use @voodocs annotations while writing code.
@@ -18,7 +18,7 @@ import json
 
 
 class InstructionGenerator:
-    """Generates AI assistant instruction files for VooDocs."""
+    """Generates AI assistant instruction files for Voodocs."""
     
     # Supported AI assistants
     ASSISTANTS = {
@@ -126,10 +126,10 @@ class InstructionGenerator:
     
     def _generate_header(self) -> str:
         """Generate instruction header."""
-        return f"""# VooDocs Instructions for {self.assistant_info['name']}
+        return f"""# Voodocs Instructions for {self.assistant_info['name']}
 
 **Project**: {self.project_name}  
-**Generated**: Automatically by VooDocs  
+**Generated**: Automatically by Voodocs  
 **Purpose**: Guide AI assistants to document code using @voodocs annotations
 
 ---"""
@@ -138,7 +138,7 @@ class InstructionGenerator:
         """Generate overview section."""
         return """## Overview
 
-VooDocs is an AI-native documentation system that allows you to document code in **DarkArts language** - a mathematical and logical notation that AI naturally understands. Your annotations will be automatically translated into human-readable documentation, property-based tests, and API specifications.
+Voodocs is an AI-native documentation system that allows you to document code in **DarkArts language** - a mathematical and logical notation that AI naturally understands. Your annotations will be automatically translated into human-readable documentation, property-based tests, and API specifications.
 
 **Key Benefits:**
 - Document in AI's native language (mathematical notation)
@@ -154,7 +154,7 @@ As an AI coding assistant, you should add `@voodocs` annotations to **every sign
         """Generate core principles section."""
         return """## Core Principles
 
-When writing code with VooDocs annotations, follow these principles:
+When writing code with Voodocs annotations, follow these principles:
 
 1. **Annotate as you code** - Add `@voodocs` annotations immediately when creating functions/classes
 2. **Be precise** - Use mathematical notation for exact specifications
@@ -310,7 +310,7 @@ DarkArts is a mathematical notation language for precise specifications. Use the
 | `ℤ` | Integers (..., -1, 0, 1, ...) | `x ∈ ℤ` |
 | `ℝ` | Real numbers | `x ∈ ℝ` |
 
-**Tip**: You can use plain English too! VooDocs understands both mathematical notation and natural language. Mix them for clarity."""
+**Tip**: You can use plain English too! Voodocs understands both mathematical notation and natural language. Mix them for clarity."""
     
     def _generate_examples(self, language: str) -> str:
         """Generate example annotations."""
@@ -554,7 +554,7 @@ complexity: "O(1)"
 \"\"\"
 ```
 
-VooDocs generates:
+Voodocs generates:
 
 ```python
 # Generated test
@@ -611,7 +611,7 @@ complexity: "O(n log n)"
 
 **Also Good:**
 ```python
-complexity: "O(n)"  # VooDocs infers space as O(1)
+complexity: "O(n)"  # Voodocs infers space as O(1)
 ```
 
 ### 4. Document Security Implications
@@ -678,7 +678,7 @@ side_effects: ["Does stuff"]  # Too vague
 
 By documenting in DarkArts language, you're not just writing comments - you're creating a **formal specification** that generates tests, documentation, and API specs automatically.
 
-**Generated by VooDocs** - AI-native documentation for modern development."""
+**Generated by Voodocs** - AI-native documentation for modern development."""
     
     def detect_assistant(self) -> Optional[str]:
         """

package/lib/darkarts/plugins/voodocs/pdf_exporter.py

@@ -6,7 +6,7 @@
 🔒{read:markdown-files,write:pdf-files,¬network,¬exec}
 ⚡{O(n)|n=markdown-length,pdf-rendering:depends-on-lib}
 
-VooDocs PDF Exporter
+Voodocs PDF Exporter
 
 Markdown to PDF conversion with print-ready formatting:
 - WeasyPrint support (HTML → PDF with CSS)

package/lib/darkarts/plugins/voodocs/test_generator.py

@@ -6,7 +6,7 @@
 🔒{read-only:annotations,write:test-files,¬network,¬exec}
 ⚡{O(n)|n=functions,codegen:linear}
 
-VooDocs Test Generator
+Voodocs Test Generator
 
 Automatic test generation from @voodocs annotations with:
 - Precondition tests (validate inputs match declared constraints)

package/lib/darkarts/telemetry.py

@@ -6,7 +6,7 @@
 🔒{⚠️NETWORK:supabase-api,write:config-dir,¬sensitive-data,anonymous-only}
 ⚡{O(1):event-creation,network:async-non-blocking}
 
-VooDocs Telemetry Client
+Voodocs Telemetry Client
 
 Privacy-respecting anonymous usage analytics with:
 - Anonymous session IDs (UUID-based, no PII)
@@ -32,11 +32,11 @@ import urllib.error
 SUPABASE_URL = os.getenv("VOODOCS_SUPABASE_URL", "https://sjatkayudkbkmipubhfy.supabase.co")
 SUPABASE_ANON_KEY = os.getenv("VOODOCS_SUPABASE_ANON_KEY", "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiJzdXBhYmFzZSIsInJlZiI6InNqYXRrYXl1ZGtia21pcHViaGZ5Iiwicm9sZSI6ImFub24iLCJpYXQiOjE3NjYxNjE0MTMsImV4cCI6MjA4MTczNzQxM30.Wj3dbokjKPsmWTgbPw77aPnCoZCsE5hrFfIH-R_ErzI")
 
-# VooDocs version
+# Voodocs version
 VERSION = "0.1.2"
 
 class TelemetryClient:
-    """Anonymous telemetry client for VooDocs CLI."""
+    """Anonymous telemetry client for Voodocs CLI."""
     
     def __init__(self):
         self.session_id = self._get_or_create_session_id()
@@ -90,9 +90,9 @@ class TelemetryClient:
         
         if not notice_file.exists():
             print("\n" + "="*70)
-            print("📊 VooDocs Telemetry")
+            print("📊 Voodocs Telemetry")
             print("="*70)
-            print("VooDocs collects anonymous usage data to improve the product.")
+            print("Voodocs collects anonymous usage data to improve the product.")
             print("No personal information is collected.")
             print()
             print("To disable telemetry:")

package/lib/darkarts/validation/README.md

@@ -7,14 +7,15 @@ This module provides validation tools for @darkarts annotations.
 ## Overview
 
 The validation module ensures that @darkarts annotations are accurate and up-to-date by:
+
 - **Semantic Validation**: Verifying dependencies match actual imports
-- **Performance Validation**: Checking complexity claims match code structure  
+- **Performance Validation**: Checking complexity claims match code structure
 - **Benchmarking**: Measuring actual performance to validate claims
 - **Auto-fix**: Automatically correcting validation issues
 
 ## Installation
 
-The validation module is part of the VooDocs package:
+The validation module is part of the Voodocs package:
 
 ```bash
 pip install voodocs
@@ -117,11 +118,13 @@ validation/
 ## Next Steps
 
 **Phase 2**: CLI Integration (Week 2)
+
 - Integrate into `voodocs` CLI
 - Add `voodocs validate` command
 - Add `--validate` flag to `voodocs generate`
 
 **Phase 3**: Advanced Features (Week 3)
+
 - Watch mode integration
 - Configuration file support
 - HTML/JSON reports
@@ -144,4 +147,4 @@ See `../../docs/darkarts/CODE_REVIEW_PROCESS.md` for contribution guidelines.
 
 ## License
 
-Part of VooDocs - see repository root for license.
+Part of Voodocs - see repository root for license.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@voodocs/cli",
-  "version": "2.1.3",
+  "version": "2.2.1",
   "description": "AI-Native Symbolic Documentation System - The world's first documentation tool using mathematical notation with semantic validation",
   "main": "voodocs_cli.py",
   "bin": {
@@ -60,6 +60,7 @@
     "lib/darkarts/core/",
     "lib/darkarts/validation/",
     "lib/darkarts/instructions/",
+    "lib/darkarts/documentation/",
     "lib/darkarts/exceptions.py",
     "lib/darkarts/telemetry.py",
     "lib/darkarts/parsers/typescript/dist/",

package/requirements.txt

@@ -1,4 +1,4 @@
-# VooDocs Python Dependencies
+# Voodocs Python Dependencies
 # Python 3.7+ required
 # Install with: pip3 install -r requirements.txt
 
@@ -9,5 +9,5 @@ PyYAML>=6.0.0
 # pytest>=7.0.0  # For running unit tests
 # hypothesis>=6.0.0  # For property-based testing (used in generated tests)
 
-# Note: VooDocs core uses only Python standard library.
+# Note: Voodocs core uses only Python standard library.
 # PyYAML is the only required external dependency for API spec generation.