@feigi/fleet-ctl 3.154.8 → 3.156.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.
@@ -4,10 +4,10 @@
4
4
  // fix-applier writes its record to `<scratch>/dispositions-fix-pr-<M>[-x].json`,
5
5
  // one file per fix-applier; the review result file it answers is
6
6
  // `<scratch>/pr<M>/<run>/review.json`, `<run>` the run root the PR's latest
7
- // `reviewed=<head>:<survived>/<refuted>/<unverified>:<run>` names. This
8
- // script reads the two together, judges the record, and writes its verdict
9
- // onto the PR's ledger row as a token `ledger.mjs dispatch` gates the PR's
10
- // finisher on:
7
+ // `reviewed=<head>:<survived>/<refuted>/<unverified>:<run>` names. This module
8
+ // reads the two together and judges the record; `ledger.mjs dispositions`
9
+ // runs that judgement and writes its verdict onto the PR's ledger row as a
10
+ // token `ledger.mjs dispatch` gates the PR's finisher on:
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
@@ -21,8 +21,8 @@
21
21
  // filed could not be read
22
22
  // escalation-answer=<run>:<bucket>[<index>]:upheld|sent-back
23
23
  // the maintainer's answer to one escalated
24
- // finding, written by --uphold and
25
- // --send-back and by nothing else
24
+ // finding, written by the verb's --uphold
25
+ // and --send-back and by nothing else
26
26
  //
27
27
  // `<run>` is the review's own run, so a verdict on one review never answers
28
28
  // a later one — a second review at the same head included.
@@ -159,13 +159,14 @@
159
159
  // that entry's filing unjudged. With no rule broken and nothing escalated the
160
160
  // verdict is `unchecked`, which `ledger.mjs dispatch` refuses a finisher on —
161
161
  // never ok, and never a mismatch, since the record broke nothing. Run the
162
- // check again once `gh` answers.
162
+ // verb again once `gh` answers.
163
163
  //
164
164
  // Escalation answers: the maintainer answers an escalated finding `upheld` —
165
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
166
+ // `ledger.mjs dispositions <member> --scratch <dir>` takes `--uphold <list>`
167
+ // and `--send-back <list>`, each a comma-separated list of `<bucket>[<index>]`
168
+ // as the output prints it, and records the answers for the escalated member,
169
+ // `fix-pr-<M>[-x]`, in one write that adds
169
170
  // `escalation-answer=<run>:<bucket>[<index>]:upheld|sent-back` per finding to
170
171
  // the PR's row and replaces the escalate with the verdict the record then
171
172
  // earns: `ok` — `unchecked` when a filing could not be read — with every
@@ -177,11 +178,11 @@
177
178
  // Every record judged against a review reads that review's answers off the
178
179
  // PR's rows, whether or not the run records any: an upheld finding is no
179
180
  // 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
+ // whatever its reason. Running the verb again with no answer flags therefore
181
182
  // reproduces the verdict and its violations.
182
183
  //
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
184
+ // A run that records answers refuses — nothing judged, the ledger
185
+ // byte-identical — unless: the PR's current dispositions
185
186
  // verdict on its latest review is an escalate naming the member; no
186
187
  // fix-applier on the PR is live; the record, judged with the answers already
187
188
  // on the row, breaks no rule; every listed finding is one the record escalates,
@@ -189,35 +190,32 @@
189
190
  // answer. A record that breaks a rule has no outside-diff escalate to answer:
190
191
  // a second failure on one review clears only with a new review.
191
192
  //
192
- // Exit status: 0 ok; 1 mismatch, escalate or unchecked; 2 nothing judged and
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.
193
+ // Who writes what. This module is the judgement, and writes nothing.
194
+ // `ledger.mjs dispositions` runs judgeMember() in-process over the ledger it
195
+ // loaded and is the only writer of a dispositions verdict and of an
196
+ // escalation answer: its exit status is 0 for `ok`, 1 for `mismatch`,
197
+ // `escalate` or `unchecked` — a verdict, written — and 2 for nothing judged
198
+ // and nothing written, which is a bad flag, an answer the run refuses to
199
+ // record, no valid Label map (the message names `label-map.mjs ensure`), an
200
+ // unreadable or malformed review file, a record file that exists but cannot
201
+ // be read, a git or ledger failure. A missing or unparseable RECORD is judged,
202
+ // not refused: the fix-applier wrote nothing a reader can use, so every
203
+ // finding it had to cover is dropped.
199
204
  //
