crackerjack 0.18.2__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/lsp/_base.py

@@ -0,0 +1,194 @@
+"""Base protocol and classes for Rust tool integration."""
+
+import json
+import typing as t
+from abc import ABC, abstractmethod
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Protocol
+
+if t.TYPE_CHECKING:
+    from crackerjack.orchestration.execution_strategies import ExecutionContext
+
+
+@dataclass
+class Issue:
+    """Base class for tool issues."""
+
+    file_path: Path
+    line_number: int
+    message: str
+    severity: str = "error"
+
+    def to_dict(self) -> dict[str, t.Any]:
+        """Convert issue to dictionary."""
+        return {
+            "file_path": str(self.file_path),
+            "line_number": self.line_number,
+            "message": self.message,
+            "severity": self.severity,
+        }
+
+
+@dataclass
+class ToolResult:
+    """Unified result format for all Rust tools."""
+
+    success: bool
+    issues: list[Issue] = field(default_factory=list)
+    error: str | None = None
+    raw_output: str = ""
+    execution_time: float = 0.0
+    tool_version: str | None = None
+    _execution_mode: str | None = None
+
+    @property
+    def has_errors(self) -> bool:
+        """Check if result contains error-level issues."""
+        return any(issue.severity == "error" for issue in self.issues)
+
+    @property
+    def error_count(self) -> int:
+        """Count of error-level issues."""
+        return len([i for i in self.issues if i.severity == "error"])
+
+    @property
+    def warning_count(self) -> int:
+        """Count of warning-level issues."""
+        return len([i for i in self.issues if i.severity == "warning"])
+
+    def to_dict(self) -> dict[str, t.Any]:
+        """Convert result to dictionary."""
+        return {
+            "success": self.success,
+            "issues": [issue.to_dict() for issue in self.issues],
+            "error": self.error,
+            "raw_output": self.raw_output,
+            "execution_time": self.execution_time,
+            "tool_version": self.tool_version,
+            "error_count": self.error_count,
+            "warning_count": self.warning_count,
+        }
+
+
+class RustToolAdapter(Protocol):
+    """Protocol for Rust-based analysis tools."""
+
+    def __init__(self, context: "ExecutionContext") -> None:
+        """Initialize adapter with execution context."""
+        ...
+
+    def get_command_args(self, target_files: list[Path]) -> list[str]:
+        """Get command arguments for tool execution."""
+        ...
+
+    def parse_output(self, output: str) -> ToolResult:
+        """Parse tool output into standardized result."""
+        ...
+
+    def supports_json_output(self) -> bool:
+        """Check if tool supports JSON output mode."""
+        ...
+
+    def get_tool_version(self) -> str | None:
+        """Get tool version if available."""
+        ...
+
+    def validate_tool_available(self) -> bool:
+        """Validate that the tool is available and executable."""
+        ...
+
+
+class BaseRustToolAdapter(ABC):
+    """Abstract base implementation of RustToolAdapter."""
+
+    def __init__(self, context: "ExecutionContext") -> None:
+        """Initialize adapter with execution context."""
+        self.context = context
+        self._tool_version: str | None = None
+
+    @abstractmethod
+    def get_command_args(self, target_files: list[Path]) -> list[str]:
+        """Get command arguments for tool execution."""
+        pass
+
+    @abstractmethod
+    def parse_output(self, output: str) -> ToolResult:
+        """Parse tool output into standardized result."""
+        pass
+
+    @abstractmethod
+    def supports_json_output(self) -> bool:
+        """Check if tool supports JSON output mode."""
+        pass
+
+    @abstractmethod
+    def get_tool_name(self) -> str:
+        """Get the name of the tool."""
+        pass
+
+    def get_tool_version(self) -> str | None:
+        """Get tool version if available."""
+        if self._tool_version is None:
+            self._tool_version = self._fetch_tool_version()
+        return self._tool_version
+
+    def validate_tool_available(self) -> bool:
+        """Validate that the tool is available and executable."""
+        import subprocess
+
+        tool_name = self.get_tool_name()
+        try:
+            result = subprocess.run(
+                ["which", tool_name], capture_output=True, text=True, check=False
+            )
+            return result.returncode == 0
+        except (subprocess.SubprocessError, FileNotFoundError):
+            return False
+
+    def _fetch_tool_version(self) -> str | None:
+        """Fetch tool version from command line."""
+        import subprocess
+
+        tool_name = self.get_tool_name()
+        try:
+            result = subprocess.run(
+                [tool_name, "--version"],
+                capture_output=True,
+                text=True,
+                check=True,
+                timeout=10,
+            )
+            return result.stdout.strip().split("\\n")[0]
+        except (
+            subprocess.SubprocessError,
+            FileNotFoundError,
+            subprocess.TimeoutExpired,
+        ):
+            return None
+
+    def _should_use_json_output(self) -> bool:
+        """Determine if JSON output should be used based on context."""
+        return self.supports_json_output() and (
+            self.context.ai_agent_mode or self.context.ai_debug_mode
+        )
+
+    def _parse_json_output_safe(self, output: str) -> dict[str, t.Any] | None:
+        """Safely parse JSON output with error handling."""
+        try:
+            json_result = json.loads(output)
+            return t.cast(dict[str, t.Any] | None, json_result)
+        except json.JSONDecodeError:
+            # Log the error but don't fail completely
+            return None
+
+    def _create_error_result(
+        self, error_message: str, raw_output: str = ""
+    ) -> ToolResult:
+        """Create a ToolResult for error conditions."""
+        return ToolResult(
+            success=False,
+            error=error_message,
+            raw_output=raw_output,
+            tool_version=self.get_tool_version(),
+        )