python-checkup 0.0.1__py3-none-any.whl

python_checkup/__init__.py

@@ -0,0 +1,9 @@
+from importlib.metadata import PackageNotFoundError, version
+
+try:
+    __version__ = version("python-checkup")
+except PackageNotFoundError:
+    # Fallback for local source execution without installed metadata.
+    __version__ = "0.1.0"
+
+__all__ = ["__version__"]

python_checkup/__main__.py

@@ -0,0 +1,3 @@
+from python_checkup.cli import main
+
+main()

python_checkup/analysis_request.py

@@ -0,0 +1,35 @@
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from pathlib import Path
+
+from python_checkup.config import CheckupConfig
+from python_checkup.models import Category
+
+
+@dataclass
+class AnalysisRequest:
+    """Input contract shared by all analyzers."""
+
+    project_root: Path
+    files: list[Path]
+    config: CheckupConfig
+    categories: set[Category]
+    profile: str
+    framework: str | None = None
+    diff_base: str | None = None
+    quiet: bool = False
+    no_cache: bool = False
+    metadata: dict[str, object] = field(default_factory=dict)
+
+    def config_dict(self) -> dict[str, object]:
+        """Return a mutable dict representation for legacy integrations."""
+        data = self.config.__dict__.copy()
+        data["framework"] = self.framework
+        data["profile"] = self.profile
+        data["categories"] = [
+            category.value
+            for category in sorted(self.categories, key=lambda c: c.value)
+        ]
+        data.update(self.metadata)
+        return data

python_checkup/analyzer_catalog.py

@@ -0,0 +1,100 @@
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+
+from python_checkup.models import Category
+
+
+@dataclass(frozen=True)
+class AnalyzerInfo:
+    """Static metadata about a known analyzer."""
+
+    name: str
+    categories: frozenset[Category]
+    default_enabled: bool = True
+    optional: bool = False
+    requires_network: bool = False
+    project_wide: bool = False
+    profiles: frozenset[str] = field(
+        default_factory=lambda: frozenset({"quick", "default", "full"})
+    )
+
+
+ANALYZER_CATALOG: dict[str, AnalyzerInfo] = {
+    "ruff": AnalyzerInfo(
+        name="ruff",
+        categories=frozenset(
+            {
+                Category.QUALITY,
+                Category.SECURITY,
+                Category.COMPLEXITY,
+                Category.DEAD_CODE,
+            }
+        ),
+        profiles=frozenset({"quick", "default", "full"}),
+    ),
+    "mypy": AnalyzerInfo(
+        name="mypy",
+        categories=frozenset({Category.TYPE_SAFETY}),
+        profiles=frozenset({"default", "full"}),
+        project_wide=True,
+    ),
+    "bandit": AnalyzerInfo(
+        name="bandit",
+        categories=frozenset({Category.SECURITY}),
+        profiles=frozenset({"default", "full"}),
+    ),
+    "radon": AnalyzerInfo(
+        name="radon",
+        categories=frozenset({Category.COMPLEXITY}),
+        profiles=frozenset({"default", "full"}),
+    ),
+    "vulture": AnalyzerInfo(
+        name="vulture",
+        categories=frozenset({Category.DEAD_CODE}),
+        profiles=frozenset({"default", "full"}),
+        project_wide=True,
+    ),
+    "deptry": AnalyzerInfo(
+        name="deptry",
+        categories=frozenset({Category.DEPENDENCIES}),
+        profiles=frozenset({"quick", "default", "full"}),
+        project_wide=True,
+    ),
+    "dependency-vulns": AnalyzerInfo(
+        name="dependency-vulns",
+        categories=frozenset({Category.DEPENDENCIES}),
+        default_enabled=False,
+        optional=True,
+        requires_network=True,
+        project_wide=True,
+        profiles=frozenset({"full"}),
+    ),
+    "detect-secrets": AnalyzerInfo(
+        name="detect-secrets",
+        categories=frozenset({Category.SECURITY}),
+        default_enabled=False,
+        optional=True,
+        profiles=frozenset({"full"}),
+    ),
+    "basedpyright": AnalyzerInfo(
+        name="basedpyright",
+        categories=frozenset({Category.TYPE_SAFETY}),
+        default_enabled=False,
+        optional=True,
+        project_wide=True,
+        profiles=frozenset({"full"}),
+    ),
+    "typos": AnalyzerInfo(
+        name="typos",
+        categories=frozenset({Category.QUALITY}),
+        default_enabled=False,
+        optional=True,
+        profiles=frozenset({"full"}),
+    ),
+}
+
+
+def get_analyzer_info(name: str) -> AnalyzerInfo | None:
+    """Return catalog metadata for an analyzer name."""
+    return ANALYZER_CATALOG.get(name)

