code-mower 0.5.0b5__py3-none-any.whl

code_mower/doctor_checks/github.py

@@ -0,0 +1,128 @@
+"""GitHub auth, repository, and Actions cost diagnostics facade."""
+
+from __future__ import annotations
+
+import shutil
+from typing import Any, Mapping, Sequence
+
+from .common import (
+    ACTIONS_COST_SAMPLE_DEFAULT,
+    DoctorCheck,
+    STATUS_PASS,
+    STATUS_WARN,
+)
+from .github_actions import (
+    _check_actions_cost_sample,
+    _check_recent_actions_billing_blocks,
+)
+from .github_actions_permissions import check_actions_permissions
+from .github_branch import check_branch_protection
+from .github_config import configured_repositories, selected_saas_or_hosted_lanes
+from .github_provider import check_private_repo_provider_surface
+from .github_repo import check_repo_metadata, check_repo_permissions
+
+
+def check_github_setup(
+    *,
+    config: Mapping[str, Any],
+    lanes: Sequence[tuple[str, Mapping[str, Any]]],
+    http_timeout: int,
+    actions_cost_sample: int = ACTIONS_COST_SAMPLE_DEFAULT,
+) -> list[DoctorCheck]:
+    checks: list[DoctorCheck] = []
+    gh_path = shutil.which("gh")
+    if not gh_path:
+        return [
+            DoctorCheck(
+                name="github.cli",
+                status=STATUS_WARN,
+                message="GitHub setup checks require the gh CLI",
+                detail={"gh_path": ""},
+                remediation=(
+                    "Install GitHub CLI, run `gh auth login`, then rerun "
+                    "`code-mower doctor --github`."
+                ),
+            )
+        ]
+
+    checks.append(
+        DoctorCheck(
+            name="github.cli",
+            status=STATUS_PASS,
+            message="gh found for GitHub setup checks",
+            detail={"gh_path": gh_path},
+        )
+    )
+
+    repos = configured_repositories(config)
+    if not repos:
+        checks.append(
+            DoctorCheck(
+                name="github.repositories",
+                status=STATUS_WARN,
+                message="config declares no repositories for GitHub setup checks",
+                remediation=(
+                    "Add repositories[].slug entries to code-mower.yml before "
+                    "running GitHub-backed audits."
+                ),
+            )
+        )
+        return checks
+
+    selected_saas_or_hosted = selected_saas_or_hosted_lanes(lanes)
+    private_repos: list[str] = []
+    unknown_visibility_repos: list[str] = []
+    for repo in repos:
+        slug = str(repo.get("slug") or "")
+        metadata_check, metadata = check_repo_metadata(
+            gh_path=gh_path,
+            slug=slug,
+            configured_default_branch=str(repo.get("default_branch") or "main"),
+            http_timeout=http_timeout,
+        )
+        checks.append(metadata_check)
+        if metadata is None:
+            unknown_visibility_repos.append(slug)
+            continue
+
+        if metadata.is_private:
+            private_repos.append(slug)
+
+        checks.extend(
+            [
+                check_repo_permissions(slug=slug, repo_payload=metadata.payload),
+                check_actions_permissions(
+                    gh_path=gh_path,
+                    slug=slug,
+                    http_timeout=http_timeout,
+                ),
+                _check_recent_actions_billing_blocks(
+                    gh_path=gh_path,
+                    slug=slug,
+                    http_timeout=http_timeout,
+                ),
+                _check_actions_cost_sample(
+                    gh_path=gh_path,
+                    slug=slug,
+                    private=metadata.is_private,
+                    http_timeout=http_timeout,
+                    sample_limit=actions_cost_sample,
+                ),
+                check_branch_protection(
+                    gh_path=gh_path,
+                    slug=slug,
+                    default_branch=metadata.default_branch,
+                    http_timeout=http_timeout,
+                ),
+            ]
+        )
+
+    provider_check = check_private_repo_provider_surface(
+        private_repos=private_repos,
+        unknown_visibility_repos=unknown_visibility_repos,
+        selected_saas_or_hosted=selected_saas_or_hosted,
+    )
+    if provider_check is not None:
+        checks.append(provider_check)
+
+    return checks

