python-checkup 0.0.1__py3-none-any.whl

python_checkup/cli.py

@@ -0,0 +1,763 @@
+from __future__ import annotations
+
+import asyncio
+import sys
+from pathlib import Path
+
+import click
+from rich.console import Console
+
+from python_checkup import __version__
+from python_checkup.config import CheckupConfig
+from python_checkup.models import Category, HealthReport
+from python_checkup.plan import (
+    PROFILE_DEFAULT,
+    PROFILE_FULL,
+    PROFILE_QUICK,
+    TYPE_BACKEND_AUTO,
+    TYPE_BACKEND_BASEDPYRIGHT,
+    TYPE_BACKEND_MYPY,
+    ScanPlan,
+    build_scan_plan,
+    parse_categories,
+)
+
+err_console = Console(stderr=True)
+
+
+class _SubcommandFirstGroup(click.Group):
+    """Click group that recognises subcommands before consuming PATH.
+
+    Without this, ``python-checkup install-skill`` would feed
+    ``install-skill`` to the positional PATH argument and never
+    dispatch the subcommand.  We override :meth:`parse_args` to
+    peek at the first non-option token and, if it matches a known
+    command name, strip any default PATH value so Click routes
+    correctly.
+    """
+
+    def parse_args(self, ctx: click.Context, args: list[str]) -> list[str]:
+        """Rewrite args so subcommand names aren't swallowed by PATH."""
+        # Find the first non-option token
+        for token in args:
+            if token.startswith("-"):
+                continue
+            if token in self.commands:
+                # Insert an explicit default for PATH so the arg
+                # isn't consumed by the subcommand name.
+                args = [".", *args]
+                break
+            # First non-option is NOT a command → let Click handle normally
+            break
+        return super().parse_args(ctx, args)
+
+
+@click.group(
+    cls=_SubcommandFirstGroup,
+    invoke_without_command=True,
+    context_settings={"allow_interspersed_args": True},
+)
+@click.argument(
+    "path",
+    default=".",
+    required=False,
+    type=click.Path(),
+)
+@click.option(
+    "--json",
+    "json_output",
+    is_flag=True,
+    help="Output full results as JSON.",
+)
+@click.option(
+    "--score",
+    "score_only",
+    is_flag=True,
+    help="Output only the numeric score.",
+)
+@click.option(
+    "--verbose",
+    "-v",
+    is_flag=True,
+    help="Show all issues with file:line.",
+)
+@click.option(
+    "--diff",
+    "diff_base",
+    default=None,
+    is_eager=False,
+    flag_value="main",
+    is_flag=False,
+    help="Only analyze files changed vs BASE (default: main).",
+)
+@click.option(
+    "--fail-under",
+    type=float,
+    default=None,
+    help="Exit 1 if score is below SCORE.",
+)
+@click.option(
+    "--profile",
+    type=click.Choice([PROFILE_QUICK, PROFILE_DEFAULT, PROFILE_FULL]),
+    default=PROFILE_DEFAULT,
+    help="Scan profile: quick, default, or full.",
+)
+@click.option(
+    "--only",
+    "only_categories",
+    default=None,
+    help="Only run these categories (comma-separated).",
+)
+@click.option(
+    "--skip",
+    "skip_categories",
+    default=None,
+    help="Skip these categories (comma-separated).",
+)
+@click.option(
+    "--analyzers",
+    "analyzer_names",
+    default=None,
+    help="Only run these analyzers (comma-separated). Overrides --only/--skip.",
+)
+@click.option(
+    "--quick",
+    is_flag=True,
+    help="Compatibility alias for --profile quick.",
+)
+@click.option(
+    "--no-lint",
+    is_flag=True,
+    help="Skip linting (Ruff).",
+)
+@click.option(
+    "--no-typecheck",
+    is_flag=True,
+    help="Skip type checking (mypy).",
+)
+@click.option(
+    "--no-security",
+    is_flag=True,
+    help="Skip security scanning (Bandit).",
+)
+@click.option(
+    "--no-complexity",
+    is_flag=True,
+    help="Skip complexity analysis (Radon).",
+)
+@click.option(
+    "--no-dead-code",
+    is_flag=True,
+    help="Skip dead code detection (Vulture).",
+)
+@click.option(
+    "--type-backend",
+    type=click.Choice(
+        [TYPE_BACKEND_AUTO, TYPE_BACKEND_MYPY, TYPE_BACKEND_BASEDPYRIGHT]
+    ),
+    default=TYPE_BACKEND_AUTO,
+    help="Type checking backend: auto (default), mypy, or basedpyright.",
+)
+@click.option(
+    "--fix",
+    is_flag=True,
+    help="Apply safe Ruff fixes before rescanning.",
+)
+@click.option(
+    "--show-fixes",
+    is_flag=True,
+    help="Show fix suggestions inline.",
+)
+@click.option(
+    "--config",
+    "config_path",
+    type=click.Path(exists=True),
+    default=None,
+    help="Path to pyproject.toml.",
+)
+@click.option(
+    "--no-cache",
+    "no_cache",
+    is_flag=True,
+    help="Skip the cache and force a fresh analysis.",
+)
+@click.option(
+    "--clear-cache",
+    "clear_cache",
+    is_flag=True,
+    help="Delete all cached results and exit.",
+)
+@click.option(
+    "--badge",
+    is_flag=True,
+    help="Output a shields.io badge URL for the score.",
+)
+@click.option(
+    "--web",
+    is_flag=True,
+    help="Serve an interactive HTML report in the browser.",
+)
+@click.option(
+    "--port",
+    type=int,
+    default=8765,
+    help="Port for the web report server (default: 8765).",
+)
+@click.option(
+    "--mcp",
+    is_flag=True,
+    help="Start as MCP server (stdio transport).",
+)
+@click.version_option(version=__version__, prog_name="python-checkup")
+@click.pass_context
+def main(
+    ctx: click.Context,
+    path: str,
+    json_output: bool,
+    score_only: bool,
+    verbose: bool,
+    diff_base: str | None,
+    fail_under: float | None,
+    profile: str,
+    only_categories: str | None,
+    skip_categories: str | None,
+    analyzer_names: str | None,
+    quick: bool,
+    no_lint: bool,
+    no_typecheck: bool,
+    no_security: bool,
+    no_complexity: bool,
+    no_dead_code: bool,
+    type_backend: str,
+    fix: bool,
+    show_fixes: bool,
+    config_path: str | None,
+    no_cache: bool,
+    clear_cache: bool,
+    badge: bool,
+    web: bool,
+    port: int,
+    mcp: bool,
+) -> None:
+    """python-checkup -- fast, local-first Python code health checker.
+
+    Analyzes a Python project and produces a 0-100 health score with
+    categorized diagnostics covering code quality, type safety,
+    security, complexity, and dead code.
+
+    \b
+    Examples:
+        python-checkup .                        # Scan current directory
+        python-checkup src/ --verbose           # Scan src/ with all issues
+        python-checkup . --score                # Just the number (for CI)
+        python-checkup . --diff develop         # Only changed files
+        python-checkup . --fail-under 70        # Exit 1 if score < 70
+        python-checkup . --profile quick        # Fast feedback
+        python-checkup . --analyzers ruff,mypy  # Run specific analyzers
+    """
+    ctx.ensure_object(dict)
+
+    # Handle early-exit modes (MCP, cache clear, subcommands)
+    if _handle_early_exits(ctx, path, mcp, clear_cache):
+        return
+
+    # Validate that PATH exists (we can't use click.Path(exists=True)
+    # because it would reject subcommand names like "mcp" and "install-skill")
+    resolved = Path(path).resolve()
+    if not resolved.exists():
+        raise click.BadParameter(
+            f"Path '{path}' does not exist.",
+            param_hint="'PATH'",
+        )
+
+    # --score wins over --json (simpler request)
+    if score_only:
+        json_output = False
+
+    only_set = parse_categories(only_categories)
+    skip_set = _build_skip_categories(
+        skip_categories,
+        no_lint,
+        no_typecheck,
+        no_security,
+        no_complexity,
+        no_dead_code,
+    )
+
+    plan, skip_analyzers = _resolve_analyzers(
+        analyzer_names=analyzer_names,
+        profile=profile,
+        only_set=only_set,
+        skip_set=skip_set,
+        quick=quick,
+        fix=fix,
+        show_fixes=show_fixes,
+        diff_base=diff_base,
+        type_backend=type_backend,
+    )
+
+    # Load config
+    from python_checkup.config import load_config
+
+    project_root = Path(path).resolve()
+    config = load_config(Path(config_path).parent if config_path else project_root)
+
+    if fix:
+        _apply_safe_ruff_fixes(project_root)
+
+    # Discover files
+    files, total_project_files = _discover_files(
+        project_root,
+        config,
+        diff_base,
+        skip_analyzers,
+    )
+
+    # Run analysis and output results
+    report = _run_analysis(
+        project_root=project_root,
+        config=config,
+        files=files,
+        skip_analyzers=skip_analyzers,
+        score_only=score_only,
+        json_output=json_output,
+        badge=badge,
+        no_cache=no_cache,
+        plan=plan,
+        diff_base=diff_base,
+    )
+
+    _output_report(
+        report,
+        score_only=score_only,
+        badge=badge,
+        json_output=json_output,
+        web=web,
+        verbose=verbose,
+        show_fixes=show_fixes,
+        diff_base=diff_base,
+        files=files,
+        total_project_files=total_project_files,
+        project_root=project_root,
+        config=config,
+        plan=plan,
+        no_cache=no_cache,
+        port=port,
+    )
+
+    # Exit code
+    if fail_under is not None and report.score < fail_under:
+        sys.exit(1)
+
+
+def _handle_early_exits(
+    ctx: click.Context,
+    path: str,
+    mcp: bool,
+    clear_cache: bool,
+) -> bool:
+    """Handle MCP, cache-clear, and subcommand early-exit modes.
+
+    Returns ``True`` if the caller should return immediately.
+    """
+    if mcp:
+        from python_checkup.mcp.server import start_mcp_server
+
+        start_mcp_server()
+        return True
+
+    if clear_cache:
+        from python_checkup.cache import AnalysisCache
+
+        resolved = Path(path).resolve()
+        cache = AnalysisCache(resolved, enabled=True)
+        count = cache.clear()
+        err_console.print(f"[green]Cleared {count} cached entries.[/green]")
+        return True
+
+    return ctx.invoked_subcommand is not None
+
+
+def _build_skip_categories(
+    skip_categories: str | None,
+    no_lint: bool,
+    no_typecheck: bool,
+    no_security: bool,
+    no_complexity: bool,
+    no_dead_code: bool,
+) -> set[Category]:
+    """Build the set of categories to skip from CLI flags."""
+    skip_set = set(parse_categories(skip_categories) or set())
+
+    flag_to_category = [
+        (no_lint, Category.QUALITY),
+        (no_typecheck, Category.TYPE_SAFETY),
+        (no_security, Category.SECURITY),
+        (no_complexity, Category.COMPLEXITY),
+        (no_dead_code, Category.DEAD_CODE),
+    ]
+    for flag, category in flag_to_category:
+        if flag:
+            skip_set.add(category)
+
+    return skip_set
+
+
+def _resolve_analyzers(
+    *,
+    analyzer_names: str | None,
+    profile: str,
+    only_set: frozenset[Category] | None,
+    skip_set: set[Category],
+    quick: bool,
+    fix: bool,
+    show_fixes: bool,
+    diff_base: str | None,
+    type_backend: str,
+) -> tuple[ScanPlan, set[str]]:
+    """Resolve the scan plan and the set of analyzers to skip.
+
+    Returns ``(plan, skip_analyzers)``.
+    """
+    if analyzer_names:
+        return _resolve_explicit_analyzers(
+            analyzer_names,
+            profile,
+            quick,
+            fix,
+            show_fixes,
+            diff_base,
+            type_backend,
+        )
+
+    plan = build_scan_plan(
+        profile=profile,
+        only_categories=only_set,
+        skip_categories=frozenset(skip_set),
+        quick=quick,
+        include_optional=profile == PROFILE_FULL,
+        apply_fixes=fix,
+        show_fix_suggestions=show_fixes,
+        diff_mode=diff_base is not None,
+        type_backend=type_backend,
+    )
+    skip_analyzers = _derive_skip_analyzers_from_plan(plan)
+    return plan, skip_analyzers
+
+
+def _resolve_explicit_analyzers(
+    analyzer_names: str,
+    profile: str,
+    quick: bool,
+    fix: bool,
+    show_fixes: bool,
+    diff_base: str | None,
+    type_backend: str,
+) -> tuple[ScanPlan, set[str]]:
+    """Handle --analyzers: validate names and build a plan from them."""
+    from python_checkup.analyzer_catalog import ANALYZER_CATALOG
+
+    requested = {a.strip() for a in analyzer_names.split(",") if a.strip()}
+    unknown = requested - set(ANALYZER_CATALOG.keys())
+    if unknown:
+        raise click.BadParameter(
+            f"Unknown analyzer(s): {', '.join(sorted(unknown))}. "
+            f"Available: {', '.join(sorted(ANALYZER_CATALOG.keys()))}",
+            param_hint="'--analyzers'",
+        )
+    skip_analyzers = set(ANALYZER_CATALOG.keys()) - requested
+
+    selected_categories: set[Category] = set()
+    for name in requested:
+        selected_categories.update(ANALYZER_CATALOG[name].categories)
+
+    plan = build_scan_plan(
+        profile=profile,
+        only_categories=frozenset(selected_categories),
+        skip_categories=frozenset(),
+        quick=quick,
+        include_optional=True,
+        apply_fixes=fix,
+        show_fix_suggestions=show_fixes,
+        diff_mode=diff_base is not None,
+        type_backend=type_backend,
+    )
+    return plan, skip_analyzers
+
+
+def _derive_skip_analyzers_from_plan(plan: ScanPlan) -> set[str]:
+    """Derive the analyzer skip-set from a scan plan's categories/profile."""
+    skip: set[str] = set()
+
+    # Map absent categories to the analyzers they control
+    category_analyzers: dict[Category, set[str]] = {
+        Category.QUALITY: {"typos"},
+        Category.TYPE_SAFETY: {"mypy", "basedpyright"},
+        Category.SECURITY: {"bandit", "detect-secrets"},
+        Category.COMPLEXITY: {"radon"},
+        Category.DEAD_CODE: {"vulture"},
+        Category.DEPENDENCIES: {"deptry", "dependency-vulns", "pip-audit"},
+    }
+    for category, analyzers in category_analyzers.items():
+        if category not in plan.categories:
+            skip.update(analyzers)
+
+    # Enforce type backend mutual exclusion when TYPE_SAFETY is active
+    if Category.TYPE_SAFETY in plan.categories:
+        if plan.type_backend == TYPE_BACKEND_MYPY:
+            skip.add("basedpyright")
+        elif plan.type_backend == TYPE_BACKEND_BASEDPYRIGHT:
+            skip.add("mypy")
+
+    # Ruff is only needed if at least one of these categories is active
+    ruff_categories = {
+        Category.QUALITY,
+        Category.SECURITY,
+        Category.COMPLEXITY,
+        Category.DEAD_CODE,
+    }
+    if not (plan.categories & ruff_categories):
+        skip.add("ruff")
+
+    if plan.profile == PROFILE_QUICK:
+        skip.update({"mypy", "bandit", "radon", "vulture"})
+
+    return skip
+
+
+def _discover_files(
+    project_root: Path,
+    config: CheckupConfig,
+    diff_base: str | None,
+    skip_analyzers: set[str],
+) -> tuple[list[Path], int]:
+    """Discover Python files to analyze.
+
+    Returns ``(files, total_project_files)``.
+    """
+    from python_checkup.discovery import discover_python_files
+
+    if diff_base is not None:
+        from python_checkup.diff import get_changed_files
+
+        files = get_changed_files(project_root, base=diff_base)
+        total_project_files = len(
+            discover_python_files(project_root, config.ignore_files)
+        )
+        # Skip Vulture in diff mode -- dead code detection
+        # on a subset is misleading
+        skip_analyzers.add("vulture")
+    else:
+        files = discover_python_files(project_root, config.ignore_files)
+        total_project_files = len(files)
+
+    return files, total_project_files
+
+
+def _run_analysis(
+    *,
+    project_root: Path,
+    config: CheckupConfig,
+    files: list[Path],
+    skip_analyzers: set[str],
+    score_only: bool,
+    json_output: bool,
+    badge: bool,
+    no_cache: bool,
+    plan: ScanPlan,
+    diff_base: str | None,
+) -> HealthReport:
+    """Run the async analysis pipeline and return the report."""
+    from python_checkup.runner import run_analysis
+
+    quiet = score_only or json_output or badge
+    return asyncio.run(
+        run_analysis(
+            project_root=project_root,
+            config=config,
+            files=files,
+            skip_analyzers=skip_analyzers,
+            quiet=quiet,
+            no_cache=no_cache,
+            plan=plan,
+            diff_base=diff_base,
+        )
+    )
+
+
+def _output_report(
+    report: HealthReport,
+    *,
+    score_only: bool,
+    badge: bool,
+    json_output: bool,
+    web: bool,
+    verbose: bool,
+    show_fixes: bool,
+    diff_base: str | None,
+    files: list[Path],
+    total_project_files: int,
+    project_root: Path,
+    config: CheckupConfig,
+    plan: ScanPlan,
+    no_cache: bool,
+    port: int,
+) -> None:
+    """Render the analysis report in the requested format."""
+    if score_only:
+        click.echo(report.score)
+    elif badge:
+        from python_checkup.formatters.badge import generate_badge_url
+
+        click.echo(generate_badge_url(report.score))
+    elif json_output:
+        from python_checkup.formatters.json_fmt import format_json
+
+        click.echo(format_json(report))
+    elif web:
+        from python_checkup.web.server import RunContext, serve_report
+
+        run_context = RunContext(
+            project_root=project_root,
+            config=config,
+            files=files,
+            plan=plan,
+            no_cache=no_cache,
+            diff_base=diff_base,
+        )
+        serve_report(report, port=port, run_context=run_context)
+    else:
+        from python_checkup.formatters.terminal import print_report
+
+        print_report(
+            report,
+            verbose=verbose,
+            show_fix=show_fixes,
+            diff_mode=diff_base is not None,
+            changed_file_count=len(files) if diff_base else None,
+            total_file_count=total_project_files,
+        )
+
+
+def _apply_safe_ruff_fixes(project_root: Path) -> None:
+    import subprocess
+
+    try:
+        ruff_bin = "ruff"
+        subprocess.run(  # noqa: S603
+            [ruff_bin, "check", "--fix", "--no-unsafe-fixes", str(project_root)],
+            check=False,
+            cwd=project_root,
+            capture_output=True,
+            text=True,
+        )
+    except FileNotFoundError:
+        err_console.print(
+            "[yellow]Ruff is not installed, so no fixes were applied.[/yellow]"
+        )
+
+
+@main.group("mcp")
+def mcp_cmd() -> None:
+    """MCP server management commands."""
+
+
+@mcp_cmd.command("install")
+@click.option(
+    "--editor",
+    type=click.Choice(["auto", "claude-code", "cursor", "vscode"]),
+    default="auto",
+    help="Target editor (default: auto-detect).",
+)
+def mcp_install(editor: str) -> None:
+    """Install python-checkup as an MCP server for your AI coding agent."""
+    from python_checkup.mcp.installer import install_mcp_config
+
+    err_console.print("[bold]Installing python-checkup MCP server...[/bold]")
+    installed = install_mcp_config()
+    if installed:
+        err_console.print(
+            f"\n[green]Installed to {len(installed)} location(s).[/green]"
+        )
+        err_console.print("[dim]Restart your editor to activate.[/dim]")
+    else:
+        err_console.print(
+            "[yellow]No editor configs found. "
+            "Created .mcp.json for Claude Code.[/yellow]"
+        )
+
+
+@main.command("install-skill")
+@click.option(
+    "--agent",
+    "-a",
+    multiple=True,
+    help="Specific agent(s) to install for (e.g., claude-code, cursor).",
+)
+@click.option(
+    "--project",
+    "-p",
+    is_flag=True,
+    help="Also install to .agents/python-checkup/ in current directory.",
+)
+@click.option(
+    "--force",
+    "-f",
+    is_flag=True,
+    help="Overwrite existing skill files.",
+)
+@click.option(
+    "--list-agents",
+    is_flag=True,
+    help="List all supported agents and their directories.",
+)
+def install_skill_cmd(
+    agent: tuple[str, ...],
+    project: bool,
+    force: bool,
+    list_agents: bool,
+) -> None:
+    """Install python-checkup skill files for AI coding agents."""
+    from rich.table import Table
+
+    from python_checkup.skills.agents import detect_installed_agents, get_agent_targets
+
+    if list_agents:
+        table = Table(title="Supported AI Coding Agents", show_header=True)
+        table.add_column("Agent", style="cyan")
+        table.add_column("Directory", style="dim")
+        table.add_column("Detected", justify="center")
+
+        all_targets = get_agent_targets()
+        detected = {t.name for t in detect_installed_agents()}
+
+        for target in all_targets:
+            is_detected = "\u2713" if target.name in detected else ""
+            if target.is_append and target.global_rules_file:
+                dir_str = f"{target.global_rules_file} (append)"
+            else:
+                dir_str = str(target.skill_dir)
+            table.add_row(target.display_name, dir_str, is_detected)
+
+        err_console.print(table)
+        return
+
+    from python_checkup.skills.installer import install_skill
+
+    agents_list = list(agent) if agent else None
+    install_skill(agents=agents_list, project_level=project, force=force)
+
+
+@main.command("uninstall-skill")
+@click.option(
+    "--agent",
+    "-a",
+    multiple=True,
+    help="Specific agent(s) to uninstall from.",
+)
+def uninstall_skill_cmd(agent: tuple[str, ...]) -> None:
+    """Remove installed python-checkup skill files."""
+    from python_checkup.skills.installer import uninstall_skill
+
+    agents_list = list(agent) if agent else None
+    uninstall_skill(agents=agents_list)