@feigi/fleet-ctl 3.139.1 → 3.141.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/commands/review-and-fix.md +1 -1
- package/commands/run-merge-bot.md +10 -17
- package/package.json +1 -1
- package/scripts/dispositions-check.mjs +166 -27
- package/scripts/finisher-label.mjs +3 -7
- package/scripts/labelled-head.mjs +189 -0
- package/scripts/ledger-grammar.mjs +44 -10
- package/scripts/ledger.mjs +6 -3
- package/scripts/ready-to-merge-head.mjs +29 -0
- package/skills/run-team/SKILL.md +11 -11
- package/skills/run-team/references/dispositions-escalation.md +36 -0
|
@@ -17,7 +17,7 @@ Label names in this file are roles; the Label map gives the string to type; a me
|
|
|
17
17
|
|
|
18
18
|
See **Specialists** — those constraints are not optional.
|
|
19
19
|
2. Plan the actions. Split explicitly into **apply now** / **defer**. A finding is deferred, never dropped. **Every `suggestion` — the review's `severity`, the plugin's *Suggestions* bucket — arrives unchecked: the review budgets that band 0 refuters, so nothing has looked at it yet.** Checking it is now your job, not nobody's. So split it by SCOPE first, and check it in either scope. Out of the PR's ticket scope → defer and file, but **the claim bar runs first:** a suggestion whose claim is about shape — step 5's worth-a-claim bar, recorded `claimKind: shape` — gets no refuter and goes to the `PR #<pr> review: the suggestion band, checked` record, and every other out-of-scope suggestion gets the same refuter an in-scope one does, dispatched the same way, before it is filed. In scope → dispatch one refuter against it, biased to refuse, and hand it this instruction verbatim with one substitution: resolve `<scratch>/pr<N>/<finding>/` in it to an absolute path under your own run root — `mktemp -d` once per round for `<scratch>/pr<N>/fix-XXXXXXXX/`, never bare `pr<N>`, since finding ids restart at 1 each round too — and write that absolute path into the refuter's prompt in its place; a refuter never derives its own path, and tell it your step-3 `testCmd`, which its rules call `<testCmd>`: *Try to REFUTE this finding. Default to refuted=true if uncertain. Verify by RUNNING something — compile it, run the test, apply the mutation. Do not reason your way to agreement. Observe that run synchronously — run the command, wait for it, read its exit code. Never poll a log file for a completion marker: prefer ONE blocking run to a poll loop, and treat its return as permission to look, never as the answer. Reading a log the run has already finished writing is fine; waiting on one is not. If you match a test reporter's own output, accepting both `ℹ` and `#` is necessary but NOT sufficient — strip SGR escapes first as well. node's prefix moves with the node version and with whether stdout is a TTY, and color wraps the whole line so it begins with ESC and no prefix anchor matches at all, which returns empty at exit 0 — indistinguishable from a hung run and from a run of zero tests. For an uncolored baseline use `env -u FORCE_COLOR`; `FORCE_COLOR=` empty still enables color, so it is not a control. State your search scope AND what your pattern would have missed. A grep over one ref does not support a claim about history; a pattern built from the token a diff removed does not support a claim that the category is empty. When your check scores a mutant killed or a test red, run only in your own copy of the tree, and these rules decide it and nothing else: Valid red: a run that completed — the command returned on its own, with no signal and no timeout, deadline or kill having fired — in which the test the claim names is reported failing. An exit ≠ 0 with no failing test is not red, and a different test failing is not red for this claim. A red in the full suite only triggers a narrowed run; it is never evidence on its own. Narrowed run: the Test entrypoint with arguments appended, `<testCmd> <args>`. That appended arguments reach the Test entrypoint is all that is promised about them, so a narrowed run counts only if it reports `tests` > 0 and its output names the claimed test. If no narrowing can be proven, run the full `<testCmd>` and read the named test's own result from its output. Kill: the mutant produced a valid red in a narrowed run, and the same narrowed command, in the same tree with the mutant reverted, ran a valid green with the named test passing — completed, exit 0, `tests` > 0, `cancelled` 0. A completed exit ≠ 0 with the named test not failing is not a kill, and no kill stands without that green run on the unmutated tree. The result is inconclusive, never a kill, when the red does not reproduce in the narrowed run, when the unmutated tree is red too, or when no usable run exists. Evidence line: every kill and every valid red you claim carries one line in the claim's own free-text field: `red: <cmd> → exit N, fail K incl <test>; baseline: <cmd> → exit 0, <test> pass`. A failing-test finding filed off the review's shared run carries the `red:` half alone. This refuter has no abstain: a run that could not decide — neither a valid red nor a valid green — is no kill and no refutation, so name the runs in `reason`, each with its evidence line, and leave `refuted` true, so the suggestion defers on the record instead of applying on a check that decided nothing. A failure injection with no positive control has produced NO result, never a negative one. Before you read an injected fault — an env var, an argv word, a mutant — as having had no effect, prove the injection reached the child: one run whose output differs with it present versus absent, or the child echoing the injected value back. Uncontrolled, the cell is unrun — say so in your verdict instead of reporting a no-effect result. Build such an invocation as an array expanded braced and quoted — `cfg=(SETB=1 BADJ=1); env "${cfg[@]}" sh ./probe.sh` — or inline the assignments literally — `env SETB=1 BADJ=1 sh ./probe.sh`; NEVER from an unquoted scalar — `cfg="SETB=1 BADJ=1"; env $cfg sh ./probe.sh` — which under zsh passes ONE argument, sets a variable literally named `SETB` to `1 BADJ=1`, never sets `BADJ` at all, and still exits 0. `env $cfg[@]` is not the portable spelling either: measured, bash word-splits it into `SETB=1` and `BADJ=1[@]`, so the injection variable is set to a corrupted value, while zsh behaves exactly as with the bare `$cfg` — `BADJ` never set, exit 0. Everything you write — mutants, fixtures, scratch repos — goes under `<scratch>/pr<N>/<finding>/` and nowhere else; the checkout and any worktree are never write targets, though `git show`/`git archive` at a pinned ref read fine anywhere. Chain the directory change into the command, `cd "$D" && git …`, never `cd "$D"; git …`, so a failed `cd` cannot leave a `git` command running in the checkout — and bracket a fixture's own git with `git rev-parse --show-toplevel`: before `git init` it must NOT resolve to the host repository, and `fatal: not a git repository` (exit 128) is the usual pass, not a failure — an outer repository whose ignore rules cover your scratch dir is a pass too; before any `git commit` it must resolve to your scratch path, which catches a forgotten `git init` under any enclosing repository — compare resolved forms (`realpath`), since `--show-toplevel` can report a symlinked parent such as `/tmp` or a symlinked `$HOME` under its resolved name.* That last clause is the whole mechanism — a refuter left to reason its way to agreement rubber-stamps, and "apply only what survives" silently degrades into "apply everything in scope". Apply only what survives; a refuted one defers with the refutation in its body. **Out of scope the refuter decides only where the suggestion is filed — it defers either way, never applied.** Refuted → the `PR #<pr> review: the suggestion band, checked` record, never an open issue. Survived, or its refuter crashed or abstained → its own open issue labelled `needs-triage`, citing the verdict, or the run that crashed, in the body. There is no cap on these refuters; your final verdict (step 4) says how many you dispatched against out-of-scope suggestions. "In scope" means the ticket's scope, not merely the same files — and applying one still never licenses editing a file the ticket has no business in. **A finding in `unverified` whose refuters ran and crashed or abstained always defers, whatever its severity** — and which it is, you read off the finding's **`refutersDispatched`** and **`refutersInconclusive`**, never off severity and never off an empty vote list: `refutersDispatched` above zero with nothing decided means every refuter dispatched against it died or abstained, and `refutersInconclusive` counts the ones that abstained. Only a `survived` finding has been checked; severity says how much a finding would matter if true, never whether anything looked. **Deferring a crash is your move, and re-running it is not** — the review already re-dispatched every crashed refuter pair once, in-run, so a crash that reaches you crashed twice, and the result's `resume` field names the one move left, which is not yours: nothing replays a review that ran in a runner's kernel — it is reported, not acted on. So say *in the deferral* that its refuters crashed rather than that it went unchecked, and re-run nothing for it. **An abstention is not a crash** — a refuter that abstained ran and could not decide: defer and file the finding, citing the inconclusive runs each abstaining refuter named in its `reason`, and never describe its refuters as crashed. **A `suggestion` is also in `unverified`, for a different reason — `refutersDispatched` of zero, the 0-refuter budget the workflow gives that band by policy, so nothing looked *there* — and the scope split above, not this rule, covers it.**
|
|
20
|
-
**Write every ruling to `<scratch>/dispositions-<your name>.json`, `<your name>` the `fix-pr-<pr>[-x]` you were dispatched as (standalone, `fix-pr-<pr>`) — the disposition record `dispositions-check.mjs` judges against the review result file before any finisher is dispatched.** It is `{"head": "<the review file's head>", "run": "<the run root's name in the review path>", "entries": [ … ]}` — `run` the `<run>` of the review path your prompt names, which the check holds against the one the PR's latest `reviewed=` names, so a record written against an earlier review of the same PR, a same-head one included, is a mismatch (standalone, with no ledger naming a run, leave it out): one entry per `survived` finding and per `unverified` finding, plus one per `refuted` finding you reverse. Each entry carries `bucket` (`survived|unverified|refuted`), `index` (its position in that bucket of the review file — stable, since a round's file never changes), `scope` (`in|out`), `claimKind` (`behavior|shape`) and `disposition` (`apply|defer`), and where they apply `reason`, `issue` (the number you filed it to or commented on), `verdictPath` (a suggestion's refuter verdict file, in scope and, above the claim bar, out of scope) and `remedyFiles` (the files its remedy names). A `refuted` entry carries `scope`, `claimKind` and `disposition` like every other entry, and a non-empty `reason` holding the evidence that reverses it; a missing or blank `reason` is a mismatch. The check reads scope off the diff before it reads your entry: a finding with no `line`, or on a line `git diff` touches from the PR's merge-base with `origin/main` to the review's `head`, is in scope whatever `scope` says, and only otherwise does the declared one stand. An in-scope `survived` finding deferred passes only with `reason` `false-rationale`, `mutual-exclusion`, `remedy-worse` or `remedy-outside-diff`. `remedy-outside-diff` — the remedy would edit a file the PR's diff does not touch — also needs `remedyFiles` to name at least one file absent from `git diff` from that merge-base to the review's `head`: none named, or every one in that diff, is a mismatch. A `critical` or `important` finding deferred for it goes to
|
|
20
|
+
**Write every ruling to `<scratch>/dispositions-<your name>.json`, `<your name>` the `fix-pr-<pr>[-x]` you were dispatched as (standalone, `fix-pr-<pr>`) — the disposition record `dispositions-check.mjs` judges against the review result file before any finisher is dispatched.** It is `{"head": "<the review file's head>", "run": "<the run root's name in the review path>", "entries": [ … ]}` — `run` the `<run>` of the review path your prompt names, which the check holds against the one the PR's latest `reviewed=` names, so a record written against an earlier review of the same PR, a same-head one included, is a mismatch (standalone, with no ledger naming a run, leave it out): one entry per `survived` finding and per `unverified` finding, plus one per `refuted` finding you reverse. Each entry carries `bucket` (`survived|unverified|refuted`), `index` (its position in that bucket of the review file — stable, since a round's file never changes), `scope` (`in|out`), `claimKind` (`behavior|shape`) and `disposition` (`apply|defer`), and where they apply `reason`, `issue` (the number you filed it to or commented on), `verdictPath` (a suggestion's refuter verdict file, in scope and, above the claim bar, out of scope) and `remedyFiles` (the files its remedy names). A `refuted` entry carries `scope`, `claimKind` and `disposition` like every other entry, and a non-empty `reason` holding the evidence that reverses it; a missing or blank `reason` is a mismatch. The check reads scope off the diff before it reads your entry: a finding with no `line`, or on a line `git diff` touches from the PR's merge-base with `origin/main` to the review's `head`, is in scope whatever `scope` says, and only otherwise does the declared one stand. An in-scope `survived` finding deferred passes only with `reason` `false-rationale`, `mutual-exclusion`, `remedy-worse` or `remedy-outside-diff`. `remedy-outside-diff` — the remedy would edit a file the PR's diff does not touch — also needs `remedyFiles` to name at least one file absent from `git diff` from that merge-base to the review's `head`: none named, or every one in that diff, is a mismatch. A `critical` or `important` finding deferred for it goes to the maintainer instead of passing: the script exits 1 with verdict `escalate`, `ledger.mjs dispatch` refuses the PR's finisher until answered; a `suggestion` deferred for it passes. Any other reason, none, or a `survived` or `unverified` finding with no entry is a mismatch: the script exits 1 naming each violating entry's bucket, index and rule, and `ledger.mjs dispatch` refuses the PR's finisher. `disposition` has no `dismiss`: an in-scope `survived` finding verified correct, needing no change, is deferred with `reason` `false-rationale` and filed on the suggestion-band record — step 5's `PR #<pr> review: the suggestion band, checked`.
|
|
21
21
|
**Give every entry whose finding stands a Charge:** `charge` — `false-claim`, `unmet`, `both` or `none` — and, with `none` only, a `chargeReason`: `defect-outside-acceptance` (a defect outside the ticket's acceptance criteria, which no text the implementer wrote claims is otherwise), `not-the-implementers-text` (the false text predates the PR, or comes from the ticket) or `claim-about-untouched-code` (a claim about code the change does not touch). A `survived` finding not deferred `false-rationale` stands, and so does every `refuted` one you reverse; an `unverified` one never does. Charge the work as submitted — a finding you apply is charged as if it were still there — by the definitions of `closed_own_ticket` and `minted_false_claim` in the header of `docs/metrics/tier-outcomes.tsv`, against the ticket as its implementer was dispatched with it; an entry scoped `out` is charged `none`. The check requires a Charge on every standing entry of the record answering the PR's first review — the first that counted no survived and no unverified finding, or else the first a fix-applier answered — and a record answering a later review, or one checked with no ledger, needs none. Wherever a `charge` or `chargeReason` appears it is judged: an unknown value, `none` with no `chargeReason`, a `chargeReason` with any other `charge` or with none, and an out-of-scope entry charged anything but `none` are each a mismatch.
|
|
22
22
|
3. **Run `checkCmd` and `testCmd` before you commit**, from the worktree, each copied verbatim — not a runner you picked. `checkCmd` is the Recipe's Check step and `testCmd` is the command your dispatcher handed you; **standalone, with no dispatcher to hand you them, they are the repo's own Check step and Test entrypoint**, read off the repo's Recipe cache (`derive-testcmd.sh <repo> check` prints the first, `derive-testcmd.sh <repo> test` the second). Read them off the repo, never invent one: "not a runner you picked" is what this step forbids, and on the standalone path nothing else defines the referent. With no usable Recipe cache (`derive-testcmd.sh` refuses), run the Recipe derivation step first — dispatch a `task` member, agent `fleet-recipe-deriver`, its prompt naming the main checkout's absolute path as `<repo>` and a scratch directory of its own; it proves all three commands in a throwaway worktree and writes the cache only on proof, and its `RECIPE NOT PROVEN` is a stop, reported with its reason. Never fall back to a runner of your own choosing. `tests 0` is a FAILED run, not a pass: a glob matching nothing still exits 0. **Zero is not the only no-work count.** A run reporting **0 passes with no failures** skipped everything it collected, and a count **materially below the whole suite** means you ran a partial tree — this suite reported `tests 937` when this line was written, so compare what you get against a full run rather than against zero. The number drifts; that is the safe direction, because a stale one produces a loud false red while its absence produces a silent false green. Red, zero-test, or either no-work count → fix it or move the finding to defer; never commit over it. Then commit and push — `~/.omp/plugins/node_modules/@feigi/fleet-ctl/scripts/fleet-run push-sync.mjs --branch <branch>`, which pushes the explicit refspec `HEAD:refs/heads/<branch>` and then moves the worktree holding `<branch>` to the pushed SHA, or names why it did not and exits 3 with the push landed: this step also runs from a `--detach` worktree (`run-team/SKILL.md`'s worktree-recreation form), where a bare `git push` exits 128 (`fatal: You are not currently on a branch`), any push whose destination is `HEAD` rather than a full or branch refname (`-u` or not, forced or not) exits 1 (`error: The destination you provided is not a full refname`), and a refspec push alone leaves the claim worktree's `refs/heads/<branch>` at its old tip — and report the test result alongside the SHA. **Then reconcile the PR body with what you actually did.** It merges into the permanent record and nothing downstream re-derives it: your commit messages are yours to fix and usually get fixed, the body is neither. Removing a change, or reversing one, leaves the body asserting work the diff no longer contains. Seen twice in one run, and caught only by a finisher's reading. `gh pr edit <pr> --body-file <path>`, and re-read the body against the final diff rather than against your memory of it. **Never `--no-verify` on a commit you push, or on the push itself.** The fleet runs in repos it knows nothing about: it must not assume a pre-commit hook exists, and must never bypass one that does on what reaches the branch — a hook that fails is a finding to report, not an obstacle. Nothing re-reviews what you commit here, so this run is the only gate between your edit and a merge.
|
|
23
23
|
**Under the fleet, run the two through `recipe-check.mjs`, not one by one:** from the worktree, after `git add` and before the commit, `~/.omp/plugins/node_modules/@feigi/fleet-ctl/scripts/fleet-run recipe-check.mjs --member <your name> --testCmd "<testCmd>" --reports <scratch>/reports` — `<your name>` the `fix-pr-<pr>[-x]` you were dispatched as, and `<testCmd>` the whole command you were handed, one quoted argument. It runs the Recipe's Check step, which is `checkCmd`, then `<testCmd>` exactly as handed, against the staged tree, and records both results beside your report. The record is keyed to the tree, so run it again after any content change or rebase — a message-only amend keeps it valid — and the controller refuses an `applied` report whose head's tree has no green record. After the commit, and before you push or report, compare `git rev-parse 'HEAD^{tree}'` with the `tree` field of your record, `<scratch>/reports/<your name>.check.json`. A commit hook that rewrote and re-staged files after the record was written makes the two differ. When they do, list the paths it changed, `git diff --name-only "$(jq -r .tree <scratch>/reports/<your name>.check.json)" HEAD`. If the PR changes every listed path anyway, run `recipe-check.mjs` again with the same arguments: right after the commit the index holds the committed tree, so the re-run runs both commands on that tree and records it, leaving the head's sha as it is. A listed path the PR does not otherwise change is a stale base the hook staged rather than left unstaged, and a re-run would record it green: `git fetch origin && git rebase origin/main`, take the commit back with `git reset --soft HEAD^`, put each such path alone back with `git restore --source=HEAD --staged --worktree -- <that path>`, run `recipe-check.mjs`, then `git commit -C ORIG_HEAD` and compare again. A hook that stages such a path again on the rebased base → push nothing and report that cause. Equal trees need no re-run. Exit 1 is red; exit 2 and 4 are refusals that record nothing: your brief says how each ends; exit 75 (no slot free) and exit 143, 130 or 129 (a SIGTERM, SIGINT or SIGHUP, nothing recorded) are no test result: run it again, with `timeout: 0` on the call for a signal. **Standalone, with no report to settle against,** run `checkCmd` and `testCmd` yourself, each copied verbatim.
|
|
@@ -31,34 +31,27 @@ was given for, and the label no longer covers it.
|
|
|
31
31
|
|
|
32
32
|
## The labelled head
|
|
33
33
|
|
|
34
|
-
`ready-to-merge` is a finisher's verdict on one tree, and it does not expire when that tree does. **A GitHub label does not follow the branch** — one merged PR's timeline shows it,
|
|
34
|
+
`ready-to-merge` is a finisher's verdict on one tree, and it does not expire when that tree does. **A GitHub label does not follow the branch** — one merged PR's timeline shows it, which the `timeline` route below reads: `labeled ready-to-merge`, then commits and a `head_ref_force_pushed`, then `merged`, with no `unlabeled` anywhere between. The label stayed put while the head moved out from under it. Every other guard in this chain — the finisher's dispatch pin, the halt on a moved head, the worktree audit — runs *before* the label exists, so none of them is watching this window. You are the last gate, and **re-deriving the head is a requirement here, not bot discretion**: merge only a head that still carries the audit the label stands for.
|
|
35
35
|
|
|
36
|
-
**The labelled head is the head its labeller recorded.** Whoever adds `ready-to-merge` — a finisher, or `review-and-fix` run standalone — posts a PR comment whose whole body is `ready-to-merge-head: <sha>`, naming the head it audited, immediately before the label. The prefix `ready-to-merge-head:` is not a label: type it as written, whatever string the Label map gives `ready-to-merge`. Read the newest one before `gh pr update-branch` and before anything else that can move the head:
|
|
36
|
+
**The labelled head is the head its labeller recorded.** Whoever adds `ready-to-merge` — a finisher, or `review-and-fix` run standalone — posts a PR comment whose whole body is `ready-to-merge-head: <sha>`, naming the head it audited, immediately before the label. The prefix `ready-to-merge-head:` is not a label: type it as written, whatever string the Label map gives `ready-to-merge`. Read the newest one before `gh pr update-branch` and before anything else that can move the head, with one read-only command that decides the route — you never compare the SHAs yourself:
|
|
37
37
|
|
|
38
38
|
```bash
|
|
39
|
-
|
|
40
|
-
-q '[.comments[] | {createdAt, sha: (.body | capture("\\Aready-to-merge-head: (?<sha>[0-9a-f]{40})\\s*\\z").sha)}]
|
|
41
|
-
| sort_by(.createdAt) | last | .sha // ""'
|
|
39
|
+
~/.omp/plugins/node_modules/@feigi/fleet-ctl/scripts/fleet-run labelled-head.mjs --pr <pr>
|
|
42
40
|
```
|
|
43
41
|
|
|
44
|
-
|
|
42
|
+
It prints one JSON line, `{pr, record, head, route, timeline, exit}`: `record` is the newest record's SHA (`null` when no comment is a record), `head` the PR's current head, and `route` one of `current`, `gate` or `timeline`. **The route is the command's answer, not yours to re-derive:** a `record` that differs from `head` is route `gate`, never `timeline` — the `timeline` route is reached only when `record` is `null`. Exit 2 means a read failed (its `step` is `read-pr`, `label-map` or `read-timeline`, its `error` what `gh` said): skip the PR and report `<step>-#<pr>`, the way any other gate refusal is reported.
|
|
45
43
|
|
|
46
|
-
|
|
44
|
+
Nothing else names that head. A commit's dates are when it was made, not when it was pushed, so a commit made before the label and pushed after it carries no date after the label; and a plain push that a force-push then orphans leaves no line on the PR's timeline at all.
|
|
47
45
|
|
|
48
|
-
**
|
|
46
|
+
**Route `current` — the recorded head is the current head — is the normal case, and it proceeds untouched** — label applied, head unchanged, merge goes ahead exactly as it did before this gate existed.
|
|
49
47
|
|
|
50
|
-
**
|
|
48
|
+
**Route `gate` — the recorded head is not the current head — is not refused on sight: it may be a rebase-carry, and the merge gate decides.** The label binds to the change the finisher audited, not to one SHA: a rewrite that leaves the PR's net change byte-identical — a conflict-free rebase onto a newer `main` — keeps it, and anything a push adds, drops or edits does not, whenever it was pushed and however its commits are dated. So, in the main checkout after a plain `git fetch origin`, run step 3's gate now, before step 1, with `--pre <record>` and no `--post`. **`rebaseCarry` null → refuse:** report `head-moved-after-label-#<pr>` and stop on that PR. Leave the label where it is — you audited nothing and removing another member's verdict is not yours to do. What clears it is a **fresh** finisher against the new head; the first audit does not transfer, because it verified a different tree. Non-null → the current head carries the labelled head's change: `--pre` stays the labelled head on every later gate run, step 1's `pre` must read `rebaseCarry.accepted` (any other head is a push since the proof — refuse with `head-moved-after-label-#<pr>`), and your report names the carry as `rebase-carry-#<pr>` with both SHAs.
|
|
51
49
|
|
|
52
|
-
|
|
53
|
-
label="<ready-to-merge string>" gh api "repos/{owner}/{repo}/issues/<pr>/timeline?per_page=100" --paginate \
|
|
54
|
-
-q '.[] | select((.event == "labeled" and .label.name == env.label)
|
|
55
|
-
or .event == "committed" or .event == "head_ref_force_pushed")
|
|
56
|
-
| .event + " " + (.sha // .label.name // "")'
|
|
57
|
-
```
|
|
50
|
+
**Route `timeline` — no record, a hand-added label or one applied before its labeller recorded a head — falls back to the timeline, which can refuse a moved head but never name the labelled one.** The command has already read it, `gh api repos/{owner}/{repo}/issues/<pr>/timeline?per_page=100 --paginate`, and printed the verdict as `timeline: {label, verdict, after}`, `label` the Label map's string for `ready-to-merge`. Run the command before `gh pr update-branch`, on this route too: your own rebase lands commits after the label by construction, so once you have rebased this read can no longer tell your commits from someone else's.
|
|
58
51
|
|
|
59
|
-
|
|
52
|
+
`verdict` is `moved` when a `committed` or `head_ref_force_pushed` event follows the last `labeled` event for that string, `after` listing those events as `<event> <sha>`; otherwise `clean`. **`moved` with no record → refuse:** report `head-moved-after-label-#<pr>` and stop on that PR, the label left where it is — nothing names a head the label was applied to, so no carry can be proven. **`clean` is the normal case, and it proceeds untouched.** A timeline with no `labeled` event for that string has no verdict: the label is on the PR, so a read that never saw it applied came back empty or wrong, and the command exits 2 with `step` `read-timeline`.
|
|
60
53
|
|
|
61
|
-
Record the head before you rebase — `
|
|
54
|
+
Record the head before you rebase — the `head` the command printed, read before anything moved it — because step 3 hands it to the merge gate as `--pre` and nothing later can reconstruct it. Where step 1 runs, that is its `pre`; on an already-current PR it is simply the head you merge. After a carry, `--pre` is the labelled head instead.
|
|
62
55
|
|
|
63
56
|
What this gate deliberately does not answer. It does not ask *who* audited — a hand-added `ready-to-merge` with no finisher behind it reads clean here, and the reviewer-only rule in `run-team/SKILL.md` is what owns that — nor who posted the record or who force-pushed. A head rebased after the label by an **earlier, abandoned pass of this command** is judged like any other moved head: with a record, carried when its net change is the labelled head's, refused when it is not; without one, refused.
|
|
64
57
|
|
package/package.json
CHANGED
|
@@ -11,14 +11,18 @@
|
|
|
11
11
|
//
|
|
12
12
|
// dispositions-ok=fix-pr-<M>[-x]:<run> every rule below held
|
|
13
13
|
// dispositions-mismatch=fix-pr-<M>[-x]:<run> at least one entry broke one
|
|
14
|
-
// dispositions-escalate=fix-pr-<M>[-x]:<run>
|
|
15
|
-
// but a critical or important
|
|
16
|
-
// was deferred
|
|
17
|
-
// or a rule broke
|
|
18
|
-
// fix-applier's record on
|
|
19
|
-
// review already had
|
|
14
|
+
// dispositions-escalate=fix-pr-<M>[-x]:<run> the maintainer answers: either every
|
|
15
|
+
// rule held but a critical or important
|
|
16
|
+
// finding was deferred
|
|
17
|
+
// `remedy-outside-diff`, or a rule broke
|
|
18
|
+
// and an earlier fix-applier's record on
|
|
19
|
+
// the same review already had
|
|
20
20
|
// dispositions-unchecked=fix-pr-<M>[-x]:<run> no rule broke, but where a deferral was
|
|
21
21
|
// filed could not be read
|
|
22
|
+
// escalation-answer=<run>:<bucket>[<index>]:upheld|sent-back
|
|
23
|
+
// the maintainer's answer to one escalated
|
|
24
|
+
// finding, written by --uphold and
|
|
25
|
+
// --send-back and by nothing else
|
|
22
26
|
//
|
|
23
27
|
// `<run>` is the review's own run, so a verdict on one review never answers
|
|
24
28
|
// a later one — a second review at the same head included.
|
|
@@ -95,6 +99,7 @@
|
|
|
95
99
|
// is escalated rather than passed: the verdict is `escalate`, and the
|
|
96
100
|
// output names each such finding. A `suggestion` passes as `ok`. A record
|
|
97
101
|
// that also breaks a rule is a `mismatch`, its escalations printed too.
|
|
102
|
+
// The maintainer's answers (below) clear an escalation.
|
|
98
103
|
// - Refuter evidence: a suggestion — an `unverified` finding no refuter
|
|
99
104
|
// was dispatched against (`refutersDispatched` zero or absent) — needs
|
|
100
105
|
// `verdictPath` when it is in scope, by the presumption above or by its
|
|
@@ -156,12 +161,41 @@
|
|
|
156
161
|
// never ok, and never a mismatch, since the record broke nothing. Run the
|
|
157
162
|
// check again once `gh` answers.
|
|
158
163
|
//
|
|
164
|
+
// Escalation answers: the maintainer answers an escalated finding `upheld` —
|
|
165
|
+
// the deferral stands — or `sent-back` — the finding is applied in this PR.
|
|
166
|
+
// `--uphold <list>` and `--send-back <list>`, each a comma-separated list of
|
|
167
|
+
// `<bucket>[<index>]` as the output prints it, record the answers for the
|
|
168
|
+
// escalated member, `--member fix-pr-<M>[-x]`, in one write that adds
|
|
169
|
+
// `escalation-answer=<run>:<bucket>[<index>]:upheld|sent-back` per finding to
|
|
170
|
+
// the PR's row and replaces the escalate with the verdict the record then
|
|
171
|
+
// earns: `ok` — `unchecked` when a filing could not be read — with every
|
|
172
|
+
// finding upheld; `mismatch`, or `escalate` when an earlier fix-applier's
|
|
173
|
+
// record on the same review already failed, with any sent back. A send-back
|
|
174
|
+
// is a failure like any other. `<run>` is the review whose escalation the
|
|
175
|
+
// answer settles, so an answer on one review answers nothing on a later one.
|
|
176
|
+
//
|
|
177
|
+
// Every record judged against a review reads that review's answers off the
|
|
178
|
+
// PR's rows, whether or not the run records any: an upheld finding is no
|
|
179
|
+
// escalation, and an entry that defers a sent-back finding is a violation
|
|
180
|
+
// whatever its reason. Running the check again with no answer flags therefore
|
|
181
|
+
// reproduces the verdict and its violations.
|
|
182
|
+
//
|
|
183
|
+
// A run that records answers refuses — exit 2, the cause named, the ledger
|
|
184
|
+
// byte-identical — unless: a ledger is in use; the PR's current dispositions
|
|
185
|
+
// verdict on its latest review is an escalate naming the member; no
|
|
186
|
+
// fix-applier on the PR is live; the record, judged with the answers already
|
|
187
|
+
// on the row, breaks no rule; every listed finding is one the record escalates,
|
|
188
|
+
// none listed twice or both ways; and every escalation of the record has an
|
|
189
|
+
// answer. A record that breaks a rule has no outside-diff escalate to answer:
|
|
190
|
+
// a second failure on one review clears only with a new review.
|
|
191
|
+
//
|
|
159
192
|
// Exit status: 0 ok; 1 mismatch, escalate or unchecked; 2 nothing judged and
|
|
160
|
-
// nothing written — a bad flag,
|
|
161
|
-
// `label-map.mjs ensure`), an unreadable or
|
|
162
|
-
// record file that exists but cannot be read, a git
|
|
163
|
-
// missing or unparseable RECORD is judged, not refused:
|
|
164
|
-
// nothing a reader can use, so every finding it had to
|
|
193
|
+
// nothing written — a bad flag, an answer the run refuses to record, no valid
|
|
194
|
+
// Label map (the message names `label-map.mjs ensure`), an unreadable or
|
|
195
|
+
// malformed review file, a record file that exists but cannot be read, a git
|
|
196
|
+
// or ledger failure. A missing or unparseable RECORD is judged, not refused:
|
|
197
|
+
// the fix-applier wrote nothing a reader can use, so every finding it had to
|
|
198
|
+
// cover is dropped.
|
|
165
199
|
//
|
|
166
200
|
// Without a ledger the record is judged all the same and the exit status is
|
|
167
201
|
// the whole verdict: no token is written, no row is read, and `token` in the
|
|
@@ -189,7 +223,7 @@ import { isCLI } from "./is-cli.mjs";
|
|
|
189
223
|
import { gitEnv } from "./git-env.mjs";
|
|
190
224
|
import { fleetFile, FleetDirUnresolvable } from "./fleet-dir.mjs";
|
|
191
225
|
import { readLabelMap } from "./label-map.mjs";
|
|
192
|
-
import { parseMember, memberTokens, rowNums, dispositionsToken, firstReview, prTokens } from "./ledger-grammar.mjs";
|
|
226
|
+
import { parseMember, memberTokens, rowNums, dispositionsToken, escalationAnswerToken, escalationAnswers, firstReview, prTokens } from "./ledger-grammar.mjs";
|
|
193
227
|
import { deriveRun, LedgerError } from "./fleet-tick.mjs";
|
|
194
228
|
import { VERDICT_SCHEMA } from "./review-core.mjs";
|
|
195
229
|
|
|
@@ -212,6 +246,8 @@ export const ALLOWED_DEFER = Object.freeze(["false-rationale", "mutual-exclusion
|
|
|
212
246
|
const COVERED = ["survived", "unverified"];
|
|
213
247
|
const BUCKETS = [...COVERED, "refuted"];
|
|
214
248
|
const ENUMS = { scope: ["in", "out"], claimKind: ["behavior", "shape"], disposition: ["apply", "defer"] };
|
|
249
|
+
// The rule an entry breaks when it defers a finding the maintainer sent back.
|
|
250
|
+
const SENT_BACK = "sent back to be applied in this PR — the maintainer answered this finding's escalation, and this entry defers it; a deferral is a mismatch whatever its reason";
|
|
215
251
|
|
|
216
252
|
// A Charge: what a finding that stands on a PR's first review says about the
|
|
217
253
|
// work as submitted. `none` names one of CHARGE_REASONS; no other Charge does.
|
|
@@ -491,10 +527,15 @@ function chargeProblem(e, { inScope, required }) {
|
|
|
491
527
|
* `charges` is whether the record answers the PR's first review (firstReview()
|
|
492
528
|
* in ledger-grammar.mjs), where every entry whose finding stands carries a
|
|
493
529
|
* Charge; a Charge an entry carries anywhere is judged all the same.
|
|
530
|
+
* `answers` is the maintainer's escalation answers for the review's run
|
|
531
|
+
* (escalationAnswers() in ledger-grammar.mjs): a finding's address,
|
|
532
|
+
* `<bucket>[<index>]`, to `upheld` or `sent-back`. An upheld finding is no
|
|
533
|
+
* escalation, and an entry that defers a sent-back finding is a violation
|
|
534
|
+
* whatever its reason.
|
|
494
535
|
* `review` must pass reviewProblem() — a bucket missing or holding a
|
|
495
536
|
* non-object is a TypeError here, not a violation.
|
|
496
537
|
*/
|
|
497
|
-
export function checkDispositions({ review, record, recordProblem = null, run = null, touched, diffFiles = null, roots = [], filing = null, charges = false }) {
|
|
538
|
+
export function checkDispositions({ review, record, recordProblem = null, run = null, touched, diffFiles = null, roots = [], filing = null, charges = false, answers = new Map() }) {
|
|
498
539
|
const violations = [];
|
|
499
540
|
const escalations = [];
|
|
500
541
|
const unchecked = [];
|
|
@@ -552,6 +593,13 @@ export function checkDispositions({ review, record, recordProblem = null, run =
|
|
|
552
593
|
const inScope = presumed !== null || e.scope === "in";
|
|
553
594
|
const charge = chargeProblem(e, { inScope, required: charges && stands(bucket, e) });
|
|
554
595
|
if (charge !== null) at(bucket, index, charge);
|
|
596
|
+
// The maintainer sent this finding back to be applied in this PR: an entry
|
|
597
|
+
// that defers it breaks that answer whatever its reason, so nothing else
|
|
598
|
+
// about the deferral is judged.
|
|
599
|
+
if (e.disposition === "defer" && answers.get(key) === "sent-back") {
|
|
600
|
+
at(bucket, index, SENT_BACK);
|
|
601
|
+
return;
|
|
602
|
+
}
|
|
555
603
|
if (bucket === "refuted" && !e.reason?.trim()) {
|
|
556
604
|
at(bucket, index, "a reversed refutation names its evidence in reason, and this one names none");
|
|
557
605
|
return;
|
|
@@ -610,7 +658,7 @@ export function checkDispositions({ review, record, recordProblem = null, run =
|
|
|
610
658
|
return;
|
|
611
659
|
}
|
|
612
660
|
const severity = finding.severity;
|
|
613
|
-
if (severity !== "suggestion") escalations.push({ bucket, index, severity: severity ?? null, files: outside });
|
|
661
|
+
if (severity !== "suggestion" && answers.get(key) !== "upheld") escalations.push({ bucket, index, severity: severity ?? null, files: outside });
|
|
614
662
|
}
|
|
615
663
|
}
|
|
616
664
|
// Where the deferral must be filed. `claimKind` is trusted, never judged.
|
|
@@ -648,7 +696,7 @@ export function formatViolation({ bucket, index, rule }) {
|
|
|
648
696
|
}
|
|
649
697
|
|
|
650
698
|
export function formatEscalation({ bucket, index, severity, files }) {
|
|
651
|
-
return `${bucket}[${index}]: a ${severity ?? "severity-less"} finding deferred remedy-outside-diff, its remedy in ${files.join(", ")} —
|
|
699
|
+
return `${bucket}[${index}]: a ${severity ?? "severity-less"} finding deferred remedy-outside-diff, its remedy in ${files.join(", ")} — the maintainer answers`;
|
|
652
700
|
}
|
|
653
701
|
|
|
654
702
|
// The row text with `token` in place of every verdict the same member wrote
|
|
@@ -688,7 +736,7 @@ export function failedBefore(rows, pr, member, run) {
|
|
|
688
736
|
|
|
689
737
|
const die = makeDie(NAME);
|
|
690
738
|
const { arg, has, sweep, stray } = defineFlags(die, {
|
|
691
|
-
flags: { member: "value", scratch: "value", repo: "value", ledger: "value", "no-ledger": "bool", review: "value" },
|
|
739
|
+
flags: { member: "value", scratch: "value", repo: "value", ledger: "value", "no-ledger": "bool", review: "value", uphold: "value", "send-back": "value" },
|
|
692
740
|
});
|
|
693
741
|
|
|
694
742
|
// The one git primitive. An ambient GIT_DIR or GIT_WORK_TREE — a hook, a
|
|
@@ -834,8 +882,31 @@ function readJson(path) {
|
|
|
834
882
|
return JSON.parse(readFileSync(path, "utf8"));
|
|
835
883
|
}
|
|
836
884
|
|
|
885
|
+
// A finding's address as the check prints it: its bucket and its position in
|
|
886
|
+
// that bucket of the review file.
|
|
887
|
+
const ADDRESS = new RegExp(`^(${BUCKETS.join("|")})\\[(0|[1-9][0-9]*)\\]$`);
|
|
888
|
+
|
|
889
|
+
// The findings a `--uphold` or `--send-back` list names, each `<bucket>[<index>]`
|
|
890
|
+
// — or null when the flag is absent. A second occurrence of the flag would be
|
|
891
|
+
// read by nothing, so it is refused rather than dropped.
|
|
892
|
+
function addressList(flag) {
|
|
893
|
+
const raw = arg(flag);
|
|
894
|
+
if (raw === null) return null;
|
|
895
|
+
if (process.argv.filter((a) => a === `--${flag}`).length > 1) die(`--${flag} is given twice — name every finding in one comma-separated list`);
|
|
896
|
+
const list = raw.split(",").map((a) => a.trim());
|
|
897
|
+
const bad = list.find((a) => !ADDRESS.test(a));
|
|
898
|
+
if (bad !== undefined) die(`--${flag} names ${JSON.stringify(bad)}, which is no <bucket>[<index>] — a bucket is ${BUCKETS.join(", ")}, an index a whole number from 0`);
|
|
899
|
+
return list;
|
|
900
|
+
}
|
|
901
|
+
|
|
902
|
+
// Addresses in the record's own order: by bucket, then by index.
|
|
903
|
+
const byAddress = (a, b) => {
|
|
904
|
+
const [x, y] = [a, b].map((s) => ADDRESS.exec(s));
|
|
905
|
+
return BUCKETS.indexOf(x[1]) - BUCKETS.indexOf(y[1]) || Number(x[2]) - Number(y[2]);
|
|
906
|
+
};
|
|
907
|
+
|
|
837
908
|
function main() {
|
|
838
|
-
const usage = "usage: dispositions-check.mjs --member fix-pr-<M>[-x] --scratch <dir> [--repo <path>] [--ledger <path> | --no-ledger --review <path>]";
|
|
909
|
+
const usage = "usage: dispositions-check.mjs --member fix-pr-<M>[-x] --scratch <dir> [--repo <path>] [--ledger <path> | --no-ledger --review <path>] [--uphold <list>] [--send-back <list>]";
|
|
839
910
|
const name = arg("member");
|
|
840
911
|
const scratch = arg("scratch");
|
|
841
912
|
if (!name || !scratch) die(usage);
|
|
@@ -845,9 +916,25 @@ function main() {
|
|
|
845
916
|
if (member === null || member.family !== "fix-pr") die(`'${name}' is not a fix-applier — expected fix-pr-<M>, a -b, -c … suffix allowed`);
|
|
846
917
|
const pr = member.number;
|
|
847
918
|
const repo = arg("repo") ?? process.cwd();
|
|
919
|
+
// The maintainer's answers, when this run records them: `--uphold` and
|
|
920
|
+
// `--send-back`, each a list of the escalated findings answered that way.
|
|
921
|
+
// Told before anything is read, since a list that cannot be one is a usage error.
|
|
922
|
+
const uphold = addressList("uphold");
|
|
923
|
+
const sendBack = addressList("send-back");
|
|
924
|
+
const listed = new Map();
|
|
925
|
+
for (const [flag, list, answer] of [["--uphold", uphold, "upheld"], ["--send-back", sendBack, "sent-back"]]) {
|
|
926
|
+
for (const a of list ?? []) {
|
|
927
|
+
if (listed.has(a)) die(listed.get(a) === answer ? `${flag} lists ${a} twice` : `${a} is listed in both --uphold and --send-back — a finding is answered one way`);
|
|
928
|
+
listed.set(a, answer);
|
|
929
|
+
}
|
|
930
|
+
}
|
|
931
|
+
const recording = listed.size > 0;
|
|
848
932
|
const standalone = has("no-ledger");
|
|
849
933
|
if (standalone && arg("ledger") !== null) die("--no-ledger and --ledger contradict: name one");
|
|
850
934
|
const ledgerFile = standalone ? null : ledgerInUse(arg("ledger"), repo);
|
|
935
|
+
if (recording && ledgerFile === null) {
|
|
936
|
+
die(`${uphold !== null ? "--uphold" : "--send-back"} records the maintainer's answer on the ledger row, and no ledger is in use — run it for the escalated member where the run's ledger is`);
|
|
937
|
+
}
|
|
851
938
|
// Without a ledger nothing names the review the record answers, so `--review`
|
|
852
939
|
// must; with one, the latest `reviewed=` already does. Both are usage errors,
|
|
853
940
|
// so they are told before the Label map, the ledger or the tracker is read.
|
|
@@ -870,7 +957,7 @@ function main() {
|
|
|
870
957
|
// same per-PR fold `ledger.mjs dispatch` gates the finisher by, so the check
|
|
871
958
|
// and the gate never judge two different reviews. Without one it is the
|
|
872
959
|
// `--review` path the checks above required.
|
|
873
|
-
let data = null, row = null, run = null, charges = false, reviewPath;
|
|
960
|
+
let data = null, row = null, run = null, charges = false, reviewPath, answers = new Map();
|
|
874
961
|
if (ledgerFile === null) {
|
|
875
962
|
reviewPath = arg("review");
|
|
876
963
|
} else {
|
|
@@ -889,9 +976,30 @@ function main() {
|
|
|
889
976
|
}
|
|
890
977
|
if (latest === undefined) die(`PR #${pr} has no reviewed= on the ledger — no review for ${member.name}'s record to answer`);
|
|
891
978
|
run = latest.run;
|
|
979
|
+
// Answers clear the escalate they answer and nothing else: the PR's current
|
|
980
|
+
// verdict on this review must be that escalate, and no fix-applier on the PR
|
|
981
|
+
// may be working — its landing would answer the review in its own right.
|
|
982
|
+
if (recording) {
|
|
983
|
+
const current = latest.dispositions;
|
|
984
|
+
if (current === null || current.verdict !== "escalate" || current.member !== member.name) {
|
|
985
|
+
die(`PR #${pr}'s current dispositions verdict on review ${run} is ${current === null ? "none" : `${current.verdict} from ${current.member}`}, not an escalate from ${member.name} — escalation answers clear the escalate they answer, and nothing else`);
|
|
986
|
+
}
|
|
987
|
+
if (latest.fixLive.length > 0) {
|
|
988
|
+
die(`${latest.fixLive.join(", ")} still live on PR #${pr} — a fix-applier answering review ${run} has not settled, so the answers wait: settle it, then record them`);
|
|
989
|
+
}
|
|
990
|
+
}
|
|
991
|
+
// Every record judged against this review reads the answers recorded for it.
|
|
992
|
+
// A token that only looks like one answers nothing, and says so.
|
|
993
|
+
const tokens = prTokens(data.rows, pr);
|
|
994
|
+
answers = escalationAnswers(tokens, run);
|
|
995
|
+
for (const t of tokens) {
|
|
996
|
+
if (t.startsWith("escalation-answer=") && escalationAnswerToken(t) === null) {
|
|
997
|
+
console.error(`${NAME}: ignoring malformed token ${t} on PR #${pr}'s row — it answers nothing`);
|
|
998
|
+
}
|
|
999
|
+
}
|
|
892
1000
|
// Charges are required only on the record answering the PR's first
|
|
893
1001
|
// review; this record answers `run`, so `run` counts as answered.
|
|
894
|
-
charges = firstReview(
|
|
1002
|
+
charges = firstReview(tokens, [run])?.run === run;
|
|
895
1003
|
reviewPath = join(scratch, `pr${pr}`, run, "review.json");
|
|
896
1004
|
}
|
|
897
1005
|
let review;
|
|
@@ -937,17 +1045,44 @@ function main() {
|
|
|
937
1045
|
const diffFiles = git(repo, ["diff", "--no-color", "--no-ext-diff", "--no-renames", "--name-only", "-z", base, head],
|
|
938
1046
|
`list the files of ${base}..${head}`).split("\0").filter(Boolean);
|
|
939
1047
|
|
|
940
|
-
const
|
|
941
|
-
|
|
942
|
-
|
|
1048
|
+
const touched = touchedLines(diff);
|
|
1049
|
+
const filing = { pr, roles, issue: issueReader(repo), verdict: verdictReader(scratch, pr) };
|
|
1050
|
+
const judge = (answered) => checkDispositions({
|
|
1051
|
+
review, record, recordProblem, run, touched, diffFiles, roots: [review.snapshot, top], charges, answers: answered, filing,
|
|
943
1052
|
});
|
|
1053
|
+
let judged = judge(answers);
|
|
1054
|
+
let recorded = [];
|
|
1055
|
+
if (recording) {
|
|
1056
|
+
// The answers go on the row only when they answer exactly what the record
|
|
1057
|
+
// escalates, judged with the answers already there. A record that breaks a
|
|
1058
|
+
// rule has no outside-diff escalate to answer; a finding the record does not
|
|
1059
|
+
// escalate, or an escalated one left unanswered, makes an answer that
|
|
1060
|
+
// settles nothing.
|
|
1061
|
+
if (judged.violations.length > 0) {
|
|
1062
|
+
die(`${member.name}'s record breaks a rule, so its escalate is no outside-diff one: the maintainer's answers clear an escalate whose record breaks none. A broken rule is a mismatch, and after an earlier failure on review ${run} a second failure, which only a new review of the PR clears — run the check without --uphold and --send-back to judge it. It breaks:\n`
|
|
1063
|
+
+ judged.violations.map((v) => ` ${member.name}: ${formatViolation(v)}`).join("\n"));
|
|
1064
|
+
}
|
|
1065
|
+
const open = judged.escalations.map((x) => `${x.bucket}[${x.index}]`).sort(byAddress);
|
|
1066
|
+
for (const a of [...listed.keys()].sort(byAddress)) {
|
|
1067
|
+
if (!open.includes(a)) die(`${a} is not one of ${member.name}'s escalated findings${open.length > 0 ? ` (${open.join(", ")})` : " — its record escalates none"}`);
|
|
1068
|
+
}
|
|
1069
|
+
const unanswered = open.filter((a) => !listed.has(a));
|
|
1070
|
+
if (unanswered.length > 0) {
|
|
1071
|
+
die(`${member.name}'s record escalates ${open.join(", ")}, and ${unanswered.join(", ")} ${unanswered.length === 1 ? "has" : "have"} no answer — every escalated finding is answered in one run, with --uphold or --send-back`);
|
|
1072
|
+
}
|
|
1073
|
+
answers = new Map([...answers, ...listed]);
|
|
1074
|
+
judged = judge(answers);
|
|
1075
|
+
recorded = open.map((a) => [a, listed.get(a)]);
|
|
1076
|
+
}
|
|
1077
|
+
const { violations, escalations, unchecked } = judged;
|
|
944
1078
|
// No ledger, no row: the exit status below is the verdict, and with no
|
|
945
1079
|
// earlier fix-applier's verdict to count, a broken rule is always a
|
|
946
1080
|
// mismatch.
|
|
947
1081
|
// A mismatch an earlier fix-applier already drew on this review makes this
|
|
948
|
-
// one the second: it is written as an escalate, which
|
|
949
|
-
// A
|
|
950
|
-
//
|
|
1082
|
+
// one the second: it is written as an escalate, which only a new review of
|
|
1083
|
+
// the PR clears. A finding the maintainer sent back counts as a broken rule
|
|
1084
|
+
// like any other, here and in failedBefore(). A broken rule outranks an
|
|
1085
|
+
// escalation, and an escalation a filing the tracker could not answer.
|
|
951
1086
|
const secondMismatch = violations.length > 0 && data !== null && failedBefore(data.rows, pr, member, run);
|
|
952
1087
|
const verdict = violations.length > 0 ? (secondMismatch ? "escalate" : "mismatch")
|
|
953
1088
|
: escalations.length > 0 ? "escalate" : unchecked.length > 0 ? "unchecked" : "ok";
|
|
@@ -957,9 +1092,13 @@ function main() {
|
|
|
957
1092
|
const key = row.split(/\s/)[0];
|
|
958
1093
|
if (!/^#[0-9]+$/.test(key)) die(`the row carrying ${member.name} has no #<n> key for \`ledger.mjs row\` to rewrite it by: ${row}`);
|
|
959
1094
|
const text = row.slice(key.length).trim();
|
|
960
|
-
const
|
|
1095
|
+
const answerTokens = recorded.map(([a, answer]) => `escalation-answer=${run}:${a}:${answer}`);
|
|
1096
|
+
const updated = withVerdict([text, ...answerTokens].join(" · "), token);
|
|
961
1097
|
if (updated === text) console.error(` ${member.name}: row ${key} already carries ${token} — not written again`);
|
|
962
|
-
else runLedger(ledgerFile, ["row", key, updated], `write ${token} onto row ${key}`);
|
|
1098
|
+
else runLedger(ledgerFile, ["row", key, updated], `write ${recorded.length > 0 ? `the escalation answers and ${token}` : token} onto row ${key}`);
|
|
1099
|
+
}
|
|
1100
|
+
if (recorded.length > 0) {
|
|
1101
|
+
console.error(`${member.name}: recorded the maintainer's escalation answers on review ${run} — ${recorded.map(([a, answer]) => `${a} ${answer === "sent-back" ? "sent back" : answer}`).join(", ")}`);
|
|
963
1102
|
}
|
|
964
1103
|
|
|
965
1104
|
for (const v of violations) console.error(`${member.name}: ${formatViolation(v)}`);
|
|
@@ -89,6 +89,7 @@ import { inertVerdict } from "./finisher-scope.mjs";
|
|
|
89
89
|
import { gitEnv } from "./git-env.mjs";
|
|
90
90
|
import { LABEL_LIST_ARGS, LABEL_LIST_LIMIT, releaseLabelsDefined, releaseLabelsIn } from "./release-labels.mjs";
|
|
91
91
|
import { readLabelMap } from "./label-map.mjs";
|
|
92
|
+
import { headRecordBody, newestHeadRecord } from "./ready-to-merge-head.mjs";
|
|
92
93
|
import { ticketlessVerdict } from "./ticketless.mjs";
|
|
93
94
|
|
|
94
95
|
const NAME = "finisher-label";
|
|
@@ -233,16 +234,11 @@ if (ticketless) receipt.inert = inertVerdict({ worktree: resolve(repo ?? "."), p
|
|
|
233
234
|
// --- 2: the head record ----------------------------------------------------
|
|
234
235
|
// The newest record wins, the way the merge bot reads it: a matching record
|
|
235
236
|
// older than one naming another head is not the record the bot will act on.
|
|
236
|
-
const
|
|
237
|
-
const records = first.comments
|
|
238
|
-
.map((c, i) => ({ i, at: c.createdAt, m: RECORD.exec(c.body) }))
|
|
239
|
-
.filter((c) => c.m !== null)
|
|
240
|
-
.sort((a, b) => (a.at < b.at ? -1 : a.at > b.at ? 1 : a.i - b.i));
|
|
241
|
-
const recorded = records.length > 0 && records[records.length - 1].m[1] === pin;
|
|
237
|
+
const recorded = newestHeadRecord(first.comments) === pin;
|
|
242
238
|
const labelled = firstLabels.includes(LABEL);
|
|
243
239
|
|
|
244
240
|
if (!recorded) {
|
|
245
|
-
gh("comment", ["pr", "comment", String(pr), "--body",
|
|
241
|
+
gh("comment", ["pr", "comment", String(pr), "--body", headRecordBody(pin)]);
|
|
246
242
|
receipt.commented = true;
|
|
247
243
|
}
|
|
248
244
|
|
|
@@ -0,0 +1,189 @@
|
|
|
1
|
+
#!/usr/bin/env node
|
|
2
|
+
// The merge bot's "labelled head" step as one read-only command, so the bot
|
|
3
|
+
// never compares two SHAs by eye: a recorded head printed beside a different
|
|
4
|
+
// current head was read as "no record" and sent down the timeline fallback,
|
|
5
|
+
// which refuses a moved head without ever calling merge-gate.mjs.
|
|
6
|
+
//
|
|
7
|
+
// labelled-head.mjs --pr <N> [--repo <dir>]
|
|
8
|
+
//
|
|
9
|
+
// `--repo` is the directory `gh` runs in (it resolves the repository from
|
|
10
|
+
// there), the cwd when omitted. Reached through the Resolver:
|
|
11
|
+
// `~/.omp/plugins/node_modules/@feigi/fleet-ctl/scripts/fleet-run labelled-head.mjs ...`.
|
|
12
|
+
//
|
|
13
|
+
// One `gh pr view <N> --json comments,headRefOid` read gives the newest head
|
|
14
|
+
// record (ready-to-merge-head.mjs owns its grammar, the one finisher-label.mjs
|
|
15
|
+
// writes) and the current head together. The route follows from those two
|
|
16
|
+
// alone:
|
|
17
|
+
//
|
|
18
|
+
// current a record exists and names the current head: proceed untouched.
|
|
19
|
+
// gate a record exists and names another head: not refused on sight, it
|
|
20
|
+
// may be a rebase-carry. Run merge-gate.mjs with `--pre <record>`
|
|
21
|
+
// and no `--post`; its `rebaseCarry` decides.
|
|
22
|
+
// timeline no record: a hand-added label, or one applied before its labeller
|
|
23
|
+
// recorded a head. The timeline is read here and its verdict
|
|
24
|
+
// printed. A recorded head is never routed to `timeline`.
|
|
25
|
+
//
|
|
26
|
+
// The timeline read is the only one that needs the Label map's string for
|
|
27
|
+
// `ready-to-merge`, so the map is read only on that route. The `timeline`
|
|
28
|
+
// object holds `verdict`, `moved` when a `committed` or `head_ref_force_pushed`
|
|
29
|
+
// event follows the last `labeled` event for that string, else `clean`; and
|
|
30
|
+
// `after`, those events as `<event> <sha>`. A timeline with no `labeled` event
|
|
31
|
+
// for that string has no verdict: the label is on the PR, so a read that never
|
|
32
|
+
// saw it applied came back empty or wrong, and it fails as `read-timeline`.
|
|
33
|
+
// The label is left where it is on every verdict: this command writes nothing.
|
|
34
|
+
//
|
|
35
|
+
// Stdout is one JSON line on every run that gets past its flags (a flag
|
|
36
|
+
// refusal, and a receipt that cannot be written, print none):
|
|
37
|
+
//
|
|
38
|
+
// {pr, record, head, route, timeline [, step, error], exit}
|
|
39
|
+
//
|
|
40
|
+
// record the newest record's SHA, null when none
|
|
41
|
+
// head the PR's current head
|
|
42
|
+
// route `current`, `gate` or `timeline`; null on exit 2
|
|
43
|
+
// timeline null off the `timeline` route, else {label, verdict, after}
|
|
44
|
+
// step on exit 2 only, the read that failed: `read-pr`, `label-map`,
|
|
45
|
+
// or `read-timeline`
|
|
46
|
+
// error on exit 2 only, what `gh` (or the invocation) said
|
|
47
|
+
//
|
|
48
|
+
// Exit vocabulary:
|
|
49
|
+
//
|
|
50
|
+
// 0 a route was decided
|
|
51
|
+
// 2 the invocation or a read failed — a missing or unknown flag, or a
|
|
52
|
+
// receipt stdout would not take, is a refusal on stderr with no receipt,
|
|
53
|
+
// as in every other script's `die()`
|
|
54
|
+
|
|
55
|
+
import { spawnSync } from "node:child_process";
|
|
56
|
+
import { statSync } from "node:fs";
|
|
57
|
+
import { resolve } from "node:path";
|
|
58
|
+
import { makeDie, defineFlags, writeAll } from "./arg.mjs";
|
|
59
|
+
import { gitEnv } from "./git-env.mjs";
|
|
60
|
+
import { readLabelMap } from "./label-map.mjs";
|
|
61
|
+
import { newestHeadRecord } from "./ready-to-merge-head.mjs";
|
|
62
|
+
|
|
63
|
+
const NAME = "labelled-head";
|
|
64
|
+
const USAGE = "usage: labelled-head.mjs --pr <N> [--repo <dir>]";
|
|
65
|
+
|
|
66
|
+
const MOVING = new Set(["committed", "head_ref_force_pushed"]);
|
|
67
|
+
|
|
68
|
+
const die = makeDie(NAME);
|
|
69
|
+
const { arg, numArg, sweep, stray } = defineFlags(die, {
|
|
70
|
+
flags: { pr: "value", repo: "value" },
|
|
71
|
+
});
|
|
72
|
+
|
|
73
|
+
// The sweep runs before the required-flag check so a misspelt flag is named
|
|
74
|
+
// as that, not buried under a missing-flag usage line.
|
|
75
|
+
sweep();
|
|
76
|
+
stray();
|
|
77
|
+
const pr = numArg("pr");
|
|
78
|
+
const repo = arg("repo");
|
|
79
|
+
if (pr === null) die(USAGE);
|
|
80
|
+
|
|
81
|
+
const receipt = { pr, record: null, head: null, route: null, timeline: null, exit: 0 };
|
|
82
|
+
|
|
83
|
+
function finish(exit, extra = {}, message = null) {
|
|
84
|
+
Object.assign(receipt, extra, { exit });
|
|
85
|
+
const written = writeAll(1, `${JSON.stringify(receipt)}\n`);
|
|
86
|
+
if (message !== null) writeAll(2, `${NAME}: ${message}\n`);
|
|
87
|
+
// The receipt is the only carrier of the route: a lost write is exit 2, never
|
|
88
|
+
// a decided route with nothing printed.
|
|
89
|
+
if (!written) die("the receipt could not be written to stdout");
|
|
90
|
+
process.exit(exit);
|
|
91
|
+
}
|
|
92
|
+
|
|
93
|
+
function fail(step, error) {
|
|
94
|
+
finish(2, { step, error }, `${step}: ${error}`);
|
|
95
|
+
}
|
|
96
|
+
|
|
97
|
+
if (repo !== null) {
|
|
98
|
+
// `throwIfNoEntry` covers ENOENT alone: an unreadable path (EACCES, ELOOP)
|
|
99
|
+
// still throws, and must take the receipt path rather than a stack trace.
|
|
100
|
+
let stat;
|
|
101
|
+
try {
|
|
102
|
+
stat = statSync(repo, { throwIfNoEntry: false });
|
|
103
|
+
} catch (e) {
|
|
104
|
+
fail("read-pr", `--repo cannot be read: ${repo} (${e.code ?? e.message})`);
|
|
105
|
+
}
|
|
106
|
+
if (!stat?.isDirectory()) fail("read-pr", `--repo is not a directory: ${repo}`);
|
|
107
|
+
}
|
|
108
|
+
|
|
109
|
+
// `gh` resolves its repository from the cwd's git remotes, so an ambient
|
|
110
|
+
// GIT_DIR would retarget every call at another repository.
|
|
111
|
+
const GH_ENV = gitEnv();
|
|
112
|
+
|
|
113
|
+
function gh(step, args) {
|
|
114
|
+
const r = spawnSync("gh", args, { encoding: "utf8", env: GH_ENV, stdio: ["ignore", "pipe", "pipe"], maxBuffer: 64 * 1024 * 1024, ...(repo === null ? {} : { cwd: repo }) });
|
|
115
|
+
if (r.error) fail(step, `could not run gh: ${r.error.message}`);
|
|
116
|
+
if (r.signal) fail(step, `gh was killed by ${r.signal}`);
|
|
117
|
+
if (r.status !== 0) fail(step, (r.stderr ?? "").trim() || `gh exited ${r.status}`);
|
|
118
|
+
return r.stdout;
|
|
119
|
+
}
|
|
120
|
+
|
|
121
|
+
const isObject = (v) => v !== null && typeof v === "object" && !Array.isArray(v);
|
|
122
|
+
|
|
123
|
+
// The route the record and the head decide. A record is never routed to
|
|
124
|
+
// `timeline`: that is the whole of this function.
|
|
125
|
+
function routeOf(record, head) {
|
|
126
|
+
if (record === null) return "timeline";
|
|
127
|
+
return record === head ? "current" : "gate";
|
|
128
|
+
}
|
|
129
|
+
|
|
130
|
+
// The verdict the timeline events give, `events` as `{event, sha, label}` in
|
|
131
|
+
// timeline order, `label` the string the `ready-to-merge` role maps to; null
|
|
132
|
+
// when no `labeled` event names `label`, since nothing is after a line never
|
|
133
|
+
// seen.
|
|
134
|
+
function timelineVerdict(events, label) {
|
|
135
|
+
const last = events.findLastIndex((e) => e.event === "labeled" && e.label === label);
|
|
136
|
+
if (last === -1) return null;
|
|
137
|
+
const after = events.slice(last + 1).filter((e) => MOVING.has(e.event)).map((e) => `${e.event} ${e.sha ?? ""}`.trimEnd());
|
|
138
|
+
return { label, verdict: after.length > 0 ? "moved" : "clean", after };
|
|
139
|
+
}
|
|
140
|
+
|
|
141
|
+
const out = gh("read-pr", ["pr", "view", String(pr), "--json", "comments,headRefOid"]);
|
|
142
|
+
let view;
|
|
143
|
+
try {
|
|
144
|
+
view = JSON.parse(out);
|
|
145
|
+
} catch {
|
|
146
|
+
fail("read-pr", `gh printed no JSON: ${out.slice(0, 200)}`);
|
|
147
|
+
}
|
|
148
|
+
if (
|
|
149
|
+
!isObject(view) ||
|
|
150
|
+
!/^[0-9a-f]{40}$/.test(view.headRefOid) ||
|
|
151
|
+
!Array.isArray(view.comments) ||
|
|
152
|
+
!view.comments.every((c) => isObject(c) && typeof c.body === "string" && typeof c.createdAt === "string")
|
|
153
|
+
) {
|
|
154
|
+
fail("read-pr", `gh printed an unexpected shape: ${out.slice(0, 200)}`);
|
|
155
|
+
}
|
|
156
|
+
|
|
157
|
+
const record = newestHeadRecord(view.comments);
|
|
158
|
+
const head = view.headRefOid;
|
|
159
|
+
const route = routeOf(record, head);
|
|
160
|
+
receipt.record = record;
|
|
161
|
+
receipt.head = head;
|
|
162
|
+
if (route !== "timeline") finish(0, { route });
|
|
163
|
+
|
|
164
|
+
let label;
|
|
165
|
+
try {
|
|
166
|
+
label = readLabelMap({ cwd: resolve(repo ?? ".") })["ready-to-merge"];
|
|
167
|
+
} catch (e) {
|
|
168
|
+
fail("label-map", e.message);
|
|
169
|
+
}
|
|
170
|
+
// `-q` runs per page, so a paginated timeline answers one JSON value per
|
|
171
|
+
// line however many pages it took.
|
|
172
|
+
// A `head_ref_force_pushed` event carries its SHA in `commit_id`, `sha` null.
|
|
173
|
+
const lines = gh("read-timeline", [
|
|
174
|
+
"api",
|
|
175
|
+
`repos/{owner}/{repo}/issues/${pr}/timeline?per_page=100`,
|
|
176
|
+
"--paginate",
|
|
177
|
+
"-q",
|
|
178
|
+
'.[] | select(.event == "labeled" or .event == "committed" or .event == "head_ref_force_pushed") | {event, sha: (.sha // .commit_id), label: .label.name} | tojson',
|
|
179
|
+
]);
|
|
180
|
+
let events;
|
|
181
|
+
try {
|
|
182
|
+
events = lines.split("\n").filter((l) => l !== "").map((l) => JSON.parse(l));
|
|
183
|
+
} catch {
|
|
184
|
+
fail("read-timeline", `gh printed no JSON: ${lines.slice(0, 200)}`);
|
|
185
|
+
}
|
|
186
|
+
if (!events.every(isObject)) fail("read-timeline", `gh printed an unexpected shape: ${lines.slice(0, 200)}`);
|
|
187
|
+
const timeline = timelineVerdict(events, label);
|
|
188
|
+
if (timeline === null) fail("read-timeline", `no labeled event for ${label} in the timeline`);
|
|
189
|
+
finish(0, { route, timeline });
|
|
@@ -268,16 +268,18 @@ export const prTokens = (rows, pr) => streams(rows).get(pr) ?? [];
|
|
|
268
268
|
// dispositions-check.mjs's verdict on a review fix-applier's disposition
|
|
269
269
|
// record: `dispositions-ok=fix-pr-<M>[-x]:<run>`,
|
|
270
270
|
// `dispositions-mismatch=…`, `dispositions-escalate=…` (a critical or
|
|
271
|
-
// important deferral, or a second mismatch on one review, that
|
|
272
|
-
//
|
|
273
|
-
// filed could not be read), `<run>` the run of the review the
|
|
274
|
-
// answers, as its `reviewed=` names it. `ledger.mjs dispatch` refuses a
|
|
275
|
-
// finisher on anything but an ok. A
|
|
276
|
-
//
|
|
277
|
-
//
|
|
278
|
-
//
|
|
279
|
-
//
|
|
280
|
-
//
|
|
271
|
+
// important deferral, or a second mismatch on one review, that the
|
|
272
|
+
// maintainer answers) or `dispositions-unchecked=…` (no rule broke, but where
|
|
273
|
+
// a deferral was filed could not be read), `<run>` the run of the review the
|
|
274
|
+
// record answers, as its `reviewed=` names it. `ledger.mjs dispatch` refuses a
|
|
275
|
+
// finisher on anything but an ok. A mismatch returns the PR to fixDue for one
|
|
276
|
+
// retry. An escalate clears one of two ways: the maintainer's escalation
|
|
277
|
+
// answers, recorded through dispositions-check.mjs, replace an escalate over
|
|
278
|
+
// a deferral outside the PR's diff with the verdict they give, and a second
|
|
279
|
+
// mismatch on one review clears only when a new review of the PR counts again
|
|
280
|
+
// from none. An unchecked is answered by running the check again, so the tick
|
|
281
|
+
// offers no fix-applier for it. A token outside this shape is no verdict at
|
|
282
|
+
// all, which the gate reads as unchecked: fail closed.
|
|
281
283
|
export function dispositionsToken(tok) {
|
|
282
284
|
const m = /^dispositions-(ok|mismatch|escalate|unchecked)=([^:\s]+):(run-[A-Za-z0-9]{8})$/i.exec(tok);
|
|
283
285
|
if (!m) return null;
|
|
@@ -286,6 +288,38 @@ export function dispositionsToken(tok) {
|
|
|
286
288
|
return { verdict: m[1].toLowerCase(), member, run: m[3] };
|
|
287
289
|
}
|
|
288
290
|
|
|
291
|
+
// The maintainer's answer to one finding a fix-applier's record escalated, as
|
|
292
|
+
// dispositions-check.mjs writes it onto the PR's row, and the only writer:
|
|
293
|
+
// `escalation-answer=<run>:<bucket>[<index>]:upheld` (the deferral stands) or
|
|
294
|
+
// `…:sent-back` (the finding is applied in this PR). `<run>` is the run of the
|
|
295
|
+
// review whose escalation it answers, as its `reviewed=` names it, and
|
|
296
|
+
// `<bucket>[<index>]` the finding's address as the check prints it. It is no
|
|
297
|
+
// dispositions verdict and no member, so neither dispositionsToken() nor
|
|
298
|
+
// parseToken() claims it, and a token outside this shape answers nothing.
|
|
299
|
+
const ESCALATION_ANSWER = /^escalation-answer=(run-[A-Za-z0-9]{8}):(survived|unverified|refuted)\[(0|[1-9][0-9]*)\]:(upheld|sent-back)$/;
|
|
300
|
+
export function escalationAnswerToken(tok) {
|
|
301
|
+
const m = typeof tok === "string" ? ESCALATION_ANSWER.exec(tok) : null;
|
|
302
|
+
return m === null ? null : { run: m[1], bucket: m[2], index: Number(m[3]), answer: m[4] };
|
|
303
|
+
}
|
|
304
|
+
|
|
305
|
+
/**
|
|
306
|
+
* The answers `tokens` (prTokens()) carry for review `run`: a Map from a
|
|
307
|
+
* finding's address, `<bucket>[<index>]`, to `upheld` or `sent-back`. An answer
|
|
308
|
+
* recorded against another run counts for nothing, so a new review starts
|
|
309
|
+
* from none. A finding carrying both answers reads as sent back — the stricter
|
|
310
|
+
* reading, as currentDispositions() reads one fix-applier's two verdicts.
|
|
311
|
+
*/
|
|
312
|
+
export function escalationAnswers(tokens, run) {
|
|
313
|
+
const answers = new Map();
|
|
314
|
+
for (const tok of tokens) {
|
|
315
|
+
const a = escalationAnswerToken(tok);
|
|
316
|
+
if (a === null || a.run !== run) continue;
|
|
317
|
+
const address = `${a.bucket}[${a.index}]`;
|
|
318
|
+
if (answers.get(address) !== "sent-back") answers.set(address, a.answer);
|
|
319
|
+
}
|
|
320
|
+
return answers;
|
|
321
|
+
}
|
|
322
|
+
|
|
289
323
|
/**
|
|
290
324
|
* A PR's first review, read off its `tokens` (prTokens()): walking its
|
|
291
325
|
* `reviewed=` tokens in ledger order, the first that counted no survived and
|
package/scripts/ledger.mjs
CHANGED
|
@@ -1986,9 +1986,12 @@ function dispositionsRefusal(pr, review) {
|
|
|
1986
1986
|
}
|
|
1987
1987
|
if (v.verdict === "escalate") {
|
|
1988
1988
|
return `dispositions escalate — ${v.member} deferred a finding above suggestion severity because its remedy lies outside the PR's diff, `
|
|
1989
|
-
+
|
|
1990
|
-
+
|
|
1991
|
-
+
|
|
1989
|
+
+ `or its record drew a second mismatch on this review: review ${review.run} gets no finisher until the escalate clears. `
|
|
1990
|
+
+ "An outside-diff deferral clears when the maintainer's escalation answers are recorded with "
|
|
1991
|
+
+ `dispositions-check.mjs --member ${v.member} --scratch <scratch> --uphold '<list>' --send-back '<list>'; `
|
|
1992
|
+
+ "a second mismatch clears only with a new review of the PR. "
|
|
1993
|
+
+ `dispositions-check.mjs --member ${v.member} --scratch <scratch> alone names each escalated finding or violating entry by bucket and index, `
|
|
1994
|
+
+ "for the PR comment that hands it to the maintainer";
|
|
1992
1995
|
}
|
|
1993
1996
|
return null;
|
|
1994
1997
|
}
|
|
@@ -0,0 +1,29 @@
|
|
|
1
|
+
// The head record, as its writer posts it and its reader reads it back: a PR
|
|
2
|
+
// comment whose whole body is `ready-to-merge-head: <sha>`, naming the head
|
|
3
|
+
// the labeller audited, posted immediately before the `ready-to-merge` label.
|
|
4
|
+
// Shared by finisher-label.mjs, which writes it, and labelled-head.mjs, which
|
|
5
|
+
// the merge bot runs to read it, so the grammar is stated once. The prefix is
|
|
6
|
+
// not a label: it is `ready-to-merge-head:` whatever string the Label map
|
|
7
|
+
// gives `ready-to-merge`.
|
|
8
|
+
|
|
9
|
+
// The whole body: 40 lowercase hex after the prefix, and nothing else but
|
|
10
|
+
// trailing whitespace (a newline, CRLF, blank lines). A prefix before the
|
|
11
|
+
// keyword, a suffix after the SHA, a second line, a short or uppercase SHA is
|
|
12
|
+
// not a record.
|
|
13
|
+
const HEAD_RECORD = /^ready-to-merge-head: ([0-9a-f]{40})\s*$/;
|
|
14
|
+
|
|
15
|
+
// The body the writer posts for `sha`.
|
|
16
|
+
export const headRecordBody = (sha) => `ready-to-merge-head: ${sha}`;
|
|
17
|
+
|
|
18
|
+
// The newest record among `comments` (`{body, createdAt}` as `gh pr view --json
|
|
19
|
+
// comments` prints them): newest by `createdAt`, the later array position
|
|
20
|
+
// winning a tie, since the sort is stable. A comment that is not a record,
|
|
21
|
+
// however new, hides nothing. Answers the SHA, or null when no comment is a
|
|
22
|
+
// record.
|
|
23
|
+
export function newestHeadRecord(comments) {
|
|
24
|
+
const records = comments
|
|
25
|
+
.map((c) => ({ at: c.createdAt, m: HEAD_RECORD.exec(c.body) }))
|
|
26
|
+
.filter((c) => c.m !== null)
|
|
27
|
+
.sort((a, b) => (a.at < b.at ? -1 : a.at > b.at ? 1 : 0));
|
|
28
|
+
return records.length === 0 ? null : records[records.length - 1].m[1];
|
|
29
|
+
}
|
package/skills/run-team/SKILL.md
CHANGED
|
@@ -611,14 +611,9 @@ answers that one: the check's stderr names it, and the record's issue number
|
|
|
611
611
|
needs correcting); the tick offers no fix-applier for it. `dispositions
|
|
612
612
|
mismatch` — no finisher: the tick prints `DISPATCH fix-pr PR#<M>` for it, and
|
|
613
613
|
the next-suffix fix-applier answers it (**Then dispatch a fix-applier**).
|
|
614
|
-
`dispositions escalate` — no finisher, no
|
|
615
|
-
|
|
616
|
-
|
|
617
|
-
only a human can rule on either. Post the check's output, which names each
|
|
618
|
-
escalated finding or violating entry, with `gh pr comment <M>`, and flag the PR
|
|
619
|
-
for a human; re-running the check reprints it. Dispatch no fix-applier and no
|
|
620
|
-
finisher for that review, and expect no `fix-due` row for it; a new
|
|
621
|
-
review of the PR starts the check again. **On any PR with a
|
|
614
|
+
`dispositions escalate` — no finisher, no `fix-due` row: a finding above
|
|
615
|
+
`suggestion` deferred `remedy-outside-diff` clears with the maintainer's answers,
|
|
616
|
+
a second mismatch only with a new review (**Dispositions escalation**). **On any PR with a
|
|
622
617
|
returned review, `0/<n>/0` included, it refuses too while a fix-applier on the
|
|
623
618
|
PR is still live, verdict or not** —
|
|
624
619
|
`fix-pr-<M>[-x] still live`: settle it, run the check for it, then dispatch
|
|
@@ -783,9 +778,14 @@ re-run the check for the mismatched member to reprint them. It writes its own
|
|
|
783
778
|
record, and when it reports you run the check for it exactly as for the first
|
|
784
779
|
one. `ok` ends it. A second failure on the same review is written as
|
|
785
780
|
`dispositions-escalate=fix-pr-<M>-b:<run>` in place of a mismatch: the tick
|
|
786
|
-
prints no `DISPATCH fix-pr` for it
|
|
787
|
-
`
|
|
788
|
-
|
|
781
|
+
prints no `DISPATCH fix-pr` for it. Post the check's output with
|
|
782
|
+
`gh pr comment <M>`. A second failure is flagged for a human. A new review of
|
|
783
|
+
the PR counts again from none. An escalate whose check printed no violations is
|
|
784
|
+
the maintainer's to answer instead, one yes/no per escalated finding: yes upholds
|
|
785
|
+
the deferral, no sends it back to be applied in this PR. With every finding
|
|
786
|
+
explicitly answered this session, record them with `dispositions-check.mjs`
|
|
787
|
+
`--uphold` and `--send-back`: `ok` gets the finisher, `mismatch` the tick's
|
|
788
|
+
retry, `escalate` is a second failure. See references/dispositions-escalation.md.
|
|
789
789
|
|
|
790
790
|
### The main-gain hit
|
|
791
791
|
|
|
@@ -0,0 +1,36 @@
|
|
|
1
|
+
# Dispositions escalation: what you do with an escalate
|
|
2
|
+
|
|
3
|
+
What SKILL.md's **Dispositions escalation** points at: the message, the records and the comment that clear a `dispositions escalate` whose check printed no violations — a `critical`, `important` or severity-less finding a fix-applier deferred `remedy-outside-diff`, its record breaking no rule. An escalate whose check printed violations is a second mismatch on one review: no answer clears it, you comment and flag the PR for a human, and a new review of the PR counts again from none.
|
|
4
|
+
|
|
5
|
+
## Ask the maintainer
|
|
6
|
+
|
|
7
|
+
Post the check's output with `gh pr comment <M>`: it names each escalated finding, and re-running the check for the escalated member reprints it. Then put one message to the maintainer, with one yes/no for each escalated finding. Each finding is named by:
|
|
8
|
+
|
|
9
|
+
- its address, `<bucket>[<index>]` as the check printed it, its severity and its claim, read from `<scratch>/pr<M>/<run>/review.json`;
|
|
10
|
+
- its remedy files, as the check printed them;
|
|
11
|
+
- the issue it was filed to and the fix-applier's reason, read from the escalated member's record `<scratch>/dispositions-<member>.json`.
|
|
12
|
+
|
|
13
|
+
Yes means upheld: the deferral stands. No means sent back: the finding is applied in this PR.
|
|
14
|
+
|
|
15
|
+
Record nothing until every finding has an answer, and nothing without the maintainer's explicit answer in this session. Answers arrive in pieces, so hold each until the last is in; silence, a default and your own reading of the finding are no answer.
|
|
16
|
+
|
|
17
|
+
## Record the answers
|
|
18
|
+
|
|
19
|
+
On the answers, in this order:
|
|
20
|
+
|
|
21
|
+
1. Run `dispositions-check.mjs --member <member> --scratch <scratch> --uphold '<list>' --send-back '<list>'`, `<member>` the escalated fix-applier and each list the findings answered that way, `<bucket>[<index>]` separated by commas. Quote each list — `[` opens a glob under zsh — and pass a flag only for a list that has a finding in it. One write puts an `escalation-answer=<run>:<bucket>[<index>]:upheld|sent-back` token per finding on the PR's row and replaces the escalate with the verdict the answers earn. It refuses instead, exit 2 and the ledger untouched, naming the cause: the PR's current verdict on its latest review is not an escalate from that member, a fix-applier on the PR is live, the record breaks a rule, a finding is not one the record escalates or is listed twice or both ways, or an escalated finding has no answer.
|
|
22
|
+
2. Record one line per finding: `ledger.mjs ruled <M> "escalation answer <bucket>[<index>]: upheld|sent back — <reason>"`, the maintainer's reason.
|
|
23
|
+
3. Post one PR comment under the escalate comment, quoting the answers.
|
|
24
|
+
|
|
25
|
+
The verdict then decides what follows:
|
|
26
|
+
|
|
27
|
+
- `ok`: dispatch the finisher, as for any `ok`. An upheld finding passes; its deferral is judged by every other rule as before.
|
|
28
|
+
- `mismatch`: a sent-back finding is a broken rule, so the tick prints `DISPATCH fix-pr PR#<M>` and the retry runs as any mismatch's does. The retry's `--violations` are the check's lines as printed, the sent-back ones included; re-run the check for the member to reprint them. The retry's record is judged with the answers: deferring a sent-back finding again, for any reason, is a second failure, and applying it while deferring an upheld one `remedy-outside-diff` passes.
|
|
29
|
+
- `escalate`: an earlier fix-applier on the review had already failed, so the send-back is the second failure. Comment, flag the PR for a human, and a new review of the PR counts again from none.
|
|
30
|
+
- `unchecked`: the answers are recorded, but a filing could not be read. Run the check again once `gh` answers; it reads the answers already on the row.
|
|
31
|
+
|
|
32
|
+
An answer belongs to one review. A new review counts from none, so the same finding deferred again on it escalates again.
|
|
33
|
+
|
|
34
|
+
## Any other answer
|
|
35
|
+
|
|
36
|
+
The maintainer may rule otherwise: close the PR, re-review it. Record `ledger.mjs ruled <M> <decision>` and carry it out.
|