python-checkup 0.0.1__py3-none-any.whl

python_checkup/formatters/terminal.py

@@ -0,0 +1,396 @@
+from __future__ import annotations
+
+import sys
+from typing import TYPE_CHECKING
+
+from rich.console import Console
+from rich.panel import Panel
+from rich.table import Table
+from rich.text import Text
+
+from python_checkup.models import Category, HealthReport, Severity
+
+if TYPE_CHECKING:
+    from python_checkup.models import CategoryScore, Diagnostic
+
+# Severity icons
+SEVERITY_ICON: dict[Severity, str] = {
+    Severity.ERROR: "[red bold]ERR[/red bold]",
+    Severity.WARNING: "[yellow]WRN[/yellow]",
+    Severity.INFO: "[blue]INF[/blue]",
+}
+
+# Category display names
+CATEGORY_LABEL: dict[Category, str] = {
+    Category.QUALITY: "Code Quality",
+    Category.TYPE_SAFETY: "Type Safety",
+    Category.SECURITY: "Security",
+    Category.COMPLEXITY: "Complexity",
+    Category.DEAD_CODE: "Dead Code",
+    Category.DEPENDENCIES: "Dependencies",
+}
+
+
+def print_report(
+    report: HealthReport,
+    *,
+    verbose: bool = False,
+    show_fix: bool = False,
+    diff_mode: bool = False,
+    changed_file_count: int | None = None,
+    total_file_count: int | None = None,
+) -> None:
+    """Print a complete health report to the terminal.
+
+    All Rich output goes to stderr so stdout stays clean for piping.
+    """
+    console = Console(file=sys.stderr)
+
+    console.print()
+
+    # 1. Score panel
+    _print_score_panel(console, report)
+
+    # 2. Diff mode notice
+    if diff_mode and changed_file_count is not None:
+        total = total_file_count or "?"
+        console.print(
+            f"\n  [dim]Analyzed {changed_file_count} changed "
+            f"files (out of {total} total)[/dim]"
+        )
+
+    # 3. Category breakdown table
+    if report.category_scores:
+        console.print()
+        _print_category_table(console, report.category_scores)
+
+    if report.coverage:
+        console.print()
+        _print_coverage(console, report.coverage)
+
+    # 4. Top issues
+    issues = _sort_issues(report.diagnostics)
+    if issues:
+        console.print()
+        _print_top_issues(
+            console,
+            issues,
+            verbose=verbose,
+            show_fix=show_fix,
+        )
+
+    # 5. "What to fix first" -- 3 highest-impact issues
+    if not verbose and issues:
+        high_impact = _select_high_impact(issues, report.category_scores)
+        if high_impact:
+            console.print()
+            _print_fix_first(console, high_impact)
+
+    # 6. Footer
+    console.print()
+    _print_footer(console, report)
+    console.print()
+
+
+def _print_score_panel(console: Console, report: HealthReport) -> None:
+    score = report.score
+    color = _score_color(score)
+
+    score_text = Text()
+    score_text.append(f" {score}", style=f"bold {color}")
+    score_text.append(" / 100  ", style="dim")
+    score_text.append(f"{report.label}", style=f"bold {color}")
+
+    panel = Panel(
+        score_text,
+        title="[bold white]python-checkup[/bold white]",
+        subtitle=_score_bar(score, width=30),
+        border_style=color,
+        expand=False,
+        padding=(1, 3),
+    )
+    console.print(panel)
+
+
+def _score_bar(score: float, width: int = 30) -> str:
+    filled = int(score / 100 * width)
+    empty = width - filled
+    color = _score_color(score)
+    return f"[{color}]{'━' * filled}[/{color}][dim]{'━' * empty}[/dim]"
+
+
+def _print_category_table(
+    console: Console,
+    category_scores: list[CategoryScore],
+) -> None:
+    table = Table(
+        show_header=True,
+        header_style="bold",
+        expand=False,
+        title="Category Breakdown",
+        title_style="bold",
+    )
+    table.add_column("Category", style="cyan", min_width=14)
+    table.add_column("Score", justify="right", min_width=7)
+    table.add_column("Weight", justify="right", style="dim", min_width=7)
+    table.add_column("Issues", justify="right", min_width=7)
+    table.add_column("Status", style="dim", min_width=8)
+    table.add_column("Details", style="dim")
+
+    for cs in sorted(
+        category_scores,
+        key=lambda c: (c.category == Category.COMPLEXITY, c.score),
+    ):
+        color = _score_color(cs.score)
+        label = CATEGORY_LABEL.get(cs.category, cs.category.value)
+        bar = _inline_bar(cs.score, width=12)
+
+        table.add_row(
+            label,
+            f"[{color}]{cs.score}[/{color}]",
+            f"{cs.weight}%",
+            str(cs.issue_count),
+            cs.status,
+            f"{bar}  {cs.details}"
+            + (f" ({cs.coverage_note})" if cs.coverage_note else ""),
+        )
+
+    console.print(table)
+
+
+def _inline_bar(score: float, width: int = 12) -> str:
+    filled = int(score / 100 * width)
+    empty = width - filled
+    color = _score_color(score)
+    return f"[{color}]{'█' * filled}[/{color}][dim]{'░' * empty}[/dim]"
+
+
+def _sort_issues(
+    diagnostics: list[Diagnostic],
+) -> list[Diagnostic]:
+    """Sort issues by severity (errors first), then file and line."""
+    severity_order = {
+        Severity.ERROR: 0,
+        Severity.WARNING: 1,
+        Severity.INFO: 2,
+    }
+    return sorted(
+        diagnostics,
+        key=lambda d: (
+            severity_order.get(d.severity, 9),
+            str(d.file_path),
+            d.line,
+        ),
+    )
+
+
+def _print_top_issues(
+    console: Console,
+    issues: list[Diagnostic],
+    *,
+    verbose: bool,
+    show_fix: bool,
+) -> None:
+    # Filter to errors and warnings (skip info unless verbose)
+    if not verbose:
+        issues = [d for d in issues if d.severity != Severity.INFO]
+
+    max_issues = len(issues) if verbose else 10
+    shown = issues[:max_issues]
+    remaining = len(issues) - len(shown)
+
+    table = Table(
+        show_header=True,
+        header_style="bold",
+        expand=True,
+        title=f"{'All' if verbose else 'Top'} Issues",
+        title_style="bold",
+    )
+    table.add_column("", width=3)
+    table.add_column("Location", style="cyan", no_wrap=True)
+    table.add_column("Rule", style="bold", no_wrap=True, min_width=6)
+    table.add_column("Message")
+
+    for d in shown:
+        icon = SEVERITY_ICON.get(d.severity, "")
+        location = f"{d.file_path}:{d.line}:{d.column}"
+
+        # Truncate long file paths
+        if len(location) > 45:
+            parts = str(d.file_path).split("/")
+            if len(parts) > 3:
+                short_path = f".../{'/'.join(parts[-2:])}"
+            else:
+                short_path = str(d.file_path)
+            location = f"{short_path}:{d.line}:{d.column}"
+
+        message = d.message
+        if show_fix and d.fix:
+            message += f"\n[dim green]  Fix: {d.fix}[/dim green]"
+
+        table.add_row(icon, location, d.rule_id, message)
+
+    console.print(table)
+
+    if remaining > 0:
+        console.print(
+            f"  [dim]...and {remaining} more issues. "
+            f"Run with --verbose to see all.[/dim]"
+        )
+
+
+def _select_high_impact(
+    issues: list[Diagnostic],
+    category_scores: list[CategoryScore],
+) -> list[Diagnostic]:
+    """Select the 3 highest-impact issues to fix first.
+
+    "High impact" = errors in the lowest-scoring category.
+    """
+    if not category_scores:
+        return issues[:3]
+
+    worst_categories = sorted(category_scores, key=lambda cs: cs.score)
+
+    selected: list[Diagnostic] = []
+    for cs in worst_categories:
+        if len(selected) >= 3:
+            break
+        category_errors = [
+            d
+            for d in issues
+            if d.category == cs.category
+            and d.severity == Severity.ERROR
+            and d not in selected
+        ]
+        selected.extend(category_errors[: 3 - len(selected)])
+
+    # Fill with remaining errors if needed
+    if len(selected) < 3:
+        remaining_errors = [
+            d for d in issues if d.severity == Severity.ERROR and d not in selected
+        ]
+        selected.extend(remaining_errors[: 3 - len(selected)])
+
+    return selected[:3]
+
+
+def _print_fix_first(console: Console, issues: list[Diagnostic]) -> None:
+    console.print("[bold]What to fix first:[/bold]")
+    console.print("[dim]These issues have the highest impact on your score:[/dim]")
+    console.print()
+
+    for i, d in enumerate(issues, 1):
+        icon = SEVERITY_ICON.get(d.severity, "")
+        category_label = CATEGORY_LABEL.get(d.category, d.category.value)
+
+        console.print(
+            f"  {i}. {icon} [bold]{d.rule_id}[/bold] in "
+            f"[cyan]{d.file_path}:{d.line}[/cyan]"
+        )
+        console.print(f"     {d.message}")
+        if d.fix:
+            console.print(f"     [green]Fix: {d.fix}[/green]")
+        console.print(f"     [dim]Category: {category_label}[/dim]")
+        console.print()
+
+
+def _print_footer(console: Console, report: HealthReport) -> None:
+    files_str = f"{report.project.total_files} files"
+    lines_str = f"{report.project.total_lines:,} lines"
+    time_str = _format_duration(report.duration_ms)
+    analyzers_str = ", ".join(report.analyzers_used) or "none"
+
+    console.print(
+        f"  [dim]Scanned {files_str} ({lines_str}) in "
+        f"{time_str} using {analyzers_str}[/dim]"
+    )
+
+    if report.analyzers_skipped:
+        skipped = ", ".join(report.analyzers_skipped)
+        console.print(f"  [dim]Skipped: {skipped}[/dim]")
+
+    if report.cache_stats and report.cache_stats.get("hits", 0) > 0:
+        hits = report.cache_stats["hits"]
+        misses = report.cache_stats["misses"]
+        hit_rate = report.cache_stats.get("hit_rate_pct", 0)
+        console.print(
+            f"  [dim]Cache: {hits} hits, {misses} misses ({hit_rate}% hit rate)[/dim]"
+        )
+
+    if report.project.framework:
+        console.print(f"  [dim]Framework detected: {report.project.framework}[/dim]")
+
+
+# Map optional analyzer names to their pip extras for install hints.
+ANALYZER_EXTRA: dict[str, str] = {
+    "dependency-vulns": "vulns",
+    "detect-secrets": "secrets",
+    "basedpyright": "pyright",
+    "typos": "quality-extra",
+}
+
+
+def _print_coverage(console: Console, coverage: object) -> None:
+    confidence = getattr(coverage, "confidence", "unknown")
+    profile = getattr(coverage, "profile", "default")
+    console.print(f"  [dim]Coverage: {confidence} ({profile} profile)[/dim]")
+
+    partial_reasons = getattr(coverage, "partial_reasons", [])
+    if partial_reasons:
+        for reason in partial_reasons:
+            console.print(f"  [dim]- {reason}[/dim]")
+
+    # Explain weight redistribution when categories are not scored.
+    cat_coverage: list[object] = getattr(coverage, "category_coverage", [])
+    redistributed_cats: list[str] = []
+    for cc in cat_coverage:
+        status = getattr(cc, "status", "")
+        if status in ("unavailable", "skipped_by_user"):
+            cat = getattr(cc, "category", None)
+            label = CATEGORY_LABEL.get(cat, str(cat)) if cat is not None else "unknown"
+            redistributed_cats.append(f"{label} ({status.replace('_', ' ')})")
+    if redistributed_cats:
+        console.print(
+            "  [dim]Weight redistributed from: "
+            + ", ".join(redistributed_cats)
+            + "[/dim]"
+        )
+
+    # Provenance notes (e.g. "scanned from uv.lock (42 packages)")
+    provenance: list[str] = getattr(coverage, "provenance", [])
+    for note in provenance:
+        console.print(f"  [dim]{note}[/dim]")
+
+    optional: list[str] = getattr(coverage, "analyzers_optional_unavailable", [])
+    if optional:
+        console.print(
+            "  [dim]Optional analyzers not installed: " + ", ".join(optional) + "[/dim]"
+        )
+        extras = {ANALYZER_EXTRA[a] for a in optional if a in ANALYZER_EXTRA}
+        if extras:
+            extras_str = ",".join(sorted(extras))
+            console.print(
+                f"  [dim]Enable with: "
+                f"uvx --from 'python-checkup[{extras_str}]' python-checkup .[/dim]"
+            )
+
+
+def _format_duration(ms: int) -> str:
+    if ms < 1000:
+        return f"{ms}ms"
+    elif ms < 60_000:
+        return f"{ms / 1000:.1f}s"
+    else:
+        minutes = ms // 60_000
+        seconds = (ms % 60_000) / 1000
+        return f"{minutes}m {seconds:.0f}s"
+
+
+def _score_color(score: float) -> str:
+    if score >= 75:
+        return "green"
+    elif score >= 50:
+        return "yellow"
+    else:
+        return "red"

