claude-dev-env 2.16.0 → 2.17.0

package/_shared/pr-loop/scripts/check_convergence_availability.py

@@ -0,0 +1,275 @@
+"""Resolve whether a reviewer gate is waived, and why, for the convergence check.
+
+::
+
+    flag / resolved settings disable the reviewer  -> waived, note "copilot_down"
+    copilot out of quota                           -> waived, "copilot unavailable: <reason>"
+    bugbot settings-disabled (opt-out / no opt-in) -> waived, "bugbot_down"
+    copilot quota available                         -> not waived (live gates run)
+    copilot probe error / indeterminate             -> not waived; probe_error_reason set;
+                                                       live gates still run (no hard-fail)
+
+When ``~/.claude/settings.json`` is readable it is the sole source for both
+``CLAUDE_REVIEWS_DISABLED`` and ``CLAUDE_REVIEWS_ENABLED``. The process env is
+the fallback only when that file is missing, unreadable, or not a JSON object.
+
+Bugbot has no quota or outage API. Confirmed-down for Bugbot means the resolved
+settings disable it (opt-out or missing opt-in). A runtime Bugbot outage is
+detected later as a poll timeout, not at this gate.
+"""
+
+from __future__ import annotations
+
+import functools
+import json
+import logging
+import os
+import subprocess
+from typing import NamedTuple
+
+import _pr_converge_path_setup  # noqa: F401
+from copilot_quota import evaluate_copilot_quota
+from pr_converge_scripts_constants.convergence_gate_constants import (
+    BUGBOT_DOWN_BYPASS_NOTE,
+    COPILOT_DOWN_BYPASS_NOTE,
+    REVIEWER_UNAVAILABLE_NOTE_TEMPLATE,
+    SETTINGS_DISK_FALLBACK_LOG_TEMPLATE,
+)
+from pr_loop_shared_constants.claude_permissions_constants import (
+    get_claude_user_settings_path,
+)
+from pr_loop_shared_constants.copilot_quota_constants import (
+    COPILOT_QUOTA_DEFAULT_ENV_FILE_PATH,
+    EXIT_CODE_OUT_OF_QUOTA,
+    EXIT_CODE_QUOTA_AVAILABLE,
+)
+from pr_loop_shared_constants.reviews_disabled_constants import (
+    CLAUDE_REVIEWS_DISABLED_BUGBOT_TOKEN,
+    CLAUDE_REVIEWS_DISABLED_BUGTEAM_TOKEN,
+    CLAUDE_REVIEWS_DISABLED_CODEX_TOKEN,
+    CLAUDE_REVIEWS_DISABLED_COPILOT_TOKEN,
+    CLAUDE_REVIEWS_DISABLED_ENV_VAR_NAME,
+    CLAUDE_REVIEWS_DISABLED_TOKEN_SEPARATOR,
+    CLAUDE_REVIEWS_ENABLED_ENV_VAR_NAME,
+)
+
+_logger = logging.getLogger(__name__)
+
+
+class ReviewerWaiver(NamedTuple):
+    """Whether a reviewer gate is waived, and the note printed on the bypassed line."""
+
+    is_waived: bool
+    bypass_note: str
+    probe_error_reason: str = ""
+
+
+class _ReviewsSettings(NamedTuple):
+    """Resolved disabled and enabled reviewer tokens for one settings source."""
+
+    disabled_tokens: frozenset[str]
+    enabled_tokens: frozenset[str]
+
+
+def _tokens_from_text(reviews_token_text: str) -> frozenset[str]:
+    """Split a comma-separated reviews token list into lowercase tokens."""
+    return frozenset(
+        each_token.strip().lower()
+        for each_token in reviews_token_text.split(CLAUDE_REVIEWS_DISABLED_TOKEN_SEPARATOR)
+        if each_token.strip()
+    )
+
+
+def _tokens_from_env(environment_variable_name: str) -> frozenset[str]:
+    """Return the tokens listed in a process environment variable."""
+    return _tokens_from_text(os.environ.get(environment_variable_name, ""))
+
+
+def _tokens_from_env_block(
+    all_env_entries: dict[str, object], environment_variable_name: str
+) -> frozenset[str]:
+    """Return the tokens listed under one key of a settings.json env block."""
+    reviews_token_text = all_env_entries.get(environment_variable_name, "")
+    if not isinstance(reviews_token_text, str):
+        return frozenset()
+    return _tokens_from_text(reviews_token_text)
+
+
+def _try_read_disk_env_block() -> dict[str, object] | None:
+    """Return the settings.json env block, or None when disk is not authoritative."""
+    settings_path = get_claude_user_settings_path()
+    if not settings_path.is_file():
+        return None
+    try:
+        settings_payload = json.loads(settings_path.read_text(encoding="utf-8"))
+    except (OSError, ValueError):
+        return None
+    if not isinstance(settings_payload, dict):
+        return None
+    all_env_entries = settings_payload.get("env", {})
+    if not isinstance(all_env_entries, dict):
+        return {}
+    return all_env_entries
+
+
+@functools.lru_cache(maxsize=1)
+def _log_disk_settings_fallback_once() -> None:
+    """Log once per process that settings.json fell back to the process env."""
+    _logger.warning(
+        SETTINGS_DISK_FALLBACK_LOG_TEMPLATE,
+        CLAUDE_REVIEWS_DISABLED_ENV_VAR_NAME,
+        CLAUDE_REVIEWS_ENABLED_ENV_VAR_NAME,
+    )
+
+
+@functools.lru_cache(maxsize=1)
+def _resolve_reviews_settings() -> _ReviewsSettings:
+    """Return disabled and enabled tokens from disk, or env when disk is unreadable.
+
+    Cached for the process. Four reviewer gates ask for these tokens in one
+    run, and settings cannot change under a running check, so the disk read
+    and JSON parse happen once. A test that rebinds the settings path calls
+    ``_resolve_reviews_settings.cache_clear()`` first.
+    """
+    all_disk_env_entries = _try_read_disk_env_block()
+    if all_disk_env_entries is not None:
+        return _ReviewsSettings(
+            disabled_tokens=_tokens_from_env_block(
+                all_disk_env_entries, CLAUDE_REVIEWS_DISABLED_ENV_VAR_NAME
+            ),
+            enabled_tokens=_tokens_from_env_block(
+                all_disk_env_entries, CLAUDE_REVIEWS_ENABLED_ENV_VAR_NAME
+            ),
+        )
+    _log_disk_settings_fallback_once()
+    return _ReviewsSettings(
+        disabled_tokens=_tokens_from_env(CLAUDE_REVIEWS_DISABLED_ENV_VAR_NAME),
+        enabled_tokens=_tokens_from_env(CLAUDE_REVIEWS_ENABLED_ENV_VAR_NAME),
+    )
+
+
+def _is_copilot_disabled_via_resolved_settings() -> bool:
+    """Return True when the resolved settings disable the copilot reviewer."""
+    return (
+        CLAUDE_REVIEWS_DISABLED_COPILOT_TOKEN
+        in _resolve_reviews_settings().disabled_tokens
+    )
+
+
+def _is_off_by_default_reviewer_disabled(reviewer_token: str) -> bool:
+    """Return True when the resolved settings leave an opt-in reviewer off.
+
+    ::
+
+        enabled names the token, disabled empty  -> False  (gate runs)
+        neither list names the token             -> True   (off by default)
+        both lists name the token                -> True   (opt-out wins)
+
+    Args:
+        reviewer_token: The lowercase reviewer token to look up in both lists.
+
+    Returns:
+        True when the reviewer stays off for this run.
+    """
+    reviews_settings = _resolve_reviews_settings()
+    is_opted_out = reviewer_token in reviews_settings.disabled_tokens
+    is_opted_in = reviewer_token in reviews_settings.enabled_tokens
+    return is_opted_out or not is_opted_in
+
+
+def _is_bugbot_disabled_via_resolved_settings() -> bool:
+    """Return True when the resolved settings disable the bugbot reviewer.
+
+    Bugbot is off by default. It is disabled when the disabled list names it, or
+    when the enabled list does not name it.
+    """
+    return _is_off_by_default_reviewer_disabled(CLAUDE_REVIEWS_DISABLED_BUGBOT_TOKEN)
+
+
+def _is_bugteam_disabled_via_resolved_settings() -> bool:
+    """Return True when the resolved settings disable the bug-audit family.
+
+    Bugteam is off by default. It is disabled when the disabled list names it,
+    or when the enabled list does not name it.
+    """
+    return _is_off_by_default_reviewer_disabled(CLAUDE_REVIEWS_DISABLED_BUGTEAM_TOKEN)
+
+
+def _is_codex_disabled_via_resolved_settings() -> bool:
+    """Return True when the resolved settings disable the Codex reviewer.
+
+    Codex is off by default. It is disabled when the disabled list names it, or
+    when the enabled list does not name it.
+    """
+    return _is_off_by_default_reviewer_disabled(CLAUDE_REVIEWS_DISABLED_CODEX_TOKEN)
+
+
+def _unavailable_note(reviewer_token: str, message: str) -> str:
+    """Format the bypass note for a confirmed-down reviewer."""
+    return REVIEWER_UNAVAILABLE_NOTE_TEMPLATE.format(
+        token=reviewer_token, message=message
+    )
+
+
+@functools.lru_cache(maxsize=None)
+def _probe_copilot_quota() -> ReviewerWaiver:
+    """Probe Copilot quota once per run; waive only on confirmed out-of-quota.
+
+    ::
+
+        exit == out-of-quota (1)  -> waived, "copilot unavailable: <msg>"
+        exit == available (0)     -> not waived (live gates run)
+        exit == API down / no account / other non-zero
+                                  -> not waived; probe_error_reason set (live gates run)
+        probe raises              -> not waived; probe_error_reason set (live gates run)
+    """
+    try:
+        quota_decision = evaluate_copilot_quota(
+            cli_account=None,
+            env_file_path=COPILOT_QUOTA_DEFAULT_ENV_FILE_PATH,
+        )
+    except (OSError, ValueError, RuntimeError, subprocess.SubprocessError) as probe_error:
+        _logger.warning(
+            "reviewer-availability: probe error for %s: %s",
+            CLAUDE_REVIEWS_DISABLED_COPILOT_TOKEN,
+            probe_error,
+        )
+        return ReviewerWaiver(False, "", str(probe_error))
+    if quota_decision.exit_code == EXIT_CODE_OUT_OF_QUOTA:
+        return ReviewerWaiver(
+            True,
+            _unavailable_note(
+                CLAUDE_REVIEWS_DISABLED_COPILOT_TOKEN, quota_decision.message
+            ),
+            "",
+        )
+    if quota_decision.exit_code == EXIT_CODE_QUOTA_AVAILABLE:
+        return ReviewerWaiver(False, "", "")
+    return ReviewerWaiver(False, "", quota_decision.message)
+
+
+def _waiver_from_cli_flag(is_down_flag: bool, bypass_note: str) -> ReviewerWaiver:
+    """Build a waiver from an explicit CLI flag alone (fixture offline path)."""
+    if is_down_flag:
+        return ReviewerWaiver(True, bypass_note, "")
+    return ReviewerWaiver(False, "", "")
+
+
+def _resolve_copilot_waiver(is_copilot_down_flag: bool) -> ReviewerWaiver:
+    """Resolve the Copilot waiver from flag, resolved settings, then the quota probe."""
+    if is_copilot_down_flag or _is_copilot_disabled_via_resolved_settings():
+        return ReviewerWaiver(True, COPILOT_DOWN_BYPASS_NOTE, "")
+    return _probe_copilot_quota()
+
+
+def _resolve_bugbot_waiver(is_bugbot_down_flag: bool) -> ReviewerWaiver:
+    """Resolve the Bugbot waiver from flag, then resolved settings.
+
+    Bugbot has no quota or outage API. Once the resolved settings (disk when
+    readable, else env) confirm the opt-in, the gate is enforced. Re-probing
+    via ``evaluate_reviewer_availability`` would re-read the process env and
+    undo a mid-session disk enable of Bugbot.
+    """
+    if is_bugbot_down_flag or _is_bugbot_disabled_via_resolved_settings():
+        return ReviewerWaiver(True, BUGBOT_DOWN_BYPASS_NOTE, "")
+    return ReviewerWaiver(False, "", "")

