diff --git a/.github/cursor-review/README.md b/.github/cursor-review/README.md index 9586dfe9..cdaa3057 100644 --- a/.github/cursor-review/README.md +++ b/.github/cursor-review/README.md @@ -416,6 +416,7 @@ All optional except `workflows_ref` (required, no default) — pass them under | `approve_scope` | `delta` | Rounds 2+ of auto-approve gate only on findings inside the verified incremental block, live re-raises of unresolved threads (by `repeat_of`, or by landing on the path and line of an earlier round's still-open thread), and High/Critical anywhere; the rest post as threads marked non-blocking and are never auto-resolved. Fails closed to `full` (every finding counts) on round 1, an unavailable/discarded/empty block, a block naming an unparseable path, an unknown ledger, an unreadable list of earlier open threads, or an explicitly empty value. | | `defer_approval` | `false` | For a caller that runs cursor-approve after this workflow: an APPROVE outcome still reports `approve_gate` = `pass` but posts no approval and resolves no thread, and withdraws the approver's own earlier auto-approvals and requests for changes, so cursor-approve's decide is the only approver. Pass the workflow's `approve_scope_effective` output (the scope `decide` actually gated under, `full` on any fallback) to cursor-approve's `approve_scope`, so its resolution honours non-gating marks only after a `delta` round. | | `approve_max_failed_reviewers` | `0` | Errored panel reviewers (status `error`) auto-approve tolerates before withholding its decision. `0` → any reviewer that did not complete means no decision. Never tolerates another status, more than N, or a review type with no completed reviewer; tolerated cells are named in the decision. | +| `rereview_command` | `''` (off) | A comment command, e.g. `/review`, asking for another round on the **same commit**. Empty leaves the same-commit dedupe absolute. Needs the SAME value on [`cursor-review-auto-label.yml`](../../docs/callers/cursor-review-auto-label.md) plus `issue_comment` in that caller's triggers: that half re-applies the label (removing it first, since adding a label already present raises no event), this half stops the dedupe from skipping the round it starts. Setting one alone is a silent no-op. The command must be the first token of the first line, and the commenter's association must be `OWNER`, `MEMBER` or `COLLABORATOR` — not the opted-in roster. The request must postdate the review it overrides, so one request buys one round; `max_rounds` still applies. Exists because the documented alternative cannot work: the consolidated review is `COMMENTED`, which GitHub will not dismiss. See [the setup guide](../../docs/callers/cursor-review.md#asking-for-another-round-on-the-same-commit). | | `max_rounds` | `5` | Per-PR review-round cap; `0` → none. Counts the posting identity's consolidated reviews since `needs-human-review` was last removed; at or over the cap the panel is skipped, the PR is labelled `needs-human-review`, one comment lists the latest round's open findings above the threshold, and the `approve_gate` output is `capped`. Fails open on a read error. See [the setup guide](../../docs/callers/cursor-review.md#round-cap-and-the-approve_gate-output). | | `runs_on` | `'"ubuntu-latest"'` | JSON-encoded `runs-on` (same shape as `cursor-review-auto-label.yml`'s) for the four credential-free heavy jobs only: `diff-size`, `preflight`, the `review` panel and `consolidate`. The gate, ledger, Slack notices and every job holding the App token or `pull-requests: write` stay on GitHub-hosted `ubuntu-latest`. Those four run models with unsandboxed shell over PR code, so use a self-hosted pool only if each job gets a fresh pod (fresh filesystem and `$HOME`), holds no cloud identity or token, and can't reach private networks or the metadata server. The image must be linux/x64 with bash, git, curl, jq, python3, gh, tar and GNU coreutils. | @@ -464,8 +465,13 @@ and upsert are both `continue-on-error`: the size verdict lives in the trigger label is on) starts a run. - **Re-review after changes**: push commits. The new HEAD SHA bypasses the idempotency check and a re-applied label runs a fresh panel. -- **Re-review unchanged content**: dismiss the existing review, then re-apply - the label. +- **Re-review unchanged content**: set `rereview_command` (e.g. `/review`) on + BOTH `cursor-review.yml` and `cursor-review-auto-label.yml`, then comment it + as an OWNER / MEMBER / COLLABORATOR. Dismissing the existing review — what + this said before — cannot be done: the consolidated review is posted + `COMMENTED`, and GitHub dismisses only `APPROVED` and `CHANGES_REQUESTED` + ones, so without the command the only re-review is a new commit. See + [the caller page](../../docs/callers/cursor-review.md#asking-for-another-round-on-the-same-commit). ## Customizing the review diff --git a/.github/cursor-review/tests/test_rereview_command.py b/.github/cursor-review/tests/test_rereview_command.py new file mode 100644 index 00000000..b296d5aa --- /dev/null +++ b/.github/cursor-review/tests/test_rereview_command.py @@ -0,0 +1,407 @@ +#!/usr/bin/env python3 +"""Tests for `rereview_command` — asking for another round on the SAME commit. + +WHY IT EXISTS. `Check for existing review` skips the panel when a non-dismissed +Bot review carrying the consolidated marker exists for the current HEAD SHA. +That dedupe is otherwise ABSOLUTE, and both documented escape hatches fail for +the case that actually wants one: pushing a commit is not an option when the +code is fine, and "dismiss the existing review" cannot be done at all, because +that review is posted COMMENTED and GitHub does not permit dismissing a +commented review. So a round that reached no decision because reviewers +ERRORED could only be retried by pushing a no-op commit. + +TWO HALVES, AND BOTH ARE NEEDED. `cursor-review-auto-label.yml` turns the +comment into a label event (a label is the only thing cursor-review.yml +triggers on, and 49 of its expressions read `github.event.pull_request`, so it +cannot be called from an `issue_comment` event directly). `cursor-review.yml` +then has to not dedupe the round that arrives. Setting one without the other +is a silent no-op, so `BothHalvesTest` pins that the input exists on both. + +Parsed WITHOUT PyYAML, like its sibling suites: this repo is stdlib-only and CI +installs no requirements for these tests. + +Run: python3 -m unittest discover -s .github/cursor-review/tests -p 'test_*.py' -v +""" + +import io +import json +import os +import re +import shutil +import subprocess +import unittest + +WORKFLOWS = os.path.normpath( + os.path.join(os.path.dirname(__file__), "..", "..", "workflows") +) +REVIEW = os.path.join(WORKFLOWS, "cursor-review.yml") +AUTO_LABEL = os.path.join(WORKFLOWS, "cursor-review-auto-label.yml") + +AUTHORIZED = ("OWNER", "MEMBER", "COLLABORATOR") +OUTSIDERS = ("CONTRIBUTOR", "NONE", "FIRST_TIME_CONTRIBUTOR", "MANNEQUIN") + + +def read(path): + with io.open(path, encoding="utf-8") as f: + return f.read() + + +def step(path, name_fragment): + """One step's raw YAML block, located by a fragment of its `name:`.""" + text, out, cur = read(path), [], None + for line in text.splitlines(): + if re.match(r"^ - name: ", line): + if cur is not None: + out.append("\n".join(cur)) + cur = [line] if name_fragment in line else None + elif cur is not None: + cur.append(line) + if cur is not None: + out.append("\n".join(cur)) + assert len(out) == 1, f"{name_fragment!r} matched {len(out)} steps in {path}" + return out[0] + + +def run_block(block): + """The `run:` script of a step block, dedented.""" + m = re.search(r"^ run: \|\n(.*)", block, re.S | re.M) + assert m, "step has no run: block" + body = [] + for line in m.group(1).splitlines(): + if line.strip() and not line.startswith(" "): + break + body.append(line[10:]) + return "\n".join(body) + + +def jq_filter(script, after): + """The single-quoted jq program that follows `after` in a shell script.""" + seg = script[script.index(after):] + start = seg.index("'") + 1 + return seg[start:seg.index("' \\", start)] + + +class BothHalvesTest(unittest.TestCase): + """The input must exist on both workflows, defaulting to off.""" + + def test_the_input_exists_on_both_and_defaults_to_empty(self): + for path in (REVIEW, AUTO_LABEL): + with self.subTest(path=os.path.basename(path)): + text = read(path) + m = re.search( + r"^ rereview_command:\n(.*?)^ \w+:", + text, re.S | re.M, + ) + self.assertIsNotNone(m, "input not declared") + decl = m.group(1) + self.assertIn("type: string", decl) + self.assertIn("required: false", decl) + self.assertRegex(decl, r"default:\s*''") + + def test_each_half_tells_the_reader_the_other_is_required(self): + # Setting one alone is a silent no-op, which is the failure mode most + # likely to be read as "the command does not work". + self.assertIn("rereview_command", read(AUTO_LABEL)) + m = re.search(r"^ rereview_command:\n(.*?)^ \w+:", + read(AUTO_LABEL), re.S | re.M) + self.assertIn("SAME value on cursor-review.yml", m.group(1)) + + def test_the_gate_asks_for_nothing_the_documented_caller_does_not_grant(self): + # A nested job cannot exceed its caller's grant, and the documented + # caller grants only `contents` + `pull-requests`. An `issues: read` + # here (once added for the comment read, which Pull requests already + # authorizes on a PR) failed EVERY caller at startup on the pin bump. + text = read(REVIEW) + gate = text[text.index("\n gate:"):text.index("\n ledger:")] + perms = re.search(r"(?m)^ permissions:\n((?: .*\n)+)", gate) + self.assertIsNotNone(perms) + granted = set(re.findall(r"(?m)^ ([a-z-]+):", perms.group(1))) + self.assertEqual({"contents", "pull-requests"}, granted) + + +class GateBypassTest(unittest.TestCase): + """The dedupe step's shape: off by default, and one request buys one round.""" + + @classmethod + def setUpClass(cls): + cls.block = step(REVIEW, "Check for prior review on this commit") + cls.script = run_block(cls.block) + + def test_the_command_arrives_through_the_environment(self): + self.assertIn("REREVIEW_COMMAND: ${{ inputs.rereview_command }}", self.block) + + def test_an_unset_command_cannot_force_anything(self): + # `-n "${REREVIEW_COMMAND:-}"` is what keeps the default behaviour + # byte-identical for every existing caller. + self.assertIn('[ -n "${REREVIEW_COMMAND:-}" ]', self.script) + + def test_the_bypass_requires_a_comment_newer_than_the_review(self): + # Otherwise one stale `/review` would force a round every time the + # label was touched, forever. + self.assertIn(".created_at > $since", self.script) + self.assertIn("submitted_at", self.script) + + def test_reviews_are_read_from_every_page(self): + # 30 per page, oldest first: page 1 alone drops the NEWEST round. + self.assertIn('gh api --paginate "repos/$REPO/pulls/$PR_NUMBER/reviews"', + self.script) + self.assertNotRegex(self.script, r'gh api "repos/\$REPO/pulls/\$PR_NUMBER/reviews"') + + def test_a_command_with_whitespace_is_warned_about(self): + self.assertIn("::warning::rereview_command contains whitespace", self.script) + + def test_the_skip_branch_still_exists(self): + self.assertIn("already_reviewed=true", self.script) + self.assertIn("already_reviewed=false", self.script) + + def test_the_comment_body_is_never_echoed(self): + # Public logs; a comment body is attacker-authored. + for line in self.script.splitlines(): + if line.strip().startswith("echo"): + self.assertNotIn("$COMMENT", line) + self.assertNotIn(".body", line) + + +@unittest.skipIf(shutil.which("jq") is None, "jq not installed") +class GateFilterTest(unittest.TestCase): + """The real jq program, run against the payload shapes it will meet. + + Extracted from the workflow rather than copied, so the test cannot drift + from what ships. The input framing matches `gh api --paginate | jq -s`: + one JSON array per page, slurped into an array of pages. + """ + + SINCE = "2026-10-10T03:00:00Z" + + @classmethod + def setUpClass(cls): + cls.filter = jq_filter(run_block(step(REVIEW, "Check for prior review on this commit")), + "FORCED=$(gh api") + + def count(self, pages, command="/review"): + proc = subprocess.run( + ["jq", "-s", "--arg", "cmd", command, "--arg", "since", self.SINCE, + self.filter], + input="\n".join(json.dumps(p) for p in pages), + capture_output=True, text=True, + ) + self.assertEqual(0, proc.returncode, proc.stderr) + return int(proc.stdout.strip()) + + @staticmethod + def comment(body, association="OWNER", at="2026-10-10T04:00:00Z"): + return {"body": body, "author_association": association, "created_at": at} + + def test_a_plain_command_counts(self): + self.assertEqual(1, self.count([[self.comment("/review")]])) + + def test_an_argument_is_allowed(self): + self.assertEqual(1, self.count([[self.comment("/review please look again")]])) + self.assertEqual(1, self.count([[self.comment("/review\targ")]])) + + def test_leading_whitespace_is_tolerated(self): + self.assertEqual(1, self.count([[self.comment(" /review")]])) + + def test_a_crlf_body_counts(self): + self.assertEqual(1, self.count([[self.comment("/review\r\nthanks")]])) + + def test_a_prefix_collision_does_not_count(self): + # `startswith` would have matched both of these. + for body in ("/reviewer", "/reviewed it", "/reviewing"): + with self.subTest(body=body): + self.assertEqual(0, self.count([[self.comment(body)]])) + + def test_the_command_must_open_the_comment(self): + # Otherwise quoting someone else's `/review` would re-fire a round. + self.assertEqual(0, self.count([[self.comment("hello\n/review")]])) + self.assertEqual(0, self.count([[self.comment("> /review")]])) + + def test_a_blank_first_line_is_not_skipped(self): + # Trimming the WHOLE body first would strip the newline and promote + # line two; the auto-label half (`head -n 1`) never sees it either. + for body in ("\n/review", " \n/review", "\r\n/review"): + with self.subTest(body=body): + self.assertEqual(0, self.count([[self.comment(body)]])) + + def test_only_ascii_blanks_delimit_the_token(self): + # Matches awk's default field split in the auto-label half: a body the + # label step would not act on must not count here either. + for body in ("/review\u00a0x", "\u00a0/review"): + with self.subTest(body=body): + self.assertEqual(0, self.count([[self.comment(body)]])) + + def test_a_comment_older_than_the_review_does_not_count(self): + self.assertEqual( + 0, self.count([[self.comment("/review", at="2026-10-10T02:00:00Z")]]) + ) + + def test_only_an_authorized_association_counts(self): + for assoc in AUTHORIZED: + with self.subTest(assoc=assoc): + self.assertEqual(1, self.count([[self.comment("/review", assoc)]])) + for assoc in OUTSIDERS: + with self.subTest(assoc=assoc): + self.assertEqual(0, self.count([[self.comment("/review", assoc)]])) + + def test_a_missing_or_empty_body_is_not_an_error(self): + # The filter runs over every comment on the PR, so it meets these. + for body in (None, "", " ", "\n"): + with self.subTest(body=body): + self.assertEqual(0, self.count([[self.comment(body)]])) + self.assertEqual(0, self.count([[{"author_association": "OWNER", + "created_at": "2026-10-10T04:00:00Z"}]])) + + def test_it_reads_every_page(self): + self.assertEqual( + 1, self.count([[self.comment("lgtm")], [self.comment("/review")]]) + ) + + def test_an_empty_page_is_not_an_error(self): + self.assertEqual(0, self.count([[]])) + + def test_the_command_string_is_configurable(self): + pages = [[self.comment("/look-again")]] + self.assertEqual(1, self.count(pages, command="/look-again")) + self.assertEqual(0, self.count(pages, command="/review")) + + +class AutoLabelCommandTest(unittest.TestCase): + """The step that turns the comment into a label event.""" + + @classmethod + def setUpClass(cls): + cls.block = step(AUTO_LABEL, "asks for another round") + cls.script = run_block(cls.block) + + def test_it_only_runs_on_a_comment_and_only_when_enabled(self): + self.assertIn("github.event_name == 'issue_comment'", self.block) + self.assertIn("inputs.rereview_command != ''", self.block) + + def test_only_a_new_comment_counts(self): + # An edited or deleted old `/review` must not toggle the label. + self.assertIn("github.event.action == 'created'", self.block) + + def test_the_job_prefilters_comments_before_a_runner_or_token(self): + text = read(AUTO_LABEL) + job = text[text.index("\n auto-label:"):text.index("\n steps:")] + m = re.search(r"(?m)^ if: >-\n((?: .*\n)+)", job) + self.assertIsNotNone(m, "auto-label job has no if:") + cond = m.group(1) + self.assertIn("github.event_name != 'issue_comment'", cond) + for term in ("inputs.rereview_command != ''", + "github.event.action == 'created'", + "github.event.issue.pull_request", + "github.event.issue.state == 'open'", + "github.event.comment.author_association"): + self.assertIn(term, cond) + for assoc in AUTHORIZED: + self.assertIn(assoc, cond) + for assoc in OUTSIDERS: + self.assertNotIn(assoc, cond) + + def test_the_add_waits_for_the_remove_to_land(self): + # Fired back to back, the `unlabeled` run can be created second and + # cancel the `labeled` run through cursor-review's trigger slot. + between = self.script[self.script.index("--remove-label"): + self.script.rindex("--add-label")] + self.assertIn("--json labels", between) + self.assertRegex(between, r"(?m)^\s+sleep \d+$") + + def test_a_command_with_whitespace_is_warned_about(self): + self.assertIn("::warning::rereview_command contains whitespace", self.script) + + def test_the_comment_body_is_not_interpolated_into_the_script(self): + # The injection guard: `${{ github.event.comment.body }}` inside a + # `run:` would let a comment run shell. It must arrive via `env:`. + self.assertIn("COMMENT_BODY: ${{ github.event.comment.body }}", self.block) + self.assertNotIn("${{ github.event.comment.body }}", self.script) + self.assertNotIn("${{", self.script) + + def test_it_ignores_comments_on_plain_issues(self): + self.assertIn("IS_PR: ${{ github.event.issue.pull_request != null }}", self.block) + self.assertIn('[ "$IS_PR" != "true" ]', self.script) + + def test_it_matches_the_first_token_not_a_prefix(self): + self.assertIn("awk '{print $1}'", self.script) + self.assertIn('"$first_token" != "$REREVIEW_COMMAND"', self.script) + + def test_authorization_is_the_comment_association(self): + self.assertIn("ASSOCIATION: ${{ github.event.comment.author_association }}", + self.block) + for assoc in AUTHORIZED: + self.assertIn(assoc, self.script) + for assoc in OUTSIDERS: + self.assertNotIn(assoc, self.script) + + def test_it_removes_before_adding(self): + # Adding a label that is already present raises NO event, and after a + # round the label is always already present — so a re-add alone would + # look exactly like the command being ignored. + self.assertIn("--remove-label", self.script) + self.assertLess(self.script.index("--remove-label"), + self.script.rindex("--add-label")) + + def test_a_closed_pr_is_left_alone(self): + self.assertIn("--json labels,state", self.script) + self.assertLess(self.script.index('!= "OPEN"'), + self.script.index("--remove-label")) + + def test_a_failed_re_add_is_retried_and_then_fails_loudly(self): + # After the remove lands, one failed add would leave the PR unlabeled. + self.assertRegex(self.script, r"for attempt in 1 2 3; do\n\s+if gh pr edit .*--add-label") + self.assertIn("exit 1", self.script[self.script.rindex("--add-label"):]) + + def test_the_skip_label_still_wins(self): + self.assertIn("SKIP_LABEL", self.script) + + def test_the_body_is_never_echoed(self): + for line in self.script.splitlines(): + if line.strip().startswith("echo"): + self.assertNotIn("COMMENT_BODY", line) + self.assertNotIn("first_token", line) + + +@unittest.skipIf(shutil.which("awk") is None, "awk not installed") +class FirstTokenTest(unittest.TestCase): + """The shell half of the command match, run as the step runs it.""" + + @classmethod + def setUpClass(cls): + cls.script = run_block(step(AUTO_LABEL, "asks for another round")) + m = re.search(r"first_token=\$\((.*?)\)\n", cls.script, re.S) + assert m, "first-token pipeline not found" + cls.pipeline = m.group(1) + + def token(self, body): + proc = subprocess.run( + ["bash", "-c", f'COMMENT_BODY="$1"; printf "%s" "$({self.pipeline})"', + "bash", body], + capture_output=True, text=True, + ) + self.assertEqual(0, proc.returncode, proc.stderr) + return proc.stdout + + def test_it_extracts_the_command(self): + self.assertEqual("/review", self.token("/review")) + self.assertEqual("/review", self.token("/review please")) + self.assertEqual("/review", self.token(" /review ")) + self.assertEqual("/review", self.token("/review\r\nmore")) + self.assertEqual("/review", self.token("/review\nsecond line")) + + def test_a_collision_yields_a_different_token(self): + for body in ("/reviewer", "/reviewed", "/reviewing now"): + with self.subTest(body=body): + self.assertNotEqual("/review", self.token(body)) + + def test_a_later_line_is_not_reached(self): + self.assertNotEqual("/review", self.token("hello\n/review")) + self.assertNotEqual("/review", self.token("\n/review")) + + def test_degenerate_bodies_yield_nothing(self): + for body in ("", " ", "\n", "\r\n"): + with self.subTest(body=body): + self.assertEqual("", self.token(body)) + + +if __name__ == "__main__": + unittest.main(verbosity=2) diff --git a/.github/workflows/cursor-review-auto-label.yml b/.github/workflows/cursor-review-auto-label.yml index 19d8b741..e99d1bcb 100644 --- a/.github/workflows/cursor-review-auto-label.yml +++ b/.github/workflows/cursor-review-auto-label.yml @@ -10,6 +10,9 @@ name: Cursor Review Auto-Label (reusable) # - assigned -> the newly-assigned reviewer # - opened -> the PR author (skipped while the PR is a draft) # - ready_for_review -> the PR author +# - issue_comment -> an authorized commenter typing `rereview_command` +# (e.g. `/review`), which asks for ANOTHER round on +# the SAME commit. Off unless that input is set. # A caller that lists only `[assigned]` keeps the original assignment-only # behavior; add `opened` / `ready_for_review` to also label on PR creation. # @@ -63,6 +66,23 @@ name: Cursor Review Auto-Label (reusable) on: workflow_call: inputs: + rereview_command: + description: >- + Opt-in: a comment command (e.g. `/review`) that re-applies the review + label so cursor-review.yml runs ANOTHER round on the SAME commit. + Empty (the default) ignores every comment, so a caller that does not + list `issue_comment` in its `on:` is unaffected either way. Set the + SAME value on cursor-review.yml's `rereview_command`: this half makes + the round start, and that half stops its same-commit dedupe from + skipping it. Setting only this one re-applies a label that the dedupe + then no-ops, which looks exactly like the command being ignored. + Authorization is the comment's own association — OWNER, MEMBER or + COLLABORATOR, the bar `pr-derisk.yml` applies to `/derisk` — never + the opted-in roster, which governs who gets labelled automatically + rather than who may ask for a re-read. + type: string + required: false + default: '' review_label: description: >- Label to apply. MUST match the label cursor-review.yml triggers on @@ -125,6 +145,20 @@ permissions: jobs: auto-label: name: Auto-apply review label + # Every comment on every issue and PR fires `issue_comment`. Settle the + # cheap, payload-only questions here so the rest never allocates a runner + # (possibly the caller's self-hosted `runs_on` pool) or mints the App + # token: the feature is on, this is a NEW comment (an edited or deleted + # old `/review` must not toggle the label and cancel a running panel), + # on an open PR, from an authorized association. The step re-checks the + # association and the live PR state; this is only the prefilter. + if: >- + github.event_name != 'issue_comment' + || (inputs.rereview_command != '' + && github.event.action == 'created' + && github.event.issue.pull_request + && github.event.issue.state == 'open' + && contains(fromJSON('["OWNER","MEMBER","COLLABORATOR"]'), github.event.comment.author_association)) runs-on: ${{ fromJSON(inputs.runs_on) }} permissions: contents: read @@ -262,3 +296,109 @@ jobs: echo "Applying $REVIEW_LABEL label for $candidate (action=$ACTION)." gh pr edit "$PR_NUMBER" --repo "$REPO" --add-label "$REVIEW_LABEL" + + - name: Re-apply the label when an authorized commenter asks for another round + # The one moment that is NOT about who became responsible for a PR: a + # human saying "look at this again". It exists because the same-commit + # dedupe in cursor-review.yml had no working escape hatch — its own + # documented one is to dismiss the existing review, and that review is + # posted COMMENTED, a state GitHub does not let anyone dismiss. So a + # round that reached no decision because reviewers ERRORED could only + # be retried by pushing a commit that changed nothing. + # + # Unlike the step above this must REMOVE and re-add: after a round the + # label is already present, and adding a label that is already there + # raises no event at all. + if: github.event_name == 'issue_comment' && github.event.action == 'created' && inputs.rereview_command != '' + env: + GH_TOKEN: ${{ steps.app-token-narrow.outputs.token || steps.app-token-default.outputs.token }} + # `null` unless the comment is on a PR; issue_comment fires for plain + # issues too, which have no label worth touching. + IS_PR: ${{ github.event.issue.pull_request != null }} + PR_NUMBER: ${{ github.event.issue.number }} + REPO: ${{ github.repository }} + # Through the ENVIRONMENT, never interpolated into the script: a + # comment body is attacker-authored text and `${{ }}` in a `run:` + # would be a shell-injection hole. + COMMENT_BODY: ${{ github.event.comment.body }} + ASSOCIATION: ${{ github.event.comment.author_association }} + REVIEW_LABEL: ${{ inputs.review_label }} + SKIP_LABEL: ${{ inputs.skip_label }} + REREVIEW_COMMAND: ${{ inputs.rereview_command }} + run: | + if [ "$IS_PR" != "true" ]; then + echo "Comment is not on a pull request — no-op." + exit 0 + fi + + # The match below is against ONE whitespace-free token, so a value + # like `/cursor review` can never match and the feature would + # silently do nothing. + case "$REREVIEW_COMMAND" in + *[[:space:]]*) + echo "::warning::rereview_command contains whitespace, so it can never match a comment's first token — use a single token such as /review." + exit 0 ;; + esac + + # The FIRST token of the first line, so `/review please have another + # look` counts and `/reviewer` does not. Nothing from the body is + # echoed: these logs are public. + first_token=$(printf '%s' "$COMMENT_BODY" | head -n 1 | tr -d '\r' | awk '{print $1}') + if [ "$first_token" != "$REREVIEW_COMMAND" ]; then + echo "Comment does not open with the re-review command — no-op." + exit 0 + fi + + case "$ASSOCIATION" in + OWNER|MEMBER|COLLABORATOR) ;; + *) + echo "::warning::Ignoring a re-review command from a $ASSOCIATION association." + exit 0 ;; + esac + + # A comment on a closed or merged PR still fires issue_comment, and + # the label event it would raise starts a round on code that can no + # longer land. + pr=$(gh pr view "$PR_NUMBER" --repo "$REPO" --json labels,state) + if [ "$(echo "$pr" | jq -r .state)" != "OPEN" ]; then + echo "PR is not open — no-op." + exit 0 + fi + labels=$(echo "$pr" | jq -c '[.labels[].name]') + if echo "$labels" | jq -e --arg l "$SKIP_LABEL" 'index($l)' > /dev/null; then + echo "$SKIP_LABEL present — not re-reviewing." + exit 0 + fi + + if echo "$labels" | jq -e --arg l "$REVIEW_LABEL" 'index($l)' > /dev/null; then + echo "Re-review requested — removing and re-adding $REVIEW_LABEL to raise a fresh event." + gh pr edit "$PR_NUMBER" --repo "$REPO" --remove-label "$REVIEW_LABEL" + # The remove raises an `unlabeled` run and the add a `labeled` one, + # and both land in cursor-review's `trigger` slot with + # cancel-in-progress. Fired back to back, GitHub does not promise + # which run is created first — and if `unlabeled` is second it + # cancels the round this command asked for. So wait until the + # remove is visible, then give its run a head start. + for _ in 1 2 3 4 5 6 7 8 9 10; do + if ! gh pr view "$PR_NUMBER" --repo "$REPO" --json labels --jq '[.labels[].name]' \ + | jq -e --arg l "$REVIEW_LABEL" 'index($l)' > /dev/null; then + break + fi + sleep 2 + done + sleep 10 + else + echo "Re-review requested — applying $REVIEW_LABEL." + fi + # Retried: once the remove above has landed, a single failed add + # would leave the PR WITHOUT the label it had before the command — + # strictly worse than ignoring the request. + for attempt in 1 2 3; do + if gh pr edit "$PR_NUMBER" --repo "$REPO" --add-label "$REVIEW_LABEL"; then + exit 0 + fi + echo "::warning::Adding $REVIEW_LABEL failed (attempt $attempt of 3)." + [ "$attempt" -lt 3 ] && sleep $((attempt * 5)) + done + echo "::error::Could not re-add $REVIEW_LABEL — the PR is now missing it; re-apply it by hand." + exit 1 diff --git a/.github/workflows/cursor-review.yml b/.github/workflows/cursor-review.yml index 208b2bc5..b11a3046 100644 --- a/.github/workflows/cursor-review.yml +++ b/.github/workflows/cursor-review.yml @@ -255,6 +255,23 @@ on: type: boolean required: false default: true + rereview_command: + description: >- + Opt-in: the comment command that asks for ANOTHER round on the SAME + commit, e.g. `/review`. Empty (the default) leaves the same-commit + dedupe absolute, exactly as before. When set, this workflow does not + skip a round if an authorized commenter posted that command AFTER the + newest consolidated review for the current HEAD SHA — so a round that + reached no decision because reviewers errored can be re-run without + pushing an empty commit. It does NOT by itself give anyone a way to + TRIGGER a run: the command has to reach the review label, which is + `cursor-review-auto-label.yml`'s `issue_comment` moment. Authorized + means an OWNER / MEMBER / COLLABORATOR association on the comment, + the same bar `pr-derisk.yml` applies to `/derisk`. `max_rounds` still + caps how many rounds a PR can have. + type: string + required: false + default: '' run_without_label: description: >- Run on plain pull_request events (opened / reopened / ready_for_review @@ -762,6 +779,12 @@ jobs: runs-on: ubuntu-latest permissions: contents: read + # Also covers `rereview_command`'s read of the PR's conversation + # comments: `issues/{n}/comments` on a PULL REQUEST is authorized by + # Pull requests, not Issues. Do NOT add `issues: read` — a nested job + # cannot exceed its caller's grant, and the documented caller grants + # only `contents` + `pull-requests`, so every caller would fail at + # startup on the pin bump, whether or not it set the command. pull-requests: read outputs: should_run: ${{ steps.check.outputs.should_run }} @@ -941,6 +964,7 @@ jobs: PR_NUMBER: ${{ github.event.pull_request.number }} REPO: ${{ github.repository }} HEAD_SHA: ${{ github.event.pull_request.head.sha }} + REREVIEW_COMMAND: ${{ inputs.rereview_command }} run: | # Idempotency: skip the matrix if a Cursor Review consolidated # review already exists for this exact HEAD SHA. Protects against @@ -949,8 +973,10 @@ jobs: # # Escape hatches: # - Push commits → new HEAD SHA, check finds nothing, runs. - # - Dismiss the existing review → DISMISSED state filtered out - # below, so re-applying the label fires a fresh run. + # - `rereview_command` (below) → an authorized command comment newer + # than the review lets ONE re-labeled run through. Dismissing the + # review is not a hatch: it is posted COMMENTED, which GitHub will + # not dismiss (DISMISSED is still filtered out, for older reviews). # # API failure falls through to running, not skipping — better to # double-review than silently no-op. @@ -976,13 +1002,63 @@ jobs: # matters. Residual, accepted: another installed App could post a # marked review. Closing THAT needs the identity check to move into # the posting job, where the token exists. - EXISTING=$(gh api "repos/$REPO/pulls/$PR_NUMBER/reviews" 2>/dev/null \ + # + # Every page, slurped: the endpoint returns 30 per page oldest-first, + # so on a long-lived PR the newest round is exactly what page 1 drops. + # A failed fetch degrades to "no prior review", as it always has. + REVIEWS=$( { gh api --paginate "repos/$REPO/pulls/$PR_NUMBER/reviews" 2>/dev/null || true; } \ + | jq -c -s 'add // []' 2>/dev/null) || REVIEWS='[]' + EXISTING=$(printf '%s' "$REVIEWS" \ | jq --arg sha "$HEAD_SHA" '[.[] | select(.commit_id == $sha and .state != "DISMISSED" and (.user.type == "Bot") and (.body | startswith("## 🔍 Cursor Review — Consolidated panel")))] | length' \ 2>/dev/null || echo 0) - if [ "$EXISTING" -gt 0 ]; then + # An explicit re-review request overrides the dedupe above, which is + # otherwise ABSOLUTE for a given commit: the only documented escape + # hatches were a new commit or dismissing the existing review, and + # the review this step matches is posted COMMENTED — a state GitHub + # does not let anyone dismiss. So "look again at this same commit" + # had no working path at all, which matters most in exactly the case + # it is wanted: a round that reached no decision because reviewers + # errored, where the code is fine and nothing needs pushing. + # + # The signal is a command comment NEWER than the review it overrides, + # so one request buys exactly one round: the round it triggers posts + # a newer review, and the next run dedupes again. A stale command + # from three rounds ago can never re-fire. + # + # Authorization is the comment's association, the bar `/derisk` + # uses. It is checked HERE rather than trusted from whoever applied + # the label, because the label is how the request arrives and a + # label says nothing about who asked. + # + # Nothing from the comment is echoed: these logs are public and a + # comment body is attacker-authored text. + FORCED=0 + case "${REREVIEW_COMMAND:-}" in + *[[:space:]]*) + echo "::warning::rereview_command contains whitespace, so it can never match a comment's first token — use a single token such as /review." ;; + esac + if [ "$EXISTING" -gt 0 ] && [ -n "${REREVIEW_COMMAND:-}" ]; then + LAST_REVIEW=$(printf '%s' "$REVIEWS" \ + | jq -r --arg sha "$HEAD_SHA" '[.[] | select(.commit_id == $sha and .state != "DISMISSED" and (.user.type == "Bot") and (.body | startswith("## 🔍 Cursor Review — Consolidated panel"))) | .submitted_at] | max // ""' \ + 2>/dev/null || echo "") + if [ -n "$LAST_REVIEW" ]; then + FORCED=$(gh api --paginate "repos/$REPO/issues/$PR_NUMBER/comments" 2>/dev/null \ + | jq -s --arg cmd "$REREVIEW_COMMAND" --arg since "$LAST_REVIEW" \ + '[.[][] | select(.created_at > $since) + | select(.author_association == "OWNER" or .author_association == "MEMBER" or .author_association == "COLLABORATOR") + | select(((.body // "") | split("\n")[0] // "" | sub("\r$"; "") | sub("^[ \t]+"; "") | sub("[ \t].*$"; "")) == $cmd)] | length' \ + 2>/dev/null || echo 0) + case "$FORCED" in ''|*[!0-9]*) FORCED=0 ;; esac + fi + fi + + if [ "$EXISTING" -gt 0 ] && [ "$FORCED" -eq 0 ]; then echo "Already reviewed at $HEAD_SHA ($EXISTING existing review(s)) — skipping matrix." echo "already_reviewed=true" >> "$GITHUB_OUTPUT" + elif [ "$EXISTING" -gt 0 ]; then + echo "Already reviewed at $HEAD_SHA, but an authorized re-review was requested after that review — proceeding." + echo "already_reviewed=false" >> "$GITHUB_OUTPUT" else echo "No prior review for $HEAD_SHA — proceeding." echo "already_reviewed=false" >> "$GITHUB_OUTPUT" diff --git a/docs/callers/cursor-review-auto-label.md b/docs/callers/cursor-review-auto-label.md index e27f2ad8..9d00cfff 100644 --- a/docs/callers/cursor-review-auto-label.md +++ b/docs/callers/cursor-review-auto-label.md @@ -99,6 +99,7 @@ Only that. The label write goes through the App token, not `GITHUB_TOKEN`. | Input | Default | Notes | |---|---|---| +| `rereview_command` | `''` (off) | A comment command, e.g. `/review`, that re-applies the review label so another round runs on the **same commit**. Needs `issue_comment` in your `on:` triggers, and the SAME value on `cursor-review.yml`'s `rereview_command` — this half starts the round, that half stops its same-commit dedupe from skipping it. Set only here, the label is re-applied and then the dedupe no-ops it, which looks exactly like the command being ignored. Authorized = an `OWNER` / `MEMBER` / `COLLABORATOR` association; the opted-in roster is not consulted. **Also widen the job's `if:` above** to `github.event_name == 'issue_comment' \|\| ()` — `github.event.pull_request` is null on a comment event, so the same-repo check alone skips every command. See [the full caller](cursor-review.md#asking-for-another-round-on-the-same-commit). | | `review_label` | `cursor-review` | Must match `cursor-review.yml`'s `review_label`. | | `skip_label` | `skip-cursor-review` | Present on a PR ⇒ never auto-label it. | | `runs_on` | `'"ubuntu-latest"'` | JSON. Set for self-hosted runners. | diff --git a/docs/callers/cursor-review.md b/docs/callers/cursor-review.md index 33035a47..c10f37ee 100644 --- a/docs/callers/cursor-review.md +++ b/docs/callers/cursor-review.md @@ -139,6 +139,7 @@ pull-requests: write # posting the consolidated review (and, at the round cap, | `approve_scope` | `delta` | What an auto-approve round after the first gates on. `delta`: a finding above `approve_max_severity` blocks only when it sits inside a hunk of the verified incremental block (the changes since the last reviewed commit), re-raises an earlier finding whose thread is still unresolved (the judge names that thread in `repeat_of`, or the finding sits on the path and line of an earlier round's thread that is still open — so a re-raise of an unanswered thread gates without a `repeat_of`), or is High/Critical anywhere in the reviewed diff. Every other finding is still posted, as a thread marked *Outside this round's changes: not blocking auto-approve*, and is never auto-resolved — it stays open for a human (and still counts for the `blocking` gate). Round 1, an incremental block that was unavailable or discarded, an empty one (a pure rebase, or no new-side hunk), one naming a path that cannot be parsed, an unknown prior-review ledger, and a list of earlier open threads that could not be read all fail closed to `full`; so does an explicitly empty value (only the input's own default picks `delta`). The decision note states the scope used, the gating vs non-gating counts, and why each gating finding gated. `full`: every finding counts wherever it sits (the behaviour before this input). The panel reviews the full diff either way. No effect without `approve_max_severity`. | | `defer_approval` | `false` | Only for a caller that runs [cursor-approve](cursor-approve.md) after this workflow: a round that would approve still reports `approve_gate` = `pass`, but posts **no** approval and resolves no thread, and withdraws the approver's own earlier auto-approvals and requests for changes instead — so cursor-approve's decide is the only approver. Requests changes as usual. No effect without `approve_max_severity`. | | `approve_max_failed_reviewers` | `0` | How many panel reviewers may **error** (the cell ran but failed, timed out, or never uploaded) before auto-approve withholds its decision. `0` keeps the strict rule: any reviewer that did not complete means no decision. `N` tolerates up to N errored reviewers and names them in the decision (e.g. "approved with 1/6 reviewers errored: `:edge-case`"). See [auto-approve](#auto-approve). No effect without `approve_max_severity`. | +| `rereview_command` | `''` (off) | A comment command, e.g. `/review`, that asks for ANOTHER round on the **same commit**. Empty leaves the same-commit dedupe absolute. Set the same value on [`cursor-review-auto-label.yml`](cursor-review-auto-label.md) — that half turns the comment into the label event, this half stops the dedupe from skipping the round it starts; setting only one is a silent no-op. Authorized = an `OWNER` / `MEMBER` / `COLLABORATOR` association on the comment. One request buys one round, and `max_rounds` still applies. See [below](#asking-for-another-round-on-the-same-commit). | | `max_rounds` | `5` | Cap on review rounds per PR (`0` → no cap). At or over it, no panel runs: the PR is labelled `needs-human-review`, one comment lists the latest round's open findings above the threshold, and the `approve_gate` output is `capped`. Removing the label resets the count. See [round cap](#round-cap-and-the-approve_gate-output). | | `runs_on` | `'"ubuntu-latest"'` | JSON-encoded `runs-on` for `diff-size`, `preflight`, the `review` panel and `consolidate` only — the jobs that hold no write credential. Every other job stays on GitHub-hosted `ubuntu-latest`. A self-hosted pool is fine only if it is one-job-per-fresh-pod, identity-free and private-network-isolated (those jobs run models with shell over PR code), on linux/x64 with bash, git, curl, jq, python3, gh, tar and GNU coreutils. Empty falls back to the default, so `${{ vars.CURSOR_REVIEW_RUNS_ON }}` is safe while the variable is unset; e.g. `'["self-hosted", "linux", "x64"]'`. | @@ -221,6 +222,80 @@ default and then drift from it. (`catalog-drift.py` also parses that default out of the workflow.) Overriding the judge is better done with a literal, or by changing the default in the reusable. +## Asking for another round on the same commit + +A round can end with no decision for a reason that has nothing to do with the +code — most often reviewer cells erroring, which `approve_max_failed_reviewers` +counts. The fix is to run it again, and until `rereview_command` there was no +way to: the dedupe keys on the consolidated review for the current HEAD SHA, +dismissing that review is impossible (it is `COMMENTED`), and the code is fine, +so there is nothing to push. + +Set the **same** command on both workflows: + +```yaml +# CI - Cursor Review +jobs: + cursor-review: + uses: Comfy-Org/github-workflows/.github/workflows/cursor-review.yml@ # v1 + with: + workflows_ref: + rereview_command: '/review' + +# CI - Cursor Review Auto-Label — add issue_comment to its triggers +on: + pull_request: + types: [assigned, opened, ready_for_review] + issue_comment: + types: [created] +jobs: + auto-label: + # Widen the canonical guard: `github.event.pull_request` is null on + # `issue_comment`, so the same-repo check alone skips every `/review`. + # (A comment event runs in the base repo with its secrets, fork PR or not; + # the reusable checks the commenter's association itself.) + if: >- + github.event_name == 'issue_comment' + || (github.event.pull_request.head.repo.full_name == github.repository + && github.actor != 'dependabot[bot]') + uses: Comfy-Org/github-workflows/.github/workflows/cursor-review-auto-label.yml@ # v1 + with: + rereview_command: '/review' +``` + +Then a maintainer comments `/review` and the next round runs. What that does, +precisely: + +- **auto-label** removes and re-adds the review label, which raises the + `labeled` event cursor-review triggers on. It removes first because adding a + label that is already present raises no event at all, and after a round the + label is always already present. +- **the gate** sees the prior review for this SHA, then looks for an authorized + command comment **newer than that review**. One request therefore buys exactly + one round: the round it starts posts a newer review, so the next run dedupes + again and a `/review` from three rounds ago can never re-fire. + +Details worth knowing: + +- The command must be the **first token of the first line**, so `/review please + look again` counts and `/reviewer` does not, and quoting someone else's + `/review` further down a comment does nothing. +- Authorization is the comment's own association, the bar `pr-derisk.yml` + applies to `/derisk`. The opted-in roster is not consulted — it governs who + gets labelled automatically, not who may ask for a re-read. +- Comments on plain issues are ignored, and `skip-cursor-review` still wins. +- `max_rounds` still caps completed rounds, but it bounds rather than prevents + repeat spending: each command cancels an in-flight panel through the + `trigger` slot, and a cancelled panel posts no review, so it is never counted. + `MEMBER` / `COLLABORATOR` also do not imply write access (a read-only + collaborator qualifies) — the same bar, and the same trade, as `/derisk`. +- Only a newly **created** comment counts; editing or deleting an old + `/review` does nothing. +- The value must be a single token with no whitespace (`/cursor review` can + never match); both workflows warn if it is not. +- Nothing from the comment reaches a log: a comment body is attacker-authored + text, and these logs may be public. + ## Gotchas **The label must be applied by a GitHub App token, not `GITHUB_TOKEN`.** Events @@ -272,9 +347,14 @@ remove the label, confirm it is gone, then re-add it. **One review per commit — re-labeling alone will not re-review.** The gate skips the panel if a non-dismissed consolidated review already exists for the PR's HEAD -SHA, so a remove-and-re-add on unchanged content no-ops by design. To get a fresh -review of the same commit, **dismiss the existing review first**, then apply the -label. +SHA, so a remove-and-re-add on unchanged content no-ops by design. + +**Dismissing that review is not actually an option, despite what this page used +to say here.** The consolidated review is posted `COMMENTED`, and GitHub only +dismisses `APPROVED` and `CHANGES_REQUESTED` reviews — so the one remedy this +page prescribed could never be carried out. Set +[`rereview_command`](#asking-for-another-round-on-the-same-commit) to get a +working one; without it, the only way to re-review is to push a commit. Pushing a commit clears the dedupe (new head SHA), but with the label-gated caller above it does **not** by itself start a run — `types: [labeled, unlabeled]` omits @@ -341,8 +421,9 @@ both pass it and you get two panels and two reviews. Keying on the PR number alone keeps every trigger in one group. Keep `labeled`/`unlabeled` in the list even in label-free mode: the label path -stays live alongside it, which is how you force a re-review on an unchanged commit -(dismiss the existing review, then apply the label — see the dedupe gotcha below). +stays live alongside it, and it is how a re-review on an unchanged commit arrives +(see [`rereview_command`](#asking-for-another-round-on-the-same-commit); the +dedupe gotcha below explains why dismissing the review is not the answer). **The reusable owns a group of its own — it ADDS to your caller group, it does not replace it.** `cursor-review.yml` declares a workflow-level `concurrency: cursor-review-reusable--` with `cancel-in-progress: true`, which reaches you at your next pin bump with no caller edit and no permission change. Its slot rule: the trigger label and `skip-cursor-review` share one `trigger` slot, so **applying `skip-cursor-review` mid-panel cancels the running panel**; every other label gets its own `label-` slot, so an unrelated label add never kills a running review; `pull_request_review_thread` events stay out of `trigger`, so resolving a finding thread on a blocking caller cannot cancel a panel; and under `run_without_label: true` the four plain PR actions the gate accepts (`opened` / `reopened` / `ready_for_review` / `synchronize`) join `trigger` as well, so a push supersedes a running panel and the veto label can still reach it.