code-mower 0.5.0b5__py3-none-any.whl

code_mower/doctor_checks/providers.py

@@ -0,0 +1,159 @@
+"""Provider catalog coverage and runtime check orchestration."""
+
+from __future__ import annotations
+
+from typing import Any, Mapping
+
+from .common import (
+    DoctorCheck,
+    STATUS_FAIL,
+    STATUS_PASS,
+    STATUS_SKIP,
+    STATUS_WARN,
+    as_mapping,
+    as_sequence,
+    code_mower_config,
+)
+from .provider_api_model import check_api_model
+from .provider_env import check_required_env, check_token_env
+from .provider_local_cli import (
+    check_local_cli,
+    check_local_cli_probe,
+)
+from .provider_probe import (
+    evaluate_json_probe,
+    local_cli_probe_remediation,
+)
+
+__all__ = [
+    "check_lane_runtime",
+    "effective_lane",
+    "evaluate_json_probe",
+    "local_cli_probe_remediation",
+    "provider_template_coverage",
+    "selected_lanes",
+]
+
+
+def selected_lanes(
+    config: Mapping[str, Any],
+    profile: str | None,
+) -> tuple[str, ...]:
+    lanes = as_mapping(config.get("lanes"), "lanes")
+    if not profile:
+        return tuple(str(lane_id) for lane_id in sorted(lanes))
+    profiles = as_mapping(config.get("profiles", {}), "profiles")
+    profile_config = profiles.get(profile)
+    if not isinstance(profile_config, Mapping):
+        known = ", ".join(sorted(str(item) for item in profiles))
+        raise code_mower_config.ConfigError(
+            f"unknown profile {profile!r}; known profiles: {known}"
+        )
+    return tuple(str(lane_id) for lane_id in as_sequence(profile_config.get("lanes", [])))
+
+
+def provider_template_coverage(
+    lanes: tuple[str, ...],
+    templates: Mapping[str, Any],
+) -> DoctorCheck:
+    provider_templates = as_mapping(
+        templates.get("provider_templates"),
+        "provider_templates",
+    )
+    missing = sorted(set(lanes) - set(str(item) for item in provider_templates))
+    if missing:
+        return DoctorCheck(
+            name="provider_templates.coverage",
+            status=STATUS_FAIL,
+            message=f"provider templates missing selected lanes: {', '.join(missing)}",
+            detail={"missing_lanes": missing},
+            remediation=(
+                "Add these lane ids to the provider catalog or remove them from "
+                "the selected profile before running audits."
+            ),
+        )
+    return DoctorCheck(
+        name="provider_templates.coverage",
+        status=STATUS_PASS,
+        message="provider templates cover selected lanes",
+    )
+
+
+def _merge_mapping_defaults(
+    defaults: Mapping[str, Any],
+    overrides: Mapping[str, Any],
+) -> dict[str, Any]:
+    merged = dict(defaults)
+    merged.update(overrides)
+    return merged
+
+
+def effective_lane(
+    lane_id: str,
+    lane: Mapping[str, Any],
+    provider_templates: Mapping[str, Any],
+) -> Mapping[str, Any]:
+    template = provider_templates.get(lane_id, {})
+    if not isinstance(template, Mapping):
+        template = {}
+    merged = _merge_mapping_defaults(template, lane)
+    for key in ("labels", "provider_config", "review_hygiene"):
+        template_value = template.get(key, {})
+        lane_value = lane.get(key, {})
+        if isinstance(template_value, Mapping) and isinstance(lane_value, Mapping):
+            merged[key] = _merge_mapping_defaults(template_value, lane_value)
+    return merged
+
+
+def check_lane_runtime(
+    lane_id: str,
+    lane: Mapping[str, Any],
+    *,
+    probe_runtime: bool,
+    http_timeout: int,
+) -> list[DoctorCheck]:
+    checks = check_token_env(lane_id, lane)
+    checks.extend(check_required_env(lane_id, lane))
+    driver = str(lane.get("driver", ""))
+    if driver == "local_cli":
+        checks.append(check_local_cli(lane_id, lane))
+        checks.append(
+            check_local_cli_probe(
+                lane_id,
+                lane,
+                probe_runtime=probe_runtime,
+                http_timeout=http_timeout,
+            )
+        )
+    elif driver == "api_model":
+        checks.extend(
+            check_api_model(
+                lane_id,
+                lane,
+                probe_runtime=probe_runtime,
+                http_timeout=http_timeout,
+            )
+        )
+    elif driver in {"manual", "hosted_bridge", "saas_event"}:
+        checks.append(
+            DoctorCheck(
+                name="runtime.probe",
+                status=STATUS_SKIP,
+                lane=lane_id,
+                message=f"{driver} lanes do not have a local runtime probe yet",
+            )
+        )
+    else:
+        checks.append(
+            DoctorCheck(
+                name="runtime.probe",
+                status=STATUS_WARN,
+                lane=lane_id,
+                message=f"unknown driver {driver!r}; no runtime probe available",
+                remediation=(
+                    "Use a supported driver: local_cli, api_model, hosted_bridge, "
+                    "saas_event, or manual."
+                ),
+            )
+        )
+    return checks

