Coverage for src/keel/github.py: 100%

307 statements  

« prev     ^ index     » next       coverage.py v7.16.2, created at 2026-10-20 19:17 +0000

1"""Thin, fail-soft ``gh`` (GitHub CLI) wrappers (argv, no shell). 

2 

3Like :mod:`keel.git`, these build the exact ``gh`` command for each backbone 

4operation and run it via the injectable ``_run`` seam. Command construction is 

5unit-tested offline; live behaviour is opt-in. 

6""" 

7 

8from __future__ import annotations 

9 

10import base64 

11import json 

12import random 

13import re 

14import time 

15import urllib.parse 

16from collections.abc import Sequence 

17 

18from .runner import CommandResult, run_argv 

19 

20_TRANSIENT_PATTERNS = ( 

21 "rate limit", 

22 "secondary rate limit", 

23 "too many requests", 

24 "connection reset", 

25 "connection refused", 

26 "could not resolve host", 

27 "network is unreachable", 

28 "tls handshake", 

29 "ssl error", 

30 "timed out", 

31 "timeout", 

32 "500 internal server error", 

33 "502 bad gateway", 

34 "503 service unavailable", 

35 "504 gateway timeout", 

36 "http 429", 

37 "http 500", 

38 "http 502", 

39 "http 503", 

40 "http 504", 

41) 

42 

43 

44def is_transient_error(result: CommandResult) -> bool: 

45 """Return whether ``result`` failed due to a transient network or rate limit error.""" 

46 if result.ok: 

47 return False 

48 if result.timed_out: 

49 return True 

50 combined = f"{result.stderr} {result.stdout}".lower() 

51 for pattern in _TRANSIENT_PATTERNS: 

52 if pattern in combined: 

53 return True 

54 return False 

55 

56 

57def run_argv_retry( 

58 argv: Sequence[str], 

59 *, 

60 cwd: str | None = None, 

61 max_attempts: int = 3, 

62 backoff_factor: float = 1.0, 

63 jitter: bool = True, 

64 _run=None, 

65 _sleep=None, 

66) -> CommandResult: 

67 """Execute a ``gh`` command with jittered exponential backoff on transient errors. 

68 

69 Retries only transient network, 5xx server errors, or secondary rate limit errors. 

70 Deterministic and dependency-free, with injectable ``_run`` and ``_sleep`` seams 

71 for offline testing at 100% line + branch coverage. 

72 """ 

73 sleep_fn = _sleep or time.sleep 

74 attempt = 1 

75 while True: 

76 result = run_argv(argv, cwd=cwd, **_kw(_run)) 

77 if result.ok or attempt >= max_attempts or not is_transient_error(result): 

78 return result 

79 delay = backoff_factor * (2 ** (attempt - 1)) 

80 if jitter: 

81 delay += random.uniform(0.0, 0.5) if _sleep is None else 0.1 # nosec B311 

82 sleep_fn(delay) 

83 attempt += 1 

84 

85 

86def open_pr( 

87 title: str, body: str, base: str, head: str, *, cwd: str | None = None, _run=None 

88) -> CommandResult: 

89 return run_argv( 

90 ["gh", "pr", "create", "--title", title, "--body", body, "--base", base, "--head", head], 

91 cwd=cwd, 

92 **_kw(_run), 

93 ) 

94 

95 

96def ci_conclusion(pr: int | str, *, cwd: str | None = None, _run=None) -> str | None: 

97 """Return the PR's check-rollup state (e.g. SUCCESS/FAILURE/PENDING). 

98 

99 Three distinct answers, because collapsing them is what let a PR with **no 

100 checks at all** read as clear to merge (issue #675): 

101 

102 * a conclusion string — checks reported, here is what they said 

103 * ``""`` — ``gh`` answered and the rollup is **empty**: nothing ran for this 

104 head. A fact about the *PR*. 

105 * ``None`` — ``gh`` could not be asked. A fact about the *runner*. 

106 

107 Only the caller can weigh those, so this returns the empty string rather than 

108 folding it into ``None``. :func:`keel.ship.ci_ran` reads the distinction. 

109 

110 ``statusCheckRollup`` retains every historical run of a check, not just the 

111 latest — a check that failed once and was later rerun to green still carries 

112 its old FAILURE conclusion in the raw list, and a freshly requeued rerun may 

113 carry no timestamp at all yet. The ``--jq`` filter dedupes by check identity 

114 (``context`` for legacy commit statuses, ``name`` for check runs — an empty 

115 string is treated the same as absent, matching the Python-side dedupe used 

116 by the merge gate) down to each check's most recent entry before collecting 

117 conclusions. "Most recent" prefers an entry genuinely still in flight (no 

118 ``conclusion`` yet *and* a recognized pending ``status``) over any 

119 concluded one for the same check — a new run cannot be queued before the 

120 previous one concluded — and otherwise compares ``completedAt``, falling 

121 back to ``startedAt``. Requiring a recognized pending ``status`` (not 

122 merely an absent ``conclusion``) means a malformed or unexpected payload 

123 shape can never mask a genuine stale failure. This mirrors 

124 :func:`keel.cli._rollup_recency`/``_PENDING_CHECK_STATES``, manually 

125 verified against a real ``jq`` binary; jq output can't be exercised by 

126 this module's offline unit tests (see the module docstring). 

127 """ 

128 pending_states = '"EXPECTED","PENDING","QUEUED","REQUESTED","WAITING","IN_PROGRESS"' 

129 jq = ( 

130 "[.statusCheckRollup[]] " 

131 "| group_by(" 

132 '(.context | select(. != null and . != "")) ' 

133 '// (.name | select(. != null and . != "")) ' 

134 '// ""' 

135 ") " 

136 "| map(max_by([" 

137 '((.conclusion == null or .conclusion == "") and ' 

138 '(((.status // .state) | if type == "string" then ascii_upcase else "" end) ' 

139 "| IN(" + pending_states + "))), " 

140 '(.completedAt // .startedAt // "")' 

141 "])) " 

142 "| map(" 

143 'if (.conclusion != null and .conclusion != "") then .conclusion ' 

144 'elif (((.status // .state) | if type == "string" then ascii_upcase else "" end) ' 

145 "| IN(" + pending_states + ')) then "PENDING" ' 

146 'elif (.state != null and .state != "") then .state ' 

147 "else empty end" 

148 ") " 

149 '| unique | join(",")' 

150 ) 

151 result = run_argv( 

152 ["gh", "pr", "view", str(pr), "--json", "statusCheckRollup", "--jq", jq], 

153 cwd=cwd, 

154 **_kw(_run), 

155 ) 

156 if not result.ok: 

157 return None 

158 return result.stdout.strip() 

159 

160 

161def ci_check_names(pr: int | str, *, cwd: str | None = None, _run=None) -> list[str] | None: 

