python-checkup 0.0.1__py3-none-any.whl

python_checkup/mcp/server.py

@@ -0,0 +1,411 @@
+from __future__ import annotations
+
+import json
+import logging
+import sys
+from pathlib import Path
+
+from mcp.server.fastmcp import FastMCP
+
+from python_checkup.models import Category, Diagnostic, HealthReport, Severity
+
+# Configure logging to stderr (CRITICAL for stdio servers --
+# any stdout output corrupts the JSON-RPC protocol)
+logging.basicConfig(
+    level=logging.INFO,
+    format="%(name)s %(levelname)s: %(message)s",
+    stream=sys.stderr,
+)
+logger = logging.getLogger("python-checkup-mcp")
+
+mcp_server = FastMCP("python-checkup")
+
+
+# Tool 1: Full health check
+
+
+@mcp_server.tool()
+async def python_checkup_diagnose(
+    path: str,
+    quick: bool = False,
+) -> str:
+    """Run a complete health check on a Python project or specific files.
+
+    Returns a 0-100 health score with categorized diagnostics covering
+    code quality, type safety, security, complexity, and dead code.
+
+    Call this after making significant code changes, before committing,
+    or when you want an overview of a project's health. Use quick=True
+    to skip slow analyzers (mypy) for sub-3-second results.
+
+    Args:
+        path: Absolute path to the project directory or a specific file.
+        quick: If True, skip slow analyzers (mypy) for faster results.
+    """
+    try:
+        from python_checkup.config import load_config
+        from python_checkup.discovery import discover_python_files
+        from python_checkup.runner import run_analysis
+
+        project_path = Path(path).resolve()
+        if not project_path.exists():
+            return f"Error: Path does not exist: {path}"
+
+        # If path is a file, use its parent as project root
+        if project_path.is_file():
+            project_root = project_path.parent
+            files = [project_path]
+            config = load_config(project_root)
+        else:
+            project_root = project_path
+            config = load_config(project_root)
+            files = discover_python_files(project_root, config.ignore_files)
+
+        skip: set[str] = set()
+        if quick:
+            skip.add("mypy")
+
+        report = await run_analysis(
+            project_root=project_root,
+            config=config,
+            files=files,
+            skip_analyzers=skip,
+            quiet=True,  # No Rich progress in MCP mode
+        )
+
+        return _format_report(report)
+
+    except Exception as e:
+        logger.exception("Error in python_checkup_diagnose")
+        return f"Error running analysis: {e}"
+
+
+# Tool 2: Lint specific files
+
+
+@mcp_server.tool()
+async def python_checkup_lint(
+    paths: list[str],
+) -> str:
+    """Run Ruff linting on specific Python files.
+
+    Returns lint issues with rule IDs, severity, messages, and auto-fix
+    suggestions. Use this for quick feedback after editing Python files.
+    Faster than a full diagnose since it only runs the linter.
+
+    Args:
+        paths: List of absolute file paths to lint.
+    """
+    try:
+        from python_checkup.analyzers.ruff import RuffAnalyzer
+        from python_checkup.config import load_config
+
+        analyzer = RuffAnalyzer()
+        if not await analyzer.is_available():
+            return "Error: Ruff is not installed. Run: pip install ruff"
+
+        file_paths = [Path(p).resolve() for p in paths]
+        for p in file_paths:
+            if not p.exists():
+                return f"Error: File not found: {p}"
+
+        from python_checkup.analysis_request import AnalysisRequest
+        from python_checkup.plan import PROFILE_DEFAULT
+
+        diagnostics = await analyzer.analyze(
+            AnalysisRequest(
+                project_root=file_paths[0].parent,
+                files=file_paths,
+                config=load_config(file_paths[0].parent),
+                categories={
+                    Category.QUALITY,
+                    Category.SECURITY,
+                    Category.COMPLEXITY,
+                    Category.DEAD_CODE,
+                },
+                profile=PROFILE_DEFAULT,
+            )
+        )
+
+        if not diagnostics:
+            return "No lint issues found. Code looks clean!"
+
+        return _format_diagnostics(diagnostics, max_items=30)
+
+    except Exception as e:
+        logger.exception("Error in python_checkup_lint")
+        return f"Error running lint: {e}"
+
+
+# Tool 3: Type check specific files
+
+
+@mcp_server.tool()
+async def python_checkup_typecheck(
+    paths: list[str],
+) -> str:
+    """Run type checking (mypy) on specific Python files.
+
+    Returns type errors with locations, error codes, and explanations.
+    Use this when writing or modifying typed Python code to catch type
+    mismatches, missing annotations, and incompatible assignments.
+
+    Args:
+        paths: List of absolute file paths to type-check.
+    """
+    try:
+        from python_checkup.analyzers.registry import get_analyzer
+
+        analyzer = await get_analyzer("mypy")
+        if analyzer is None:
+            return "Error: mypy is not installed. Run: pip install python-checkup"
+
+        file_paths = [Path(p).resolve() for p in paths]
+        for p in file_paths:
+            if not p.exists():
+                return f"Error: File not found: {p}"
+
+        from python_checkup.analysis_request import AnalysisRequest
+        from python_checkup.config import load_config
+        from python_checkup.plan import PROFILE_DEFAULT
+
+        diagnostics = await analyzer.analyze(
+            AnalysisRequest(
+                project_root=file_paths[0].parent,
+                files=file_paths,
+                config=load_config(file_paths[0].parent),
+                categories={Category.TYPE_SAFETY},
+                profile=PROFILE_DEFAULT,
+            )
+        )
+
+        if not diagnostics:
+            return "No type errors found. Types look correct!"
+
+        return _format_diagnostics(diagnostics, max_items=30)
+
+    except Exception as e:
+        logger.exception("Error in python_checkup_typecheck")
+        return f"Error running type check: {e}"
+
+
+# Tool 4: Security scan specific files
+
+
+@mcp_server.tool()
+async def python_checkup_security(
+    paths: list[str],
+) -> str:
+    """Run security analysis on specific Python files.
+
+    Checks for vulnerabilities including SQL injection, hardcoded secrets,
+    insecure deserialization, shell injection, and weak cryptography.
+    Returns findings with CWE mappings and severity levels.
+
+    Call this before committing code that handles user input, credentials,
+    file operations, subprocess calls, or external data.
+
+    Args:
+        paths: List of absolute file paths to scan for security issues.
+    """
+    try:
+        from python_checkup.analyzers.registry import get_analyzer
+        from python_checkup.analyzers.ruff import RuffAnalyzer
+
+        results: list[Diagnostic] = []
+
+        file_paths = [Path(p).resolve() for p in paths]
+        for p in file_paths:
+            if not p.exists():
+                return f"Error: File not found: {p}"
+
+        # Try Bandit
+        bandit = await get_analyzer("bandit")
+        if bandit:
+            from python_checkup.analysis_request import AnalysisRequest
+            from python_checkup.config import load_config
+            from python_checkup.plan import PROFILE_DEFAULT
+
+            diagnostics = await bandit.analyze(
+                AnalysisRequest(
+                    project_root=file_paths[0].parent,
+                    files=file_paths,
+                    config=load_config(file_paths[0].parent),
+                    categories={Category.SECURITY},
+                    profile=PROFILE_DEFAULT,
+                )
+            )
+            results.extend(diagnostics)
+
+        # Also run Ruff S-rules (always available)
+        ruff = RuffAnalyzer()
+        if await ruff.is_available():
+            from python_checkup.analysis_request import AnalysisRequest
+            from python_checkup.config import load_config
+            from python_checkup.plan import PROFILE_DEFAULT
+
+            all_diags = await ruff.analyze(
+                AnalysisRequest(
+                    project_root=file_paths[0].parent,
+                    files=file_paths,
+                    config=load_config(file_paths[0].parent),
+                    categories={Category.SECURITY},
+                    profile=PROFILE_DEFAULT,
+                )
+            )
+            security_diags = [d for d in all_diags if d.category == Category.SECURITY]
+            results.extend(security_diags)
+
+        # Deduplicate by (file, line, rule_id)
+        seen: set[tuple[str, int, str]] = set()
+        unique: list[Diagnostic] = []
+        for d in results:
+            key = (str(d.file_path), d.line, d.rule_id)
+            if key not in seen:
+                seen.add(key)
+                unique.append(d)
+
+        if not unique:
+            return "No security issues found. Code looks secure!"
+
+        return _format_diagnostics(unique, max_items=30)
+
+    except Exception as e:
+        logger.exception("Error in python_checkup_security")
+        return f"Error running security scan: {e}"
+
+
+# Tool 5: Explain a rule
+
+
+@mcp_server.tool()
+async def python_checkup_explain_rule(
+    rule_id: str,
+) -> str:
+    """Explain a specific lint/analysis rule by its ID.
+
+    Returns the rule's purpose, an example of code that violates it,
+    an example of correct code, and the recommended fix pattern.
+    Supports Ruff rules (F401, E501, S101, C901, etc.), Bandit rules
+    (B101, B608, etc.), and mypy error codes (return-value, arg-type, etc.).
+
+    Use this to understand a flagged issue before fixing it.
+
+    Args:
+        rule_id: The rule ID to explain (e.g., 'S101', 'F401', 'C901', 'B608').
+    """
+    try:
+        from python_checkup.skills.rule_db import explain_rule
+
+        explanation = explain_rule(rule_id)
+        return explanation
+
+    except Exception as e:
+        logger.exception("Error in python_checkup_explain_rule")
+        return f"Error explaining rule: {e}"
+
+
+# Output formatting helpers
+
+
+def _format_report(report: HealthReport) -> str:
+    """Format a HealthReport for MCP output, keeping under token limit."""
+    data: dict[str, object] = {
+        "score": report.score,
+        "label": report.label,
+        "categoryScores": [
+            {
+                "category": cs.category.value,
+                "score": cs.score,
+                "weight": cs.weight,
+                "issueCount": cs.issue_count,
+                "details": cs.details,
+            }
+            for cs in report.category_scores
+        ],
+        "project": {
+            "pythonVersion": report.project.python_version,
+            "framework": report.project.framework,
+            "totalFiles": report.project.total_files,
+            "totalLines": report.project.total_lines,
+        },
+        "analyzersUsed": report.analyzers_used,
+        "analyzersSkipped": report.analyzers_skipped,
+        "durationMs": report.duration_ms,
+        "totalIssues": len(report.diagnostics),
+    }
+
+    # Add top issues (limit to 50 to stay under token limit)
+    max_issues = 50
+    top = sorted(
+        report.diagnostics,
+        key=lambda d: (
+            0 if d.severity == Severity.ERROR else 1,
+            str(d.file_path),
+        ),
+    )[:max_issues]
+
+    data["topIssues"] = [
+        {
+            "file": str(d.file_path),
+            "line": d.line,
+            "ruleId": d.rule_id,
+            "severity": d.severity.value,
+            "message": d.message,
+            "fix": d.fix,
+        }
+        for d in top
+    ]
+
+    if len(report.diagnostics) > max_issues:
+        data["truncated"] = True
+        data["note"] = f"Showing top {max_issues} of {len(report.diagnostics)} issues."
+
+    return json.dumps(data, indent=2)
+
+
+def _format_diagnostics(
+    diagnostics: list[Diagnostic],
+    max_items: int = 30,
+) -> str:
+    sorted_diags = sorted(
+        diagnostics,
+        key=lambda d: (
+            0 if d.severity == Severity.ERROR else 1,
+            str(d.file_path),
+        ),
+    )[:max_items]
+
+    items = [
+        {
+            "file": str(d.file_path),
+            "line": d.line,
+            "column": d.column,
+            "ruleId": d.rule_id,
+            "severity": d.severity.value,
+            "message": d.message,
+            "fix": d.fix,
+            "helpUrl": d.help_url,
+        }
+        for d in sorted_diags
+    ]
+
+    result: dict[str, object] = {
+        "totalIssues": len(diagnostics),
+        "showing": len(items),
+        "issues": items,
+    }
+
+    if len(diagnostics) > max_items:
+        result["truncated"] = True
+
+    return json.dumps(result, indent=2)
+
+
+# Entry point
+
+
+def start_mcp_server() -> None:
+    """Start the MCP server on stdio transport."""
+    logger.info("Starting python-checkup MCP server")
+    mcp_server.run(transport="stdio")

