python-checkup 0.0.1__py3-none-any.whl

python_checkup/analyzers/mypy.py

@@ -0,0 +1,217 @@
+from __future__ import annotations
+
+import asyncio
+import json
+import logging
+import re
+from pathlib import Path
+
+from python_checkup.analysis_request import AnalysisRequest
+from python_checkup.models import Category, Diagnostic, Severity
+
+logger = logging.getLogger("python_checkup")
+
+# Fallback regex for mypy < 1.7 (no JSON output support)
+MYPY_LINE_RE = re.compile(
+    r"^(.+?):(\d+):(?:(\d+):)?\s*(error|warning|note):\s*(.+?)(?:\s+\[(.+)\])?$"
+)
+
+
+class MypyAnalyzer:
+    """Type checking via mypy."""
+
+    @property
+    def name(self) -> str:
+        return "mypy"
+
+    @property
+    def category(self) -> Category:
+        return Category.TYPE_SAFETY
+
+    async def is_available(self) -> bool:
+        """Check if mypy is importable."""
+        try:
+            import mypy.api  # noqa: F401
+
+            return True
+        except ImportError:
+            return False
+
+    async def analyze(
+        self,
+        request: AnalysisRequest,
+    ) -> list[Diagnostic]:
+        """Run mypy on the given files.
+
+        Strategy:
+        1. Try --output json first (mypy 1.7+)
+        2. If that flag is unrecognized, fall back to text parsing
+        3. Run in a thread pool since mypy.api.run() is blocking
+        """
+        files = request.files
+        config = request.config_dict()
+
+        if not files:
+            return []
+
+        timeout: int = 60
+        if "timeout" in config and isinstance(config["timeout"], int | float):
+            timeout = int(config["timeout"])
+
+        # Build args for mypy.api.run()
+        args = self._build_args(files, use_json=True)
+
+        loop = asyncio.get_running_loop()
+
+        try:
+            stdout, stderr, exit_code = await asyncio.wait_for(
+                loop.run_in_executor(None, self._run_mypy, args),
+                timeout=timeout,
+            )
+        except asyncio.TimeoutError:
+            logger.warning("mypy timed out after %ds", timeout)
+            return []
+
+        # Exit code 2 = fatal error (bad args, can't find files, etc.)
+        if exit_code == 2:
+            # Check if it's because --output json isn't supported
+            if "unrecognized" in stderr.lower() or "error: argument" in stderr.lower():
+                logger.debug(
+                    "mypy doesn't support --output json, falling back to text parsing"
+                )
+                args = self._build_args(files, use_json=False)
+                try:
+                    stdout, stderr, exit_code = await asyncio.wait_for(
+                        loop.run_in_executor(None, self._run_mypy, args),
+                        timeout=timeout,
+                    )
+                except asyncio.TimeoutError:
+                    logger.warning("mypy timed out after %ds (fallback)", timeout)
+                    return []
+
+                if exit_code == 2:
+                    logger.error("mypy fatal error: %s", stderr)
+                    return []
+                return self._parse_text_output(stdout)
+            else:
+                logger.error("mypy fatal error: %s", stderr)
+                return []
+
+        # Exit code 0 = clean, 1 = type errors found
+        if not stdout.strip():
+            return []
+
+        return self._parse_json_output(stdout)
+
+    def _build_args(
+        self,
+        files: list[Path],
+        use_json: bool,
+    ) -> list[str]:
+        args: list[str] = []
+
+        if use_json:
+            args.extend(["--output", "json"])
+
+        args.extend(
+            [
+                "--no-color-output",
+                "--no-error-summary",
+                "--show-absolute-path",
+                "--incremental",  # Use .mypy_cache/ for speed
+            ]
+        )
+
+        # Pass file paths
+        args.extend(str(f) for f in files)
+
+        return args
+
+    @staticmethod
+    def _run_mypy(args: list[str]) -> tuple[str, str, int]:
+        """Call mypy.api.run() -- must run in thread pool (blocking)."""
+        from mypy.api import run
+
+        return run(args)
+
+    def _parse_json_output(self, stdout: str) -> list[Diagnostic]:
+        """Parse mypy JSON Lines output (one JSON object per line)."""
+        diagnostics: list[Diagnostic] = []
+
+        for line in stdout.strip().splitlines():
+            line = line.strip()
+            if not line:
+                continue
+
+            try:
+                item = json.loads(line)
+            except json.JSONDecodeError:
+                logger.debug("Skipping non-JSON mypy output line: %s", line[:80])
+                continue
+
+            severity = _map_mypy_severity(item.get("severity", "error"))
+            code = item.get("code", "misc")
+
+            diagnostics.append(
+                Diagnostic(
+                    file_path=Path(item["file"]),
+                    line=item.get("line", 0),
+                    column=item.get("column", 0),
+                    severity=severity,
+                    rule_id=f"mypy-{code}",
+                    tool="mypy",
+                    category=Category.TYPE_SAFETY,
+                    message=item.get("message", ""),
+                    fix=item.get("hint"),
+                    end_line=item.get("end_line"),
+                    end_column=item.get("end_column"),
+                )
+            )
+
+        return diagnostics
+
+    def _parse_text_output(self, stdout: str) -> list[Diagnostic]:
+        """Fallback: parse mypy's traditional text output.
+
+        Format: file.py:10:5: error: message [error-code]
+        """
+        diagnostics: list[Diagnostic] = []
+
+        for line in stdout.strip().splitlines():
+            match = MYPY_LINE_RE.match(line)
+            if not match:
+                continue
+
+            filepath, lineno, colno, level, message, code = match.groups()
+
+            # Skip notes -- they're supplementary info, not actionable findings
+            if level == "note":
+                continue
+
+            severity = _map_mypy_severity(level)
+            code = code or "misc"
+
+            diagnostics.append(
+                Diagnostic(
+                    file_path=Path(filepath),
+                    line=int(lineno),
+                    column=int(colno) if colno else 0,
+                    severity=severity,
+                    rule_id=f"mypy-{code}",
+                    tool="mypy",
+                    category=Category.TYPE_SAFETY,
+                    message=message.strip(),
+                )
+            )
+
+        return diagnostics
+
+
+def _map_mypy_severity(level: str) -> Severity:
+    match level:
+        case "error":
+            return Severity.ERROR
+        case "warning":
+            return Severity.WARNING
+        case _:
+            return Severity.INFO

