claude-dev-env 1.93.0 → 1.94.0

package/skills/pr-converge/scripts/check_convergence_gates.py

@@ -0,0 +1,235 @@
+"""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 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)
+    pr_object = json.loads(stdout)
+    head_sha: object = pr_object.get("head", {}).get("sha")
+    if not isinstance(head_sha, str):
+        raise SystemExit(EXIT_CODE_GH_ERROR)
+    return head_sha
+
+
+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}"
+    pr_object = json.loads(stdout)
+    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 == "clean":
+        return True, "clean"
+    return False, state_text
+
+
+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 _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)
+    ]
+    all_flat.sort(
+        key=lambda each_review: str(each_review.get("submitted_at", "")), reverse=True
+    )
+    return 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)}"

package/skills/pr-converge/scripts/check_convergence_thread_gates.py

@@ -0,0 +1,219 @@
+"""Review-thread and pending-reviewer IO leaves for the convergence gate checks.
+
+Each function issues one ``gh`` call (GraphQL or REST) and returns a
+``(passed, detail)`` pair the convergence checker turns into a PASS/FAIL line.
+The checker re-imports these names, so a test patches them on the checker module.
+"""
+
+from __future__ import annotations
+
+import json
+
+import _pr_converge_path_setup  # noqa: F401
+from check_convergence_gates import (
+    JsonObject,
+    ReviewStateGroup,
+    _gh_api,
+    _run_gh_command,
+)
+from pr_converge_skill_constants.constants import (
+    CLAUDE_LOGIN_FILTER_SUBSTRING,
+    COPILOT_LOGIN_FILTER_SUBSTRING,
+    COPILOT_REVIEWER_LOGIN,
+    CURSOR_LOGIN_FILTER_SUBSTRING,
+    GH_REQUESTED_REVIEWERS_PATH_TEMPLATE,
+    GRAPHQL_REVIEW_THREADS_PAGE_SIZE,
+    UNRESOLVED_THREAD_DETAIL_MAX,
+)
+from pr_converge_scripts_constants.convergence_gate_constants import (
+    GRAPHQL_REVIEW_THREADS_QUERY,
+    PENDING_REVIEWER_JOIN_SEPARATOR,
+    THREAD_PATH_JOIN_SEPARATOR,
+)
+
+
+def _gh_graphql(query: str, variables: JsonObject) -> tuple[int, str]:
+    """Run a ``gh api graphql`` query with variables and return returncode and stdout."""
+    all_arguments: list[str] = ["gh", "api", "graphql", "-f", f"query={query}"]
+    for each_key, each_variable in variables.items():
+        if each_variable is None:
+            continue
+        flag = "-F" if isinstance(each_variable, int) else "-f"
+        all_arguments.extend([flag, f"{each_key}={each_variable}"])
+    return _run_gh_command(all_arguments)
+
+
+def _thread_author_login(thread: JsonObject) -> str:
+    """Return the login of a review thread's first comment author, or empty string."""
+    comments_wrapper = thread.get("comments", {})
+    if not isinstance(comments_wrapper, dict):
+        return ""
+    comments_nodes = comments_wrapper.get("nodes", [])
+    if not isinstance(comments_nodes, list) or not comments_nodes:
+        return ""
+    first_comment = comments_nodes[0]
+    author_wrapper = (
+        first_comment.get("author") if isinstance(first_comment, dict) else None
+    )
+    if not isinstance(author_wrapper, dict):
+        return ""
+    login = author_wrapper.get("login", "")
+    return login if isinstance(login, str) else ""
+
+
+def _is_unresolved_bot_thread(thread: JsonObject, bot_logins: ReviewStateGroup) -> bool:
+    """Return whether a review thread is unresolved, current, and bot-authored."""
+    if thread.get("isResolved") is True or thread.get("isOutdated") is True:
+        return False
+    login = _thread_author_login(thread).lower()
+    return any(each_bot in login for each_bot in bot_logins)
+
+
+def _unresolved_bot_threads_in_page(
+    nodes: object, bot_logins: ReviewStateGroup
+) -> list[JsonObject]:
+    """Return the unresolved bot-authored threads among one page of thread nodes."""
+    if not isinstance(nodes, list):
+        return []
+    return [
+        each_thread
+        for each_thread in nodes
+        if isinstance(each_thread, dict)
+        and _is_unresolved_bot_thread(each_thread, bot_logins)
+    ]
+
+
+def _review_threads_container(graphql_payload: object) -> JsonObject | None:
+    """Return the ``reviewThreads`` object from a GraphQL payload, or None."""
+    if not isinstance(graphql_payload, dict):
+        return None
+    envelope = graphql_payload.get("data", {})
+    repository = envelope.get("repository", {}) if isinstance(envelope, dict) else {}
+    pull_request = (
+        repository.get("pullRequest", {}) if isinstance(repository, dict) else {}
+    )
+    threads = (
+        pull_request.get("reviewThreads", {}) if isinstance(pull_request, dict) else {}
+    )
+    return threads if isinstance(threads, dict) else None
+
+
+def _fetch_review_threads_page(
+    *, owner: str, repo: str, number: int, cursor: str | None
+) -> tuple[str, object, object]:
+    """Fetch one page of review threads and return an error text, nodes, and page info."""
+    variables: JsonObject = {
+        "owner": owner,
+        "repo": repo,
+        "number": number,
+        "first": GRAPHQL_REVIEW_THREADS_PAGE_SIZE,
+        "cursor": cursor,
+    }
+    returncode, stdout = _gh_graphql(GRAPHQL_REVIEW_THREADS_QUERY, variables)
+    if returncode != 0:
+        return f"gh api graphql error: {stdout}", [], {}
+    try:
+        graphql_payload = json.loads(stdout)
+    except json.JSONDecodeError:
+        return "gh api graphql response not valid JSON", [], {}
+    threads = _review_threads_container(graphql_payload)
+    if threads is None:
+        return "unexpected GraphQL response shape", [], {}
+    return "", threads.get("nodes", []), threads.get("pageInfo", {})
+
+
+def _next_thread_cursor(page_info: object) -> str | None:
+    """Return the next pagination cursor, or None when there is no next page."""
+    if not isinstance(page_info, dict):
+        return None
+    if not page_info.get("hasNextPage"):
+        return None
+    next_cursor = page_info.get("endCursor")
+    return next_cursor if isinstance(next_cursor, str) else None
+
+
+def _format_unresolved_detail(all_unresolved: list[JsonObject]) -> str:
+    """Format the unresolved-thread count and a bounded list of their paths."""
+    detail_parts = [
+        str(each_thread.get("path", "?"))
+        for each_thread in all_unresolved[:UNRESOLVED_THREAD_DETAIL_MAX]
+    ]
+    detail_text = THREAD_PATH_JOIN_SEPARATOR.join(detail_parts)
+    if len(all_unresolved) > UNRESOLVED_THREAD_DETAIL_MAX:
+        detail_text += (
+            f" ... and {len(all_unresolved) - UNRESOLVED_THREAD_DETAIL_MAX} more"
+        )
+    return f"{len(all_unresolved)} unresolved ({detail_text})"
+
+
+def _count_unresolved_bot_threads(
+    *, owner: str, repo: str, number: int
+) -> tuple[bool, str]:
+    """Return whether zero unresolved bot review threads remain on the PR."""
+    bot_logins = (
+        CURSOR_LOGIN_FILTER_SUBSTRING,
+        CLAUDE_LOGIN_FILTER_SUBSTRING,
+        COPILOT_LOGIN_FILTER_SUBSTRING,
+    )
+    all_unresolved: list[JsonObject] = []
+    cursor: str | None = None
+    while True:
+        error_text, nodes, page_info = _fetch_review_threads_page(
+            owner=owner, repo=repo, number=number, cursor=cursor
+        )
+        if error_text:
+            return False, error_text
+        all_unresolved.extend(_unresolved_bot_threads_in_page(nodes, bot_logins))
+        cursor = _next_thread_cursor(page_info)
+        if cursor is None:
+            break
+    if not all_unresolved:
+        return True, "0 unresolved"
+    return False, _format_unresolved_detail(all_unresolved)
+
+
+def _requested_reviewer_users(pending_payload: object) -> list[object]:
+    if isinstance(pending_payload, dict):
+        users = pending_payload.get("users", [])
+    elif isinstance(pending_payload, list):
+        users = pending_payload
+    else:
+        return []
+    return users if isinstance(users, list) else []
+
+
+def _pending_copilot_logins(all_users: list[object]) -> list[str]:
+    """Return the Copilot reviewer logins still pending among requested reviewers."""
+    pending: list[str] = []
+    for each_user in all_users:
+        if not isinstance(each_user, dict):
+            continue
+        login = each_user.get("login", "")
+        if isinstance(login, str) and COPILOT_REVIEWER_LOGIN.lower() in login.lower():
+            pending.append(login)
+    return pending
+
+
+def _check_no_pending_reviews(
+    *, owner: str, repo: str, number: int
+) -> tuple[bool, str]:
+    """Return whether no Copilot review request is still pending on the PR."""
+    endpoint = GH_REQUESTED_REVIEWERS_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:
+        pending_payload = json.loads(stdout)
+    except json.JSONDecodeError:
+        return True, "no pending (empty response)"
+    copilot_pending = _pending_copilot_logins(
+        _requested_reviewer_users(pending_payload)
+    )
+    if copilot_pending:
+        return (
+            False,
+            f"pending: {PENDING_REVIEWER_JOIN_SEPARATOR.join(copilot_pending)}",
+        )
+    return True, "no pending reviewers"

