claude-dev-env 8.6.1 → 8.7.0

package/scripts/review_closure_github.py

@@ -0,0 +1,345 @@
+"""Read from GitHub what the review closure verdict rests on.
+
+Three reads answer one pull request: the pull request itself, its review
+threads, and the check runs on its head commit.
+
+::
+
+    read_pull_request("jl-cmd/claude-dev-env", 1442, token)
+    read_review_threads("jl-cmd/claude-dev-env", 1442, token)
+    read_approvals_conclusion("jl-cmd/claude-dev-env", "ab845eb", token)
+
+Two routes carry the review threads. A Claude Code session reaches GitHub
+through a proxy that refuses GraphQL and serves the threads over a REST route
+of its own, so the REST route is read first and the GraphQL query answers for
+a workflow runner.
+"""
+
+from __future__ import annotations
+
+import functools
+import json
+import os
+import urllib.error
+import urllib.request
+from collections.abc import Mapping
+
+from dev_env_scripts_constants.review_closure_constants import (
+    ALL_THREAD_NODE_KEYS,
+    ALL_TOKEN_ENVIRONMENT_VARIABLES,
+    CHECK_RUN_PAGE_SIZE,
+    CHECK_RUNS_ENDPOINT_TEMPLATE,
+    CHECK_RUNS_KEY,
+    GET_METHOD,
+    GITHUB_API_ROOT,
+    GITHUB_GRAPHQL_ENDPOINT,
+    MAX_REVIEW_COMMENT_PAGES,
+    NAME_VARIABLE,
+    NO_SIGN_IN_MESSAGE,
+    NUMBER_VARIABLE,
+    OWNER_VARIABLE,
+    PAGE_SIZE_VARIABLE,
+    POST_METHOD,
+    PULL_REQUEST_ENDPOINT_TEMPLATE,
+    QUERY_KEY,
+    REQUEST_FAILED_TEMPLATE,
+    REQUEST_TIMEOUT_SECONDS,
+    REVIEW_COMMENT_PAGE_SIZE,
+    REVIEW_COMMENTS_ENDPOINT_TEMPLATE,
+    REVIEW_THREAD_PAGE_SIZE,
+    REVIEW_THREAD_QUERY,
+    REVIEW_THREADS_ENDPOINT_TEMPLATE,
+    SLUG_SEPARATOR,
+    VARIABLES_KEY,
+)
+from pr_verification.config.constants import (
+    ACCEPT_HEADER,
+    API_VERSION_HEADER,
+    AUTHORIZATION_HEADER,
+    BEARER_PREFIX,
+    CONTENT_TYPE_HEADER,
+    GITHUB_ACCEPT_TYPE,
+    GITHUB_API_VERSION,
+    HTTP_OK,
+    JSON_CONTENT_TYPE,
+    UTF8_ENCODING,
+)
+from pr_verification.github_parsing import GitHubError
+from review_closure_model import (
+    ReviewThread,
+    approvals_conclusion,
+    comment_records_by_id,
+    parse_thread,
+)
+
+
+def github_token() -> str:
+    """Find the GitHub token this run authenticates with.
+
+    Returns:
+        The first token the environment carries.
+
+    Raises:
+        GitHubError: No token is set.
+    """
+    for each_variable in ALL_TOKEN_ENVIRONMENT_VARIABLES:
+        token = os.environ.get(each_variable)
+        if token:
+            return token
+    raise GitHubError(NO_SIGN_IN_MESSAGE)
+
+
+def request_json(
+    method: str,
+    url: str,
+    token: str,
+    all_payload_fields: Mapping[str, object] | None,
+) -> object:
+    """Send one GitHub request and read its JSON answer.
+
+    Args:
+        method: The HTTP method.
+        url: The absolute request URL.
+        token: The GitHub token the request authenticates with.
+        all_payload_fields: The JSON body to send, or None for a read.
+
+    Returns:
+        The decoded answer.
+
+    Raises:
+        GitHubError: The request failed, or GitHub answered with a status
+            other than success.
+    """
+    request = _built_request(method, url, token, all_payload_fields)
+    try:
+        with urllib.request.urlopen(request, timeout=REQUEST_TIMEOUT_SECONDS) as reply:
+            return _decoded_answer(url, reply.status, reply.read())
+    except (urllib.error.URLError, OSError, ValueError) as failure:
+        raise GitHubError(str(failure)) from failure
+
+
+def read_pull_request(slug: str, number: int, token: str) -> Mapping[str, object]:
+    """Read one pull request from the GitHub REST API.
+
+    Args:
+        slug: The repository as ``owner/name``.
+        number: The pull request number.
+        token: The GitHub token the request authenticates with.
+
+    Returns:
+        The pull request fields, carrying its number, its head commit, and
+        the account that opened it.
+
+    Raises:
+        GitHubError: GitHub answered with something other than a pull
+            request object.
+    """
+    document = request_json(
+        GET_METHOD,
+        PULL_REQUEST_ENDPOINT_TEMPLATE.format(
+            api_root=GITHUB_API_ROOT, slug=slug, number=number
+        ),
+        token,
+        None,
+    )
+    if not isinstance(document, Mapping):
+        raise GitHubError(str(document))
+    return document
+
+
+def read_review_threads(slug: str, number: int, token: str) -> tuple[ReviewThread, ...]:
+    """Read the review threads on a pull request.
+
+    Args:
+        slug: The repository as ``owner/name``.
+        number: The pull request number.
+        token: The GitHub token the request authenticates with.
+
+    Returns:
+        Every review thread on the pull request.
+
+    Raises:
+        GitHubError: Both routes failed, or the GraphQL answer carried no
+            review threads.
+    """
+    all_records = _thread_records_over_rest(slug, number, token)
+    all_comment_records_by_id: Mapping[object, Mapping[str, object]] = {}
+    if all_records is None:
+        all_records = _thread_records_over_graphql(slug, number, token)
+    else:
+        all_comment_records_by_id = read_review_comments_by_id(slug, number, token)
+    return tuple(
+        parse_thread(each_record, all_comment_records_by_id)
+        for each_record in all_records
+        if isinstance(each_record, Mapping)
+    )
+
+
+def read_review_comments_by_id(
+    slug: str, number: int, token: str
+) -> dict[object, Mapping[str, object]]:
+    """Read every review comment on a pull request, keyed by identifier.
+
+    Args:
+        slug: The repository as ``owner/name``.
+        number: The pull request number.
+        token: The GitHub token the request authenticates with.
+
+    Returns:
+        Each review comment under its identifier.
+
+    Raises:
+        GitHubError: A page answered with something other than a list.
+    """
+    all_records: list[object] = []
+    for each_page in range(1, MAX_REVIEW_COMMENT_PAGES + 1):
+        page = _review_comment_page(slug, number, token, each_page)
+        all_records.extend(page)
+        if len(page) < REVIEW_COMMENT_PAGE_SIZE:
+            break
+    return comment_records_by_id(all_records)
+
+
+def _review_comment_page(slug: str, number: int, token: str, page: int) -> list[object]:
+    document = request_json(
+        GET_METHOD,
+        REVIEW_COMMENTS_ENDPOINT_TEMPLATE.format(
+            api_root=GITHUB_API_ROOT,
+            slug=slug,
+            number=number,
+            page_size=REVIEW_COMMENT_PAGE_SIZE,
+            page=page,
+        ),
+        token,
+        None,
+    )
+    if not isinstance(document, list):
+        raise GitHubError(str(document))
+    return document
+
+
+def read_approvals_conclusion(slug: str, sha: str, token: str) -> str | None:
+    """Read what the Claude Approvals check reports on one commit.
+
+    Args:
+        slug: The repository as ``owner/name``.
+        sha: The head commit.
+        token: The GitHub token the request authenticates with.
+
+    Returns:
+        That check run's conclusion, or None where it does not run.
+
+    Raises:
+        GitHubError: GitHub answered with an unexpected shape.
+    """
+    document = request_json(
+        GET_METHOD,
+        CHECK_RUNS_ENDPOINT_TEMPLATE.format(
+            api_root=GITHUB_API_ROOT,
+            slug=slug,
+            sha=sha,
+            page_size=CHECK_RUN_PAGE_SIZE,
+        ),
+        token,
+        None,
+    )
+    return approvals_conclusion(_check_run_records(document))
+
+
+def _check_run_records(document: object) -> list[object]:
+    if not isinstance(document, Mapping):
+        raise GitHubError(str(document))
+    all_check_runs = document.get(CHECK_RUNS_KEY)
+    if not isinstance(all_check_runs, list):
+        raise GitHubError(str(document))
+    return all_check_runs
+
+
+def _built_request(
+    method: str,
+    url: str,
+    token: str,
+    all_payload_fields: Mapping[str, object] | None,
+) -> urllib.request.Request:
+    return urllib.request.Request(
+        url=url,
+        data=_encoded_body(all_payload_fields),
+        headers=_all_request_headers(token, all_payload_fields),
+        method=method,
+    )
+
+
+def _all_request_headers(
+    token: str, all_payload_fields: Mapping[str, object] | None
+) -> dict[str, str]:
+    all_headers = {
+        ACCEPT_HEADER: GITHUB_ACCEPT_TYPE,
+        API_VERSION_HEADER: GITHUB_API_VERSION,
+        AUTHORIZATION_HEADER: BEARER_PREFIX + token,
+    }
+    if all_payload_fields is not None:
+        all_headers[CONTENT_TYPE_HEADER] = JSON_CONTENT_TYPE
+    return all_headers
+
+
+def _encoded_body(all_payload_fields: Mapping[str, object] | None) -> bytes | None:
+    if all_payload_fields is None:
+        return None
+    return json.dumps(all_payload_fields).encode(UTF8_ENCODING)
+
+
+def _decoded_answer(url: str, status: int, body: bytes) -> object:
+    if status != HTTP_OK:
+        raise GitHubError(REQUEST_FAILED_TEMPLATE.format(url=url, status=status))
+    return json.loads(body.decode(UTF8_ENCODING))
+
+
+def _thread_records_over_rest(
+    slug: str, number: int, token: str
+) -> list[object] | None:
+    try:
+        document = request_json(
+            GET_METHOD,
+            REVIEW_THREADS_ENDPOINT_TEMPLATE.format(
+                api_root=GITHUB_API_ROOT, slug=slug, number=number
+            ),
+            token,
+            None,
+        )
+    except GitHubError:
+        return None
+    return document if isinstance(document, list) else None
+
+
+def _thread_records_over_graphql(slug: str, number: int, token: str) -> list[object]:
+    document = request_json(
+        POST_METHOD,
+        GITHUB_GRAPHQL_ENDPOINT,
+        token,
+        _thread_query_payload(slug, number),
+    )
+    all_records = functools.reduce(
+        functools.partial(_field_at, document), ALL_THREAD_NODE_KEYS, document
+    )
+    if not isinstance(all_records, list):
+        raise GitHubError(str(document))
+    return all_records
+
+
+def _thread_query_payload(slug: str, number: int) -> dict[str, object]:
+    owner, _, name = slug.partition(SLUG_SEPARATOR)
+    return {
+        QUERY_KEY: REVIEW_THREAD_QUERY,
+        VARIABLES_KEY: {
+            OWNER_VARIABLE: owner,
+            NAME_VARIABLE: name,
+            NUMBER_VARIABLE: number,
+            PAGE_SIZE_VARIABLE: REVIEW_THREAD_PAGE_SIZE,
+        },
+    }
+
+
+def _field_at(document: object, all_fields: object, key: str) -> object:
+    if not isinstance(all_fields, Mapping):
+        raise GitHubError(str(document))
+    return all_fields.get(key)

