claude-dev-env 7.0.0 → 7.2.0

package/scripts/pr_verification/github_api.py

@@ -0,0 +1,376 @@
+from __future__ import annotations
+
+import json
+
+from .branch_refs import (
+    GetJson,
+    _resolve_candidate_base_shas,
+    replace_candidate_base_sha,
+)
+from .config.constants import (
+    ACCEPT_HEADER,
+    API_VERSION_HEADER,
+    AUTHORIZATION_HEADER,
+    BEARER_PREFIX,
+    COMMIT_ENDPOINT_TEMPLATE,
+    COMMIT_PARENTS_KEY,
+    CONTENT_TYPE_HEADER,
+    GITHUB_ACCEPT_TYPE,
+    GITHUB_API_VERSION,
+    GITHUB_JSON_ERROR_TEMPLATE,
+    GITHUB_PAGE_SIZE,
+    GITHUB_REQUEST_ERROR_TEMPLATE,
+    GITHUB_SHAPE_ERROR_TEMPLATE,
+    HTTP_CREATED,
+    HTTP_NO_CONTENT,
+    HTTP_OK,
+    ISSUE_LABELS_ENDPOINT_TEMPLATE,
+    ISSUE_LABELS_KEY,
+    JSON_CONTENT_TYPE,
+    PULL_ENDPOINT_TEMPLATE,
+    PULL_SHA_KEY,
+    PULLS_ENDPOINT_TEMPLATE,
+    STATUS_CONTEXT_KEY,
+    STATUS_DESCRIPTION_KEY,
+    STATUS_ENDPOINT_TEMPLATE,
+    STATUS_STATE_KEY,
+    UTF8_ENCODING,
+)
+from .github_labels import DeleteLabel, ReadLabelsPage, remove_label_if_present
+from .github_parsing import (
+    GitHubError,
+    _parse_pull_candidates,
+    _require_pull_list,
+    parse_candidate,
+    require_mapping,
+    require_text,
+)
+from .github_transport import HttpReply, HttpRequester, request_http
+from .model import PullRequestCandidate, RepositorySettings, StatusState
+
+
+def _build_pull_page_endpoint(repository: RepositorySettings, page: int) -> str:
+    return PULLS_ENDPOINT_TEMPLATE.format(
+        repository=repository.slug,
+        page_size=GITHUB_PAGE_SIZE,
+        page=page,
+    )
+
+
+def _build_status_body(state: StatusState, context: str, description: str) -> bytes:
+    status_payload = {
+        STATUS_STATE_KEY: state.value,
+        STATUS_CONTEXT_KEY: context,
+        STATUS_DESCRIPTION_KEY: description,
+    }
+    return json.dumps(status_payload).encode(UTF8_ENCODING)
+
+
+def _list_open_candidates(
+    get_json: GetJson,
+    repository: RepositorySettings,
+    should_require_merge_commit: bool,
+) -> tuple[PullRequestCandidate, ...]:
+    all_candidates: list[PullRequestCandidate] = []
+    page = 1
+    while True:
+        endpoint = _build_pull_page_endpoint(repository, page)
+        raw_page = _require_pull_list(get_json(endpoint))
+        all_candidates.extend(
+            _parse_pull_candidates(
+                repository.slug,
+                raw_page,
+                should_require_merge_commit,
+            )
+        )
+        if len(raw_page) < GITHUB_PAGE_SIZE:
+            return _resolve_candidate_base_shas(
+                all_candidates,
+                repository,
+                get_json,
+                should_require_merge_commit,
+            )
+        page += 1
+
+
+class GitHubApi:
+    def __init__(
+        self,
+        api_url: str,
+        installation_token: str,
+        requester: HttpRequester = request_http,
+    ) -> None:
+        self.api_url = api_url
+        self.installation_token = installation_token
+        self.requester = requester
+
+    def list_open_candidates(
+        self,
+        repository: RepositorySettings,
+        *,
+        should_require_merge_commit: bool = True,
+    ) -> tuple[PullRequestCandidate, ...]:
+        """List recognized pull requests.
+
+        Args:
+            repository: Repository to query.
+
+        Returns:
+            Recognized pull requests.
+
+        Raises:
+            GitHubError: If GitHub data is invalid.
+        """
+        return _list_open_candidates(
+            self.get_json,
+            repository,
+            should_require_merge_commit,
+        )
+
+    def get_candidate(
+        self,
+        repository: RepositorySettings,
+        pull_request_number: int,
+        *,
+        should_require_merge_commit: bool = True,
+    ) -> PullRequestCandidate:
+        """Read one pull request.
+
+        Args:
+            repository: Repository to query.
+
+        Returns:
+            Pull request metadata.
+        """
+        endpoint = PULL_ENDPOINT_TEMPLATE.format(
+            repository=repository.slug,
+            pull_number=pull_request_number,
+        )
+        candidate = parse_candidate(
+            repository.slug,
+            self.get_json(endpoint),
+            should_require_merge_commit=should_require_merge_commit,
+        )
+        if should_require_merge_commit:
+            return candidate
+        return replace_candidate_base_sha(candidate, repository, self.get_json)
+
+    def get_commit_parents(
+        self, repository: RepositorySettings, commit_sha: str
+    ) -> tuple[str, ...]:
+        """Read commit parent SHAs.
+
+        Args:
+            repository: Repository to query.
+
+        Returns:
+            Parent commit SHAs.
+
+        Raises:
+            GitHubError: If GitHub data is invalid.
+        """
+        endpoint = COMMIT_ENDPOINT_TEMPLATE.format(
+            repository=repository.slug,
+            commit_sha=commit_sha,
+        )
+        commit_mapping = require_mapping(self.get_json(endpoint), "commit")
+        raw_parents = commit_mapping.get(COMMIT_PARENTS_KEY)
+        if not isinstance(raw_parents, list):
+            raise GitHubError(GITHUB_SHAPE_ERROR_TEMPLATE.format(resource="commit"))
+        return tuple(
+            require_text(require_mapping(each_parent, "commit"), PULL_SHA_KEY, "commit")
+            for each_parent in raw_parents
+        )
+
+    def post_status(
+        self,
+        repository: RepositorySettings,
+        commit_sha: str,
+        state: StatusState,
+        context: str,
+        description: str,
+    ) -> None:
+        """Post one advisory commit status.
+
+        Args:
+            commit_sha: Commit receiving the status.
+
+        Raises:
+            GitHubError: If GitHub rejects the request.
+        """
+        endpoint = STATUS_ENDPOINT_TEMPLATE.format(
+            repository=repository.slug,
+            commit_sha=commit_sha,
+        )
+        request_body = _build_status_body(state, context, description)
+        request_json(
+            self.requester,
+            "POST",
+            self.api_url + endpoint,
+            authorized_headers(self.installation_token),
+            request_body,
+            HTTP_CREATED,
+        )
+
+    def add_label(
+        self,
+        repository: RepositorySettings,
+        pull_request_number: int,
+        label: str,
+    ) -> None:
+        """Add one label to a pull request.
+
+        Args:
+            label: Label to add.
+
+        Raises:
+            GitHubError: If GitHub rejects the request.
+        """
+        endpoint = ISSUE_LABELS_ENDPOINT_TEMPLATE.format(
+            repository=repository.slug,
+            pull_number=pull_request_number,
+        )
+        request_body = json.dumps({ISSUE_LABELS_KEY: [label]}).encode(UTF8_ENCODING)
+        request_json(
+            self.requester,
+            "POST",
+            self.api_url + endpoint,
+            authorized_headers(self.installation_token),
+            request_body,
+            HTTP_OK,
+        )
+
+    def remove_label(
+        self,
+        repository: RepositorySettings,
+        pull_request_number: int,
+        label: str,
+    ) -> None:
+        """Remove one label from a pull request.
+
+        Args:
+            repository: Repository containing the pull request.
+            pull_request_number: Pull request number.
+            label: Label to remove.
+
+        Raises:
+            GitHubError: If GitHub rejects the request.
+        """
+        all_headers = authorized_headers(self.installation_token)
+        remove_label_if_present(
+            _labels_page_reader(self.requester, self.api_url, all_headers),
+            _label_deleter(self.requester, self.api_url, all_headers),
+            repository,
+            pull_request_number,
+            label,
+        )
+
+    def get_json(self, endpoint: str) -> object:
+        """Read one JSON resource.
+
+        Args:
+            endpoint: Repository API path.
+
+        Returns:
+            Decoded JSON payload.
+        """
+        return request_json(
+            self.requester,
+            "GET",
+            self.api_url + endpoint,
+            authorized_headers(self.installation_token),
+            None,
+            HTTP_OK,
+        )
+
+
+def authorized_headers(token: str) -> dict[str, str]:
+    """Build headers for an installation token request.
+
+    Args:
+        token: Installation token.
+
+    Returns:
+        Request headers.
+    """
+    return {
+        AUTHORIZATION_HEADER: BEARER_PREFIX + token,
+        ACCEPT_HEADER: GITHUB_ACCEPT_TYPE,
+        CONTENT_TYPE_HEADER: JSON_CONTENT_TYPE,
+        API_VERSION_HEADER: GITHUB_API_VERSION,
+    }
+
+
+def _labels_page_reader(
+    requester: HttpRequester, api_url: str, all_headers: dict[str, str]
+) -> ReadLabelsPage:
+    def read_labels_page(endpoint: str) -> object:
+        return request_json(
+            requester, "GET", api_url + endpoint, all_headers, None, HTTP_OK
+        )
+
+    return read_labels_page
+
+
+def _label_deleter(
+    requester: HttpRequester, api_url: str, all_headers: dict[str, str]
+) -> DeleteLabel:
+    def delete_label(endpoint: str) -> None:
+        _delete_label(requester, api_url + endpoint, all_headers)
+
+    return delete_label
+
+
+def _delete_label(
+    requester: HttpRequester, url: str, all_headers: dict[str, str]
+) -> None:
+    reply = requester("DELETE", url, all_headers, None)
+    if reply.status_code in (HTTP_OK, HTTP_NO_CONTENT):
+        return
+    raise GitHubError(
+        GITHUB_REQUEST_ERROR_TEMPLATE.format(
+            method="DELETE", url=url, status_code=reply.status_code
+        )
+    )
+
+
+def _decode_json_reply(reply: HttpReply, url: str) -> object:
+    try:
+        return json.loads(reply.body.decode(UTF8_ENCODING))
+    except (UnicodeDecodeError, json.JSONDecodeError) as error:
+        raise GitHubError(GITHUB_JSON_ERROR_TEMPLATE.format(url=url)) from error
+
+
+def _raise_unexpected_status(method: str, url: str, status_code: int) -> None:
+    raise GitHubError(
+        GITHUB_REQUEST_ERROR_TEMPLATE.format(
+            method=method, url=url, status_code=status_code
+        )
+    )
+
+
+def request_json(
+    requester: HttpRequester,
+    method: str,
+    url: str,
+    all_headers: dict[str, str],
+    body: bytes | None,
+    expected_status: int,
+) -> object:
+    """Send a request and decode JSON.
+    Args:
+        requester: Request function.
+        method: HTTP method.
+        url: Request URL.
+        all_headers: Headers.
+        body: Optional body.
+        expected_status: Required status.
+    Returns:
+        Decoded JSON payload.
+    Raises:
+        GitHubError: If status or JSON is invalid.
+    """
+    reply = requester(method, url, all_headers, body)
+    if reply.status_code != expected_status:
+        _raise_unexpected_status(method, url, reply.status_code)
+    return _decode_json_reply(reply, url)

