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

crackerjack/adapters/lint/codespell.py

@@ -0,0 +1,273 @@
+"""Codespell adapter for ACB QA framework - spelling error detection.
+
+Codespell checks for common spelling errors in code, comments, and documentation.
+It helps maintain professional quality by catching:
+- Typos in comments and docstrings
+- Misspelled variable/function names
+- Documentation errors
+- Common spelling mistakes
+
+ACB Patterns:
+- MODULE_ID and MODULE_STATUS at module level
+- depends.set() registration after class definition
+- Extends BaseToolAdapter for tool execution
+- Async execution with output parsing
+"""
+
+from __future__ import annotations
+
+import typing as t
+from contextlib import suppress
+from pathlib import Path
+from uuid import UUID, uuid4
+
+from acb.depends import depends
+from pydantic import Field
+
+from crackerjack.adapters._tool_adapter_base import (
+    BaseToolAdapter,
+    ToolAdapterSettings,
+    ToolExecutionResult,
+    ToolIssue,
+)
+from crackerjack.models.qa_results import QACheckType
+
+if t.TYPE_CHECKING:
+    from crackerjack.models.qa_config import QACheckConfig
+
+# ACB Module Registration (REQUIRED)
+MODULE_ID = uuid4()
+MODULE_STATUS = "stable"
+
+
+class CodespellSettings(ToolAdapterSettings):
+    """Settings for Codespell adapter."""
+
+    tool_name: str = "codespell"
+    use_json_output: bool = False  # Codespell uses text output
+    fix_enabled: bool = False  # Auto-fix spelling errors
+    skip_hidden: bool = True
+    ignore_words: list[str] = Field(default_factory=list)
+    ignore_words_file: Path | None = None
+    check_filenames: bool = False
+    quiet_level: int = 2  # Only show errors
+
+
+class CodespellAdapter(BaseToolAdapter):
+    """Adapter for Codespell - spelling error checker.
+
+    Detects and optionally fixes common spelling mistakes:
+    - Comments and docstrings
+    - String literals
+    - Variable and function names (optional)
+    - Documentation files
+
+    Features:
+    - Auto-fix support
+    - Custom ignore words
+    - Configurable scanning scope
+    - Multiple file type support
+
+    Example:
+        ```python
+        settings = CodespellSettings(
+            fix_enabled=True,
+            ignore_words=["acb", "pydantic"],
+            skip_hidden=True,
+        )
+        adapter = CodespellAdapter(settings=settings)
+        await adapter.init()
+        result = await adapter.check(files=[Path("src/"), Path("docs/")])
+        ```
+    """
+
+    settings: CodespellSettings | None = None
+
+    def __init__(self, settings: CodespellSettings | None = None) -> None:
+        """Initialize Codespell adapter.
+
+        Args:
+            settings: Optional settings override
+        """
+        super().__init__(settings=settings)
+
+    async def init(self) -> None:
+        """Initialize adapter with default settings."""
+        if not self.settings:
+            self.settings = await CodespellSettings.create_async()
+        await super().init()
+
+    @property
+    def adapter_name(self) -> str:
+        """Human-readable adapter name."""
+        return "Codespell (Spelling)"
+
+    @property
+    def module_id(self) -> UUID:
+        """Reference to module-level MODULE_ID."""
+        return MODULE_ID
+
+    @property
+    def tool_name(self) -> str:
+        """CLI tool name."""
+        return "codespell"
+
+    def build_command(
+        self,
+        files: list[Path],
+        config: QACheckConfig | None = None,
+    ) -> list[str]:
+        """Build Codespell command.
+
+        Args:
+            files: Files/directories to check
+            config: Optional configuration override
+
+        Returns:
+            Command as list of strings
+        """
+        if not self.settings:
+            raise RuntimeError("Settings not initialized")
+
+        cmd = [self.tool_name]
+
+        # Auto-fix
+        if self.settings.fix_enabled:
+            cmd.append("--write-changes")
+
+        # Skip hidden files
+        if self.settings.skip_hidden:
+            cmd.append("--skip=.*")
+
+        # Ignore specific words
+        if self.settings.ignore_words:
+            cmd.extend(["--ignore-words-list", ",".join(self.settings.ignore_words)])
+
+        # Ignore words file
+        if self.settings.ignore_words_file and self.settings.ignore_words_file.exists():
+            cmd.extend(["--ignore-words", str(self.settings.ignore_words_file)])
+
+        # Check filenames
+        if self.settings.check_filenames:
+            cmd.append("--check-filenames")
+
+        # Quiet level
+        cmd.extend(["--quiet-level", str(self.settings.quiet_level)])
+
+        # Add targets
+        cmd.extend([str(f) for f in files])
+
+        return cmd
+
+    def _parse_codespell_line(
+        self, line: str
+    ) -> tuple[Path | None, int | None, str, str | None] | None:
+        """Parse a single line from codespell output.
+
+        Args:
+            line: A line from codespell output
+
+        Returns:
+            Tuple of (file_path, line_number, message, suggestion) or None if parsing fails
+        """
+        # Codespell format: "file.py:10: tyop ==> typo"
+        if ":" not in line or "==>" not in line:
+            return None
+
+        parts = line.split(":", maxsplit=2)
+        if len(parts) < 2:
+            return None
+
+        file_path = Path(parts[0].strip())
+        line_number = int(parts[1].strip()) if parts[1].strip().isdigit() else None
+
+        # Parse error and suggestion
+        error_part = parts[2].strip() if len(parts) > 2 else line
+        if "==>" in error_part:
+            wrong, correct = error_part.split("==>", maxsplit=1)
+            wrong = wrong.strip()
+            correct = correct.strip()
+
+            message = f"Spelling: '{wrong}' should be '{correct}'"
+            suggestion = f"Replace '{wrong}' with '{correct}'"
+        else:
+            message = error_part
+            suggestion = None
+
+        return file_path, line_number, message, suggestion
+
+    async def parse_output(
+        self,
+        result: ToolExecutionResult,
+    ) -> list[ToolIssue]:
+        """Parse Codespell text output into standardized issues.
+
+        Args:
+            result: Raw execution result from Codespell
+
+        Returns:
+            List of parsed issues
+        """
+        if not result.raw_output:
+            return []
+
+        issues = []
+        lines = result.raw_output.strip().split("\n")
+
+        for line in lines:
+            parsed_result = self._parse_codespell_line(line)
+            if parsed_result is not None:
+                file_path, line_number, message, suggestion = parsed_result
+
+                issue = ToolIssue(
+                    file_path=file_path,
+                    line_number=line_number,
+                    message=message,
+                    code="SPELLING",
+                    severity="warning",
+                    suggestion=suggestion,
+                )
+                issues.append(issue)
+
+        return issues
+
+    def _get_check_type(self) -> QACheckType:
+        """Return format check type."""
+        return QACheckType.FORMAT
+
+    def get_default_config(self) -> QACheckConfig:
+        """Get default configuration for Codespell adapter.
+
+        Returns:
+            QACheckConfig with sensible defaults
+        """
+        from crackerjack.models.qa_config import QACheckConfig
+
+        return QACheckConfig(
+            check_id=MODULE_ID,
+            check_name=self.adapter_name,
+            check_type=QACheckType.FORMAT,
+            enabled=True,
+            file_patterns=["**/*.py", "**/*.md", "**/*.rst", "**/*.txt"],
+            exclude_patterns=[
+                "**/.git/**",
+                "**/.venv/**",
+                "**/node_modules/**",
+                "**/__pycache__/**",
+            ],
+            timeout_seconds=60,
+            is_formatter=False,  # Only checks, doesn't format
+            parallel_safe=True,
+            stage="fast",  # Spelling checks in fast stage
+            settings={
+                "fix_enabled": False,
+                "skip_hidden": True,
+                "ignore_words": ["acb", "pydantic", "uuid"],
+                "check_filenames": False,
+            },
+        )
+
+
+# ACB Registration (REQUIRED at module level)
+with suppress(Exception):
+    depends.set(CodespellAdapter)

