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

crackerjack/exceptions/README.md

@@ -0,0 +1,301 @@
+> Crackerjack Docs: [Main](<../../README.md>) | [Crackerjack Package](<../README.md>) | [Exceptions](<./README.md>)
+
+# Exceptions
+
+Custom exception types with rich formatting and context-aware error reporting. Provides enhanced UX for tool execution failures and configuration issues.
+
+## Exception Hierarchy
+
+```
+BaseException
+└── Exception
+    ├── ToolExecutionError         # Rich tool execution failures
+    └── ConfigIntegrityError       # Configuration validation issues
+```
+
+## Custom Exception Types
+
+### ToolExecutionError
+
+Enhanced error with rich formatting for failed tool executions. Provides detailed context including exit codes, stdout/stderr, duration, and actionable suggestions.
+
+**Features:**
+
+- Rich console formatting with syntax highlighting
+- Automatic output truncation for readability
+- Actionable error messages with suggestions
+- Context tracking (command, cwd, duration)
+- Integration with Crackerjack's console system
+
+**Constructor:**
+
+```python
+ToolExecutionError(
+    tool: str,              # Tool name that failed
+    exit_code: int,         # Process exit code
+    stdout: str = "",       # Standard output
+    stderr: str = "",       # Standard error
+    command: list[str] | None = None,   # Full command executed
+    cwd: Path | None = None,            # Working directory
+    duration: float | None = None,      # Execution duration (seconds)
+)
+```
+
+**Usage Example:**
+
+```python
+from crackerjack.exceptions import ToolExecutionError
+from pathlib import Path
+
+try:
+    result = subprocess.run(
+        ["ruff", "check", "."], capture_output=True, text=True, cwd=project_dir
+    )
+    if result.returncode != 0:
+        raise ToolExecutionError(
+            tool="ruff",
+            exit_code=result.returncode,
+            stdout=result.stdout,
+            stderr=result.stderr,
+            command=["ruff", "check", "."],
+            cwd=project_dir,
+            duration=2.5,
+        )
+except ToolExecutionError as e:
+    # Rich formatted output
+    console.print(e.format_rich())
+
+    # Or get actionable message
+    print(e.get_actionable_message())
+```
+
+**Rich Formatting:**
+
+```python
+from acb.console import Console
+
+console = Console()
+
+# Create error
+error = ToolExecutionError(
+    tool="pytest",
+    exit_code=1,
+    stderr="test_example.py::test_feature FAILED",
+    duration=3.2,
+)
+
+# Display with rich formatting
+panel = error.format_rich(console)
+console.print(panel)
+```
+
+**Output:**
+
+```
+╭─ ❌ Tool Execution Failed: pytest ─────────────╮
+│ Tool: pytest                                   │
+│ Exit Code: 1                                   │
+│ Duration: 3.20s                                │
+│                                                │
+│ Error Output:                                  │
+│   test_example.py::test_feature FAILED         │
+╰────────────────────────────────────────────────╯
+```
+
+**Actionable Messages:**
+
+The `get_actionable_message()` method provides smart error pattern detection:
+
+```python
+error = ToolExecutionError(
+    tool="ruff", exit_code=1, stderr="ModuleNotFoundError: No module named 'requests'"
+)
+
+print(error.get_actionable_message())
+# Output:
+# Tool 'ruff' failed with exit code 1
+# → Check Python dependencies are installed (try: uv sync)
+```
+
+**Common Patterns Detected:**
+
+- Permission denied → Check file permissions
+- Command not found → Ensure tool is installed
+- Timeout errors → Increase timeout setting
+- Syntax errors → Check code syntax
+- Import errors → Run dependency sync
+- Type errors → Fix type annotations
+- Out of memory → Reduce batch size
+
+### ConfigIntegrityError
+
+Simple exception for configuration validation and integrity issues.
+
+**Usage Example:**
+
+```python
+from crackerjack.exceptions import ConfigIntegrityError
+
+
+def validate_config(config: dict) -> None:
+    if "required_field" not in config:
+        raise ConfigIntegrityError(
+            "Missing required field 'required_field' in configuration"
+        )
+
+    if config.get("version") != "1.0":
+        raise ConfigIntegrityError(
+            f"Unsupported config version: {config.get('version')}"
+        )
+```
+
+## Error Handling Patterns
+
+### Pattern 1: Tool Execution with Context
+
+```python
+from crackerjack.exceptions import ToolExecutionError
+import subprocess
+import time
+
+
+def run_tool(tool: str, args: list[str], cwd: Path) -> bool:
+    """Run tool with comprehensive error reporting."""
+    start = time.time()
+
+    try:
+        result = subprocess.run(
+            [tool] + args, capture_output=True, text=True, cwd=cwd, timeout=300
+        )
+
+        if result.returncode != 0:
+            raise ToolExecutionError(
+                tool=tool,
+                exit_code=result.returncode,
+                stdout=result.stdout,
+                stderr=result.stderr,
+                command=[tool] + args,
+                cwd=cwd,
+                duration=time.time() - start,
+            )
+
+        return True
+
+    except subprocess.TimeoutExpired as e:
+        raise ToolExecutionError(
+            tool=tool,
+            exit_code=-1,
+            stderr=f"Tool execution timed out after {e.timeout}s",
+            command=[tool] + args,
+            cwd=cwd,
+            duration=e.timeout,
+        ) from e
+```
+
+### Pattern 2: Graceful Error Display
+
+```python
+from crackerjack.exceptions import ToolExecutionError
+from acb.console import Console
+from acb.depends import depends
+
+
+@depends.inject
+def execute_with_nice_errors(func: callable, console: Console = depends()) -> bool:
+    """Execute function with rich error formatting."""
+    try:
+        return func()
+    except ToolExecutionError as e:
+        console.print(e.format_rich())
+        console.print(f"\n[yellow]{e.get_actionable_message()}[/yellow]")
+        return False
+```
+
+### Pattern 3: Config Validation
+
+```python
+from crackerjack.exceptions import ConfigIntegrityError
+from pathlib import Path
+import yaml
+
+
+def load_and_validate_config(path: Path) -> dict:
+    """Load config with integrity validation."""
+    if not path.exists():
+        raise ConfigIntegrityError(f"Configuration file not found: {path}")
+
+    with open(path) as f:
+        config = yaml.safe_load(f)
+
+    required = ["version", "project_name", "settings"]
+    missing = [k for k in required if k not in config]
+
+    if missing:
+        raise ConfigIntegrityError(
+            f"Missing required config fields: {', '.join(missing)}"
+        )
+
+    return config
+```
+
+## Best Practices
+
+### Use ToolExecutionError for All Tool Failures
+
+Provides consistent, rich error reporting across the codebase:
+
+```python
+# ✅ Good - Rich error context
+if exit_code != 0:
+    raise ToolExecutionError(
+        tool="mypy", exit_code=exit_code, stderr=stderr, duration=duration
+    )
+
+# ❌ Bad - Generic exception
+if exit_code != 0:
+    raise RuntimeError(f"mypy failed: {stderr}")
+```
+
+### Include All Available Context
+
+More context enables better error messages:
+
+```python
+# ✅ Good - Full context
+raise ToolExecutionError(
+    tool="pytest",
+    exit_code=1,
+    stdout=result.stdout,
+    stderr=result.stderr,
+    command=full_command,
+    cwd=project_dir,
+    duration=elapsed,
+)
+
+# ⚠️ Minimal - Missing helpful context
+raise ToolExecutionError(tool="pytest", exit_code=1)
+```
+
+### Use format_rich() for User-Facing Errors
+
+Provides best UX with Rich console integration:
+
+```python
+try:
+    run_checks()
+except ToolExecutionError as e:
+    console.print(e.format_rich())  # Beautiful formatting
+    console.print(f"\n{e.get_actionable_message()}")  # Smart suggestions
+```
+
+## Implementation Files
+
+- **`tool_execution_error.py`** - ToolExecutionError with rich formatting
+- **`config.py`** - ConfigIntegrityError for configuration validation
+
+## Related
+
+- [Decorators](<../decorators/README.md>) - Error handling decorators
+- [Errors](../errors/README.md) - Core error types and CrackerjackError base
+- [MCP](<../mcp/README.md>) - Error caching and pattern analysis
+- [Console Integration](https://github.com/Textualize/rich) - Rich console formatting

crackerjack/exceptions/__init__.py

@@ -0,0 +1,5 @@
+"""Custom exceptions for crackerjack."""
+
+from .tool_execution_error import ToolExecutionError
+
+__all__ = ["ToolExecutionError"]

crackerjack/exceptions/config.py

@@ -0,0 +1,4 @@
+class ConfigIntegrityError(Exception):
+    """Custom exception for configuration integrity issues."""
+
+    pass

crackerjack/exceptions/tool_execution_error.py

@@ -0,0 +1,245 @@
+"""Enhanced tool execution error with rich formatting.
+
+Provides context-rich error reporting for failed tool executions.
+Part of Phase 10.2.3: Development Velocity Improvements.
+"""
+
+from pathlib import Path
+
+from acb.console import Console
+from rich.panel import Panel
+
+
+class ToolExecutionError(Exception):
+    """Enhanced error with context for tool execution failures.
+
+    Provides detailed information about what went wrong during tool execution,
+    including exit code, stdout, stderr, and rich formatting for better UX.
+    """
+
+    def __init__(
+        self,
+        tool: str,
+        exit_code: int,
+        stdout: str = "",
+        stderr: str = "",
+        command: list[str] | None = None,
+        cwd: Path | None = None,
+        duration: float | None = None,
+    ):
+        """Initialize tool execution error.
+
+        Args:
+            tool: Tool name that failed
+            exit_code: Process exit code
+            stdout: Standard output from tool
+            stderr: Standard error from tool
+            command: Full command that was executed (optional)
+            cwd: Working directory where command was run (optional)
+            duration: Execution duration in seconds (optional)
+        """
+        self.tool = tool
+        self.exit_code = exit_code
+        self.stdout = stdout.strip()
+        self.stderr = stderr.strip()
+        self.command = command
+        self.cwd = cwd
+        self.duration = duration
+
+        # Create base exception message
+        message = f"Tool '{tool}' failed with exit code {exit_code}"
+        if duration is not None:
+            message += f" after {duration:.1f}s"
+
+        super().__init__(message)
+
+    def format_rich(self, console: Console | None = None) -> Panel:
+        """Format error for rich console display with syntax highlighting.
+
+        Args:
+            console: Optional console for width detection
+
+        Returns:
+            Formatted rich Panel with error details
+        """
+        # Build error content with sections
+        content_parts = []
+
+        # Tool and exit code
+        content_parts.extend(
+            (
+                f"[bold red]Tool:[/bold red] {self.tool}",
+                f"[bold red]Exit Code:[/bold red] {self.exit_code}",
+            )
+        )
+
+        # Duration if available
+        if self.duration is not None:
+            content_parts.append(
+                f"[bold yellow]Duration:[/bold yellow] {self.duration:.2f}s"
+            )
+
+        # Working directory if available
+        if self.cwd:
+            content_parts.append(f"[bold cyan]Directory:[/bold cyan] {self.cwd}")
+
+        # Command if available
+        if self.command:
+            cmd_str = " ".join(self.command)
+            # Truncate very long commands
+            if len(cmd_str) > 100:
+                cmd_str = cmd_str[:97] + "..."
+            content_parts.append(f"[bold cyan]Command:[/bold cyan] {cmd_str}")
+
+        # Standard error (most important)
+        if self.stderr:
+            content_parts.append("\n[bold yellow]Error Output:[/bold yellow]")
+            # Limit error output to last 20 lines for readability
+            stderr_lines = self.stderr.split("\n")
+            if len(stderr_lines) > 20:
+                content_parts.append("[dim]...(truncated)[/dim]")
+                stderr_lines = stderr_lines[-20:]
+            content_parts.append(self._format_output(stderr_lines))
+
+        # Standard output (if present and stderr is empty)
+        elif self.stdout:
+            content_parts.append("\n[bold yellow]Output:[/bold yellow]")
+            stdout_lines = self.stdout.split("\n")
+            if len(stdout_lines) > 20:
+                content_parts.append("[dim]...(truncated)[/dim]")
+                stdout_lines = stdout_lines[-20:]
+            content_parts.append(self._format_output(stdout_lines))
+
+        # No output available
+        else:
+            content_parts.append("\n[dim]No error output available[/dim]")
+
+        # Combine all parts
+        content = "\n".join(content_parts)
+
+        return Panel(
+            content,
+            title=f"❌ Tool Execution Failed: {self.tool}",
+            border_style="red",
+            expand=False,
+        )
+
+    def _format_output(self, lines: list[str]) -> str:
+        """Format output lines with proper indentation and markup.
+
+        Args:
+            lines: Output lines to format
+
+        Returns:
+            Formatted output string
+        """
+        # Remove ANSI color codes for cleaner display
+        import re
+
+        # Standard ANSI escape sequence pattern (not security-critical, safe to use directly)
+        ansi_escape = re.compile(r"\x1b\[[0-9;]*m")
+
+        formatted_lines = []
+        for line in lines:
+            # Strip ANSI codes
+            clean_line = ansi_escape.sub("", line)
+            # Indent for readability
+            if clean_line.strip():
+                formatted_lines.append(f"  {clean_line}")
+
+        return "\n".join(formatted_lines) if formatted_lines else "[dim]  (empty)[/dim]"
+
+    def _get_error_suggestion(self, combined_output: str) -> str | None:
+        """Get specific suggestion based on error patterns in output.
+
+        Args:
+            combined_output: Combined stderr and stdout in lowercase
+
+        Returns:
+            Suggestion string, or None if no pattern matched
+        """
+        error_patterns = {
+            "permission denied": "→ Check file permissions or run with appropriate access",
+            (
+                "command not found",
+                "no such file",
+            ): f"→ Ensure '{self.tool}' is installed and in PATH",
+            (
+                "timeout",
+                "timed out",
+            ): "→ Tool execution timed out - consider increasing timeout",
+            (
+                "syntaxerror",
+                "syntax error",
+            ): "→ Check code syntax in files being analyzed",
+            (
+                "importerror",
+                "modulenotfounderror",
+            ): "→ Check Python dependencies are installed (try: uv sync)",
+            ("typeerror", "type error"): "→ Fix type annotation errors in your code",
+            "out of memory": "→ Reduce batch size or increase available memory",
+        }
+
+        for patterns, suggestion in error_patterns.items():
+            patterns_list = patterns if isinstance(patterns, tuple) else (patterns,)
+            if any(pattern in combined_output for pattern in patterns_list):
+                return suggestion
+
+        return None
+
+    def get_actionable_message(self) -> str:
+        """Get actionable error message for developers.
+
+        Returns:
+            Human-readable error message with suggestions
+        """
+        messages = [f"Tool '{self.tool}' failed with exit code {self.exit_code}"]
+
+        # Add common error patterns and suggestions
+        combined_output = f"{self.stderr} {self.stdout}".lower()
+        suggestion = self._get_error_suggestion(combined_output)
+
+        if suggestion:
+            messages.append(suggestion)
+        elif self.stderr:
+            messages.append("→ Check error output above for details")
+        else:
+            messages.append(f"→ Run '{self.tool}' manually for more details")
+
+        return "\n".join(messages)
+
+    def __str__(self) -> str:
+        """String representation for logging and debugging.
+
+        Returns:
+            Detailed string representation
+        """
+        parts = [
+            f"ToolExecutionError: {self.tool}",
+            f"Exit Code: {self.exit_code}",
+        ]
+
+        if self.duration is not None:
+            parts.append(f"Duration: {self.duration:.2f}s")
+
+        if self.command:
+            parts.append(f"Command: {' '.join(self.command)}")
+
+        if self.stderr:
+            parts.append(f"Stderr: {self.stderr[:200]}...")
+        elif self.stdout:
+            parts.append(f"Stdout: {self.stdout[:200]}...")
+
+        return " | ".join(parts)
+
+    def __repr__(self) -> str:
+        """Developer representation.
+
+        Returns:
+            Repr string
+        """
+        return (
+            f"ToolExecutionError(tool={self.tool!r}, "
+            f"exit_code={self.exit_code}, "
+            f"duration={self.duration})"
+        )