Add do-epic's gate read and parked-chunk state files
This commit is contained in:
@@ -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]}")
|
||||
@@ -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
|
||||
@@ -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()
|
||||
@@ -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()
|
||||
Reference in New Issue
Block a user