Files
2026-11-19 18:07:54 +01:00

71 lines
5.0 KiB
Python

"""The human approval that `chunk-pr merge` waits for where the project's config sets `wait-for-approval`."""
import typing
from forge.reviews import APPROVED, CHANGES_REQUESTED, github_decision, REVIEW_REQUIRED, waiting_threads
from failure import Failure
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, by_human: bool) -> bool | Failure:
"""Whether merge waits for an approval. Never where a person merges the pull request (by_human): that person reads its approvals. Otherwise as the project config's `wait-for-approval` says; chunk-pr reads approvals on GitHub only, so a Gitea project that sets it fails, and the chunk never merges past an approval the config requires."""
if by_human:
return False
if wait_for_approval and forge != "gh":
return Failure("the project's config sets wait-for-approval, but chunk-pr reads approvals on GitHub only, so it cannot merge this pull request; ask the human to merge it")
return wait_for_approval
def approval(number: str, run: Run) -> bool | Failure:
"""Whether GitHub reports pull request number approved, as its branch protection asks, read once: False while it still wants a review. A Failure where a reviewer requested changes, or where the protection asks for no review."""
decision = github_decision(number, run)
if isinstance(decision, Failure):
return decision
if decision == CHANGES_REQUESTED:
return Failure(f"a reviewer requested changes on pull request {number}")
if not decision:
return Failure("wait-for-approval is set, but the branch protection requires no review, so GitHub reports no decision; ask the human to require a review in the protection or to set wait-for-approval to false")
if decision not in (APPROVED, REVIEW_REQUIRED):
return Failure(f"GitHub reports the review decision {decision!r} on pull request {number}, and chunk-pr doesn't know that decision")
return decision == APPROVED
def approved(number: str, run: Run, sleep: typing.Callable[[float], None]) -> Failure | None:
"""None once GitHub reports pull request number approved; a Failure where `approval` fails, where a reviewer's comment waits for an answer, or where no approval came within WAIT_SECONDS."""
for waited in range(0, WAIT_SECONDS + 1, POLL_SECONDS):
read = approval(number, run)
if read is True or isinstance(read, Failure):
return None if read is True else read
asked = unanswered(number, run)
if asked is not None:
return asked
if waited < WAIT_SECONDS:
sleep(POLL_SECONDS)
return Failure(f"pull request {number} wasn't approved within {WAIT_SECONDS // 60} minutes; run chunk-pr merge again once it is")
def left_to_park(number: str, run: Run) -> Failure:
"""Why a merge under PARKS ends at once where pull request number passed its checks and awaits an approval, in place of waiting as `approved` does: a reviewer's comment waits for an answer, which the worker gives first, or else do-epic parks the chunk, so the worker ends its run."""
return unanswered(number, run) or 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")
def left_to_a_person(number: str, parks: bool) -> str:
"""What merge prints where the project's config leaves the merge of pull request number to a person (`merge = "human"`): what the worker does now, which under PARKS is to end its run, as in `left_to_park`."""
now = "end your run now, since do-epic parks the chunk and resumes this session once it is merged or a reviewer comments." if parks else "leave the merge to them, and report the chunk as ready to merge. Once it is merged, run chunk-pr clean in this worktree."
return f"Marked pull request #{number} ready. It passed its checks and awaits a person's merge, since the project's config sets `merge = \"human\"`: {now}"
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, 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):
return waiting
if not waiting:
return 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")