crackerjack/adapters/lsp/README.md

@@ -0,0 +1,49 @@
+> Crackerjack Docs: [Main](<../../../README.md>) | [Adapters](<../README.md>) | [LSP](<./README.md>)
+
+# LSP Adapters
+
+Rust-backed tools with Language Server Protocol integration for fast, incremental diagnostics.
+
+## Overview
+
+- Shared base (`_base.py`) defines `Issue`/`ToolResult` and adapter protocol
+- Optional LSP paths for low-latency diagnostics, with CLI fallback
+- Useful for continuous analysis in editors and orchestrated runs
+
+## Built-in Implementations
+
+| Module | Description | LSP | Status |
+| ------ | ----------- | --- | ------ |
+| `zuban.py` | Ultra-fast Python type checking with LSP and CLI fallback | Yes | Stable |
+| `skylos.py` | Dead code detection with JSON/text parsing | N/A | Stable |
+
+Support modules:
+
+- `_client.py` — Optimized Zuban LSP client wrapper
+- `_manager.py` — LSP process and workspace lifecycle helpers
+- `_base.py` — Common protocol types and base adapter
+
+## Zuban (LSP) Usage
+
+```python
+from pathlib import Path
+from crackerjack.adapters.lsp.zuban import ZubanAdapter
+
+
+async def typecheck_with_lsp(ctx) -> None:
+    adapter = ZubanAdapter(context=ctx, strict_mode=True, use_lsp=True)
+    result = await adapter.check_with_lsp_or_fallback([Path("src/")])
+    print("errors:", result.error_count, "warnings:", result.warning_count)
+```
+
+CLI helpers are available to manage Zuban LSP via `python -m crackerjack` options (start/stop/restart).
+
+## Notes
+
+- LSP improves iteration speed; adapters transparently fall back to CLI
+- Some Zuban builds may have TOML parsing issues; health checks guard usage
+
+## Related
+
+- [Type](<../type/README.md>) — Non-LSP type checkers and settings
+- [Refactor](<../refactor/README.md>) — Skylos-based dead code detection

