@feigi/fleet-ctl 0.0.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (245) hide show
  1. package/.claude-plugin/plugin.json +9 -0
  2. package/LICENSE +202 -0
  3. package/NOTICE +18 -0
  4. package/agents/fleet-finisher.agent.md +7 -0
  5. package/agents/fleet-implementer-alt.agent.md +210 -0
  6. package/agents/fleet-implementer.agent.md +210 -0
  7. package/agents/fleet-merge-bot.agent.md +7 -0
  8. package/agents/fleet-review-comments.agent.md +40 -0
  9. package/agents/fleet-review-correctness.agent.md +43 -0
  10. package/agents/fleet-review-runner.agent.md +73 -0
  11. package/agents/fleet-review-silent-failure.agent.md +49 -0
  12. package/agents/fleet-review-simplify.agent.md +46 -0
  13. package/agents/fleet-review-snapshot.agent.md +24 -0
  14. package/agents/fleet-review-tests.agent.md +46 -0
  15. package/agents/fleet-review-types.agent.md +41 -0
  16. package/agents/fleet-review-verifier.agent.md +29 -0
  17. package/commands/review-and-fix.md +98 -0
  18. package/commands/run-merge-bot.md +357 -0
  19. package/commands/run-team-help.md +17 -0
  20. package/package.json +23 -0
  21. package/scripts/agent-test-dir-prose.test.mjs +59 -0
  22. package/scripts/agent-test.test.mjs +1636 -0
  23. package/scripts/ambient-git-vars-mjs-prose.test.mjs +354 -0
  24. package/scripts/ambient-git-vars-prose.test.mjs +192 -0
  25. package/scripts/ancestry-check-position-prose.test.mjs +175 -0
  26. package/scripts/apply-ruleset.test.mjs +420 -0
  27. package/scripts/arg-header-probes-prose.test.mjs +393 -0
  28. package/scripts/arg.mjs +600 -0
  29. package/scripts/arg.test.mjs +1354 -0
  30. package/scripts/board-cli.test.mjs +694 -0
  31. package/scripts/board-identity.test.mjs +429 -0
  32. package/scripts/board-liveness-banner.test.mjs +119 -0
  33. package/scripts/board-prev-shape.test.mjs +229 -0
  34. package/scripts/board-tryparse-null.test.mjs +119 -0
  35. package/scripts/board.html +471 -0
  36. package/scripts/board.mjs +2037 -0
  37. package/scripts/board.test.mjs +3086 -0
  38. package/scripts/brief-after-cut-prose.test.mjs +53 -0
  39. package/scripts/candidates-exit3-prose.test.mjs +302 -0
  40. package/scripts/candidates.mjs +674 -0
  41. package/scripts/candidates.test.mjs +2101 -0
  42. package/scripts/caveat-unification-prose.test.mjs +98 -0
  43. package/scripts/ci-comment-rot-prose.test.mjs +2025 -0
  44. package/scripts/ci-completes-premise-prose.test.mjs +257 -0
  45. package/scripts/ci-state-prose.test.mjs +113 -0
  46. package/scripts/ci-state.mjs +761 -0
  47. package/scripts/ci-state.test.mjs +1640 -0
  48. package/scripts/ci-vacuous-green.test.mjs +368 -0
  49. package/scripts/citation-sweep-prose.test.mjs +1572 -0
  50. package/scripts/claim-lifecycle.test.mjs +185 -0
  51. package/scripts/claim-ticket.sh +417 -0
  52. package/scripts/claim-ticket.test.mjs +1121 -0
  53. package/scripts/closing-keyword-prose.test.mjs +193 -0
  54. package/scripts/cockpit-launch-idempotent-prose.test.mjs +165 -0
  55. package/scripts/cockpit-tick-nonblocking.test.mjs +210 -0
  56. package/scripts/compute-board.mjs +579 -0
  57. package/scripts/compute-board.test.mjs +1060 -0
  58. package/scripts/compute-spend.mjs +329 -0
  59. package/scripts/compute-spend.test.mjs +451 -0
  60. package/scripts/cross-repo-citation-prose.test.mjs +156 -0
  61. package/scripts/cwd-isolation-pins.mjs +83 -0
  62. package/scripts/dedupe-guard-prose.test.mjs +243 -0
  63. package/scripts/derive-testcmd.sh +239 -0
  64. package/scripts/derive-testcmd.test.mjs +380 -0
  65. package/scripts/diff-stats.mjs +231 -0
  66. package/scripts/diff-stats.test.mjs +408 -0
  67. package/scripts/dispatch-block-golden-prose.test.mjs +1024 -0
  68. package/scripts/dispatch-block-pins-prose.test.mjs +615 -0
  69. package/scripts/drop-merged-label.sh +173 -0
  70. package/scripts/drop-merged-label.test.mjs +480 -0
  71. package/scripts/expected-jobs-prose.test.mjs +80 -0
  72. package/scripts/filing-bar-seat-prose.test.mjs +242 -0
  73. package/scripts/filing-claim-bar-prose.test.mjs +166 -0
  74. package/scripts/finisher-dispatch-premise-prose.test.mjs +312 -0
  75. package/scripts/finisher-halt-prose.test.mjs +106 -0
  76. package/scripts/finisher-name-prose.test.mjs +134 -0
  77. package/scripts/finisher-own-tree-prose.test.mjs +285 -0
  78. package/scripts/finisher-pin-race-prose.test.mjs +339 -0
  79. package/scripts/fix-applier-correction-rules-prose.test.mjs +201 -0
  80. package/scripts/fix-applier-result-file-prose.test.mjs +100 -0
  81. package/scripts/fleet-bootstrap +155 -0
  82. package/scripts/fleet-heartbeat.mjs +272 -0
  83. package/scripts/fleet-heartbeat.test.mjs +450 -0
  84. package/scripts/fleet-provenance +207 -0
  85. package/scripts/fleet-provenance.test.mjs +64 -0
  86. package/scripts/fleet-run +148 -0
  87. package/scripts/fleet-run.test.mjs +90 -0
  88. package/scripts/fleet-state.mjs +400 -0
  89. package/scripts/fleet-state.test.mjs +373 -0
  90. package/scripts/fleet-tick-prose.test.mjs +299 -0
  91. package/scripts/fleet-tick.mjs +832 -0
  92. package/scripts/fleet-tick.test.mjs +1332 -0
  93. package/scripts/force-with-lease-reason-prose.test.mjs +184 -0
  94. package/scripts/frontmatter-allowlist.json +64 -0
  95. package/scripts/frontmatter-check.mjs +256 -0
  96. package/scripts/frontmatter-check.test.mjs +436 -0
  97. package/scripts/git-env.mjs +124 -0
  98. package/scripts/git-env.test.mjs +149 -0
  99. package/scripts/git-status-untracked-mode-sweep.test.mjs +216 -0
  100. package/scripts/gone-walk.test.mjs +213 -0
  101. package/scripts/gp-sep-invariant-prose.test.mjs +188 -0
  102. package/scripts/head-moved-after-label-prose.test.mjs +233 -0
  103. package/scripts/immutable-body-claim-prose.test.mjs +413 -0
  104. package/scripts/implementer-model-tier.test.mjs +643 -0
  105. package/scripts/inflight-citation-prose.test.mjs +144 -0
  106. package/scripts/inflight-exit2-prose.test.mjs +81 -0
  107. package/scripts/inflight-probe-guard-prose.test.mjs +109 -0
  108. package/scripts/inflight-scan-scope-prose.test.mjs +57 -0
  109. package/scripts/inflight.sh +1106 -0
  110. package/scripts/inflight.test.mjs +2984 -0
  111. package/scripts/injection-control-prose.test.mjs +404 -0
  112. package/scripts/install-root-audit.test.mjs +464 -0
  113. package/scripts/instrument-check-prose.test.mjs +235 -0
  114. package/scripts/instruments.sh +394 -0
  115. package/scripts/instruments.test.mjs +787 -0
  116. package/scripts/issue-tracker-prose.test.mjs +71 -0
  117. package/scripts/json.sh +248 -0
  118. package/scripts/json.test.mjs +364 -0
  119. package/scripts/ledger-dispatch.test.mjs +516 -0
  120. package/scripts/ledger-grammar.mjs +85 -0
  121. package/scripts/ledger-grammar.test.mjs +142 -0
  122. package/scripts/ledger-read-require-file.test.mjs +197 -0
  123. package/scripts/ledger.mjs +1753 -0
  124. package/scripts/ledger.test.mjs +3554 -0
  125. package/scripts/line-distance-prose.test.mjs +245 -0
  126. package/scripts/liveness-rationale-prose.test.mjs +83 -0
  127. package/scripts/locale-pin-prose.test.mjs +189 -0
  128. package/scripts/member-outcome-prose.test.mjs +167 -0
  129. package/scripts/member-outcomes-header.test.mjs +148 -0
  130. package/scripts/member-outcomes-prose.test.mjs +63 -0
  131. package/scripts/member-outcomes.mjs +231 -0
  132. package/scripts/member-outcomes.test.mjs +507 -0
  133. package/scripts/member-prompt-prose.test.mjs +161 -0
  134. package/scripts/member-record.mjs +605 -0
  135. package/scripts/member-record.test.mjs +516 -0
  136. package/scripts/member-write-guard.mjs +279 -0
  137. package/scripts/member-write-guard.test.mjs +211 -0
  138. package/scripts/merge-commit-probe-prose.test.mjs +122 -0
  139. package/scripts/merge-gate.mjs +262 -0
  140. package/scripts/merge-gate.test.mjs +613 -0
  141. package/scripts/muted-git-guard-sweep.test.mjs +493 -0
  142. package/scripts/net-ssh-precedence-prose.test.mjs +91 -0
  143. package/scripts/net-watchdog-prose.test.mjs +79 -0
  144. package/scripts/net.sh +409 -0
  145. package/scripts/net.test.mjs +211 -0
  146. package/scripts/no-ci-gate-prose.test.mjs +108 -0
  147. package/scripts/no-undo-audit.sh +1134 -0
  148. package/scripts/no-undo-audit.test.mjs +3965 -0
  149. package/scripts/no-wave.test.mjs +138 -0
  150. package/scripts/node-floor-sweep.test.mjs +611 -0
  151. package/scripts/pointer-target-prose.test.mjs +186 -0
  152. package/scripts/pr-overlap.mjs +417 -0
  153. package/scripts/pr-overlap.test.mjs +695 -0
  154. package/scripts/printf-die-sweep.test.mjs +384 -0
  155. package/scripts/prompt-renderer.mjs +39 -0
  156. package/scripts/prompt-renderer.test.mjs +68 -0
  157. package/scripts/prose-pin.mjs +808 -0
  158. package/scripts/prose-pin.test.mjs +1034 -0
  159. package/scripts/prove-merge.sh +228 -0
  160. package/scripts/prove-merge.test.mjs +995 -0
  161. package/scripts/pull-table-relabel-prose.test.mjs +60 -0
  162. package/scripts/quiet-payload-prose.test.mjs +222 -0
  163. package/scripts/reap.sh +1768 -0
  164. package/scripts/reap.test.mjs +4395 -0
  165. package/scripts/reaping-prose.test.mjs +159 -0
  166. package/scripts/refuter-scratch-prose.test.mjs +135 -0
  167. package/scripts/release-label-required-prose.test.mjs +71 -0
  168. package/scripts/release-label-split-prose.test.mjs +169 -0
  169. package/scripts/release-ticket.sh +1716 -0
  170. package/scripts/release-ticket.test.mjs +5106 -0
  171. package/scripts/renovate-release-contract.test.mjs +379 -0
  172. package/scripts/repo-root.mjs +544 -0
  173. package/scripts/repo-root.test.mjs +873 -0
  174. package/scripts/reporter-output-rule-prose.test.mjs +208 -0
  175. package/scripts/review-agent-report-only.test.mjs +49 -0
  176. package/scripts/review-core-cwd-isolation.test.mjs +374 -0
  177. package/scripts/review-core-reads.test.mjs +478 -0
  178. package/scripts/review-core-refuter-scratch.test.mjs +148 -0
  179. package/scripts/review-core-snapshot-path.test.mjs +777 -0
  180. package/scripts/review-core-specialist-scratch.test.mjs +189 -0
  181. package/scripts/review-core-testcmd.test.mjs +288 -0
  182. package/scripts/review-core-unrun.test.mjs +530 -0
  183. package/scripts/review-core-unverified-discriminant.test.mjs +208 -0
  184. package/scripts/review-core.mjs +1028 -0
  185. package/scripts/review-eval-resolver-path.test.mjs +55 -0
  186. package/scripts/review-eval.mjs +197 -0
  187. package/scripts/review-host-fixture.mjs +73 -0
  188. package/scripts/review-in-run-retry.test.mjs +187 -0
  189. package/scripts/review-no-vendor-dispatch.test.mjs +45 -0
  190. package/scripts/review-path-default.test.mjs +796 -0
  191. package/scripts/review-runner-spawns.test.mjs +93 -0
  192. package/scripts/review-runner.test.mjs +155 -0
  193. package/scripts/review-tier-audit.test.mjs +140 -0
  194. package/scripts/run-artifact-pr-prose.test.mjs +341 -0
  195. package/scripts/run-merge-bot-prose.test.mjs +1391 -0
  196. package/scripts/scratch-partition-invariant-prose.test.mjs +74 -0
  197. package/scripts/scripts-path-citation-sweep.test.mjs +73 -0
  198. package/scripts/section-between-guard-prose.test.mjs +378 -0
  199. package/scripts/select-dimensions.test.mjs +674 -0
  200. package/scripts/shared-refusal.test.mjs +388 -0
  201. package/scripts/shell-traps-prose.test.mjs +507 -0
  202. package/scripts/shortlist.mjs +355 -0
  203. package/scripts/shortlist.test.mjs +366 -0
  204. package/scripts/slow-transport.mjs +72 -0
  205. package/scripts/snapshot-repo.test.mjs +772 -0
  206. package/scripts/snapshot-runner-audience-prose.test.mjs +129 -0
  207. package/scripts/spend-view.test.mjs +312 -0
  208. package/scripts/staleness-qualifier-prose.test.mjs +251 -0
  209. package/scripts/staleness-verdict-prose.test.mjs +142 -0
  210. package/scripts/staleness.mjs +414 -0
  211. package/scripts/staleness.test.mjs +893 -0
  212. package/scripts/stalled-member-liveness-prose.test.mjs +219 -0
  213. package/scripts/stash-prohibition-prose.test.mjs +313 -0
  214. package/scripts/strip-comments.mjs +44 -0
  215. package/scripts/tier-check.mjs +468 -0
  216. package/scripts/tier-check.test.mjs +726 -0
  217. package/scripts/tier-guard-gate-prose.test.mjs +216 -0
  218. package/scripts/tier-outcomes-header.test.mjs +586 -0
  219. package/scripts/tier-outcomes.mjs +441 -0
  220. package/scripts/tier-outcomes.test.mjs +342 -0
  221. package/scripts/tier-roles.mjs +250 -0
  222. package/scripts/tier-roles.test.mjs +316 -0
  223. package/scripts/tracker-block-copy-prose.test.mjs +288 -0
  224. package/scripts/triage-labels-gloss-prose.test.mjs +97 -0
  225. package/scripts/unattended-git-sweep.test.mjs +142 -0
  226. package/scripts/verify-sha-exit2-prose.test.mjs +269 -0
  227. package/scripts/verify-sha.sh +117 -0
  228. package/scripts/verify-sha.test.mjs +693 -0
  229. package/scripts/watcher-degraded-block.test.mjs +372 -0
  230. package/scripts/watcher-key-prose.test.mjs +106 -0
  231. package/scripts/within-run-pair-prose.test.mjs +208 -0
  232. package/scripts/worktree-audit.sh +482 -0
  233. package/scripts/worktree-audit.test.mjs +1407 -0
  234. package/scripts/worktree-head-prose.test.mjs +276 -0
  235. package/scripts/worktree-listing-sweep.test.mjs +217 -0
  236. package/scripts/worktree-model-prose.test.mjs +216 -0
  237. package/scripts/worktree.sh +470 -0
  238. package/skills/next-ticket/SKILL.md +138 -0
  239. package/skills/run-team/SKILL.md +3603 -0
  240. package/skills/run-team/references/ci-and-staleness.md +75 -0
  241. package/skills/run-team/references/correction-tickets.md +37 -0
  242. package/skills/run-team/references/isolation.md +23 -0
  243. package/skills/run-team/references/member-lifecycle.md +73 -0
  244. package/skills/run-team/references/reaping.md +73 -0
  245. package/skills/sizing-a-ticket/SKILL.md +39 -0