162 """The distinct check identities reported for ``pr``, or ``None`` when ``gh`` failed. 

163 

164 Used for the **count** an operator sees, so "0 checks" is a visible fact rather 

165 than something inferred from a blank word. Identity is ``context`` for legacy 

166 commit statuses and ``name`` for check runs — the same identity 

167 :func:`ci_conclusion` dedupes on, so the two views agree about what "one check" 

168 is. ``[]`` means the rollup is genuinely empty; ``None`` means ``gh`` could not 

169 be asked. 

170 """ 

171 jq = ( 

172 "[.statusCheckRollup[] " 

173 '| (.context | select(. != null and . != "")) ' 

174 '// (.name | select(. != null and . != "")) ' 

175 "// empty] " 

176 "| unique | .[]" 

177 ) 

178 return _rollup_strings(pr, jq, cwd=cwd, _run=_run) 

179 

180 

181def ci_workflow_names(pr: int | str, *, cwd: str | None = None, _run=None) -> list[str] | None: 

182 """The distinct **workflow** names that reported for ``pr``, or ``None`` on failure. 

183 

184 Deliberately not :func:`ci_check_names`. ``knobs.ci_workflows`` is keyed by the 

185 *workflow* name (``CI``, ``CodeQL``), but the rollup reports *job* names — a 

186 matrix job appears as ``test (py3.13 / ubuntu-latest)``, never as ``CI``. Asking 

187 the presence question against job names would report every declared workflow 

188 missing on a repo that uses a matrix, which is most of them. 

189 

190 ``workflowName`` is what a check run carries for this; legacy commit statuses have 

191 none, so they fall back to ``context``/``name`` — a project that declares a bare 

192 status-check name still matches. 

193 """ 

194 jq = ( 

195 "[.statusCheckRollup[] " 

196 '| (.workflowName | select(. != null and . != "")) ' 

197 '// (.context | select(. != null and . != "")) ' 

198 '// (.name | select(. != null and . != "")) ' 

199 "// empty] " 

200 "| unique | .[]" 

201 ) 

202 return _rollup_strings(pr, jq, cwd=cwd, _run=_run) 

203 

204 

205def _rollup_strings(pr, jq: str, *, cwd: str | None, _run) -> list[str] | None: 

206 result = run_argv( 

207 ["gh", "pr", "view", str(pr), "--json", "statusCheckRollup", "--jq", jq], 

208 cwd=cwd, 

209 **_kw(_run), 

210 ) 

211 if not result.ok: 

212 return None 

213 return [line.strip() for line in result.stdout.splitlines() if line.strip()] 

214 

215 

216def merged_prs( 

217 *, search: str | None = None, limit: int = 100, cwd: str | None = None, _run=None 

218) -> CommandResult: 

219 """List recently-merged PR numbers as a JSON array (``[{"number": N}, ...]``). 

220 

221 Thin I/O for ``capture-verify`` transport derivation: the authoritative 

222 merged-PR set is read from the host instead of trusting the agent's args. 

223 ``search`` narrows the set (e.g. ``"merged:>=2026-06-01"``). Fail-soft — 

224 the caller inspects ``result.ok`` and degrades gracefully when offline. 

225 """ 

226 argv = ["gh", "pr", "list", "--state", "merged", "--limit", str(limit), "--json", "number"] 

227 if search: 

228 argv += ["--search", search] 

229 return run_argv(argv, cwd=cwd, **_kw(_run)) 

230 

231 

232def list_prs( 

233 *, head: str | None = None, limit: int = 100, cwd: str | None = None, _run=None 

234) -> CommandResult: 

235 """List PRs (any state) as a JSON array (``[{"number": N, "headRefName": ...}, ...]``). 

236 

237 Thin I/O for dry-run integrity verification: the PRs that exist around a 

238 rehearsed run are read from the host. ``head`` narrows to a specific head 

239 branch. Fail-soft — the caller inspects ``result.ok`` and degrades to "no 

240 PRs observed" when offline. 

241 """ 

242 argv = [ 

243 "gh", 

244 "pr", 

245 "list", 

246 "--state", 

247 "all", 

248 "--limit", 

249 str(limit), 

250 "--json", 

251 "number,headRefName", 

252 ] 

253 if head: 

254 argv += ["--head", head] 

255 return run_argv(argv, cwd=cwd, **_kw(_run)) 

256 

257 

258def pr_labels( 

259 pr: int | str, 

260 *, 

261 repo: str | None = None, 

262 cwd: str | None = None, 

263 _run=None, 

264 _sleep=None, 

265) -> list[str] | None: 

266 """The label names currently on ``pr``, or ``None`` when ``gh`` could not be asked. 

267 

268 ``None`` is a fact about the runner, not the PR: callers that gate on a label must 

269 treat it as "unknown" and go on, never as "no labels" (#1504). ``repo`` 

270 (``owner/name``) pins the read to the repository the caller's other reads use, so a 

271 fork's PR with the same number is never read instead; the read is retried like 

272 :func:`pr_files`, since a single ``gh`` blip would otherwise skip the early check. 

273 """ 

274 argv = ["gh", "pr", "view", str(pr), "--json", "labels", "--jq", ".labels[].name"] 

275 if repo: 

276 argv += ["--repo", repo] 

277 return _lines(argv, cwd=cwd, _run=_run, _sleep=_sleep) 

278 

279 

280def pr_state(pr: int | str, *, cwd: str | None = None, _run=None) -> str | None: 

281 """Live PR state as ``open`` / ``merged`` / ``closed``, or ``None`` when unreadable. 

282 

283 ``None`` is a fact about the **runner** (``gh`` missing, offline, no auth) and must 

284 not be read as a fact about the PR — the caller maps it to ``unknown``, never to 

285 ``missing``. A ``gh`` call that succeeds and reports no such PR is the only thing 

286 that means the PR is gone. 

287 """ 

288 result = run_argv( 

289 ["gh", "pr", "view", str(pr), "--json", "state", "--jq", ".state"], 

290 cwd=cwd, 

291 **_kw(_run), 

292 ) 

293 if not result.ok: 

294 return None 

295 raw = result.stdout.strip().lower() 

296 return raw if raw in ("open", "merged", "closed") else None 

297 

298 

299def pr_files(pr: int | str, *, cwd: str | None = None, _run=None, _sleep=None) -> list[str] | None: 

300 """Paths the pull request changed — what it *meant* to change (#561). 

301 

302 Read from GitHub rather than from a local diff on purpose: after a squash-merge 

303 the head branch is usually deleted, so the branch tip may not exist locally at 

304 the moment this check runs. ``None`` when ``gh`` could not be asked. 

305 """ 

306 return _lines( 

307 ["gh", "pr", "view", str(pr), "--json", "files", "--jq", ".files[].path"], 

308 cwd=cwd, 

309 _run=_run, 

310 _sleep=_sleep, 

311 ) 