python_checkup/analyzers/__init__.py

@@ -0,0 +1,54 @@
+from __future__ import annotations
+
+from typing import Protocol, runtime_checkable
+
+from python_checkup.analysis_request import AnalysisRequest
+from python_checkup.models import Category, Diagnostic
+
+
+@runtime_checkable
+class Analyzer(Protocol):
+    """Protocol that all analyzers must satisfy.
+
+    Analyzers can be built-in or loaded via entry points.
+    Each analyzer:
+    - Has a unique name and primary category
+    - Can check if its underlying tool is available
+    - Runs analysis and returns a list of Diagnostics
+    """
+
+    @property
+    def name(self) -> str:
+        """Unique identifier, e.g. 'ruff', 'mypy', 'bandit'."""
+        ...
+
+    @property
+    def category(self) -> Category:
+        """Primary category this analyzer contributes to."""
+        ...
+
+    async def is_available(self) -> bool:
+        """Check if the underlying tool is installed and runnable.
+
+        Returns True if the tool is available, False otherwise.
+        This should be fast (check PATH, try import, etc).
+        """
+        ...
+
+    async def analyze(
+        self,
+        request: AnalysisRequest,
+    ) -> list[Diagnostic]:
+        """Run analysis on the given files.
+
+        Args:
+            request: Structured request describing project context, enabled
+                categories, profile, files, and configuration.
+
+        Returns:
+            List of diagnostics found. Empty list means no issues.
+
+        Raises:
+            TimeoutError: If analysis exceeds configured timeout.
+        """
+        ...

python_checkup/analyzers/bandit.py

