code-mower 0.5.0b5__py3-none-any.whl

code_mower/doctor_checks/github_actions_failures.py

@@ -0,0 +1,103 @@
+"""GitHub Actions failure and billing-block diagnostics."""
+
+from __future__ import annotations
+
+from .common import DoctorCheck, STATUS_PASS, STATUS_WARN
+from .github_actions_failure_annotations import (
+    _annotation_mentions_actions_billing_block,
+    _check_run_id_from_actions_job,
+)
+from .github_actions_failure_scan import (
+    inspect_recent_actions_failures,
+)
+
+
+def _check_recent_actions_billing_blocks(
+    *,
+    gh_path: str,
+    slug: str,
+    http_timeout: int,
+) -> DoctorCheck:
+    inspection = inspect_recent_actions_failures(
+        gh_path=gh_path,
+        slug=slug,
+        http_timeout=http_timeout,
+    )
+    if inspection.unavailable_detail is not None:
+        return DoctorCheck(
+            name="github.actions.recent_failures",
+            status=STATUS_WARN,
+            message=f"could not inspect recent GitHub Actions runs for {slug}",
+            detail={"repo": slug, **inspection.unavailable_detail},
+            remediation=(
+                "Verify gh auth can read Actions run metadata, then rerun "
+                "`code-mower doctor --github`."
+            ),
+        )
+
+    if inspection.missing_workflow_runs:
+        return DoctorCheck(
+            name="github.actions.recent_failures",
+            status=STATUS_WARN,
+            message=f"recent Actions response for {slug} did not include workflow_runs",
+            detail={"repo": slug},
+        )
+
+    if inspection.has_billing_blocks:
+        return DoctorCheck(
+            name="github.actions.recent_failures",
+            status=STATUS_WARN,
+            message=(
+                f"{slug} has recent Actions jobs blocked by billing "
+                "or spending limits"
+            ),
+            detail={
+                "repo": slug,
+                "billing_block_count": len(inspection.billing_blocks),
+                "billing_blocks": [block.as_detail() for block in inspection.billing_blocks],
+                "inspected_failed_runs": inspection.inspected_failed_runs,
+                "inspected_failed_jobs": inspection.inspected_failed_jobs,
+            },
+            remediation=(
+                "Fix GitHub billing or Actions spending limits, then rerun "
+                "failed workflows before relying on branch protection or "
+                "deploy checks."
+            ),
+        )
+
+    if inspection.incomplete_inspections:
+        return DoctorCheck(
+            name="github.actions.recent_failures",
+            status=STATUS_WARN,
+            message=f"{slug} has recent failed Actions runs that doctor could not fully inspect",
+            detail={
+                "repo": slug,
+                "incomplete_inspection_count": inspection.incomplete_inspection_count,
+                "incomplete_inspections": list(inspection.incomplete_inspections[:5]),
+                "inspected_failed_runs": inspection.inspected_failed_runs,
+                "inspected_failed_jobs": inspection.inspected_failed_jobs,
+            },
+            remediation=(
+                "Verify gh auth can read workflow jobs and annotations, or inspect "
+                "recent failed Actions runs manually before treating doctor as a "
+                "green setup signal."
+            ),
+        )
+
+    return DoctorCheck(
+        name="github.actions.recent_failures",
+        status=STATUS_PASS,
+        message=f"{slug} has no recent Actions billing-block annotations",
+        detail={
+            "repo": slug,
+            "inspected_failed_runs": inspection.inspected_failed_runs,
+            "inspected_failed_jobs": inspection.inspected_failed_jobs,
+        },
+    )
+
+
+__all__ = (
+    "_annotation_mentions_actions_billing_block",
+    "_check_recent_actions_billing_blocks",
+    "_check_run_id_from_actions_job",
+)

code_mower/doctor_checks/github_actions_permissions.py

