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

crackerjack/adapters/README.md

@@ -0,0 +1,18 @@
+# Adapters
+
+Interfaces and adapters to external tools/services or subsystems. Each adapter follows ACB-style patterns with typed settings, async initialization, and standardized results.
+
+## Index
+
+- [AI](<./ai/README.md>) — Claude-powered code fixing and AI helpers
+- [Complexity](<./complexity/README.md>) — Code complexity analysis (Complexipy)
+- [Format](<./format/README.md>) — Code and docs formatting (Ruff, Mdformat)
+- [Lint](<./lint/README.md>) — Spelling and simple linters (Codespell)
+- [LSP](<./lsp/README.md>) — Rust tools with LSP (Zuban, Skylos)
+- [Refactor](<./refactor/README.md>) — Modernization and dead-code (Refurb, Creosote, Skylos)
+- [SAST](<./sast/README.md>) — Static application security testing (Semgrep, Bandit, Pyscn)
+- [Security](<./security/README.md>) — Secret leak prevention and credential detection (Gitleaks)
+- [Type](<./type/README.md>) — Static type checking (Zuban, Pyrefly, Ty)
+- [Utility](<./utility/README.md>) — Small config-driven checks (EOF newline, regex, size)
+
+See `crackerjack/models/qa_config.py` and `crackerjack/models/qa_results.py` for configuration and result schemas used across adapters.

crackerjack/adapters/__init__.py