@@ -0,0 +1,158 @@
+from __future__ import annotations
+
+import asyncio
+import json
+import logging
+import shutil
+from pathlib import Path
+
+from python_checkup.analysis_request import AnalysisRequest
+from python_checkup.models import Category, Diagnostic, Severity
+
+logger = logging.getLogger("python_checkup")
+
+# Bandit severity -> python-checkup Severity
+BANDIT_SEVERITY_MAP: dict[str, Severity] = {
+    "HIGH": Severity.ERROR,
+    "MEDIUM": Severity.WARNING,
+    "LOW": Severity.INFO,
+}
+
+
+class BanditAnalyzer:
+    """Security scanning via Bandit."""
+
+    @property
+    def name(self) -> str:
+        return "bandit"
+
+    @property
+    def category(self) -> Category:
+        return Category.SECURITY
+
+    async def is_available(self) -> bool:
+        """Check if bandit is on PATH."""
+        return shutil.which("bandit") is not None
+
+    async def analyze(
+        self,
+        request: AnalysisRequest,
+    ) -> list[Diagnostic]:
+        files = request.files
+        config = request.config_dict()
+        if not files:
+            return []
+
+        cmd = ["bandit", "-f", "json", "--quiet"]
+
+        str_paths = [str(f) for f in files]
+        cmd.extend(str_paths)
+
+        timeout: int = 60
+        if "timeout" in config and isinstance(config["timeout"], int | float):
+            timeout = int(config["timeout"])
+
+        try:
+            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,
+            )
+        except asyncio.TimeoutError:
+            logger.warning("Bandit timed out")
+            return []
+        except FileNotFoundError:
+            logger.warning("Bandit binary not found")
+            return []
+
+        # Exit codes: 0 = clean, 1 = issues found, 2 = error
+        if proc.returncode == 2:
+            logger.error("Bandit error: %s", stderr.decode())
+            return []
+
+        output = stdout.decode()
+        if not output.strip():
+            return []
+
+        try:
+            data = json.loads(output)
+        except json.JSONDecodeError:
+            logger.error("Failed to parse Bandit JSON output")
+            return []
+
+        results = data.get("results", [])
+        if not isinstance(results, list):
+            return []
+
+        diagnostics = [_map_bandit_result(r) for r in results]
+
+        # Suppress noisy Bandit rules in test files (same approach as
+        # Ruff's per-file-ignores).  B101 (assert), B108 (temp dirs),
+        # B603/B607 (subprocess), B404 (subprocess import), B105/B106
+        # (hardcoded passwords) are standard practice in test suites.
+        _test_suppressed = {"B101", "B108", "B603", "B607", "B404", "B105", "B106"}
+        diagnostics = [
+            d
+            for d in diagnostics
+            if not (d.rule_id in _test_suppressed and _is_test_file(d.file_path))
+        ]
+
+        return diagnostics
+
+
+def _is_test_file(path: Path) -> bool:
+    """Return True if *path* looks like a test file or sits inside a tests/ dir."""
+    parts = path.parts
+    return (
+        any(p in ("tests", "test") for p in parts)
+        or path.name.startswith("test_")
+        or path.name.endswith("_test.py")
+    )
+
+
+def _safe_int(val: object, default: int = 0) -> int:
+    if val is None:
+        return default
+    if isinstance(val, int):
+        return val
+    try:
+        return int(str(val))
+    except (TypeError, ValueError):
+        return default
+
+
+def _map_bandit_result(raw: dict[str, object]) -> Diagnostic:
+    severity = BANDIT_SEVERITY_MAP.get(
+        str(raw.get("issue_severity", "LOW")),
+        Severity.INFO,
+    )
+
+    test_id = str(raw.get("test_id", "B000"))
+
+    # Build fix suggestion from CWE
+    cwe = raw.get("issue_cwe")
+    fix_text: str | None = None
+    if isinstance(cwe, dict) and cwe.get("id"):
+        fix_text = f"CWE-{cwe['id']}"
+
+    help_url = raw.get("more_info")
+
+    end_col = raw.get("end_col_offset")
+
+    return Diagnostic(
+        file_path=Path(str(raw.get("filename", "unknown"))),
+        line=_safe_int(raw.get("line_number")),
+        column=_safe_int(raw.get("col_offset")),
+        severity=severity,
+        rule_id=test_id,
+        tool="bandit",
+        category=Category.SECURITY,
+        message=str(raw.get("issue_text", "")),
+        fix=fix_text,
+        help_url=str(help_url) if help_url else None,
+        end_column=_safe_int(end_col) if end_col else None,
+    )

python_checkup/analyzers/basedpyright.py