@@ -0,0 +1,388 @@
1
+ // #567 and #878: the cross-file sync requirement, EXECUTED.
2
+ //
3
+ // arg.mjs states the CLI refusal rules; ledger.mjs and member-outcomes.mjs
4
+ // cannot route through arg()/has() — each hand-rolls its own argv reader so it
5
+ // can word its refusals for --file and --require-file — and so each used to
6
+ // carry its own copy of those rules. The requirement that the copies stay in
7
+ // step was asserted only in PROSE, in two file headers. Measured on the
8
+ // post-#563 tree: the copies could be edited independently and the suite
9
+ // stayed green, because each file's tests pin only its own wording. That is
10
+ // the same class of defect #563 itself fixed — a requirement documented where
11
+ // nothing executes it. This file is what executes it.
12
+ //
13
+ // #878 added a second rule on the same terms — the digits rule isDigits(),
14
+ // whose out-of-reach consumers are fleet-tick.mjs (its own parseArgs) and
15
+ // review-core.mjs (a review argument, not argv). Both are ordinary modules
16
+ // and import the rule directly; neither holds a copy. Its wiring pin rides
17
+ // in test 1 below, beside #567's; one further test sits near the bottom of
18
+ // this file — a DERIVED sweep asserting the rule is spelled nowhere else,
19
+ // because a second copy is behaviour-identical and no behavioural test in
20
+ // this repo can see one.
21
+ //
22
+ // THREE tests for #567's two predicates, because none of them covers another:
23
+ //
24
+ // 1. The WIRING pin. A copy re-inlined byte-for-byte behaviour-identically
25
+ // changes no observable behaviour at all, so no behavioural test in this
26
+ // repo can see it — only a source assertion can. Measured: replacing
27
+ // ledger.mjs's `isFlagLike(file)` with `(file.startsWith("--") ||
28
+ // file.trim() === "")` reds this test and nothing else.
29
+ // 2. The DIFFERENTIAL. The wiring pin is a text-lift, and a text pin proves
30
+ // a spelling, never a behaviour: it stays green if the predicate itself
31
+ // is gutted, and it is blind to a regression ABOVE the pinned line that
32
+ // corrupts the value before it arrives. This one runs all three readers
33
+ // over the same values and requires the same verdict, so a copy that
34
+ // reappears DRIFTED reds here even if it is spelled to satisfy test 1.
35
+ // 3. The must-ACCEPT pin. Every case in 1 and 2 is input the rule must
36
+ // REFUSE, and a rule that refused everything would satisfy both. The
37
+ // predicates are fed input they must accept, including the neighbours the
38
+ // `--`-prefix rule deliberately does not cost: a single leading `-`, a
39
+ // `--` anywhere but the front, and a longer flag name that merely shares
40
+ // a prefix with the one being asked about.
41
+ //
42
+ // KNOWN CEILING on test 1, the presence-pin ceiling member-prompt-prose.test.mjs
43
+ // records: it asserts each refusal LINE routes through a predicate. It cannot
44
+ // prove some other line further down does not re-refuse on a hand-written
45
+ // rule of its own. Test 2 is the backstop for exactly that, on the values it
46
+ // samples. (Not strip-comments.mjs's ceiling, which is about trailing `code;
47
+ // // note` surviving the strip — measured, closing that one closes a
48
+ // different escape and leaves this one open.)
49
+ //
50
+ // SECOND CEILING, disclosed rather than fixed: these are text pins, so they
51
+ // answer a spelling. The `^` anchors mean re-indenting a pinned line reds
52
+ // them though nothing executable changed. Import ORDER and import LAYOUT are
53
+ // deliberately not pinned — each imported name is matched on its own, and
54
+ // `[^}]*` spans newlines — so a reflow or a reorder is free.
55
+ import { test } from "node:test";
56
+ import assert from "node:assert/strict";
57
+ import { readFileSync, readdirSync, writeFileSync, mkdtempSync, mkdirSync, symlinkSync, rmSync } from "node:fs";
58
+ import { spawnSync } from "node:child_process";
59
+ import { fileURLToPath } from "node:url";
60
+ import { tmpdir } from "node:os";
61
+ import { join } from "node:path";
62
+ import { stripComments } from "./strip-comments.mjs";
63
+ import { isFlagLike, hasEqualsForm, isDigits } from "./arg.mjs";
64
+
65
+ const src = (name) => stripComments(readFileSync(fileURLToPath(new URL(`./${name}`, import.meta.url)), "utf8"));
66
+
67
+ test("every refusal that shares arg.mjs's rules calls a predicate instead of restating one", () => {
68
+ const arg = src("arg.mjs");
69
+ // The rules themselves, stated once. Anchored at the export, so moving the
70
+ // expression back inside a factory reds here rather than quietly leaving two
71
+ // statements of the same rule in one file.
72
+ assert.match(arg, /^export function isFlagLike\(value\) \{$/m, "arg.mjs no longer exports isFlagLike");
73
+ assert.match(arg, /^export function hasEqualsForm\(name, argv = process\.argv\) \{$/m, "arg.mjs no longer exports hasEqualsForm");
74
+ // arg.mjs's own guards are consumers too. Without these, the rule could be
75
+ // exported for ledger.mjs while arg() kept a second copy — which is the
76
+ // ticket's defect with the two files swapped.
77
+ assert.match(arg, /if \(isFlagLike\(value\)\) die\(`--\$\{name\} needs a value`\);/, "arg()'s value guard restates the rule instead of calling isFlagLike");
78
+ assert.match(arg, /if \(hasEqualsForm\(name\)\) die\(`--\$\{name\} needs a space-separated value/, "arg()'s `=` guard restates the rule instead of calling hasEqualsForm");
79
+ assert.match(arg, /if \(hasEqualsForm\(name\)\) die\(`--\$\{name\} is a boolean flag/, "has()'s `=` guard restates the rule instead of calling hasEqualsForm");
80
+
81
+ const ledger = src("ledger.mjs");
82
+ // Each name on its own, because what must hold is that it comes from
83
+ // arg.mjs — not the order, and not the layout. `[^}]*` DOES span newlines
84
+ // (measured), here and in arg.test.mjs's #367 wiring pin, so a reflow of
85
+ // either import unpins nothing.
86
+ for (const fn of ["isFlagLike", "hasEqualsForm"]) {
87
+ assert.match(ledger, new RegExp(String.raw`^import \{[^}]*\b${fn}\b[^}]*\} from "\./arg\.mjs";`, "m"), `ledger.mjs no longer imports ${fn} from arg.mjs`);
88
+ }
89
+ // Each assertion pins the predicate call AND the wording beside it: the
90
+ // wording is deliberately ledger.mjs's own, not generated from a flag name,
91
+ // and a fix that unified the messages would be the other half of #567's AC
92
+ // going the wrong way.
93
+ // No `$`: stripComments blanks whole-line comments only, so a trailing
94
+ // `// note` survives the strip and would red an end-anchored pin over a
95
+ // line whose code did not change.
96
+ assert.match(ledger, /^if \(hasEqualsForm\("file", argv\)\) die\("--file needs a space-separated value, not --file="\);/m, "ledger.mjs's --file= guard drifted from arg.mjs's rule or lost its own wording");
97
+ assert.match(ledger, /^if \(hasEqualsForm\("require-file", argv\)\) die\("--require-file is a boolean flag, not --require-file="\);/m, "ledger.mjs's --require-file= guard drifted from arg.mjs's rule or lost its own wording");
98
+ assert.match(ledger, /if \(fileIdx !== -1 && file && isFlagLike\(file\)\) die\("--file needs a path"\);/, "ledger.mjs's --file value guard drifted from arg.mjs's rule or lost its own wording");
99
+
100
+ const memberOutcomes = src("member-outcomes.mjs");
101
+ assert.match(memberOutcomes, /^import \{[^}]*\bisFlagLike\b[^}]*\} from "\.\/arg\.mjs";/m, "member-outcomes.mjs no longer imports isFlagLike from arg.mjs");
102
+ assert.match(memberOutcomes, /if \(isFlagLike\(file\)\) die\("--file needs a path"\);/, "member-outcomes.mjs's --file guard drifted from arg.mjs's rule or lost its own wording");
103
+
104
+ // The blank spelling is the one a hand-written copy has historically dropped
105
+ // — member-outcomes.mjs's copy was `!file || file.startsWith("--")`, the rule
106
+ // with that clause missing, and `--file " "` was accepted for it. Nothing
107
+ // outside arg.mjs's own predicate should spell it again.
108
+ for (const [name, text] of [["ledger.mjs", ledger], ["member-outcomes.mjs", memberOutcomes]]) {
109
+ assert.doesNotMatch(text, /trim\(\) === ""/, `${name} hand-writes the blank-value rule again instead of calling isFlagLike`);
110
+ }
111
+
112
+ // #878's rule, on the same terms. Anchored at the export for the same
113
+ // reason the two above are, and paired with arg.mjs's OWN consumer —
114
+ // numArg() — because exporting the rule while arg.mjs kept a second copy of
115
+ // it is this ticket's defect with the files swapped.
116
+ assert.match(arg, /^export function isDigits\(value\) \{$/m, "arg.mjs no longer exports isDigits");
117
+ assert.match(arg, /if \(!isDigits\(raw\)\) die\(`--\$\{name\} needs a number, got \$\{raw\}`\);/, "numArg() restates the digits rule instead of calling isDigits");
118
+
119
+ // The two consumers that cannot route through numArg(): fleet-tick.mjs
120
+ // reads its flags with node:util's parseArgs, and review-core.mjs takes its
121
+ // `pr` as a workflow argument rather than from argv. Each keeps its own
122
+ // wording — "must be a non-negative integer" and "must be a PR number" —
123
+ // and neither may keep its own spelling of the rule.
124
+ const fleetTick = src("fleet-tick.mjs");
125
+ assert.match(fleetTick, /^import \{[^}]*\bisDigits\b[^}]*\} from "\.\/arg\.mjs";/m, "fleet-tick.mjs no longer imports isDigits from arg.mjs");
126
+ assert.match(fleetTick, /if \(!isDigits\(String\(raw\)\.trim\(\)\)\) die\(`--\$\{name\} must be a non-negative integer, got '\$\{raw\}'`\);/, "fleet-tick.mjs's integer guard drifted from arg.mjs's rule or lost its own wording");
127
+
128
+ const reviewCore = src("review-core.mjs");
129
+ assert.match(reviewCore, /^import \{[^}]*\bisDigits\b[^}]*\} from "\.\/arg\.mjs";/m, "review-core.mjs no longer imports isDigits from arg.mjs");
130
+ assert.match(reviewCore, /if \(!isDigits\(pr\)\) throw new Error\(/, "review-core.mjs's numeric-pr guard drifted from arg.mjs's rule");
131
+ });
132
+
133
+ // The three readers, run for real over the same values. `arg()` is exercised
134
+ // through a throwaway script rather than in-process because it reads the live
135
+ // process.argv and exits the process on refusal — both of which a test runner
136
+ // cannot host.
137
+ function probeFixture(t) {
138
+ const dir = mkdtempSync(join(tmpdir(), "shared-refusal-"));
139
+ t.after(() => rmSync(dir, { recursive: true, force: true }));
140
+ writeFileSync(join(dir, "arg.mjs"), readFileSync(fileURLToPath(new URL("./arg.mjs", import.meta.url))));
141
+ writeFileSync(join(dir, "probe.mjs"), [
142
+ 'import { makeDie, makeArg } from "./arg.mjs";',
143
+ 'const arg = makeArg(makeDie("probe"));',
144
+ 'console.log(arg("file") ?? "<absent>");',
145
+ "",
146
+ ].join("\n"));
147
+
148
+ // The same isolation ledger.test.mjs's own CLI fixture uses: the real `gh`
149
+ // must be unreachable, or an ACCEPTED value would carry these assertions on
150
+ // to this repo's live issue list. `git` is reachable only so that anything
151
+ // reaching defaultLedgerPath() fails on its own terms.
152
+ const realGit = spawnSync("which", ["git"], { encoding: "utf8" }).stdout.trim();
153
+ assert.ok(realGit, "shared-refusal.test.mjs setup: could not locate a `git` binary on PATH");
154
+ const bin = join(dir, "bin");
155
+ mkdirSync(bin, { recursive: true });
156
+ symlinkSync(realGit, join(bin, "git"));
157
+ const env = { ...process.env, PATH: bin };
158
+ delete env.GIT_DIR;
159
+ delete env.GIT_WORK_TREE;
160
+
161
+ // member-outcomes.mjs takes a session dir positional and refuses before it
162
+ // reaches the --file rule if that dir has no readable `subagents`, so the
163
+ // probe would otherwise measure the wrong guard.
164
+ mkdirSync(join(dir, "session", "subagents"), { recursive: true });
165
+
166
+ const run = (script, args) => spawnSync(process.execPath, [script, ...args], { encoding: "utf8", env, cwd: dir });
167
+ const LEDGER = fileURLToPath(new URL("./ledger.mjs", import.meta.url));
168
+ const MEMBER_OUTCOMES = fileURLToPath(new URL("./member-outcomes.mjs", import.meta.url));
169
+ return {
170
+ // "Refused BY THIS RULE", never merely "exited non-zero": an accepted odd
171
+ // path sends ledger.mjs on to a missing file and a tracker it cannot
172
+ // reach, which is a non-zero exit that says nothing about the guard.
173
+ viaArg: (value) => {
174
+ const r = run(join(dir, "probe.mjs"), ["--file", value]);
175
+ return r.status === 2 && /--file needs a value|--file needs a space-separated value/.test(r.stderr);
176
+ },
177
+ viaLedger: (value) => {
178
+ const r = run(LEDGER, ["--file", value, "check", "some subject"]);
179
+ return r.status === 2 && /--file needs a path|--file needs a space-separated value/.test(r.stderr);
180
+ },
181
+ // The third copy site. Pinned by SOURCE TEXT alone until #1128, which is
182
+ // a spelling and not a behaviour: the mutation that reds nothing is one
183
+ // ABOVE the `if (isFlagLike(file))` line, corrupting `file` before it
184
+ // arrives — measured, `const file = (raw ?? "").trim() || <default>` left
185
+ // every member-outcomes test green while `--file " "` wrote the
186
+ // production metrics path at exit 0. Only a spawn sees that.
187
+ viaMemberOutcomes: (value) => {
188
+ const r = run(MEMBER_OUTCOMES, [join(dir, "session"), "--file", value]);
189
+ return r.status === 2 && /--file needs a path/.test(r.stderr);
190
+ },
191
+ viaArgRaw: (args) => run(join(dir, "probe.mjs"), args),
192
+ viaLedgerRaw: (args) => run(LEDGER, args),
193
+ };
194
+ }
195
+
196
+ test("all three readers reach the same verdict on the shared rule — the copies cannot drift", (t) => {
197
+ const p = probeFixture(t);
198
+
199
+ // REFUSE on all three. The blank spellings are the ones a hand-written copy
200
+ // has historically dropped — member-outcomes.mjs's copy was `!file ||
201
+ // file.startsWith("--")`, and `--file " "` wrote the production metrics
202
+ // TSV to a whitespace-named path at exit 0.
203
+ for (const value of [" ", "\t"]) {
204
+ assert.equal(p.viaArg(value), true, `arg() must refuse ${JSON.stringify(value)}`);
205
+ assert.equal(p.viaLedger(value), true, `ledger.mjs must refuse ${JSON.stringify(value)} — its copy has drifted narrower than arg.mjs's rule`);
206
+ assert.equal(p.viaMemberOutcomes(value), true, `member-outcomes.mjs must refuse ${JSON.stringify(value)} — its copy has drifted narrower than arg.mjs's rule`);
207
+ }
208
+
209
+ // `--`-prefixed values reach the shared rule in only two of the three:
210
+ // member-outcomes.mjs refuses them one guard earlier, in its own
211
+ // unknown-option sweep, under wording that names the sweep and not --file.
212
+ // `--require-file` is #362's own case: the flag that used to become the path.
213
+ for (const value of ["--require-file", "--other"]) {
214
+ assert.equal(p.viaArg(value), true, `arg() must refuse ${JSON.stringify(value)}`);
215
+ assert.equal(p.viaLedger(value), true, `ledger.mjs must refuse ${JSON.stringify(value)} — its copy has drifted narrower than arg.mjs's rule`);
216
+ }
217
+
218
+ // ACCEPT on both sides. These are the neighbours the `--`-prefix rule is
219
+ // deliberately not allowed to cost.
220
+ //
221
+ // Asserted as "the value was USED as the path", never as "nothing refused
222
+ // it": a not-refused assertion is satisfied by any unrelated failure, and by
223
+ // a guard that swallowed the value and fell back to a default — which is the
224
+ // fail-open shape this whole family of guards exists to close. Each value is
225
+ // relative and names nothing in the fixture dir, so ledger.mjs quotes it
226
+ // back in its not-found warning, and arg() echoes it on stdout.
227
+ for (const value of ["-1", "-weird--ledger.md", "foo--bar", "plain-name.md"]) {
228
+ assert.equal(p.viaArg(value), false, `arg() must accept ${JSON.stringify(value)}`);
229
+ assert.equal(p.viaArgRaw(["--file", value]).stdout.trim(), value, `arg() accepted ${JSON.stringify(value)} but did not return it`);
230
+ assert.equal(p.viaLedger(value), false, `ledger.mjs must accept ${JSON.stringify(value)} — its copy has drifted wider than arg.mjs's rule`);
231
+ assert.match(p.viaLedgerRaw(["--file", value, "check", "s"]).stderr, new RegExp(`ledger file not found: ${value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")}\\b`), `ledger.mjs accepted ${JSON.stringify(value)} but did not read the ledger at it`);
232
+ }
233
+
234
+ // The `=` spelling, in both argv positions, on both readers. ledger.mjs's is
235
+ // pinned positionally in ledger.test.mjs already; what is pinned here is
236
+ // that the two readers agree, which is the property a copy breaks.
237
+ for (const args of [["--file=/tmp/x"], ["--file=/tmp/x", "check", "s"], ["check", "--file=/tmp/x", "s"]]) {
238
+ assert.match(p.viaLedgerRaw(args).stderr, /--file needs a space-separated value/, `ledger.mjs let \`${args.join(" ")}\` through`);
239
+ }
240
+ assert.match(p.viaArgRaw(["--file=/tmp/x"]).stderr, /--file needs a space-separated value/, "arg() let --file=<path> through");
241
+
242
+ // TWO values are excluded from the table above, deliberately and not by
243
+ // oversight: an empty string and a trailing `--file` with nothing after it.
244
+ // isFlagLike answers TRUE for both, but ledger.mjs guards its call with
245
+ // `file &&` so that those two land on its own pre-existing "given with no
246
+ // path" wording instead — the behaviour #362's Measured block records as
247
+ // already correct. Pinned here so the exclusion is a decision on the record
248
+ // rather than a hole.
249
+ const trailing = p.viaLedgerRaw(["--file"]);
250
+ assert.equal(trailing.status, 2);
251
+ assert.match(trailing.stderr, /--file given with no path/, "ledger.mjs's trailing-flag wording was absorbed into the shared rule's");
252
+ });
253
+
254
+ test("the shared rules accept what they must — the false-positive half", () => {
255
+ // A rule that refused everything would satisfy every assertion above.
256
+ for (const value of ["-1", "-weird--ledger.md", "foo--bar", "/tmp/x", "check", "0", "-"]) {
257
+ assert.equal(isFlagLike(value), false, `isFlagLike must accept ${JSON.stringify(value)}`);
258
+ }
259
+ for (const value of [undefined, "", " ", "\t\n", "--file", "--"]) {
260
+ assert.equal(isFlagLike(value), true, `isFlagLike must refuse ${JSON.stringify(value)}`);
261
+ }
262
+
263
+ // hasEqualsForm matches on `--name=`, so a longer name that merely shares
264
+ // the prefix is NOT its business — it is a flag nothing reads, which is
265
+ // sweep()'s to refuse in sweep()'s own wording. A rule that answered true
266
+ // here would turn ledger.mjs's --file guard into a refusal of --filename.
267
+ assert.equal(hasEqualsForm("file", ["--filename=x"]), false, "hasEqualsForm claimed a longer flag name sharing the prefix");
268
+ assert.equal(hasEqualsForm("file", ["--file", "x"]), false, "hasEqualsForm claimed a well-formed space-separated value");
269
+ assert.equal(hasEqualsForm("file", ["check", "a=b"]), false, "hasEqualsForm claimed a positional containing an `=`");
270
+ assert.equal(hasEqualsForm("file", ["--file=x"]), true, "hasEqualsForm missed the `=` spelling");
271
+ assert.equal(hasEqualsForm("file", ["check", "s", "--file=x"]), true, "hasEqualsForm scans only the front of argv");
272
+ // The empty value after `=`, which is the spelling most likely to read as
273
+ // "the flag is absent" on both sides.
274
+ assert.equal(hasEqualsForm("file", ["--file="]), true, "hasEqualsForm missed a bare `--file=`");
275
+ });
276
+
277
+ // ── #878: the digits rule, and the one copy the sandbox forces ────────────
278
+ //
279
+ // BOTH historical spellings, because the drift came back as either one:
280
+ // ci-state.mjs wrote `/^[0-9]+$/` and fleet-tick.mjs's int() wrote `/^\d+$/`,
281
+ // and a sweep that banned only the first stays green while the second is
282
+ // re-inlined (measured — reverting int() to its own regex reds the wiring pin
283
+ // and nothing here).
284
+ //
285
+ // Anchored exactly, so a DIFFERENT rule that happens to use the digit class
286
+ // is not caught: candidates.mjs's `Number.isInteger(limit) && limit >= 1` is
287
+ // a bounded positive-integer rule over a DEFAULTED value — not a copy of this
288
+ // one, and #878 left it where it is.
289
+ //
290
+ // Composed, never written contiguously, so this file's own source cannot
291
+ // satisfy the check it performs — the same reason
292
+ // scripts-path-citation-sweep.test.mjs gives for its stale citation.
293
+ const DIGITS_RULE = new RegExp([
294
+ ["\\^\\[0-9\\]", "\\+\\$"].join(""),
295
+ ["\\^\\\\d", "\\+\\$"].join(""),
296
+ ].join("|"));
297
+
298
+ // DERIVED, never a hand list, and the direction is what makes that safe: this
299
+ // asserts an ABSENCE across the tree, so a set discovered by reading the
300
+ // script directory can only GROW as files arrive. That is the opposite of
301
+ // arg.test.mjs's CONSUMERS/STRAYS matrices, which assert a PRESENCE per file
302
+ // and so must be spelled out — a discovered set there shrinks silently when a
303
+ // caller drops the call.
304
+ //
305
+ // Test files are excluded. A test may legitimately quote the rule to pin it,
306
+ // and a pin is not a second implementation of it — the same `grep -v test`
307
+ // scoping every sweep in arg.mjs's header uses.
308
+ const RULE_SITES = () => {
309
+ const here = fileURLToPath(new URL(".", import.meta.url));
310
+ const sites = [];
311
+ for (const name of readdirSync(here)) {
312
+ if (!/\.(mjs|js)$/.test(name) || name.endsWith(".test.mjs")) continue;
313
+ if (DIGITS_RULE.test(stripComments(readFileSync(join(here, name), "utf8")))) sites.push(name);
314
+ }
315
+ return sites.sort();
316
+ };
317
+
318
+ // The ticket's own words: "adding a second copy is the drift, not the fix".
319
+ // Before #878 the invariant had three spellings — ci-state.mjs's `/^[0-9]+$/`,
320
+ // fleet-tick.mjs's `/^\d+$/`, and candidates.mjs's Number.isInteger (which
321
+ // stays, being a bounded positive-integer rule over a defaulted value rather
322
+ // than this one) — and the fix is only a fix while the count stays at one.
323
+ // A behavioural test cannot see a second copy at all: pasted back into
324
+ // diff-stats.mjs it would refuse exactly what numArg() refuses and the whole
325
+ // suite would stay green, which is how three spellings accumulated.
326
+ test("#878: the digits rule is spelled only in arg.mjs", () => {
327
+ assert.deepEqual(
328
+ RULE_SITES(),
329
+ ["arg.mjs"],
330
+ "a copy of the digits rule appeared outside arg.mjs — arg.mjs's header says why every other consumer must import it instead",
331
+ );
332
+ });
333
+
334
+ // The verdicts themselves. Every value above this line is input the rule
335
+ // must REFUSE, and a rule that refused everything satisfies all of them —
336
+ // `42`/`"42"`/`"0"` are the must-ACCEPT half, and `42` as a NUMBER is not
337
+ // decoration: every caller holds a PR number or a count as a number, so a
338
+ // rule that lost RegExp.test's coercion would refuse every real invocation
339
+ // while still refusing every bad one. `null`/`undefined` answer FALSE here,
340
+ // which every caller depends on: each reads absence first and owes
341
+ // "required" rather than a complaint about digits.
342
+ test("#878: isDigits reaches the same verdict on both historical spellings' inputs", () => {
343
+ for (const v of ["42", 42, "0", 0, "007"]) assert.equal(isDigits(v), true, `must accept ${JSON.stringify(v)} (${typeof v})`);
344
+ for (const v of ["abc", "42x", "x42", "", " 42", "1e3", "-1", "+42", "4.0", "my-branch", null, undefined]) {
345
+ assert.equal(isDigits(v), false, `must refuse ${JSON.stringify(v)} (${typeof v})`);
346
+ }
347
+ });
348
+
349
+ // #878's numArg() returns `number | null`, and that shape is only safe while
350
+ // every caller tests absence as `=== null` — `!x` is true for a zero the
351
+ // caller plainly GAVE, which is the exact fail-open #878 closed, just moved
352
+ // from the digits rule to the caller's own absence check. Nothing in
353
+ // numArg()'s construction stops a future or careless caller from writing
354
+ // `if (!numArg(...))`; this sweep is the structural backstop the review
355
+ // comment on this ticket asked for, in the one place a discovered set is the
356
+ // right shape rather than a spelled-out one (contrast CONSUMERS/RULE_SITES
357
+ // above): the risk here IS a future file adding a numArg() import, and a
358
+ // spelled-out list would need editing at the exact moment the regression
359
+ // landed to catch it — which, by definition, it never would.
360
+ //
361
+ // Two independent checks per consumer file, because a caller can reintroduce
362
+ // the bug two ways: testing the bound variable (`if (!pr)`) or testing the
363
+ // call inline (`if (!numArg("pr"))`) before ever binding one.
364
+ test("#878: every numArg() consumer tests absence with === null, never a bare falsy check", () => {
365
+ const dir = fileURLToPath(new URL(".", import.meta.url));
366
+ const files = readdirSync(dir).filter((f) => f.endsWith(".mjs") && !f.endsWith(".test.mjs") && f !== "arg.mjs");
367
+ const consumers = [];
368
+ for (const file of files) {
369
+ const text = src(file);
370
+ if (!/^import\s*\{[^}]*\bdefineFlags\b[^}]*\}\s*from\s*"\.\/arg\.mjs";/m.test(text) || !/\bnumArg\(/.test(text)) continue;
371
+ consumers.push(file);
372
+ assert.doesNotMatch(text, /!\s*numArg\(/, `${file} tests a numArg() call inline with a bare falsy check instead of === null`);
373
+ for (const [, name] of text.matchAll(/const\s+(\w+)\s*=\s*numArg\(/g)) {
374
+ assert.doesNotMatch(
375
+ text,
376
+ new RegExp(String.raw`![\s]*\b${name}\b`),
377
+ `${file} tests numArg()'s "${name}" result with a bare falsy check instead of === null — a zero the caller gave would read as absent`,
378
+ );
379
+ }
380
+ }
381
+ // A vacuousness guard: if the import scan above ever finds nothing, every
382
+ // assertion in the loop is skipped and this test passes for the wrong
383
+ // reason. Pinned against the known set (#878's routed three, plus
384
+ // merge-gate.mjs's `--pr`, #1800), not just a non-empty check, so the scan
385
+ // itself breaking (a reformat of the import line, say) reds here instead of
386
+ // silently stopping coverage.
387
+ assert.deepEqual(consumers.sort(), ["ci-state.mjs", "diff-stats.mjs", "merge-gate.mjs", "pr-overlap.mjs"], "the numArg() consumer sweep found a different set than #878 routed — update this list deliberately for a new caller");
388
+ });