@@ -0,0 +1,55 @@
+"""GitHub Actions enablement doctor checks."""
+
+from __future__ import annotations
+
+from .common import DoctorCheck, STATUS_PASS, STATUS_WARN
+from .github_api import _github_api_json
+
+
+def check_actions_permissions(
+    *,
+    gh_path: str,
+    slug: str,
+    http_timeout: int,
+) -> DoctorCheck:
+    actions_payload, actions_detail = _github_api_json(
+        gh_path,
+        f"repos/{slug}/actions/permissions",
+        http_timeout=http_timeout,
+    )
+    if actions_payload is None:
+        return DoctorCheck(
+            name="github.actions.permissions",
+            status=STATUS_WARN,
+            message=f"could not inspect GitHub Actions permissions for {slug}",
+            detail={"repo": slug, **actions_detail},
+            remediation=(
+                "A repo admin should verify Actions are enabled and workflow "
+                "token permissions can write issues/labels or that PAT "
+                "fallback secrets are configured."
+            ),
+        )
+
+    enabled = bool(actions_payload.get("enabled"))
+    return DoctorCheck(
+        name="github.actions.permissions",
+        status=STATUS_PASS if enabled else STATUS_WARN,
+        message=(
+            f"{slug} GitHub Actions are enabled and inspectable"
+            if enabled
+            else f"{slug} GitHub Actions appear disabled"
+        ),
+        detail={
+            "repo": slug,
+            "enabled": enabled,
+            "allowed_actions": str(actions_payload.get("allowed_actions") or ""),
+        },
+        remediation=(
+            None
+            if enabled
+            else (
+                "Enable GitHub Actions for this repository before expecting "
+                "Code Mower labelers or audit workflows to run."
+            )
+        ),
+    )

code_mower/doctor_checks/github_api.py

@@ -0,0 +1,79 @@
+"""Redacted GitHub API helpers for doctor checks."""
+
+from __future__ import annotations
+
+import json
+import subprocess
+from typing import Any, Mapping
+
+from .privacy import auth_probe_output_detail
+
+
+def _github_api_payload(
+    gh_path: str,
+    endpoint: str,
+    *,
+    http_timeout: int,
+) -> tuple[Any | None, dict[str, Any]]:
+    try:
+        completed = subprocess.run(
+            [gh_path, "api", endpoint],
+            capture_output=True,
+            text=True,
+            check=False,
+            timeout=http_timeout,
+        )
+    except (OSError, subprocess.TimeoutExpired) as exc:
+        return None, {"error_type": exc.__class__.__name__}
+    output = (completed.stdout or completed.stderr or "").strip()
+    detail: dict[str, Any] = {
+        "endpoint": endpoint,
+        "returncode": completed.returncode,
+        **auth_probe_output_detail(output),
+    }
+    if completed.returncode != 0:
+        return None, detail
+    try:
+        payload = json.loads(completed.stdout or "{}")
+    except json.JSONDecodeError:
+        detail["parse_error"] = "json"
+        return None, detail
+    return payload, detail
+
+
+def _github_api_json(
+    gh_path: str,
+    endpoint: str,
+    *,
+    http_timeout: int,
+) -> tuple[Mapping[str, Any] | None, dict[str, Any]]:
+    payload, detail = _github_api_payload(
+        gh_path,
+        endpoint,
+        http_timeout=http_timeout,
+    )
+    if payload is None:
+        return None, detail
+    if not isinstance(payload, Mapping):
+        detail["parse_error"] = "not_object"
+        return None, detail
+    return payload, detail
+
+
+def _github_api_list(
+    gh_path: str,
+    endpoint: str,
+    *,
+    http_timeout: int,
+) -> tuple[list[Any] | None, dict[str, Any]]:
+    payload, detail = _github_api_payload(
+        gh_path,
+        endpoint,
+        http_timeout=http_timeout,
+    )
+    if payload is None:
+        return None, detail
+    if not isinstance(payload, list):
+        detail["parse_error"] = "not_list"
+        return None, detail
+    return payload, detail

code_mower/doctor_checks/github_branch.py