package/scripts/pr_verification/github_labels.py

@@ -0,0 +1,88 @@
+from __future__ import annotations
+
+import urllib.parse
+from collections.abc import Callable
+
+from .config.constants import (
+    GITHUB_PAGE_SIZE,
+    ISSUE_LABEL_ENDPOINT_TEMPLATE,
+    ISSUE_LABELS_PAGE_ENDPOINT_TEMPLATE,
+)
+from .model import RepositorySettings
+
+ReadLabelsPage = Callable[[str], object]
+DeleteLabel = Callable[[str], None]
+
+
+def _label_is_present(all_labels: object, label: str) -> bool:
+    if not isinstance(all_labels, list):
+        return False
+    return any(
+        isinstance(each_label, dict) and each_label.get("name") == label
+        for each_label in all_labels
+    )
+
+
+def _label_page_endpoint(
+    repository: RepositorySettings, pull_request_number: int, page: int
+) -> str:
+    return ISSUE_LABELS_PAGE_ENDPOINT_TEMPLATE.format(
+        repository=repository.slug,
+        pull_number=pull_request_number,
+        page_size=GITHUB_PAGE_SIZE,
+        page=page,
+    )
+
+
+def _issue_label_endpoint(
+    repository: RepositorySettings, pull_request_number: int, label: str
+) -> str:
+    return ISSUE_LABEL_ENDPOINT_TEMPLATE.format(
+        repository=repository.slug,
+        pull_number=pull_request_number,
+        label=urllib.parse.quote(label, safe=""),
+    )
+
+
+def _label_is_on_any_page(
+    read_labels_page: ReadLabelsPage,
+    repository: RepositorySettings,
+    pull_request_number: int,
+    label: str,
+) -> bool:
+    page = 1
+    while True:
+        raw_page = read_labels_page(
+            _label_page_endpoint(repository, pull_request_number, page)
+        )
+        if _label_is_present(raw_page, label):
+            return True
+        if not isinstance(raw_page, list) or len(raw_page) < GITHUB_PAGE_SIZE:
+            return False
+        page += 1
+
+
+def remove_label_if_present(
+    read_labels_page: ReadLabelsPage,
+    delete_label: DeleteLabel,
+    repository: RepositorySettings,
+    pull_request_number: int,
+    label: str,
+) -> None:
+    """Delete one label from a pull request when a labels page still carries it.
+
+    Pages /issues/{n}/labels at per_page=100 until the label is found or a
+    short page ends the walk.
+
+    Args:
+        read_labels_page: Reads one labels endpoint and returns its parsed body.
+        delete_label: Deletes the label the endpoint names.
+        repository: Repository holding the pull request.
+        pull_request_number: Pull request number.
+        label: Label to remove.
+    """
+    if not _label_is_on_any_page(
+        read_labels_page, repository, pull_request_number, label
+    ):
+        return
+    delete_label(_issue_label_endpoint(repository, pull_request_number, label))