python_checkup/analyzers/radon.py

@@ -0,0 +1,150 @@
+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")
+
+# Only report functions at or above this grade as diagnostics.
+# Grade C (CC 11-20) is common in real-world code and not actionable
+# enough to penalise.  We start warning at D (CC 21-30).
+DIAGNOSTIC_THRESHOLD = "D"  # CC >= 21
+
+# Map CC grades to severity
+CC_GRADE_SEVERITY: dict[str, Severity] = {
+    "D": Severity.WARNING,  # 21-30: complex
+    "E": Severity.ERROR,  # 31-40: very complex
+    "F": Severity.ERROR,  # 41+: unmaintainable
+}
+
+
+class RadonAnalyzer:
+    """Complexity analysis via Radon."""
+
+    @property
+    def name(self) -> str:
+        return "radon"
+
+    @property
+    def category(self) -> Category:
+        return Category.COMPLEXITY
+
+    async def is_available(self) -> bool:
+        """Check if radon is importable."""
+        try:
+            import radon.complexity  # noqa: F401
+            import radon.metrics  # noqa: F401
+
+            return True
+        except ImportError:
+            return False
+
+    async def analyze(
+        self,
+        request: AnalysisRequest,
+    ) -> list[Diagnostic]:
+        files = request.files
+        if not files:
+            return []
+
+        # Run in thread pool -- Radon is CPU-bound Python code
+        loop = asyncio.get_running_loop()
+        return await loop.run_in_executor(
+            None,
+            self._analyze_sync,
+            files,
+            request.metadata,
+        )
+
+    def _analyze_sync(
+        self,
+        files: list[Path],
+        metadata: dict[str, object],
+    ) -> list[Diagnostic]:
+        """Synchronous analysis -- runs in thread pool."""
+        from radon.complexity import cc_rank, cc_visit
+        from radon.metrics import mi_visit
+
+        diagnostics: list[Diagnostic] = []
+        mi_scores: list[float] = []
+
+        for file_path in files:
+            try:
+                source = file_path.read_text(errors="ignore")
+            except OSError as e:
+                logger.debug("Cannot read %s: %s", file_path, e)
+                continue
+
+            if not source.strip():
+                continue
+
+            # 1. Cyclomatic complexity per function/method
+            try:
+                cc_results = cc_visit(source)
+                for block in cc_results:
+                    grade = cc_rank(block.complexity)
+                    if grade >= DIAGNOSTIC_THRESHOLD:
+                        severity = CC_GRADE_SEVERITY.get(grade, Severity.WARNING)
+                        block_type = _block_type_label(block)
+                        diagnostics.append(
+                            Diagnostic(
+                                file_path=file_path,
+                                line=block.lineno,
+                                column=0,
+                                severity=severity,
+                                rule_id=f"CC-{grade}",
+                                tool="radon",
+                                category=Category.COMPLEXITY,
+                                message=(
+                                    f"{block_type} '{block.name}' has cyclomatic "
+                                    f"complexity of {block.complexity} (grade {grade})"
+                                ),
+                                fix=_cc_fix_suggestion(block.complexity, grade),
+                                end_line=(
+                                    block.endline if hasattr(block, "endline") else None
+                                ),
+                            )
+                        )
+            except Exception as e:
+                logger.debug("Radon CC failed on %s: %s", file_path, e)
+
+            # 2. Maintainability Index per file
+            try:
+                mi: float = mi_visit(source, multi=True)
+                mi_scores.append(mi)
+            except Exception as e:
+                logger.debug("Radon MI failed on %s: %s", file_path, e)
+
+        # Store MI scores in config for the scoring engine
+        metadata["_radon_mi_scores"] = mi_scores
+
+        return diagnostics
+
+
+def _block_type_label(block: Any) -> str:
+    if hasattr(block, "is_method") and block.is_method:
+        return f"Method ({block.classname})"
+    elif hasattr(block, "is_method"):
+        return "Function"
+    else:
+        return "Class"
+
+
+def _cc_fix_suggestion(complexity: int, grade: str) -> str:
+    if grade == "F":
+        return (
+            f"Complexity {complexity} is dangerously high. "
+            "Extract helper functions, replace conditional chains with "
+            "a dispatch dict or Strategy pattern, and eliminate nested loops."
+        )
+    # D and E
+    return (
+        f"Complexity {complexity} makes this hard to test and maintain. "
+        "Consider extracting helper functions or using early returns "
+        "to reduce nesting."
+    )