312 

313 

314def commit_files(sha: str, *, cwd: str | None = None, _run=None, _sleep=None) -> list[str] | None: 

315 """Paths a commit changed against its first parent — what actually *landed*. 

316 

317 For a squash-merge the commit has one parent, so this is precisely the set of 

318 files the merge wrote onto the base branch. ``None`` when ``gh`` could not be 

319 asked; an empty list means the commit changed nothing, which is itself a fact. 

320 """ 

321 return _lines( 

322 ["gh", "api", f"repos/{{owner}}/{{repo}}/commits/{sha}", "--jq", ".files[].filename"], 

323 cwd=cwd, 

324 _run=_run, 

325 _sleep=_sleep, 

326 ) 

327 

328 

329def pr_added_lines( 

330 pr: int | str, *, cwd: str | None = None, _run=None, _sleep=None 

331) -> dict[str, list[str] | None] | None: 

332 """Added lines per file in ``pr`` (#1511). ``None`` value marks an unverifiable file.""" 

333 rows = _json_rows( 

334 ["gh", "api", f"repos/{{owner}}/{{repo}}/pulls/{pr}/files?per_page=100"], 

335 cwd=cwd, 

336 _run=_run, 

337 _sleep=_sleep, 

338 ) 

339 if rows is None: 

340 return None 

341 out: dict[str, list[str] | None] = {} 

342 for row in rows: 

343 path = str(row.get("filename") or "").strip() 

344 if not path: 

345 continue 

346 patch = row.get("patch") 

347 if row.get("status") not in ("added", "modified"): 

348 out[path] = None 

349 elif isinstance(patch, str): 

350 out[path] = [line[1:] for line in patch.splitlines() if line.startswith("+")] 

351 elif row.get("changes") == 0: 

352 out[path] = [] 

353 else: 

354 out[path] = None 

355 return out 

356 

357 

358def commit_file_content( 

359 sha: str, path: str, *, cwd: str | None = None, _run=None, _sleep=None 

360) -> str | None: 

361 """UTF-8 file content at ``sha`` from GitHub's contents endpoint (<= 1 MB), or ``None``.""" 

362 quoted = urllib.parse.quote(path.lstrip("/"), safe="/") 

363 data = rest_json( 

364 run_argv_retry( 

365 ["gh", "api", f"repos/{{owner}}/{{repo}}/contents/{quoted}?ref={sha}"], 

366 cwd=cwd, 

367 _run=_run, 

368 _sleep=_sleep, 

369 ) 

370 ) 

371 if ( 

372 not isinstance(data, dict) 

373 or data.get("type") != "file" 

374 or data.get("encoding") != "base64" 

375 or not isinstance(data.get("content"), str) 

376 ): 

377 return None 

378 try: 

379 return base64.b64decode("".join(data["content"].split()), validate=True).decode("utf-8") 

380 except (ValueError, UnicodeDecodeError): 

381 return None 

382 

383 

384def _lines(argv: list[str], *, cwd: str | None, _run, _sleep=None) -> list[str] | None: 

385 """Read newline-separated ``gh`` output, retrying transient failures. 

386 

387 Routed through :func:`run_argv_retry` rather than :func:`run_argv`: the retry 

388 was written, tested, and called by nothing (#938). These are the reads it was 

389 written for — ``pr_files`` and ``commit_files`` — and one 

390 ``keel verify-merge`` run makes ``4 + N`` of 

391 them, N being the pull requests merged in the window (5–25 in this repo). Since 

392 #936 made an unreadable input exit 2 instead of quietly passing, a single blip 

393 on the busiest day produces a loud wrong answer, and a gate that cries wolf is 

394 a gate that gets bypassed. 

395 

396 Retries only transient errors, so a persistent failure still returns ``None`` 

397 and still becomes ``unknown``. The retry must not become a slower way to 

398 fail open. 

399 """ 

400 result = run_argv_retry(argv, cwd=cwd, _run=_run, _sleep=_sleep) 

401 if not result.ok: 

402 return None 

403 return [line.strip() for line in result.stdout.splitlines() if line.strip()] 

404 

405 

406#: How far back one `gh pr list` page reaches. A window older than this many 

407#: merges is reported as unreadable rather than empty — see #937 in the docstring 

408#: below. Named so the ceiling is one place to read and one place to change. 

409MERGED_PAGE_LIMIT = 100 

410 

411 

412def prs_merged_between( 

413 base: str, 

414 since: str, 

415 until: str, 

416 *, 

417 cwd: str | None = None, 

418 _run=None, 

419 _sleep=None, 

420 limit: int = MERGED_PAGE_LIMIT, 

421) -> list[int] | None: 

422 """Pull request numbers merged into ``base`` in the half-open window (#561). 

423 

424 ``since``/``until`` are ISO-8601 timestamps. This is the window in which another 

425 merge can land work that a branch created before ``since`` will not contain — the 

426 precondition for an update-branch squash reverting it. 

427 

428 ``None`` when the answer could not be read — including when the page came back 

429 **truncated**, which is #933's rule reached by a different mechanism (#937). 

430 ``gh pr list`` returns the *newest* N merges, and the window filter used to run 

431 inside ``--jq``, after that cut. On a repository where more than ``limit`` 

432 pull requests merged since the window closed, the window's merges are not in 

433 the page at all, the filter matches nothing, and an empty list reads as 

434 "nothing overtook this merge" — a successful read that saw none of the answer. 

435 

436 Live here, not latent: this repo has ~500 merged pull requests and 

437 ``docs/keel/cli.md`` documents a retrospective ``verify-merge --pr 543`` on a 

438 pull request from a previous month, which is exactly the shape that trips it. 

439 

440 Truncation is detectable because the page is newest-first: if it came back 

441 **full** and its oldest entry still merged at or after ``since``, the page 

442 never reached back far enough to contain the window. Paginating would also 

443 work, but on a repo this size a retrospective check would walk hundreds of 

444 pull requests to answer one question; saying "I could not see that far" is 

445 honest and cheap. Raising ``limit`` is a separate tuning decision. 

446 

447 The filter therefore runs in Python rather than ``--jq``: the truncation 

448 check needs the raw ``mergedAt`` values, which ``--jq`` had already discarded. 

449 """ 

450 rows = _json_rows( 

451 [ 

452 "gh", 

453 "pr", 

454 "list", 

455 "--base", 

456 base, 

457 "--state", 

458 "merged", 

459 "--limit", 

460 str(limit), 

461 "--json", 

462 "number,mergedAt", 

463 ], 

464 cwd=cwd, 

465 _run=_run, 

466 _sleep=_sleep, 

467 ) 

468 if rows is None: 

469 return None 

470 merged_at = [str(row.get("mergedAt") or "") for row in rows] 

