@antelopejs/tooling-configs 0.3.5 → 0.3.7

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.
@@ -4,14 +4,14 @@ import { a as isString, c as object, f as parseJson, i as isObject, n as childre
4
4
  import { a as exitIs, c as interrupted, i as exists, r as equal, u as refused } from "../checks-CxkSu2E6.mjs";
5
5
  import { n as runCliAsync } from "../cli-4Tv71vYk.mjs";
6
6
  import { c as repositoryRoot } from "../files-DJ0TeaTU.mjs";
7
- import { a as readFeatures, c as allocateRun, d as loadRun, f as openWorkspace, g as saveRun, h as removeTree, i as planFor, l as git, m as operatorTmpdir, n as SMOKE_FEATURE, o as CACHE_DIR, p as operatorEnv, r as checkMap, s as RUNS_DIR, u as isolatedEnv } from "../map-s_jKqBQv.mjs";
7
+ import { _ as saveRun, a as readFeatures, b as matchesPath, c as allocateRun, d as loadRun, f as openWorkspace, g as removeTree, h as recordProcesses, i as planFor, l as git, m as operatorTmpdir, n as SMOKE_FEATURE, o as CACHE_DIR, p as operatorEnv, r as checkMap, s as RUNS_DIR, u as isolatedEnv, v as withLocalBins, y as writeWhole } from "../map-COx26Bu6.mjs";
8
8
  import { appendFileSync, closeSync, copyFileSync, cpSync, existsSync, lstatSync, mkdirSync, mkdtempSync, openSync, readFileSync, readdirSync, readlinkSync, realpathSync, renameSync, rmSync, rmdirSync, statSync, symlinkSync, unlinkSync, writeFileSync } from "node:fs";
9
- import { basename, dirname, extname, isAbsolute, join, matchesGlob, posix, relative, resolve, sep } from "node:path";
9
+ import { basename, dirname, extname, isAbsolute, join, posix, relative, resolve, sep } from "node:path";
10
10
  import { execFileSync, spawn, spawnSync } from "node:child_process";
11
11
  import { pathToFileURL } from "node:url";
12
12
  import ts from "typescript";
13
13
  import { createHash, randomBytes } from "node:crypto";
14
- import { constants as constants$1, tmpdir } from "node:os";
14
+ import { availableParallelism, constants as constants$1, tmpdir } from "node:os";
15
15
  import { parseArgs } from "node:util";
16
16
  import { createServer } from "node:net";
17
17
  import { setTimeout as setTimeout$1 } from "node:timers/promises";
@@ -55,7 +55,7 @@ function flaggedDoors(workspace, files) {
55
55
  "publish"
56
56
  ].flatMap((kind) => {
57
57
  const globs = doorGlobs(workspace, kind);
58
- const hits = files.filter((file) => globs.some((glob) => matchesGlob(file, glob)));
58
+ const hits = files.filter((file) => globs.some((glob) => matchesPath(file, glob)));
59
59
  return hits.length > 0 ? [{
60
60
  kind,
61
61
  files: hits
@@ -511,7 +511,7 @@ function seconds(ms) {
511
511
  //#region src/verify/formal.ts
512
512
  const OUTPUT_LIMIT = 67108864;
513
513
  function changesCheckFiles(check, changed) {
514
- return changed.some((file) => (check.files ?? []).some((glob) => matchesGlob(file, glob)));
514
+ return changed.some((file) => (check.files ?? []).some((glob) => matchesPath(file, glob)));
515
515
  }
516
516
  /** The formal checks of verify.config.ts whose covered files or own `files` the change touches. */
517
517
  function touchedFormalChecks(workspace, changed) {
@@ -525,11 +525,27 @@ function passingRules(check, exitCode, output) {
525
525
  if (check.passing) return [...new Set([...output.matchAll(check.passing)].map((match) => match[1]))];
526
526
  return !check.violation && exitCode === 0 ? ["property"] : [];
527
527
  }
528
+ function withIndices(pattern) {
529
+ return pattern.hasIndices ? pattern : new RegExp(pattern.source, `${pattern.flags}d`);
530
+ }
531
+ function counterexampleLengths(check, output) {
532
+ if (!check.violation) return {};
533
+ const seen = /* @__PURE__ */ new Map();
534
+ for (const match of output.matchAll(withIndices(check.violation))) {
535
+ const states = match.groups?.states;
536
+ const rule = match[1];
537
+ const statesIsRule = match.indices?.[1]?.[0] === match.indices?.groups?.states?.[0];
538
+ const length = states === void 0 || !/^\d+$/.test(states) || statesIsRule ? null : Number(states);
539
+ seen.set(rule, seen.has(rule) && seen.get(rule) !== length ? null : length);
540
+ }
541
+ return Object.fromEntries([...seen].filter((entry) => entry[1] !== null && Number.isSafeInteger(entry[1])));
542
+ }
528
543
  function rulesOf(check, run) {
529
544
  return {
530
545
  exitCode: run.status,
531
546
  violated: violatedRules(check, run.status, run.stdout ?? ""),
532
- passing: passingRules(check, run.status, run.stdout ?? "")
547
+ passing: passingRules(check, run.status, run.stdout ?? ""),
548
+ lengths: counterexampleLengths(check, run.stdout ?? "")
533
549
  };
534
550
  }
535
551
  function runCommand(command, cwd) {
@@ -553,6 +569,44 @@ function baseRun(workspace, check, baseSha, folder) {
553
569
  writeRun(folder, "base-", command, run);
554
570
  return rulesOf(check, run);
555
571
  }
572
+ function gitOutput(root, args) {
573
+ const run = spawnSync("git", args, {
574
+ cwd: root,
575
+ encoding: "utf8",
576
+ maxBuffer: OUTPUT_LIMIT
577
+ });
578
+ return run.status === 0 ? run.stdout : null;
579
+ }
580
+ function namedOnBase(workspace, check, baseSha) {
581
+ const config = relative(workspace.root, join(workspace.skill, "verify.config.ts"));
582
+ const text = gitOutput(workspace.root, ["show", `${baseSha}:${config}`]);
583
+ if (text === null) return false;
584
+ return [
585
+ "\"",
586
+ "'",
587
+ "`"
588
+ ].some((quote) => text.includes(`${quote}${check.name}${quote}`));
589
+ }
590
+ function renamedFromBase(root, check, diff) {
591
+ const fields = (gitOutput(root, [
592
+ "diff",
593
+ "-M",
594
+ "--name-status",
595
+ "-z",
596
+ diff.baseSha,
597
+ diff.headSha
598
+ ]) ?? "").split("\0");
599
+ return fields.some((field, index) => field.startsWith("R") && (check.files ?? []).some((glob) => matchesPath(fields[index + 2] ?? "", glob)));
600
+ }
601
+ /**
602
+ * Whether the diff adds the check: the base could not run it, its name
603
+ * appears nowhere in the base's verify.config.ts, and no file of its own
604
+ * `files` is a rename of a base file. A moved or renamed check, or one whose
605
+ * base ran, is a changed check, gated against the base.
606
+ */
607
+ function addedByDiff(workspace, check, diff, base) {
608
+ return base.exitCode !== 0 && !namedOnBase(workspace, check, diff.baseSha) && !renamedFromBase(workspace.root, check, diff);
609
+ }
556
610
  function gateFields(workspace, check, diff, folder, head) {
557
611
  const behaviour = behaviourChange(workspace.root, check, diff);
558
612
  const checkChanged = changesCheckFiles(check, diff.changed);
@@ -568,6 +622,7 @@ function gateFields(workspace, check, diff, folder, head) {
568
622
  return {
569
623
  behaviour,
570
624
  checkChanged,
625
+ newCheck: checkChanged && addedByDiff(workspace, check, diff, base),
571
626
  base,
572
627
  fixed: base.violated.filter((rule) => head.passing.includes(rule) && !head.violated.includes(rule)),
573
628
  missing: base.violated.filter((rule) => !atHead.has(rule))
@@ -575,7 +630,8 @@ function gateFields(workspace, check, diff, folder, head) {
575
630
  }
576
631
  /**
577
632
  * Runs one formal check from the repository root and writes its command,
578
- * output, exit code and violated rules under `evidence/formal/<name>/`.
633
+ * output, exit code, violated rules and their counterexample lengths under
634
+ * `evidence/formal/<name>/`.
579
635
  * When the check covers the diff (`diff` given), it also records whether the
580
636
  * diff changed the covered code's behaviour. When it did, or when the diff
581
637
  * changed the check's own `files`, it runs the check on the base: `fixed`
@@ -594,6 +650,7 @@ function runFormalCheck(workspace, state, check, diff) {
594
650
  exitCode: run.status,
595
651
  violated: head.violated,
596
652
  passing: head.passing,
653
+ lengths: head.lengths,
597
654
  folder: relative(state.evidence, folder)
598
655
  };
599
656
  if (diff !== null) Object.assign(result, { commits: {
@@ -604,13 +661,72 @@ function runFormalCheck(workspace, state, check, diff) {
604
661
  writeFileSync(join(folder, "result.json"), `${JSON.stringify(result, null, 2)}\n`);
605
662
  return result;
606
663
  }
664
+ function lengthOf(lengths, rule) {
665
+ return lengths !== void 0 && Object.hasOwn(lengths, rule) ? lengths[rule] : void 0;
666
+ }
667
+ function knownFindingsOfBase(result) {
668
+ const { base } = result;
669
+ if (!base || base.exitCode !== 0) return false;
670
+ const atHead = new Set(result.violated);
671
+ const fixed = new Set(result.fixed ?? []);
672
+ return base.violated.every((rule) => atHead.has(rule) || fixed.has(rule)) && result.violated.every((rule) => {
673
+ const length = lengthOf(result.lengths, rule);
674
+ return base.violated.includes(rule) && length !== void 0 && length === lengthOf(base.lengths, rule);
675
+ });
676
+ }
677
+ /**
678
+ * The outcome a result's base run forces before the findings are weighed: a
679
+ * check the diff adds, on a diff that leaves the covered behaviour unchanged,
680
+ * passes its recorded findings, since its record is reviewed with it and the
681
+ * base has nothing to compare, and fails with the advice to land it alone when
682
+ * the covered code changed too; otherwise a failure
683
+ * for a changed check with no base run recorded, a base run that exited non-zero
684
+ * while HEAD breaks rules, or, when the covered behaviour is unchanged, a rule
685
+ * HEAD breaks that the base did not. `null` when the base decides nothing.
686
+ */
687
+ function baseGate(result) {
688
+ const { base, behaviour } = result;
689
+ if (result.newCheck === true && base && base.exitCode !== 0 && behaviour?.changed === false) return {
690
+ fails: false,
691
+ outcome: `new check, absent from the base: ${result.violated.length > 0 ? `recorded findings ${result.violated.join(", ")}` : "no violated rule"}`
692
+ };
693
+ if (result.newCheck === true && behaviour?.changed === true && result.violated.length > 0) return {
694
+ fails: true,
695
+ outcome: "new check with a covered-code change: land the check in its own PR first"
696
+ };
697
+ if (result.checkChanged === true && !base) return {
698
+ fails: true,
699
+ outcome: "the check's own files changed but no base run was recorded"
700
+ };
701
+ if (!base) return null;
702
+ if (base.exitCode !== 0 && result.violated.length > 0) return {
703
+ fails: true,
704
+ outcome: `the base run exited ${base.exitCode}, so ${result.violated.join(", ")} cannot be compared with the base`
705
+ };
706
+ const added = result.violated.filter((rule) => !base.violated.includes(rule));
707
+ if (behaviour?.changed === false && added.length > 0) return {
708
+ fails: true,
709
+ outcome: `covered behaviour unchanged (${behaviour.method}), but the check breaks rules the base did not: ${added.join(", ")}`
710
+ };
711
+ return null;
712
+ }
607
713
  /**
608
714
  * How a formal check's result weighs on a verdict whose diff it covers. A
609
715
  * non-zero exit (a tool error, or a check that no longer matches its record)
610
- * fails. Recorded findings fail only when the diff changed the covered code's
611
- * behaviour; otherwise they are reported as known. A rule the base broke and
612
- * HEAD reports passing is reported as fixed; one HEAD does not report at all
613
- * fails.
716
+ * fails, so every violated rule of a result that reaches the rest of the gate
717
+ * is a recorded finding. A rule the base broke that HEAD does not report at
718
+ * all fails. A base run that exited non-zero cannot vouch for HEAD's findings,
719
+ * and a changed check with no base run recorded fails. A check the diff adds
720
+ * (the base could not run it, never names it and holds none of its files
721
+ * under another path) passes its recorded findings when the covered
722
+ * behaviour is unchanged. Otherwise, when the covered behaviour is unchanged,
723
+ * recorded findings are known, except a rule HEAD breaks that the base run
724
+ * did not, which fails whatever the diff touched. When the behaviour
725
+ * changed, they are known only when the base run exited 0 and broke every
726
+ * one of them, each with the same counterexample length at HEAD as on the
727
+ * base, and every other rule the base broke is fixed at HEAD; a new rule, a
728
+ * changed length, or a length either run did not report fails. A rule the
729
+ * base broke and HEAD reports passing is reported as fixed.
614
730
  */
615
731
  function formalGate(result) {
616
732
  if (result.exitCode !== 0) return {
@@ -626,6 +742,8 @@ function formalGate(result) {
626
742
  outcome: `violated ${result.violated.join(", ") || "nothing"}`
627
743
  };
628
744
  const how = result.behaviour.method;
745
+ const againstBase = baseGate(result);
746
+ if (againstBase) return againstBase;
629
747
  if (!result.behaviour.changed) return {
630
748
  fails: false,
631
749
  outcome: `covered behaviour unchanged (${how}): ${result.violated.length > 0 ? `known findings ${result.violated.join(", ")}` : "no violated rule"}`
@@ -635,6 +753,10 @@ function formalGate(result) {
635
753
  fails: false,
636
754
  outcome: `covered behaviour changed (${how}), no violated rule${fixed}`
637
755
  };
756
+ if (knownFindingsOfBase(result)) return {
757
+ fails: false,
758
+ outcome: `covered behaviour changed (${how}), same known findings as base: ${result.violated.join(", ")}${fixed}`
759
+ };
638
760
  return {
639
761
  fails: true,
640
762
  outcome: `covered behaviour changed (${how}), violated ${result.violated.join(", ")}${fixed}`
@@ -647,6 +769,125 @@ function readFormalResult(state, name) {
647
769
  return JSON.parse(readFileSync(file, "utf8"));
648
770
  }
649
771
  //#endregion
772
+ //#region src/verify/jobs.ts
773
+ const INTERRUPTS$1 = [
774
+ "SIGINT",
775
+ "SIGTERM",
776
+ "SIGHUP",
777
+ "SIGQUIT"
778
+ ];
779
+ /**
780
+ * The most features a `journey` call runs at once: `requested`, capped at
781
+ * the number of features and at half the logical cores, one feature per
782
+ * physical core where each core runs two threads. A feature is mostly an
783
+ * app booting under `ajs project dev`, which keeps a core busy, so features
784
+ * past one per physical core slow each other's boot more than they overlap
785
+ * it. The cap only stops a count that oversubscribes the machine; the
786
+ * synced skill recommends 4.
787
+ */
788
+ function jobLimit(requested, features) {
789
+ return Math.max(1, Math.min(requested, features, Math.floor(availableParallelism() / 2)));
790
+ }
791
+ /**
792
+ * For each feature, the earlier features of the list it waits for: the
793
+ * same feature listed again, or one that registers a journey id it
794
+ * registers too. A journey listed under two features runs once in a
795
+ * sequential call and the later feature reuses its PASS (#194); running the
796
+ * two at once would run it twice and print another line. Waiting keeps the
797
+ * reuse, and with it the sequential output and evidence, at the cost of the
798
+ * overlap of those two features only.
799
+ */
800
+ function dependencies(runs, journeysOf) {
801
+ const ids = runs.map((run) => new Set(journeysOf(run.feature)));
802
+ return runs.map((run, index) => runs.flatMap((earlier, before) => before < index && (earlier.feature === run.feature || [...ids[before]].some((id) => ids[index].has(id))) ? [before] : []));
803
+ }
804
+ /**
805
+ * Starts `args` under this Node in a process group of its own, so a
806
+ * terminal's interrupt reaches it once, through {@link runConcurrently}, and
807
+ * collects what it prints into `slot`. Resolves once it exited. A process
808
+ * that ended on a signal or could not start is named on its stderr.
809
+ */
810
+ function runProcess(slot, args) {
811
+ return new Promise((resolve) => {
812
+ const child = spawn(process.execPath, args, {
813
+ stdio: [
814
+ "ignore",
815
+ "pipe",
816
+ "pipe"
817
+ ],
818
+ detached: true
819
+ });
820
+ slot.child = child;
821
+ child.stdout.on("data", (chunk) => slot.stdout.push(chunk));
822
+ child.stderr.on("data", (chunk) => slot.stderr.push(chunk));
823
+ const end = (passed, note) => {
824
+ if (note !== void 0) slot.stderr.push(Buffer.from(`${slot.run.feature}: ${note}\n`));
825
+ slot.passed = passed;
826
+ resolve();
827
+ };
828
+ child.once("error", (error) => end(false, `its journey process could not start: ${error.message}`));
829
+ child.once("close", (code, signal) => signal === null ? end(code === 0) : end(false, `its journey process ended on ${signal}`));
830
+ });
831
+ }
832
+ /**
833
+ * Runs each feature in its own `journey <run> <feature>` process, `jobs` at
834
+ * a time, and prints each feature's output whole, in the order of `runs`,
835
+ * as soon as it and every feature before it have ended. A process per
836
+ * feature gives each one the `process.env`, verify.config.ts module state
837
+ * and uncaught-error handler its own call would have, which features
838
+ * sharing one process could not keep apart while running at once. A feature
839
+ * whose process fails, ends on a signal or leaves an uncaught error does not
840
+ * stop the others. An interrupt reaches every running feature's process,
841
+ * which stops what its journey started; the call then prints what ended, in
842
+ * order, and exits with the shell's code for the signal.
843
+ * @param argsOf the arguments, after the Node executable, of the process that runs one feature.
844
+ * @returns 1 when any feature's process failed, else 0.
845
+ */
846
+ async function runConcurrently(runs, jobs, journeysOf, argsOf) {
847
+ const after = dependencies(runs, journeysOf);
848
+ const slots = runs.map((run, index) => ({
849
+ run,
850
+ after: after[index],
851
+ state: "waiting",
852
+ stdout: [],
853
+ stderr: [],
854
+ passed: false
855
+ }));
856
+ let printed = 0;
857
+ const flush = () => {
858
+ for (; slots[printed]?.state === "ended"; printed++) {
859
+ process.stdout.write(Buffer.concat(slots[printed].stdout));
860
+ process.stderr.write(Buffer.concat(slots[printed].stderr));
861
+ }
862
+ };
863
+ let interrupted;
864
+ const ready = () => interrupted === void 0 ? slots.find((slot) => slot.state === "waiting" && slot.after.every((index) => slots[index].state === "ended")) : void 0;
865
+ const busy = () => slots.filter((slot) => slot.state === "running").length;
866
+ const forward = (signal) => {
867
+ interrupted ??= signal;
868
+ for (const slot of slots) if (slot.state === "running") slot.child?.kill(signal);
869
+ };
870
+ for (const signal of INTERRUPTS$1) process.on(signal, forward);
871
+ await new Promise((done) => {
872
+ const fill = () => {
873
+ for (let slot = ready(); slot !== void 0 && busy() < jobs; slot = ready()) {
874
+ const started = slot;
875
+ started.state = "running";
876
+ runProcess(started, argsOf(started.run)).then(() => {
877
+ started.state = "ended";
878
+ flush();
879
+ fill();
880
+ });
881
+ }
882
+ if (busy() === 0 && (interrupted !== void 0 || ready() === void 0)) done();
883
+ };
884
+ fill();
885
+ });
886
+ for (const signal of INTERRUPTS$1) process.off(signal, forward);
887
+ if (interrupted !== void 0) process.exit(128 + constants$1.signals[interrupted]);
888
+ return slots.every((slot) => slot.passed) ? 0 : 1;
889
+ }
890
+ //#endregion
650
891
  //#region src/verify/judgement.ts
651
892
  const DOOR_KINDS = [
652
893
  "data",
@@ -1564,253 +1805,6 @@ function minorRule(input) {
1564
1805
  };
1565
1806
  }
1566
1807
  //#endregion
1567
- //#region src/verify/interface.ts
1568
- const CALL_ARGS = ["verify-argument", 7];
1569
- function runtimeMembers(value) {
1570
- if (!Array.isArray(value)) return [];
1571
- return value.filter(isObject).map((member) => ({
1572
- path: String(member.path),
1573
- kind: String(member.kind)
1574
- }));
1575
- }
1576
- function splitPath(path) {
1577
- const colon = path.indexOf(":");
1578
- return {
1579
- entry: path.slice(0, colon),
1580
- keys: path.slice(colon + 1).split(".")
1581
- };
1582
- }
1583
- function writeJson(folder, file, value) {
1584
- writeFileSync(join(folder, file), `${JSON.stringify(value, null, 2)}\n`);
1585
- }
1586
- /** Links the repository's node_modules under an extracted package, so its declarations resolve their imports. */
1587
- function linkDependencies(packageFolder, repo) {
1588
- symlinkSync(join(repo, "node_modules"), join(packageFolder, "node_modules"), "dir");
1589
- }
1590
- function readSurface(context, folder, label) {
1591
- const step = context.step(`${label} declared surface`);
1592
- try {
1593
- const surface = declaredSurface(folder);
1594
- writeJson(step, "surface.json", Object.fromEntries(surface));
1595
- context.expect(step, [{
1596
- name: `${label} declarations read`,
1597
- pass: true,
1598
- detail: `${surface.size} functions`
1599
- }]);
1600
- return surface;
1601
- } catch (error) {
1602
- const detail = error instanceof Error ? error.message : String(error);
1603
- context.expect(step, [{
1604
- name: `${label} declarations read`,
1605
- pass: false,
1606
- detail
1607
- }], { critical: true });
1608
- return;
1609
- }
1610
- }
1611
- function logged(context, project, path, args) {
1612
- const calls = context.stubCalls(project);
1613
- const seen = calls.some((call) => call.path === path && JSON.stringify(call.args) === JSON.stringify(args));
1614
- return {
1615
- name: `the stub provider received ${path}(${JSON.stringify(args).slice(1, -1)})`,
1616
- pass: seen,
1617
- detail: JSON.stringify(calls.filter((call) => call.path.startsWith(path)))
1618
- };
1619
- }
1620
- async function callProxy(context, app, path) {
1621
- const { entry, keys } = splitPath(path);
1622
- const result = await context.call(`call ${path}`, app, {
1623
- entry,
1624
- path: keys,
1625
- args: CALL_ARGS
1626
- });
1627
- context.expect(result.folder, [
1628
- {
1629
- name: `${path} resolved through core`,
1630
- pass: result.ok,
1631
- detail: JSON.stringify(result.value ?? result.error)
1632
- },
1633
- equal(`${path} returned the stub provider's answer`, result.value, {
1634
- stub: path,
1635
- args: CALL_ARGS
1636
- }),
1637
- logged(context, app.project, path, CALL_ARGS)
1638
- ]);
1639
- }
1640
- async function callRegistering(context, app, path) {
1641
- const { entry, keys } = splitPath(path);
1642
- const result = await context.driver(`register ${path}`, app, "/registering", {
1643
- entry,
1644
- path: keys
1645
- });
1646
- context.expect(result.folder, [
1647
- {
1648
- name: `${path} register and unregister resolved through core`,
1649
- pass: result.ok,
1650
- detail: JSON.stringify(result.value ?? result.error)
1651
- },
1652
- logged(context, app.project, `${path}.register`, ["verify-registration"]),
1653
- logged(context, app.project, `${path}.unregister`, ["verify-registration"])
1654
- ]);
1655
- }
1656
- async function callEvent(context, app, path) {
1657
- const { entry, keys } = splitPath(path);
1658
- const result = await context.driver(`emit ${path}`, app, "/event", {
1659
- entry,
1660
- path: keys,
1661
- args: CALL_ARGS
1662
- });
1663
- context.expect(result.folder, [equal(`a handler registered on ${path} received the emitted arguments`, result.value, CALL_ARGS)]);
1664
- }
1665
- async function callHook(context, app, path, expected) {
1666
- const result = await context.driver(`call ${path}`, app, "/hook", { path });
1667
- context.expect(result.folder, [{
1668
- name: `${path} resolved through core`,
1669
- pass: result.ok,
1670
- detail: JSON.stringify(result.value ?? result.error)
1671
- }, equal(`${path} returned the value verify.config.ts expects`, result.value, expected)]);
1672
- }
1673
- function unreachable(context, path, detail) {
1674
- context.expect(context.step(`no call for ${path}`), [{
1675
- name: `${path} is called through core`,
1676
- pass: false,
1677
- detail
1678
- }]);
1679
- }
1680
- async function callMember(context, app, path, members) {
1681
- const hooks = context.workspace.config.interface ?? {};
1682
- const providerSide = hooks.providerSide?.[path];
1683
- const hook = hooks.calls?.[path];
1684
- const kind = members.find((member) => member.path === path)?.kind;
1685
- if (providerSide !== void 0) {
1686
- const step = context.step(`provider side ${path}`);
1687
- context.expect(step, [{
1688
- name: `${path} is called by providers only`,
1689
- pass: providerSide.trim() !== "",
1690
- detail: providerSide
1691
- }]);
1692
- } else if (hook !== void 0) await callHook(context, app, path, hook.expect);
1693
- else if (kind === void 0) unreachable(context, path, "declared in the .d.ts files but the loaded package does not export it");
1694
- else if (kind === "async") await callProxy(context, app, path);
1695
- else if (kind === "registering") await callRegistering(context, app, path);
1696
- else if (kind === "event") await callEvent(context, app, path);
1697
- else unreachable(context, path, `a plain ${kind}: add interface.calls["${path}"] to verify.config.ts, or interface.providerSide["${path}"] with why consumers never call it`);
1698
- }
1699
- /** Loads the packed interface with a stub provider and a consumer, and calls every declared function through core. */
1700
- const everyFunction = {
1701
- title: "every declared function answers through core from a stub provider",
1702
- entryPoint: "a consumer module calling the packed interface in `ajs project dev`",
1703
- async run(context) {
1704
- const declared = readSurface(context, context.state.pack, "head");
1705
- const project = context.fixture();
1706
- const app = await context.dev("ajs project dev", project);
1707
- const surface = await context.driver("runtime surface", app, "/surface", {});
1708
- const members = runtimeMembers(surface.value);
1709
- context.expect(surface.folder, [{
1710
- name: "the consumer walked the loaded interface",
1711
- pass: surface.ok && members.length > 0,
1712
- detail: `${members.length} members`
1713
- }]);
1714
- for (const path of declared?.keys() ?? []) await callMember(context, app, path, members);
1715
- const stopped = await context.stop("SIGINT", app);
1716
- context.expect(stopped.folder, [interrupted(stopped)]);
1717
- }
1718
- };
1719
- function publishedVersion(output) {
1720
- const text = output.trim();
1721
- return text === "" ? null : text.replace(/^"|"$/g, "");
1722
- }
1723
- async function fetchPublished(context, name, version) {
1724
- const folder = join(CACHE_DIR, "published", name.replace("/", "+"), version);
1725
- mkdirSync(folder, { recursive: true });
1726
- const packed = await context.command(`npm pack ${name}@${version}`, "npm", [
1727
- "pack",
1728
- `${name}@${version}`,
1729
- "--pack-destination",
1730
- folder
1731
- ], { env: {
1732
- npm_config_offline: "false",
1733
- npm_config_prefer_offline: "false"
1734
- } });
1735
- const tarball = readdirSync(folder).find((file) => file.endsWith(".tgz"));
1736
- if (packed.exitCode !== 0 || tarball === void 0) {
1737
- context.expect(packed.folder, [exitIs(packed, 0)], { critical: true });
1738
- return;
1739
- }
1740
- const extracted = join(context.work, "published");
1741
- mkdirSync(extracted, { recursive: true });
1742
- const untar = await context.command("extract published", "tar", [
1743
- "-xzf",
1744
- join(folder, tarball),
1745
- "-C",
1746
- extracted
1747
- ]);
1748
- context.expect(untar.folder, [exitIs(untar, 0)], { critical: true });
1749
- const root = join(extracted, "package");
1750
- linkDependencies(root, context.repo);
1751
- return root;
1752
- }
1753
- function changeTitles(context) {
1754
- if (context.state.title !== "") return [context.state.title];
1755
- const base = git(context.repo, [
1756
- "merge-base",
1757
- context.state.baseRef,
1758
- "HEAD"
1759
- ]);
1760
- return git(context.repo, [
1761
- "log",
1762
- "--format=%s",
1763
- `${base}..HEAD`
1764
- ]).split("\n").filter(Boolean);
1765
- }
1766
- /** The journeys the interface kind ships, by id. */
1767
- const INTERFACE_JOURNEYS = {
1768
- "every-function": everyFunction,
1769
- "minor-bump": {
1770
- title: "an added, changed or removed function releases as a new minor",
1771
- entryPoint: "the published package against the packed head, as a module author upgrading sees it",
1772
- async run(context) {
1773
- const name = String(context.workspace.manifest.name);
1774
- const headVersion = String(context.workspace.manifest.version);
1775
- const view = await context.command(`npm view ${name}`, "npm", [
1776
- "view",
1777
- name,
1778
- "version",
1779
- "--json"
1780
- ], { env: {
1781
- npm_config_offline: "false",
1782
- npm_config_prefer_offline: "false"
1783
- } });
1784
- const missing = view.exitCode !== 0 && /E404/.test(view.stderr);
1785
- if (view.exitCode !== 0 && !missing) context.notVerified(`npm view ${name} failed: ${view.stderr.trim().slice(-200)}`);
1786
- const published = missing ? null : publishedVersion(view.stdout);
1787
- const head = readSurface(context, context.state.pack, "head");
1788
- const root = published === null ? void 0 : await fetchPublished(context, name, published);
1789
- const diff = diffSurface((root === void 0 ? void 0 : readSurface(context, root, `published ${published}`)) ?? /* @__PURE__ */ new Map(), head ?? /* @__PURE__ */ new Map());
1790
- const titles = changeTitles(context);
1791
- const verdict = minorRule({
1792
- published,
1793
- headVersion,
1794
- titles,
1795
- diff
1796
- });
1797
- const step = context.step("minor rule");
1798
- writeJson(step, "minor-rule.json", {
1799
- published,
1800
- headVersion,
1801
- titles,
1802
- ...diff,
1803
- ...verdict
1804
- });
1805
- context.expect(step, [{
1806
- name: verdict.required === "minor" ? `releases at least the next minor of ${published}` : "no function changed against the published version",
1807
- pass: verdict.ok,
1808
- detail: verdict.reason
1809
- }]);
1810
- }
1811
- }
1812
- };
1813
- //#endregion
1814
1808
  //#region src/verify/record.ts
1815
1809
  const DEFAULT_TIMEOUT_MS = 6e5;
1816
1810
  /** Quotes an argument the way a shell user would type it. */
@@ -1943,110 +1937,496 @@ function killOwnGroup(pid) {
1943
1937
  return;
1944
1938
  }
1945
1939
  }
1946
- /** Kills the process group of `pid`, or `pid` alone, ignoring a process already gone. */
1947
- function killGroup(pid) {
1948
- try {
1949
- process.kill(-pid, "SIGKILL");
1950
- } catch {
1951
- try {
1952
- process.kill(pid, "SIGKILL");
1953
- } catch {
1954
- return;
1955
- }
1940
+ /** Kills the process group of `pid`, or `pid` alone, ignoring a process already gone. */
1941
+ function killGroup(pid) {
1942
+ try {
1943
+ process.kill(-pid, "SIGKILL");
1944
+ } catch {
1945
+ try {
1946
+ process.kill(pid, "SIGKILL");
1947
+ } catch {
1948
+ return;
1949
+ }
1950
+ }
1951
+ }
1952
+ /** Reads what a background command has written so far. */
1953
+ function readOutput(folder) {
1954
+ return {
1955
+ stdout: readFileSync(join(folder, "stdout.txt"), "utf8"),
1956
+ stderr: readFileSync(join(folder, "stderr.txt"), "utf8")
1957
+ };
1958
+ }
1959
+ /** Where `freePort` looks first: below the kernel's ephemeral range, which outgoing connections keep drawing from, and below the 20000-29999 ports antelopejs-lease hands out. */
1960
+ const PORT_RANGE = {
1961
+ low: 1e4,
1962
+ high: 2e4
1963
+ };
1964
+ const PORT_ATTEMPTS = 50;
1965
+ function bindable(port) {
1966
+ return new Promise((resolve) => {
1967
+ const server = createServer();
1968
+ server.once("error", () => resolve(null));
1969
+ server.listen(port, "127.0.0.1", () => {
1970
+ const address = server.address();
1971
+ const bound = address !== null && address instanceof Object ? address.port : null;
1972
+ server.close(() => resolve(bound));
1973
+ });
1974
+ });
1975
+ }
1976
+ /**
1977
+ * A free TCP port on the loopback interface for a process the harness starts
1978
+ * next. It tries random ports below the kernel's ephemeral range first, where
1979
+ * no outgoing connection on a busy host takes it between this check and the
1980
+ * app's own bind, and falls back to a port the kernel picks.
1981
+ */
1982
+ async function freePort() {
1983
+ for (let attempt = 0; attempt < PORT_ATTEMPTS; attempt++) {
1984
+ const bound = await bindable(PORT_RANGE.low + Math.floor(Math.random() * (PORT_RANGE.high - PORT_RANGE.low)));
1985
+ if (bound !== null) return bound;
1986
+ }
1987
+ const picked = await bindable(0);
1988
+ if (picked === null) throw new Error("no free loopback port");
1989
+ return picked;
1990
+ }
1991
+ function reason(error) {
1992
+ return error.cause instanceof Error ? error.cause.message : error.message;
1993
+ }
1994
+ /** Sends one request and writes http.json with the status and body. */
1995
+ async function httpRecorded(folder, url, init = {}) {
1996
+ mkdirSync(folder, { recursive: true });
1997
+ let result;
1998
+ try {
1999
+ const response = await fetch(url, {
2000
+ method: init.method ?? "GET",
2001
+ body: init.body,
2002
+ headers: init.body ? { "content-type": "application/json" } : void 0,
2003
+ signal: AbortSignal.timeout(init.timeoutMs ?? 5e3)
2004
+ });
2005
+ const body = await response.text();
2006
+ let json;
2007
+ try {
2008
+ json = parseJson(body);
2009
+ } catch {
2010
+ json = void 0;
2011
+ }
2012
+ result = {
2013
+ folder,
2014
+ url,
2015
+ status: response.status,
2016
+ body,
2017
+ json,
2018
+ error: null
2019
+ };
2020
+ } catch (error) {
2021
+ result = {
2022
+ folder,
2023
+ url,
2024
+ status: null,
2025
+ body: "",
2026
+ json: void 0,
2027
+ error: error instanceof Error ? reason(error) : String(error)
2028
+ };
2029
+ }
2030
+ writeFileSync(join(folder, "http.json"), `${JSON.stringify({
2031
+ request: {
2032
+ url,
2033
+ ...init
2034
+ },
2035
+ response: result
2036
+ }, null, 2)}\n`);
2037
+ return result;
2038
+ }
2039
+ const TREE_SKIP = /* @__PURE__ */ new Set([
2040
+ "node_modules",
2041
+ ".git",
2042
+ ".pnpm-store"
2043
+ ]);
2044
+ function listTree(root, folder = root) {
2045
+ return readdirSync(folder, { withFileTypes: true }).filter((entry) => !TREE_SKIP.has(entry.name)).sort((left, right) => left.name.localeCompare(right.name)).flatMap((entry) => {
2046
+ const path = join(folder, entry.name);
2047
+ const name = relative(root, path);
2048
+ if (entry.isDirectory()) return [`${name}/`, ...listTree(root, path)];
2049
+ return [`${name} ${statSync(path).size}`];
2050
+ });
2051
+ }
2052
+ /** Writes `tree.txt`: every path under `root` with its size, node_modules and .git left out. */
2053
+ function recordTree(folder, root) {
2054
+ mkdirSync(folder, { recursive: true });
2055
+ let lines;
2056
+ try {
2057
+ lines = listTree(root);
2058
+ } catch {
2059
+ lines = [];
2060
+ }
2061
+ writeFileSync(join(folder, "tree.txt"), `${root}\n${lines.join("\n")}\n`);
2062
+ return lines;
2063
+ }
2064
+ //#endregion
2065
+ //#region src/verify/interface.ts
2066
+ const CALL_ARGS = ["verify-argument", 7];
2067
+ function runtimeMembers(value) {
2068
+ if (!Array.isArray(value)) return [];
2069
+ return value.filter(isObject).map((member) => ({
2070
+ path: String(member.path),
2071
+ kind: String(member.kind)
2072
+ }));
2073
+ }
2074
+ function splitPath(path) {
2075
+ const colon = path.indexOf(":");
2076
+ return {
2077
+ entry: path.slice(0, colon),
2078
+ keys: path.slice(colon + 1).split(".")
2079
+ };
2080
+ }
2081
+ function writeJson(folder, file, value) {
2082
+ writeFileSync(join(folder, file), `${JSON.stringify(value, null, 2)}\n`);
2083
+ }
2084
+ /** Links the repository's node_modules under an extracted package, so its declarations resolve their imports. */
2085
+ function linkDependencies(packageFolder, repo) {
2086
+ symlinkSync(join(repo, "node_modules"), join(packageFolder, "node_modules"), "dir");
2087
+ }
2088
+ function readSurface(context, folder, label) {
2089
+ const step = context.step(`${label} declared surface`);
2090
+ try {
2091
+ const surface = declaredSurface(folder);
2092
+ writeJson(step, "surface.json", Object.fromEntries(surface));
2093
+ context.expect(step, [{
2094
+ name: `${label} declarations read`,
2095
+ pass: true,
2096
+ detail: `${surface.size} functions`
2097
+ }]);
2098
+ return surface;
2099
+ } catch (error) {
2100
+ const detail = error instanceof Error ? error.message : String(error);
2101
+ context.expect(step, [{
2102
+ name: `${label} declarations read`,
2103
+ pass: false,
2104
+ detail
2105
+ }], { critical: true });
2106
+ return;
2107
+ }
2108
+ }
2109
+ function logged(context, project, path, args) {
2110
+ const calls = context.stubCalls(project);
2111
+ const seen = calls.some((call) => call.path === path && JSON.stringify(call.args) === JSON.stringify(args));
2112
+ return {
2113
+ name: `the stub provider received ${path}(${JSON.stringify(args).slice(1, -1)})`,
2114
+ pass: seen,
2115
+ detail: JSON.stringify(calls.filter((call) => call.path.startsWith(path)))
2116
+ };
2117
+ }
2118
+ async function callProxy(context, app, path) {
2119
+ const { entry, keys } = splitPath(path);
2120
+ const result = await context.call(`call ${path}`, app, {
2121
+ entry,
2122
+ path: keys,
2123
+ args: CALL_ARGS
2124
+ });
2125
+ context.expect(result.folder, [
2126
+ {
2127
+ name: `${path} resolved through core`,
2128
+ pass: result.ok,
2129
+ detail: JSON.stringify(result.value ?? result.error)
2130
+ },
2131
+ equal(`${path} returned the stub provider's answer`, result.value, {
2132
+ stub: path,
2133
+ args: CALL_ARGS
2134
+ }),
2135
+ logged(context, app.project, path, CALL_ARGS)
2136
+ ]);
2137
+ }
2138
+ async function callRegistering(context, app, path) {
2139
+ const { entry, keys } = splitPath(path);
2140
+ const result = await context.driver(`register ${path}`, app, "/registering", {
2141
+ entry,
2142
+ path: keys
2143
+ });
2144
+ context.expect(result.folder, [
2145
+ {
2146
+ name: `${path} register and unregister resolved through core`,
2147
+ pass: result.ok,
2148
+ detail: JSON.stringify(result.value ?? result.error)
2149
+ },
2150
+ logged(context, app.project, `${path}.register`, ["verify-registration"]),
2151
+ logged(context, app.project, `${path}.unregister`, ["verify-registration"])
2152
+ ]);
2153
+ }
2154
+ async function callEvent(context, app, path) {
2155
+ const { entry, keys } = splitPath(path);
2156
+ const result = await context.driver(`emit ${path}`, app, "/event", {
2157
+ entry,
2158
+ path: keys,
2159
+ args: CALL_ARGS
2160
+ });
2161
+ context.expect(result.folder, [equal(`a handler registered on ${path} received the emitted arguments`, result.value, CALL_ARGS)]);
2162
+ }
2163
+ async function callHook(context, app, path, expected) {
2164
+ const result = await context.driver(`call ${path}`, app, "/hook", { path });
2165
+ context.expect(result.folder, [{
2166
+ name: `${path} resolved through core`,
2167
+ pass: result.ok,
2168
+ detail: JSON.stringify(result.value ?? result.error)
2169
+ }, equal(`${path} returned the value verify.config.ts expects`, result.value, expected)]);
2170
+ }
2171
+ function unreachable(context, path, detail) {
2172
+ context.expect(context.step(`no call for ${path}`), [{
2173
+ name: `${path} is called through core`,
2174
+ pass: false,
2175
+ detail
2176
+ }]);
2177
+ }
2178
+ async function callMember(context, app, path, members) {
2179
+ const hooks = context.workspace.config.interface ?? {};
2180
+ const providerSide = hooks.providerSide?.[path];
2181
+ const hook = hooks.calls?.[path];
2182
+ const kind = members.find((member) => member.path === path)?.kind;
2183
+ if (providerSide !== void 0) {
2184
+ const step = context.step(`provider side ${path}`);
2185
+ context.expect(step, [{
2186
+ name: `${path} is called by providers only`,
2187
+ pass: providerSide.trim() !== "",
2188
+ detail: providerSide
2189
+ }]);
2190
+ } else if (hook !== void 0) await callHook(context, app, path, hook.expect);
2191
+ else if (kind === void 0) unreachable(context, path, "declared in the .d.ts files but the loaded package does not export it");
2192
+ else if (kind === "async") await callProxy(context, app, path);
2193
+ else if (kind === "registering") await callRegistering(context, app, path);
2194
+ else if (kind === "event") await callEvent(context, app, path);
2195
+ else unreachable(context, path, `a plain ${kind}: add interface.calls["${path}"] to verify.config.ts, or interface.providerSide["${path}"] with why consumers never call it`);
2196
+ }
2197
+ /** Loads the packed interface with a stub provider and a consumer, and calls every declared function through core. */
2198
+ const everyFunction = {
2199
+ title: "every declared function answers through core from a stub provider",
2200
+ entryPoint: "a consumer module calling the packed interface in `ajs project dev`",
2201
+ async run(context) {
2202
+ const declared = readSurface(context, context.state.pack, "head");
2203
+ const project = context.fixture();
2204
+ const app = await context.dev("ajs project dev", project);
2205
+ const surface = await context.driver("runtime surface", app, "/surface", {});
2206
+ const members = runtimeMembers(surface.value);
2207
+ context.expect(surface.folder, [{
2208
+ name: "the consumer walked the loaded interface",
2209
+ pass: surface.ok && members.length > 0,
2210
+ detail: `${members.length} members`
2211
+ }]);
2212
+ for (const path of declared?.keys() ?? []) await callMember(context, app, path, members);
2213
+ const stopped = await context.stop("SIGINT", app);
2214
+ context.expect(stopped.folder, [interrupted(stopped)]);
1956
2215
  }
1957
- }
1958
- /** Reads what a background command has written so far. */
1959
- function readOutput(folder) {
2216
+ };
2217
+ /** Reads the latest version and its sha512 integrity from `npm view <name> version dist.integrity --json`. */
2218
+ function publishedView(output) {
2219
+ const text = output.trim();
2220
+ if (text === "") return {
2221
+ version: null,
2222
+ integrity: null
2223
+ };
2224
+ const parsed = parseJson(text);
2225
+ if (isString(parsed)) return {
2226
+ version: parsed,
2227
+ integrity: null
2228
+ };
2229
+ if (!isObject(parsed)) return {
2230
+ version: null,
2231
+ integrity: null
2232
+ };
1960
2233
  return {
1961
- stdout: readFileSync(join(folder, "stdout.txt"), "utf8"),
1962
- stderr: readFileSync(join(folder, "stderr.txt"), "utf8")
2234
+ version: optStr(parsed, "version") ?? null,
2235
+ integrity: sha512Token(optStr(parsed, "dist.integrity"))
1963
2236
  };
1964
2237
  }
1965
- /** Asks the kernel for a free TCP port on the loopback interface. */
1966
- function freePort() {
1967
- return new Promise((resolve, reject) => {
1968
- const server = createServer();
1969
- server.once("error", reject);
1970
- server.listen(0, "127.0.0.1", () => {
1971
- const address = server.address();
1972
- const port = address !== null && address instanceof Object ? address.port : 0;
1973
- server.close(() => resolve(port));
1974
- });
1975
- });
2238
+ /** The `sha512-` token of a Subresource Integrity value, which may list several hashes; `null` when it has none, which npm also checks but this cache cannot. */
2239
+ function sha512Token(integrity) {
2240
+ return (integrity ?? "").split(/\s+/).find((token) => token.startsWith("sha512-")) ?? null;
1976
2241
  }
1977
- function reason(error) {
1978
- return error.cause instanceof Error ? error.cause.message : error.message;
1979
- }
1980
- /** Sends one request and writes http.json with the status and body. */
1981
- async function httpRecorded(folder, url, init = {}) {
1982
- mkdirSync(folder, { recursive: true });
1983
- let result;
2242
+ const ONLINE = {
2243
+ npm_config_offline: "false",
2244
+ npm_config_prefer_offline: "false"
2245
+ };
2246
+ function tarballsIn(folder) {
2247
+ if (!existsSync(folder)) return [];
2248
+ return readdirSync(folder).filter((entry) => entry.endsWith(".tgz")).map((entry) => join(folder, entry));
2249
+ }
2250
+ /** The registry's integrity string of a file: `sha512-` and the base64 of its SHA-512. */
2251
+ function integrityOf(file) {
2252
+ return `sha512-${createHash("sha512").update(readFileSync(file)).digest("base64")}`;
2253
+ }
2254
+ /** Packs into a staging folder next to the cache, so the cache only ever receives a complete tarball that matches the published integrity. */
2255
+ async function packPublished(context, published, folder) {
2256
+ const { name, version, integrity } = published;
2257
+ mkdirSync(dirname(folder), { recursive: true });
2258
+ const staging = mkdtempSync(`${folder}.pack-`);
2259
+ const release = onInterrupt(() => rmSync(staging, {
2260
+ recursive: true,
2261
+ force: true
2262
+ }));
1984
2263
  try {
1985
- const response = await fetch(url, {
1986
- method: init.method ?? "GET",
1987
- body: init.body,
1988
- headers: init.body ? { "content-type": "application/json" } : void 0,
1989
- signal: AbortSignal.timeout(init.timeoutMs ?? 5e3)
1990
- });
1991
- const body = await response.text();
1992
- let json;
1993
- try {
1994
- json = parseJson(body);
1995
- } catch {
1996
- json = void 0;
2264
+ const packed = await context.command(`npm pack ${name}@${version}`, "npm", [
2265
+ "pack",
2266
+ `${name}@${version}`,
2267
+ "--pack-destination",
2268
+ staging
2269
+ ], { env: ONLINE });
2270
+ const [staged] = tarballsIn(staging);
2271
+ if (packed.exitCode !== 0 || staged === void 0) {
2272
+ context.expect(packed.folder, [exitIs(packed, 0)], { critical: true });
2273
+ return;
1997
2274
  }
1998
- result = {
1999
- folder,
2000
- url,
2001
- status: response.status,
2002
- body,
2003
- json,
2004
- error: null
2005
- };
2006
- } catch (error) {
2007
- result = {
2008
- folder,
2009
- url,
2010
- status: null,
2011
- body: "",
2012
- json: void 0,
2013
- error: error instanceof Error ? reason(error) : String(error)
2014
- };
2275
+ if (integrity !== null) {
2276
+ const actual = integrityOf(staged);
2277
+ context.expect(context.step(`check packed ${name}@${version}`), [{
2278
+ name: `the packed tarball of ${name}@${version} has the integrity the registry publishes`,
2279
+ pass: actual === integrity,
2280
+ detail: `packed ${actual}, published ${integrity}`
2281
+ }], { critical: true });
2282
+ }
2283
+ if (integrity === null) {
2284
+ const uncached = join(context.work, basename(staged));
2285
+ copyFileSync(staged, uncached);
2286
+ return uncached;
2287
+ }
2288
+ mkdirSync(folder, { recursive: true });
2289
+ const cached = join(folder, basename(staged));
2290
+ renameSync(staged, cached);
2291
+ return cached;
2292
+ } finally {
2293
+ release();
2294
+ rmSync(staging, {
2295
+ recursive: true,
2296
+ force: true
2297
+ });
2015
2298
  }
2016
- writeFileSync(join(folder, "http.json"), `${JSON.stringify({
2017
- request: {
2018
- url,
2019
- ...init
2020
- },
2021
- response: result
2022
- }, null, 2)}\n`);
2023
- return result;
2024
2299
  }
2025
- const TREE_SKIP = /* @__PURE__ */ new Set([
2026
- "node_modules",
2027
- ".git",
2028
- ".pnpm-store"
2029
- ]);
2030
- function listTree(root, folder = root) {
2031
- return readdirSync(folder, { withFileTypes: true }).filter((entry) => !TREE_SKIP.has(entry.name)).sort((left, right) => left.name.localeCompare(right.name)).flatMap((entry) => {
2032
- const path = join(folder, entry.name);
2033
- const name = relative(root, path);
2034
- if (entry.isDirectory()) return [`${name}/`, ...listTree(root, path)];
2035
- return [`${name} ${statSync(path).size}`];
2300
+ async function extractPublished(context, tarball) {
2301
+ const extracted = join(context.work, "published");
2302
+ rmSync(extracted, {
2303
+ recursive: true,
2304
+ force: true
2036
2305
  });
2306
+ mkdirSync(extracted, { recursive: true });
2307
+ const untar = await context.command("extract published", "tar", [
2308
+ "-xzf",
2309
+ tarball,
2310
+ "-C",
2311
+ extracted
2312
+ ]);
2313
+ context.expect(untar.folder, [exitIs(untar, 0)], { critical: true });
2314
+ const root = join(extracted, "package");
2315
+ linkDependencies(root, context.repo);
2316
+ return root;
2037
2317
  }
2038
- /** Writes `tree.txt`: every path under `root` with its size, node_modules and .git left out. */
2039
- function recordTree(folder, root) {
2040
- mkdirSync(folder, { recursive: true });
2041
- let lines;
2318
+ /**
2319
+ * A private copy, under the journey's work folder, of the cached tarball of a
2320
+ * version, only when it is the folder's single tarball and the copy's
2321
+ * integrity is the published one. Hashing and extracting the same copy keeps
2322
+ * another run that replaces the cached file in between from changing what
2323
+ * this journey reads.
2324
+ */
2325
+ function trustedTarball(files, integrity, work) {
2326
+ const [only] = files;
2327
+ if (files.length !== 1 || integrity === null) return void 0;
2328
+ const copy = join(work, basename(only));
2042
2329
  try {
2043
- lines = listTree(root);
2330
+ copyFileSync(only, copy);
2044
2331
  } catch {
2045
- lines = [];
2332
+ return;
2046
2333
  }
2047
- writeFileSync(join(folder, "tree.txt"), `${root}\n${lines.join("\n")}\n`);
2048
- return lines;
2334
+ return integrityOf(copy) === integrity ? copy : void 0;
2335
+ }
2336
+ /** Extracts a published version from the cache when its one tarball has the published integrity, and packs it again otherwise. */
2337
+ async function fetchPublished(context, name, published) {
2338
+ const { version, integrity } = published;
2339
+ const folder = join(CACHE_DIR, "published", name.replace("/", "+"), version);
2340
+ const files = tarballsIn(folder);
2341
+ mkdirSync(context.work, { recursive: true });
2342
+ const trusted = trustedTarball(files, integrity, context.work);
2343
+ if (trusted !== void 0) {
2344
+ context.expect(context.step(`reuse cached ${name}@${version}`), [{
2345
+ name: `the cached tarball of ${name}@${version} has the published integrity, so it is reused and no npm pack ran`,
2346
+ pass: true,
2347
+ detail: `${files[0]}: ${integrity}`
2348
+ }]);
2349
+ return extractPublished(context, trusted);
2350
+ }
2351
+ if (files.length > 0) {
2352
+ for (const file of files) rmSync(file, { force: true });
2353
+ context.expect(context.step(`discard cached ${name}@${version}`), [{
2354
+ name: `the cached tarballs of ${name}@${version} are deleted and packed again, as ${files.length === 1 ? "the one" : `none of the ${files.length}`} cannot be trusted`,
2355
+ pass: tarballsIn(folder).length === 0,
2356
+ detail: `${files.join(", ")} against ${integrity ?? "no published integrity"}`
2357
+ }]);
2358
+ }
2359
+ const packed = await packPublished(context, {
2360
+ name,
2361
+ version,
2362
+ integrity
2363
+ }, folder);
2364
+ return packed === void 0 ? void 0 : extractPublished(context, packed);
2365
+ }
2366
+ function changeTitles(context) {
2367
+ if (context.state.title !== "") return [context.state.title];
2368
+ const base = git(context.repo, [
2369
+ "merge-base",
2370
+ context.state.baseRef,
2371
+ "HEAD"
2372
+ ]);
2373
+ return git(context.repo, [
2374
+ "log",
2375
+ "--format=%s",
2376
+ `${base}..HEAD`
2377
+ ]).split("\n").filter(Boolean);
2049
2378
  }
2379
+ /** The journeys the interface kind ships, by id. */
2380
+ const INTERFACE_JOURNEYS = {
2381
+ "every-function": everyFunction,
2382
+ "minor-bump": {
2383
+ title: "an added, changed or removed function releases as a new minor",
2384
+ entryPoint: "the published package against the packed head, as a module author upgrading sees it",
2385
+ async run(context) {
2386
+ const name = String(context.workspace.manifest.name);
2387
+ const headVersion = String(context.workspace.manifest.version);
2388
+ const view = await context.command(`npm view ${name}`, "npm", [
2389
+ "view",
2390
+ name,
2391
+ "version",
2392
+ "dist.integrity",
2393
+ "--json"
2394
+ ], { env: ONLINE });
2395
+ const missing = view.exitCode !== 0 && /E404/.test(view.stderr);
2396
+ if (view.exitCode !== 0 && !missing) context.notVerified(`npm view ${name} failed: ${view.stderr.trim().slice(-200)}`);
2397
+ const { version: published, integrity } = missing ? {
2398
+ version: null,
2399
+ integrity: null
2400
+ } : publishedView(view.stdout);
2401
+ const head = readSurface(context, context.state.pack, "head");
2402
+ const root = published === null ? void 0 : await fetchPublished(context, name, {
2403
+ version: published,
2404
+ integrity
2405
+ });
2406
+ const diff = diffSurface((root === void 0 ? void 0 : readSurface(context, root, `published ${published}`)) ?? /* @__PURE__ */ new Map(), head ?? /* @__PURE__ */ new Map());
2407
+ const titles = changeTitles(context);
2408
+ const verdict = minorRule({
2409
+ published,
2410
+ headVersion,
2411
+ titles,
2412
+ diff
2413
+ });
2414
+ const step = context.step("minor rule");
2415
+ writeJson(step, "minor-rule.json", {
2416
+ published,
2417
+ headVersion,
2418
+ titles,
2419
+ ...diff,
2420
+ ...verdict
2421
+ });
2422
+ context.expect(step, [{
2423
+ name: verdict.required === "minor" ? `releases at least the next minor of ${published}` : "no function changed against the published version",
2424
+ pass: verdict.ok,
2425
+ detail: verdict.reason
2426
+ }]);
2427
+ }
2428
+ }
2429
+ };
2050
2430
  //#endregion
2051
2431
  //#region src/verify/sources.ts
2052
2432
  const IDENTITY = [
@@ -3092,7 +3472,12 @@ var JourneyAbort = class extends Error {};
3092
3472
  var NotVerified = class extends Error {};
3093
3473
  const READY_TIMEOUT_MS = 12e4;
3094
3474
  const STOP_TIMEOUT_MS = 3e4;
3475
+ /** The longest wait between readiness probes. */
3095
3476
  const POLL_MS = 250;
3477
+ /** The wait between readiness probes in the first `FAST_POLL_WINDOW_MS`, where most apps come up: an app ready in 300 ms is seen within 25 ms of it instead of at the 500 ms tick. */
3478
+ const FAST_POLL_MS = 25;
3479
+ /** How long readiness is probed every `FAST_POLL_MS` before falling back to `POLL_MS`. */
3480
+ const FAST_POLL_WINDOW_MS = 3e3;
3096
3481
  const SETTLE_MS = 3e3;
3097
3482
  /** The waits between the readiness reruns after a failed journey: one miss under load does not hide a catch. */
3098
3483
  const READINESS_RETRY_MS = [
@@ -3282,11 +3667,10 @@ var VerifyContext = class {
3282
3667
  });
3283
3668
  this.running.push(entry);
3284
3669
  this.started.push(entry);
3285
- this.state.processes.push({
3670
+ recordProcesses(this.state, { add: [{
3286
3671
  name: `${name} (${project})`,
3287
3672
  pid: handle.pid
3288
- });
3289
- saveRun(this.state);
3673
+ }] });
3290
3674
  await this.waitReady(app, handle, fixture !== void 0);
3291
3675
  return this.caches.observed(app);
3292
3676
  }
@@ -3317,9 +3701,10 @@ var VerifyContext = class {
3317
3701
  handle.exited.then(() => {
3318
3702
  exited = true;
3319
3703
  });
3704
+ const fastUntil = Date.now() + FAST_POLL_WINDOW_MS;
3320
3705
  let check = await this.probe(app, fixture, folder);
3321
3706
  while (!check.pass && !exited && Date.now() < deadline) {
3322
- await setTimeout$1(POLL_MS);
3707
+ await setTimeout$1(Date.now() < fastUntil ? FAST_POLL_MS : POLL_MS);
3323
3708
  check = await this.probe(app, fixture, folder);
3324
3709
  }
3325
3710
  const settle = this.workspace.config.template?.probe.log ? this.workspace.config.template.probe.settleMs ?? SETTLE_MS : 0;
@@ -3395,8 +3780,7 @@ var VerifyContext = class {
3395
3780
  untrack(pid) {
3396
3781
  const index = this.running.findIndex((entry) => entry.app.pid === pid);
3397
3782
  if (index !== -1) this.running.splice(index, 1);
3398
- this.state.processes = this.state.processes.filter((record) => record.pid !== pid);
3399
- saveRun(this.state);
3783
+ recordProcesses(this.state, { drop: [pid] });
3400
3784
  }
3401
3785
  async scaffold(name, project, flags = [
3402
3786
  "--pm",
@@ -3505,13 +3889,24 @@ function statusOf(context, failure) {
3505
3889
  if (failure.notVerified !== null) return "NOT VERIFIED";
3506
3890
  return failure.error !== null || context.steps.some((step) => step.checks.some((check) => !check.pass)) || context.steps.length === 0 ? "FAIL" : "PASS";
3507
3891
  }
3892
+ /** Removes the empty folders from `folder` up to, not including, `top`; it stops at the first that another journey of the run filled or removed meanwhile. */
3893
+ function removeEmptyParents(folder, top) {
3894
+ try {
3895
+ for (let parent = dirname(folder); parent !== top && readdirSync(parent).length === 0; parent = dirname(parent)) rmdirSync(parent);
3896
+ } catch {
3897
+ return;
3898
+ }
3899
+ }
3508
3900
  /** Deletes a journey's scratch folder and HOME, and their parents once empty; the evidence stays. A folder it cannot delete is reported on stderr and left for the next prune. */
3509
3901
  function discard(context) {
3510
- for (const folder of [context.work, context.home]) try {
3511
- removeTree(folder);
3512
- for (let parent = dirname(folder); parent !== context.state.dir && readdirSync(parent).length === 0; parent = dirname(parent)) rmdirSync(parent);
3513
- } catch (error) {
3514
- process.stderr.write(`could not delete ${folder}: ${error instanceof Error ? error.message : String(error)}\n`);
3902
+ for (const folder of [context.work, context.home]) {
3903
+ try {
3904
+ removeTree(folder);
3905
+ } catch (error) {
3906
+ process.stderr.write(`could not delete ${folder}: ${error instanceof Error ? error.message : String(error)}\n`);
3907
+ continue;
3908
+ }
3909
+ removeEmptyParents(folder, context.state.dir);
3515
3910
  }
3516
3911
  }
3517
3912
  async function runOne(workspace, state, feature, id, journey) {
@@ -3521,8 +3916,7 @@ async function runOne(workspace, state, feature, id, journey) {
3521
3916
  const own = state.processes.filter((record) => !others.has(record.pid));
3522
3917
  for (const record of own) killGroup(record.pid);
3523
3918
  discard(context);
3524
- state.processes = state.processes.filter((record) => others.has(record.pid));
3525
- saveRun(state);
3919
+ recordProcesses(state, { drop: own.map((record) => record.pid) });
3526
3920
  });
3527
3921
  try {
3528
3922
  return await driveJourney(context, feature, id, journey);
@@ -3697,7 +4091,7 @@ async function runFeature(workspace, state, feature, ids) {
3697
4091
  results.push(source === void 0 ? stamp(state, await runOne(workspace, state, feature, id, journey), tree) : reuse(state, feature, id, source));
3698
4092
  }
3699
4093
  const merged = registered.flatMap((id) => results.filter((result) => result.journey === id).concat(results.some((result) => result.journey === id) ? [] : earlier.filter((result) => result.journey === id)));
3700
- writeFileSync(join(state.evidence, feature, "feature.json"), `${JSON.stringify(merged, null, 2)}\n`);
4094
+ writeWhole(join(state.evidence, feature, "feature.json"), `${JSON.stringify(merged, null, 2)}\n`);
3701
4095
  return results;
3702
4096
  }
3703
4097
  //#endregion
@@ -4001,6 +4395,11 @@ const USAGE = `Usage: antelopejs-verify <command>
4001
4395
  build, prepare an isolated run, print its folder; --all runs every feature, before a release
4002
4396
  doctor <run> check the run is worth driving
4003
4397
  journey <run> <feature> [ids...] run a feature's journeys and record evidence
4398
+ journey <run> --plan [--jobs <n>] run every feature the run's plan lists, smoke first
4399
+ journey <run> --features <a,b> [--jobs <n>]
4400
+ run the named features, each whole, in that order;
4401
+ --jobs runs up to n features at once, each in its own process,
4402
+ at most half the cores, never with services
4004
4403
  formal <run> [--all] run the formal checks that cover the diff and gate them on changed behaviour
4005
4404
  doors [patch] [--base <ref>] print the One-way-door line for a patch, or for the diff
4006
4405
  clean <run> stop what the run started, keep only the evidence
@@ -4024,15 +4423,115 @@ function printMap(workspace) {
4024
4423
  for (const problem of problems) print(problem);
4025
4424
  return problems.length === 0 ? 0 : 1;
4026
4425
  }
4027
- async function runJourneys(workspace, dir, feature, ids) {
4028
- const results = await runFeature(workspace, loadRun(dir), feature, ids);
4426
+ /**
4427
+ * The features a `journey` call runs, in order.
4428
+ *
4429
+ * `journey <run> <feature> [ids...]` runs one feature, or the named journeys
4430
+ * of it. `journey <run> --plan` runs every feature `plan` lists as `run` for
4431
+ * the run's base and `--all`, `smoke` first. `journey <run> --features a,b`
4432
+ * runs the named features whole, in that order. Several features take a flag
4433
+ * rather than more positionals because a positional after the feature is a
4434
+ * journey id: reading it as a feature whenever a feature file has that name
4435
+ * would change what an existing call runs as soon as someone adds a feature
4436
+ * named like one of its journeys.
4437
+ */
4438
+ function featureRuns(workspace, rest, flags) {
4439
+ const [dir, feature, ...ids] = rest;
4440
+ if (flags.plan !== true && flags.features === void 0) return [{
4441
+ feature,
4442
+ ids
4443
+ }];
4444
+ if (flags.plan === true && flags.features !== void 0) throw new Error("journey takes --plan or --features, not both");
4445
+ if (feature !== void 0) throw new Error("--plan and --features run whole features; name journey ids after one feature: journey <run> <feature> [ids...]");
4446
+ if (flags.plan === true) {
4447
+ const state = loadRun(dir);
4448
+ return planFor(workspace, state.baseRef, state.all).run.map((name) => ({
4449
+ feature: name,
4450
+ ids: []
4451
+ }));
4452
+ }
4453
+ const names = (flags.features ?? []).flatMap((list) => list.split(",")).map((name) => name.trim()).filter(Boolean);
4454
+ if (names.length === 0) throw new Error("--features names no feature");
4455
+ return names.map((name) => ({
4456
+ feature: name,
4457
+ ids: []
4458
+ }));
4459
+ }
4460
+ /**
4461
+ * Runs one feature's journeys as its own `journey` call would, and prints its
4462
+ * lines once it ends. A feature that cannot run, an unknown feature or
4463
+ * journey for one, prints its error on stderr instead.
4464
+ * @returns whether every journey it ran passed.
4465
+ */
4466
+ async function journeyFeature(workspace, dir, { feature, ids }) {
4467
+ let results;
4468
+ try {
4469
+ results = await runFeature(workspace, loadRun(dir), feature, ids);
4470
+ } catch (error) {
4471
+ process.stderr.write(`${error instanceof Error ? error.message : String(error)}\n`);
4472
+ return false;
4473
+ }
4029
4474
  for (const result of results) {
4030
4475
  print(`${result.status} ${feature}/${result.journey}${result.reusedFrom === void 0 ? ` (${seconds(result.ms)})` : ` (reuses ${result.reusedFrom}, not run again)`}`);
4031
4476
  for (const step of result.steps) for (const check of step.checks.filter((entry) => !entry.pass)) print(` ${step.name}: ${check.name} (${check.detail})`);
4032
4477
  if (result.error) print(` ${result.error.split("\n")[0]}`);
4033
4478
  if (result.notVerified) print(` ${result.notVerified}`);
4034
4479
  }
4035
- return results.every((result) => result.status === "PASS") ? 0 : 1;
4480
+ return results.every((result) => result.status === "PASS");
4481
+ }
4482
+ /**
4483
+ * Runs the features in order, each one as if by its own call: a feature
4484
+ * whose journeys fail does not stop the next, a feature reuses the PASS of a
4485
+ * journey an earlier one ran, and `process.env` is restored after each
4486
+ * feature. An uncaught error a journey leaves behind (a timer that throws, a
4487
+ * rejection nobody awaits) ends the call, as it would end a single call, and
4488
+ * names the features that did not run. Module-level state a repository's
4489
+ * verify.config.ts keeps is shared by the features of one call. `--jobs`
4490
+ * runs features at once in processes of their own instead, through
4491
+ * {@link runConcurrently}.
4492
+ * @returns 1 when any feature had a journey that did not pass or could not run, else 0.
4493
+ */
4494
+ async function runJourneys(workspace, dir, runs) {
4495
+ let current = 0;
4496
+ const abort = (message) => {
4497
+ const left = runs.slice(current + 1).map((run) => run.feature);
4498
+ process.stderr.write(`${runs[current]?.feature ?? "journey"}: a journey left an uncaught error: ${message}\n${left.length > 0 ? `not run: ${left.join(", ")}\n` : ""}`);
4499
+ process.exit(1);
4500
+ };
4501
+ const onError = (error) => abort(error.message);
4502
+ const onRejection = (reason) => abort(reason instanceof Error ? reason.message : String(reason));
4503
+ process.on("uncaughtException", onError);
4504
+ process.on("unhandledRejection", onRejection);
4505
+ const env = { ...process.env };
4506
+ let passed = true;
4507
+ for (; current < runs.length; current++) {
4508
+ passed = await journeyFeature(workspace, dir, runs[current]) && passed;
4509
+ restoreEnv(env);
4510
+ }
4511
+ process.off("uncaughtException", onError);
4512
+ process.off("unhandledRejection", onRejection);
4513
+ return passed ? 0 : 1;
4514
+ }
4515
+ /** Puts `process.env` back to `saved`, so a journey that set a variable leaves the next feature the environment its own call would have. */
4516
+ function restoreEnv(saved) {
4517
+ for (const key of Object.keys(process.env)) if (!Object.hasOwn(saved, key)) delete process.env[key];
4518
+ Object.assign(process.env, saved);
4519
+ }
4520
+ /**
4521
+ * How many features a `journey` call runs at once: 1 without `--jobs`, else
4522
+ * `--jobs` capped by {@link jobLimit}. `--jobs` applies to `--plan` and
4523
+ * `--features` only, and more than 1 is refused when verify.config.ts
4524
+ * declares `services`: every journey resets them as it starts, which would
4525
+ * wipe the data of a journey running beside it.
4526
+ */
4527
+ function jobsFor(workspace, runs, flags) {
4528
+ if (flags.jobs === void 0) return 1;
4529
+ if (flags.plan !== true && flags.features === void 0) throw new Error("--jobs runs whole features at once: use it with --plan or --features");
4530
+ if (!/^[1-9]\d*$/.test(flags.jobs)) throw new Error(`--jobs takes a number of features, 1 or more, not ${flags.jobs}`);
4531
+ const requested = Number(flags.jobs);
4532
+ const services = Object.keys(workspace.config.services ?? {});
4533
+ if (requested > 1 && services.length > 0) throw new Error(`--jobs ${requested} refused: verify.config.ts declares services (${services.join(", ")}), and each journey resets them as it starts, which would wipe the data of a journey running beside it. Run the features without --jobs.`);
4534
+ return jobLimit(requested, runs.length);
4036
4535
  }
4037
4536
  function runFormal(workspace, dir, all) {
4038
4537
  const state = loadRun(dir);
@@ -4089,7 +4588,13 @@ async function main(argv) {
4089
4588
  },
4090
4589
  pr: { type: "string" },
4091
4590
  all: { type: "boolean" },
4092
- kind: { type: "string" }
4591
+ kind: { type: "string" },
4592
+ plan: { type: "boolean" },
4593
+ features: {
4594
+ type: "string",
4595
+ multiple: true
4596
+ },
4597
+ jobs: { type: "string" }
4093
4598
  }
4094
4599
  });
4095
4600
  const [command, ...rest] = positionals;
@@ -4098,6 +4603,8 @@ async function main(argv) {
4098
4603
  return 0;
4099
4604
  }
4100
4605
  const root = repositoryRoot();
4606
+ const path = withLocalBins(root, process.env.PATH);
4607
+ if (path !== void 0) process.env.PATH = path;
4101
4608
  const workspace = await openWorkspace(root, detectKind(root, values.kind));
4102
4609
  if (command === "new") print((await createRun(workspace, values.base, values.title, values.all === true)).dir);
4103
4610
  else if (command === "map") return printMap(workspace);
@@ -4109,8 +4616,20 @@ async function main(argv) {
4109
4616
  const lines = doctor(workspace, loadRun(rest[0]));
4110
4617
  for (const line of lines) print(`${line.ok ? "ok " : "FAIL"} ${line.check}: ${line.detail}`);
4111
4618
  return lines.every((line) => line.ok) ? 0 : 1;
4112
- } else if (command === "journey") return runJourneys(workspace, rest[0], rest[1], rest.slice(2));
4113
- else if (command === "formal") return runFormal(workspace, rest[0], values.all === true);
4619
+ } else if (command === "journey") {
4620
+ const runs = featureRuns(workspace, rest, values);
4621
+ const jobs = jobsFor(workspace, runs, values);
4622
+ if (jobs === 1) return runJourneys(workspace, rest[0], runs);
4623
+ return runConcurrently(runs, jobs, (name) => featureJourneys(workspace, name) ?? [], ({ feature }) => [
4624
+ ...process.execArgv,
4625
+ process.argv[1],
4626
+ "journey",
4627
+ resolve(rest[0]),
4628
+ feature,
4629
+ "--kind",
4630
+ workspace.kind
4631
+ ]);
4632
+ } else if (command === "formal") return runFormal(workspace, rest[0], values.all === true);
4114
4633
  else if (command === "doors") return printDoors(workspace, rest[0] ? patchFiles(rest[0]) : planFor(workspace, values.base).changed);
4115
4634
  else if (command === "clean") for (const line of clean(loadRun(rest[0]))) print(line);
4116
4635
  else if (command === "verdict" || command === "publish") return judge(workspace, command, rest[0], Number(values.pr));