@voodocs/cli 0.1.2 → 0.3.0

package/CHANGELOG.md

@@ -1,3 +1,162 @@
+## [0.3.0] - 2025-12-20
+
+### Added
+
+#### AI-Aware Integration System
+
+**Native AI Assistant Integration**
+- Auto-detects existing AI configurations (Claude, Cursor, Copilot, Gemini, Junie)
+- Interactive menu for selecting AI assistant(s) during `voodocs context init`
+- Generates native configuration files for each AI assistant
+- Supports 5+ AI assistants with more coming
+
+**Supported AI Assistants:**
+1. **Claude Code** - Generates `.claude/skills/voodocs-context/SKILL.md` (2,341 chars)
+   - Full skill with YAML frontmatter
+   - On-demand context loading
+   - Executable scripts support
+
+2. **Cursor** - Generates `.cursor/rules/voodocs-context.mdc` (2,560 chars)
+   - Comprehensive rules file
+   - Context system commands
+   - Workflow best practices
+
+3. **GitHub Copilot** - Generates `.github/copilot-instructions.md` (1,981 chars)
+   - Project-specific instructions
+   - Context integration guide
+   - Annotation format examples
+
+4. **Windsurf** - Generates `.windsurfrules` (1,180 chars)
+   - Concise rules format
+   - Essential commands
+   - Quick reference
+
+5. **Cline** - Generates `.clinerules` (806 chars)
+   - Minimal configuration
+   - Core workflow
+   - Context basics
+
+**Integration Features:**
+- Context system overview and commands
+- @voodocs annotation format (Python & TypeScript)
+- Development workflow best practices
+- Invariant checking instructions
+- Architecture diagram generation
+- AI-specific guidance and tips
+
+**User Experience:**
+- ✓ markers show detected AI configurations
+- Numbered menu for easy selection
+- Creates parent directories automatically
+- Handles existing files with overwrite prompt
+- Default: generate all integrations
+- Can select individual AIs or all at once
+
+**Technical Implementation:**
+- New module: `ai_integrations.py` (685 lines)
+- Detection: `detect_ai_assistants()` function
+- Generation: AI-specific template functions
+- Integration: Updated `cmd_context_init()` command
+
+### Changed
+- Enhanced `voodocs context init` with AI assistant detection and integration
+- Improved user prompts with visual markers for detected configurations
+- Updated next steps to include AI-specific guidance
+
+### Documentation
+- Added AI integration research notes
+- Created comprehensive AI integration summary
+- Documented all supported AI assistant formats
+
+### Impact
+
+This release makes VooDocs **truly AI-native**, working seamlessly with any AI assistant. The context system becomes the single source of truth that all AIs understand and respect.
+
+**Key Benefits:**
+- One command sets up everything
+- Works with any AI assistant
+- Native format for each AI
+- No manual configuration needed
+- Consistent AI behavior across teams
+- Context-aware development
+
+## [0.2.0] - 2025-12-19
+
+### Added
+
+#### Context System - Phase 4: Verification & Visualization
+
+**Invariant Checking (`voodocs context check`)**
+- Automatically validate code against documented invariants
+- Pattern-based detection for 6 common security issues (SQL injection, unhashed passwords, logged secrets, etc.)
+- File and line number reporting for violations
+- JSON output format for CI/CD integration
+- Module and invariant filtering options
+- Severity levels (error, warning, info)
+
+**Architecture Diagram Generation (`voodocs context diagram`)**
+- Auto-generate visual diagrams from context files
+- 3 diagram types: modules, dependencies, flow
+- Supports Mermaid and D2 formats
+- Auto-renders to PNG using manus-render-diagram
+- Console output or file export
+
+**Enhanced Validation (`voodocs context validate`)**
+- Smart suggestions for missing sections
+- Integrated invariant checking with `--check-invariants` flag
+- Completeness, quality, and consistency checks
+- Actionable recommendations for improvement
+
+#### Context System - Phase 3: Auto-Generation & Query
+
+**Auto-Generation (`voodocs context generate`)**
+- Automatically extract context from @voodocs annotations
+- Recursively scans codebase for annotations
+- Extracts global invariants, assumptions, and modules
+- Supports multiple languages (Python, TypeScript, JavaScript, Java, C++, Go, Rust)
+
+**Query System (`voodocs context query`)**
+- Query context like a database using regex patterns
+- Section filtering and multiple output formats (text, JSON, YAML)
+
+**Git Integration**
+- Auto-detects Git commit hash and author
+- Integrated into `update` and `sync` commands
+
+#### Context System - Phase 2: Versioning & History
+
+**Version Management**
+- `voodocs context update`: Update context and increment version
+- `voodocs context sync`: Sync context with code version
+- `voodocs context history`: Show version history
+- `voodocs context diff`: Compare context versions
+
+#### Context System - Phase 1: Foundation
+
+**Core Commands**
+- `voodocs context init`: Initialize .voodocs.context file
+- `voodocs context view`: View context as Markdown
+- `voodocs context status`: Show context file status
+
+### Changed
+- Enhanced `voodocs context validate` with smart suggestions
+- Improved error messages and user feedback
+
+### Documentation
+- Added comprehensive Phase 3 and Phase 4 implementation guides
+- Updated README with new context system commands
+- Added example architecture diagram
+
+### Performance
+- Invariant checking: < 1 second for 15 files
+- Diagram generation: < 100ms + 1-2s for PNG rendering
+- Enhanced validation: < 50ms
+
+### Code Statistics
+- Total Context System: 3,060 lines across 4 phases
+- 12 context commands implemented
+- 980 lines added in Phase 4
+
 ## [0.1.2] - 2025-12-19
 
 ### Fixed

