claude-dev-env 4.3.0 → 7.1.0

package/scripts/pr_verification/github.py

@@ -0,0 +1,137 @@
+from __future__ import annotations
+
+import json
+import time
+from collections.abc import Callable
+from pathlib import Path
+
+from . import github_api, github_transport
+from .config.constants import (
+    APP_EXPIRATION_CLAIM,
+    APP_ISSUED_AT_CLAIM,
+    APP_ISSUER_CLAIM,
+    APP_JWT_ALGORITHM,
+    CONTENTS_PERMISSION_KEY,
+    HTTP_CREATED,
+    INSTALLATION_TOKEN_ENDPOINT_TEMPLATE,
+    ISSUES_PERMISSION_KEY,
+    PERMISSIONS_KEY,
+    PULL_REQUESTS_PERMISSION_KEY,
+    READ_PERMISSION,
+    REPOSITORIES_KEY,
+    STATUSES_PERMISSION_KEY,
+    TOKEN_KEY,
+    TOKEN_RESOURCE_NAME,
+    UTF8_ENCODING,
+    WRITE_PERMISSION,
+)
+from .config.timing import (
+    APP_JWT_CLOCK_SKEW_SECONDS,
+    APP_JWT_LIFETIME_SECONDS,
+)
+from .github_api import authorized_headers, request_json
+from .github_parsing import require_mapping, require_text
+from .github_transport import (
+    HttpRequester,
+    JwtEncoder,
+    encode_app_jwt,
+    request_http,
+)
+from .model import RepositorySettings
+
+GitHubApi = github_api.GitHubApi
+GitHubError = github_api.GitHubError
+HttpReply = github_transport.HttpReply
+
+
+def _build_installation_token_body(
+    repository: RepositorySettings, should_write_issue_labels: bool
+) -> bytes:
+    all_permissions = {
+        CONTENTS_PERMISSION_KEY: READ_PERMISSION,
+        PULL_REQUESTS_PERMISSION_KEY: READ_PERMISSION,
+        STATUSES_PERMISSION_KEY: WRITE_PERMISSION,
+    }
+    if should_write_issue_labels:
+        all_permissions[ISSUES_PERMISSION_KEY] = WRITE_PERMISSION
+        all_permissions[PULL_REQUESTS_PERMISSION_KEY] = WRITE_PERMISSION
+    token_request = {
+        REPOSITORIES_KEY: [repository.name],
+        PERMISSIONS_KEY: all_permissions,
+    }
+    return json.dumps(token_request).encode(UTF8_ENCODING)
+
+
+class GitHubAppAuthenticator:
+    def __init__(
+        self,
+        api_url: str,
+        app_id: int,
+        installation_id: int,
+        private_key_path: Path,
+        requester: HttpRequester = request_http,
+        jwt_encoder: JwtEncoder = encode_app_jwt,
+        clock: Callable[[], float] = time.time,
+    ) -> None:
+        self.api_url = api_url
+        self.app_id = app_id
+        self.installation_id = installation_id
+        self.private_key_path = private_key_path
+        self.requester = requester
+        self.jwt_encoder = jwt_encoder
+        self.clock = clock
+
+    def issue_repository_api(
+        self,
+        repository: RepositorySettings,
+        *,
+        should_write_issue_labels: bool = False,
+    ) -> GitHubApi:
+        """Create a repository-scoped API client.
+
+        Args:
+            repository: Repository to scope.
+
+        Returns:
+            Authenticated API client.
+        """
+        installation_token = self._request_repository_token(
+            repository, should_write_issue_labels
+        )
+        return GitHubApi(self.api_url, installation_token, self.requester)
+
+    def _request_repository_token(
+        self, repository: RepositorySettings, should_write_issue_labels: bool
+    ) -> str:
+        app_token = self.create_app_token()
+        endpoint = INSTALLATION_TOKEN_ENDPOINT_TEMPLATE.format(
+            installation_id=self.installation_id
+        )
+        request_body = _build_installation_token_body(
+            repository, should_write_issue_labels
+        )
+        token_payload = request_json(
+            self.requester,
+            "POST",
+            self.api_url + endpoint,
+            authorized_headers(app_token),
+            request_body,
+            HTTP_CREATED,
+        )
+        token_mapping = require_mapping(token_payload, TOKEN_RESOURCE_NAME)
+        return require_text(token_mapping, TOKEN_KEY, TOKEN_RESOURCE_NAME)
+
+    def create_app_token(self) -> str:
+        """Create an app JWT for token exchange.
+
+        Returns:
+            The encoded app token.
+        """
+        current_time = int(self.clock())
+        all_claims: dict[str, int | str] = {
+            APP_ISSUER_CLAIM: str(self.app_id),
+            APP_ISSUED_AT_CLAIM: current_time - APP_JWT_CLOCK_SKEW_SECONDS,
+            APP_EXPIRATION_CLAIM: current_time + APP_JWT_LIFETIME_SECONDS,
+        }
+        private_key = self.private_key_path.read_text(encoding=UTF8_ENCODING)
+        return self.jwt_encoder(all_claims, private_key, APP_JWT_ALGORITHM)

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))