Files
claude-config/bin/forge/pulls.py
T

218 lines
12 KiB
Python

"""Finding a pull request from origin's own branch, listing the ready ones, reading whether one merges into its base, and waiting for the checks on its head commit."""
import dataclasses
import fnmatch
import json
import re
import typing
from failure import Failure
from forge.commands import Forge, gitea, Run
from forge.reviews import GITEA_DRAFT
# How long checks_passed waits between two reads: of the head commit's status on Gitea, or of gh's watch while it reports no checks.
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:
"""The number of the open pull request from origin's own branch whose head is head; None where there is none."""
return pull_at(forge, branch, head, "open", run)
def merged_pull(forge: Forge, branch: str, head: str, run: Run) -> str | None | Failure:
"""The number of the merged pull request from origin's own branch whose head was head; None where there is none. A rebase or a squash merge counts: the pull request keeps the head it had."""
return pull_at(forge, branch, head, "merged", run)
def pull_at(forge: Forge, branch: str, head: str, state: typing.Literal["open", "merged"], run: Run) -> str | None | Failure:
if forge == "gh":
# gh lists the open pull requests unless told another state.
listed = run(["gh", "pr", "list", "--head", branch, *(["--state", "merged"] if state == "merged" else []), "--json", "number,headRefOid,isCrossRepository", "--template", "{{range .}}{{.number}}\t{{.headRefOid}}\t{{.isCrossRepository}}\n{{end}}"])
if isinstance(listed, Failure):
return listed
rows = [line.split("\t") for line in listed.splitlines()]
return next((row[0] for row in rows if row[1:] == [head, "false"]), None)
# Gitea lists at most 50 a page; the pull request sought is among the newest. Gitea has no merged state: a merged pull request is a closed one marked merged.
pulls = gitea(run, f"repos/{{owner}}/{{repo}}/pulls?state={'open' if state == 'open' else 'closed'}&limit=50")
if isinstance(pulls, Failure):
return pulls
try:
# Match the label, not the ref: once origin deletes a merged branch, Gitea reports its ref as refs/pull/<N>/head.
return next((str(pull["number"]) for pull in pulls if pull["head"]["label"] == branch and pull["head"]["sha"] == head and pull["head"]["repo"]["full_name"] == pull["base"]["repo"]["full_name"] and (state == "open" or pull["merged"] is True)), None)
except (KeyError, TypeError):
return Failure(f"tea api listed pull requests in a shape that can't be read: {str(pulls)[:200]}")
@dataclasses.dataclass(frozen=True)
class ReadyPull:
"""An open pull request from one of origin's own branches that is no draft."""
number: str
url: str
# The commit ID of its head.
head: str
def ready_pulls(forge: Forge, run: Run) -> list[ReadyPull] | Failure:
"""Each open pull request from origin's own branches that is no draft, which Gitea tells by its title (GITEA_DRAFT); Gitea names no head repo for a fork that was deleted. A row is left out where its head is no commit ID, since the caller passes the head to git, or where its number is not all digits, since the caller prints it."""
if forge == "gh":
# A limit: an awaited pull request past the first 100 open ones, drafts and forks counted, is not seen. `--draft=false` would make gh search, and GitHub's search index lags a pull request just marked ready.
listed = run(["gh", "pr", "list", "--limit", "100", "--json", "number,url,headRefOid,isDraft,isCrossRepository", "--template", "{{range .}}{{.number}}\t{{.url}}\t{{.headRefOid}}\t{{.isDraft}}\t{{.isCrossRepository}}\n{{end}}"])
if isinstance(listed, Failure):
return listed
rows = [line.split("\t") for line in listed.splitlines()]
found = [ReadyPull(*row[:3]) for row in rows if row[3:] == ["false", "false"]]
else:
pulls = gitea(run, "repos/{owner}/{repo}/pulls?state=open&limit=50")
if isinstance(pulls, Failure):
return pulls
try:
found = [ReadyPull(str(pull["number"]), pull["html_url"], pull["head"]["sha"]) for pull in pulls if (pull["head"]["repo"] or {}).get("full_name") == pull["base"]["repo"]["full_name"] and not pull["title"].upper().startswith(GITEA_DRAFT)]
except (AttributeError, KeyError, TypeError):
return Failure(f"tea api listed pull requests in a shape that can't be read: {str(pulls)[:200]}")
return [pull for pull in found if pull.number.isascii() and pull.number.isdigit() and isinstance(pull.head, str) and re.fullmatch(r"[0-9a-f]{40,64}", pull.head)]
# Why a pull request doesn't merge into its base as it stands, as the words after "pull request #<N>".
CONFLICTS = "conflicts with its base branch"
BEHIND = "is behind its base branch, whose protection requires it up to date"
def unmergeable(forge: Forge, number: str, run: Run) -> str | None | Failure:
"""Why pull request number doesn't merge into its base as it stands: CONFLICTS or BEHIND. None where it merges, and while GitHub still computes whether it does.
GitHub reports a pull request as behind only where the base's protection requires an up-to-date branch. Gitea's `mergeable` never tells that case. Gitea also answers false for the seconds it checks for conflicts after a push to either branch, which reads as CONFLICTS here.
"""
if forge == "gh":
viewed = run(["gh", "pr", "view", number, "--json", "mergeable,mergeStateStatus"])
if isinstance(viewed, Failure):
return viewed
try:
state = json.loads(viewed)
return CONFLICTS if state["mergeable"] == "CONFLICTING" else BEHIND if state["mergeStateStatus"] == "BEHIND" else None
except (ValueError, KeyError, TypeError):
return Failure(f"gh pr view printed no mergeability: {viewed.strip()[:200]}")
pull = gitea(run, f"repos/{{owner}}/{{repo}}/pulls/{number}")
if isinstance(pull, Failure):
return pull
try:
return CONFLICTS if pull["mergeable"] is False else None
except (KeyError, TypeError):
return Failure(f"tea api answered pull request {number} in a shape that can't be read: {str(pull)[:200]}")
def other_base(forge: Forge, number: str, base: str, run: Run) -> Failure | None:
"""A Failure, naming both branches, where the forge merges pull request number into another branch than base, the one its checkout takes. None where the two agree.
A tool decides from the checkout's base who merges the pull request, so it doesn't act on one the forge would merge elsewhere."""
onto = base_branch(forge, number, run)
if isinstance(onto, Failure) or onto == base:
return onto if isinstance(onto, Failure) else None
return Failure(f"pull request #{number} merges into {onto} on the forge, but this checkout takes {base} as the base of its branch; a person settles which holds, and changes the pull request's base on the forge or the branch's `chunk-base` in git's config")
def base_branch(forge: Forge, number: str, run: Run) -> str | Failure:
"""The branch the forge merges pull request number into."""
if forge == "gh":
viewed = run(["gh", "pr", "view", number, "--json", "baseRefName"])
if isinstance(viewed, Failure):
return viewed
try:
name = json.loads(viewed)["baseRefName"]
except (ValueError, KeyError, TypeError):
name = None
return name if name and isinstance(name, str) else Failure(f"gh pr view printed no base branch: {viewed.strip()[:200]}")
pull = gitea(run, f"repos/{{owner}}/{{repo}}/pulls/{number}")
if isinstance(pull, Failure):
return pull
try:
name = pull["base"]["ref"]
except (KeyError, TypeError):
name = None
return name if name and isinstance(name, str) else Failure(f"tea api answered pull request {number} in a shape that can't be read: {str(pull)[:200]}")
def required_checks(forge: Forge, base: str, run: Run) -> set[str] | Failure:
"""The checks, or glob patterns of checks, that the forge's protection of the branch base requires before a merge. None on GitHub, where gh's watch covers them.
Gitea answers a branch with the protection rule it applies there, so the cut never picks among the rules itself.
"""
if forge == "gh":
return set()
branch = gitea(run, f"repos/{{owner}}/{{repo}}/branches/{base}")
if isinstance(branch, Failure):
return branch
try:
return set(branch.get("status_check_contexts") or []) if branch.get("enable_status_check") else set()
except (AttributeError, TypeError):
return Failure(f"tea api answered branch {base} in a shape that can't be read: {str(branch)[:200]}")
@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."""
@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. On GitHub such a head always counts as passed: gh cannot tell a head whose checks have yet to start from a head that has none.
"""
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], 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 not in watched.reason:
return watched
if waited < settle:
sleep(POLL_SECONDS)
return None
polls = WAIT_SECONDS // POLL_SECONDS
now: Pending | Failure | None = None
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(now.missing)}, which the protection requires, never passed" if isinstance(now, Pending) and now.missing else "a check is still pending"
return Failure(f"gave up on pull request {number} after {WAIT_SECONDS // 60} minutes: {waited_on}")