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

crackerjack/api.py

@@ -3,13 +3,13 @@ import typing as t
 from dataclasses import dataclass
 from pathlib import Path
 
-from rich.console import Console
+from acb.console import Console
+from acb.depends import depends
 
 from .code_cleaner import CleaningResult, CodeCleaner, PackageCleaningResult
 from .core.workflow_orchestrator import WorkflowOrchestrator
 from .errors import CrackerjackError, ErrorCode
-from .interactive import InteractiveCLI
-from .interactive import WorkflowOptions as InteractiveWorkflowOptions
+from .interactive import InteractiveCLI, InteractiveWorkflowOptions
 from .models.config import WorkflowOptions
 from .services.regex_patterns import SAFE_PATTERNS
 
@@ -50,16 +50,15 @@ class CrackerjackAPI:
         verbose: bool = False,
     ) -> None:
         self.project_path = project_path or Path.cwd()
-        self.console = console or Console()
+        self.console = console or depends.get_sync(Console)
         self.verbose = verbose
 
         self.orchestrator = WorkflowOrchestrator(
-            console=self.console,
             pkg_path=self.project_path,
             verbose=self.verbose,
         )
 
-        self.container = self.orchestrator.container
+        self.container = t.cast(t.Any, getattr(self.orchestrator, "container", None))
 
         self._code_cleaner: CodeCleaner | None = None
         self._interactive_cli: InteractiveCLI | None = None
@@ -601,7 +600,6 @@ class CrackerjackAPI:
         return None
 
     def _find_fallback_package_directory(self) -> Path | None:
-        # Only check project directory name, not src
         package_dir = self.project_path / self.project_path.name
         if self._is_valid_python_package_directory(package_dir):
             return package_dir

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

@@ -7,7 +7,7 @@ from .handlers import (
     setup_ai_agent_env,
 )
 from .options import CLI_OPTIONS, BumpOption, Options, create_options
-from .utils import get_package_version
+from .version import get_package_version
 
 __all__ = [
     "CLI_OPTIONS",

crackerjack/cli/cache_handlers.py

@@ -1,6 +1,7 @@
 import typing as t
 
-from rich.console import Console
+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
@@ -8,7 +9,8 @@ from rich.text import Text
 from crackerjack.services.cache import CrackerjackCache
 
 
-def handle_clear_cache(console: Console) -> None:
+@depends.inject  # type: ignore[misc]
+def handle_clear_cache(console: Inject[Console]) -> None:
     """Clear all caches and display results."""
     try:
         cache = CrackerjackCache()
@@ -16,9 +18,7 @@ def handle_clear_cache(console: Console) -> None:
         # Clear memory caches and get cleanup stats
         cleanup_results = cache.cleanup_all()
 
-        # Clear disk cache completely
-        if cache.enable_disk_cache and cache.cache_dir:
-            cache.disk_cache.clear()
+        # Note:CrackerjackCache uses memory-only caching (no disk cache to clear)
 
         # Calculate total items cleared
         total_cleared = sum(cleanup_results.values())
@@ -37,14 +37,15 @@ def handle_clear_cache(console: Console) -> None:
         table.add_row("Total", str(total_cleared), style="bold green")
 
         console.print()
-        console.print(table)
+        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")
 
 
-def handle_cache_stats(console: Console) -> None:
+@depends.inject  # type: ignore[misc]
+def handle_cache_stats(console: Inject[Console]) -> None:
     """Display detailed cache statistics."""
     try:
         cache = CrackerjackCache()
@@ -55,10 +56,10 @@ def handle_cache_stats(console: Console) -> None:
         _add_cache_totals_row(main_table, totals)
 
         console.print()
-        console.print(main_table)
+        console.print(Panel(main_table, border_style="blue"))
 
-        _display_performance_insights(console, totals)
-        _display_cache_directory_info(console, cache)
+        _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")
@@ -134,7 +135,10 @@ def _add_cache_totals_row(table: Table, totals: dict[str, t.Any]) -> None:
     )
 
 
-def _display_performance_insights(console: Console, totals: dict[str, t.Any]) -> None:
+@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)
@@ -175,30 +179,31 @@ def _generate_performance_insights(hit_rate: float, total_size: float) -> list[s
     return insights
 
 
-def _display_cache_directory_info(console: Console, cache: CrackerjackCache) -> None:
+@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[t.Any](cache.cache_dir.rglob("*.cache")))
+        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, console: Console
-) -> bool:
+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(console)
+        handle_clear_cache()
         return True
 
     if cache_stats:
-        handle_cache_stats(console)
+        handle_cache_stats()
         return True
 
     return False

crackerjack/cli/cache_handlers_enhanced.py

@@ -61,12 +61,9 @@ class EnhancedCacheHandlers:
             pre_clear_stats = self.cache.get_cache_stats()
 
             # Clear memory caches and get cleanup stats
+            # Note: cleanup_all() already handles all cache types (memory + disk)
             cleanup_results = self.cache.cleanup_all()
 