471 if len(rows) >= limit and merged_at and min(merged_at) >= since: 

472 # Full page whose oldest entry is still inside/after the window: the read 

473 # succeeded and saw only part of the answer, which must not read as clean. 

474 return None 

475 return [ 

476 int(row["number"]) 

477 for row in rows 

478 if isinstance(row.get("number"), int) and since < str(row.get("mergedAt") or "") < until 

479 ] 

480 

481 

482def _json_rows(argv: list[str], *, cwd: str | None, _run, _sleep=None) -> list[dict] | None: 

483 """Parse ``gh --json`` output into rows, or ``None`` when it could not be read.""" 

484 result = run_argv_retry(argv, cwd=cwd, _run=_run, _sleep=_sleep) 

485 if not result.ok: 

486 return None 

487 try: 

488 data = json.loads(result.stdout or "[]") 

489 except ValueError: 

490 return None 

491 return data if isinstance(data, list) else None 

492 

493 

494def _merge_window_fields(result: CommandResult) -> list[str]: 

495 """The four TSV fields of a ``pr_merge_window`` read, trailing blank preserved. 

496 

497 Trims newlines only. ``str.strip()`` also removes the trailing tab, so a merged 

498 PR whose ``mergeCommit.oid`` has not appeared yet arrives as three fields and 

499 reads as malformed rather than as "not settled yet" — which is precisely the 

500 state the poll above exists to recognise (#938). 

501 """ 

502 return result.stdout.strip("\r\n").split("\t") 

503 

504 

505#: Reads of a just-merged PR before GitHub has populated ``mergeCommit.oid``. 

506#: Three attempts a second apart: the field settles in well under a second in 

507#: practice, and the cap matters more than the ceiling — this runs immediately 

508#: after an irreversible merge, so it must give up rather than hang (#938). 

509MERGE_COMMIT_POLL_ATTEMPTS = 3 

510MERGE_COMMIT_POLL_DELAY_S = 1.0 

511 

512 

513def pr_merge_window( 

514 pr: int | str, *, cwd: str | None = None, _run=None, _sleep=None 

515) -> dict | None: 

516 """When a PR branched and merged, its base, and the SHA it merged as (#561). 

517 

518 ``createdAt`` stands in for the branch point. It is the conservative choice: a 

519 branch is cut at or before its PR is opened, so the window can only be too wide, 

520 never too narrow — a wider window over-reports rather than missing a revert. 

521 

522 ``None`` when ``gh`` cannot be asked or the PR is not merged. 

523 

524 A merged PR whose ``mergeCommit.oid`` has not appeared yet is **polled** for, 

525 briefly, rather than read as absent. ``ship.md`` tells the operator to run the 

526 drift check "immediately after a successful merge" — the one moment the field 

527 is least likely to be populated — and since #936 an unreadable input exits 2. 

528 Without the poll the runbook's own timing is the most frequent trigger of the 

529 loud path, and the shipped remedy is a sentence of prose asking an agent to 

530 retry (#938). Bounded, and giving up still yields ``None``: the poll must not 

531 become a way to eventually pass. 

532 """ 

533 # Named rather than written as two adjacent literals inside the argv list: an 

534 # implicit concatenation there reads as a possible missing comma (CodeQL flags it), 

535 # and an argv list is exactly where that ambiguity is expensive. 

536 jq = '[.createdAt, .mergedAt, .baseRefName, (.mergeCommit.oid // "")] | @tsv' 

537 argv = [ 

538 "gh", 

539 "pr", 

540 "view", 

541 str(pr), 

542 "--json", 

543 "createdAt,mergedAt,baseRefName,mergeCommit", 

544 "--jq", 

545 jq, 

546 ] 

547 sleep_fn = _sleep or time.sleep 

548 for attempt in range(1, MERGE_COMMIT_POLL_ATTEMPTS + 1): 

549 result = run_argv_retry(argv, cwd=cwd, _run=_run, _sleep=_sleep) 

550 # Only newlines are trimmed. `.strip()` also eats the trailing tab, which is 

551 # the very field being waited on — an empty SHA would arrive as three fields 

552 # and read as malformed rather than as "not settled yet". 

553 parts = _merge_window_fields(result) if result.ok else [] 

554 # Poll only the settling case: merged (first three fields present) with the 

555 # SHA still empty. An unmerged PR or an unreadable `gh` is a real answer, and 

556 # waiting on either would just make every such call three seconds slower. 

557 settling = len(parts) == 4 and all(parts[:3]) and not parts[3] 

558 if not settling: 

559 break 

560 if attempt < MERGE_COMMIT_POLL_ATTEMPTS: 

561 sleep_fn(MERGE_COMMIT_POLL_DELAY_S) 

562 if not result.ok: 

563 return None 

564 parts = _merge_window_fields(result) 

565 if len(parts) != 4 or not all(parts[:3]) or not parts[3]: 

566 return None 

567 return { 

568 "branched_at": parts[0], 

569 "merged_at": parts[1], 

570 "base": parts[2], 

571 "merge_commit": parts[3], 

572 } 

573 

574 

575def pr_merge_snapshot(pr: int | str, *, cwd: str | None = None, _run=None) -> CommandResult: 

576 return run_argv( 

577 [ 

578 "gh", 

579 "pr", 

580 "view", 

581 str(pr), 

582 "--json", 

583 "headRefOid,headRefName,mergeStateStatus,statusCheckRollup", 

584 ], 

585 cwd=cwd, 

586 **_kw(_run), 

587 ) 

588 

589 

590def merge_pr( 

591 pr: int | str, 

592 *, 

593 method: str = "squash", 

594 head_sha: str | None = None, 

595 cwd: str | None = None, 

596 _run=None, 

597) -> CommandResult: 

598 """Merge the pull request over GraphQL, pinned to ``head_sha`` when one is known. 

599 

600 ``--match-head-commit`` is this transport's spelling of the pin :func:`rest_merge_pr` 

601 sends as ``sha``: GitHub refuses the merge if the head is not that commit. Without it 

602 the head could move between the checks `keel merge` ran and this call, and the merge 

603 would land whatever it moved to. 

604 """ 

605 argv = ["gh", "pr", "merge", str(pr), f"--{method}"] 

606 if head_sha: 

607 argv += ["--match-head-commit", head_sha] 

608 return run_argv(argv, cwd=cwd, **_kw(_run)) 

609 

610 

611def _run_id_of(link: object) -> str | None: 

612 """The GitHub Actions run id in a check's details link, or ``None``.""" 

613 match = re.search(r"/actions/runs/(\d+)", link) if isinstance(link, str) else None 

614 return match.group(1) if match else None 

615 

616 

617def failed_check_runs( 

618 pr: int | str, names: Sequence[str], *, cwd: str | None = None, _run=None 

619) -> tuple[dict[str, str], str | None]: 

