@voodocs/cli 0.1.0

package/cli.py

@@ -0,0 +1,1340 @@
+#!/usr/bin/env python3
+"""
+VooDocs CLI - AI-native documentation for modern development
+
+Commands:
+  init      - Initialize VooDocs in a project
+  instruct  - Generate AI assistant instructions
+  generate  - Generate docs, tests, and API specs from annotations
+  status    - Show project status and statistics
+  version   - Show VooDocs version
+"""
+
+import sys
+import argparse
+import traceback
+import time
+from pathlib import Path
+from functools import wraps
+
+# Add lib to path (resolve symlinks for npm bin)
+import os
+script_path = Path(os.path.realpath(__file__)).parent
+sys.path.insert(0, str(script_path / "lib"))
+
+from darkarts.plugins.voodocs.instruction_generator import InstructionGenerator
+from darkarts.plugins.voodocs.documentation_generator import DocumentationGenerator
+from darkarts.plugins.voodocs.test_generator import TestGenerator
+from darkarts.plugins.voodocs.api_spec_generator import APISpecGenerator
+from darkarts.plugins.voodocs.annotation_validator import AnnotationValidator
+from darkarts.plugins.voodocs.html_exporter import HTMLExporter
+from darkarts.plugins.voodocs.pdf_exporter import PDFExporter
+from darkarts.annotations.parser import AnnotationParser
+from darkarts.telemetry import get_telemetry_client, track_command
+from darkarts.exceptions import (
+    VooDocsError,
+    ParserError,
+    ParserNotBuiltError,
+    AnnotationError,
+    GeneratorError,
+    ConfigurationError
+)
+
+# Telemetry environment variables
+os.environ.setdefault("VOODOCS_SUPABASE_URL", "https://sjatkayudkbkmipubhfy.supabase.co")
+os.environ.setdefault("VOODOCS_SUPABASE_ANON_KEY", "sb_publishable_rHfzdx4jc7QH3JFSRC-sDA_6HHhzdU5")
+
+def track_command_execution(command_name):
+    """Decorator to track command execution with telemetry."""
+    def decorator(func):
+        @wraps(func)
+        def wrapper(args):
+            start_time = time.time()
+            success = False
+            error_type = None
+            
+            try:
+                result = func(args)
+                success = True
+                return result
+            except Exception as e:
+                error_type = type(e).__name__
+                raise
+            finally:
+                duration_ms = int((time.time() - start_time) * 1000)
+                
+                # Track telemetry
+                try:
+                    track_command(
+                        command=command_name,
+                        success=success,
+                        duration_ms=duration_ms,
+                        error_type=error_type
+                    )
+                except:
+                    pass  # Never let telemetry break the CLI
+        
+        return wrapper
+    return decorator
+
+
+def main():
+    """Main CLI entry point."""
+    parser = argparse.ArgumentParser(
+        prog="voodocs",
+        description="""VooDocs - AI-native documentation for modern development
+
+VooDocs teaches AI coding assistants to document code in the DarkArts language,
+then automatically generates human-readable docs, tests, and API specs.
+        """,
+        epilog="""Examples:
+  # Initialize a new project
+  voodocs init
+  
+  # Generate AI assistant instructions
+  voodocs instruct --assistant cursor
+  
+  # Generate docs, tests, and API specs
+  voodocs generate src/
+  voodocs generate --docs-only src/
+  voodocs generate --tests-only src/
+  
+  # Validate annotation quality
+  voodocs validate src/ --strict
+  
+  # Check coverage for CI/CD
+  voodocs check . --min-coverage 80 --min-quality 70
+  
+  # Export documentation
+  voodocs export docs/api.md --format html
+  
+  # Watch for changes
+  voodocs watch src/
+
+For more information, visit: https://voodocs.com
+Documentation: https://github.com/3vilEnterprises/vooodooo-magic/tree/main/packages/voodocs
+        """,
+        formatter_class=argparse.RawDescriptionHelpFormatter
+    )
+    
+    parser.add_argument(
+        "--version",
+        action="version",
+        version="VooDocs 0.1.0"
+    )
+    
+    subparsers = parser.add_subparsers(dest="command", help="Available commands")
+    
+    # init command
+    init_parser = subparsers.add_parser(
+        "init",
+        help="Initialize VooDocs in a project"
+    )
+    init_parser.add_argument(
+        "--project-name",
+        type=str,
+        help="Project name (default: current directory name)"
+    )
+    init_parser.add_argument(
+        "--language",
+        type=str,
+        choices=["python", "typescript", "javascript"],
+        default="python",
+        help="Primary programming language (default: python)"
+    )
+    
+    # instruct command
+    instruct_parser = subparsers.add_parser(
+        "instruct",
+        help="Generate AI assistant instructions"
+    )
+    instruct_parser.add_argument(
+        "--assistant",
+        type=str,
+        choices=["cursor", "claude", "copilot", "windsurf", "generic"],
+        help="AI assistant type (auto-detected if not specified)"
+    )
+    instruct_parser.add_argument(
+        "--language",
+        type=str,
+        choices=["python", "typescript", "javascript"],
+        default="python",
+        help="Primary programming language (default: python)"
+    )
+    instruct_parser.add_argument(
+        "--output",
+        type=str,
+        help="Output file path (default: assistant's config file)"
+    )
+    
+    # generate command
+    generate_parser = subparsers.add_parser(
+        "generate",
+        help="Generate docs, tests, and API specs from annotations"
+    )
+    generate_parser.add_argument(
+        "--debug",
+        action="store_true",
+        help="Show full stack traces on errors"
+    )
+    generate_parser.add_argument(
+        "paths",
+        nargs="+",
+        help="Files or directories to process"
+    )
+    generate_parser.add_argument(
+        "--output-dir",
+        type=str,
+        default="./voodocs-output",
+        help="Output directory (default: ./voodocs-output)"
+    )
+    generate_parser.add_argument(
+        "--docs-only",
+        action="store_true",
+        help="Generate only documentation"
+    )
+    generate_parser.add_argument(
+        "--tests-only",
+        action="store_true",
+        help="Generate only tests"
+    )
+    generate_parser.add_argument(
+        "--api-only",
+        action="store_true",
+        help="Generate only API specs"
+    )
+    generate_parser.add_argument(
+        "--test-framework",
+        type=str,
+        choices=["pytest", "unittest", "jest"],
+        default="pytest",
+        help="Test framework (default: pytest)"
+    )
+    generate_parser.add_argument(
+        "--api-format",
+        type=str,
+        choices=["openapi", "swagger", "graphql"],
+        default="openapi",
+        help="API spec format (default: openapi)"
+    )
+    generate_parser.add_argument(
+        "--recursive",
+        action="store_true",
+        default=True,
+        help="Process directories recursively (default: true)"
+    )
+    generate_parser.add_argument(
+        "--verbose",
+        action="store_true",
+        help="Show detailed output"
+    )
+    
+    # status command
+    status_parser = subparsers.add_parser(
+        "status",
+        help="Show project status and statistics"
+    )
+    status_parser.add_argument(
+        "paths",
+        nargs="*",
+        default=["."],
+        help="Paths to analyze (default: current directory)"
+    )
+    
+    # watch command
+    watch_parser = subparsers.add_parser(
+        "watch",
+        help="Watch files and automatically regenerate documentation"
+    )
+    watch_parser.add_argument(
+        "paths",
+        nargs="+",
+        help="Paths to watch for changes"
+    )
+    watch_parser.add_argument(
+        "--output-dir",
+        default="./voodocs-output",
+        help="Output directory (default: ./voodocs-output)"
+    )
+    watch_parser.add_argument(
+        "--docs-only",
+        action="store_true",
+        help="Generate only documentation"
+    )
+    watch_parser.add_argument(
+        "--tests-only",
+        action="store_true",
+        help="Generate only tests"
+    )
+    watch_parser.add_argument(
+        "--api-only",
+        action="store_true",
+        help="Generate only API specs"
+    )
+    watch_parser.add_argument(
+        "--interval",
+        type=int,
+        default=2,
+        help="Check interval in seconds (default: 2)"
+    )
+    
+    # validate command
+    validate_parser = subparsers.add_parser(
+        "validate",
+        help="Validate annotation quality and correctness"
+    )
+    validate_parser.add_argument(
+        "paths",
+        nargs="+",
+        help="Paths to validate"
+    )
+    validate_parser.add_argument(
+        "--strict",
+        action="store_true",
+        help="Treat warnings as errors"
+    )
+    validate_parser.add_argument(
+        "--format",
+        choices=["text", "json"],
+        default="text",
+        help="Output format (default: text)"
+    )
+    
+    # check command (for CI/CD)
+    check_parser = subparsers.add_parser(
+        "check",
+        help="Check annotation coverage and quality (for CI/CD)"
+    )
+    check_parser.add_argument(
+        "paths",
+        nargs="*",
+        default=["."],
+        help="Paths to check (default: current directory)"
+    )
+    check_parser.add_argument(
+        "--min-coverage",
+        type=int,
+        default=0,
+        help="Minimum annotation coverage percentage (0-100)"
+    )
+    check_parser.add_argument(
+        "--min-quality",
+        type=int,
+        default=0,
+        help="Minimum quality score (0-100)"
+    )
+    
+    # export command
+    export_parser = subparsers.add_parser(
+        "export",
+        help="Export documentation to different formats"
+    )
+    export_parser.add_argument(
+        "input_file",
+        help="Input Markdown file to export"
+    )
+    export_parser.add_argument(
+        "--format",
+        choices=["html", "pdf"],
+        required=True,
+        help="Export format"
+    )
+    export_parser.add_argument(
+        "--output",
+        help="Output file path (optional)"
+    )
+    
+    # telemetry command
+    telemetry_parser = subparsers.add_parser(
+        "telemetry",
+        help="Manage telemetry settings"
+    )
+    telemetry_parser.add_argument(
+        "action",
+        choices=["enable", "disable", "status"],
+        help="Telemetry action"
+    )
+    
+    args = parser.parse_args()
+    
+    # Execute command
+    if args.command == "init":
+        cmd_init(args)
+    elif args.command == "instruct":
+        cmd_instruct(args)
+    elif args.command == "generate":
+        cmd_generate(args)
+    elif args.command == "status":
+        cmd_status(args)
+    elif args.command == "watch":
+        cmd_watch(args)
+    elif args.command == "validate":
+        cmd_validate(args)
+    elif args.command == "check":
+        cmd_check(args)
+    elif args.command == "export":
+        cmd_export(args)
+    elif args.command == "telemetry":
+        cmd_telemetry(args)
+    else:
+        parser.print_help()
+        sys.exit(1)
+
+
+@track_command_execution("init")
+def cmd_init(args):
+    """Initialize VooDocs in a project."""
+    print("🎯 VooDocs Initialization")
+    print("=" * 60)
+    print()
+    
+    try:
+        # Interactive prompts if not provided
+        if not args.project_name:
+            default_name = Path.cwd().name
+            response = input(f"Project name [{default_name}]: ").strip()
+            project_name = response if response else default_name
+        else:
+            project_name = args.project_name
+        
+        if not args.language:
+            print("\nSelect primary language:")
+            print("  1. Python")
+            print("  2. TypeScript")
+            print("  3. JavaScript")
+            response = input("Choice [1]: ").strip()
+            language_map = {"1": "python", "2": "typescript", "3": "javascript", "": "python"}
+            language = language_map.get(response, "python")
+        else:
+            language = args.language
+        
+        print(f"\n📦 Setting up VooDocs for '{project_name}'...")
+        
+        # Create .voodocs directory
+        voodocs_dir = Path(".voodocs")
+        voodocs_dir.mkdir(exist_ok=True)
+        
+        # Create config file with all options
+        config = {
+            "project_name": project_name,
+            "language": language,
+            "version": "0.1.0",
+            "output_dir": "./voodocs-output",
+            "test_framework": "pytest",
+            "api_format": "openapi",
+            "exclude_patterns": [
+                "**/test_*.py",
+                "**/node_modules/**",
+                "**/__pycache__/**",
+                "**/venv/**",
+                "**/.venv/**"
+            ],
+            "include_patterns": [],
+            "annotation_coverage_threshold": 50
+        }
+        
+        import json
+        config_file = voodocs_dir / "config.json"
+        config_file.write_text(json.dumps(config, indent=2))
+        
+        print(f"✓ Created .voodocs/config.json")
+        print(f"✓ Project: {project_name}")
+        print(f"✓ Language: {language}")
+        print()
+        print("Next steps:")
+        print("  1. Run 'voodocs instruct' to generate AI assistant instructions")
+        print("  2. Start coding with @voodocs annotations")
+        print("  3. Run 'voodocs generate <path>' to generate docs and tests")
+    
+    except PermissionError:
+        print("❌ Permission denied: Cannot create .voodocs directory")
+        print("   Check directory permissions and try again.")
+        sys.exit(1)
+    
+    except Exception as e:
+        print(f"❌ Failed to initialize VooDocs: {e}")
+        sys.exit(1)
+
+
+@track_command_execution("instruct")
+def cmd_instruct(args):
+    """Generate AI assistant instructions."""
+    print("📝 Generating AI assistant instructions...")
+    
+    try:
+        # Load config
+        config = load_config()
+        
+        # Detect or use specified assistant
+        assistant = args.assistant
+        if not assistant:
+            generator = InstructionGenerator()
+            assistant = generator.detect_assistant()
+            if assistant:
+                print(f"✓ Detected AI assistant: {assistant}")
+            else:
+                assistant = "generic"
+                print(f"⚠ Could not detect AI assistant, using generic")
+        
+        # Generate instructions
+        generator = InstructionGenerator(
+            assistant=assistant,
+            project_name=config.get("project_name", "Your Project")
+        )
+        
+        output_file = args.output
+        language = args.language or config.get("language", "python")
+        
+        instructions = generator.generate(
+            output_file=output_file,
+            language=language
+        )
+        
+        output_path = output_file or generator.assistant_info["config_file"]
+        
+        print(f"✓ Generated instructions: {output_path}")
+        print(f"✓ File size: {len(instructions):,} characters")
+        print()
+        print(f"Instructions have been generated for {generator.assistant_info['name']}.")
+        print(f"Your AI assistant will now automatically add @voodocs annotations!")
+    
+    except PermissionError as e:
+        print(f"❌ Permission denied: Cannot write to {output_path if 'output_path' in locals() else 'output file'}")
+        print("   Check file permissions and try again.")
+        sys.exit(1)
+    
+    except Exception as e:
+        print(f"❌ Failed to generate instructions: {e}")
+        sys.exit(1)
+
+
+@track_command_execution("generate")
+def cmd_generate(args):
+    """Generate documentation, tests, and API specs from annotations."""
+    print("🚀 VooDocs Generate")
+    print("=" * 60)
+    
+    # Load configuration
+    config = load_config()
+    
+    # Use config values as defaults, CLI args override
+    output_dir_path = args.output_dir if hasattr(args, 'output_dir') and args.output_dir != './voodocs-output' else config.get('output_dir', './voodocs-output')
+    test_framework = args.test_framework if hasattr(args, 'test_framework') else config.get('test_framework', 'pytest')
+    api_format = args.api_format if hasattr(args, 'api_format') else config.get('api_format', 'openapi')
+    
+    # Determine what to generate
+    generate_docs = not (args.tests_only or args.api_only)
+    generate_tests = not (args.docs_only or args.api_only)
+    generate_api = not (args.docs_only or args.tests_only)
+    
+    if args.docs_only:
+        generate_docs = True
+        generate_tests = False
+        generate_api = False
+    elif args.tests_only:
+        generate_docs = False
+        generate_tests = True
+        generate_api = False
+    elif args.api_only:
+        generate_docs = False
+        generate_tests = False
+        generate_api = True
+    
+    print(f"📁 Output directory: {output_dir_path}")
+    print(f"📄 Generate docs: {'✓' if generate_docs else '✗'}")
+    print(f"🧪 Generate tests: {'✓' if generate_tests else '✗'}")
+    print(f"🔌 Generate API specs: {'✓' if generate_api else '✗'}")
+    print()
+    
+    # Create output directory
+    output_dir = Path(output_dir_path)
+    output_dir.mkdir(parents=True, exist_ok=True)
+    
+    # Collect files to process
+    files_to_process = []
+    for path_str in args.paths:
+        path = Path(path_str)
+        if path.is_file():
+            files_to_process.append(path)
+        elif path.is_dir():
+            if args.recursive:
+                # Find all Python/TypeScript files
+                files_to_process.extend(path.rglob("*.py"))
+                files_to_process.extend(path.rglob("*.ts"))
+                files_to_process.extend(path.rglob("*.js"))
+            else:
+                files_to_process.extend(path.glob("*.py"))
+                files_to_process.extend(path.glob("*.ts"))
+                files_to_process.extend(path.glob("*.js"))
+    
+    if not files_to_process:
+        print("❌ No files found to process")
+        sys.exit(1)
+    
+    print(f"📋 Processing {len(files_to_process)} file(s)...")
+    print()
+    
+    # Initialize generators
+    parser = AnnotationParser()
+    doc_generator = DocumentationGenerator() if generate_docs else None
+    test_generator = TestGenerator(framework=args.test_framework) if generate_tests else None
+    api_generator = APISpecGenerator(format=args.api_format) if generate_api else None
+    
+    # Statistics
+    stats = {
+        "files_processed": 0,
+        "files_with_annotations": 0,
+        "total_functions": 0,
+        "total_classes": 0,
+        "docs_generated": 0,
+        "tests_generated": 0,
+        "api_specs_generated": 0
+    }
+    
+    # Process each file
+    for file_path in files_to_process:
+        if args.verbose:
+            print(f"Processing: {file_path}")
+        
+        try:
+            # Parse file
+            parsed = parser.parse_file(str(file_path))
+            stats["files_processed"] += 1
+            
+            if not parsed.has_annotations():
+                if args.verbose:
+                    print(f"  ⚠ No annotations found")
+                continue
+            
+            stats["files_with_annotations"] += 1
+            stats["total_functions"] += len(parsed.get_all_functions())
+            stats["total_classes"] += len(parsed.module.classes)
+            
+            # Generate relative output path
+            rel_path = file_path.stem
+            
+            # Generate documentation
+            if generate_docs:
+                doc_output = output_dir / "docs" / f"{rel_path}.md"
+                doc_output.parent.mkdir(parents=True, exist_ok=True)
+                doc_generator.generate(parsed, str(doc_output))
+                stats["docs_generated"] += 1
+                if args.verbose:
+                    print(f"  ✓ Documentation: {doc_output}")
+            
+            # Generate tests
+            if generate_tests:
+                test_output = output_dir / "tests" / f"test_{rel_path}.py"
+                test_output.parent.mkdir(parents=True, exist_ok=True)
+                test_generator.generate(parsed, str(test_output))
+                stats["tests_generated"] += 1
+                if args.verbose:
+                    print(f"  ✓ Tests: {test_output}")
+            
+            # Generate API spec
+            if generate_api:
+                api_ext = ".yaml" if args.api_format in ["openapi", "swagger"] else ".graphql"
+                api_output = output_dir / "api" / f"{rel_path}{api_ext}"
+                api_output.parent.mkdir(parents=True, exist_ok=True)
+                api_generator.generate(parsed, str(api_output))
+                stats["api_specs_generated"] += 1
+                if args.verbose:
+                    print(f"  ✓ API Spec: {api_output}")
+        
+        except ParserNotBuiltError as e:
+            print(f"\n❌ {e}")
+            print(f"\nThe TypeScript parser requires building before use.")
+            print(f"Please run the following commands:")
+            print(f"  cd {Path(__file__).parent / 'lib/darkarts/parsers/typescript'}")
+            print(f"  npm install")
+            print(f"  npm run build")
+            sys.exit(1)
+        
+        except FileNotFoundError as e:
+            print(f"  ❌ File not found: {file_path}")
+            if args.debug:
+                traceback.print_exc()
+            continue
+        
+        except SyntaxError as e:
+            print(f"  ❌ Syntax error in {file_path.name}: {e}")
+            if args.debug:
+                traceback.print_exc()
+            continue
+        
+        except AnnotationError as e:
+            print(f"  ❌ Annotation error in {file_path.name}: {e}")
+            if args.debug:
+                traceback.print_exc()
+            continue
+        
+        except GeneratorError as e:
+            print(f"  ❌ Generator error for {file_path.name}: {e}")
+            if args.debug:
+                traceback.print_exc()
+            continue
+        
+        except PermissionError:
+            print(f"  ❌ Permission denied: {file_path}")
+            print(f"     Check file permissions and try again.")
+            continue
+        
+        except Exception as e:
+            print(f"  ❌ Unexpected error in {file_path.name}: {e}")
+            print(f"     Run with --debug for full stack trace.")
+            if args.debug:
+                traceback.print_exc()
+            continue
+    
+    # Print summary
+    print()
+    print("=" * 60)
+    print("📊 Generation Summary")
+    print("=" * 60)
+    print(f"Files processed:        {stats['files_processed']}")
+    print(f"Files with annotations: {stats['files_with_annotations']}")
+    print(f"Total functions:        {stats['total_functions']}")
+    print(f"Total classes:          {stats['total_classes']}")
+    print()
+    if generate_docs:
+        print(f"✓ Documentation files:  {stats['docs_generated']}")
+    if generate_tests:
+        print(f"✓ Test files:           {stats['tests_generated']}")
+    if generate_api:
+        print(f"✓ API specs:            {stats['api_specs_generated']}")
+    print()
+    print(f"✨ All outputs saved to: {output_dir}")
+
+
+@track_command_execution("status")
+def cmd_status(args):
+    """Show project status and statistics."""
+    print("📊 VooDocs Project Status")
+    print("=" * 60)
+    
+    # Collect files
+    files = []
+    for path_str in args.paths:
+        path = Path(path_str)
+        if path.is_file():
+            files.append(path)
+        elif path.is_dir():
+            files.extend(path.rglob("*.py"))
+            files.extend(path.rglob("*.ts"))
+            files.extend(path.rglob("*.js"))
+    
+    if not files:
+        print("❌ No files found")
+        sys.exit(1)
+    
+    # Parse and analyze
+    parser = AnnotationParser()
+    stats = {
+        "total_files": len(files),
+        "files_with_annotations": 0,
+        "total_functions": 0,
+        "annotated_functions": 0,
+        "total_classes": 0,
+        "annotated_classes": 0,
+        "annotation_fields": {
+            "preconditions": 0,
+            "postconditions": 0,
+            "complexity": 0,
+            "error_cases": 0,
+            "security_implications": 0
+        }
+    }
+    
+    for file_path in files:
+        try:
+            parsed = parser.parse_file(str(file_path))
+            
+            if parsed.has_annotations():
+                stats["files_with_annotations"] += 1
+            
+            all_functions = parsed.get_all_functions()
+            stats["total_functions"] += len(all_functions)
+            
+            for func in all_functions:
+                if func.preconditions or func.postconditions:
+                    stats["annotated_functions"] += 1
+                if func.preconditions:
+                    stats["annotation_fields"]["preconditions"] += 1
+                if func.postconditions:
+                    stats["annotation_fields"]["postconditions"] += 1
+                if func.complexity:
+                    stats["annotation_fields"]["complexity"] += 1
+                if func.error_cases:
+                    stats["annotation_fields"]["error_cases"] += 1
+                if func.security_implications:
+                    stats["annotation_fields"]["security_implications"] += 1
+            
+            stats["total_classes"] += len(parsed.module.classes)
+            for cls in parsed.module.classes:
+                if cls.class_invariants or cls.state_transitions:
+                    stats["annotated_classes"] += 1
+        
+        except Exception:
+            pass
+    
+    # Calculate percentages
+    func_coverage = (stats["annotated_functions"] / stats["total_functions"] * 100) if stats["total_functions"] > 0 else 0
+    class_coverage = (stats["annotated_classes"] / stats["total_classes"] * 100) if stats["total_classes"] > 0 else 0
+    file_coverage = (stats["files_with_annotations"] / stats["total_files"] * 100) if stats["total_files"] > 0 else 0
+    
+    # Calculate quality score (0-100)
+    quality_score = _calculate_quality_score(stats)
+    quality_grade = _get_quality_grade(quality_score)
+    
+    # Print stats with visual indicators
+    print(f"Total files:            {stats['total_files']}")
+    print(f"Files with annotations: {stats['files_with_annotations']} {_coverage_bar(file_coverage)}")
+    print()
+    print(f"Total functions:        {stats['total_functions']}")
+    print(f"Annotated functions:    {stats['annotated_functions']} {_coverage_bar(func_coverage)}")
+    print()
+    print(f"Total classes:          {stats['total_classes']}")
+    print(f"Annotated classes:      {stats['annotated_classes']} {_coverage_bar(class_coverage)}")
+    print()
+    print("Annotation Field Usage:")
+    for field, count in stats["annotation_fields"].items():
+        percentage = (count / stats['total_functions'] * 100) if stats['total_functions'] > 0 else 0
+        print(f"  {field:25} {count:3} ({percentage:5.1f}%)")
+    print()
+    
+    # Quality Score
+    print("📈 Documentation Quality")
+    print("=" * 60)
+    print(f"Overall Score: {quality_score:.1f}/100 {quality_grade}")
+    print(f"Coverage:      {func_coverage:.1f}% {_coverage_bar(func_coverage)}")
+    print()
+    
+    # Detailed breakdown
+    print("Quality Breakdown:")
+    print(f"  Coverage Score:     {_coverage_score(func_coverage):.1f}/40")
+    print(f"  Completeness Score: {_completeness_score(stats):.1f}/30")
+    print(f"  Richness Score:     {_richness_score(stats):.1f}/30")
+    print()
+    
+    # Recommendations
+    if quality_score < 50:
+        print("💡 Recommendations:")
+        print("   • Run 'voodocs instruct' to help your AI assistant add annotations")
+        print("   • Focus on adding preconditions and postconditions first")
+        print("   • Add complexity annotations to performance-critical functions")
+    elif quality_score < 70:
+        print("💡 Good progress! To improve further:")
+        print("   • Add error_cases to functions that can fail")
+        print("   • Document security_implications for sensitive functions")
+        print("   • Aim for 80%+ annotation coverage")
+    elif quality_score < 90:
+        print("🎉 Great work! Your documentation is solid.")
+        print("   • Consider adding more detailed error cases")
+        print("   • Document edge cases and security considerations")
+    else:
+        print("✨ Excellent! Your codebase is exceptionally well-documented with VooDocs.")
+
+
+def _calculate_quality_score(stats):
+    """Calculate overall documentation quality score (0-100)."""
+    total_funcs = stats['total_functions']
+    if total_funcs == 0:
+        return 0
+    
+    # Coverage score (40 points)
+    coverage = (stats['annotated_functions'] / total_funcs) * 40
+    
+    # Completeness score (30 points) - how many have both pre and post
+    completeness = _completeness_score(stats)
+    
+    # Richness score (30 points) - usage of advanced fields
+    richness = _richness_score(stats)
+    
+    return min(100, coverage + completeness + richness)
+
+
+def _coverage_score(coverage_pct):
+    """Calculate coverage score (0-40)."""
+    return min(40, coverage_pct * 0.4)
+
+
+def _completeness_score(stats):
+    """Calculate completeness score (0-30)."""
+    total_funcs = stats['total_functions']
+    if total_funcs == 0:
+        return 0
+    
+    # Functions with both preconditions and postconditions
+    pre = stats['annotation_fields']['preconditions']
+    post = stats['annotation_fields']['postconditions']
+    complete = min(pre, post)
+    
+    return (complete / total_funcs) * 30
+
+
+def _richness_score(stats):
+    """Calculate richness score (0-30)."""
+    total_funcs = stats['total_functions']
+    if total_funcs == 0:
+        return 0
+    
+    # Advanced fields: complexity, error_cases, security_implications
+    complexity = stats['annotation_fields']['complexity']
+    errors = stats['annotation_fields']['error_cases']
+    security = stats['annotation_fields']['security_implications']
+    
+    richness = (complexity + errors + security) / (total_funcs * 3) * 30
+    return min(30, richness)
+
+
+def _get_quality_grade(score):
+    """Get letter grade for quality score."""
+    if score >= 90:
+        return "🏆 A+"
+    elif score >= 80:
+        return "🥇 A"
+    elif score >= 70:
+        return "🥈 B"
+    elif score >= 60:
+        return "🥉 C"
+    elif score >= 50:
+        return "📝 D"
+    else:
+        return "❌ F"
+
+
+def _coverage_bar(percentage):
+    """Generate a visual coverage bar."""
+    filled = int(percentage / 5)  # 20 blocks for 100%
+    empty = 20 - filled
+    
+    bar = "█" * filled + "░" * empty
+    
+    if percentage >= 80:
+        color = "🟢"
+    elif percentage >= 50:
+        color = "🟡"
+    else:
+        color = "🔴"
+    
+    return f"{color} [{bar}] {percentage:.1f}%"
+
+
+def load_config():
+    """Load VooDocs configuration."""
+    config_file = Path(".voodocs/config.json")
+    
+    # Default configuration
+    default_config = {
+        "project_name": Path.cwd().name,
+        "language": "python",
+        "version": "0.1.0",
+        "output_dir": "./voodocs-output",
+        "test_framework": "pytest",
+        "api_format": "openapi",
+        "exclude_patterns": [
+            "**/test_*.py",
+            "**/node_modules/**",
+            "**/__pycache__/**",
+            "**/venv/**",
+            "**/.venv/**"
+        ],
+        "include_patterns": [],
+        "annotation_coverage_threshold": 50
+    }
+    
+    if config_file.exists():
+        import json
+        try:
+            user_config = json.loads(config_file.read_text())
+            # Merge user config with defaults
+            default_config.update(user_config)
+        except json.JSONDecodeError:
+            print("⚠ Warning: Invalid config file, using defaults")
+    
+    return default_config
+
+
+@track_command_execution("watch")
+def cmd_watch(args):
+    """Watch files and automatically regenerate documentation."""
+    import time
+    import hashlib
+    
+    print("👀 VooDocs Watch Mode")
+    print("=" * 60)
+    print(f"📁 Watching: {', '.join(args.paths)}")
+    print(f"📁 Output directory: {args.output_dir}")
+    print(f"⏱️  Check interval: {args.interval}s")
+    print("\nPress Ctrl+C to stop watching...\n")
+    
+    # Track file modification times and hashes
+    file_states = {}
+    
+    def get_file_hash(filepath):
+        """Get MD5 hash of file content."""
+        try:
+            with open(filepath, 'rb') as f:
+                return hashlib.md5(f.read()).hexdigest()
+        except Exception:
+            return None
+    
+    def collect_files(paths):
+        """Collect all relevant files from paths."""
+        files = []
+        for path_str in paths:
+            path = Path(path_str)
+            if path.is_file():
+                if path.suffix in ['.py', '.ts', '.js', '.tsx', '.jsx']:
+                    files.append(path)
+            elif path.is_dir():
+                for ext in ['.py', '.ts', '.js', '.tsx', '.jsx']:
+                    files.extend(path.rglob(f'*{ext}'))
+        return files
+    
+    def regenerate(changed_files):
+        """Regenerate documentation for changed files."""
+        print(f"\n🔄 Changes detected in {len(changed_files)} file(s):")
+        for f in changed_files:
+            print(f"  - {f}")
+        
+        print("\n🚀 Regenerating...")
+        
+        # Create a mock args object for cmd_generate
+        class GenerateArgs:
+            pass
+        
+        gen_args = GenerateArgs()
+        gen_args.paths = [str(f) for f in changed_files]
+        gen_args.output_dir = args.output_dir
+        gen_args.docs_only = args.docs_only
+        gen_args.tests_only = args.tests_only
+        gen_args.api_only = args.api_only
+        gen_args.verbose = False
+        gen_args.debug = False
+        
+        try:
+            cmd_generate(gen_args)
+            print(f"✅ Regeneration complete at {time.strftime('%H:%M:%S')}\n")
+        except Exception as e:
+            print(f"❌ Error during regeneration: {e}\n")
+    
+    try:
+        # Initial scan
+        all_files = collect_files(args.paths)
+        print(f"📋 Watching {len(all_files)} file(s)...\n")
+        
+        for filepath in all_files:
+            file_states[str(filepath)] = get_file_hash(filepath)
+        
+        # Watch loop
+        while True:
+            time.sleep(args.interval)
+            
+            # Check for changes
+            changed_files = []
+            current_files = collect_files(args.paths)
+            
+            for filepath in current_files:
+                filepath_str = str(filepath)
+                current_hash = get_file_hash(filepath)
+                
+                # New file or modified file
+                if filepath_str not in file_states or file_states[filepath_str] != current_hash:
+                    changed_files.append(filepath)
+                    file_states[filepath_str] = current_hash
+            
+            # Check for deleted files
+            current_file_strs = {str(f) for f in current_files}
+            deleted_files = [f for f in file_states.keys() if f not in current_file_strs]
+            
+            if deleted_files:
+                print(f"\n🗑️  Deleted file(s):")
+                for f in deleted_files:
+                    print(f"  - {f}")
+                    del file_states[f]
+                print()
+            
+            # Regenerate if changes detected
+            if changed_files:
+                regenerate(changed_files)
+    
+    except KeyboardInterrupt:
+        print("\n\n👋 Watch mode stopped.")
+        sys.exit(0)
+    except Exception as e:
+        print(f"\n❌ Watch mode error: {e}")
+        if args.debug:
+            traceback.print_exc()
+        sys.exit(1)
+
+
+@track_command_execution("validate")
+def cmd_validate(args):
+    """Validate annotation quality and correctness."""
+    import json
+    
+    print("🔍 VooDocs Validate")
+    print("=" * 60)
+    
+    # Collect files
+    files = []
+    for path_str in args.paths:
+        path = Path(path_str)
+        if path.is_file():
+            files.append(path)
+        elif path.is_dir():
+            files.extend(path.rglob("*.py"))
+            files.extend(path.rglob("*.ts"))
+            files.extend(path.rglob("*.js"))
+    
+    if not files:
+        print("❌ No files found")
+        sys.exit(1)
+    
+    print(f"📋 Validating {len(files)} file(s)...\n")
+    
+    # Validate each file
+    parser = AnnotationParser()
+    validator = AnnotationValidator()
+    all_issues = []
+    files_with_issues = 0
+    
+    for file_path in files:
+        try:
+            parsed = parser.parse_file(str(file_path))
+            issues = validator.validate(parsed)
+            
+            if issues:
+                files_with_issues += 1
+                all_issues.extend(issues)
+                
+                if args.format == "text":
+                    print(f"\n📄 {file_path}")
+                    print("-" * 60)
+                    for issue in issues:
+                        print(f"  {issue}")
+        
+        except Exception as e:
+            if args.format == "text":
+                print(f"\n📄 {file_path}")
+                print(f"  ❌ [ERROR] Failed to parse: {e}")
+            all_issues.append({
+                "severity": "error",
+                "message": f"Failed to parse: {e}",
+                "location": str(file_path)
+            })
+    
+    # Print summary
+    if args.format == "text":
+        print("\n" + "=" * 60)
+        print("📊 Validation Summary")
+        print("=" * 60)
+        
+        summary = validator.get_summary()
+        print(f"Files validated:        {len(files)}")
+        print(f"Files with issues:      {files_with_issues}")
+        print(f"Total issues:           {summary['total']}")
+        print(f"  Errors:               {summary['errors']}")
+        print(f"  Warnings:             {summary['warnings']}")
+        print(f"  Info:                 {summary['info']}")
+        print()
+        
+        # Exit code
+        if validator.has_errors():
+            print("❌ Validation failed with errors")
+            sys.exit(1)
+        elif args.strict and summary['warnings'] > 0:
+            print("❌ Validation failed (strict mode: warnings treated as errors)")
+            sys.exit(1)
+        elif summary['total'] > 0:
+            print("⚠️  Validation passed with warnings")
+            sys.exit(0)
+        else:
+            print("✅ Validation passed!")
+            sys.exit(0)
+    
+    else:  # JSON format
+        output = {
+            "files_validated": len(files),
+            "files_with_issues": files_with_issues,
+            "summary": validator.get_summary(),
+            "issues": [
+                {
+                    "severity": issue.severity,
+                    "message": issue.message,
+                    "location": issue.location,
+                    "suggestion": issue.suggestion
+                }
+                for issue in all_issues
+            ]
+        }
+        print(json.dumps(output, indent=2))
+        
+        # Exit code
+        if validator.has_errors():
+            sys.exit(1)
+        elif args.strict and validator.get_summary()['warnings'] > 0:
+            sys.exit(1)
+        else:
+            sys.exit(0)
+
+
+
+
+@track_command_execution("check")
+def cmd_check(args):
+    """Check annotation coverage and quality (for CI/CD)."""
+    print("🔍 VooDocs Check (CI/CD Mode)")
+    print("=" * 60)
+    
+    # Collect files
+    files = []
+    for path_str in args.paths:
+        path = Path(path_str)
+        if path.is_file():
+            files.append(path)
+        elif path.is_dir():
+            files.extend(path.rglob("*.py"))
+            files.extend(path.rglob("*.ts"))
+            files.extend(path.rglob("*.js"))
+    
+    if not files:
+        print("❌ No files found")
+        sys.exit(1)
+    
+    print(f"📋 Checking {len(files)} file(s)...\n")
+    
+    # Parse all files and calculate metrics
+    parser = AnnotationParser()
+    validator = AnnotationValidator()
+    
+    total_functions = 0
+    annotated_functions = 0
+    total_files = len(files)
+    files_with_annotations = 0
+    all_issues = []
+    
+    for file_path in files:
+        try:
+            parsed = parser.parse_file(str(file_path))
+            functions = parsed.get_all_functions()
+            total_functions += len(functions)
+            
+            # Count annotated functions
+            for func in functions:
+                if func.preconditions or func.postconditions:
+                    annotated_functions += 1
+            
+            # Check if file has any annotations
+            if parsed.module.module_purpose or functions:
+                files_with_annotations += 1
+            
+            # Validate
+            issues = validator.validate(parsed)
+            all_issues.extend(issues)
+        
+        except Exception as e:
+            print(f"⚠️  Failed to parse {file_path}: {e}")
+    
+    # Calculate coverage
+    function_coverage = (annotated_functions / total_functions * 100) if total_functions > 0 else 0
+    file_coverage = (files_with_annotations / total_files * 100) if total_files > 0 else 0
+    
+    # Calculate quality score (same as status command)
+    summary = validator.get_summary()
+    coverage_score = function_coverage * 0.4  # 40 points
+    completeness_score = max(0, 30 - summary['warnings'] * 2)  # 30 points, -2 per warning
+    richness_score = max(0, 30 - summary['info'])  # 30 points, -1 per info
+    quality_score = coverage_score + completeness_score + richness_score
+    
+    # Print results
+    print("📊 Results")
+    print("=" * 60)
+    print(f"Files checked:          {total_files}")
+    print(f"Files with annotations: {files_with_annotations} ({file_coverage:.1f}%)")
+    print(f"Functions checked:      {total_functions}")
+    print(f"Annotated functions:    {annotated_functions} ({function_coverage:.1f}%)")
+    print(f"Quality score:          {quality_score:.1f}/100")
+    print()
+    print(f"Validation issues:")
+    print(f"  Errors:               {summary['errors']}")
+    print(f"  Warnings:             {summary['warnings']}")
+    print(f"  Info:                 {summary['info']}")
+    print()
+    
+    # Check thresholds
+    failed = False
+    
+    if function_coverage < args.min_coverage:
+        print(f"❌ Coverage check failed: {function_coverage:.1f}% < {args.min_coverage}%")
+        failed = True
+    else:
+        print(f"✅ Coverage check passed: {function_coverage:.1f}% >= {args.min_coverage}%")
+    
+    if quality_score < args.min_quality:
+        print(f"❌ Quality check failed: {quality_score:.1f} < {args.min_quality}")
+        failed = True
+    else:
+        print(f"✅ Quality check passed: {quality_score:.1f} >= {args.min_quality}")
+    
+    if validator.has_errors():
+        print(f"❌ Validation failed: {summary['errors']} error(s) found")
+        failed = True
+    else:
+        print(f"✅ Validation passed: No errors")
+    
+    print()
+    
+    if failed:
+        print("❌ Check failed")
+        sys.exit(1)
+    else:
+        print("✅ All checks passed!")
+        sys.exit(0)
+
+
+
+@track_command_execution("export")
+def cmd_export(args):
+    """Export documentation to different formats."""
+    print(f"📤 Exporting to {args.format.upper()}...")
+    
+    try:
+        if args.format == "html":
+            exporter = HTMLExporter()
+            output_file = exporter.export(args.input_file, args.output)
+            print(f"✅ HTML exported to: {output_file}")
+        
+        elif args.format == "pdf":
+            exporter = PDFExporter()
+            output_file = exporter.export(args.input_file, args.output)
+            print(f"✅ PDF exported to: {output_file}")
+    
+    except FileNotFoundError as e:
+        print(f"❌ Error: {e}")
+        sys.exit(1)
+    
+    except ImportError as e:
+        print(f"❌ Error: {e}")
+        sys.exit(1)
+    
+    except Exception as e:
+        print(f"❌ Export failed: {e}")
+        sys.exit(1)
+
+
+def cmd_telemetry(args):
+    """Manage telemetry settings."""
+    client = get_telemetry_client()
+    
+    if args.action == "enable":
+        client.enable()
+    elif args.action == "disable":
+        client.disable()
+    elif args.action == "status":
+        client.status()
+
+
+if __name__ == "__main__":
+    main()