Skip to content

Commit d492b6a

Browse files
mattmilleraiclaude
andcommitted
feat(cursor-review): approve_scope — gate auto-approve rounds 2+ on the delta since the last reviewed commit
Rounds after the first count a finding above approve_max_severity only when it sits inside the verified incremental block, re-raises an unresolved earlier thread, or is High/Critical anywhere. Other findings post as threads marked non-blocking and are never auto-resolved. Round 1, an unavailable or discarded block, and an unknown ledger fail closed to full; full keeps today's gate. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
1 parent 010a255 commit d492b6a

7 files changed

Lines changed: 494 additions & 17 deletions

File tree

‎.github/cursor-review/README.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -287,6 +287,7 @@ All optional except `workflows_ref` (required, no default) — pass them under
287287
| `run_without_label` | `false` | Run on plain PR events instead of requiring the trigger label. Also requires widening the caller's `types:` — see [the setup guide](../../docs/callers/cursor-review.md). |
288288
| `blocking` | `false` | Adds the fail-closed **Blocking gate** check: red while any cursor-review finding thread is unresolved and non-outdated, and red when the round that should have produced those threads did not land (including an over-cap skip). Blocking the merge additionally requires marking that check required in the caller's ruleset — see [the blocking section above](#optional-make-the-review-blocking). |
289289
| `approve_max_severity` | `''` (off) | Opt-in auto-approve: `medium`, `low` or `nit` → the bot approves (pinned to the reviewed commit) when every finding is at or below it and requests changes when any is above; anything else fails the run. Read the trust model in [the setup guide](../../docs/callers/cursor-review.md#auto-approve) first — the approval is no stronger than push access. |
290+
| `approve_scope` | `delta` | Rounds 2+ of auto-approve gate only on findings inside the verified incremental block, live re-raises of unresolved threads, 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 block, or an unknown ledger. |
290291
| `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. |
291292
| `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). |
292293
| `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. |

‎.github/cursor-review/auto-approve.py‎

Lines changed: 223 additions & 13 deletions
Original file line numberDiff line numberDiff line change
@@ -216,6 +216,138 @@ def _load_post_review():
216216
return _load_sibling("post-review.py", "post_review")
217217

218218

219+
def _load_incremental_diff():
220+
"""incremental-diff.py, for the same section parser its `check` uses."""
221+
return _load_sibling("incremental-diff.py", "incremental_diff")
222+
223+
224+
# --- approve_scope (rounds 2+ gate on the delta since the last reviewed commit) ---
225+
#
226+
# On a round after the first, a finding above the threshold counts toward the
227+
# gate under `delta` only when it is IN the verified incremental block (its path
228+
# and line fall inside one of that block's new-side hunks), a LIVE REPEAT (its
229+
# `repeat_of` names an earlier thread the ledger reads as unresolved), or SEVERE
230+
# (High/Critical, or a severity nobody recognises) anywhere in the reviewed diff.
231+
# Everything else is still posted, as a thread carrying NON_GATING_MARKER, but
232+
# does not block — and that thread is never auto-resolved, so it stays for a human.
233+
#
234+
# The scope is resolved FAIL-CLOSED: anything short of a verified block and a
235+
# readable ledger runs the round as `full`, exactly as before the input existed.
236+
ALLOWED_SCOPES = ("delta", "full")
237+
SCOPE_DELTA = "delta"
238+
SCOPE_FULL = "full"
239+
# diff-size's `incremental_state`: `none` (no usable last-reviewed SHA — round 1,
240+
# or a re-run on the same head), `built` (verified; may be EMPTY on a pure
241+
# rebase), `unavailable` (a later round whose block could not be built), and
242+
# `discarded` (built, then thrown away by the subset fail-safe).
243+
INCREMENTAL_NONE = "none"
244+
INCREMENTAL_BUILT = "built"
245+
SEVERE = ("critical", "high")
246+
# Hard-coded by post-review.py into a non-gating thread's body, AFTER the model's
247+
# text, which is stripped of this marker first — so a finding cannot exempt
248+
# itself by echoing it. Read back by the open-thread check and auto-resolve.
249+
NON_GATING_MARKER = "<!-- cursor-review-non-gating -->"
250+
NON_GATING_NOTE = "_Outside this round's changes: not blocking auto-approve._"
251+
HUNK_RE = re.compile(r"^@@ -\d+(?:,\d+)? \+(\d+)(?:,(\d+))? @@")
252+
253+
254+
def validate_scope(value: str) -> str:
255+
scope = (value or SCOPE_DELTA).strip().lower()
256+
if scope not in ALLOWED_SCOPES:
257+
raise ValueError(f"approve_scope must be one of {', '.join(ALLOWED_SCOPES)}, got {value!r}")
258+
return scope
259+
260+
261+
def hunk_ranges(patch_text: str) -> dict:
262+
"""{path: [(first, last), ...]} of every new-side hunk in a unified diff."""
263+
inc = _load_incremental_diff()
264+
ranges = {}
265+
for header, lines in inc.split_sections(patch_text or ""):
266+
paths = inc.section_paths(header, lines)
267+
if not paths:
268+
continue
269+
for line in lines:
270+
m = HUNK_RE.match(line)
271+
if m:
272+
start, count = int(m.group(1)), int(m.group(2) if m.group(2) is not None else 1)
273+
if count > 0:
274+
ranges.setdefault(paths[1], []).append((start, start + count - 1))
275+
return ranges
276+
277+
278+
def live_thread_urls(ledger) -> frozenset:
279+
"""Thread URLs of every earlier finding the ledger reads as still unresolved."""
280+
out = set()
281+
for entry in (ledger or {}).get("entries") or []:
282+
if not isinstance(entry, dict) or not entry.get("anchored", True):
283+
continue
284+
thread = entry.get("thread") or {}
285+
url = entry.get("discussion_url")
286+
if isinstance(url, str) and url and not thread.get("resolved"):
287+
out.add(url.strip())
288+
return frozenset(out)
289+
290+
291+
def resolve_scope(requested: str, incremental_state: str, incremental_text, ledger) -> dict:
292+
"""The scope this round actually gates on. Pure; fails closed to `full`.
293+
294+
Returns {"scope", "note", "ranges", "live"}: `note` says why a `delta`
295+
request ran as `full` (empty when it did not).
296+
"""
297+
full = {"scope": SCOPE_FULL, "note": "", "ranges": {}, "live": frozenset()}
298+
if requested != SCOPE_DELTA:
299+
return full
300+
state = (incremental_state or "").strip().lower()
301+
if state == INCREMENTAL_NONE:
302+
return {**full, "note": "first round (no usable last-reviewed commit), so the whole diff counts"}
303+
if state != INCREMENTAL_BUILT:
304+
return {**full, "note": f"the incremental block is {state or 'unavailable'}, so the round fails closed to `full`"}
305+
if incremental_text is None:
306+
return {**full, "note": "the incremental block could not be read, so the round fails closed to `full`"}
307+
status = (ledger or {}).get("status") if isinstance(ledger, dict) else None
308+
if status not in ("ok", "empty"):
309+
return {**full, "note": f"the prior-review ledger is {status or 'unknown'}, so the round fails closed to `full`"}
310+
return {"scope": SCOPE_DELTA, "note": "", "ranges": hunk_ranges(incremental_text), "live": live_thread_urls(ledger)}
311+
312+
313+
def gating_reason(finding, scope: dict):
314+
"""Why `finding` counts toward the gate, or None when it does not. Pure."""
315+
if not isinstance(finding, dict):
316+
return "malformed finding"
317+
if (scope or {}).get("scope") != SCOPE_DELTA:
318+
return "full scope"
319+
sev = finding.get("severity")
320+
sev = sev.strip().lower() if isinstance(sev, str) else ""
321+
if sev not in SEVERITY_ORDER:
322+
return "unrecognised severity"
323+
if sev in SEVERE:
324+
return f"{sev} anywhere in the diff"
325+
repeat = finding.get("repeat_of")
326+
if isinstance(repeat, str) and repeat.strip() in scope.get("live", ()):
327+
return "re-raise of an unresolved earlier finding"
328+
line = finding.get("line")
329+
try:
330+
line = int(line)
331+
except (TypeError, ValueError):
332+
return "no usable line anchor"
333+
path = finding.get("file")
334+
for first, last in scope.get("ranges", {}).get(path, ()) if isinstance(path, str) else ():
335+
if first <= line <= last:
336+
return "inside this round's changes"
337+
return None
338+
339+
340+
def non_gating(finding, threshold: str, scope: dict) -> bool:
341+
"""True for an above-threshold finding the delta scope does not count."""
342+
return (isinstance(finding, dict) and above_threshold(finding.get("severity"), threshold)
343+
and gating_reason(finding, scope) is None)
344+
345+
346+
def is_non_gating_thread(body: str) -> bool:
347+
"""A thread post-review.py marked non-gating (the marker on its own line)."""
348+
return NON_GATING_MARKER in (body or "").splitlines()
349+
350+
219351
def validate_threshold(value: str) -> str:
220352
threshold = (value or "").strip().lower()
221353
if threshold not in ALLOWED_THRESHOLDS:
@@ -254,6 +386,7 @@ def decide(
254386
reviewed_base: str = "",
255387
live_base: str = "",
256388
human_review: bool = False,
389+
scope=None,
257390
):
258391
"""Return (event, reasons, blocking_findings). Pure; no I/O.
259392
@@ -264,7 +397,7 @@ def decide(
264397
event, _, reasons, blocking = decide_gate(
265398
threshold, findings, panel, judge_status, delivered, reviewed_sha,
266399
live_head_sha, open_thread_severities, ungated, human_review,
267-
reviewed_diff_empty, reviewed_base, live_base,
400+
reviewed_diff_empty, reviewed_base, live_base, scope,
268401
)
269402
return event, reasons, blocking
270403

@@ -283,8 +416,17 @@ def decide_gate(
283416
reviewed_diff_empty: bool = False,
284417
reviewed_base: str = "",
285418
live_base: str = "",
419+
scope=None,
286420
):
287-
"""decide(), plus the approve_gate value: (event, gate, reasons, blocking)."""
421+
"""decide(), plus the approve_gate value: (event, gate, reasons, blocking).
422+
423+
`scope` is resolve_scope()'s result; None (every existing caller) is `full`.
424+
Under `delta`, an above-threshold finding blocks only if gating_reason()
425+
gives one, and an open thread post-review.py marked non-gating does not
426+
block either. A `full` round counts both, exactly as before.
427+
"""
428+
noted = scope is not None
429+
scope = scope or {"scope": SCOPE_FULL}
288430
if human_review:
289431
# Before the trust checks: a PR handed to a human is never approved,
290432
# whatever this round found. NONE also withdraws an earlier approval.
@@ -311,20 +453,45 @@ def decide_gate(
311453
if reasons:
312454
return NONE, GATE_UNTRUSTED, reasons, []
313455

314-
blocking = [
456+
above = [
315457
f for f in findings if not isinstance(f, dict) or above_threshold(f.get("severity"), threshold)
316458
]
459+
blocking = [f for f in above if gating_reason(f, scope) is not None]
460+
# The note rides as a second reason only for a caller that resolved a scope,
461+
# so reasons[0] — what every review body and log line leads with — is unchanged.
462+
note = [scope_note(scope, len(blocking), len(above) - len(blocking), blocking)] if noted else []
317463
if blocking:
318-
return REQUEST_CHANGES, GATE_FAIL, [f"{len(blocking)} finding(s) above `{threshold}`"], blocking
464+
return REQUEST_CHANGES, GATE_FAIL, [f"{len(blocking)} finding(s) above `{threshold}`", *note], blocking
319465

320466
# Same line as this round's findings, so a Medium thread from an earlier round
321467
# blocks a `low` threshold exactly as a Medium finding this round would.
322-
open_blocking = [
323-
s for s in open_thread_severities if s is None or above_threshold(s, threshold)
324-
]
468+
# Entries are a severity (legacy callers) or (severity, non_gating).
469+
delta = scope.get("scope") == SCOPE_DELTA
470+
open_blocking = []
471+
for entry in open_thread_severities:
472+
sev, marked = entry if isinstance(entry, tuple) else (entry, False)
473+
if (sev is None or above_threshold(sev, threshold)) and not (delta and marked):
474+
open_blocking.append(sev)
325475
if open_blocking:
326-
return NONE, GATE_FAIL, [f"{len(open_blocking)} open thread(s) above `{threshold}` (or unbadged) from an earlier round"], []
327-
return APPROVE, GATE_PASS, [f"every finding is at or below `{threshold}`"], []
476+
return NONE, GATE_FAIL, [f"{len(open_blocking)} open thread(s) above `{threshold}` (or unbadged) from an earlier round", *note], []
477+
if above:
478+
return APPROVE, GATE_PASS, [f"every finding inside this round's changes is at or below `{threshold}`", *note], []
479+
return APPROVE, GATE_PASS, [f"every finding is at or below `{threshold}`", *note], []
480+
481+
482+
def scope_note(scope: dict, gating: int, non_gating_count: int, blocking: list) -> str:
483+
"""The decision note's scope line: which scope, how many gated, and why."""
484+
scope = scope or {}
485+
text = f"approve_scope `{scope.get('scope') or SCOPE_FULL}`: {gating} gating, {non_gating_count} non-gating finding(s) above the threshold"
486+
if scope.get("note"):
487+
text += f" ({scope['note']})"
488+
if scope.get("scope") == SCOPE_DELTA and blocking:
489+
why = {}
490+
for f in blocking:
491+
reason = gating_reason(f, scope)
492+
why[reason] = why.get(reason, 0) + 1
493+
text += "; gating because: " + ", ".join(f"{n}× {r}" for r, n in why.items())
494+
return text
328495

329496

330497
def reviewed_diff_is_empty(path: str) -> bool:
@@ -450,7 +617,7 @@ def set_output(key: str, value) -> None:
450617

451618

452619
def open_thread_severities(repo: str, pr: int) -> list:
453-
"""Severities of every open (unresolved, non-outdated) cursor-review thread.
620+
"""(severity, non_gating) of every open (unresolved, non-outdated) cursor-review thread.
454621
455622
This round's own threads are included on purpose: decide() only reaches the
456623
thread check when every finding of this round is at or below the threshold
@@ -466,7 +633,8 @@ def open_thread_severities(repo: str, pr: int) -> list:
466633
if thread.get("isResolved") or thread.get("isOutdated"):
467634
continue
468635
first = ((thread.get("comments") or {}).get("nodes") or [{}])[0]
469-
out.append(thread_severity(first.get("body") or ""))
636+
body = first.get("body") or ""
637+
out.append((thread_severity(body), is_non_gating_thread(body)))
470638
return out
471639

472640

@@ -581,8 +749,12 @@ def plan_thread_resolution(threads: list, poster_login: str, threshold: str):
581749
for thread in threads:
582750
if gate.is_cursor_thread(thread) and not thread.get("isResolved") and not thread.get("isOutdated"):
583751
first = ((thread.get("comments") or {}).get("nodes") or [{}])[0]
584-
live = thread_severity(first.get("body") or "")
585-
if live is None or above_threshold(live, threshold):
752+
body = first.get("body") or ""
753+
live = thread_severity(body)
754+
# A thread a delta-scoped round marked non-gating did not hold the
755+
# approval back, so it does not hold the others' resolution back
756+
# either. It is never resolved itself (SKIP_ABOVE below).
757+
if (live is None or above_threshold(live, threshold)) and not is_non_gating_thread(body):
586758
blocked = True
587759
verdict, severity = classify_thread(thread, poster_login, threshold, gate)
588760
if verdict == NOT_OURS:
@@ -711,6 +883,8 @@ def render_body(event: str, reasons: list, threshold: str, blocking: list, revie
711883
line = str(line) if isinstance(line, int) and not isinstance(line, bool) else "?"
712884
path = f.get("file") if isinstance(f.get("file"), str) else "?"
713885
lines.append(f"- **{sev}** — {render_code_ref(path[:300], line)}")
886+
if len(reasons) > 1:
887+
lines.append(f"\n_Scope: {reasons[-1]}._")
714888
lines.append(f"\n_Threshold: `{threshold}` (set by this repo's `approve_max_severity`)._")
715889
return "\n".join(lines)
716890

@@ -732,6 +906,14 @@ def cmd_decide(args) -> int:
732906
ungated = int(args.ungated or 0)
733907
except ValueError:
734908
ungated = 1 # unparseable → assume something missed a thread
909+
try:
910+
requested_scope = validate_scope(getattr(args, "approve_scope", "") or "")
911+
except ValueError as e:
912+
print(f"::error::{e}")
913+
return 2
914+
scope = resolve_scope(requested_scope, getattr(args, "incremental_state", "") or "",
915+
_read_optional(getattr(args, "incremental", "") or ""),
916+
_read_json_optional(getattr(args, "ledger", "") or ""))
735917

736918
try:
737919
pr = read_pr(args.repo, args.pr_number)
@@ -756,8 +938,11 @@ def cmd_decide(args) -> int:
756938
reviewed_diff_is_empty(args.reviewed_diff),
757939
args.base_ref,
758940
live_base,
941+
scope,
759942
)
760943
set_output("approve_gate", gate)
944+
if len(reasons) > 1:
945+
emit(f"ℹ️ **Auto-approve scope** — {reasons[-1]}.")
761946
if event == NONE:
762947
emit(f"ℹ️ **Auto-approve: no decision** — {'; '.join(reasons)}.")
763948
return withdraw_own_approvals(args)
@@ -842,6 +1027,27 @@ def cmd_decide(args) -> int:
8421027
return 0
8431028

8441029

1030+
def _read_optional(path: str):
1031+
"""A text file's contents, or None when no path was given or it cannot be read."""
1032+
if not path:
1033+
return None
1034+
try:
1035+
with open(path, encoding="utf-8", errors="surrogateescape", newline="") as f:
1036+
return f.read()
1037+
except OSError:
1038+
return None
1039+
1040+
1041+
def _read_json_optional(path: str):
1042+
"""A JSON object from `path`, or None (missing, unreadable, or not an object)."""
1043+
text = _read_optional(path)
1044+
try:
1045+
data = json.loads(text) if text is not None else None
1046+
except ValueError:
1047+
return None
1048+
return data if isinstance(data, dict) else None
1049+
1050+
8451051
def defer_to_cursor_approve(args, reason: str) -> int:
8461052
"""`--defer-approval true` on an APPROVE outcome: post nothing, keep the gate.
8471053
@@ -1807,6 +2013,10 @@ def main() -> int:
18072013
d.add_argument("--poster-login", default="")
18082014
# `true` = report the gate but never post an APPROVE (see the docstring).
18092015
d.add_argument("--defer-approval", default="")
2016+
d.add_argument("--approve-scope", default=SCOPE_FULL)
2017+
d.add_argument("--incremental", default="")
2018+
d.add_argument("--incremental-state", default="")
2019+
d.add_argument("--ledger", default="")
18102020
s = sub.add_parser("dismiss-stale")
18112021
s.add_argument("--repo", required=True)
18122022
s.add_argument("--pr-number", required=True)

0 commit comments

Comments
 (0)