python_checkup/models.py

@@ -0,0 +1,114 @@
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from enum import Enum
+from pathlib import Path
+
+
+class Severity(Enum):
+    """Diagnostic severity levels."""
+
+    ERROR = "error"
+    WARNING = "warning"
+    INFO = "info"
+
+
+class Category(Enum):
+    """Analysis categories that map to scored dimensions."""
+
+    QUALITY = "quality"
+    TYPE_SAFETY = "type_safety"
+    SECURITY = "security"
+    COMPLEXITY = "complexity"
+    DEAD_CODE = "dead_code"
+    DEPENDENCIES = "dependencies"
+
+
+@dataclass(frozen=True)
+class Diagnostic:
+    """A single finding from an analyzer.
+
+    This is the universal exchange type. Every analyzer produces these,
+    every consumer (scoring, formatting, MCP) reads them.
+    """
+
+    file_path: Path
+    line: int
+    column: int
+    severity: Severity
+    rule_id: str  # e.g., "S101", "E501", "C901", "mypy-return-value"
+    tool: str  # e.g., "ruff", "mypy", "bandit", "radon", "vulture"
+    category: Category
+    message: str
+    fix: str | None = None  # Suggested remediation text
+    help_url: str | None = None  # URL to rule documentation
+    end_line: int | None = None
+    end_column: int | None = None
+
+
+@dataclass
+class CategoryScore:
+    """Score for a single analysis category."""
+
+    category: Category
+    score: int  # 0-100 (truncated, not rounded — 100 means truly perfect)
+    weight: int  # Configured weight (0-100)
+    issue_count: int
+    error_count: int = 0
+    warning_count: int = 0
+    details: str = ""  # Human-readable summary, e.g. "8 errors, 15 warnings"
+    status: str = "scored"  # scored, partial
+    coverage_note: str = ""
+
+
+@dataclass
+class CategoryCoverage:
+    """Coverage metadata for a single category."""
+
+    category: Category
+    status: str  # scored, partial, unavailable, skipped_by_user
+    analyzers: list[str] = field(default_factory=list)
+    reason: str = ""
+
+
+@dataclass
+class CoverageInfo:
+    """Explains how complete an analysis run was."""
+
+    profile: str
+    confidence: str  # full, partial, limited
+    requested_categories: list[Category] = field(default_factory=list)
+    scored_categories: list[Category] = field(default_factory=list)
+    category_coverage: list[CategoryCoverage] = field(default_factory=list)
+    analyzers_used: list[str] = field(default_factory=list)
+    analyzers_missing: list[str] = field(default_factory=list)
+    analyzers_optional_unavailable: list[str] = field(default_factory=list)
+    partial_reasons: list[str] = field(default_factory=list)
+    provenance: list[str] = field(default_factory=list)
+
+
+@dataclass
+class ProjectInfo:
+    """Metadata about the analyzed project."""
+
+    python_version: str | None
+    framework: str | None  # "django-5.1", "fastapi-0.115", "flask-3.1", None
+    total_files: int
+    total_lines: int
+    packages: list[str] = field(default_factory=list)
+
+
+@dataclass
+class HealthReport:
+    """Complete analysis result -- the top-level return type."""
+
+    score: int  # 0-100 weighted overall (truncated, not rounded)
+    label: str  # "Healthy", "Needs work", "Critical"
+    category_scores: list[CategoryScore]
+    diagnostics: list[Diagnostic]
+    project: ProjectInfo
+    duration_ms: int
+    analyzers_used: list[str] = field(default_factory=list)
+    analyzers_skipped: list[str] = field(default_factory=list)
+    cache_stats: dict[str, int] | None = None  # hits, misses, hit_rate_pct
+    coverage: CoverageInfo | None = None

