@antelopejs/tooling-configs 0.5.5 → 0.5.7

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -1,9 +1,15 @@
1
- # @antelopejs/tooling-configs
1
+ <a href="https://github.com/AntelopeJS/antelopejs"><img data-illustration src="./.github/readme/strip.svg" width="100%" alt="TOOLING · TOOLING CONFIGS: part of AntelopeJS, hexagonal architecture beyond your own code. A glowing button reads Star AntelopeJS."></a>
2
2
 
3
3
  <div align="center">
4
- <a href="https://www.npmjs.com/package/@antelopejs/tooling-configs"><img alt="npm" src="https://img.shields.io/npm/v/@antelopejs/tooling-configs?style=for-the-badge&labelColor=000000&color=000000"></a>
5
- <a href="./LICENSE"><img alt="License" src="https://img.shields.io/npm/l/@antelopejs/tooling-configs?style=for-the-badge&labelColor=000000&color=000000"></a>
6
- <a href="https://discord.gg/g4pFt6eXqu"><img src="https://img.shields.io/badge/Discord-18181B?logo=discord&style=for-the-badge&color=000000" alt="Discord"></a>
4
+
5
+ # @antelopejs/tooling-configs
6
+
7
+ <a href="https://www.npmjs.com/package/@antelopejs/tooling-configs"><img data-illustration alt="npm" src="https://img.shields.io/npm/v/@antelopejs/tooling-configs?style=for-the-badge&labelColor=000000&color=000000"></a> <a href="./LICENSE"><img data-illustration alt="License" src="https://img.shields.io/npm/l/@antelopejs/tooling-configs?style=for-the-badge&labelColor=000000&color=000000"></a> <a href="https://discord.gg/g4pFt6eXqu"><img data-illustration alt="Discord" src="https://img.shields.io/badge/Discord-18181B?logo=discord&style=for-the-badge&color=000000"></a> <a href="./docs"><img data-illustration alt="Documentation" src="https://img.shields.io/badge/Docs-18181B?style=for-the-badge&color=000000"></a> <a href="https://github.com/AntelopeJS/antelopejs"><img data-illustration alt="Star AntelopeJS" src="https://img.shields.io/github/stars/AntelopeJS/antelopejs?label=Star%20AntelopeJS&style=for-the-badge&labelColor=000000&color=000000&logo=github"></a>
8
+
9
+ **Shared oxlint, oxfmt and Knip presets for AntelopeJS projects, with a command that installs them and fails CI when they drift.**
10
+
11
+ [Documentation](./docs) · [All interfaces and providers](https://github.com/AntelopeJS/antelopejs#ecosystem)
12
+
7
13
  </div>
8
14
 
9
15
  The AntelopeJS guardrail pack: shared lint, format and dead-code presets, the commands that install and enforce them in a repository, and a check for the version ranges of interface dependencies.
@@ -463,6 +469,8 @@ The defaults declare what Knip cannot infer for an AntelopeJS module:
463
469
 
464
470
  An implementer must never be handed a breaking minor it does not implement. `workspace:`, `file:` and `link:` specs are skipped. Pass paths to check only those manifests.
465
471
 
472
+ When the interface sits in the same repository, as in a DMS monorepo, `antelopejs-sync` moves the implementer's range for you: a minor interface release from `0.6.1` to `0.7.0` moves `>=0.6.0 <0.7.0` to `>=0.7.0 <0.8.0`, then sync runs `pnpm install --lockfile-only` so the lockfile follows. The interface is not on npm yet when the release hook runs, so the workspace must link it: set `link-workspace-packages=true` in `.npmrc` or `linkWorkspacePackages: true` in `pnpm-workspace.yaml`. When the relock fails, sync leaves the ranges unmoved and exits 1. An interface `.release-it.json` whose `after:bump` hook runs `pnpm --dir ../.. run sync` and `git add -u ../..` commits both with the release. `antelopejs-sync --check` reports the stale range as drift.
473
+
466
474
  ```jsonc
467
475
  // package.json
468
476
  {
@@ -493,6 +501,10 @@ checks that remain the author's responsibility.
493
501
 
494
502
  See [CONTRIBUTING.md](./CONTRIBUTING.md). `pnpm install`, then `pnpm checks` runs the typecheck, lint, format check, Knip, tests, size and sync checks. Repositories with recorded debt also run the ratchet.
495
503
 
504
+ ## Part of AntelopeJS
505
+
506
+ This package belongs to [AntelopeJS](https://github.com/AntelopeJS/antelopejs), the TypeScript framework where modules depend on contracts and the application chooses the provider. The open-source back office [AntelopeJS DMS](https://github.com/AntelopeJS/dms) is built on it.
507
+
496
508
  ## License
497
509
 
498
510
  [Apache-2.0](./LICENSE), except the vendored anti-slop rules (MIT).
@@ -3,7 +3,7 @@ import { o as packageManager, s as parseManifest } from "../package-DnxZ2CXZ.mjs
3
3
  import { t as runCli } from "../cli-4Tv71vYk.mjs";
4
4
  import { c as repositoryRoot, l as resolveRevision } from "../files-DJ0TeaTU.mjs";
5
5
  import { a as DIRECTORY_LINK, c as revisionCounts, d as createAddedPolicy, f as describeAllowance, i as stampProof, l as workspaceManifests, m as recordVerdict, o as compareRevisions, p as fillStars, u as allowedByGlob } from "../proof-stamp-Kg-tkM6G.mjs";
6
- import { c as packagesAt, i as isTestSource, l as unpublishedAt, o as loadTypeScript, r as isExportPath, s as outputRoot, t as emitPackage } from "../typescript-DhavwHb7.mjs";
6
+ import { c as packagesAt, i as isTestSource, l as unpublishedAt, o as loadTypeScript, r as isExportPath, s as outputRoot, t as emitPackage } from "../typescript-CqcOaci8.mjs";
7
7
  import { createRequire } from "node:module";
8
8
  import { copyFileSync, cpSync, existsSync, globSync, mkdirSync, readFileSync, readdirSync, realpathSync, rmSync, statSync, symlinkSync, writeFileSync } from "node:fs";
9
9
  import { basename, dirname, isAbsolute, join, parse, posix, relative, resolve, sep } from "node:path";
@@ -1,116 +1,8 @@
1
1
  #!/usr/bin/env node
2
+ import { n as describeViolation, r as localVersions, t as checkInterfaceRanges } from "../interface-ranges-CcVSr59f.mjs";
2
3
  import { readFileSync } from "node:fs";
3
4
  import { join, relative } from "node:path";
4
5
  import { execFileSync } from "node:child_process";
5
- //#region src/interface-ranges.ts
6
- /**
7
- * At startup `@antelopejs/core` keeps one copy of each interface package, the
8
- * one its implementing module installed, and refuses to start when any loaded
9
- * module declares a range that copy falls outside. An exact pin (`0.1.7`) or a
10
- * 0.x caret (`^0.1.2` means `<0.2.0`) therefore stops a module from starting
11
- * as soon as the implementer resolves the next interface release, with no
12
- * change to the module itself.
13
- *
14
- * A consumer accepts every release from its floor up to the next breaking one
15
- * (`>=0.1.7 <1.0.0`). The module that implements an interface is the opposite
16
- * case: it must never be handed a breaking minor it does not implement, so it
17
- * caps the range below the next minor (`>=0.3.0 <0.4.0`) while the interface
18
- * is 0.x.
19
- */
20
- const INTERFACE_PACKAGE_PREFIX = "@antelopejs/interface-";
21
- /** A module's own interface linked from the workspace is the copy it builds against, not a release it resolves. */
22
- const LOCAL_SPEC_PREFIXES = [
23
- "workspace:",
24
- "file:",
25
- "link:"
26
- ];
27
- /** The fields `@antelopejs/core` checks at startup. */
28
- const CHECKED_FIELDS = ["dependencies", "optionalDependencies"];
29
- const BOUNDED_RANGE = /^>=(\d+)\.(\d+)\.(\d+) <(\d+)\.(\d+)\.(\d+)$/;
30
- const SINGLE_VERSION = /^[\^~=]?v?(\d+)\.(\d+)\.(\d+)$/;
31
- const formatVersion = ([major, minor, patch]) => `${major}.${minor}.${patch}`;
32
- const sameVersion = (a, b) => a[0] === b[0] && a[1] === b[1] && a[2] === b[2];
33
- /** The first release a module declaring `floor` must not be handed. */
34
- function rangeCeiling(floor, role) {
35
- const [major, minor] = floor;
36
- if (major > 0) return [
37
- major + 1,
38
- 0,
39
- 0
40
- ];
41
- return role === "implementer" ? [
42
- 0,
43
- minor + 1,
44
- 0
45
- ] : [
46
- 1,
47
- 0,
48
- 0
49
- ];
50
- }
51
- function expectedRange(floor, role) {
52
- return `>=${formatVersion(floor)} <${formatVersion(rangeCeiling(floor, role))}`;
53
- }
54
- function toVersion(match, offset) {
55
- return [
56
- Number(match[offset]),
57
- Number(match[offset + 1]),
58
- Number(match[offset + 2])
59
- ];
60
- }
61
- /** The lowest release `spec` accepts, when it is a shape this check reads. */
62
- function readFloor(spec) {
63
- const bounded = BOUNDED_RANGE.exec(spec);
64
- if (bounded) return toVersion(bounded, 1);
65
- const single = SINGLE_VERSION.exec(spec);
66
- return single ? toVersion(single, 1) : void 0;
67
- }
68
- function compareVersions(a, b) {
69
- return a[0] - b[0] || a[1] - b[1] || a[2] - b[2];
70
- }
71
- /** A range is accepted when it is bounded for its role and admits the interface this package builds against. */
72
- function isAcceptedRange(spec, role, local) {
73
- const bounded = BOUNDED_RANGE.exec(spec);
74
- if (!bounded) return false;
75
- const floor = toVersion(bounded, 1);
76
- const ceiling = toVersion(bounded, 4);
77
- if (!sameVersion(ceiling, rangeCeiling(floor, role))) return false;
78
- return local === void 0 || compareVersions(local, floor) >= 0 && compareVersions(local, ceiling) < 0;
79
- }
80
- function isLocalSpec(spec) {
81
- return LOCAL_SPEC_PREFIXES.some((prefix) => spec.startsWith(prefix));
82
- }
83
- /**
84
- * `localVersions` holds the versions of the packages that sit in the same
85
- * repository. An implemented interface is usually one of them, and its
86
- * version, rather than the declared floor, decides the minor to stop below.
87
- */
88
- function checkInterfaceRanges(manifest, localVersions = /* @__PURE__ */ new Map()) {
89
- const implemented = new Set(manifest.antelopeJs?.implements ?? []);
90
- const violations = [];
91
- for (const field of CHECKED_FIELDS) for (const [name, spec] of Object.entries(manifest[field] ?? {})) {
92
- if (!name.startsWith(INTERFACE_PACKAGE_PREFIX) || isLocalSpec(spec)) continue;
93
- const role = implemented.has(name) ? "implementer" : "consumer";
94
- const localVersion = localVersions.get(name);
95
- const local = role === "implementer" && localVersion !== void 0 ? readFloor(localVersion) : void 0;
96
- if (isAcceptedRange(spec, role, local)) continue;
97
- const floor = local ?? readFloor(spec);
98
- violations.push({
99
- field,
100
- name,
101
- spec,
102
- role,
103
- expected: floor ? expectedRange(floor, role) : void 0
104
- });
105
- }
106
- return violations;
107
- }
108
- function describeViolation(violation) {
109
- const { field, name, spec, role, expected } = violation;
110
- const fix = expected ? `use "${expected}"` : role === "implementer" ? "declare it as >=<floor> <next minor>" : "declare it as >=<floor> <1.0.0";
111
- return `${field}["${name}"] is "${spec}": ${role === "implementer" ? "this package implements it, so it must stop below the next minor" : "it must accept every release up to the next breaking one"}; ${fix}`;
112
- }
113
- //#endregion
114
6
  //#region src/bin/check-interface-ranges.ts
115
7
  /**
116
8
  * Every manifest in the repository by default, whatever directory the lint
@@ -135,10 +27,9 @@ function main() {
135
27
  path,
136
28
  manifest: JSON.parse(readFileSync(path, "utf8"))
137
29
  }));
138
- const localVersions = /* @__PURE__ */ new Map();
139
- for (const { manifest } of manifests) if (manifest.name && manifest.version) localVersions.set(manifest.name, manifest.version);
30
+ const versions = localVersions(manifests.map(({ manifest }) => manifest));
140
31
  let failures = 0;
141
- for (const { path, manifest } of manifests) for (const violation of checkInterfaceRanges(manifest, localVersions)) {
32
+ for (const { path, manifest } of manifests) for (const violation of checkInterfaceRanges(manifest, versions)) {
142
33
  console.error(`${path}: ${describeViolation(violation)}`);
143
34
  failures += 1;
144
35
  }
@@ -1,7 +1,7 @@
1
1
  #!/usr/bin/env node
2
2
  import { n as runCliAsync } from "../cli-4Tv71vYk.mjs";
3
3
  import { c as repositoryRoot } from "../files-DJ0TeaTU.mjs";
4
- import { r as runChecks, t as CHECKS_SKIP_ENV } from "../checks-DqTjyKCC.mjs";
4
+ import { r as runChecks, t as CHECKS_SKIP_ENV } from "../checks-CD2oFGrt.mjs";
5
5
  import { parseArgs } from "node:util";
6
6
  //#region src/bin/checks.ts
7
7
  const SIGNAL_EXIT = /* @__PURE__ */ new Map([
@@ -2,7 +2,7 @@
2
2
  import { t as runCli } from "../cli-4Tv71vYk.mjs";
3
3
  import { c as repositoryRoot } from "../files-DJ0TeaTU.mjs";
4
4
  import { c as revisionCounts, i as stampProof, o as compareRevisions } from "../proof-stamp-Kg-tkM6G.mjs";
5
- import { a as listsNoFiles, c as packagesAt, n as extendedConfigs, t as emitPackage } from "../typescript-DhavwHb7.mjs";
5
+ import { a as listsNoFiles, c as packagesAt, n as extendedConfigs, t as emitPackage } from "../typescript-CqcOaci8.mjs";
6
6
  import { copyFileSync, existsSync, mkdirSync } from "node:fs";
7
7
  import { dirname, isAbsolute, join, relative, resolve, sep } from "node:path";
8
8
  //#region src/guardrails/comment-proof.ts
package/dist/bin/sync.mjs CHANGED
@@ -4,11 +4,13 @@ import { a as managedPackage, c as repositoryTools, f as toolingVersions, l as s
4
4
  import { t as admits } from "../semver-BDxeEcP_.mjs";
5
5
  import { i as presetConfig, n as SETUP_SCRIPT, r as lefthook, t as PRESET_CONFIGS } from "../templates-Dg188oRC.mjs";
6
6
  import { a as VERIFY_KINDS, c as isVerifyKind, i as SYNCED_SKILL_FILES, l as skillFolder, o as claudeLink, s as claudeLinkTarget, u as planDocsSkills } from "../shared-igPpEDpS.mjs";
7
+ import { r as localVersions, t as checkInterfaceRanges } from "../interface-ranges-CcVSr59f.mjs";
7
8
  import { t as runCli } from "../cli-4Tv71vYk.mjs";
8
9
  import { c as CI_CONTEXT, f as ciWorkflow, i as hasChecksWorkflow, n as ciNodeCallers, p as placeholderTestScript, r as ciRenovateSyncCallers, s as renovateArtifacts, t as MISSING_CHECKS_WORKFLOW, u as CI_PATH } from "../workflow-CPcNc8KL.mjs";
9
- import { a as gitFiles, c as repositoryRoot } from "../files-DJ0TeaTU.mjs";
10
- import { a as stepsOf, c as workspacePatterns, i as matchingScripts, n as droppedChecksSteps, o as planDocs, s as workspaceDirectories } from "../checks-DqTjyKCC.mjs";
10
+ import { a as gitFiles, c as repositoryRoot, u as trackedManifests } from "../files-DJ0TeaTU.mjs";
11
+ import { n as workspaceDirectories, r as workspacePatterns, t as planDocs } from "../docs-compat-Ft1r2sf0.mjs";
11
12
  import { i as recordedRelease, t as measureBaseline } from "../ratchet-1O8k4Dxu.mjs";
13
+ import { a as stepsOf, i as matchingScripts, n as droppedChecksSteps } from "../checks-CD2oFGrt.mjs";
12
14
  import { n as SUPPRESSIONS_FILE, r as adoptedBudget } from "../suppression-budget-DgYdu6JK.mjs";
13
15
  import { u as typescript } from "../suppressions-CQTcKCi1.mjs";
14
16
  import { t as DEFAULT_SHARED } from "../map-DRyYz_Fw.mjs";
@@ -87,6 +89,19 @@ function untypedDocsFiles(root) {
87
89
  return [...found];
88
90
  }
89
91
  //#endregion
92
+ //#region src/guardrails/run-pnpm.ts
93
+ /** Runs pnpm, the only manager the pack's CI installs with, with `args` quietly; returns its output only when it failed. */
94
+ function runPnpm(root, args) {
95
+ const command = ["pnpm", ...args].join(" ");
96
+ const result = spawnSync("pnpm", args, {
97
+ cwd: root,
98
+ encoding: "utf8"
99
+ });
100
+ if (result.error) return `${command} failed: ${result.error.message}`;
101
+ if (result.status === 0) return void 0;
102
+ return `${command} failed (exit ${result.status}).\n${result.stdout}${result.stderr}`.trimEnd();
103
+ }
104
+ //#endregion
90
105
  //#region src/guardrails/agents-block.ts
91
106
  const AGENTS_BLOCK_START = "<!-- antelopejs-guardrails:start -->";
92
107
  const AGENTS_BLOCK_END = "<!-- antelopejs-guardrails:end -->";
@@ -258,10 +273,16 @@ function agentsBlock(context) {
258
273
  //#endregion
259
274
  //#region src/guardrails/pnpm-workspace.ts
260
275
  const PATH = "pnpm-workspace.yaml";
261
- /** Whether the pinned pnpm reads settings from a `pnpm-workspace.yaml` without `packages`, which pnpm before 10.5 rejects. An unpinned pnpm counts as current. */
262
- function readsSettings(manifest) {
276
+ /** The first pnpm that keeps `pnpm --dir <nested> install` in the nested project when the root `pnpm-workspace.yaml` has no `packages`. Earlier pnpm installs the root instead. */
277
+ const SCOPED_NESTED_INSTALLS = "11.27.1";
278
+ /**
279
+ * What sync does for a repository without a `pnpm-workspace.yaml`, by its pinned pnpm. An unpinned pnpm counts as current.
280
+ * pnpm 10 and earlier only warn about an undecided build, so they get no file. pnpm 11 fails the install without one, and before 11.27.1 misroutes nested installs with one, so its pin must rise.
281
+ */
282
+ function creation(manifest) {
263
283
  const pinned = manifest.packageManager?.split("@")[1];
264
- return pinned === void 0 || admits(">=10.5.0", pinned);
284
+ if (pinned === void 0 || admits(`>=${SCOPED_NESTED_INSTALLS}`, pinned)) return "write";
285
+ return admits(">=11.0.0", pinned) ? "raise" : "skip";
265
286
  }
266
287
  /**
267
288
  * The dependency builds sync declares and pnpm 11 must be told to skip.
@@ -270,6 +291,14 @@ function readsSettings(manifest) {
270
291
  function skippedBuilds(captures) {
271
292
  return captures ? ["lefthook", "mongodb-memory-server"] : ["lefthook"];
272
293
  }
294
+ /** Whether `current` holds nothing but builds sync turns off, so pnpm reads it only to make the repository root a workspace. */
295
+ function onlyDecidedBuilds(current) {
296
+ const document = parseDocument(current);
297
+ const builds = document.get("allowBuilds");
298
+ if (document.errors.length || !isMap(document.contents) || document.contents.items.length !== 1 || !isMap(builds) || !builds.items.length) return false;
299
+ const synced = skippedBuilds(true);
300
+ return builds.items.every(({ key, value }) => isScalar(key) && synced.includes(String(key.value)) && isScalar(value) && value.value === false);
301
+ }
273
302
  /**
274
303
  * `current` with `allowBuilds.<name>` set to `false` for each of `names` the repository does not already decide.
275
304
  * pnpm 11 fails an install on a dependency build it was not told about.
@@ -301,10 +330,18 @@ function pnpmWorkspaceArtifacts(root, manifest, managed) {
301
330
  if (!managed || packageManager(manifest) !== "pnpm") return [];
302
331
  const file = join(root, PATH);
303
332
  const current = existsSync(file) ? readFileSync(file, "utf8") : void 0;
304
- if (current === void 0 && !readsSettings(manifest)) return [];
305
333
  const names = skippedBuilds(usesCaptures(root));
306
334
  try {
307
335
  const content = withBuildsDecided(names, current);
336
+ const action = creation(manifest);
337
+ if (action !== "write" && onlyDecidedBuilds(content)) {
338
+ if (action === "skip" && current === void 0) return [];
339
+ return [{
340
+ kind: "error",
341
+ path: PATH,
342
+ message: action === "skip" ? `${PATH} holds nothing but the allowBuilds that antelopejs-sync writes. pnpm before 11 does not need it, and it makes a nested \`pnpm install\` install the repository root. Delete ${PATH}, then rerun antelopejs-sync.` : `pnpm 11 needs a ${PATH} to install ${names.join(" and ")}, and before ${SCOPED_NESTED_INSTALLS} that file makes a nested \`pnpm install\` install the repository root. Set \`packageManager\` to \`pnpm@${SCOPED_NESTED_INSTALLS}\` or later, then rerun antelopejs-sync.`
343
+ }];
344
+ }
308
345
  return [content === current ? {
309
346
  kind: "unchanged",
310
347
  path: PATH
@@ -881,7 +918,7 @@ const KIND_TEXT = {
881
918
  - a plain function runs the \`interface.calls\` hook of \`verify.config.ts\` and must return its \`expect\`; one only providers call is listed in \`interface.providerSide\` with why.
882
919
  A declared function with none of these fails the journey.
883
920
  - \`minor-bump\`: reads the declared functions of the packed head and of the published version (\`npm pack <name>@<latest>\`). An added, changed or removed function needs a release of at least the next minor. The release is the head version when it is already bumped, otherwise what changelogen makes of the change title (\`new --title\`) or the commit subjects since the base.`,
884
- layer: `- \`services\`: image, port, readiness command and a \`reset\` command run before every journey, as for a module. \`new\` starts them in Docker on free ports; a journey reads them with \`context.service(name)\` and \`context.native(...)\`.
921
+ layer: `- \`services\`: image, port, optional \`args\`, readiness command and a \`reset\` command run before every journey, as for a module. \`new\` starts them in Docker on free ports; a journey reads them with \`context.service(name)\` and \`context.native(...)\`.
885
922
  - \`interface.provide(api, services)\` runs in the stub provider after the generic stubs attach, for example to hand a client pointed at \`services\` to \`internal.SetClient\`.
886
923
  - \`interface.calls["<entry>:<path>"]\` calls a plain exported function from the consumer and states the value it must return.
887
924
  - \`interface.providerSide["<entry>:<path>"]\` names a function only providers call, with the reason.`,
@@ -894,7 +931,7 @@ const KIND_TEXT = {
894
931
  user: "The user of a module is an app developer: they add it to `antelope.config.ts`, configure it, and other modules call the interfaces it implements.",
895
932
  launch: "`new` runs the setup (`pnpm run build` by default), then starts every `services` entry of `verify.config.ts` in its own Docker container on a free loopback port, named `<prefix>-<repo>-<service>-<run>` (`VERIFY_CONTAINER_PREFIX`, default `verify`), and waits for each readiness command. A provider with sandbox keys in `saas.env` records the missing ones.",
896
933
  builtins: "- `module-dev`: a fixture project installs the module as `local` with `moduleConfig(services)` as its config, plus the `companions(services)` modules and a consumer module. `ajs project dev` must answer, the consumer must load every implemented interface, Ctrl+C must exit 130 and the port must refuse afterwards.",
897
- layer: `- \`services\`: image, port, readiness command and a \`reset\` command run before every journey, so each starts from a clean state.
934
+ layer: `- \`services\`: image, port, readiness command and a \`reset\` command run before every journey, so each starts from a clean state. Optional \`args\` follow the image in \`docker run\` in place of its default command, such as \`["--performance-schema=ON", "--log-bin"]\` for MariaDB's server.
898
935
  - \`moduleConfig(services)\`: the module's configuration, pointing at the run's containers.
899
936
  - \`companions(services)\`: other modules the fixture project loads, keyed by name, each a \`source\` and an optional \`config\` as in \`antelope.config.ts\`. Add the provider of every interface the module imports that it does not implement, such as \`@antelopejs/api\` for \`@antelopejs/interface-api\`, or the module never finishes starting.
900
937
  - \`saas: { env, sandbox }\`: a SaaS module runs against the provider's sandbox with keys from these environment variables. Without every key, each journey is NOT VERIFIED and so is the verdict, never PASS or PASS+NOTES.
@@ -915,7 +952,7 @@ Both take their project from \`context.prepared("scaffolded", ...)\`, so the run
915
952
  layer: `- \`template.name\`: the listing name users pass to \`--template\`.
916
953
  - \`template.project\`: list it under \`projectTemplates\`.
917
954
  - \`template.module\`: a module template, listed under \`templates\` and created with \`ajs module init\`; it excludes \`template.project\`.
918
- - \`services\`: image, port, readiness command and \`reset\`, as for a module. \`new\` starts them in Docker on free ports; a journey reads them with \`context.service(name)\` and \`context.native(...)\` and passes their endpoints to the project it starts through the \`env\` of \`context.dev\`.
955
+ - \`services\`: image, port, optional \`args\`, readiness command and \`reset\`, as for a module. \`new\` starts them in Docker on free ports; a journey reads them with \`context.service(name)\` and \`context.native(...)\` and passes their endpoints to the project it starts through the \`env\` of \`context.dev\`.
919
956
  - \`context.dev(name, project, { command })\`: a template that is not an \`ajs\` project starts with its own command, such as \`["node", "ace", "serve"]\`, in place of \`ajs project dev\`. The harness records its PID, so \`context.stop\` and \`clean\` stop it, and \`template.probe\` decides when it is ready. Leave \`scaffold-dev\` and \`scaffold-checks\` out of its features: both run \`ajs\`.
920
957
  - \`template.probe\`: \`path\`, \`status\` and \`body\` for an HTTP welcome page or endpoint, or \`log\` and \`settleMs\` for a template that serves nothing.`,
921
958
  smoke: "`scaffold-dev` and `scaffold-checks`, or, for a template that is not an `ajs` project, its own journeys that start it with `context.dev(name, project, { command })`",
@@ -1923,19 +1960,8 @@ function ensureBranchCleanup(root) {
1923
1960
  reason: failureText(write)
1924
1961
  } : { kind: "enabled" };
1925
1962
  }
1926
- /** Runs pnpm, the only manager the pack's CI installs with, with `args` quietly; returns its output only when it failed. */
1927
- function run(root, args) {
1928
- const command = ["pnpm", ...args].join(" ");
1929
- const result = spawnSync("pnpm", args, {
1930
- cwd: root,
1931
- encoding: "utf8"
1932
- });
1933
- if (result.error) return `${command} failed: ${result.error.message}`;
1934
- if (result.status === 0) return void 0;
1935
- return `${command} failed (exit ${result.status}).\n${result.stdout}${result.stderr}`.trimEnd();
1936
- }
1937
1963
  function install(root) {
1938
- return run(root, ["install"]);
1964
+ return runPnpm(root, ["install"]);
1939
1965
  }
1940
1966
  function resolveOxfmt(root) {
1941
1967
  const require = createRequire(join(root, "package.json"));
@@ -2087,7 +2113,7 @@ function bootstrap(root) {
2087
2113
  };
2088
2114
  const foreign = FOREIGN_INSTALL_FILES.filter(({ file }) => existsSync(join(root, file)));
2089
2115
  paths.push(...ensurePnpmWorkspace(root, foreign.length > 0));
2090
- const imported = foreign.some(({ importable }) => importable) && !existsSync(join(root, "pnpm-lock.yaml")) ? run(root, ["import"]) : void 0;
2116
+ const imported = foreign.some(({ importable }) => importable) && !existsSync(join(root, "pnpm-lock.yaml")) ? runPnpm(root, ["import"]) : void 0;
2091
2117
  if (imported !== void 0) return {
2092
2118
  paths,
2093
2119
  removed: [],
@@ -2141,7 +2167,92 @@ function initRepository(root, options = {}) {
2141
2167
  };
2142
2168
  }
2143
2169
  //#endregion
2170
+ //#region src/guardrails/interface-ranges-sync.ts
2171
+ /** Each tracked manifest that parses; a fixture that is not JSON is not a package this repository releases. */
2172
+ function tracked(root) {
2173
+ return trackedManifests(root).flatMap((path) => {
2174
+ try {
2175
+ const text = readFileSync(join(root, path), "utf8");
2176
+ return [{
2177
+ path,
2178
+ text,
2179
+ manifest: parseManifest(text)
2180
+ }];
2181
+ } catch {
2182
+ return [];
2183
+ }
2184
+ });
2185
+ }
2186
+ function movedNote(path, violation) {
2187
+ return `${path}: moved ${violation.field}["${violation.name}"] from "${violation.spec}" to "${violation.expected}", the range of the interface version this repository holds.`;
2188
+ }
2189
+ /** The relock failure, after which the moved manifests are back as they were so the next sync moves them again. */
2190
+ function writeAndRelock(root, manifests, moved) {
2191
+ const rootManifest = manifests.find(({ path }) => path === "package.json");
2192
+ const manager = packageManager(rootManifest?.manifest ?? {});
2193
+ if (manager !== "pnpm") return `${manager} is not pnpm, so sync cannot relock them.`;
2194
+ for (const [path, { after }] of moved) writeFileSync(join(root, path), after);
2195
+ const failure = runPnpm(root, ["install", "--lockfile-only"]);
2196
+ if (failure !== void 0) for (const [path, { before }] of moved) writeFileSync(join(root, path), before);
2197
+ return failure;
2198
+ }
2199
+ /**
2200
+ * Moves each tracked manifest's range for an interface it implements from
2201
+ * this repository to the range `antelopejs-check-interface-ranges` expects,
2202
+ * then relocks, or leaves every manifest as it was when the relock fails. A
2203
+ * minor release of that interface otherwise leaves its module's range below
2204
+ * the new version and fails the check on the release commit. It runs before
2205
+ * the rest of sync, which then plans the docs-compat READMEs from the moved
2206
+ * ranges and the new lockfile. `check` reports the moves without writing.
2207
+ */
2208
+ function moveInterfaceRanges(root, check) {
2209
+ const manifests = tracked(root);
2210
+ const versions = localVersions(manifests.map(({ manifest }) => manifest));
2211
+ const moves = {
2212
+ paths: [],
2213
+ notes: [],
2214
+ errors: []
2215
+ };
2216
+ const moved = /* @__PURE__ */ new Map();
2217
+ for (const { path, text, manifest } of manifests) {
2218
+ const fixes = checkInterfaceRanges(manifest, versions).filter((violation) => violation.role === "implementer" && violation.expected !== void 0 && versions.has(violation.name));
2219
+ if (!fixes.length) continue;
2220
+ for (const { field, name, expected } of fixes) {
2221
+ const dependencies = manifest[field];
2222
+ if (dependencies && expected) dependencies[name] = expected;
2223
+ }
2224
+ moved.set(path, {
2225
+ before: text,
2226
+ after: serializeManifest(manifest, text)
2227
+ });
2228
+ moves.paths.push(path);
2229
+ moves.notes.push(...fixes.map((fix) => movedNote(path, fix)));
2230
+ }
2231
+ if (check || !moved.size) return moves;
2232
+ const failure = writeAndRelock(root, manifests, moved);
2233
+ if (failure !== void 0) moves.errors.push(`Left the interface ranges in ${moves.paths.join(", ")} unmoved: the lockfile could not follow them. ${failure}`);
2234
+ return moves;
2235
+ }
2236
+ //#endregion
2144
2237
  //#region src/bin/sync.ts
2238
+ /** The sync result with the interface range moves that ran before it, or the moves alone when relocking them failed. */
2239
+ function withRangeMoves(ranges, result) {
2240
+ if (!result) return {
2241
+ artifacts: [],
2242
+ paths: [],
2243
+ removed: [],
2244
+ errors: ranges.errors,
2245
+ notes: ranges.notes,
2246
+ verifyNotes: [],
2247
+ advisories: [],
2248
+ dependenciesAdded: false
2249
+ };
2250
+ return {
2251
+ ...result,
2252
+ paths: result.errors.length ? [] : [.../* @__PURE__ */ new Set([...ranges.paths, ...result.paths])],
2253
+ notes: [...ranges.notes, ...result.notes]
2254
+ };
2255
+ }
2145
2256
  function printSync(result, { check, installed }) {
2146
2257
  for (const note of result.notes) process.stdout.write(`Note: ${check || result.errors.length ? "Planned migration. " : ""}${note}\n`);
2147
2258
  for (const note of result.verifyNotes) process.stdout.write(`Note: ${note}\n`);
@@ -2186,12 +2297,15 @@ runCli(() => {
2186
2297
  if (values.verify !== void 0 && !isVerifyChoice(values.verify)) throw new Error("--verify must be interface, module, template, or custom.");
2187
2298
  if (values.init && (values.check || values.profile === "template")) throw new Error("--init sets up a full-profile repository; it cannot be combined with --check or --profile template.");
2188
2299
  if (values.init) return init(values.verify);
2189
- return printSync(syncRepository(repositoryRoot(), {
2190
- check: values.check,
2300
+ const root = repositoryRoot();
2301
+ const check = Boolean(values.check);
2302
+ const ranges = moveInterfaceRanges(root, check);
2303
+ return printSync(withRangeMoves(ranges, ranges.errors.length ? void 0 : syncRepository(root, {
2304
+ check,
2191
2305
  profile: values.profile,
2192
2306
  verify: values.verify
2193
- }), {
2194
- check: Boolean(values.check),
2307
+ })), {
2308
+ check,
2195
2309
  installed: false
2196
2310
  });
2197
2311
  });
@@ -1343,8 +1343,8 @@ function waitReady$1(container, ready, folder) {
1343
1343
  /**
1344
1344
  * Starts every service of verify.config.ts in its own container, named
1345
1345
  * `<prefix>-<repo>-<service>-<run id>`, publishes its port on a free
1346
- * loopback port chosen by Docker, raises its open-file limit to 64000, and
1347
- * waits for its readiness command. Each
1346
+ * loopback port chosen by Docker, raises its open-file limit to 64000, passes
1347
+ * its `args` after the image, and waits for its readiness command. Each
1348
1348
  * container is recorded before it is probed, so `clean` removes it even when
1349
1349
  * it never became ready.
1350
1350
  */
@@ -1362,7 +1362,8 @@ function startServices(workspace, state, prefix) {
1362
1362
  "--ulimit",
1363
1363
  `nofile=${OPEN_FILES}:${OPEN_FILES}`,
1364
1364
  ...env,
1365
- definition.image
1365
+ definition.image,
1366
+ ...definition.args ?? []
1366
1367
  ];
1367
1368
  const folder = join(state.evidence, "services", service);
1368
1369
  const elapsed = stopwatch();