python-checkup 0.0.1__py3-none-any.whl

python_checkup/analyzers/typos.py

@@ -0,0 +1,80 @@
+from __future__ import annotations
+
+import asyncio
+import json
+import shutil
+from pathlib import Path
+
+from python_checkup.analysis_request import AnalysisRequest
+from python_checkup.models import Category, Diagnostic, Severity
+
+
+class TyposAnalyzer:
+    """Source-code typo detection via typos."""
+
+    @property
+    def name(self) -> str:
+        return "typos"
+
+    @property
+    def category(self) -> Category:
+        return Category.QUALITY
+
+    async def is_available(self) -> bool:
+        return shutil.which("typos") is not None
+
+    async def analyze(self, request: AnalysisRequest) -> list[Diagnostic]:
+        if not request.files:
+            return []
+
+        cmd = ["typos", "--format", "json", *[str(path) for path in request.files]]
+        timeout = request.config.timeout
+        proc = await asyncio.create_subprocess_exec(
+            *cmd,
+            stdout=asyncio.subprocess.PIPE,
+            stderr=asyncio.subprocess.PIPE,
+        )
+        stdout, _stderr = await asyncio.wait_for(proc.communicate(), timeout=timeout)
+
+        # typos exits 0 when clean, 2 when typos found.
+        if proc.returncode not in (0, 2):
+            return []
+
+        output = stdout.decode().strip()
+        if not output:
+            return []
+
+        diagnostics: list[Diagnostic] = []
+        for line in output.splitlines():
+            try:
+                raw = json.loads(line)
+            except json.JSONDecodeError:
+                continue
+
+            if not isinstance(raw, dict):
+                continue
+
+            path = Path(str(raw.get("path", "unknown")))
+            typo = str(raw.get("typo", ""))
+            corrections = raw.get("corrections", [])
+            fix: str | None = None
+            if isinstance(corrections, list) and corrections:
+                fix = (
+                    f"Replace with: {', '.join(str(item) for item in corrections[:3])}"
+                )
+
+            diagnostics.append(
+                Diagnostic(
+                    file_path=path,
+                    line=int(raw.get("line_num", 0) or 0),
+                    column=int(raw.get("byte_offset", 0) or 0),
+                    severity=Severity.INFO,
+                    rule_id="TYPOS",
+                    tool="typos",
+                    category=Category.QUALITY,
+                    message=f"Possible typo: {typo}",
+                    fix=fix,
+                )
+            )
+
+        return diagnostics

python_checkup/analyzers/vulture.py