-            # Clear disk cache completely
-            if self.cache.enable_disk_cache and self.cache.cache_dir:
-                self.cache.disk_cache.clear()
-
             # Calculate total items cleared
             total_cleared = sum(cleanup_results.values())
 

crackerjack/cli/facade.py

@@ -1,11 +1,74 @@
 import asyncio
+import shlex
 from pathlib import Path
 
-from rich.console import Console
+from acb.console import Console
+from acb.depends import depends
 
 from crackerjack.core.workflow_orchestrator import WorkflowOrchestrator
 from crackerjack.models.protocols import OptionsProtocol
 
+# Valid semantic commands for crackerjack operations
+VALID_COMMANDS = {"test", "lint", "check", "format", "security", "complexity", "all"}
+
+
+def validate_command(
+    command: str | None, args: str | None = None
+) -> tuple[str, list[str]]:
+    """Validate command and detect common misuse patterns.
+
+    Args:
+        command: Semantic command name (test, lint, check, etc.)
+        args: Additional arguments as a string
+
+    Returns:
+        Tuple of (validated_command, cleaned_args_list)
+
+    Raises:
+        ValueError: If command is invalid or misused
+
+    Examples:
+        >>> validate_command("test", "")
+        ("test", [])
+        >>> validate_command("check", "--verbose")
+        ("check", ["--verbose"])
+        >>> validate_command("--ai-fix", "-t")
+        Traceback (most recent call last):
+        ...
+        ValueError: Invalid command: '--ai-fix'...
+    """
+    # CRITICAL: Check for None command first
+    if command is None:
+        raise ValueError("Command cannot be None")
+
+    # Detect if user put flags in command parameter
+    if command.startswith("--") or command.startswith("-"):
+        raise ValueError(
+            f"Invalid command: {command!r}\n"
+            f"Commands should be semantic (e.g., 'test', 'lint', 'check')\n"
+            f"Use ai_agent_mode=True parameter for auto-fix, not --ai-fix in command"
+        )
+
+    # Validate against known semantic commands
+    if command not in VALID_COMMANDS:
+        raise ValueError(
+            f"Unknown command: {command!r}\n"
+            f"Valid commands: {', '.join(sorted(VALID_COMMANDS))}"
+        )
+
+    # Parse args and detect --ai-fix misuse
+    # Handle None gracefully by converting to empty string
+    args_str = args if args is not None else ""
+    # Use shlex.split for proper shell argument parsing (handles quotes)
+    parsed_args = shlex.split(args_str) if args_str else []
+    if "--ai-fix" in parsed_args:
+        raise ValueError(
+            "Do not pass --ai-fix in args parameter\n"
+            "Use ai_agent_mode=True parameter instead"
+        )
+
+    return command, parsed_args
+
 
 class CrackerjackCLIFacade:
     def __init__(
@@ -13,10 +76,9 @@ class CrackerjackCLIFacade:
         console: Console | None = None,
         pkg_path: Path | None = None,
     ) -> None:
-        self.console = console or Console(force_terminal=True)
+        self.console = console or depends.get_sync(Console)
         self.pkg_path = pkg_path or Path.cwd()
         self.orchestrator = WorkflowOrchestrator(
-            console=self.console,
             pkg_path=self.pkg_path,
         )
 
@@ -49,15 +111,15 @@ class CrackerjackCLIFacade:
     def _should_handle_special_mode(self, options: OptionsProtocol) -> bool:
         return (
             getattr(options, "start_mcp_server", False)
-            or getattr(options, "enterprise_batch", False)
+            or getattr(options, "advanced_batch", False)
             or getattr(options, "monitor_dashboard", False)
         )
 
     def _handle_special_modes(self, options: OptionsProtocol) -> None:
         if getattr(options, "start_mcp_server", False):
             self._start_mcp_server()
-        elif getattr(options, "enterprise_batch", False):
-            self._handle_enterprise_batch(options)
+        elif getattr(options, "advanced_batch", False):
+            self._handle_advanced_batch(options)
         elif getattr(options, "monitor_dashboard", False):
             self._handle_monitor_dashboard(options)
 
@@ -79,9 +141,9 @@ class CrackerjackCLIFacade:
             self.console.print(f"[red]❌ Failed to start MCP server: {e}[/ red]")
             raise SystemExit(1)
 
-    def _handle_enterprise_batch(self, options: OptionsProtocol) -> None:
+    def _handle_advanced_batch(self, options: OptionsProtocol) -> None:
         self.console.print(
-            "[red]❌ Enterprise batch processing is not yet implemented[/ red]"
+            "[red]❌ Advanced batch processing is not yet implemented[/ red]"
         )
         raise SystemExit(1)
 

crackerjack/cli/formatting.py

@@ -0,0 +1,13 @@
+from __future__ import annotations
+
+from crackerjack.config import get_console_width
+
+
+def separator(char: str = "-", width: int | None = None) -> str:
+    """Return a horizontal separator string.
+
+    - char: the character to repeat (default '-')
+    - width: explicit width; if None, uses configured console width
+    """
+    w = width if isinstance(width, int) and width > 0 else get_console_width()
+    return char * w