@@ -0,0 +1,103 @@
+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 BasedPyrightAnalyzer:
+    """Type checking via basedpyright."""
+
+    @property
+    def name(self) -> str:
+        return "basedpyright"
+
+    @property
+    def category(self) -> Category:
+        return Category.TYPE_SAFETY
+
+    async def is_available(self) -> bool:
+        return shutil.which("basedpyright") is not None
+
+    async def analyze(self, request: AnalysisRequest) -> list[Diagnostic]:
+        if not request.files:
+            return []
+
+        cmd = [
+            "basedpyright",
+            "--outputjson",
+            "--project",
+            str(request.project_root),
+            *[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)
+
+        if proc.returncode not in (0, 1):
+            return []
+
+        output = stdout.decode().strip()
+        if not output:
+            return []
+
+        try:
+            data = json.loads(output)
+        except json.JSONDecodeError:
+            return []
+
+        diagnostics: list[Diagnostic] = []
+        raw_diags = data.get("generalDiagnostics", [])
+        if not isinstance(raw_diags, list):
+            return []
+
+        for raw in raw_diags:
+            if not isinstance(raw, dict):
+                continue
+
+            severity_raw = str(raw.get("severity", "warning"))
+            severity = Severity.ERROR if severity_raw == "error" else Severity.WARNING
+            file_path = Path(str(raw.get("file", "unknown")))
+            rule = str(raw.get("rule", "basedpyright"))
+            message = str(raw.get("message", ""))
+
+            line = 0
+            column = 0
+            end_line: int | None = None
+            end_column: int | None = None
+            range_data = raw.get("range")
+            if isinstance(range_data, dict):
+                start = range_data.get("start")
+                end = range_data.get("end")
+                if isinstance(start, dict):
+                    line = int(start.get("line", 0)) + 1
+                    column = int(start.get("character", 0)) + 1
+                if isinstance(end, dict):
+                    end_line = int(end.get("line", 0)) + 1
+                    end_column = int(end.get("character", 0)) + 1
+
+            diagnostics.append(
+                Diagnostic(
+                    file_path=file_path,
+                    line=line,
+                    column=column,
+                    severity=severity,
+                    rule_id=f"basedpyright-{rule}",
+                    tool="basedpyright",
+                    category=Category.TYPE_SAFETY,
+                    message=message,
+                    end_line=end_line,
+                    end_column=end_column,
+                )
+            )
+
+        return diagnostics

python_checkup/analyzers/cached.py

@@ -0,0 +1,106 @@
+from __future__ import annotations
+
+import logging
+from pathlib import Path
+from typing import Any
+
+from python_checkup.analysis_request import AnalysisRequest
+from python_checkup.cache import AnalysisCache
+from python_checkup.models import Category, Diagnostic
+
+logger = logging.getLogger("python_checkup")
+
+
+class CachedAnalyzer:
+    """Wraps any Analyzer with per-file caching.
+
+    This is transparent to consumers -- it has the same interface
+    as the underlying analyzer. The cache lookup happens per-file,
+    so editing one file in a 1000-file project only re-analyzes
+    that single file.
+    """
+
+    def __init__(self, analyzer: Any, cache: AnalysisCache) -> None:
+        self._analyzer = analyzer
+        self._cache = cache
+
+    @property
+    def name(self) -> str:
+        return self._analyzer.name  # type: ignore[no-any-return]
+
+    @property
+    def category(self) -> Category:
+        return self._analyzer.category  # type: ignore[no-any-return]
+
+    async def is_available(self) -> bool:
+        return await self._analyzer.is_available()  # type: ignore[no-any-return]
+
+    async def analyze(
+        self,
+        request: AnalysisRequest,
+    ) -> list[Diagnostic]:
+        """Analyze files, using cache for unchanged files.
+
+        1. For each file, check if we have cached results
+        2. Collect all cache misses into a batch
+        3. Run the underlying analyzer only on missed files
+        4. Cache the new results per-file
+        5. Return all results (cached + fresh)
+        """
+        files = request.files
+        cached_results: list[Diagnostic] = []
+        uncached_files = []
+
+        for f in files:
+            cached = self._cache.get(self._analyzer.name, f)
+            if cached is not None:
+                cached_results.extend(cached)
+            else:
+                uncached_files.append(f)
+
+        if not uncached_files:
+            logger.debug(
+                "%s: all %d files cached",
+                self._analyzer.name,
+                len(files),
+            )
+            return cached_results
+
+        logger.debug(
+            "%s: %d/%d files need analysis",
+            self._analyzer.name,
+            len(uncached_files),
+            len(files),
+        )
+
+        # Run analyzer only on uncached files
+        uncached_request = AnalysisRequest(
+            project_root=request.project_root,
+            files=uncached_files,
+            config=request.config,
+            categories=set(request.categories),
+            profile=request.profile,
+            framework=request.framework,
+            diff_base=request.diff_base,
+            quiet=request.quiet,
+            no_cache=request.no_cache,
+            metadata=dict(request.metadata),
+        )
+        new_results: list[Diagnostic] = await self._analyzer.analyze(uncached_request)
+
+        # Group results by file for per-file caching
+        results_by_file: dict[Path, list[Diagnostic]] = {f: [] for f in uncached_files}
+        for d in new_results:
+            if d.file_path in results_by_file:
+                results_by_file[d.file_path].append(d)
+
+        # Cache each file's results (including empty lists for clean files)
+        for file_path, file_diagnostics in results_by_file.items():
+            self._cache.set(
+                self._analyzer.name,
+                file_path,
+                file_diagnostics,
+            )
+
+        cached_results.extend(new_results)
+        return cached_results