crackerjack/adapters/lsp/__init__.py

@@ -0,0 +1,27 @@
+"""LSP adapter consolidation for Rust-based analysis tools.
+
+This module consolidates all LSP-related adapter functionality:
+- Zuban: Type checking with LSP integration
+- Skylos: Dead code detection
+- Base protocols and tool result structures
+- Manager for coordinating multiple tools
+"""
+
+from ._base import BaseRustToolAdapter, Issue, RustToolAdapter, ToolResult
+from ._client import ZubanLSPClient
+from ._manager import RustToolHookManager
+from .skylos import DeadCodeIssue, SkylosAdapter
+from .zuban import TypeIssue, ZubanAdapter
+
+__all__ = [
+    "RustToolAdapter",
+    "BaseRustToolAdapter",
+    "ToolResult",
+    "Issue",
+    "SkylosAdapter",
+    "DeadCodeIssue",
+    "ZubanAdapter",
+    "TypeIssue",
+    "RustToolHookManager",
+    "ZubanLSPClient",
+]

crackerjack/adapters/{rust_tool_manager.py → lsp/_manager.py}

@@ -5,9 +5,9 @@ import time
 import typing as t
 from pathlib import Path
 
-from .rust_tool_adapter import BaseRustToolAdapter, ToolResult
-from .skylos_adapter import SkylosAdapter
-from .zuban_adapter import ZubanAdapter
+from ._base import BaseRustToolAdapter, ToolResult
+from .skylos import SkylosAdapter
+from .zuban import ZubanAdapter
 
 if t.TYPE_CHECKING:
     from crackerjack.orchestration.execution_strategies import ExecutionContext