@@ -0,0 +1,151 @@
+from __future__ import annotations
+
+import asyncio
+import logging
+from pathlib import Path
+from typing import Any
+
+from python_checkup.analysis_request import AnalysisRequest
+from python_checkup.models import Category, Diagnostic, Severity
+
+logger = logging.getLogger("python_checkup")
+
+# Vulture item types and their human-readable labels
+ITEM_TYPE_LABELS: dict[str, str] = {
+    "attribute": "Unused attribute",
+    "class": "Unused class",
+    "function": "Unused function",
+    "import": "Unused import",
+    "method": "Unused method",
+    "property": "Unused property",
+    "variable": "Unused variable",
+    "unreachable_code": "Unreachable code",
+}
+
+# Map item types to severity
+ITEM_TYPE_SEVERITY: dict[str, Severity] = {
+    "unreachable_code": Severity.ERROR,  # Definitely dead
+    "import": Severity.WARNING,  # Likely dead
+    "function": Severity.WARNING,  # Likely dead
+    "method": Severity.WARNING,  # Likely dead
+    "class": Severity.WARNING,  # Likely dead
+    "variable": Severity.INFO,  # Might be dynamic access
+    "attribute": Severity.INFO,  # Might be dynamic access
+    "property": Severity.INFO,  # Might be dynamic access
+}
+
+
+class VultureAnalyzer:
+    """Dead code detection via Vulture."""
+
+    @property
+    def name(self) -> str:
+        return "vulture"
+
+    @property
+    def category(self) -> Category:
+        return Category.DEAD_CODE
+
+    async def is_available(self) -> bool:
+        """Check if vulture is importable."""
+        try:
+            import vulture  # noqa: F401
+
+            return True
+        except ImportError:
+            return False
+
+    async def analyze(
+        self,
+        request: AnalysisRequest,
+    ) -> list[Diagnostic]:
+        """Run Vulture dead code detection.
+
+        IMPORTANT: Vulture accumulates state across scavenge() calls.
+        A fresh Vulture() instance MUST be created for each analysis run.
+        """
+        files = request.files
+        config = request.config_dict()
+        if not files:
+            return []
+
+        min_confidence: int = 80
+        raw_conf = config.get("min_confidence", 80)
+        if isinstance(raw_conf, int | float):
+            min_confidence = int(raw_conf)
+
+        # Run in thread pool -- Vulture's AST parsing is CPU-bound
+        loop = asyncio.get_running_loop()
+        return await loop.run_in_executor(
+            None, self._analyze_sync, files, min_confidence
+        )
+
+    def _analyze_sync(
+        self,
+        files: list[Path],
+        min_confidence: int,
+    ) -> list[Diagnostic]:
+        """Synchronous analysis -- runs in thread pool."""
+        from vulture.core import Vulture
+
+        # CRITICAL: Fresh instance every time.
+        v = Vulture()
+
+        try:
+            v.scavenge([str(f) for f in files])
+        except Exception as e:
+            logger.error("Vulture scavenge failed: %s", e)
+            return []
+
+        unused_code = v.get_unused_code(min_confidence=min_confidence)
+
+        diagnostics: list[Diagnostic] = []
+        for item in unused_code:
+            severity = ITEM_TYPE_SEVERITY.get(item.typ, Severity.INFO)
+            type_label = ITEM_TYPE_LABELS.get(item.typ, f"Unused {item.typ}")
+
+            diagnostics.append(
+                Diagnostic(
+                    file_path=Path(item.filename),
+                    line=item.first_lineno,
+                    column=0,
+                    severity=severity,
+                    rule_id=f"V-{item.typ}",
+                    tool="vulture",
+                    category=Category.DEAD_CODE,
+                    message=(
+                        f"{type_label}: '{item.name}' ({item.confidence}% confidence)"
+                    ),
+                    fix=_dead_code_fix(item),
+                    end_line=item.last_lineno,
+                )
+            )
+
+        return diagnostics
+
+
+def _dead_code_fix(item: Any) -> str:
+    match item.typ:
+        case "import":
+            return f"Remove unused import '{item.name}'"
+        case "function":
+            return (
+                f"Remove unused function '{item.name}' or add it to a "
+                "whitelist if it's used via dynamic dispatch"
+            )
+        case "method":
+            return (
+                f"Remove unused method '{item.name}' or mark it with "
+                "@typing.override if it implements an interface"
+            )
+        case "class":
+            return (
+                f"Remove unused class '{item.name}' or add it to __all__ "
+                "if it's part of the public API"
+            )
+        case "variable":
+            return f"Remove unused variable '{item.name}' or prefix with underscore"
+        case "unreachable_code":
+            return "Remove unreachable code after return/raise/continue/break"
+        case _:
+            return f"Remove unused {item.typ} '{item.name}'"

python_checkup/cache.py

