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

crackerjack/agents/enhanced_proactive_agent.py

@@ -0,0 +1,185 @@
+"""
+Enhanced proactive agent that integrates Claude Code external agent consultation.
+
+This module extends the base ProactiveAgent to consult with Claude Code's external
+agents (like crackerjack-architect, python-pro, security-auditor) when handling
+complex issues that require specialized expertise.
+"""
+
+import typing as t
+from abc import abstractmethod
+
+from .base import AgentContext, FixResult, Issue
+from .claude_code_bridge import ClaudeCodeBridge
+from .proactive_agent import ProactiveAgent
+
+
+class EnhancedProactiveAgent(ProactiveAgent):
+    """
+    Proactive agent enhanced with Claude Code external agent consultation.
+
+    This agent follows the standard crackerjack agent pattern but adds intelligent
+    consultation with external Claude Code agents for complex scenarios that
+    require specialized expertise.
+    """
+
+    def __init__(self, context: AgentContext) -> None:
+        super().__init__(context)
+        self.claude_bridge = ClaudeCodeBridge(context)
+        self._external_consultation_enabled = True
+
+    def enable_external_consultation(self, enabled: bool = True) -> None:
+        """Enable or disable external Claude Code agent consultation."""
+        self._external_consultation_enabled = enabled
+
+    async def _execute_with_plan(
+        self, issue: Issue, plan: dict[str, t.Any]
+    ) -> FixResult:
+        """
+        Execute fix with plan, consulting external agents when appropriate.
+
+        This method enhances the base implementation by:
+        1. First attempting the internal fix
+        2. Evaluating if external consultation would improve the result
+        3. Consulting with relevant Claude Code agents
+        4. Combining internal and external guidance for better results
+        """
+        # First, get the internal fix result
+        internal_result = await self._execute_internal_fix(issue, plan)
+
+        # Determine if we should consult external agents
+        if not self._should_consult_external_agents(issue, internal_result, plan):
+            return internal_result
+
+        # Consult with relevant external agents
+        external_consultations = await self._consult_external_agents(issue, plan)
+
+        # Enhance the result with external guidance
+        enhanced_result = self._combine_internal_and_external_results(
+            internal_result, external_consultations
+        )
+
+        return enhanced_result
+
+    async def _execute_internal_fix(
+        self, issue: Issue, plan: dict[str, t.Any]
+    ) -> FixResult:
+        """Execute the internal fix using the built-in agent logic."""
+        # This calls the concrete agent's analyze_and_fix implementation
+        return await self.analyze_and_fix(issue)
+
+    def _should_consult_external_agents(
+        self, issue: Issue, internal_result: FixResult, plan: dict[str, t.Any]
+    ) -> bool:
+        """Determine if external consultation would be beneficial."""
+        if not self._external_consultation_enabled:
+            return False
+
+        # Consult external agents if:
+        # 1. Internal result has low confidence
+        # 2. Issue is complex and requires specialized expertise
+        # 3. Plan strategy indicates external specialist guidance
+        return (
+            self.claude_bridge.should_consult_external_agent(
+                issue, internal_result.confidence
+            )
+            or plan.get("strategy") == "external_specialist_guided"
+            or not internal_result.success
+        )
+
+    async def _consult_external_agents(
+        self, issue: Issue, plan: dict[str, t.Any]
+    ) -> list[dict[str, t.Any]]:
+        """Consult with relevant external Claude Code agents."""
+        recommended_agents = self.claude_bridge.get_recommended_external_agents(issue)
+        consultations = []
+
+        # Limit to top 2 agents to avoid overwhelming the system
+        for agent_name in recommended_agents[:2]:
+            if self.claude_bridge.verify_agent_availability(agent_name):
+                consultation = await self.claude_bridge.consult_external_agent(
+                    issue, agent_name, {"plan": plan}
+                )
+                if consultation.get("status") == "success":
+                    consultations.append(consultation)
+
+        return consultations
+
+    def _combine_internal_and_external_results(
+        self, internal_result: FixResult, external_consultations: list[dict[str, t.Any]]
+    ) -> FixResult:
+        """Combine internal fix result with external agent consultations."""
+        if not external_consultations:
+            return internal_result
+
+        # Use the bridge to create an enhanced result
+        enhanced_result = self.claude_bridge.create_enhanced_fix_result(
+            internal_result, external_consultations
+        )
+
+        # Add metadata about external consultation
+        enhanced_result.recommendations.insert(
+            0,
+            f"Enhanced with consultation from {len(external_consultations)} Claude Code agents",
+        )
+
+        return enhanced_result
+
+    async def plan_before_action(self, issue: Issue) -> dict[str, t.Any]:
+        """
+        Create a plan that considers both internal and external capabilities.
+
+        This method should be implemented by concrete agents to define their
+        specific planning logic while having access to external consultation.
+        """
+        # Default implementation - concrete agents should override this
+        if self.claude_bridge.should_consult_external_agent(issue, 0.0):
+            return {
+                "strategy": "external_specialist_guided",
+                "approach": "consult_claude_code_experts",
+                "patterns": ["external_guidance"],
+                "validation": ["verify_with_external_agents"],
+            }
+
+        return {
+            "strategy": "internal_pattern_based",
+            "approach": "apply_internal_logic",
+            "patterns": ["standard_patterns"],
+            "validation": ["run_internal_checks"],
+        }
+
+    @abstractmethod
+    async def analyze_and_fix(self, issue: Issue) -> FixResult:
+        """
+        Concrete agents must implement their specific fix logic.
+
+        This method contains the core agent-specific logic for analyzing
+        and fixing issues. The enhanced execution framework will automatically
+        handle external consultation when appropriate.
+        """
+        pass
+
+
+# Convenience function to enhance existing agents
+def enhance_agent_with_claude_code_bridge(
+    agent_class: type[ProactiveAgent],
+) -> type[EnhancedProactiveAgent]:
+    """
+    Enhance an existing ProactiveAgent class with Claude Code external consultation.
+
+    This function creates a new class that inherits from both the original agent
+    and EnhancedProactiveAgent, providing external consultation capabilities
+    while preserving the original agent's logic.
+    """
+
+    class EnhancedAgent(EnhancedProactiveAgent, agent_class):  # type: ignore[misc,valid-type]
+        def __init__(self, context: AgentContext) -> None:
+            # Initialize both parent classes
+            EnhancedProactiveAgent.__init__(self, context)
+            agent_class.__init__(self, context)
+
+    # Preserve the original class name and metadata
+    EnhancedAgent.__name__ = f"Enhanced{agent_class.__name__}"
+    EnhancedAgent.__qualname__ = f"Enhanced{agent_class.__qualname__}"
+
+    return EnhancedAgent

