Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
74 changes: 68 additions & 6 deletions .github/cursor-approve/card.py
Original file line number Diff line number Diff line change
Expand Up @@ -33,6 +33,13 @@
``capped``) the caller's ``if:`` let through. On a ``pass`` the start phase
then overwrites it with the axes table, as before.

Every review that decide posts links the card (BE-20246), and so must exist
before it: a review cannot be edited afterwards to add the link, because
auto-approve.py treats an edited approval as stale and never withdraws an
edited request for changes. So on a PR's first round decide calls ``ensure``
just before its review, which creates the card from ``render_pending`` when
there is none, and the round's ``render_round`` replaces that in the same step.

Every card carries two machine-readable markers on the lines right after
``CARD_MARKER`` — ``STATE_MARKER`` and ``NEXT_MARKER`` — a stable contract
for agents, documented in docs/callers/cursor-approve.md.
Expand Down Expand Up @@ -496,6 +503,28 @@ def _gating_row(finding: dict) -> str:
return f"- **{sev}** — {ref} — {link}" + (f" — gated: {why}" if why else "")


PENDING_TEXT = ("Deciding this round. This card is rewritten with the result in a moment; if it still says "
"this, the card was not updated, so this round's latest auto-approve review is the decision and "
"the workflow run says why.")


def render_pending(round_no, max_rounds, sha: str, run_url: str) -> str:
"""The card decide creates on a PR's first round, just before posting the
review that links to it (BE-20246); ``render_round`` replaces it seconds
later, in the same step.

``pass``/``none``, the pair ``render_start`` writes while the axes are
pending: a round in progress, nothing to do. Agents already read it that
way. Any other pair would ask something of an agent that reads the card
in that window. ``no_decision``/``none`` reads as "escalate to a human",
and a remedy in ``next`` would have it push or relabel under a round that
may be approving.
"""
lines = card_head(STATE_PASS, NEXT_NONE) + [heading(round_no, max_rounds, sha), "", f"**{PENDING_TEXT}**"]
lines += ["", _reviewed_line(sha, run_url)]
return "\n".join(lines) + "\n"


def render_round(round_no, max_rounds, sha: str, state: str, next_step: str, headline: str,
reasons: list, next_text: str, run_url: str, gating=None, threshold: str = "") -> str:
"""The card cursor-review's decide writes for the round it just decided.
Expand Down Expand Up @@ -722,13 +751,48 @@ def list_comments(repo: str, pr_number) -> list:
return [c for page in pages for c in page] if pages and isinstance(pages[0], list) else pages


def upsert(repo: str, pr_number, login: str, body: str, entry=None, keep=None) -> dict:
def _comment(text: str) -> dict:
"""A comment write's response, which must name the comment it wrote."""
comment = json.loads(text)
if not isinstance(comment, dict) or comment.get("id") is None:
raise ValueError(f"the comment write returned no comment id ({type(comment).__name__})")
return comment


def ensure(repo: str, pr_number, login: str, body: str) -> tuple:
"""(card, created): this PR's card, created with `body` when there is none.

For a review that links the card, which needs the comment's URL before it
is posted: this file's ``ensure`` phase, and cursor-review's decide on a
PR's first round (BE-20246).
"""
card = find_card(list_comments(repo, pr_number), login)
Comment thread
mattmillerai marked this conversation as resolved.
Resolved
if card is not None:
return card, False
try:
return _comment(gh(["api", "-X", "POST", f"repos/{repo}/issues/{pr_number}/comments", "--input", "-"],
{"body": body})), True
except (RuntimeError, ValueError):
# A POST that failed ambiguously (a timeout, a reply without an id)
# may have written the card anyway. Look once more, so the caller edits
# that card by id rather than posting a second one.
card = find_card(list_comments(repo, pr_number), login)
if card is None:
raise
return card, True