@@ -1,9 +1,31 @@
-"""Rust tool adapters for unified integration."""
+"""Rust tool adapters for unified integration.
 
-from .rust_tool_adapter import Issue, RustToolAdapter, ToolResult
-from .rust_tool_manager import RustToolHookManager
-from .skylos_adapter import DeadCodeIssue, SkylosAdapter
-from .zuban_adapter import TypeIssue, ZubanAdapter
+QA Framework Adapters:
+The QA framework adapters are organized by check type in subdirectories:
+- format/: Code formatting (ruff, mdformat)
+- lint/: Code linting (codespell)
+- security/: Security scanning (bandit, gitleaks)
+- type/: Type checking (zuban)
+- refactor/: Refactoring suggestions (refurb, creosote)
+- complexity/: Complexity analysis (complexipy)
+- utility/: Utility checks (text patterns, EOF, syntax, size, deps)
+- shared/: Base classes for all QA adapters
+
+ACB 0.19.0+ auto-discovers adapters via depends.set() at module level.
+"""
+
+from .lsp._base import (
+    Issue,
+    RustToolAdapter,
+    ToolResult,
+)
+from .lsp._manager import RustToolHookManager
+from .lsp.skylos import DeadCodeIssue, SkylosAdapter
+from .lsp.zuban import TypeIssue, ZubanAdapter
+
+# NOTE: ACB 0.19.0+ uses depends.set() for adapter registration at module level
+# AI adapter registration moved to crackerjack.adapters.ai.claude module
+# QA adapters are auto-discovered from their category subdirectories
 
 __all__ = [
     "RustToolAdapter",

crackerjack/adapters/_output_paths.py

@@ -0,0 +1,167 @@
+"""Centralized output path management for adapter files.
+
+This module provides utilities for managing adapter output files in a centralized
+location (.crackerjack/outputs/) to keep the project root clean.
+
+ACB Patterns:
+- Pure utility module (no DI registration needed)
+- Simple, focused responsibility
+- Consistent path management across all adapters
+"""
+
+from __future__ import annotations
+
+import logging
+from datetime import datetime
+from pathlib import Path
+
+logger = logging.getLogger(__name__)
+
+
+class AdapterOutputPaths:
+    """Centralized path manager for adapter output files.
+
+    All adapter output files (JSON results, logs, temporary files) are stored in:
+    .crackerjack/outputs/
+
+    This keeps the project root clean and makes it easy to:
+    - Add to .gitignore
+    - Clean up old files
+    - Find all adapter outputs in one place
+    """
+
+    # Base directory for all adapter outputs
+    OUTPUTS_DIR = ".crackerjack/outputs"
+
+    @classmethod
+    def get_output_dir(cls, adapter_name: str | None = None) -> Path:
+        """Get the output directory for an adapter.
+
+        Args:
+            adapter_name: Optional adapter-specific subdirectory
+
+        Returns:
+            Path to output directory (created if doesn't exist)
+        """
+        base_dir = Path.cwd() / cls.OUTPUTS_DIR
+
+        if adapter_name:
+            output_dir = base_dir / adapter_name
+        else:
+            output_dir = base_dir
+
+        # Create directory if it doesn't exist
+        output_dir.mkdir(parents=True, exist_ok=True)
+
+        return output_dir
+
+    @classmethod
+    def get_output_file(
+        cls,
+        adapter_name: str,
+        filename: str,
+        timestamped: bool = False,
+    ) -> Path:
+        """Get path for an adapter output file.
+
+        Args:
+            adapter_name: Name of the adapter (e.g., 'complexipy', 'bandit')
+            filename: Base filename (e.g., 'results.json')
+            timestamped: If True, add timestamp to filename
+
+        Returns:
+            Full path to output file in .crackerjack/outputs/adapter_name/
+
+        Examples:
+            >>> AdapterOutputPaths.get_output_file("complexipy", "results.json")
+            PosixPath('.crackerjack/outputs/complexipy/results.json')
+
+            >>> AdapterOutputPaths.get_output_file(
+            ...     "bandit", "scan.json", timestamped=True
+            ... )
+            PosixPath('.crackerjack/outputs/bandit/scan_2025_12_09__12:34:56.json')
+        """
+        output_dir = cls.get_output_dir(adapter_name)
+
+        if timestamped:
+            # Add timestamp before extension
+            stem = Path(filename).stem
+            suffix = Path(filename).suffix
+            timestamp = datetime.now().strftime("%Y_%m_%d__%H:%M:%S")
+            filename = f"{stem}_{timestamp}{suffix}"
+
+        return output_dir / filename
+
+    @classmethod
+    def get_latest_output(
+        cls, adapter_name: str, pattern: str = "*.json"
+    ) -> Path | None:
+        """Get the most recently modified output file for an adapter.
+
+        Args:
+            adapter_name: Name of the adapter
+            pattern: Glob pattern for files (default: *.json)
+
+        Returns:
+            Path to most recent file, or None if no files found
+        """
+        output_dir = cls.get_output_dir(adapter_name)
+
+        if not output_dir.exists():
+            return None
+
+        files = sorted(
+            output_dir.glob(pattern),
+            key=lambda p: p.stat().st_mtime,
+            reverse=True,
+        )
+
+        return files[0] if files else None
+
+    @classmethod
+    def cleanup_old_outputs(
+        cls,
+        adapter_name: str,
+        pattern: str = "*.json",
+        keep_latest: int = 5,
+    ) -> int:
+        """Remove old output files, keeping only the most recent ones.
+
+        Args:
+            adapter_name: Name of the adapter
+            pattern: Glob pattern for files (default: *.json)
+            keep_latest: Number of most recent files to keep
+
+        Returns:
+            Number of files deleted
+        """
+        output_dir = cls.get_output_dir(adapter_name)
+
+        if not output_dir.exists():
+            return 0
+
+        files = sorted(
+            output_dir.glob(pattern),
+            key=lambda p: p.stat().st_mtime,
+            reverse=True,
+        )
+
+        # Keep the N most recent files, delete the rest
+        files_to_delete = files[keep_latest:]
+        deleted_count = 0
+
+        for file_path in files_to_delete:
+            try:
+                file_path.unlink()
+                deleted_count += 1
+                logger.debug(f"Deleted old output file: {file_path}")
+            except OSError as e:
+                logger.warning(f"Failed to delete {file_path}: {e}")
+
+        if deleted_count > 0:
+            logger.info(
+                f"Cleaned up {deleted_count} old {adapter_name} output files, "
+                f"kept {keep_latest} most recent"
+            )
+
+        return deleted_count

crackerjack/adapters/_qa_adapter_base.py

@@ -0,0 +1,309 @@
+"""Base adapter for ACB Quality Assurance framework.
+
+This module provides the foundational classes and protocols for implementing
+QA checks as ACB adapters following ACB 0.19.0+ patterns.
+
+Key ACB Patterns:
+- MODULE_ID and MODULE_STATUS are module-level constants in concrete adapters
+- Dependency injection via module-level depends.set() after class definition
+- Runtime-checkable protocols for type safety
+- Concrete base class for shared implementation
+- Settings extend acb.config.Settings with validators
+- Async init() method for lazy initialization
+
+CRITICAL: Imports protocols from models.protocols, not local definitions.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import typing as t
+from contextlib import asynccontextmanager
+from pathlib import Path
+
+from acb.config import Settings
+from pydantic import Field, field_validator
+
+# Import protocol from models.protocols per crackerjack pattern
+from crackerjack.models.protocols import QAAdapterProtocol
+
+if t.TYPE_CHECKING:
+    from uuid import UUID
+
+    from crackerjack.models.qa_config import QACheckConfig
+    from crackerjack.models.qa_results import QAResult
+
+
+class QABaseSettings(Settings):
+    """Base settings for quality assurance adapters.
+
+    All QA adapter settings should inherit from this class to ensure
+    consistent configuration patterns across all checks.
+    """
+
+    enabled: bool = True
+    timeout_seconds: int = Field(300, ge=1, le=7200)
+    file_patterns: list[str] = Field(default_factory=lambda: ["**/*.py"])
+    exclude_patterns: list[str] = Field(default_factory=list)
+    fail_on_error: bool = True
+    verbose: bool = False
+    cache_enabled: bool = True
+    cache_ttl: int = 3600
+    max_workers: int = Field(4, ge=1, le=16)
+
+    @field_validator("timeout_seconds")
+    @classmethod
+    def validate_timeout(cls, v: int) -> int:
+        """Validate timeout is within reasonable bounds."""
+        if v < 1 or v > 3600:
+            raise ValueError("Timeout must be between 1 and 3600 seconds")
+        return v
+
+    @field_validator("max_workers")
+    @classmethod
+    def validate_workers(cls, v: int) -> int:
+        """Validate worker count is reasonable."""
+        if v < 1 or v > 16:
+            raise ValueError("Max workers must be between 1 and 16")
+        return v
+
+
+# QAAdapterProtocol is imported from models.protocols per crackerjack pattern
+# See crackerjack/models/protocols.py for protocol definition
+
+
+from acb.adapters import AdapterMetadata
+
+
+class QAAdapterBase:
+    """Concrete base class for quality assurance adapters.
+
+    Provides shared implementation for all QA adapters following ACB patterns.
+    Unlike traditional abstract base classes, this is concrete and provides
+    default implementations where sensible.
+
+    IMPORTANT ACB Patterns:
+    - MODULE_ID must be defined at module level in concrete adapters (not here)
+    - depends.set() registration happens at module level after class definition
+    - Use async init() for lazy initialization, not __init__
+    - Subclasses override specific methods as needed
+
+    Example:
+        ```python
+        # In concrete adapter file (e.g., ruff_lint.py)
+        import uuid
+        from contextlib import suppress
+        from acb.depends import depends
+        from crackerjack.adapters.qa.base import QAAdapterBase, QABaseSettings
+
+        # MODULE_ID at module level (REQUIRED by ACB)
+        MODULE_ID = uuid.UUID("01937d86-5f2a-7b3c-9d1e-a2b3c4d5e6f7")
+        MODULE_STATUS = "stable"
+
+
+        class RuffLintSettings(QABaseSettings):
+            select_rules: list[str] = []
+            ignore_rules: list[str] = []
+            fix_enabled: bool = False
+
+
+        class RuffLintAdapter(QAAdapterBase):
+            settings: RuffLintSettings | None = None
+
+            async def init(self) -> None:
+                if not self.settings:
+                    self.settings = RuffLintSettings()
+                await super().init()
+
+            @property
+            def adapter_name(self) -> str:
+                return "Ruff Linter"
+
+            @property
+            def module_id(self) -> uuid.UUID:
+                return MODULE_ID
+
+            async def check(self, files=None, config=None):
+                # Implementation here
+                return QAResult(...)
+
+
+        # Register at module level (REQUIRED by ACB)
+        with suppress(Exception):
+            depends.set(RuffLintAdapter)
+        ```
+    """
+
+    settings: QABaseSettings | None = None
+    metadata: AdapterMetadata | None = None
+
+    def __init__(self) -> None:
+        """Initialize adapter instance.
+
+        Note: ACB pattern is to do minimal work here. Use async init()
+        for expensive setup operations.
+        """
+        self._initialized = False
+        self._semaphore: asyncio.Semaphore | None = None
+
+    async def init(self) -> None:
+        """ACB standard initialization method.
+
+        Called lazily before first check. Override in subclasses to:
+        - Load settings
+        - Setup async resources
+        - Initialize clients/connections
+        - Validate configuration
+        """
+        if not self.settings:
+            self.settings = QABaseSettings()
+
+        # Create semaphore for concurrency control
+        max_workers = self.settings.max_workers
+        self._semaphore = asyncio.Semaphore(max_workers)
+
+        self._initialized = True
+
+    @property
+    def adapter_name(self) -> str:
+        """Human-readable adapter name.
+
+        Override in subclasses for better identification.
+        """
+        return self.__class__.__name__
+
+    @property
+    def module_id(self) -> UUID:
+        """Reference to module-level MODULE_ID.
+
+        Must be overridden in concrete adapters to return the
+        module-level MODULE_ID constant.
+        """
+        raise NotImplementedError(
+            f"{self.__class__.__name__} must implement module_id property "
+            "that returns the module-level MODULE_ID constant"
+        )
+
+    async def check(
+        self,
+        files: list[Path] | None = None,
+        config: QACheckConfig | None = None,
+    ) -> QAResult:
+        """Execute the quality assurance check.
+
+        Must be overridden in concrete adapters.
+
+        Args:
+            files: List of files to check (None = check all files matching patterns)
+            config: Optional configuration override for this check
+
+        Returns:
+            QAResult containing the check execution results
+        """
+        raise NotImplementedError(
+            f"{self.__class__.__name__} must implement check() method"
+        )
+
+    async def validate_config(self, config: QACheckConfig) -> bool:
+        """Validate configuration.
+
+        Default implementation provides basic validation.
+        Override for adapter-specific validation.
+
+        Args:
+            config: Configuration to validate
+
+        Returns:
+            True if configuration is valid, False otherwise
+        """
+        return config is not None
+
+    def get_default_config(self) -> QACheckConfig:
+        """Get default configuration.
+
+        Must be overridden in concrete adapters.
+
+        Returns:
+            QACheckConfig with sensible defaults for this check
+        """
+        raise NotImplementedError(
+            f"{self.__class__.__name__} must implement get_default_config() method"
+        )
+
+    async def health_check(self) -> dict[str, t.Any]:
+        """ACB standard health check method.
+
+        Provides basic health status. Override for more detailed checks.
+
+        Returns:
+            Dictionary with health status and metadata
+        """
+        return {
+            "status": "healthy" if self._initialized else "not_initialized",
+            "adapter": self.adapter_name,
+            "module_id": str(self.module_id) if self._initialized else "unknown",
+            "settings_loaded": self.settings is not None,
+            "metadata": self.metadata.dict() if self.metadata else None,
+        }
+
+    def _should_check_file(self, file_path: Path, config: QACheckConfig) -> bool:
+        """Determine if a file should be checked based on patterns.
+
+        Args:
+            file_path: Path to the file
+            config: Configuration containing file patterns
+
+        Returns:
+            True if file should be checked, False otherwise
+        """
+        # Check if file matches any include patterns
+        matches_include = any(
+            file_path.match(pattern) for pattern in config.file_patterns
+        )
+
+        if not matches_include:
+            return False
+
+        # Check if file matches any exclude patterns
+        matches_exclude = any(
+            file_path.match(pattern) for pattern in config.exclude_patterns
+        )
+
+        return not matches_exclude
+
+    @asynccontextmanager
+    async def _lifecycle(self) -> t.AsyncIterator[QAAdapterBase]:
+        """ACB pattern for resource lifecycle management.
+
+        Use this context manager for proper setup/teardown:
+
+        ```python
+        async with adapter._lifecycle():
+            result = await adapter.check(files)
+        ```
+        """
+        try:
+            if not self._initialized:
+                await self.init()
+            yield self
+        finally:
+            await self._cleanup()
+
+    async def _cleanup(self) -> None:
+        """Cleanup async resources.
+
+        Override in subclasses to clean up:
+        - Close connections
+        - Release resources
+        - Flush caches
+        """
+        # Base implementation - subclasses can extend
+        self._semaphore = None
+
+
+# Export the main classes and protocol
+__all__ = [
+    "QAAdapterBase",
+    "QAAdapterProtocol",
+    "QABaseSettings",
+]