crackerjack 0.38.15__py3-none-any.whl → 0.39.0__py3-none-any.whl

crackerjack/__main__.py

@@ -34,6 +34,12 @@ from .cli.handlers import (
     handle_stop_zuban_lsp,
     handle_watchdog_mode,
 )
+from .cli.semantic_handlers import (
+    handle_remove_from_semantic_index,
+    handle_semantic_index,
+    handle_semantic_search,
+    handle_semantic_stats,
+)
 
 console = Console(force_terminal=True)
 app = typer.Typer(
@@ -1041,17 +1047,10 @@ def _handle_mkdocs_integration(
         return False
 
 
-def _create_mkdocs_services() -> dict[str, t.Any]:
-    """Create and configure MkDocs services."""
-    from logging import getLogger
+def _create_sync_filesystem_service() -> t.Any:
+    """Create filesystem service that matches FileSystemServiceProtocol."""
     from pathlib import Path
 
-    from crackerjack.documentation.mkdocs_integration import (
-        MkDocsIntegrationService,
-        MkDocsSiteBuilder,
-    )
-
-    # Create filesystem service that matches FileSystemServiceProtocol
     class SyncFileSystemService:
         def read_file(self, path: str | Path) -> str:
             return Path(path).read_text()
@@ -1068,7 +1067,12 @@ def _create_mkdocs_services() -> dict[str, t.Any]:
         def ensure_directory(self, path: str | Path) -> None:
             Path(path).mkdir(parents=True, exist_ok=True)
 
-    # Create config manager that implements ConfigManagerProtocol
+    return SyncFileSystemService()
+
+
+def _create_config_manager() -> t.Any:
+    """Create config manager that implements ConfigManagerProtocol."""
+
     class ConfigManager:
         def __init__(self) -> None:
             self._config: dict[str, t.Any] = {}
@@ -1085,11 +1089,48 @@ def _create_mkdocs_services() -> dict[str, t.Any]:
         def load(self) -> bool:
             return True
 
-    filesystem = SyncFileSystemService()
-    config_manager = ConfigManager()
+    return ConfigManager()
+
+
+def _create_logger_adapter(logger: t.Any) -> t.Any:
+    """Create logger adapter for protocol compatibility."""
+
+    class LoggerAdapter:
+        def __init__(self, logger: t.Any) -> None:
+            self._logger = logger
+
+        def debug(self, message: str, **kwargs: t.Any) -> None:
+            self._logger.debug(message)
+
+        def info(self, message: str, **kwargs: t.Any) -> None:
+            self._logger.info(message)
+
+        def warning(self, message: str, **kwargs: t.Any) -> None:
+            self._logger.warning(message)
+
+        def error(self, message: str, **kwargs: t.Any) -> None:
+            self._logger.error(message)
+
+    return LoggerAdapter(logger)
+
+
+def _create_mkdocs_services() -> dict[str, t.Any]:
+    """Create and configure MkDocs services."""
+    from logging import getLogger
+
+    from crackerjack.documentation.mkdocs_integration import (
+        MkDocsIntegrationService,
+        MkDocsSiteBuilder,
+    )
+
+    filesystem = _create_sync_filesystem_service()
+    config_manager = _create_config_manager()
     logger = getLogger(__name__)
+    logger_adapter = _create_logger_adapter(logger)
 
-    integration_service = MkDocsIntegrationService(config_manager, filesystem, logger)
+    integration_service = MkDocsIntegrationService(
+        config_manager, filesystem, logger_adapter
+    )
     builder = MkDocsSiteBuilder(integration_service)
 
     return {"builder": builder, "filesystem": filesystem, "config": config_manager}
@@ -1317,6 +1358,11 @@ def main(
     diff_config: str | None = CLI_OPTIONS["diff_config"],
     config_interactive: bool = CLI_OPTIONS["config_interactive"],
     refresh_cache: bool = CLI_OPTIONS["refresh_cache"],
+    # Semantic search options
+    index: str | None = CLI_OPTIONS["index"],
+    search: str | None = CLI_OPTIONS["search"],
+    semantic_stats: bool = CLI_OPTIONS["semantic_stats"],
+    remove_from_index: str | None = CLI_OPTIONS["remove_from_index"],
 ) -> None:
     options = create_options(
         commit,
@@ -1409,6 +1455,12 @@ def main(
         run_tests=run_tests,
     )
 
+    # Add semantic search options to the options object
+    options.index = index
+    options.search = search
+    options.semantic_stats = semantic_stats
+    options.remove_from_index = remove_from_index
+
     # Setup debug and verbose flags
     ai_fix, verbose = _setup_debug_and_verbose_flags(ai_debug, debug, verbose, options)
     setup_ai_agent_env(ai_fix, ai_debug or debug)
@@ -1442,6 +1494,17 @@ def _process_all_commands(local_vars: t.Any, console: t.Any, options: t.Any) ->
         handle_config_updates(options)
         return False
 
+    # Handle semantic search commands early (they exit after execution)
+    if not _handle_semantic_commands(
+        local_vars["index"],
+        local_vars["search"],
+        local_vars["semantic_stats"],
+        local_vars["remove_from_index"],
+        console,
+        options,
+    ):
+        return False
+
     # Handle server commands (monitoring, websocket, MCP, zuban LSP)
     if _handle_server_commands(
         local_vars["monitor"],
@@ -1625,6 +1688,64 @@ def _handle_coverage_status(
         return False
 
 
+def _handle_semantic_commands(
+    index: str | None,
+    search: str | None,
+    semantic_stats: bool,
+    remove_from_index: str | None,
+    console: Console,
+    options: t.Any,
+) -> bool:
+    """Handle semantic search commands.
+
+    Returns True if execution should continue, False if should return early.
+    """
+    if not _has_semantic_operations(index, search, semantic_stats, remove_from_index):
+        return True
+
+    console.print("[cyan]🔍[/cyan] Running semantic search operations...")
+
+    try:
+        _execute_semantic_operations(index, search, semantic_stats, remove_from_index)
+        return False  # Exit after semantic operations
+
+    except Exception as e:
+        console.print(f"[red]❌[/red] Semantic search error: {e}")
+        return False
+
+
+def _has_semantic_operations(
+    index: str | None,
+    search: str | None,
+    semantic_stats: bool,
+    remove_from_index: str | None,
+) -> bool:
+    """Check if any semantic operations are requested."""
+    return any([index, search, semantic_stats, remove_from_index])
+
+
+def _execute_semantic_operations(
+    index: str | None,
+    search: str | None,
+    semantic_stats: bool,
+    remove_from_index: str | None,
+) -> list[str]:
+    """Execute semantic operations in sequence and return remaining operations."""
+    if index:
+        handle_semantic_index(index)
+
+    if search:
+        handle_semantic_search(search)
+
+    if semantic_stats:
+        handle_semantic_stats()
+
+    if remove_from_index:
+        handle_remove_from_semantic_index(remove_from_index)
+
+    return []
+
+
 def _handle_enterprise_features(local_vars: t.Any, console: t.Any) -> bool:
     """Handle enterprise features."""
     # Handle enterprise optimizer

crackerjack/agents/__init__.py

@@ -7,6 +7,7 @@ from . import (
     performance_agent,
     refactoring_agent,
     security_agent,
+    semantic_agent,
     test_creation_agent,
     test_specialist_agent,
 )
@@ -33,6 +34,7 @@ __all__ = [
     "refactoring_agent",
     "reset_agent_tracker",
     "security_agent",
+    "semantic_agent",
     "test_creation_agent",
     "test_specialist_agent",
 ]

crackerjack/agents/base.py

@@ -28,6 +28,7 @@ class IssueType(Enum):
     TEST_ORGANIZATION = "test_organization"
     COVERAGE_IMPROVEMENT = "coverage_improvement"
     REGEX_VALIDATION = "regex_validation"
+    SEMANTIC_CONTEXT = "semantic_context"
 
 
 @dataclass

crackerjack/agents/claude_code_bridge.py

@@ -0,0 +1,319 @@
+"""
+Bridge between crackerjack's built-in agents and Claude Code's external agents.
+
+This module provides integration between the internal agent system and Claude Code's
+specialized agents located in ~/.claude/agents. It enables crackerjack's built-in
+agents to consult with expert external agents for complex scenarios.
+"""
+
+import logging
+import typing as t
+from pathlib import Path
+
+from .base import AgentContext, FixResult, Issue, IssueType
+
+# Mapping of internal issue types to Claude Code external agents
+CLAUDE_CODE_AGENT_MAPPING = {
+    IssueType.COMPLEXITY: ["refactoring-specialist", "crackerjack-architect"],
+    IssueType.DRY_VIOLATION: ["refactoring-specialist", "crackerjack-architect"],
+    IssueType.PERFORMANCE: ["performance-specialist", "python-pro"],
+    IssueType.SECURITY: ["security-auditor", "python-pro"],
+    IssueType.TYPE_ERROR: ["python-pro", "crackerjack-architect"],
+    IssueType.TEST_FAILURE: ["crackerjack-test-specialist", "python-pro"],
+    IssueType.TEST_ORGANIZATION: ["crackerjack-test-specialist", "testing-specialist"],
+    IssueType.IMPORT_ERROR: ["python-pro", "refactoring-specialist"],
+    IssueType.DOCUMENTATION: ["documentation-specialist", "crackerjack-architect"],
+    IssueType.FORMATTING: ["python-pro"],
+}
+
+# Minimum confidence threshold for consulting external agents
+EXTERNAL_CONSULTATION_THRESHOLD = 0.8
+
+
+class ClaudeCodeBridge:
+    """Bridge for consulting Claude Code external agents."""
+
+    def __init__(self, context: AgentContext) -> None:
+        self.context = context
+        self.logger = logging.getLogger(__name__)
+        self._agent_path = Path.home() / ".claude" / "agents"
+        self._consultation_cache: dict[str, dict[str, t.Any]] = {}
+
+    def should_consult_external_agent(
+        self, issue: Issue, internal_confidence: float
+    ) -> bool:
+        """Determine if we should consult an external Claude Code agent."""
+        # Only consult for complex issues that meet threshold
+        if internal_confidence >= EXTERNAL_CONSULTATION_THRESHOLD:
+            return False
+
+        # Check if we have relevant external agents for this issue type
+        return issue.type in CLAUDE_CODE_AGENT_MAPPING
+
+    def _get_agent_mapping(self) -> dict[t.Any, list[str]]:
+        """Get the agent mapping for external access."""
+        return CLAUDE_CODE_AGENT_MAPPING
+
+    def _get_consultation_threshold(self) -> float:
+        """Get the consultation threshold for external access."""
+        return EXTERNAL_CONSULTATION_THRESHOLD
+
+    def get_recommended_external_agents(self, issue: Issue) -> list[str]:
+        """Get list of recommended external agents for an issue."""
+        return CLAUDE_CODE_AGENT_MAPPING.get(issue.type, [])
+
+    def verify_agent_availability(self, agent_name: str) -> bool:
+        """Check if a Claude Code agent file exists."""
+        agent_file = self._agent_path / f"{agent_name}.md"
+        return agent_file.exists()
+
+    async def consult_external_agent(
+        self, issue: Issue, agent_name: str, context: dict[str, t.Any] | None = None
+    ) -> dict[str, t.Any]:
+        """
+        Consult with a Claude Code external agent for expert guidance.
+
+        This method would ideally use the Task tool to invoke external agents,
+        but since we're within crackerjack's internal system, we'll simulate
+        the consultation process and provide structured recommendations.
+        """
+        cache_key = (
+            f"{agent_name}:{issue.type.value}:{issue.file_path}:{issue.line_number}"
+        )
+
+        if cache_key in self._consultation_cache:
+            self.logger.debug(f"Using cached consultation for {agent_name}")
+            return self._consultation_cache[cache_key]
+
+        if not self.verify_agent_availability(agent_name):
+            self.logger.warning(f"Agent {agent_name} not available in ~/.claude/agents")
+            return {"status": "unavailable", "recommendations": []}
+
+        # Generate consultation based on agent expertise and issue type
+        consultation = await self._generate_agent_consultation(
+            issue, agent_name, context
+        )
+
+        # Cache successful consultations
+        if consultation.get("status") == "success":
+            self._consultation_cache[cache_key] = consultation
+
+        return consultation
+
+    async def _generate_agent_consultation(
+        self, issue: Issue, agent_name: str, context: dict[str, t.Any] | None = None
+    ) -> dict[str, t.Any]:
+        """Generate structured consultation response from agent expertise."""
+        consultation: dict[str, t.Any] = {
+            "status": "success",
+            "agent": agent_name,
+            "issue_type": issue.type.value,
+            "recommendations": [],
+            "patterns": [],
+            "validation_steps": [],
+            "confidence": 0.9,
+        }
+
+        # Agent-specific consultation logic
+        if agent_name == "crackerjack-architect":
+            consultation.update(
+                await self._consult_crackerjack_architect(issue, context)
+            )
+        elif agent_name == "python-pro":
+            consultation.update(await self._consult_python_pro(issue, context))
+        elif agent_name == "security-auditor":
+            consultation.update(await self._consult_security_auditor(issue, context))
+        elif agent_name == "refactoring-specialist":
+            consultation.update(
+                await self._consult_refactoring_specialist(issue, context)
+            )
+        elif agent_name == "crackerjack-test-specialist":
+            consultation.update(await self._consult_test_specialist(issue, context))
+        else:
+            consultation.update(
+                await self._consult_generic_agent(issue, agent_name, context)
+            )
+
+        return consultation
+
+    async def _consult_crackerjack_architect(
+        self, issue: Issue, context: dict[str, t.Any] | None = None
+    ) -> dict[str, t.Any]:
+        """Consult with crackerjack-architect for architectural guidance."""
+        return {
+            "recommendations": [
+                "Apply clean code principles (DRY, YAGNI, KISS)",
+                "Follow crackerjack's modular architecture patterns",
+                "Use protocol-based dependency injection",
+                "Break complex functions into focused helper methods",
+                "Maintain single responsibility principle",
+            ],
+            "patterns": [
+                "extract_method",
+                "dependency_injection",
+                "protocol_interfaces",
+                "helper_methods",
+                "single_responsibility",
+            ],
+            "validation_steps": [
+                "run_complexity_check",
+                "verify_type_annotations",
+                "check_architectural_consistency",
+                "validate_against_crackerjack_patterns",
+            ],
+        }
+
+    async def _consult_python_pro(
+        self, issue: Issue, context: dict[str, t.Any] | None = None
+    ) -> dict[str, t.Any]:
+        """Consult with python-pro for Python-specific best practices."""
+        return {
+            "recommendations": [
+                "Use modern Python 3.13+ type hints with | unions",
+                "Apply proper error handling patterns",
+                "Follow PEP 8 style guidelines",
+                "Use pathlib over os.path",
+                "Implement proper context managers",
+            ],
+            "patterns": [
+                "type_annotations",
+                "context_managers",
+                "exception_handling",
+                "python_idioms",
+                "modern_syntax",
+            ],
+            "validation_steps": [
+                "run_type_checking",
+                "verify_python_compatibility",
+                "check_style_compliance",
+                "validate_error_handling",
+            ],
+        }
+
+    async def _consult_security_auditor(
+        self, issue: Issue, context: dict[str, t.Any] | None = None
+    ) -> dict[str, t.Any]:
+        """Consult with security-auditor for security best practices."""
+        return {
+            "recommendations": [
+                "Never use hardcoded paths or credentials",
+                "Use secure temp file creation",
+                "Avoid shell=True in subprocess calls",
+                "Implement proper input validation",
+                "Use environment variables for sensitive data",
+            ],
+            "patterns": [
+                "secure_temp_files",
+                "input_validation",
+                "safe_subprocess",
+                "environment_variables",
+                "sanitization",
+            ],
+            "validation_steps": [
+                "run_security_scan",
+                "check_for_hardcoded_secrets",
+                "validate_subprocess_calls",
+                "verify_temp_file_handling",
+            ],
+        }
+
+    async def _consult_refactoring_specialist(
+        self, issue: Issue, context: dict[str, t.Any] | None = None
+    ) -> dict[str, t.Any]:
+        """Consult with refactoring-specialist for code improvement."""
+        return {
+            "recommendations": [
+                "Break down complex functions (complexity ≤ 15)",
+                "Extract common patterns into utilities",
+                "Remove dead code and unused imports",
+                "Apply DRY principle to eliminate duplication",
+                "Use composition over inheritance",
+            ],
+            "patterns": [
+                "extract_method",
+                "eliminate_duplication",
+                "dead_code_removal",
+                "complexity_reduction",
+                "composition_pattern",
+            ],
+            "validation_steps": [
+                "measure_complexity_reduction",
+                "verify_test_coverage_maintained",
+                "check_for_dead_code",
+                "validate_duplication_removal",
+            ],
+        }
+
+    async def _consult_test_specialist(
+        self, issue: Issue, context: dict[str, t.Any] | None = None
+    ) -> dict[str, t.Any]:
+        """Consult with crackerjack-test-specialist for testing guidance."""
+        return {
+            "recommendations": [
+                "Avoid complex async tests that can hang",
+                "Use synchronous config tests for reliability",
+                "Mock external dependencies properly",
+                "Follow crackerjack's testing patterns",
+                "Maintain test coverage ratchet",
+            ],
+            "patterns": [
+                "synchronous_tests",
+                "proper_mocking",
+                "test_organization",
+                "coverage_improvement",
+                "fixture_patterns",
+            ],
+            "validation_steps": [
+                "run_test_suite",
+                "verify_coverage_increase",
+                "check_test_reliability",
+                "validate_mock_usage",
+            ],
+        }
+
+    async def _consult_generic_agent(
+        self, issue: Issue, agent_name: str, context: dict[str, t.Any] | None = None
+    ) -> dict[str, t.Any]:
+        """Generic consultation for unspecified agents."""
+        return {
+            "recommendations": [
+                f"Consult {agent_name} documentation for specific guidance",
+                "Apply domain-specific best practices",
+                "Follow established patterns and conventions",
+            ],
+            "patterns": ["domain_specific_patterns"],
+            "validation_steps": ["validate_domain_requirements"],
+        }
+
+    def create_enhanced_fix_result(
+        self, base_result: FixResult, consultations: list[dict[str, t.Any]]
+    ) -> FixResult:
+        """Enhance a FixResult with external agent consultations."""
+        enhanced_result = FixResult(
+            success=base_result.success,
+            confidence=base_result.confidence,
+            fixes_applied=base_result.fixes_applied.copy(),
+            remaining_issues=base_result.remaining_issues.copy(),
+            recommendations=base_result.recommendations.copy(),
+            files_modified=base_result.files_modified.copy(),
+        )
+
+        # Aggregate recommendations from all consultations
+        for consultation in consultations:
+            if consultation.get("status") == "success":
+                agent_name = consultation.get("agent", "unknown")
+                enhanced_result.recommendations.extend(
+                    [
+                        f"[{agent_name}] {rec}"
+                        for rec in consultation.get("recommendations", [])
+                    ]
+                )
+
+                # Boost confidence if external agents provided guidance
+                external_confidence = consultation.get("confidence", 0.0)
+                enhanced_result.confidence = max(
+                    enhanced_result.confidence,
+                    (enhanced_result.confidence + external_confidence) / 2,
+                )
+
+        return enhanced_result

crackerjack/agents/coordinator.py

@@ -450,12 +450,15 @@ class AgentCoordinator:
 
         try:
             plan = await architect.plan_before_action(primary_issue)
-            plan = self._enrich_architectural_plan(plan, all_issues)
+            # Ensure plan is properly typed as dict[str, Any]
+            if not isinstance(plan, dict):
+                plan = {"strategy": "default", "confidence": 0.5}
+            enriched_plan = self._enrich_architectural_plan(plan, all_issues)
 
             self.logger.info(
-                f"Created architectural plan: {plan.get('strategy', 'unknown')}"
+                f"Created architectural plan: {enriched_plan.get('strategy', 'unknown')}"
             )
-            return plan  # type: ignore[no-any-return]
+            return enriched_plan
 
         except Exception as e:
             self.logger.exception(f"Failed to create architectural plan: {e}")