python_checkup/analyzers/registry.py

@@ -0,0 +1,69 @@
+from __future__ import annotations
+
+import logging
+from importlib.metadata import entry_points
+
+from python_checkup.analyzers import Analyzer
+
+logger = logging.getLogger("python_checkup")
+
+
+async def discover_analyzers() -> list[Analyzer]:
+    """Discover all analyzers whose underlying tools are available.
+
+    Loads built-in and third-party analyzers via entry points, verifies
+    protocol conformance, checks availability, and returns only those
+    that are ready to run.
+    """
+    eps = entry_points(group="python-checkup.analyzers")
+    available: list[Analyzer] = []
+    unavailable: list[str] = []
+
+    for ep in eps:
+        try:
+            analyzer_cls = ep.load()
+            analyzer = analyzer_cls()
+
+            # Verify the plugin satisfies the Analyzer protocol
+            if not isinstance(analyzer, Analyzer):
+                logger.warning(
+                    "Plugin '%s' does not implement the Analyzer protocol, skipping",
+                    ep.name,
+                )
+                unavailable.append(ep.name)
+                continue
+
+            if await analyzer.is_available():
+                available.append(analyzer)
+                logger.debug("Analyzer available: %s", ep.name)
+            else:
+                unavailable.append(ep.name)
+                logger.debug("Analyzer not available: %s", ep.name)
+        except Exception:
+            logger.debug("Failed to load analyzer plugin '%s'", ep.name, exc_info=True)
+            unavailable.append(ep.name)
+
+    return available
+
+
+async def get_analyzer(name: str) -> Analyzer | None:
+    """Load a specific analyzer by name."""
+    eps = entry_points(group="python-checkup.analyzers")
+    for ep in eps:
+        if ep.name == name:
+            try:
+                analyzer_cls = ep.load()
+                analyzer = analyzer_cls()
+
+                if not isinstance(analyzer, Analyzer):
+                    logger.warning(
+                        "Plugin '%s' does not implement the Analyzer protocol",
+                        name,
+                    )
+                    return None
+
+                if await analyzer.is_available():
+                    return analyzer
+            except Exception:
+                logger.debug("Failed to load analyzer '%s'", name, exc_info=True)
+    return None

