rungate 0.8.13 → 0.8.16
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/README.md +182 -0
- package/gates/.gate-salt +1 -1
- package/hooks/HarnessAFKGate.hook.ts +5 -1
- package/hooks/HookCurrency.hook.ts +11 -8
- package/hooks/MergeGuard.hook.ts +7 -1
- package/hooks/StaleTTLCleanup.hook.ts +4 -4
- package/hooks/VerifyPhaseLock.hook.ts +3 -3
- package/hooks/lib/findWorkflow.ts +3 -2
- package/hooks/lib/paths.ts +14 -2
- package/hooks/lib/utils.ts +23 -3
- package/lib/active-milestone.ts +50 -0
- package/lib/ai-review-rounds.ts +99 -0
- package/lib/ai-review-suppression.ts +200 -21
- package/lib/bash-write-guard.ts +397 -23
- package/lib/board-flow.ts +280 -0
- package/lib/board-lane-health.ts +578 -0
- package/lib/board-mirror.ts +136 -39
- package/lib/board-ready-fanout.ts +297 -14
- package/lib/board-ready-rule.ts +1211 -0
- package/lib/board-throughput.ts +136 -0
- package/lib/board-walkthrough.ts +240 -0
- package/lib/body-evidence.ts +203 -0
- package/lib/branch-protection.ts +399 -9
- package/lib/bun-version.ts +36 -0
- package/lib/cli-commands.ts +75 -4
- package/lib/closing-reference-audit.ts +307 -6
- package/lib/config-loader.ts +254 -25
- package/lib/config-readers.ts +170 -10
- package/lib/config-trackable.ts +96 -57
- package/lib/conformity.ts +121 -7
- package/lib/create-sc.ts +25 -2
- package/lib/derived-spec.ts +21 -9
- package/lib/filing-compliance.ts +367 -0
- package/lib/filing-plan.ts +47 -21
- package/lib/finding-arbiter.ts +79 -5
- package/lib/finding-jury.ts +43 -4
- package/lib/finding-promotion.ts +1123 -0
- package/lib/generators/agents-md.ts +149 -0
- package/lib/git-isolation.ts +137 -1
- package/lib/github-api-base.ts +66 -0
- package/lib/github.ts +194 -9
- package/lib/graphql-cursor.ts +80 -0
- package/lib/hook-scopes.ts +78 -0
- package/lib/issue-create-override.ts +415 -3
- package/lib/issue-decomposition.ts +124 -7
- package/lib/issue-extraction.ts +9 -7
- package/lib/issue-file-overlap.ts +373 -0
- package/lib/issue-filing-gate.ts +1109 -52
- package/lib/issue-repair.ts +90 -9
- package/lib/issue-shape.ts +199 -0
- package/lib/live-issues.ts +31 -2
- package/lib/local-work.ts +423 -0
- package/lib/markdown-fence.ts +134 -0
- package/lib/milestone-title.ts +46 -0
- package/lib/scaffold/ai-review-findings.ts +148 -3
- package/lib/scaffold/ai-review-step.ts +65 -5
- package/lib/scaffold/ai-review-unmeasured-workflow.ts +3 -0
- package/lib/scaffold/steps.ts +115 -9
- package/lib/source-census.ts +108 -0
- package/lib/spec-deps.ts +55 -11
- package/lib/spec-placement.ts +203 -13
- package/lib/spec-registry.ts +75 -16
- package/lib/spec-source.ts +609 -0
- package/lib/spec-write-sweep.ts +4 -0
- package/lib/stage-ladder.ts +896 -3
- package/lib/state-claim-readings.ts +252 -0
- package/lib/success-doc.ts +7 -6
- package/lib/test-command-positions.ts +135 -1
- package/lib/work-status.ts +551 -0
- package/lib/worktree-repo.ts +14 -2
- package/package.json +7 -1
- package/scripts/ai-review-findings.ts +8 -13
- package/scripts/ai-review-threads.ts +16 -17
- package/scripts/audit-closing-references.ts +330 -0
- package/scripts/audit-specs.ts +59 -103
- package/scripts/board-conformance.ts +747 -40
- package/scripts/board-mirror.ts +594 -13
- package/scripts/board-ready.ts +979 -0
- package/scripts/board-snapshot.ts +464 -12
- package/scripts/claim-files.ts +578 -0
- package/scripts/criterion-inventory.ts +526 -50
- package/scripts/finding-promotion.ts +547 -0
- package/scripts/generate-code-map.ts +1 -1
- package/scripts/plan-issues.ts +279 -40
- package/scripts/plan-spec.ts +105 -3
- package/scripts/sync-sc-status.ts +147 -7
- package/scripts/worktree-census.ts +958 -0
- package/scripts/worktree-sweep.ts +269 -0
|
@@ -32,12 +32,16 @@
|
|
|
32
32
|
* A producer that repaired the thing it measures would make the reading
|
|
33
33
|
* true by taking it.
|
|
34
34
|
*/
|
|
35
|
+
import { spawnSync } from "child_process";
|
|
35
36
|
import { existsSync, readFileSync } from "fs";
|
|
36
37
|
import { isAbsolute, join } from "path";
|
|
37
38
|
import { parseArgs } from "util";
|
|
39
|
+
import { describeSpecSource, resolveSpecSource, type GitRunner } from "../lib/spec-source";
|
|
38
40
|
import { openFrontier, phaseOf } from "../lib/board-mirror";
|
|
41
|
+
import { withoutAmbientGitOverrides } from "../lib/git-isolation";
|
|
39
42
|
import { createGitHubClient, listMilestones } from "../lib/github";
|
|
40
|
-
import { readBoardConfig, readQueueLabel } from "../lib/config-readers";
|
|
43
|
+
import { readBoardConfig, readBoardInputs, readQueueLabel } from "../lib/config-readers";
|
|
44
|
+
import { resolveRepoSlug } from "../lib/branch-cleanup";
|
|
41
45
|
import {
|
|
42
46
|
inMilestoneFamily,
|
|
43
47
|
readIssueStates,
|
|
@@ -48,7 +52,18 @@ import {
|
|
|
48
52
|
type LiveIssue,
|
|
49
53
|
type ProjectFieldReading,
|
|
50
54
|
} from "../lib/live-issues";
|
|
51
|
-
import {
|
|
55
|
+
import {
|
|
56
|
+
criterionCoverage,
|
|
57
|
+
milestonePlan,
|
|
58
|
+
placementCoverage,
|
|
59
|
+
placementReading,
|
|
60
|
+
type CriterionCoverage,
|
|
61
|
+
} from "../lib/spec-placement";
|
|
62
|
+
// SC-2615, SC-2616, SC-2617 — the three repository-wide populations.
|
|
63
|
+
import { answerableIds, criterionAnswer, specCriteriaIn, specPathSweep } from "../lib/board-mirror";
|
|
64
|
+
import { dependencyPlan } from "../lib/spec-deps";
|
|
65
|
+
import type { DeclaredWork, PlannedEdge, RepoIssueCriteria, SpecDeferral, SpecPlacementRow } from "./board-conformance";
|
|
66
|
+
import { parseCriteria } from "../lib/spec-evidence";
|
|
52
67
|
|
|
53
68
|
/**
|
|
54
69
|
* THE one non-zero exit, declared once so `test/board-snapshot.test.ts` can
|
|
@@ -208,9 +223,267 @@ export interface ProducedSnapshot {
|
|
|
208
223
|
* {@link criterionCoverage}, which owns that decision.
|
|
209
224
|
*/
|
|
210
225
|
criteria: CriterionCoverage[];
|
|
226
|
+
/**
|
|
227
|
+
* The three REPOSITORY-WIDE populations — SC-2615, SC-2616, SC-2617.
|
|
228
|
+
*
|
|
229
|
+
* Optional in the type because they are optional on the wire: each is
|
|
230
|
+
* emitted only when it could be taken, and `board-conformance` reads an
|
|
231
|
+
* absent key as UNMEASURED rather than as a zero.
|
|
232
|
+
*
|
|
233
|
+
* The row types are IMPORTED from the reader rather than spelled again
|
|
234
|
+
* here. Two declarations of one wire shape are two deciders that agree —
|
|
235
|
+
* `.claude/rules/checks-must-be-able-to-fail.md` — and nothing would have
|
|
236
|
+
* gone red when they drifted. The import is `type`-only and the reader has
|
|
237
|
+
* no relative imports of its own, so its mutation battery is untouched.
|
|
238
|
+
*/
|
|
239
|
+
specPlacements?: SpecPlacementRow[];
|
|
240
|
+
/** SC-2734: the bank in `.claude/spec-deferral-ratchet.json`. Absent when it could not be read. */
|
|
241
|
+
specDeferrals?: SpecDeferral[];
|
|
242
|
+
repoIssues?: RepoIssueCriteria[];
|
|
243
|
+
plannedEdges?: PlannedEdge[];
|
|
244
|
+
/** SC-2752: unticked criteria in in-scope specs and open stage items. Absent when it could not be read. */
|
|
245
|
+
declaredWork?: DeclaredWork[];
|
|
246
|
+
}
|
|
247
|
+
|
|
248
|
+
/**
|
|
249
|
+
* The work this repository DECLARES — SC-2752, #1953.
|
|
250
|
+
*
|
|
251
|
+
* Every unticked criterion in an in-scope spec, then every open stage item
|
|
252
|
+
* in `project-state.json`. In scope is the same population `spec-placement`
|
|
253
|
+
* counts: a spec that states criteria (`PLANNED` or `UNPLANNED`) and is not
|
|
254
|
+
* deferred. The criteria are read through `parseCriteria`, the one reader of
|
|
255
|
+
* a spec's checkbox lines, so "unticked" has one answer in the tree.
|
|
256
|
+
*
|
|
257
|
+
* A consumer repository has no `project-state.json`: an absent file declares
|
|
258
|
+
* no stage work, which is a measured fact. A file that is present and will
|
|
259
|
+
* not parse, an UNREADABLE in-scope spec, or a spec that cannot be read is
|
|
260
|
+
* returned as `{}` — the key omitted, which `declared-work` reads as
|
|
261
|
+
* UNMEASURED. A shorter list is exactly what a tree with fewer commitments
|
|
262
|
+
* produces, so a partial read must never be emitted as one.
|
|
263
|
+
*/
|
|
264
|
+
export function readDeclaredWork(
|
|
265
|
+
root: string,
|
|
266
|
+
specs: readonly { path: string; state: SpecPlacementRow["state"]; deferred?: boolean }[],
|
|
267
|
+
): { declaredWork?: DeclaredWork[] } {
|
|
268
|
+
const work: DeclaredWork[] = [];
|
|
269
|
+
for (const s of specs) {
|
|
270
|
+
if (s.deferred === true || s.state === "NO_CRITERIA") continue;
|
|
271
|
+
if (s.state === "UNREADABLE") return {};
|
|
272
|
+
let content: string;
|
|
273
|
+
try {
|
|
274
|
+
content = readFileSync(join(root, s.path), "utf-8");
|
|
275
|
+
} catch {
|
|
276
|
+
// Named as UNMEASURED by the omitted key, never read as an empty spec.
|
|
277
|
+
return {};
|
|
278
|
+
}
|
|
279
|
+
for (const c of parseCriteria(content)) if (!c.ticked) work.push({ kind: "criterion", id: c.id, source: s.path });
|
|
280
|
+
}
|
|
281
|
+
const statePath = join(root, "project-state.json");
|
|
282
|
+
if (existsSync(statePath)) {
|
|
283
|
+
let state: unknown;
|
|
284
|
+
try {
|
|
285
|
+
state = JSON.parse(readFileSync(statePath, "utf-8"));
|
|
286
|
+
} catch {
|
|
287
|
+
return {};
|
|
288
|
+
}
|
|
289
|
+
// Every level must be the shape it claims, or the population is unread.
|
|
290
|
+
// `JSON.parse` accepts `null` and `[]`, and optional chaining on either
|
|
291
|
+
// reads as "no stages", which would drop the stage half silently (AI
|
|
292
|
+
// review of #2096). Only a plan with no `stages` key declares none.
|
|
293
|
+
const isObject = (v: unknown): v is Record<string, unknown> =>
|
|
294
|
+
v !== null && typeof v === "object" && !Array.isArray(v);
|
|
295
|
+
if (!isObject(state)) return {};
|
|
296
|
+
const stages = state.stages;
|
|
297
|
+
if (stages !== undefined && !Array.isArray(stages)) return {};
|
|
298
|
+
for (const stage of (stages ?? []) as unknown[]) {
|
|
299
|
+
if (!isObject(stage) || !Array.isArray(stage.items)) return {};
|
|
300
|
+
for (const item of stage.items as unknown[]) {
|
|
301
|
+
if (!isObject(item)) return {};
|
|
302
|
+
if (item.done !== false || typeof item.id !== "string") continue;
|
|
303
|
+
work.push({
|
|
304
|
+
kind: "stage-item",
|
|
305
|
+
id: item.id,
|
|
306
|
+
source: "project-state.json",
|
|
307
|
+
issue: typeof item.issue === "number" ? item.issue : null,
|
|
308
|
+
});
|
|
309
|
+
}
|
|
310
|
+
}
|
|
311
|
+
}
|
|
312
|
+
return { declaredWork: work };
|
|
313
|
+
}
|
|
314
|
+
|
|
315
|
+
/** The path the deferral bank lives at, relative to the project root — SC-2734. */
|
|
316
|
+
export const DEFERRAL_BANK = ".claude/spec-deferral-ratchet.json";
|
|
317
|
+
|
|
318
|
+
/**
|
|
319
|
+
* Read the deferral bank — SC-2734. Returns `{}` (the key omitted) when the
|
|
320
|
+
* file is absent or is not `{ "deferred": [{ path, criteria }] }`, and says
|
|
321
|
+
* which on stderr, because a corrupt bank is never a missing one.
|
|
322
|
+
*/
|
|
323
|
+
export function readDeferralBank(root: string): { specDeferrals?: SpecDeferral[] } {
|
|
324
|
+
const path = join(root, DEFERRAL_BANK);
|
|
325
|
+
if (!existsSync(path)) {
|
|
326
|
+
process.stderr.write(`board-snapshot: ${DEFERRAL_BANK} is absent; deferred specs cannot be checked\n`);
|
|
327
|
+
return {};
|
|
328
|
+
}
|
|
329
|
+
let raw: unknown;
|
|
330
|
+
try {
|
|
331
|
+
raw = JSON.parse(readFileSync(path, "utf-8"));
|
|
332
|
+
} catch (e) {
|
|
333
|
+
process.stderr.write(`board-snapshot: ${DEFERRAL_BANK} could not be parsed (${(e as Error).message}); deferred specs cannot be checked\n`);
|
|
334
|
+
return {};
|
|
335
|
+
}
|
|
336
|
+
const list = (raw as { deferred?: unknown })?.deferred;
|
|
337
|
+
if (!Array.isArray(list) || !list.every(d => typeof d?.path === "string" && Number.isInteger(d?.criteria))) {
|
|
338
|
+
process.stderr.write(`board-snapshot: ${DEFERRAL_BANK} is not { "deferred": [{ path, criteria }] }; deferred specs cannot be checked\n`);
|
|
339
|
+
return {};
|
|
340
|
+
}
|
|
341
|
+
return { specDeferrals: list.map(d => ({ path: d.path as string, criteria: d.criteria as number })) };
|
|
342
|
+
}
|
|
343
|
+
|
|
344
|
+
/**
|
|
345
|
+
* `git -C <root> …`, built per root so the runner cannot be pointed at one
|
|
346
|
+
* checkout while the reading is taken in another.
|
|
347
|
+
*
|
|
348
|
+
* Injected for the same reason {@link BoardSnapshotGitHub} is: a case that
|
|
349
|
+
* reaches a real repository measures whatever this machine happens to be on,
|
|
350
|
+
* and goes green or red for reasons the case never wrote down.
|
|
351
|
+
*/
|
|
352
|
+
/**
|
|
353
|
+
* How long any one `git` call may take before it is killed.
|
|
354
|
+
*
|
|
355
|
+
* **One of these calls is network I/O.** `resolveSpecSource` runs `git fetch`,
|
|
356
|
+
* and a stalled remote or an HTTPS remote that drops to a credential prompt
|
|
357
|
+
* blocks `spawnSync` forever. Through `board-conformance` the outer
|
|
358
|
+
* `PRODUCE_TIMEOUT_MS` eventually kills the child, but `board-snapshot` is
|
|
359
|
+
* also a standalone entry point and there is nothing above it — so an
|
|
360
|
+
* unattended run wedges with no bound at all. A wedge is worse than a
|
|
361
|
+
* refusal, because nothing observes it. Review of #1896 round 3.
|
|
362
|
+
*
|
|
363
|
+
* **And it must be strictly UNDER the outer bound, which is why it is
|
|
364
|
+
* derived rather than written.** Round 12 found the two equal: this was
|
|
365
|
+
* `60_000` and `board-conformance`'s `PRODUCE_TIMEOUT_MS` is
|
|
366
|
+
* `Number(process.env.RUNGATE_PRODUCE_TIMEOUT_MS) || 60_000`. With both at
|
|
367
|
+
* 60s the outer `spawnSync` kills the whole child at the same moment the
|
|
368
|
+
* inner timeout would fire, so the specific message this code builds —
|
|
369
|
+
* *"it timed out — the bound is 60000ms"* — never reaches anyone through
|
|
370
|
+
* the primary caller. The reader saw `board-snapshot was killed by
|
|
371
|
+
* SIGTERM` instead, which names the wrong bound and the wrong subject.
|
|
372
|
+
*
|
|
373
|
+
* A diagnostic that cannot fire in the path it was written for is the
|
|
374
|
+
* shape `.claude/rules/checks-must-be-able-to-fail.md` calls a line in a
|
|
375
|
+
* report. Reading the same env var keeps the margin under a consumer who
|
|
376
|
+
* lowers the outer bound, which a fixed smaller number would not.
|
|
377
|
+
*/
|
|
378
|
+
export const GIT_TIMEOUT_FRACTION = 0.5;
|
|
379
|
+
|
|
380
|
+
/** The outer bound this must stay under, read the same way the outer reads it. */
|
|
381
|
+
export function gitTimeoutFor(env: NodeJS.ProcessEnv): number {
|
|
382
|
+
const outer = Number(env.RUNGATE_PRODUCE_TIMEOUT_MS) || 60_000;
|
|
383
|
+
return Math.max(1, Math.floor(outer * GIT_TIMEOUT_FRACTION));
|
|
211
384
|
}
|
|
212
385
|
|
|
213
|
-
export
|
|
386
|
+
export const GIT_TIMEOUT_MS = gitTimeoutFor(process.env);
|
|
387
|
+
|
|
388
|
+
/**
|
|
389
|
+
* The ambient environment with every git override removed.
|
|
390
|
+
*
|
|
391
|
+
* **The list is not declared here.** Round 8 of this review added a
|
|
392
|
+
* seven-name denylist to this file and round 9 found it short by the whole
|
|
393
|
+
* `GIT_CONFIG*` family — which is the predictable outcome of a second
|
|
394
|
+
* registry, not bad luck about one entry: two deciders over one question
|
|
395
|
+
* are behaviourally one, and no case here could tell which was answering
|
|
396
|
+
* (`.claude/rules/checks-must-be-able-to-fail.md`). `lib/git-isolation.ts`
|
|
397
|
+
* has owned this set since #1001, so this is the declaration's second
|
|
398
|
+
* consumer rather than its second spelling.
|
|
399
|
+
*
|
|
400
|
+
* {@link withoutAmbientGitOverrides} is the half that only REMOVES.
|
|
401
|
+
* `gitIsolatedEnv` is deliberately not used: it additionally sets
|
|
402
|
+
* `GIT_CONFIG_GLOBAL=/dev/null`, which discards `credential.helper` —
|
|
403
|
+
* measured on this machine as the system gitconfig's `osxkeychain` — and
|
|
404
|
+
* {@link GIT_TIMEOUT_MS}'s comment above records that one of these calls
|
|
405
|
+
* is a `git fetch`. Isolation that cannot authenticate turns a reading
|
|
406
|
+
* into a refusal.
|
|
407
|
+
*/
|
|
408
|
+
export function gitEnv(from: NodeJS.ProcessEnv): NodeJS.ProcessEnv {
|
|
409
|
+
return { ...withoutAmbientGitOverrides(from), GIT_TERMINAL_PROMPT: "0" };
|
|
410
|
+
}
|
|
411
|
+
|
|
412
|
+
/**
|
|
413
|
+
* `spawnSync`, injected so a case can assert WHAT was asked for.
|
|
414
|
+
*
|
|
415
|
+
* A timeout is invisible from outside unless something hangs, and a test
|
|
416
|
+
* that hangs to prove it does not hang is not a test. The seam puts the
|
|
417
|
+
* options object where a case can read it, and lets a case hand back the
|
|
418
|
+
* shape `spawnSync` returns when it kills a child — which is the half that
|
|
419
|
+
* actually decides what the caller sees.
|
|
420
|
+
*/
|
|
421
|
+
export type GitSpawn = typeof spawnSync;
|
|
422
|
+
|
|
423
|
+
export const LIVE_GIT = (root: string, spawn: GitSpawn = spawnSync): GitRunner => {
|
|
424
|
+
return args => {
|
|
425
|
+
const r = spawn("git", ["-C", root, ...args], {
|
|
426
|
+
encoding: "utf-8",
|
|
427
|
+
timeout: GIT_TIMEOUT_MS,
|
|
428
|
+
// A prompt is a hang wearing a different hat: git waits on a terminal
|
|
429
|
+
// nobody is sitting at. Refusing to ask is what makes the timeout the
|
|
430
|
+
// last line of defence rather than the first.
|
|
431
|
+
//
|
|
432
|
+
// **AND THE REPO-LOCATING VARIABLES ARE STRIPPED.** `GIT_DIR`,
|
|
433
|
+
// `GIT_WORK_TREE` and friends take precedence over `-C root`'s
|
|
434
|
+
// discovery, so a caller that already set them — a git hook, a
|
|
435
|
+
// wrapper around its own nested git — silently points every call
|
|
436
|
+
// here at a DIFFERENT repository while each downstream check still
|
|
437
|
+
// reports a clean, confident reading for the wrong tree. That is
|
|
438
|
+
// this module's whole defect reached through the environment
|
|
439
|
+
// instead of through an exit code. Review of #1896 round 8.
|
|
440
|
+
env: gitEnv(process.env),
|
|
441
|
+
});
|
|
442
|
+
// `code` carries `status`, and `status` is NULL when the process never
|
|
443
|
+
// ran — no `git` on PATH — or when it was killed by a signal, which now
|
|
444
|
+
// includes the timeout above. Both are a different fact from any exit
|
|
445
|
+
// code, and `lib/spec-source.ts` refuses on either rather than reading
|
|
446
|
+
// it as an answer about a file.
|
|
447
|
+
//
|
|
448
|
+
// **BUT THEY ARE NOT THE SAME SENTENCE, AND A SIGNAL IS NOT A
|
|
449
|
+
// MECHANISM.** Measured, with Bun's `spawnSync`:
|
|
450
|
+
//
|
|
451
|
+
// timeout status null signal SIGTERM code ETIMEDOUT
|
|
452
|
+
// maxBuffer status null signal SIGTERM code ENOBUFS
|
|
453
|
+
// no binary status UNDEFINED signal null code ENOENT
|
|
454
|
+
//
|
|
455
|
+
// Two things fall out, and neither was in the review that prompted
|
|
456
|
+
// this. The middle row is indistinguishable from the first by signal
|
|
457
|
+
// alone, so only `ETIMEDOUT` may name the bound — `r.signal !== null`
|
|
458
|
+
// attributed an out-of-buffer kill, or an OOM killer, to a timeout
|
|
459
|
+
// that had not fired. And the last row returns **undefined**, not
|
|
460
|
+
// null, so `code: r.status` made `inRepo.code === null` false and a
|
|
461
|
+
// missing `git` walked past the one guard written for it into a
|
|
462
|
+
// working-tree read. `?? null` is the fix and the tri-state is the
|
|
463
|
+
// lesson again.
|
|
464
|
+
const code = r.status ?? null;
|
|
465
|
+
const why =
|
|
466
|
+
code !== null || r.error === undefined
|
|
467
|
+
? ""
|
|
468
|
+
: (r.error as NodeJS.ErrnoException).code === "ETIMEDOUT"
|
|
469
|
+
? `${r.error.message} (timed out — the bound is ${GIT_TIMEOUT_MS}ms)`
|
|
470
|
+
: r.signal !== null
|
|
471
|
+
? `${r.error.message} (killed by ${r.signal}; the cause was not reported as a timeout)`
|
|
472
|
+
: `${r.error.message} (it never started — this is not a timeout)`;
|
|
473
|
+
return {
|
|
474
|
+
ok: r.status === 0,
|
|
475
|
+
code,
|
|
476
|
+
stdout: r.stdout ?? "",
|
|
477
|
+
stderr: [r.stderr ?? "", why].filter(s => s !== "").join("\n"),
|
|
478
|
+
};
|
|
479
|
+
};
|
|
480
|
+
};
|
|
481
|
+
|
|
482
|
+
export async function main(
|
|
483
|
+
argv: string[],
|
|
484
|
+
gh: BoardSnapshotGitHub = LIVE_GITHUB,
|
|
485
|
+
git: (root: string) => GitRunner = LIVE_GIT,
|
|
486
|
+
): Promise<number> {
|
|
214
487
|
let parsed;
|
|
215
488
|
try {
|
|
216
489
|
parsed = parseArgs({
|
|
@@ -228,9 +501,25 @@ export async function main(argv: string[], gh: BoardSnapshotGitHub = LIVE_GITHUB
|
|
|
228
501
|
}
|
|
229
502
|
|
|
230
503
|
const { values, positionals } = parsed;
|
|
231
|
-
|
|
504
|
+
// THE ROOT IS RESOLVED FIRST, because the config under it is now one of
|
|
505
|
+
// the places the arguments come from (#1718). It used to be read after
|
|
506
|
+
// every argument check, which is fine when arguments are the only source
|
|
507
|
+
// and impossible once they are not.
|
|
508
|
+
const root = values["project-root"] ?? process.cwd();
|
|
509
|
+
const configured = readBoardInputs(root);
|
|
510
|
+
|
|
511
|
+
// **An argument the caller gave always wins, and a BLANK one still
|
|
512
|
+
// refuses.** Falling back to config on a blank would substitute a value
|
|
513
|
+
// for one somebody typed — `--prefix ""` is a mistake to name, not a
|
|
514
|
+
// request for the default. So the fallback is reached only by absence,
|
|
515
|
+
// which is the one case that carries no instruction to override.
|
|
516
|
+
const specArg = positionals[0] ?? configured.engineSpec ?? undefined;
|
|
232
517
|
if (!specArg) {
|
|
233
|
-
console.error(
|
|
518
|
+
console.error(
|
|
519
|
+
`board-snapshot: no spec given, and no \`board.engineSpec\` in this project's rungate config ` +
|
|
520
|
+
`(read from ${root}). Pass the spec as the first argument, or set \`board.engineSpec\` so the ` +
|
|
521
|
+
`command can take its own reading.\n\n${USAGE}`,
|
|
522
|
+
);
|
|
234
523
|
return REFUSAL_EXIT;
|
|
235
524
|
}
|
|
236
525
|
// ONE reading, trimmed once — the same binding `plan-spec` and `plan-deps`
|
|
@@ -238,30 +527,90 @@ export async function main(argv: string[], gh: BoardSnapshotGitHub = LIVE_GITHUB
|
|
|
238
527
|
// milestone titles starting with the space, matched none of the live ones,
|
|
239
528
|
// and reported a conformant board as needing every milestone created.
|
|
240
529
|
// Round 1 of #1705.
|
|
241
|
-
const prefixRead = readMilestonePrefix(values.prefix);
|
|
530
|
+
const prefixRead = readMilestonePrefix(values.prefix ?? configured.milestonePrefix ?? undefined);
|
|
242
531
|
if (prefixRead.kind !== "given") {
|
|
243
532
|
console.error(
|
|
244
533
|
prefixRead.kind === "absent"
|
|
245
|
-
? `board-snapshot: --prefix is required
|
|
534
|
+
? `board-snapshot: --prefix is required, and no \`board.milestonePrefix\` is set in this ` +
|
|
535
|
+
`project's rungate config (read from ${root})\n\n${USAGE}`
|
|
246
536
|
: `board-snapshot: --prefix was given as ${JSON.stringify(prefixRead.raw)}, which is blank. ` +
|
|
247
537
|
`It would match no milestone on the board and report every phase as missing.\n\n${USAGE}`,
|
|
248
538
|
);
|
|
249
539
|
return REFUSAL_EXIT;
|
|
250
540
|
}
|
|
251
541
|
const prefix = prefixRead.prefix;
|
|
252
|
-
|
|
542
|
+
// The third input, same shape: the flag, then the environment CI sets,
|
|
543
|
+
// then the project's own `origin`. `resolveRepoSlug` is the existing
|
|
544
|
+
// binding for that last step and carries its own reason when it fails —
|
|
545
|
+
// a second reader here would be two deciders over one fact.
|
|
546
|
+
//
|
|
547
|
+
// **AND THE SAME BLANK RULE, which review of #1890 found applied to two
|
|
548
|
+
// of the three inputs.** `"" ?? x` keeps `""`, and `resolveRepoSlug`'s
|
|
549
|
+
// own `if (repo && repo.trim())` is falsy for it, so `--repo ""` — a CI
|
|
550
|
+
// line interpolating an unset `$REPO` — fell through to this checkout's
|
|
551
|
+
// `origin` and took a live reading against a repository the caller never
|
|
552
|
+
// named, without even the provenance line, which fires only when the
|
|
553
|
+
// flag was ABSENT. Spelled here rather than inside `resolveRepoSlug`:
|
|
554
|
+
// its other callers may legitimately read a blank as "not given", and
|
|
555
|
+
// this command's contract is that a typed empty is a mistake to name.
|
|
556
|
+
if (values.repo !== undefined && String(values.repo).trim() === "") {
|
|
557
|
+
console.error(
|
|
558
|
+
`board-snapshot: --repo was given as ${JSON.stringify(values.repo)}, which is blank. Falling back to ` +
|
|
559
|
+
`this project's origin would take a reading against a repository you did not name. Pass a value, or ` +
|
|
560
|
+
`omit --repo entirely.\n\n${USAGE}`,
|
|
561
|
+
);
|
|
562
|
+
return REFUSAL_EXIT;
|
|
563
|
+
}
|
|
564
|
+
const slug = resolveRepoSlug({ projectRoot: root, repo: values.repo ?? process.env.GITHUB_REPOSITORY });
|
|
565
|
+
const repo = slug.slug;
|
|
253
566
|
if (!repo) {
|
|
254
|
-
console.error(
|
|
567
|
+
console.error(
|
|
568
|
+
`board-snapshot: --repo is required (or set GITHUB_REPOSITORY). Falling back to this ` +
|
|
569
|
+
`project's origin remote did not resolve one either: ${slug.reason ?? "no reason given"}\n\n${USAGE}`,
|
|
570
|
+
);
|
|
255
571
|
return REFUSAL_EXIT;
|
|
256
572
|
}
|
|
257
573
|
|
|
258
|
-
|
|
574
|
+
// WHERE EACH INPUT CAME FROM, on stderr so it never reaches the snapshot
|
|
575
|
+
// on stdout. A reading taken from config and one taken from the command
|
|
576
|
+
// line are the same bytes downstream, and only one of them is reproducible
|
|
577
|
+
// by somebody who did not watch you type it.
|
|
578
|
+
const fromConfig = [
|
|
579
|
+
positionals[0] === undefined && configured.engineSpec !== null ? `spec=${specArg} (board.engineSpec)` : null,
|
|
580
|
+
values.prefix === undefined && configured.milestonePrefix !== null
|
|
581
|
+
? `prefix=${prefix} (board.milestonePrefix)`
|
|
582
|
+
: null,
|
|
583
|
+
slug.source === "origin" ? `repo=${repo} (origin remote of ${root})` : null,
|
|
584
|
+
].filter((s): s is string => s !== null);
|
|
585
|
+
if (fromConfig.length > 0) {
|
|
586
|
+
console.error(`board-snapshot: resolved from the repository, not the command line — ${fromConfig.join(", ")}`);
|
|
587
|
+
}
|
|
588
|
+
|
|
589
|
+
// **THE SPEC COMES FROM `origin/main`, AND THE LINE BELOW SAYS SO** — D3.
|
|
590
|
+
// This was a bare `readFileSync` until 2026-11-08, so every reading it
|
|
591
|
+
// produced was scoped by whichever branch the caller stood on and the
|
|
592
|
+
// output named none of them. A branch mid-edit on a Phase placement table
|
|
593
|
+
// and a branch four days behind main give different numbers against the
|
|
594
|
+
// SAME live board, and both printed as an ordinary reading.
|
|
595
|
+
//
|
|
596
|
+
// Three answers, and the third is the point: a tracked path is read from
|
|
597
|
+
// the ref; an UNTRACKED one is read from disk and said so (a planted
|
|
598
|
+
// fixture has no `origin/main` version, which is a fact about the file);
|
|
599
|
+
// and a failure anywhere in between is UNMEASURED. It does NOT fall back
|
|
600
|
+
// to disk — that is the working-tree read wearing a repair, and it fires
|
|
601
|
+
// in exactly the case where the two disagree most.
|
|
259
602
|
const specPath = isAbsolute(specArg) ? specArg : join(root, specArg);
|
|
260
|
-
|
|
603
|
+
const source = resolveSpecSource({ root, absPath: specPath, git: git(root) });
|
|
604
|
+
// ALWAYS, never only on the interesting arm. A provenance line that
|
|
605
|
+
// appears when something is odd teaches the reader that silence means
|
|
606
|
+
// origin/main, and silence is also what a broken emitter looks like.
|
|
607
|
+
console.error(`board-snapshot: ${describeSpecSource(source)}`);
|
|
608
|
+
if (source.kind === "unmeasured") return REFUSAL_EXIT;
|
|
609
|
+
if (source.kind === "untracked" && !existsSync(specPath)) {
|
|
261
610
|
console.error(`board-snapshot: no such spec: ${specPath}`);
|
|
262
611
|
return REFUSAL_EXIT;
|
|
263
612
|
}
|
|
264
|
-
const content = readFileSync(specPath, "utf-8");
|
|
613
|
+
const content = source.kind === "ref" ? source.content : readFileSync(specPath, "utf-8");
|
|
265
614
|
|
|
266
615
|
// An unsound placement table is UNMEASURED, not a board with fewer
|
|
267
616
|
// phases. A criterion the table never places, or places twice, makes the
|
|
@@ -451,6 +800,104 @@ export async function main(argv: string[], gh: BoardSnapshotGitHub = LIVE_GITHUB
|
|
|
451
800
|
const columnRead =
|
|
452
801
|
board !== null && snapshotIssues.length > 0 && snapshotIssues.every(i => "criteriaField" in i);
|
|
453
802
|
|
|
803
|
+
// ── The three REPOSITORY-WIDE populations — SC-2615, SC-2616, SC-2617 ──
|
|
804
|
+
//
|
|
805
|
+
// Everything above this line is engine-scoped: `phases` comes from the one
|
|
806
|
+
// spec named on the command line and `issues` is that spec's milestone
|
|
807
|
+
// family. Each of the three below asks the same shape of question of the
|
|
808
|
+
// whole tree, and each is emitted ONLY when it could actually be taken —
|
|
809
|
+
// `board-conformance` reads an absent key as UNMEASURED, and an absent key
|
|
810
|
+
// is the honest thing to write when nothing was read.
|
|
811
|
+
|
|
812
|
+
// SC-2615. The sweep's own `specs` rows are passed through, UNREADABLE
|
|
813
|
+
// ones included: the reading refuses on them by name, which it cannot do
|
|
814
|
+
// if the producer drops them. The key is omitted only when the sweep could
|
|
815
|
+
// not enumerate `specs/` at all — then there are no rows to carry, and an
|
|
816
|
+
// empty list would be indistinguishable from a tree whose specs are all
|
|
817
|
+
// placed.
|
|
818
|
+
const coverage = placementCoverage(root, specPathSweep, (base, path) =>
|
|
819
|
+
readFileSync(join(base, path), "utf-8"),
|
|
820
|
+
);
|
|
821
|
+
const placements =
|
|
822
|
+
coverage.specs.length === 0 && coverage.reading === "UNMEASURED"
|
|
823
|
+
? {}
|
|
824
|
+
: {
|
|
825
|
+
specPlacements: coverage.specs.map(s => ({
|
|
826
|
+
path: s.path,
|
|
827
|
+
state: s.state,
|
|
828
|
+
criteria: s.criteria,
|
|
829
|
+
placed: s.placed,
|
|
830
|
+
...(s.deferred ? { deferred: true } : {}),
|
|
831
|
+
})),
|
|
832
|
+
};
|
|
833
|
+
|
|
834
|
+
// SC-2734. The bank the deferred specs are compared against. An absent or
|
|
835
|
+
// malformed file omits the key, and the reading goes UNMEASURED as soon as
|
|
836
|
+
// any spec declares itself deferred — a bank nobody could read is not an
|
|
837
|
+
// empty bank, and reading it as one would let every deferral through.
|
|
838
|
+
const deferrals = readDeferralBank(root);
|
|
839
|
+
|
|
840
|
+
// SC-2616. The criterion union comes from the SAME sweep `board-mirror`
|
|
841
|
+
// uses to build the column, so "which ids exist" has one answer. A second
|
|
842
|
+
// enumeration here would be a second decider that no behavioural case
|
|
843
|
+
// could separate from the first.
|
|
844
|
+
//
|
|
845
|
+
// `servesNone` is the literal `NAMES_NONE` string, which is the one way
|
|
846
|
+
// this repository spells the declaration (SC-2609). Matching anything
|
|
847
|
+
// looser — "no criterion", "n/a" — would let an issue opt out by accident,
|
|
848
|
+
// and the entire criterion is that *has not said* and *says none* are
|
|
849
|
+
// different facts.
|
|
850
|
+
// An UNMEASURED sweep omits the key, the same way the other two do. `ids`
|
|
851
|
+
// is `[]` on a sweep that refused — an unreadable `specs/`, a criterion two
|
|
852
|
+
// specs both state — and an empty union matches nothing in any issue, so
|
|
853
|
+
// every issue would report `names: []` whatever it actually names. The
|
|
854
|
+
// reading has no way to tell that from a tracker where nobody has declared
|
|
855
|
+
// anything: it would call all 72 issues offenders, or, if every one of them
|
|
856
|
+
// happened to carry the `servesNone` text, report MET. Raised in review of
|
|
857
|
+
// #1903 — the producer had the gate on the other two populations and not on
|
|
858
|
+
// this one.
|
|
859
|
+
const sweep = specCriteriaIn(root);
|
|
860
|
+
const openIssues = liveIssues.filter(i => i.state === "OPEN");
|
|
861
|
+
const ids = answerableIds(sweep);
|
|
862
|
+
const repoIssues =
|
|
863
|
+
sweep.reading === "UNMEASURED"
|
|
864
|
+
? {}
|
|
865
|
+
: {
|
|
866
|
+
repoIssues: openIssues.map(i => {
|
|
867
|
+
// The one decider (#2020): the `needs-criterion` label reads it too.
|
|
868
|
+
const { names, servesNone } = criterionAnswer({ title: i.title, body: i.body }, ids);
|
|
869
|
+
return { number: i.number, names, servesNone };
|
|
870
|
+
}),
|
|
871
|
+
};
|
|
872
|
+
|
|
873
|
+
// SC-2617. `missing` and `present` are the plan's own two halves — derived
|
|
874
|
+
// edges the tracker lacks, and derived edges it carries. `extra` is
|
|
875
|
+
// deliberately excluded: an edge somebody added that the plan does not
|
|
876
|
+
// derive is reported by `plan-deps` and removed by nobody, so counting it
|
|
877
|
+
// here would let hand-added ordering satisfy a reading about derived
|
|
878
|
+
// ordering.
|
|
879
|
+
//
|
|
880
|
+
// An UNMEASURED plan omits the key. `dependencyPlan` returns UNMEASURED
|
|
881
|
+
// for a truncated `blockedBy` among other reasons, and a truncated read
|
|
882
|
+
// produces exactly the false `missing` edges this reading would then count
|
|
883
|
+
// as the tracker's failure.
|
|
884
|
+
const plan = dependencyPlan(liveIssues);
|
|
885
|
+
const edges =
|
|
886
|
+
plan.reading === "UNMEASURED"
|
|
887
|
+
? {}
|
|
888
|
+
: {
|
|
889
|
+
plannedEdges: [
|
|
890
|
+
...plan.present.map(e => ({ blocked: e.blocked, blocker: e.blocker, present: true })),
|
|
891
|
+
...plan.missing.map(e => ({ blocked: e.blocked, blocker: e.blocker, present: false })),
|
|
892
|
+
],
|
|
893
|
+
};
|
|
894
|
+
|
|
895
|
+
// SC-2752. Built from the SAME sweep rows `spec-placement` reads, so the two
|
|
896
|
+
// readings cannot disagree about which specs are in scope. A sweep that
|
|
897
|
+
// could not enumerate `specs/` emits no rows, and `declared-work` is then
|
|
898
|
+
// UNMEASURED rather than a stage-only count.
|
|
899
|
+
const declared = placements.specPlacements === undefined ? {} : readDeclaredWork(root, placements.specPlacements);
|
|
900
|
+
|
|
454
901
|
const snapshot: ProducedSnapshot = {
|
|
455
902
|
producedAt: new Date().toISOString(),
|
|
456
903
|
spec: specArg,
|
|
@@ -459,6 +906,11 @@ export async function main(argv: string[], gh: BoardSnapshotGitHub = LIVE_GITHUB
|
|
|
459
906
|
closedBlockers: [...named].sort((a, b) => a - b),
|
|
460
907
|
queueLabel: readQueueLabel(root),
|
|
461
908
|
criteria: criterionCoverage(content, snapshotIssues, columnRead),
|
|
909
|
+
...placements,
|
|
910
|
+
...deferrals,
|
|
911
|
+
...repoIssues,
|
|
912
|
+
...edges,
|
|
913
|
+
...declared,
|
|
462
914
|
};
|
|
463
915
|
|
|
464
916
|
process.stdout.write(`${JSON.stringify(snapshot, null, 2)}\n`);
|