rungate 0.8.0 → 0.8.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.
Files changed (73) hide show
  1. package/gates/.gate-salt +1 -0
  2. package/gates/SCHEMA-GUIDE.md +485 -0
  3. package/gates/ac-quality.test.ts +106 -0
  4. package/gates/adversarial.test.ts +283 -0
  5. package/gates/brief-assembler.test.ts +487 -0
  6. package/gates/brief-assembler.ts +448 -0
  7. package/gates/bunfig.toml +2 -0
  8. package/gates/chain.test.ts +91 -0
  9. package/gates/e2e-smoke.test.ts +234 -0
  10. package/gates/error-classifier.test.ts +250 -0
  11. package/gates/error-classifier.ts +99 -0
  12. package/gates/gate-executor.ts +3071 -0
  13. package/gates/orchestrator.test.ts +968 -0
  14. package/gates/orchestrator.ts +827 -0
  15. package/gates/preload.ts +89 -0
  16. package/gates/prompts/ac-adversary.md +20 -0
  17. package/gates/prompts/evidence-validator.md +22 -0
  18. package/gates/prompts/prove-reproducer.md +53 -0
  19. package/gates/prompts.sha256 +3 -0
  20. package/gates/prove.test.ts +164 -0
  21. package/gates/rook-state.test.ts +108 -0
  22. package/gates/run-attribution.ts +290 -0
  23. package/gates/run-gate.ts +163 -0
  24. package/gates/schema-parity.test.ts +378 -0
  25. package/gates/schema.ts +1209 -0
  26. package/gates/self-heal.test.ts +511 -0
  27. package/gates/self-heal.ts +125 -0
  28. package/gates/ship-orchestrator.test.ts +399 -0
  29. package/gates/ship-orchestrator.ts +384 -0
  30. package/gates/spec-compliance-probe.ts +159 -0
  31. package/gates/test-fixtures/broken-no-environments.json +110 -0
  32. package/gates/test-fixtures/consumer-directory-layout.json +90 -0
  33. package/gates/test-fixtures/valid-standard.json +91 -0
  34. package/gates/test-utils.ts +43 -0
  35. package/gates/typecheck-gate.ts +111 -0
  36. package/gates/witness.ts +349 -0
  37. package/gates/workflow.test.ts +2018 -0
  38. package/hooks/BashWriteGuard.hook.ts +19 -0
  39. package/hooks/GateResultProtection.hook.ts +27 -1
  40. package/hooks/VerifyPhaseLock.hook.ts +51 -11
  41. package/hooks/WorkflowStateGuard.hook.ts +24 -0
  42. package/lib/ai-review-rounds.ts +462 -0
  43. package/lib/bash-file-read.ts +17 -3
  44. package/lib/bash-write-guard.ts +1285 -50
  45. package/lib/distribution-standing.ts +75 -4
  46. package/lib/failure-intake.ts +12 -4
  47. package/lib/file-extensions.ts +81 -0
  48. package/lib/finding-arbiter.ts +1015 -0
  49. package/lib/finding-jury.ts +537 -0
  50. package/lib/gate-enforcement.ts +171 -43
  51. package/lib/gate-result-protection.ts +12 -2
  52. package/lib/generators/code-map.ts +55 -4
  53. package/lib/generators/types.ts +27 -1
  54. package/lib/github.ts +55 -0
  55. package/lib/interpreters.ts +64 -0
  56. package/lib/issue-create-override.ts +69 -8
  57. package/lib/issue-filing-gate.ts +605 -0
  58. package/lib/js-top-level-code.ts +20 -2
  59. package/lib/junit-checks.ts +239 -1
  60. package/lib/package-closure.ts +114 -0
  61. package/lib/publish-window.ts +287 -0
  62. package/lib/scaffold/ai-review-findings.ts +142 -3
  63. package/lib/scaffold/ai-review-step.ts +1012 -18
  64. package/lib/scaffold/managed-workflow.ts +163 -4
  65. package/lib/scaffold/steps.ts +498 -22
  66. package/lib/scanner.ts +13 -4
  67. package/lib/ticked-sc-symbols.ts +361 -0
  68. package/lib/transcript-checker.ts +6 -0
  69. package/lib/workflow-actions.ts +18 -0
  70. package/package.json +3 -1
  71. package/scripts/arbitrate-finding.ts +224 -0
  72. package/scripts/generate-code-map.ts +18 -10
  73. package/scripts/sync-sc-status.ts +82 -8