crackerjack/adapters/{skylos_adapter.py → lsp/skylos.py}

@@ -4,7 +4,7 @@ import typing as t
 from dataclasses import dataclass
 from pathlib import Path
 
-from .rust_tool_adapter import BaseRustToolAdapter, Issue, ToolResult
+from ._base import BaseRustToolAdapter, Issue, ToolResult
 
 if t.TYPE_CHECKING:
     from crackerjack.orchestration.execution_strategies import ExecutionContext
@@ -38,7 +38,7 @@ class SkylosAdapter(BaseRustToolAdapter):
     def __init__(
         self,
         context: "ExecutionContext",
-        confidence_threshold: int = 86,
+        confidence_threshold: int = 99,  # Higher threshold to reduce false positives in DI system
         web_dashboard_port: int = 5090,
     ) -> None:
         """Initialize Skylos adapter."""
@@ -56,7 +56,14 @@ class SkylosAdapter(BaseRustToolAdapter):
 
     def get_command_args(self, target_files: list[Path]) -> list[str]:
         """Get command arguments for Skylos execution."""
-        args = ["uv", "run", "skylos", "--confidence", str(self.confidence_threshold)]
+        # Use higher confidence threshold to avoid false positives from DI system
+        args = [
+            "uv",
+            "run",
+            "skylos",
+            "--confidence",
+            str(max(95, self.confidence_threshold)),
+        ]
 
         # Add JSON mode for AI agents
         if self._should_use_json_output():
@@ -66,14 +73,59 @@ class SkylosAdapter(BaseRustToolAdapter):
         if self.context.interactive:
             args.extend(["--web", "--port", str(self.web_dashboard_port)])
 
-        # Add target files or default to current directory
+        # Add target files or determine the appropriate target directory
         if target_files:
             args.extend(str(f) for f in target_files)
         else:
-            args.append(".")
+            package_target = self._determine_package_target()
+            args.append(package_target)
 
         return args
 
+    def _determine_package_target(self) -> str:
+        """Determine the package target directory to scan."""
+        from pathlib import Path
+
+        # Look for package directory in common locations
+        cwd = Path.cwd()
+        package_name = self._get_package_name_from_pyproject(cwd)
+
+        if not package_name:
+            package_name = self._find_package_directory_with_init(cwd)
+
+        # Default to 'crackerjack' if nothing found
+        if not package_name:
+            package_name = "crackerjack"
+
+        return f"./{package_name}"
+
+    def _get_package_name_from_pyproject(self, cwd: Path) -> str | None:
+        """Get package name from pyproject.toml."""
+        pyproject_path = cwd / "pyproject.toml"
+        if not pyproject_path.exists():
+            return None
+
+        import tomllib
+        from contextlib import suppress
+
+        with suppress(Exception):
+            with pyproject_path.open("rb") as f:
+                data = tomllib.load(f)
+                project_name = data.get("project", {}).get("name")
+                if project_name:
+                    return project_name.replace("-", "_")
+        return None
+
+    def _find_package_directory_with_init(self, cwd: Path) -> str | None:
+        """Find first directory with __init__.py in project root."""
+        excluded = {"tests", "docs", ".venv", "venv", "build", "dist"}
+
+        for item in cwd.iterdir():
+            if item.is_dir() and (item / "__init__.py").exists():
+                if item.name not in excluded:
+                    return item.name
+        return None
+
     def parse_output(self, output: str) -> ToolResult:
         """Parse Skylos output into standardized result."""
         if self._should_use_json_output():
@@ -102,7 +154,7 @@ class SkylosAdapter(BaseRustToolAdapter):
                 for item in data.get("dead_code", [])
             ]
 