@@ -0,0 +1,244 @@
+from __future__ import annotations
+
+import hashlib
+import json
+import logging
+import time
+from pathlib import Path
+
+from python_checkup import __version__
+from python_checkup.models import Category, Diagnostic, Severity
+
+logger = logging.getLogger("python_checkup")
+
+# Include the package version so any python-checkup upgrade automatically
+# invalidates the cache (analyzer logic may have changed).
+CACHE_VERSION = f"v1-{__version__}"
+# Maximum age for cache entries before cleanup (7 days)
+CACHE_MAX_AGE_SECONDS = 7 * 24 * 60 * 60
+# Maximum total cache size before cleanup (100 MB)
+CACHE_MAX_SIZE_BYTES = 100 * 1024 * 1024
+
+
+class AnalysisCache:
+    """Per-file, per-analyzer cache backed by the local filesystem.
+
+    Each file's diagnostics are cached independently, keyed on the
+    SHA-256 hash of the file's content. When a file changes, its hash
+    changes, so the old cache entry is never read again.
+
+    The cache directory defaults to .python-checkup-cache/ in the project root.
+    """
+
+    def __init__(self, project_root: Path, enabled: bool = True) -> None:
+        self.project_root = project_root
+        self.enabled = enabled
+        self.cache_dir = project_root / ".python-checkup-cache" / CACHE_VERSION
+        self._hits = 0
+        self._misses = 0
+
+        if self.enabled:
+            self._ensure_cache_dir()
+
+    def _ensure_cache_dir(self) -> None:
+        """Create cache directory and .gitignore if they don't exist."""
+        self.cache_dir.mkdir(parents=True, exist_ok=True)
+
+        gitignore = self.project_root / ".python-checkup-cache" / ".gitignore"
+        if not gitignore.exists():
+            gitignore.write_text("*\n")
+
+    def _file_hash(self, path: Path) -> str:
+        """Compute truncated SHA-256 hash of file contents.
+
+        Returns first 16 hex chars (64 bits) of SHA-256.
+        Reads file in binary mode to avoid encoding issues.
+        """
+        h = hashlib.sha256()
+        try:
+            with open(path, "rb") as f:
+                for chunk in iter(lambda: f.read(8192), b""):
+                    h.update(chunk)
+        except OSError:
+            return "0" * 16
+        return h.hexdigest()[:16]
+
+    def _cache_key(self, analyzer_name: str, file_path: Path) -> str:
+        """Build cache key: {analyzer_name}:{content_hash}."""
+        content_hash = self._file_hash(file_path)
+        return f"{analyzer_name}:{content_hash}"
+
+    def _cache_path(self, cache_key: str) -> Path:
+        # Replace colons for Windows compatibility
+        safe_key = cache_key.replace(":", "_")
+        return self.cache_dir / f"{safe_key}.json"
+
+    def get(self, analyzer_name: str, file_path: Path) -> list[Diagnostic] | None:
+        """Return cached diagnostics if file content hasn't changed.
+
+        Returns None on cache miss. Returns list[Diagnostic] on hit
+        (which may be an empty list, meaning "no issues found").
+        """
+        if not self.enabled:
+            return None
+
+        cache_key = self._cache_key(analyzer_name, file_path)
+        cache_file = self._cache_path(cache_key)
+
+        if not cache_file.exists():
+            self._misses += 1
+            return None
+
+        try:
+            raw = json.loads(cache_file.read_text())
+            diagnostics = [_deserialize_diagnostic(d) for d in raw]
+            self._hits += 1
+            logger.debug("Cache hit: %s for %s", analyzer_name, file_path.name)
+            return diagnostics
+        except (json.JSONDecodeError, KeyError, TypeError, ValueError):
+            logger.debug("Cache corrupted for %s, removing", cache_key)
+            cache_file.unlink(missing_ok=True)
+            self._misses += 1
+            return None
+
+    def set(
+        self,
+        analyzer_name: str,
+        file_path: Path,
+        diagnostics: list[Diagnostic],
+    ) -> None:
+        """Cache diagnostics for a file.
+
+        Stores an empty list for clean files (so we know "no issues"
+        vs "not yet analyzed").
+        """
+        if not self.enabled:
+            return
+
+        cache_key = self._cache_key(analyzer_name, file_path)
+        cache_file = self._cache_path(cache_key)
+
+        try:
+            serialized = [_serialize_diagnostic(d) for d in diagnostics]
+            cache_file.write_text(json.dumps(serialized, default=str))
+        except OSError as e:
+            logger.debug("Failed to write cache for %s: %s", cache_key, e)
+
+    def get_stats(self) -> dict[str, int]:
+        total = self._hits + self._misses
+        return {
+            "hits": self._hits,
+            "misses": self._misses,
+            "total": total,
+            "hit_rate_pct": (round(self._hits / total * 100) if total > 0 else 0),
+        }
+
+    def clear(self) -> int:
+        """Delete all cache entries. Returns number of entries deleted."""
+        count = 0
+        if self.cache_dir.exists():
+            for f in self.cache_dir.glob("*.json"):
+                f.unlink()
+                count += 1
+        logger.info("Cleared %d cache entries", count)
+        return count
+
+    def cleanup(self) -> int:
+        """Remove stale cache entries older than CACHE_MAX_AGE_SECONDS.
+
+        Also enforces CACHE_MAX_SIZE_BYTES by removing oldest entries
+        first. Returns number of entries removed.
+        """
+        if not self.cache_dir.exists():
+            return 0
+
+        now = time.time()
+        entries: list[tuple[Path, float, int]] = []
+        removed = 0
+
+        for f in self.cache_dir.glob("*.json"):
+            stat = f.stat()
+            age = now - stat.st_mtime
+            if age > CACHE_MAX_AGE_SECONDS:
+                f.unlink()
+                removed += 1
+            else:
+                entries.append((f, stat.st_mtime, stat.st_size))
+
+        # Enforce size limit: remove oldest first
+        total_size = sum(size for _, _, size in entries)
+        if total_size > CACHE_MAX_SIZE_BYTES:
+            entries.sort(key=lambda e: e[1])  # oldest first
+            for path, _, size in entries:
+                if total_size <= CACHE_MAX_SIZE_BYTES:
+                    break
+                path.unlink()
+                total_size -= size
+                removed += 1
+
+        if removed > 0:
+            logger.debug("Cache cleanup: removed %d stale entries", removed)
+        return removed
+
+
+def _serialize_diagnostic(d: Diagnostic) -> dict[str, object]:
+    return {
+        "file_path": str(d.file_path),
+        "line": d.line,
+        "column": d.column,
+        "severity": d.severity.value,
+        "rule_id": d.rule_id,
+        "tool": d.tool,
+        "category": d.category.value,
+        "message": d.message,
+        "fix": d.fix,
+        "help_url": d.help_url,
+        "end_line": d.end_line,
+        "end_column": d.end_column,
+    }
+
+
+def _deserialize_diagnostic(data: dict[str, object]) -> Diagnostic:
+    file_path = data["file_path"]
+    line = data["line"]
+    column = data["column"]
+    severity_val = data["severity"]
+    rule_id = data["rule_id"]
+    tool = data["tool"]
+    category_val = data["category"]
+    message = data["message"]
+
+    if (
+        not isinstance(file_path, str)
+        or not isinstance(line, int)
+        or not isinstance(column, int)
+        or not isinstance(severity_val, str)
+        or not isinstance(rule_id, str)
+        or not isinstance(tool, str)
+        or not isinstance(category_val, str)
+        or not isinstance(message, str)
+    ):
+        msg = "Invalid diagnostic data types"
+        raise TypeError(msg)
+
+    fix = data.get("fix")
+    help_url = data.get("help_url")
+    end_line = data.get("end_line")
+    end_column = data.get("end_column")
+
+    return Diagnostic(
+        file_path=Path(file_path),
+        line=line,
+        column=column,
+        severity=Severity(severity_val),
+        rule_id=rule_id,
+        tool=tool,
+        category=Category(category_val),
+        message=message,
+        fix=str(fix) if fix is not None else None,
+        help_url=str(help_url) if help_url is not None else None,
+        end_line=int(end_line) if isinstance(end_line, int | float | str) else None,
+        end_column=int(end_column)
+        if isinstance(end_column, int | float | str)
+        else None,
+    )