python_checkup/plan.py

@@ -0,0 +1,109 @@
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+
+from python_checkup.models import Category
+
+PROFILE_QUICK = "quick"
+PROFILE_DEFAULT = "default"
+PROFILE_FULL = "full"
+
+TYPE_BACKEND_MYPY = "mypy"
+TYPE_BACKEND_BASEDPYRIGHT = "basedpyright"
+TYPE_BACKEND_AUTO = "auto"
+
+ALL_CATEGORIES = {
+    Category.QUALITY,
+    Category.TYPE_SAFETY,
+    Category.SECURITY,
+    Category.COMPLEXITY,
+    Category.DEAD_CODE,
+    Category.DEPENDENCIES,
+}
+
+
+@dataclass(frozen=True)
+class ScanPlan:
+    """Concrete execution plan for a single run."""
+
+    profile: str = PROFILE_DEFAULT
+    categories: frozenset[Category] = field(
+        default_factory=lambda: frozenset(ALL_CATEGORIES)
+    )
+    skipped_categories: frozenset[Category] = field(default_factory=frozenset)
+    type_backend: str = TYPE_BACKEND_AUTO
+    include_optional: bool = False
+    apply_fixes: bool = False
+    show_fix_suggestions: bool = False
+    diff_mode: bool = False
+
+    def includes(self, category: Category) -> bool:
+        """Return True if the category is enabled in this plan."""
+        return category in self.categories
+
+
+def parse_categories(value: str | None) -> frozenset[Category] | None:
+    """Parse a comma-separated category list."""
+    if value is None:
+        return None
+
+    mapping = {
+        "quality": Category.QUALITY,
+        "types": Category.TYPE_SAFETY,
+        "type_safety": Category.TYPE_SAFETY,
+        "security": Category.SECURITY,
+        "complexity": Category.COMPLEXITY,
+        "dead_code": Category.DEAD_CODE,
+        "dead-code": Category.DEAD_CODE,
+        "dependencies": Category.DEPENDENCIES,
+    }
+
+    categories: set[Category] = set()
+    for part in value.split(","):
+        key = part.strip().lower()
+        if not key:
+            continue
+        category = mapping.get(key)
+        if category is None:
+            msg = f"Unknown category: {part}"
+            raise ValueError(msg)
+        categories.add(category)
+
+    return frozenset(categories)
+
+
+def build_scan_plan(
+    *,
+    profile: str = PROFILE_DEFAULT,
+    only_categories: frozenset[Category] | None = None,
+    skip_categories: frozenset[Category] | None = None,
+    quick: bool = False,
+    include_optional: bool | None = None,
+    apply_fixes: bool = False,
+    show_fix_suggestions: bool = False,
+    diff_mode: bool = False,
+    type_backend: str = TYPE_BACKEND_AUTO,
+) -> ScanPlan:
+    """Build a concrete plan from CLI options."""
+    if quick:
+        profile = PROFILE_QUICK
+
+    categories = set(only_categories or ALL_CATEGORIES)
+    actually_skipped: frozenset[Category] = frozenset()
+    if skip_categories:
+        actually_skipped = frozenset(skip_categories & categories)
+        categories.difference_update(skip_categories)
+
+    if include_optional is None:
+        include_optional = profile == PROFILE_FULL
+
+    return ScanPlan(
+        profile=profile,
+        categories=frozenset(categories),
+        skipped_categories=actually_skipped,
+        type_backend=type_backend,
+        include_optional=include_optional,
+        apply_fixes=apply_fixes,
+        show_fix_suggestions=show_fix_suggestions,
+        diff_mode=diff_mode,
+    )