package/skills/pr-converge/scripts/conftest.py

@@ -0,0 +1,8 @@
+"""Put the pr-converge scripts directory on sys.path for the test suite."""
+
+import sys
+from pathlib import Path
+
+_scripts_directory = Path(__file__).resolve().parent
+if str(_scripts_directory) not in sys.path:
+    sys.path.insert(0, str(_scripts_directory))

package/skills/pr-converge/scripts/pr_converge_scripts_constants/CLAUDE.md

@@ -9,6 +9,7 @@ Constants module for the `pr-converge` skill's Python scripts. Re-exports all ru
 | `__init__.py` | Package marker |
 | `pr_converge_constants.py` | Re-exports all constants from `pr_converge_skill_constants.constants` plus adds script-specific values |
 | `reflow_skill_md_constants.py` | Constants for `reflow_skill_md.py`: line width limit, list item patterns, `TARGET_SKILL_PATH` |
+| `convergence_gate_constants.py` | Constants for `check_convergence_gates.py`: short-SHA length, join separators, and the review-threads GraphQL query |
 
 ## Conventions
 

package/skills/pr-converge/scripts/pr_converge_scripts_constants/convergence_gate_constants.py

@@ -0,0 +1,36 @@
+"""Named constants for the convergence gate IO leaves.
+
+Holds the short-SHA length, the join separators for gate detail strings, and
+the GraphQL query that lists a PR's review threads.
+"""
+
+SHORT_SHA_LENGTH: int = 7
+
+THREAD_PATH_JOIN_SEPARATOR: str = "; "
+
+PENDING_REVIEWER_JOIN_SEPARATOR: str = ", "
+
+GRAPHQL_REVIEW_THREADS_QUERY: str = """
+query($owner: String!, $repo: String!, $number: Int!, $first: Int!, $cursor: String) {
+  repository(owner: $owner, name: $repo) {
+    pullRequest(number: $number) {
+      reviewThreads(first: $first, after: $cursor) {
+        nodes {
+          isResolved
+          isOutdated
+          path
+          comments(first: 1) {
+            nodes {
+              author { login }
+            }
+          }
+        }
+        pageInfo {
+          hasNextPage
+          endCursor
+        }
+      }
+    }
+  }
+}
+"""

package/skills/pr-converge/scripts/test__pr_converge_path_setup.py

@@ -0,0 +1,26 @@
+"""Importing _pr_converge_path_setup registers the skill and shared directories.
+
+::
+
+    import _pr_converge_path_setup
+    ok: str(skill_directory) in sys.path
+    ok: str(shared_pr_loop_scripts_directory) in sys.path
+"""
+
+from __future__ import annotations
+
+import sys
+from pathlib import Path
+
+import _pr_converge_path_setup  # noqa: F401
+
+_SCRIPTS_DIRECTORY = Path(__file__).absolute().parent
+
+
+def test_path_setup_registers_skill_and_shared_directories() -> None:
+    skill_directory = _SCRIPTS_DIRECTORY.parent
+    shared_directory = (
+        _SCRIPTS_DIRECTORY.parent.parent.parent / "_shared" / "pr-loop" / "scripts"
+    )
+    assert str(skill_directory) in sys.path
+    assert str(shared_directory) in sys.path