620 """``({name: run id}, error)`` for the failed checks called exactly ``names``. 

621 

622 The checks are found through ``gh pr checks``, whose details link names the Actions run. 

623 ``gh pr checks`` exits non-zero when a check is pending or failing but still prints the 

624 rows, so stdout is read whatever the exit code; empty stdout *with* a failing exit is an 

625 error (authentication, network), not an empty listing. A cancelled or timed-out job 

626 (``cancel``) counts as failed. A check with no Actions run (a third-party status) cannot 

627 be rerun here. Several names can share one run, which is why the caller reruns by run id. 

628 """ 

629 listed = run_argv( 

630 ["gh", "pr", "checks", str(pr), "--json", "name,link,bucket"], cwd=cwd, **_kw(_run) 

631 ) 

632 try: 

633 rows = json.loads(listed.stdout) if listed.stdout.strip() else ([] if listed.ok else None) 

634 except ValueError: 

635 rows = None 

636 if not isinstance(rows, list): 

637 return {}, f"could not list the checks of PR #{pr}: {listed.output.strip()}" 

638 runs: dict[str, str] = {} 

639 for name in names: 

640 for row in rows: 

641 if ( 

642 isinstance(row, dict) 

643 and row.get("name") == name 

644 and row.get("bucket") in ("fail", "cancel") 

645 and _run_id_of(row.get("link")) 

646 ): 

647 runs[name] = str(_run_id_of(row.get("link"))) 

648 break 

649 else: 

650 return {}, f"no failed GitHub Actions run found for check {name!r}" 

651 return runs, None 

652 

653 

654def rerun_run(run_id: str, *, cwd: str | None = None, _run=None) -> tuple[bool, str]: 

655 """Rerun the failed jobs of one Actions run: ``(ok, detail)``.""" 

656 result = run_argv(["gh", "run", "rerun", run_id, "--failed"], cwd=cwd, **_kw(_run)) 

657 if not result.ok: 

658 return False, f"gh run rerun {run_id} failed: {result.output.strip()}" 

659 return True, f"reran the failed jobs of run {run_id}" 

660 

661 

662def comment(pr: int | str, body: str, *, cwd: str | None = None, _run=None) -> CommandResult: 

663 return run_argv(["gh", "pr", "comment", str(pr), "--body", body], cwd=cwd, **_kw(_run)) 

664 

665 

666def post_issue_comment( 

667 owner_repo: str, 

668 issue_or_pr: int | str, 

669 body: str, 

670 *, 

671 cwd: str | None = None, 

672 _run=None, 

673) -> CommandResult: 

674 return run_argv( 

675 [ 

676 "gh", 

677 "api", 

678 f"repos/{owner_repo}/issues/{issue_or_pr}/comments", 

679 "-X", 

680 "POST", 

681 "-F", 

682 f"body={body}", 

683 ], 

684 cwd=cwd, 

685 **_kw(_run), 

686 ) 

687 

688 

689def create_issue( 

690 owner_repo: str, 

691 title: str, 

692 body: str, 

693 *, 

694 cwd: str | None = None, 

695 _run=None, 

696) -> CommandResult: 

697 """Open one issue over REST; the response JSON names its ``number`` and ``html_url``. 

698 

699 ``-f``, never ``-F``, for the same reason as :func:`issue_labels_add_argv`: ``-F`` 

700 reads a value starting with ``@`` as a file path, and a title or body is text. 

701 Mutating — callers gate it on operator consent. 

702 """ 

703 return run_argv( 

704 [ 

705 "gh", 

706 "api", 

707 f"repos/{owner_repo}/issues", 

708 "-X", 

709 "POST", 

710 "-f", 

711 f"title={title}", 

712 "-f", 

713 f"body={body}", 

714 ], 

715 cwd=cwd, 

716 **_kw(_run), 

717 ) 

718 

719 

720def edit_issue_comment( 

721 owner_repo: str, 

722 comment_id: int | str, 

723 body: str, 

724 *, 

725 cwd: str | None = None, 

726 _run=None, 

727) -> CommandResult: 

728 return run_argv( 

729 [ 

730 "gh", 

731 "api", 

732 f"repos/{owner_repo}/issues/comments/{comment_id}", 

733 "-X", 

734 "PATCH", 

735 "-F", 

736 f"body={body}", 

737 ], 

738 cwd=cwd, 

739 **_kw(_run), 

740 ) 

741 

742 

743def close_issue( 

744 issue: int | str, 

745 *, 

746 cwd: str | None = None, 

747 repo: str | None = None, 

748 reason: str | None = None, 

749 _run=None, 

750) -> CommandResult: 

751 """``gh issue close``; ``repo`` names the repository, ``reason`` the state reason. 

752 

753 ``swarm-land`` closes a landed cluster's issues as ``completed`` in the configured 

754 ``owner/repo`` (#1422) rather than whatever repository the checkout's remote names. 

755 """ 

756 argv = ["gh", "issue", "close", str(issue)] 

757 if repo: 

758 argv += ["--repo", repo] 

759 if reason: 

760 argv += ["--reason", reason] 

761 return run_argv(argv, cwd=cwd, **_kw(_run)) 

762 

763 

764def issue_facts( 

765 issue: int | str, 

766 *, 

767 cwd: str | None = None, 

768 fields: str = "title,labels", 

769 _run=None, 

770) -> CommandResult: 

771 """Fetch an issue's ``title`` and ``labels`` as JSON for ``keel guard``. 

772 

773 Thin I/O for blocker evaluation: the issue facts are read from the host 

774 rather than trusting agent-supplied args. Fail-soft — the caller inspects 

775 ``result.ok`` and falls back to offline args when offline. 

776 

777 ``fields`` widens the same call for the capture sink, which needs the body 

778 too. It stays a parameter rather than a second function so both readers make 

779 the identical request and a change to one is a change to both. 

780 """ 

781 return run_argv( 

782 ["gh", "issue", "view", str(issue), "--json", fields], 

783 cwd=cwd, 

784 **_kw(_run), 

785 ) 

786 

787 

788#: Labels read in one page. GitHub's default is 30; a policy pack plus keel's 

789#: attribution vocabulary exceeds that on any real repository, and a truncated 

790#: listing would report labels as missing that exist. 

791LABEL_PAGE_LIMIT = 500 

792 

793 

794def label_list_argv(repo: str | None = None) -> list[str]: 

795 """The exact ``gh label list`` command ``keel doctor`` runs (pure, for tests).""" 

796 argv = ["gh", "label", "list", "--limit", str(LABEL_PAGE_LIMIT), "--json", "name"] 

797 return argv + ["--repo", repo] if repo else argv 

798 

799 

800def list_labels(*, repo: str | None = None, cwd: str | None = None, _run=None) -> CommandResult: 