crackerjack/agents/error_middleware.py

@@ -0,0 +1,53 @@
+"""Shared error-handling middleware helpers for agents."""
+
+from __future__ import annotations
+
+import typing as t
+from functools import wraps
+
+from acb.console import Console
+
+from crackerjack.agents.base import FixResult, Issue, SubAgent
+
+if t.TYPE_CHECKING:  # pragma: no cover - typing helpers
+    from crackerjack.agents.coordinator import AgentCoordinator
+
+
+def agent_error_boundary(
+    func: t.Callable[..., t.Awaitable[FixResult]],
+) -> t.Callable[..., t.Awaitable[FixResult]]:
+    """Decorator that centralizes error handling for agent execution.
+
+    Ensures all agent failures are logged consistently and converted into a
+    ``FixResult`` that upstream orchestrators can reason about without custom
+    ``try``/``except`` blocks.
+    """
+
+    @wraps(func)
+    async def wrapper(
+        self: AgentCoordinator,
+        agent: SubAgent,
+        issue: Issue,
+        *args: t.Any,
+        **kwargs: t.Any,
+    ) -> FixResult:
+        try:
+            return await func(self, agent, issue, *args, **kwargs)
+        except Exception as exc:  # pragma: no cover - exercised via decorator tests
+            console: Console | None = getattr(self.context, "console", None)
+            message = f"{agent.name} encountered an error while processing issue {issue.id}: {exc}"
+            self.logger.exception(message, exc_info=exc)
+            if console is not None:
+                console.print(f"[red]{message}[/red]")
+
+            return FixResult(
+                success=False,
+                confidence=0.0,
+                remaining_issues=[message],
+                recommendations=[
+                    "Review agent logs for stack trace",
+                    "Re-run with --debug to capture additional context",
+                ],
+            )
+
+    return wrapper