-            # Skylos success means no issues found
+            # For skylos, having dead code issues means the check failed (not success)
             success = len(issues) == 0
 
             return ToolResult(
@@ -141,7 +193,7 @@ class SkylosAdapter(BaseRustToolAdapter):
             if issue:
                 issues.append(issue)
 
-        # Success if no issues found
+        # For skylos, having ANY dead code issues means it failed the check
         success = len(issues) == 0
 
         return ToolResult(

crackerjack/adapters/{zuban_adapter.py → lsp/zuban.py}

@@ -6,14 +6,14 @@ from contextlib import suppress
 from dataclasses import dataclass
 from pathlib import Path
 
-from .rust_tool_adapter import BaseRustToolAdapter, Issue, ToolResult
+from ._base import BaseRustToolAdapter, Issue, ToolResult
 
 if t.TYPE_CHECKING:
     from crackerjack.orchestration.execution_strategies import ExecutionContext
     from crackerjack.services.lsp_client import LSPClient
 
 # Import the LSP client wrapper
-from .lsp_client import ZubanLSPClient
+from ._client import ZubanLSPClient
 
 
 @dataclass
@@ -111,12 +111,9 @@ class ZubanAdapter(BaseRustToolAdapter):
 
         try:
             # Import here to avoid circular imports
-            from rich.console import Console
-
             from crackerjack.services.lsp_client import LSPClient
 
-            console = getattr(self.context, "console", Console())
-            self._lsp_client = LSPClient(console=console)
+            self._lsp_client = LSPClient()
             self._lsp_available = self._lsp_client.is_server_running()
 
         except ImportError:

crackerjack/adapters/refactor/README.md

@@ -0,0 +1,59 @@
+> Crackerjack Docs: [Main](<../../../README.md>) | [Adapters](<../README.md>) | [Refactor](<./README.md>)
+
+# Refactor Adapters
+
+Modernization and dead-code tooling to simplify code and reduce risk.
+
+## Overview
+
+- Suggest idiomatic patterns and cleanups (Refurb)
+- Identify unused dependencies (Creosote)
+- Detect dead code for deletion (Skylos)
+
+## Built-in Implementations
+
+| Module | Description | Status |
+| ------ | ----------- | ------ |
+| `refurb.py` | Refactoring suggestions for modern Python idioms | Stable |
+| `creosote.py` | Detects unused dependencies in `pyproject.toml`/`requirements*.txt` | Stable |
+| `skylos.py` | Dead code detection (text/JSON parsing) | Stable |
+
+## Examples
+
+Refurb:
+
+```python
+from pathlib import Path
+from crackerjack.adapters.refactor.refurb import RefurbAdapter, RefurbSettings
+
+
+async def suggest_refactors() -> None:
+    adapter = RefurbAdapter(settings=RefurbSettings(explain=True))
+    await adapter.init()
+    result = await adapter.check(files=[Path("src/")])
+```
+
+Creosote:
+
+```python
+from pathlib import Path
+from crackerjack.adapters.refactor.creosote import CreosoteAdapter, CreosoteSettings
+
+
+async def find_unused_deps() -> None:
+    adapter = CreosoteAdapter(
+        settings=CreosoteSettings(config_file=Path("pyproject.toml"))
+    )
+    await adapter.init()
+    result = await adapter.check()
+```
+
+## Notes
+
+- Treat Refurb suggestions as warnings; human review recommended
+- Exclude dev/build tools in Creosote to avoid false positives
+
+## Related
+
+- [Complexity](<../complexity/README.md>) — Use complexity reports to target refactors
+- [Format](<../format/README.md>) — Formatting changes often enable simpler refactors

crackerjack/adapters/refactor/__init__.py

@@ -0,0 +1,12 @@
+"""Refactor adapters for code improvement suggestions.
+
+Adapters:
+- refurb: Modern Python best practices and idiom suggestions
+- creosote: Unused dependency detection
+- skylos: Dead code detection (unused imports, functions, classes, variables)
+"""
+
+# ACB will auto-discover these adapters via depends.set() in module files
+# No explicit imports needed here
+
+__all__ = []