python_checkup/analyzers/ruff.py

@@ -0,0 +1,256 @@
+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")
+
+
+# Map Ruff rule prefixes to python-checkup categories
+RULE_PREFIX_TO_CATEGORY: dict[str, Category] = {
+    # Security (flake8-bandit)
+    "S": Category.SECURITY,
+    # Complexity (mccabe)
+    "C9": Category.COMPLEXITY,
+    # Dead code (eradicate)
+    "ERA": Category.DEAD_CODE,
+    # Framework-specific rules map to quality
+    "DJ": Category.QUALITY,
+    "FAST": Category.QUALITY,
+    "ASYNC": Category.QUALITY,
+}
+
+# Ruff rules that are errors (not warnings)
+# E9xx are syntax errors, F-prefixed are important
+ERROR_PREFIXES = {"E9", "F"}
+
+
+def _get_framework_rules(framework: object | None) -> list[str]:
+    """Get framework-specific rule extensions."""
+    framework_rules: dict[str, list[str]] = {
+        "django": ["DJ", "S610", "S611"],
+        "fastapi": ["FAST", "ASYNC"],
+        "flask": ["S201"],
+    }
+    return framework_rules.get(str(framework), []) if framework else []
+
+
+class RuffAnalyzer:
+    """Linting via Ruff."""
+
+    @property
+    def name(self) -> str:
+        return "ruff"
+
+    @property
+    def category(self) -> Category:
+        return Category.QUALITY
+
+    async def is_available(self) -> bool:
+        """Check if ruff is on PATH."""
+        return shutil.which("ruff") is not None
+
+    async def analyze(
+        self,
+        request: AnalysisRequest,
+    ) -> list[Diagnostic]:
+        """Run ruff check with JSON output and parse results.
+
+        We respect the project's existing ruff.toml / [tool.ruff] config.
+        We do NOT override rule selection -- the user's config is authoritative.
+        We only add --output-format json for machine-readable output.
+
+        When a framework is detected (config["framework"]), we extend the
+        rule selection with framework-specific rules (DJ for Django, FAST/ASYNC
+        for FastAPI, S201 for Flask).
+
+        Diagnostics whose categories are not in ``request.categories`` are
+        filtered out so that ``--skip security`` (for example) suppresses
+        Ruff's S-prefixed rules alongside Bandit and detect-secrets.
+        """
+        files = request.files
+
+        if not files:
+            return []
+
+        cmd = self._build_ruff_command(request)
+        diagnostics = await self._run_ruff_and_parse(cmd, request.config_dict())
+
+        if diagnostics and request.categories:
+            diagnostics = [d for d in diagnostics if d.category in request.categories]
+
+        return diagnostics
+
+    def _build_ruff_command(self, request: AnalysisRequest) -> list[str]:
+        """Build the ruff command with framework-specific rules."""
+        config = request.config_dict()
+        cmd = [
+            "ruff",
+            "check",
+            "--output-format",
+            "json",
+            "--no-cache",
+        ]
+
+        framework = config.get("framework")
+        extend_rules = _get_framework_rules(framework)
+
+        if extend_rules:
+            cmd.extend(["--extend-select", ",".join(extend_rules)])
+
+        str_paths = [str(f) for f in request.files]
+        cmd.extend(str_paths)
+
+        return cmd
+
+    async def _run_ruff_and_parse(
+        self,
+        cmd: list[str],
+        config: dict[str, object],
+    ) -> list[Diagnostic]:
+        """Execute ruff and parse JSON output into diagnostics."""
+        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("Ruff timed out")
+            return []
+        except FileNotFoundError:
+            logger.warning("Ruff binary not found")
+            return []
+
+        if proc.returncode == 2:
+            logger.error("Ruff error: %s", stderr.decode())
+            return []
+
+        output = stdout.decode()
+        if not output.strip():
+            return []
+
+        try:
+            raw_diagnostics = json.loads(output)
+        except json.JSONDecodeError:
+            logger.error("Failed to parse Ruff JSON output")
+            return []
+
+        return [_map_diagnostic(d) for d in raw_diagnostics]
+
+
+def _map_diagnostic(raw: dict[str, object]) -> Diagnostic:
+    """Map a single Ruff JSON diagnostic to our Diagnostic model.
+
+    Ruff JSON output per item:
+    {
+        "code": "F401",
+        "message": "`os` imported but unused",
+        "filename": "/path/to/file.py",
+        "location": {"row": 1, "column": 8},
+        "end_location": {"row": 1, "column": 10},
+        "fix": {
+            "message": "Remove unused import: `os`",
+            "applicability": "safe",
+            "edits": [...]
+        },
+        "url": "https://docs.astral.sh/ruff/rules/unused-import",
+        "noqa_row": 1,
+        "cell": null
+    }
+    """
+    code = str(raw.get("code", "UNKNOWN"))
+    category = _categorize_rule(code)
+    severity = _severity_for_rule(code)
+
+    fix_info = raw.get("fix")
+    fix_message: str | None = None
+    if isinstance(fix_info, dict):
+        fix_message = str(fix_info["message"]) if fix_info.get("message") else None
+
+    location = raw.get("location")
+    end_location = raw.get("end_location")
+
+    row = 0
+    col = 0
+    if isinstance(location, dict):
+        row = int(location.get("row") or 0)
+        col = int(location.get("column") or 0)
+
+    end_row: int | None = None
+    end_col: int | None = None
+    if isinstance(end_location, dict):
+        end_row = int(end_location.get("row") or 0)
+        end_col = int(end_location.get("column") or 0)
+
+    return Diagnostic(
+        file_path=Path(str(raw.get("filename", "unknown"))),
+        line=row,
+        column=col,
+        severity=severity,
+        rule_id=code,
+        tool="ruff",
+        category=category,
+        message=str(raw.get("message", "")),
+        fix=fix_message,
+        help_url=str(raw["url"]) if raw.get("url") else None,
+        end_line=end_row,
+        end_column=end_col,
+    )
+
+
+def _categorize_rule(code: str) -> Category:
+    """Map a Ruff rule code to a python-checkup category.
+
+    Rule prefix conventions:
+    - S*    -> Security (flake8-bandit)
+    - C9*   -> Complexity (mccabe)
+    - ERA*  -> Dead code (eradicate)
+    - Everything else -> Quality
+    """
+    for prefix, category in RULE_PREFIX_TO_CATEGORY.items():
+        if code.startswith(prefix):
+            return category
+    return Category.QUALITY
+
+
+def _severity_for_rule(code: str) -> Severity:
+    """Determine severity based on rule code.
+
+    - E9xx (syntax errors) and F-prefixed (Pyflakes) -> ERROR
+    - S-prefixed (security) -> ERROR
+    - Style rules (W, D, I) -> INFO
+    - Everything else -> WARNING
+    """
+    # Syntax errors are always errors
+    if code.startswith("E9"):
+        return Severity.ERROR
+
+    # Pyflakes rules are errors (unused imports, undefined names, etc.)
+    if code.startswith("F"):
+        return Severity.ERROR
+
+    # Security rules are errors
+    if code.startswith("S"):
+        return Severity.ERROR
+
+    # Style/formatting are info
+    if code.startswith(("W", "D", "I")):
+        return Severity.INFO
+
+    # Default to warning
+    return Severity.WARNING