package/scripts/review_closure_model.py

@@ -0,0 +1,360 @@
+"""Decide whether a review finding on a pull request head is answered.
+
+A review bot posts a finding, the agent driving the pull request answers it or
+pushes the fix, and the thread closes. Until then the finding waits. These
+functions read the threads and the approvals conclusion, and name what waits.
+
+::
+
+    thread: a bot comment, nothing after it     -> open
+    thread: a bot comment, then an agent reply  -> closed
+    thread: a bot comment, code since replaced  -> closed
+    thread: a red circle, resolved in silence   -> open
+
+A red circle marks a finding a review states as blocking, so resolution alone
+leaves it open. The reply says what changed, or why the finding stands.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Iterable, Mapping, Sequence
+from dataclasses import dataclass
+
+from dev_env_scripts_constants.review_closure_constants import (
+    ALL_BLOCKING_CONCLUSIONS,
+    ALL_COMMENT_AUTHOR_KEYS,
+    ALL_COMMENT_LIST_KEYS,
+    ALL_OUTDATED_KEYS,
+    ALL_RESOLVED_KEYS,
+    APPROVALS_CHECK_NAME,
+    APPROVALS_OPEN_REASON,
+    AUTHOR_LOGIN_KEY,
+    CHECK_RUN_CONCLUSION_KEY,
+    CHECK_RUN_NAME_KEY,
+    CLOSED_DETAIL,
+    CLOSED_VERDICT_LABEL,
+    COMMENT_BODY_KEY,
+    COMMENT_IDENTIFIER_KEY,
+    COMMENT_IDS_KEY,
+    COMMENT_NODES_KEY,
+    HEAD_KEY,
+    NUMBER_KEY,
+    OPEN_DETAIL_TEMPLATE,
+    OPEN_VERDICT_LABEL,
+    RED_CIRCLE_MARKER,
+    RED_CIRCLE_OPEN_REASON,
+    SHA_KEY,
+    SHORT_SHA_LENGTH,
+    THREAD_PATH_KEY,
+    UNANSWERED_OPEN_REASON,
+    UNNAMED_THREAD_SUBJECT,
+    USER_KEY,
+    VERDICT_LINE_TEMPLATE,
+)
+
+
+@dataclass(frozen=True)
+class ReviewComment:
+    """One comment inside a review thread."""
+
+    author_login: str
+    body: str
+
+
+@dataclass(frozen=True)
+class ReviewThread:
+    """One review thread, as the closure decision reads it."""
+
+    subject: str
+    is_resolved: bool
+    is_outdated: bool
+    all_comments: tuple[ReviewComment, ...]
+
+
+@dataclass(frozen=True)
+class OpenFinding:
+    """One finding that still waits on the agent driving the pull request."""
+
+    subject: str
+    reason: str
+
+
+def carries_red_circle(thread: ReviewThread) -> bool:
+    """Say whether a thread opens with a blocking finding.
+
+    Args:
+        thread: The review thread to read.
+
+    Returns:
+        True when its first comment carries the red circle a review marks a
+        blocking finding with.
+    """
+    if not thread.all_comments:
+        return False
+    return RED_CIRCLE_MARKER in thread.all_comments[0].body
+
+
+def has_driver_reply(thread: ReviewThread, all_driver_logins: frozenset[str]) -> bool:
+    """Say whether the driving agent answered a thread.
+
+    Args:
+        thread: The review thread to read.
+        all_driver_logins: The logins whose comments count as the answer.
+
+    Returns:
+        True when any comment after the first carries one of those logins.
+    """
+    return any(
+        each_comment.author_login in all_driver_logins
+        for each_comment in thread.all_comments[1:]
+    )
+
+
+def opened_by_driver(thread: ReviewThread, all_driver_logins: frozenset[str]) -> bool:
+    """Say whether the driving agent started a thread itself.
+
+    Args:
+        thread: The review thread to read.
+        all_driver_logins: The logins that count as the driving agent.
+
+    Returns:
+        True when its first comment carries one of those logins.
+    """
+    return bool(thread.all_comments) and (
+        thread.all_comments[0].author_login in all_driver_logins
+    )
+
+
+def thread_finding(
+    thread: ReviewThread, all_driver_logins: frozenset[str]
+) -> OpenFinding | None:
+    """Decide whether one review thread still waits on the driving agent.
+
+    Args:
+        thread: The review thread to judge.
+        all_driver_logins: The logins whose comments count as the answer.
+
+    Returns:
+        The finding this thread leaves open, or None when it is closed.
+    """
+    if thread.is_outdated:
+        return None
+    if opened_by_driver(thread, all_driver_logins):
+        return None
+    if has_driver_reply(thread, all_driver_logins):
+        return None
+    if carries_red_circle(thread):
+        return OpenFinding(subject=thread.subject, reason=RED_CIRCLE_OPEN_REASON)
+    if thread.is_resolved:
+        return None
+    return OpenFinding(subject=thread.subject, reason=UNANSWERED_OPEN_REASON)
+
+
+def all_open_findings(
+    all_threads: Iterable[ReviewThread],
+    all_driver_logins: frozenset[str],
+    approvals_conclusion_text: str | None,
+) -> tuple[OpenFinding, ...]:
+    """Collect every finding on a pull request head that waits on its agent.
+
+    Args:
+        all_threads: The review threads on the pull request.
+        all_driver_logins: The logins whose comments count as the answer.
+        approvals_conclusion_text: What the Claude Approvals check run on the
+            head concluded, or None where that check does not run.
+
+    Returns:
+        One finding per open review thread, then the approvals finding when
+        that check reports a blocking row on this commit.
+    """
+    all_findings = [
+        each_finding
+        for each_finding in (
+            thread_finding(each_thread, all_driver_logins)
+            for each_thread in all_threads
+        )
+        if each_finding is not None
+    ]
+    if approvals_conclusion_text in ALL_BLOCKING_CONCLUSIONS:
+        all_findings.append(
+            OpenFinding(subject=APPROVALS_CHECK_NAME, reason=APPROVALS_OPEN_REASON)
+        )
+    return tuple(all_findings)
+
+
+def head_sha(all_pull_request_fields: Mapping[str, object]) -> str:
+    """Read the head commit a pull request reports.
+
+    Args:
+        all_pull_request_fields: The pull request as GitHub reports it.
+
+    Returns:
+        The head commit, or an empty string when the field is absent.
+    """
+    all_head_fields = all_pull_request_fields.get(HEAD_KEY)
+    if isinstance(all_head_fields, Mapping):
+        return str(all_head_fields.get(SHA_KEY) or "")
+    return ""
+
+
+def verdict_line(
+    slug: str,
+    all_pull_request_fields: Mapping[str, object],
+    all_findings: Sequence[OpenFinding],
+) -> str:
+    """Build the one line the command prints for a pull request.
+
+    Args:
+        slug: The repository as ``owner/name``.
+        all_pull_request_fields: The pull request the verdict describes.
+        all_findings: The findings that still wait on the driving agent.
+
+    Returns:
+        A line naming the verdict, the pull request, its head commit, and
+        either the closed detail or how many findings wait.
+    """
+    return VERDICT_LINE_TEMPLATE.format(
+        label=OPEN_VERDICT_LABEL if all_findings else CLOSED_VERDICT_LABEL,
+        slug=slug,
+        number=all_pull_request_fields.get(NUMBER_KEY),
+        sha=head_sha(all_pull_request_fields)[:SHORT_SHA_LENGTH],
+        detail=_verdict_detail(all_findings),
+    )
+
+
+def _verdict_detail(all_findings: Sequence[OpenFinding]) -> str:
+    if not all_findings:
+        return CLOSED_DETAIL
+    return OPEN_DETAIL_TEMPLATE.format(count=len(all_findings))
+
+
+def driver_logins(
+    all_pull_request_fields: Mapping[str, object],
+    all_extra_logins: Iterable[str],
+) -> frozenset[str]:
+    """Collect the logins whose comments answer a finding.
+
+    Args:
+        all_pull_request_fields: The pull request, carrying the account that
+            opened it.
+        all_extra_logins: Logins named on the command line.
+
+    Returns:
+        The account that opened the pull request, with every extra login.
+    """
+    all_logins = {each_login for each_login in all_extra_logins if each_login}
+    all_author_fields = all_pull_request_fields.get(USER_KEY)
+    if isinstance(all_author_fields, Mapping):
+        author_login = all_author_fields.get(AUTHOR_LOGIN_KEY)
+        if author_login:
+            all_logins.add(str(author_login))
+    return frozenset(all_logins)
+
+
+def parse_thread(
+    all_thread_fields: Mapping[str, object],
+    all_comment_records_by_id: Mapping[object, Mapping[str, object]] | None = None,
+) -> ReviewThread:
+    """Read one review thread from either route's answer.
+
+    The GraphQL answer nests each thread's comments. The session route names
+    them by identifier instead, so that route's caller passes the comments it
+    read for the pull request and this joins the two.
+
+    Args:
+        all_thread_fields: The thread as the REST route or the GraphQL query
+            reports it.
+        all_comment_records_by_id: The pull request's review comments, keyed
+            by identifier, for a thread that names its comments by identifier.
+
+    Returns:
+        The thread in the shape the closure decision reads.
+    """
+    return ReviewThread(
+        subject=str(all_thread_fields.get(THREAD_PATH_KEY) or UNNAMED_THREAD_SUBJECT),
+        is_resolved=_any_flag(all_thread_fields, ALL_RESOLVED_KEYS),
+        is_outdated=_any_flag(all_thread_fields, ALL_OUTDATED_KEYS),
+        all_comments=tuple(
+            _parse_comment(each_record)
+            for each_record in _comment_records(
+                all_thread_fields, all_comment_records_by_id or {}
+            )
+        ),
+    )
+
+
+def comment_records_by_id(
+    all_comment_records: Iterable[object],
+) -> dict[object, Mapping[str, object]]:
+    """Key a pull request's review comments by their identifiers.
+
+    Args:
+        all_comment_records: The review comments GitHub reports.
+
+    Returns:
+        Each comment under its identifier.
+    """
+    return {
+        each_record[COMMENT_IDENTIFIER_KEY]: each_record
+        for each_record in all_comment_records
+        if isinstance(each_record, Mapping) and COMMENT_IDENTIFIER_KEY in each_record
+    }
+
+
+def approvals_conclusion(all_check_runs: Iterable[object]) -> str | None:
+    """Find what the Claude Approvals check reports on a commit.
+
+    Args:
+        all_check_runs: The check runs GitHub reports for the head commit.
+
+    Returns:
+        That check run's conclusion, or None where the repository does not
+        run it and where it has not concluded.
+    """
+    for each_run in all_check_runs:
+        if (
+            isinstance(each_run, Mapping)
+            and each_run.get(CHECK_RUN_NAME_KEY) == APPROVALS_CHECK_NAME
+        ):
+            conclusion = each_run.get(CHECK_RUN_CONCLUSION_KEY)
+            return None if conclusion is None else str(conclusion)
+    return None
+
+
+def _comment_records(
+    all_thread_fields: Mapping[str, object],
+    all_comment_records_by_id: Mapping[object, Mapping[str, object]],
+) -> list[Mapping[str, object]]:
+    all_identifiers = all_thread_fields.get(COMMENT_IDS_KEY)
+    if isinstance(all_identifiers, list):
+        return [
+            all_comment_records_by_id[each_identifier]
+            for each_identifier in all_identifiers
+            if each_identifier in all_comment_records_by_id
+        ]
+    for each_key in ALL_COMMENT_LIST_KEYS:
+        found = all_thread_fields.get(each_key)
+        if isinstance(found, Mapping):
+            found = found.get(COMMENT_NODES_KEY)
+        if isinstance(found, list):
+            return [each for each in found if isinstance(each, Mapping)]
+    return []
+
+
+def _parse_comment(all_comment_fields: Mapping[str, object]) -> ReviewComment:
+    return ReviewComment(
+        author_login=_comment_author_login(all_comment_fields),
+        body=str(all_comment_fields.get(COMMENT_BODY_KEY) or ""),
+    )
+
+
+def _comment_author_login(all_comment_fields: Mapping[str, object]) -> str:
+    for each_key in ALL_COMMENT_AUTHOR_KEYS:
+        all_author_fields = all_comment_fields.get(each_key)
+        if isinstance(all_author_fields, Mapping):
+            return str(all_author_fields.get(AUTHOR_LOGIN_KEY) or "")
+    return ""
+
+
+def _any_flag(all_fields: Mapping[str, object], all_keys: Sequence[str]) -> bool:
+    return any(all_fields.get(each_key) for each_key in all_keys)