@@ -0,0 +1,56 @@
+"""GitHub branch protection doctor checks."""
+
+from __future__ import annotations
+
+import urllib.parse
+from typing import Mapping
+
+from .common import DoctorCheck, STATUS_PASS, STATUS_WARN
+from .github_api import _github_api_json
+
+
+def check_branch_protection(
+    *,
+    gh_path: str,
+    slug: str,
+    default_branch: str,
+    http_timeout: int,
+) -> DoctorCheck:
+    encoded_branch = urllib.parse.quote(default_branch, safe="")
+    protection_payload, protection_detail = _github_api_json(
+        gh_path,
+        f"repos/{slug}/branches/{encoded_branch}/protection",
+        http_timeout=http_timeout,
+    )
+    if protection_payload is None:
+        return DoctorCheck(
+            name="github.branch_protection",
+            status=STATUS_WARN,
+            message=f"could not confirm branch protection for {slug}@{default_branch}",
+            detail={
+                "repo": slug,
+                "default_branch": default_branch,
+                **protection_detail,
+            },
+            remediation=(
+                "Before enabling autonomous merge, protect the default branch "
+                "and make required checks explicit."
+            ),
+        )
+
+    required_checks = protection_payload.get("required_status_checks")
+    contexts: list[str] = []
+    if isinstance(required_checks, Mapping):
+        raw_contexts = required_checks.get("contexts")
+        if isinstance(raw_contexts, list):
+            contexts = [str(item) for item in raw_contexts]
+    return DoctorCheck(
+        name="github.branch_protection",
+        status=STATUS_PASS,
+        message=f"{slug}@{default_branch} branch protection is inspectable",
+        detail={
+            "repo": slug,
+            "default_branch": default_branch,
+            "required_status_check_count": len(contexts),
+        },
+    )

code_mower/doctor_checks/github_config.py

@@ -0,0 +1,25 @@
+"""GitHub doctor configuration helpers."""
+
+from __future__ import annotations
+
+from typing import Any, Mapping, Sequence
+
+from .common import as_sequence
+
+
+def configured_repositories(config: Mapping[str, Any]) -> tuple[Mapping[str, Any], ...]:
+    repos: list[Mapping[str, Any]] = []
+    for repo in as_sequence(config.get("repositories", [])):
+        if isinstance(repo, Mapping) and repo.get("slug"):
+            repos.append(repo)
+    return tuple(repos)
+
+
+def selected_saas_or_hosted_lanes(
+    lanes: Sequence[tuple[str, Mapping[str, Any]]],
+) -> list[str]:
+    selected: list[str] = []
+    for lane_id, lane in lanes:
+        if str(lane.get("driver", "")) in {"saas_event", "hosted_bridge"}:
+            selected.append(lane_id)
+    return selected

code_mower/doctor_checks/github_provider.py

@@ -0,0 +1,61 @@
+"""Hosted-provider GitHub repository compatibility checks."""
+
+from __future__ import annotations
+
+from collections.abc import Sequence
+
+from .common import DoctorCheck, STATUS_PASS, STATUS_WARN
+
+
+def check_private_repo_provider_surface(
+    *,
+    private_repos: Sequence[str],
+    unknown_visibility_repos: Sequence[str],
+    selected_saas_or_hosted: Sequence[str],
+) -> DoctorCheck | None:
+    if private_repos and selected_saas_or_hosted:
+        return DoctorCheck(
+            name="github.provider.private_repo",
+            status=STATUS_WARN,
+            message=(
+                "private repos selected with SaaS/hosted lanes: "
+                + ", ".join(selected_saas_or_hosted)
+            ),
+            detail={
+                "private_repo_count": len(private_repos),
+                "lanes": list(selected_saas_or_hosted),
+            },
+            remediation=(
+                "Install each provider's GitHub App for the selected private "
+                "repositories, confirm plan support, and decide whether sending "
+                "diffs/source to that provider is acceptable."
+            ),
+        )
+
+    if unknown_visibility_repos and selected_saas_or_hosted:
+        return DoctorCheck(
+            name="github.provider.private_repo",
+            status=STATUS_WARN,
+            message=(
+                "could not determine repository visibility for SaaS/hosted lanes: "
+                + ", ".join(selected_saas_or_hosted)
+            ),
+            detail={
+                "unknown_repo_count": len(unknown_visibility_repos),
+                "lanes": list(selected_saas_or_hosted),
+            },
+            remediation=(
+                "Verify gh auth can read repository metadata before deciding "
+                "whether hosted provider apps need private-repo access."
+            ),
+        )
+
+    if selected_saas_or_hosted:
+        return DoctorCheck(
+            name="github.provider.private_repo",
+            status=STATUS_PASS,
+            message="selected SaaS/hosted lanes have no private repos in config",
+            detail={"lanes": list(selected_saas_or_hosted)},
+        )
+
+    return None

