@feigi/fleet-ctl 3.23.36 → 3.23.38

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.
Files changed (205) hide show
  1. package/package.json +1 -1
  2. package/scripts/cell-readout.mjs +38 -11
  3. package/scripts/main-checkout.mjs +1 -1
  4. package/scripts/member-write-guard.mjs +1 -1
  5. package/scripts/repo-root.mjs +1 -1
  6. package/skills/run-team/references/reaping.md +1 -1
  7. package/scripts/agent-test-dir-prose.test.mjs +0 -59
  8. package/scripts/agent-test.test.mjs +0 -1640
  9. package/scripts/ambient-git-vars-mjs-prose.test.mjs +0 -397
  10. package/scripts/ambient-git-vars-prose.test.mjs +0 -192
  11. package/scripts/ancestry-check-position-prose.test.mjs +0 -175
  12. package/scripts/apply-ruleset.test.mjs +0 -421
  13. package/scripts/arg-header-probes-prose.test.mjs +0 -394
  14. package/scripts/arg.test.mjs +0 -1354
  15. package/scripts/board-cli.test.mjs +0 -710
  16. package/scripts/board-identity.test.mjs +0 -429
  17. package/scripts/board-liveness-banner.test.mjs +0 -119
  18. package/scripts/board-prev-shape.test.mjs +0 -228
  19. package/scripts/board-tryparse-null.test.mjs +0 -119
  20. package/scripts/board.test.mjs +0 -3121
  21. package/scripts/brief-after-cut-prose.test.mjs +0 -53
  22. package/scripts/candidates-exit3-prose.test.mjs +0 -302
  23. package/scripts/candidates.test.mjs +0 -2312
  24. package/scripts/caveat-unification-prose.test.mjs +0 -98
  25. package/scripts/cell-readout.test.mjs +0 -615
  26. package/scripts/ci-comment-rot-prose.test.mjs +0 -2025
  27. package/scripts/ci-completes-premise-prose.test.mjs +0 -257
  28. package/scripts/ci-state-prose.test.mjs +0 -113
  29. package/scripts/ci-state.test.mjs +0 -1933
  30. package/scripts/ci-vacuous-green.test.mjs +0 -368
  31. package/scripts/citation-sweep-prose.test.mjs +0 -1712
  32. package/scripts/claim-lifecycle.test.mjs +0 -187
  33. package/scripts/claim-ticket.test.mjs +0 -1122
  34. package/scripts/closing-keyword-prose.test.mjs +0 -193
  35. package/scripts/cockpit-launch-idempotent-prose.test.mjs +0 -165
  36. package/scripts/cockpit-tick-nonblocking.test.mjs +0 -210
  37. package/scripts/compute-board.test.mjs +0 -1214
  38. package/scripts/compute-spend.test.mjs +0 -517
  39. package/scripts/consumer-technology-prose.test.mjs +0 -126
  40. package/scripts/cross-repo-citation-prose.test.mjs +0 -155
  41. package/scripts/cwd-isolation-pins.mjs +0 -83
  42. package/scripts/dedupe-guard-prose.test.mjs +0 -243
  43. package/scripts/delete-merged-branch.test.mjs +0 -576
  44. package/scripts/derive-testcmd.test.mjs +0 -595
  45. package/scripts/diff-stats.test.mjs +0 -404
  46. package/scripts/dispatch-block-golden-prose.test.mjs +0 -1130
  47. package/scripts/dispatch-block-pins-prose.test.mjs +0 -615
  48. package/scripts/dispositions-check.test.mjs +0 -936
  49. package/scripts/dispositions-gate-prose.test.mjs +0 -129
  50. package/scripts/drop-merged-label.test.mjs +0 -479
  51. package/scripts/exec-stub.mjs +0 -93
  52. package/scripts/exec-stub.test.mjs +0 -69
  53. package/scripts/expected-jobs-prose.test.mjs +0 -80
  54. package/scripts/fan-out-authorization-prose.test.mjs +0 -80
  55. package/scripts/filing-bar-seat-prose.test.mjs +0 -242
  56. package/scripts/filing-claim-bar-prose.test.mjs +0 -166
  57. package/scripts/finisher-died-prose.test.mjs +0 -31
  58. package/scripts/finisher-dispatch-premise-prose.test.mjs +0 -312
  59. package/scripts/finisher-halt-prose.test.mjs +0 -106
  60. package/scripts/finisher-name-prose.test.mjs +0 -134
  61. package/scripts/finisher-own-tree-prose.test.mjs +0 -299
  62. package/scripts/finisher-pin-race-prose.test.mjs +0 -339
  63. package/scripts/finisher-test-verdict-prose.test.mjs +0 -102
  64. package/scripts/fix-applier-correction-rules-prose.test.mjs +0 -202
  65. package/scripts/fix-applier-result-file-prose.test.mjs +0 -149
  66. package/scripts/fleet-bootstrap.test.mjs +0 -75
  67. package/scripts/fleet-heartbeat.test.mjs +0 -450
  68. package/scripts/fleet-provenance.test.mjs +0 -138
  69. package/scripts/fleet-run.test.mjs +0 -90
  70. package/scripts/fleet-state.test.mjs +0 -460
  71. package/scripts/fleet-tick-prose.test.mjs +0 -300
  72. package/scripts/fleet-tick.test.mjs +0 -2444
  73. package/scripts/force-with-lease-reason-prose.test.mjs +0 -184
  74. package/scripts/frontmatter-check.test.mjs +0 -436
  75. package/scripts/git-env.test.mjs +0 -149
  76. package/scripts/git-status-untracked-mode-sweep.test.mjs +0 -216
  77. package/scripts/gone-walk.test.mjs +0 -213
  78. package/scripts/gp-sep-invariant-prose.test.mjs +0 -188
  79. package/scripts/head-moved-after-label-prose.test.mjs +0 -233
  80. package/scripts/immutable-body-claim-prose.test.mjs +0 -204
  81. package/scripts/implementer-model-tier.test.mjs +0 -235
  82. package/scripts/inflight-citation-prose.test.mjs +0 -144
  83. package/scripts/inflight-exit2-prose.test.mjs +0 -81
  84. package/scripts/inflight-probe-guard-prose.test.mjs +0 -109
  85. package/scripts/inflight-scan-scope-prose.test.mjs +0 -57
  86. package/scripts/inflight.test.mjs +0 -2882
  87. package/scripts/injection-control-prose.test.mjs +0 -404
  88. package/scripts/install-root-audit.test.mjs +0 -464
  89. package/scripts/instrument-check-prose.test.mjs +0 -235
  90. package/scripts/instruments.test.mjs +0 -787
  91. package/scripts/is-cli.test.mjs +0 -99
  92. package/scripts/issue-tracker-prose.test.mjs +0 -71
  93. package/scripts/json.test.mjs +0 -364
  94. package/scripts/ledger-dispatch.test.mjs +0 -927
  95. package/scripts/ledger-grammar.test.mjs +0 -227
  96. package/scripts/ledger-read-require-file.test.mjs +0 -197
  97. package/scripts/ledger-rotate.test.mjs +0 -142
  98. package/scripts/ledger.test.mjs +0 -3436
  99. package/scripts/line-distance-prose.test.mjs +0 -245
  100. package/scripts/liveness-rationale-prose.test.mjs +0 -83
  101. package/scripts/locale-pin-prose.test.mjs +0 -189
  102. package/scripts/main-checkout.test.mjs +0 -332
  103. package/scripts/member-outcome-prose.test.mjs +0 -167
  104. package/scripts/member-outcomes-header.test.mjs +0 -129
  105. package/scripts/member-outcomes-prose.test.mjs +0 -63
  106. package/scripts/member-outcomes.test.mjs +0 -638
  107. package/scripts/member-prompt-prose.test.mjs +0 -165
  108. package/scripts/member-record.test.mjs +0 -541
  109. package/scripts/member-write-guard.test.mjs +0 -214
  110. package/scripts/merge-commit-probe-prose.test.mjs +0 -122
  111. package/scripts/merge-gate.test.mjs +0 -613
  112. package/scripts/muted-git-guard-sweep.test.mjs +0 -493
  113. package/scripts/net-ssh-precedence-prose.test.mjs +0 -91
  114. package/scripts/net-watchdog-prose.test.mjs +0 -79
  115. package/scripts/net.test.mjs +0 -211
  116. package/scripts/no-ci-gate-prose.test.mjs +0 -108
  117. package/scripts/no-undo-audit.test.mjs +0 -3961
  118. package/scripts/no-wave.test.mjs +0 -138
  119. package/scripts/node-floor-sweep.test.mjs +0 -611
  120. package/scripts/pointer-target-prose.test.mjs +0 -186
  121. package/scripts/pr-cost.test.mjs +0 -521
  122. package/scripts/pr-overlap.test.mjs +0 -692
  123. package/scripts/printf-die-sweep.test.mjs +0 -384
  124. package/scripts/prompt-renderer.mjs +0 -40
  125. package/scripts/prompt-renderer.test.mjs +0 -68
  126. package/scripts/prose-pin.mjs +0 -807
  127. package/scripts/prose-pin.test.mjs +0 -1034
  128. package/scripts/prove-merge.test.mjs +0 -995
  129. package/scripts/pull-table-relabel-prose.test.mjs +0 -60
  130. package/scripts/quiet-payload-prose.test.mjs +0 -222
  131. package/scripts/reap-cherry-check-prose.test.mjs +0 -80
  132. package/scripts/reap.test.mjs +0 -4432
  133. package/scripts/reaping-prose.test.mjs +0 -239
  134. package/scripts/reaping-reap-authorizers-prose.test.mjs +0 -112
  135. package/scripts/reaping-release-authorizers-prose.test.mjs +0 -85
  136. package/scripts/recipe-derivation-prose.test.mjs +0 -112
  137. package/scripts/recipe-prove.test.mjs +0 -1042
  138. package/scripts/refuter-scratch-prose.test.mjs +0 -135
  139. package/scripts/release-label-required-prose.test.mjs +0 -71
  140. package/scripts/release-label-split-prose.test.mjs +0 -184
  141. package/scripts/release-ticket-reap-pairing-prose.test.mjs +0 -63
  142. package/scripts/release-ticket.test.mjs +0 -5099
  143. package/scripts/renovate-release-contract.test.mjs +0 -379
  144. package/scripts/repo-root.test.mjs +0 -873
  145. package/scripts/reporter-output-rule-prose.test.mjs +0 -208
  146. package/scripts/review-agent-report-only.test.mjs +0 -49
  147. package/scripts/review-core-booking.test.mjs +0 -35
  148. package/scripts/review-core-cwd-isolation.test.mjs +0 -374
  149. package/scripts/review-core-reads.test.mjs +0 -478
  150. package/scripts/review-core-refuter-scratch.test.mjs +0 -148
  151. package/scripts/review-core-scratch-refusal.test.mjs +0 -64
  152. package/scripts/review-core-shared-test-run.test.mjs +0 -275
  153. package/scripts/review-core-snapshot-path.test.mjs +0 -830
  154. package/scripts/review-core-specialist-scratch.test.mjs +0 -191
  155. package/scripts/review-core-testcmd.test.mjs +0 -335
  156. package/scripts/review-core-unrun.test.mjs +0 -566
  157. package/scripts/review-core-unverified-discriminant.test.mjs +0 -208
  158. package/scripts/review-eval-resolver-path.test.mjs +0 -55
  159. package/scripts/review-host-fixture.mjs +0 -89
  160. package/scripts/review-in-run-retry.test.mjs +0 -211
  161. package/scripts/review-no-vendor-dispatch.test.mjs +0 -45
  162. package/scripts/review-path-default.test.mjs +0 -796
  163. package/scripts/review-runner-spawns.test.mjs +0 -95
  164. package/scripts/review-runner.test.mjs +0 -166
  165. package/scripts/review-tier-audit.test.mjs +0 -140
  166. package/scripts/run-artifact-pr-prose.test.mjs +0 -341
  167. package/scripts/run-merge-bot-prose.test.mjs +0 -1413
  168. package/scripts/run-team-local-hook.test.mjs +0 -442
  169. package/scripts/scratch-partition-invariant-prose.test.mjs +0 -74
  170. package/scripts/scripts-path-citation-sweep.test.mjs +0 -73
  171. package/scripts/section-between-guard-prose.test.mjs +0 -379
  172. package/scripts/select-dimensions.test.mjs +0 -674
  173. package/scripts/shared-refusal.test.mjs +0 -388
  174. package/scripts/shell-traps-prose.test.mjs +0 -504
  175. package/scripts/shortlist.test.mjs +0 -380
  176. package/scripts/slow-transport.mjs +0 -72
  177. package/scripts/snapshot-repo.test.mjs +0 -1006
  178. package/scripts/snapshot-runner-audience-prose.test.mjs +0 -130
  179. package/scripts/spend-view.test.mjs +0 -312
  180. package/scripts/staleness-qualifier-prose.test.mjs +0 -251
  181. package/scripts/staleness-verdict-prose.test.mjs +0 -142
  182. package/scripts/staleness.test.mjs +0 -893
  183. package/scripts/stalled-member-liveness-prose.test.mjs +0 -219
  184. package/scripts/stash-prohibition-prose.test.mjs +0 -313
  185. package/scripts/strip-comments.mjs +0 -44
  186. package/scripts/temp-dir.mjs +0 -47
  187. package/scripts/ticket-router.test.mjs +0 -981
  188. package/scripts/tier-check.test.mjs +0 -828
  189. package/scripts/tier-outcomes-header.test.mjs +0 -518
  190. package/scripts/tier-outcomes.test.mjs +0 -572
  191. package/scripts/tier-roles.test.mjs +0 -535
  192. package/scripts/tracker-block-copy-prose.test.mjs +0 -288
  193. package/scripts/triage-labels-gloss-prose.test.mjs +0 -97
  194. package/scripts/unattended-git-sweep.test.mjs +0 -142
  195. package/scripts/verify-sha-exit2-prose.test.mjs +0 -269
  196. package/scripts/verify-sha.test.mjs +0 -692
  197. package/scripts/watcher-degraded-block.test.mjs +0 -369
  198. package/scripts/watcher-key-prose.test.mjs +0 -106
  199. package/scripts/within-run-pair-prose.test.mjs +0 -212
  200. package/scripts/worktree-audit.test.mjs +0 -1408
  201. package/scripts/worktree-head-prose.test.mjs +0 -276
  202. package/scripts/worktree-listing-sweep.test.mjs +0 -217
  203. package/scripts/worktree-model-prose.test.mjs +0 -216
  204. package/scripts/worktree-porcelain.mjs +0 -35
  205. package/scripts/worktree-porcelain.test.mjs +0 -102