package/_shared/pr-loop/scripts/check_convergence_gates.py

@@ -0,0 +1,279 @@
+"""Review and Bugbot IO leaves for the convergence gate checks.
+
+Each function issues one ``gh`` REST call and returns a ``(passed, detail)``
+pair the convergence checker turns into a PASS/FAIL line, or a raw
+``(returncode, stdout)`` pair for the low-level callers. The checker re-imports
+these names, so a test patches them on the checker module.
+"""
+
+from __future__ import annotations
+
+import json
+import re
+import subprocess
+import sys
+
+import _pr_converge_path_setup  # noqa: F401
+from pr_converge_skill_constants.constants import (
+    ALL_BUGBOT_CHECK_RUN_COMPLETE_CONCLUSIONS,
+    BUGBOT_CHECK_RUN_NAME_SUBSTRING,
+    BUGBOT_DIRTY_BODY_REGEX,
+    CHECK_RUNS_PER_PAGE,
+    CURSOR_LOGIN_FILTER_SUBSTRING,
+    EXIT_CODE_GH_ERROR,
+    GH_CHECK_RUNS_PATH_TEMPLATE,
+    GH_PR_OBJECT_PATH_TEMPLATE,
+    GH_REVIEWS_PATH_TEMPLATE,
+    REVIEWS_PER_PAGE,
+)
+from pr_converge_scripts_constants.convergence_gate_constants import (
+    MERGEABLE_STATE_CLEAN,
+    REVIEW_SUBMITTED_AT_KEY,
+    SHORT_SHA_LENGTH,
+)
+
+JsonObject = dict[str, object]
+ReviewStateGroup = tuple[str, ...]
+
+
+def _run_gh_command(all_arguments: list[str]) -> tuple[int, str]:
+    completed_process = subprocess.run(
+        all_arguments,
+        capture_output=True,
+        text=True,
+        encoding="utf-8",
+        errors="replace",
+        check=False,
+    )
+    return completed_process.returncode, completed_process.stdout
+
+
+def _gh_api(endpoint_path: str) -> tuple[int, str]:
+    return _run_gh_command(["gh", "api", endpoint_path])
+
+
+def _gh_api_paginated(endpoint_path: str) -> tuple[int, str]:
+    return _run_gh_command(["gh", "api", endpoint_path, "--paginate", "--slurp"])
+
+
+def _short_sha(commit_id: str) -> str:
+    return commit_id[:SHORT_SHA_LENGTH]
+
+
+def _get_pr_head_sha(*, owner: str, repo: str, number: int) -> str:
+    """Return the PR HEAD SHA, exiting with the gh-error code when the call fails."""
+    endpoint = GH_PR_OBJECT_PATH_TEMPLATE.format(owner=owner, repo=repo, number=number)
+    returncode, stdout = _gh_api(endpoint)
+    if returncode != 0:
+        sys.stderr.write(f"gh api error fetching PR object: {stdout}\n")
+        raise SystemExit(EXIT_CODE_GH_ERROR)
+    try:
+        pr_object = json.loads(stdout)
+    except json.JSONDecodeError as decode_error:
+        sys.stderr.write(f"gh api PR object not valid JSON: {stdout}\n")
+        raise SystemExit(EXIT_CODE_GH_ERROR) from decode_error
+    head_object = pr_object.get("head") if isinstance(pr_object, dict) else None
+    head_sha: object = head_object.get("sha") if isinstance(head_object, dict) else None
+    if not isinstance(head_sha, str):
+        raise SystemExit(EXIT_CODE_GH_ERROR)
+    return head_sha
+
+
+def _evaluate_mergeable_from_pr_object(pr_object: JsonObject) -> tuple[bool, str]:
+    """Return whether a PR object dict is cleanly mergeable.
+
+    Pure evaluator: no network IO. Live and fixture paths share this contract.
+
+    Args:
+        pr_object: Pull request JSON object with mergeable and mergeable_state fields.
+
+    Returns:
+        (True, clean) when mergeable is true and state is clean; otherwise (False, state).
+    """
+    mergeable: object = pr_object.get("mergeable")
+    mergeable_state: object = pr_object.get("mergeable_state", "unknown")
+    state_text = str(mergeable_state)
+    if mergeable is True and state_text == MERGEABLE_STATE_CLEAN:
+        return True, MERGEABLE_STATE_CLEAN
+    return False, state_text
+
+
+def _get_mergeable(*, owner: str, repo: str, number: int) -> tuple[bool, str]:
+    """Return whether the PR is cleanly mergeable, with the mergeable-state detail."""
+    endpoint = GH_PR_OBJECT_PATH_TEMPLATE.format(owner=owner, repo=repo, number=number)
+    returncode, stdout = _gh_api(endpoint)
+    if returncode != 0:
+        return False, f"gh api error: {stdout}"
+    try:
+        pr_object = json.loads(stdout)
+    except json.JSONDecodeError:
+        return False, "gh api PR object not valid JSON"
+    if not isinstance(pr_object, dict):
+        return False, "unknown"
+    return _evaluate_mergeable_from_pr_object(pr_object)
+
+
+def _bugbot_check_runs(
+    *, owner: str, repo: str, sha: str
+) -> tuple[int, list[JsonObject]]:
+    """Fetch the check runs for a SHA and return the returncode and run dicts."""
+    endpoint = GH_CHECK_RUNS_PATH_TEMPLATE.format(owner=owner, repo=repo, sha=sha)
+    returncode, stdout = _gh_api(f"{endpoint}?per_page={CHECK_RUNS_PER_PAGE}")
+    if returncode != 0:
+        return returncode, []
+    try:
+        payload = json.loads(stdout)
+    except json.JSONDecodeError:
+        return returncode, []
+    raw_runs = payload.get("check_runs") if isinstance(payload, dict) else None
+    if not isinstance(raw_runs, list):
+        return returncode, []
+    return returncode, [each_run for each_run in raw_runs if isinstance(each_run, dict)]
+
+
+def _bugbot_run_conclusion_detail(check_run: JsonObject) -> tuple[bool, str]:
+    """Return the pass flag and detail for one bugbot check run."""
+    conclusion = check_run.get("conclusion", "")
+    if conclusion in ALL_BUGBOT_CHECK_RUN_COMPLETE_CONCLUSIONS:
+        check_id = check_run.get("id", "?")
+        detail_url = check_run.get("html_url", "")
+        details_suffix = f" ({detail_url})" if detail_url else ""
+        return True, f"check run {check_id}, conclusion: {conclusion}{details_suffix}"
+    return (
+        False,
+        f"check run conclusion is '{conclusion}', expected {ALL_BUGBOT_CHECK_RUN_COMPLETE_CONCLUSIONS}",
+    )
+
+
+def _check_bugbot(*, owner: str, repo: str, sha: str) -> tuple[bool, str]:
+    """Return whether the Cursor Bugbot check run on a SHA completed successfully."""
+    returncode, check_runs = _bugbot_check_runs(owner=owner, repo=repo, sha=sha)
+    if returncode != 0:
+        return False, "gh api error fetching check runs"
+    for each_check_run in check_runs:
+        each_name = each_check_run.get("name", "")
+        if not isinstance(each_name, str):
+            continue
+        if BUGBOT_CHECK_RUN_NAME_SUBSTRING.lower() not in each_name.lower():
+            continue
+        return _bugbot_run_conclusion_detail(each_check_run)
+    return False, "no bugbot check run found"
+
+
+def _sort_reviews_newest_first(all_reviews: list[JsonObject]) -> list[JsonObject]:
+    """Return the reviews ordered newest-first by submission time.
+
+    The live gh path and the offline fixture path both feed the same
+    newest-first evaluators, so both order their reviews through here.
+
+    Args:
+        all_reviews: Review objects in any order.
+
+    Returns:
+        A new list ordered newest-first; a review with no submitted_at sorts last.
+    """
+    return sorted(
+        all_reviews,
+        key=lambda each_review: str(each_review.get(REVIEW_SUBMITTED_AT_KEY, "")),
+        reverse=True,
+    )
+
+
+def _flatten_paginated_reviews(stdout: str) -> list[JsonObject] | None:
+    """Flatten a slurped, paginated reviews payload into a newest-first list."""
+    try:
+        reviews_payload = json.loads(stdout)
+    except json.JSONDecodeError:
+        return None
+    if not isinstance(reviews_payload, list):
+        return None
+    all_flat: list[JsonObject] = [
+        each_entry
+        for each_page in reviews_payload
+        if isinstance(each_page, list)
+        for each_entry in each_page
+        if isinstance(each_entry, dict)
+    ]
+    return _sort_reviews_newest_first(all_flat)
+
+
+def _review_matches_login(review: JsonObject, login_substring: str) -> bool:
+    user_object = review.get("user")
+    if not isinstance(user_object, dict):
+        return False
+    login = user_object.get("login", "")
+    return isinstance(login, str) and login_substring in login.lower()
+
+
+def _review_commit_starts_with(review: JsonObject, head_sha: str) -> bool:
+    commit_id = review.get("commit_id", "")
+    return isinstance(commit_id, str) and commit_id.startswith(head_sha)
+
+
+def _check_bugbot_not_dirty(
+    *, owner: str, repo: str, number: int, head_sha: str
+) -> tuple[bool, str]:
+    """Return whether the newest Cursor Bugbot review on HEAD reports no findings."""
+    endpoint = GH_REVIEWS_PATH_TEMPLATE.format(owner=owner, repo=repo, number=number)
+    returncode, stdout = _gh_api_paginated(f"{endpoint}?per_page={REVIEWS_PER_PAGE}")
+    if returncode != 0:
+        return True, "bugbot reviews unavailable (non-fatal)"
+    all_flat = _flatten_paginated_reviews(stdout)
+    if all_flat is None:
+        return True, "bugbot reviews not valid JSON (non-fatal)"
+    dirty_pattern = re.compile(BUGBOT_DIRTY_BODY_REGEX, re.IGNORECASE)
+    for each_review in all_flat:
+        if not _review_matches_login(each_review, CURSOR_LOGIN_FILTER_SUBSTRING):
+            continue
+        if not _review_commit_starts_with(each_review, head_sha):
+            continue
+        body = each_review.get("body", "")
+        if isinstance(body, str) and dirty_pattern.search(body):
+            return False, "bugbot review body reports findings"
+        return True, "clean"
+    return True, "no bugbot review at HEAD"
+
+
+def _bot_review_state_detail(
+    review: JsonObject,
+    clean_states: ReviewStateGroup,
+    dirty_states: ReviewStateGroup,
+) -> tuple[bool, str]:
+    """Return the pass flag and detail for one bot review's state."""
+    review_state = review.get("state", "")
+    commit_id = review.get("commit_id", "")
+    short_commit = _short_sha(commit_id) if isinstance(commit_id, str) else "?"
+    if review_state in clean_states:
+        review_id = review.get("id", "?")
+        return True, f"review {review_id}, state: {review_state}, commit {short_commit}"
+    if review_state in dirty_states:
+        return False, f"review state is '{review_state}' (dirty), commit {short_commit}"
+    return False, f"review state is '{review_state}', commit {short_commit}"
+
+
+def _check_bot_review(
+    *,
+    owner: str,
+    repo: str,
+    number: int,
+    head_sha: str,
+    login_substring: str,
+    clean_states: ReviewStateGroup,
+    dirty_states: ReviewStateGroup,
+    label: str,
+) -> tuple[bool, str]:
+    """Return whether the newest matching bot review on HEAD is in a clean state."""
+    endpoint = GH_REVIEWS_PATH_TEMPLATE.format(owner=owner, repo=repo, number=number)
+    returncode, stdout = _gh_api_paginated(f"{endpoint}?per_page={REVIEWS_PER_PAGE}")
+    if returncode != 0:
+        return False, f"gh api error: {stdout}"
+    all_flat = _flatten_paginated_reviews(stdout)
+    if all_flat is None:
+        return False, f"no {label} review found"
+    for each_review in all_flat:
+        if not _review_matches_login(each_review, login_substring):
+            continue
+        if not _review_commit_starts_with(each_review, head_sha):
+            continue
+        return _bot_review_state_detail(each_review, clean_states, dirty_states)
+    return False, f"no {label} review found on {_short_sha(head_sha)}"