crackerjack/agents/formatting_agent.py

@@ -134,10 +134,9 @@ class FormattingAgent(SubAgent):
             [
                 "uv",
                 "run",
-                "pre-commit",
-                "run",
-                "trailing-whitespace",
-                "--all-files",
+                "python",
+                "-m",
+                "crackerjack.tools.trailing_whitespace",
             ],
         )
 
@@ -149,10 +148,9 @@ class FormattingAgent(SubAgent):
             [
                 "uv",
                 "run",
-                "pre-commit",
-                "run",
-                "end-of-file-fixer",
-                "--all-files",
+                "python",
+                "-m",
+                "crackerjack.tools.end_of_file_fixer",
             ],
         )
 

crackerjack/agents/helpers/__init__.py

@@ -0,0 +1,9 @@
+"""Package for helper modules used by crackerjack agents.
+
+This package contains supporting modules for various agent types:
+- performance: Performance analysis and optimization helpers
+- refactoring: Code refactoring utilities
+- test_creation: Test generation helpers
+"""
+
+# This file makes the directory a proper Python package

crackerjack/agents/helpers/performance/__init__.py

@@ -0,0 +1,22 @@
+"""Performance optimization helpers for the PerformanceAgent.
+
+This module provides specialized helpers for detecting and fixing performance
+anti-patterns while maintaining the AgentContext pattern.
+"""
+
+from .performance_ast_analyzer import PerformanceASTAnalyzer
+from .performance_pattern_detector import (
+    ListOpAnalyzer,
+    NestedLoopAnalyzer,
+    PerformancePatternDetector,
+)
+from .performance_recommender import OptimizationResult, PerformanceRecommender
+
+__all__ = [
+    "PerformancePatternDetector",
+    "PerformanceASTAnalyzer",
+    "PerformanceRecommender",
+    "OptimizationResult",
+    "NestedLoopAnalyzer",
+    "ListOpAnalyzer",
+]

crackerjack/agents/helpers/performance/performance_ast_analyzer.py

