@antelopejs/tooling-configs 0.4.1 → 0.5.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (41) hide show
  1. package/README.md +68 -29
  2. package/dist/bin/api-diff.mjs +235 -37
  3. package/dist/bin/body-check.mjs +14 -11
  4. package/dist/bin/capture.mjs +173 -54
  5. package/dist/bin/check-size.mjs +1 -1
  6. package/dist/bin/checks.mjs +166 -11
  7. package/dist/bin/comment-proof.mjs +29 -7
  8. package/dist/bin/garden.mjs +8 -58
  9. package/dist/bin/lease.mjs +48 -11
  10. package/dist/bin/ratchet.mjs +48 -14
  11. package/dist/bin/suppressions.mjs +3 -3
  12. package/dist/bin/sync.mjs +199 -80
  13. package/dist/bin/verify.mjs +1163 -474
  14. package/dist/capture/index.d.mts +6 -1
  15. package/dist/capture/index.mjs +1 -1
  16. package/dist/{ci-workflow-37qJa9LX.mjs → ci-workflow-COJUT12b.mjs} +121 -1
  17. package/dist/eslint.d.mts +16 -3
  18. package/dist/eslint.mjs +21 -6
  19. package/dist/formal/index.d.mts +20 -4
  20. package/dist/formal/index.mjs +71 -19
  21. package/dist/{map-B23_WMGE.mjs → map-DRyYz_Fw.mjs} +20 -1
  22. package/dist/oxc/anti-slop/index.mjs +156 -421
  23. package/dist/oxc/guardrails/index.d.mts +1 -1
  24. package/dist/oxc/guardrails/index.mjs +789 -103
  25. package/dist/oxc/lint.d.mts +13 -15
  26. package/dist/oxc/lint.mjs +19 -29
  27. package/dist/{package-CqqBgE8Y.mjs → package-Dn7VTFUW.mjs} +71 -17
  28. package/dist/{proof-stamp-DDDC0J6l.mjs → proof-stamp-DLWpPwQE.mjs} +72 -10
  29. package/dist/{ratchet-Q-JXuZIX.mjs → ratchet-ClfblHNJ.mjs} +18 -15
  30. package/dist/require-safety-comment-for-type-assertion-mnb0CIxa.mjs +181 -0
  31. package/dist/{scenes-DZVXkcxS.mjs → scenes-d-VQ0LOm.mjs} +4 -1
  32. package/dist/semver-BDxeEcP_.mjs +57 -0
  33. package/dist/{suppression-base-9L8dlMQK.mjs → suppression-base-Drnl6Y7F.mjs} +2 -2
  34. package/dist/{suppression-budget-C0SkPO5R.mjs → suppression-budget-Dvb_IqBo.mjs} +1 -1
  35. package/dist/{suppressions-DM60NkvL.mjs → suppressions-BroaaGJ_.mjs} +1 -1
  36. package/dist/{templates-BKZv-BRw.mjs → templates-lJBZFskp.mjs} +8 -3
  37. package/dist/type-aware-rules-DMuN6sHb.mjs +30 -0
  38. package/dist/{typescript-DAgQIAAR.mjs → typescript-BBbry7uU.mjs} +123 -27
  39. package/dist/verify/index.d.mts +60 -15
  40. package/package.json +3 -1
  41. package/dist/require-safety-comment-for-type-assertion-BBQ669kj.mjs +0 -83
@@ -1,10 +1,10 @@
1
1
  #!/usr/bin/env node
2
- import { c as object, f as parseJson, m as strings, r as flag, t as child, u as optStr } from "../json-CG2L7YFl.mjs";
3
- import { n as parseScenes, r as selectScenes } from "../scenes-DZVXkcxS.mjs";
2
+ import { a as isString, c as object, f as parseJson, i as isObject, m as strings, r as flag, t as child, u as optStr } from "../json-CG2L7YFl.mjs";
3
+ import { n as parseScenes, r as selectScenes } from "../scenes-d-VQ0LOm.mjs";
4
4
  import { n as runCliAsync } from "../cli-4Tv71vYk.mjs";
5
5
  import { c as repositoryRoot } from "../files-DJ0TeaTU.mjs";
6
- import { existsSync, mkdirSync, mkdtempSync, readFileSync, readdirSync, rmSync, writeFileSync } from "node:fs";
7
- import { dirname, join } from "node:path";
6
+ import { cpSync, existsSync, mkdirSync, mkdtempSync, readFileSync, readdirSync, rmSync, writeFileSync } from "node:fs";
7
+ import { dirname, join, relative } from "node:path";
8
8
  import { execFileSync, spawn, spawnSync } from "node:child_process";
9
9
  import { parse as parse$1, stringify } from "yaml";
10
10
  import { pathToFileURL } from "node:url";
@@ -52,30 +52,38 @@ function demoEnvironment(options) {
52
52
  DMS_CLIENT_BASE_URL: `http://localhost:${options.port}`
53
53
  };
