@feigi/fleet-ctl 3.24.1 → 3.24.2
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/package.json +1 -1
- package/scripts/arg.mjs +59 -56
- package/scripts/candidates.mjs +48 -48
- package/scripts/git-env.mjs +21 -22
- package/scripts/repo-root.mjs +35 -32
package/package.json
CHANGED
package/scripts/arg.mjs
CHANGED
|
@@ -2,8 +2,8 @@
|
|
|
2
2
|
// has(), sweep(), stray(), the three refusal rules
|
|
3
3
|
// isFlagLike()/hasEqualsForm()/isDigits(), and writeAll() — the short-write
|
|
4
4
|
// and EAGAIN retry loop every script's own stdout/stderr write routes
|
|
5
|
-
// through
|
|
6
|
-
//
|
|
5
|
+
// through.
|
|
6
|
+
// These helpers were five drifting copies of arg(), three of has(), seven of die() in
|
|
7
7
|
// two incompatible shapes — one paste behind on any guard fix. One copy now;
|
|
8
8
|
// a fix to the contract lands here once and reaches every caller that routes
|
|
9
9
|
// through the helper it fixes.
|
|
@@ -18,16 +18,16 @@
|
|
|
18
18
|
// argv reader cannot call arg()/has() at all, because those refuse under a
|
|
19
19
|
// GENERATED message ("--<name> needs a value") and such a reader exists
|
|
20
20
|
// precisely to refuse under its own ("--file needs a path"). ledger.mjs
|
|
21
|
-
// splices --file/--require-file out of argv itself
|
|
21
|
+
// splices --file/--require-file out of argv itself and
|
|
22
22
|
// member-outcomes.mjs reads its own --file, so both were out of arg()'s
|
|
23
23
|
// reach — and both answered that by copying the expression, which is a
|
|
24
24
|
// requirement recorded where nothing executes it.
|
|
25
25
|
//
|
|
26
|
-
//
|
|
26
|
+
// That gap is closed: the rules are stated once, as isFlagLike() and
|
|
27
27
|
// hasEqualsForm() below, and BOTH readers import and call them while keeping
|
|
28
28
|
// their own wording. No script now restates one of these rules as a value
|
|
29
29
|
// guard instead of calling it. That is executed, not documented —
|
|
30
|
-
//
|
|
30
|
+
// a test reds when a copy is re-inlined, including one
|
|
31
31
|
// re-inlined behaviour-identically, which no behavioural test can see. Read
|
|
32
32
|
// the current division with `grep -n 'from "./arg.mjs"'
|
|
33
33
|
// scripts/*.mjs | grep -v test` rather than trusting a list
|
|
@@ -51,7 +51,7 @@
|
|
|
51
51
|
// importing this file refuses its command line through a die() bound from
|
|
52
52
|
// here, and a module that binds none has no command line to refuse a flag on
|
|
53
53
|
// — review-core.mjs, which imports isDigits alone and is itself imported by
|
|
54
|
-
// review-eval.mjs, joined the `scripts/*.mjs` glob when
|
|
54
|
+
// review-eval.mjs, joined the `scripts/*.mjs` glob when it was renamed from
|
|
55
55
|
// `.js`. A future script that refuses WITHOUT makeDie falls out of this grep;
|
|
56
56
|
// that is the price of the filter, named here rather than hidden. Read that output
|
|
57
57
|
// for the roster — the scripts this header names exemplify a way of
|
|
@@ -60,8 +60,8 @@
|
|
|
60
60
|
// fleet-tick.mjs is the one script still outside arg()/has(), and
|
|
61
61
|
// deliberately: it parses its flags with node:util's parseArgs, so its
|
|
62
62
|
// unknown-flag, required-flag and range refusals are a separate edit site on
|
|
63
|
-
// its own terms. Its integer guard is no longer one of them —
|
|
64
|
-
//
|
|
63
|
+
// its own terms. Its integer guard is no longer one of them — the digits
|
|
64
|
+
// grammar has its own predicate (isDigits() below) precisely because
|
|
65
65
|
// isFlagLike() cannot express it, and int() now calls that instead of
|
|
66
66
|
// hand-writing the third spelling. What stays fleet-tick's own there is the
|
|
67
67
|
// `String(raw).trim()` its input needs and the wording of its refusal, not
|
|
@@ -82,15 +82,15 @@
|
|
|
82
82
|
|
|
83
83
|
import { writeSync } from "node:fs";
|
|
84
84
|
|
|
85
|
-
//
|
|
85
|
+
// ONE write-retry loop, not three. Resuming a short write and waiting
|
|
86
86
|
// out an EAGAIN are properties of the FD, not of any one caller, so die()
|
|
87
87
|
// below, ci-state.mjs's verdict writes and staleness.mjs's verdict() all
|
|
88
88
|
// route through writeAll() instead of each hand-rolling the same
|
|
89
89
|
// while/try/subarray. They were three independent copies held in step by a
|
|
90
90
|
// comment reading "mirrors emit()" and by nothing executable — which is
|
|
91
91
|
// exactly how one of them (ci-state.mjs's emit()) stayed the only one with no
|
|
92
|
-
// retry cap at all. board.mjs's fault() is the fourth site and
|
|
93
|
-
//
|
|
92
|
+
// retry cap at all. board.mjs's fault() is the fourth site, and it stays
|
|
93
|
+
// outside this file deliberately — its own comment says why.
|
|
94
94
|
const MAX_EAGAIN_RETRIES = 200;
|
|
95
95
|
|
|
96
96
|
// Shared across every retry: Atomics.wait never writes or notifies it, so one
|
|
@@ -104,7 +104,7 @@ const IDLE = new Int32Array(new SharedArrayBuffer(4));
|
|
|
104
104
|
// full — the state an fd reaches once a stream has been initialised on it
|
|
105
105
|
// (console.error does that to fd 2) and enough output is queued behind it. It
|
|
106
106
|
// either SHORT-WRITES, returning the count it managed and throwing nothing at
|
|
107
|
-
// all, silently truncating with no diagnostic for a catch to see
|
|
107
|
+
// all, silently truncating with no diagnostic for a catch to see;
|
|
108
108
|
// or it throws EAGAIN. So this resumes from writeSync's own return value
|
|
109
109
|
// until the buffer is empty, and reads EAGAIN as "momentarily full", waiting
|
|
110
110
|
// 1ms for the reader rather than treating it as failure. The wait is what
|
|
@@ -112,7 +112,7 @@ const IDLE = new Int32Array(new SharedArrayBuffer(4));
|
|
|
112
112
|
// bare `continue` burned a full core for the whole stall where the 1ms wait
|
|
113
113
|
// burned almost none, both delivering the same bytes.
|
|
114
114
|
//
|
|
115
|
-
// The EAGAIN retry is CAPPED
|
|
115
|
+
// The EAGAIN retry is CAPPED. Uncapped, a reader that stays open but
|
|
116
116
|
// never drains — not merely a slow one — spins here forever, and every caller
|
|
117
117
|
// is one whose whole job is to finish and report an exit code, so an
|
|
118
118
|
// indefinite hang trades that guarantee away. Past the cap this gives up on
|
|
@@ -141,7 +141,7 @@ export function writeAll(fd, text) {
|
|
|
141
141
|
return true;
|
|
142
142
|
}
|
|
143
143
|
|
|
144
|
-
// die() is writeSync, not console.error
|
|
144
|
+
// die() is writeSync, not console.error. On a pipe,
|
|
145
145
|
// process.stderr.write is ASYNC and process.exit() discards whatever is
|
|
146
146
|
// still queued — a large forwarded child stderr (gh's own) eats the refusal
|
|
147
147
|
// line that follows it, because the refusal is queued last and dropped
|
|
@@ -158,9 +158,9 @@ export function makeDie(name) {
|
|
|
158
158
|
// The try covers the TEMPLATE as well as the write, and that is the whole
|
|
159
159
|
// of its job: uncaught, a throwing msg — or anything escaping writeAll —
|
|
160
160
|
// skips process.exit(2) and drops the process to Node's default exit 1,
|
|
161
|
-
// inverting the caller's own exit-code contract
|
|
161
|
+
// inverting the caller's own exit-code contract. Hoisting the
|
|
162
162
|
// string out to writeAll's argument list reintroduces precisely that,
|
|
163
|
-
// which is why
|
|
163
|
+
// which is why a test pin requires it to sit inside.
|
|
164
164
|
// writeAll's false return is ignored on purpose, and says no more than
|
|
165
165
|
// this function always promised: the message may be lost, the exit code
|
|
166
166
|
// may not.
|
|
@@ -173,7 +173,7 @@ export function makeDie(name) {
|
|
|
173
173
|
};
|
|
174
174
|
}
|
|
175
175
|
|
|
176
|
-
//
|
|
176
|
+
// A flag given with no value must never read as the flag being
|
|
177
177
|
// absent. Every arg()-reading call site falls back with `||`/`??`, so a
|
|
178
178
|
// trailing flag used to silently substitute a default — the malformed
|
|
179
179
|
// invocation reading as a successful one.
|
|
@@ -183,19 +183,19 @@ export function makeDie(name) {
|
|
|
183
183
|
// `--flag=value` form `indexOf` cannot see (`arg()` would otherwise report
|
|
184
184
|
// the flag absent and the caller would fall back exactly as if it were).
|
|
185
185
|
// Rejecting a `--`-prefixed value does forfeit a real capability — a value
|
|
186
|
-
// that legitimately starts with `--` — and staleness.mjs
|
|
186
|
+
// that legitimately starts with `--` — and staleness.mjs is a caller
|
|
187
187
|
// that can want one: its `--gone`/`--present` value is a string quoted out of
|
|
188
|
-
// a ticket,
|
|
188
|
+
// a ticket, such as `--label ready-for-agent`. Refusing loudly here
|
|
189
189
|
// still beats silently taking the next flag as this one's value, so this
|
|
190
|
-
// guard itself does not bend for it. staleness.mjs
|
|
190
|
+
// guard itself does not bend for it. staleness.mjs instead opts a
|
|
191
191
|
// caller in per flag with its own end-of-options separator, `--gone --
|
|
192
192
|
// '<value>'`, read before arg() ever sees the value — bare, with no `--`
|
|
193
193
|
// immediately before it, this refusal still stands unchanged.
|
|
194
|
-
//
|
|
194
|
+
// The two predicates immediately below ARE those rules, exported so a
|
|
195
195
|
// caller that cannot route through arg()/has() consumes them instead of
|
|
196
196
|
// copying the expression — the header above says which callers and why.
|
|
197
197
|
// isDigits(), further down, is a third export on the same terms for a
|
|
198
|
-
// different rule
|
|
198
|
+
// different rule; these two are the ones this paragraph is about.
|
|
199
199
|
//
|
|
200
200
|
// What travels is the RULE, never the refusal text: each caller keeps its own
|
|
201
201
|
// die() wording, which is the constraint that made copying look necessary in
|
|
@@ -204,7 +204,7 @@ export function makeDie(name) {
|
|
|
204
204
|
// flag they typed and not the grammar behind it.
|
|
205
205
|
//
|
|
206
206
|
// Plain exports, not factories, because neither takes a script NAME — one is a
|
|
207
|
-
// predicate over a value, the other over an argv. That is also why
|
|
207
|
+
// predicate over a value, the other over an argv. That is also why a
|
|
208
208
|
// proposed makeCli(NAME) collapse of makeDie/makeArg/makeHas cannot absorb
|
|
209
209
|
// them whichever way it lands: those three exist to BIND a name, and these
|
|
210
210
|
// have no name to bind.
|
|
@@ -237,7 +237,7 @@ export function makeArg(die) {
|
|
|
237
237
|
};
|
|
238
238
|
}
|
|
239
239
|
|
|
240
|
-
//
|
|
240
|
+
// A boolean flag written --name=value must refuse, not read as
|
|
241
241
|
// absent — same fail-open class as arg()'s `=` guard above, but
|
|
242
242
|
// boolean-specific wording: there is no value to take, so "needs a
|
|
243
243
|
// space-separated value" would lie.
|
|
@@ -248,7 +248,7 @@ export function makeHas(die) {
|
|
|
248
248
|
};
|
|
249
249
|
}
|
|
250
250
|
|
|
251
|
-
//
|
|
251
|
+
// The digits rule, stated once. A non-numeric `--pr` was first closed in
|
|
252
252
|
// ci-state.mjs alone, and the identical shape stayed live in its siblings.
|
|
253
253
|
// Measured on the pre-fix tree against a stub `gh` that ANSWERS, the way a
|
|
254
254
|
// real one does for a branch ref: `diff-stats.mjs --pr abc` reached
|
|
@@ -266,13 +266,14 @@ export function makeHas(die) {
|
|
|
266
266
|
// payload field. Its members are ci-state.mjs, diff-stats.mjs and
|
|
267
267
|
// pr-overlap.mjs, and all three now route through numArg() below. A sweep for
|
|
268
268
|
// the flag NAME finds two of the three, which is how the third stayed open
|
|
269
|
-
// through
|
|
269
|
+
// through that first fix's review.
|
|
270
270
|
//
|
|
271
271
|
// Stated here rather than a third time at the call sites, because the
|
|
272
272
|
// invariant had no single expression: ci-state.mjs spelled it `/^[0-9]+$/`
|
|
273
273
|
// while fleet-tick.mjs's int() spells it `/^\d+$/` over a parseArgs value,
|
|
274
|
-
// each with its own wording.
|
|
275
|
-
// to stop exactly this drift, and a fourth spelling IS
|
|
274
|
+
// each with its own wording. This shared module exists, over an earlier "no
|
|
275
|
+
// shared module" ruling, to stop exactly this drift, and a fourth spelling IS
|
|
276
|
+
// the drift.
|
|
276
277
|
|
|
277
278
|
// `+`, so the empty string is not a number. arg() already refuses that value
|
|
278
279
|
// through isFlagLike, but this predicate's other consumers do not read argv
|
|
@@ -300,7 +301,7 @@ export function makeHas(die) {
|
|
|
300
301
|
// this same invariant (claim-ticket.sh, inflight.sh, release-ticket.sh,
|
|
301
302
|
// drop-merged-label.sh) carries an extra `0?*` clause that refuses them, and
|
|
302
303
|
// this rule deliberately does not adopt it — tightening here would refuse a
|
|
303
|
-
// `--pr 007` that
|
|
304
|
+
// `--pr 007` that the already-shipped guard accepts, which is a behaviour change
|
|
304
305
|
// dressed as a de-duplication.
|
|
305
306
|
//
|
|
306
307
|
// A plain export rather than a factory, for the reason isFlagLike and
|
|
@@ -322,8 +323,9 @@ export function isDigits(value) {
|
|
|
322
323
|
// header's "what travels is the RULE, never the refusal text", applied to a
|
|
323
324
|
// product whose two refusals genuinely differ in that respect.
|
|
324
325
|
//
|
|
325
|
-
// This also discharges
|
|
326
|
-
// positionally. That guard had to sit BELOW
|
|
326
|
+
// This also discharges the original ci-state.mjs guard's placement rule
|
|
327
|
+
// structurally instead of positionally. That guard had to sit BELOW
|
|
328
|
+
// ci-state.mjs's usage die because
|
|
327
329
|
// RegExp.test coerces `null` to "null": hoisted above it, an omitted `--pr`
|
|
328
330
|
// was answered with a complaint about a number and the usage line never
|
|
329
331
|
// printed. numArg() only ever tests a value it actually read, so the refusal
|
|
@@ -343,14 +345,15 @@ function readNum(die, arg, name) {
|
|
|
343
345
|
return Number(raw);
|
|
344
346
|
}
|
|
345
347
|
|
|
346
|
-
//
|
|
348
|
+
// The guards above all answer "was this flag given well?", and none of
|
|
347
349
|
// them can answer "was a flag given that nothing reads?". A MISSPELLED name is
|
|
348
350
|
// simply never looked for, so `ci-state.mjs --pr 5 --basee main` computed a
|
|
349
351
|
// real verdict against the DEFAULT base and exited 0/1 with no refusal — the
|
|
350
|
-
// same fail-open harm as
|
|
351
|
-
// value, an unread flag. It bites hardest where the
|
|
352
|
-
// by a model each run (ci-state.mjs,
|
|
353
|
-
// one landing: a doc naming
|
|
352
|
+
// same fail-open harm as a valueless flag reading as absent, reached from the
|
|
353
|
+
// other side: not an absent value, an unread flag. It bites hardest where the
|
|
354
|
+
// caller is markdown re-read by a model each run (ci-state.mjs,
|
|
355
|
+
// candidates.mjs), and one landing is already on record: a doc naming
|
|
356
|
+
// `--label` where the flag is `--require-label`.
|
|
354
357
|
//
|
|
355
358
|
// Only `--`-prefixed tokens are its business. Everything else is positional and
|
|
356
359
|
// is not — board.mjs's `build`/`serve` subcommands, and every valued flag's
|
|
@@ -358,7 +361,7 @@ function readNum(die, arg, name) {
|
|
|
358
361
|
// above refuses `--base --other` outright, so there is nothing to skip over and
|
|
359
362
|
// no need to know here which names take a value.
|
|
360
363
|
//
|
|
361
|
-
//
|
|
364
|
+
// That leftover class — a bare or single-dash token nothing reads,
|
|
362
365
|
// `ci-state.mjs --pr 42 basee main` or `-basee` — is not this function's fix,
|
|
363
366
|
// and stays out of scope here for the same reason board.mjs's subcommands are:
|
|
364
367
|
// this sweep still refuses ONLY a `--`-prefixed token, unchanged.
|
|
@@ -384,7 +387,7 @@ function readNum(die, arg, name) {
|
|
|
384
387
|
// needs a value"; both exit 2, both name a real error, both refuse before gh.
|
|
385
388
|
//
|
|
386
389
|
// candidates.mjs deliberately does NOT route through this. It accepts no
|
|
387
|
-
// positionals, so its parseArgs
|
|
390
|
+
// positionals, so its parseArgs additionally refuses a bare
|
|
388
391
|
// `candidates.mjs ready-for-agent` — which this cannot, board.mjs's
|
|
389
392
|
// subcommands being exactly that shape. Strictly stronger there; leave it.
|
|
390
393
|
//
|
|
@@ -393,9 +396,9 @@ function readNum(die, arg, name) {
|
|
|
393
396
|
// DATA — `check
|
|
394
397
|
// "--require-file silently absent when value missing"` works today and is the
|
|
395
398
|
// shape of issue titles in this repo — so this sweep would refuse working
|
|
396
|
-
// invocations, which
|
|
397
|
-
//
|
|
398
|
-
//
|
|
399
|
+
// invocations, which is worse than the bug. ledger.mjs NARROWED that gap
|
|
400
|
+
// without routing through this sweep, rather than closing it, and later
|
|
401
|
+
// narrowed it again: ledger.mjs's own refuseStrayInCheckTail() is read on
|
|
399
402
|
// `check`'s tail ALONE, and refuses a `--`-prefixed token there only when it
|
|
400
403
|
// shares that tail with something else — the shape an unquoted stray flag
|
|
401
404
|
// makes, never the shape a one-argument subject makes — so a subject that
|
|
@@ -405,7 +408,7 @@ function readNum(die, arg, name) {
|
|
|
405
408
|
// tracker query, so `the --basee flag is unread` is queried as `unread basee
|
|
406
409
|
// flag`.
|
|
407
410
|
//
|
|
408
|
-
//
|
|
411
|
+
// refuseStrayInCheckTail() was widened again, past `--`-prefixed tokens: it
|
|
409
412
|
// also refuses a bare ONE-dash spelling of ledger.mjs's own flag names
|
|
410
413
|
// (`-require-file` for `--require-file`), matched by name rather than
|
|
411
414
|
// prefix, still only when the tail carries something besides it. ledger.mjs
|
|
@@ -414,13 +417,13 @@ function readNum(die, arg, name) {
|
|
|
414
417
|
//
|
|
415
418
|
// `check` alone, on a documented-convention test that ledger.mjs states once
|
|
416
419
|
// on refuseStrayInCheckTail() itself, with the docs and the measurement behind
|
|
417
|
-
// it
|
|
420
|
+
// it — not restated here, and not restated at its call site either.
|
|
418
421
|
// What guards the other three instead is ledger.mjs's refuseStrayInId(), a
|
|
419
422
|
// bare prefix test on the id slot ahead of the tail, where a `--` token is
|
|
420
423
|
// never data.
|
|
421
424
|
//
|
|
422
425
|
// It is the LENGTH gate that spares the legitimate case, not the prefix test
|
|
423
|
-
// — refuseStrayInId()'s id-slot prefix test is now `startsWith("-")
|
|
426
|
+
// — refuseStrayInId()'s id-slot prefix test is now `startsWith("-")`,
|
|
424
427
|
// no longer the same one this sweep uses (`startsWith("--")`). The id slot
|
|
425
428
|
// can take the stricter single-dash test because no free text ever lives
|
|
426
429
|
// there — a legitimate id is bare digits, optionally `#`-prefixed. This
|
|
@@ -429,10 +432,10 @@ function readNum(die, arg, name) {
|
|
|
429
432
|
// above can't either. A prefix test with no length gate was measured
|
|
430
433
|
// refusing the legitimate subject.
|
|
431
434
|
//
|
|
432
|
-
//
|
|
435
|
+
// That narrowing does not make this file's cost disappear; it buys a smaller version of
|
|
433
436
|
// the same cost. An unquoted subject carrying a `--` word is a working
|
|
434
437
|
// invocation ledger.mjs's `check` now refuses too: `check the --basee flag is
|
|
435
|
-
// unread` answered at exit 0 before
|
|
438
|
+
// unread` answered at exit 0 before that narrowing and exits 2 after it. The residual
|
|
436
439
|
// that stays open and owned is a lone stray with no subject beside it, still
|
|
437
440
|
// taken as the subject, which ledger.mjs's own comment prices.
|
|
438
441
|
function refuseUnknown(die, known) {
|
|
@@ -443,19 +446,19 @@ function refuseUnknown(die, known) {
|
|
|
443
446
|
}
|
|
444
447
|
}
|
|
445
448
|
|
|
446
|
-
//
|
|
449
|
+
// sweep() above only ever refuses a `--`-prefixed token — deliberately,
|
|
447
450
|
// per its own comment, because staying ignorant of which names take a value
|
|
448
451
|
// is what keeps it from having to refuse board.mjs's `build`/`serve` or any
|
|
449
452
|
// flag's own value. That leaves the OTHER half of "was a flag given that
|
|
450
453
|
// nothing reads?" open: a bare word or a single dash, which sweep's
|
|
451
454
|
// `startsWith("--")` check was never going to catch — `ci-state.mjs --pr 42
|
|
452
455
|
// basee main` runs the compare against the DEFAULT base and reports a real,
|
|
453
|
-
// wrong verdict at exit 0/1, the same fail-open harm
|
|
454
|
-
// positional side rather than the misspelled-flag side. `-basee` is the
|
|
456
|
+
// wrong verdict at exit 0/1, the same fail-open harm sweep() closes, reached
|
|
457
|
+
// from the positional side rather than the misspelled-flag side. `-basee` is the
|
|
455
458
|
// likelier typo of the two, since the caller plainly meant a flag.
|
|
456
459
|
//
|
|
457
|
-
// Widening sweep's own bound past `--` cannot fix this —
|
|
458
|
-
//
|
|
460
|
+
// Widening sweep's own bound past `--` cannot fix this — the sweep is ruled
|
|
461
|
+
// never to refuse tokens outside that bound, and
|
|
459
462
|
// board.mjs's subcommands are exactly the shape a widened sweep would catch
|
|
460
463
|
// by mistake. Nor can `startsWith("-")`: it refuses a legitimate negative
|
|
461
464
|
// value such as `--spend-since -1`, which arg() accepts today. The only way
|
|
@@ -495,7 +498,7 @@ function refuseStrays(die, flags, positionals) {
|
|
|
495
498
|
}
|
|
496
499
|
}
|
|
497
500
|
|
|
498
|
-
//
|
|
501
|
+
// ONE declaration of a script's flags, and every reader bound to it.
|
|
499
502
|
// `flags` maps each name to "value" or "bool"; `positionals` is the grammar
|
|
500
503
|
// refuseStrays() above accepts ahead of the flags (board.mjs's
|
|
501
504
|
// `build`/`serve`). One key per flag, so a name cannot be declared both ways.
|
|
@@ -526,7 +529,7 @@ function refuseStrays(die, flags, positionals) {
|
|
|
526
529
|
// That refusal goes through die() at exit 2, never a thrown Error: exit 1 is
|
|
527
530
|
// a verdict in ci-state.mjs (not green), merge-gate.mjs (blocked) and
|
|
528
531
|
// tier-roles.mjs (check failed), which is the inversion makeDie() exists to
|
|
529
|
-
// prevent
|
|
532
|
+
// prevent. It is worded `bug:` because only the script's own
|
|
530
533
|
// source can reach it — no command line can make a correct table disagree
|
|
531
534
|
// with a correct read.
|
|
532
535
|
//
|
|
@@ -540,7 +543,7 @@ function refuseStrays(die, flags, positionals) {
|
|
|
540
543
|
// the needle.
|
|
541
544
|
//
|
|
542
545
|
// The TABLE, by contrast, is copied once here, before anything derives from
|
|
543
|
-
// it
|
|
546
|
+
// it: sweep() takes its names at construction while the other readers
|
|
544
547
|
// look a name up per call, so a caller mutating its own `flags` object
|
|
545
548
|
// afterwards would leave arg() accepting a name sweep() refuses. With the
|
|
546
549
|
// copy, no reader sees a later mutation, and no kind the construction check
|
|
@@ -548,10 +551,10 @@ function refuseStrays(die, flags, positionals) {
|
|
|
548
551
|
// object stays its own, unchanged — the line gitEnv() in git-env.mjs holds
|
|
549
552
|
// for its caller's `base` too.
|
|
550
553
|
//
|
|
551
|
-
//
|
|
554
|
+
// `flags` not being a plain object at all — `null`, or absent
|
|
552
555
|
// because a caller typed `{ flag: {...} }` instead of `{ flags: {...} }` and
|
|
553
556
|
// this destructures it to `undefined` — used to throw a TypeError straight
|
|
554
|
-
// out of `Object.keys(undefined)`, before
|
|
557
|
+
// out of `Object.keys(undefined)`, before the copy below was introduced.
|
|
555
558
|
// `{ ...undefined }` and `{ ...null }` both spread to `{}` without
|
|
556
559
|
// complaint, so the copy would otherwise turn a loud construction-time crash
|
|
557
560
|
// into a silently empty flag table whose every read fails later, elsewhere,
|
package/scripts/candidates.mjs
CHANGED
|
@@ -19,8 +19,8 @@
|
|
|
19
19
|
// reduction that did not apply, a capped result). 3 = the query succeeded,
|
|
20
20
|
// returned at least one row, and every row was removed by the to-spec
|
|
21
21
|
// filter — distinct from 1 so a caller such as run-team's phase 0 can say
|
|
22
|
-
// "the only labeled items are specs, run to-tickets" instead of "no work"
|
|
23
|
-
//
|
|
22
|
+
// "the only labeled items are specs, run to-tickets" instead of "no work".
|
|
23
|
+
// Exit 3 describes the FINAL query attempt only — with
|
|
24
24
|
// `--allow-fallback`, a labeled all-specs pass that falls back to a
|
|
25
25
|
// genuinely empty unfiltered pass is exit 1, not 3; the drop count is never
|
|
26
26
|
// carried across the two attempts.
|
|
@@ -32,7 +32,7 @@ import { makeDie, makeArg, makeHas } from "./arg.mjs";
|
|
|
32
32
|
const NAME = "candidates";
|
|
33
33
|
|
|
34
34
|
// die()/arg()/has() shared with the other fleet scripts — see arg.mjs for
|
|
35
|
-
// the fail-open
|
|
35
|
+
// the fail-open and pipe-safety rationale.
|
|
36
36
|
// No caller of THIS file is a hand-typed CLI. Two are markdown re-read by a
|
|
37
37
|
// model each run (next-ticket/SKILL.md, run-team/SKILL.md), which is why a
|
|
38
38
|
// malformed invocation is more plausible here than the shared guard's shape
|
|
@@ -54,14 +54,14 @@ const limit = Number(arg("limit") ?? 500);
|
|
|
54
54
|
if (!Number.isInteger(limit) || limit < 1) die(`--limit must be a positive integer, got '${arg("limit")}'`);
|
|
55
55
|
|
|
56
56
|
// The accepted flag set, declared once, and the only check on flag NAMES.
|
|
57
|
-
//
|
|
57
|
+
// Before this check, an unrecognised flag was ignored, so
|
|
58
58
|
// `--label ready-for-agent` — the spelling run-team's own phase 0 rule carried
|
|
59
59
|
// — ran the UNFILTERED query at exit 0, the widening `--require-label` exists
|
|
60
60
|
// to prevent.
|
|
61
61
|
//
|
|
62
62
|
// Runs BELOW the value guards, deliberately: where both would refuse — notably
|
|
63
63
|
// `--require-label` and `--limit` given with no value — arriving second leaves
|
|
64
|
-
// the refusal to
|
|
64
|
+
// the refusal to arg()'s wording above rather than Node's. Nothing above emits
|
|
65
65
|
// output or runs a query, so refusing this late is still refusing before gh.
|
|
66
66
|
//
|
|
67
67
|
// The catch is unconditional, and THAT is the guard. Testing `e.code` for
|
|
@@ -96,8 +96,9 @@ try {
|
|
|
96
96
|
|
|
97
97
|
if (allowFallback && !requireLabel) die("--allow-fallback is meaningless without --require-label");
|
|
98
98
|
|
|
99
|
-
//
|
|
100
|
-
// label is QUOTED into the search term, so a `"`
|
|
99
|
+
// The label quoting's other half, and the half that quoting (query() below)
|
|
100
|
+
// newly makes possible: the label is QUOTED into the search term, so a `"`
|
|
101
|
+
// inside it closes that quote
|
|
101
102
|
// early and the remainder becomes free text — the same misparse, with the fix
|
|
102
103
|
// applied. A `\` breaks the same term from the other side, because GitHub
|
|
103
104
|
// DOES honour `\"` as an escaped quote inside a qualifier: measured against
|
|
@@ -108,7 +109,7 @@ if (allowFallback && !requireLabel) die("--allow-fallback is meaningless without
|
|
|
108
109
|
// having eaten the closing quote and swallowed the whole following qualifier.
|
|
109
110
|
// Doubling does not escape it. Here the label term is LAST, so a trailing
|
|
110
111
|
// backslash leaves its value unterminated and the query answers zero rows at
|
|
111
|
-
// HTTP 200, no error —
|
|
112
|
+
// HTTP 200, no error — the unquoted label's silent empty, with the fix applied. Neither
|
|
112
113
|
// character can be represented, so refuse both at exit 2 ("the query broke")
|
|
113
114
|
// rather than send a query whose empty answer would read as exit 1.
|
|
114
115
|
if (requireLabel && /["\\]/.test(requireLabel)) die(`--require-label cannot contain a double quote or a backslash, got '${requireLabel}'`);
|
|
@@ -117,7 +118,7 @@ if (requireLabel && /["\\]/.test(requireLabel)) die(`--require-label cannot cont
|
|
|
117
118
|
// GitHub's search has no `-label:"wayfinder:*"` — and none is quoted despite
|
|
118
119
|
// the colon each value carries. Measured 2026-09-08 against feigi/fleet-plugin:
|
|
119
120
|
// negating `wayfinder:map` alone excludes exactly one more issue than the
|
|
120
|
-
// unfiltered open count
|
|
121
|
+
// unfiltered open count — a colon inside a label
|
|
121
122
|
// value is parsed as part of the label, not as a delimiter that ends it early
|
|
122
123
|
// and spills the remainder into free text, the failure mode `label:"…"`
|
|
123
124
|
// quoting exists for a SPACE (see `query()`'s comment below). Stated as a
|
|
@@ -133,7 +134,7 @@ const EXCLUDE =
|
|
|
133
134
|
"-label:in-progress -label:onhold -label:wontfix -label:needs-triage -label:needs-info -label:wayfinder:map -label:wayfinder:research -label:wayfinder:prototype -label:wayfinder:grilling -label:wayfinder:task";
|
|
134
135
|
// `d` walks the body line by line rather than one regex over the whole
|
|
135
136
|
// string, because RE2 (gojq's engine — gh applies `--jq` with gojq, not the
|
|
136
|
-
// system jq this file's own tests stub
|
|
137
|
+
// system jq this file's own tests stub) has no lookahead, so
|
|
137
138
|
// "capture every ref up to the next heading" cannot be expressed as a single
|
|
138
139
|
// pattern. A heading line (`^#{1,6}[ \t]`) toggles a running "inside a
|
|
139
140
|
// blocking section" flag on when its text DECLARES one: any of the verb
|
|
@@ -144,15 +145,15 @@ const EXCLUDE =
|
|
|
144
145
|
// `:` aside. The noun form cannot be given the verb forms' tolerance:
|
|
145
146
|
// `## Dependency injection` is an ordinary section title in a code repo, and
|
|
146
147
|
// arming on it would turn every `#N` in its bullets into a blocker the body
|
|
147
|
-
// never declared
|
|
148
|
-
//
|
|
148
|
+
// never declared. The noun form cannot be dropped either: a real brief headed
|
|
149
|
+
// its section with it, and a gate naming the verbs alone opened nothing there.
|
|
149
150
|
//
|
|
150
151
|
// Either form may carry EMPHASIS, which markdown puts outside the words:
|
|
151
152
|
// `## **Dependencies**` names a dependency exactly as `## Dependencies` does,
|
|
152
153
|
// and read without the `\*` runs it armed no section at all, so every ref its
|
|
153
|
-
// bullets declared was dropped — exit 0, nothing on stderr,
|
|
154
|
+
// bullets declared was dropped — exit 0, nothing on stderr, a silent
|
|
154
155
|
// wrong admission reached through this gate rather than through the inline
|
|
155
|
-
// label separator
|
|
156
|
+
// label separator. The runs are
|
|
156
157
|
// `\**` rather than `\*{0,2}` because `*`, `**` and `***` are all emphasis a
|
|
157
158
|
// heading is written with, and the noun form needs one on EACH side of its
|
|
158
159
|
// optional colon: markdown closes the bold before it (`**Dependencies**:`)
|
|
@@ -162,8 +163,7 @@ const EXCLUDE =
|
|
|
162
163
|
// the runs go AROUND it, and they match asterisks ONLY, so
|
|
163
164
|
// `## **Dependency injection**` still arms nothing. Widen either run to a
|
|
164
165
|
// general wildcard and that heading arms, which is the whole distinction the
|
|
165
|
-
// anchor exists to hold;
|
|
166
|
-
// engines.
|
|
166
|
+
// anchor exists to hold; a test pins both directions, on both engines.
|
|
167
167
|
//
|
|
168
168
|
// `after` is an inline label only, because `## After the migration` is
|
|
169
169
|
// ordinary narrative and arming on it invents a blocker, while a heading that
|
|
@@ -182,7 +182,7 @@ const EXCLUDE =
|
|
|
182
182
|
// match. The separator is a combined `[\s*]*` run rather than asterisk groups
|
|
183
183
|
// flanking the colon: those groups sat ahead of the separating whitespace, so
|
|
184
184
|
// they matched only asterisks flush against the phrase, and a space before the
|
|
185
|
-
// bold — where markdown actually puts it — dropped the ref
|
|
185
|
+
// bold — where markdown actually puts it — dropped the ref. Both passes
|
|
186
186
|
// are strictly line-local, which the removed `(?:depends on|…)\s+#\d+` regex
|
|
187
187
|
// was not: its `\s+` crossed newlines, so a
|
|
188
188
|
// phrase ending one line with its ref opening the next was collected and now
|
|
@@ -192,20 +192,20 @@ const EXCLUDE =
|
|
|
192
192
|
// restriction above closes. A ref elsewhere in the body — not under a
|
|
193
193
|
// heading section, not after a label — is not collected: neither pass reaches
|
|
194
194
|
// it. Verified against real gojq (`go install
|
|
195
|
-
// github.com/itchyny/gojq/cmd/gojq@v0.12.19`) on every form in
|
|
196
|
-
//
|
|
195
|
+
// github.com/itchyny/gojq/cmd/gojq@v0.12.19`) on every form in the
|
|
196
|
+
// suite's dependency-forms fixtures, not only the system jq the
|
|
197
197
|
// STUB there execs. The engines now agree on every one of those forms,
|
|
198
198
|
// including the ones that used to split. The separator is `[\t \p{Zs}*]*`
|
|
199
199
|
// and not `[\s*]*`, so `Blocked by:<U+00A0>#12` collects `[12]` under BOTH
|
|
200
200
|
// engines where it used to collect `[12]` under Oniguruma and `[]` under RE2
|
|
201
|
-
// —
|
|
201
|
+
// — the ref is ruled a real blocker, because GFM renders that line as
|
|
202
202
|
// `Blocked by: #12` and autolinks the ref, so a reader sees a dependency and
|
|
203
203
|
// an admission gate must not miss one. Since no fixture splits any more, the
|
|
204
204
|
// gated tests can no longer identify their engine by disagreement: the STUB
|
|
205
205
|
// records which binary it executed and they assert that recording is gojq.
|
|
206
206
|
// The per-position rulings are set out above the JQ declaration below.
|
|
207
207
|
//
|
|
208
|
-
// `depmiss` is the diagnostic half
|
|
208
|
+
// `depmiss` is the diagnostic half, and it is deliberately LOOSER
|
|
209
209
|
// than the gate: any heading MENTIONING the concept that the gate did not
|
|
210
210
|
// arm. The gate's own pattern is named `armed` and both halves call it, so
|
|
211
211
|
// "did not arm" is the exact complement of what opened the section rather
|
|
@@ -234,10 +234,10 @@ const EXCLUDE =
|
|
|
234
234
|
// because the only whitespace that would disturb the line this prints is the
|
|
235
235
|
// CR of a CRLF body (what GitHub's web textarea writes), and a regex there
|
|
236
236
|
// would buy cosmetics at the price of one more regex position to rule on and
|
|
237
|
-
// keep portable
|
|
238
|
-
// at the `JSON.stringify` below, because this is a stderr signal and
|
|
239
|
-
//
|
|
240
|
-
// ENGINE-PORTABLE CLASSES
|
|
237
|
+
// keep portable. `dh` never reaches stdout: the payload is stripped of it
|
|
238
|
+
// at the `JSON.stringify` below, because this is a stderr signal and a
|
|
239
|
+
// payload field is ruled out of scope.
|
|
240
|
+
// ENGINE-PORTABLE CLASSES. The program below contains no `\\s`, `\\d` or
|
|
241
241
|
// `\\b`: every position spells an explicit class. It has to, because the suite
|
|
242
242
|
// applies this expression with system jq (Oniguruma, all three Unicode-aware)
|
|
243
243
|
// while gh applies it with its embedded gojq (Go RE2, where `\\s` is
|
|
@@ -267,7 +267,7 @@ const EXCLUDE =
|
|
|
267
267
|
// Unlike `armed`/`depmiss` above, this one also has to recognize a
|
|
268
268
|
// BARE marker-only heading — no title text follows, so `[ \t]` alone
|
|
269
269
|
// never matches it, and the old open section wrongly kept collecting
|
|
270
|
-
// refs past it (
|
|
270
|
+
// refs past it (over-collection). GFM still renders a bare `##`
|
|
271
271
|
// as a real (empty) `<h2>`, so it must still close the section: `$`
|
|
272
272
|
// admits end-of-line, `\r?` admits the same position just before a
|
|
273
273
|
// CRLF line's trailing `\r` (the one `split("\n")` leaves behind).
|
|
@@ -307,18 +307,18 @@ const EXCLUDE =
|
|
|
307
307
|
// escaping below — jq's `\\p{Zs}` is `\\\\p{Zs}` in this JS source string.
|
|
308
308
|
//
|
|
309
309
|
// Measured over 24 fixtures on jq-1.7.1-apple and gojq 0.12.19: zero splits.
|
|
310
|
-
//
|
|
310
|
+
// The suite pins the rows that used to split, on both engines, and
|
|
311
311
|
// proves which engine each gated test actually reached.
|
|
312
312
|
//
|
|
313
|
-
// NATIVE EDGES
|
|
313
|
+
// NATIVE EDGES. `d` is the UNION of the body scan above and the
|
|
314
314
|
// numbers on the issue's native "blocked by" edges, which ride the same
|
|
315
|
-
// query as gh's `blockedBy` field — no extra round trip, the cost
|
|
316
|
-
// deferred
|
|
315
|
+
// query as gh's `blockedBy` field — no extra round trip, the cost they were
|
|
316
|
+
// once deferred on — merged and sorted by the final `unique`. Union, not
|
|
317
317
|
// replacement: to-tickets still writes blockers only as body text, and a
|
|
318
318
|
// hand-written body can name a blocker nobody wired as an edge, so dropping
|
|
319
319
|
// the scan would silently un-block both. The edges close the opposite miss:
|
|
320
|
-
//
|
|
321
|
-
// cross, and only
|
|
320
|
+
// a body can chain its blocker as `**#N**` behind a parenthetical the scan
|
|
321
|
+
// cannot cross, and then only the native edge carries it. `d` stays RAW — a closed
|
|
322
322
|
// blocker's number is kept although the edge carries its state, exactly as
|
|
323
323
|
// the scan keeps one, because the consumers (run-team / next-ticket step 2)
|
|
324
324
|
// judge openness and a `d` whose two halves meant different things would
|
|
@@ -389,7 +389,7 @@ const JQ =
|
|
|
389
389
|
|
|
390
390
|
function query(label) {
|
|
391
391
|
// The label is a VALUE in GitHub's query language, not part of its syntax,
|
|
392
|
-
// so it is quoted rather than interpolated raw
|
|
392
|
+
// so it is quoted rather than interpolated raw. Unquoted, a value
|
|
393
393
|
// ends at the FIRST SPACE and every word after it becomes a free-text term
|
|
394
394
|
// instead — measured 2026-08-17, `label:ready-for-agent candidates` returns
|
|
395
395
|
// strictly fewer issues here than `label:ready-for-agent`, and on
|
|
@@ -398,7 +398,7 @@ function query(label) {
|
|
|
398
398
|
// the narrowed result as the label's own answer, and an empty one as exit 1,
|
|
399
399
|
// "the query worked and there is no work" — against a queue that is not
|
|
400
400
|
// empty. Reachable wherever a repo remapped its triage labels, which
|
|
401
|
-
//
|
|
401
|
+
// a per-repo triage-label mapping exists to invite. Stated as relationships
|
|
402
402
|
// rather than counts on purpose: the queue churns hourly, so a pinned digit
|
|
403
403
|
// is wrong within a day and reads as the fix having regressed.
|
|
404
404
|
//
|
|
@@ -511,7 +511,7 @@ function refuseIfCapped(rows, description) {
|
|
|
511
511
|
// worth a fence parser: every drop is logged by number, so a false positive is
|
|
512
512
|
// loud rather than silent.
|
|
513
513
|
//
|
|
514
|
-
//
|
|
514
|
+
// Two shapes the predicate leaves undecided by accident, now decided.
|
|
515
515
|
// Depth is `#{2,6}`, not `##` — two or more `#`, not exactly two, and capped
|
|
516
516
|
// where CommonMark caps an ATX heading, same as `depnums`' own `#{1,6}` above:
|
|
517
517
|
// a line of seven `#` is not a heading and must not read as the signature.
|
|
@@ -526,7 +526,7 @@ function refuseIfCapped(rows, description) {
|
|
|
526
526
|
// tagged). The separator between marker and text is `[ \t]+` — horizontal
|
|
527
527
|
// whitespace only, not `\s+` — so a heading can never span a line break: a
|
|
528
528
|
// body whose line is exactly `##` with `User Stories` starting the next
|
|
529
|
-
// line no longer reads as the same heading. That is also
|
|
529
|
+
// line no longer reads as the same heading. That is also the ruling for
|
|
530
530
|
// this position, on GFM's own rule: only a space or a tab opens a heading, so
|
|
531
531
|
// `##<U+00A0>User Stories` renders as a PARAGRAPH and is not a spec at all.
|
|
532
532
|
//
|
|
@@ -538,7 +538,7 @@ function refuseIfCapped(rows, description) {
|
|
|
538
538
|
// the `\r` of a CRLF body — what GitHub's web textarea writes — and leak that
|
|
539
539
|
// spec silently. It is spelled out rather than left as `\s*` because `\s` is
|
|
540
540
|
// the one construct here whose meaning changes with the engine (Oniguruma
|
|
541
|
-
// reads it Unicode-aware, RE2 as `[\t\n\f\r ]`), and
|
|
541
|
+
// reads it Unicode-aware, RE2 as `[\t\n\f\r ]`), and the position is ruled
|
|
542
542
|
// by what GFM renders: `## User Stories` padded with U+00A0, EM SPACE or
|
|
543
543
|
// IDEOGRAPHIC SPACE are all real `<h2>`s, so all three are still to-spec specs
|
|
544
544
|
// and all three are dropped. `\p{Zs}` is exactly "renders as a blank" and both
|
|
@@ -548,8 +548,8 @@ function refuseIfCapped(rows, description) {
|
|
|
548
548
|
// is not dropped. Before the ruling this position diverged — a U+00A0-padded
|
|
549
549
|
// heading was a spec under the system jq the suite execs and NOT one under the
|
|
550
550
|
// gojq gh applies, so in production dropSpecs never fired and the spec shipped
|
|
551
|
-
// as a claimable ticket. Pinned against real gojq
|
|
552
|
-
// which
|
|
551
|
+
// as a claimable ticket. Pinned against real gojq by a test that also pins
|
|
552
|
+
// which engine it reached.
|
|
553
553
|
//
|
|
554
554
|
// This is the ONLY line of defence — nothing downstream catches a spec. A
|
|
555
555
|
// leaked one is decided and needs no human hands, so it passes both of phase
|
|
@@ -561,7 +561,7 @@ function refuseIfCapped(rows, description) {
|
|
|
561
561
|
// unfiltered query is a SUPERSET of the labeled one, and every spec dropped in
|
|
562
562
|
// pass 1 is dropped again in pass 2. Unattributed, that reads as the same spec
|
|
563
563
|
// counted twice; named, a reader can tell "2 drops, 1 spec, seen both passes"
|
|
564
|
-
// from "2 drops, 2 specs" at a glance. Deliberately not deduplicated
|
|
564
|
+
// from "2 drops, 2 specs" at a glance. Deliberately not deduplicated.
|
|
565
565
|
function dropSpecs(rows, pass) {
|
|
566
566
|
const kept = [];
|
|
567
567
|
for (const { spec, ...rest } of rows) {
|
|
@@ -582,13 +582,13 @@ refuseIfCapped(rows, requireLabel ? ` with label:${requireLabel}` : "");
|
|
|
582
582
|
// After refuseIfCapped, never before: filtering first can shrink the array below
|
|
583
583
|
// `limit` and the cap check would stop seeing a truncated list. Before the
|
|
584
584
|
// emptiness test below, never after: a queue whose every row was filtered out
|
|
585
|
-
// IS an empty queue
|
|
586
|
-
// one, for a caller reading only the exit code, is
|
|
585
|
+
// IS an empty queue. Telling that case apart from a genuinely empty
|
|
586
|
+
// one, for a caller reading only the exit code, is exit 3's job — set at
|
|
587
587
|
// the foot of this file, which is what the raw count below is captured for.
|
|
588
588
|
// Raw count captured just before the filter that can empty `rows` out, so
|
|
589
589
|
// `allFilteredOut` below can tell "nothing came back" from "rows came back
|
|
590
590
|
// and the filter ate them all". Reassigned wholesale in the fallback branch,
|
|
591
|
-
// never OR'd/summed with pass 1's value —
|
|
591
|
+
// never OR'd/summed with pass 1's value — exit 3's edge case is exactly a pass 1
|
|
592
592
|
// all-filtered (raw>0) whose fallback pass is genuinely empty (raw=0), which
|
|
593
593
|
// must read as the fallback's own facts (exit 1), not a merge of the two.
|
|
594
594
|
const rawCount1 = rows.length;
|
|
@@ -614,7 +614,7 @@ if (rows.length === 0 && allowFallback && requireLabel) {
|
|
|
614
614
|
// next-ticket step 2), not here, and to-tickets publishes chains blockers-first
|
|
615
615
|
// so lower numbers are the blockers anyway. `d` covers every body form
|
|
616
616
|
// to-tickets publishes — heading + list, bold/inline label, the original bare
|
|
617
|
-
// phrasings —
|
|
617
|
+
// phrasings — and GitHub's native blocked-by edges too, so
|
|
618
618
|
// a chain wired only as edges reaches this sort with its blockers in `d`.
|
|
619
619
|
// Native sub-issue links are still not read: parent/child is hierarchy, not
|
|
620
620
|
// blocking, so a blocker recorded only as one reaches it with none.
|
|
@@ -622,7 +622,7 @@ rows.sort((a, b) => a.n - b.n);
|
|
|
622
622
|
|
|
623
623
|
for (const r of rows) {
|
|
624
624
|
console.error(` #${r.n} [${r.l.join(",")}] ${r.t}${r.d.length ? ` deps:${r.d.join(";")}` : ""}`);
|
|
625
|
-
//
|
|
625
|
+
// A SECOND line, never a field on the row above: that row's format is
|
|
626
626
|
// what phase 0 reads and it stays byte-identical, `deps:` suppressed on an
|
|
627
627
|
// empty list and all. Indented under the row it belongs to, and repeating
|
|
628
628
|
// `#N` so a reader who greps the wording still gets the candidate with it.
|
|
@@ -650,8 +650,8 @@ for (const r of rows) {
|
|
|
650
650
|
//
|
|
651
651
|
// `dh` is dropped here rather than never collected: the heading text exists
|
|
652
652
|
// only inside gh's process, where the reduction runs, so the only way to it is
|
|
653
|
-
// a field on the row — and
|
|
654
|
-
// stderr signal being the whole of what
|
|
653
|
+
// a field on the row — and a payload field is ruled out of scope, the
|
|
654
|
+
// stderr signal being the whole of what this diagnostic asks for. Here, and not in
|
|
655
655
|
// `dropSpecs`' destructure where the row's other stderr-only field (`spec`)
|
|
656
656
|
// leaves the payload: that runs BEFORE the per-candidate lines above, which
|
|
657
657
|
// are what `dh` is for. A replacer, not a rebuilt array: it drops the key
|
|
@@ -662,7 +662,7 @@ console.log(JSON.stringify(rows, (k, v) => (k === "dh" ? undefined : v)));
|
|
|
662
662
|
|
|
663
663
|
// Exit 1 for a successful query with no survivors, exit 3 when those zero
|
|
664
664
|
// survivors are the filter's doing rather than the query's — see the
|
|
665
|
-
// exit-code contract in the file header
|
|
665
|
+
// exit-code contract in the file header. `allFilteredOut` already
|
|
666
666
|
// describes only the final attempt (see above), so no further branching on
|
|
667
667
|
// requireLabel/allowFallback is needed here.
|
|
668
668
|
//
|
package/scripts/git-env.mjs
CHANGED
|
@@ -2,37 +2,36 @@
|
|
|
2
2
|
// two exports, one per half of the same spawn. `gitEnv()` builds the env the
|
|
3
3
|
// git child is given; `workspaceDirFromGitCommonDir()` turns what the most
|
|
4
4
|
// common of those children answers with, `rev-parse --git-common-dir`, into
|
|
5
|
-
// the workspace directory a run's files live under. The first half
|
|
6
|
-
// reasoning
|
|
5
|
+
// the workspace directory a run's files live under. The first half's
|
|
6
|
+
// reasoning is below; the second's sits beside its own function.
|
|
7
7
|
//
|
|
8
8
|
// GIT_DIR and GIT_WORK_TREE outrank both the child's cwd and an explicit `-C`
|
|
9
|
-
// argument — measured directly
|
|
9
|
+
// argument — measured directly: a `git rev-parse`/`ls-files` call
|
|
10
10
|
// pointed at a repository via `cwd` or `-C` still answers for whichever
|
|
11
11
|
// repository an ambient GIT_DIR or GIT_WORK_TREE names, silently, often at
|
|
12
|
-
// exit 0.
|
|
13
|
-
//
|
|
14
|
-
//
|
|
15
|
-
//
|
|
12
|
+
// exit 0. The shell scripts under this directory close the identical class
|
|
13
|
+
// with one line, `unset GIT_DIR GIT_WORK_TREE`; there is no shell to unset in
|
|
14
|
+
// here, so the child's env has to be built instead — and the reasons
|
|
15
|
+
// net.sh/worktree.sh are exempt from that line ("a library... unset there would
|
|
16
16
|
// reach back into the caller's environment") do not transfer: a spawned
|
|
17
17
|
// child's env object is already private to it, never the calling process's.
|
|
18
18
|
//
|
|
19
19
|
// `fleet-state.mjs`'s `statePath()` and `ledger.mjs`'s tracker-query probe
|
|
20
20
|
// each spell the same three lines inline — `{ ...process.env }` then two
|
|
21
|
-
// `delete`s — predating this module, and
|
|
22
|
-
//
|
|
23
|
-
//
|
|
21
|
+
// `delete`s — predating this module, and that duplication is exactly the
|
|
22
|
+
// reason a THIRD hand-spelled copy (the hazard measured here, `ledger.mjs`'s
|
|
23
|
+
// `defaultLedgerPath()`) should not become a fourth.
|
|
24
24
|
// A shared helper also turns "does this call scrub the ambient vars" back
|
|
25
25
|
// into a one-name grep, `gitEnv(`, the way `unset GIT_DIR GIT_WORK_TREE` is
|
|
26
|
-
// one for shell
|
|
26
|
+
// one for shell.
|
|
27
27
|
//
|
|
28
28
|
// The two pre-existing inline sites are deliberately NOT migrated to call
|
|
29
|
-
// this.
|
|
30
|
-
// `fleet-state.mjs`'s `statePath()
|
|
31
|
-
//
|
|
32
|
-
//
|
|
33
|
-
//
|
|
34
|
-
//
|
|
35
|
-
// carries both of them by name instead of by import.
|
|
29
|
+
// this. Both are already fixed and covered by tests of their own —
|
|
30
|
+
// `fleet-state.mjs`'s `statePath()`, and `ledger.mjs`'s tracker-query scrub
|
|
31
|
+
// ("an inherited GIT_DIR or GH_REPO cannot retarget the query…") — and
|
|
32
|
+
// touching either to satisfy a detector would be churn with no behavioural
|
|
33
|
+
// change. The suite's census of ambient-var scrubs carries both of them by
|
|
34
|
+
// name instead of by import.
|
|
36
35
|
|
|
37
36
|
import { realpathSync } from "node:fs";
|
|
38
37
|
import { dirname, resolve } from "node:path";
|
|
@@ -65,11 +64,11 @@ export function gitEnv(overrides = {}, base = process.env) {
|
|
|
65
64
|
// from the checkout root agree about the run's single ledger, its single
|
|
66
65
|
// heartbeat and its single board.
|
|
67
66
|
//
|
|
68
|
-
// Three callers hand-spelled that resolution, one apiece, before
|
|
67
|
+
// Three callers hand-spelled that resolution, one apiece, before this function:
|
|
69
68
|
// `ledger.mjs`'s `defaultLedgerPath()`, `fleet-state.mjs`'s `statePath()` and
|
|
70
69
|
// `board.mjs`'s `resolveCockpitInstance()` — and `fleet-state.mjs`'s own
|
|
71
70
|
// comment had already written down the trigger ("if a third file ever needs
|
|
72
|
-
// this, the resolution itself should move"), which
|
|
71
|
+
// this, the resolution itself should move"), which the third caller's arrival tripped.
|
|
73
72
|
// What is NOT shared is the part each caller owns: the filename it joins on
|
|
74
73
|
// (`ledger.md`, `heartbeat.json`, `.fleet`), the wording of the warning it
|
|
75
74
|
// degrades with, and what its own degraded answer is. Hence the seam: this
|
|
@@ -100,9 +99,9 @@ export function gitEnv(overrides = {}, base = process.env) {
|
|
|
100
99
|
* than a path; a trailing newline riding on a real answer would be discarded
|
|
101
100
|
* by `dirname()` anyway, together with the rest of the final segment.
|
|
102
101
|
*
|
|
103
|
-
* `canonicalise` is OPT-IN, and deliberately so
|
|
102
|
+
* `canonicalise` is OPT-IN, and deliberately so. Only `board.mjs`
|
|
104
103
|
* takes it: a symlinked route to one workspace derives a SECOND port and a
|
|
105
|
-
* second state directory for a cockpit already being served
|
|
104
|
+
* second state directory for a cockpit already being served, so the
|
|
106
105
|
* cockpit's key has to be the canonical form. `ledger.mjs` and
|
|
107
106
|
* `fleet-state.mjs` do not — both PRINT the path they resolve (the ledger in
|
|
108
107
|
* `check`'s JSON, both in their degrade warnings), and realpath would change
|
package/scripts/repo-root.mjs
CHANGED
|
@@ -7,21 +7,21 @@
|
|
|
7
7
|
// with it. What the premise costs is a precondition: there has to be a `.git`
|
|
8
8
|
// at or above the file. A checkout and a worktree both have one; a bare `git
|
|
9
9
|
// archive` extraction does not. Review specialists used to measure the suite in
|
|
10
|
-
// exactly such an extraction, which cost this repo 19 silent declines per run
|
|
11
|
-
//
|
|
10
|
+
// exactly such an extraction, which cost this repo 19 silent declines per run;
|
|
11
|
+
// since then the review snapshot is `git init`ed and committed
|
|
12
12
|
// at cut time, so the declines below are no longer the review's normal path.
|
|
13
13
|
// They remain the answer for any OTHER repo-less tree — a hand-cut archive, a
|
|
14
14
|
// tarball unpacked in CI — which is why the guard stays rather than becoming
|
|
15
15
|
// dead weight.
|
|
16
16
|
//
|
|
17
|
-
// Before
|
|
17
|
+
// Before this module, each file paid that cost as a bare module-scope `execFileSync`
|
|
18
18
|
// whose failure escaped. Node cannot attribute a throw during module
|
|
19
19
|
// evaluation to any test, so it synthesised one entry at line 1 of the file and
|
|
20
20
|
// the run showed a single failure in place of the file's real tests — a
|
|
21
21
|
// diagnostic that reads like a regression in the tree under test rather than an
|
|
22
22
|
// environment missing a repository.
|
|
23
23
|
//
|
|
24
|
-
//
|
|
24
|
+
// There is a second way "there has to be a `.git`" is not the same
|
|
25
25
|
// question as "there has to be THIS repository": git's discovery walk answers
|
|
26
26
|
// with whatever working tree it finds first, and nothing about that answer
|
|
27
27
|
// says it is fleet-plugin's own tree rather than an ambient repository the
|
|
@@ -33,11 +33,11 @@
|
|
|
33
33
|
// through it.
|
|
34
34
|
//
|
|
35
35
|
// The first fix here compared the resolved root's OWN `.claude-plugin/
|
|
36
|
-
// plugin.json` name against this file's — and
|
|
36
|
+
// plugin.json` name against this file's — and a review measured that a
|
|
37
37
|
// DIFFERENT checkout of this same plugin, sitting above some unrelated caller
|
|
38
38
|
// directory, still passed: same name, wrong tree. The second fix required the
|
|
39
39
|
// running script to be somewhere INSIDE the resolved root — and that review
|
|
40
|
-
// measured it regresses
|
|
40
|
+
// measured it regresses the ambient-repository case's OWN shape: pre-cutover, an installed copy
|
|
41
41
|
// under the harness's own plugin cache genuinely sat inside the operator's
|
|
42
42
|
// dotfiles checkout, which was exactly the ambient repository the bug is about.
|
|
43
43
|
// Containment is not identity either. What repoRoot now insists on is
|
|
@@ -46,10 +46,10 @@
|
|
|
46
46
|
// must both be tracked by `root`'s OWN git (`git ls-files --error-unmatch`).
|
|
47
47
|
// An installed plugin's cache directory sits inside the operator's dotfiles
|
|
48
48
|
// checkout but is never committed there, so it fails; a real checkout, a
|
|
49
|
-
// worktree, a `plugin/`-nested layout
|
|
49
|
+
// worktree, a `plugin/`-nested layout, and a vendored copy inside
|
|
50
50
|
// a monorepo all pass, because in each of those the file genuinely IS part of
|
|
51
51
|
// that repository's own tracked tree. The self-relative manifest lookup is
|
|
52
|
-
// what
|
|
52
|
+
// what survived the payload's re-nesting under `plugin/`: a
|
|
53
53
|
// hardcoded `root/.claude-plugin/plugin.json` breaks the moment the manifest
|
|
54
54
|
// moves a level deeper, while `dirname(thisFile)/../.claude-plugin/
|
|
55
55
|
// plugin.json` does not care where `root` (the git toplevel) ends up relative
|
|
@@ -68,14 +68,15 @@
|
|
|
68
68
|
// binary at all. A repository may well be
|
|
69
69
|
// present; what is missing is an answer. A
|
|
70
70
|
// probe that could not look must never read as
|
|
71
|
-
// an answer
|
|
72
|
-
//
|
|
73
|
-
//
|
|
71
|
+
// an answer: buying a skip with it would
|
|
72
|
+
// reproduce that defect inside the guard
|
|
73
|
+
// written against it. `repoRoot` THROWS here,
|
|
74
74
|
// which is the loud module-load failure the
|
|
75
|
-
//
|
|
75
|
+
// earlier bare-`execFileSync` code produced
|
|
76
|
+
// for these.
|
|
76
77
|
// the root answers, but its identity, not non-emptiness, not name
|
|
77
78
|
// own git does not TRACK this equality, and not mere containment either
|
|
78
|
-
// file or this file's own (
|
|
79
|
+
// file or this file's own (each measured failing): a root that
|
|
79
80
|
// manifest merely names the same plugin, contains an
|
|
80
81
|
// untracked copy, or answers non-empty for
|
|
81
82
|
// some other reason, is still a stranger's
|
|
@@ -92,7 +93,7 @@
|
|
|
92
93
|
// skipping; each caller's own non-vacuity
|
|
93
94
|
// guard is what judges it. The
|
|
94
95
|
// wrong-repository half of this used to live
|
|
95
|
-
// here too, before
|
|
96
|
+
// here too, before it moved up into the
|
|
96
97
|
// identity check above, where it can throw
|
|
97
98
|
// loudly instead of waiting on each caller's
|
|
98
99
|
// guard to notice.
|
|
@@ -131,9 +132,10 @@ const NO_REPOSITORY_ANYWHERE = /not a git repository \(or any /;
|
|
|
131
132
|
* caller resolved. Relative to `cwd` would ask the wrong question, since
|
|
132
133
|
* `cwd` is exactly the thing under test; relative to a resolved `root` would
|
|
133
134
|
* have to guess how many levels separate the manifest from the git toplevel,
|
|
134
|
-
* and
|
|
135
|
-
*
|
|
136
|
-
*
|
|
135
|
+
* and the payload's re-nesting under `plugin/` already changed that answer
|
|
136
|
+
* once. This guesses nothing — wherever
|
|
137
|
+
* this file is copied (a checkout, a worktree, an installed plugin cache, or
|
|
138
|
+
* a `plugin/` subdirectory), its own manifest is always exactly
|
|
137
139
|
* one directory up from it.
|
|
138
140
|
*/
|
|
139
141
|
function ownManifestPath() {
|
|
@@ -180,7 +182,7 @@ export function ownPluginName() {
|
|
|
180
182
|
* nearest the pathspec itself (measured: from an unrelated cwd, the same
|
|
181
183
|
* absolute path is reported "outside repository at <that other repo>").
|
|
182
184
|
*
|
|
183
|
-
* GIT_DIR scrubbed (
|
|
185
|
+
* GIT_DIR scrubbed (gitEnv()): measured, an ambient GIT_DIR answers
|
|
184
186
|
* for a DIFFERENT repository regardless of `cwd` — `ls-files
|
|
185
187
|
* --error-unmatch` on a path this file's OWN repository genuinely tracks
|
|
186
188
|
* then exits 1 "did not match any file(s) known to git", a false negative
|
|
@@ -206,7 +208,7 @@ function isTrackedBy(root, path) {
|
|
|
206
208
|
* than an ambient repository the caller's directory happened to nest under.
|
|
207
209
|
*
|
|
208
210
|
* Containment (is the running script somewhere INSIDE `root`?) was tried
|
|
209
|
-
* first and is not enough — it regresses
|
|
211
|
+
* first and is not enough — it regresses the ambient-repository case's own measured shape. There,
|
|
210
212
|
* pre-cutover, self was under the harness's own plugin cache at
|
|
211
213
|
* `fleet-plugin/fleet/0.1.1/scripts/repo-root.mjs`, and `root` resolved to
|
|
212
214
|
* that cache's own parent dotfiles directory, which genuinely CONTAINED self
|
|
@@ -218,7 +220,7 @@ function isTrackedBy(root, path) {
|
|
|
218
220
|
* working tree is exactly as much a stranger as no copy at all. This also
|
|
219
221
|
* accepts every tree that legitimately IS this file's own — this checkout, a
|
|
220
222
|
* worktree, a
|
|
221
|
-
* `plugin/`-nested layout
|
|
223
|
+
* `plugin/`-nested layout, even a vendored copy inside a larger
|
|
222
224
|
* monorepo — because in every one of those cases the file is actually
|
|
223
225
|
* COMMITTED to that repository's index, which an ambient-but-unrelated
|
|
224
226
|
* repository's cache directory never is.
|
|
@@ -286,13 +288,13 @@ function dotGitAtOrAbove(cwd) {
|
|
|
286
288
|
*
|
|
287
289
|
* A working tree that IS found is not returned on the strength of being
|
|
288
290
|
* found — `assertOwnRoot` checks it is this plugin's own before it ever
|
|
289
|
-
* reaches a caller
|
|
291
|
+
* reaches a caller. A non-empty wrong root throws exactly as loudly as
|
|
290
292
|
* an unanswerable one; the old guard against it lived only in each caller's
|
|
291
293
|
* non-vacuity check on `trackedShellScripts`, which a non-empty foreign
|
|
292
294
|
* answer sailed straight through.
|
|
293
295
|
*/
|
|
294
296
|
export function repoRoot(cwd) {
|
|
295
|
-
// GIT_DIR/GIT_WORK_TREE scrubbed (
|
|
297
|
+
// GIT_DIR/GIT_WORK_TREE scrubbed (gitEnv()): measured from a
|
|
296
298
|
// subdirectory of a real working tree (the realistic shape — `cwd` here is
|
|
297
299
|
// wherever the calling script happens to live, rarely the root itself) —
|
|
298
300
|
// an ambient GIT_DIR alone answers `--show-toplevel` with `cwd` ITSELF, not
|
|
@@ -338,8 +340,8 @@ export function skipWithoutRepo(root, subject) {
|
|
|
338
340
|
// file at the path, for any reader — rather than a failure to look: nothing
|
|
339
341
|
// there at all (ENOENT); a file standing where one of the path's own
|
|
340
342
|
// directories should be (ENOTDIR); and a symlink that loops, or chains past the
|
|
341
|
-
// kernel's link limit (ELOOP), which no reader can ever open a file through
|
|
342
|
-
//
|
|
343
|
+
// kernel's link limit (ELOOP), which no reader can ever open a file through.
|
|
344
|
+
// `root` is git's own resolved toplevel, so every link counted toward
|
|
343
345
|
// that limit is one inside the tracked path itself — a fact about the tree,
|
|
344
346
|
// not about where the checkout sits.
|
|
345
347
|
//
|
|
@@ -371,7 +373,7 @@ function isRegularFile(path) {
|
|
|
371
373
|
* Every file tracked in the working tree at `root` that `pathspecs` match,
|
|
372
374
|
* repo-relative — the one discovery rule behind all three exports below, so what
|
|
373
375
|
* `root` must be and which repository answers cannot drift apart between
|
|
374
|
-
* them
|
|
376
|
+
* them. `caller` is the export's own name, for the refusal.
|
|
375
377
|
*
|
|
376
378
|
* `root` must be a real root — call it only where `repoRoot` answered. A `null`
|
|
377
379
|
* root is rejected rather than absorbed into an empty list: `execFileSync`
|
|
@@ -390,13 +392,13 @@ function isRegularFile(path) {
|
|
|
390
392
|
* checked out on disk), a file standing where the path's own directory was.
|
|
391
393
|
* Every caller reads each path it is handed, and one absent path in the answer
|
|
392
394
|
* aborted that read with a raw ENOENT, leaving every real finding in every
|
|
393
|
-
* other file unreported
|
|
395
|
+
* other file unreported. Passing over it lets nothing ship unswept: a
|
|
394
396
|
* deletion that is committed does not ship, and one that is not is swept again
|
|
395
397
|
* in any checkout that has the file; a link with no file behind it has no text
|
|
396
398
|
* to sweep. A path the probe could not look at is not one of these — it
|
|
397
399
|
* throws, as NO_REGULAR_FILE_THERE says.
|
|
398
400
|
*
|
|
399
|
-
* GIT_DIR scrubbed (
|
|
401
|
+
* GIT_DIR scrubbed (gitEnv()): measured, an ambient GIT_DIR silently
|
|
400
402
|
* substitutes a DIFFERENT repository's tracked list for `root`'s own — the
|
|
401
403
|
* caller's non-vacuity guard cannot see this, since the wrong list is
|
|
402
404
|
* routinely non-empty. GIT_WORK_TREE is inert here (measured, for `*.sh` and
|
|
@@ -465,7 +467,7 @@ const NODE_SHEBANG = /^#!\s*(?:\S*\/)?(?:env(?:\s+(?:-(?:u|-unset|C|-chdir)(?:=\
|
|
|
465
467
|
const SHEBANG_BYTES = 256;
|
|
466
468
|
|
|
467
469
|
// The most of a first line ever read, and the length at which one is not a
|
|
468
|
-
// node shebang
|
|
470
|
+
// node shebang. Reading on to the end of the line however long read a
|
|
469
471
|
// tracked `#!` file holding no newline into memory whole to answer a boolean —
|
|
470
472
|
// measured, 300 MiB of one peaked above 1.1 GiB, and one past the longest
|
|
471
473
|
// string V8 builds (~512 MiB) threw ERR_STRING_TOO_LONG out of the whole
|
|
@@ -476,9 +478,10 @@ const SHEBANG_BYTES = 256;
|
|
|
476
478
|
// Linux, on a prefix naming node — is one no author writes.
|
|
477
479
|
//
|
|
478
480
|
// A cap, not a verdict on the bytes before it: those are not judged at all,
|
|
479
|
-
// so this is never
|
|
481
|
+
// so this is never a prefix verdict, the kind hasNodeShebang() refuses to
|
|
482
|
+
// give. Refused rather than
|
|
480
483
|
// thrown, because one pathological tracked file must not abort every sweep's
|
|
481
|
-
// listing
|
|
484
|
+
// listing; rather than listed, because a sweep reads each listed file
|
|
482
485
|
// whole, which would move the unbounded read, not remove it.
|
|
483
486
|
const SHEBANG_MAX_BYTES = 4096;
|
|
484
487
|
|
|
@@ -488,7 +491,7 @@ const SHEBANG_MAX_BYTES = 4096;
|
|
|
488
491
|
* first read and grows past it only for a longer line, never past
|
|
489
492
|
* SHEBANG_MAX_BYTES: a first line that long or longer, newline not counted, is
|
|
490
493
|
* not one, and nothing past the cap is read. A verdict on the prefix one read
|
|
491
|
-
* holds parts from the line's own both ways
|
|
494
|
+
* holds parts from the line's own both ways: it misses a `node` past
|
|
492
495
|
* its end, reads `nodemon` cut after its `node` as `node` at the end of the
|
|
493
496
|
* line, and decodes a character it cuts in half as U+FFFD. A file that does
|
|
494
497
|
* not open with `#!` is decided on that first read however long its first
|
|
@@ -530,7 +533,7 @@ function hasNodeShebang(path, buf) {
|
|
|
530
533
|
* Every tracked file this repository ships that the consumer's own `node`
|
|
531
534
|
* executes, in the working tree at `root`, repo-relative: each `*.mjs`, and
|
|
532
535
|
* any other file whose first line is a node shebang — the extensionless
|
|
533
|
-
* entrypoints `fleet-run`, `fleet-bootstrap` and `fleet-provenance
|
|
536
|
+
* entrypoints `fleet-run`, `fleet-bootstrap` and `fleet-provenance`.
|
|
534
537
|
* A shebang decides, never an extension alone: `plugin/workflows/*.js` is ESM
|
|
535
538
|
* a harness runs and plain node never loads, and carries none. Test files —
|
|
536
539
|
* `*.test.mjs`, the one naming this repository gives them — are not shipped,
|