python_checkup/mcp/__init__.py

@@ -0,0 +1,3 @@
+from python_checkup.mcp.server import start_mcp_server
+
+__all__ = ["start_mcp_server"]

python_checkup/mcp/installer.py

@@ -0,0 +1,119 @@
+from __future__ import annotations
+
+import json
+import sys
+from pathlib import Path
+
+from rich.console import Console
+
+console = Console(file=sys.stderr)
+
+# MCP config entry to install for each editor
+MCP_CONFIG_ENTRY: dict[str, object] = {
+    "command": "uvx",
+    "args": ["python-checkup", "--mcp"],
+}
+
+# Editor config file locations and their JSON key for MCP servers
+EDITOR_TARGETS: list[dict[str, object]] = [
+    {
+        "name": "Claude Code (project)",
+        "path": Path(".mcp.json"),
+        "key": "mcpServers",
+        "relative": True,
+    },
+    {
+        "name": "Cursor",
+        "path": Path(".cursor/mcp.json"),
+        "key": "mcpServers",
+        "relative": True,
+    },
+    {
+        "name": "VS Code",
+        "path": Path(".vscode/mcp.json"),
+        "key": "servers",  # VS Code uses "servers" not "mcpServers"
+        "relative": True,
+    },
+]
+
+
+def install_mcp_config(project_root: Path | None = None) -> list[str]:
+    """Detect editors and write MCP server config.
+
+    Only installs into editor directories that already exist (so we
+    don't create .cursor/ for someone who doesn't use Cursor), except
+    for .mcp.json which is always created for Claude Code.
+
+    Returns list of paths where config was written.
+    """
+    root = project_root or Path.cwd()
+    installed: list[str] = []
+
+    for target in EDITOR_TARGETS:
+        is_relative = bool(target["relative"])
+        target_path = target["path"]
+        if not isinstance(target_path, Path):
+            continue  # pragma: no cover
+        target_key = target["key"]
+        if not isinstance(target_key, str):
+            continue  # pragma: no cover
+        target_name = target["name"]
+        if not isinstance(target_name, str):
+            continue  # pragma: no cover
+
+        config_path = root / target_path if is_relative else Path.home() / target_path
+
+        # Only install if the editor directory already exists
+        # (don't create .cursor/ for someone who doesn't use Cursor)
+        if is_relative:
+            parent = config_path.parent
+            if parent.name in (".cursor", ".vscode") and not parent.exists():
+                continue
+
+        try:
+            _write_config(config_path, target_key)
+            installed.append(str(config_path))
+            console.print(
+                f"  [green]Installed[/green] -> {config_path} ({target_name})"
+            )
+        except Exception as e:
+            console.print(f"  [red]Failed[/red] -> {config_path}: {e}")
+
+    # Always install .mcp.json (Claude Code project-level)
+    claude_path = root / ".mcp.json"
+    if str(claude_path) not in installed:
+        try:
+            _write_config(claude_path, "mcpServers")
+            installed.append(str(claude_path))
+            console.print(f"  [green]Installed[/green] -> {claude_path}")
+        except Exception as e:
+            console.print(f"  [red]Failed[/red] -> {claude_path}: {e}")
+
+    return installed
+
+
+def _write_config(path: Path, server_key: str) -> None:
+    """Write or merge MCP config into a JSON file.
+
+    Preserves existing server entries -- only adds/updates the
+    ``python-checkup`` entry under the appropriate key.
+    """
+    existing: dict[str, object] = {}
+    if path.exists():
+        try:
+            raw = path.read_text()
+            loaded = json.loads(raw)
+            if isinstance(loaded, dict):
+                existing = loaded
+        except (json.JSONDecodeError, OSError):
+            existing = {}
+
+    # Merge -- don't overwrite other servers
+    servers = existing.get(server_key)
+    if not isinstance(servers, dict):
+        servers = {}
+    servers["python-checkup"] = MCP_CONFIG_ENTRY
+    existing[server_key] = servers
+
+    path.parent.mkdir(parents=True, exist_ok=True)
+    path.write_text(json.dumps(existing, indent=2) + "\n")