@@ -1,1354 +0,0 @@
1
- import { test } from "node:test";
2
- import assert from "node:assert";
3
- import { readFileSync, writeFileSync, existsSync, rmSync } from "node:fs";
4
- import { spawnSync } from "node:child_process";
5
- import { fileURLToPath } from "node:url";
6
- import { tempDir } from "./temp-dir.mjs";
7
- import { join } from "node:path";
8
- import { stripComments } from "./strip-comments.mjs";
9
- import { writeExecStub } from "./exec-stub.mjs";
10
-
11
- const ARG_MODULE = fileURLToPath(new URL("./arg.mjs", import.meta.url));
12
-
13
- // #367 replaced seven private copies of die() with arg.mjs's makeDie(), and
14
- // that migration is the load-bearing half of the change: board.mjs and
15
- // ledger.mjs were still on the async console.error shape #176/#328/#363 exist
16
- // to kill, and the other five on writeSync variants that had drifted apart.
17
- // Nothing pinned the wiring. Reverting board.mjs and ledger.mjs to their
18
- // pre-#367 console.error die() left the whole suite green at 640/640
19
- // (measured), so the bug this refactor closes could walk straight back in on
20
- // the next edit or merge resolution.
21
- //
22
- // THREE assertions per consumer, because each alone is vacuous:
23
- // - the WIRING line alone pins a NAME, not a module. candidates.mjs can
24
- // declare its own local console.error makeDie(), keep the wiring line
25
- // byte-identical, and the suite stays green at 640/640 (measured).
26
- // - the IMPORT alone leaves a script free to import makeDie and then bind
27
- // die to something else entirely.
28
- // - both together still miss a wrong NAME CONSTANT: `const NAME =
29
- // "wrongname"` makes every refusal claim to come from another script, and
30
- // the full suite stays green for six of the seven (measured — only
31
- // candidates is covered, by its own `/^candidates: …/m` assertions).
32
- //
33
- // The SHAPE makeDie() itself must have — the try around the write, with
34
- // process.exit(2) unconditionally after it — is pinned in candidates.test.mjs,
35
- // next to the EAGAIN race that motivates it. The write LOOP it delegates to is
36
- // arg.mjs's writeAll(), pinned and EXECUTED once further down this file
37
- // (#1549); until then it was hand-copied into three scripts and its regex into
38
- // three test files. This file pins that every consumer actually reaches die()
39
- // — a source text-lift pin tests a COPY, so the call site is what makes the
40
- // lifted shape load-bearing.
41
- //
42
- // Line-anchored under /m where an anchor helps, but deliberately WITHOUT `$`
43
- // terminators: a trailing comment on a pinned line is a legitimate edit and
44
- // must not turn these red (measured).
45
- //
46
- // The list is spelled out rather than discovered by globbing for files that
47
- // import arg.mjs: a discovered set silently SHRINKS when a consumer drops the
48
- // import, which is precisely the regression being pinned. A consumer added
49
- // later has to be added here deliberately.
50
- const CONSUMERS = ["board", "candidates", "ci-state", "diff-stats", "fleet-tick", "ledger", "pr-overlap"];
51
-
52
- test("every fleet script wires die() to arg.mjs's makeDie under its own NAME — the #367 migration, pinned", () => {
53
- for (const name of CONSUMERS) {
54
- const src = stripComments(readFileSync(fileURLToPath(new URL(`./${name}.mjs`, import.meta.url)), "utf8"));
55
- assert.match(
56
- src,
57
- /^import \{[^}]*\bmakeDie\b[^}]*\} from "\.\/arg\.mjs";/m,
58
- `${name}.mjs must import makeDie from ./arg.mjs, not define its own die()`,
59
- );
60
- assert.match(
61
- src,
62
- /^const die = makeDie\(NAME\);/m,
63
- `${name}.mjs must bind die to makeDie(NAME) at module scope`,
64
- );
65
- assert.match(
66
- src,
67
- new RegExp(`const NAME = "${name}";`),
68
- `${name}.mjs's NAME must be its own script name, or its refusals misidentify themselves`,
69
- );
70
- }
71
- });
72
-
73
- // The leading newline in makeDie()'s writeSync is documented there as
74
- // "load-bearing, not formatting", and nothing pinned it: dropping it left all
75
- // 640 tests green (measured). Every existing refusal assertion matches
76
- // line-anchored against stderr that carries no concurrently-draining child
77
- // output — which is the exact condition the newline exists for, so none of
78
- // them can see it.
79
- //
80
- // Pinned behaviourally rather than as another source regex: the harm is a
81
- // runtime property (the refusal landing mid-line behind a partial line already
82
- // on fd 2), and a regex over the template literal would pin the spelling while
83
- // still proving nothing about what reaches the fd.
84
- test("die()'s refusal starts its own line even when a partial line is already on fd 2", () => {
85
- const dir = tempDir("arg-die-");
86
- writeFileSync(join(dir, "arg.mjs"), readFileSync(ARG_MODULE));
87
- writeFileSync(join(dir, "run.mjs"), [
88
- 'import { writeSync } from "node:fs";',
89
- 'import { makeDie } from "./arg.mjs";',
90
- 'writeSync(2, "forwarded child stderr with no trailing newline");',
91
- 'makeDie("probe")("refused");',
92
- "",
93
- ].join("\n"));
94
-
95
- const r = spawnSync(process.execPath, [join(dir, "run.mjs")], { encoding: "utf8" });
96
- assert.equal(r.status, 2, r.stderr);
97
- assert.match(r.stderr, /^probe: refused$/m);
98
- });
99
-
100
- // ── #299/#328: the guard around die()'s own writeSync, EXECUTED ───────────
101
- //
102
- // makeDie()'s try/catch exists because fd 2 goes non-blocking once enough
103
- // forwarded child stderr is queued on a pipe: writeSync then throws EAGAIN,
104
- // and uncaught that throw skips process.exit(2), leaving Node's default exit
105
- // 1. For ci-state.mjs the inversion is not a confusing failure but a WRONG
106
- // ANSWER — its own vocabulary spends 1 on "gate not satisfied", so a tool that
107
- // could not read reads as a legitimate verdict the fleet then gates on.
108
- //
109
- // candidates.test.mjs already pins the guard's source SHAPE, and that pin is
110
- // deterministic — but it is a text pin, and it stops at `buf = buf.subarray(writeSync(2, buf));`.
111
- // It says nothing about what the catch does or whether the exit below still
112
- // runs: `catch { process.exit(1); }` satisfies it (measured, green) and is the
113
- // whole defect back. Nothing in this repo EXECUTED the catch until here.
114
- //
115
- // Two tests, because neither covers the other and only one of them works on
116
- // every platform — see each for its own measurements.
117
-
118
- test("die() keeps exit 2 when its own writeSync throws — the guard executed, not lifted", () => {
119
- // The write is made to fail deterministically instead of by racing a pipe:
120
- // fd 2 is closed, so writeSync throws EBADF. A different errno from the
121
- // EAGAIN in the field, the same and only thing die() promises about it — the
122
- // message may be lost, the exit code may not.
123
- //
124
- // Measured on darwin: guarded, exit 2; with the try/catch reverted, exit 1.
125
- // That is the #299 inversion itself, reproduced without the race, so this is
126
- // the assertion that discriminates on a machine where EAGAIN never fires.
127
- const dir = tempDir("arg-die-throw-");
128
- writeFileSync(join(dir, "arg.mjs"), readFileSync(ARG_MODULE));
129
- writeFileSync(join(dir, "run.mjs"), [
130
- 'import { closeSync } from "node:fs";',
131
- 'import { makeDie } from "./arg.mjs";',
132
- "closeSync(2);",
133
- 'makeDie("probe")("refused");',
134
- "",
135
- ].join("\n"));
136
-
137
- const r = spawnSync(process.execPath, [join(dir, "run.mjs")], { encoding: "utf8" });
138
- // No stderr to quote in the message — the fd this process would report on is
139
- // the one the test closed.
140
- assert.equal(r.status, 2, `exit ${r.status}: die()'s writeSync threw and took the exit code with it`);
141
- });
142
-
143
- // die()'s EAGAIN retry loop resumes short writes and waits out transient
144
- // backpressure, but #889's loop originally had no cap: a stderr reader that
145
- // stays open but never drains — not just a slow one — left writeSync
146
- // throwing EAGAIN forever, so process.exit(2) never ran and the guarantee
147
- // this file exists to keep was traded for an indefinite hang.
148
- // MAX_EAGAIN_RETRIES bounds it: past the cap the loop gives up on the
149
- // message and falls through to exit 2 anyway, same as a non-EAGAIN error
150
- // already did.
151
- //
152
- // Reproduced with a real non-blocking pipe, not a mock: fcntl sets O_NONBLOCK
153
- // on the write end before the child ever touches it, so the OS — not a stub
154
- // — is what throws EAGAIN. The read end is held open but never read, which is
155
- // the case this pins: closing it instead would make every write EPIPE, a
156
- // different (already-handled) failure this loop's cap is not needed for.
157
- test("die() exits 2 within a bound even when stderr is a saturated pipe whose reader never drains — #889's retry cap", (t) => {
158
- if (spawnSync("python3", ["-c", ""]).status !== 0) return t.skip("needs python3");
159
- const dir = tempDir("arg-die-stall-");
160
- writeFileSync(join(dir, "arg.mjs"), readFileSync(ARG_MODULE));
161
- writeFileSync(join(dir, "run.mjs"), [
162
- 'import { makeDie } from "./arg.mjs";',
163
- 'makeDie("probe")("refused");',
164
- "",
165
- ].join("\n"));
166
-
167
- const harness = [
168
- "import fcntl, os, subprocess, sys, time",
169
- "r, w = os.pipe()",
170
- "fcntl.fcntl(w, fcntl.F_SETFL, fcntl.fcntl(w, fcntl.F_GETFL) | os.O_NONBLOCK)",
171
- "try:",
172
- " while True:",
173
- " os.write(w, b'x' * 65536)",
174
- "except BlockingIOError:",
175
- " pass",
176
- "start = time.time()",
177
- "proc = subprocess.Popen(sys.argv[1:], stderr=w, stdout=subprocess.DEVNULL)",
178
- "os.close(w)",
179
- "try:",
180
- " code = proc.wait(timeout=5)",
181
- "except subprocess.TimeoutExpired:",
182
- " proc.kill()",
183
- " proc.wait()",
184
- " print('TIMEOUT')",
185
- " sys.exit(1)",
186
- "print(f'EXIT={code} ELAPSED={time.time() - start:.3f}')",
187
- ].join("\n");
188
-
189
- const r = spawnSync("python3", ["-c", harness, process.execPath, join(dir, "run.mjs")], { encoding: "utf8" });
190
- assert.match(
191
- r.stdout,
192
- /^EXIT=2 ELAPSED=\d/m,
193
- `die() must exit 2 within the bound against a permanently saturated pipe; got stdout=${r.stdout} stderr=${r.stderr}`,
194
- );
195
- });
196
-
197
- // How large a first write must be to come back SHORT from the fd a spawnSync
198
- // child sees as stderr. That fd is a Unix SOCKET on both platforms (fstat:
199
- // isSocket()), and what one non-blocking write to it takes differs. darwin's
200
- // is 65,536 bytes, every time. Linux has a floor and no ceiling: a write at or
201
- // under 146,176 bytes went through whole in every trial, and past it one
202
- // usually takes exactly 146,176 — but the parent drains the socket while the
203
- // write is still in the kernel, so a write that races a quick enough reader
204
- // goes through WHOLE at any size (measured for #1730; ci-state.test.mjs
205
- // carries the table).
206
- // #1722 sized this fixture against 584,704, the largest first write in its
207
- // own sample, and that was never a bound: on CI a 2 MiB first write has gone
208
- // through whole, on main among other branches
209
- // (https://github.com/feigi/fleet-plugin/actions/runs/36019414829).
210
- // So no size makes one spawn's short write certain, and this one is not what
211
- // the tests rely on for it — SHORT_WRITE_ATTEMPTS is. 2 MiB stays because it
212
- // is the size CI's whole-write rate was measured at, and it stays under the
213
- // 8 MiB maxBuffer the probes spawn with.
214
- const SHORT_WRITE_BYTES = 2 * 1024 * 1024;
215
- // What the fixture guards compare against: the floor above, measured and
216
- // independent of SHORT_WRITE_BYTES (#1722) — a guard compared against the
217
- // constant a fixture is built from can never be false. A payload at or under
218
- // it goes out in one write on Linux however it is written, so a probe that
219
- // small could never short-write there at all. Same name and number as
220
- // ci-state.test.mjs's own constant, which carries the measurement.
221
- const LINUX_FIRST_WRITE_BYTES = 146_176;
222
- // How many spawns a probe gets to see its first write come back short. A whole
223
- // first write on Linux is the race above, not a defect, so the probe is run
224
- // again rather than failed on it. The cap is what keeps the short-write
225
- // assertion able to fail: an fd that no longer short-writes at all — a Node
226
- // release that initialises streams blocking, say — goes through whole on
227
- // every spawn, and the test still reds, after this many.
228
- const SHORT_WRITE_ATTEMPTS = 10;
229
-
230
- // Spawns a #1548 probe until the first write it recorded came back short, at
231
- // most SHORT_WRITE_ATTEMPTS times, and returns that last spawn and its record.
232
- // Only a whole first write is retried: anything else — a short write, EAGAIN,
233
- // a failed write, a probe that died before recording — is the test's own to
234
- // judge, so it stops there too. The record is removed before each spawn so a
235
- // probe that dies cannot be judged on the previous spawn's numbers.
236
- function spawnUntilShortWrite(runScript, recordPath) {
237
- for (let attempts = 1; ; attempts++) {
238
- rmSync(recordPath, { force: true });
239
- const r = spawnSync(process.execPath, [runScript], { encoding: null, maxBuffer: 8 * 1024 * 1024 });
240
- const record = existsSync(recordPath) ? JSON.parse(readFileSync(recordPath, "utf8")) : undefined;
241
- if (!record || record.firstWriteBytes !== record.payloadBytes || attempts === SHORT_WRITE_ATTEMPTS) {
242
- return { r, record, attempts };
243
- }
244
- }
245
- }
246
-
247
- // ── #1548: die()'s writeSync loop delivers the FULL message, EXECUTED ────
248
- //
249
- // The retry-cap test above only proves the loop gives up in time against a
250
- // pipe that never drains at all; it says nothing about what a loop that DOES
251
- // keep draining actually delivers. #889's source-shape pin has the same gap,
252
- // and it is not candidates.mjs that holds it: the pin lives in
253
- // candidates.test.mjs and matches arg.mjs's own source, read through that
254
- // file's ARG_MODULE. candidates.mjs only CALLS die() — makeDie(NAME) moved
255
- // the shape out of it in #367, as the comment sitting beside that pin in
256
- // candidates.test.mjs records. A mutant that collapses the whole while loop
257
- // to one bare `writeSync(2, buf)` still matches a pin anchored on the try
258
- // block's shape, and a short write from that single call would silently
259
- // truncate the message with nothing here to catch it.
260
- //
261
- // fd 2's non-blocking state is forced deterministically, no fcntl or python3
262
- // needed: `console.error("")` lazily initialises Node's own stream object for
263
- // fd 2, and that initialisation is what puts a pipe fd into O_NONBLOCK — the
264
- // exact mechanism ci-state.mjs's own vlog relies on. Once fd 2
265
- // is non-blocking, a single writeSync of a buffer larger than one pipe buffer
266
- // SHORT-WRITES rather than blocking until spawnSync's reader drains it —
267
- // always on darwin, and on Linux on all but the spawns that lose the race
268
- // SHORT_WRITE_ATTEMPTS exists for.
269
- //
270
- // Neither half of that precondition shows up in the delivered bytes, so both
271
- // are ASSERTED here rather than assumed. A fixture that stopped outgrowing
272
- // one pipe buffer, a Node release that initialises streams blocking, or a
273
- // maintainer swapping `console.error("")` for a direct `writeSync(2, "\n")`
274
- // would each retire this pin silently — measured against that last shape,
275
- // one write took the whole payload and the collapsed-loop mutant passed. So
276
- // the fixture records what its own first write returned and the test asserts
277
- // it came back SHORT on one of its spawns, the same standard
278
- // ci-state.test.mjs holds its pipe fixtures to when it asserts they still
279
- // outgrow the buffer.
280
- //
281
- // die()'s own catch swallows the message but never the exit code, so exit 2
282
- // is not what discriminates the loop from a bare call — both reach it. What
283
- // discriminates them is whether every byte after the first short write ever
284
- // arrives: a bare call stops at the first short write, the loop resumes from
285
- // writeSync's own return value until the buffer is empty or the retry cap
286
- // gives up, and spawnSync's default draining is fast enough that the cap is
287
- // never the limiting factor here (measured: every run delivered the message
288
- // whole).
289
- test("die() resumes from a genuine short write and delivers the full message, not just the first pipe buffer", (t) => {
290
- const dir = tempDir("arg-die-short-");
291
- // The fixture embeds the message, so this is the largest dir this file
292
- // creates; reaped here the way staleness.test.mjs reaps its own repos.
293
- t.after(() => rmSync(dir, { recursive: true, force: true }));
294
- writeFileSync(join(dir, "arg.mjs"), readFileSync(ARG_MODULE));
295
- const msg = "x".repeat(SHORT_WRITE_BYTES);
296
- // die()'s own write, whole: its leading newline, the bound name, the message.
297
- const expected = Buffer.from(`\nprobe: ${msg}\n`);
298
- const firstWrite = join(dir, "first-write.json");
299
- writeFileSync(join(dir, "run.mjs"), [
300
- 'import { writeFileSync, writeSync } from "node:fs";',
301
- 'import { makeDie } from "./arg.mjs";',
302
- '// Lazily touching fd 2 through console.error puts it in O_NONBLOCK.',
303
- 'console.error("");',
304
- '// Measure that state before die() runs instead of trusting it: with fd 2',
305
- '// non-blocking this comes back SHORT, and with fd 2 blocking it takes',
306
- '// every byte in this one call. EAGAIN is recorded as 0 — a blocking fd',
307
- '// never raises it. The unwritten remainder is deliberately never retried,',
308
- '// so stderr is the newline console.error printed, exactly the recorded',
309
- "// count of filler, then die()'s own write and nothing else.",
310
- `const filler = Buffer.alloc(${expected.length}, 0x70);`,
311
- "let firstWriteBytes;",
312
- "try {",
313
- " firstWriteBytes = writeSync(2, filler);",
314
- "} catch (e) {",
315
- ' firstWriteBytes = e.code === "EAGAIN" ? 0 : -1;',
316
- "}",
317
- `writeFileSync(${JSON.stringify(firstWrite)}, JSON.stringify({ payloadBytes: filler.length, firstWriteBytes }));`,
318
- `makeDie("probe")(${JSON.stringify(msg)});`,
319
- "",
320
- ].join("\n"));
321
-
322
- const { r, record, attempts } = spawnUntilShortWrite(join(dir, "run.mjs"), firstWrite);
323
- assert.equal(r.status, 2, `die() must still exit 2: stderr had ${r.stderr?.length} bytes`);
324
- // Guarded on the size of the write die() has to make, not on the bytes that
325
- // arrived: a truncated delivery is itself about one buffer long, so a guard
326
- // over the captured stderr would fire on a real defect and blame the
327
- // fixture for it — the trap ci-state.test.mjs documents above its own
328
- // stderr-completeness pin.
329
- assert.ok(
330
- expected.length > LINUX_FIRST_WRITE_BYTES,
331
- `fixture no longer outgrows one write on Linux (${expected.length} bytes, floor ${LINUX_FIRST_WRITE_BYTES}), so this test would pass without proving anything`,
332
- );
333
- const { payloadBytes, firstWriteBytes } = record;
334
- assert.ok(
335
- firstWriteBytes >= 0 && firstWriteBytes < payloadBytes,
336
- `fd 2 took all ${payloadBytes} bytes in one write on each of ${attempts} spawns, so nothing short-wrote and a collapsed loop would pass this test too (last first write returned ${firstWriteBytes})`,
337
- );
338
- // Reverting the loop to one bare writeSync leaves die()'s own write stopped
339
- // at its first short write (measured: one pipe buffer's worth arrived in
340
- // place of the whole message), so this is false on that shape and true only
341
- // once every retried write lands.
342
- assert.ok(
343
- r.stderr.subarray(1 + firstWriteBytes).equals(expected),
344
- `die() dropped bytes across a short write: got ${r.stderr.length - 1 - firstWriteBytes}, expected ${expected.length}`,
345
- );
346
- assert.equal(
347
- r.stderr.length,
348
- 1 + firstWriteBytes + expected.length,
349
- `stderr must be the newline console.error printed, the filler that landed, then die()'s message and nothing else`,
350
- );
351
- });
352
-
353
- // ── #1549: writeAll(), the one loop the three callers now share ──────────
354
- //
355
- // die() here, staleness.mjs's verdict() and ci-state.mjs's verdict writes each
356
- // hand-rolled this loop, held in step by a comment reading "mirrors emit()"
357
- // and by nothing executable — and they HAD already drifted: emit() was the one
358
- // that never grew #889's retry cap, so the copy nobody re-read was the copy
359
- // that could hang. The loop is arg.mjs's writeAll() now, pinned ONCE here at
360
- // its definition rather than as three near-identical regexes in three files.
361
- //
362
- // The shape pin and the executed tests below are not redundant. The pin
363
- // cannot see what the loop DELIVERS. The executed tests cannot see a loop
364
- // rewritten behaviourally-identically but hand-copied back into a caller,
365
- // which is the regression this ticket exists to prevent.
366
- test("writeAll()'s loop consumes writeSync's return value, resets its EAGAIN retry count on progress, and caps the retry — the single definition the three callers share", () => {
367
- const source = stripComments(readFileSync(ARG_MODULE, "utf8"));
368
- // Names the FILE when writeAll is renamed or deleted: the regex alone would
369
- // then fail as an opaque match-against-undefined. The same standard
370
- // ci-state.test.mjs holds its own pin to.
371
- assert.equal(
372
- source.match(/^\s*export function writeAll\(/gm)?.length,
373
- 1,
374
- "arg.mjs declares writeAll() more than once, or not at all — every caller's write loop is meant to be this one definition",
375
- );
376
- assert.match(
377
- source,
378
- /^\s*export function writeAll\(fd, text\) \{\s*^\s*let buf = Buffer\.from\(text\);\s*^\s*let retries = 0;\s*^\s*while \(buf\.length\) \{\s*^\s*try \{\s*^\s*const written = writeSync\(fd, buf\);\s*^\s*if \(written > 0\) retries = 0;\s*^\s*buf = buf\.subarray\(written\);/m,
379
- );
380
- // The cap and the wait, which the fragment above stops short of — #889's
381
- // whole content, and the clause emit() was missing before #1549 merged the
382
- // three copies. Measured: collapsing the loop to a bare `writeSync(fd,
383
- // Buffer.from(text))` reds the regex above while leaving candidates.test.mjs's
384
- // die() wiring pin GREEN, and hoisting die()'s template out of its try reds
385
- // that one while leaving these green — the two pins discriminate different
386
- // defects and neither substitutes for the other.
387
- assert.match(
388
- source,
389
- /^\s*if \(e\.code !== "EAGAIN" \|\| \+\+retries > MAX_EAGAIN_RETRIES\) return false;\s*^\s*Atomics\.wait\(IDLE, 0, 0, 1\);/m,
390
- );
391
- });
392
-
393
- // The half that a suite feeding this function only FAILING fds can never pin:
394
- // what writeAll must ACCEPT. Its false return is a positive claim that bytes
395
- // were lost, and staleness.mjs's verdict() turns that claim straight into a
396
- // could-not-check downgrade and exit 2 — so a writeAll that answered false
397
- // after a merely SHORT write would convert healthy verdicts into failures on
398
- // exactly the saturated-pipe caller the loop was written for. A short write is
399
- // the ordinary case on a non-blocking fd, not an error, and nothing else in
400
- // this suite says so: every other test here asserts the BYTES arrive, which a
401
- // loop returning a wrong `false` would still satisfy.
402
- //
403
- // Same fixture as the die() short-write test above — console.error puts fd 2
404
- // in O_NONBLOCK, and the first write's own return value is recorded to prove
405
- // the fd really did short-write rather than take everything at once, retried
406
- // the same way when a spawn loses the race.
407
- test("writeAll() returns true and delivers every byte across a genuine short write — the case it must never refuse", (t) => {
408
- const dir = tempDir("arg-writeall-short-");
409
- t.after(() => rmSync(dir, { recursive: true, force: true }));
410
- writeFileSync(join(dir, "arg.mjs"), readFileSync(ARG_MODULE));
411
- const payload = "w".repeat(SHORT_WRITE_BYTES);
412
- const expected = Buffer.from(payload);
413
- const result = join(dir, "result.json");
414
- writeFileSync(join(dir, "run.mjs"), [
415
- 'import { writeFileSync, writeSync } from "node:fs";',
416
- 'import { writeAll } from "./arg.mjs";',
417
- '// Lazily touching fd 2 through console.error puts it in O_NONBLOCK.',
418
- 'console.error("");',
419
- `const filler = Buffer.alloc(${expected.length}, 0x70);`,
420
- "let firstWriteBytes;",
421
- "try {",
422
- " firstWriteBytes = writeSync(2, filler);",
423
- "} catch (e) {",
424
- ' firstWriteBytes = e.code === "EAGAIN" ? 0 : -1;',
425
- "}",
426
- `const ok = writeAll(2, ${JSON.stringify(payload)});`,
427
- `writeFileSync(${JSON.stringify(result)}, JSON.stringify({ payloadBytes: filler.length, firstWriteBytes, ok }));`,
428
- "",
429
- ].join("\n"));
430
-
431
- const { r, record, attempts } = spawnUntilShortWrite(join(dir, "run.mjs"), result);
432
- assert.equal(r.status, 0, `the probe itself failed: ${r.stderr?.subarray(0, 400)}`);
433
- assert.ok(
434
- expected.length > LINUX_FIRST_WRITE_BYTES,
435
- `fixture no longer outgrows one write on Linux (${expected.length} bytes, floor ${LINUX_FIRST_WRITE_BYTES}), so this test would pass without proving anything`,
436
- );
437
- const { payloadBytes, firstWriteBytes, ok } = record;
438
- assert.ok(
439
- firstWriteBytes >= 0 && firstWriteBytes < payloadBytes,
440
- `fd 2 took all ${payloadBytes} bytes in one write on each of ${attempts} spawns, so nothing short-wrote and this proves nothing about resuming (last first write returned ${firstWriteBytes})`,
441
- );
442
- assert.equal(
443
- ok,
444
- true,
445
- "writeAll reported a lost write after a survivable short write — verdict() would downgrade a healthy verdict to could-not-check on this",
446
- );
447
- assert.ok(
448
- r.stderr.subarray(1 + firstWriteBytes).equals(expected),
449
- `writeAll dropped bytes across a short write: got ${r.stderr.length - 1 - firstWriteBytes}, expected ${expected.length}`,
450
- );
451
- });
452
-
453
- // The other direction, and the one verdict()'s downgrade is actually built on:
454
- // a write that is genuinely lost has to come back false, or a caller that
455
- // promised "a failed write is a could-not-check" silently reports success.
456
- test("writeAll() returns false when the write is genuinely lost, not merely delayed", (t) => {
457
- const dir = tempDir("arg-writeall-lost-");
458
- t.after(() => rmSync(dir, { recursive: true, force: true }));
459
- writeFileSync(join(dir, "arg.mjs"), readFileSync(ARG_MODULE));
460
- writeFileSync(join(dir, "run.mjs"), [
461
- 'import { closeSync } from "node:fs";',
462
- 'import { writeAll } from "./arg.mjs";',
463
- "// fd 2 closed, so writeSync throws EBADF — a non-EAGAIN errno, the shape",
464
- "// that loses the bytes outright rather than the one worth waiting out.",
465
- "closeSync(2);",
466
- 'const ok = writeAll(2, "this cannot land");',
467
- "process.stdout.write(JSON.stringify({ ok }));",
468
- "",
469
- ].join("\n"));
470
-
471
- const r = spawnSync(process.execPath, [join(dir, "run.mjs")], { encoding: "utf8" });
472
- assert.equal(r.status, 0, `the probe itself failed: ${r.stdout}`);
473
- assert.deepEqual(
474
- JSON.parse(r.stdout),
475
- { ok: false },
476
- "writeAll must report a lost write rather than swallow it — verdict()'s could-not-check downgrade is built on this return",
477
- );
478
- });
479
-
480
- // Read out of arg.mjs rather than written down twice. The test below claims
481
- // its transfer crosses this cap; a cap that moved and a fixture that did not
482
- // must red there rather than pass quietly on a payload that no longer
483
- // reaches it.
484
- const MAX_EAGAIN_RETRIES = Number(
485
- stripComments(readFileSync(ARG_MODULE, "utf8")).match(/^const MAX_EAGAIN_RETRIES = (\d+);/m)?.[1],
486
- );
487
-
488
- // #1549 regression: retries must reset on forward progress, or the cap bounds
489
- // CUMULATIVE EAGAINs across the whole transfer instead of a no-progress
490
- // stall. A reader that is merely slow — alive, busy, but still draining —
491
- // must get its full payload; only a reader that never drains at all should
492
- // ever hit the cap.
493
- //
494
- // Reproduced with a real O_NONBLOCK pipe, not a mock: the child inherits the
495
- // write end (via `pass_fds`, not fd 2, so writeAll's own fd argument is
496
- // exercised directly), and the parent drains it a page at a time, reading
497
- // ONLY from a pipe FIONREAD reports FULL. That pacing is what makes the
498
- // stall count a measurement rather than a hope (#1689): a full pipe the
499
- // writer still holds payload for is an EAGAIN it has already taken, so every
500
- // paced read is one CONFIRMED stall. The payload is sized off the pipe's own
501
- // measured capacity — capacity, plus a page for each stall wanted — so how
502
- // many stalls the transfer takes is arithmetic, not a property of how this
503
- // machine happened to schedule the two processes.
504
- //
505
- // STALLS is asserted past MAX_EAGAIN_RETRIES because that is what makes the
506
- // green mean anything. The first version of this test paced its reader with
507
- // 1ms sleeps and asserted only the delivered bytes; it did kill the mutant
508
- // (measured 10/10 on darwin), but the number of stalls it produced was an
509
- // accident of the machine and nothing looked at it — a bigger pipe, a faster
510
- // reader or a cheaper Atomics.wait could have dropped the transfer under the
511
- // cap and left it passing while pinning nothing. Below the cap, a retry
512
- // counter that resets and one that accumulates deliver the same payload.
513
- //
514
- // Nothing here starves the writer: the reader reads the instant FIONREAD
515
- // says full, with no sleep in between, and the worst gap between paced reads
516
- // is REPORTED rather than asserted — a green run already implies every stall
517
- // stayed under the cap, so the number's job is to separate "the reset is
518
- // gone" from "this machine starved the writer past the cap" when this reds.
519
- // Measured 3.1ms against a 200ms budget.
520
- //
521
- // The reader frees a PAGE per read, not a token 256 bytes, and that is
522
- // load-bearing on both platforms: a write of at most PIPE_BUF — 512 on
523
- // darwin, 4096 on Linux, per each one's limits.h — is ATOMIC, so a writer
524
- // holding a tail that small takes EAGAIN rather than a partial write
525
- // whenever the reader has freed less room than the tail needs. At 256-byte
526
- // reads the two deadlock at the end of the payload, measured on darwin at
527
- // exactly `payload - capacity - 256` bytes delivered, 8/8 runs — the writer
528
- // spending its whole cap on a reader that is itself waiting for a pipe that
529
- // can never fill again. A page always leaves room for an atomic tail.
530
- //
531
- // Measured against the pre-fix shape (`if (written > 0) retries = 0;`
532
- // deleted): ok:false at 184-190 confirmed stalls of the 300 this transfer
533
- // takes, around 63% of the payload delivered, 3/3 runs.
534
- test("writeAll() delivers the full payload across more confirmed EAGAIN stalls than MAX_EAGAIN_RETRIES — progress must RESET the retry count, not merely extend it", (t) => {
535
- if (spawnSync("python3", ["-c", ""]).status !== 0) return t.skip("needs python3");
536
- assert.ok(
537
- Number.isFinite(MAX_EAGAIN_RETRIES),
538
- "arg.mjs no longer declares `const MAX_EAGAIN_RETRIES = <digits>;` — this test cannot say what its transfer has to cross",
539
- );
540
- const dir = tempDir("arg-writeall-slowdrain-");
541
- t.after(() => rmSync(dir, { recursive: true, force: true }));
542
- writeFileSync(join(dir, "arg.mjs"), readFileSync(ARG_MODULE));
543
- // Half again the cap: far enough past it that an accumulating counter
544
- // cannot reach the end of the payload, near enough that the whole transfer
545
- // — one 1ms Atomics.wait per stall — still runs in well under a second.
546
- const stallTarget = MAX_EAGAIN_RETRIES + Math.ceil(MAX_EAGAIN_RETRIES / 2);
547
- const chunkBytes = 4096;
548
- writeFileSync(join(dir, "run.mjs"), [
549
- 'import { writeAll } from "./arg.mjs";',
550
- "const [fd, bytes] = process.argv.slice(2).map(Number);",
551
- 'const ok = writeAll(fd, "z".repeat(bytes));',
552
- "process.stdout.write(JSON.stringify({ ok }));",
553
- "",
554
- ].join("\n"));
555
-
556
- const harness = [
557
- "import array, fcntl, os, select, subprocess, sys, termios, time",
558
- "chunk, wanted = int(sys.argv[1]), int(sys.argv[2])",
559
- "r, w = os.pipe()",
560
- "fcntl.fcntl(w, fcntl.F_SETFL, fcntl.fcntl(w, fcntl.F_GETFL) | os.O_NONBLOCK)",
561
- "# Calibrate what this pipe actually holds, then hand it back empty: a",
562
- "# later FIONREAD reading that same number is the writer sitting on a",
563
- "# pipe with nowhere to put its next byte. Measured 65536 on darwin,",
564
- "# which is also Linux's default pipe capacity — but read rather than",
565
- "# assumed, so a platform holding some other amount still buys the number",
566
- "# of stalls this transfer asks for instead of timing out against a level",
567
- "# its pipe never reaches.",
568
- "capacity = 0",
569
- "try:",
570
- " while True:",
571
- " capacity += os.write(w, b'x' * 4096)",
572
- "except BlockingIOError:",
573
- " pass",
574
- "left = capacity",
575
- "while left:",
576
- " left -= len(os.read(r, left))",
577
- "payload = capacity + chunk * wanted",
578
- "proc = subprocess.Popen(sys.argv[3:] + [str(w), str(payload)], pass_fds=(w,), stdout=subprocess.PIPE)",
579
- "os.close(w)",
580
- "pending = array.array('i', [0])",
581
- "got, stalls, worst_gap, last_read, done = 0, 0, 0.0, None, False",
582
- "# 20s against a transfer measured at 0.5s. It bounds the one shape this",
583
- "# harness cannot assert its way out of: a platform whose pipe never",
584
- "# reports the calibrated level again, leaving the reader waiting for a",
585
- "# fullness that cannot arrive. That exits DRAIN_TIMEOUT — loud, and not",
586
- "# mistakable for a delivered payload.",
587
- "deadline = time.time() + 20",
588
- "while time.time() < deadline:",
589
- " paced = False",
590
- " if got + capacity < payload:",
591
- " # The writer still holds bytes that cannot fit, so a full pipe",
592
- " # here is an EAGAIN it has already taken. Read only from one.",
593
- " full = exited = False",
594
- " while time.time() < deadline:",
595
- " fcntl.ioctl(r, termios.FIONREAD, pending)",
596
- " if pending[0] >= capacity:",
597
- " full = True",
598
- " break",
599
- " if proc.poll() is not None:",
600
- " exited = True",
601
- " break",
602
- " time.sleep(0.001)",
603
- " if not full and not exited:",
604
- " break",
605
- " paced = full",
606
- " if paced:",
607
- " stalls += 1",
608
- " if not select.select([r], [], [], 1)[0]:",
609
- " continue",
610
- " piece = os.read(r, chunk)",
611
- " now = time.time()",
612
- " if paced and last_read is not None and now - last_read > worst_gap:",
613
- " worst_gap = now - last_read",
614
- " last_read = now",
615
- " if not piece:",
616
- " done = True",
617
- " break",
618
- " got += len(piece)",
619
- "if not done:",
620
- " proc.kill()",
621
- " proc.communicate()",
622
- " print('DRAIN_TIMEOUT')",
623
- " sys.exit(1)",
624
- "try:",
625
- " out, _ = proc.communicate(timeout=30)",
626
- "except subprocess.TimeoutExpired:",
627
- " proc.kill()",
628
- " proc.communicate()",
629
- " print('TIMEOUT')",
630
- " sys.exit(1)",
631
- "print(out.decode())",
632
- "print(f'BYTES_RECEIVED={got} PAYLOAD={payload} STALLS={stalls} WORST_GAP_MS={worst_gap * 1000:.1f} CAPACITY={capacity}')",
633
- ].join("\n");
634
-
635
- const r = spawnSync(
636
- "python3",
637
- ["-c", harness, String(chunkBytes), String(stallTarget), process.execPath, join(dir, "run.mjs")],
638
- { encoding: "utf8" },
639
- );
640
- assert.doesNotMatch(
641
- r.stdout,
642
- /TIMEOUT/,
643
- `the transfer never finished: either writeAll hung against a reader that never stopped draining, or (DRAIN_TIMEOUT) the harness never saw the pipe reach the level it calibrated, so it stopped freeing room. ${r.stdout} ${r.stderr}`,
644
- );
645
- const stalls = Number(r.stdout.match(/STALLS=(\d+)/)?.[1]);
646
- const worstGapMs = Number(r.stdout.match(/WORST_GAP_MS=([\d.]+)/)?.[1]);
647
- const received = Number(r.stdout.match(/BYTES_RECEIVED=(\d+)/)?.[1]);
648
- const payloadBytes = Number(r.stdout.match(/PAYLOAD=(\d+)/)?.[1]);
649
- assert.match(
650
- r.stdout,
651
- /\{"ok":true\}/,
652
- `writeAll reported a lost write against a reader that kept draining the whole time — an un-reset retry counter gives up around stall ${MAX_EAGAIN_RETRIES} of the ${stallTarget} this transfer takes, and this one got to ${stalls}. The worst gap between paced reads was ${worstGapMs}ms; past ${MAX_EAGAIN_RETRIES}ms that is this machine starving the writer for longer than the cap, not the reset going missing: ${r.stdout}`,
653
- );
654
- assert.equal(
655
- received,
656
- payloadBytes,
657
- `the reader received ${received} of ${payloadBytes} bytes — writeAll gave up before the slow reader finished draining`,
658
- );
659
- // The green above says nothing unless the transfer really did cross the
660
- // cap: under it, a counter that resets on progress and one that accumulates
661
- // across the whole call deliver the very same payload.
662
- assert.ok(
663
- stalls > MAX_EAGAIN_RETRIES,
664
- `the harness confirmed ${stalls} stalls against a cap of ${MAX_EAGAIN_RETRIES} — an accumulating retry counter survives a transfer that never crosses it, so this pins nothing: ${r.stdout}`,
665
- );
666
- });
667
-
668
- // The three scripts #328 names plus fleet-tick, end to end. Each forwards gh's
669
- // own stderr (execFileSync with no `stdio`, so Node re-emits it through the
670
- // ASYNC process.stderr) and only then refuses through die() — so the flood has
671
- // to come from gh, not from the test, or fd 2 is never the one under pressure.
672
- // That FORWARDS-then-refuses shape is the entry rule for this table, not
673
- // "reaches die()", which every consumer does.
674
- //
675
- // Spelled out rather than derived from CONSUMERS above, because each consumer
676
- // that is absent is absent for its own reason and none of them is "has no
677
- // gh-failure path": candidates carries its own copy of this row already
678
- // (candidates.test.mjs, at the JQ_OVERRIDE that motivated the fix); ledger
679
- // CAPTURES gh's stderr (`stdio: ["ignore", "pipe", "pipe"]` on ledger.mjs's gh
680
- // search call) instead of forwarding it, so fd 2 is never the fd under
681
- // pressure; board LOGS a failed gh and returns null (board.mjs's `tryRun`) rather than refusing, so
682
- // it has no exit 2 to invert in the first place. fleet-tick is here because it
683
- // does forward and does refuse (fleet-tick.mjs's `openPrs`) — measured at 65,613 B
684
- // forwarded and exit 2 — and since #1803 it reaches gh with no argv at all,
685
- // the gh read being the first thing it does that can refuse.
686
- // A consumer added later belongs here deliberately.
687
- const GH_FLOOD = [
688
- { script: "ci-state", argv: ["--pr", "42"] },
689
- { script: "diff-stats", argv: ["--pr", "42"] },
690
- { script: "pr-overlap", argv: ["--a", "5", "--b", "6"] },
691
- { script: "fleet-tick", argv: [] },
692
- ];
693
-
694
- // A `gh` that writes exactly `bytes` to stderr and then fails, so the script
695
- // under test takes its execFileSync catch. The payload is a file the stub
696
- // `cat`s rather than shell-generated, to keep the byte count exact.
697
- function runWithFloodingGh(script, argv, bytes) {
698
- const dir = tempDir("arg-die-flood-");
699
- writeFileSync(join(dir, "flood"), "z".repeat(bytes));
700
- writeExecStub(join(dir, "gh"), `#!/bin/sh\ncat "${join(dir, "flood")}" >&2\nexit 1\n`);
701
- return spawnSync(
702
- process.execPath,
703
- [fileURLToPath(new URL(`./${script}.mjs`, import.meta.url)), ...argv],
704
- { cwd: dir, encoding: "utf8", env: { ...process.env, PATH: `${dir}:${process.env.PATH}` } },
705
- );
706
- }
707
-
708
- for (const { script, argv } of GH_FLOOD) {
709
- test(`${script}.mjs still exits 2 when gh fails behind a stderr larger than the pipe buffer`, () => {
710
- // The row the guard must NOT change. A catch around the write could just as
711
- // easily swallow the refusal on the ordinary path, or return before the
712
- // exit — so the small case pins both halves: the line lands, the code is 2.
713
- // Anchored on the script's own NAME prefix only, not the wording after it,
714
- // so rephrasing a refusal is not this test's business.
715
- const ordinary = runWithFloodingGh(script, argv, 64);
716
- assert.equal(ordinary.status, 2, `expected exit 2 on the ordinary path, got ${ordinary.status}: ${ordinary.stderr}`);
717
- assert.match(ordinary.stderr, new RegExp(`^${script}: `, "m"), `${script}.mjs refused without saying so: ${ordinary.stderr}`);
718
-
719
- // The row that inverted. Platform-bound and therefore a CI gate, not a
720
- // local one: measured on darwin, all four of these still exit 2 with the
721
- // try/catch reverted (4/4) — EAGAIN never fires there, which is why the
722
- // deterministic test above exists.
723
- //
724
- // The Linux rates are #328's, read off that issue's body rather than
725
- // measured here: the #322 review recorded the unfixed inversion per script
726
- // at 5/10, 6/10, 7/10; a second pass at 4/10, 3/10, 0/10 and then 6/10,
727
- // 4/10; a third harness at 1/40, 0/40, 0/40 against a self-validating 32/40
728
- // control. So the unfixed span is 0/10 to 7/10 — one script read 0/10 in a
729
- // pass that read 4/10 and 3/10 for its siblings — and the guard drops all
730
- // three to 0/10 in the passes that measured it. #328's own conclusion is
731
- // that the RATE is machine-dependent and only the MECHANISM is confirmed,
732
- // so a single green Linux run is not evidence the guard is present; the
733
- // deterministic test above is what pins that, on every platform.
734
- //
735
- // candidates.test.mjs's 7/15 unfixed / 0/20 fixed is a DIFFERENT
736
- // experiment — candidates.mjs under JQ_OVERRIDE (#299) — not these scripts
737
- // under a gh stub. The two are not one series; neither figure carries over.
738
- const flooded = runWithFloodingGh(script, argv, 200_000);
739
- assert.ok(
740
- flooded.stderr.length > 60_000,
741
- `gh's forwarded stderr must exceed the pipe buffer or this pins nothing, got ${flooded.stderr.length}`,
742
- );
743
- assert.equal(flooded.status, 2, `expected exit 2 behind ${flooded.stderr.length} B of forwarded stderr, got ${flooded.status}`);
744
- });
745
- }
746
-
747
- // ── #365: a flag name no script reads ────────────────────────────────────────
748
- //
749
- // The guards above answer "was this flag given well?". Nothing answered "was a
750
- // flag given that nothing reads?" — a misspelled name is never looked for, so
751
- // `ci-state.mjs --pr 5 --basee main` compared against the DEFAULT base and
752
- // returned a real, wrong verdict at exit 0/1. The fleet gates PR-green on that
753
- // verdict.
754
- //
755
- // Driven per script rather than only against sweep(), because the unit
756
- // contract below passes just as well with the call site missing: what has to
757
- // hold is that each script REACHES it, with a set that contains the name it
758
- // misspelled. The matrix is spelled out for the same reason CONSUMERS above is
759
- // — a discovered set shrinks silently when a caller drops the call.
760
- //
761
- // candidates.mjs is in the matrix but is NOT a sweep() caller: it refuses
762
- // through its own parseArgs (#173), which additionally rejects a bare
763
- // positional the shared sweep must accept (board.mjs's subcommands are that
764
- // shape). Pinned on the OUTCOME both mechanisms owe — exit 2, the stray named,
765
- // no query — so the row stays honest either way.
766
- const STRAYS = [
767
- { script: "board", argv: ["build", "--ledgerr", "x"], stray: "--ledgerr" },
768
- { script: "candidates", argv: ["--require-labell", "x"], stray: "--require-labell" },
769
- { script: "ci-state", argv: ["--pr", "42", "--basee", "main"], stray: "--basee" },
770
- { script: "diff-stats", argv: ["--pr", "42", "--basee", "main"], stray: "--basee" },
771
- { script: "pr-overlap", argv: ["--a", "5", "--b", "6", "--basee", "main"], stray: "--basee" },
772
- ];
773
-
774
- // A `gh` that records the fact of being called and then fails. Two jobs: it
775
- // keeps a regressed sweep off this repo's live GitHub data, and its receipt
776
- // file is what pins "before any gh call" — assert.doesNotMatch on stderr would
777
- // pass just as well for a script that queried and stayed quiet about it.
778
- function stubGhBin() {
779
- // The prefix holds a space on purpose (#880): this path reaches a shell
780
- // redirect inside the stub, and an unquoted one word-splits on it and
781
- // silently writes no receipt. Baked in here rather than left to the ambient
782
- // `TMPDIR` so every machine runs the hazardous shape, not just one whose
783
- // TMPDIR happens to contain a space.
784
- const dir = tempDir("arg sweep-");
785
- const receipt = join(dir, "gh-was-called");
786
- // `>> "$GH_LOG"`, not the interpolated path: ci-state.test.mjs's GH_STUB
787
- // form, which keeps the path out of the generated script text entirely so
788
- // there is no interpolation left to quote wrongly.
789
- writeExecStub(join(dir, "gh"), `#!/bin/sh\necho "$@" >> "$GH_LOG"\nexit 1\n`);
790
- // The env is built HERE, beside the path it carries. `GH_LOG` is now what
791
- // makes the receipt work at all, so handing callers a ready env is what
792
- // keeps the two from drifting apart — a caller assembling its own would be
793
- // one omission away from reinstating the vacuous pass.
794
- return { dir, receipt, env: { ...process.env, PATH: `${dir}:${process.env.PATH}`, GH_LOG: receipt } };
795
- }
796
-
797
- for (const { script, argv, stray } of STRAYS) {
798
- test(`${script}.mjs refuses the unknown flag ${stray} by name, before any query`, () => {
799
- const { dir, receipt, env } = stubGhBin();
800
- const r = spawnSync(
801
- process.execPath,
802
- [fileURLToPath(new URL(`./${script}.mjs`, import.meta.url)), ...argv],
803
- { cwd: dir, encoding: "utf8", env },
804
- );
805
- assert.equal(r.status, 2, `expected exit 2, got ${r.status}: ${r.stderr}`);
806
- assert.ok(
807
- r.stderr.includes(stray),
808
- `${script}.mjs refused without naming ${stray} — a caller cannot fix a typo it is not shown: ${r.stderr}`,
809
- );
810
- // `if` rather than assert.ok(!existsSync(...), msg): a template message is
811
- // built eagerly, so reading the receipt inline throws ENOENT on the PASSING
812
- // path — the failure this file hit on its first run.
813
- if (existsSync(receipt)) assert.fail(`${script}.mjs reached gh before refusing ${stray}: ${readFileSync(receipt, "utf8")}`);
814
- });
815
- }
816
-
817
- // ── #880: the receipt is only evidence if the stub can WRITE it ───────────
818
- //
819
- // Every assertion in the loop above reads the receipt's NON-EXISTENCE, which
820
- // is the one direction a BROKEN stub satisfies too. The stub interpolated its
821
- // path into an unquoted redirect, so under a `TMPDIR` holding a space the
822
- // shell redirected into the path's FIRST word and handed the remainder to
823
- // `echo` as an argument: the receipt was never created, and all five rows
824
- // above passed BECAUSE the stub misfired rather than because the script
825
- // refused. Measured against the byte-identical template — `gh` ran, exited 1,
826
- // receipt absent.
827
- //
828
- // This is the must-ACCEPT half, and the only test here that would red on that
829
- // bug: feed the stub the one input it must record, and prove it recorded.
830
- // Deliberately spaced via `stubGhBin()`'s own prefix rather than the ambient
831
- // `TMPDIR`, so the quoting stays pinned on a machine whose TMPDIR is clean.
832
- //
833
- // It also pins the ENV threading, which is the new failure mode the `$GH_LOG`
834
- // form introduces in place of the old one: with `GH_LOG` unset the redirect
835
- // is `>> ""`, which writes no receipt and reds nothing else in this file
836
- // (measured). A caller that builds its own env and omits the variable
837
- // reintroduces the vacuous pass in a new spelling, so `stubGhBin()` hands the
838
- // env back already carrying it and this test fails if that stops being true.
839
- test("#880: the gh stub records a real call, from a directory whose path holds a space", () => {
840
- const { dir, receipt, env } = stubGhBin();
841
- assert.match(dir, / /, "fixture: the stub's directory must hold a space, or this pins nothing");
842
- assert.equal(existsSync(receipt), false, "fixture: the receipt must not pre-exist, or its presence proves nothing");
843
-
844
- const r = spawnSync("sh", ["-c", "gh pr view 42"], { cwd: dir, encoding: "utf8", env });
845
-
846
- assert.equal(r.status, 1, `fixture: the stub must be the gh on PATH, and it refuses: ${r.stderr}`);
847
- assert.equal(
848
- existsSync(receipt),
849
- true,
850
- "the stub swallowed a real `gh` call — every \"before any gh call\" pin above is passing vacuously",
851
- );
852
- assert.equal(
853
- readFileSync(receipt, "utf8"),
854
- "pr view 42\n",
855
- "and it records the argv, so a call that was reached can be named rather than merely counted",
856
- );
857
- });
858
-
859
- // ── #878: a required argument that must be a PR number ───────────────────
860
- //
861
- // #840 closed this in ci-state.mjs alone. The identical shape stayed live in
862
- // its siblings, and the class is NOT bounded by the `arg("pr")` spelling —
863
- // pr-overlap.mjs reads `--a`/`--b`, which is how a sweep for the flag NAME
864
- // missed it. Measured on the pre-fix tree against a `gh` that ANSWERS, the way
865
- // a real one does for a branch ref: `diff-stats.mjs --pr abc` reached
866
- // `gh pr view abc` and printed `{"pr":null,…}` at exit 0, and `pr-overlap.mjs
867
- // --a abc --b def` printed `{"a":null,"b":null,…}` at exit 0 carrying a real
868
- // `signal: "files"` verdict. Each payload's only identifying field was built
869
- // with `Number()`, and `JSON.stringify(NaN)` is `null`.
870
- //
871
- // Driven per script, for the reason the matrices above are: numArg()'s own
872
- // verdicts are covered by shared-refusal.test.mjs, and that unit contract
873
- // passes just as well with a call site left on plain arg(). What has to hold
874
- // is that each script REACHES it.
875
- //
876
- // The receipt is the load-bearing assertion, not the exit code. Exit 2, an
877
- // empty stdout and a matching stderr line are each reproducible by a LATER
878
- // guard: downgrade this one and the script runs on to a gh that fails, whose
879
- // die() reproduces all three. Only a refusal reached BEFORE the query can show
880
- // gh was never asked — and reaching gh is half the harm here, since it can
881
- // answer for the branch the value names.
882
- //
883
- // Both anchors per script, separately: a guard that loses `$` still matches
884
- // "42x" on its digit prefix and one that loses `^` still matches "x42" on its
885
- // suffix, so neither mutant survives the pair. ci-state.mjs's rows are its
886
- // own test file's (`a non-numeric --pr refuses before any query`); these are
887
- // the two scripts #840 left open, plus ci-state.mjs once for the routing.
888
- const NON_NUMERIC = [
889
- { script: "ci-state", argv: ["--pr", "abc"], flag: "--pr" },
890
- { script: "diff-stats", argv: ["--pr", "abc"], flag: "--pr" },
891
- { script: "diff-stats", argv: ["--pr", "42x"], flag: "--pr" },
892
- { script: "diff-stats", argv: ["--pr", "x42"], flag: "--pr" },
893
- // The second flag, given a good first one: pr-overlap.mjs refuses each on
894
- // its own name rather than dumping the usage line that names both.
895
- { script: "pr-overlap", argv: ["--a", "abc", "--b", "6"], flag: "--a" },
896
- { script: "pr-overlap", argv: ["--a", "5", "--b", "def"], flag: "--b" },
897
- { script: "pr-overlap", argv: ["--a", "5", "--b", "6x"], flag: "--b" },
898
- { script: "pr-overlap", argv: ["--a", "x5", "--b", "6"], flag: "--a" },
899
- ];
900
-
901
- for (const { script, argv, flag } of NON_NUMERIC) {
902
- test(`${script}.mjs refuses a non-numeric ${flag} (${argv.join(" ")}) by name, before any query`, () => {
903
- const { dir, receipt, env } = stubGhBin();
904
- const r = spawnSync(
905
- process.execPath,
906
- [fileURLToPath(new URL(`./${script}.mjs`, import.meta.url)), ...argv],
907
- { cwd: dir, encoding: "utf8", env },
908
- );
909
- assert.equal(r.status, 2, `expected exit 2, got ${r.status}: ${r.stderr}`);
910
- assert.match(
911
- r.stderr,
912
- new RegExp(`${flag} needs a number`),
913
- `${script}.mjs refused without naming ${flag} as the non-numeric one: ${r.stderr}`,
914
- );
915
- assert.equal(r.stdout.trim(), "", `a refusal ships no payload, and stdout reads ${r.stdout}`);
916
- if (existsSync(receipt)) assert.fail(`${script}.mjs reached gh before refusing ${flag}: ${readFileSync(receipt, "utf8")}`);
917
- });
918
- }
919
-
920
- // A `gh` that ANSWERS both shapes these two scripts ask for, so the accepting
921
- // path can be measured rather than inferred from a refusal that did not
922
- // happen. `$2` is the subcommand (`gh pr view <n> --json …`, `gh pr diff <n>
923
- // --name-only`), the same positional pr-overlap.test.mjs's own stub keys on.
924
- function stubGhAnswering() {
925
- const dir = tempDir("arg num-");
926
- const receipt = join(dir, "gh-was-called");
927
- writeExecStub(
928
- join(dir, "gh"),
929
- '#!/bin/sh\necho "$@" >> "$GH_LOG"\ncase "$2" in\n' +
930
- " view) echo '{\"files\":[{\"path\":\"a.ts\",\"additions\":1,\"deletions\":0}],\"changedFiles\":1}' ;;\n" +
931
- " diff) echo src/shared.ts ;;\n" +
932
- " *) exit 1 ;;\n" +
933
- "esac\n",
934
- );
935
- return { dir, receipt, env: { ...process.env, PATH: `${dir}:${process.env.PATH}`, GH_LOG: receipt } };
936
- }
937
-
938
- const runAnswering = (script, argv, env, dir) =>
939
- spawnSync(
940
- process.execPath,
941
- [fileURLToPath(new URL(`./${script}.mjs`, import.meta.url)), ...argv],
942
- { cwd: dir, encoding: "utf8", env },
943
- );
944
-
945
- // The direction a new guard gets wrong on its own: what it wrongly REFUSES.
946
- // The matrix above feeds it nothing but invalid input, and a guard tightened
947
- // past the digits every real caller sends would refuse a working invocation —
948
- // the outcome #365's own AC calls worse than the bug.
949
- //
950
- // `strictEqual`, because the TYPE is the contract #878 settles and this file's
951
- // `assert` is the loose one. numArg() returns a NUMBER so that no payload site
952
- // restates `Number(pr)`, and those restatements are exactly where `NaN` became
953
- // `null`: a payload reading back the string "42" would satisfy a loose check
954
- // while telling every consumer that keys on a number something else.
955
- test("#878: a digits value is accepted, and each payload names its PR as a number", () => {
956
- const { dir, receipt, env } = stubGhAnswering();
957
-
958
- const stats = runAnswering("diff-stats", ["--pr", "42"], env, dir);
959
- assert.equal(stats.status, 0, stats.stdout + stats.stderr);
960
- assert.strictEqual(JSON.parse(stats.stdout).pr, 42, `diff-stats.mjs's payload lost its PR number: ${stats.stdout}`);
961
-
962
- const overlap = runAnswering("pr-overlap", ["--a", "5", "--b", "6"], env, dir);
963
- assert.equal(overlap.status, 0, overlap.stdout + overlap.stderr);
964
- const payload = JSON.parse(overlap.stdout);
965
- assert.strictEqual(payload.a, 5, `pr-overlap.mjs's payload lost --a: ${overlap.stdout}`);
966
- assert.strictEqual(payload.b, 6, `pr-overlap.mjs's payload lost --b: ${overlap.stdout}`);
967
-
968
- // The stub really answered, so the two exit-0 rows above are the accepting
969
- // path and not a script that refused quietly at code 0.
970
- assert.match(readFileSync(receipt, "utf8"), /^pr view 42 /m, "diff-stats.mjs never asked gh for PR 42");
971
- assert.match(readFileSync(receipt, "utf8"), /^pr diff 5 /m, "pr-overlap.mjs never asked gh for PR 5");
972
- });
973
-
974
- // `--pr 0` is the row the `=== null` absence check exists for, and the one a
975
- // later "simplification" back to `!pr` silently breaks: numArg() returns a
976
- // NUMBER, so `!pr` is true for a zero the caller plainly GAVE, and the script
977
- // would answer it with a usage line claiming --pr is required. gh answers it
978
- // truthfully instead, as no such PR. Measured through the receipt, since a
979
- // usage die and a gh refusal both exit 2 and only the query tells them apart.
980
- test("#878: `--pr 0` reaches gh rather than drawing the usage line for an absent flag", () => {
981
- const { dir, receipt, env } = stubGhAnswering();
982
- const r = runAnswering("diff-stats", ["--pr", "0"], env, dir);
983
- assert.equal(r.status, 0, r.stdout + r.stderr);
984
- assert.strictEqual(JSON.parse(r.stdout).pr, 0, `a zero PR must survive to the payload as 0: ${r.stdout}`);
985
- assert.doesNotMatch(r.stderr, /usage:/, `--pr 0 was answered as an absent flag: ${r.stderr}`);
986
- assert.match(readFileSync(receipt, "utf8"), /^pr view 0 /m, "diff-stats.mjs never asked gh for PR 0");
987
- });
988
-
989
- // ── #463: a bare or single-dash token nothing reads ──────────────────────
990
- //
991
- // The matrix above pins sweep()'s bound: it only ever refuses a
992
- // `--`-prefixed token, by design (its own comment, and #365's triage ruling
993
- // that board.mjs's `build`/`serve` must stay out of reach). A bare word or a
994
- // single dash — the likelier typo, since the caller plainly meant a flag —
995
- // rode through in total silence: `ci-state.mjs --pr 42 basee main` computed
996
- // a real, wrong verdict at exit 0/1 against the default base, the same
997
- // fail-open harm as #365 reached from the positional side. stray() closes
998
- // it because the script's flag table says which names take a value, so `-1` on
999
- // `--spend-since` is not mistaken for one of these.
1000
- //
1001
- // board.mjs is the one row here with a positional of its own, so its cases
1002
- // pair a valid subcommand with an EXTRA stray, rather than replacing the
1003
- // subcommand — an unrecognised subcommand on its own (`board.mjs junk`) is
1004
- // the pre-existing "usage: board.mjs build|serve" die and not this fix's
1005
- // business, per board.mjs's own comment on where stray() is called from.
1006
- // Its second row makes that extra token a DECLARED positional, which is the
1007
- // only shape reaching stray()'s `usedPositional` gate; the token is `serve`
1008
- // after `build` rather than the reverse, because a guard deleted from under
1009
- // the reverse spelling starts a real server and hangs spawnSync instead of
1010
- // failing.
1011
- //
1012
- // staleness.mjs queries git, not gh, so its row's receipt assertion is
1013
- // vacuous and the named token is what discriminates: with the guard deleted
1014
- // the script runs on to a git call that also exits 2, and only the wording
1015
- // tells the two apart.
1016
- const STRAY_POSITIONALS = [
1017
- { script: "board", argv: ["build", "--ledger", "x", "junk"], stray: "junk" },
1018
- { script: "ci-state", argv: ["--pr", "42", "basee", "main"], stray: "basee" },
1019
- { script: "ci-state", argv: ["--pr", "42", "-basee", "main"], stray: "-basee" },
1020
- { script: "diff-stats", argv: ["--pr", "42", "stray"], stray: "stray" },
1021
- { script: "pr-overlap", argv: ["--a", "5", "--b", "6", "stray"], stray: "stray" },
1022
- { script: "board", argv: ["build", "--ledger", "x", "serve"], stray: "serve" },
1023
- { script: "staleness", argv: ["--path", "README.md", "--present", "needle", "JUNKTOKEN"], stray: "JUNKTOKEN" },
1024
- ];
1025
-
1026
- for (const { script, argv, stray } of STRAY_POSITIONALS) {
1027
- test(`${script}.mjs refuses the stray positional '${stray}' by name, before any query`, () => {
1028
- const { dir, receipt, env } = stubGhBin();
1029
- const r = spawnSync(
1030
- process.execPath,
1031
- [fileURLToPath(new URL(`./${script}.mjs`, import.meta.url)), ...argv],
1032
- { cwd: dir, encoding: "utf8", env },
1033
- );
1034
- assert.equal(r.status, 2, `expected exit 2, got ${r.status}: ${r.stderr}`);
1035
- assert.ok(
1036
- r.stderr.includes(stray),
1037
- `${script}.mjs refused without naming ${stray}: ${r.stderr}`,
1038
- );
1039
- if (existsSync(receipt)) assert.fail(`${script}.mjs reached gh before refusing ${stray}: ${readFileSync(receipt, "utf8")}`);
1040
- });
1041
- }
1042
-
1043
- // The unit-level rules stray() itself must hold, driven against a throwaway
1044
- // consumer the same way runSweep() drives sweep() — the real call sites are
1045
- // pinned by the STRAY_POSITIONALS matrix and by board.test.mjs's serve-side
1046
- // sibling ("CLI: serve refuses a stray positional the same way build does").
1047
- // Neither half names a position in the file, deliberately: the runSweep()
1048
- // half of this sentence used to say "above", and was wrong.
1049
- //
1050
- // `body` is the probe's own statements against the bound readers `f` and the
1051
- // caller's own `table` object, so the same harness drives defineFlags()'s
1052
- // wrong-kind refusals and its construction-time snapshot further down.
1053
- function runFlags(argv, flags, positionals, body) {
1054
- const dir = tempDir("arg-stray-unit-");
1055
- writeFileSync(join(dir, "arg.mjs"), readFileSync(ARG_MODULE));
1056
- writeFileSync(join(dir, "run.mjs"), [
1057
- 'import { makeDie, defineFlags } from "./arg.mjs";',
1058
- 'const die = makeDie("probe");',
1059
- `const table = ${JSON.stringify(flags)};`,
1060
- `const f = defineFlags(die, { flags: table, positionals: ${JSON.stringify(positionals)} });`,
1061
- body,
1062
- 'console.log("ok");',
1063
- "",
1064
- ].join("\n"));
1065
- return spawnSync(process.execPath, [join(dir, "run.mjs"), ...argv], { encoding: "utf8" });
1066
- }
1067
-
1068
- function runStray(argv, flags, positionals) {
1069
- return runFlags(argv, flags, positionals, "f.stray();");
1070
- }
1071
-
1072
- // The pin the naive widenings both fail, named in #463's own AC: a value that
1073
- // looks like a flag (`startsWith("-")` would refuse it) on a name stray()
1074
- // was TOLD takes one.
1075
- test("stray() accepts a negative value on a declared value flag", () => {
1076
- const r = runStray(["--spend-since", "-1"], { "spend-since": "value" }, []);
1077
- assert.equal(r.status, 0, r.stderr);
1078
- assert.match(r.stdout, /^ok$/m);
1079
- });
1080
-
1081
- test("stray() accepts the one declared positional and refuses an unrelated extra token", () => {
1082
- const ok = runStray(["build"], {}, ["build", "serve"]);
1083
- assert.equal(ok.status, 0, ok.stderr);
1084
- const extra = runStray(["build", "junk"], {}, ["build", "serve"]);
1085
- assert.equal(extra.status, 2, extra.stderr);
1086
- assert.match(extra.stderr, /unexpected argument 'junk'/);
1087
- });
1088
-
1089
- // The case the test above cannot reach, and the only one that exercises the
1090
- // `usedPositional` gate at all: `junk` is refused by the ordinary
1091
- // unknown-token path, which holds just as well with the gate gone. Measured
1092
- // — dropping `!usedPositional` from stray() left arg.test.mjs,
1093
- // board.test.mjs and board-cli.test.mjs entirely green, while
1094
- // `board.mjs serve --port 0 build` went from exit 2 to exit 0 with the
1095
- // server actually starting and `build` silently swallowed.
1096
- test("stray() refuses a second declared positional, not only an unrelated token", () => {
1097
- const r = runStray(["build", "serve"], {}, ["build", "serve"]);
1098
- assert.equal(r.status, 2, r.stderr);
1099
- assert.match(r.stderr, /unexpected argument 'serve'/);
1100
- });
1101
-
1102
- // #1077: `valueFlags` naming exactly the flags that take a value used to be
1103
- // stated only in prose at each call site, and the dangerous drift — a BOOLEAN
1104
- // flag's name listed there — bought the token after it an unconditional skip,
1105
- // hiding the very stray this guard exists to catch. The list is now derived
1106
- // from the script's flag table, so what is pinned here is that a "bool" entry
1107
- // consumes nothing, and — below — that the table cannot disagree with the
1108
- // reads the script makes.
1109
- test("stray() skips only after a \"value\" name — a \"bool\" flag consumes nothing", () => {
1110
- const skipped = runStray(["--since", "junk"], { since: "value" }, []);
1111
- assert.equal(skipped.status, 0, skipped.stderr);
1112
- const caught = runStray(["--quiet", "junk"], { quiet: "bool" }, []);
1113
- assert.equal(caught.status, 2, caught.stderr);
1114
- assert.match(caught.stderr, /unexpected argument 'junk'/);
1115
- });
1116
-
1117
- // The guarantee that replaced the pin above it (#1077): a read that
1118
- // contradicts the table refuses, so a boolean typed as "value" — or the
1119
- // reverse — cannot survive the first run that reaches the read. Exit 2 via
1120
- // die(), never an uncaught Error: exit 1 is a verdict in ci-state.mjs,
1121
- // merge-gate.mjs and tier-roles.mjs.
1122
- const WRONG_KIND = [
1123
- { read: 'f.has("quiet");', flags: { quiet: "value" }, message: "bug: --quiet read as bool but declared value" },
1124
- { read: 'f.arg("quiet");', flags: { quiet: "bool" }, message: "bug: --quiet read as value but declared bool" },
1125
- { read: 'f.numArg("pr");', flags: { pr: "bool" }, message: "bug: --pr read as value but declared bool" },
1126
- { read: 'f.arg("base");', flags: { quiet: "bool" }, message: "bug: --base read as value but not declared" },
1127
- { read: 'f.has("toString");', flags: {}, message: "bug: --toString read as bool but not declared" },
1128
- ];
1129
-
1130
- for (const { read, flags, message } of WRONG_KIND) {
1131
- test(`defineFlags(): ${read} against ${JSON.stringify(flags)} exits 2 naming the bug`, () => {
1132
- const r = runFlags([], flags, [], read);
1133
- assert.equal(r.status, 2, r.stderr);
1134
- assert.ok(r.stderr.includes(`\nprobe: ${message}\n`), r.stderr);
1135
- assert.doesNotMatch(r.stdout, /^ok$/m);
1136
- });
1137
- }
1138
-
1139
- // #1077 follow-up: a declared kind that is neither "value" nor "bool" — an
1140
- // author typo in the table itself, not a caller's mistake — used to
1141
- // construct successfully and surface only the first time (if ever) a reader
1142
- // for that name ran, worded as though the CALLER had misused it rather than
1143
- // pointing at the table that is actually wrong. Refused here, at
1144
- // construction, regardless of which flags a given run happens to touch.
1145
- test("defineFlags(): a declared kind other than \"value\" or \"bool\" refuses at construction", () => {
1146
- const r = runFlags([], { pr: "number" }, [], "");
1147
- assert.equal(r.status, 2, r.stderr);
1148
- assert.ok(r.stderr.includes('\nprobe: bug: --pr declared number, not "value" or "bool"\n'), r.stderr);
1149
- assert.doesNotMatch(r.stdout, /^ok$/m);
1150
- });
1151
-
1152
- // #2172 review: `flags` itself, not just each entry's declared kind, is
1153
- // refused at construction when it is not a plain object — `null`, or
1154
- // `undefined` from a caller typo like `{ flag: {...} }` instead of
1155
- // `{ flags: {...} }`. Before #2172 the copy quietly spread either into `{}`,
1156
- // trading the old `Object.keys(undefined)` TypeError for a silently empty
1157
- // flag table whose reads all fail later with no mention of the table itself.
1158
- test("defineFlags(): a missing or null flags table refuses at construction instead of silently building an empty one", () => {
1159
- const missing = runFlags([], undefined, [], "");
1160
- assert.equal(missing.status, 2, missing.stderr);
1161
- assert.ok(missing.stderr.includes("\nprobe: bug: defineFlags() needs a flags table, got undefined\n"), missing.stderr);
1162
- assert.doesNotMatch(missing.stdout, /^ok$/m);
1163
- const nullTable = runFlags([], null, [], "");
1164
- assert.equal(nullTable.status, 2, nullTable.stderr);
1165
- assert.ok(nullTable.stderr.includes("\nprobe: bug: defineFlags() needs a flags table, got null\n"), nullTable.stderr);
1166
- assert.doesNotMatch(nullTable.stdout, /^ok$/m);
1167
- });
1168
-
1169
- // The half a new guard can get wrong the other way: refusing a read the
1170
- // table DOES declare. Every reader is driven with its own kind, given and
1171
- // absent, so a check that compared the wrong way round reds here.
1172
- test("defineFlags(): a read of the declared kind answers exactly as before", () => {
1173
- const flags = { base: "value", pr: "value", quiet: "bool" };
1174
- const body = 'console.log(JSON.stringify([f.arg("base"), f.numArg("pr"), f.has("quiet")]));';
1175
- const given = runFlags(["--base", "main", "--pr", "7", "--quiet"], flags, [], body);
1176
- assert.equal(given.status, 0, given.stderr);
1177
- assert.match(given.stdout, /^\["main",7,true\]$/m);
1178
- const absent = runFlags([], flags, [], body);
1179
- assert.equal(absent.status, 0, absent.stderr);
1180
- assert.match(absent.stdout, /^\[null,null,false\]$/m);
1181
- });
1182
-
1183
- // #2114: the table is snapshotted at construction, so a caller mutating its own
1184
- // `flags` object afterwards is seen by NO reader. Before the snapshot,
1185
- // arg()/numArg()/has() and stray() read the caller's object live at call
1186
- // time, so a key added to it after construction was readable by arg() even
1187
- // though sweep() never validated it — the copy closes that gap by binding
1188
- // all four to the same construction-time snapshot. sweep() itself is NOT in
1189
- // this regression matrix: it took its accepted names once at construction,
1190
- // via `Object.keys(flags)`, in both the pre- and post-#2114 code, so that
1191
- // array is a fixed snapshot either way and a later mutation to the caller's
1192
- // table can never reach it — a `f.sweep();` row here passed whether or not
1193
- // the table itself was copied (measured: reverting the copy alone leaves it
1194
- // green while every row below goes red), proving nothing about this fix.
1195
- // The standalone test right after this array pins that existing sweep()
1196
- // invariant on its own terms, as documentation rather than regression.
1197
- const LATE_ADDITION = [
1198
- { kind: "value", read: "f.stray();", message: "unexpected argument '5'" },
1199
- { kind: "value", read: 'f.arg("late");', message: "bug: --late read as value but not declared" },
1200
- { kind: "value", read: 'f.numArg("late");', message: "bug: --late read as value but not declared" },
1201
- { kind: "bool", read: 'f.has("late");', message: "bug: --late read as bool but not declared" },
1202
- ];
1203
-
1204
- for (const { kind, read, message } of LATE_ADDITION) {
1205
- // `argv` is fully determined by `kind` — "value" needs the flag AND its
1206
- // value token, "bool" only the flag itself — so it is derived here rather
1207
- // than duplicated by hand in every row above.
1208
- const argv = kind === "value" ? ["--late", "5"] : ["--late"];
1209
- test(`defineFlags(): a ${kind} flag added to the caller's table after construction is unknown to ${read}`, () => {
1210
- const r = runFlags(argv, { base: "value" }, [], `table.late = ${JSON.stringify(kind)};\n${read}`);
1211
- assert.equal(r.status, 2, r.stderr);
1212
- assert.ok(r.stderr.includes(`\nprobe: ${message}\n`), r.stderr);
1213
- assert.doesNotMatch(r.stdout, /^ok$/m);
1214
- });
1215
- }
1216
-
1217
- // sweep()'s own accepted-name snapshot is unrelated to #2114: it passes
1218
- // identically whether or not the table itself is copied, because
1219
- // `Object.keys(flags)` already returns a fixed array at construction in
1220
- // both versions of the code — a later mutation to the caller's table cannot
1221
- // reach an array that was built before the mutation ran. This documents
1222
- // that existing invariant; it is deliberately NOT part of the LATE_ADDITION
1223
- // matrix above, since it cannot discriminate this fix either way.
1224
- test("defineFlags(): a value flag added to the caller's table after construction stays unknown to f.sweep(), independent of the table copy", () => {
1225
- const r = runFlags(["--late", "5"], { base: "value" }, [], 'table.late = "value";\nf.sweep();');
1226
- assert.equal(r.status, 2, r.stderr);
1227
- assert.ok(r.stderr.includes("\nprobe: unknown flag --late — accepted: --base\n"), r.stderr);
1228
- assert.doesNotMatch(r.stdout, /^ok$/m);
1229
- });
1230
-
1231
- // The half the snapshot must ACCEPT: every name declared at construction stays
1232
- // readable with its declared kind however the caller's object changes after —
1233
- // deleted, flipped to the other kind, or set to a kind the construction-time
1234
- // check would have refused. Read live, stray() would refuse `main` behind a
1235
- // now-"bool" --base and arg("base") would die on the flipped kind.
1236
- test("defineFlags(): later deletes and kind changes to the caller's table leave every reader on the declared table", () => {
1237
- const flags = { base: "value", pr: "value", quiet: "bool" };
1238
- const body = [
1239
- 'table.base = "bool";',
1240
- "delete table.pr;",
1241
- 'table.quiet = "number";',
1242
- "f.sweep();",
1243
- "f.stray();",
1244
- 'console.log(JSON.stringify([f.arg("base"), f.numArg("pr"), f.has("quiet")]));',
1245
- ].join("\n");
1246
- const r = runFlags(["--base", "main", "--pr", "7", "--quiet"], flags, [], body);
1247
- assert.equal(r.status, 0, r.stderr);
1248
- assert.match(r.stdout, /^\["main",7,true\]$/m);
1249
- });
1250
-
1251
- test("stray() refuses a bare positional on a script that declares none", () => {
1252
- const r = runStray(["junk"], {}, []);
1253
- assert.equal(r.status, 2, r.stderr);
1254
- assert.match(r.stderr, /unexpected argument 'junk'/);
1255
- });
1256
-
1257
- test("stray() refuses a single-dash token the same way as a bare word", () => {
1258
- const r = runStray(["-basee"], {}, []);
1259
- assert.equal(r.status, 2, r.stderr);
1260
- assert.match(r.stderr, /unexpected argument '-basee'/);
1261
- });
1262
-
1263
- test("stray() refuses a stray that arrives BEFORE a known value flag, not only after", () => {
1264
- const r = runStray(["junk", "--pr", "42"], { pr: "value" }, []);
1265
- assert.equal(r.status, 2, r.stderr);
1266
- assert.match(r.stderr, /unexpected argument 'junk'/);
1267
- });
1268
-
1269
- // `--`-prefixed tokens are never this guard's business, known or not — that
1270
- // is sweep()'s bound, unchanged (#463's own comment on refuseStrays()). Run
1271
- // without sweep() ahead of it, same as runSweep()'s own probe convention, so
1272
- // this proves stray()'s OWN bound rather than sweep() having caught it first.
1273
- test("stray() leaves a `--`-prefixed token alone, even an unknown one", () => {
1274
- const r = runStray(["--bogus"], {}, []);
1275
- assert.equal(r.status, 0, r.stderr);
1276
- });
1277
-
1278
- // The other half, and the one the ticket calls worse than the bug: a sweep
1279
- // that refuses a working invocation. Each script's own suite drives its full
1280
- // known set through its own stub rig (ci-state.test.mjs, board-cli.test.mjs);
1281
- // what belongs HERE is the shape rule those sets are read by, because getting
1282
- // it wrong refuses every caller of every script at once.
1283
- //
1284
- // Written against a throwaway consumer rather than a real script so the four
1285
- // cases are visible in one place — the real call sites are pinned by the
1286
- // matrix above and by their own suites' accept tests.
1287
- //
1288
- // The probe calls sweep BEFORE arg(), which is the reverse of what the call
1289
- // sites do, and deliberately: with arg() first it dies on `--base=main` on its
1290
- // own, so the `=` case below asserts arg()'s behaviour and pins nothing about
1291
- // the sweep — measured, it stayed green with the `=` split deleted. Sweep-first
1292
- // is also the real ordering wherever the flag's own arg() runs later, which is
1293
- // every board.mjs flag and ci-state's --workflow-file.
1294
- //
1295
- // The below-the-guards ordering the call sites use is not pinned here but
1296
- // behaviourally, by diff-stats.test.mjs's `--pr --json` case: measured, hoisting
1297
- // diff-stats.mjs's sweep above its `if (!pr)` guard turns that red.
1298
- function runSweep(argv) {
1299
- const dir = tempDir("arg-sweep-unit-");
1300
- writeFileSync(join(dir, "arg.mjs"), readFileSync(ARG_MODULE));
1301
- writeFileSync(join(dir, "run.mjs"), [
1302
- 'import { makeDie, defineFlags } from "./arg.mjs";',
1303
- 'const die = makeDie("probe");',
1304
- 'const f = defineFlags(die, { flags: { base: "value", quiet: "bool" } });',
1305
- 'f.sweep();',
1306
- 'const value = f.arg("base");',
1307
- 'console.log(`ok base=${value}`);',
1308
- "",
1309
- ].join("\n"));
1310
- return spawnSync(process.execPath, [join(dir, "run.mjs"), ...argv], { encoding: "utf8" });
1311
- }
1312
-
1313
- test("sweep accepts a subcommand, a value and every known flag — the invocations it must not break", () => {
1314
- // board.mjs's `build`/`serve` are argv[2] positionals and `main` is a value
1315
- // that would read as a flag name if the sweep looked past the `--` prefix.
1316
- // One case each, plus a boolean known flag, so a sweep narrowed to any one
1317
- // of the three goes red here.
1318
- const r = runSweep(["build", "--base", "main", "--quiet"]);
1319
- assert.equal(r.status, 0, r.stderr);
1320
- assert.match(r.stdout, /^ok base=main$/m);
1321
- });
1322
-
1323
- test("sweep refuses a stray flag even when every required flag is well-formed", () => {
1324
- // The live shape: nothing else is wrong, so no other guard fires and the
1325
- // script would otherwise run to a confident verdict on its defaults.
1326
- const r = runSweep(["--base", "main", "--bogus", "x"]);
1327
- assert.equal(r.status, 2, r.stderr);
1328
- assert.match(r.stderr, /^probe: unknown flag --bogus — accepted: --base, --quiet$/m);
1329
- });
1330
-
1331
- test("sweep leaves --known=value to arg()'s wording and still catches --unknown=value", () => {
1332
- // Looked up by NAME, so `--base=main` falls through to the #169/#364 guards
1333
- // that have the specific thing to say about it. Reversing that would replace
1334
- // "needs a space-separated value" with a generic unknown-flag line, and the
1335
- // caller would go hunting a typo that is not there.
1336
- const known = runSweep(["--base=main"]);
1337
- assert.equal(known.status, 2, known.stderr);
1338
- assert.match(known.stderr, /--base needs a space-separated value/);
1339
-
1340
- // The same form on a name nothing reads is still the sweep's, and it echoes
1341
- // the token as typed rather than the parsed name.
1342
- const unknown = runSweep(["--base", "main", "--basee=x"]);
1343
- assert.equal(unknown.status, 2, unknown.stderr);
1344
- assert.match(unknown.stderr, /unknown flag --basee=x/);
1345
- });
1346
-
1347
- test("sweep refuses a stray that arrives BEFORE the good flags, not only after them", () => {
1348
- // Position must not decide it. A loop that stopped at the first known flag,
1349
- // or one anchored at a fixed argv index, passes the case above and fails
1350
- // this one — the shape #462 caught in has().
1351
- const r = runSweep(["--bogus", "--base", "main"]);
1352
- assert.equal(r.status, 2, r.stderr);
1353
- assert.match(r.stderr, /unknown flag --bogus/);
1354
- });