@antelopejs/tooling-configs 0.6.0 → 0.7.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.
@@ -1,17 +1,20 @@
1
1
  import { t as CEILINGS_FILE } from "./ceilings-B7KayYIG.mjs";
2
2
  import { l as serializeManifest, o as packageManager, s as parseManifest } from "./package-DDG3YH7W.mjs";
3
+ import { f as parseJson } from "./json-CG2L7YFl.mjs";
3
4
  import { a as gitFiles, u as trackedManifests } from "./files-C-JJhExM.mjs";
4
5
  import { n as workspaceDirectories } from "./docs-compat-CSljVi3O.mjs";
5
6
  import { n as shimInvocation, t as runCommand } from "./run-command-BlFRPORx.mjs";
7
+ import { n as tagVersion } from "./npm-CIIqL5SG.mjs";
6
8
  import { t as accepting } from "./ports-DAeEJsYh.mjs";
7
- import { existsSync, mkdtempSync, readFileSync, readdirSync, rmSync, statSync, writeFileSync } from "node:fs";
9
+ import { existsSync, mkdirSync, mkdtempSync, readFileSync, readdirSync, realpathSync, rmSync, statSync, writeFileSync } from "node:fs";
8
10
  import { basename, dirname, join, posix, relative, resolve, sep } from "node:path";
9
11
  import { spawnSync } from "node:child_process";
10
- import { isMap, isScalar, isSeq, parseAllDocuments, parseDocument } from "yaml";
12
+ import { isMap, isScalar, isSeq, parseAllDocuments, parseDocument, stringify } from "yaml";
11
13
  import ts from "@typescript/typescript6";
12
14
  import { createHash } from "node:crypto";
13
15
  import { tmpdir } from "node:os";
14
- import { satisfies, validRange } from "semver";
16
+ import { gunzipSync } from "node:zlib";
17
+ import { validRange } from "semver";
15
18
  import { minimatch } from "minimatch";
16
19
  //#region src/guardrails/run-pnpm.ts
17
20
  /** Runs pnpm, the only manager the pack's CI installs with, with `args` quietly; returns its output only when it failed. */
