Read a pull request's checks and waiting review threads once, and fail chunk-pr merge at once where do-epic parks

This commit is contained in:
2026-11-18 23:08:36 +01:00
parent 4e0b625191
commit 7058e8c13b
5 changed files with 123 additions and 43 deletions
+19 -12
View File
@@ -10,6 +10,8 @@ from forge.commands import Forge, Run
# A human answers in hours, so merge polls once a minute and gives up after 90 minutes. That leaves half an hour for the queue and the checks inside the 2 hours a background command may run; a run that needs more is killed before the give-up message prints, and its next run goes on from what it pushed.
POLL_SECONDS = 60
WAIT_SECONDS = 90 * 60
# The environment variable do-epic sets to 1 for its chunks' workers. With it, merge doesn't wait for an approval: do-epic parks the chunk and polls the forge itself, so the chunk holds no running slot meanwhile (docs/decisions.md → `do-epic: drives one Jira epic …`, "Long gates").
PARKS = "CHUNK_PR_PARKS"
def awaited(forge: Forge, wait_for_approval: bool) -> bool | Failure:
@@ -59,16 +61,21 @@ def approved(number: str, run: Run, sleep: typing.Callable[[float], None] = time
def unanswered(number: str, run: Run) -> Failure | None:
"""A Failure naming the files where a reviewer's comment waits for an answer on pull request number: a review thread nobody resolved, whose last comment someone other than the pull request's author wrote. So a thread the worker answered, as that author, waits for the reviewer again. None where no thread waits."""
read = run(["gh", "api", "graphql", "-f", f"query={THREADS}", "-F", "owner={owner}", "-F", "repo={repo}", "-F", f"number={number}"])
try:
pull = read if isinstance(read, Failure) else json.loads(read)["data"]["repository"]["pullRequest"]
if isinstance(pull, Failure):
return pull
author = pull["author"]["login"]
waiting = sorted({thread["path"] for thread in pull["reviewThreads"]["nodes"] if not thread["isResolved"] and any(comment["author"]["login"] != author for comment in thread["comments"]["nodes"])})
except (ValueError, KeyError, TypeError):
return Failure(f"gh api graphql printed no review threads: {str(read).strip()[:200]}")
if not waiting:
return None
"""A Failure naming the files where a reviewer's comment waits for an answer on pull request number, as `waiting_threads` finds them, or saying why they cannot be read. None where no thread waits."""
waiting = waiting_threads(number, run)
if isinstance(waiting, Failure) or not waiting:
return waiting or None
return Failure(f"a reviewer's comment on pull request {number} waits for an answer, in {', '.join(waiting)}; answer it in its thread, push any fix, and run chunk-pr merge again")
def waiting_threads(number: str, run: Run) -> list[str] | Failure:
"""The files where a reviewer's comment waits for an answer on pull request number, read once: those of each review thread nobody resolved, whose last comment someone other than the pull request's author wrote. So a thread the worker answered, as that author, waits for the reviewer again."""
read = run(["gh", "api", "graphql", "-f", f"query={THREADS}", "-F", "owner={owner}", "-F", "repo={repo}", "-F", f"number={number}"])
if isinstance(read, Failure):
return read
try:
pull = json.loads(read)["data"]["repository"]["pullRequest"]
author = pull["author"]["login"]
return sorted({thread["path"] for thread in pull["reviewThreads"]["nodes"] if not thread["isResolved"] and any(comment["author"]["login"] != author for comment in thread["comments"]["nodes"])})
except (ValueError, KeyError, TypeError):
return Failure(f"gh api graphql printed no review threads: {read.strip()[:200]}")
+10 -9
View File
@@ -45,7 +45,8 @@ merge merges the pull request in its turn: the chunks of one project on this
Where the project's config sets `wait-for-approval = true` (`project-config --help`), it
merges only once GitHub reports the pull request approved as its branch protection
requires. It waits for that outside its turn, so other chunks merge meanwhile, and takes
a new turn once approved.
a new turn once approved. In a chunk do-epic runs, which sets CHUNK_PR_PARKS=1, it
fails at once instead of waiting: do-epic parks the chunk until the approval comes.
It stops, without merging, and says what to do before running it again:
- on a merge conflict in step 1, naming the conflicted files, with the merge in progress;
- where `larv-review scoring-run-owed` exits 1 after step 3, because the chunk owes a
@@ -85,7 +86,7 @@ import sys
import time
import typing
from chunk_pr.approval import approval, approved, awaited, unanswered
from chunk_pr.approval import approval, approved, awaited, PARKS, unanswered
from forge.pulls import checks_passed, merged_pull, open_pull, required_checks
from failure import Failure
from forge.commands import Forge, forge_of, gitea, Run, runner
@@ -119,7 +120,7 @@ def main(argv: list[str]) -> int:
if argv[:1] in (["-h"], ["--help"]):
print(__doc__.strip())
return 0
done = step(argv, runner(os.getcwd()), functools.cache(lambda: located(os.getcwd(), pathlib.Path.home())))
done = step(argv, runner(os.getcwd()), functools.cache(lambda: located(os.getcwd(), pathlib.Path.home())), os.environ.get(PARKS) == "1")
if isinstance(done, Failure):
print(f"chunk-pr: {done.reason}", file=sys.stderr)
return 1
@@ -127,8 +128,8 @@ def main(argv: list[str]) -> int:
return 0
def step(argv: list[str], run: Run, config: Config) -> str | Failure:
"""Run the step argv names: the line to print, or a Failure. A malformed argv doesn't run anything."""
def step(argv: list[str], run: Run, config: Config, parks: bool = False) -> str | Failure:
"""Run the step argv names: the line to print, or a Failure. A malformed argv doesn't run anything. parks is whether a merge fails at once where it would wait for an approval (`merged`)."""
match argv:
case ["open", title, *body] if len(body) <= 1 and not title.startswith("-"):
return Failure("give a title of one line") if not one_line(title) else misfit(title, run, config) or opened(title, body[0] if body else "", run)
@@ -138,7 +139,7 @@ def step(argv: list[str], run: Run, config: Config) -> str | Failure:
return Failure("give a title of one line") if title and not one_line(title[0]) else (misfit(title[0], run, config) if title else None) or marked_ready(run, title[0] if title else None)
case ["merge", *given]:
finishes = finishes_of(given)
return Failure(USAGE) if finishes is None else merged(run, config, finishes=finishes)
return Failure(USAGE) if finishes is None else merged(run, config, finishes=finishes, parks=parks)
case ["clean"]:
return cleaned(run)
return Failure(USAGE)
@@ -304,8 +305,8 @@ def finishes_of(given: list[str]) -> list[list[str]] | None:
return finishes
def merged(run: Run, config: Config, sleep: typing.Callable[[float], None] = time.sleep, finishes: typing.Sequence[list[str]] = ()) -> str | Failure:
"""Merge the branch's pull request in the project's merge queue. Each pass of the loop is one turn in the queue; a pull request that still wants its approval leaves the queue while it waits, so the next chunk merges meanwhile, and takes a new turn once approved."""
def merged(run: Run, config: Config, sleep: typing.Callable[[float], None] = time.sleep, finishes: typing.Sequence[list[str]] = (), parks: bool = False) -> str | Failure:
"""Merge the branch's pull request in the project's merge queue. Each pass of the loop is one turn in the queue; a pull request that still wants its approval leaves the queue while it waits, so the next chunk merges meanwhile, and takes a new turn once approved. Where parks, it doesn't wait for the approval: it fails at once, telling the worker that do-epic parks the chunk."""
found = pull(run)
if isinstance(found, Failure):
return found
@@ -337,7 +338,7 @@ def merged(run: Run, config: Config, sleep: typing.Callable[[float], None] = tim
if not isinstance(taken, AwaitsApproval):
return taken if isinstance(taken, Failure) else taken + absent
# Out of the queue, so the project's other chunks merge while this one waits.
waited = approved(number, run, sleep)
waited = Failure(f"pull request {number} passed its checks and awaits an approval; end your run now, since do-epic parks the chunk and resumes this session once it is approved or a reviewer comments") if parks else approved(number, run, sleep)
if isinstance(waited, Failure):
return waited
+10
View File
@@ -377,6 +377,16 @@ class Merge(unittest.TestCase):
self.assertEqual(merged(checkout, checkout.config, slept.append), "Merged pull request #12 (merge).")
self.assertEqual(slept, [60])
def test_a_merge_that_parks_returns_at_once_while_the_branch_protection_still_wants_a_review(self):
checkout = self.requiring_approval(GITHUB, "REVIEW_REQUIRED")
failed = merged(checkout, checkout.config, self.fail, parks=True)
self.assertEqual(failed.reason, "pull request 12 passed its checks and awaits an approval; end your run now, since do-epic parks the chunk and resumes this session once it is approved or a reviewer comments")
self.assertEqual(checkout.ran.count(GH_DECISION), 1)
def test_a_merge_that_parks_merges_an_approved_pull_request(self):
checkout = self.requiring_approval()
self.assertEqual(merged(checkout, checkout.config, self.fail, parks=True), "Merged pull request #12 (merge).")
def test_an_approval_that_never_comes_leaves_it_unmerged_after_90_minutes(self):
checkout = self.requiring_approval(GITHUB, "REVIEW_REQUIRED")
slept: list[float] = []
+55 -21
View File
@@ -1,5 +1,7 @@
"""Finding a pull request from origin's own branch, and waiting for the checks on its head commit."""
import dataclasses
import fnmatch
import json
import time
import typing
@@ -10,6 +12,8 @@ from forge.commands import Forge, gitea, Run
POLL_SECONDS = 10
# How long checks_passed waits on Gitea for the checks before it gives up; CI took about 3 minutes in 2026-11. gh's watch waits as long as the checks run.
WAIT_SECONDS = 30 * 60
# What gh says of a pull request whose head has no check.
NO_CHECKS = "no checks reported"
def open_pull(forge: Forge, branch: str, head: str, run: Run) -> str | None | Failure:
@@ -57,37 +61,67 @@ def required_checks(forge: Forge, base: str, run: Run) -> set[str] | Failure:
return Failure(f"tea api answered branch {base} in a shape that can't be read: {str(branch)[:200]}")
def checks_passed(forge: Forge, number: str, head: str, required: set[str], run: Run, sleep: typing.Callable[[float], None] = time.sleep, settle: int = 0) -> Failure | None:
"""None once every check on pull request number, whose head commit is head, has passed, or where it has none for settle seconds; a Failure where one fails, or where they have not all passed within WAIT_SECONDS.
@dataclasses.dataclass(frozen=True)
class CheckFailed(Failure):
"""A check on a pull request's head failed, which a new push answers. Any other Failure of a read of the checks says the forge could not be read."""
On Gitea it also waits for a passed check to match each of required: a check CI has yet to queue is no status at all.
@dataclasses.dataclass(frozen=True)
class Pending:
"""The checks on a pull request's head have not all passed yet, and none failed."""
# The checks, or glob patterns, that the protection requires and no passed check matches yet. Empty where a check that reported is still running.
missing: list[str]
def checks_now(forge: Forge, number: str, head: str, required: set[str], run: Run, settled: bool = True) -> Pending | Failure | None:
"""The checks on pull request number, whose head commit is head, read once: None where every one passed, Pending while one still runs, a CheckFailed where one failed, and any other Failure where the forge cannot be read.
On Gitea a passed check must also match each of required: a check CI has yet to queue is no status at all. A head without any check counts as passed once settled, and as pending before, since CI may not have queued its checks yet. gh reports no check as pending before it starts, so there such a head always counts as passed.
"""
if forge == "gh":
listed = run(["gh", "pr", "checks", number, "--json", "bucket"])
if isinstance(listed, Failure):
return None if NO_CHECKS in listed.reason else listed
try:
buckets = {check["bucket"] for check in json.loads(listed)}
except (ValueError, KeyError, TypeError):
return Failure(f"gh pr checks printed no checks: {listed.strip()[:200]}")
if buckets & {"fail", "cancel"}:
return CheckFailed(f"a check on pull request {number} failed")
return Pending([]) if "pending" in buckets else None
status = gitea(run, f"repos/{{owner}}/{{repo}}/commits/{head}/status")
if isinstance(status, Failure):
return status
try:
count, state = status["total_count"], status["state"]
passed = [check["context"] for check in status.get("statuses") or [] if check["status"] == "success"]
except (KeyError, TypeError, AttributeError):
return Failure(f"tea api printed no commit status for {head}: {str(status)[:200]}")
if state not in ("pending", "success"):
return CheckFailed(f"a check on pull request {number} ended in {state}")
# Gitea matches a required context as a glob, and reads a commit with no status as pending, with total_count 0.
missing = sorted(pattern for pattern in required if not fnmatch.filter(passed, pattern))
return None if (count == 0 and settled or state == "success") and not missing else Pending(missing)
def checks_passed(forge: Forge, number: str, head: str, required: set[str], run: Run, sleep: typing.Callable[[float], None] = time.sleep, settle: int = 0) -> Failure | None:
"""None once every check on pull request number, whose head commit is head, has passed, or where it has none for settle seconds; a Failure where one fails, or where they have not all passed within WAIT_SECONDS. checks_now says what counts as passed on Gitea."""
if forge == "gh":
for waited in range(0, settle + 1, POLL_SECONDS):
watched = run(["gh", "pr", "checks", number, "--watch", "--fail-fast"])
if not isinstance(watched, Failure):
return None
if "no checks reported" not in watched.reason:
if NO_CHECKS not in watched.reason:
return watched
if waited < settle:
sleep(POLL_SECONDS)
return None
for _ in range(WAIT_SECONDS // POLL_SECONDS + 1):
status = gitea(run, f"repos/{{owner}}/{{repo}}/commits/{head}/status")
if isinstance(status, Failure):
return status
try:
count, state = status["total_count"], status["state"]
passed = [check["context"] for check in status.get("statuses") or [] if check["status"] == "success"]
except (KeyError, TypeError, AttributeError):
return Failure(f"tea api printed no commit status for {head}: {str(status)[:200]}")
if state not in ("pending", "success"):
return Failure(f"a check on pull request {number} ended in {state}")
# Gitea matches a required context as a glob, and reads a commit with no status as pending, with total_count 0.
missing = sorted(pattern for pattern in required if not fnmatch.filter(passed, pattern))
if (count == 0 and _ * POLL_SECONDS >= settle or state == "success") and not missing:
return None
if _ < WAIT_SECONDS // POLL_SECONDS:
polls = WAIT_SECONDS // POLL_SECONDS
for poll in range(polls + 1):
now = checks_now(forge, number, head, required, run, settled=poll * POLL_SECONDS >= settle)
if not isinstance(now, Pending):
return now
if poll < polls:
sleep(POLL_SECONDS)
waited_on = f"{', '.join(missing)}, which the protection requires, never passed" if missing else "a check is still pending"
waited_on = f"{', '.join(now.missing)}, which the protection requires, never passed" if now.missing else "a check is still pending"
return Failure(f"gave up on pull request {number} after {WAIT_SECONDS // 60} minutes: {waited_on}")
+29 -1
View File
@@ -6,8 +6,9 @@ import unittest
sys.path.insert(0, str(pathlib.Path(__file__).resolve().parents[1]))
from forge.pulls import checks_passed, open_pull, POLL_SECONDS, required_checks, WAIT_SECONDS
from forge.pulls import CheckFailed, checks_now, checks_passed, open_pull, Pending, POLL_SECONDS, required_checks, WAIT_SECONDS
from forge.commands import forge_of, gitea, url_beside
from failure import Failure
class ForgeOf(unittest.TestCase):
@@ -69,6 +70,33 @@ class RequiredChecks(unittest.TestCase):
self.assertEqual(required_checks("gh", "main", self.fail), set())
class ChecksNow(unittest.TestCase):
def test_reads_on_gh_once_and_says_a_check_is_pending(self):
read = []
self.assertEqual(checks_now("gh", "7", "abc", set(), lambda command: read.append(command) or '[{"bucket": "pass"}, {"bucket": "pending"}]'), Pending([]))
self.assertEqual(read, [["gh", "pr", "checks", "7", "--json", "bucket"]])
def test_takes_on_gh_passed_and_skipped_checks_and_no_checks_as_passed(self):
self.assertIsNone(checks_now("gh", "7", "abc", set(), lambda command: '[{"bucket": "pass"}, {"bucket": "skipping"}]'))
self.assertIsNone(checks_now("gh", "7", "abc", set(), lambda command: Failure("gh pr checks: no checks reported on the 'x' branch")))
def test_fails_on_gh_where_a_check_failed_or_was_cancelled_or_gh_fails(self):
for bucket in ("fail", "cancel"):
self.assertEqual(checks_now("gh", "7", "abc", set(), lambda command: f'[{{"bucket": "pending"}}, {{"bucket": "{bucket}"}}]'), CheckFailed("a check on pull request 7 failed"))
self.assertEqual(checks_now("gh", "7", "abc", set(), lambda command: Failure("no network")), Failure("no network"))
self.assertEqual(checks_now("tea", "1", "abc", set(), tea(['{"state": "failure", "total_count": 1}'])), CheckFailed("a check on pull request 1 ended in failure"))
self.assertEqual(checks_now("gh", "7", "abc", set(), lambda command: "[1]").reason, "gh pr checks printed no checks: [1]")
def test_reads_on_tea_once_and_names_each_required_check_that_has_not_passed(self):
self.assertEqual(checks_now("tea", "1", "abc", {"lint"}, tea(['{"state": "pending", "total_count": 0, "statuses": []}'])), Pending(["lint"]))
self.assertEqual(checks_now("tea", "1", "abc", set(), tea(['{"state": "pending", "total_count": 1}'])), Pending([]))
self.assertIsNone(checks_now("tea", "1", "abc", set(), tea(['{"state": "success", "total_count": 1}'])))
def test_takes_a_commit_with_no_status_on_tea_as_pending_until_settled(self):
self.assertEqual(checks_now("tea", "1", "abc", set(), tea(['{"state": "pending", "total_count": 0}']), settled=False), Pending([]))
self.assertIsNone(checks_now("tea", "1", "abc", set(), tea(['{"state": "pending", "total_count": 0}'])))
class ChecksPassed(unittest.TestCase):
def test_waits_on_tea_while_a_check_is_pending(self):
slept = []