@antelopejs/tooling-configs 0.3.4 → 0.3.6

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,16 +4,17 @@ 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, i as planFor, l as git, m as saveRun, n as SMOKE_FEATURE, o as CACHE_DIR, p as removeTree, r as checkMap, s as RUNS_DIR, u as isolatedEnv } from "../map-mT2iQzit.mjs";
8
- import { appendFileSync, closeSync, copyFileSync, cpSync, existsSync, lstatSync, mkdirSync, mkdtempSync, openSync, readFileSync, readdirSync, readlinkSync, realpathSync, rmSync, rmdirSync, statSync, symlinkSync, writeFileSync } from "node:fs";
9
- import { dirname, extname, isAbsolute, join, matchesGlob, posix, relative, resolve, sep } from "node:path";
7
+ import { _ as withLocalBins, 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-CiFEGFRz.mjs";
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";
10
10
  import { execFileSync, spawn, spawnSync } from "node:child_process";
11
11
  import { pathToFileURL } from "node:url";
12
12
  import ts from "typescript";
13
- import { createHash } from "node:crypto";
13
+ import { createHash, randomBytes } from "node:crypto";
14
14
  import { constants as constants$1, tmpdir } from "node:os";
15
15
  import { parseArgs } from "node:util";
16
16
  import { createServer } from "node:net";
17
+ import { setTimeout as setTimeout$1 } from "node:timers/promises";
17
18
  //#region src/verify/doors.ts
18
19
  const RELEASE_FILES = [
19
20
  "package.json",
@@ -339,7 +340,7 @@ const DETAIL_LENGTH = 160;
339
340
  const OUTPUT_LIMIT$1 = 67108864;
340
341
  /** Runs `action` in a throwaway worktree of `sha` whose `node_modules` links the checkout's, then removes it. */
341
342
  function inWorktree(repo, sha, action) {
342
- const dir = mkdtempSync(join(tmpdir(), "antelopejs-verify-behaviour-"));
343
+ const dir = mkdtempSync(join(operatorTmpdir(), "antelopejs-verify-behaviour-"));
343
344
  git(repo, [
344
345
  "worktree",
345
346
  "add",
@@ -370,6 +371,7 @@ function probeFingerprint(repo, command, sha) {
370
371
  return inWorktree(repo, sha, (dir) => {
371
372
  const run = spawnSync(program, [...args, dir], {
372
373
  cwd: repo,
374
+ env: operatorEnv(),
373
375
  encoding: "utf8",
374
376
  maxBuffer: OUTPUT_LIMIT$1
375
377
  });
@@ -451,6 +453,61 @@ function behaviourChange(repo, check, commits) {
451
453
  };
452
454
  }
453
455
  //#endregion
456
+ //#region src/verify/timing.ts
457
+ /** Starts a clock; the returned function gives the whole milliseconds elapsed since. */
458
+ function stopwatch() {
459
+ const start = performance.now();
460
+ return () => Math.round(performance.now() - start);
461
+ }
462
+ /** Runs `phase` and records how long it took on the run, also when it throws, so a run whose `new` failed still shows the time it spent; a failed phase is labelled as such. */
463
+ async function timed(state, phase, run) {
464
+ const elapsed = stopwatch();
465
+ let failed = true;
466
+ try {
467
+ const value = await run();
468
+ failed = false;
469
+ return value;
470
+ } finally {
471
+ state.timings.push({
472
+ phase: failed ? `${phase} (failed)` : phase,
473
+ ms: elapsed()
474
+ });
475
+ }
476
+ }
477
+ /**
478
+ * Times the step folders of one journey: a step lasts from the `start` call
479
+ * that names it to the next `start` call, or to `finish` for the last one.
480
+ */
481
+ var StepClock = class {
482
+ times = [];
483
+ open = null;
484
+ /** Ends the running step, if any, and starts timing `step`. */
485
+ start(step) {
486
+ this.close();
487
+ this.open = {
488
+ step,
489
+ elapsed: stopwatch()
490
+ };
491
+ }
492
+ /** Ends the running step and returns how long every step lasted, in the order they started. */
493
+ finish() {
494
+ this.close();
495
+ return this.times;
496
+ }
497
+ close() {
498
+ if (this.open === null) return;
499
+ this.times.push({
500
+ step: this.open.step,
501
+ ms: this.open.elapsed()
502
+ });
503
+ this.open = null;
504
+ }
505
+ };
506
+ /** Milliseconds as seconds with one decimal, e.g. `12.3 s`; `not measured` when there is no measurement. */
507
+ function seconds(ms) {
508
+ return ms === null || ms === void 0 ? "not measured" : `${(ms / 1e3).toFixed(1)} s`;
509
+ }
510
+ //#endregion
454
511
  //#region src/verify/formal.ts
455
512
  const OUTPUT_LIMIT = 67108864;
456
513
  function changesCheckFiles(check, changed) {
@@ -468,17 +525,34 @@ function passingRules(check, exitCode, output) {
468
525
  if (check.passing) return [...new Set([...output.matchAll(check.passing)].map((match) => match[1]))];
469
526
  return !check.violation && exitCode === 0 ? ["property"] : [];
470
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
+ }
471
543
  function rulesOf(check, run) {
472
544
  return {
473
545
  exitCode: run.status,
474
546
  violated: violatedRules(check, run.status, run.stdout ?? ""),
475
- passing: passingRules(check, run.status, run.stdout ?? "")
547
+ passing: passingRules(check, run.status, run.stdout ?? ""),
548
+ lengths: counterexampleLengths(check, run.stdout ?? "")
476
549
  };
477
550
  }
478
551
  function runCommand(command, cwd) {
479
552
  const [program, ...args] = command;
480
553
  return spawnSync(program, args, {
481
554
  cwd,
555
+ env: operatorEnv(),
482
556
  encoding: "utf8",
483
557
  maxBuffer: OUTPUT_LIMIT
484
558
  });
@@ -517,7 +591,8 @@ function gateFields(workspace, check, diff, folder, head) {
517
591
  }
518
592
  /**
519
593
  * Runs one formal check from the repository root and writes its command,
520
- * output, exit code and violated rules under `evidence/formal/<name>/`.
594
+ * output, exit code, violated rules and their counterexample lengths under
595
+ * `evidence/formal/<name>/`.
521
596
  * When the check covers the diff (`diff` given), it also records whether the
522
597
  * diff changed the covered code's behaviour. When it did, or when the diff
523
598
  * changed the check's own `files`, it runs the check on the base: `fixed`
@@ -525,6 +600,7 @@ function gateFields(workspace, check, diff, folder, head) {
525
600
  * the rules the base broke that HEAD reports neither failing nor passing.
526
601
  */
527
602
  function runFormalCheck(workspace, state, check, diff) {
603
+ const elapsed = stopwatch();
528
604
  const folder = join(state.evidence, "formal", check.name);
529
605
  mkdirSync(folder, { recursive: true });
530
606
  const run = runCommand(check.command, workspace.root);
@@ -535,22 +611,42 @@ function runFormalCheck(workspace, state, check, diff) {
535
611
  exitCode: run.status,
536
612
  violated: head.violated,
537
613
  passing: head.passing,
614
+ lengths: head.lengths,
538
615
  folder: relative(state.evidence, folder)
539
616
  };
540
617
  if (diff !== null) Object.assign(result, { commits: {
541
618
  baseSha: diff.baseSha,
542
619
  headSha: diff.headSha
543
620
  } }, gateFields(workspace, check, diff, folder, head));
621
+ result.ms = elapsed();
544
622
  writeFileSync(join(folder, "result.json"), `${JSON.stringify(result, null, 2)}\n`);
545
623
  return result;
546
624
  }
625
+ function lengthOf(lengths, rule) {
626
+ return lengths !== void 0 && Object.hasOwn(lengths, rule) ? lengths[rule] : void 0;
627
+ }
628
+ function knownFindingsOfBase(result) {
629
+ const { base } = result;
630
+ if (!base || base.exitCode !== 0) return false;
631
+ const atHead = new Set(result.violated);
632
+ const fixed = new Set(result.fixed ?? []);
633
+ return base.violated.every((rule) => atHead.has(rule) || fixed.has(rule)) && result.violated.every((rule) => {
634
+ const length = lengthOf(result.lengths, rule);
635
+ return base.violated.includes(rule) && length !== void 0 && length === lengthOf(base.lengths, rule);
636
+ });
637
+ }
547
638
  /**
548
639
  * How a formal check's result weighs on a verdict whose diff it covers. A
549
640
  * non-zero exit (a tool error, or a check that no longer matches its record)
550
- * fails. Recorded findings fail only when the diff changed the covered code's
551
- * behaviour; otherwise they are reported as known. A rule the base broke and
552
- * HEAD reports passing is reported as fixed; one HEAD does not report at all
553
- * fails.
641
+ * fails, so every violated rule of a result that reaches the rest of the gate
642
+ * is a recorded finding. A rule the base broke that HEAD does not report at
643
+ * all fails. Recorded findings are known when the diff left the covered
644
+ * code's behaviour unchanged. When it changed them, they are known only when
645
+ * the base run exited 0 and broke every one of them, each with the same
646
+ * counterexample length at HEAD as on the base, and every other rule the
647
+ * base broke is fixed at HEAD; a new rule, a changed length, or a length
648
+ * either run did not report fails. A rule the base broke and HEAD reports
649
+ * passing is reported as fixed.
554
650
  */
555
651
  function formalGate(result) {
556
652
  if (result.exitCode !== 0) return {
@@ -575,6 +671,10 @@ function formalGate(result) {
575
671
  fails: false,
576
672
  outcome: `covered behaviour changed (${how}), no violated rule${fixed}`
577
673
  };
674
+ if (knownFindingsOfBase(result)) return {
675
+ fails: false,
676
+ outcome: `covered behaviour changed (${how}), same known findings as base: ${result.violated.join(", ")}${fixed}`
677
+ };
578
678
  return {
579
679
  fails: true,
580
680
  outcome: `covered behaviour changed (${how}), violated ${result.violated.join(", ")}${fixed}`
@@ -742,20 +842,30 @@ function startServices(workspace, state, prefix) {
742
842
  definition.image
743
843
  ];
744
844
  const folder = join(state.evidence, "services", service);
745
- const started = docker(args);
746
- record(join(folder, "01-run"), args, started);
747
- if (started.status !== 0) throw new Error(`docker ${args.join(" ")} failed: ${started.stderr}`);
748
- const container = {
749
- service,
750
- name,
751
- host: "127.0.0.1",
752
- port: 0
753
- };
754
- state.containers.push(container);
755
- saveRun(state);
756
- container.port = publishedPort(name, definition.port);
757
- saveRun(state);
758
- waitReady(name, definition.ready, join(folder, "02-ready"));
845
+ const elapsed = stopwatch();
846
+ let failed = true;
847
+ try {
848
+ const started = docker(args);
849
+ record(join(folder, "01-run"), args, started);
850
+ if (started.status !== 0) throw new Error(`docker ${args.join(" ")} failed: ${started.stderr}`);
851
+ const container = {
852
+ service,
853
+ name,
854
+ host: "127.0.0.1",
855
+ port: 0
856
+ };
857
+ state.containers.push(container);
858
+ saveRun(state);
859
+ container.port = publishedPort(name, definition.port);
860
+ saveRun(state);
861
+ waitReady(name, definition.ready, join(folder, "02-ready"));
862
+ failed = false;
863
+ } finally {
864
+ state.timings.push({
865
+ phase: `service ${service} (start and ready)${failed ? " (failed)" : ""}`,
866
+ ms: elapsed()
867
+ });
868
+ }
759
869
  }
760
870
  }
761
871
  /** Runs a service's readiness command once in its container, recorded in `folder`: the stderr when it fails, `null` when it passes. */
@@ -1494,253 +1604,6 @@ function minorRule(input) {
1494
1604
  };
1495
1605
  }
1496
1606
  //#endregion
1497
- //#region src/verify/interface.ts
1498
- const CALL_ARGS = ["verify-argument", 7];
1499
- function runtimeMembers(value) {
1500
- if (!Array.isArray(value)) return [];
1501
- return value.filter(isObject).map((member) => ({
1502
- path: String(member.path),
1503
- kind: String(member.kind)
1504
- }));
1505
- }
1506
- function splitPath(path) {
1507
- const colon = path.indexOf(":");
1508
- return {
1509
- entry: path.slice(0, colon),
1510
- keys: path.slice(colon + 1).split(".")
1511
- };
1512
- }
1513
- function writeJson(folder, file, value) {
1514
- writeFileSync(join(folder, file), `${JSON.stringify(value, null, 2)}\n`);
1515
- }
1516
- /** Links the repository's node_modules under an extracted package, so its declarations resolve their imports. */
1517
- function linkDependencies(packageFolder, repo) {
1518
- symlinkSync(join(repo, "node_modules"), join(packageFolder, "node_modules"), "dir");
1519
- }
1520
- function readSurface(context, folder, label) {
1521
- const step = context.step(`${label} declared surface`);
1522
- try {
1523
- const surface = declaredSurface(folder);
1524
- writeJson(step, "surface.json", Object.fromEntries(surface));
1525
- context.expect(step, [{
1526
- name: `${label} declarations read`,
1527
- pass: true,
1528
- detail: `${surface.size} functions`
1529
- }]);
1530
- return surface;
1531
- } catch (error) {
1532
- const detail = error instanceof Error ? error.message : String(error);
1533
- context.expect(step, [{
1534
- name: `${label} declarations read`,
1535
- pass: false,
1536
- detail
1537
- }], { critical: true });
1538
- return;
1539
- }
1540
- }
1541
- function logged(context, project, path, args) {
1542
- const calls = context.stubCalls(project);
1543
- const seen = calls.some((call) => call.path === path && JSON.stringify(call.args) === JSON.stringify(args));
1544
- return {
1545
- name: `the stub provider received ${path}(${JSON.stringify(args).slice(1, -1)})`,
1546
- pass: seen,
1547
- detail: JSON.stringify(calls.filter((call) => call.path.startsWith(path)))
1548
- };
1549
- }
1550
- async function callProxy(context, app, path) {
1551
- const { entry, keys } = splitPath(path);
1552
- const result = await context.call(`call ${path}`, app, {
1553
- entry,
1554
- path: keys,
1555
- args: CALL_ARGS
1556
- });
1557
- context.expect(result.folder, [
1558
- {
1559
- name: `${path} resolved through core`,
1560
- pass: result.ok,
1561
- detail: JSON.stringify(result.value ?? result.error)
1562
- },
1563
- equal(`${path} returned the stub provider's answer`, result.value, {
1564
- stub: path,
1565
- args: CALL_ARGS
1566
- }),
1567
- logged(context, app.project, path, CALL_ARGS)
1568
- ]);
1569
- }
1570
- async function callRegistering(context, app, path) {
1571
- const { entry, keys } = splitPath(path);
1572
- const result = await context.driver(`register ${path}`, app, "/registering", {
1573
- entry,
1574
- path: keys
1575
- });
1576
- context.expect(result.folder, [
1577
- {
1578
- name: `${path} register and unregister resolved through core`,
1579
- pass: result.ok,
1580
- detail: JSON.stringify(result.value ?? result.error)
1581
- },
1582
- logged(context, app.project, `${path}.register`, ["verify-registration"]),
1583
- logged(context, app.project, `${path}.unregister`, ["verify-registration"])
1584
- ]);
1585
- }
1586
- async function callEvent(context, app, path) {
1587
- const { entry, keys } = splitPath(path);
1588
- const result = await context.driver(`emit ${path}`, app, "/event", {
1589
- entry,
1590
- path: keys,
1591
- args: CALL_ARGS
1592
- });
1593
- context.expect(result.folder, [equal(`a handler registered on ${path} received the emitted arguments`, result.value, CALL_ARGS)]);
1594
- }
1595
- async function callHook(context, app, path, expected) {
1596
- const result = await context.driver(`call ${path}`, app, "/hook", { path });
1597
- context.expect(result.folder, [{
1598
- name: `${path} resolved through core`,
1599
- pass: result.ok,
1600
- detail: JSON.stringify(result.value ?? result.error)
1601
- }, equal(`${path} returned the value verify.config.ts expects`, result.value, expected)]);
1602
- }
1603
- function unreachable(context, path, detail) {
1604
- context.expect(context.step(`no call for ${path}`), [{
1605
- name: `${path} is called through core`,
1606
- pass: false,
1607
- detail
1608
- }]);
1609
- }
1610
- async function callMember(context, app, path, members) {
1611
- const hooks = context.workspace.config.interface ?? {};
1612
- const providerSide = hooks.providerSide?.[path];
1613
- const hook = hooks.calls?.[path];
1614
- const kind = members.find((member) => member.path === path)?.kind;
1615
- if (providerSide !== void 0) {
1616
- const step = context.step(`provider side ${path}`);
1617
- context.expect(step, [{
1618
- name: `${path} is called by providers only`,
1619
- pass: providerSide.trim() !== "",
1620
- detail: providerSide
1621
- }]);
1622
- } else if (hook !== void 0) await callHook(context, app, path, hook.expect);
1623
- else if (kind === void 0) unreachable(context, path, "declared in the .d.ts files but the loaded package does not export it");
1624
- else if (kind === "async") await callProxy(context, app, path);
1625
- else if (kind === "registering") await callRegistering(context, app, path);
1626
- else if (kind === "event") await callEvent(context, app, path);
1627
- 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`);
1628
- }
1629
- /** Loads the packed interface with a stub provider and a consumer, and calls every declared function through core. */
1630
- const everyFunction = {
1631
- title: "every declared function answers through core from a stub provider",
1632
- entryPoint: "a consumer module calling the packed interface in `ajs project dev`",
1633
- async run(context) {
1634
- const declared = readSurface(context, context.state.pack, "head");
1635
- const project = context.fixture();
1636
- const app = await context.dev("ajs project dev", project);
1637
- const surface = await context.driver("runtime surface", app, "/surface", {});
1638
- const members = runtimeMembers(surface.value);
1639
- context.expect(surface.folder, [{
1640
- name: "the consumer walked the loaded interface",
1641
- pass: surface.ok && members.length > 0,
1642
- detail: `${members.length} members`
1643
- }]);
1644
- for (const path of declared?.keys() ?? []) await callMember(context, app, path, members);
1645
- const stopped = await context.stop("SIGINT", app);
1646
- context.expect(stopped.folder, [interrupted(stopped)]);
1647
- }
1648
- };
1649
- function publishedVersion(output) {
1650
- const text = output.trim();
1651
- return text === "" ? null : text.replace(/^"|"$/g, "");
1652
- }
1653
- async function fetchPublished(context, name, version) {
1654
- const folder = join(CACHE_DIR, "published", name.replace("/", "+"), version);
1655
- mkdirSync(folder, { recursive: true });
1656
- const packed = await context.command(`npm pack ${name}@${version}`, "npm", [
1657
- "pack",
1658
- `${name}@${version}`,
1659
- "--pack-destination",
1660
- folder
1661
- ], { env: {
1662
- npm_config_offline: "false",
1663
- npm_config_prefer_offline: "false"
1664
- } });
1665
- const tarball = readdirSync(folder).find((file) => file.endsWith(".tgz"));
1666
- if (packed.exitCode !== 0 || tarball === void 0) {
1667
- context.expect(packed.folder, [exitIs(packed, 0)], { critical: true });
1668
- return;
1669
- }
1670
- const extracted = join(context.work, "published");
1671
- mkdirSync(extracted, { recursive: true });
1672
- const untar = await context.command("extract published", "tar", [
1673
- "-xzf",
1674
- join(folder, tarball),
1675
- "-C",
1676
- extracted
1677
- ]);
1678
- context.expect(untar.folder, [exitIs(untar, 0)], { critical: true });
1679
- const root = join(extracted, "package");
1680
- linkDependencies(root, context.repo);
1681
- return root;
1682
- }
1683
- function changeTitles(context) {
1684
- if (context.state.title !== "") return [context.state.title];
1685
- const base = git(context.repo, [
1686
- "merge-base",
1687
- context.state.baseRef,
1688
- "HEAD"
1689
- ]);
1690
- return git(context.repo, [
1691
- "log",
1692
- "--format=%s",
1693
- `${base}..HEAD`
1694
- ]).split("\n").filter(Boolean);
1695
- }
1696
- /** The journeys the interface kind ships, by id. */
1697
- const INTERFACE_JOURNEYS = {
1698
- "every-function": everyFunction,
1699
- "minor-bump": {
1700
- title: "an added, changed or removed function releases as a new minor",
1701
- entryPoint: "the published package against the packed head, as a module author upgrading sees it",
1702
- async run(context) {
1703
- const name = String(context.workspace.manifest.name);
1704
- const headVersion = String(context.workspace.manifest.version);
1705
- const view = await context.command(`npm view ${name}`, "npm", [
1706
- "view",
1707
- name,
1708
- "version",
1709
- "--json"
1710
- ], { env: {
1711
- npm_config_offline: "false",
1712
- npm_config_prefer_offline: "false"
1713
- } });
1714
- const missing = view.exitCode !== 0 && /E404/.test(view.stderr);
1715
- if (view.exitCode !== 0 && !missing) context.notVerified(`npm view ${name} failed: ${view.stderr.trim().slice(-200)}`);
1716
- const published = missing ? null : publishedVersion(view.stdout);
1717
- const head = readSurface(context, context.state.pack, "head");
1718
- const root = published === null ? void 0 : await fetchPublished(context, name, published);
1719
- const diff = diffSurface((root === void 0 ? void 0 : readSurface(context, root, `published ${published}`)) ?? /* @__PURE__ */ new Map(), head ?? /* @__PURE__ */ new Map());
1720
- const titles = changeTitles(context);
1721
- const verdict = minorRule({
1722
- published,
1723
- headVersion,
1724
- titles,
1725
- diff
1726
- });
1727
- const step = context.step("minor rule");
1728
- writeJson(step, "minor-rule.json", {
1729
- published,
1730
- headVersion,
1731
- titles,
1732
- ...diff,
1733
- ...verdict
1734
- });
1735
- context.expect(step, [{
1736
- name: verdict.required === "minor" ? `releases at least the next minor of ${published}` : "no function changed against the published version",
1737
- pass: verdict.ok,
1738
- detail: verdict.reason
1739
- }]);
1740
- }
1741
- }
1742
- };
1743
- //#endregion
1744
1607
  //#region src/verify/record.ts
1745
1608
  const DEFAULT_TIMEOUT_MS = 6e5;
1746
1609
  /** Quotes an argument the way a shell user would type it. */
@@ -1892,18 +1755,38 @@ function readOutput(folder) {
1892
1755
  stderr: readFileSync(join(folder, "stderr.txt"), "utf8")
1893
1756
  };
1894
1757
  }
1895
- /** Asks the kernel for a free TCP port on the loopback interface. */
1896
- function freePort() {
1897
- return new Promise((resolve, reject) => {
1758
+ /** 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. */
1759
+ const PORT_RANGE = {
1760
+ low: 1e4,
1761
+ high: 2e4
1762
+ };
1763
+ const PORT_ATTEMPTS = 50;
1764
+ function bindable(port) {
1765
+ return new Promise((resolve) => {
1898
1766
  const server = createServer();
1899
- server.once("error", reject);
1900
- server.listen(0, "127.0.0.1", () => {
1767
+ server.once("error", () => resolve(null));
1768
+ server.listen(port, "127.0.0.1", () => {
1901
1769
  const address = server.address();
1902
- const port = address !== null && address instanceof Object ? address.port : 0;
1903
- server.close(() => resolve(port));
1770
+ const bound = address !== null && address instanceof Object ? address.port : null;
1771
+ server.close(() => resolve(bound));
1904
1772
  });
1905
1773
  });
1906
1774
  }
1775
+ /**
1776
+ * A free TCP port on the loopback interface for a process the harness starts
1777
+ * next. It tries random ports below the kernel's ephemeral range first, where
1778
+ * no outgoing connection on a busy host takes it between this check and the
1779
+ * app's own bind, and falls back to a port the kernel picks.
1780
+ */
1781
+ async function freePort() {
1782
+ for (let attempt = 0; attempt < PORT_ATTEMPTS; attempt++) {
1783
+ const bound = await bindable(PORT_RANGE.low + Math.floor(Math.random() * (PORT_RANGE.high - PORT_RANGE.low)));
1784
+ if (bound !== null) return bound;
1785
+ }
1786
+ const picked = await bindable(0);
1787
+ if (picked === null) throw new Error("no free loopback port");
1788
+ return picked;
1789
+ }
1907
1790
  function reason(error) {
1908
1791
  return error.cause instanceof Error ? error.cause.message : error.message;
1909
1792
  }
@@ -1974,9 +1857,375 @@ function recordTree(folder, root) {
1974
1857
  } catch {
1975
1858
  lines = [];
1976
1859
  }
1977
- writeFileSync(join(folder, "tree.txt"), `${root}\n${lines.join("\n")}\n`);
1978
- return lines;
1979
- }
1860
+ writeFileSync(join(folder, "tree.txt"), `${root}\n${lines.join("\n")}\n`);
1861
+ return lines;
1862
+ }
1863
+ //#endregion
1864
+ //#region src/verify/interface.ts
1865
+ const CALL_ARGS = ["verify-argument", 7];
1866
+ function runtimeMembers(value) {
1867
+ if (!Array.isArray(value)) return [];
1868
+ return value.filter(isObject).map((member) => ({
1869
+ path: String(member.path),
1870
+ kind: String(member.kind)
1871
+ }));
1872
+ }
1873
+ function splitPath(path) {
1874
+ const colon = path.indexOf(":");
1875
+ return {
1876
+ entry: path.slice(0, colon),
1877
+ keys: path.slice(colon + 1).split(".")
1878
+ };
1879
+ }
1880
+ function writeJson(folder, file, value) {
1881
+ writeFileSync(join(folder, file), `${JSON.stringify(value, null, 2)}\n`);
1882
+ }
1883
+ /** Links the repository's node_modules under an extracted package, so its declarations resolve their imports. */
1884
+ function linkDependencies(packageFolder, repo) {
1885
+ symlinkSync(join(repo, "node_modules"), join(packageFolder, "node_modules"), "dir");
1886
+ }
1887
+ function readSurface(context, folder, label) {
1888
+ const step = context.step(`${label} declared surface`);
1889
+ try {
1890
+ const surface = declaredSurface(folder);
1891
+ writeJson(step, "surface.json", Object.fromEntries(surface));
1892
+ context.expect(step, [{
1893
+ name: `${label} declarations read`,
1894
+ pass: true,
1895
+ detail: `${surface.size} functions`
1896
+ }]);
1897
+ return surface;
1898
+ } catch (error) {
1899
+ const detail = error instanceof Error ? error.message : String(error);
1900
+ context.expect(step, [{
1901
+ name: `${label} declarations read`,
1902
+ pass: false,
1903
+ detail
1904
+ }], { critical: true });
1905
+ return;
1906
+ }
1907
+ }
1908
+ function logged(context, project, path, args) {
1909
+ const calls = context.stubCalls(project);
1910
+ const seen = calls.some((call) => call.path === path && JSON.stringify(call.args) === JSON.stringify(args));
1911
+ return {
1912
+ name: `the stub provider received ${path}(${JSON.stringify(args).slice(1, -1)})`,
1913
+ pass: seen,
1914
+ detail: JSON.stringify(calls.filter((call) => call.path.startsWith(path)))
1915
+ };
1916
+ }
1917
+ async function callProxy(context, app, path) {
1918
+ const { entry, keys } = splitPath(path);
1919
+ const result = await context.call(`call ${path}`, app, {
1920
+ entry,
1921
+ path: keys,
1922
+ args: CALL_ARGS
1923
+ });
1924
+ context.expect(result.folder, [
1925
+ {
1926
+ name: `${path} resolved through core`,
1927
+ pass: result.ok,
1928
+ detail: JSON.stringify(result.value ?? result.error)
1929
+ },
1930
+ equal(`${path} returned the stub provider's answer`, result.value, {
1931
+ stub: path,
1932
+ args: CALL_ARGS
1933
+ }),
1934
+ logged(context, app.project, path, CALL_ARGS)
1935
+ ]);
1936
+ }
1937
+ async function callRegistering(context, app, path) {
1938
+ const { entry, keys } = splitPath(path);
1939
+ const result = await context.driver(`register ${path}`, app, "/registering", {
1940
+ entry,
1941
+ path: keys
1942
+ });
1943
+ context.expect(result.folder, [
1944
+ {
1945
+ name: `${path} register and unregister resolved through core`,
1946
+ pass: result.ok,
1947
+ detail: JSON.stringify(result.value ?? result.error)
1948
+ },
1949
+ logged(context, app.project, `${path}.register`, ["verify-registration"]),
1950
+ logged(context, app.project, `${path}.unregister`, ["verify-registration"])
1951
+ ]);
1952
+ }
1953
+ async function callEvent(context, app, path) {
1954
+ const { entry, keys } = splitPath(path);
1955
+ const result = await context.driver(`emit ${path}`, app, "/event", {
1956
+ entry,
1957
+ path: keys,
1958
+ args: CALL_ARGS
1959
+ });
1960
+ context.expect(result.folder, [equal(`a handler registered on ${path} received the emitted arguments`, result.value, CALL_ARGS)]);
1961
+ }
1962
+ async function callHook(context, app, path, expected) {
1963
+ const result = await context.driver(`call ${path}`, app, "/hook", { path });
1964
+ context.expect(result.folder, [{
1965
+ name: `${path} resolved through core`,
1966
+ pass: result.ok,
1967
+ detail: JSON.stringify(result.value ?? result.error)
1968
+ }, equal(`${path} returned the value verify.config.ts expects`, result.value, expected)]);
1969
+ }
1970
+ function unreachable(context, path, detail) {
1971
+ context.expect(context.step(`no call for ${path}`), [{
1972
+ name: `${path} is called through core`,
1973
+ pass: false,
1974
+ detail
1975
+ }]);
1976
+ }
1977
+ async function callMember(context, app, path, members) {
1978
+ const hooks = context.workspace.config.interface ?? {};
1979
+ const providerSide = hooks.providerSide?.[path];
1980
+ const hook = hooks.calls?.[path];
1981
+ const kind = members.find((member) => member.path === path)?.kind;
1982
+ if (providerSide !== void 0) {
1983
+ const step = context.step(`provider side ${path}`);
1984
+ context.expect(step, [{
1985
+ name: `${path} is called by providers only`,
1986
+ pass: providerSide.trim() !== "",
1987
+ detail: providerSide
1988
+ }]);
1989
+ } else if (hook !== void 0) await callHook(context, app, path, hook.expect);
1990
+ else if (kind === void 0) unreachable(context, path, "declared in the .d.ts files but the loaded package does not export it");
1991
+ else if (kind === "async") await callProxy(context, app, path);
1992
+ else if (kind === "registering") await callRegistering(context, app, path);
1993
+ else if (kind === "event") await callEvent(context, app, path);
1994
+ 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`);
1995
+ }
1996
+ /** Loads the packed interface with a stub provider and a consumer, and calls every declared function through core. */
1997
+ const everyFunction = {
1998
+ title: "every declared function answers through core from a stub provider",
1999
+ entryPoint: "a consumer module calling the packed interface in `ajs project dev`",
2000
+ async run(context) {
2001
+ const declared = readSurface(context, context.state.pack, "head");
2002
+ const project = context.fixture();
2003
+ const app = await context.dev("ajs project dev", project);
2004
+ const surface = await context.driver("runtime surface", app, "/surface", {});
2005
+ const members = runtimeMembers(surface.value);
2006
+ context.expect(surface.folder, [{
2007
+ name: "the consumer walked the loaded interface",
2008
+ pass: surface.ok && members.length > 0,
2009
+ detail: `${members.length} members`
2010
+ }]);
2011
+ for (const path of declared?.keys() ?? []) await callMember(context, app, path, members);
2012
+ const stopped = await context.stop("SIGINT", app);
2013
+ context.expect(stopped.folder, [interrupted(stopped)]);
2014
+ }
2015
+ };
2016
+ /** Reads the latest version and its sha512 integrity from `npm view <name> version dist.integrity --json`. */
2017
+ function publishedView(output) {
2018
+ const text = output.trim();
2019
+ if (text === "") return {
2020
+ version: null,
2021
+ integrity: null
2022
+ };
2023
+ const parsed = parseJson(text);
2024
+ if (isString(parsed)) return {
2025
+ version: parsed,
2026
+ integrity: null
2027
+ };
2028
+ if (!isObject(parsed)) return {
2029
+ version: null,
2030
+ integrity: null
2031
+ };
2032
+ return {
2033
+ version: optStr(parsed, "version") ?? null,
2034
+ integrity: sha512Token(optStr(parsed, "dist.integrity"))
2035
+ };
2036
+ }
2037
+ /** 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. */
2038
+ function sha512Token(integrity) {
2039
+ return (integrity ?? "").split(/\s+/).find((token) => token.startsWith("sha512-")) ?? null;
2040
+ }
2041
+ const ONLINE = {
2042
+ npm_config_offline: "false",
2043
+ npm_config_prefer_offline: "false"
2044
+ };
2045
+ function tarballsIn(folder) {
2046
+ if (!existsSync(folder)) return [];
2047
+ return readdirSync(folder).filter((entry) => entry.endsWith(".tgz")).map((entry) => join(folder, entry));
2048
+ }
2049
+ /** The registry's integrity string of a file: `sha512-` and the base64 of its SHA-512. */
2050
+ function integrityOf(file) {
2051
+ return `sha512-${createHash("sha512").update(readFileSync(file)).digest("base64")}`;
2052
+ }
2053
+ /** Packs into a staging folder next to the cache, so the cache only ever receives a complete tarball that matches the published integrity. */
2054
+ async function packPublished(context, published, folder) {
2055
+ const { name, version, integrity } = published;
2056
+ mkdirSync(dirname(folder), { recursive: true });
2057
+ const staging = mkdtempSync(`${folder}.pack-`);
2058
+ const release = onInterrupt(() => rmSync(staging, {
2059
+ recursive: true,
2060
+ force: true
2061
+ }));
2062
+ try {
2063
+ const packed = await context.command(`npm pack ${name}@${version}`, "npm", [
2064
+ "pack",
2065
+ `${name}@${version}`,
2066
+ "--pack-destination",
2067
+ staging
2068
+ ], { env: ONLINE });
2069
+ const [staged] = tarballsIn(staging);
2070
+ if (packed.exitCode !== 0 || staged === void 0) {
2071
+ context.expect(packed.folder, [exitIs(packed, 0)], { critical: true });
2072
+ return;
2073
+ }
2074
+ if (integrity !== null) {
2075
+ const actual = integrityOf(staged);
2076
+ context.expect(context.step(`check packed ${name}@${version}`), [{
2077
+ name: `the packed tarball of ${name}@${version} has the integrity the registry publishes`,
2078
+ pass: actual === integrity,
2079
+ detail: `packed ${actual}, published ${integrity}`
2080
+ }], { critical: true });
2081
+ }
2082
+ if (integrity === null) {
2083
+ const uncached = join(context.work, basename(staged));
2084
+ copyFileSync(staged, uncached);
2085
+ return uncached;
2086
+ }
2087
+ mkdirSync(folder, { recursive: true });
2088
+ const cached = join(folder, basename(staged));
2089
+ renameSync(staged, cached);
2090
+ return cached;
2091
+ } finally {
2092
+ release();
2093
+ rmSync(staging, {
2094
+ recursive: true,
2095
+ force: true
2096
+ });
2097
+ }
2098
+ }
2099
+ async function extractPublished(context, tarball) {
2100
+ const extracted = join(context.work, "published");
2101
+ rmSync(extracted, {
2102
+ recursive: true,
2103
+ force: true
2104
+ });
2105
+ mkdirSync(extracted, { recursive: true });
2106
+ const untar = await context.command("extract published", "tar", [
2107
+ "-xzf",
2108
+ tarball,
2109
+ "-C",
2110
+ extracted
2111
+ ]);
2112
+ context.expect(untar.folder, [exitIs(untar, 0)], { critical: true });
2113
+ const root = join(extracted, "package");
2114
+ linkDependencies(root, context.repo);
2115
+ return root;
2116
+ }
2117
+ /**
2118
+ * A private copy, under the journey's work folder, of the cached tarball of a
2119
+ * version, only when it is the folder's single tarball and the copy's
2120
+ * integrity is the published one. Hashing and extracting the same copy keeps
2121
+ * another run that replaces the cached file in between from changing what
2122
+ * this journey reads.
2123
+ */
2124
+ function trustedTarball(files, integrity, work) {
2125
+ const [only] = files;
2126
+ if (files.length !== 1 || integrity === null) return void 0;
2127
+ const copy = join(work, basename(only));
2128
+ try {
2129
+ copyFileSync(only, copy);
2130
+ } catch {
2131
+ return;
2132
+ }
2133
+ return integrityOf(copy) === integrity ? copy : void 0;
2134
+ }
2135
+ /** Extracts a published version from the cache when its one tarball has the published integrity, and packs it again otherwise. */
2136
+ async function fetchPublished(context, name, published) {
2137
+ const { version, integrity } = published;
2138
+ const folder = join(CACHE_DIR, "published", name.replace("/", "+"), version);
2139
+ const files = tarballsIn(folder);
2140
+ mkdirSync(context.work, { recursive: true });
2141
+ const trusted = trustedTarball(files, integrity, context.work);
2142
+ if (trusted !== void 0) {
2143
+ context.expect(context.step(`reuse cached ${name}@${version}`), [{
2144
+ name: `the cached tarball of ${name}@${version} has the published integrity, so it is reused and no npm pack ran`,
2145
+ pass: true,
2146
+ detail: `${files[0]}: ${integrity}`
2147
+ }]);
2148
+ return extractPublished(context, trusted);
2149
+ }
2150
+ if (files.length > 0) {
2151
+ for (const file of files) rmSync(file, { force: true });
2152
+ context.expect(context.step(`discard cached ${name}@${version}`), [{
2153
+ 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`,
2154
+ pass: tarballsIn(folder).length === 0,
2155
+ detail: `${files.join(", ")} against ${integrity ?? "no published integrity"}`
2156
+ }]);
2157
+ }
2158
+ const packed = await packPublished(context, {
2159
+ name,
2160
+ version,
2161
+ integrity
2162
+ }, folder);
2163
+ return packed === void 0 ? void 0 : extractPublished(context, packed);
2164
+ }
2165
+ function changeTitles(context) {
2166
+ if (context.state.title !== "") return [context.state.title];
2167
+ const base = git(context.repo, [
2168
+ "merge-base",
2169
+ context.state.baseRef,
2170
+ "HEAD"
2171
+ ]);
2172
+ return git(context.repo, [
2173
+ "log",
2174
+ "--format=%s",
2175
+ `${base}..HEAD`
2176
+ ]).split("\n").filter(Boolean);
2177
+ }
2178
+ /** The journeys the interface kind ships, by id. */
2179
+ const INTERFACE_JOURNEYS = {
2180
+ "every-function": everyFunction,
2181
+ "minor-bump": {
2182
+ title: "an added, changed or removed function releases as a new minor",
2183
+ entryPoint: "the published package against the packed head, as a module author upgrading sees it",
2184
+ async run(context) {
2185
+ const name = String(context.workspace.manifest.name);
2186
+ const headVersion = String(context.workspace.manifest.version);
2187
+ const view = await context.command(`npm view ${name}`, "npm", [
2188
+ "view",
2189
+ name,
2190
+ "version",
2191
+ "dist.integrity",
2192
+ "--json"
2193
+ ], { env: ONLINE });
2194
+ const missing = view.exitCode !== 0 && /E404/.test(view.stderr);
2195
+ if (view.exitCode !== 0 && !missing) context.notVerified(`npm view ${name} failed: ${view.stderr.trim().slice(-200)}`);
2196
+ const { version: published, integrity } = missing ? {
2197
+ version: null,
2198
+ integrity: null
2199
+ } : publishedView(view.stdout);
2200
+ const head = readSurface(context, context.state.pack, "head");
2201
+ const root = published === null ? void 0 : await fetchPublished(context, name, {
2202
+ version: published,
2203
+ integrity
2204
+ });
2205
+ const diff = diffSurface((root === void 0 ? void 0 : readSurface(context, root, `published ${published}`)) ?? /* @__PURE__ */ new Map(), head ?? /* @__PURE__ */ new Map());
2206
+ const titles = changeTitles(context);
2207
+ const verdict = minorRule({
2208
+ published,
2209
+ headVersion,
2210
+ titles,
2211
+ diff
2212
+ });
2213
+ const step = context.step("minor rule");
2214
+ writeJson(step, "minor-rule.json", {
2215
+ published,
2216
+ headVersion,
2217
+ titles,
2218
+ ...diff,
2219
+ ...verdict
2220
+ });
2221
+ context.expect(step, [{
2222
+ name: verdict.required === "minor" ? `releases at least the next minor of ${published}` : "no function changed against the published version",
2223
+ pass: verdict.ok,
2224
+ detail: verdict.reason
2225
+ }]);
2226
+ }
2227
+ }
2228
+ };
1980
2229
  //#endregion
1981
2230
  //#region src/verify/sources.ts
1982
2231
  const IDENTITY = [
@@ -2105,16 +2354,22 @@ function setupCommands(workspace) {
2105
2354
  async function runSetup(workspace, state) {
2106
2355
  const commands = setupCommands(workspace);
2107
2356
  for (const [index, [program, ...args]] of commands.entries()) {
2108
- const folder = join(state.evidence, "setup", `${String(index + 1).padStart(2, "0")}-${program}`);
2357
+ const name = `${String(index + 1).padStart(2, "0")}-${program}`;
2358
+ const folder = join(state.evidence, "setup", name);
2359
+ const elapsed = stopwatch();
2109
2360
  const result = await runRecorded(folder, {
2110
2361
  program,
2111
2362
  args,
2112
2363
  cwd: workspace.root,
2113
2364
  env: {
2114
- ...process.env,
2365
+ ...operatorEnv(),
2115
2366
  ...workspace.config.env
2116
2367
  }
2117
2368
  });
2369
+ state.timings.push({
2370
+ phase: `setup/${name}${result.exitCode === 0 ? "" : " (failed)"}`,
2371
+ ms: elapsed()
2372
+ });
2118
2373
  if (result.exitCode !== 0) throw new Error(`setup \`${result.command}\` exited ${result.exitCode}; see ${folder}`);
2119
2374
  }
2120
2375
  }
@@ -2175,7 +2430,7 @@ function recorded(dir) {
2175
2430
  };
2176
2431
  }
2177
2432
  }
2178
- function entries(folder) {
2433
+ function entries$1(folder) {
2179
2434
  try {
2180
2435
  return readdirSync(folder, { withFileTypes: true }).filter((entry) => entry.isDirectory()).map((entry) => join(folder, entry.name));
2181
2436
  } catch {
@@ -2202,7 +2457,7 @@ function pruneRun(dir, now) {
2202
2457
  */
2203
2458
  function pruneRuns() {
2204
2459
  const now = Date.now();
2205
- for (const repo of entries(RUNS_DIR)) for (const dir of entries(repo)) pruneRun(dir, now);
2460
+ for (const repo of entries$1(RUNS_DIR)) for (const dir of entries$1(repo)) pruneRun(dir, now);
2206
2461
  }
2207
2462
  /**
2208
2463
  * Creates an isolated run: runs the setup (the build by default), then
@@ -2211,17 +2466,26 @@ function pruneRuns() {
2211
2466
  * kind's backing `services` start in Docker on free ports.
2212
2467
  */
2213
2468
  async function createRun(workspace, baseRef, title, all) {
2469
+ const pruned = stopwatch();
2214
2470
  pruneRuns();
2471
+ const pruneMs = pruned();
2215
2472
  const state = allocateRun(workspace, baseRef, title, all);
2473
+ state.timings.push({
2474
+ phase: "prune old runs",
2475
+ ms: pruneMs
2476
+ });
2216
2477
  saveRun(state);
2217
- await runSetup(workspace, state);
2218
- if (workspace.kind === "interface") state.pack = await packInterface(workspace, state);
2219
- startServices(workspace, state, containerPrefix());
2220
- if (workspace.kind === "template") {
2221
- state.manifestUrl = seedSources(workspace, state);
2222
- state.templateName = templateName(workspace);
2478
+ try {
2479
+ await runSetup(workspace, state);
2480
+ if (workspace.kind === "interface") state.pack = await timed(state, "pack interface", () => packInterface(workspace, state));
2481
+ startServices(workspace, state, containerPrefix());
2482
+ if (workspace.kind === "template") await timed(state, "seed template sources", () => {
2483
+ state.manifestUrl = seedSources(workspace, state);
2484
+ state.templateName = templateName(workspace);
2485
+ });
2486
+ } finally {
2487
+ saveRun(state);
2223
2488
  }
2224
- saveRun(state);
2225
2489
  return state;
2226
2490
  }
2227
2491
  function alive(pid) {
@@ -2530,12 +2794,489 @@ const BUILTIN_JOURNEYS = {
2530
2794
  }
2531
2795
  };
2532
2796
  //#endregion
2797
+ //#region src/verify/app-fault.ts
2798
+ /** The signals a process outside the run sends to end an app. Any other signal, such as SIGABRT or SIGSEGV, is the product crashing. */
2799
+ const OUTSIDE_KILLS = /* @__PURE__ */ new Set([
2800
+ "SIGKILL",
2801
+ "SIGTERM",
2802
+ "SIGHUP",
2803
+ "SIGINT"
2804
+ ]);
2805
+ /**
2806
+ * Why one of the apps a journey started points away from the product, or
2807
+ * `null`: an app killed by SIGKILL, SIGTERM, SIGHUP or SIGINT that the harness
2808
+ * did not send, or an app that could not bind the port the harness gave it.
2809
+ */
2810
+ function appFault(started) {
2811
+ for (const { app, sent, exit } of started) {
2812
+ const label = `${app.name} (pid ${app.pid})`;
2813
+ if (exit?.signal && OUTSIDE_KILLS.has(exit.signal) && !sent.includes(exit.signal)) return `${label} was killed by ${exit.signal}, a signal the harness did not send`;
2814
+ const output = readOutput(app.folder);
2815
+ const port = new RegExp(`(?<![0-9])${app.port}(?![0-9])`);
2816
+ const taken = `${output.stdout}\n${output.stderr}`.split("\n").find((line) => line.includes("EADDRINUSE") && port.test(line));
2817
+ if (taken !== void 0) return `${label} could not bind port ${app.port}, which another process holds: ${taken.trim().slice(0, 300)}`;
2818
+ }
2819
+ return null;
2820
+ }
2821
+ //#endregion
2822
+ //#region src/verify/caches.ts
2823
+ /** Where `ajs` installs the modules of a project that names no other `cacheFolder`. */
2824
+ const PROJECT_CACHE = join(".antelope", "cache");
2825
+ const MANIFEST = "manifest.json";
2826
+ /** Where `ajs` keeps a project's lock records, one folder per `<package>@<version>`. */
2827
+ const LOCK_FOLDER = "antelope-lock";
2828
+ /** How many milliseconds the harness waits at most for the file system clock to pass an install. */
2829
+ const CLOCK_ATTEMPTS = 100;
2830
+ /** A start time later than every command's, for a module the harness first sees outside a command: any lock record it has counts as one `ajs` installed it from. */
2831
+ const UNKNOWN_START = 2n ** 63n;
2832
+ /** A version `ajs` records for a registry package; a git module records `git:<branch>:<commit>`. */
2833
+ const REGISTRY_VERSION = /^\d+\.\d+\.\d+(?:[-+][0-9A-Za-z.+-]*)?$/;
2834
+ /** When the folder at `path` was created, which tells apart the folders created one after another there even when the file system reuses the inode; `0n` when the file system does not record it. */
2835
+ function bornAt(path) {
2836
+ try {
2837
+ return lstatSync(path, { bigint: true }).birthtimeNs;
2838
+ } catch {
2839
+ return 0n;
2840
+ }
2841
+ }
2842
+ /** Whether `project` held the lock record of `name@version` when a command that started at `start` began; `ajs` writes a record only after an install that used none. */
2843
+ function pinned(project, name, version, start) {
2844
+ try {
2845
+ const record = join(project, LOCK_FOLDER, `${name}@${version}`);
2846
+ return lstatSync(record, { bigint: true }).mtimeNs <= start;
2847
+ } catch {
2848
+ return false;
2849
+ }
2850
+ }
2851
+ function names(folder) {
2852
+ try {
2853
+ return readdirSync(folder).filter((name) => !name.startsWith("."));
2854
+ } catch {
2855
+ return [];
2856
+ }
2857
+ }
2858
+ /** Every entry under `root`, by its path relative to `root`, with its modification time; symbolic links are listed, not followed. */
2859
+ function* entries(root, prefix = "") {
2860
+ for (const entry of readdirSync(join(root, prefix), { withFileTypes: true })) {
2861
+ const path = join(prefix, entry.name);
2862
+ const directory = entry.isDirectory();
2863
+ yield {
2864
+ path,
2865
+ mtime: lstatSync(join(root, path), { bigint: true }).mtimeNs,
2866
+ directory
2867
+ };
2868
+ if (directory) yield* entries(root, path);
2869
+ }
2870
+ }
2871
+ /** Whether a project's antelope config (antelope.json or antelope.config.*) mentions `cacheFolder`, so `ajs` may install somewhere other than `.antelope/cache`. */
2872
+ function namesCacheFolder(project) {
2873
+ try {
2874
+ return readdirSync(project).filter((name) => /^antelope(\.config)?\.[cm]?[jt]s(on)?$/.test(name)).some((name) => /\bcacheFolder\b/.test(readFileSync(join(project, name), "utf8")));
2875
+ } catch {
2876
+ return false;
2877
+ }
2878
+ }
2879
+ /**
2880
+ * Copies `source` into a staging entry next to `target` and renames it onto
2881
+ * `target`, so a reader sees all of the copy or none of it. A failed copy, a
2882
+ * deleted source or a `target` another writer filled first leaves `target`
2883
+ * as it was.
2884
+ */
2885
+ function publish(source, target) {
2886
+ const staging = join(dirname(target), `.staging-${randomBytes(6).toString("hex")}`);
2887
+ try {
2888
+ cpSync(source, staging, {
2889
+ recursive: true,
2890
+ verbatimSymlinks: true,
2891
+ preserveTimestamps: true
2892
+ });
2893
+ renameSync(staging, target);
2894
+ } catch {
2895
+ return;
2896
+ } finally {
2897
+ removeTree(staging);
2898
+ }
2899
+ }
2900
+ /** The manifest `ajs` writes each time it finishes installing a module: its modification time and each module's version, sorted by module. */
2901
+ function manifestOf(cache) {
2902
+ try {
2903
+ const file = join(cache, MANIFEST);
2904
+ const manifest = parseJson(readFileSync(file, "utf8"));
2905
+ if (!isObject(manifest)) return void 0;
2906
+ const modules = Object.entries(manifest).map(([name, version]) => [name, String(version)]).sort(([left], [right]) => left < right ? -1 : 1);
2907
+ return {
2908
+ mtime: lstatSync(file, { bigint: true }).mtimeNs,
2909
+ modules
2910
+ };
2911
+ } catch {
2912
+ return;
2913
+ }
2914
+ }
2915
+ /**
2916
+ * Why `cache` is not exactly what `ajs` installed, or `undefined` when it is.
2917
+ * Each file of a module must be no newer than the module's bound. Outside the
2918
+ * modules, `ajs` writes only the manifest and the folders that hold the
2919
+ * modules, which must be no newer than the manifest.
2920
+ */
2921
+ function changeIn(cache, installed, manifest) {
2922
+ const modules = [...installed].map(([name, module]) => ({
2923
+ folder: join(name),
2924
+ label: `${name}@${module.version}`,
2925
+ bound: module.bound
2926
+ }));
2927
+ try {
2928
+ for (const { path, mtime, directory } of entries(cache)) {
2929
+ if (path === MANIFEST) continue;
2930
+ const owner = modules.find(({ folder }) => path === folder || path.startsWith(`${folder}${sep}`));
2931
+ if (owner === void 0) {
2932
+ if (!directory) return `${path} belongs to no installed module`;
2933
+ if (mtime > manifest) return `${path} changed after ajs wrote ${MANIFEST}`;
2934
+ } else if (mtime > owner.bound) return `${path} changed after ajs installed ${owner.label}`;
2935
+ }
2936
+ } catch (error) {
2937
+ return `it could not be read: ${error instanceof Error ? error.message : String(error)}`;
2938
+ }
2939
+ }
2940
+ /**
2941
+ * The module caches of the projects one journey creates, and the run's kept
2942
+ * copies of them in `store`. Kept copies are never written, so journeys of
2943
+ * one run can copy them at once.
2944
+ *
2945
+ * Only a cache exactly as a fresh `ajs` install leaves it is kept. `ajs`
2946
+ * writes a registry module's files, then records its version in
2947
+ * `manifest.json`, so the manifest's modification time when the harness first
2948
+ * sees the module bounds every file of it. A file modified later, a module
2949
+ * whose version or folder changes after that, a module `ajs` installed from a
2950
+ * lock record the project held before the command, and a git module, which
2951
+ * `ajs` updates in place and builds with the project's own install command,
2952
+ * each keep the cache out of the store.
2953
+ */
2954
+ var ProjectCaches = class {
2955
+ store;
2956
+ projects = /* @__PURE__ */ new Map();
2957
+ constructor(store) {
2958
+ this.store = store;
2959
+ }
2960
+ /** Gives a project that has installed no module yet a copy of the largest kept cache, so `ajs` reuses the packages an earlier journey installed instead of packing and installing them again. A project whose antelope config names its own `cacheFolder` gets no copy, since `ajs` would not read `.antelope/cache`. */
2961
+ seed(project) {
2962
+ const state = { installed: /* @__PURE__ */ new Map() };
2963
+ this.projects.set(project, state);
2964
+ if (namesCacheFolder(project)) return;
2965
+ const cache = join(project, PROJECT_CACHE);
2966
+ if ((manifestOf(cache)?.modules.length ?? 0) > 0) {
2967
+ this.observe();
2968
+ return;
2969
+ }
2970
+ let largest;
2971
+ for (const name of names(this.store)) {
2972
+ const folder = join(this.store, name);
2973
+ const size = manifestOf(folder)?.modules.length ?? 0;
2974
+ if (size > (largest?.size ?? 0)) largest = {
2975
+ folder,
2976
+ size
2977
+ };
2978
+ }
2979
+ if (largest === void 0) return;
2980
+ mkdirSync(dirname(cache), { recursive: true });
2981
+ publish(largest.folder, cache);
2982
+ const copied = manifestOf(cache);
2983
+ if (copied === void 0) return;
2984
+ let bound = copied.mtime;
2985
+ try {
2986
+ for (const { mtime } of entries(cache)) if (mtime > bound) bound = mtime;
2987
+ } catch {
2988
+ return;
2989
+ }
2990
+ for (const [name, version] of copied.modules) state.installed.set(name, {
2991
+ version,
2992
+ born: bornAt(join(cache, name)),
2993
+ bound
2994
+ });
2995
+ this.passClock(bound);
2996
+ }
2997
+ /**
2998
+ * Records the bound of each module that appeared in a project's manifest
2999
+ * since the last call, and refuses the cache of a project whose recorded
3000
+ * module left the manifest, changed version or sits in a new folder. A
3001
+ * module that appeared with a lock record no newer than `start`, the start
3002
+ * of the command that just ended, was installed from that record.
3003
+ */
3004
+ observe(start = UNKNOWN_START) {
3005
+ let latest = -1n;
3006
+ for (const [project, state] of this.projects) {
3007
+ const cache = join(project, PROJECT_CACHE);
3008
+ const manifest = manifestOf(cache);
3009
+ if (manifest === void 0) continue;
3010
+ const listed = new Map(manifest.modules);
3011
+ for (const [name, known] of state.installed) if (!listed.has(name)) state.refused ??= `${name} left ${MANIFEST} after ajs installed ${name}@${known.version}`;
3012
+ for (const [name, version] of manifest.modules) {
3013
+ const born = bornAt(join(cache, name));
3014
+ const known = state.installed.get(name);
3015
+ if (known === void 0) {
3016
+ state.installed.set(name, {
3017
+ version,
3018
+ born,
3019
+ bound: manifest.mtime
3020
+ });
3021
+ if (manifest.mtime > latest) latest = manifest.mtime;
3022
+ if (pinned(project, name, version, start)) state.refused ??= `ajs installed ${name}@${version} from the project's lock record`;
3023
+ } else if (known.version !== version) state.refused ??= `${name} changed from ${known.version} to ${version} after ajs installed it`;
3024
+ else if (born !== known.born) state.refused ??= `${name} was created again after ajs installed ${name}@${version}`;
3025
+ }
3026
+ }
3027
+ if (latest >= 0n) this.passClock(latest);
3028
+ }
3029
+ /** Observes the project caches once a command or an app start has ended, and returns its result. Its `folder` is the step folder the harness created as it began, so a lock record no newer than that folder was there before the command. */
3030
+ observed(result) {
3031
+ this.observe(bornAt(result.folder) || UNKNOWN_START);
3032
+ return result;
3033
+ }
3034
+ /**
3035
+ * Returns once the file system clock has moved past `time`, so a file the
3036
+ * journey writes from now on is newer than a bound of `time`. The clock
3037
+ * advances in ticks of a few milliseconds, and a write within the tick of
3038
+ * the bound would carry the bound's time.
3039
+ */
3040
+ passClock(time) {
3041
+ const probe = join(this.store, `.clock-${randomBytes(6).toString("hex")}`);
3042
+ const pause = new Int32Array(new SharedArrayBuffer(4));
3043
+ try {
3044
+ mkdirSync(this.store, { recursive: true });
3045
+ for (let attempt = 0; attempt < CLOCK_ATTEMPTS; attempt += 1) {
3046
+ writeFileSync(probe, "");
3047
+ if (lstatSync(probe, { bigint: true }).mtimeNs > time) return;
3048
+ Atomics.wait(pause, 0, 0, 1);
3049
+ }
3050
+ } catch {
3051
+ return;
3052
+ } finally {
3053
+ rmSync(probe, { force: true });
3054
+ }
3055
+ }
3056
+ /**
3057
+ * Keeps a copy of each project's module cache for the rest of the run, one per set of installed versions; a set already kept stays as it is. Call it once the journey passed and every app stopped.
3058
+ * Returns why each cache that changed after `ajs` installed it was not kept.
3059
+ */
3060
+ keep() {
3061
+ this.observe();
3062
+ const skipped = [];
3063
+ for (const [project, state] of this.projects) {
3064
+ const cache = join(project, PROJECT_CACHE);
3065
+ const manifest = manifestOf(cache);
3066
+ if (manifest === void 0 || manifest.modules.length === 0) continue;
3067
+ const target = join(this.store, createHash("sha256").update(manifest.modules.map((entry) => entry.join("@")).join("\n")).digest("hex").slice(0, 16));
3068
+ if (existsSync(target)) continue;
3069
+ const unregistered = manifest.modules.find(([, version]) => !REGISTRY_VERSION.test(version));
3070
+ const change = state.refused ?? (unregistered === void 0 ? changeIn(cache, state.installed, manifest.mtime) : `${unregistered.join("@")} is not a registry version, and ajs updates a git module in place`);
3071
+ if (change !== void 0) {
3072
+ skipped.push(`${cache}: ${change}`);
3073
+ continue;
3074
+ }
3075
+ mkdirSync(this.store, { recursive: true });
3076
+ publish(cache, target);
3077
+ }
3078
+ return skipped;
3079
+ }
3080
+ };
3081
+ //#endregion
3082
+ //#region src/verify/prepared.ts
3083
+ const KEY = /^[a-z0-9]+(?:-[a-z0-9]+)*$/;
3084
+ /** The path of `path` inside `root`, or `null` when it lies outside. */
3085
+ function inside(root, path) {
3086
+ const rest = relative(root, path);
3087
+ if (rest === ".." || rest.startsWith(`..${sep}`) || isAbsolute(rest)) return null;
3088
+ return rest;
3089
+ }
3090
+ /** Surveys `folder` in one walk that descends only into real directories, so it never follows a symlink; a target may name the folder by its real path. */
3091
+ function survey(folder) {
3092
+ const real = realpathSync(folder);
3093
+ const found = {
3094
+ links: [],
3095
+ special: null
3096
+ };
3097
+ const walk = (at) => {
3098
+ for (const entry of readdirSync(join(folder, at), { withFileTypes: true })) {
3099
+ const path = join(at, entry.name);
3100
+ if (entry.isDirectory()) walk(path);
3101
+ else if (entry.isSymbolicLink()) {
3102
+ const pointed = readlinkSync(join(folder, path));
3103
+ const target = isAbsolute(pointed) ? inside(folder, pointed) ?? inside(real, pointed) : null;
3104
+ if (target !== null) found.links.push({
3105
+ path,
3106
+ target
3107
+ });
3108
+ } else if (!entry.isFile()) found.special ??= path;
3109
+ }
3110
+ };
3111
+ walk("");
3112
+ return found;
3113
+ }
3114
+ /**
3115
+ * Copies `source` to `target`, which ends up at `root`. Each of `links`
3116
+ * points to its target inside `root`, so no copy reaches another journey's
3117
+ * folder. Every other symlink keeps its target, so pnpm's relative links in a
3118
+ * copy never point back into the source.
3119
+ */
3120
+ function copyTree(source, target, links = [], root = target) {
3121
+ cpSync(source, target, {
3122
+ recursive: true,
3123
+ verbatimSymlinks: true,
3124
+ preserveTimestamps: true
3125
+ });
3126
+ for (const link of links) {
3127
+ unlinkSync(join(target, link.path));
3128
+ symlinkSync(join(root, link.target), join(target, link.path));
3129
+ }
3130
+ }
3131
+ /** Judges the build of `folder` by the steps it recorded. */
3132
+ function judge$1(steps, folder) {
3133
+ const checks = steps.flatMap((step) => step.checks);
3134
+ if (checks.length === 0) return {
3135
+ kept: false,
3136
+ reason: "the build recorded no check"
3137
+ };
3138
+ if (!checks.every((check) => check.pass)) return {
3139
+ kept: false,
3140
+ reason: "a check of the build failed"
3141
+ };
3142
+ const found = survey(folder);
3143
+ return found.special === null ? {
3144
+ kept: true,
3145
+ links: found.links
3146
+ } : {
3147
+ kept: false,
3148
+ reason: `${found.special} is not a file, directory or symlink, which a copy would drop`
3149
+ };
3150
+ }
3151
+ /** The links `keep` recorded, each a path then its target, joined by NUL, the one character no path holds. */
3152
+ function readLinks(kept) {
3153
+ const fields = readFileSync(join(kept, "links"), "utf8").split("\0");
3154
+ const links = [];
3155
+ for (let at = 0; at + 1 < fields.length; at += 2) links.push({
3156
+ path: fields[at],
3157
+ target: fields[at + 1]
3158
+ });
3159
+ return links;
3160
+ }
3161
+ /** The journey that built what the run kept, as its path under the evidence. */
3162
+ function builder(kept) {
3163
+ return readFileSync(join(kept, "from.txt"), "utf8").trim();
3164
+ }
3165
+ /**
3166
+ * Copies what the run kept into the journey, with the evidence of that build
3167
+ * under the step `marker`, and returns `null`. When the copy fails, or what
3168
+ * the run kept is gone or replaced once it ends, as when the journey that
3169
+ * built reruns meanwhile, the partial copy is removed and this returns why.
3170
+ */
3171
+ function reuse$1({ marker, key, kept, folder }) {
3172
+ const evidence = join(marker, "build");
3173
+ try {
3174
+ const memo = statSync(kept).ino;
3175
+ copyTree(join(kept, "evidence"), evidence);
3176
+ copyTree(join(kept, "folder"), folder, readLinks(kept));
3177
+ const from = builder(kept);
3178
+ if (statSync(kept).ino !== memo) throw new Error(`${kept} was replaced while it was copied`);
3179
+ writeFileSync(join(marker, "prepared.txt"), `${key}: ${folder} is a copy of what ${from} prepared; build/ holds the evidence of that build\n`);
3180
+ return null;
3181
+ } catch (error) {
3182
+ removeTree(evidence);
3183
+ removeTree(folder);
3184
+ return error instanceof Error ? error.message : String(error);
3185
+ }
3186
+ }
3187
+ /** Removes what the run kept by first renaming it away, so a journey copying it meanwhile fails instead of copying a half-deleted tree. */
3188
+ function drop(kept) {
3189
+ const trash = mkdtempSync(`${kept}.`);
3190
+ renameSync(kept, join(trash, "dropped"));
3191
+ removeTree(trash);
3192
+ }
3193
+ /** Keeps the built folder and the build's step evidence for the rest of the run, published by one rename; when another journey kept the key first, its copy stays and this returns `false`. */
3194
+ function keep(context, kept, folder, built) {
3195
+ mkdirSync(dirname(kept), { recursive: true });
3196
+ const staging = mkdtempSync(`${kept}.`);
3197
+ try {
3198
+ mkdirSync(join(staging, "evidence"));
3199
+ for (const step of built.steps) copyTree(join(context.folder, step), join(staging, "evidence", step));
3200
+ copyTree(folder, join(staging, "folder"), built.links, join(kept, "folder"));
3201
+ writeFileSync(join(staging, "links"), built.links.flatMap((link) => [link.path, link.target]).join("\0"));
3202
+ writeFileSync(join(staging, "from.txt"), `${relative(context.state.evidence, context.folder)}\n`);
3203
+ renameSync(staging, kept);
3204
+ return true;
3205
+ } catch (error) {
3206
+ if (!existsSync(kept)) throw error;
3207
+ return false;
3208
+ } finally {
3209
+ removeTree(staging);
3210
+ }
3211
+ }
3212
+ /** Runs `build` with a HOME of its own for its commands, deleted when it ends. */
3213
+ async function buildAlone(context, key, folder, build) {
3214
+ const outer = context.buildHome;
3215
+ const home = join(context.home, `.prepared-${key}`);
3216
+ mkdirSync(home, { recursive: true });
3217
+ context.buildHome = home;
3218
+ try {
3219
+ await build(folder);
3220
+ } finally {
3221
+ context.buildHome = outer;
3222
+ removeTree(home);
3223
+ }
3224
+ }
3225
+ /** Builds `key` in this journey after the step `marker`, which marks the steps after it as the build and says, after `before`, whether the run kept it. */
3226
+ async function buildHere(context, where, build, before = "") {
3227
+ const { marker, key, kept, folder } = where;
3228
+ const note = (outcome) => writeFileSync(join(marker, "prepared.txt"), `${key}: ${before}${folder} was built here by the steps after this one; ${outcome}\n`);
3229
+ const earlier = new Set(readdirSync(context.folder));
3230
+ const checked = context.steps.length;
3231
+ mkdirSync(folder, { recursive: true });
3232
+ try {
3233
+ await buildAlone(context, key, folder, build);
3234
+ } catch (error) {
3235
+ note("not kept: the build threw, so the next journey builds again");
3236
+ throw error;
3237
+ }
3238
+ const verdict = judge$1(context.steps.slice(checked), folder);
3239
+ if (!verdict.kept) {
3240
+ note(`not kept: ${verdict.reason}, so the next journey builds again`);
3241
+ return;
3242
+ }
3243
+ note(keep(context, kept, folder, {
3244
+ steps: readdirSync(context.folder).filter((entry) => !earlier.has(entry)),
3245
+ links: verdict.links
3246
+ }) ? "kept, so later journeys of the run copy it" : `not kept: ${builder(kept)} kept ${key} first, so later journeys copy that build`);
3247
+ }
3248
+ /** `JourneyContext.prepared` for one journey of the run. */
3249
+ async function prepare(context, key, build) {
3250
+ if (!KEY.test(key)) throw new Error(`prepared key ${JSON.stringify(key)} must be lowercase letters and digits joined by dashes`);
3251
+ const folder = join(context.work, key);
3252
+ if (existsSync(folder)) throw new Error(`${folder} already exists: a journey prepares ${key} once`);
3253
+ const kept = join(context.state.dir, "prepared", key);
3254
+ if (existsSync(kept) && builder(kept) === relative(context.state.evidence, context.folder)) drop(kept);
3255
+ const where = {
3256
+ marker: context.step(`prepared ${key}`),
3257
+ key,
3258
+ kept,
3259
+ folder
3260
+ };
3261
+ if (!existsSync(kept)) await buildHere(context, where, build);
3262
+ else {
3263
+ const failed = reuse$1(where);
3264
+ if (failed !== null) await buildHere(context, where, build, `copying what the run kept failed (${failed}), so `);
3265
+ }
3266
+ return folder;
3267
+ }
3268
+ //#endregion
2533
3269
  //#region src/verify/context.ts
2534
3270
  var JourneyAbort = class extends Error {};
2535
3271
  var NotVerified = class extends Error {};
2536
3272
  const READY_TIMEOUT_MS = 12e4;
2537
3273
  const STOP_TIMEOUT_MS = 3e4;
3274
+ /** The longest wait between readiness probes. */
2538
3275
  const POLL_MS = 250;
3276
+ /** 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. */
3277
+ const FAST_POLL_MS = 25;
3278
+ /** How long readiness is probed every `FAST_POLL_MS` before falling back to `POLL_MS`. */
3279
+ const FAST_POLL_WINDOW_MS = 3e3;
2539
3280
  const SETTLE_MS = 3e3;
2540
3281
  /** The waits between the readiness reruns after a failed journey: one miss under load does not hide a catch. */
2541
3282
  const READINESS_RETRY_MS = [
@@ -2543,19 +3284,9 @@ const READINESS_RETRY_MS = [
2543
3284
  1e3,
2544
3285
  2e3
2545
3286
  ];
2546
- /** The signals a process outside the run sends to end an app. Any other signal, such as SIGABRT or SIGSEGV, is the product crashing. */
2547
- const OUTSIDE_KILLS = /* @__PURE__ */ new Set([
2548
- "SIGKILL",
2549
- "SIGTERM",
2550
- "SIGHUP",
2551
- "SIGINT"
2552
- ]);
2553
3287
  function slug(text) {
2554
3288
  return text.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-|-$/g, "");
2555
3289
  }
2556
- function sleep(ms) {
2557
- return new Promise((resolve) => setTimeout(resolve, ms));
2558
- }
2559
3290
  /** The harness side of a journey: every driving call writes its evidence into a new numbered step folder. */
2560
3291
  var VerifyContext = class {
2561
3292
  repo;
@@ -2563,12 +3294,17 @@ var VerifyContext = class {
2563
3294
  work;
2564
3295
  home;
2565
3296
  steps = [];
3297
+ /** The HOME every command gets while `prepared` runs a build; the journey's HOME when `null`. */
3298
+ buildHome = null;
2566
3299
  running = [];
2567
3300
  started = [];
2568
3301
  fixtures = /* @__PURE__ */ new Map();
2569
3302
  index = 0;
3303
+ /** Times every step folder of the journey. */
3304
+ clock = new StepClock();
2570
3305
  workspace;
2571
3306
  state;
3307
+ caches;
2572
3308
  constructor(workspace, state, feature, journey) {
2573
3309
  this.workspace = workspace;
2574
3310
  this.state = state;
@@ -2576,6 +3312,7 @@ var VerifyContext = class {
2576
3312
  this.folder = join(state.evidence, feature, journey);
2577
3313
  this.work = join(state.dir, "work", feature, journey);
2578
3314
  this.home = join(state.dir, "homes", feature, journey);
3315
+ this.caches = new ProjectCaches(join(state.dir, "ajs-cache"));
2579
3316
  for (const folder of [
2580
3317
  this.folder,
2581
3318
  this.work,
@@ -2588,16 +3325,18 @@ var VerifyContext = class {
2588
3325
  mkdirSync(folder, { recursive: true });
2589
3326
  }
2590
3327
  }
2591
- /** A fresh numbered step folder. */
3328
+ /** A fresh numbered step folder; it also ends the clock of the previous step and starts its own. */
2592
3329
  step(name) {
2593
3330
  this.index += 1;
2594
3331
  const folder = join(this.folder, `${String(this.index).padStart(2, "0")}-${slug(name)}`);
2595
3332
  mkdirSync(folder, { recursive: true });
3333
+ this.clock.start(basename(folder));
2596
3334
  return folder;
2597
3335
  }
2598
3336
  env(extra = {}) {
2599
- return isolatedEnv(this.workspace, this.home, extra);
3337
+ return isolatedEnv(this.workspace, this.buildHome ?? this.home, extra);
2600
3338
  }
3339
+ prepared = (key, build) => prepare(this, key, build);
2601
3340
  command(name, program, args, options = {}) {
2602
3341
  return runRecorded(this.step(name), {
2603
3342
  program,
@@ -2605,7 +3344,7 @@ var VerifyContext = class {
2605
3344
  cwd: options.cwd ?? this.work,
2606
3345
  env: this.env(options.env),
2607
3346
  timeoutMs: options.timeoutMs
2608
- });
3347
+ }).then((result) => this.caches.observed(result));
2609
3348
  }
2610
3349
  /** Runs `ajs <args>` of the repository's `@antelopejs/core`. */
2611
3350
  ajs(name, args, options = {}) {
@@ -2669,6 +3408,7 @@ var VerifyContext = class {
2669
3408
  const fixture = writeFixture(this.workspace, this.state, folder, config);
2670
3409
  this.fixtures.set(fixture.project, fixture);
2671
3410
  this.tree("fixture project", fixture.project);
3411
+ this.caches.seed(fixture.project);
2672
3412
  return fixture.project;
2673
3413
  }
2674
3414
  /** The log the stub provider wrote, one call per line: the provider's view of what core delivered. */
@@ -2732,7 +3472,7 @@ var VerifyContext = class {
2732
3472
  });
2733
3473
  saveRun(this.state);
2734
3474
  await this.waitReady(app, handle, fixture !== void 0);
2735
- return app;
3475
+ return this.caches.observed(app);
2736
3476
  }
2737
3477
  async probe(app, fixture, folder) {
2738
3478
  const probe = this.workspace.config.template?.probe;
@@ -2761,13 +3501,14 @@ var VerifyContext = class {
2761
3501
  handle.exited.then(() => {
2762
3502
  exited = true;
2763
3503
  });
3504
+ const fastUntil = Date.now() + FAST_POLL_WINDOW_MS;
2764
3505
  let check = await this.probe(app, fixture, folder);
2765
3506
  while (!check.pass && !exited && Date.now() < deadline) {
2766
- await sleep(POLL_MS);
3507
+ await setTimeout$1(Date.now() < fastUntil ? FAST_POLL_MS : POLL_MS);
2767
3508
  check = await this.probe(app, fixture, folder);
2768
3509
  }
2769
3510
  const settle = this.workspace.config.template?.probe.log ? this.workspace.config.template.probe.settleMs ?? SETTLE_MS : 0;
2770
- if (check.pass && settle > 0) await sleep(settle);
3511
+ if (check.pass && settle > 0) await setTimeout$1(settle);
2771
3512
  const alive = {
2772
3513
  name: "still running after readiness",
2773
3514
  pass: !exited,
@@ -2858,7 +3599,7 @@ var VerifyContext = class {
2858
3599
  pass: set.exitCode === 0,
2859
3600
  detail: set.stderr.slice(-300)
2860
3601
  }], { critical: true });
2861
- return this.ajs(name, [
3602
+ const init = await this.ajs(name, [
2862
3603
  "project",
2863
3604
  "init",
2864
3605
  relative(this.work, project),
@@ -2866,6 +3607,8 @@ var VerifyContext = class {
2866
3607
  this.state.templateName,
2867
3608
  ...flags
2868
3609
  ]);
3610
+ if (init.exitCode === 0) this.caches.seed(project);
3611
+ return init;
2869
3612
  }
2870
3613
  /** Stops every app the journey left running. */
2871
3614
  async cleanup() {
@@ -2885,21 +3628,13 @@ var VerifyContext = class {
2885
3628
  const failure = await this.unready(name, service.ready);
2886
3629
  if (failure !== null) return `the service ${name} no longer passes its readiness command: ${failure}`;
2887
3630
  }
2888
- for (const { app, sent, exit } of this.started) {
2889
- const label = `${app.name} (pid ${app.pid})`;
2890
- if (exit?.signal && OUTSIDE_KILLS.has(exit.signal) && !sent.includes(exit.signal)) return `${label} was killed by ${exit.signal}, a signal the harness did not send`;
2891
- const output = readOutput(app.folder);
2892
- const port = new RegExp(`(?<![0-9])${app.port}(?![0-9])`);
2893
- const taken = `${output.stdout}\n${output.stderr}`.split("\n").find((line) => line.includes("EADDRINUSE") && port.test(line));
2894
- if (taken !== void 0) return `${label} could not bind port ${app.port}, which another process holds: ${taken.trim().slice(0, 300)}`;
2895
- }
2896
- return null;
3631
+ return appFault(this.started);
2897
3632
  }
2898
3633
  /** The last readiness failure of a service after the reruns, or `null` once one rerun passes. */
2899
3634
  async unready(name, ready) {
2900
3635
  let failure = null;
2901
3636
  for (const wait of [0, ...READINESS_RETRY_MS]) {
2902
- await sleep(wait);
3637
+ await setTimeout$1(wait);
2903
3638
  failure = readinessFailure(this.service(name).container, ready, this.step(`${name} readiness after the failure`));
2904
3639
  if (failure === null) return null;
2905
3640
  }
@@ -2935,12 +3670,12 @@ function resetServices(context) {
2935
3670
  for (const [name, service] of Object.entries(context.workspace.config.services ?? {})) {
2936
3671
  if (!service.reset) continue;
2937
3672
  const container = context.service(name).container;
3673
+ const folder = context.step(`reset ${name}`);
2938
3674
  const run = spawnSync("docker", [
2939
3675
  "exec",
2940
3676
  container,
2941
3677
  ...service.reset
2942
3678
  ], { encoding: "utf8" });
2943
- const folder = context.step(`reset ${name}`);
2944
3679
  writeFileSync(join(folder, "command.txt"), `docker exec ${container} ${service.reset.join(" ")}\n`);
2945
3680
  writeFileSync(join(folder, "stdout.txt"), run.stdout ?? "");
2946
3681
  writeFileSync(join(folder, "stderr.txt"), run.stderr ?? "");
@@ -2983,6 +3718,7 @@ async function runOne(workspace, state, feature, id, journey) {
2983
3718
  }
2984
3719
  async function driveJourney(context, feature, id, journey) {
2985
3720
  const { state } = context;
3721
+ const elapsed = stopwatch();
2986
3722
  let failure = {
2987
3723
  error: null,
2988
3724
  notVerified: null
@@ -3002,15 +3738,20 @@ async function driveJourney(context, feature, id, journey) {
3002
3738
  notVerified: fault
3003
3739
  };
3004
3740
  }
3741
+ const status = statusOf(context, failure);
3742
+ const skipped = status === "PASS" ? context.caches.keep() : [];
3743
+ if (skipped.length > 0) writeFileSync(join(context.step("module cache not kept"), "note.txt"), `${skipped.map((reason) => `${reason}; a later journey installs its modules again`).join("\n")}\n`);
3005
3744
  const result = {
3006
3745
  feature,
3007
3746
  journey: id,
3008
3747
  title: journey.title,
3009
3748
  entryPoint: journey.entryPoint,
3010
- status: statusOf(context, failure),
3749
+ status,
3011
3750
  steps: context.steps,
3012
3751
  ...failure,
3013
- folder: relative(state.evidence, context.folder)
3752
+ folder: relative(state.evidence, context.folder),
3753
+ stepMs: context.clock.finish(),
3754
+ ms: elapsed()
3014
3755
  };
3015
3756
  writeFileSync(join(context.folder, "result.json"), `${JSON.stringify(result, null, 2)}\n`);
3016
3757
  return result;
@@ -3092,7 +3833,7 @@ function stamp(state, result, tree) {
3092
3833
  writeFileSync(join(state.evidence, result.folder, "result.json"), `${JSON.stringify(stamped, null, 2)}\n`);
3093
3834
  return stamped;
3094
3835
  }
3095
- /** Records `source` as the result of `id` under `feature` without running the journey: its own result.json names the folder it reuses. */
3836
+ /** Records `source` as the result of `id` under `feature` without running the journey: its own result.json names the folder it reuses, and its time is zero so a run's total counts the journey once. */
3096
3837
  function reuse(state, feature, id, source) {
3097
3838
  const folder = join(state.evidence, feature, id);
3098
3839
  rmSync(folder, {
@@ -3104,7 +3845,9 @@ function reuse(state, feature, id, source) {
3104
3845
  ...source,
3105
3846
  feature,
3106
3847
  folder: relative(state.evidence, folder),
3107
- reusedFrom: source.folder
3848
+ reusedFrom: source.folder,
3849
+ ms: 0,
3850
+ stepMs: []
3108
3851
  };
3109
3852
  writeFileSync(join(folder, "result.json"), `${JSON.stringify(result, null, 2)}\n`);
3110
3853
  return result;
@@ -3143,6 +3886,57 @@ async function runFeature(workspace, state, feature, ids) {
3143
3886
  return results;
3144
3887
  }
3145
3888
  //#endregion
3889
+ //#region src/verify/timing-report.ts
3890
+ /** How many of a journey's steps the verdict names. */
3891
+ const SLOWEST_STEPS = 3;
3892
+ /** The label of the verdict's last timing row; it states what the sum leaves out. */
3893
+ const TOTAL_LABEL = "**Total measured** (commands only; agent time between commands is not included)";
3894
+ function sum(values) {
3895
+ return values.every((ms) => ms !== null) ? values.reduce((total, ms) => total + (ms ?? 0), 0) : null;
3896
+ }
3897
+ function slowest(steps) {
3898
+ return steps.toSorted((a, b) => b.ms - a.ms).slice(0, SLOWEST_STEPS);
3899
+ }
3900
+ /** Collects what a run measured: its `new` phases, each journey's total and slowest steps, each formal check. */
3901
+ function timingReport(setup, features, formal) {
3902
+ const journeys = features.flatMap(({ feature, results }) => results.map((result) => ({
3903
+ feature,
3904
+ journey: result.journey,
3905
+ ms: result.ms ?? null,
3906
+ slowestSteps: slowest(result.stepMs ?? [])
3907
+ })));
3908
+ const checks = formal.map((result) => ({
3909
+ name: result.name,
3910
+ ms: result.ms ?? null
3911
+ }));
3912
+ return {
3913
+ setup,
3914
+ journeys,
3915
+ formal: checks,
3916
+ totalMs: setup.length === 0 ? null : sum([
3917
+ ...setup.map((entry) => entry.ms),
3918
+ ...journeys.map((entry) => entry.ms),
3919
+ ...checks.map((entry) => entry.ms)
3920
+ ])
3921
+ };
3922
+ }
3923
+ function journeyCell(entry) {
3924
+ if (entry.ms === null || entry.slowestSteps.length === 0) return seconds(entry.ms);
3925
+ const steps = entry.slowestSteps.map((step) => `\`${step.step}\` ${seconds(step.ms)}`).join(", ");
3926
+ return `${seconds(entry.ms)} (slowest steps: ${steps})`;
3927
+ }
3928
+ /** The `### Timing` table of a verdict: one row per measured phase, journey and formal check, then the sum. */
3929
+ function timingTable(report) {
3930
+ return [
3931
+ "| Phase | Time |",
3932
+ "|---|---|",
3933
+ ...report.setup.length > 0 ? report.setup.map((entry) => `| ${entry.phase} | ${seconds(entry.ms)} |`) : [`| new (setup, pack, services, sources) | ${seconds(null)} |`],
3934
+ ...report.journeys.map((entry) => `| journey ${entry.feature}/${entry.journey} | ${journeyCell(entry)} |`),
3935
+ ...report.formal.map((entry) => `| formal ${entry.name} | ${seconds(entry.ms)} |`),
3936
+ `| ${TOTAL_LABEL} | ${seconds(report.totalMs)} |`
3937
+ ];
3938
+ }
3939
+ //#endregion
3146
3940
  //#region src/verify/verdict.ts
3147
3941
  /** The GitHub `owner/repo` of the origin remote. */
3148
3942
  function originRepository(root) {
@@ -3183,8 +3977,13 @@ function journeyRows(workspace, state, plan, link) {
3183
3977
  const reasons = [];
3184
3978
  const notVerified = [];
3185
3979
  const outsideNotVerified = [];
3980
+ const listed = [];
3186
3981
  for (const feature of plan.run) {
3187
3982
  const results = readResults(state, feature) ?? [];
3983
+ listed.push({
3984
+ feature,
3985
+ results
3986
+ });
3188
3987
  const registered = featureJourneys(workspace, feature) ?? [];
3189
3988
  for (const id of registered.filter((journey) => !results.some((result) => result.journey === journey))) reasons.push(`${feature}/${id} was not run`);
3190
3989
  for (const result of results) {
@@ -3196,18 +3995,26 @@ function journeyRows(workspace, state, plan, link) {
3196
3995
  rows.push(journeyRow(feature, result, link));
3197
3996
  }
3198
3997
  }
3199
- for (const feature of featuresOutsidePlan(state, plan)) for (const result of readResults(state, feature) ?? []) {
3200
- if (result.status === "FAIL") reasons.push(`${feature}/${result.journey} failed; ${feature} is outside the diff's features, so check its covers globs`);
3201
- const stale = staleReuse(state, result);
3202
- if (stale !== null) reasons.push(`${feature}/${result.journey} reuses ${result.reusedFrom}, which is now ${stale}`);
3203
- if (result.status === "NOT VERIFIED") outsideNotVerified.push(`${feature}/${result.journey}: ${result.notVerified}`);
3204
- rows.push(journeyRow(`${feature} (outside the diff's features)`, result, link));
3998
+ for (const feature of featuresOutsidePlan(state, plan)) {
3999
+ const results = readResults(state, feature) ?? [];
4000
+ listed.push({
4001
+ feature,
4002
+ results
4003
+ });
4004
+ for (const result of results) {
4005
+ if (result.status === "FAIL") reasons.push(`${feature}/${result.journey} failed; ${feature} is outside the diff's features, so check its covers globs`);
4006
+ const stale = staleReuse(state, result);
4007
+ if (stale !== null) reasons.push(`${feature}/${result.journey} reuses ${result.reusedFrom}, which is now ${stale}`);
4008
+ if (result.status === "NOT VERIFIED") outsideNotVerified.push(`${feature}/${result.journey}: ${result.notVerified}`);
4009
+ rows.push(journeyRow(`${feature} (outside the diff's features)`, result, link));
4010
+ }
3205
4011
  }
3206
4012
  return {
3207
4013
  rows,
3208
4014
  reasons,
3209
4015
  notVerified,
3210
- outsideNotVerified
4016
+ outsideNotVerified,
4017
+ listed
3211
4018
  };
3212
4019
  }
3213
4020
  function doorReasons(workspace, judgement, plan) {
@@ -3232,6 +4039,7 @@ function doorsSection(judgement) {
3232
4039
  function formalSection(workspace, state, plan, link) {
3233
4040
  const reasons = [];
3234
4041
  const lines = [];
4042
+ const ran = [];
3235
4043
  const touched = touchedFormalChecks(workspace, plan.changed).map((check) => check.name);
3236
4044
  for (const check of workspace.config.formal ?? []) {
3237
4045
  const result = readFormalResult(state, check.name);
@@ -3240,6 +4048,7 @@ function formalSection(workspace, state, plan, link) {
3240
4048
  if (gate) reasons.push(`formal check ${check.name} covers the diff but was not run`);
3241
4049
  continue;
3242
4050
  }
4051
+ ran.push(result);
3243
4052
  if (gate && result.behaviour === void 0 && result.exitCode === 0) reasons.push(`formal check ${check.name} covers the diff but its run did not compare the covered behaviour with the base`);
3244
4053
  const weight = formalGate(result);
3245
4054
  if (gate && weight.fails) reasons.push(`formal check ${check.name}: ${weight.outcome}`);
@@ -3248,7 +4057,8 @@ function formalSection(workspace, state, plan, link) {
3248
4057
  }
3249
4058
  return {
3250
4059
  reasons,
3251
- lines
4060
+ lines,
4061
+ ran
3252
4062
  };
3253
4063
  }
3254
4064
  function docsReasons(judgement, plan) {
@@ -3266,6 +4076,15 @@ function resultOf(reasons, notVerified, notes) {
3266
4076
  if (notVerified.length > 0) return "NOT VERIFIED";
3267
4077
  return notes > 0 ? "PASS+NOTES" : "PASS";
3268
4078
  }
4079
+ /** The verdict's Unmapped surfaces section, empty when every changed surface has a feature. */
4080
+ function unmappedSection(unmapped) {
4081
+ if (unmapped.length === 0) return [];
4082
+ return [
4083
+ "### Unmapped surfaces",
4084
+ ...unmapped.map((file) => `- \`${file}\` matches no feature glob; add it to a feature file.`),
4085
+ ""
4086
+ ];
4087
+ }
3269
4088
  /**
3270
4089
  * Computes the verdict of a run from its journey results, the diff plan and
3271
4090
  * the verifier's judgement, and writes verdict.md, verdict.json and plan.json
@@ -3293,6 +4112,7 @@ function renderVerdict(workspace, state, pr, judgement) {
3293
4112
  ...judgement.notVerified
3294
4113
  ];
3295
4114
  const result = resultOf(reasons, journeys.notVerified, notVerified.length + judgement.attention.length);
4115
+ const timings = timingReport(state.timings, journeys.listed, formal.ran);
3296
4116
  const touched = plan.touched.map((entry) => `\`${entry.feature}\` (diff: ${entry.files.map((file) => `\`${file}\``).join(", ")})`);
3297
4117
  const markdown = [
3298
4118
  `## Verify: ${result}`,
@@ -3307,11 +4127,7 @@ function renderVerdict(workspace, state, pr, judgement) {
3307
4127
  `- ${SMOKE_FEATURE}: runs on every verdict`,
3308
4128
  ...plan.full ? [`- ${fullLine(plan.full)}`] : [],
3309
4129
  "",
3310
- ...plan.unmapped.length > 0 ? [
3311
- "### Unmapped surfaces",
3312
- ...plan.unmapped.map((file) => `- \`${file}\` matches no feature glob; add it to a feature file.`),
3313
- ""
3314
- ] : [],
4130
+ ...unmappedSection(plan.unmapped),
3315
4131
  ...reasons.length > 0 ? [
3316
4132
  "### Why it fails",
3317
4133
  ...reasons.map((reason) => `- ${reason}`),
@@ -3334,6 +4150,9 @@ function renderVerdict(workspace, state, pr, judgement) {
3334
4150
  "### Attention",
3335
4151
  ...bullets(judgement.attention, "Nothing."),
3336
4152
  "",
4153
+ "### Timing",
4154
+ ...timingTable(timings),
4155
+ "",
3337
4156
  `Evidence: \`verify-evidence\` branch, [\`pr-${pr}/${plan.headSha}/\`](${link("")})`,
3338
4157
  ""
3339
4158
  ].join("\n");
@@ -3344,7 +4163,8 @@ function renderVerdict(workspace, state, pr, judgement) {
3344
4163
  headSha: plan.headSha,
3345
4164
  skillSha,
3346
4165
  pr,
3347
- reasons
4166
+ reasons,
4167
+ timings
3348
4168
  }, null, 2)}\n`);
3349
4169
  return {
3350
4170
  result,
@@ -3366,6 +4186,8 @@ const USAGE = `Usage: antelopejs-verify <command>
3366
4186
  build, prepare an isolated run, print its folder; --all runs every feature, before a release
3367
4187
  doctor <run> check the run is worth driving
3368
4188
  journey <run> <feature> [ids...] run a feature's journeys and record evidence
4189
+ journey <run> --plan run every feature the run's plan lists, smoke first
4190
+ journey <run> --features <a,b> run the named features, each whole, in that order
3369
4191
  formal <run> [--all] run the formal checks that cover the diff and gate them on changed behaviour
3370
4192
  doors [patch] [--base <ref>] print the One-way-door line for a patch, or for the diff
3371
4193
  clean <run> stop what the run started, keep only the evidence
@@ -3389,15 +4211,98 @@ function printMap(workspace) {
3389
4211
  for (const problem of problems) print(problem);
3390
4212
  return problems.length === 0 ? 0 : 1;
3391
4213
  }
3392
- async function runJourneys(workspace, dir, feature, ids) {
3393
- const results = await runFeature(workspace, loadRun(dir), feature, ids);
4214
+ /**
4215
+ * The features a `journey` call runs, in order.
4216
+ *
4217
+ * `journey <run> <feature> [ids...]` runs one feature, or the named journeys
4218
+ * of it. `journey <run> --plan` runs every feature `plan` lists as `run` for
4219
+ * the run's base and `--all`, `smoke` first. `journey <run> --features a,b`
4220
+ * runs the named features whole, in that order. Several features take a flag
4221
+ * rather than more positionals because a positional after the feature is a
4222
+ * journey id: reading it as a feature whenever a feature file has that name
4223
+ * would change what an existing call runs as soon as someone adds a feature
4224
+ * named like one of its journeys.
4225
+ */
4226
+ function featureRuns(workspace, rest, flags) {
4227
+ const [dir, feature, ...ids] = rest;
4228
+ if (flags.plan !== true && flags.features === void 0) return [{
4229
+ feature,
4230
+ ids
4231
+ }];
4232
+ if (flags.plan === true && flags.features !== void 0) throw new Error("journey takes --plan or --features, not both");
4233
+ if (feature !== void 0) throw new Error("--plan and --features run whole features; name journey ids after one feature: journey <run> <feature> [ids...]");
4234
+ if (flags.plan === true) {
4235
+ const state = loadRun(dir);
4236
+ return planFor(workspace, state.baseRef, state.all).run.map((name) => ({
4237
+ feature: name,
4238
+ ids: []
4239
+ }));
4240
+ }
4241
+ const names = (flags.features ?? []).flatMap((list) => list.split(",")).map((name) => name.trim()).filter(Boolean);
4242
+ if (names.length === 0) throw new Error("--features names no feature");
4243
+ return names.map((name) => ({
4244
+ feature: name,
4245
+ ids: []
4246
+ }));
4247
+ }
4248
+ /**
4249
+ * Runs one feature's journeys as its own `journey` call would, and prints its
4250
+ * lines once it ends. A feature that cannot run, an unknown feature or
4251
+ * journey for one, prints its error on stderr instead.
4252
+ * @returns whether every journey it ran passed.
4253
+ */
4254
+ async function journeyFeature(workspace, dir, { feature, ids }) {
4255
+ let results;
4256
+ try {
4257
+ results = await runFeature(workspace, loadRun(dir), feature, ids);
4258
+ } catch (error) {
4259
+ process.stderr.write(`${error instanceof Error ? error.message : String(error)}\n`);
4260
+ return false;
4261
+ }
3394
4262
  for (const result of results) {
3395
- print(`${result.status} ${feature}/${result.journey}${result.reusedFrom === void 0 ? "" : ` (reuses ${result.reusedFrom}, not run again)`}`);
4263
+ print(`${result.status} ${feature}/${result.journey}${result.reusedFrom === void 0 ? ` (${seconds(result.ms)})` : ` (reuses ${result.reusedFrom}, not run again)`}`);
3396
4264
  for (const step of result.steps) for (const check of step.checks.filter((entry) => !entry.pass)) print(` ${step.name}: ${check.name} (${check.detail})`);
3397
4265
  if (result.error) print(` ${result.error.split("\n")[0]}`);
3398
4266
  if (result.notVerified) print(` ${result.notVerified}`);
3399
4267
  }
3400
- return results.every((result) => result.status === "PASS") ? 0 : 1;
4268
+ return results.every((result) => result.status === "PASS");
4269
+ }
4270
+ /**
4271
+ * Runs the features in order, each one as if by its own call: a feature
4272
+ * whose journeys fail does not stop the next, a feature reuses the PASS of a
4273
+ * journey an earlier one ran, and `process.env` is restored after each
4274
+ * feature. An uncaught error a journey leaves behind (a timer that throws, a
4275
+ * rejection nobody awaits) ends the call, as it would end a single call, and
4276
+ * names the features that did not run. Module-level state a repository's
4277
+ * verify.config.ts keeps is shared by the features of one call. This loop is
4278
+ * the one place a capped number of features would run at once.
4279
+ * @returns 1 when any feature had a journey that did not pass or could not run, else 0.
4280
+ */
4281
+ async function runJourneys(workspace, dir, runs) {
4282
+ let current = 0;
4283
+ const abort = (message) => {
4284
+ const left = runs.slice(current + 1).map((run) => run.feature);
4285
+ process.stderr.write(`${runs[current]?.feature ?? "journey"}: a journey left an uncaught error: ${message}\n${left.length > 0 ? `not run: ${left.join(", ")}\n` : ""}`);
4286
+ process.exit(1);
4287
+ };
4288
+ const onError = (error) => abort(error.message);
4289
+ const onRejection = (reason) => abort(reason instanceof Error ? reason.message : String(reason));
4290
+ process.on("uncaughtException", onError);
4291
+ process.on("unhandledRejection", onRejection);
4292
+ const env = { ...process.env };
4293
+ let passed = true;
4294
+ for (; current < runs.length; current++) {
4295
+ passed = await journeyFeature(workspace, dir, runs[current]) && passed;
4296
+ restoreEnv(env);
4297
+ }
4298
+ process.off("uncaughtException", onError);
4299
+ process.off("unhandledRejection", onRejection);
4300
+ return passed ? 0 : 1;
4301
+ }
4302
+ /** Puts `process.env` back to `saved`, so a journey that set a variable leaves the next feature the environment its own call would have. */
4303
+ function restoreEnv(saved) {
4304
+ for (const key of Object.keys(process.env)) if (!Object.hasOwn(saved, key)) delete process.env[key];
4305
+ Object.assign(process.env, saved);
3401
4306
  }
3402
4307
  function runFormal(workspace, dir, all) {
3403
4308
  const state = loadRun(dir);
@@ -3454,7 +4359,12 @@ async function main(argv) {
3454
4359
  },
3455
4360
  pr: { type: "string" },
3456
4361
  all: { type: "boolean" },
3457
- kind: { type: "string" }
4362
+ kind: { type: "string" },
4363
+ plan: { type: "boolean" },
4364
+ features: {
4365
+ type: "string",
4366
+ multiple: true
4367
+ }
3458
4368
  }
3459
4369
  });
3460
4370
  const [command, ...rest] = positionals;
@@ -3463,6 +4373,8 @@ async function main(argv) {
3463
4373
  return 0;
3464
4374
  }
3465
4375
  const root = repositoryRoot();
4376
+ const path = withLocalBins(root, process.env.PATH);
4377
+ if (path !== void 0) process.env.PATH = path;
3466
4378
  const workspace = await openWorkspace(root, detectKind(root, values.kind));
3467
4379
  if (command === "new") print((await createRun(workspace, values.base, values.title, values.all === true)).dir);
3468
4380
  else if (command === "map") return printMap(workspace);
@@ -3474,7 +4386,7 @@ async function main(argv) {
3474
4386
  const lines = doctor(workspace, loadRun(rest[0]));
3475
4387
  for (const line of lines) print(`${line.ok ? "ok " : "FAIL"} ${line.check}: ${line.detail}`);
3476
4388
  return lines.every((line) => line.ok) ? 0 : 1;
3477
- } else if (command === "journey") return runJourneys(workspace, rest[0], rest[1], rest.slice(2));
4389
+ } else if (command === "journey") return runJourneys(workspace, rest[0], featureRuns(workspace, rest, values));
3478
4390
  else if (command === "formal") return runFormal(workspace, rest[0], values.all === true);
3479
4391
  else if (command === "doors") return printDoors(workspace, rest[0] ? patchFiles(rest[0]) : planFor(workspace, values.base).changed);
3480
4392
  else if (command === "clean") for (const line of clean(loadRun(rest[0]))) print(line);