801 """List a repository's labels as JSON. Fail-soft: the caller reads ``result.ok``.""" 

802 return run_argv(label_list_argv(repo), cwd=cwd, **_kw(_run)) 

803 

804 

805#: Seconds ``keel doctor`` waits for ``gh auth status`` — one round trip to GitHub. 

806AUTH_STATUS_TIMEOUT_S = 10 

807 

808 

809def auth_status(*, cwd: str | None = None, _run=None) -> CommandResult: 

810 """``gh auth status``: is ``gh`` logged in? Fail-soft; the caller reads ``result.ok``. 

811 

812 Read-only (no ``--show-token``), so its output names the account, never the token. 

813 """ 

814 return run_argv(["gh", "auth", "status"], cwd=cwd, timeout=AUTH_STATUS_TIMEOUT_S, **_kw(_run)) 

815 

816 

817def label_create_argv(name: str, repo: str | None = None) -> list[str]: 

818 """The exact ``gh label create`` command for one label. 

819 

820 Built here, in the one module that owns keel's ``gh`` command shapes, so the command 

821 ``keel doctor`` *prints* for an operator to paste and the command ``--fix`` *runs* 

822 are the same string and cannot drift apart. 

823 """ 

824 argv = ["gh", "label", "create", name] 

825 return argv + ["--repo", repo] if repo else argv 

826 

827 

828def create_label( 

829 name: str, *, repo: str | None = None, cwd: str | None = None, _run=None 

830) -> CommandResult: 

831 """Create one repository label. Mutating — callers gate it on operator consent.""" 

832 return run_argv(label_create_argv(name, repo), cwd=cwd, **_kw(_run)) 

833 

834 

835def issue_labels_add_argv(owner_repo: str, number: int, labels: Sequence[str]) -> list[str]: 

836 """The exact REST call that adds ``labels`` to issue or pull request ``number``. 

837 

838 ``-f``, never ``-F``: ``-F`` reads a value starting with ``@`` as a file path, and a 

839 label is a name, not a file. Over REST, like :func:`post_issue_comment`, so a host that 

840 blocks GraphQL can still label the pull request it opened. 

841 """ 

842 argv = ["gh", "api", f"repos/{owner_repo}/issues/{number}/labels", "-X", "POST"] 

843 for label in labels: 

844 argv += ["-f", f"labels[]={label}"] 

845 return argv 

846 

847 

848def add_issue_labels( 

849 owner_repo: str, 

850 number: int, 

851 labels: Sequence[str], 

852 *, 

853 cwd: str | None = None, 

854 _run=None, 

855) -> CommandResult: 

856 """Add ``labels`` to issue or pull request ``number``. Mutating, and fail-soft.""" 

857 return run_argv(issue_labels_add_argv(owner_repo, number, labels), cwd=cwd, **_kw(_run)) 

858 

859 

860def _kw(_run): 

861 return {"_run": _run} if _run is not None else {} 

862 

863 

864# --- REST transport (#1175) ------------------------------------------------- 

865# 

866# `gh pr view --json` and `gh pr merge` both go over GitHub's **GraphQL** endpoint. 

867# On a host whose egress proxy allows the REST API and blocks GraphQL — the remote 

868# environment #1169/#1170/#1171 were shipped from — every one of them fails before 

869# `keel merge` reaches its claim, its window re-check, its CI rollup or its evidence 

870# verification, and the operator is pushed off the only sanctioned merge path onto a 

871# hand-driven squash. These are the same reads and the same write, asked over REST. 

872# 

873# `gh api` expands `{owner}` and `{repo}` from the checkout's own remote, so none of 

874# this needs the project config — which matters for `keel verify-merge`, whose whole 

875# contract is that it reads GitHub and nothing else. 

876 

877#: A query that costs nothing and proves only that the endpoint answers at all. 

878_GRAPHQL_PROBE = ["gh", "api", "graphql", "-f", "query=query{__typename}"] 

879 

880 

881def graphql_available(*, cwd: str | None = None, _run=None) -> bool: 

882 """Can this host reach GitHub's GraphQL endpoint? 

883 

884 Probed once per run and reused, because the answer is a property of the *host* 

885 (its proxy) rather than of any pull request. A blocked endpoint fails the probe 

886 the same way it fails a real query — a non-zero exit, usually carrying a proxy's 

887 403 or 405 — so the probe needs no special-casing of the reason. 

888 

889 Deliberately **not** a fallback after a failed call. Reads could retry safely; 

890 `gh pr merge` cannot. A merge that failed for an unknown reason may or may not 

891 have landed, and re-driving it over a second transport is how a pull request gets 

892 merged twice. The transport is chosen before anything is attempted. 

893 """ 

894 return run_argv(_GRAPHQL_PROBE, cwd=cwd, **_kw(_run)).ok 

895 

896 

897def rest_pull(pr: int | str, *, cwd: str | None = None, _run=None) -> CommandResult: 

898 """The pull request as REST returns it (``head.sha``, ``mergeable_state``, …).""" 

899 return run_argv(["gh", "api", f"repos/{{owner}}/{{repo}}/pulls/{pr}"], cwd=cwd, **_kw(_run)) 

900 

901 

902def rest_check_runs(sha: str, *, cwd: str | None = None, _run=None) -> CommandResult: 

903 """Check runs for one commit — the Actions half of a status-check rollup.""" 

904 return run_argv( 

905 [ 

906 "gh", 

907 "api", 

908 "--paginate", 

909 f"repos/{{owner}}/{{repo}}/commits/{sha}/check-runs?per_page=100", 

910 ], 

911 cwd=cwd, 

912 **_kw(_run), 

913 ) 

914 

915 

916def rest_commit_statuses(sha: str, *, cwd: str | None = None, _run=None) -> CommandResult: 

917 """Commit statuses for one commit — the other half, for non-Actions CI.""" 

918 return run_argv( 

919 [ 

920 "gh", 

921 "api", 

922 "--paginate", 

923 f"repos/{{owner}}/{{repo}}/commits/{sha}/statuses?per_page=100", 

924 ], 

925 cwd=cwd, 

926 **_kw(_run), 

927 ) 

928 

929 

930def rest_json(result: CommandResult) -> object | None: 

931 """Parse a `gh api` body, tolerating `--paginate`'s concatenated pages.""" 

932 if not result.ok: 

933 return None 

934 text = (result.stdout or "").strip() 

935 if not text: 

936 return None 

937 try: 

938 return json.loads(text) 

939 except json.JSONDecodeError: 

940 pass 

941 # `gh api --paginate` concatenates one JSON document per page rather than merging 

942 # them, so a two-page read is `[…][…]` and is not a document at all. Decoding them 

943 # one at a time is what the flag actually returns, and a reader that only tried 

944 # `json.loads` saw the second page as a syntax error and reported "no checks". 

