crackerjack 0.18.2__py3-none-any.whl → 0.45.2__py3-none-any.whl

crackerjack/cli/README.md

@@ -0,0 +1,394 @@
+> Crackerjack Docs: [Main](<../../README.md>) | [CLAUDE.md](../../docs/guides/CLAUDE.md) | [CLI](<./README.md>)
+
+# CLI
+
+Command-line interface handlers and option processing for the Crackerjack CLI using Click and Typer frameworks.
+
+## Overview
+
+The CLI package provides the primary user interface for Crackerjack, handling command-line arguments, option validation, and routing to appropriate backend handlers. It follows a modular handler-based architecture with 90% ACB compliance, using protocol-based dependency injection for most components.
+
+## Architecture
+
+### Entry Point Flow
+
+```
+python -m crackerjack [options]
+    ↓
+__main__.py
+    ↓
+options.py (Option parsing & validation)
+    ↓
+handlers/ (Specialized command handlers)
+    ↓
+Managers/Orchestration (Backend coordination)
+```
+
+### Core Components
+
+- **options.py**: CLI option definitions, validation, and parsing using Pydantic models
+- **handlers.py**: Main command handlers for quality workflows
+- **facade.py**: CLI facade for simplified command routing
+- **interactive.py**: Interactive mode for guided workflows
+- **utils.py**: CLI utility functions
+
+### Handler Modules
+
+**handlers/** — Specialized command handlers by feature:
+
+- **main_handlers.py**: Core quality workflow execution (fast, comprehensive, tests)
+- **analytics.py**: Coverage analytics, metrics, and reporting
+- **monitoring.py**: Health monitoring, watchdog, and status checks
+- **documentation.py**: Documentation generation and changelog automation
+- **changelog.py**: Changelog management and versioning
+- **coverage.py**: Coverage ratchet and improvement workflows
+- **ai_features.py**: AI agent integration and auto-fixing
+- **advanced.py**: Advanced features and experimental workflows
+- **config_handlers.py**: Configuration management and initialization
+
+### Cache Handlers
+
+- **cache_handlers.py**: Basic cache management operations
+- **cache_handlers_enhanced.py**: Advanced cache operations with pattern analysis
+- **semantic_handlers.py**: Semantic search and code comprehension handlers
+
+## Command Categories
+
+### Quality Workflows
+
+```bash
+# Fast hooks (~5s)
+python -m crackerjack --fast
+
+# Comprehensive hooks (~30s)
+python -m crackerjack --comp
+
+# Full quality + tests
+python -m crackerjack --run-tests
+
+# AI-powered auto-fixing
+python -m crackerjack --ai-fix --run-tests
+```
+
+### Publishing & Versioning
+
+```bash
+# Interactive versioning
+python -m crackerjack --publish interactive
+
+# Automated bump
+python -m crackerjack --publish patch  # or minor, major, auto
+
+# Full release workflow
+python -m crackerjack --all patch
+```
+
+### MCP Server Management
+
+```bash
+# Start MCP server
+python -m crackerjack --start-mcp-server
+
+# Restart server
+python -m crackerjack --restart-mcp-server
+
+# Health monitoring
+python -m crackerjack --watchdog
+```
+
+### Coverage & Analytics
+
+```bash
+# Coverage report
+python -m crackerjack --coverage-report
+
+# Analytics dashboard
+python -m crackerjack --analytics
+
+# Benchmark performance
+python -m crackerjack --benchmark
+```
+
+### Development Modes
+
+```bash
+# Fast iteration (skip comprehensive hooks)
+python -m crackerjack --fast-iteration
+
+# Run specific tool only
+python -m crackerjack --tool ruff
+
+# Changed files only
+python -m crackerjack --changed-only
+
+# Debug mode
+python -m crackerjack --debug --verbose
+```
+
+## Option Processing
+
+### Option Validation
+
+The `Options` Pydantic model provides type-safe option parsing with validation:
+
+```python
+from crackerjack.cli.options import Options, BumpOption
+
+# Parse and validate options
+options = Options(run_tests=True, ai_fix=True, test_workers=4, publish=BumpOption.patch)
+```
+
+### Bump Options
+
+Versioning options with enum validation:
+
+- **patch**: 1.0.0 → 1.0.1 (bug fixes)
+- **minor**: 1.0.0 → 1.1.0 (new features)
+- **major**: 1.0.0 → 2.0.0 (breaking changes)
+- **interactive**: Guided version selection
+- **auto**: AI-powered version recommendation
+
+### Test Workers
+
+Parallel test execution configuration:
+
+```bash
+--test-workers 0   # Auto-detect (default, recommended)
+--test-workers 4   # Explicit worker count
+--test-workers 1   # Sequential execution (debugging)
+--test-workers -2  # Fractional (half cores)
+```
+
+## Handler Architecture
+
+### Protocol-Based Dependency Injection
+
+Most handlers use ACB dependency injection (90% compliance):
+
+```python
+from acb.depends import depends, Inject
+from crackerjack.models.protocols import Console, CrackerjackCache
+
+
+@depends.inject
+def handle_quality_check(
+    console: Inject[Console] = None,
+    cache: Inject[CrackerjackCache] = None,
+) -> None:
+    console.print("[green]Running quality checks...[/green]")
+    # ... handler logic
+```
+
+### Handler Routing
+
+Handlers are organized by feature domain for maintainability:
+
+```python
+# Main quality workflows
+from crackerjack.cli.handlers.main_handlers import (
+    handle_fast_hooks,
+    handle_comprehensive_hooks,
+    handle_tests,
+)
+
+# Analytics and reporting
+from crackerjack.cli.handlers.analytics import (
+    handle_coverage_report,
+    handle_analytics_dashboard,
+)
+
+# MCP server management
+from crackerjack.cli.handlers.monitoring import (
+    handle_start_mcp_server,
+    handle_watchdog,
+)
+```
+
+## Interactive Mode
+
+Guided workflows with prompts and validation:
+
+```bash
+python -m crackerjack --interactive
+```
+
+**Features:**
+
+- Step-by-step guidance
+- Option validation with helpful errors
+- Confirmation prompts for destructive actions
+- Progress indicators for long operations
+
+## Facade Pattern
+
+The `CrackerjackCLIFacade` provides simplified command routing:
+
+```python
+from crackerjack.cli.facade import CrackerjackCLIFacade
+
+facade = CrackerjackCLIFacade()
+result = await facade.run_quality_workflow(fast=True, ai_fix=True, verbose=True)
+```
+
+**Note:** Facade needs DI integration (currently manual instantiation).
+
+## Usage Examples
+
+### Adding a New CLI Option
+
+```python
+# 1. Add to Options model (options.py)
+class Options(BaseModel):
+    my_new_option: bool = False
+
+
+# 2. Add Click/Typer parameter (__main__.py)
+@click.option("--my-new-option", is_flag=True, help="Enable new feature")
+# 3. Create handler (handlers/my_feature.py)
+@depends.inject
+def handle_my_feature(console: Inject[Console] = None) -> None:
+    console.print("[cyan]Running new feature...[/cyan]")
+
+
+# 4. Route in main (__main__.py)
+if options.my_new_option:
+    handle_my_feature()
+```
+
+### Adding a New Handler Module
+
+```python
+# handlers/my_handlers.py
+from acb.depends import depends, Inject
+from crackerjack.models.protocols import Console
+
+
+@depends.inject
+async def handle_my_command(
+    arg1: str,
+    console: Inject[Console] = None,
+) -> bool:
+    """Handler for my custom command."""
+    console.print(f"Processing: {arg1}")
+    # ... implementation
+    return True
+```
+
+## Best Practices
+
+1. **Use Protocol-Based DI**: Import from `models/protocols.py`, not concrete classes
+1. **Validate Options Early**: Use Pydantic validators in the `Options` model
+1. **Keep Handlers Focused**: Single responsibility per handler
+1. **Provide User Feedback**: Use rich console for progress and status
+1. **Handle Errors Gracefully**: Catch exceptions and provide helpful error messages
+1. **Support --verbose**: Add verbose logging for troubleshooting
+1. **Document Options**: Clear help text for all CLI options
+1. **Test Interactive Flows**: Verify prompts and validation work correctly
+
+## Anti-Patterns to Avoid
+
+```python
+# ❌ Direct console instantiation
+from rich.console import Console
+console = Console()
+
+# ✅ Use dependency injection
+@depends.inject
+def handler(console: Inject[Console] = None):
+    console.print("...")
+
+
+# ❌ Complex logic in option parsing
+@click.option("--complex")
+def command(complex):
+    if complex:
+        # 50 lines of logic here
+
+# ✅ Delegate to handlers
+@click.option("--complex")
+def command(complex):
+    if complex:
+        handle_complex_workflow()
+
+
+# ❌ Silent failures
+def handler():
+    try:
+        risky_operation()
+    except Exception:
+        pass  # Don't do this!
+
+# ✅ Inform the user
+def handler():
+    try:
+        risky_operation()
+    except Exception as e:
+        console.print(f"[red]Error: {e}[/red]")
+        raise
+```
+
+## Configuration
+
+CLI behavior can be customized via `settings/crackerjack.yaml`:
+
+```yaml
+# CLI defaults
+verbose: false
+interactive: false
+test_workers: 0  # Auto-detect
+debug: false
+ai_debug: false
+
+# Feature flags
+experimental_hooks: false
+async_mode: true
+```
+
+## Troubleshooting
+
+### Option Parsing Issues
+
+```bash
+# Enable debug mode for detailed output
+python -m crackerjack --debug --verbose
+
+# Check option values
+python -m crackerjack --help
+```
+
+### Handler Failures
+
+```bash
+# Use verbose mode for detailed logs
+python -m crackerjack --verbose --run-tests
+
+# Enable AI debugging for agent issues
+python -m crackerjack --ai-debug --ai-fix
+```
+
+### Test Worker Configuration
+
+```bash
+# Sequential execution for debugging flaky tests
+python -m crackerjack --run-tests --test-workers 1
+
+# Disable auto-detection globally
+export CRACKERJACK_DISABLE_AUTO_WORKERS=1
+```
+
+## Related
+
+- [Managers](<../managers/README.md>) — Backend managers called by CLI handlers
+- [Orchestration](<../orchestration/README.md>) — Workflow orchestration layer
+- [Options](<./options.py>) — Full list of CLI options
+- [Main README](<../../README.md>) — Command examples and workflows
+- [CLAUDE.md](../../docs/guides/CLAUDE.md) — Essential commands reference
+
+## Future Enhancements
+
+- [ ] Complete DI integration for CrackerjackCLIFacade
+- [ ] Plugin system for custom commands
+- [ ] Command auto-completion (shell integration)
+- [ ] Configuration profiles (dev, ci, production)
+- [ ] Command aliasing and shortcuts
+- [ ] Enhanced interactive mode with TUI

crackerjack/cli/__init__.py

@@ -0,0 +1,24 @@
+from .handlers import (
+    handle_interactive_mode,
+    handle_monitor_mode,
+    handle_orchestrated_mode,
+    handle_standard_mode,
+    handle_watchdog_mode,
+    setup_ai_agent_env,
+)
+from .options import CLI_OPTIONS, BumpOption, Options, create_options
+from .version import get_package_version
+
+__all__ = [
+    "CLI_OPTIONS",
+    "BumpOption",
+    "Options",
+    "create_options",
+    "get_package_version",
+    "handle_interactive_mode",
+    "handle_monitor_mode",
+    "handle_orchestrated_mode",
+    "handle_standard_mode",
+    "handle_watchdog_mode",
+    "setup_ai_agent_env",
+]

crackerjack/cli/cache_handlers.py

@@ -0,0 +1,209 @@
+import typing as t
+
+from acb.console import Console
+from acb.depends import Inject, depends
+from rich.panel import Panel
+from rich.table import Table
+from rich.text import Text
+
+from crackerjack.services.cache import CrackerjackCache
+
+
+@depends.inject  # type: ignore[misc]
+def handle_clear_cache(console: Inject[Console]) -> None:
+    """Clear all caches and display results."""
+    try:
+        cache = CrackerjackCache()
+
+        # Clear memory caches and get cleanup stats
+        cleanup_results = cache.cleanup_all()
+
+        # Note:CrackerjackCache uses memory-only caching (no disk cache to clear)
+
+        # Calculate total items cleared
+        total_cleared = sum(cleanup_results.values())
+
+        # Create results table
+        table = Table(
+            title="Cache Cleared", show_header=True, header_style="bold green"
+        )
+        table.add_column("Cache Type", style="cyan", no_wrap=True)
+        table.add_column("Items Cleared", justify="right", style="yellow")
+
+        for cache_type, count in cleanup_results.items():
+            table.add_row(cache_type.replace("_", " ").title(), str(count))
+
+        table.add_row("", "", end_section=True)
+        table.add_row("Total", str(total_cleared), style="bold green")
+
+        console.print()
+        console.print(Panel(table, title="Cache Cleared", border_style="green"))
+        console.print(f"\n✅ Successfully cleared {total_cleared} cache entries")
+
+    except Exception as e:
+        console.print(f"\n❌ Error clearing cache: {e}", style="bold red")
+
+
+@depends.inject  # type: ignore[misc]
+def handle_cache_stats(console: Inject[Console]) -> None:
+    """Display detailed cache statistics."""
+    try:
+        cache = CrackerjackCache()
+        stats = cache.get_cache_stats()
+
+        main_table = _create_cache_stats_table()
+        totals = _populate_cache_stats_table(main_table, stats)
+        _add_cache_totals_row(main_table, totals)
+
+        console.print()
+        console.print(Panel(main_table, border_style="blue"))
+
+        _display_performance_insights(totals)
+        _display_cache_directory_info(cache)
+
+    except Exception as e:
+        console.print(f"\n❌ Error retrieving cache stats: {e}", style="bold red")
+
+
+def _create_cache_stats_table() -> Table:
+    """Create and configure the main cache statistics table."""
+    table = Table(title="Cache Statistics", show_header=True, header_style="bold blue")
+    table.add_column("Cache Layer", style="cyan", no_wrap=True)
+    table.add_column("Hit Rate %", justify="right", style="green")
+    table.add_column("Hits", justify="right", style="yellow")
+    table.add_column("Misses", justify="right", style="red")
+    table.add_column("Entries", justify="right", style="magenta")
+    table.add_column("Size (MB)", justify="right", style="blue")
+    return table
+
+
+def _populate_cache_stats_table(
+    table: Table, stats: dict[str, t.Any]
+) -> dict[str, t.Any]:
+    """Populate table with cache statistics and return totals."""
+    totals = {"hits": 0, "misses": 0, "entries": 0, "size": 0.0}
+
+    for cache_name, cache_stats in stats.items():
+        hit_rate = cache_stats.get("hit_rate_percent", 0.0)
+        hits = cache_stats.get("hits", 0)
+        misses = cache_stats.get("misses", 0)
+        entries = cache_stats.get("total_entries", 0)
+        size_mb = cache_stats.get("total_size_mb", 0.0)
+
+        hit_rate_style = _get_hit_rate_style(hit_rate)
+
+        table.add_row(
+            cache_name.replace("_", " ").title(),
+            Text(f"{hit_rate:.1f}", style=hit_rate_style),
+            str(hits),
+            str(misses),
+            str(entries),
+            f"{size_mb:.2f}",
+        )
+
+        totals["hits"] += hits
+        totals["misses"] += misses
+        totals["entries"] += entries
+        totals["size"] += size_mb
+
+    return totals
+
+
+def _get_hit_rate_style(hit_rate: float) -> str:
+    """Get color style for hit rate based on performance."""
+    return "green" if hit_rate > 70 else "yellow" if hit_rate > 40 else "red"
+
+
+def _add_cache_totals_row(table: Table, totals: dict[str, t.Any]) -> None:
+    """Add totals row to cache statistics table."""
+    overall_hit_rate = (
+        (totals["hits"] / (totals["hits"] + totals["misses"]) * 100)
+        if (totals["hits"] + totals["misses"]) > 0
+        else 0
+    )
+    overall_style = _get_hit_rate_style(overall_hit_rate)
+
+    table.add_row("", "", "", "", "", "", end_section=True)
+    table.add_row(
+        "Overall",
+        Text(f"{overall_hit_rate:.1f}", style=f"bold {overall_style}"),
+        str(totals["hits"]),
+        str(totals["misses"]),
+        str(totals["entries"]),
+        f"{totals['size']:.2f}",
+        style="bold",
+    )
+
+
+@depends.inject  # type: ignore[misc]
+def _display_performance_insights(
+    totals: dict[str, t.Any], console: Inject[Console]
+) -> None:
+    """Display performance insights panel based on cache statistics."""
+    overall_hit_rate = (
+        (totals["hits"] / (totals["hits"] + totals["misses"]) * 100)
+        if (totals["hits"] + totals["misses"]) > 0
+        else 0
+    )
+
+    insights = _generate_performance_insights(overall_hit_rate, totals["size"])
+
+    if insights:
+        insights_text = "\n".join(insights)
+        insights_panel = Panel(
+            insights_text,
+            title="Performance Insights",
+            border_style="blue",
+            padding=(1, 2),
+        )
+        console.print()
+        console.print(insights_panel)
+
+
+def _generate_performance_insights(hit_rate: float, total_size: float) -> list[str]:
+    """Generate performance insights based on cache metrics."""
+    insights = []
+
+    if hit_rate > 80:
+        insights.append("🚀 Excellent cache performance!")
+    elif hit_rate > 60:
+        insights.append("✅ Good cache performance")
+    elif hit_rate > 30:
+        insights.append("⚠️ Moderate cache performance - consider cache warming")
+    else:
+        insights.append("❌ Poor cache performance - check cache configuration")
+
+    if total_size > 100:
+        insights.append(f"💾 Large cache size ({total_size:.1f}MB) - consider cleanup")
+
+    return insights
+
+
+@depends.inject  # type: ignore[misc]
+def _display_cache_directory_info(
+    cache: CrackerjackCache, console: Inject[Console]
+) -> None:
+    """Display cache directory information."""
+    if not (cache.enable_disk_cache and cache.cache_dir):
+        return
+
+    cache_dir_info = f"📁 Cache Directory: {cache.cache_dir}"
+    if cache.cache_dir.exists():
+        disk_files = len(list(cache.cache_dir.rglob("*.cache")))
+        cache_dir_info += f" ({disk_files} files)"
+
+    console.print()
+    console.print(cache_dir_info)
+
+
+def _handle_cache_commands(clear_cache: bool, cache_stats: bool) -> bool:
+    """Handle cache management commands. Returns True if a cache command was executed."""
+    if clear_cache:
+        handle_clear_cache()
+        return True
+
+    if cache_stats:
+        handle_cache_stats()
+        return True
+
+    return False