@@ -39,7 +42,7 @@ function runPnpm(root, args) {
39
42
  * module whose range that copy falls outside, so a pin breaks startup at the
40
43
  * next patch release.
41
44
  */
42
- const ANTELOPEJS_SCOPE = "@antelopejs/";
45
+ const ANTELOPEJS_SCOPE$1 = "@antelopejs/";
43
46
  /** A linked folder is the copy the dependent builds against, not a release it resolves. */
44
47
  const LINK_SPEC_PREFIXES = ["file:", "link:"];
45
48
  /** pnpm replaces a `workspace:` spec with a range on the sibling's version when it publishes the package. */
@@ -138,6 +141,15 @@ function isCapped(bounds, local) {
138
141
  if (compareVersions(ceiling, nextMinor(floor)) !== 0) return false;
139
142
  return local === void 0 || compareVersions(local, floor) >= 0 && compareVersions(local, ceiling) < 0;
140
143
  }
144
+ /**
145
+ * The range to use in place of `spec` on the minor of `newest`, or `undefined` when `spec` already stops below the
146
+ * next minor of its floor and admits `newest`.
147
+ */
148
+ function cappedReplacement(spec, newest) {
149
+ const version = readFloor(newest);
150
+ if (version === void 0 || isCapped(readBounds(spec.trim()), version)) return void 0;
151
+ return cappedRange(version);
152
+ }
141
153
  function isLinkSpec(spec) {
142
154
  return LINK_SPEC_PREFIXES.some((prefix) => spec.startsWith(prefix));
143
155
  }
@@ -176,7 +188,7 @@ function checkEntry(manifest, field, [name, spec], local) {
176
188
  }
177
189
  /** Whether `manifest` declares an `@antelopejs/*` package in a field this check reads. */
178
190
  function declaresAntelopePackage(manifest) {
179
- return CHECKED_FIELDS.some((field) => Object.keys(manifest[field] ?? {}).some((name) => name.startsWith(ANTELOPEJS_SCOPE)));
191
+ return CHECKED_FIELDS.some((field) => Object.keys(manifest[field] ?? {}).some((name) => name.startsWith(ANTELOPEJS_SCOPE$1)));
180
192
  }
181
193
  /**
182
194
  * The version of each named package among `manifests`, the packages that sit
@@ -206,7 +218,7 @@ function checkDependencyRanges(manifest, localVersions = /* @__PURE__ */ new Map
206
218
  const violations = [];
207
219
  for (const field of CHECKED_FIELDS) for (const entry of Object.entries(manifest[field] ?? {})) {
208
220
  const [name, spec] = entry;
209
- if (!name.startsWith(ANTELOPEJS_SCOPE) || isLinkSpec(spec)) continue;
221
+ if (!name.startsWith(ANTELOPEJS_SCOPE$1) || isLinkSpec(spec)) continue;
210
222
  const violation = checkEntry(manifest, field, entry, localVersions.get(name));
211
223
  if (violation) violations.push(violation);
212
224
  }
@@ -326,9 +338,373 @@ async function checkGitIdentity(root, signal) {
326
338
  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`;
327
339
  }
328
340
  //#endregion
341
+ //#region src/guardrails/published-entries.ts
342
+ /** The compiler options of the consumer: the strictest a consumer commonly sets, with every declaration file it loads checked. */
343
+ const CONSUMER_OPTIONS = {
344
+ module: "nodenext",
345
+ moduleResolution: "nodenext",
346
+ target: "esnext",
347
+ strict: true,
348
+ skipLibCheck: false,
349
+ noEmit: true,
350
+ types: ["node"]
351
+ };
352
+ /** The consumer files, an ES module that imports each entry and a CommonJS module that requires it, with the resolution mode TypeScript gives each. */
353
+ const CONSUMER_FILES = {
354
+ import: {
355
+ file: "consumer.mts",
356
+ mode: ts.ModuleKind.ESNext
357
+ },
358
+ require: {
359
+ file: "consumer.cts",
360
+ mode: ts.ModuleKind.CommonJS
361
+ }
362
+ };
363
+ const DECLARATION_EXTENSIONS = /* @__PURE__ */ new Set([
364
+ ts.Extension.Dts,
365
+ ts.Extension.Dmts,
366
+ ts.Extension.Dcts
367
+ ]);
368
+ const DECLARATION_FILE$1 = /\.d\.[cm]?ts$/;
369
+ /** An `exports` value that names declarations: a `types` condition or a `.d.ts`, `.d.mts` or `.d.cts` target. */
370
+ const NAMES_DECLARATIONS = /"types"\s*:|\.d\.[cm]?ts"/;
371
+ function isPath(target) {
372
+ return typeof target === "string";
373
+ }
374
+ /** Every path a subpath's value lists, under any condition. */
375
+ function targetPaths(target) {
376
+ if (target === null) return [];
377
+ if (isPath(target)) return [target];
378
+ return (Array.isArray(target) ? target : Object.values(target)).flatMap(targetPaths);
379
+ }
380
+ /** `exports` as a map of subpaths: a path, a list or a map of conditions stands for the `.` subpath. */
381
+ function subpaths(exports) {
382
+ if (exports === null || isPath(exports) || Array.isArray(exports)) return [[".", exports]];
383
+ const entries = Object.entries(exports);
384
+ return entries.every(([key]) => key.startsWith(".")) ? entries : [[".", exports]];
385
+ }
386
+ function patternMatcher(pattern) {
387
+ const [before = "", after = ""] = pattern.split("*");
388
+ const escape = (text) => text.replace(/[.+?^${}()|[\]\\]/g, "\\$&");
389
+ return new RegExp(`^${escape(before)}(.+)${escape(after)}$`);
390
+ }
391
+ /** The subpaths a key stands for: itself, or, for a `*` key, one per shipped file a target of its value matches. */
392
+ function expanded(key, value, files) {
393
+ if (!key.includes("*")) return [key];
394
+ return targetPaths(value).flatMap((target) => {
395
+ const matcher = patternMatcher(target.replace(/^\.\//, ""));
396
+ return files.flatMap((file) => {
397
+ const star = matcher.exec(file)?.[1];
398
+ return star === void 0 ? [] : [key.replace("*", star)];
399
+ });
400
+ });
401
+ }
402
+ /** A specifier for each subpath of `exports`, with whether its value names declarations; a subpath naming a declaration file is left out, since no consumer imports one by name. */
403
+ function candidates(name, exports, files) {
404
+ const found = /* @__PURE__ */ new Map();
405
+ for (const [key, value] of subpaths(exports)) for (const subpath of expanded(key, value, files)) if (!DECLARATION_FILE$1.test(subpath)) found.set(`${name}${subpath.slice(1)}`, (found.get(`${name}${subpath.slice(1)}`) ?? false) || NAMES_DECLARATIONS.test(JSON.stringify(value)));
406
+ return found;
407
+ }
408
+ /**
409
+ * The specifiers the consumer in `consumer` imports and requires from the package `name`, given the `files` it ships
410
+ * relative to its folder. Each `exports` subpath, a `*` subpath once per shipped file a target of it matches, is kept
411
+ * for a mode when TypeScript resolves it in that mode to a declaration file, or to JavaScript while its value names
412
+ * declarations, so a declaration file missing from the tarball fails. A subpath TypeScript does not resolve, such as one
413
+ * a `null` key hides or a stylesheet, is left out. A package without `exports` is imported by its bare name.
414
+ */
415
+ function entrySpecifiers(name, exports, files, consumer) {
416
+ if (exports === void 0) return {
417
+ import: [name],
418
+ require: []
419
+ };
420
+ const { options } = ts.convertCompilerOptionsFromJson(CONSUMER_OPTIONS, consumer);
421
+ const found = [...candidates(name, exports, files)];
422
+ const kept = (mode) => found.flatMap(([specifier, namesDeclarations]) => {
423
+ const { resolvedModule } = ts.resolveModuleName(specifier, join(consumer, CONSUMER_FILES[mode].file), options, ts.sys, void 0, void 0, CONSUMER_FILES[mode].mode);
424
+ if (!resolvedModule) return [];
425
+ return DECLARATION_EXTENSIONS.has(resolvedModule.extension) || namesDeclarations ? [specifier] : [];
426
+ });
427
+ return {
428
+ import: kept("import"),
429
+ require: kept("require")
430
+ };
431
+ }
432
+ //#endregion
433
+ //#region src/guardrails/pack-tarball.ts
434
+ /** The flag that stops `pack` from running lifecycle scripts, by package manager. */
435
+ const IGNORE_SCRIPTS = {
436
+ pnpm: "--config.ignore-scripts=true",
437
+ npm: "--ignore-scripts"
438
+ };
439
+ /**
440
+ * Packs the package in `cwd` into `destination`: runs its `prepack` through `<manager> run`, which uses the configured
441
+ * script shell, then `<manager> pack` with lifecycle scripts off, since `pnpm pack` runs them through cmd.exe on Windows
442
+ * whatever the script shell, so a POSIX `prepare` fails there. Returns the first failed command, else the pack.
443
+ */
444
+ async function packTarball(manager, cwd, destination, signal) {
445
+ const prepack = await runCommand(manager, [
446
+ "run",
447
+ "--if-present",
448
+ "prepack"
449
+ ], {
450
+ cwd,
451
+ signal
452
+ });
453
+ if (prepack.status !== 0) return prepack;
454
+ return runCommand(manager, [
455
+ "pack",
456
+ IGNORE_SCRIPTS[manager],
457
+ "--pack-destination",
458
+ destination
459
+ ], {
460
+ cwd,
461
+ signal
462
+ });
463
+ }
464
+ //#endregion
465
+ //#region src/guardrails/published-types.ts
466
+ const DECLARATION_FILE = /\.d\.[cm]?ts$/;
467
+ /** An `exports` map that names declarations: a `types` condition or a `.d.ts`, `.d.mts` or `.d.cts` target. */
468
+ const TYPED_EXPORTS = /"types"\s*:|\.d\.[cm]?ts"/;
469
+ function declaresTypes(manifest) {
470
+ return manifest.types !== void 0 || manifest.typings !== void 0 || TYPED_EXPORTS.test(JSON.stringify(manifest.exports ?? null));
471
+ }
472
+ /** The root and workspace packages that are not `private`, with their manifests. */
473
+ function publicPackages(root) {
474
+ return ["", ...workspaceDirectories(root)].flatMap((directory) => {
475
+ const manifest = parseManifest(readFileSync(join(root, directory, "package.json"), "utf8"));
476
+ const { name } = manifest;
477
+ return name && manifest.private !== true ? [{
478
+ directory,
479
+ name,
480
+ manifest
481
+ }] : [];
482
+ });
483
+ }
484
+ /** The root and workspace packages that are not `private` and declare declarations through `types`, `typings` or `exports`. */
485
+ function typedPackages(root) {
486
+ return publicPackages(root).filter(({ manifest }) => declaresTypes(manifest)).map(({ directory, name }) => ({
487
+ directory,
488
+ name
489
+ }));
490
+ }
491
+ /** The arguments that install a consumer's dependencies without a lockfile and without running install scripts. */
492
+ const INSTALL_ARGUMENTS = {
493
+ pnpm: [
494
+ "install",
495
+ "--ignore-scripts",
496
+ "--prefer-offline",
497
+ "--no-frozen-lockfile"
498
+ ],
499
+ npm: [
500
+ "install",
501
+ "--ignore-scripts",
502
+ "--prefer-offline",
503
+ "--no-audit",
504
+ "--no-fund"
505
+ ]
506
+ };
507
+ /** The files under `directory`, relative to it with `/` separators, its `node_modules` left out. */
508
+ function shippedFiles(directory, prefix = "") {
509
+ return readdirSync(directory, { withFileTypes: true }).flatMap((entry) => {
510
+ const path = `${prefix}${entry.name}`;
511
+ if (entry.isDirectory()) return entry.name === "node_modules" ? [] : shippedFiles(join(directory, entry.name), `${path}/`);
512
+ return entry.isFile() ? [path] : [];
513
+ });
514
+ }
515
+ /** `output` with the consumer's own path and the package manager's store path before the package removed, so each error names the file as `<name>/<path>`. */
516
+ function readable(output, consumer, name) {
517
+ const store = new RegExp(String.raw`(?:node_modules/\.pnpm/[^/\s]+/)?node_modules/${name.replace(/[.*+?^${}()|[\]\\/]/g, "\\$&")}/`, "g");
518
+ return [consumer, consumer.replaceAll("\\", "/")].reduce((text, path) => text.split(`${path}/`).join(""), output).replace(store, `${name}/`);
519
+ }
520
+ const TAR_BLOCK = 512;
521
+ /** The text of the entry `path` in the gzipped tar archive `tarball`, read in Node so no `tar` binary, which differs across platforms, is needed. */
522
+ function tarEntry(tarball, path) {
523
+ const archive = gunzipSync(readFileSync(tarball));
524
+ for (let offset = 0; offset + TAR_BLOCK <= archive.length;) {
525
+ const header = archive.subarray(offset, offset + TAR_BLOCK);
526
+ const name = header.toString("utf8", 0, 100).replace(/\0.*$/s, "");
527
+ if (!name) return void 0;
528
+ const size = Number.parseInt(header.toString("utf8", 124, 136), 8) || 0;
529
+ const start = offset + TAR_BLOCK;
530
+ if (name === path) return archive.toString("utf8", start, start + size);
531
+ offset = start + Math.ceil(size / TAR_BLOCK) * TAR_BLOCK;
532
+ }
533
+ }
534
+ function packedManifest(destination) {
535
+ const [file = ""] = readdirSync(destination);
536
+ const tarball = join(destination, file);
537
+ const text = tarEntry(tarball, "package/package.json");
538
+ return text === void 0 ? { failure: `${file} holds no package/package.json.\n` } : {
539
+ failure: "",
540
+ tarball,
541
+ manifest: parseManifest(text)
542
+ };
543
+ }
544
+ /** Packs the package `name` once per run through {@link packTarball} and reads the manifest its tarball holds. */
545
+ async function pack(run, name) {
546
+ const cached = run.packs.get(name);
547
+ if (cached) return cached;
548
+ const slot = String(run.packs.size);
549
+ const destination = join(run.scratch, "tarballs", slot);
550
+ mkdirSync(destination, { recursive: true });
551
+ const result = await packTarball(run.manager, join(run.root, run.members.get(name) ?? ""), destination, run.signal);
552
+ const packed = result.status === 0 ? packedManifest(destination) : { failure: `Packing ${name} failed:\n${result.output}` };
553
+ run.packs.set(name, packed);
554
+ return packed;
555
+ }
556
+ function dependencyNames(manifest) {
557
+ return [
558
+ manifest.dependencies,
559
+ manifest.optionalDependencies,
560
+ manifest.peerDependencies
561
+ ].flatMap((ranges) => Object.keys(ranges ?? {}));
562
+ }
563
+ /** The tarball of each package of the repository that `name`'s packed manifest depends on, directly or through another such package, by name. */
564
+ async function siblingTarballs(run, name, manifest) {
565
+ const tarballs = /* @__PURE__ */ new Map();
566
+ const pending = [manifest];
567
+ for (let next = pending.pop(); next; next = pending.pop()) for (const dependency of dependencyNames(next)) {
568
+ if (dependency === name || tarballs.has(dependency)) continue;
569
+ if (!run.members.has(dependency)) continue;
570
+ const sibling = await pack(run, dependency);
571
+ if (!("tarball" in sibling)) return {
572
+ failure: sibling.failure,
573
+ tarballs
574
+ };
575
+ tarballs.set(dependency, `file:${sibling.tarball}`);
576
+ pending.push(sibling.manifest);
577
+ }
578
+ return {
579
+ failure: "",
580
+ tarballs
581
+ };
582
+ }
583
+ /** Writes the consumer's `package.json`, and for pnpm its `pnpm-workspace.yaml` in block style, which pnpm edits when it records a setting, so each sibling resolves to its tarball wherever it is required. */
584
+ function writeConsumer(consumer, manager, dependencies, overrides) {
585
+ const manifest = {
586
+ name: "published-types-consumer",
587
+ private: true,
588
+ dependencies
589
+ };
590
+ writeFileSync(join(consumer, "package.json"), JSON.stringify(manager === "npm" ? {
591
+ ...manifest,
592
+ overrides
593
+ } : {
594
+ ...manifest,
595
+ pnpm: { overrides }
596
+ }));
597
+ if (manager === "pnpm") writeFileSync(join(consumer, "pnpm-workspace.yaml"), stringify({
598
+ packages: ["."],
599
+ overrides
600
+ }));
601
+ }
602
+ async function typecheck(run, consumer, typed, manifest) {
603
+ const installed = realpathSync(join(consumer, "node_modules", typed.name));
604
+ const files = shippedFiles(installed);
605
+ const entries = entrySpecifiers(typed.name, manifest.exports, files, consumer);
606
+ const lines = {
607
+ import: entries.import.map((specifier, index) => `import type * as entry${index} from ${JSON.stringify(specifier)};\n`),
608
+ require: entries.require.map((specifier, index) => `import entry${index} = require(${JSON.stringify(specifier)});\n`)
609
+ };
610
+ const written = ["import", "require"].flatMap((mode) => {
611
+ if (!lines[mode].length) return [];
612
+ const { file } = CONSUMER_FILES[mode];
613
+ writeFileSync(join(consumer, file), lines[mode].join(""));
614
+ return [file];
615
+ });
616
+ const deep = manifest.exports === void 0 ? files.filter((file) => DECLARATION_FILE.test(file)).map((file) => relative(consumer, join(installed, file))) : [];
617
+ writeFileSync(join(consumer, "tsconfig.json"), JSON.stringify({
618
+ compilerOptions: CONSUMER_OPTIONS,
619
+ files: [...written, ...deep]
620
+ }));
621
+ const typescript = join(consumer, "node_modules", "typescript");
622
+ const { bin } = parseManifest(readFileSync(join(typescript, "package.json"), "utf8"));
623
+ const tsc = await runCommand(process.execPath, [
624
+ join(typescript, bin?.tsc ?? "bin/tsc"),
625
+ "-p",
626
+ ".",
627
+ "--pretty",
628
+ "false"
629
+ ], {
630
+ cwd: consumer,
631
+ signal: run.signal,
632
+ shell: false
633
+ });
634
+ return tsc.status === 0 ? "" : readable(tsc.output, consumer, typed.name);
635
+ }
636
+ async function consumerErrors(run, typed, slot) {
637
+ const packed = await pack(run, typed.name);
638
+ if (!("tarball" in packed)) return packed.failure;
639
+ const siblings = await siblingTarballs(run, typed.name, packed.manifest);
640
+ if (siblings.failure) return siblings.failure;
641
+ const consumer = join(run.scratch, `consumer-${slot}`);
642
+ mkdirSync(consumer);
643
+ const overrides = {
644
+ ...Object.fromEntries(siblings.tarballs),
645
+ [typed.name]: `file:${packed.tarball}`
646
+ };
647
+ writeConsumer(consumer, run.manager, {
648
+ typescript: "latest",
649
+ "@types/node": "latest",
650
+ ...packed.manifest.peerDependencies,
651
+ ...overrides
652
+ }, overrides);
653
+ const install = await runCommand(run.manager, INSTALL_ARGUMENTS[run.manager], {
654
+ cwd: consumer,
655
+ signal: run.signal
656
+ });
657
+ if (install.status !== 0) return `Installing the tarball failed:\n${install.output}`;
658
+ return typecheck(run, consumer, typed, packed.manifest);
659
+ }
660
+ function packsWithPnpmOrNpm(manager) {
661
+ return manager === "pnpm" || manager === "npm";
662
+ }
663
+ /**
664
+ * Packs each package `typedPackages` finds, running its `prepack`, and installs the tarball alone in a scratch
665
+ * directory with its peers, optional ones included, `typescript` and `@types/node` at the latest version unless it
666
+ * names them as peers, and the tarball of each package of the repository it depends on in place of the registry's.
667
+ * Then runs `tsc` with `skipLibCheck` off over a consumer file importing each entry its `exports` names, or, without
668
+ * `exports`, the package itself and every declaration file it ships. Returns what failed, each package's errors under
669
+ * its `package.json`, empty when every package passed.
670
+ */
671
+ async function checkPublishedTypes(root, signal) {
672
+ const manager = packageManager(parseManifest(readFileSync(join(root, "package.json"), "utf8")));
673
+ if (!packsWithPnpmOrNpm(manager)) return `This check packs with pnpm or npm, not ${manager}.\n`;
674
+ const scratch = realpathSync.native(mkdtempSync(join(tmpdir(), "published-types-")));
675
+ const run = {
676
+ root,
677
+ manager,
678
+ scratch,
679
+ signal,
680
+ members: new Map(publicPackages(root).map(({ name, directory }) => [name, directory])),
681
+ packs: /* @__PURE__ */ new Map()
682
+ };
683
+ let failures = "";
684
+ try {
685
+ for (const [slot, typed] of typedPackages(root).entries()) {
686
+ if (signal?.aborted) break;
687
+ const failure = await consumerErrors(run, typed, slot);
688
+ if (failure) failures += `${join(typed.directory, "package.json")}: ${typed.name} as a consumer installs it, checked by tsc with skipLibCheck off:\n${failure}`;
689
+ }
690
+ } finally {
691
+ rmSync(scratch, {
692
+ recursive: true,
693
+ force: true
694
+ });
695
+ }
696
+ return failures;
697
+ }
698
+ //#endregion
329
699
  //#region src/guardrails/readme-version.ts
330
700
  /** An object literal holding no other, such as a config example's `source: { package, version }`. */
331
701
  const FLAT_OBJECT = /\{[^{}]*\}/g;
702
+ const ANTELOPEJS_SCOPE = "@antelopejs/";
703
+ const DEFAULT_REGISTRY = "https://registry.npmjs.org/";
704
+ /** How long one read of a package's dist-tags may take before it counts as failed. */
705
+ const REGISTRY_TIMEOUT_MS = 3e3;
706
+ /** How many times a read that failed or timed out is made before the version counts as unreadable. */
707
+ const REGISTRY_ATTEMPTS = 2;
332
708
  function stringField(body, key) {
333
709
  return new RegExp(String.raw`(?<![\w$-])["']?${key}["']?\s*:\s*["']([^"'\n]+)["']`).exec(body);
334
710
  }
@@ -354,33 +730,74 @@ function ownPackages(root) {
354
730
  function examplesIn(readme, text, packages) {
355
731
  return [...text.matchAll(FLAT_OBJECT)].flatMap((object) => {
356
732
  const name = stringField(object[0], "package")?.[1];
357
- const owner = name === void 0 ? void 0 : packages.get(name);
358
733
  const field = stringField(object[0], "version");
359
734
  const range = field?.[1];
360
- if (!name || !owner || !field || range === void 0) return [];
735
+ if (!name?.startsWith(ANTELOPEJS_SCOPE) || !field || range === void 0) return [];
361
736
  return [{
362
737
  readme,
363
738
  line: text.slice(0, object.index + field.index).split("\n").length,
364
739
  name,
365
740
  range,
366
- owner
741
+ owner: packages.get(name)
367
742
  }];
368
743
  });
369
744
  }
370
- /** The config examples in the `README.md` of the root and of each workspace package that give one of the repository's own packages, by its `package.json` `name`, a `version`. */
745
+ /** The config examples in the `README.md` of the root and of each workspace package that give an `@antelopejs/*` package a `version`. */
371
746
  function readmeExamples(root) {
372
747
  const readmes = packageDirectories(root).map((directory) => relative$1(directory, "README.md")).filter((readme) => existsSync(join(root, readme)));
373
748
  if (!readmes.length) return [];
374
749
  const packages = ownPackages(root);
375
750
  return readmes.flatMap((readme) => examplesIn(readme, readFileSync(join(root, readme), "utf8"), packages));
376
751
  }
752
+ function registry() {
753
+ const configured = process.env.npm_config_registry || process.env.NPM_CONFIG_REGISTRY;
754
+ if (!configured) return DEFAULT_REGISTRY;
755
+ return configured.endsWith("/") ? configured : `${configured}/`;
756
+ }
757
+ /** The `latest` dist-tag of `name` on the registry npm is configured with, or `undefined` when it cannot be read within {@link REGISTRY_ATTEMPTS} reads of {@link REGISTRY_TIMEOUT_MS} each. */
758
+ async function publishedVersion(name) {
759
+ for (let attempt = 0; attempt < REGISTRY_ATTEMPTS; attempt++) try {
760
+ const response = await fetch(new URL(name.replace("/", "%2f"), registry()), {
761
+ headers: { accept: "application/vnd.npm.install-v1+json" },
762
+ signal: AbortSignal.timeout(REGISTRY_TIMEOUT_MS)
763
+ });
764
+ return response.ok ? tagVersion(parseJson(await response.text()), "latest") : void 0;
765
+ } catch {
766
+ continue;
767
+ }
768
+ }
769
+ async function newestVersions(examples) {
770
+ const names = [...new Set(examples.map(({ name }) => name))];
771
+ const entries = await Promise.all(names.map(async (name) => {
772
+ const owner = examples.find((example) => example.name === name)?.owner;
773
+ if (owner) return [name, {
774
+ version: owner.version,
775
+ source: `the version in ${owner.manifest}`
776
+ }];
777
+ const version = await publishedVersion(name);
778
+ return [name, version === void 0 ? void 0 : {
779
+ version,
780
+ source: "its newest published version"
781
+ }];
782
+ }));
783
+ return new Map(entries);
784
+ }
785
+ function describe({ readme, line, name, range }, newest) {
786
+ if (newest === void 0) return `${readme}:${line} gives ${name} the version range "${range}", but its newest published version could not be read from ${registry()}.\n`;
787
+ const expected = cappedReplacement(range, newest.version);
788
+ if (expected === void 0) return "";
789
+ return `${readme}:${line} gives ${name} the version range "${range}", which does not stop below the next minor of ${newest.version}, ${newest.source}. Use "${expected}".\n`;
790
+ }
377
791
  /**
378
- * Fails for each README config example whose `version` range, read as npm reads it, does not admit the `version` in
379
- * the named package's `package.json`, naming the README line; empty when every one does. A value that is not a range,
380
- * such as a dist-tag, passes.
792
+ * Fails for each README config example whose `@antelopejs/*` `version` range does not stop below the next minor of the
793
+ * package's newest version and admit it, naming the README line and the range to use. The newest version is the one in
794
+ * the repository's own `package.json` for its own packages, and the registry's `latest` dist-tag for any other. A value
795
+ * that is not a range, such as a dist-tag, passes.
381
796
  */
382
- function checkReadmeVersion(root) {
383
- return readmeExamples(root).filter(({ range, owner }) => validRange(range) !== null && !satisfies(owner.version, range)).map(({ readme, line, name, range, owner }) => `${readme}:${line} gives ${name} the version range "${range}", which does not admit ${owner.version}, the version in ${owner.manifest}. Set a range that admits it.\n`).join("");
797
+ async function checkReadmeVersion(root) {
798
+ const examples = readmeExamples(root).filter(({ range }) => validRange(range) !== null);
799
+ const newest = await newestVersions(examples);
800
+ return examples.map((example) => describe(example, newest.get(example.name))).join("");
384
801
  }
385
802
  //#endregion
386
803
  //#region src/guardrails/services.ts
@@ -1277,7 +1694,8 @@ const CHECK_STEPS = [
1277
1694
  "lockfile:singletons",
1278
1695
  "dependency:ranges",
1279
1696
  "git:identity",
1280
- "readme:version"
1697
+ "readme:version",
1698
+ "published:types"
1281
1699
  ];
1282
1700
  /** Steps `antelopejs-checks` runs itself, no package.json script behind them: each returns what failed, empty when it passed. */
1283
1701
  const OWN_STEPS = /* @__PURE__ */ new Map([
@@ -1286,7 +1704,8 @@ const OWN_STEPS = /* @__PURE__ */ new Map([
1286
1704
  ["lockfile:singletons", (root) => Promise.resolve(checkSingletonPackages(root))],
1287
1705
  ["dependency:ranges", (root) => Promise.resolve(checkRepositoryRanges(root))],
1288
1706
  ["git:identity", checkGitIdentity],
1289
- ["readme:version", (root) => Promise.resolve(checkReadmeVersion(root))]
1707
+ ["readme:version", checkReadmeVersion],
1708
+ ["published:types", checkPublishedTypes]
1290
1709
  ]);
1291
1710
  function hasWork(root, step) {
1292
1711
  if (step === "ratchet") return existsSync(join(root, CEILINGS_FILE));
@@ -1296,6 +1715,7 @@ function hasWork(root, step) {
1296
1715
  if (step === "dependency:ranges") return isGitCheckout(root) && hasDependencyRanges(root);
1297
1716
  if (step === "git:identity") return isGitCheckout(root);
1298
1717
  if (step === "readme:version") return readmeExamples(root).length > 0;
1718
+ if (step === "published:types") return typedPackages(root).length > 0;
1299
1719
  return true;
1300
1720
  }
1301
1721
  /** A command that runs a package script: the package manager, an optional `run`, then the script name. */
@@ -1325,18 +1745,21 @@ function droppedChecksSteps(current, synced) {
1325
1745
  if (!dropped.length) return [];
1326
1746
  return [`package.json: the checks script now runs ${command}, which does not run ${dropped.map((step) => `"${step}"`).join(", ")} from the replaced script. Call each from one of its steps, such as test or lint, or it no longer runs in checks.`];
1327
1747
  }
1328
- /** The step that runs after the others, never beside them: tests often hold time limits that CPU contention would break. */
1329
- const RUNS_ALONE = "test";
1748
+ /**
1749
+ * The steps that run after the others, each alone and in this order: tests often hold time limits that CPU contention
1750
+ * would break, and `published:types` packs each package, whose `prepack` rebuilds the output other steps and tests read.
1751
+ */
1752
+ const RUNS_ALONE = ["test", "published:types"];
1330
1753
  /** The step that runs before the others when it writes files, such as a workspace package's `dist`, that they read. */
1331
1754
  const RUNS_FIRST = "typecheck";
1332
1755
  /** The groups of steps that run one after another, the steps of a group at the same time. */
1333
1756
  function phases(root, steps) {
1334
1757
  const first = steps.includes(RUNS_FIRST) && typecheckWrites(root) ? [RUNS_FIRST] : [];
1335
- const last = steps.includes(RUNS_ALONE) ? [RUNS_ALONE] : [];
1758
+ const alone = RUNS_ALONE.filter((step) => steps.includes(step));
1336
1759
  return [
1337
1760
  first,
1338
- steps.filter((step) => !first.includes(step) && !last.includes(step)),
1339
- last
1761
+ steps.filter((step) => !first.includes(step) && !alone.includes(step)),
1762
+ ...alone.map((step) => [step])
1340
1763
  ].filter((phase) => phase.length > 0);
1341
1764
  }
1342
1765
  /** The environment variable naming, comma-separated, the steps `runChecks` leaves to another CI job. */
@@ -1399,7 +1822,7 @@ function summary(failures, passed, skipped) {
1399
1822
  /**
1400
1823
  * Runs the `checks:prepare` package script first when it exists and a step will run, and stops there if it fails.
1401
1824
  * Then runs `typecheck` first when it writes files the other steps read (see `typecheckWrites`), every other check step
1402
- * except `test` at the same time, then `test` alone, and reports only what failed, each step's
1825
+ * except `test` and `published:types` at the same time, then each of those alone, and reports only what failed, each step's
1403
1826
  * output buffered and listed in step order whichever step finishes first. `skipSetting` is the comma-separated value of
1404
1827
  * `ANTELOPEJS_CHECKS_SKIP`: the steps it names are not run and are counted as skipped, never as passed, and a name that
1405
1828
  * is not a step fails the run before any step starts so a typo cannot skip nothing. Unless `services` is false, the
package/dist/eslint.mjs CHANGED
@@ -1,5 +1,5 @@
1
1
  import { n as typeAwareRuleSetting, t as TYPE_AWARE_RULES } from "./type-aware-rules-Da3769fI.mjs";
2
- import { t as guardrailsPlugin } from "./guardrails-C72rFG8J.mjs";
2
+ import { t as guardrailsPlugin } from "./guardrails-6i82vsUi.mjs";
3
3
  import { createConfigForNuxt } from "@nuxt/eslint-config/flat";
4
4
  //#region src/eslint.ts
5
5
  /** Whether every rule of `plugin` has the `create` function ESLint calls, which `eslintCompatPlugin` gives each oxlint rule. */