945 decoder, index, pages = json.JSONDecoder(), 0, [] 

946 while index < len(text): 

947 try: 

948 page, index = decoder.raw_decode(text, index) 

949 except json.JSONDecodeError: 

950 return None 

951 pages.append(page) 

952 while index < len(text) and text[index] in " \t\r\n": 

953 index += 1 

954 # `pages` cannot be empty here: `text` is non-empty and stripped, so the loop ran at 

955 # least once and either appended a page or returned. A guard for it would be a branch 

956 # no input can take, which is a claim about the code that the tests cannot check. 

957 if all(isinstance(page, list) for page in pages): 

958 return [item for page in pages for item in page] 

959 return pages[0] if len(pages) == 1 else pages 

960 

961 

962def _check_run_rows(payload: object) -> list[dict]: 

963 """The check runs inside a `commits/<sha>/check-runs` body, across every page. 

964 

965 That endpoint answers with an **object** — ``{"total_count": N, "check_runs": [...]}`` 

966 — not with a bare array, and `gh api --paginate` concatenates one such object per 

967 page. So a head with more than a hundred checks arrives as ``{…}{…}``, which 

968 :func:`rest_json` correctly reports as *a list of two page objects*. 

969 

970 Read as a list of check runs, those two objects became two entries with no ``name``, 

971 no ``status`` and no ``conclusion`` — neither a failure nor pending, so the reducer 

972 counted them as checks that had reported and returned **pass**. A merge gate handed 

973 an all-green rollup for a head whose hundred-odd real checks were never looked at. 

974 

975 Only the documented shape contributes. A payload that is neither the object nor 

976 pages of it yields nothing, and the caller treats an empty rollup as *no checks have 

977 reported*, which refuses a non-docs merge rather than passing it. 

978 """ 

979 pages = payload if isinstance(payload, list) else [payload] 

980 rows: list[dict] = [] 

981 for page in pages: 

982 if not isinstance(page, dict): 

983 continue 

984 runs = page.get("check_runs") 

985 if isinstance(runs, list): 

986 rows.extend(run for run in runs if isinstance(run, dict)) 

987 return rows 

988 

989 

990def rest_rollup(check_runs: object, statuses: object) -> list[dict]: 

991 """The two REST payloads in the shape ``statusCheckRollup`` has. 

992 

993 Pure, and a translation rather than a judgement: the rollup reducer reads 

994 ``name``/``context``, ``status``, ``conclusion`` and the two timestamps, and 

995 GraphQL spells those in SCREAMING_CASE where REST spells them in lower. Keeping 

996 the translation here means the reducer, the dedupe and the recency ordering are 

997 one implementation asked the same question over either transport, instead of two 

998 that agree until they do not. 

999 

1000 Commit statuses are carried through with their ``context`` and ``state``, which is 

1001 what the GraphQL rollup returns for a ``StatusContext`` and what the reducer reads 

1002 from one (#1202). They are included rather than dropped for two reasons: a failing 

1003 status has to be able to *fail* a merge, and even a passing one makes the rollup 

1004 non-empty, which is the difference between ``pass`` and ``no-checks``. 

1005 """ 

1006 entries: list[dict] = [] 

1007 # `_check_run_rows` has already dropped every non-object, so nothing is re-checked 

1008 # here: a guard no input can trip is a claim about the data the tests cannot make. 

1009 for run in _check_run_rows(check_runs): 

1010 entries.append( 

1011 { 

1012 "name": run.get("name"), 

1013 "status": _upper(run.get("status")), 

1014 "conclusion": _upper(run.get("conclusion")), 

1015 "startedAt": run.get("started_at"), 

1016 "completedAt": run.get("completed_at"), 

1017 } 

1018 ) 

1019 for row in _status_rows(statuses): 

1020 # **Carried through, not translated.** A commit status keeps its verdict in 

1021 # `state`, exactly as the GraphQL rollup returns one, because the reducer reads 

1022 # that field now (#1202). #1175 translated it here instead, which worked and left 

1023 # the two wires speaking different shapes — and the GraphQL one, which is the 

1024 # default nearly every run takes, still counted a *failing* status as a check 

1025 # that had reported. The timestamps come along because dedupe orders by them. 

1026 entries.append( 

1027 { 

1028 "context": row.get("context"), 

1029 "state": _upper(row.get("state")), 

1030 "completedAt": row.get("updated_at"), 

1031 "startedAt": row.get("created_at"), 

1032 } 

1033 ) 

1034 return entries 

1035 

1036 

1037def _status_rows(payload: object) -> list[dict]: 

1038 """The rows of a `commits/<sha>/statuses` body, across every page. 

1039 

1040 That endpoint *does* answer with an array, so `--paginate` yields a list of pages — 

1041 which :func:`rest_json` flattens — or a single page's list. Both arrive here as a 

1042 list of row objects; anything else contributes nothing. 

1043 """ 

1044 rows = payload if isinstance(payload, list) else [] 

1045 return [row for row in rows if isinstance(row, dict)] 

1046 

1047 

1048def _upper(value: object) -> str | None: 

1049 """``value`` upper-cased when it is a string; ``None`` otherwise. 

1050 

1051 REST says ``in_progress`` and ``success`` where GraphQL says ``IN_PROGRESS`` and 

1052 ``SUCCESS``; the two differ in case alone, so upper-casing *is* the translation. 

1053 """ 

1054 return value.upper() if isinstance(value, str) else None 

1055 

1056 

1057def rest_merge_pr( 

1058 pr: int | str, 

1059 *, 

1060 method: str = "squash", 

1061 head_sha: str | None = None, 

1062 cwd: str | None = None, 

1063 _run=None, 

1064) -> CommandResult: 

1065 """Merge the pull request over REST, pinned to ``head_sha`` when one is known. 

1066 

1067 ``sha`` is REST's own head-pin: the merge is refused if the pull request has moved 

1068 since it was read. `gh pr merge` applies none by default; :func:`merge_pr` passes 

1069 ``--match-head-commit`` for the same pin, so the two transports are equally strict — 

1070 deliberately, because a merge is the one operation here that cannot be taken back. 

1071 """ 

1072 argv = [ 

1073 "gh", 

1074 "api", 

1075 "-X", 

1076 "PUT", 

1077 f"repos/{{owner}}/{{repo}}/pulls/{pr}/merge", 

1078 "-f", 

1079 f"merge_method={method}", 

1080 ] 

1081 if head_sha: 

1082 argv += ["-f", f"sha={head_sha}"] 

1083 return run_argv(argv, cwd=cwd, **_kw(_run)) 

1084 

1085 

1086def rest_pr_files( 

1087 pr: int | str, *, cwd: str | None = None, _run=None, _sleep=None 

1088) -> list[str] | None: 

1089 """Paths the pull request changed, over REST. ``None`` when unreadable.""" 