code_mower/doctor_checks/github_actions.py

@@ -0,0 +1,11 @@
+"""GitHub Actions diagnostics compatibility facade."""
+
+from __future__ import annotations
+
+from .github_actions_cost import _check_actions_cost_sample
+from .github_actions_failures import _check_recent_actions_billing_blocks
+
+__all__ = (
+    "_check_actions_cost_sample",
+    "_check_recent_actions_billing_blocks",
+)

code_mower/doctor_checks/github_actions_cost.py

@@ -0,0 +1,99 @@
+"""GitHub Actions private-repo cost heuristics."""
+
+from __future__ import annotations
+
+from .common import (
+    ACTIONS_COST_SAMPLE_MAX,
+    DoctorCheck,
+    STATUS_PASS,
+    STATUS_WARN,
+)
+from .github_api import _github_api_json
+from .github_actions_cost_summary import summarize_actions_cost_runs
+
+
+def _check_actions_cost_sample(
+    *,
+    gh_path: str,
+    slug: str,
+    private: bool,
+    http_timeout: int,
+    sample_limit: int,
+) -> DoctorCheck:
+    bounded_limit = max(1, min(sample_limit, ACTIONS_COST_SAMPLE_MAX))
+    runs_payload, runs_detail = _github_api_json(
+        gh_path,
+        f"repos/{slug}/actions/runs?per_page={bounded_limit}",
+        http_timeout=http_timeout,
+    )
+    if runs_payload is None:
+        return DoctorCheck(
+            name="github.actions.cost_sample",
+            status=STATUS_WARN,
+            message=f"could not sample recent GitHub Actions usage for {slug}",
+            detail={"repo": slug, **runs_detail},
+            remediation=(
+                "Verify gh auth can read Actions run metadata. Private repos "
+                "should periodically inspect Actions usage metrics after enabling "
+                "hosted or informational lanes."
+            ),
+        )
+
+    raw_runs = runs_payload.get("workflow_runs")
+    if not isinstance(raw_runs, list):
+        return DoctorCheck(
+            name="github.actions.cost_sample",
+            status=STATUS_WARN,
+            message=f"Actions usage response for {slug} did not include workflow_runs",
+            detail={"repo": slug},
+        )
+
+    detail = summarize_actions_cost_runs(
+        raw_runs,
+        slug=slug,
+        private=private,
+        bounded_limit=bounded_limit,
+    )
+    sample_size = int(detail["sampled_runs"])
+    metadata_run_count = int(detail["metadata_workflow_runs"])
+    schedule_runs = int(detail["schedule_runs"])
+    if not sample_size:
+        return DoctorCheck(
+            name="github.actions.cost_sample",
+            status=STATUS_PASS,
+            message=f"{slug} has no recent Actions runs in the sampled window",
+            detail=detail,
+        )
+
+    noisy_metadata = private and metadata_run_count >= max(5, int(sample_size * 0.2))
+    scheduled_private = private and schedule_runs > 0
+    if noisy_metadata or scheduled_private:
+        reasons: list[str] = []
+        if noisy_metadata:
+            reasons.append(
+                f"{metadata_run_count}/{sample_size} sampled runs look like "
+                "metadata or reviewer labeler workflows"
+            )
+        if scheduled_private:
+            reasons.append(f"{schedule_runs} sampled runs were scheduled")
+        return DoctorCheck(
+            name="github.actions.cost_sample",
+            status=STATUS_WARN,
+            message=(
+                f"{slug} private-repo Actions sample suggests avoidable spend: "
+                f"{'; '.join(reasons)}"
+            ),
+            detail=detail,
+            remediation=(
+                "Prefer label, trusted-comment, or workflow_dispatch triggers for "
+                "optional hosted reviewers; add job-level if guards before checkout; "
+                "keep informational lanes out of branch protection."
+            ),
+        )
+
+    return DoctorCheck(
+        name="github.actions.cost_sample",
+        status=STATUS_PASS,
+        message=f"{slug} recent Actions sample has no obvious private-repo cost traps",
+        detail=detail,
+    )