200
- // Without a ledger the record is judged all the same and the exit status is
201
- // the whole verdict: no token is written, no row is read, and `token` in the
202
- // stdout payload is null. That is the shape of a standalone `/review-and-fix`
203
- // with no controller, chosen by `--no-ledger` or by a ledger path that does
204
- // not exist. With no `reviewed=` to name the review, `--review <path>` names
205
- // its file, and is required; with a ledger it is refused, since the ledger
206
- // already names one.
207
- // A repository's `.fleet/ledger.md` outlives the fleet run that wrote it, so a
208
- // standalone member in a worktree of such a repository would otherwise find
209
- // the previous run's ledger, and a ledger that exists is never skipped: one
210
- // holding no row for the member is a fault (exit 2), as is a ledger path that
211
- // cannot be looked up (a parent that is a file, no permission, a symlink loop).
212
- // Only a path that does not exist is "no ledger": the default path, or one
213
- // `--ledger` names, which also prints a note on stderr that no token was
214
- // written. `--no-ledger` names that state outright: no ledger is looked for,
215
- // whatever the repository holds, and it contradicts `--ledger`.
205
+ // This script is the standalone check, a `/review-and-fix` with no
206
+ // controller: `--no-ledger --review <path>` names the review's file, and the
207
+ // record is judged all the same, the exit status the whole verdict — 0 ok,
208
+ // 1 anything else, 2 nothing judged — with no token written and `token` in the
209
+ // stdout payload null. A repository's `.fleet/ledger.md` outlives the fleet
210
+ // run that wrote it, so a ledger at the default path that exists is never
211
+ // skipped: without `--no-ledger` it is a refusal (exit 2) naming the verb.
212
+ // Only a path that does not exist is "no ledger", and `--no-ledger` names
213
+ // that state outright: no ledger is looked for, whatever the repository
214
+ // holds. `--ledger`, `--uphold` and `--send-back` are the verb's and refused.
216
215
 
217
216
  import { readFileSync, existsSync, lstatSync, realpathSync, statSync } from "node:fs";
218
217
  import { execFileSync } from "node:child_process";
219
218
  import { join, dirname, basename, isAbsolute, relative, posix, sep } from "node:path";
220
- import { fileURLToPath } from "node:url";
221
219
  import { makeDie, defineFlags } from "./arg.mjs";
222
220
  import { isCLI } from "./is-cli.mjs";
223
221
  import { gitEnv } from "./git-env.mjs";
@@ -228,8 +226,6 @@ import { deriveRun, LedgerError } from "./fleet-tick.mjs";
228
226
  import { VERDICT_SCHEMA } from "./review-core.mjs";
229
227
 
230
228
  const NAME = "dispositions-check";
231
- const SCRIPT_DIR = dirname(fileURLToPath(import.meta.url));
232
- const LEDGER_SCRIPT = join(SCRIPT_DIR, "ledger.mjs");
233
229
 
234
230
  // Two spellings of one commit: either head a prefix of the other, the way a
235
231
  // record's head (7-40 hex) is matched against its review's full head.
@@ -731,13 +727,21 @@ export function failedBefore(rows, pr, member, run) {
731
727
  }
732
728
 
733
729
  // ---------------------------------------------------------------------------
734
- // CLI
730
+ // the judgement over a ledger snapshot, and the standalone CLI
735
731
  // ---------------------------------------------------------------------------
736
732
 