1090 return _lines( 

1091 [ 

1092 "gh", 

1093 "api", 

1094 "--paginate", 

1095 f"repos/{{owner}}/{{repo}}/pulls/{pr}/files?per_page=100", 

1096 "--jq", 

1097 ".[].filename", 

1098 ], 

1099 cwd=cwd, 

1100 _run=_run, 

1101 _sleep=_sleep, 

1102 ) 

1103 

1104 

1105def _rest_commit_on_branch(sha: str, base: str, *, cwd: str | None, _run) -> bool: 

1106 """Is ``sha`` an ancestor of ``base`` — that is, did this commit actually land? 

1107 

1108 ``compare/<base>...<sha>`` answers ``identical`` when they are the same commit and 

1109 ``behind`` when ``sha`` is reachable from ``base``; ``ahead`` and ``diverged`` are 

1110 the speculative test merge, which exists as an object and is on no branch. 

1111 """ 

1112 if not sha or not base: 

1113 return False 

1114 result = run_argv( 

1115 [ 

1116 "gh", 

1117 "api", 

1118 f"repos/{{owner}}/{{repo}}/compare/{base}...{sha}", 

1119 "--jq", 

1120 ".status", 

1121 ], 

1122 cwd=cwd, 

1123 **_kw(_run), 

1124 ) 

1125 return result.ok and result.stdout.strip() in ("identical", "behind") 

1126 

1127 

1128def rest_pr_merge_window( 

1129 pr: int | str, *, cwd: str | None = None, _run=None, _sleep=None 

1130) -> dict | None: 

1131 """``branched_at`` / ``merged_at`` / ``base`` / ``merge_commit`` over REST. 

1132 

1133 The same four fields :func:`pr_merge_window` returns, and the same settling poll: 

1134 a pull request reports ``merged_at`` before ``merge_commit_sha`` is populated, and 

1135 reading it in that instant is how the drift check comes back "no merge commit yet" 

1136 for a merge that had just happened. 

1137 """ 

1138 sleep_fn = _sleep or time.sleep 

1139 for attempt in range(1, MERGE_COMMIT_POLL_ATTEMPTS + 1): 

1140 payload = rest_json( 

1141 run_argv_retry( 

1142 ["gh", "api", f"repos/{{owner}}/{{repo}}/pulls/{pr}"], 

1143 cwd=cwd, 

1144 _run=_run, 

1145 _sleep=_sleep, 

1146 ) 

1147 ) 

1148 if not isinstance(payload, dict): 

1149 return None 

1150 window = { 

1151 "branched_at": str(payload.get("created_at") or ""), 

1152 "merged_at": str(payload.get("merged_at") or ""), 

1153 "base": str((payload.get("base") or {}).get("ref") or ""), 

1154 "merge_commit": str(payload.get("merge_commit_sha") or ""), 

1155 } 

1156 # **Reachability, not presence.** REST's `merge_commit_sha` is not empty while a 

1157 # pull request is open: GitHub documents it as the *speculative test-merge* SHA 

1158 # (`refs/pull/<n>/merge`) until the merge lands, when it becomes the commit that 

1159 # actually landed. So "merged and the field is filled" is true on the first 

1160 # post-merge read even while the cached test SHA is still being served — and the 

1161 # drift check would then judge the test merge instead of the squash. GraphQL's 

1162 # `mergeCommit.oid` is null until the real commit exists, which is why the same 

1163 # poll is correct there and not here. 

1164 settling = window["merged_at"] and not _rest_commit_on_branch( 

1165 window["merge_commit"], window["base"], cwd=cwd, _run=_run 

1166 ) 

1167 if settling: 

1168 if attempt < MERGE_COMMIT_POLL_ATTEMPTS: 

1169 sleep_fn(MERGE_COMMIT_POLL_DELAY_S) 

1170 continue 

1171 # Still unsettled when the budget runs out: the SHA on offer is one this 

1172 # check could not find on the base branch, so it is not an answer. Returning 

1173 # it anyway is how the drift read would judge the speculative test merge. 

1174 return None 

1175 # **All four, exactly as the GraphQL reader requires.** REST answers an 

1176 # *unmerged* pull request with `created_at` and `base.ref` and a null 

1177 # `merged_at`, so "any field present" reported a window for one — and a caller 

1178 # that supplied `--merge-sha` then went on to judge drift on a merge that had 

1179 # not happened, where the same call over GraphQL says `unknown`. 

1180 return window if all(window.values()) else None 

1181 return None # pragma: no cover - the loop always returns on its last attempt 

1182 

1183 

1184def rest_prs_merged_between( 

1185 base: str, 

1186 since: str, 

1187 until: str, 

1188 *, 

1189 cwd: str | None = None, 

1190 _run=None, 

1191 _sleep=None, 

1192 limit: int = MERGED_PAGE_LIMIT, 

1193) -> list[int] | None: 

1194 """:func:`prs_merged_between` over REST, with the same truncation honesty. 

1195 

1196 REST cannot sort by merge time — ``sort`` takes ``created``, ``updated``, 

1197 ``popularity`` and ``long-running``, and nothing else — so the page is ordered by 

1198 ``updated`` descending and the truncation rule is re-derived on that key rather 

1199 than transplanted. It still holds, and for a reason worth writing down: merging a 

1200 pull request *updates* it, so ``merged_at <= updated_at`` for every row. If the 

1201 oldest row this page reached was updated before ``since``, every row it did not 

1202 reach was updated earlier still, so it was merged earlier still, so it is outside 

1203 the window and the window was seen whole. If it was not, the page may have stopped 

1204 short of the answer — and a partial read must not render as "nothing overtook this 

1205 merge" (#933, #937). 

1206 

1207 ``state=closed`` is the narrowest REST offers; a closed-unmerged row has no 

1208 ``merged_at``, is filtered out, and costs only a slot in the page. 

1209 """ 

1210 rows = rest_json( 

1211 run_argv_retry( 

1212 [ 

1213 "gh", 

1214 "api", 

1215 f"repos/{{owner}}/{{repo}}/pulls" 

1216 f"?base={base}&state=closed&sort=updated&direction=desc&per_page={limit}", 

1217 ], 

1218 cwd=cwd, 

1219 _run=_run, 

1220 _sleep=_sleep, 

1221 ) 

1222 ) 

1223 if not isinstance(rows, list): 

1224 return None 

1225 updated = [str(row.get("updated_at") or "") for row in rows if isinstance(row, dict)] 

1226 if len(rows) >= limit and updated and min(updated) >= since: 

1227 return None 

1228 return [ 

1229 int(row["number"]) 

1230 for row in rows 

1231 if isinstance(row, dict) 

1232 and isinstance(row.get("number"), int) 

1233 and since < str(row.get("merged_at") or "") < until 

1234 ]