Add do-epic's gate read and parked-chunk state files

This commit is contained in:
2026-11-18 23:10:12 +01:00
parent 7058e8c13b
commit 004c76679e
4 changed files with 314 additions and 0 deletions
+98
View File
@@ -0,0 +1,98 @@
"""What the pull request of a do-epic chunk waits on, read once from its forge (docs/decisions.md → `do-epic: drives one Jira epic …`, "Long gates").
A gate is something only time or a person passes: checks that still run, or an approval a reviewer has yet to give. While a chunk's pull request waits on one, its worker has nothing to do, so do-epic parks the chunk (`parked`). Anything else is news the worker acts on."""
import dataclasses
import json
import typing
from chunk_pr.approval import waiting_threads
from failure import Failure
from forge.commands import forge_of, Run
from forge.pulls import CheckFailed, checks_now, open_pull, Pending, required_checks
# What a pull request waits on, as the words after "awaits".
CHECKS = "its checks"
APPROVAL = "an approval"
@dataclasses.dataclass(frozen=True)
class Gate:
"""The gate a chunk's open pull request waits on."""
# The chunk's worktree, where the pull request's branch is checked out.
worktree: str
# The pull request's number.
pull: str
# CHECKS or APPROVAL.
on: str
@dataclasses.dataclass(frozen=True)
class Open:
"""A chunk that waits on no gate, so its worker goes on."""
# Why, as a sentence without its full stop, for the worker of a chunk that was parked.
news: str
def gate(branch: str, checkout: str, at: typing.Callable[[str], Run]) -> Gate | Open | Failure:
"""What the chunk on branch waits on, in a worktree of checkout; at gives the runner of commands in a folder. A Failure where git or the forge cannot be read, which says nothing about the gate.
A draft never waits on a gate: its worker still works on it. On Gitea only the checks are a gate, since chunk-pr reads approvals on GitHub only (`chunk_pr.approval.awaited`).
"""
worktree = worktree_of(branch, at(checkout))
if not isinstance(worktree, str):
return worktree or Open(f"no worktree of {checkout} has the branch {branch} checked out")
run = at(worktree)
read = [run(["git", *args]) for args in (["remote", "get-url", "origin"], ["rev-parse", "HEAD"], ["symbolic-ref", "--short", "refs/remotes/origin/HEAD"])]
failed = next((answer for answer in read if isinstance(answer, Failure)), None)
if failed is not None:
return failed
origin, head, base = (str(answer).strip() for answer in read)
forge = forge_of(origin)
pull = open_pull(forge, branch, head, run)
if not isinstance(pull, str):
return pull or Open(f"no pull request from origin's {branch} is open at {head[:12]}")
decision = review_decision(pull, run) if forge == "gh" else ""
if not isinstance(decision, str):
return decision or Open(f"pull request #{pull} is a draft")
required = required_checks(forge, base.removeprefix("origin/"), run)
checks = required if isinstance(required, Failure) else checks_now(forge, pull, head, required, run)
if isinstance(checks, CheckFailed):
return Open(f"{checks.reason}; fix it and push")
if isinstance(checks, Failure):
return checks
if isinstance(checks, Pending):
return Gate(worktree, pull, CHECKS)
if decision == "CHANGES_REQUESTED":
return Open(f"a reviewer requested changes on pull request #{pull}")
waiting = waiting_threads(pull, run) if forge == "gh" else []
if isinstance(waiting, Failure):
return waiting
if waiting:
return Open(f"a reviewer's comment on pull request #{pull} waits for an answer, in {', '.join(waiting)}")
if decision == "REVIEW_REQUIRED":
return Gate(worktree, pull, APPROVAL)
return Open(f"pull request #{pull} passed its checks" + (" and is approved" if decision == "APPROVED" else ""))
def worktree_of(branch: str, run: Run) -> str | None | Failure:
"""The worktree, of the checkout run works in, that has branch checked out; None where none has."""
listed = run(["git", "worktree", "list", "--porcelain"])
if isinstance(listed, Failure):
return listed
for block in listed.split("\n\n"):
lines = block.splitlines()
if f"branch refs/heads/{branch}" in lines and lines[0].startswith("worktree "):
return lines[0].removeprefix("worktree ")
return None
def review_decision(pull: str, run: Run) -> str | None | Failure:
"""GitHub's review decision on the pull request, read once: `APPROVED`, `REVIEW_REQUIRED`, `CHANGES_REQUESTED`, or empty where its branch protection asks for no review. None where it is a draft."""
viewed = run(["gh", "pr", "view", pull, "--json", "isDraft,reviewDecision"])
if isinstance(viewed, Failure):
return viewed
try:
parsed = json.loads(viewed)
return None if parsed["isDraft"] else str(parsed["reviewDecision"] or "")
except (ValueError, KeyError, TypeError):
return Failure(f"gh pr view printed no review decision: {viewed.strip()[:200]}")
+72
View File
@@ -0,0 +1,72 @@
"""The parked chunks of an epic: each keeps its worktree, pull request and session while that pull request waits on a long gate, in a file that survives a reboot (docs/decisions.md → `do-epic: drives one Jira epic …`, "Long gates").
A chunk is parked from the moment its file is written until the file is removed, whatever its window does: `scheduler` starts a window again for a parked chunk that has none, and that window goes on polling."""
import dataclasses
import json
import os
import pathlib
from failure import Failure
# Under the epic's folder, the folder that holds one file per parked chunk, named for its issue.
FOLDER = "parked"
@dataclasses.dataclass(frozen=True)
class Parked:
"""A parked chunk."""
# The key of the issue it works.
issue: str
worktree: str
# Its pull request's number.
pull: str
# The ID of its worker's claude session, which `claude --resume` takes.
session: str
# What its pull request waits on, as the words after "awaits" (`gates.CHECKS`, `gates.APPROVAL`).
on: str
@property
def waits(self) -> str:
"""Why the chunk doesn't run, for the human."""
return f"it is parked: its pull request #{self.pull} awaits {self.on}"
def file_of(folder: pathlib.Path, issue: str) -> pathlib.Path:
return folder / FOLDER / f"{issue}.json"
def park(folder: pathlib.Path, chunk: Parked) -> Failure | None:
"""Records chunk as parked under the epic's folder, in place of what was recorded for its issue. The file is whole or absent, whenever the machine stops."""
file = file_of(folder, chunk.issue)
partial = file.with_suffix(".partial")
try:
file.parent.mkdir(parents=True, exist_ok=True)
partial.write_text(json.dumps(dataclasses.asdict(chunk), indent="\t") + "\n", encoding="utf-8")
os.replace(partial, file)
except OSError as failure:
return Failure(f"cannot record the parked chunk in {file}: {failure.strerror}")
return None
def unpark(folder: pathlib.Path, issue: str) -> Failure | None:
"""Records that the issue's chunk is parked no longer."""
try:
file_of(folder, issue).unlink(missing_ok=True)
except OSError as failure:
return Failure(f"cannot remove {file_of(folder, issue)}: {failure.strerror}")
return None
def parked_chunks(folder: pathlib.Path) -> dict[str, Parked] | Failure:
"""The epic's parked chunks, by issue. A Failure where a file cannot be read as one, since a chunk taken as not parked would start a second time."""
found: dict[str, Parked] = {}
for file in sorted((folder / FOLDER).glob("*.json")):
try:
fields = json.loads(file.read_text(encoding="utf-8"))
chunk = Parked(**fields)
except (OSError, ValueError, TypeError) as failure:
return Failure(f"cannot read the parked chunk in {file}: {failure}; fix or remove the file")
if chunk.issue != file.stem or not all(isinstance(value, str) for value in fields.values()):
return Failure(f"cannot read the parked chunk in {file}: its fields are not those of {file.stem}'s chunk; fix or remove the file")
found[chunk.issue] = chunk
return found
+89
View File
@@ -0,0 +1,89 @@
import json
import pathlib
import sys
import unittest
sys.path.insert(0, str(pathlib.Path(__file__).resolve().parents[1]))
from do_epic.gates import APPROVAL, CHECKS, gate, Gate, Open
from failure import Failure
WORKTREES = "worktree /code/billing\nHEAD aaa\nbranch refs/heads/main\n\nworktree /code/billing-ABC-21\nHEAD abc\nbranch refs/heads/ABC-21\n"
HEAD = "abc" * 4
def thread(resolved: bool, last: str, path: str = "a.py") -> dict:
return {"isResolved": resolved, "path": path, "comments": {"nodes": [{"author": {"login": last}}]}}
class Forge:
"""Stands in for git and the forge's CLI in the checkout and the chunk's worktree; `ran` holds each folder a command ran in."""
def __init__(self, origin: str = "git@github.com:o/billing.git", pulls: str = f"7\t{HEAD}\tfalse\n", draft: bool = False, decision: str = "REVIEW_REQUIRED", buckets: tuple[str, ...] = ("pass",), threads: tuple[dict, ...] = (), status: str = '{"state": "success", "total_count": 1}', worktrees: str = WORKTREES, fails: str = "") -> None:
self.ran: list[str] = []
self.fails = fails
self.answers = {
"git worktree": worktrees,
"git remote": origin + "\n",
"git rev-parse": HEAD + "\n",
"git symbolic-ref": "origin/main\n",
"gh pr list": pulls,
"gh pr view": json.dumps({"isDraft": draft, "reviewDecision": decision}),
"gh pr checks": json.dumps([{"bucket": bucket} for bucket in buckets]),
"gh api graphql": json.dumps({"data": {"repository": {"pullRequest": {"author": {"login": "worker"}, "reviewThreads": {"nodes": list(threads)}}}}}),
"tea api repos/{owner}/{repo}/pulls?state=open&limit=50": json.dumps([{"number": 7, "merged": False, "head": {"label": "ABC-21", "sha": HEAD, "repo": {"full_name": "o/billing"}}, "base": {"repo": {"full_name": "o/billing"}}}]),
"tea api repos/{owner}/{repo}/branches/main": '{"name": "main"}',
"tea api repos/{owner}/{repo}/commits/" + HEAD + "/status": status,
}
def at(self, folder: str):
def run(command: list[str]) -> str | Failure:
self.ran.append(folder)
key = " ".join(command) if command[0] == "tea" else " ".join(command[:3] if command[0] == "gh" else command[:2])
return Failure(f"{key} failed") if self.fails and key.startswith(self.fails) else self.answers[key]
return run
def gate(self) -> Gate | Open | Failure:
return gate("ABC-21", "/code/billing", self.at)
class GateOfAChunk(unittest.TestCase):
def test_a_pull_request_whose_checks_passed_awaits_the_approval_its_protection_requires(self):
forge = Forge()
self.assertEqual(forge.gate(), Gate("/code/billing-ABC-21", "7", APPROVAL))
self.assertEqual(set(forge.ran[1:]), {"/code/billing-ABC-21"})
def test_a_pull_request_awaits_its_checks_while_one_runs_whatever_its_reviews_say(self):
for decision in ("REVIEW_REQUIRED", "APPROVED", "CHANGES_REQUESTED", ""):
with self.subTest(decision=decision):
self.assertEqual(Forge(decision=decision, buckets=("pass", "pending")).gate(), Gate("/code/billing-ABC-21", "7", CHECKS))
def test_a_gitea_pull_request_awaits_only_its_checks(self):
gitea = "https://gitea.larvit.se/o/billing.git"
self.assertEqual(Forge(gitea, status='{"state": "pending", "total_count": 1}').gate(), Gate("/code/billing-ABC-21", "7", CHECKS))
self.assertEqual(Forge(gitea).gate(), Open("pull request #7 passed its checks"))
def test_the_worker_goes_on_where_nothing_but_the_worker_moves_the_pull_request(self):
cases = {
"pull request #7 passed its checks and is approved": Forge(decision="APPROVED"),
"pull request #7 passed its checks": Forge(decision=""),
"pull request #7 is a draft": Forge(draft=True, buckets=("pending",)),
"a check on pull request 7 failed; fix it and push": Forge(buckets=("fail",)),
"a reviewer requested changes on pull request #7": Forge(decision="CHANGES_REQUESTED"),
"a reviewer's comment on pull request #7 waits for an answer, in a.py, b.py": Forge(threads=(thread(False, "reviewer", "b.py"), thread(False, "reviewer"), thread(True, "reviewer", "c.py"), thread(False, "worker", "d.py"))),
"no pull request from origin's ABC-21 is open at abcabcabcabc": Forge(pulls=""),
"no worktree of /code/billing has the branch ABC-21 checked out": Forge(worktrees="worktree /code/billing\nHEAD aaa\nbranch refs/heads/main\n"),
}
for news, forge in cases.items():
with self.subTest(news=news):
self.assertEqual(forge.gate(), Open(news))
def test_a_read_that_fails_is_a_failure_and_says_nothing_of_the_gate(self):
for command in ("git worktree", "git remote", "gh pr list", "gh pr view", "gh pr checks", "gh api graphql"):
with self.subTest(command=command):
self.assertEqual(Forge(fails=command).gate(), Failure(f"{command} failed"))
self.assertEqual(Forge("https://gitea.larvit.se/o/billing.git", fails="tea api repos/{owner}/{repo}/branches").gate(), Failure("tea api repos/{owner}/{repo}/branches/main failed"))
if __name__ == "__main__":
unittest.main()
+55
View File
@@ -0,0 +1,55 @@
import pathlib
import sys
import tempfile
import unittest
sys.path.insert(0, str(pathlib.Path(__file__).resolve().parents[1]))
from do_epic.parked import file_of, park, Parked, parked_chunks, unpark
from failure import Failure
CHUNK = Parked("ABC-21", "/code/billing-ABC-21", "7", "0c0f", "an approval")
class ParkedChunks(unittest.TestCase):
def setUp(self):
self.folder = pathlib.Path(self.enterContext(tempfile.TemporaryDirectory()))
def test_an_epic_without_a_parked_chunk_has_none(self):
self.assertEqual(parked_chunks(self.folder), {})
def test_a_parked_chunk_is_read_back_by_its_issue_until_it_is_unparked(self):
self.assertIsNone(park(self.folder, CHUNK))
self.assertEqual(parked_chunks(self.folder), {"ABC-21": CHUNK})
self.assertIsNone(unpark(self.folder, "ABC-21"))
self.assertEqual(parked_chunks(self.folder), {})
def test_parking_again_replaces_what_the_chunk_waits_on_and_leaves_no_partial_file(self):
park(self.folder, CHUNK)
park(self.folder, Parked("ABC-21", "/code/billing-ABC-21", "7", "0c0f", "its checks"))
self.assertEqual(parked_chunks(self.folder)["ABC-21"].on, "its checks")
self.assertEqual([file.name for file in (self.folder / "parked").iterdir()], ["ABC-21.json"])
def test_unparking_a_chunk_that_is_not_parked_does_nothing(self):
self.assertIsNone(unpark(self.folder, "ABC-21"))
def test_says_why_the_human_sees_no_chunk_run(self):
self.assertEqual(CHUNK.waits, "it is parked: its pull request #7 awaits an approval")
def test_fails_naming_the_file_where_it_holds_no_parked_chunk_or_another_issues(self):
park(self.folder, CHUNK)
file = file_of(self.folder, "ABC-21")
for text in ("{", '{"issue": "ABC-21"}', file.read_text().replace("ABC-21", "ABC-22"), file.read_text().replace('"7"', "7")):
with self.subTest(text=text):
file.write_text(text)
failed = parked_chunks(self.folder)
self.assertIsInstance(failed, Failure)
self.assertIn(f"cannot read the parked chunk in {file}: ", failed.reason)
def test_fails_where_the_folder_cannot_be_written(self):
(self.folder / "parked").write_text("a file")
self.assertIn(f"cannot record the parked chunk in {file_of(self.folder, 'ABC-21')}: ", park(self.folder, CHUNK).reason)
if __name__ == "__main__":
unittest.main()