package/scripts/pr_verification/github_parsing.py

@@ -0,0 +1,182 @@
+from __future__ import annotations
+
+from collections.abc import Mapping
+
+from .config.constants import (
+    GITHUB_SHAPE_ERROR_TEMPLATE,
+    PULL_BASE_KEY,
+    PULL_DRAFT_KEY,
+    PULL_HEAD_KEY,
+    PULL_LIST_RESOURCE_NAME,
+    PULL_MERGE_SHA_KEY,
+    PULL_NUMBER_KEY,
+    PULL_REF_KEY,
+    PULL_RESOURCE_NAME,
+    PULL_SHA_KEY,
+)
+from .model import PullRequestCandidate
+
+
+class GitHubError(RuntimeError):
+    """Raised when GitHub metadata has an invalid shape."""
+
+
+def _require_pull_list(all_pull_entries: object) -> list[object]:
+    if isinstance(all_pull_entries, list):
+        return all_pull_entries
+    raise GitHubError(
+        GITHUB_SHAPE_ERROR_TEMPLATE.format(resource=PULL_LIST_RESOURCE_NAME)
+    )
+
+
+def _parse_pull_candidates(
+    repository_slug: str,
+    all_pull_entries: list[object],
+    should_require_merge_commit: bool,
+) -> tuple[PullRequestCandidate, ...]:
+    all_candidates: list[PullRequestCandidate] = []
+    for each_pull in all_pull_entries:
+        maybe_candidate = parse_recognized_candidate(
+            repository_slug,
+            each_pull,
+            should_require_merge_commit=should_require_merge_commit,
+        )
+        if maybe_candidate is not None:
+            all_candidates.append(maybe_candidate)
+    return tuple(all_candidates)
+
+
+def _read_pull_branches(
+    all_pull_fields: Mapping[str, object],
+) -> tuple[Mapping[str, object], Mapping[str, object]]:
+    base = require_mapping(all_pull_fields.get(PULL_BASE_KEY), PULL_RESOURCE_NAME)
+    head = require_mapping(all_pull_fields.get(PULL_HEAD_KEY), PULL_RESOURCE_NAME)
+    return base, head
+
+
+def _read_pull_draft(all_pull_fields: Mapping[str, object]) -> bool:
+    is_draft = all_pull_fields.get(PULL_DRAFT_KEY)
+    if isinstance(is_draft, bool):
+        return is_draft
+    raise GitHubError(GITHUB_SHAPE_ERROR_TEMPLATE.format(resource=PULL_RESOURCE_NAME))
+
+
+def parse_candidate(
+    repository_slug: str,
+    raw_pull: object,
+    *,
+    should_require_merge_commit: bool,
+) -> PullRequestCandidate:
+    """Parse pull request metadata.
+
+    Args:
+        repository_slug: Repository slug.
+        raw_pull: GitHub pull JSON.
+
+    Returns:
+        Parsed pull request.
+
+    Raises:
+        GitHubError: If metadata is invalid.
+    """
+    pull = require_mapping(raw_pull, PULL_RESOURCE_NAME)
+    base, head = _read_pull_branches(pull)
+    pull_number = require_positive_integer(pull, PULL_NUMBER_KEY, PULL_RESOURCE_NAME)
+    return PullRequestCandidate(
+        repository_slug=repository_slug,
+        pull_request_number=pull_number,
+        base_ref=require_text(base, PULL_REF_KEY, PULL_RESOURCE_NAME),
+        base_sha=require_text(base, PULL_SHA_KEY, PULL_RESOURCE_NAME),
+        head_sha=require_text(head, PULL_SHA_KEY, PULL_RESOURCE_NAME),
+        merge_sha=_read_merge_sha(pull, should_require_merge_commit),
+        is_draft=_read_pull_draft(pull),
+    )
+
+
+def _read_merge_sha(
+    all_pull_fields: Mapping[str, object],
+    should_require_merge_commit: bool,
+) -> str:
+    merge_sha = all_pull_fields.get(PULL_MERGE_SHA_KEY)
+    if merge_sha is None and not should_require_merge_commit:
+        return ""
+    if not isinstance(merge_sha, str) or not merge_sha:
+        raise GitHubError(
+            GITHUB_SHAPE_ERROR_TEMPLATE.format(resource=PULL_RESOURCE_NAME)
+        )
+    return merge_sha
+
+
+def parse_recognized_candidate(
+    repository_slug: str,
+    raw_pull: object,
+    *,
+    should_require_merge_commit: bool = True,
+) -> PullRequestCandidate | None:
+    """Parse a pull request with a merge commit.
+
+    Args:
+        repository_slug: Repository slug.
+        raw_pull: GitHub pull JSON.
+
+    Returns:
+        Parsed pull request or None.
+    """
+    pull = require_mapping(raw_pull, PULL_RESOURCE_NAME)
+    if not should_require_merge_commit:
+        return parse_candidate(
+            repository_slug,
+            pull,
+            should_require_merge_commit=False,
+        )
+    if pull.get(PULL_MERGE_SHA_KEY) is None:
+        return None
+    return parse_candidate(repository_slug, pull, should_require_merge_commit=True)
+
+
+def require_mapping(raw_payload: object, resource: str) -> Mapping[str, object]:
+    if not isinstance(raw_payload, Mapping):
+        raise GitHubError(GITHUB_SHAPE_ERROR_TEMPLATE.format(resource=resource))
+    return raw_payload
+
+
+def require_text(
+    all_payload_fields: Mapping[str, object], field_name: str, resource: str
+) -> str:
+    """Read required text from a JSON object.
+
+    Args:
+        all_payload_fields: JSON object.
+
+    Returns:
+        Required text.
+
+    Raises:
+        GitHubError: If the field is absent.
+    """
+    field_text = all_payload_fields.get(field_name)
+    if not isinstance(field_text, str) or not field_text:
+        raise GitHubError(GITHUB_SHAPE_ERROR_TEMPLATE.format(resource=resource))
+    return field_text
+
+
+def require_positive_integer(
+    all_payload_fields: Mapping[str, object], field_name: str, resource: str
+) -> int:
+    """Read a required positive integer.
+
+    Args:
+        all_payload_fields: JSON object.
+
+    Returns:
+        Required integer.
+
+    Raises:
+        GitHubError: If the field is invalid.
+    """
+    field_integer = all_payload_fields.get(field_name)
+    if isinstance(field_integer, bool) or not isinstance(field_integer, int):
+        raise GitHubError(GITHUB_SHAPE_ERROR_TEMPLATE.format(resource=resource))
+    if field_integer < 1:
+        raise GitHubError(GITHUB_SHAPE_ERROR_TEMPLATE.format(resource=resource))
+    return field_integer