@@ -0,0 +1,357 @@
+"""AST analysis for performance complexity detection."""
+
+import ast
+import typing as t
+
+from ...base import AgentContext
+
+
+class PerformanceASTAnalyzer:
+    """Analyzes Python AST for performance-related complexity issues."""
+
+    def __init__(self, context: AgentContext) -> None:
+        """Initialize analyzer with agent context.
+
+        Args:
+            context: AgentContext for logging and operations
+        """
+        self.context = context
+
+    def extract_performance_critical_functions(
+        self, content: str
+    ) -> list[dict[str, t.Any]]:
+        """Extract functions likely to have performance issues.
+
+        Args:
+            content: File content
+
+        Returns:
+            List of performance-critical functions
+        """
+        functions: list[dict[str, t.Any]] = []
+        lines = content.split("\n")
+        current_function = None
+
+        for i, line in enumerate(lines):
+            stripped = line.strip()
+
+            if self._is_empty_or_comment_line(stripped):
+                if current_function:
+                    current_function["body"] += line + "\n"
+                continue
+
+            indent = len(line) - len(line.lstrip())
+
+            if self._is_function_definition(stripped):
+                current_function = self._handle_function_definition(
+                    current_function, functions, stripped, indent, i
+                )
+            elif current_function:
+                current_function = self._handle_function_body_line(
+                    current_function, functions, line, stripped, indent, i
+                )
+
+        self._handle_last_function(current_function, functions, len(lines))
+        return functions
+
+    @staticmethod
+    def _is_empty_or_comment_line(stripped: str) -> bool:
+        """Check if line is empty or comment.
+
+        Args:
+            stripped: Stripped line
+
+        Returns:
+            True if empty or comment
+        """
+        return not stripped or stripped.startswith("#")
+
+    @staticmethod
+    def _is_function_definition(stripped: str) -> bool:
+        """Check if line is function definition.
+
+        Args:
+            stripped: Stripped line
+
+        Returns:
+            True if function definition
+        """
+        return stripped.startswith("def ") and "(" in stripped
+
+    def _handle_function_definition(
+        self,
+        current_function: dict[str, t.Any] | None,
+        functions: list[dict[str, t.Any]],
+        stripped: str,
+        indent: int,
+        line_number: int,
+    ) -> dict[str, t.Any]:
+        """Handle function definition line.
+
+        Args:
+            current_function: Current function being parsed
+            functions: List of functions
+            stripped: Stripped line
+            indent: Indentation level
+            line_number: Line number
+
+        Returns:
+            New function dict
+        """
+        if current_function and self._is_performance_critical(current_function):
+            self._finalize_function(current_function, functions, line_number)
+
+        func_name = stripped.split("(")[0].replace("def ", "").strip()
+        return {
+            "name": func_name,
+            "signature": stripped,
+            "start_line": line_number + 1,
+            "body": "",
+            "indent_level": indent,
+        }
+
+    def _handle_function_body_line(
+        self,
+        current_function: dict[str, t.Any],
+        functions: list[dict[str, t.Any]],
+        line: str,
+        stripped: str,
+        indent: int,
+        line_number: int,
+    ) -> dict[str, t.Any] | None:
+        """Handle line within function body.
+
+        Args:
+            current_function: Current function
+            functions: Functions list
+            line: Full line
+            stripped: Stripped line
+            indent: Indent level
+            line_number: Line number
+
+        Returns:
+            Updated current function or None
+        """
+        if self._is_still_in_function(current_function, indent, stripped):
+            current_function["body"] += line + "\n"
+            return current_function
+        else:
+            if self._is_performance_critical(current_function):
+                self._finalize_function(current_function, functions, line_number)
+            return None
+
+    @staticmethod
+    def _is_still_in_function(
+        current_function: dict[str, t.Any], indent: int, stripped: str
+    ) -> bool:
+        """Check if still inside function.
+
+        Args:
+            current_function: Current function
+            indent: Indent level
+            stripped: Stripped line
+
+        Returns:
+            True if still inside
+        """
+        return indent > current_function["indent_level"] or (
+            indent == current_function["indent_level"]
+            and stripped.startswith(('"', "'", "@"))
+        )
+
+    def _finalize_function(
+        self,
+        function: dict[str, t.Any],
+        functions: list[dict[str, t.Any]],
+        end_line: int,
+    ) -> None:
+        """Finalize function and add to results.
+
+        Args:
+            function: Function to finalize
+            functions: Functions list
+            end_line: End line number
+        """
+        function["end_line"] = end_line
+        function["body_sample"] = function["body"][:300]
+        function["estimated_complexity"] = self._estimate_complexity(function["body"])
+        functions.append(function)
+
+    def _handle_last_function(
+        self,
+        current_function: dict[str, t.Any] | None,
+        functions: list[dict[str, t.Any]],
+        total_lines: int,
+    ) -> None:
+        """Handle last function in file.
+
+        Args:
+            current_function: Last function
+            functions: Functions list
+            total_lines: Total lines
+        """
+        if current_function and self._is_performance_critical(current_function):
+            self._finalize_function(current_function, functions, total_lines)
+
+    @staticmethod
+    def _is_performance_critical(function_info: dict[str, t.Any]) -> bool:
+        """Determine if function is performance-critical.
+
+        Args:
+            function_info: Function info
+
+        Returns:
+            True if performance-critical
+        """
+        body = function_info.get("body", "")
+        name = function_info.get("name", "")
+
+        performance_indicators = [
+            "for " in body
+            and len([line for line in body.split("\n") if "for " in line]) > 1,
+            "while " in body,
+            body.count("for ") > 0 and len(body) > 200,
+            any(pattern in body for pattern in (".append(", "+=", ".extend(", "len(")),
+            any(
+                pattern in name
+                for pattern in (
+                    "process",
+                    "analyze",
+                    "compute",
+                    "calculate",
+                    "optimize",
+                )
+            ),
+            "range(" in body and ("1000" in body or "len(" in body),
+        ]
+
+        return any(performance_indicators)
+
+    @staticmethod
+    def _estimate_complexity(body: str) -> int:
+        """Estimate computational complexity of function.
+
+        Args:
+            body: Function body
+
+        Returns:
+            Complexity score
+        """
+        complexity = 1
+
+        nested_for_loops = 0
+        for_depth = 0
+        lines = body.split("\n")
+
+        for line in lines:
+            stripped = line.strip()
+            if "for " in stripped:
+                for_depth += 1
+                nested_for_loops = max(nested_for_loops, for_depth)
+            elif (
+                stripped
+                and not stripped.startswith("#")
+                and len(line) - len(line.lstrip()) == 0
+            ):
+                for_depth = 0
+
+        complexity = max(complexity, nested_for_loops)
+
+        if ".sort(" in body or "sorted(" in body:
+            complexity += 1
+        if body.count("len(") > 5:
+            complexity += 1
+        if ".index(" in body or ".find(" in body:
+            complexity += 1
+
+        return complexity
+
+    def analyze_performance_patterns(
+        self, semantic_insight: t.Any, current_func: dict[str, t.Any]
+    ) -> dict[str, t.Any]:
+        """Analyze semantic patterns for performance insights.
+
+        Args:
+            semantic_insight: Semantic insight from analysis
+            current_func: Current function
+
+        Returns:
+            Analysis dict
+        """
+        analysis: dict[str, t.Any] = {
+            "issues_found": False,
+            "optimization_suggestion": "Consider reviewing similar implementations for consistency",
+            "pattern_insights": [],
+        }
+
+        if semantic_insight.high_confidence_matches > 0:
+            analysis["issues_found"] = True
+            analysis["pattern_insights"].append(
+                f"Found {semantic_insight.high_confidence_matches} highly similar implementations"
+            )
+
+            performance_concerns = []
+            for pattern in semantic_insight.related_patterns:
+                content = pattern.get("content", "").lower()
+                if any(
+                    concern in content for concern in ("for", "while", "+=", "append")
+                ):
+                    performance_concerns.append(pattern["file_path"])
+
+            if performance_concerns:
+                analysis["optimization_suggestion"] = (
+                    f"Performance review needed: {len(performance_concerns)} similar functions "
+                    f"may benefit from the same optimization approach"
+                )
+                analysis["pattern_insights"].append(
+                    f"Similar performance patterns found in: {', '.join(list(set(performance_concerns))[:3])}"
+                )
+
+        return analysis
+
+    def analyze_code_metrics(self, tree: ast.AST) -> dict[str, t.Any]:
+        """Analyze code metrics from AST.
+
+        Args:
+            tree: AST tree
+
+        Returns:
+            Metrics dict
+        """
+        metrics: dict[str, t.Any] = {
+            "total_functions": 0,
+            "total_classes": 0,
+            "average_function_length": 0,
+            "max_nesting_depth": 0,
+            "high_complexity_functions": [],
+        }
+
+        class MetricsCollector(ast.NodeVisitor):
+            def __init__(self) -> None:
+                self.function_count = 0
+                self.class_count = 0
+                self.function_lengths: list[int] = []
+                self.max_depth = 0
+
+            def visit_FunctionDef(self, node: ast.FunctionDef) -> None:
+                self.function_count += 1
+                length = (node.end_lineno or node.lineno) - node.lineno
+                self.function_lengths.append(length)
+                self.generic_visit(node)
+
+            def visit_ClassDef(self, node: ast.ClassDef) -> None:
+                self.class_count += 1
+                self.generic_visit(node)
+
+        collector = MetricsCollector()
+        collector.visit(tree)
+
+        metrics["total_functions"] = collector.function_count
+        metrics["total_classes"] = collector.class_count
+
+        if collector.function_lengths:
+            metrics["average_function_length"] = sum(collector.function_lengths) / len(
+                collector.function_lengths
+            )
+
+        return metrics