code_mower/doctor_checks/registry.py

@@ -0,0 +1,69 @@
+"""Named doctor check groups and run-plan vocabulary.
+
+The public doctor surface is intentionally simple: callers receive a flat list
+of checks. Internally, doctor now has explicit groups and stages so new
+diagnostics can be added behind stable names instead of growing another large
+command adapter.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+
+@dataclass(frozen=True)
+class DoctorCheckGroup:
+    id: str
+    description: str
+
+
+@dataclass(frozen=True)
+class DoctorCheckStage:
+    id: str
+    group_id: str
+    description: str
+    optional: bool = False
+
+
+DEFAULT_CHECK_GROUPS = (
+    DoctorCheckGroup("runtime", "Python, package, and local toolchain checks"),
+    DoctorCheckGroup("github", "GitHub auth, workflow, and private-repo cost checks"),
+    DoctorCheckGroup("providers", "Reviewer provider CLI and secret checks"),
+    DoctorCheckGroup("cloud", "Optional CodeMower.com token and service checks"),
+    DoctorCheckGroup("output", "Report, JSON, and human-readable output checks"),
+)
+
+BASE_DOCTOR_STAGES = (
+    DoctorCheckStage("load-inputs", "runtime", "Load Code Mower config and provider templates"),
+    DoctorCheckStage("select-profile", "runtime", "Resolve the requested profile and lane set"),
+    DoctorCheckStage("runtime", "runtime", "Inspect Python, pytest, GitHub CLI, and ripgrep"),
+    DoctorCheckStage("providers", "providers", "Inspect selected provider lanes"),
+)
+
+OPTIONAL_DOCTOR_STAGES = (
+    DoctorCheckStage(
+        "github",
+        "github",
+        "Inspect GitHub repository metadata, branch rules, workflows, and Actions cost",
+        optional=True,
+    ),
+    DoctorCheckStage(
+        "cloud",
+        "cloud",
+        "Inspect optional CodeMower.com token setup",
+        optional=True,
+    ),
+)
+
+
+def default_check_group_ids() -> tuple[str, ...]:
+    return tuple(group.id for group in DEFAULT_CHECK_GROUPS)
+
+
+def build_doctor_run_plan(*, github: bool = False, cloud: bool = False) -> tuple[DoctorCheckStage, ...]:
+    """Return the named stages that a doctor run will execute."""
+
+    stages = list(BASE_DOCTOR_STAGES)
+    optional_flags = {"github": github, "cloud": cloud}
+    stages.extend(stage for stage in OPTIONAL_DOCTOR_STAGES if optional_flags.get(stage.id, False))
+    return tuple(stages)

code_mower/doctor_checks/runner.py

@@ -0,0 +1,188 @@
+"""Doctor report orchestration."""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Any, Mapping
+
+from code_mower import config as code_mower_config
+
+from .cloud import check_cloud_token_surface
+from .common import ACTIONS_COST_SAMPLE_DEFAULT, load_inputs
+from .github import check_github_setup
+from .models import STATUS_FAIL, STATUS_PASS, DoctorCheck, DoctorReport
+from .providers import check_lane_runtime, effective_lane, provider_template_coverage, selected_lanes
+from .registry import DoctorCheckStage, build_doctor_run_plan
+from .runtime import (
+    check_github_auth_surface,
+    check_pytest,
+    check_python_runtime,
+    check_ripgrep,
+)
+
+
+def _global_runtime_checks(
+    *,
+    probe_runtime: bool,
+    http_timeout: int,
+) -> tuple[DoctorCheck, ...]:
+    return (
+        check_python_runtime(),
+        check_pytest(),
+        check_github_auth_surface(
+            probe_runtime=probe_runtime,
+            http_timeout=http_timeout,
+        ),
+        check_ripgrep(),
+    )
+
+
+def _run_plan_check(
+    plan: tuple[DoctorCheckStage, ...],
+    *,
+    probe_runtime: bool,
+    actions_cost_sample: int,
+) -> DoctorCheck:
+    return DoctorCheck(
+        name="doctor.plan",
+        status=STATUS_PASS,
+        message="doctor run plan: " + ", ".join(stage.id for stage in plan),
+        detail={
+            "stages": [
+                {
+                    "id": stage.id,
+                    "group": stage.group_id,
+                    "optional": stage.optional,
+                }
+                for stage in plan
+            ],
+            "probe_runtime": probe_runtime,
+            "actions_cost_sample": actions_cost_sample,
+        },
+    )
+
+
+def run_doctor(
+    *,
+    config_path: Path,
+    provider_templates_path: Path,
+    profile: str | None,
+    probe_runtime: bool = False,
+    github: bool = False,
+    cloud: bool = False,
+    http_timeout: int = 5,
+    actions_cost_sample: int = ACTIONS_COST_SAMPLE_DEFAULT,
+) -> DoctorReport:
+    plan = build_doctor_run_plan(github=github, cloud=cloud)
+    enabled_stages = {stage.id for stage in plan}
+    config, templates, checks = load_inputs(config_path, provider_templates_path)
+    checks.append(
+        _run_plan_check(
+            plan,
+            probe_runtime=probe_runtime,
+            actions_cost_sample=actions_cost_sample,
+        )
+    )
+    if config is None or templates is None:
+        return DoctorReport(
+            config_path=str(config_path),
+            provider_templates_path=str(provider_templates_path),
+            profile=profile,
+            checks=tuple(checks),
+        )
+
+    try:
+        lanes = selected_lanes(config, profile)
+    except code_mower_config.ConfigError as exc:
+        checks.append(
+            DoctorCheck(
+                name="profile.select",
+                status=STATUS_FAIL,
+                message=str(exc),
+                remediation=(
+                    "Choose an existing profile from code-mower.yml or run "
+                    "`code-mower init --easy` to inspect the recommended profile."
+                ),
+            )
+        )
+        return DoctorReport(
+            config_path=str(config_path),
+            provider_templates_path=str(provider_templates_path),
+            profile=profile,
+            checks=tuple(checks),
+        )
+
+    checks.append(
+        DoctorCheck(
+            name="profile.select",
+            status=STATUS_PASS,
+            message=(
+                f"selected profile {profile}: {', '.join(lanes)}"
+                if profile
+                else f"selected all lanes: {', '.join(lanes)}"
+            ),
+            detail={"lanes": list(lanes)},
+        )
+    )
+    checks.append(provider_template_coverage(lanes, templates))
+    checks.extend(
+        _global_runtime_checks(
+            probe_runtime=probe_runtime,
+            http_timeout=http_timeout,
+        )
+    )
+
+    lane_configs = config.get("lanes")
+    if not isinstance(lane_configs, Mapping):
+        raise code_mower_config.ConfigError("lanes must be a mapping")
+    provider_templates = templates.get("provider_templates")
+    if not isinstance(provider_templates, Mapping):
+        raise code_mower_config.ConfigError("provider_templates must be a mapping")
+
+    effective_lanes: list[tuple[str, Mapping[str, Any]]] = []
+    for lane_id in lanes:
+        lane = lane_configs.get(lane_id)
+        if not isinstance(lane, Mapping):
+            checks.append(
+                DoctorCheck(
+                    name="lane.load",
+                    status=STATUS_FAIL,
+                    lane=lane_id,
+                    message="selected lane is missing from config",
+                    remediation=(
+                        "Add the lane to code-mower.yml or remove it from the "
+                        "selected profile."
+                    ),
+                )
+            )
+            continue
+        effective = effective_lane(lane_id, lane, provider_templates)
+        effective_lanes.append((lane_id, effective))
+        checks.extend(
+            check_lane_runtime(
+                lane_id,
+                effective,
+                probe_runtime=probe_runtime,
+                http_timeout=http_timeout,
+            )
+        )
+
+    if "github" in enabled_stages:
+        checks.extend(
+            check_github_setup(
+                config=config,
+                lanes=effective_lanes,
+                http_timeout=http_timeout,
+                actions_cost_sample=actions_cost_sample,
+            )
+        )
+
+    if "cloud" in enabled_stages:
+        checks.append(check_cloud_token_surface())
+
+    return DoctorReport(
+        config_path=str(config_path),
+        provider_templates_path=str(provider_templates_path),
+        profile=profile,
+        checks=tuple(checks),
+    )

code_mower/doctor_checks/runtime.py

@@ -0,0 +1,89 @@
+"""Runtime and local toolchain doctor checks."""
+
+from __future__ import annotations
+
+import importlib.util
+import shutil
+import sys
+
+from .models import STATUS_FAIL, STATUS_PASS, STATUS_WARN, DoctorCheck
+from .privacy import auth_probe_output_detail
+from .runtime_github_auth import check_github_auth_surface
+
+__all__ = (
+    "auth_probe_output_detail",
+    "check_github_auth_surface",
+    "check_pytest",
+    "check_python_runtime",
+    "check_ripgrep",
+)
+
+
+def check_python_runtime() -> DoctorCheck:
+    version = ".".join(str(part) for part in sys.version_info[:3])
+    status = STATUS_PASS if sys.version_info >= (3, 11) else STATUS_FAIL
+    return DoctorCheck(
+        name="runtime.python",
+        status=status,
+        message=(
+            f"Python {version} satisfies Code Mower's >=3.11 requirement"
+            if status == STATUS_PASS
+            else f"Python {version} is too old; Code Mower requires >=3.11"
+        ),
+        detail={
+            "executable": sys.executable,
+            "version": version,
+            "required": ">=3.11",
+        },
+        remediation=(
+            None
+            if status == STATUS_PASS
+            else "Run Code Mower with Python >=3.11, then rerun doctor."
+        ),
+    )
+
+
+def check_ripgrep() -> DoctorCheck:
+    path = shutil.which("rg")
+    if path:
+        return DoctorCheck(
+            name="runtime.ripgrep",
+            status=STATUS_PASS,
+            message="rg found",
+            detail={"command": "rg", "path": path},
+        )
+    return DoctorCheck(
+        name="runtime.ripgrep",
+        status=STATUS_WARN,
+        message="rg was not found; reviewer CLIs may fall back to slower grep tools",
+        detail={"command": "rg"},
+        remediation=(
+            "Install ripgrep, for example `brew install ripgrep` on macOS or "
+            "`apt-get install ripgrep` on Ubuntu, and ensure rg is on PATH."
+        ),
+    )
+
+
+def check_pytest() -> DoctorCheck:
+    spec = importlib.util.find_spec("pytest")
+    if spec is not None:
+        return DoctorCheck(
+            name="runtime.pytest",
+            status=STATUS_PASS,
+            message="pytest import is available for product-side test wrappers",
+            detail={"module": "pytest"},
+        )
+    return DoctorCheck(
+        name="runtime.pytest",
+        status=STATUS_WARN,
+        message=(
+            "pytest is not installed in this Python environment; standalone "
+            "easy-mode does not require it, but product-side Code Mower test "
+            "wrappers often do"
+        ),
+        detail={"module": "pytest"},
+        remediation=(
+            "Install pytest in the product repository virtualenv before running "
+            "product-side wrapper tests, for example `python -m pip install pytest`."
+        ),
+    )

code_mower/doctor_checks/runtime_github_auth.py

@@ -0,0 +1,148 @@
+"""GitHub CLI/token auth doctor probe."""
+
+from __future__ import annotations
+
+import os
+import shutil
+import subprocess
+
+from .models import STATUS_PASS, STATUS_WARN, DoctorCheck
+from .privacy import auth_probe_output_detail
+
+
+def _github_auth_probe(
+    gh_path: str,
+    *,
+    http_timeout: int,
+) -> tuple[int | None, str, str | None]:
+    try:
+        completed = subprocess.run(
+            [gh_path, "auth", "status"],
+            capture_output=True,
+            text=True,
+            check=False,
+            timeout=http_timeout,
+        )
+    except (OSError, subprocess.TimeoutExpired) as exc:
+        return None, "", str(exc)
+    output = (completed.stdout or completed.stderr or "").strip()
+    return completed.returncode, output, None
+
+
+def _github_auth_probe_check(
+    *,
+    token_env: list[str],
+    gh_path: str,
+    http_timeout: int,
+) -> DoctorCheck:
+    returncode, output, error = _github_auth_probe(
+        gh_path,
+        http_timeout=http_timeout,
+    )
+    if error is not None:
+        qualifier = "token env is set, but " if token_env else ""
+        return DoctorCheck(
+            name="runtime.github_auth",
+            status=STATUS_WARN,
+            message=f"GitHub {qualifier}auth probe failed: {error}",
+            detail={"token_env": token_env, "gh_path": gh_path},
+            remediation=(
+                "Run `gh auth status` locally, refresh the token if needed, "
+                "or export a valid GITHUB_TOKEN/GH_TOKEN."
+                if token_env
+                else "Run `gh auth login` or export GITHUB_TOKEN/GH_TOKEN, "
+                "then rerun doctor."
+            ),
+        )
+    if returncode == 0:
+        message = (
+            "GitHub token env and CLI auth probe are valid"
+            if token_env
+            else "GitHub CLI auth probe succeeded"
+        )
+        return DoctorCheck(
+            name="runtime.github_auth",
+            status=STATUS_PASS,
+            message=message,
+            detail={
+                "token_env": token_env,
+                "gh_path": gh_path,
+                "returncode": returncode,
+                **auth_probe_output_detail(output),
+            },
+        )
+    message = (
+        f"GitHub token env is set, but auth probe exited {returncode}"
+        if token_env
+        else f"GitHub CLI auth probe exited {returncode}"
+    )
+    return DoctorCheck(
+        name="runtime.github_auth",
+        status=STATUS_WARN,
+        message=message,
+        detail={
+            "token_env": token_env,
+            "gh_path": gh_path,
+            "returncode": returncode,
+            **auth_probe_output_detail(output),
+        },
+        remediation=(
+            "Run `gh auth status`, refresh CLI auth with `gh auth login`, "
+            "or export a valid GITHUB_TOKEN/GH_TOKEN."
+            if token_env
+            else "Run `gh auth login` or export GITHUB_TOKEN/GH_TOKEN, "
+            "then rerun doctor."
+        ),
+    )
+
+
+def check_github_auth_surface(
+    *,
+    probe_runtime: bool,
+    http_timeout: int,
+) -> DoctorCheck:
+    token_env = [name for name in ("GITHUB_TOKEN", "GH_TOKEN") if os.environ.get(name)]
+    gh_path = shutil.which("gh")
+    if token_env:
+        if probe_runtime and gh_path:
+            return _github_auth_probe_check(
+                token_env=token_env,
+                gh_path=gh_path,
+                http_timeout=http_timeout,
+            )
+        return DoctorCheck(
+            name="runtime.github_auth",
+            status=STATUS_PASS,
+            message="GitHub token env is set",
+            detail={"token_env": token_env, "gh_path": gh_path or ""},
+        )
+    if gh_path:
+        if probe_runtime:
+            return _github_auth_probe_check(
+                token_env=[],
+                gh_path=gh_path,
+                http_timeout=http_timeout,
+            )
+        return DoctorCheck(
+            name="runtime.github_auth",
+            status=STATUS_WARN,
+            message="GitHub CLI is available, but token env is not set and auth was not probed",
+            detail={"token_env": [], "gh_path": gh_path},
+            remediation=(
+                "Run with --probe-runtime to verify gh auth, or export "
+                "GITHUB_TOKEN/GH_TOKEN before enabling GitHub-backed lanes."
+            ),
+        )
+    return DoctorCheck(
+        name="runtime.github_auth",
+        status=STATUS_WARN,
+        message="neither GITHUB_TOKEN/GH_TOKEN nor gh CLI was found",
+        detail={"token_env": [], "gh_path": ""},
+        remediation=(
+            "Install the GitHub CLI and run `gh auth login`, or export "
+            "GITHUB_TOKEN/GH_TOKEN."
+        ),
+    )
+
+
+__all__ = ("check_github_auth_surface",)