737
- const die = makeDie(NAME);
738
- const { arg, has, sweep, stray } = defineFlags(die, {
739
- flags: { member: "value", scratch: "value", repo: "value", ledger: "value", "no-ledger": "bool", review: "value", uphold: "value", "send-back": "value" },
740
- });
733
+ /** Nothing judged and nothing written: the cause is the message. */
734
+ export class CheckRefusal extends Error {}
735
+ const refuse = (message) => {
736
+ throw new CheckRefusal(message);
737
+ };
738
+
739
+ /** The parsed fix-applier `name` names, or a CheckRefusal. */
740
+ function parseFixApplier(name) {
741
+ const member = parseMember(name);
742
+ if (member === null || member.family !== "fix-pr") refuse(`'${name}' is not a fix-applier — expected fix-pr-<M>, a -b, -c … suffix allowed`);
743
+ return member;
744
+ }
741
745
 
742
746
  // The one git primitive. An ambient GIT_DIR or GIT_WORK_TREE — a hook, a
743
747
  // `rebase --exec` — would answer for another repository and judge the record
@@ -748,15 +752,7 @@ function git(repo, args, what) {
748
752
  encoding: "utf8", env: gitEnv({ LC_ALL: "C" }), maxBuffer: 256 * 1024 * 1024, stdio: ["ignore", "pipe", "pipe"],
749
753
  });
750
754
  } catch (e) {
751
- die(`could not ${what}: ${e.stderr?.toString().trim() || e.message}`);
752
- }
753
- }
754
-
755
- function runLedger(ledgerFile, args, what) {
756
- try {
757
- return execFileSync(process.execPath, [LEDGER_SCRIPT, "--file", ledgerFile, ...args], { encoding: "utf8" });
758
- } catch (e) {
759
- die(`could not ${what}: ${e.stderr?.trim() || e.message}`);
755
+ refuse(`could not ${what}: ${e.stderr?.toString().trim() || e.message}`);
760
756
  }
761
757
  }
762
758
 
@@ -845,36 +841,27 @@ function verdictReader(scratch, pr) {
845
841
  };
846
842
  }
847
843
 