code_mower/doctor_checks/github_repo.py

@@ -0,0 +1,120 @@
+"""GitHub repository metadata and permission doctor checks."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Any, Mapping
+
+from .common import DoctorCheck, STATUS_PASS, STATUS_WARN
+from .github_api import _github_api_json
+
+
+@dataclass(frozen=True)
+class GitHubRepoMetadata:
+    slug: str
+    is_private: bool
+    default_branch: str
+    payload: Mapping[str, Any]
+
+
+def check_repo_metadata(
+    *,
+    gh_path: str,
+    slug: str,
+    configured_default_branch: str,
+    http_timeout: int,
+) -> tuple[DoctorCheck, GitHubRepoMetadata | None]:
+    repo_payload, repo_detail = _github_api_json(
+        gh_path,
+        f"repos/{slug}",
+        http_timeout=http_timeout,
+    )
+    if repo_payload is None:
+        return (
+            DoctorCheck(
+                name="github.repo.metadata",
+                status=STATUS_WARN,
+                message=f"could not read GitHub repository metadata for {slug}",
+                detail={"repo": slug, **repo_detail},
+                remediation=(
+                    "Verify gh auth can read this repo. Private repos need "
+                    "a token or GitHub App installation with repository access."
+                ),
+            ),
+            None,
+        )
+
+    is_private = bool(repo_payload.get("private"))
+    default_branch = str(
+        repo_payload.get("default_branch") or configured_default_branch or "main"
+    )
+    return (
+        DoctorCheck(
+            name="github.repo.metadata",
+            status=STATUS_PASS,
+            message=(
+                f"{slug} is reachable "
+                f"({'private' if is_private else 'public'} repository)"
+            ),
+            detail={
+                "repo": slug,
+                "private": is_private,
+                "visibility": str(repo_payload.get("visibility") or ""),
+                "default_branch": str(repo_payload.get("default_branch") or ""),
+                "archived": bool(repo_payload.get("archived")),
+                "fork": bool(repo_payload.get("fork")),
+            },
+        ),
+        GitHubRepoMetadata(
+            slug=slug,
+            is_private=is_private,
+            default_branch=default_branch,
+            payload=repo_payload,
+        ),
+    )
+
+
+def check_repo_permissions(*, slug: str, repo_payload: Mapping[str, Any]) -> DoctorCheck:
+    permissions = repo_payload.get("permissions")
+    if isinstance(permissions, Mapping):
+        write_like = any(
+            bool(permissions.get(name))
+            for name in ("admin", "maintain", "push", "triage")
+        )
+        return DoctorCheck(
+            name="github.repo.permissions",
+            status=STATUS_PASS if write_like else STATUS_WARN,
+            message=(
+                f"{slug} token has repository write-adjacent permission"
+                if write_like
+                else f"{slug} token appears read-only for repository metadata"
+            ),
+            detail={
+                "repo": slug,
+                "admin": bool(permissions.get("admin")),
+                "maintain": bool(permissions.get("maintain")),
+                "push": bool(permissions.get("push")),
+                "triage": bool(permissions.get("triage")),
+                "pull": bool(permissions.get("pull")),
+            },
+            remediation=(
+                None
+                if write_like
+                else (
+                    "Configure a fine-grained PAT or GitHub App token with "
+                    "Issues read/write and Pull requests read before expecting "
+                    "Code Mower to apply labels or comments."
+                )
+            ),
+        )
+
+    return DoctorCheck(
+        name="github.repo.permissions",
+        status=STATUS_WARN,
+        message=f"{slug} metadata did not include token permissions",
+        detail={"repo": slug},
+        remediation=(
+            "If label writes fail, configure the lane token secrets "
+            "documented by the provider matrix."
+        ),
+    )

code_mower/doctor_checks/groups.py

@@ -0,0 +1,36 @@
+"""Doctor check grouping helpers shared by JSON and text output."""
+
+from __future__ import annotations
+
+from collections import OrderedDict
+
+
+GROUP_LABELS = OrderedDict(
+    (
+        ("setup", "Setup"),
+        ("runtime", "Runtime"),
+        ("providers", "Provider lanes"),
+        ("github", "GitHub"),
+        ("cloud", "Code Mower Cloud"),
+        ("output", "Output"),
+        ("other", "Other"),
+    )
+)
+
+
+def doctor_check_group_id(name: str, lane: str | None = None) -> str:
+    """Return the stable reporting group for a doctor check name."""
+
+    if name.startswith("github."):
+        return "github"
+    if name.startswith("cloud."):
+        return "cloud"
+    if name.startswith("output."):
+        return "output"
+    if lane or name.startswith(("env.", "provider.", "runtime.local_cli")):
+        return "providers"
+    if name.startswith("runtime."):
+        return "runtime"
+    if name.startswith(("config.", "provider_templates.", "profile.", "doctor.")):
+        return "setup"
+    return "other"

code_mower/doctor_checks/models.py

@@ -0,0 +1,96 @@
+"""Structured doctor check results."""
+
+from __future__ import annotations
+
+from dataclasses import asdict, dataclass
+from typing import Any, Mapping
+
+from .groups import GROUP_LABELS, doctor_check_group_id
+
+
+STATUS_PASS = "pass"
+STATUS_WARN = "warn"
+STATUS_FAIL = "fail"
+STATUS_SKIP = "skip"
+
+
+@dataclass(frozen=True)
+class DoctorCheck:
+    name: str
+    status: str
+    message: str
+    lane: str | None = None
+    detail: Mapping[str, Any] | None = None
+    remediation: str | None = None
+
+    def as_dict(self) -> dict[str, Any]:
+        data = asdict(self)
+        if self.detail is None:
+            data.pop("detail")
+        if self.lane is None:
+            data.pop("lane")
+        if self.remediation is None:
+            data.pop("remediation")
+        return data
+
+
+@dataclass(frozen=True)
+class DoctorReport:
+    config_path: str
+    provider_templates_path: str
+    profile: str | None
+    checks: tuple[DoctorCheck, ...]
+
+    @property
+    def failures(self) -> int:
+        return sum(1 for check in self.checks if check.status == STATUS_FAIL)
+
+    @property
+    def warnings(self) -> int:
+        return sum(1 for check in self.checks if check.status == STATUS_WARN)
+
+    @property
+    def status(self) -> str:
+        if self.failures:
+            return STATUS_FAIL
+        if self.warnings:
+            return STATUS_WARN
+        return STATUS_PASS
+
+    def group_summary(self) -> dict[str, dict[str, int | str]]:
+        summary: dict[str, dict[str, int | str]] = {}
+        for group_id, label in GROUP_LABELS.items():
+            group_checks = [
+                check
+                for check in self.checks
+                if doctor_check_group_id(check.name, check.lane) == group_id
+            ]
+            if not group_checks:
+                continue
+            failures = sum(1 for check in group_checks if check.status == STATUS_FAIL)
+            warnings = sum(1 for check in group_checks if check.status == STATUS_WARN)
+            skipped = sum(1 for check in group_checks if check.status == STATUS_SKIP)
+            summary[group_id] = {
+                "label": label,
+                "checks": len(group_checks),
+                "failures": failures,
+                "warnings": warnings,
+                "skipped": skipped,
+            }
+        return summary
+
+    def as_dict(self) -> dict[str, Any]:
+        return {
+            "mode": "doctor",
+            "status": self.status,
+            "profile": self.profile,
+            "config_path": self.config_path,
+            "provider_templates_path": self.provider_templates_path,
+            "summary": {
+                "checks": len(self.checks),
+                "failures": self.failures,
+                "warnings": self.warnings,
+            },
+            "groups": self.group_summary(),
+            "checks": [check.as_dict() for check in self.checks],
+        }