54
54
  }
55
- function manifestName(dir) {
55
+ function publishedPackage(folder) {
56
56
  try {
57
- const manifest = object(parseJson(readFileSync(join(dir, "package.json"), "utf8")), "package.json");
58
- return flag(manifest, "private") ? void 0 : optStr(manifest, "name");
57
+ const manifest = object(parseJson(readFileSync(join(folder, "package.json"), "utf8")), "package.json");
58
+ const name = optStr(manifest, "name");
59
+ if (flag(manifest, "private") || name === void 0) return void 0;
60
+ return {
61
+ name,
62
+ folder,
63
+ manifest
64
+ };
59
65
  } catch {
60
66
  return;
61
67
  }
62
68
  }
63
- /**
64
- * The pnpm overrides that make a checkout of the demo run the capturing repository's own packages:
65
- * every published package of `root` (the root itself and each `packages/*` folder) mapped to its folder.
66
- */
67
- function packageOverrides(root) {
69
+ /** Every published package of `root`: the root itself, then each `packages/*` folder in name order, private ones left out. */
70
+ function publishedPackages(root) {
68
71
  const folders = [root];
69
72
  try {
70
- for (const entry of readdirSync(join(root, "packages"), { withFileTypes: true })) if (entry.isDirectory()) folders.push(join(root, "packages", entry.name));
73
+ const entries = readdirSync(join(root, "packages"), { withFileTypes: true });
74
+ for (const entry of entries.sort((a, b) => a.name.localeCompare(b.name))) if (entry.isDirectory()) folders.push(join(root, "packages", entry.name));
71
75
  } catch {
72
76
  folders.length = 1;
73
77
  }
78
+ return folders.flatMap((folder) => publishedPackage(folder) ?? []);
79
+ }
80
+ /**
81
+ * The pnpm overrides that make a checkout of the demo run the capturing repository's own packages:
82
+ * every published package of `root` mapped to its folder.
83
+ */
84
+ function packageOverrides(root) {
74
85
  const overrides = {};
75
- for (const folder of folders) {
76
- const name = manifestName(folder);
77
- if (name !== void 0) overrides[name] = `file:${folder}`;
78
- }
86
+ for (const { name, folder } of publishedPackages(root)) overrides[name] = `file:${folder}`;
79
87
  return overrides;
80
88
  }
81
89
  /**
@@ -209,10 +217,11 @@ const READY = {
209
217
  quietMs: 500,
210
218
  pollMs: 50
211
219
  };
212
- /** A browser that opens every scene dark, with the clock frozen on the demo's instant, at 2x. */
213
- async function openContext(browser, viewport) {
220
+ /** A browser that opens every scene dark, with the clock frozen on the demo's instant, at 2x, seeded with `session` when given. */
221
+ async function openContext(browser, viewport, session) {
214
222
  const context = await browser.newContext({
215
223
  viewport,
224
+ ...session && { storageState: session },
216
225
  deviceScaleFactor: DEVICE_SCALE_FACTOR,
217
226
  colorScheme: "dark",
218
227
  reducedMotion: "reduce",
@@ -305,6 +314,15 @@ async function renderScene(context, baseUrl, scene) {
305
314
  await page.close();
306
315
  }
307
316
  }
317
+ /** The scenes' browser on Playwright, against the demo at `baseUrl`. */
318
+ function playwrightScenes(browser, baseUrl) {
319
+ return {
320
+ open: (viewport, session) => openContext(browser, viewport, session),
321
+ save: (context) => context.storageState({ indexedDB: true }),
322
+ render: (context, scene) => renderScene(context, baseUrl, scene),
323
+ close: (context) => context.close()
324
+ };
325
+ }
308
326
  /** Lossless WebP, so decoding what was written gives back the pixels that were captured. */
309
327
  function encodeWebp(sharp, png) {
310
328
  return sharp(png).webp({ lossless: true }).toBuffer();
@@ -318,6 +336,105 @@ async function decode(sharp, image) {
318
336
  };
319
337
  }
320
338
  //#endregion
339
+ //#region src/capture/built.ts
340
+ const ENTRY_FIELDS = [
341
+ "main",
342
+ "module",
343
+ "types",
344
+ "typings",
345
+ "bin",
346
+ "exports"
347
+ ];
348
+ function targets(value) {
349
+ if (value === void 0) return [];
350
+ if (isString(value)) return value.includes("*") ? [] : [value];
351
+ if (Array.isArray(value)) return value.flatMap(targets);
352
+ return isObject(value) ? Object.values(value).flatMap(targets) : [];
353
+ }
354
+ /**
355
+ * The entry files the published packages of `root` declare in `package.json` and lack on disk, one
356
+ * `<package>: <path from root> is missing` line each. Wildcard export patterns are not checked.
357
+ */
358
+ function missingBuildOutput(root) {
359
+ return publishedPackages(root).flatMap(({ name, folder, manifest }) => {
360
+ const declared = ENTRY_FIELDS.flatMap((field) => Object.hasOwn(manifest, field) ? targets(manifest[field]) : []);
361
+ return [...new Set(declared.map((target) => join(folder, target)))].filter((path) => !existsSync(path)).map((path) => `${name}: ${relative(root, path)} is missing`);
362
+ });
363
+ }
364
+ /** Throws, naming each missing entry file, when the module the demo would run is not built. */
365
+ function assertBuilt(root) {
366
+ const missing = missingBuildOutput(root);
367
+ if (missing.length === 0) return;
368
+ throw new Error([
369
+ "the module is not built, so the demo would load it without its build output:",
370
+ ...missing.map((line) => ` ${line}`),
371
+ "Run pnpm run build first."
372
+ ].join("\n"));
373
+ }
374
+ //#endregion
375
+ //#region src/capture/logs.ts
376
+ /**
377
+ * Copies the logs the demo's `capture:start` writes under `.antelope/capture` out of the checkout, which a run
378
+ * deletes, into a new temporary directory. Answers the line that names it, or nothing when the demo wrote no log.
379
+ */
380
+ function keepDemoLogs(demo) {
381
+ const logs = join(demo, ".antelope", "capture");
382
+ if (!existsSync(logs)) return [];
383
+ const kept = mkdtempSync(join(tmpdir(), "antelopejs-capture-logs-"));
384
+ cpSync(logs, kept, { recursive: true });
385
+ return [`the demo logs are kept in ${kept}`];
386
+ }
387
+ //#endregion
388
+ //#region src/capture/play.ts
389
+ /** Runs one scene's work and answers its failure line, if it has one. */
390
+ async function failureIn(scene, work) {
391
+ try {
392
+ return await work();
393
+ } catch (error) {
394
+ const reason = error instanceof Error ? error.message : String(error);
395
+ return `scene ${scene.id}: ${reason.split("\n")[0]}`;
396
+ }
397
+ }
398
+ /** Plays the setup scenes in one context and answers the session they leave, or none without setup scenes. */
399
+ async function setUp(browser, scenes, failures) {
400
+ const [first] = scenes;
401
+ if (first === void 0) return void 0;
402
+ const context = await browser.open(first.viewport, void 0);
403
+ try {
404
+ for (const scene of scenes) {
405
+ const failure = await failureIn(scene, async () => {
406
+ await browser.render(context, scene);
407
+ });
408
+ if (failure !== void 0) failures.push(failure);
409
+ }
410
+ return await browser.save(context);
411
+ } finally {
412
+ await browser.close(context);
413
+ }
414
+ }
415
+ /**
416
+ * Plays the setup scenes in one context, then each screenshot scene in a fresh context seeded with the
417
+ * session the setup left, or empty when the scene is `signedOut`, so no scene sees what another changed.
418
+ * Answers the failures, one line per scene.
419
+ */
420
+ async function playScenes(browser, scenes, keep) {
421
+ const failures = [];
422
+ const session = await setUp(browser, scenes.filter((scene) => scene.setup), failures);
423
+ for (const scene of scenes.filter((each) => !each.setup)) {
424
+ const failure = await failureIn(scene, async () => {
425
+ const context = await browser.open(scene.viewport, scene.signedOut ? void 0 : session);
426
+ try {
427
+ const png = await browser.render(context, scene);
428
+ return png === void 0 ? void 0 : await keep(scene, png);
429
+ } finally {
430
+ await browser.close(context);
431
+ }
432
+ });
433
+ if (failure !== void 0) failures.push(failure);
434
+ }
435
+ return failures;
436
+ }
437
+ //#endregion
321
438
  //#region src/capture/compare.ts
322
439
  /** The share of pixels that may differ before a capture counts as changed: 0.1%. */
323
440
  const MAX_CHANGED_RATIO = .001;
@@ -431,8 +548,7 @@ function run(command, args, cwd) {
431
548
  throw new Error(`${command} ${args.join(" ")} failed in ${cwd}\n${output.slice(-20).join("\n")}`);
432
549
  }
433
550
  /** A checkout of the demo whose dependencies on this repository's packages are overridden to the working tree. Never committed: it lives in a throwaway directory. */
434
- function checkoutDemo(root, ref, into) {
435
- const demo = join(into, "demo");
551
+ function checkoutDemo(root, ref, demo) {
436
552
  run("git", [
437
553
  "clone",
438
554
  "--quiet",
@@ -442,7 +558,7 @@ function checkoutDemo(root, ref, into) {
442
558
  ref,
443
559
  process.env.ANTELOPEJS_CAPTURE_DEMO_URL ?? DEMO_URL,
444
560
  demo
445
- ], into);
561
+ ], dirname(demo));
446
562
  const manifestPath = join(demo, "package.json");
447
563
  const manifest = object(parseJson(readFileSync(manifestPath, "utf8")), "package.json");
448
564
  const workspacePath = join(demo, "pnpm-workspace.yaml");
@@ -454,7 +570,6 @@ function checkoutDemo(root, ref, into) {
454
570
  writeFileSync(manifestPath, `${JSON.stringify(patched, null, 2)}\n`);
455
571
  writeFileSync(workspacePath, settings.workspace);
456
572
  run("pnpm", ["install", "--no-frozen-lockfile"], demo);
457
- return demo;
458
573
  }
459
574
  /** Starts the demo's capture script and resolves with its URL once the script prints `ready <url>`. */
460
575
  function startDemo(demo, env) {
@@ -489,37 +604,20 @@ function startDemo(demo, env) {
489
604
  });
490
605
  });
491
606
  }
492
- async function captureAll(session, scenes) {
493
- const failures = [];
494
- const first = scenes[0];
495
- const context = await openContext(session.browser, first?.viewport ?? {
496
- width: 1440,
497
- height: 900
498
- });
499
- for (const scene of scenes) try {
500
- const png = await renderScene(context, session.url, scene);
501
- if (png === void 0 || scene.output === void 0) continue;
502
- const failure = await settle(sharp, session.root, session.check, {
503
- scene: scene.id,
504
- output: scene.output,
505
- png
506
- });
507
- if (failure !== void 0) failures.push(failure);
508
- } catch (error) {
509
- const reason = error instanceof Error ? error.message : String(error);
510
- failures.push(`scene ${scene.id}: ${reason.split("\n")[0]}`);
511
- }
512
- await context.close();
513
- return failures;
607
+ function captureAll(session, scenes) {
608
+ return playScenes(playwrightScenes(session.browser, session.url), scenes, (scene, png) => scene.output === void 0 ? Promise.resolve(void 0) : settle(sharp, session.root, session.check, {
609
+ scene: scene.id,
610
+ output: scene.output,
611
+ png
612
+ }));
514
613
  }
515
- /** Runs the scenes against the demo and writes, or with `check` compares, their WebP files. Answers the failures, one line per scene. */
516
- async function capture(root, args) {
517
- const scenes = selectScenes(loadScenes(root), args.scene);
518
- const scratch = mkdtempSync(join(tmpdir(), "antelopejs-capture-"));
614
+ /** Checks the demo out into `checkout`, starts it on an empty MongoDB and captures the scenes, then stops both. */
615
+ async function captureFromDemo(root, args, scenes, checkout) {
519
616
  const mongo = await MongoMemoryServer.create();
520
617
  let demo;
521
618
  try {
522
- const started = await startDemo(checkoutDemo(root, args.demoRef, scratch), demoEnvironment({
619
+ checkoutDemo(root, args.demoRef, checkout);
620
+ const started = await startDemo(checkout, demoEnvironment({
523
621
  mongoUrl: mongo.getUri(),
524
622
  database: "docs_captures",
525
623
  port: DEMO_PORT
@@ -539,15 +637,36 @@ async function capture(root, args) {
539
637
  } finally {
540
638
  try {
541
639
  if (demo) await stopProcessGroup(demo, STOP);
542
- rmSync(scratch, {
543
- recursive: true,
544
- force: true
545
- });
546
640
  } finally {
547
641
  await mongo.stop();
548
642
  }
549
643
  }
550
644
  }
645
+ /**
646
+ * Runs the scenes against the demo and writes, or with `check` compares, their WebP files. Answers the failures,
647
+ * one line per scene. Refuses a module whose build output is missing before it starts anything. On a failure the
648
+ * demo's logs outlive the deleted checkout, and the failures or the error name where they are.
649
+ */
650
+ async function capture(root, args) {
651
+ const scenes = selectScenes(loadScenes(root), args.scene);
652
+ assertBuilt(root);
653
+ const scratch = mkdtempSync(join(tmpdir(), "antelopejs-capture-"));
654
+ const checkout = join(scratch, "demo");
655
+ try {
656
+ const failures = await captureFromDemo(root, args, scenes, checkout);
657
+ return failures.length ? [...failures, ...keepDemoLogs(checkout)] : [];
658
+ } catch (error) {
659
+ const kept = keepDemoLogs(checkout);
660
+ if (kept.length === 0) throw error;
661
+ const reason = error instanceof Error ? error.message : String(error);
662
+ throw new Error([reason, ...kept].join("\n"), { cause: error });
663
+ } finally {
664
+ rmSync(scratch, {
665
+ recursive: true,
666
+ force: true
667
+ });
668
+ }
669
+ }
551
670
  //#endregion
552
671
  //#region src/bin/capture.ts
553
672
  runCliAsync(async () => {
@@ -1,7 +1,7 @@
1
1
  #!/usr/bin/env node
2
2
  import { t as runCli } from "../cli-4Tv71vYk.mjs";
3
3
  import { c as repositoryRoot, n as authoredSizes, s as repositoryPath } from "../files-DJ0TeaTU.mjs";
4
- import { l as worktreeSuppressions, o as revisionSuppressions } from "../suppressions-DM60NkvL.mjs";
4
+ import { l as worktreeSuppressions, o as revisionSuppressions } from "../suppressions-BroaaGJ_.mjs";
5
5
  import { t as checkSize } from "../size-DBatLT-F.mjs";
6
6
  import { resolve } from "node:path";
7
7
  import { parseArgs } from "node:util";
@@ -1,14 +1,14 @@
1
1
  #!/usr/bin/env node
2
2
  import { t as CEILINGS_FILE } from "../ceilings-B7KayYIG.mjs";
3
- import { i as parseManifest, r as packageManager } from "../package-CqqBgE8Y.mjs";
3
+ import { a as parseManifest, i as packageManager } from "../package-Dn7VTFUW.mjs";
4
4
  import { n as runCliAsync } from "../cli-4Tv71vYk.mjs";
5
- import { c as repositoryRoot } from "../files-DJ0TeaTU.mjs";
5
+ import { a as gitFiles, c as repositoryRoot } from "../files-DJ0TeaTU.mjs";
6
6
  import { t as accepting } from "../ports-DGP6bPJy.mjs";
7
7
  import { createRequire } from "node:module";
8
8
  import { existsSync, mkdtempSync, readFileSync, readdirSync, rmSync, writeFileSync } from "node:fs";
9
9
  import { basename, dirname, join, posix, relative, resolve, sep } from "node:path";
10
10
  import { spawn } from "node:child_process";
11
- import { isMap, isScalar, isSeq, parseDocument } from "yaml";
11
+ import { isMap, isScalar, isSeq, parseAllDocuments, parseDocument } from "yaml";
12
12
  import { createHash } from "node:crypto";
13
13
  import { tmpdir } from "node:os";
14
14
  import { parseArgs } from "node:util";
@@ -76,6 +76,37 @@ function runCommand(command, args, options) {
76
76
  });
77
77
  }
78
78
  //#endregion
79
+ //#region src/guardrails/git-identity.ts
80
+ /** Config scopes stored inside the repository, which every checkout and agent sharing it commits under. */
81
+ const SHARED_SCOPES = /* @__PURE__ */ new Set(["local", "worktree"]);
82
+ /** Whether `root` is a git checkout, a `.git` folder or a linked worktree's `.git` file. */
83
+ function isGitCheckout(root) {
84
+ return existsSync(join(root, ".git"));
85
+ }
86
+ /**
87
+ * Fails when the repository's own git config, its `.git/config` shared by every worktree or a worktree's
88
+ * `config.worktree`, sets `user.name` or `user.email`: whoever commits in any checkout of it then signs as that identity.
89
+ * Global, system and command-line settings pass. Returns what failed, naming each file and value, empty when it passed.
90
+ */
91
+ async function checkGitIdentity(root, signal) {
92
+ const result = await runCommand("git", [
93
+ "config",
94
+ "--show-scope",
95
+ "--show-origin",
96
+ "--get-regexp",
97
+ String.raw`^user\.(name|email)$`
98
+ ], {
99
+ cwd: root,
100
+ signal,
101
+ shell: false
102
+ });
103
+ if (result.status === 1) return "";
104
+ if (result.status !== 0) return result.output;
105
+ const shared = result.stdout.split("\n").filter((line) => SHARED_SCOPES.has(line.split(" ")[0] ?? ""));
106
+ if (!shared.length) return "";
107
+ return `The repository's git config sets a commit identity, so every checkout and agent sharing it commits as that identity:\n${shared.map((line) => ` ${line.split(" ").slice(1).join(" ")}\n`).join("")}Remove it with git config --local --unset-all user.name and git config --local --unset-all user.email (--worktree for a config.worktree), and set an identity with --global or per command with git -c.\n`;
108
+ }
109
+ //#endregion
79
110
  //#region src/guardrails/services.ts
80
111
  /** The compose file the shared CI starts through its `services-compose-file` input, relative to the repository root. */
81
112
  const COMPOSE_FILE = ".github/compose.yml";
@@ -303,7 +334,7 @@ async function typecheckLayers(root, signal) {
303
334
  //#region src/guardrails/verify-lockfiles.ts
304
335
  /** The folder a repository's playground lives in; verify installs a fixture project from it. */
305
336
  const PLAYGROUND = "playground";
306
- const PNPM_LOCK = "pnpm-lock.yaml";
337
+ const PNPM_LOCK$1 = "pnpm-lock.yaml";
307
338
  const NPM_LOCK = "package-lock.json";
308
339
  const MANIFEST = "package.json";
309
340
  const PNPM_WORKSPACE = "pnpm-workspace.yaml";
@@ -320,6 +351,7 @@ const DIRECT_FIELDS = [
320
351
  "devDependencies",
321
352
  "optionalDependencies"
322
353
  ];
354
+ /** A lockfile or manifest this check cannot read as a version it knows. */
323
355
  var Unreadable = class extends Error {};
324
356
  /** Parses a JSON or YAML file whose top level is a mapping; throws `Unreadable` otherwise. */
325
357
  function readMapping(path) {
@@ -331,14 +363,17 @@ function readMapping(path) {
331
363
  if (document.errors.length > 0 || !isMap(contents)) throw new Unreadable(path);
332
364
  return contents;
333
365
  }
366
+ /** The mapping under `key`; `undefined` when absent or not a mapping. */
334
367
  function mapping(map, key) {
335
368
  const value = map?.get(key, true);
336
369
  return isMap(value) ? value : void 0;
337
370
  }
371
+ /** The source text of the scalar under `key`; `undefined` when absent or not a scalar. */
338
372
  function scalar(map, key) {
339
373
  const value = map?.get(key, true);
340
374
  return isScalar(value) ? String(value.value) : void 0;
341
375
  }
376
+ /** The scalar keys of a mapping, in order; none when it is absent. */
342
377
  function keys(map) {
343
378
  return (map?.items ?? []).flatMap((pair) => isScalar(pair.key) ? [String(pair.key.value)] : []);
344
379
  }
@@ -385,7 +420,7 @@ function overrideNames(selector) {
385
420
  return selector.split(">").flatMap((segment) => /^(?:@[^/@]+\/)?[^@]+/u.exec(segment) ?? []);
386
421
  }
387
422
  function pnpmDifferences(path) {
388
- const lockfile = readMapping(join(path, PNPM_LOCK));
423
+ const lockfile = readMapping(join(path, PNPM_LOCK$1));
389
424
  if (Number(scalar(lockfile, "lockfileVersion") ?? "0") < 6) throw new Unreadable(path);
390
425
  const overridden = new Set(keys(mapping(lockfile, "overrides")).flatMap(overrideNames));
391
426
  const linksLeftOut = scalar(mapping(lockfile, "settings"), "excludeLinksFromLockfile") === "true";
@@ -407,7 +442,7 @@ function npmDifferences(path) {
407
442
  return differences(readMapping(manifest), declared(rootEntry), () => false);
408
443
  }
409
444
  function lockfileIn(path) {
410
- if (existsSync(join(path, PNPM_LOCK))) return PNPM_LOCK;
445
+ if (existsSync(join(path, PNPM_LOCK$1))) return PNPM_LOCK$1;
411
446
  if (existsSync(join(path, NPM_LOCK))) return NPM_LOCK;
412
447
  return OTHER_LOCKS.some((name) => existsSync(join(path, name))) ? "other" : void 0;
413
448
  }
@@ -481,7 +516,7 @@ function fixCommand(root, folder, lockfile) {
481
516
  }
482
517
  function unlocked(root, folder) {
483
518
  if (inWorkspace(root, folder)) return "";
484
- const manager = ancestors(folder).some((above) => existsSync(join(root, above, NPM_LOCK))) ? NPM_LOCK : PNPM_LOCK;
519
+ const manager = ancestors(folder).some((above) => existsSync(join(root, above, NPM_LOCK))) ? NPM_LOCK : PNPM_LOCK$1;
485
520
  return `${folder}/${MANIFEST} has dependencies and no lockfile: run \`${fixCommand(root, folder, manager)}\`.\n`;
486
521
  }
487
522
  function checkFolder(root, { folder, lockfile }) {
@@ -489,7 +524,7 @@ function checkFolder(root, { folder, lockfile }) {
489
524
  try {
490
525
  if (lockfile === void 0) return unlocked(root, folder);
491
526
  const path = join(root, folder);
492
- const found = lockfile === PNPM_LOCK ? pnpmDifferences(path) : npmDifferences(path);
527
+ const found = lockfile === PNPM_LOCK$1 ? pnpmDifferences(path) : npmDifferences(path);
493
528
  return found.length === 0 ? "" : `${folder}/${lockfile} does not match ${folder}/${MANIFEST}: run \`${fixCommand(root, folder, lockfile)}\`.\n${found.map((line) => ` ${line}\n`).join("")}`;
494
529
  } catch (error) {
495
530
  if (error instanceof Unreadable) return `${folder}/${lockfile ?? MANIFEST}: could not read it, or a ${MANIFEST} it locks, as a version this check knows.\n`;
@@ -515,6 +550,89 @@ function checkLockfiles(root) {
515
550
  return verifyInstallFolders(root).map((install) => checkFolder(root, install)).join("");
516
551
  }
517
552
  //#endregion
553
+ //#region src/guardrails/singleton-packages.ts
554
+ const PNPM_LOCK = "pnpm-lock.yaml";
555
+ /** Packages one process must load once: every AntelopeJS interface package shares one runtime with its peers. */
556
+ const SINGLETON = /^@antelopejs\/interface-/u;
557
+ /** The fields of a lockfile package entry that point at the copy each dependency resolves to. */
558
+ const PACKAGE_FIELDS = ["dependencies", "optionalDependencies"];
559
+ /** How to move every importer onto one copy while pnpm keeps every other locked version, which `pnpm dedupe` does not. */
560
+ const REPAIR = " Set the direct specifier that locks the older copy to the newer version, run `pnpm install --lockfile-only`, then restore the specifier.\n";
561
+ /** A `name@version` key or a resolved version without its peer suffix, `(peer@1)`, which names no other copy. */
562
+ function withoutPeers(reference) {
563
+ const open = reference.indexOf("(");
564
+ return open === -1 ? reference : reference.slice(0, open);
565
+ }
566
+ /** The name and version of a `packages` key: `@scope/name@1.0.0` in version 9, `/@scope/name@1.0.0` in version 6. */
567
+ function packageKey(key) {
568
+ const match = /^\/?((?:@[^/@]+\/)?[^@]+)@(.+)$/u.exec(withoutPeers(key));
569
+ return match?.[1] && match[2] ? {
570
+ name: match[1],
571
+ version: match[2]
572
+ } : void 0;
573
+ }
574
+ /** Records `by` as a puller of the copy a dependency resolves to: `version`, or the `name@version` an `npm:` alias resolves to. */
575
+ function pull(copies, name, version, by) {
576
+ if (version === void 0) return;
577
+ const alias = packageKey(version);
578
+ const target = alias && copies.has(alias.name) ? alias : {
579
+ name,
580
+ version: withoutPeers(version)
581
+ };
582
+ copies.get(target.name)?.get(target.version)?.add(by);
583
+ }
584
+ function addPullers(copies, node, fields, by) {
585
+ for (const field of fields) {
586
+ const entries = mapping(node, field);
587
+ for (const name of keys(entries)) pull(copies, name, scalar(entries, name) ?? scalar(mapping(entries, name), "version"), by);
588
+ }
589
+ }
590
+ /** Each document of a lockfile: pnpm 11 writes its config dependencies, installed apart from the project, as a document before the project's. */
591
+ function lockfileDocuments(path) {
592
+ return parseAllDocuments(readFileSync(path, "utf8"), {
593
+ schema: "failsafe",
594
+ uniqueKeys: false
595
+ }).map((document) => {
596
+ const { contents } = document;
597
+ if (document.errors.length > 0 || !isMap(contents) || !(Number.parseFloat(scalar(contents, "lockfileVersion") ?? "") >= 6)) throw new Unreadable(path);
598
+ return contents;
599
+ });
600
+ }
601
+ function documentCopies(lockfile) {
602
+ const copies = /* @__PURE__ */ new Map();
603
+ const packages = mapping(lockfile, "packages");
604
+ for (const parsed of keys(packages).map(packageKey)) if (parsed && SINGLETON.test(parsed.name)) copies.set(parsed.name, (copies.get(parsed.name) ?? /* @__PURE__ */ new Map()).set(parsed.version, /* @__PURE__ */ new Set()));
605
+ const importers = mapping(lockfile, "importers");
606
+ for (const importer of importers ? keys(importers) : ["."]) addPullers(copies, importers ? mapping(importers, importer) : lockfile, DIRECT_FIELDS, `importer "${importer}"`);
607
+ const resolved = mapping(lockfile, "snapshots") ?? packages;
608
+ for (const key of keys(resolved)) addPullers(copies, mapping(resolved, key), PACKAGE_FIELDS, withoutPeers(key.replace(/^\//u, "")));
609
+ return copies;
610
+ }
611
+ function report(file, copies) {
612
+ return [...copies].filter(([, versions]) => versions.size > 1).map(([name, versions]) => `${file} resolves "${name}" at ${versions.size} versions, and an interface package must load once:\n${[...versions].map(([version, by]) => ` ${version}, pulled by ${[...by].join(", ") || "nothing"}\n`).join("")}${REPAIR}`).join("");
613
+ }
614
+ /** The `pnpm-lock.yaml` files on disk in the repository, tracked or not yet added, outside what `.gitignore` leaves out. */
615
+ function pnpmLockfiles(root) {
616
+ return gitFiles(root).filter((file) => (file === PNPM_LOCK || file.endsWith(`/${PNPM_LOCK}`)) && existsSync(join(root, file)));
617
+ }
618
+ /**
619
+ * Fails when a `pnpm-lock.yaml` of the repository resolves an AntelopeJS interface package, any `@antelopejs/interface-*`,
620
+ * at more than one version: each copy carries its own runtime, so two copies in one process break the contract between
621
+ * modules, or throw on a runtime protocol mismatch. Names, for each version, the importers and packages that pull it.
622
+ * Reads the lockfiles only: it spawns no package manager, writes no file and fetches nothing. Returns what failed, empty
623
+ * when every interface package resolves once.
624
+ */
625
+ function checkSingletonPackages(root) {
626
+ return pnpmLockfiles(root).map((file) => {
627
+ try {
628
+ return lockfileDocuments(join(root, file)).map((document) => report(file, documentCopies(document))).join("");
629
+ } catch (error) {
630
+ if (error instanceof Unreadable) return `${file}: could not read it as a lockfile version this check knows.\n`;
631
+ throw error;
632
+ }
633
+ }).join("");
634
+ }
635
+ //#endregion
518
636
  //#region src/guardrails/checks.ts
519
637
  const CHECK_STEPS = [
520
638
  "typecheck",
@@ -527,14 +645,23 @@ const CHECK_STEPS = [
527
645
  "suppressions",
528
646
  "sync:check",
529
647
  "verify:types",
530
- "verify:lockfiles"
648
+ "verify:lockfiles",
649
+ "lockfile:singletons",
650
+ "git:identity"
531
651
  ];
532
652
  /** Steps `antelopejs-checks` runs itself, no package.json script behind them: each returns what failed, empty when it passed. */
533
- const OWN_STEPS = /* @__PURE__ */ new Map([["verify:types", typecheckLayers], ["verify:lockfiles", (root) => Promise.resolve(checkLockfiles(root))]]);
653
+ const OWN_STEPS = /* @__PURE__ */ new Map([
654
+ ["verify:types", typecheckLayers],
655
+ ["verify:lockfiles", (root) => Promise.resolve(checkLockfiles(root))],
656
+ ["lockfile:singletons", (root) => Promise.resolve(checkSingletonPackages(root))],
657
+ ["git:identity", checkGitIdentity]
658
+ ]);
534
659
  function hasWork(root, step) {
535
660
  if (step === "ratchet") return existsSync(join(root, CEILINGS_FILE));
536
661
  if (step === "verify:types") return verifyLayers(root).length > 0;
537
662
  if (step === "verify:lockfiles") return verifyInstallFolders(root).length > 0;
663
+ if (step === "lockfile:singletons") return pnpmLockfiles(root).length > 0;
664
+ if (step === "git:identity") return isGitCheckout(root);
538
665
  return true;
539
666
  }
540
667
  /** The step that runs after the others, never beside them: tests often hold time limits that CPU contention would break. */
@@ -569,11 +696,37 @@ async function runSteps(root, manifest, steps, signal) {
569
696
  if (steps.includes(RUNS_ALONE)) failures.set(RUNS_ALONE, await runStep(RUNS_ALONE));
570
697
  return steps.flatMap((step) => failures.get(step) ?? []);
571
698
  }
699
+ /** The optional package script run once before the steps, to build what several steps read, such as a workspace package's `dist`. */
700
+ const PREPARE = "checks:prepare";
701
+ /** Runs `checks:prepare` when the manifest has it: the run's result when it failed or `signal` aborted it, else undefined. */
702
+ async function prepare(root, manifest, signal) {
703
+ if (!manifest.scripts?.[PREPARE]) return void 0;
704
+ const result = await runCommand(packageManager(manifest), ["run", PREPARE], {
705
+ cwd: root,
706
+ env: {
707
+ ...process.env,
708
+ CI: "1"
709
+ },
710
+ signal
711
+ });
712
+ const failure = result.status === 0 ? "" : `[${PREPARE}]\n${result.output}`;
713
+ if (signal?.aborted) return {
714
+ failed: failure ? 1 : 0,
715
+ interrupted: true,
716
+ output: `${failure}Checks interrupted by ${String(signal.reason)}.\n`
717
+ };
718
+ if (failure) return {
719
+ failed: 1,
720
+ interrupted: false,
721
+ output: `${failure}Checks: 0 passed, 1 failed.\n`
722
+ };
723
+ }
572
724
  function summary(failures, passed, skipped) {
573
725
  return `${failures.join("\n")}Checks: ${passed} passed, ${failures.length} failed${skipped ? `, ${skipped} skipped` : ""}.\n`;
574
726
  }
575
727
  /**
576
- * Runs every check step except `test` at the same time, then `test` alone, and reports only what failed, each step's
728
+ * Runs the `checks:prepare` package script first when it exists and a step will run, and stops there if it fails.
729
+ * Then runs every check step except `test` at the same time, then `test` alone, and reports only what failed, each step's
577
730
  * output buffered and listed in step order whichever step finishes first. `skipSetting` is the comma-separated value of
578
731
  * `ANTELOPEJS_CHECKS_SKIP`: the steps it names are not run and are counted as skipped, never as passed, and a name that
579
732
  * is not a step fails the run before any step starts so a typo cannot skip nothing. Unless `services` is false, the
@@ -599,6 +752,8 @@ async function runChecks(root, options = {}) {
599
752
  interrupted: false,
600
753
  output: `[services]\n${plan.output}Checks: 0 passed, 1 failed.\n`
601
754
  };
755
+ const unprepared = steps.length ? await prepare(root, manifest, signal) : void 0;
756
+ if (unprepared) return unprepared;
602
757
  const started = plan.kind === "start" ? await startServices(root, signal) : {
603
758
  failure: "",
604
759
  owned: false