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

crackerjack/orchestration/cache/tool_proxy_cache.py

@@ -0,0 +1,340 @@
+"""Tool proxy cache adapter for hook result caching.
+
+Bridges to existing tool_proxy cache infrastructure for consistent caching
+across the crackerjack ecosystem. Implements content-based cache keys using
+hash of hook configuration and file contents.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import json
+import logging
+import typing as t
+from contextlib import suppress
+from pathlib import Path
+from uuid import UUID
+
+from pydantic import BaseModel, Field
+
+from crackerjack.models.task import HookResult
+
+if t.TYPE_CHECKING:
+    from crackerjack.config.hooks import HookDefinition
+
+# ACB Module Registration (REQUIRED)
+MODULE_ID = UUID("01937d86-ace0-7000-8000-000000000004")  # Static UUID7
+MODULE_STATUS = "stable"
+
+logger = logging.getLogger(__name__)
+
+
+class ToolProxyCacheSettings(BaseModel):
+    """Settings for tool proxy cache adapter."""
+
+    default_ttl: int = Field(default=3600, ge=60, le=86400)  # 1 minute to 24 hours
+    max_cache_size_mb: int = Field(default=100, ge=10, le=1000)
+    enable_compression: bool = True
+
+
+class ToolProxyCacheAdapter:
+    """Cache adapter bridging to tool_proxy infrastructure.
+
+    Features:
+    - Content-based cache keys (config + file hashes)
+    - Configurable TTL per hook result
+    - Integration with existing tool_proxy cache
+    - Automatic cache invalidation on content changes
+
+    Cache Key Format:
+        {hook_name}:{config_hash}:{content_hash}
+
+    Example:
+        ```python
+        cache = ToolProxyCacheAdapter()
+        await cache.init()
+
+        # Check cache
+        cached_result = await cache.get(cache_key)
+        if cached_result:
+            return cached_result
+
+        # Execute hook and cache result
+        result = await execute_hook(hook)
+        await cache.set(cache_key, result, ttl=3600)
+        ```
+    """
+
+    def __init__(
+        self,
+        settings: ToolProxyCacheSettings | None = None,
+        cache_dir: Path | None = None,
+    ) -> None:
+        """Initialize tool proxy cache adapter.
+
+        Args:
+            settings: Optional cache settings
+            cache_dir: Optional cache directory (defaults to .crackerjack/cache)
+        """
+        self.settings = settings or ToolProxyCacheSettings()
+        self._cache_dir = cache_dir or Path.cwd() / ".crackerjack" / "cache"
+        self._cache: dict[
+            str, tuple[HookResult, float]
+        ] = {}  # key -> (result, expiry_timestamp)
+        self._initialized = False
+
+        logger.debug(
+            "ToolProxyCacheAdapter initializing",
+            extra={
+                "cache_dir": str(self._cache_dir),
+                "default_ttl": self.settings.default_ttl,
+                "enable_compression": self.settings.enable_compression,
+            },
+        )
+
+    async def init(self) -> None:
+        """Initialize cache adapter and ensure cache directory exists."""
+        if self._initialized:
+            logger.debug("Cache adapter already initialized")
+            return
+
+        try:
+            self._cache_dir.mkdir(parents=True, exist_ok=True)
+            self._initialized = True
+
+            logger.info(
+                "ToolProxyCacheAdapter initialized",
+                extra={
+                    "cache_dir": str(self._cache_dir),
+                    "default_ttl": self.settings.default_ttl,
+                },
+            )
+        except Exception as e:
+            logger.error(
+                "Failed to initialize cache adapter",
+                extra={
+                    "error": str(e),
+                    "cache_dir": str(self._cache_dir),
+                },
+            )
+            raise
+
+    async def get(self, key: str) -> HookResult | None:
+        """Retrieve cached hook result.
+
+        Args:
+            key: Cache key (computed via compute_key())
+
+        Returns:
+            Cached HookResult if found and not expired, None otherwise
+        """
+        if not self._initialized:
+            logger.warning("Cache adapter not initialized, returning None")
+            return None
+
+        try:
+            import time
+
+            if key in self._cache:
+                result, expiry = self._cache[key]
+
+                # Check expiration
+                if time.time() < expiry:
+                    logger.debug(
+                        "Cache hit",
+                        extra={
+                            "key": key,
+                            "hook_name": result.name,
+                            "status": result.status,
+                        },
+                    )
+                    return result
+                else:
+                    # Expired - remove from cache
+                    del self._cache[key]
+                    logger.debug("Cache entry expired", extra={"key": key})
+
+            logger.debug("Cache miss", extra={"key": key})
+            return None
+
+        except Exception as e:
+            logger.error(
+                "Failed to retrieve from cache",
+                extra={
+                    "key": key,
+                    "error": str(e),
+                },
+            )
+            return None
+
+    async def set(
+        self,
+        key: str,
+        result: HookResult,
+        ttl: int | None = None,
+    ) -> None:
+        """Cache hook result with TTL.
+
+        Args:
+            key: Cache key (computed via compute_key())
+            result: HookResult to cache
+            ttl: Optional time-to-live in seconds (defaults to settings.default_ttl)
+        """
+        if not self._initialized:
+            logger.warning("Cache adapter not initialized, skipping cache write")
+            return
+
+        try:
+            import time
+
+            ttl_sec = ttl or self.settings.default_ttl
+            expiry = time.time() + ttl_sec
+
+            self._cache[key] = (result, expiry)
+
+            logger.debug(
+                "Cache write",
+                extra={
+                    "key": key,
+                    "hook_name": result.name,
+                    "status": result.status,
+                    "ttl": ttl_sec,
+                },
+            )
+
+        except Exception as e:
+            logger.error(
+                "Failed to write to cache",
+                extra={
+                    "key": key,
+                    "error": str(e),
+                },
+            )
+
+    def compute_key(
+        self,
+        hook: HookDefinition,
+        files: list[Path],
+    ) -> str:
+        """Compute content-based cache key.
+
+        Cache key format: {hook_name}:{config_hash}:{content_hash}
+
+        Args:
+            hook: Hook definition
+            files: List of files to be checked by hook
+
+        Returns:
+            Cache key string
+        """
+        try:
+            # Hash hook configuration (Phase 8+ direct invocation API)
+            config_data = {
+                "name": hook.name,
+                "command": hook.command,  # Direct tool invocation command
+                "timeout": hook.timeout,
+                "stage": hook.stage.value
+                if hasattr(hook.stage, "value")
+                else str(hook.stage),
+                "security_level": hook.security_level.value
+                if hasattr(hook.security_level, "value")
+                else str(hook.security_level),
+            }
+            config_json = json.dumps(config_data, sort_keys=True)
+            config_hash = hashlib.sha256(config_json.encode()).hexdigest()[:16]
+
+            # Hash file contents (for cache invalidation on content changes)
+            content_hasher = hashlib.sha256()
+            for file_path in sorted(files):
+                try:
+                    if file_path.exists() and file_path.is_file():
+                        content_hasher.update(file_path.read_bytes())
+                except Exception as e:
+                    logger.warning(
+                        f"Failed to hash file {file_path}: {e}",
+                        extra={"file": str(file_path), "error": str(e)},
+                    )
+                    continue
+
+            content_hash = content_hasher.hexdigest()[:16]
+
+            cache_key = f"{hook.name}:{config_hash}:{content_hash}"
+
+            logger.debug(
+                "Cache key computed",
+                extra={
+                    "hook_name": hook.name,
+                    "file_count": len(files),
+                    "config_hash": config_hash,
+                    "content_hash": content_hash,
+                },
+            )
+
+            return cache_key
+
+        except Exception as e:
+            logger.error(
+                "Failed to compute cache key",
+                extra={
+                    "hook_name": hook.name,
+                    "error": str(e),
+                },
+            )
+            # Fallback to simple key
+            return f"{hook.name}:error"
+
+    async def clear(self) -> None:
+        """Clear all cached results."""
+        try:
+            self._cache.clear()
+            logger.info("Cache cleared")
+        except Exception as e:
+            logger.error("Failed to clear cache", extra={"error": str(e)})
+
+    async def get_stats(self) -> dict[str, t.Any]:
+        """Get cache statistics.
+
+        Returns:
+            Dictionary with cache statistics
+        """
+        import time
+
+        try:
+            total_entries = len(self._cache)
+            expired_entries = sum(
+                1 for _, expiry in self._cache.values() if time.time() >= expiry
+            )
+            active_entries = total_entries - expired_entries
+
+            stats = {
+                "total_entries": total_entries,
+                "active_entries": active_entries,
+                "expired_entries": expired_entries,
+                "cache_dir": str(self._cache_dir),
+                "default_ttl": self.settings.default_ttl,
+            }
+
+            logger.debug("Cache statistics", extra=stats)
+
+            return stats
+
+        except Exception as e:
+            logger.error("Failed to get cache statistics", extra={"error": str(e)})
+            return {}
+
+    @property
+    def module_id(self) -> UUID:
+        """Reference to module-level MODULE_ID."""
+        return MODULE_ID
+
+    @property
+    def adapter_name(self) -> str:
+        """Human-readable adapter name."""
+        return "ToolProxyCacheAdapter"
+
+
+# ACB Registration (REQUIRED at module level)
+with suppress(Exception):
+    from acb.depends import depends
+
+    depends.set(ToolProxyCacheAdapter)

crackerjack/orchestration/config.py

@@ -0,0 +1,297 @@
+from __future__ import annotations
+
+import dataclasses
+import os
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import TYPE_CHECKING, Any
+
+if TYPE_CHECKING:
+    from typing import Self
+else:
+    Self = "OrchestrationConfig"
+
+import yaml
+from acb.depends import depends
+
+from crackerjack.config.settings import CrackerjackSettings
+
+
+def _bool_from_env(value: str) -> bool:
+    return value.strip().lower() in {"1", "true", "yes", "on"}
+
+
+def _int_from_env(value: str, default: int) -> int:
+    try:
+        return int(value)
+    except ValueError:
+        return default
+
+
+@dataclass
+class OrchestrationConfig:
+    enable_orchestration: bool = True
+    orchestration_mode: str = "acb"
+    enable_caching: bool = True
+    cache_backend: str = "memory"
+    cache_ttl: int = 3600
+    cache_max_entries: int = 100
+    max_parallel_hooks: int = 4
+    default_timeout: int = 600
+    stop_on_critical_failure: bool = True
+    enable_dependency_resolution: bool = True
+    log_cache_stats: bool = False
+    log_execution_timing: bool = False
+    enable_strategy_parallelism: bool = True
+    enable_adaptive_execution: bool = True
+    max_concurrent_strategies: int = 2
+    enable_tool_proxy: bool = True
+    use_precommit_legacy: bool = True
+    config_file_path: Path | None = field(default=None, repr=False)
+
+    # --------------------------------------------------------------------- #
+    # Construction helpers
+    # --------------------------------------------------------------------- #
+
+    @classmethod
+    def from_settings(
+        cls,
+        settings: CrackerjackSettings | None = None,
+    ) -> OrchestrationConfig:
+        """Build configuration from CrackerjackSettings via DI."""
+        if settings is None:
+            try:
+                # Use synchronous DI retrieval to avoid coroutine leakage in tests
+                settings = depends.get_sync(CrackerjackSettings)  # type: ignore[attr-defined]
+            except Exception:
+                settings = None
+
+        if settings is None:
+            return cls()
+
+        return cls(
+            enable_orchestration=settings.enable_orchestration,
+            orchestration_mode=settings.orchestration_mode,
+            enable_caching=settings.enable_caching,
+            cache_backend=settings.cache_backend,
+            cache_ttl=settings.cache_ttl,
+            cache_max_entries=settings.cache_max_entries,
+            max_parallel_hooks=settings.max_parallel_hooks,
+            default_timeout=settings.default_timeout,
+            stop_on_critical_failure=settings.stop_on_critical_failure,
+            enable_dependency_resolution=settings.enable_dependency_resolution,
+            log_cache_stats=settings.log_cache_stats,
+            log_execution_timing=settings.log_execution_timing,
+            enable_strategy_parallelism=settings.enable_strategy_parallelism,
+            enable_adaptive_execution=settings.enable_adaptive_execution,
+            max_concurrent_strategies=settings.max_concurrent_strategies,
+            enable_tool_proxy=getattr(settings, "enable_tool_proxy", True),
+            use_precommit_legacy=settings.use_precommit_legacy,
+        )
+
+    @classmethod
+    def from_file(cls, config_path: Path) -> OrchestrationConfig:
+        if not config_path.exists():
+            msg = f"Config file not found: {config_path}"
+            raise FileNotFoundError(msg)
+
+        try:
+            raw = yaml.safe_load(config_path.read_text(encoding="utf-8"))
+            data: dict[str, Any] = raw if isinstance(raw, dict) else {}
+        except yaml.YAMLError as exc:
+            msg = f"Invalid YAML in {config_path}: {exc}"
+            raise ValueError(msg) from exc
+
+        if not isinstance(data, dict):
+            msg = f"Invalid config structure in {config_path}"
+            raise ValueError(msg)
+
+        section_any = data.get("orchestration", {})
+        section: dict[str, Any] = section_any if isinstance(section_any, dict) else {}
+
+        config = cls()
+        config.config_file_path = config_path
+        config._apply_dict(section)
+        return config
+
+    @classmethod
+    def _env_overrides(cls) -> dict[str, Any]:
+        """Return environment variable overrides."""
+        env = os.environ
+        overrides: dict[str, Any] = {}
+
+        mapping: dict[str, str] = {
+            "CRACKERJACK_ORCHESTRATION_MODE": "orchestration_mode",
+            "CRACKERJACK_CACHE_BACKEND": "cache_backend",
+        }
+
+        for env_key, attr in mapping.items():
+            if env_key in env:
+                overrides[attr] = env[env_key]
+
+        bool_vars = {
+            "CRACKERJACK_ENABLE_ORCHESTRATION": "enable_orchestration",
+            "CRACKERJACK_ENABLE_CACHING": "enable_caching",
+            "CRACKERJACK_STOP_ON_CRITICAL_FAILURE": "stop_on_critical_failure",
+            "CRACKERJACK_ENABLE_DEPENDENCY_RESOLUTION": "enable_dependency_resolution",
+            "CRACKERJACK_LOG_CACHE_STATS": "log_cache_stats",
+            "CRACKERJACK_LOG_EXECUTION_TIMING": "log_execution_timing",
+            "CRACKERJACK_ENABLE_STRATEGY_PARALLELISM": "enable_strategy_parallelism",
+            "CRACKERJACK_ENABLE_ADAPTIVE_EXECUTION": "enable_adaptive_execution",
+            "CRACKERJACK_ENABLE_TOOL_PROXY": "enable_tool_proxy",
+            "CRACKERJACK_USE_PRECOMMIT_LEGACY": "use_precommit_legacy",
+        }
+
+        for env_key, attr in bool_vars.items():
+            if env_key in env:
+                overrides[attr] = _bool_from_env(env[env_key])
+
+        int_vars = {
+            "CRACKERJACK_CACHE_TTL": ("cache_ttl", 3600),
+            "CRACKERJACK_CACHE_MAX_ENTRIES": ("cache_max_entries", 100),
+            "CRACKERJACK_MAX_PARALLEL_HOOKS": ("max_parallel_hooks", 4),
+            "CRACKERJACK_DEFAULT_TIMEOUT": ("default_timeout", 600),
+            "CRACKERJACK_MAX_CONCURRENT_STRATEGIES": ("max_concurrent_strategies", 2),
+        }
+
+        for env_key, (attr, default) in int_vars.items():
+            if env_key in env:
+                overrides[attr] = _int_from_env(env[env_key], default)
+
+        return overrides
+
+    @classmethod
+    def from_env(cls) -> OrchestrationConfig:
+        overrides = cls._env_overrides()
+        config = cls()
+        config._apply_dict(overrides)
+        return config
+
+    @classmethod
+    def load(cls, config_path: Path) -> OrchestrationConfig:
+        # Start from hard defaults; only override from file/env.
+        config = cls()
+
+        if config_path.exists():
+            file_config = cls.from_file(config_path)
+            config = config.merge(file_config)  # type: ignore[assignment]
+
+        env_overrides = cls._env_overrides()
+        config = config.with_overrides(**env_overrides)  # type: ignore[assignment]
+
+        return config
+
+    # ------------------------------------------------------------------ #
+    # Mutation helpers
+    # ------------------------------------------------------------------ #
+
+    def _apply_dict(self, values: dict[str, Any]) -> None:
+        # Accept aliases from YAML where keys are shorter (e.g., enable, mode)
+        aliases = {
+            "enable": "enable_orchestration",
+            "mode": "orchestration_mode",
+        }
+        for key, value in values.items():
+            attr = aliases.get(key, key)
+            if not hasattr(self, attr):
+                continue
+            if isinstance(value, str):
+                value = value.strip()
+            setattr(self, attr, value)
+
+    def merge(self, other: OrchestrationConfig) -> OrchestrationConfig:
+        data = dataclasses.asdict(self)
+        other_data = dataclasses.asdict(other)
+        data.update(other_data)
+        merged = OrchestrationConfig(**data)
+        merged.config_file_path = other.config_file_path or self.config_file_path
+        return merged
+
+    def with_overrides(self, **overrides: Any) -> OrchestrationConfig:
+        # Create a shallow copy without using dataclasses.replace to satisfy type checker
+        updated = OrchestrationConfig(**dataclasses.asdict(self))
+        for key, value in overrides.items():
+            if value is not None and hasattr(updated, key):
+                setattr(updated, key, value)
+        return updated
+
+    # ------------------------------------------------------------------ #
+    # Serialisation
+    # ------------------------------------------------------------------ #
+
+    def to_dict(self) -> dict[str, Any]:
+        return {
+            "orchestration": {
+                "enable": self.enable_orchestration,
+                "mode": self.orchestration_mode,
+                "enable_caching": self.enable_caching,
+                "cache_backend": self.cache_backend,
+                "cache_ttl": self.cache_ttl,
+                "cache_max_entries": self.cache_max_entries,
+                "max_parallel_hooks": self.max_parallel_hooks,
+                "default_timeout": self.default_timeout,
+                "stop_on_critical_failure": self.stop_on_critical_failure,
+                "enable_dependency_resolution": self.enable_dependency_resolution,
+                "log_cache_stats": self.log_cache_stats,
+                "log_execution_timing": self.log_execution_timing,
+                "enable_strategy_parallelism": self.enable_strategy_parallelism,
+                "enable_adaptive_execution": self.enable_adaptive_execution,
+                "max_concurrent_strategies": self.max_concurrent_strategies,
+                "enable_tool_proxy": self.enable_tool_proxy,
+                "use_precommit_legacy": self.use_precommit_legacy,
+            }
+        }
+
+    def save(self, config_path: Path) -> None:
+        config_path.write_text(
+            yaml.safe_dump(self.to_dict(), sort_keys=True),
+            encoding="utf-8",
+        )
+
+    # ------------------------------------------------------------------ #
+    # Validation / Conversion
+    # ------------------------------------------------------------------ #
+
+    def validate(self) -> list[str]:
+        errors: list[str] = []
+
+        if self.orchestration_mode not in {"acb", "legacy"}:
+            errors.append("Invalid orchestration_mode; expected 'acb' or 'legacy'")
+
+        if self.cache_backend not in {"memory", "tool_proxy", "redis"}:
+            errors.append(
+                "Invalid cache_backend; expected 'memory', 'tool_proxy', or 'redis'"
+            )
+
+        if self.cache_ttl <= 0:
+            errors.append("cache_ttl must be positive")
+        if self.cache_max_entries <= 0:
+            errors.append("cache_max_entries must be positive")
+        if self.max_parallel_hooks <= 0:
+            errors.append("max_parallel_hooks must be positive")
+        if self.default_timeout <= 0:
+            errors.append("default_timeout must be positive")
+        if self.max_concurrent_strategies <= 0:
+            errors.append("max_concurrent_strategies must be positive")
+
+        return errors
+
+    def to_orchestrator_settings(self) -> Any:
+        from crackerjack.orchestration.hook_orchestrator import HookOrchestratorSettings
+
+        execution_mode = self.orchestration_mode
+        if not self.enable_orchestration:
+            execution_mode = "legacy"
+
+        return HookOrchestratorSettings(
+            execution_mode=execution_mode,
+            enable_caching=self.enable_caching,
+            cache_backend=self.cache_backend,
+            max_parallel_hooks=self.max_parallel_hooks,
+            default_timeout=self.default_timeout,
+            enable_adaptive_execution=self.enable_adaptive_execution,
+        )
+
+
+# Convenience re-export for legacy imports
+__all__ = ["OrchestrationConfig"]