848
- // The ledger file this run writes its verdict to, or null when there is none:
849
- // `--ledger`, else the run's `.fleet/ledger.md` resolved from `repo` by
850
- // fleet-dir.mjs's fleetFile() — the workspace every worktree of one
851
- // repository shares, which is where `ledger.mjs dispatch` wrote the member's
852
- // row. The path is handed to `ledger.mjs` as `--file`, so the existence probe
853
- // and the calls that follow answer for one file. Only ENOENT means "there is
854
- // none": any other failure to look the path up is a fault, not a standalone
855
- // run. An absent path named by `--ledger` is announced on stderr; an absent
856
- // default path is not.
857
- // `lstat`, not `stat`, so a dangling symlink is a ledger that cannot be read
858
- // rather than an absent one.
859
- function ledgerInUse(explicit, repo) {
860
- let file = explicit;
861
- if (file == null) {
862
- try {
863
- file = fleetFile("ledger.md", { cwd: repo });
864
- } catch (e) {
865
- if (!(e instanceof FleetDirUnresolvable)) throw e;
866
- die(e.message);
867
- }
844
+ // The ledger file the repository's default path names, or null when there is
845
+ // none: the run's `.fleet/ledger.md` resolved from `repo` by fleet-dir.mjs's
846
+ // fleetFile() — the workspace every worktree of one repository shares, which
847
+ // is where `ledger.mjs dispatch` wrote the member's row. Only ENOENT means
848
+ // "there is none": any other failure to look the path up is a fault, not a
849
+ // standalone run. `lstat`, not `stat`, so a dangling symlink is a ledger that
850
+ // cannot be read rather than an absent one.
851
+ function defaultLedger(repo) {
852
+ let file;
853
+ try {
854
+ file = fleetFile("ledger.md", { cwd: repo });
855
+ } catch (e) {
856
+ if (!(e instanceof FleetDirUnresolvable)) throw e;
857
+ refuse(e.message);
868
858
  }
869
859
  try {
870
860
  lstatSync(file);
871
861
  return file;
872
862
  } catch (e) {
873
- if (e.code === "ENOENT") {
874
- if (explicit !== null) console.error(`${NAME}: no ledger at ${file} (named by --ledger) — judged with no ledger, so no token was written; pass --no-ledger to choose that`);
875
- return null;
876
- }
877
- die(`could not look for the ledger ${file}: ${e.message}`);
863
+ if (e.code === "ENOENT") return null;
864
+ refuse(`could not look for the ledger ${file}: ${e.message}`);
878
865
  }
879
866
  }
880
867
 
@@ -886,111 +873,124 @@ function readJson(path) {
886
873
  // that bucket of the review file.
887
874
  const ADDRESS = new RegExp(`^(${BUCKETS.join("|")})\\[(0|[1-9][0-9]*)\\]$`);
888
875
 
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);
876
+ /** The findings a `--uphold` or `--send-back` list `raw` names, each
877
+ * `<bucket>[<index>]`, or null when the flag is absent. */
878
+ function addressList(flag, raw) {
894
879
  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
880
  const list = raw.split(",").map((a) => a.trim());
897
881
  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`);
882
+ if (bad !== undefined) refuse(`--${flag} names ${JSON.stringify(bad)}, which is no <bucket>[<index>] — a bucket is ${BUCKETS.join(", ")}, an index a whole number from 0`);
899
883
  return list;
900
884
  }
901
885
 
886
+ /** The maintainer's answers the raw `--uphold` and `--send-back` lists give
887
+ * (null for an absent flag), a Map from a finding's address to `upheld` or
888
+ * `sent-back`; an address that is none, or a finding listed twice or both
889
+ * ways, is refused. Told before anything is read, since a list that cannot
890
+ * be one is a usage error. */
891
+ export function answerMap(upholdRaw, sendBackRaw) {
892
+ const [uphold, sendBack] = [addressList("uphold", upholdRaw), addressList("send-back", sendBackRaw)];
893
+ const listed = new Map();
894
+ for (const [flag, list, answer] of [["--uphold", uphold, "upheld"], ["--send-back", sendBack, "sent-back"]]) {
895
+ for (const a of list ?? []) {
896
+ if (listed.has(a)) refuse(listed.get(a) === answer ? `${flag} lists ${a} twice` : `${a} is listed in both --uphold and --send-back — a finding is answered one way`);
897
+ listed.set(a, answer);
898
+ }
899
+ }
900
+ return listed;
901
+ }
902
+
902
903
  // Addresses in the record's own order: by bucket, then by index.
903
904
  const byAddress = (a, b) => {
904
905
  const [x, y] = [a, b].map((s) => ADDRESS.exec(s));
905
906
  return BUCKETS.indexOf(x[1]) - BUCKETS.indexOf(y[1]) || Number(x[2]) - Number(y[2]);
906
907
  };
907
908
 
908
- function main() {
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>]";
910
- const name = arg("member");
911
- const scratch = arg("scratch");
912
- if (!name || !scratch) die(usage);
913
- sweep();
914
- stray();
915
- const member = parseMember(name);
916
- if (member === null || member.family !== "fix-pr") die(`'${name}' is not a fix-applier — expected fix-pr-<M>, a -b, -c … suffix allowed`);
917
- const pr = member.number;
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);
909
+ /**
910
+ * PR `pr`'s latest review on `ledger` (`{rows, dispatched, drain}`), as
911
+ * fleet-tick.mjs's deriveRun folds it — the fold `ledger.mjs dispatch` gates
912
+ * the finisher by. With `answering`, it also holds what recording the
913
+ * maintainer's answers needs: the PR's current verdict on that review is an
914
+ * escalate from fix-applier `memberName`, and no fix-applier on the PR is
915
+ * live. `ledger.mjs dispositions` asks again under its lock, against the
916
+ * ledger as it stands then, so two answer runs that read the same escalate
917
+ * cannot both write. Throws a CheckRefusal otherwise.
918
+ */
919
+ export function latestReview(ledger, pr, memberName, answering) {
920
+ let latest;
921
+ try {
922
+ latest = deriveRun({ rows: ledger.rows, dispatched: ledger.dispatched, drain: ledger.drain }, []).reviewed.find((r) => r.pr === pr);
923
+ } catch (e) {
924
+ if (!(e instanceof LedgerError)) throw e;
925
+ refuse(`${e.message} — fleet-tick.mjs refuses this ledger, so PR #${pr}'s latest review cannot be read off it`);
926
+ }
927
+ if (latest === undefined) refuse(`PR #${pr} has no reviewed= on the ledger — no review for ${memberName}'s record to answer`);
928
+ // Answers clear the escalate they answer and nothing else: the PR's current
929
+ // verdict on this review must be that escalate, and no fix-applier on the PR
930
+ // may be working — its landing would answer the review in its own right.
931
+ if (answering) {
932
+ const current = latest.dispositions;
933
+ if (current === null || current.verdict !== "escalate" || current.member !== memberName) {
934
+ refuse(`PR #${pr}'s current dispositions verdict on review ${latest.run} is ${current === null ? "none" : `${current.verdict} from ${current.member}`}, not an escalate from ${memberName} — escalation answers clear the escalate they answer, and nothing else`);
935
+ }
936
+ if (latest.fixLive.length > 0) {
937
+ refuse(`${latest.fixLive.join(", ")} still live on PR #${pr} — a fix-applier answering review ${latest.run} has not settled, so the answers wait: settle it, then record them`);
929
938
  }
930
939
  }
940
+ return latest;
941
+ }
942
+
943
+ /**
944
+ * Fix-applier `name`'s record judged against the review it answers.
945
+ * `ledger` is the snapshot to judge against, `{rows, dispatched, drain}` as
946
+ * `ledger.mjs read` prints them, or null for a standalone check, which names
947
+ * its review with `reviewPath`. `listed` is the maintainer's answers to
948
+ * record (answerMap()), empty when this run records none, and non-empty only
949
+ * with a `ledger`, the row they are recorded on. Never writes a
950
+ * ledger: the caller does, and learns what to write from the result,
951
+ * `{member, pr, head, verdict, token, violations, escalations, unchecked,
952
+ * run, recorded, secondMismatch}` — `token` null with no ledger, `recorded`
953
+ * the `[address, answer]` pairs this run records.
954
+ *
955
+ * A CheckRefusal is nothing judged: a bad flag, an answer the run refuses to
956
+ * record, no valid Label map (the message names `label-map.mjs ensure`), an
957
+ * unreadable or malformed review file, a record file that exists but cannot
958
+ * be read, a git or ledger failure. A missing or unparseable RECORD is judged,
959
+ * not refused: the fix-applier wrote nothing a reader can use, so every
960
+ * finding it had to cover is dropped.
961
+ */
962
+ export function judgeMember({ name, scratch, repo, ledger = null, reviewPath = null, listed = new Map() }) {
963
+ const member = parseFixApplier(name);
964
+ const pr = member.number;
931
965
  const recording = listed.size > 0;
932
- const standalone = has("no-ledger");
933
- if (standalone && arg("ledger") !== null) die("--no-ledger and --ledger contradict: name one");
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
- }
938
- // Without a ledger nothing names the review the record answers, so `--review`
939
- // must; with one, the latest `reviewed=` already does. Both are usage errors,
940
- // so they are told before the Label map, the ledger or the tracker is read.
941
- if (ledgerFile === null && arg("review") === null) die(`no ledger names PR #${pr}'s review — pass --review <path> for the review file ${member.name}'s record answers`);
942
- if (ledgerFile !== null && arg("review") !== null) die(`--review and a ledger contradict: with a ledger the review is the one PR #${pr}'s latest reviewed= names`);
943
- // The Label map, read once, here at the I/O boundary — after the flags and the
944
- // ledger's location are settled, before the ledger or the tracker is read: a
945
- // home's labels are compared and worded in the tracker's own spelling. No
946
- // valid map is "nothing judged" (exit 2), never a verdict; the reader's
947
- // message names `ensure`.
966
+ // The Label map, read once, here at the I/O boundary — before the ledger or
967
+ // the tracker is read: a home's labels are compared and worded in the
968
+ // tracker's own spelling. No valid map is "nothing judged", never a verdict;
969
+ // the reader's message names `ensure`.
948
970
  let roles;
949
971
  try {
950
972
  roles = readLabelMap({ cwd: repo });
951
973
  } catch (e) {
952
- die(e.message);
974
+ refuse(e.message);
953
975
  }
954
976
 
955
977
  // The review the record answers. With a ledger it is the one PR M's latest
956
978
  // `reviewed=` names — `<scratch>/pr<M>/<run>/review.json`, read off the
957
979
  // same per-PR fold `ledger.mjs dispatch` gates the finisher by, so the check
958
980
  // and the gate never judge two different reviews. Without one it is the
959
- // `--review` path the checks above required.
960
- let data = null, row = null, run = null, charges = false, reviewPath, answers = new Map();
961
- if (ledgerFile === null) {
962
- reviewPath = arg("review");
963
- } else {
964
- data = JSON.parse(runLedger(ledgerFile, ["read"], "read the ledger"));
981
+ // `reviewPath` the caller named.
982
+ let run = null, charges = false, answers = new Map();
983
+ if (ledger !== null) {
965
984
  // The verdict lands on the row carrying the member on its own PR's row —
966
985
  // where `ledger.mjs dispatch` wrote it, and where the gate reads PR M's
967
986
  // tokens from.
968
- row = data.rows.find((r) => rowNums(r).pr === pr && memberTokens(r).some((t) => t.name === member.name));
969
- if (row === undefined) die(`${member.name} is on no row of PR #${pr} — \`ledger.mjs dispatch\` records a fix-applier before its record can be checked; with no controller, pass --no-ledger`);
970
- let latest;
971
- try {
972
- latest = deriveRun({ rows: data.rows, dispatched: data.dispatched, drain: data.drain }, []).reviewed.find((r) => r.pr === pr);
973
- } catch (e) {
974
- if (!(e instanceof LedgerError)) throw e;
975
- die(`${e.message} — fleet-tick.mjs refuses this ledger, so PR #${pr}'s latest review cannot be read off it`);
976
- }
977
- if (latest === undefined) die(`PR #${pr} has no reviewed= on the ledger — no review for ${member.name}'s record to answer`);
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
- }
987
+ if (!ledger.rows.some((r) => rowNums(r).pr === pr && memberTokens(r).some((t) => t.name === member.name))) {
988
+ refuse(`${member.name} is on no row of PR #${pr} — \`ledger.mjs dispatch\` records a fix-applier before its record can be checked; with no controller, run dispositions-check.mjs with --no-ledger --review <path>`);
990
989
  }
990
+ run = latestReview(ledger, pr, member.name, recording).run;
991
991
  // Every record judged against this review reads the answers recorded for it.
992
992
  // A token that only looks like one answers nothing, and says so.
993
- const tokens = prTokens(data.rows, pr);
993
+ const tokens = prTokens(ledger.rows, pr);
994
994
  answers = escalationAnswers(tokens, run);
995
995
  for (const t of tokens) {
996
996
  if (t.startsWith("escalation-answer=") && escalationAnswerToken(t) === null) {
@@ -1006,10 +1006,10 @@ function main() {
1006
1006
  try {
1007
1007
  review = readJson(reviewPath);
1008
1008
  } catch (e) {
1009
- die(`could not read the review file ${reviewPath}: ${e.message}`);
1009
+ refuse(`could not read the review file ${reviewPath}: ${e.message}`);
1010
1010
  }
1011
1011
  const problem = reviewProblem(review);
1012
- if (problem !== null) die(`${reviewPath} ${problem}`);
1012
+ if (problem !== null) refuse(`${reviewPath} ${problem}`);
1013
1013
  const head = String(review.head).toLowerCase();
1014
1014
 
1015
1015
  // One record per fix-applier: a retry, or a fix-applier answering a later
@@ -1027,7 +1027,7 @@ function main() {
1027
1027
  try {
1028
1028
  text = readFileSync(recordPath, "utf8");
1029
1029
  } catch (e) {
1030
- die(`could not read the disposition record ${recordPath}: ${e.message}`);
1030
+ refuse(`could not read the disposition record ${recordPath}: ${e.message}`);
1031
1031
  }
1032
1032
  try {
1033
1033
  record = JSON.parse(text);
@@ -1059,62 +1059,94 @@ function main() {
1059
1059
  // escalate, or an escalated one left unanswered, makes an answer that
1060
1060
  // settles nothing.
1061
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`
1062
+ refuse(`${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 \`ledger.mjs dispositions ${member.name} --scratch <scratch>\` without --uphold and --send-back to judge it. It breaks:\n`
1063
1063
  + judged.violations.map((v) => ` ${member.name}: ${formatViolation(v)}`).join("\n"));
1064
1064
  }
1065
1065
  const open = judged.escalations.map((x) => `${x.bucket}[${x.index}]`).sort(byAddress);
1066
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"}`);
1067
+ if (!open.includes(a)) refuse(`${a} is not one of ${member.name}'s escalated findings${open.length > 0 ? ` (${open.join(", ")})` : " — its record escalates none"}`);
1068
1068
  }
1069
1069
  const unanswered = open.filter((a) => !listed.has(a));
1070
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`);
1071
+ refuse(`${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
1072
  }
1073
1073
  answers = new Map([...answers, ...listed]);
1074
1074
  judged = judge(answers);
1075
1075
  recorded = open.map((a) => [a, listed.get(a)]);
1076
1076
  }
1077
1077
  const { violations, escalations, unchecked } = judged;
1078
- // No ledger, no row: the exit status below is the verdict, and with no
1079
- // earlier fix-applier's verdict to count, a broken rule is always a
1080
- // mismatch.
1078
+ // No ledger, no row: the exit status is the verdict, and with no earlier
1079
+ // fix-applier's verdict to count, a broken rule is always a mismatch.
1081
1080
  // A mismatch an earlier fix-applier already drew on this review makes this
1082
1081
  // one the second: it is written as an escalate, which only a new review of
1083
1082
  // the PR clears. A finding the maintainer sent back counts as a broken rule
1084
1083
  // like any other, here and in failedBefore(). A broken rule outranks an
1085
1084
  // escalation, and an escalation a filing the tracker could not answer.
1086
- const secondMismatch = violations.length > 0 && data !== null && failedBefore(data.rows, pr, member, run);
1085
+ const secondMismatch = violations.length > 0 && ledger !== null && failedBefore(ledger.rows, pr, member, run);
1087
1086
  const verdict = violations.length > 0 ? (secondMismatch ? "escalate" : "mismatch")
1088
1087
  : escalations.length > 0 ? "escalate" : unchecked.length > 0 ? "unchecked" : "ok";
1089
- const token = data === null ? null : `dispositions-${verdict}=${member.name}:${run}`;
1088
+ const token = ledger === null ? null : `dispositions-${verdict}=${member.name}:${run}`;
1089
+ return { member: member.name, pr, head, verdict, token, violations, escalations, unchecked, run, recorded, secondMismatch };
1090
+ }
1090
1091
 
1091
- if (data !== null) {
1092
- const key = row.split(/\s/)[0];
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}`);
1094
- const text = row.slice(key.length).trim();
1095
- const answerTokens = recorded.map(([a, answer]) => `escalation-answer=${run}:${a}:${answer}`);
1096
- const updated = withVerdict([text, ...answerTokens].join(" · "), token);
1097
- if (updated === text) console.error(` ${member.name}: row ${key} already carries ${token} — not written again`);
1098
- else runLedger(ledgerFile, ["row", key, updated], `write ${recorded.length > 0 ? `the escalation answers and ${token}` : token} onto row ${key}`);
1099
- }
1092
+ /** What a judgement prints: the stderr lines a reader acts on, then the
1093
+ * stdout payload `{member, pr, head, verdict, token, violations, escalations,
1094
+ * unchecked}`. The exit status is the verdict's: 0 ok, 1 anything else. */
1095
+ export function printVerdict({ member, pr, head, verdict, token, violations, escalations, unchecked, run, recorded, secondMismatch }) {
1100
1096
  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(", ")}`);
1097
+ console.error(`${member}: recorded the maintainer's escalation answers on review ${run} — ${recorded.map(([a, answer]) => `${a} ${answer === "sent-back" ? "sent back" : answer}`).join(", ")}`);
1102
1098
  }
1103
-
1104
- for (const v of violations) console.error(`${member.name}: ${formatViolation(v)}`);
1105
- for (const x of escalations) console.error(`${member.name}: ${formatEscalation(x)}`);
1099
+ for (const v of violations) console.error(`${member}: ${formatViolation(v)}`);
1100
+ for (const x of escalations) console.error(`${member}: ${formatEscalation(x)}`);
1106
1101
  for (const u of unchecked) {
1107
- console.error(`${member.name}: ${u.bucket}[${u.index}]: where it was filed is unchecked — #${u.issue} could not be read through gh: ${u.problem}`);
1102
+ console.error(`${member}: ${u.bucket}[${u.index}]: where it was filed is unchecked — #${u.issue} could not be read through gh: ${u.problem}`);
1108
1103
  }
1109
1104
  if (secondMismatch) {
1110
- console.error(`${member.name}: escalate — an earlier fix-applier's record on review ${run} already failed this check; no further fix-applier answers PR #${pr}, a human does`);
1105
+ console.error(`${member}: escalate — an earlier fix-applier's record on review ${run} already failed this check; no further fix-applier answers PR #${pr}, a human does`);
1111
1106
  }
1112
- console.log(JSON.stringify({ member: member.name, pr, head, verdict, token, violations, escalations, unchecked }));
1107
+ console.log(JSON.stringify({ member, pr, head, verdict, token, violations, escalations, unchecked }));
1113
1108
  // exitCode, not exit(): stdout to a pipe is written asynchronously, and an
1114
1109
  // exit() here could cut the payload off.
1115
1110
  process.exitCode = verdict === "ok" ? 0 : 1;
1116
1111
  }
1117
1112
 
1113
+ const die = makeDie(NAME);
1114
+ const { arg, has, sweep, stray } = defineFlags(die, {
1115
+ flags: { member: "value", scratch: "value", repo: "value", ledger: "value", "no-ledger": "bool", review: "value", uphold: "value", "send-back": "value" },
1116
+ });
1117
+
1118
+ // The standalone check. A fleet run's verdict is `ledger.mjs dispositions`'s,
1119
+ // so this script writes nothing and refuses a ledger outside `--no-ledger`.
1120
+ function main() {
1121
+ const usage = "usage: dispositions-check.mjs --member fix-pr-<M>[-x] --scratch <dir> [--repo <path>] --no-ledger --review <path>";
1122
+ const name = arg("member");
1123
+ const scratch = arg("scratch");
1124
+ if (!name || !scratch) die(usage);
1125
+ sweep();
1126
+ stray();
1127
+ const verb = `ledger.mjs dispositions ${name} --scratch ${scratch}`;
1128
+ for (const flag of ["ledger", "uphold", "send-back"]) {
1129
+ if (arg(flag) !== null) {
1130
+ die(`--${flag} belongs to the ledger verb: run \`${verb}${flag === "ledger" ? "" : " --uphold '<list>' --send-back '<list>'"}\` — this script writes no ledger`);
1131
+ }
1132
+ }
1133
+ const repo = arg("repo") ?? process.cwd();
1134
+ try {
1135
+ const member = parseFixApplier(name);
1136
+ if (!has("no-ledger")) {
1137
+ const ledgerFile = defaultLedger(repo);
1138
+ if (ledgerFile !== null) {
1139
+ die(`a ledger is in use at ${ledgerFile}, and a fleet run's verdict is the ledger verb's: run \`${verb}\`; to judge a record with no controller, pass --no-ledger --review <path>`);
1140
+ }
1141
+ }
1142
+ if (arg("review") === null) die(`no ledger names PR #${member.number}'s review — pass --review <path> for the review file ${member.name}'s record answers`);
1143
+ printVerdict(judgeMember({ name, scratch, repo, reviewPath: arg("review") }));
1144
+ } catch (e) {
1145
+ if (e instanceof CheckRefusal) die(e.message);
1146
+ throw e;
1147
+ }
1148
+ }
1149
+
1118
1150
  // Only run main() as a CLI, never when imported (see is-cli.mjs): a string
1119
1151
  // comparison skipped main() through a symlinked path and exited 0 — the code
1120
1152
  // that means ok — having judged and written nothing.