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.
- package/gates/.gate-salt +1 -0
- package/gates/SCHEMA-GUIDE.md +485 -0
- package/gates/ac-quality.test.ts +106 -0
- package/gates/adversarial.test.ts +283 -0
- package/gates/brief-assembler.test.ts +487 -0
- package/gates/brief-assembler.ts +448 -0
- package/gates/bunfig.toml +2 -0
- package/gates/chain.test.ts +91 -0
- package/gates/e2e-smoke.test.ts +234 -0
- package/gates/error-classifier.test.ts +250 -0
- package/gates/error-classifier.ts +99 -0
- package/gates/gate-executor.ts +3071 -0
- package/gates/orchestrator.test.ts +968 -0
- package/gates/orchestrator.ts +827 -0
- package/gates/preload.ts +89 -0
- package/gates/prompts/ac-adversary.md +20 -0
- package/gates/prompts/evidence-validator.md +22 -0
- package/gates/prompts/prove-reproducer.md +53 -0
- package/gates/prompts.sha256 +3 -0
- package/gates/prove.test.ts +164 -0
- package/gates/rook-state.test.ts +108 -0
- package/gates/run-attribution.ts +290 -0
- package/gates/run-gate.ts +163 -0
- package/gates/schema-parity.test.ts +378 -0
- package/gates/schema.ts +1209 -0
- package/gates/self-heal.test.ts +511 -0
- package/gates/self-heal.ts +125 -0
- package/gates/ship-orchestrator.test.ts +399 -0
- package/gates/ship-orchestrator.ts +384 -0
- package/gates/spec-compliance-probe.ts +159 -0
- package/gates/test-fixtures/broken-no-environments.json +110 -0
- package/gates/test-fixtures/consumer-directory-layout.json +90 -0
- package/gates/test-fixtures/valid-standard.json +91 -0
- package/gates/test-utils.ts +43 -0
- package/gates/typecheck-gate.ts +111 -0
- package/gates/witness.ts +349 -0
- package/gates/workflow.test.ts +2018 -0
- package/hooks/BashWriteGuard.hook.ts +19 -0
- package/hooks/GateResultProtection.hook.ts +27 -1
- package/hooks/VerifyPhaseLock.hook.ts +51 -11
- package/hooks/WorkflowStateGuard.hook.ts +24 -0
- package/lib/ai-review-rounds.ts +462 -0
- package/lib/bash-file-read.ts +17 -3
- package/lib/bash-write-guard.ts +1285 -50
- package/lib/distribution-standing.ts +75 -4
- package/lib/failure-intake.ts +12 -4
- package/lib/file-extensions.ts +81 -0
- package/lib/finding-arbiter.ts +1015 -0
- package/lib/finding-jury.ts +537 -0
- package/lib/gate-enforcement.ts +171 -43
- package/lib/gate-result-protection.ts +12 -2
- package/lib/generators/code-map.ts +55 -4
- package/lib/generators/types.ts +27 -1
- package/lib/github.ts +55 -0
- package/lib/interpreters.ts +64 -0
- package/lib/issue-create-override.ts +69 -8
- package/lib/issue-filing-gate.ts +605 -0
- package/lib/js-top-level-code.ts +20 -2
- package/lib/junit-checks.ts +239 -1
- package/lib/package-closure.ts +114 -0
- package/lib/publish-window.ts +287 -0
- package/lib/scaffold/ai-review-findings.ts +142 -3
- package/lib/scaffold/ai-review-step.ts +1012 -18
- package/lib/scaffold/managed-workflow.ts +163 -4
- package/lib/scaffold/steps.ts +498 -22
- package/lib/scanner.ts +13 -4
- package/lib/ticked-sc-symbols.ts +361 -0
- package/lib/transcript-checker.ts +6 -0
- package/lib/workflow-actions.ts +18 -0
- package/package.json +3 -1
- package/scripts/arbitrate-finding.ts +224 -0
- package/scripts/generate-code-map.ts +18 -10
- package/scripts/sync-sc-status.ts +82 -8
package/lib/junit-checks.ts
CHANGED
|
@@ -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
|
+
}
|
package/lib/package-closure.ts
CHANGED
|
@@ -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
|
+
}
|