code_mower/doctor_checks/github_actions_cost_summary.py

@@ -0,0 +1,111 @@
+"""Summarize recent GitHub Actions runs for private-repo cost diagnostics."""
+
+from __future__ import annotations
+
+from collections import Counter, defaultdict
+from datetime import datetime, timezone
+from typing import Any, Mapping
+
+from .common import ACTIONS_METADATA_WORKFLOW_MARKERS
+
+
+def _parse_github_timestamp(value: Any) -> datetime | None:
+    if not value:
+        return None
+    try:
+        text = str(value)
+        if text.endswith("Z"):
+            text = text[:-1] + "+00:00"
+        return datetime.fromisoformat(text).astimezone(timezone.utc)
+    except ValueError:
+        return None
+
+
+def _approx_run_seconds(run: Mapping[str, Any]) -> float:
+    started = _parse_github_timestamp(
+        run.get("run_started_at") or run.get("created_at")
+    )
+    updated = _parse_github_timestamp(run.get("updated_at"))
+    if started is None or updated is None or updated < started:
+        return 0.0
+    return (updated - started).total_seconds()
+
+
+def _is_metadata_workflow(name: str, path: str) -> bool:
+    haystack = f"{name}\n{path}".lower()
+    return any(marker in haystack for marker in ACTIONS_METADATA_WORKFLOW_MARKERS)
+
+
+def summarize_actions_cost_runs(
+    raw_runs: list[Any],
+    *,
+    slug: str,
+    private: bool,
+    bounded_limit: int,
+) -> dict[str, Any]:
+    workflow_counts: Counter[str] = Counter()
+    event_counts: Counter[str] = Counter()
+    workflow_seconds: defaultdict[str, float] = defaultdict(float)
+    metadata_counts: Counter[str] = Counter()
+    metadata_seconds: defaultdict[str, float] = defaultdict(float)
+    schedule_runs = 0
+    total_seconds = 0.0
+
+    for run in raw_runs:
+        if not isinstance(run, Mapping):
+            continue
+        workflow_name = str(run.get("name") or run.get("display_title") or "unknown")
+        workflow_path = str(run.get("path") or "")
+        event = str(run.get("event") or "unknown")
+        seconds = _approx_run_seconds(run)
+        workflow_counts[workflow_name] += 1
+        event_counts[event] += 1
+        workflow_seconds[workflow_name] += seconds
+        total_seconds += seconds
+        if event == "schedule":
+            schedule_runs += 1
+        if _is_metadata_workflow(workflow_name, workflow_path):
+            metadata_counts[workflow_name] += 1
+            metadata_seconds[workflow_name] += seconds
+
+    sample_size = sum(workflow_counts.values())
+    metadata_run_count = sum(metadata_counts.values())
+    metadata_share = (metadata_run_count / sample_size) if sample_size else 0.0
+    return {
+        "repo": slug,
+        "private": private,
+        "sample_limit": bounded_limit,
+        "sampled_runs": sample_size,
+        "approx_total_minutes": round(total_seconds / 60, 2),
+        "metadata_workflow_runs": metadata_run_count,
+        "metadata_workflow_share": round(metadata_share, 3),
+        "schedule_runs": schedule_runs,
+        "top_workflows": [
+            {
+                "workflow": workflow,
+                "runs": count,
+                "approx_minutes": round(workflow_seconds[workflow] / 60, 2),
+            }
+            for workflow, count in workflow_counts.most_common(10)
+        ],
+        "top_metadata_workflows": [
+            {
+                "workflow": workflow,
+                "runs": count,
+                "approx_minutes": round(metadata_seconds[workflow] / 60, 2),
+            }
+            for workflow, count in metadata_counts.most_common(10)
+        ],
+        "events": [
+            {"event": event, "runs": count}
+            for event, count in event_counts.most_common(10)
+        ],
+    }
+
+
+__all__ = (
+    "_approx_run_seconds",
+    "_is_metadata_workflow",
+    "_parse_github_timestamp",
+    "summarize_actions_cost_runs",
+)