package/README.md

@@ -84,11 +84,41 @@ voodocs generate ./src --tests-only
 
 ## Core Commands
 
-- `voodocs init`: Configure your API key and activate your license
+### 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 your current license status and usage
-- `voodocs upgrade`: Get information on upgrading your plan
+- `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
 
@@ -101,6 +131,29 @@ Voodocs uses the **DarkArts language** - a mathematical and logical notation sys
 
 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:
+```bash
+voodocs context check
+```
+Detects security issues like SQL injection, unhashed passwords, and logged secrets.
+
+### 📊 Architecture Diagrams
+Auto-generate visual diagrams from your context:
+```bash
+voodocs context diagram --type modules --output arch.png --png
+```
+Supports module diagrams, dependency diagrams, and flow diagrams.
+
+### ✅ Enhanced Validation
+Smart validation with actionable suggestions:
+```bash
+voodocs context validate --check-invariants
+```
+Provides completeness checks, quality suggestions, and consistency validation.
+
 ## Why Voodocs?
 
 - **AI-First Workflow**: Designed for modern AI-assisted development. Your AI documents as it codes.
@@ -108,6 +161,8 @@ Voodocs then translates this precise, machine-readable format into natural langu
 - **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)
 
 ## Example Annotation
 

package/cli.py

@@ -137,7 +137,7 @@ Documentation: https://github.com/3vilEnterprises/vooodooo-magic/tree/main/packa
     parser.add_argument(
         "--version",
         action="version",
-        version="VooDocs 0.1.2"
+        version="VooDocs 0.3.0"
     )
     
     subparsers = parser.add_subparsers(dest="command", help="Available commands")
@@ -372,6 +372,197 @@ Documentation: https://github.com/3vilEnterprises/vooodooo-magic/tree/main/packa
         help="Telemetry action"
     )
     
+    # context command
+    context_parser = subparsers.add_parser(
+        "context",
+        help="Manage project context for AI assistants"
+    )
+    context_subparsers = context_parser.add_subparsers(dest="context_action", help="Context actions")
+    
+    # context init
+    context_init_parser = context_subparsers.add_parser(
+        "init",
+        help="Initialize a new .voodocs.context file"
+    )
+    context_init_parser.add_argument(
+        "--force",
+        action="store_true",
+        help="Overwrite existing context file"
+    )
+    
+    # context view
+    context_view_parser = context_subparsers.add_parser(
+        "view",
+        help="View context as human-readable Markdown"
+    )
+    context_view_parser.add_argument(
+        "--output",
+        "-o",
+        help="Output file path (default: print to console)"
+    )
+    
+    # context status
+    context_status_parser = context_subparsers.add_parser(
+        "status",
+        help="Show context file status"
+    )
+    
+    # context update
+    context_update_parser = context_subparsers.add_parser(
+        "update",
+        help="Update context and increment version"
+    )
+    context_update_parser.add_argument(
+        "--description",
+        "-d",
+        help="Description of the changes"
+    )
+    
+    # context sync
+    context_sync_parser = context_subparsers.add_parser(
+        "sync",
+        help="Sync context with code version"
+    )
+    context_sync_parser.add_argument(
+        "--code-version",
+        "-v",
+        help="New code version (e.g., 2.0.0)"
+    )
+    context_sync_parser.add_argument(
+        "--force",
+        action="store_true",
+        help="Skip confirmation prompts"
+    )
+    
+    # context history
+    context_history_parser = context_subparsers.add_parser(
+        "history",
+        help="Show version history"
+    )
+    
+    # context diff
+    context_diff_parser = context_subparsers.add_parser(
+        "diff",
+        help="Compare context versions"
+    )
+    context_diff_parser.add_argument(
+        "version1",
+        nargs="?",
+        help="First version (older)"
+    )
+    context_diff_parser.add_argument(
+        "version2",
+        nargs="?",
+        help="Second version (newer, default: current)"
+    )
+    
+    # context validate
+    context_validate_parser = context_subparsers.add_parser(
+        "validate",
+        help="Validate context file"
+    )
+    context_validate_parser.add_argument(
+        "--check-version",
+        action="store_true",
+        help="Check if code version matches detected version"
+    )
+    context_validate_parser.add_argument(
+        "--check-invariants",
+        action="store_true",
+        help="Check if code respects documented invariants"
+    )
+    
+    # context generate
+    context_generate_parser = context_subparsers.add_parser(
+        "generate",
+        help="Generate context from code annotations"
+    )
+    context_generate_parser.add_argument(
+        "source_dir",
+        nargs="?",
+        help="Directory to scan (default: current directory)"
+    )
+    context_generate_parser.add_argument(
+        "--update",
+        action="store_true",
+        help="Update existing context file"
+    )
+    
+    # context query
+    context_query_parser = context_subparsers.add_parser(
+        "query",
+        help="Query context like a database"
+    )
+    context_query_parser.add_argument(
+        "query",
+        help="Search query (keyword or regex)"
+    )
+    context_query_parser.add_argument(
+        "--section",
+        "-s",
+        help="Specific section to search"
+    )
+    context_query_parser.add_argument(
+        "--format",
+        "-f",
+        choices=["text", "json", "yaml"],
+        default="text",
+        help="Output format (default: text)"
+    )
+    
+    # context check
+    context_check_parser = context_subparsers.add_parser(
+        "check",
+        help="Check that code respects documented invariants"
+    )
+    context_check_parser.add_argument(
+        "--module",
+        "-m",
+        help="Filter by module name"
+    )
+    context_check_parser.add_argument(
+        "--invariant",
+        "-i",
+        help="Filter by invariant text"
+    )
+    context_check_parser.add_argument(
+        "--format",
+        "-f",
+        choices=["text", "json"],
+        default="text",
+        help="Output format (default: text)"
+    )
+    
+    # context diagram
+    context_diagram_parser = context_subparsers.add_parser(
+        "diagram",
+        help="Generate architecture diagrams from context"
+    )
+    context_diagram_parser.add_argument(
+        "--type",
+        "-t",
+        choices=["modules", "dependencies", "flow", "all"],
+        default="modules",
+        help="Diagram type (default: modules)"
+    )
+    context_diagram_parser.add_argument(
+        "--format",
+        "-f",
+        choices=["mermaid", "d2"],
+        default="mermaid",
+        help="Output format (default: mermaid)"
+    )
+    context_diagram_parser.add_argument(
+        "--output",
+        "-o",
+        help="Output file path (default: print to console)"
+    )
+    context_diagram_parser.add_argument(
+        "--png",
+        action="store_true",
+        help="Render to PNG (requires output file)"
+    )
+    
     args = parser.parse_args()
     
     # Execute command
@@ -393,6 +584,8 @@ Documentation: https://github.com/3vilEnterprises/vooodooo-magic/tree/main/packa
         cmd_export(args)
     elif args.command == "telemetry":
         cmd_telemetry(args)
+    elif args.command == "context":
+        cmd_context(args)
     else:
         parser.print_help()
         sys.exit(1)
@@ -435,7 +628,7 @@ def cmd_init(args):
         config = {
             "project_name": project_name,
             "language": language,
-            "version": "0.1.2",
+            "version": "0.2.0",
             "output_dir": "./voodocs-output",
             "test_framework": "pytest",
             "api_format": "openapi",
@@ -1353,5 +1546,72 @@ def cmd_telemetry(args):
         client.status()
 
 
+def cmd_context(args):
+    """Manage project context."""
+    from darkarts.context import (
+        cmd_context_init,
+        cmd_context_view,
+        cmd_context_status,
+        cmd_context_update,
+        cmd_context_sync,
+        cmd_context_history,
+        cmd_context_diff,
+        cmd_context_validate,
+        cmd_context_generate,
+        cmd_context_query,
+        cmd_context_check,
+        cmd_context_diagram
+    )
+    
+    if args.context_action == "init":
+        force = getattr(args, 'force', False)
+        sys.exit(cmd_context_init(force=force))
+    elif args.context_action == "view":
+        output_file = getattr(args, 'output', None)
+        sys.exit(cmd_context_view(output_file=output_file))
+    elif args.context_action == "status":
+        sys.exit(cmd_context_status())
+    elif args.context_action == "update":
+        description = getattr(args, 'description', None)
+        sys.exit(cmd_context_update(description=description))
+    elif args.context_action == "sync":
+        code_version = getattr(args, 'code_version', None)
+        force = getattr(args, 'force', False)
+        sys.exit(cmd_context_sync(code_version=code_version, force=force))
+    elif args.context_action == "history":
+        sys.exit(cmd_context_history())
+    elif args.context_action == "diff":
+        version1 = getattr(args, 'version1', None)
+        version2 = getattr(args, 'version2', None)
+        sys.exit(cmd_context_diff(version1=version1, version2=version2))
+    elif args.context_action == "validate":
+        check_version = getattr(args, 'check_version', False)
+        check_invariants = getattr(args, 'check_invariants', False)
+        sys.exit(cmd_context_validate(check_version=check_version, check_invariants=check_invariants))
+    elif args.context_action == "generate":
+        source_dir = getattr(args, 'source_dir', None)
+        update_existing = getattr(args, 'update', False)
+        sys.exit(cmd_context_generate(source_dir=source_dir, update_existing=update_existing))
+    elif args.context_action == "query":
+        query = getattr(args, 'query', '')
+        section = getattr(args, 'section', None)
+        format_type = getattr(args, 'format', 'text')
+        sys.exit(cmd_context_query(query=query, section=section, format=format_type))
+    elif args.context_action == "check":
+        module_filter = getattr(args, 'module', None)
+        invariant_filter = getattr(args, 'invariant', None)
+        format_type = getattr(args, 'format', 'text')
+        sys.exit(cmd_context_check(module_filter=module_filter, invariant_filter=invariant_filter, output_format=format_type))
+    elif args.context_action == "diagram":
+        diagram_type = getattr(args, 'type', 'modules')
+        output_format = getattr(args, 'format', 'mermaid')
+        output_file = getattr(args, 'output', None)
+        render_png = getattr(args, 'png', False)
+        sys.exit(cmd_context_diagram(diagram_type=diagram_type, output_format=output_format, output_file=output_file, render_png=render_png))
+    else:
+        print("Usage: voodocs context {init|view|status|update|sync|history|diff|validate|generate|query|check|diagram}")
+        sys.exit(1)
+
+
 if __name__ == "__main__":
     main()

package/lib/darkarts/annotations/parser.py

@@ -340,6 +340,17 @@ class AnnotationParser:
         if text.startswith('{'):
             return self._parse_object(text)
         
+        # Check if it's a YAML-style list (multiple lines starting with -)
+        if any(line.strip().startswith('-') for line in value_lines):
+            items = []
+            for line in value_lines:
+                line = line.strip()
+                if line.startswith('-'):
+                    item = line[1:].strip()
+                    if item:  # Only add non-empty items
+                        items.append(item)
+            return items if items else text
+        
         return text
     
     def _parse_list(self, text: str) -> List[str]:
@@ -616,3 +627,56 @@ class AnnotationParser:
             func.complexity = self._parse_complexity(annotations['complexity'])
         if 'side_effects' in annotations:
             func.side_effects = annotations['side_effects'] if isinstance(annotations['side_effects'], list) else [annotations['side_effects']]
+
+    def parse_directory(self, directory: Path) -> List[ParsedAnnotations]:
+        """
+        Parse all source files in a directory recursively.
+        
+        Args:
+            directory: Path to the directory to scan
+        
+        Returns:
+            List of ParsedAnnotations objects, one per file with annotations
+        """
+        results = []
+        
+        # Supported file extensions
+        extensions = {'.py', '.ts', '.tsx', '.js', '.jsx', '.java', '.cpp', '.cc', 
+                     '.cxx', '.h', '.hpp', '.cs', '.go', '.rs'}
+        
+        # Directories to skip
+        skip_dirs = {'node_modules', '.git', '__pycache__', 'venv', '.venv', 
+                    'dist', 'build', 'target', '.next', '.nuxt'}
+        
+        # Recursively find all source files
+        for path in directory.rglob('*'):
+            # Skip directories
+            if path.is_dir():
+                continue
+            
+            # Skip if in excluded directory
+            if any(skip_dir in path.parts for skip_dir in skip_dirs):
+                continue
+            
+            # Check if file has supported extension
+            if path.suffix.lower() not in extensions:
+                continue
+            
+            try:
+                # Parse the file
+                parsed = self.parse_file(str(path))
+                
+                # Only include if it has annotations
+                if (parsed.module.module_purpose or 
+                    parsed.module.dependencies or 
+                    parsed.module.assumptions or
+                    parsed.module.classes or 
+                    parsed.module.functions):
+                    results.append(parsed)
+            
+            except Exception as e:
+                # Skip files that fail to parse
+                print(f"   ⚠️  Skipped {path.relative_to(directory)}: {str(e)}")
+                continue
+        
+        return results

package/lib/darkarts/context/__init__.py

@@ -0,0 +1,84 @@
+"""
+VooDocs Context System
+
+A structured, machine-readable knowledge base for software projects.
+"""
+
+from .models import (
+    ContextFile,
+    Versioning,
+    Project,
+    Architecture,
+    ArchitectureDecision,
+    Module,
+    CriticalPath,
+    KnownIssue,
+    Assumption,
+    Change,
+    RoadmapItem,
+    create_minimal_context
+)
+
+from .yaml_utils import (
+    write_context_yaml,
+    read_context_yaml,
+    parse_context_file,
+    add_to_gitignore,
+    format_context_as_markdown
+)
+
+from .commands import (
+    cmd_context_init,
+    cmd_context_view,
+    cmd_context_status,
+    cmd_context_update,
+    cmd_context_sync,
+    cmd_context_history,
+    cmd_context_diff,
+    cmd_context_validate,
+    cmd_context_generate,
+    cmd_context_query,
+    cmd_context_check,
+    cmd_context_diagram,
+    get_context_file_path,
+    context_file_exists
+)
+
+__all__ = [
+    # Models
+    'ContextFile',
+    'Versioning',
+    'Project',
+    'Architecture',
+    'ArchitectureDecision',
+    'Module',
+    'CriticalPath',
+    'KnownIssue',
+    'Assumption',
+    'Change',
+    'RoadmapItem',
+    'create_minimal_context',
+    
+    # YAML utilities
+    'write_context_yaml',
+    'read_context_yaml',
+    'parse_context_file',
+    'add_to_gitignore',
+    'format_context_as_markdown',
+    
+    # Commands
+    'cmd_context_init',
+    'cmd_context_view',
+    'cmd_context_status',
+    'cmd_context_update',
+    'cmd_context_sync',
+    'cmd_context_history',
+    'cmd_context_diff',
+    'cmd_context_validate',
+    'cmd_context_generate',
+    'cmd_context_query',
+    'cmd_context_check',
+    'cmd_context_diagram',
+    'get_context_file_path',
+    'context_file_exists',
+]