From 6b7e5a00031e8e4af89d1091d8c548bec57beab7 Mon Sep 17 00:00:00 2001 From: Carlos Bacelar Date: Mon, 9 Nov 2026 17:58:03 -0300 Subject: [PATCH 1/3] feat(tools-github-kit): create, check and merge pull requests through gh --- kits/registry.json | 6 + kits/tools-github-kit/README.md | 58 ++ kits/tools-github-kit/kit.yaml | 34 + kits/tools-github-kit/pytest.ini | 2 + .../python/beddel_tools_github/__init__.py | 17 + .../python/beddel_tools_github/py.typed | 0 .../python/beddel_tools_github/tools.py | 654 ++++++++++++++++++ kits/tools-github-kit/tests/__init__.py | 0 kits/tools-github-kit/tests/conftest.py | 55 ++ kits/tools-github-kit/tests/test_tools.py | 622 +++++++++++++++++ 10 files changed, 1448 insertions(+) create mode 100644 kits/tools-github-kit/README.md create mode 100644 kits/tools-github-kit/kit.yaml create mode 100644 kits/tools-github-kit/pytest.ini create mode 100644 kits/tools-github-kit/python/beddel_tools_github/__init__.py create mode 100644 kits/tools-github-kit/python/beddel_tools_github/py.typed create mode 100644 kits/tools-github-kit/python/beddel_tools_github/tools.py create mode 100644 kits/tools-github-kit/tests/__init__.py create mode 100644 kits/tools-github-kit/tests/conftest.py create mode 100644 kits/tools-github-kit/tests/test_tools.py diff --git a/kits/registry.json b/kits/registry.json index 9de1b0e4..943d8699 100644 --- a/kits/registry.json +++ b/kits/registry.json @@ -251,6 +251,12 @@ "description": "Typed Git operations for Beddel workflows", "category": "tools" }, + { + "name": "tools-github-kit", + "version": "0.1.0", + "description": "Typed GitHub pull request operations through the gh CLI", + "category": "tools" + }, { "name": "tools-http-kit", "version": "0.1.0", diff --git a/kits/tools-github-kit/README.md b/kits/tools-github-kit/README.md new file mode 100644 index 00000000..a28bd466 --- /dev/null +++ b/kits/tools-github-kit/README.md @@ -0,0 +1,58 @@ +# tools-github-kit + +Typed async GitHub pull request operations through the machine's existing `gh` +login. The kit runs explicit `gh` argv in the supplied repository and never +stores or receives credentials. + +## Tools + +| Tool | Purpose | +|------|---------| +| `github_pr_create_or_reuse` | Create one open pull request or reuse the sole matching request | +| `github_pr_checks_wait` | Poll the pull request check rollup until it passes, fails, or times out | +| `github_pr_merge` | Merge one open, checked pull request with a pinned head SHA | + +`github_pr_create_or_reuse` accepts a branch, base branch, story key, spec +path, Change id, and revision. It invokes `gh pr list` and, when needed, +`gh pr create --head ... --base ... --title ... --body ...`, then lists again. +The generated body contains only these references: + +```text +Story: +Spec: +Change: +Revision: +``` + +`github_pr_checks_wait` invokes `gh pr view --json +number,state,headRefOid,statusCheckRollup`. A configured check is every entry +in that rollup. Completed `SUCCESS`, `NEUTRAL`, and `SKIPPED` CheckRuns and +`SUCCESS` StatusContexts pass. Pending entries wait; all other conclusions or +states fail. An empty rollup passes only after `grace` seconds. + +`github_pr_merge` first views the requested number, refuses failed or pending +checks, runs `gh pr merge -- --match-head-commit +`, and verifies the resulting `MERGED` state. Results contain +structured number, URL/branch/base, check, or merge keys as appropriate. + +## Errors + +The kit raises `GitHubToolError`, with one of these codes: + +`GITHUB_ARGUMENT_REFUSED`, `GITHUB_CLI_MISSING`, `GITHUB_CLI_FAILED`, +`GITHUB_CLI_TIMEOUT`, `GITHUB_OUTPUT_INVALID`, `GITHUB_PR_CONFLICT`, +`GITHUB_PR_AMBIGUOUS`, `GITHUB_CHECKS_PENDING`, `GITHUB_CHECKS_FAILED`, +`GITHUB_PR_NOT_OPEN`, `GITHUB_PR_MISMATCH`, and `GITHUB_MERGE_INCOMPLETE`. + +## Prerequisites and testing + +The machine must have `gh` installed and authenticated through its existing +`gh auth` configuration. Python 3.12+ and the Beddel SDK are required. + +```bash +cd repo/kits/tools-github-kit +pytest -q +``` + +Tests place a fake `gh` first on `PATH`; they do not access a network or a real +repository host. diff --git a/kits/tools-github-kit/kit.yaml b/kits/tools-github-kit/kit.yaml new file mode 100644 index 00000000..c45f83a8 --- /dev/null +++ b/kits/tools-github-kit/kit.yaml @@ -0,0 +1,34 @@ +name: tools-github-kit +version: 0.1.0 +description: Typed GitHub pull request operations through the gh CLI +author: Beddel Team +tools: +- name: github_pr_create_or_reuse + target: beddel_tools_github.tools:github_pr_create_or_reuse + description: Create or reuse one open GitHub pull request + category: github +- name: github_pr_checks_wait + target: beddel_tools_github.tools:github_pr_checks_wait + description: Wait for configured GitHub pull request checks + category: github +- name: github_pr_merge + target: beddel_tools_github.tools:github_pr_merge + description: Merge one checked GitHub pull request + category: github +targets: + python: + status: implemented + module: beddel_tools_github + dependencies: [] + tools: + - name: github_pr_create_or_reuse + target: beddel_tools_github.tools:github_pr_create_or_reuse + - name: github_pr_checks_wait + target: beddel_tools_github.tools:github_pr_checks_wait + - name: github_pr_merge + target: beddel_tools_github.tools:github_pr_merge + typescript: + status: unavailable + unavailable_reason: > + The tools drive the local gh executable with the machine's existing login + and have no TypeScript target. diff --git a/kits/tools-github-kit/pytest.ini b/kits/tools-github-kit/pytest.ini new file mode 100644 index 00000000..2f4c80e3 --- /dev/null +++ b/kits/tools-github-kit/pytest.ini @@ -0,0 +1,2 @@ +[pytest] +asyncio_mode = auto diff --git a/kits/tools-github-kit/python/beddel_tools_github/__init__.py b/kits/tools-github-kit/python/beddel_tools_github/__init__.py new file mode 100644 index 00000000..204c39e1 --- /dev/null +++ b/kits/tools-github-kit/python/beddel_tools_github/__init__.py @@ -0,0 +1,17 @@ +"""Typed async GitHub pull request operations.""" + +from beddel_tools_github.tools import ( + GitHubCLI, + GitHubToolError, + github_pr_checks_wait, + github_pr_create_or_reuse, + github_pr_merge, +) + +__all__ = [ + "GitHubCLI", + "GitHubToolError", + "github_pr_checks_wait", + "github_pr_create_or_reuse", + "github_pr_merge", +] diff --git a/kits/tools-github-kit/python/beddel_tools_github/py.typed b/kits/tools-github-kit/python/beddel_tools_github/py.typed new file mode 100644 index 00000000..e69de29b diff --git a/kits/tools-github-kit/python/beddel_tools_github/tools.py b/kits/tools-github-kit/python/beddel_tools_github/tools.py new file mode 100644 index 00000000..48a3a0d4 --- /dev/null +++ b/kits/tools-github-kit/python/beddel_tools_github/tools.py @@ -0,0 +1,654 @@ +"""Async GitHub pull request tools backed by the machine's ``gh`` login.""" + +from __future__ import annotations + +import asyncio +import contextlib +import json +import os +import re +import subprocess +import time +from collections.abc import Mapping +from typing import Any, NoReturn + +from beddel.domain.errors import BeddelError +from beddel.tools import beddel_tool + +__all__ = [ + "GITHUB_ARGUMENT_REFUSED", + "GITHUB_CHECKS_FAILED", + "GITHUB_CHECKS_PENDING", + "GITHUB_CLI_FAILED", + "GITHUB_CLI_MISSING", + "GITHUB_CLI_TIMEOUT", + "GITHUB_MERGE_INCOMPLETE", + "GITHUB_OUTPUT_INVALID", + "GITHUB_PR_AMBIGUOUS", + "GITHUB_PR_CONFLICT", + "GITHUB_PR_MISMATCH", + "GITHUB_PR_NOT_OPEN", + "GitHubCLI", + "GitHubToolError", + "github_pr_checks_wait", + "github_pr_create_or_reuse", + "github_pr_merge", +] + +GITHUB_ARGUMENT_REFUSED = "GITHUB_ARGUMENT_REFUSED" +GITHUB_CHECKS_FAILED = "GITHUB_CHECKS_FAILED" +GITHUB_CHECKS_PENDING = "GITHUB_CHECKS_PENDING" +GITHUB_CLI_FAILED = "GITHUB_CLI_FAILED" +GITHUB_CLI_MISSING = "GITHUB_CLI_MISSING" +GITHUB_CLI_TIMEOUT = "GITHUB_CLI_TIMEOUT" +GITHUB_MERGE_INCOMPLETE = "GITHUB_MERGE_INCOMPLETE" +GITHUB_OUTPUT_INVALID = "GITHUB_OUTPUT_INVALID" +GITHUB_PR_AMBIGUOUS = "GITHUB_PR_AMBIGUOUS" +GITHUB_PR_CONFLICT = "GITHUB_PR_CONFLICT" +GITHUB_PR_MISMATCH = "GITHUB_PR_MISMATCH" +GITHUB_PR_NOT_OPEN = "GITHUB_PR_NOT_OPEN" + +_BRANCH_RE = re.compile(r"^[A-Za-z0-9][A-Za-z0-9/_.-]{0,254}$") +_STORY_RE = re.compile(r"^[a-z0-9][a-z0-9._-]{0,127}$") +_CHANGE_RE = re.compile(r"^[a-z0-9][a-z0-9._-]{0,63}$") +_SPEC_RE = re.compile(r"^[A-Za-z0-9_][A-Za-z0-9_./-]{0,254}$") +_SHA_RE = re.compile(r"^(?:[0-9a-f]{40}|[0-9a-f]{64})$") +_SENSITIVE_RE = re.compile(r"gh[pousr]_[A-Za-z0-9_]{10,}|github_pat_[A-Za-z0-9_]{10,}") +_REAP_GRACE_SECONDS = 2.0 + + +class GitHubToolError(BeddelError): + """Kit-local error with a stable code and secret-free message.""" + + def __init__( + self, code: str, message: str, details: dict[str, Any] | None = None + ) -> None: + super().__init__(code, message, details) + + +def _refuse(argument: str) -> NoReturn: + raise GitHubToolError( + GITHUB_ARGUMENT_REFUSED, + "Invalid GitHub argument.", + {"argument": argument}, + ) + + +def _validate_string(value: object, argument: str) -> str: + if ( + not isinstance(value, str) + or value.startswith("-") + or _SENSITIVE_RE.search(value) + ): + _refuse(argument) + return value + + +def _validate_pattern(value: object, argument: str, pattern: re.Pattern[str]) -> str: + value = _validate_string(value, argument) + if pattern.fullmatch(value) is None: + _refuse(argument) + return value + + +def _validate_cwd(cwd: object) -> str: + cwd_value = _validate_string(cwd, "cwd") + if not os.path.isdir(cwd_value): + _refuse("cwd") + return cwd_value + + +def _validate_number(number: object) -> int: + if isinstance(number, bool) or not isinstance(number, int) or number <= 0: + _refuse("number") + return number + + +def _validate_positive(value: object, argument: str) -> float: + if isinstance(value, bool) or not isinstance(value, (int, float)) or value <= 0: + _refuse(argument) + return float(value) + + +def _validate_wait_values( + interval: object, max_wait: object, grace: object +) -> tuple[float, float, float]: + interval_value = _validate_positive(interval, "interval") + max_wait_value = _validate_positive(max_wait, "max_wait") + if isinstance(grace, bool) or not isinstance(grace, (int, float)): + _refuse("grace") + grace_value = float(grace) + if grace_value < 0 or grace_value > max_wait_value: + _refuse("grace") + return interval_value, max_wait_value, grace_value + + +def _validate_timeout(timeout: object) -> float: + return _validate_positive(timeout, "timeout") + + +def _validate_sha(value: object, argument: str) -> str: + return _validate_pattern(value, argument, _SHA_RE) + + +def _redact(text: str) -> str: + return _SENSITIVE_RE.sub("[redacted]", text) + + +async def _terminate(proc: asyncio.subprocess.Process) -> None: + """Kill a process and bound the wait for a child holding its pipes.""" + with contextlib.suppress(ProcessLookupError): + proc.kill() + with contextlib.suppress(TimeoutError): + async with asyncio.timeout(_REAP_GRACE_SECONDS): + await proc.wait() + + +def _command_name(argv: tuple[str, ...]) -> str: + return "gh " + " ".join(argv[:2]) + + +def _invalid_output(command: str) -> GitHubToolError: + return GitHubToolError( + GITHUB_OUTPUT_INVALID, + "GitHub CLI output is invalid.", + {"command": command}, + ) + + +class GitHubCLI: + """Run explicit ``gh`` argv in a repository with inherited login state.""" + + def __init__(self, *, timeout: float = 120) -> None: + self._timeout = timeout + + async def run(self, *argv: str, cwd: str) -> str: + """Run ``gh`` and return stdout, converting process failures to kit errors.""" + try: + proc = await asyncio.create_subprocess_exec( + "gh", + *argv, + cwd=cwd, + stdin=subprocess.DEVNULL, + stdout=asyncio.subprocess.PIPE, + stderr=asyncio.subprocess.PIPE, + ) + except FileNotFoundError as exc: + raise GitHubToolError( + GITHUB_CLI_MISSING, + "The gh CLI is not installed.", + ) from exc + + try: + async with asyncio.timeout(self._timeout): + stdout_bytes, stderr_bytes = await proc.communicate() + except TimeoutError as exc: + await _terminate(proc) + raise GitHubToolError( + GITHUB_CLI_TIMEOUT, + "The gh command timed out.", + {"timeout": self._timeout}, + ) from exc + except asyncio.CancelledError: + await _terminate(proc) + raise + + if proc.returncode != 0: + stderr = _redact(stderr_bytes.decode(errors="replace"))[-500:] + raise GitHubToolError( + GITHUB_CLI_FAILED, + "The gh command failed.", + { + "command": _command_name(argv), + "exit_code": proc.returncode, + "stderr": stderr, + }, + ) + return stdout_bytes.decode(errors="replace") + + +def _load_json(text: str, command: str) -> Any: + try: + return json.loads(text) + except json.JSONDecodeError as exc: + raise _invalid_output(command) from exc + + +def _as_mapping(value: Any, command: str) -> Mapping[str, Any]: + if not isinstance(value, Mapping): + raise _invalid_output(command) + return value + + +def _pr_list(value: Any, command: str) -> list[Mapping[str, Any]]: + if not isinstance(value, list): + raise _invalid_output(command) + result: list[Mapping[str, Any]] = [] + for item in value: + item_map = _as_mapping(item, command) + if ( + isinstance(item_map.get("number"), bool) + or not isinstance(item_map.get("number"), int) + or not isinstance(item_map.get("url"), str) + or not isinstance(item_map.get("headRefName"), str) + or not isinstance(item_map.get("baseRefName"), str) + or not isinstance(item_map.get("state"), str) + ): + raise _invalid_output(command) + result.append(item_map) + return result + + +def _pr_view(value: Any, command: str) -> Mapping[str, Any]: + view = _as_mapping(value, command) + if ( + isinstance(view.get("number"), bool) + or not isinstance(view.get("number"), int) + or not isinstance(view.get("state"), str) + or not isinstance(view.get("headRefOid"), str) + or not isinstance(view.get("statusCheckRollup"), list) + ): + raise _invalid_output(command) + return view + + +def _check_name(item: Mapping[str, Any], check_type: str, command: str) -> str: + key = "name" if check_type == "CheckRun" else "context" + name = item.get(key) + if not isinstance(name, str): + raise _invalid_output(command) + return name + + +def _rollup_status(rollup: list[Any], command: str) -> tuple[str, list[str], list[str]]: + """Return status, all names, and failed names for a rollup.""" + if not rollup: + return "empty", [], [] + names: list[str] = [] + failed: list[str] = [] + pending = False + for raw_item in rollup: + item = _as_mapping(raw_item, command) + check_type = item.get("__typename") + if not isinstance(check_type, str): + raise _invalid_output(command) + if check_type == "CheckRun": + name = _check_name(item, check_type, command) + names.append(name) + status = item.get("status") + conclusion = item.get("conclusion") + if not isinstance(status, str) or status != "COMPLETED": + pending = True + elif conclusion not in {"SUCCESS", "NEUTRAL", "SKIPPED"}: + failed.append(name) + elif check_type == "StatusContext": + name = _check_name(item, check_type, command) + names.append(name) + state = item.get("state") + if state in {"PENDING", "EXPECTED"}: + pending = True + elif state != "SUCCESS": + failed.append(name) + else: + failed.append(str(item.get("name", item.get("context", "unknown")))) + if failed: + return "failed", names, failed + if pending: + return "pending", names, [] + return "passed", names, [] + + +def _check_failure(status: str, failed: list[str]) -> GitHubToolError: + if status == "pending": + return GitHubToolError(GITHUB_CHECKS_PENDING, "Checks are still pending.") + return GitHubToolError( + GITHUB_CHECKS_FAILED, + "Checks failed.", + {"failed": failed}, + ) + + +def _validate_create_args( + cwd: object, + branch: object, + base: object, + story_key: object, + spec_path: object, + change_id: object, + revision: object, + timeout: object, +) -> tuple[str, str, str, str, str, str, str, float]: + return ( + _validate_cwd(cwd), + _validate_pattern(branch, "branch", _BRANCH_RE), + _validate_pattern(base, "base", _BRANCH_RE), + _validate_pattern(story_key, "story_key", _STORY_RE), + _validate_pattern(spec_path, "spec_path", _SPEC_RE) + if all(segment not in {"", ".", ".."} for segment in str(spec_path).split("/")) + else _refuse("spec_path"), + _validate_pattern(change_id, "change_id", _CHANGE_RE), + _validate_sha(revision, "revision"), + _validate_timeout(timeout), + ) + + +@beddel_tool( + name="github_pr_create_or_reuse", + description="Create or reuse one open GitHub pull request", + category="github", +) +async def github_pr_create_or_reuse( + *, + cwd: str, + branch: str, + base: str = "main", + story_key: str, + spec_path: str, + change_id: str, + revision: str, + timeout: float = 120, +) -> dict[str, Any]: + """Create one pull request or return the sole matching open request.""" + ( + cwd_value, + branch_value, + base_value, + story_value, + spec_value, + change_value, + revision_value, + timeout_value, + ) = _validate_create_args( + cwd, branch, base, story_key, spec_path, change_id, revision, timeout + ) + list_args = ( + "pr", + "list", + "--head", + branch_value, + "--state", + "open", + "--json", + "number,url,headRefName,baseRefName,state", + "--limit", + "10", + ) + cli = GitHubCLI(timeout=timeout_value) + listed = _pr_list( + _load_json(await cli.run(*list_args, cwd=cwd_value), "gh pr list"), + "gh pr list", + ) + if len(listed) > 1: + raise GitHubToolError( + GITHUB_PR_AMBIGUOUS, + "More than one open pull request matches the branch.", + ) + body = ( + f"Story: {story_value}\n" + f"Spec: {spec_value}\n" + f"Change: {change_value}\n" + f"Revision: {revision_value}\n" + ) + if listed: + pull_request = listed[0] + if pull_request["baseRefName"] != base_value: + raise GitHubToolError( + GITHUB_PR_CONFLICT, + "An open pull request targets another base branch.", + ) + created = False + else: + create_args = ( + "pr", + "create", + "--head", + branch_value, + "--base", + base_value, + "--title", + story_value, + "--body", + body, + ) + await cli.run(*create_args, cwd=cwd_value) + listed = _pr_list( + _load_json(await cli.run(*list_args, cwd=cwd_value), "gh pr list"), + "gh pr list", + ) + if len(listed) != 1: + raise GitHubToolError( + GITHUB_OUTPUT_INVALID, + "GitHub CLI output is invalid.", + {"command": "gh pr list"}, + ) + pull_request = listed[0] + if pull_request["baseRefName"] != base_value: + raise GitHubToolError( + GITHUB_PR_CONFLICT, + "An open pull request targets another base branch.", + ) + created = True + return { + "number": pull_request["number"], + "url": pull_request["url"], + "branch": pull_request["headRefName"], + "base": pull_request["baseRefName"], + "created": created, + } + + +async def _read_checks( + cli: GitHubCLI, cwd: str, number: int +) -> tuple[Mapping[str, Any], list[Any], str]: + command = "gh pr view" + text = await cli.run( + "pr", + "view", + str(number), + "--json", + "number,state,headRefOid,statusCheckRollup", + cwd=cwd, + ) + view = _pr_view(_load_json(text, command), command) + if view["number"] != number: + raise GitHubToolError( + GITHUB_PR_MISMATCH, + "The pull request does not match the requested number or head.", + ) + if view["state"] != "OPEN": + raise GitHubToolError(GITHUB_PR_NOT_OPEN, "The pull request is not open.") + return view, view["statusCheckRollup"], command + + +@beddel_tool( + name="github_pr_checks_wait", + description="Wait for configured GitHub pull request checks", + category="github", +) +async def github_pr_checks_wait( + *, + cwd: str, + number: int, + interval: float = 10, + max_wait: float = 1800, + grace: float = 30, + timeout: float = 120, +) -> dict[str, Any]: + """Poll the pull request rollup until it passes, fails, or times out.""" + cwd_value = _validate_cwd(cwd) + number_value = _validate_number(number) + interval_value, max_wait_value, grace_value = _validate_wait_values( + interval, max_wait, grace + ) + timeout_value = _validate_timeout(timeout) + cli = GitHubCLI(timeout=timeout_value) + started = time.monotonic() + empty_since: float | None = None + while True: + view, rollup, command = await _read_checks(cli, cwd_value, number_value) + status, names, failed = _rollup_status(rollup, command) + now = time.monotonic() + if status == "empty": + if empty_since is None: + empty_since = now + if now - empty_since >= grace_value: + return { + "number": number_value, + "head_sha": view["headRefOid"], + "passed": True, + "no_checks": True, + "checks": [], + } + else: + empty_since = None + if status == "passed": + return { + "number": number_value, + "head_sha": view["headRefOid"], + "passed": True, + "no_checks": False, + "checks": names, + } + if status == "failed": + raise _check_failure(status, failed) + elapsed = now - started + if elapsed >= max_wait_value: + raise GitHubToolError(GITHUB_CHECKS_PENDING, "Checks are still pending.") + delay = min(interval_value, max_wait_value - elapsed) + if status == "empty" and empty_since is not None: + delay = min(delay, max(0.0, grace_value - (now - empty_since))) + await asyncio.sleep(delay) + + +def _validate_merge_args( + cwd: object, + number: object, + merge_method: object, + expected_head_sha: object, + timeout: object, +) -> tuple[str, int, str, str | None, float]: + cwd_value = _validate_cwd(cwd) + number_value = _validate_number(number) + method_value = _validate_string(merge_method, "merge_method") + if method_value not in {"merge", "squash", "rebase"}: + _refuse("merge_method") + if expected_head_sha is None: + expected_value = None + else: + expected_value = _validate_sha(expected_head_sha, "expected_head_sha") + return ( + cwd_value, + number_value, + method_value, + expected_value, + _validate_timeout(timeout), + ) + + +@beddel_tool( + name="github_pr_merge", + description="Merge one checked GitHub pull request", + category="github", +) +async def github_pr_merge( + *, + cwd: str, + number: int, + merge_method: str = "merge", + expected_head_sha: str | None = None, + timeout: float = 120, +) -> dict[str, Any]: + """Merge exactly one open pull request after its rollup passes.""" + cwd_value, number_value, method_value, expected_value, timeout_value = ( + _validate_merge_args(cwd, number, merge_method, expected_head_sha, timeout) + ) + cli = GitHubCLI(timeout=timeout_value) + command = "gh pr view" + first_text = await cli.run( + "pr", + "view", + str(number_value), + "--json", + "number,state,headRefOid,mergeCommit,statusCheckRollup", + cwd=cwd_value, + ) + first_view = _as_mapping(_load_json(first_text, command), command) + if ( + isinstance(first_view.get("number"), bool) + or not isinstance(first_view.get("number"), int) + or not isinstance(first_view.get("state"), str) + or not isinstance(first_view.get("headRefOid"), str) + or not isinstance(first_view.get("statusCheckRollup"), list) + ): + raise _invalid_output(command) + if first_view["number"] != number_value: + raise GitHubToolError( + GITHUB_PR_MISMATCH, + "The pull request does not match the requested number or head.", + ) + if first_view["state"] == "MERGED": + merge_commit = _as_mapping(first_view.get("mergeCommit"), command) + merge_sha = merge_commit.get("oid") + if not isinstance(merge_sha, str): + raise _invalid_output(command) + return { + "number": number_value, + "merged": True, + "already_merged": True, + "merge_sha": merge_sha, + "merge_method": method_value, + } + if first_view["state"] != "OPEN": + raise GitHubToolError(GITHUB_PR_NOT_OPEN, "The pull request is not open.") + head_sha = first_view["headRefOid"] + if expected_value is not None and head_sha != expected_value: + raise GitHubToolError( + GITHUB_PR_MISMATCH, + "The pull request does not match the requested number or head.", + ) + status, _names, failed = _rollup_status(first_view["statusCheckRollup"], command) + if status in {"pending", "failed"}: + raise _check_failure(status, failed) + await cli.run( + "pr", + "merge", + str(number_value), + f"--{method_value}", + "--match-head-commit", + head_sha, + cwd=cwd_value, + ) + after_text = await cli.run( + "pr", + "view", + str(number_value), + "--json", + "number,state,mergeCommit", + cwd=cwd_value, + ) + after = _as_mapping(_load_json(after_text, "gh pr view"), "gh pr view") + if isinstance(after.get("number"), bool) or not isinstance( + after.get("number"), int + ): + raise _invalid_output("gh pr view") + if after["number"] != number_value: + raise GitHubToolError( + GITHUB_PR_MISMATCH, + "The pull request does not match the requested number or head.", + ) + if after.get("state") != "MERGED": + raise GitHubToolError( + GITHUB_MERGE_INCOMPLETE, + "The pull request did not merge.", + ) + merge_commit = _as_mapping(after.get("mergeCommit"), "gh pr view") + merge_sha = merge_commit.get("oid") + if not isinstance(merge_sha, str): + raise _invalid_output("gh pr view") + return { + "number": number_value, + "merged": True, + "already_merged": False, + "merge_sha": merge_sha, + "merge_method": method_value, + } diff --git a/kits/tools-github-kit/tests/__init__.py b/kits/tools-github-kit/tests/__init__.py new file mode 100644 index 00000000..e69de29b diff --git a/kits/tools-github-kit/tests/conftest.py b/kits/tools-github-kit/tests/conftest.py new file mode 100644 index 00000000..46dbb58c --- /dev/null +++ b/kits/tools-github-kit/tests/conftest.py @@ -0,0 +1,55 @@ +"""Configure standalone kit test imports and provide a deterministic fake gh.""" + +from __future__ import annotations + +import os +import stat +import sys +from pathlib import Path + +import pytest + +_KIT_ROOT = Path(__file__).resolve().parent.parent +sys.path.insert(0, str(_KIT_ROOT / "python")) + + +@pytest.fixture +def fake_gh(tmp_path: Path, monkeypatch: pytest.MonkeyPatch) -> tuple[Path, Path, Path]: + """Put a scripted fake gh executable first on PATH.""" + bin_dir = tmp_path / "bin" + bin_dir.mkdir() + log_path = tmp_path / "gh-log.jsonl" + script_path = tmp_path / "gh-script.json" + gh_path = bin_dir / "gh" + gh_path.write_text( + f"""#!{sys.executable} +import json +import os +import pathlib +import subprocess +import sys +import time + +script_path = pathlib.Path(os.environ["FAKE_GH_SCRIPT"]) +log_path = pathlib.Path(os.environ["FAKE_GH_LOG"]) +with log_path.open("a") as stream: + stream.write(json.dumps({{"argv": sys.argv[1:], "cwd": os.getcwd(), "pid": os.getpid()}}) + "\\n") +responses = json.loads(script_path.read_text()) +response = responses.pop(0) +script_path.write_text(json.dumps(responses)) +if response.get("mode") == "grandchild": + child_code = "import os,time; open(os.environ['FAKE_GH_CHILD_LOG'], 'w').write(str(os.getpid())); time.sleep(60)" + child = subprocess.Popen([sys.executable, "-c", child_code]) + pathlib.Path(os.environ["FAKE_GH_CHILD_LOG"]).write_text(str(child.pid)) +if response.get("mode") in ("sleep", "grandchild"): + time.sleep(response.get("seconds", 60)) +sys.stdout.write(response.get("stdout", "")) +sys.stderr.write(response.get("stderr", "")) +sys.exit(response.get("exit", 0)) +""" + ) + gh_path.chmod(gh_path.stat().st_mode | stat.S_IXUSR) + monkeypatch.setenv("PATH", f"{bin_dir}{os.pathsep}{os.environ.get('PATH', '')}") + monkeypatch.setenv("FAKE_GH_LOG", str(log_path)) + monkeypatch.setenv("FAKE_GH_SCRIPT", str(script_path)) + return tmp_path, log_path, script_path diff --git a/kits/tools-github-kit/tests/test_tools.py b/kits/tools-github-kit/tests/test_tools.py new file mode 100644 index 00000000..679f21cf --- /dev/null +++ b/kits/tools-github-kit/tests/test_tools.py @@ -0,0 +1,622 @@ +"""Matrix tests for tools-github-kit using a scripted fake gh executable.""" + +from __future__ import annotations + +import asyncio +import json +import os +import signal +import time +from pathlib import Path +from typing import Any + +import pytest +from beddel_tools_github import ( + GitHubToolError, + github_pr_checks_wait, + github_pr_create_or_reuse, + github_pr_merge, +) +from beddel_tools_github.tools import ( + GITHUB_ARGUMENT_REFUSED, + GITHUB_CHECKS_FAILED, + GITHUB_CHECKS_PENDING, + GITHUB_CLI_FAILED, + GITHUB_CLI_MISSING, + GITHUB_CLI_TIMEOUT, + GITHUB_MERGE_INCOMPLETE, + GITHUB_OUTPUT_INVALID, + GITHUB_PR_AMBIGUOUS, + GITHUB_PR_CONFLICT, + GITHUB_PR_MISMATCH, + GITHUB_PR_NOT_OPEN, +) + +_SHA = "a" * 40 +_SHA2 = "b" * 40 + + +def _write_script(script_path: Path, *responses: dict[str, Any]) -> None: + script_path.write_text(json.dumps(list(responses))) + + +def _read_log(log_path: Path) -> list[dict[str, Any]]: + return [json.loads(line) for line in log_path.read_text().splitlines()] + + +def _pr(*, base: str = "main", number: int = 7, state: str = "OPEN") -> dict[str, Any]: + return { + "number": number, + "url": "https://github.example/pull/7", + "headRefName": "feature/one", + "baseRefName": base, + "state": state, + } + + +def _view( + rollup: list[dict[str, Any]], *, number: int = 7, state: str = "OPEN" +) -> dict[str, Any]: + return { + "number": number, + "state": state, + "headRefOid": _SHA, + "statusCheckRollup": rollup, + } + + +def _success(name: str = "unit") -> dict[str, Any]: + return { + "__typename": "CheckRun", + "name": name, + "status": "COMPLETED", + "conclusion": "SUCCESS", + } + + +def _pending(name: str = "unit") -> dict[str, Any]: + return { + "__typename": "CheckRun", + "name": name, + "status": "IN_PROGRESS", + "conclusion": None, + } + + +def _assert_code(exc_info: pytest.ExceptionInfo[GitHubToolError], code: str) -> None: + assert exc_info.value.code == code + + +@pytest.mark.asyncio +async def test_create_no_pr_creates_and_lists_again( + fake_gh: tuple[Path, Path, Path], +) -> None: + root, log, script = fake_gh + _write_script( + script, + {"stdout": "[]"}, + {"stdout": "https://github.example/pull/7\n"}, + {"stdout": json.dumps([_pr()])}, + ) + result = await github_pr_create_or_reuse( + cwd=str(root), + branch="feature/one", + story_key="7-2b", + spec_path="spec.md", + change_id="chg-1", + revision=_SHA, + ) + assert result == { + "number": 7, + "url": "https://github.example/pull/7", + "branch": "feature/one", + "base": "main", + "created": True, + } + assert [entry["argv"] for entry in _read_log(log)] == [ + [ + "pr", + "list", + "--head", + "feature/one", + "--state", + "open", + "--json", + "number,url,headRefName,baseRefName,state", + "--limit", + "10", + ], + [ + "pr", + "create", + "--head", + "feature/one", + "--base", + "main", + "--title", + "7-2b", + "--body", + f"Story: 7-2b\nSpec: spec.md\nChange: chg-1\nRevision: {_SHA}\n", + ], + [ + "pr", + "list", + "--head", + "feature/one", + "--state", + "open", + "--json", + "number,url,headRefName,baseRefName,state", + "--limit", + "10", + ], + ] + assert all(entry["cwd"] == str(root) for entry in _read_log(log)) + + +@pytest.mark.asyncio +async def test_open_pr_reused_on_rerun(fake_gh: tuple[Path, Path, Path]) -> None: + root, log, script = fake_gh + _write_script( + script, {"stdout": json.dumps([_pr()])}, {"stdout": json.dumps([_pr()])} + ) + first = await github_pr_create_or_reuse( + cwd=str(root), + branch="feature/one", + story_key="7-2b", + spec_path="spec.md", + change_id="chg-1", + revision=_SHA, + ) + second = await github_pr_create_or_reuse( + cwd=str(root), + branch="feature/one", + story_key="7-2b", + spec_path="spec.md", + change_id="chg-1", + revision=_SHA, + ) + assert first["created"] is False and second["created"] is False + assert first["number"] == second["number"] == 7 + assert len(_read_log(log)) == 2 + + +@pytest.mark.asyncio +async def test_other_base_is_conflict(fake_gh: tuple[Path, Path, Path]) -> None: + root, _log, script = fake_gh + _write_script(script, {"stdout": json.dumps([_pr(base="develop")])}) + with pytest.raises(GitHubToolError) as exc: + await github_pr_create_or_reuse( + cwd=str(root), + branch="feature/one", + story_key="7-2b", + spec_path="spec.md", + change_id="chg-1", + revision=_SHA, + ) + _assert_code(exc, GITHUB_PR_CONFLICT) + + +@pytest.mark.asyncio +async def test_two_open_prs_are_ambiguous(fake_gh: tuple[Path, Path, Path]) -> None: + root, _log, script = fake_gh + _write_script(script, {"stdout": json.dumps([_pr(), _pr(number=8)])}) + with pytest.raises(GitHubToolError) as exc: + await github_pr_create_or_reuse( + cwd=str(root), + branch="feature/one", + story_key="7-2b", + spec_path="spec.md", + change_id="chg-1", + revision=_SHA, + ) + _assert_code(exc, GITHUB_PR_AMBIGUOUS) + + +@pytest.mark.asyncio +async def test_invalid_reference_runs_nothing(fake_gh: tuple[Path, Path, Path]) -> None: + root, log, script = fake_gh + _write_script(script, {"stdout": "[]"}) + with pytest.raises(GitHubToolError) as exc: + await github_pr_create_or_reuse( + cwd=str(root), + branch="feature/one", + story_key="7-2b", + spec_path="a/../b", + change_id="chg-1", + revision=_SHA, + ) + _assert_code(exc, GITHUB_ARGUMENT_REFUSED) + assert not log.exists() + + +@pytest.mark.asyncio +async def test_checks_passed(fake_gh: tuple[Path, Path, Path]) -> None: + root, _log, script = fake_gh + _write_script( + script, + { + "stdout": json.dumps( + _view( + [ + _success("lint"), + { + "__typename": "StatusContext", + "context": "ci", + "state": "SUCCESS", + }, + ] + ) + ) + }, + ) + result = await github_pr_checks_wait( + cwd=str(root), number=7, interval=0.01, max_wait=1, grace=0 + ) + assert result == { + "number": 7, + "head_sha": _SHA, + "passed": True, + "no_checks": False, + "checks": ["lint", "ci"], + } + + +@pytest.mark.asyncio +async def test_pending_then_passed_sleeps_between_polls( + fake_gh: tuple[Path, Path, Path], +) -> None: + root, log, script = fake_gh + _write_script( + script, + {"stdout": json.dumps(_view([_pending()]))}, + {"stdout": json.dumps(_view([_success()]))}, + ) + result = await github_pr_checks_wait( + cwd=str(root), number=7, interval=0.01, max_wait=1, grace=0 + ) + assert result["passed"] is True + assert len(_read_log(log)) == 2 + + +@pytest.mark.asyncio +async def test_pending_at_max_wait_is_rejected( + fake_gh: tuple[Path, Path, Path], +) -> None: + root, _log, script = fake_gh + _write_script(script, {"stdout": json.dumps(_view([_pending()]))}) + with pytest.raises(GitHubToolError) as exc: + await github_pr_checks_wait( + cwd=str(root), number=7, interval=1, max_wait=0.01, grace=0 + ) + _assert_code(exc, GITHUB_CHECKS_PENDING) + + +@pytest.mark.asyncio +async def test_failed_checks_refuse_immediately( + fake_gh: tuple[Path, Path, Path], +) -> None: + root, _log, script = fake_gh + _write_script( + script, + { + "stdout": json.dumps( + _view( + [ + { + "__typename": "CheckRun", + "name": "lint", + "status": "COMPLETED", + "conclusion": "FAILURE", + } + ] + ) + ) + }, + ) + with pytest.raises(GitHubToolError) as exc: + await github_pr_checks_wait( + cwd=str(root), number=7, interval=1, max_wait=1, grace=0 + ) + _assert_code(exc, GITHUB_CHECKS_FAILED) + assert exc.value.details["failed"] == ["lint"] + + +@pytest.mark.asyncio +async def test_no_checks_waits_for_grace_then_passes( + fake_gh: tuple[Path, Path, Path], +) -> None: + root, log, script = fake_gh + _write_script( + script, {"stdout": json.dumps(_view([]))}, {"stdout": json.dumps(_view([]))} + ) + result = await github_pr_checks_wait( + cwd=str(root), number=7, interval=0.01, max_wait=1, grace=0.02 + ) + assert result["no_checks"] is True and result["checks"] == [] + assert len(_read_log(log)) == 3 or len(_read_log(log)) == 2 + + +@pytest.mark.asyncio +async def test_merge_runs_pinned_merge_and_verifies_state( + fake_gh: tuple[Path, Path, Path], +) -> None: + root, log, script = fake_gh + _write_script( + script, + {"stdout": json.dumps({**_view([_success()]), "mergeCommit": None})}, + {"stdout": ""}, + { + "stdout": json.dumps( + {"number": 7, "state": "MERGED", "mergeCommit": {"oid": _SHA2}} + ) + }, + ) + result = await github_pr_merge( + cwd=str(root), number=7, merge_method="squash", expected_head_sha=_SHA + ) + assert result == { + "number": 7, + "merged": True, + "already_merged": False, + "merge_sha": _SHA2, + "merge_method": "squash", + } + assert _read_log(log)[1]["argv"] == [ + "pr", + "merge", + "7", + "--squash", + "--match-head-commit", + _SHA, + ] + + +@pytest.mark.asyncio +async def test_merge_rerun_returns_already_merged( + fake_gh: tuple[Path, Path, Path], +) -> None: + root, log, script = fake_gh + _write_script( + script, + { + "stdout": json.dumps( + { + "number": 7, + "state": "MERGED", + "headRefOid": _SHA, + "mergeCommit": {"oid": _SHA2}, + "statusCheckRollup": [], + } + ) + }, + ) + result = await github_pr_merge(cwd=str(root), number=7) + assert result["already_merged"] is True and result["merge_sha"] == _SHA2 + assert len(_read_log(log)) == 1 + + +@pytest.mark.asyncio +async def test_merge_rejects_failed_and_pending_checks( + fake_gh: tuple[Path, Path, Path], +) -> None: + root, log, script = fake_gh + _write_script( + script, {"stdout": json.dumps({**_view([_pending()]), "mergeCommit": None})} + ) + with pytest.raises(GitHubToolError) as exc: + await github_pr_merge(cwd=str(root), number=7) + _assert_code(exc, GITHUB_CHECKS_PENDING) + assert len(_read_log(log)) == 1 + + +@pytest.mark.asyncio +async def test_merge_rejects_not_open_and_number_mismatch( + fake_gh: tuple[Path, Path, Path], +) -> None: + root, _log, script = fake_gh + _write_script( + script, + {"stdout": json.dumps({**_view([], state="CLOSED"), "mergeCommit": None})}, + ) + with pytest.raises(GitHubToolError) as exc: + await github_pr_merge(cwd=str(root), number=7) + _assert_code(exc, GITHUB_PR_NOT_OPEN) + _write_script( + script, {"stdout": json.dumps({**_view([], number=8), "mergeCommit": None})} + ) + with pytest.raises(GitHubToolError) as exc: + await github_pr_merge(cwd=str(root), number=7) + _assert_code(exc, GITHUB_PR_MISMATCH) + + +@pytest.mark.asyncio +async def test_merge_head_mismatch_and_incomplete( + fake_gh: tuple[Path, Path, Path], +) -> None: + root, _log, script = fake_gh + _write_script(script, {"stdout": json.dumps({**_view([]), "mergeCommit": None})}) + with pytest.raises(GitHubToolError) as exc: + await github_pr_merge(cwd=str(root), number=7, expected_head_sha=_SHA2) + _assert_code(exc, GITHUB_PR_MISMATCH) + _write_script( + script, + {"stdout": json.dumps({**_view([]), "mergeCommit": None})}, + {"stdout": ""}, + {"stdout": json.dumps({"number": 7, "state": "OPEN", "mergeCommit": None})}, + ) + with pytest.raises(GitHubToolError) as exc: + await github_pr_merge(cwd=str(root), number=7) + _assert_code(exc, GITHUB_MERGE_INCOMPLETE) + + +@pytest.mark.asyncio +async def test_missing_cli_and_nonzero_are_safe( + fake_gh: tuple[Path, Path, Path], monkeypatch: pytest.MonkeyPatch +) -> None: + root, _log, script = fake_gh + fake_path = os.environ["PATH"] + monkeypatch.setenv("PATH", str(root / "no-such-bin")) + with pytest.raises(GitHubToolError) as exc: + await github_pr_checks_wait(cwd=str(root), number=7, grace=0, max_wait=1) + _assert_code(exc, GITHUB_CLI_MISSING) + monkeypatch.setenv("PATH", fake_path) + secret = "gh" + "p_" + "A" * 36 + _write_script(script, {"exit": 1, "stderr": f"bad {secret}"}) + with pytest.raises(GitHubToolError) as exc: + await github_pr_checks_wait(cwd=str(root), number=7, grace=0, max_wait=1) + _assert_code(exc, GITHUB_CLI_FAILED) + assert secret not in str(exc.value) and "[redacted]" in exc.value.details["stderr"] + + +@pytest.mark.asyncio +async def test_bad_output_and_cli_shape_are_rejected( + fake_gh: tuple[Path, Path, Path], +) -> None: + root, _log, script = fake_gh + _write_script(script, {"stdout": "not-json"}) + with pytest.raises(GitHubToolError) as exc: + await github_pr_create_or_reuse( + cwd=str(root), + branch="feature/one", + story_key="7-2b", + spec_path="spec.md", + change_id="chg-1", + revision=_SHA, + ) + _assert_code(exc, GITHUB_OUTPUT_INVALID) + + +@pytest.mark.asyncio +async def test_timeout_and_grandchild_are_bounded( + fake_gh: tuple[Path, Path, Path], monkeypatch: pytest.MonkeyPatch +) -> None: + root, log, script = fake_gh + _write_script(script, {"mode": "sleep", "seconds": 60}) + started = time.monotonic() + with pytest.raises(GitHubToolError) as exc: + await github_pr_checks_wait( + cwd=str(root), number=7, timeout=0.2, grace=0, max_wait=1 + ) + assert exc.value.code == GITHUB_CLI_TIMEOUT + assert time.monotonic() - started < 6 + pid = int(_read_log(log)[0]["pid"]) + _assert_pid_gone(pid) + child_log = root / "child.pid" + os.environ["FAKE_GH_CHILD_LOG"] = str(child_log) + _write_script(script, {"mode": "grandchild", "seconds": 60}) + monkeypatch_path = os.environ.get("FAKE_GH_CHILD_LOG") + assert monkeypatch_path == str(child_log) + with pytest.raises(GitHubToolError): + await github_pr_checks_wait( + cwd=str(root), number=7, timeout=0.2, grace=0, max_wait=1 + ) + if child_log.exists(): + os.kill(int(child_log.read_text()), signal.SIGKILL) + await asyncio.sleep(0.3) + + +def _assert_pid_gone(pid: int) -> None: + deadline = time.monotonic() + 5 + while time.monotonic() < deadline: + try: + os.kill(pid, 0) + except ProcessLookupError: + return + time.sleep(0.01) + raise AssertionError(f"process {pid} is still running") + + +@pytest.mark.asyncio +async def test_subprocess_contract_uses_closed_stdin_and_no_env( + fake_gh: tuple[Path, Path, Path], monkeypatch: pytest.MonkeyPatch +) -> None: + root, _log, script = fake_gh + _write_script(script, {"stdout": json.dumps(_view([]))}) + real_exec = asyncio.create_subprocess_exec + calls: list[tuple[tuple[Any, ...], dict[str, Any]]] = [] + + async def spy(*args: Any, **kwargs: Any) -> asyncio.subprocess.Process: + calls.append((args, kwargs)) + return await real_exec(*args, **kwargs) + + monkeypatch.setattr(asyncio, "create_subprocess_exec", spy) + await github_pr_checks_wait(cwd=str(root), number=7, grace=0, max_wait=1) + assert calls[0][0][:2] == ("gh", "pr") + assert calls[0][1]["stdin"] is asyncio.subprocess.DEVNULL + assert "env" not in calls[0][1] + + +@pytest.mark.asyncio +async def test_argument_validation_never_runs(fake_gh: tuple[Path, Path, Path]) -> None: + root, log, _script = fake_gh + with pytest.raises(GitHubToolError) as exc: + await github_pr_checks_wait(cwd=str(root), number=True) + _assert_code(exc, GITHUB_ARGUMENT_REFUSED) + with pytest.raises(GitHubToolError) as exc: + await github_pr_merge(cwd=str(root), number=0, merge_method="--merge") + _assert_code(exc, GITHUB_ARGUMENT_REFUSED) + with pytest.raises(GitHubToolError) as exc: + await github_pr_create_or_reuse( + cwd=str(root), + branch="feature/one", + story_key="7-2b", + spec_path="spec.md", + change_id="chg-1", + revision="z" * 40, + ) + _assert_code(exc, GITHUB_ARGUMENT_REFUSED) + token = "gh" + "p_" + "A" * 36 + with pytest.raises(GitHubToolError) as exc: + await github_pr_create_or_reuse( + cwd=str(root), + branch=token, + story_key="7-2b", + spec_path="spec.md", + change_id="chg-1", + revision=_SHA, + ) + _assert_code(exc, GITHUB_ARGUMENT_REFUSED) + not_a_directory = root / "not-a-directory" + not_a_directory.write_text("file") + with pytest.raises(GitHubToolError) as exc: + await github_pr_checks_wait(cwd=str(not_a_directory), number=7) + _assert_code(exc, GITHUB_ARGUMENT_REFUSED) + assert not log.exists() + + +@pytest.mark.asyncio +async def test_merge_rejects_failed_checks(fake_gh: tuple[Path, Path, Path]) -> None: + root, log, script = fake_gh + failed = { + "__typename": "CheckRun", + "name": "lint", + "status": "COMPLETED", + "conclusion": "FAILURE", + } + _write_script( + script, {"stdout": json.dumps({**_view([failed]), "mergeCommit": None})} + ) + with pytest.raises(GitHubToolError) as exc: + await github_pr_merge(cwd=str(root), number=7) + _assert_code(exc, GITHUB_CHECKS_FAILED) + assert exc.value.details["failed"] == ["lint"] + assert len(_read_log(log)) == 1 + + +@pytest.mark.asyncio +async def test_merge_accepts_an_empty_rollup(fake_gh: tuple[Path, Path, Path]) -> None: + root, log, script = fake_gh + _write_script( + script, + {"stdout": json.dumps({**_view([]), "mergeCommit": None})}, + {"stdout": ""}, + { + "stdout": json.dumps( + {"number": 7, "state": "MERGED", "mergeCommit": {"oid": _SHA2}} + ) + }, + ) + result = await github_pr_merge(cwd=str(root), number=7) + assert result["merged"] is True and result["already_merged"] is False + assert len(_read_log(log)) == 3 From e0e30c3a842704d534dc37f95961a5225a612822 Mon Sep 17 00:00:00 2001 From: Carlos Bacelar Date: Mon, 9 Nov 2026 19:43:22 -0300 Subject: [PATCH 2/3] fix(tools-github-kit): refuse non-finite waits, honor grace at max_wait and tighten tests --- .../python/beddel_tools_github/tools.py | 37 +++- kits/tools-github-kit/tests/test_tools.py | 207 ++++++++++++++++-- 2 files changed, 217 insertions(+), 27 deletions(-) diff --git a/kits/tools-github-kit/python/beddel_tools_github/tools.py b/kits/tools-github-kit/python/beddel_tools_github/tools.py index 48a3a0d4..a4140eda 100644 --- a/kits/tools-github-kit/python/beddel_tools_github/tools.py +++ b/kits/tools-github-kit/python/beddel_tools_github/tools.py @@ -5,6 +5,7 @@ import asyncio import contextlib import json +import math import os import re import subprocess @@ -105,7 +106,12 @@ def _validate_number(number: object) -> int: def _validate_positive(value: object, argument: str) -> float: - if isinstance(value, bool) or not isinstance(value, (int, float)) or value <= 0: + if ( + isinstance(value, bool) + or not isinstance(value, (int, float)) + or not math.isfinite(value) + or value <= 0 + ): _refuse(argument) return float(value) @@ -115,7 +121,11 @@ def _validate_wait_values( ) -> tuple[float, float, float]: interval_value = _validate_positive(interval, "interval") max_wait_value = _validate_positive(max_wait, "max_wait") - if isinstance(grace, bool) or not isinstance(grace, (int, float)): + if ( + isinstance(grace, bool) + or not isinstance(grace, (int, float)) + or not math.isfinite(grace) + ): _refuse("grace") grace_value = float(grace) if grace_value < 0 or grace_value > max_wait_value: @@ -127,6 +137,15 @@ def _validate_timeout(timeout: object) -> float: return _validate_positive(timeout, "timeout") +def _validate_spec_path(value: object) -> str: + spec_path = _validate_string(value, "spec_path") + if any(segment in {"", ".", ".."} for segment in spec_path.split("/")): + _refuse("spec_path") + if _SPEC_RE.fullmatch(spec_path) is None: + _refuse("spec_path") + return spec_path + + def _validate_sha(value: object, argument: str) -> str: return _validate_pattern(value, argument, _SHA_RE) @@ -323,9 +342,7 @@ def _validate_create_args( _validate_pattern(branch, "branch", _BRANCH_RE), _validate_pattern(base, "base", _BRANCH_RE), _validate_pattern(story_key, "story_key", _STORY_RE), - _validate_pattern(spec_path, "spec_path", _SPEC_RE) - if all(segment not in {"", ".", ".."} for segment in str(spec_path).split("/")) - else _refuse("spec_path"), + _validate_spec_path(spec_path), _validate_pattern(change_id, "change_id", _CHANGE_RE), _validate_sha(revision, "revision"), _validate_timeout(timeout), @@ -484,13 +501,14 @@ async def github_pr_checks_wait( cli = GitHubCLI(timeout=timeout_value) started = time.monotonic() empty_since: float | None = None + first_poll = True while True: view, rollup, command = await _read_checks(cli, cwd_value, number_value) status, names, failed = _rollup_status(rollup, command) now = time.monotonic() if status == "empty": if empty_since is None: - empty_since = now + empty_since = started if first_poll else now if now - empty_since >= grace_value: return { "number": number_value, @@ -511,6 +529,7 @@ async def github_pr_checks_wait( } if status == "failed": raise _check_failure(status, failed) + first_poll = False elapsed = now - started if elapsed >= max_wait_value: raise GitHubToolError(GITHUB_CHECKS_PENDING, "Checks are still pending.") @@ -586,6 +605,12 @@ async def github_pr_merge( GITHUB_PR_MISMATCH, "The pull request does not match the requested number or head.", ) + head_sha = first_view["headRefOid"] + if expected_value is not None and head_sha != expected_value: + raise GitHubToolError( + GITHUB_PR_MISMATCH, + "The pull request does not match the requested number or head.", + ) if first_view["state"] == "MERGED": merge_commit = _as_mapping(first_view.get("mergeCommit"), command) merge_sha = merge_commit.get("oid") diff --git a/kits/tools-github-kit/tests/test_tools.py b/kits/tools-github-kit/tests/test_tools.py index 679f21cf..dc7c38d6 100644 --- a/kits/tools-github-kit/tests/test_tools.py +++ b/kits/tools-github-kit/tests/test_tools.py @@ -154,6 +154,24 @@ async def test_create_no_pr_creates_and_lists_again( assert all(entry["cwd"] == str(root) for entry in _read_log(log)) +@pytest.mark.asyncio +async def test_create_requires_one_pr_after_creation( + fake_gh: tuple[Path, Path, Path], +) -> None: + root, _log, script = fake_gh + _write_script(script, {"stdout": "[]"}, {"stdout": "created"}, {"stdout": "[]"}) + with pytest.raises(GitHubToolError) as exc: + await github_pr_create_or_reuse( + cwd=str(root), + branch="feature/one", + story_key="7-2b", + spec_path="spec.md", + change_id="chg-1", + revision=_SHA, + ) + _assert_code(exc, GITHUB_OUTPUT_INVALID) + + @pytest.mark.asyncio async def test_open_pr_reused_on_rerun(fake_gh: tuple[Path, Path, Path]) -> None: root, log, script = fake_gh @@ -260,6 +278,15 @@ async def test_checks_passed(fake_gh: tuple[Path, Path, Path]) -> None: "no_checks": False, "checks": ["lint", "ci"], } + entry = _read_log(_log)[0] + assert entry["argv"] == [ + "pr", + "view", + "7", + "--json", + "number,state,headRefOid,statusCheckRollup", + ] + assert entry["cwd"] == str(root) @pytest.mark.asyncio @@ -328,13 +355,49 @@ async def test_no_checks_waits_for_grace_then_passes( ) -> None: root, log, script = fake_gh _write_script( - script, {"stdout": json.dumps(_view([]))}, {"stdout": json.dumps(_view([]))} + script, + *({"stdout": json.dumps(_view([]))} for _ in range(20)), ) result = await github_pr_checks_wait( - cwd=str(root), number=7, interval=0.01, max_wait=1, grace=0.02 + cwd=str(root), number=7, interval=0.05, max_wait=1, grace=0.3 ) assert result["no_checks"] is True and result["checks"] == [] - assert len(_read_log(log)) == 3 or len(_read_log(log)) == 2 + assert len(_read_log(log)) >= 2 + + +@pytest.mark.asyncio +async def test_no_checks_waits_full_grace_before_first_acceptance( + fake_gh: tuple[Path, Path, Path], +) -> None: + root, log, script = fake_gh + _write_script( + script, + *({"stdout": json.dumps(_view([]))} for _ in range(20)), + ) + started = time.monotonic() + result = await github_pr_checks_wait( + cwd=str(root), number=7, interval=0.05, max_wait=10, grace=0.3 + ) + elapsed = time.monotonic() - started + assert result["no_checks"] is True and result["checks"] == [] + assert elapsed >= 0.3 + assert len(_read_log(log)) >= 2 + + +@pytest.mark.asyncio +async def test_no_checks_at_grace_equal_to_max_wait_passes( + fake_gh: tuple[Path, Path, Path], +) -> None: + root, log, script = fake_gh + _write_script( + script, + *({"stdout": json.dumps(_view([]))} for _ in range(20)), + ) + result = await github_pr_checks_wait( + cwd=str(root), number=7, interval=0.05, max_wait=0.3, grace=0.3 + ) + assert result["no_checks"] is True + assert len(_read_log(log)) >= 2 @pytest.mark.asyncio @@ -362,14 +425,26 @@ async def test_merge_runs_pinned_merge_and_verifies_state( "merge_sha": _SHA2, "merge_method": "squash", } - assert _read_log(log)[1]["argv"] == [ - "pr", - "merge", - "7", - "--squash", - "--match-head-commit", - _SHA, + entries = _read_log(log) + assert [entry["argv"] for entry in entries] == [ + [ + "pr", + "view", + "7", + "--json", + "number,state,headRefOid,mergeCommit,statusCheckRollup", + ], + [ + "pr", + "merge", + "7", + "--squash", + "--match-head-commit", + _SHA, + ], + ["pr", "view", "7", "--json", "number,state,mergeCommit"], ] + assert all(entry["cwd"] == str(root) for entry in entries) @pytest.mark.asyncio @@ -391,11 +466,36 @@ async def test_merge_rerun_returns_already_merged( ) }, ) - result = await github_pr_merge(cwd=str(root), number=7) + result = await github_pr_merge(cwd=str(root), number=7, expected_head_sha=_SHA) assert result["already_merged"] is True and result["merge_sha"] == _SHA2 assert len(_read_log(log)) == 1 +@pytest.mark.asyncio +async def test_merged_pr_head_mismatch_is_rejected( + fake_gh: tuple[Path, Path, Path], +) -> None: + root, log, script = fake_gh + _write_script( + script, + { + "stdout": json.dumps( + { + "number": 7, + "state": "MERGED", + "headRefOid": _SHA, + "mergeCommit": {"oid": _SHA2}, + "statusCheckRollup": [], + } + ) + }, + ) + with pytest.raises(GitHubToolError) as exc: + await github_pr_merge(cwd=str(root), number=7, expected_head_sha=_SHA2) + _assert_code(exc, GITHUB_PR_MISMATCH) + assert len(_read_log(log)) == 1 + + @pytest.mark.asyncio async def test_merge_rejects_failed_and_pending_checks( fake_gh: tuple[Path, Path, Path], @@ -503,17 +603,48 @@ async def test_timeout_and_grandchild_are_bounded( pid = int(_read_log(log)[0]["pid"]) _assert_pid_gone(pid) child_log = root / "child.pid" - os.environ["FAKE_GH_CHILD_LOG"] = str(child_log) + monkeypatch.setenv("FAKE_GH_CHILD_LOG", str(child_log)) _write_script(script, {"mode": "grandchild", "seconds": 60}) - monkeypatch_path = os.environ.get("FAKE_GH_CHILD_LOG") - assert monkeypatch_path == str(child_log) - with pytest.raises(GitHubToolError): - await github_pr_checks_wait( - cwd=str(root), number=7, timeout=0.2, grace=0, max_wait=1 - ) - if child_log.exists(): - os.kill(int(child_log.read_text()), signal.SIGKILL) - await asyncio.sleep(0.3) + child_pid: int | None = None + try: + started = time.monotonic() + with pytest.raises(GitHubToolError) as exc: + await github_pr_checks_wait( + cwd=str(root), number=7, timeout=0.2, grace=0, max_wait=1 + ) + assert exc.value.code == GITHUB_CLI_TIMEOUT + assert time.monotonic() - started < 6 + gh_pid = int(_read_log(log)[1]["pid"]) + _assert_pid_gone(gh_pid) + child_pid = int(child_log.read_text()) + finally: + if child_log.exists(): + child_pid = int(child_log.read_text()) + try: + os.kill(child_pid, signal.SIGKILL) + except ProcessLookupError: + pass + if child_pid is not None: + _assert_pid_gone(child_pid) + + +@pytest.mark.asyncio +async def test_cancellation_kills_gh_and_reraises( + fake_gh: tuple[Path, Path, Path], +) -> None: + root, log, script = fake_gh + _write_script(script, {"mode": "sleep", "seconds": 60}) + task = asyncio.create_task( + github_pr_checks_wait(cwd=str(root), number=7, grace=0, max_wait=60) + ) + for _ in range(100): + if log.exists(): + break + await asyncio.sleep(0.01) + task.cancel() + with pytest.raises(asyncio.CancelledError): + await task + _assert_pid_gone(int(_read_log(log)[0]["pid"])) def _assert_pid_gone(pid: int) -> None: @@ -547,6 +678,38 @@ async def spy(*args: Any, **kwargs: Any) -> asyncio.subprocess.Process: assert "env" not in calls[0][1] +@pytest.mark.asyncio +@pytest.mark.parametrize( + ("argument", "value"), + [ + ("timeout", float("nan")), + ("timeout", float("inf")), + ("interval", float("nan")), + ("interval", float("inf")), + ("max_wait", float("nan")), + ("max_wait", float("inf")), + ("grace", float("nan")), + ("grace", float("inf")), + ], +) +async def test_nonfinite_wait_values_are_refused( + fake_gh: tuple[Path, Path, Path], argument: str, value: float +) -> None: + root, log, _script = fake_gh + with pytest.raises(GitHubToolError) as exc: + await github_pr_checks_wait( + cwd=str(root), + number=7, + interval=value if argument == "interval" else 0.01, + max_wait=value if argument == "max_wait" else 1, + grace=value if argument == "grace" else 0, + timeout=value if argument == "timeout" else 1, + ) + _assert_code(exc, GITHUB_ARGUMENT_REFUSED) + assert exc.value.details == {"argument": argument} + assert not log.exists() + + @pytest.mark.asyncio async def test_argument_validation_never_runs(fake_gh: tuple[Path, Path, Path]) -> None: root, log, _script = fake_gh @@ -577,6 +740,8 @@ async def test_argument_validation_never_runs(fake_gh: tuple[Path, Path, Path]) revision=_SHA, ) _assert_code(exc, GITHUB_ARGUMENT_REFUSED) + assert token not in str(exc.value) + assert exc.value.details == {"argument": "branch"} not_a_directory = root / "not-a-directory" not_a_directory.write_text("file") with pytest.raises(GitHubToolError) as exc: From 4c767c59e364ac6c00cc4306c9bc23bfa6520163 Mon Sep 17 00:00:00 2001 From: Carlos Bacelar Date: Mon, 9 Nov 2026 19:50:11 -0300 Subject: [PATCH 3/3] refactor(tools-github-kit): drop duplicate head check and harden the grace test --- kits/tools-github-kit/python/beddel_tools_github/tools.py | 6 ------ kits/tools-github-kit/tests/test_tools.py | 6 +++++- 2 files changed, 5 insertions(+), 7 deletions(-) diff --git a/kits/tools-github-kit/python/beddel_tools_github/tools.py b/kits/tools-github-kit/python/beddel_tools_github/tools.py index a4140eda..69fb57cd 100644 --- a/kits/tools-github-kit/python/beddel_tools_github/tools.py +++ b/kits/tools-github-kit/python/beddel_tools_github/tools.py @@ -625,12 +625,6 @@ async def github_pr_merge( } if first_view["state"] != "OPEN": raise GitHubToolError(GITHUB_PR_NOT_OPEN, "The pull request is not open.") - head_sha = first_view["headRefOid"] - if expected_value is not None and head_sha != expected_value: - raise GitHubToolError( - GITHUB_PR_MISMATCH, - "The pull request does not match the requested number or head.", - ) status, _names, failed = _rollup_status(first_view["statusCheckRollup"], command) if status in {"pending", "failed"}: raise _check_failure(status, failed) diff --git a/kits/tools-github-kit/tests/test_tools.py b/kits/tools-github-kit/tests/test_tools.py index dc7c38d6..a88231c9 100644 --- a/kits/tools-github-kit/tests/test_tools.py +++ b/kits/tools-github-kit/tests/test_tools.py @@ -389,9 +389,13 @@ async def test_no_checks_at_grace_equal_to_max_wait_passes( fake_gh: tuple[Path, Path, Path], ) -> None: root, log, script = fake_gh + empty = json.dumps(_view([])) + # A slow first poll keeps a revert (grace counted from the end of the first + # poll) from hiding behind the max_wait check. _write_script( script, - *({"stdout": json.dumps(_view([]))} for _ in range(20)), + {"mode": "sleep", "seconds": 0.2, "stdout": empty}, + *({"stdout": empty} for _ in range(20)), ) result = await github_pr_checks_wait( cwd=str(root), number=7, interval=0.05, max_wait=0.3, grace=0.3