code_mower/doctor_checks/github_actions_failure_annotations.py

@@ -0,0 +1,27 @@
+"""GitHub Actions annotation parsing helpers."""
+
+from __future__ import annotations
+
+import re
+from typing import Any, Mapping
+
+from .common import ACTIONS_BILLING_BLOCK_PATTERNS
+
+
+def _annotation_mentions_actions_billing_block(message: str) -> bool:
+    lowered = message.lower()
+    return any(pattern in lowered for pattern in ACTIONS_BILLING_BLOCK_PATTERNS)
+
+
+def _check_run_id_from_actions_job(job: Mapping[str, Any]) -> Any | None:
+    check_run_url = str(job.get("check_run_url") or "")
+    match = re.search(r"/check-runs/([0-9]+)$", check_run_url)
+    if match:
+        return match.group(1)
+    return None
+
+
+__all__ = (
+    "_annotation_mentions_actions_billing_block",
+    "_check_run_id_from_actions_job",
+)

code_mower/doctor_checks/github_actions_failure_models.py

@@ -0,0 +1,47 @@
+"""Structured GitHub Actions recent-failure inspection results."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Any, Mapping
+
+
+@dataclass(frozen=True)
+class ActionsBillingBlock:
+    run_id: Any
+    workflow: str
+    head_sha: str
+    job_id: Any
+    check_run_id: str
+    job: str
+
+    def as_detail(self) -> dict[str, Any]:
+        return {
+            "run_id": self.run_id,
+            "workflow": self.workflow,
+            "head_sha": self.head_sha,
+            "job_id": self.job_id,
+            "check_run_id": self.check_run_id,
+            "job": self.job,
+        }
+
+
+@dataclass(frozen=True)
+class ActionsFailureInspection:
+    inspected_failed_runs: int = 0
+    inspected_failed_jobs: int = 0
+    billing_blocks: tuple[ActionsBillingBlock, ...] = ()
+    incomplete_inspections: tuple[dict[str, Any], ...] = ()
+    unavailable_detail: Mapping[str, Any] | None = None
+    missing_workflow_runs: bool = False
+
+    @property
+    def has_billing_blocks(self) -> bool:
+        return bool(self.billing_blocks)
+
+    @property
+    def incomplete_inspection_count(self) -> int:
+        return len(self.incomplete_inspections)
+
+
+__all__ = ("ActionsBillingBlock", "ActionsFailureInspection")

code_mower/doctor_checks/github_actions_failure_scan.py

@@ -0,0 +1,200 @@
+"""GitHub Actions recent-failure inspection helpers."""
+
+from __future__ import annotations
+
+from typing import Any, Mapping
+
+from .common import (
+    MAX_ACTIONS_FAILED_JOBS_TO_INSPECT,
+    MAX_ACTIONS_FAILED_RUNS_TO_INSPECT,
+)
+from .github_actions_failure_annotations import (
+    _annotation_mentions_actions_billing_block,
+    _check_run_id_from_actions_job,
+)
+from .github_actions_failure_models import (
+    ActionsBillingBlock,
+    ActionsFailureInspection,
+)
+from .github_actions_failure_selection import (
+    _actions_job_context,
+    _actions_run_context,
+    _incomplete_inspection_detail,
+    _is_inspectable_actions_failure,
+)
+from .github_api import _github_api_json, _github_api_list
+
+
+def _append_incomplete(
+    incomplete_inspections: list[dict[str, Any]],
+    detail: Mapping[str, Any],
+) -> None:
+    incomplete_inspections.append(dict(detail))
+
+
+def inspect_recent_actions_failures(
+    *,
+    gh_path: str,
+    slug: str,
+    http_timeout: int,
+) -> ActionsFailureInspection:
+    runs_payload, runs_detail = _github_api_json(
+        gh_path,
+        f"repos/{slug}/actions/runs?per_page=10",
+        http_timeout=http_timeout,
+    )
+    if runs_payload is None:
+        return ActionsFailureInspection(unavailable_detail=runs_detail)
+
+    raw_runs = runs_payload.get("workflow_runs")
+    if not isinstance(raw_runs, list):
+        return ActionsFailureInspection(missing_workflow_runs=True)
+
+    inspected_runs = 0
+    inspected_jobs = 0
+    billing_blocks: list[ActionsBillingBlock] = []
+    incomplete_inspections: list[dict[str, Any]] = []
+    for run in raw_runs:
+        if not _is_inspectable_actions_failure(run):
+            continue
+        if inspected_runs >= MAX_ACTIONS_FAILED_RUNS_TO_INSPECT:
+            _append_incomplete(
+                incomplete_inspections,
+                _incomplete_inspection_detail(
+                    stage="runs",
+                    reason="inspection_limit_reached",
+                    limit=MAX_ACTIONS_FAILED_RUNS_TO_INSPECT,
+                ),
+            )
+            break
+        run_context = _actions_run_context(run)
+        run_id = run_context["run_id"]
+        if run_id is None:
+            continue
+        inspected_runs += 1
+        jobs_payload, _jobs_detail = _github_api_json(
+            gh_path,
+            f"repos/{slug}/actions/runs/{run_id}/jobs?per_page=20",
+            http_timeout=http_timeout,
+        )
+        workflow = run_context["workflow"]
+        if jobs_payload is None:
+            _append_incomplete(
+                incomplete_inspections,
+                _incomplete_inspection_detail(
+                    run_id=run_id,
+                    workflow=workflow,
+                    stage="jobs",
+                ),
+            )
+            continue
+        raw_jobs = jobs_payload.get("jobs")
+        if not isinstance(raw_jobs, list):
+            _append_incomplete(
+                incomplete_inspections,
+                _incomplete_inspection_detail(
+                    run_id=run_id,
+                    workflow=workflow,
+                    stage="jobs",
+                    reason="missing_jobs",
+                ),
+            )
+            continue
+        if not raw_jobs:
+            _append_incomplete(
+                incomplete_inspections,
+                _incomplete_inspection_detail(
+                    run_id=run_id,
+                    workflow=workflow,
+                    stage="jobs",
+                    reason="no_jobs",
+                ),
+            )
+            continue
+        for job in raw_jobs:
+            if not _is_inspectable_actions_failure(job):
+                continue
+            if inspected_jobs >= MAX_ACTIONS_FAILED_JOBS_TO_INSPECT:
+                _append_incomplete(
+                    incomplete_inspections,
+                    _incomplete_inspection_detail(
+                        run_id=run_id,
+                        workflow=workflow,
+                        stage="annotations",
+                        reason="inspection_limit_reached",
+                        limit=MAX_ACTIONS_FAILED_JOBS_TO_INSPECT,
+                    ),
+                )
+                break
+            job_context = _actions_job_context(job)
+            job_id = job_context["job_id"]
+            if job_id is None:
+                continue
+            check_run_id = _check_run_id_from_actions_job(job)
+            job_name = job_context["job"]
+            if check_run_id is None:
+                _append_incomplete(
+                    incomplete_inspections,
+                    _incomplete_inspection_detail(
+                        run_id=run_id,
+                        workflow=workflow,
+                        job=job_name,
+                        stage="annotations",
+                        reason="missing_check_run_id",
+                    ),
+                )
+                continue
+            inspected_jobs += 1
+            annotations, _annotations_detail = _github_api_list(
+                gh_path,
+                f"repos/{slug}/check-runs/{check_run_id}/annotations?per_page=20",
+                http_timeout=http_timeout,
+            )
+            if annotations is None:
+                _append_incomplete(
+                    incomplete_inspections,
+                    _incomplete_inspection_detail(
+                        run_id=run_id,
+                        workflow=workflow,
+                        job_id=job_id,
+                        job=job_name,
+                        stage="annotations",
+                    ),
+                )
+                continue
+            for annotation in annotations:
+                if not isinstance(annotation, Mapping):
+                    continue
+                message = str(annotation.get("message") or "")
+                if _annotation_mentions_actions_billing_block(message):
+                    billing_blocks.append(
+                        ActionsBillingBlock(
+                            run_id=run_id,
+                            workflow=workflow,
+                            head_sha=run_context["head_sha"],
+                            job_id=job_id,
+                            check_run_id=str(check_run_id),
+                            job=job_name,
+                        )
+                    )
+                    return ActionsFailureInspection(
+                        inspected_failed_runs=inspected_runs,
+                        inspected_failed_jobs=inspected_jobs,
+                        billing_blocks=tuple(billing_blocks),
+                        incomplete_inspections=tuple(incomplete_inspections),
+                    )
+
+    return ActionsFailureInspection(
+        inspected_failed_runs=inspected_runs,
+        inspected_failed_jobs=inspected_jobs,
+        incomplete_inspections=tuple(incomplete_inspections),
+    )
+
+
+__all__ = (
+    "ActionsBillingBlock",
+    "ActionsFailureInspection",
+    "_annotation_mentions_actions_billing_block",
+    "_check_run_id_from_actions_job",
+    "inspect_recent_actions_failures",
+)

code_mower/doctor_checks/github_actions_failure_selection.py

@@ -0,0 +1,63 @@
+"""GitHub Actions failure selection and detail helpers."""
+
+from __future__ import annotations
+
+from typing import Any, Mapping
+
+from .common import ACTIONS_INSPECTABLE_FAILURE_CONCLUSIONS
+
+
+def _is_inspectable_actions_failure(record: Any) -> bool:
+    return (
+        isinstance(record, Mapping)
+        and record.get("conclusion") in ACTIONS_INSPECTABLE_FAILURE_CONCLUSIONS
+    )
+
+
+def _actions_run_context(run: Mapping[str, Any]) -> dict[str, Any]:
+    return {
+        "run_id": run.get("id"),
+        "workflow": str(run.get("name") or ""),
+        "head_sha": str(run.get("head_sha") or ""),
+    }
+
+
+def _actions_job_context(job: Mapping[str, Any]) -> dict[str, Any]:
+    return {
+        "job_id": job.get("id"),
+        "job": str(job.get("name") or ""),
+    }
+
+
+def _incomplete_inspection_detail(
+    *,
+    stage: str,
+    run_id: Any | None = None,
+    workflow: str | None = None,
+    job_id: Any | None = None,
+    job: str | None = None,
+    reason: str | None = None,
+    limit: int | None = None,
+) -> dict[str, Any]:
+    detail: dict[str, Any] = {"stage": stage}
+    if run_id is not None:
+        detail["run_id"] = run_id
+    if workflow:
+        detail["workflow"] = workflow
+    if job_id is not None:
+        detail["job_id"] = job_id
+    if job:
+        detail["job"] = job
+    if reason:
+        detail["reason"] = reason
+    if limit is not None:
+        detail["limit"] = limit
+    return detail
+
+
+__all__ = (
+    "_actions_job_context",
+    "_actions_run_context",
+    "_incomplete_inspection_detail",
+    "_is_inspectable_actions_failure",
+)