@voodocs/cli 0.2.0 → 0.3.1

package/lib/darkarts/context/ai_instructions.py

@@ -0,0 +1,734 @@
+"""
+AI instruction templates for VooDocs Context System.
+
+This module provides templates for generating AI assistant instructions
+that teach them how to use the VooDocs context system effectively.
+"""
+
+from typing import Dict, Optional
+
+
+def generate_cursorrules(project_name: str, project_purpose: str) -> str:
+    """
+    Generate .cursorrules content for Cursor AI.
+    
+    Args:
+        project_name: Name of the project
+        project_purpose: Brief purpose of the project
+    
+    Returns:
+        Content for .cursorrules file
+    """
+    return f"""# {project_name} - VooDocs Context System
+
+## Project Overview
+{project_purpose}
+
+## VooDocs Context System (v0.2.0+)
+
+This project uses VooDocs with the Context System for intelligent documentation and validation.
+
+### Context File Location
+- **Context file**: `.voodocs.context` (YAML format)
+- **Auto-generated**: From @voodocs annotations in code
+- **Version controlled**: Track context changes over time
+
+### Essential Commands
+
+#### Before Starting Work
+```bash
+# Read the project context to understand architecture, invariants, and assumptions
+voodocs context view
+```
+
+#### During Development
+```bash
+# Add @voodocs annotations to your code (see format below)
+# Then auto-generate context from annotations
+voodocs context generate --update
+
+# Check if code respects documented invariants
+voodocs context check
+
+# Query specific information
+voodocs context query "search term" --section invariants
+```
+
+#### Before Committing
+```bash
+# Validate context and check invariants
+voodocs context validate --check-invariants
+
+# Update context version with description
+voodocs context update --description "Brief description of changes"
+```
+
+#### Architecture & Documentation
+```bash
+# Generate architecture diagrams
+voodocs context diagram --type modules --output docs/architecture.mmd
+
+# View full context as Markdown
+voodocs context view > docs/CONTEXT.md
+```
+
+### @voodocs Annotation Format
+
+Add to Python/TypeScript/JavaScript files:
+
+**Python:**
+```python
+\"\"\"@voodocs
+module_purpose: "Brief description of what this module does"
+dependencies: [
+    "other-module: What it provides",
+    "external-lib: Why we use it"
+]
+assumptions: [
+    "Database connection is established",
+    "User is authenticated",
+    "Environment variables are set"
+]
+invariants: [
+    "All user input must be validated",
+    "Passwords must be hashed before storage",
+    "API keys must never be logged"
+]
+security_model: "Brief description of security approach"
+performance_notes: "Expected performance characteristics"
+\"\"\"
+```
+
+**TypeScript/JavaScript:**
+```typescript
+/**@voodocs
+module_purpose: "Brief description of what this module does"
+dependencies: [
+    "react: UI framework",
+    "axios: HTTP client"
+]
+assumptions: [
+    "API endpoint is available",
+    "User has valid token"
+]
+invariants: [
+    "All API responses must be validated",
+    "Errors must be handled gracefully"
+]
+*/
+```
+
+### Context-Aware Development Workflow
+
+1. **Understand Context**: Always run `voodocs context view` before making changes
+2. **Check Invariants**: Ensure you understand the global invariants that must be respected
+3. **Add Annotations**: Document your code with @voodocs annotations as you write
+4. **Update Context**: Run `voodocs context generate --update` after adding features
+5. **Validate**: Run `voodocs context check` to ensure invariants are respected
+6. **Update Version**: Use `voodocs context update` to track context changes
+
+### What to Document
+
+**Module Purpose**: What this module does and why it exists
+**Dependencies**: What this module depends on (internal and external)
+**Assumptions**: What must be true for this module to work correctly
+**Invariants**: Rules that must always hold (security, data integrity, etc.)
+**Security Model**: How this module handles security concerns
+**Performance Notes**: Expected performance characteristics and bottlenecks
+
+### Context Sections
+
+The `.voodocs.context` file contains:
+
+- **Project**: Name, purpose, domain
+- **Versioning**: Code version, context version, last updated
+- **Invariants**: Global rules that must always hold
+- **Assumptions**: System-wide assumptions
+- **Architecture**: Modules, decisions, patterns
+- **Critical Paths**: Important workflows
+- **Dependencies**: External libraries and tools
+- **Known Issues**: Bugs and limitations
+- **Change History**: Version tracking with Git integration
+
+### Best Practices
+
+1. **Read context first**: Always check context before making changes
+2. **Document as you code**: Add @voodocs annotations while writing code
+3. **Keep invariants clear**: Make invariants specific and testable
+4. **Update regularly**: Run `voodocs context generate --update` frequently
+5. **Validate before commit**: Run `voodocs context check` before committing
+6. **Track changes**: Use `voodocs context update` to document what changed
+
+### CI/CD Integration
+
+The context system can be integrated into CI/CD pipelines:
+
+```yaml
+# GitHub Actions example
+- name: Validate Context
+  run: voodocs context validate --check-invariants
+
+- name: Check Invariants
+  run: voodocs context check --format json
+```
+
+### Querying Context
+
+Search for specific information:
+
+```bash
+# Find security-related invariants
+voodocs context query "security" --section invariants
+
+# Find authentication assumptions
+voodocs context query "auth" --section assumptions --format json
+
+# Search all sections
+voodocs context query "database"
+```
+
+### Architecture Diagrams
+
+Generate visual documentation:
+
+```bash
+# Module dependency diagram
+voodocs context diagram --type modules
+
+# External dependencies
+voodocs context diagram --type dependencies
+
+# Critical path workflows
+voodocs context diagram --type flow
+
+# Generate all diagrams
+voodocs context diagram --type all --output docs/arch
+```
+
+### Remember
+
+- The context system is your source of truth for project understanding
+- Invariants are enforced rules - respect them
+- Assumptions are documented expectations - validate them
+- Context is version-controlled - track changes
+- Always check context before making architectural decisions
+
+---
+
+**VooDocs Context System** - AI-native documentation that keeps code and context in sync.
+"""
+
+
+def generate_context_guide(project_name: str, project_purpose: str) -> str:
+    """
+    Generate comprehensive context guide for AI assistants.
+    
+    Args:
+        project_name: Name of the project
+        project_purpose: Brief purpose of the project
+    
+    Returns:
+        Content for VOODOCS_CONTEXT_GUIDE.md file
+    """
+    return f"""# VooDocs Context System Guide - {project_name}
+
+## Project Overview
+
+**Name**: {project_name}  
+**Purpose**: {project_purpose}
+
+This project uses the **VooDocs Context System** (v0.2.0+) for intelligent documentation, validation, and architecture management.
+
+---
+
+## What is the Context System?
+
+The VooDocs Context System is an AI-native documentation framework that:
+
+1. **Auto-generates** project context from code annotations
+2. **Validates** code against documented invariants
+3. **Tracks** changes with version control integration
+4. **Visualizes** architecture with auto-generated diagrams
+5. **Queries** like a database for instant information
+
+---
+
+## Quick Start
+
+### 1. View Current Context
+
+```bash
+voodocs context view
+```
+
+This shows you:
+- Project purpose and domain
+- Global invariants (rules that must hold)
+- System assumptions
+- Architecture and modules
+- Dependencies
+- Known issues
+
+**Do this before making any changes!**
+
+### 2. Check Invariants
+
+```bash
+voodocs context check
+```
+
+This validates that the code respects all documented invariants:
+- Password hashing
+- API key protection
+- SQL injection prevention
+- Input validation
+- Error handling
+- And more...
+
+### 3. Update Context
+
+```bash
+voodocs context generate --update
+```
+
+This scans the codebase for @voodocs annotations and updates the context file.
+
+---
+
+## The `.voodocs.context` File
+
+**Location**: `./.voodocs.context`  
+**Format**: YAML  
+**Purpose**: Single source of truth for project understanding
+
+### Structure
+
+```yaml
+project:
+  name: "{project_name}"
+  purpose: "{project_purpose}"
+  domain: "Application domain"
+
+versioning:
+  code_version: "1.0.0"
+  context_version: "1.0"
+  last_updated: "2025-12-19"
+
+invariants:
+  global:
+    - "All passwords must be hashed before storage"
+    - "API keys must never be logged"
+    - "All database queries must use parameterized statements"
+
+assumptions:
+  - "Database connection is established at startup"
+  - "User authentication is handled by auth service"
+
+architecture:
+  modules:
+    module-name:
+      purpose: "What this module does"
+      dependencies: ["other-module"]
+
+dependencies:
+  external:
+    - name: "library-name"
+      version: "1.0.0"
+      purpose: "Why we use it"
+
+critical_paths:
+  - name: "User Login Flow"
+    steps:
+      - "User enters credentials"
+      - "Credentials validated"
+      - "JWT token generated"
+      - "Token returned to client"
+```
+
+---
+
+## @voodocs Annotations
+
+### Purpose
+
+Annotations are **structured comments** that document:
+- What a module does
+- What it depends on
+- What assumptions it makes
+- What invariants it enforces
+
+### Format
+
+**Python:**
+```python
+\"\"\"@voodocs
+module_purpose: "User authentication and session management"
+dependencies: [
+    "bcrypt: Password hashing",
+    "jwt: Token generation",
+    "database: User storage"
+]
+assumptions: [
+    "Database connection is available",
+    "Redis is running for session storage"
+]
+invariants: [
+    "Passwords must be hashed with bcrypt",
+    "Sessions must expire after 24 hours",
+    "Failed login attempts must be rate-limited"
+]
+security_model: "Passwords hashed with bcrypt (cost 12), JWTs expire in 24h, rate limiting on failed attempts"
+performance_notes: "O(1) for session lookup (Redis), O(log n) for user lookup (indexed database)"
+\"\"\"
+
+def authenticate_user(username: str, password: str) -> Optional[str]:
+    # Implementation
+    pass
+```
+
+**TypeScript:**
+```typescript
+/**@voodocs
+module_purpose: "API client for backend communication"
+dependencies: [
+    "axios: HTTP client",
+    "zod: Response validation"
+]
+assumptions: [
+    "API endpoint is reachable",
+    "User has valid authentication token"
+]
+invariants: [
+    "All API responses must be validated",
+    "Network errors must be handled gracefully",
+    "Retry logic must use exponential backoff"
+]
+*/
+
+export class ApiClient {{
+    // Implementation
+}}
+```
+
+### Fields
+
+| Field | Required | Description |
+|-------|----------|-------------|
+| `module_purpose` | Yes | Brief description of what this module does |
+| `dependencies` | No | List of dependencies (internal and external) |
+| `assumptions` | No | What must be true for this module to work |
+| `invariants` | No | Rules that must always hold |
+| `security_model` | No | How security is handled |
+| `performance_notes` | No | Expected performance characteristics |
+
+---
+
+## Command Reference
+
+### Context Management
+
+| Command | Purpose |
+|---------|---------|
+| `voodocs context init` | Initialize context file |
+| `voodocs context view` | View context as Markdown |
+| `voodocs context status` | Show context status |
+
+### Auto-Generation
+
+| Command | Purpose |
+|---------|---------|
+| `voodocs context generate` | Generate context from code |
+| `voodocs context generate --update` | Update existing context |
+
+### Validation
+
+| Command | Purpose |
+|---------|---------|
+| `voodocs context validate` | Validate context file |
+| `voodocs context validate --check-invariants` | Validate + check code |
+| `voodocs context check` | Check code against invariants |
+| `voodocs context check --format json` | JSON output for CI/CD |
+
+### Querying
+
+| Command | Purpose |
+|---------|---------|
+| `voodocs context query "term"` | Search all sections |
+| `voodocs context query "term" --section invariants` | Search specific section |
+| `voodocs context query "term" --format json` | JSON output |
+
+### Versioning
+
+| Command | Purpose |
+|---------|---------|
+| `voodocs context update` | Update context version |
+| `voodocs context sync` | Sync with code version |
+| `voodocs context history` | Show version history |
+| `voodocs context diff v1 v2` | Compare versions |
+
+### Visualization
+
+| Command | Purpose |
+|---------|---------|
+| `voodocs context diagram --type modules` | Module diagram |
+| `voodocs context diagram --type dependencies` | Dependency diagram |
+| `voodocs context diagram --type flow` | Flow diagram |
+| `voodocs context diagram --type all` | All diagrams |
+
+---
+
+## Development Workflow
+
+### 1. Before Starting Work
+
+```bash
+# Read the context
+voodocs context view
+
+# Check current status
+voodocs context status
+
+# Validate everything
+voodocs context validate --check-invariants
+```
+
+### 2. During Development
+
+```bash
+# Add @voodocs annotations to your code
+# (See annotation format above)
+
+# Update context from annotations
+voodocs context generate --update
+
+# Check if code respects invariants
+voodocs context check
+```
+
+### 3. Before Committing
+
+```bash
+# Final validation
+voodocs context validate --check-invariants
+
+# Update context version
+voodocs context update --description "Added user authentication module"
+
+# Generate updated diagrams
+voodocs context diagram --type all --output docs/architecture
+```
+
+### 4. During Code Review
+
+```bash
+# Compare context versions
+voodocs context diff v1.0 v1.1
+
+# Check specific invariant
+voodocs context check --invariant "password"
+
+# Query for specific information
+voodocs context query "authentication" --section assumptions
+```
+
+---
+
+## Invariant Checking
+
+### What Are Invariants?
+
+Invariants are **rules that must always hold**. Examples:
+- "All passwords must be hashed before storage"
+- "API keys must never be logged"
+- "All database queries must use parameterized statements"
+
+### How It Works
+
+The invariant checker uses **pattern-based detection** to find violations:
+
+```bash
+voodocs context check
+```
+
+**Output:**
+```
+✅ All passwords must be hashed before storage
+   No violations found
+
+❌ API keys must never be logged
+   Found 2 potential violation(s):
+   
+   📍 src/auth.py:45
+      logger.info(f"Using API key: {{api_key}}")
+      → API keys/secrets should not be logged
+```
+
+### Supported Patterns
+
+- Password security (hashing detection)
+- API key protection (logging detection)
+- SQL injection prevention (parameterized queries)
+- Input validation
+- Null/None checking
+- Error handling
+
+---
+
+## Architecture Diagrams
+
+### Generate Diagrams
+
+```bash
+# Module dependency diagram
+voodocs context diagram --type modules --output architecture.mmd
+
+# External dependencies
+voodocs context diagram --type dependencies --output dependencies.mmd
+
+# Critical path workflows
+voodocs context diagram --type flow --output flows.mmd
+```
+
+### Viewing Diagrams
+
+The diagrams are generated in **Mermaid** format. View them:
+- Copy to [Mermaid Live Editor](https://mermaid.live)
+- Use VS Code with Mermaid extension
+- Render in GitHub (supports Mermaid in markdown)
+
+---
+
+## CI/CD Integration
+
+### GitHub Actions
+
+```yaml
+name: Context Validation
+
+on: [push, pull_request]
+
+jobs:
+  validate:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v2
+      
+      - name: Install VooDocs
+        run: npm install -g @voodocs/cli
+      
+      - name: Validate Context
+        run: voodocs context validate --check-invariants
+      
+      - name: Check Invariants
+        run: voodocs context check --format json > violations.json
+      
+      - name: Upload Report
+        uses: actions/upload-artifact@v2
+        with:
+          name: context-report
+          path: violations.json
+```
+
+---
+
+## Best Practices
+
+### 1. Read Context First
+Always run `voodocs context view` before making changes.
+
+### 2. Document As You Code
+Add @voodocs annotations while writing code, not after.
+
+### 3. Keep Invariants Specific
+❌ Bad: "Data must be valid"  
+✅ Good: "All user input must be validated using Zod schemas"
+
+### 4. Update Regularly
+Run `voodocs context generate --update` frequently during development.
+
+### 5. Validate Before Commit
+Always run `voodocs context check` before committing.
+
+### 6. Track Changes
+Use `voodocs context update` to document what changed and why.
+
+### 7. Query for Understanding
+Use `voodocs context query` to quickly find information.
+
+### 8. Generate Diagrams
+Keep architecture diagrams up-to-date with `voodocs context diagram`.
+
+---
+
+## Troubleshooting
+
+### "No modules found in context"
+
+**Problem**: Trying to generate module diagram but no modules defined.
+
+**Solution**: Add modules to `.voodocs.context`:
+```yaml
+architecture:
+  modules:
+    module-name:
+      purpose: "What it does"
+      dependencies: []
+```
+
+Or add `module_purpose` to @voodocs annotations and regenerate.
+
+### "Invariant violations found"
+
+**Problem**: Code doesn't respect documented invariants.
+
+**Solution**: 
+1. Review the violation report
+2. Fix the code to respect the invariant
+3. Or update the invariant if it's incorrect
+
+### "Context file not found"
+
+**Problem**: No `.voodocs.context` file exists.
+
+**Solution**: Run `voodocs context init` to create one.
+
+---
+
+## Summary
+
+The VooDocs Context System is your **single source of truth** for:
+- ✅ Project understanding
+- ✅ Architecture documentation
+- ✅ Code validation
+- ✅ Change tracking
+- ✅ Visual documentation
+
+**Always check context before making changes!**
+
+---
+
+**VooDocs v0.2.0+** - AI-native documentation that keeps code and context in sync.
+"""
+
+
+def generate_ai_instructions(project_name: str, project_purpose: str, ai_type: str = "cursor") -> Dict[str, str]:
+    """
+    Generate AI instruction files for different AI assistants.
+    
+    Args:
+        project_name: Name of the project
+        project_purpose: Brief purpose of the project
+        ai_type: Type of AI assistant ("cursor", "claude", "copilot", "all")
+    
+    Returns:
+        Dictionary mapping filename to content
+    """
+    instructions = {}
+    
+    if ai_type in ["cursor", "all"]:
+        instructions[".cursorrules"] = generate_cursorrules(project_name, project_purpose)
+    
+    if ai_type in ["all", "cursor", "claude", "copilot"]:
+        instructions["VOODOCS_CONTEXT_GUIDE.md"] = generate_context_guide(project_name, project_purpose)
+    
+    return instructions