def upsert(repo: str, pr_number, login: str, body: str, entry=None, keep=None, card=None) -> dict:
"""Edit the existing card in place, or create it when there is none.

The card's axes sentinel is carried into `body` (see `with_axes_history`);
`entry` and `keep` are decide's; `keep` stays None for every other writer.
`card` is a card this run created seconds ago (``ensure``): it is edited
without listing the comments again, since a listing taken that soon after
the write could miss it and post a second card.
"""
card = find_card(list_comments(repo, pr_number), login)
if card is None:
card = find_card(list_comments(repo, pr_number), login)
body = with_axes_history(body, card.get("body") if card is not None else "", entry, keep)
if card is not None:
return json.loads(gh(["api", "-X", "PATCH", f"repos/{repo}/issues/comments/{card['id']}", "--input", "-"],
Expand Down Expand Up @@ -795,10 +859,8 @@ def main(argv=None) -> int:
body = render_start(args.round, args.max_rounds, args.commit_sha, axes, args.approve_gate, args.run_url)
elif args.cmd == "ensure":
try:
card = find_card(list_comments(args.repo, args.pr_number), args.login)
if card is None:
body = render_start(args.round, args.max_rounds, args.commit_sha, axes, "", args.run_url)
card = upsert(args.repo, args.pr_number, args.login, body)
card, _ = ensure(args.repo, args.pr_number, args.login,
render_start(args.round, args.max_rounds, args.commit_sha, axes, "", args.run_url))
except (RuntimeError, ValueError) as e:
print(f"::warning::Could not find or create the cursor-approve card: {e}")
return 0
Expand Down
126 changes: 126 additions & 0 deletions .github/cursor-approve/tests/test_card.py
Original file line number Diff line number Diff line change
Expand Up @@ -129,6 +129,20 @@ def test_start_pass(self):
self.assertIn(f"Reviewed commit: `{SHA}`", body)
self.assertNotIn("Next step", body)

def test_pending_asks_nothing_of_an_agent(self):
# BE-20246: on screen for the seconds between a first round's review
# and its real card. It carries the start phase's "round in progress"
# pair, which every agent already reads as nothing to do: the fleet
# escalates `no_decision`/`none` to a human, and a remedy in `next`
# would have an agent push or relabel under a round that may be approving.
body = card.render_pending("1", "5", SHA, RUN)
self.assertEqual(markers(body), markers(card.render_start("1", "5", SHA, ["correctness"], "pass", RUN)))
self.assertEqual(markers(body), ("pass", "none"))
self.assertIn("Cursor approve · round 1 of 5 · `aaaaaaa`", body)
self.assertIn(f"**{card.PENDING_TEXT}**", body)
self.assertIn(f"Reviewed commit: `{SHA}` · [workflow run]({RUN})", body)
self.assertNotIn("Next step", body)

def test_start_capped(self):
body = card.render_start("5", "5", SHA, ["correctness"], "capped", RUN)
self.assertEqual(markers(body), ("capped", "human"))
Expand Down Expand Up @@ -393,6 +407,118 @@ def test_no_card_creates_one(self):
self.assertEqual(len(writes), 1)
self.assertEqual(writes[0][0][2], "POST")

def test_a_card_this_run_created_is_edited_without_listing_again(self):
# BE-20246: a listing taken seconds after `ensure` created the card
# could miss it, and upsert would then post a second card.
calls = []

def fake_gh(args, payload=None):
calls.append((args, payload))
return json.dumps({"id": 9})

with mock.patch.object(card, "gh", fake_gh):
card.upsert("o/r", 1, LOGIN, card.CARD_MARKER + "\nnew",
card={"id": 9, "user": {"login": LOGIN}, "body": card.render_pending("1", "5", SHA, RUN)})
self.assertEqual([c[0][:4] for c in calls], [["api", "-X", "PATCH", "repos/o/r/issues/comments/9"]])
self.assertEqual(calls[0][1], {"body": card.CARD_MARKER + "\nnew"})


class Ensure(unittest.TestCase):
"""`ensure`: the card a review links to, created first when there is none."""

URL = "https://github.com/o/r/pull/1#issuecomment-9"

def run_ensure(self, comments, reply=None):
self.writes = []

def fake_gh(args, payload=None):
if "--paginate" in args:
return json.dumps([comments])
self.writes.append((args[2], args[3], payload))
return json.dumps({"id": 9, "html_url": self.URL}) if reply is None else reply

with mock.patch.object(card, "gh", fake_gh):
return card.ensure("o/r", 1, LOGIN, "PENDING")

def test_an_existing_card_is_returned_untouched(self):
existing = {"id": 7, "user": {"login": LOGIN}, "body": card.CARD_MARKER + "\nold",
"html_url": "https://github.com/o/r/pull/1#issuecomment-7"}
self.assertEqual(self.run_ensure([existing]), (existing, False))
self.assertEqual(self.writes, [])

def test_no_card_creates_one_from_the_body_given(self):
found, created = self.run_ensure([])
self.assertTrue(created)
self.assertEqual(found["html_url"], self.URL)
self.assertEqual(self.writes, [("POST", "repos/o/r/issues/1/comments", {"body": "PENDING"})])

def test_a_marker_from_another_author_is_not_the_card(self):
_, created = self.run_ensure([{"id": 7, "user": {"login": "attacker"}, "body": card.CARD_MARKER}])
self.assertTrue(created)

def test_a_reply_without_a_comment_id_is_an_error(self):
for reply in ("null", "[]", "{}", '{"html_url": "https://github.com/o/r/pull/1"}'):
with self.subTest(reply=reply), self.assertRaises(ValueError):
self.run_ensure([], reply=reply)

def test_an_ambiguous_create_that_landed_is_found_and_returned_as_created(self):
# A timeout or a reply without an id may still have written the card:
# the caller must edit that one by id, not post a second.
landed = {"id": 9, "user": {"login": LOGIN}, "body": card.CARD_MARKER + "\nPENDING", "html_url": self.URL}
for failure in (RuntimeError("gh api failed: timed out"), "{}"):
with self.subTest(failure=failure):
listings = iter([[], [landed]])

def fake_gh(args, payload=None, failure=failure):
if "--paginate" in args:
return json.dumps([next(listings)])
if isinstance(failure, Exception):
raise failure
return failure

with mock.patch.object(card, "gh", fake_gh):
self.assertEqual(card.ensure("o/r", 1, LOGIN, "PENDING"), (landed, True))

def test_a_failed_create_with_no_card_after_it_still_raises(self):
def fake_gh(args, payload=None):
if "--paginate" in args:
return json.dumps([[]])
raise RuntimeError("gh api failed: HTTP 502")

with mock.patch.object(card, "gh", fake_gh), self.assertRaises(RuntimeError):
card.ensure("o/r", 1, LOGIN, "PENDING")

def test_the_ensure_phase_prints_the_url_it_found_or_created(self):
for comments, want in (([], self.URL),
([{"id": 7, "user": {"login": LOGIN}, "body": card.CARD_MARKER,
"html_url": "https://github.com/o/r/pull/1#issuecomment-7"}],
"https://github.com/o/r/pull/1#issuecomment-7")):
with self.subTest(want=want), tempfile.TemporaryDirectory() as tmp:
out = os.path.join(tmp, "out")

def fake_gh(args, payload=None, comments=comments):
if "--paginate" in args:
return json.dumps([comments])
return json.dumps({"id": 9, "html_url": self.URL})

with mock.patch.object(card, "gh", fake_gh), mock.patch.dict(os.environ, {"GITHUB_OUTPUT": out}):
self.assertEqual(card.main(["ensure", "--repo", "o/r", "--pr-number", "1", "--login", LOGIN,
"--commit-sha", SHA, "--axes", "correctness"]), 0)
with open(out, encoding="utf-8") as f:
self.assertEqual(f.read(), f"card_url={want}\n")

def test_the_ensure_phase_never_fails_the_job(self):
with tempfile.TemporaryDirectory() as tmp:
out = os.path.join(tmp, "out")
open(out, "w").close()
with mock.patch.object(card, "gh", side_effect=RuntimeError("gh api failed: HTTP 502")), \
mock.patch.dict(os.environ, {"GITHUB_OUTPUT": out}), \
contextlib.redirect_stdout(io.StringIO()):
self.assertEqual(card.main(["ensure", "--repo", "o/r", "--pr-number", "1", "--login", LOGIN,
"--commit-sha", SHA, "--axes", "correctness"]), 0)
with open(out, encoding="utf-8") as f:
self.assertEqual(f.read(), "")


def _secrets_declared(path):
"""Names under `on.workflow_call.secrets` — text-parsed (stdlib only)."""
Expand Down
Loading
Loading