@@ -111,6 +111,17 @@ function attr(tag: string, name: string): string | null {
111
111
  interface ScannedTestcase {
112
112
  /** The full name, rebuilt from the `<testsuite>` nesting. */
113
113
  name: string;
114
+ /**
115
+ * The source file, as the report spells it — MEASURED on bun 1.3.14,
116
+ * `file="test/ai-review-wif.test.ts"`, repo-relative with the directory
117
+ * on the front (#1172).
118
+ *
119
+ * Read from the `<testcase>` attribute rather than from the outermost
120
+ * `<testsuite>` name, with that name as the fallback. Both carry it
121
+ * today; the attribute is the one that stays correct if a testcase is
122
+ * ever emitted outside a file-level suite.
123
+ */
124
+ file: string;
114
125
  /** The `time` attribute in MILLISECONDS, or `NaN` when it carries none. */
115
126
  ms: number;
116
127
  /** False for a `<skipped />` testcase — filtered out, `.skip` or `.todo`. */
@@ -173,6 +184,7 @@ function scanJunitTestcases(xml: string): { cases: ScannedTestcase[]; skipped: n
173
184
  // Everything above it is a `describe`.
174
185
  const testcase: ScannedTestcase = {
175
186
  name: [...suites.slice(1), attr(rest, "name") ?? ""].join(" > "),
187
+ file: attr(rest, "file") ?? suites[0] ?? "",
176
188
  ms: durationMs(rest),
177
189
  ran: true,
178
190
  failure: null,
@@ -351,6 +363,8 @@ export function unionNames(base: string[] | null, extra: string[]): string[] | n
351
363
  export interface TestcaseDuration {
352
364
  /** The full name, as the console prints it. */
353
365
  name: string;
366
+ /** The source file the report attributes it to, e.g. `test/a.test.ts`. */
367
+ file: string;
354
368
  /** Milliseconds. */
355
369
  ms: number;
356
370
  /** The runner killed it: bun wrote `<failure type="TimeoutError" />`. */
@@ -390,7 +404,7 @@ export function parseJunitDurations(xml: string): JunitDurationReading {
390
404
  const ran = scan.cases.filter(c => c.ran);
391
405
  const durations = ran
392
406
  .filter(c => Number.isFinite(c.ms))
393
- .map(c => ({ name: c.name, ms: c.ms, timedOut: c.failure === "TimeoutError" }));
407
+ .map(c => ({ name: c.name, file: c.file, ms: c.ms, timedOut: c.failure === "TimeoutError" }));
394
408
  return {
395
409
  durations,
396
410
  count: durations.length,
@@ -534,3 +548,227 @@ export function timeoutProximityViolations(
534
548
  }
535
549
  return out;
536
550
  }
551
+
552
+ /* ───────────────────────────────────────────────────────────────────────────
553
+ * #1172: a per-file budget list that can see files that are NOT on it
554
+ *
555
+ * `GIT_FIXTURE_SUITES` names the `ai-review-*` suites whose cases are built
556
+ * on real `git` subprocesses and which therefore declare a calibrated
557
+ * file-level budget instead of inheriting bun's default. `AC-3` of #1140
558
+ * iterates that list and asserts each named file declares one. That holds
559
+ * the list to its claim in **one direction only**: a file that is ON the
560
+ * list must declare. It says nothing about a file that should be on it and
561
+ * is not.
562
+ *
563
+ * So the list can go stale in silence. Someone adds an eighth `ai-review-*`
564
+ * suite built on `checkout()`, it inherits 5000ms, nothing reddens, and the
565
+ * first anyone hears is the "is this red mine?" rebase tax #1140 was filed
566
+ * about. That is the same shape as an allowlist whose own entries are the
567
+ * evidence for them: the budget governs its members and cannot see arrivals.
568
+ *
569
+ * ## Why the structural rule is not the fix, measured
570
+ *
571
+ * "Every `ai-review-*` suite that spawns `bash` and `git` must declare" is
572
+ * over-broad. Measured on 2026-10-22 it catches `ai-review-wif` and
573
+ * `ai-review-baseline-seal`, neither of which has a case above 2500ms.
574
+ * Handing a fast file a 120s ceiling costs hang-detection latency — a
575
+ * genuine hang reports in two minutes instead of five seconds — for no
576
+ * benefit. The criterion that actually qualifies a file is **the measured
577
+ * cost of its fixture**, and that needs a duration reading.
578
+ *
579
+ * ## …and nor is widening the list, which is the cheapest wrong fix
580
+ *
581
+ * Adding today's near-misses to `GIT_FIXTURE_SUITES` changes the membership
582
+ * ROSTER without changing how membership is DETERMINED, so the next arrival
583
+ * is exactly as invisible as this one was. `test/ai-review-fixture-budget.ts`
584
+ * performs that repair over a planted eighth file and measures what it
585
+ * reports, rather than dismissing it in prose.
586
+ *
587
+ * ## So the criterion is DECLARATION, not membership — and the two already disagree
588
+ *
589
+ * This check therefore does not ask "is this file on the list". It asks
590
+ * "does this file declare a budget of its own", read off the TREE. The two
591
+ * are not the same question, and the first real reading taken through this
592
+ * code proved it: over 562 cases of the live `ai-review-*` surface,
593
+ * `ai-review-fixture-budget.test.ts` carried a 5083.13ms case, was **not**
594
+ * on `GIT_FIXTURE_SUITES`, and was in no danger whatever, because it opens
595
+ * with `setDefaultTimeout(gitFixtureTestTimeout())`. A membership criterion
596
+ * reports that file forever; a declaration criterion reports nothing,
597
+ * truthfully, and still reports the eighth suite that declares nothing.
598
+ *
599
+ * The list survives for the job it can do — `budgetSurfaceCoverage` uses it
600
+ * to decide whether a reading COVERS the surface — and for `AC-3`, which
601
+ * holds its named files to declaring. Neither of those gates this check.
602
+ *
603
+ * ## UNMEASURED, never green
604
+ *
605
+ * A `bun test` run cannot read its own JUnit report — the file is written
606
+ * when the run ends — so the population arrives from outside via
607
+ * `SUITE_JUNIT_REPORT`, exactly as in #621. Two readings, not one verdict:
608
+ * `budgetSurfaceCoverage` answers "did this report see the surface at all?"
609
+ * and `budgetMembershipViolations` answers "is anything it saw unbudgeted?".
610
+ * An empty report satisfies the second perfectly, which is why the first
611
+ * exists and why the second stays SILENT on an empty reading rather than
612
+ * refusing it — if both refused, a red row could not say which broke.
613
+ * ──────────────────────────────────────────────────────────────────────── */
614
+
615
+ /** A set of files held to a per-file budget, and the rule for joining it. */
616
+ export interface BudgetSurface {
617
+ /** Names the surface in a failure message, e.g. `the ai-review-* suites`. */
618
+ label: string;
619
+ /**
620
+ * Which files the question is about, matched against the BASENAME.
621
+ *
622
+ * Basename because the two spellings disagree: bun writes
623
+ * `file="test/ai-review-wif.test.ts"` and the member lists in this repo
624
+ * hold bare `"ai-review-wif.test.ts"`. Comparing the two directly is a
625
+ * check that matches nothing and reports clean — the quietest possible
626
+ * version of this defect.
627
+ */
628
+ pattern: RegExp;
629
+ /**
630
+ * Does this file already declare a budget of its own? Read off the TREE.
631
+ *
632
+ * THIS is the criterion, and it is deliberately not "is it on `members`".
633
+ * A file that declares is not inheriting `inheritedMs`, so it is not at
634
+ * risk, whether or not any list knows about it — and the two readings
635
+ * already disagree on the live surface. See the block above.
636
+ */
637
+ declaresOwnBudget: (basename: string) => boolean;
638
+ /**
639
+ * The roster, used ONLY to judge whether a reading covers the surface.
640
+ *
641
+ * It does not gate `budgetMembershipViolations`. If it did, the check
642
+ * would be a list consulting itself about its own completeness, which is
643
+ * the defect #1172 is filed about.
644
+ */
645
+ members: readonly string[];
646
+ /** What a file on this surface inherits when it declares nothing. */
647
+ inheritedMs: number;
648
+ /**
649
+ * The fraction of `inheritedMs` at or above which a non-member qualifies.
650
+ *
651
+ * Not 1.0. A case that has already crossed the inherited budget has
652
+ * already gone red, and a list that only admits files after they have
653
+ * failed is the rebase tax rather than a guard against it. #1140 measured
654
+ * the population at 2500–7500ms against a 5000ms line, so half the
655
+ * inherited budget is the band where a file is one busy afternoon from
656
+ * red.
657
+ */
658
+ qualifyingFraction: number;
659
+ }
660
+
661
+ /** The last path segment, for comparing a report's spelling to a member list. */
662
+ function basenameOf(file: string): string {
663
+ const i = file.lastIndexOf("/");
664
+ return i === -1 ? file : file.slice(i + 1);
665
+ }
666
+
667
+ /** `pattern` without `g`/`y`, whose `lastIndex` makes `.test()` alternate. */
668
+ function stateless(pattern: RegExp): RegExp {
669
+ return new RegExp(pattern.source, pattern.flags.replace(/[gy]/g, ""));
670
+ }
671
+
672
+ /** Every testcase in `reading` that belongs to `surface`. */
673
+ function onSurface(reading: JunitDurationReading, surface: BudgetSurface): TestcaseDuration[] {
674
+ const re = stateless(surface.pattern);
675
+ return (reading.durations ?? []).filter(d => re.test(basenameOf(d.file)));
676
+ }
677
+
678
+ /**
679
+ * What is wrong with the READING, before anything is concluded from it.
680
+ *
681
+ * A report of the whole suite with the surface filtered out passes
682
+ * `durationCoverageViolations` — it read thousands of durations — and
683
+ * satisfies the membership check by containing none of the files it is
684
+ * about. So the surface has its own coverage question, and it is the one
685
+ * that matters here.
686
+ */
687
+ export function budgetSurfaceCoverage(
688
+ reading: JunitDurationReading,
689
+ surface: BudgetSurface,
690
+ source: string,
691
+ ): string[] {
692
+ if (reading.durations === null) {
693
+ return [
694
+ `UNMEASURED: the JUnit report at ${source} could not be read ` +
695
+ `(${reading.reason ?? "no reason recorded"}), so nothing is known about what ${surface.label} cost (#1172)`,
696
+ ];
697
+ }
698
+ const seen = onSurface(reading, surface);
699
+ if (seen.length === 0) {
700
+ return [
701
+ `UNMEASURED: the JUnit report at ${source} carries ${reading.count} testcase durations and NONE of ` +
702
+ `them is on ${surface.label} — a report that did not see the surface satisfies the membership ` +
703
+ `check by having nothing to check, which is not a measurement (#1172)`,
704
+ ];
705
+ }
706
+ const files = new Set(seen.map(d => basenameOf(d.file)));
707
+ const unseenMembers = surface.members.filter(m => !files.has(m));
708
+ if (unseenMembers.length > 0) {
709
+ return [
710
+ `UNMEASURED: ${unseenMembers.length} of ${surface.members.length} files already on the list do not ` +
711
+ `appear in ${source} (${unseenMembers.join(", ")}) — the reading covers part of ${surface.label}, ` +
712
+ `so a qualifying file outside that part is invisible to it (#1172)`,
713
+ ];
714
+ }
715
+ return [];
716
+ }
717
+
718
+ /**
719
+ * Every file on `surface` that has earned a budget and has not been given
720
+ * one — named, with the case and the duration that qualified it.
721
+ *
722
+ * ## Three classes, and only one of them is a finding
723
+ *
724
+ * | What the report shows | What it means | Reported |
725
+ * |---|---|---|
726
+ * | an UNDECLARED file with a case at or above the qualifying band | it inherits a budget it is about to outgrow | **yes** |
727
+ * | a file that DECLARES, at any duration | it is not inheriting anything; its raised ceiling is why it is slow and green | no |
728
+ * | an undeclared file whose slowest case is under the band | fast, and a 120s ceiling would cost it hang-detection for nothing | no |
729
+ *
730
+ * The second row is what makes this usable rather than circular. A declared
731
+ * file's durations are taken UNDER the raised budget, so comparing them to
732
+ * the inherited default would report every one of them forever and train
733
+ * its reader to ignore the check — the cost #1140 is filed about,
734
+ * reintroduced by the guard against it.
735
+ *
736
+ * SILENT on a reading of nothing, deliberately — `budgetSurfaceCoverage` is
737
+ * the question about an empty reading, and keeping them apart is what makes
738
+ * a red row say which one broke.
739
+ */
740
+ export function budgetMembershipViolations(
741
+ reading: JunitDurationReading,
742
+ surface: BudgetSurface,
743
+ ): string[] {
744
+ if (!Number.isFinite(surface.inheritedMs) || surface.inheritedMs <= 0) {
745
+ return [
746
+ `no usable inherited budget to compare against (${surface.inheritedMs}) — a budget of zero or NaN ` +
747
+ `qualifies every file rather than none, which is noise and not a finding (#1172)`,
748
+ ];
749
+ }
750
+ const floor = surface.inheritedMs * surface.qualifyingFraction;
751
+
752
+ /** The slowest qualifying case per undeclared file, so one file is one row. */
753
+ const worst = new Map<string, TestcaseDuration>();
754
+ for (const d of onSurface(reading, surface)) {
755
+ const base = basenameOf(d.file);
756
+ if (!(d.ms >= floor)) continue;
757
+ // Asked per FILE, not per case, and asked last so a fast file never
758
+ // costs a source read.
759
+ if (surface.declaresOwnBudget(base)) continue;
760
+ const held = worst.get(base);
761
+ if (held === undefined || d.ms > held.ms) worst.set(base, d);
762
+ }
763
+
764
+ return [...worst.entries()]
765
+ .sort(([a], [b]) => a.localeCompare(b))
766
+ .map(
767
+ ([file, d]) =>
768
+ `${file} is on ${surface.label}, declares no budget of its own, and its case "${d.name}" took ` +
769
+ `${d.ms.toFixed(2)}ms — ${((d.ms / surface.inheritedMs) * 100).toFixed(1)}% of the ` +
770
+ `${surface.inheritedMs}ms it inherits. It is one busy run from a red that is about machine load ` +
771
+ `and not about the code. Add it to the budget list and declare the file-level budget, or make ` +
772
+ `it faster (#1172)`,
773
+ );
774
+ }
@@ -278,6 +278,98 @@ function scanModuleRelativeJoins(raw: string): { resolved: RuntimeRead[]; unreso
278
278
  return { resolved, unresolved };
279
279
  }
280
280
 
281
+ /**
282
+ * A path an instruction STRING tells the user to run, rooted at the installed
283
+ * harness rather than at the user's own project.
284
+ *
285
+ * ## The third syntax (#1174)
286
+ *
287
+ * The two scanners above ask what published CODE reaches. Neither can see a
288
+ * path that only ever appears in a message, and a message is how this package
289
+ * hands a consumer the way out of a refusal.
290
+ *
291
+ * `REPAIR_HINT` in `lib/gate-result-protection.ts` is the documented repair
292
+ * for a corrupt `workflow-state.json`, and it names
293
+ * `<harness>/gates/orchestrator.ts`. `gates/` had **zero** entries in the
294
+ * published `0.8.0` tarball, so that command could not resolve for any npm
295
+ * consumer — and by #1137's design the guard printing it is deliberately
296
+ * unbypassable, so there was no second route out. `packageClosureViolations`
297
+ * reported the package closed the whole time, because every IMPORT and every
298
+ * READ did resolve. A detector narrower than what it detects, which is the
299
+ * shape `.claude/rules/checks-must-be-able-to-fail.md` names second and which
300
+ * #484 records one paragraph above having already made once.
301
+ *
302
+ * Shipping `hooks/` for the first time in 0.8.0 took this from two
303
+ * instructions to six. A published directory brings its instructions with it,
304
+ * so closing one packaging gap widens this surface rather than narrowing it —
305
+ * which is the argument for a check here instead of a one-time fix.
306
+ *
307
+ * ## Only harness-rooted paths count
308
+ *
309
+ * `lib/typescript-project.ts` emits `bun scripts/typecheck.ts`, and that
310
+ * `scripts/` is the CONSUMER's, where the scaffold writes one. Resolving a
311
+ * bare relative path against this package would invent a defect in the
312
+ * commonest kind of instruction we emit. So the path has to say it means the
313
+ * harness: an explicit `$HARNESS_ROOT`/`<harness>` anchor, or the `./` of a
314
+ * `bun -e` one-liner, which these hints run from the harness root.
315
+ */
316
+ export interface InstructionPath {
317
+ /** How the string named the harness root, for the violation message. */
318
+ anchor: string;
319
+ /** Package-relative path the instruction names. */
320
+ path: string;
321
+ }
322
+
323
+ /** Spellings of "the installed harness package root" inside a message. */
324
+ const HARNESS_ROOT_ANCHOR =
325
+ /(\$\{HARNESS_ROOT\}|\$HARNESS_ROOT|<harness>)\/((?:[\w.-]+\/)*[\w.-]+\.\w+)/g;
326
+
327
+ /**
328
+ * The import specifier of a `bun -e` one-liner — a `./`-rooted path after the
329
+ * `from` keyword. Quotes are optional here because the hint is itself inside
330
+ * a string, so they arrive backslash-escaped as often as not.
331
+ *
332
+ * Spelled without an example of the thing it matches on purpose:
333
+ * `relativeImports` above scans RAW source, so a docstring quoting a real
334
+ * specifier is read as a phantom import and the mutation battery in
335
+ * `test/package-closure.test.ts` aborts rewriting it. Found by that battery.
336
+ */
337
+ const BUN_EVAL_SPECIFIER = /from\s*\\?["']?\.\/((?:[\w.-]+\/)*[\w.-]+\.\w+)/g;
338
+
339
+ export function instructionPaths(raw: string): InstructionPath[] {
340
+ // Comments out, string and template text kept. `runtimeReads` does the same
341
+ // thing for the same reason, and here the live tree proves it is needed in
342
+ // both directions: `lib/shell-path-interpolation.ts` explains shell quoting
343
+ // with a `${HARNESS_ROOT}/scripts/x.ts` example in a DOCSTRING, which a
344
+ // scanner reading raw source reports as a shipped instruction; and three of
345
+ // the six real instructions are template literals, which `keepStringContents`
346
+ // alone blanks. Either half alone gets the live tree wrong.
347
+ const source = stripStringsAndComments(raw, {
348
+ keepStringContents: true,
349
+ keepTemplateText: true,
350
+ });
351
+ const found: InstructionPath[] = [];
352
+ let m: RegExpExecArray | null;
353
+
354
+ HARNESS_ROOT_ANCHOR.lastIndex = 0;
355
+ while ((m = HARNESS_ROOT_ANCHOR.exec(source)) !== null) {
356
+ found.push({ anchor: m[1], path: m[2] });
357
+ }
358
+
359
+ // Scoped to the line carrying the `bun -e`, not to `./` generally: a bare
360
+ // `./` in any other message is relative to wherever the user is standing,
361
+ // and this package cannot say where that is.
362
+ for (const line of source.split("\n")) {
363
+ if (!line.includes("bun -e")) continue;
364
+ BUN_EVAL_SPECIFIER.lastIndex = 0;
365
+ while ((m = BUN_EVAL_SPECIFIER.exec(line)) !== null) {
366
+ found.push({ anchor: "bun -e .", path: m[1] });
367
+ }
368
+ }
369
+
370
+ return found;
371
+ }
372
+
281
373
  /**
282
374
  * The single binding. `test/package-closure.test.ts` builds a mutant of this
283
375
  * module with the body short-circuited to `return []` and asserts the suite
@@ -344,6 +436,28 @@ export function packageClosureViolations(root: string, published: Set<string>):
344
436
  }
345
437
  }
346
438
 
439
+ // #1174. An instruction naming a path the tarball does not carry is the
440
+ // same closure property again, in the one syntax neither scanner above
441
+ // can reach — so it is answered here, against the same `published` set,
442
+ // rather than in a fourth checker that could drift from these three.
443
+ for (const { anchor, path } of instructionPaths(source)) {
444
+ // Absent from the working tree too is a different bug — a stale or
445
+ // illustrative path — and not this check's business. Same rule the
446
+ // import walker below applies, and on the live tree it is what keeps
447
+ // `$HARNESS_ROOT/scripts/x.ts` out of the violation list.
448
+ if (!existsSync(join(root, path))) continue;
449
+
450
+ const isPublished = statSync(join(root, path)).isDirectory()
451
+ ? [...published].some(p => p.startsWith(`${path}/`))
452
+ : published.has(path);
453
+
454
+ if (!isPublished) {
455
+ violations.push(
456
+ `${file} instructs the user to run ${anchor}/${path}, which files[] does not publish`,
457
+ );
458
+ }
459
+ }
460
+
347
461
  for (const specifier of relativeImports(source)) {
348
462
  const target = resolve(dirname(join(root, file)), specifier);
349
463
  const targetRel = relative(root, target);
@@ -0,0 +1,287 @@
1
+ /**
2
+ * Where a tree is, relative to the registry, while a release is happening
3
+ * (#1237, #1226).
4
+ *
5
+ * ## One reading, two checks, two tolerances
6
+ *
7
+ * Two checks in this repository ask the same question — *does the registry
8
+ * serve the version this tree declares?* — and answered it with different
9
+ * tolerances, so a single release produced two opposite failures:
10
+ *
11
+ * - `distributionViolations` compares `SUCCESS.md`'s standing line to
12
+ * `package.json` and to the registry independently, which tolerates the
13
+ * pre-publish window (#1049) and reddens `main` for the post-publish one.
14
+ * Until this module, clearing that red meant a human editing a markdown
15
+ * file — and `SUCCESS.md` is DA-owned (#296), so the only agents who hit
16
+ * the failure were the only ones forbidden to fix it. Twice on 2026-10-22:
17
+ * `b7281397` and `803e1e66`, each a one-line hand edit over a red `main`.
18
+ * - the adjudicator pin in `.github/workflows/ai-review.yml` has no tolerance
19
+ * at all, so the pre-publish window turns a required check into a repo-wide
20
+ * merge block.
21
+ *
22
+ * This module is the one place that classifies the reading, so the two checks
23
+ * can disagree about what to DO with a state without disagreeing about which
24
+ * state it is.
25
+ *
26
+ * ## A tolerance is not an off switch
27
+ *
28
+ * The state that must stay red is **bumped and never published**: `main`
29
+ * declaring a version no consumer can obtain, with nothing in flight that
30
+ * will change that. It is observationally identical, at the instant you look,
31
+ * to a release that is publishing right now. Nothing but elapsed time
32
+ * separates them, so the separator has to be an event with a time on it.
33
+ *
34
+ * The release tag is that event. `release.yml` triggers on `push: tags: v*`,
35
+ * so a tree carrying a version with no `v<version>` tag was never released,
36
+ * and a tag older than the window is a release that was triggered and did not
37
+ * land. Both are NEVER_PUBLISHED. Only "tagged, and recently" is tolerated.
38
+ *
39
+ * ## The CDN edge is a third state, and it is decided without a clock
40
+ *
41
+ * `dist-tags.latest` is a pointer that propagates on its own schedule, and
42
+ * reading it to answer *did the publish take effect* reported three
43
+ * consecutive successful releases as failures (#445, #472) — 0.4.1 missed a
44
+ * 120-second budget by 48 seconds. So a version's EXISTENCE is read from the
45
+ * versions list, which is the same reading `release.yml`'s postflight trusts,
46
+ * and `latest` is consulted only to tell PUBLISHED from TAG_LAG. A
47
+ * propagation delay therefore cannot age into NEVER_PUBLISHED however long it
48
+ * lasts: no clock is involved in that branch.
49
+ */
50
+ import { execFileSync } from "child_process";
51
+
52
+ /**
53
+ * The registry's account of a package, as the two readings that answer
54
+ * different questions.
55
+ *
56
+ * `versions` answers *does this exist*. `latest` answers *is it what a
57
+ * consumer gets*. Keeping them apart is the whole of #445; collapsing them
58
+ * would make PUBLISHED and TAG_LAG the same row, which is the fourth shape in
59
+ * `.claude/rules/checks-must-be-able-to-fail.md` — two deciders that agree.
60
+ */
61
+ export interface Packument {
62
+ /** The `latest` dist-tag. `null` when the registry did not report one. */
63
+ latest: string | null;
64
+ /** Every version the registry serves. */
65
+ versions: string[];
66
+ /** Publish time per version, plus `created` and `modified`, which are not versions. */
67
+ time: Record<string, string>;
68
+ }
69
+
70
+ /**
71
+ * How long after its release tag a version may be absent from the registry
72
+ * before that stops being a release and starts being a defect.
73
+ *
74
+ * Derived, not chosen: the 0.8.1 release pushed `v0.8.1` at 18:48:45Z and the
75
+ * registry served it at 19:04:37Z — **sixteen minutes**, nearly all of it the
76
+ * full suite `release.yml` runs against the tag before publishing. Ninety
77
+ * minutes is five times that, which leaves room for a slow runner and a
78
+ * queued job without leaving room for a release that failed in the morning to
79
+ * still read as "publishing now" in the afternoon.
80
+ *
81
+ * Raising it trades detection latency for tolerance of a slower pipeline.
82
+ * Lowering it below the longest real release makes every release red again,
83
+ * which is the defect this module exists to remove.
84
+ */
85
+ export const PUBLISH_WINDOW_MS = 90 * 60 * 1000;
86
+
87
+ /**
88
+ * `PUBLISHED` — the registry serves this version and points `latest` at it.
89
+ * `TAG_LAG` — the registry HAS it; `latest` has not caught up. Not a defect.
90
+ * `PUBLISH_PENDING` — absent, and its release tag is inside the window.
91
+ * `NEVER_PUBLISHED` — absent, with no release in flight. A defect.
92
+ * `UNMEASURED` — the registry was not read. Never a pass.
93
+ */
94
+ export type PublishState =
95
+ | "PUBLISHED"
96
+ | "TAG_LAG"
97
+ | "PUBLISH_PENDING"
98
+ | "NEVER_PUBLISHED"
99
+ | "UNMEASURED";
100
+
101
+ export interface PublishWindowReading {
102
+ /** `package.json` `version`. */
103
+ treeVersion: string;
104
+ /** `null` when the registry could not be read. */
105
+ packument: Packument | null;
106
+ /** ISO time of the `v<treeVersion>` tag; `null` when there is no such tag. */
107
+ releaseTagAt: string | null;
108
+ now: Date;
109
+ }
110
+
111
+ /**
112
+ * The single classifier. One exported binding, so there is one thing to
113
+ * mutate and no second predicate over the same fields to hold a case up.
114
+ */
115
+ export function publishState(r: PublishWindowReading): PublishState {
116
+ const p = r.packument;
117
+ if (p === null || p.latest === null) return "UNMEASURED";
118
+ if (p.versions.includes(r.treeVersion)) {
119
+ return p.latest === r.treeVersion ? "PUBLISHED" : "TAG_LAG";
120
+ }
121
+ if (r.releaseTagAt === null) return "NEVER_PUBLISHED";
122
+ const tagged = Date.parse(r.releaseTagAt);
123
+ if (Number.isNaN(tagged)) return "NEVER_PUBLISHED";
124
+ const elapsed = r.now.getTime() - tagged;
125
+ // A negative elapsed time is clock skew, not a window that has not opened
126
+ // yet. Treating it as pending would hand an unbounded tolerance to any
127
+ // runner whose clock is behind the tagger's.
128
+ if (elapsed < 0 || elapsed > PUBLISH_WINDOW_MS) return "NEVER_PUBLISHED";
129
+ return "PUBLISH_PENDING";
130
+ }
131
+
132
+ /** `true` for the two states in which a consumer can obtain the tree's version. */
133
+ export function registryHasTreeVersion(s: PublishState): boolean {
134
+ return s === "PUBLISHED" || s === "TAG_LAG";
135
+ }
136
+
137
+ /**
138
+ * The release a consumer had immediately before the current `latest`.
139
+ *
140
+ * Ordered by PUBLISH TIME and not by version string, because the question is
141
+ * "what did a consumer get before now" and those genuinely disagree: a patch
142
+ * cut from a maintenance branch after a later minor shipped is newer in time
143
+ * and older in semver.
144
+ *
145
+ * `created` and `modified` sit in the same map and sort alongside real
146
+ * entries, so the keys are filtered against `versions` rather than taken from
147
+ * `time` directly. A reader that skipped that returns `created` on a
148
+ * single-release package and every comparison downstream holds vacuously.
149
+ */
150
+ export function previousPublished(p: Packument): string | null {
151
+ const dated = p.versions
152
+ .filter(v => typeof p.time[v] === "string")
153
+ .map(v => ({ v, t: Date.parse(p.time[v]!) }))
154
+ .filter(x => !Number.isNaN(x.t))
155
+ .sort((a, b) => b.t - a.t);
156
+ return dated.length >= 2 ? dated[1]!.v : null;
157
+ }
158
+
159
+ /**
160
+ * What the registry says, from its own JSON endpoint.
161
+ *
162
+ * Deliberately not `npm view`: no npm CLI on the path and no lockfile, so the
163
+ * reading is the same on a laptop and on CI. A failure THROWS rather than
164
+ * returning a fallback — an unreachable registry is an unmeasured check, and
165
+ * a check reporting "no problems found" when it could not look is the
166
+ * fail-open shape `.claude/rules/checks-must-be-able-to-fail.md` opens with.
167
+ */
168
+ export async function readPackument(
169
+ pkg: string,
170
+ fetchImpl: typeof fetch = fetch,
171
+ ): Promise<Packument> {
172
+ const res = await fetchImpl(`https://registry.npmjs.org/${pkg}`);
173
+ if (!res.ok) throw new Error(`registry returned ${res.status} for ${pkg}`);
174
+ const body = (await res.json()) as {
175
+ "dist-tags"?: { latest?: unknown };
176
+ versions?: unknown;
177
+ time?: unknown;
178
+ };
179
+ const versions = body.versions;
180
+ if (typeof versions !== "object" || versions === null) {
181
+ throw new Error(`registry returned no versions for ${pkg}`);
182
+ }
183
+ const latest = body["dist-tags"]?.latest;
184
+ const time = (typeof body.time === "object" && body.time !== null ? body.time : {}) as Record<
185
+ string,
186
+ string
187
+ >;
188
+ return {
189
+ latest: typeof latest === "string" ? latest : null,
190
+ versions: Object.keys(versions),
191
+ time,
192
+ };
193
+ }
194
+
195
+ /**
196
+ * A version, and nothing that is also a git option, a pathspec or a revision.
197
+ *
198
+ * Checked before any git runs, and `null` on a miss. A string that is not a
199
+ * version can never be a release tag, so refusing it costs nothing and closes
200
+ * the door on `--all`, `HEAD`, `""` and anything else that would be read as
201
+ * something other than a name.
202
+ */
203
+ const SEMVER = /^\d+\.\d+\.\d+(?:[-+][0-9A-Za-z.-]+)*$/;
204
+
205
+ /**
206
+ * When `v<version>` was tagged **on the remote**, or `null`.
207
+ *
208
+ * ## Why the remote, and not this checkout
209
+ *
210
+ * This reading is the entire separator between *the registry does not have it
211
+ * YET* and *somebody bumped the version and never published*. Those states are
212
+ * observationally identical at the instant you look, so whatever tells them
213
+ * apart decides whether the tolerance is honest.
214
+ *
215
+ * As first shipped it was `git log -1 --format=%cI v<version>` against the
216
+ * local checkout, and that is **evidence produced by the party being
217
+ * measured**. `release.yml` fires on tag PUSH. An unpushed local tag proves
218
+ * nothing was ever triggered, and it bought a full `PUBLISH_WINDOW_MS` of
219
+ * tolerance for exactly the state that has to stay red — so the exemption was
220
+ * mintable by anyone who could run `git tag`.
221
+ *
222
+ * Three things changed, and they are separate defects:
223
+ *
224
+ * - `v${version}` was an unqualified **revision-or-pathspec**: a local BRANCH
225
+ * named `v1.2.3` resolved it as readily as a tag, and so could a path. It is
226
+ * now `refs/tags/v<version>` read through `for-each-ref`, which cannot match
227
+ * a branch or a path.
228
+ * - `%cI` is the **committer date of the commit the tag points at** — when the
229
+ * code was written, not when the release was cut. It is now
230
+ * `%(creatordate:iso-strict)` off the ref itself.
231
+ * - existence is confirmed with `ls-remote` against `origin`, so the evidence
232
+ * comes from the remote rather than from the working copy.
233
+ *
234
+ * The local date is pinned to the remote's object id. A local tag shadowing a
235
+ * pushed one with a fresher date would otherwise extend its own window.
236
+ *
237
+ * ## This is the weaker of the two available designs, deliberately
238
+ *
239
+ * The stronger one asks the Actions API whether a release run exists for the
240
+ * tag, so the separator is produced by a party other than the thing being
241
+ * gated. That is the right principle and it is filed rather than built: it
242
+ * puts a networked call to a rate-limited API on a path a unit test takes, and
243
+ * this repository already carries one open flake of exactly that shape. The
244
+ * remote ref is weaker evidence — a pushed tag is not proof a run started —
245
+ * but it is produced outside the checkout, which is the property that was
246
+ * missing.
247
+ *
248
+ * ## The bare catch falls CLOSED, and that is the point
249
+ *
250
+ * `.claude/rules/config-access.md` bans the fail-OPEN version of this pattern,
251
+ * where a catch turns a failed read into "no problems found". This one falls
252
+ * the other way: every failure path returns `null`, `null` means no release is
253
+ * in flight, and no release in flight means `NEVER_PUBLISHED` — the red state.
254
+ * An unreachable remote, a checkout with no tags fetched and a version nobody
255
+ * released all land on the refusal. Do not "fix" this into a throw or a
256
+ * fallback without reading which direction it falls in.
257
+ */
258
+ export function releaseTagTime(root: string, version: string): string | null {
259
+ if (!SEMVER.test(version)) return null;
260
+ const ref = `refs/tags/v${version}`;
261
+ const git = (...args: string[]) =>
262
+ execFileSync("git", ["-C", root, ...args], {
263
+ encoding: "utf-8",
264
+ stdio: ["ignore", "pipe", "ignore"],
265
+ });
266
+ try {
267
+ // Existence, from the remote. `--exit-code` makes "no such tag" a non-zero
268
+ // exit rather than empty output, so an absent ref and a failed command do
269
+ // not have to be told apart here — both are the refusal.
270
+ const remote = git("ls-remote", "--tags", "--exit-code", "origin", ref);
271
+ const line = remote.split("\n").find(l => l.endsWith(`\t${ref}`));
272
+ if (line === undefined) return null;
273
+ const remoteOid = line.split("\t")[0]!.trim();
274
+ if (remoteOid === "") return null;
275
+
276
+ // The date, from the ref itself rather than from the commit under it, and
277
+ // only if the local ref is the object the remote is serving.
278
+ const local = git("for-each-ref", "--format=%(objectname) %(creatordate:iso-strict)", ref).trim();
279
+ if (local === "") return null;
280
+ const [localOid, ...rest] = local.split(" ");
281
+ if (localOid !== remoteOid) return null;
282
+ const when = rest.join(" ").trim();
283
+ return when === "" ? null : when;
284
+ } catch {
285
+ return null;
286
+ }
287
+ }