@antelopejs/tooling-configs 0.2.17 → 0.2.18

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 (39) hide show
  1. package/README.md +27 -18
  2. package/dist/bin/api-diff.mjs +25 -14
  3. package/dist/bin/body-check.mjs +3 -3
  4. package/dist/bin/capture.d.mts +1 -0
  5. package/dist/bin/capture.mjs +559 -0
  6. package/dist/bin/check-size.mjs +3 -3
  7. package/dist/bin/checks.mjs +2 -2
  8. package/dist/bin/comment-proof.mjs +3 -3
  9. package/dist/bin/garden.mjs +1 -1
  10. package/dist/bin/ratchet.mjs +146 -100
  11. package/dist/bin/suppressions.mjs +5 -5
  12. package/dist/bin/sync.mjs +115 -169
  13. package/dist/bin/verify.mjs +238 -125
  14. package/dist/capture/index.d.mts +50 -0
  15. package/dist/capture/index.mjs +2 -0
  16. package/dist/{files-Bc036sJW.mjs → files-DJ0TeaTU.mjs} +10 -4
  17. package/dist/formal/index.d.mts +40 -0
  18. package/dist/formal/index.mjs +205 -0
  19. package/dist/oxc/anti-slop/index.mjs +717 -16
  20. package/dist/oxc/fmt.mjs +1 -1
  21. package/dist/oxc/guardrails/index.d.mts +1 -1
  22. package/dist/oxc/guardrails/index.mjs +93 -5
  23. package/dist/oxc/lint.d.mts +9 -0
  24. package/dist/oxc/lint.mjs +14 -3
  25. package/dist/{oxlint-Bltmk8-6.mjs → oxlint-DIV-lLSS.mjs} +7 -3
  26. package/dist/{package-DTxLPNDu.mjs → package-BRTjkzt5.mjs} +26 -1
  27. package/dist/{proof-stamp-w-3j47A-.mjs → proof-stamp-DDDC0J6l.mjs} +3 -3
  28. package/dist/{ratchet-DwRj9h4L.mjs → ratchet-BAcLRYuM.mjs} +194 -21
  29. package/dist/scenes-DZVXkcxS.mjs +104 -0
  30. package/dist/shared-igPpEDpS.mjs +622 -0
  31. package/dist/{size-DNtWruCO.mjs → size-DBatLT-F.mjs} +2 -2
  32. package/dist/{suppression-base-DAfCXwjL.mjs → suppression-base-9L8dlMQK.mjs} +36 -11
  33. package/dist/{suppression-budget-Bd2GqMYb.mjs → suppression-budget-C0SkPO5R.mjs} +56 -19
  34. package/dist/{suppressions-BD_f8f7L.mjs → suppressions-DM60NkvL.mjs} +1 -1
  35. package/dist/templates-CypDm-j9.mjs +121 -0
  36. package/dist/{typescript-BmS5BmrS.mjs → typescript-CM0LrVP7.mjs} +2 -2
  37. package/dist/verify/index.d.mts +6 -1
  38. package/package.json +28 -4
  39. package/dist/shared-CoUt4GUm.mjs +0 -73
package/dist/bin/sync.mjs CHANGED
@@ -1,21 +1,29 @@
1
1
  #!/usr/bin/env node
2
2
  import { a as formatCeilings, l as readCeilings, s as isRetired, t as CEILINGS_FILE } from "../ceilings-B7KayYIG.mjs";
3
- import { a as VERIFY_KINDS, c as isVerifyKind, i as SYNCED_SKILL_FILES, l as skillFolder, o as claudeLink, s as claudeLinkTarget } from "../shared-CoUt4GUm.mjs";
3
+ import { a as repositoryTools, i as parseManifest, n as managedPackage, o as templatePackage, r as packageManager, s as toolingVersions } from "../package-BRTjkzt5.mjs";
4
+ import { i as presetConfig, n as SETUP_SCRIPT, r as lefthook, t as PRESET_CONFIGS } from "../templates-CypDm-j9.mjs";
5
+ 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";
4
6
  import { t as runCli } from "../cli-4Tv71vYk.mjs";
5
- import { o as repositoryRoot } from "../files-Bc036sJW.mjs";
6
- import { a as repositoryTools, i as parseManifest, n as managedPackage, o as toolingVersions, r as packageManager, t as execCommand } from "../package-DTxLPNDu.mjs";
7
- import { r as recordedRelease, t as measureBaseline } from "../ratchet-DwRj9h4L.mjs";
8
- import { n as SUPPRESSIONS_FILE, r as adoptedBudget } from "../suppression-budget-Bd2GqMYb.mjs";
7
+ import { c as repositoryRoot } from "../files-DJ0TeaTU.mjs";
8
+ import { i as recordedRelease, t as measureBaseline } from "../ratchet-BAcLRYuM.mjs";
9
+ import { n as SUPPRESSIONS_FILE, r as adoptedBudget } from "../suppression-budget-C0SkPO5R.mjs";
9
10
  import { a as MUTATION_PATH, c as MISSING_CHECKS_WORKFLOW, d as hasChecksWorkflow, l as ciNodeCallers, o as ciWorkflow, r as CI_PATH, s as mutationCaller, u as ciRenovateSyncCallers } from "../ci-workflow-ChW4He0r.mjs";
10
11
  import { chmodSync, existsSync, lstatSync, mkdirSync, readFileSync, readdirSync, readlinkSync, rmdirSync, statSync, symlinkSync, unlinkSync, writeFileSync } from "node:fs";
11
12
  import { dirname, join, resolve } from "node:path";
12
13
  import { execFileSync } from "node:child_process";
13
- import { parseArgs } from "node:util";
14
14
  import { isMap, isScalar, isSeq, parseDocument } from "yaml";
15
15
  import ts from "typescript";
16
+ import { parseArgs } from "node:util";
16
17
  //#region src/guardrails/agents-block.ts
17
18
  const AGENTS_BLOCK_START = "<!-- antelopejs-guardrails:start -->";
18
19
  const AGENTS_BLOCK_END = "<!-- antelopejs-guardrails:end -->";
20
+ const ITERATION = `### While you work
21
+
22
+ \`pnpm run checks\` runs every step, so run it once, at the end. While you iterate, run only the check that covers what you changed:
23
+
24
+ - \`pnpm run typecheck\` after you change types or signatures.
25
+ - \`pnpm exec oxlint <files>\` and \`pnpm exec oxfmt <files>\` on the files you changed.
26
+ - Run one test file instead of the whole suite. In a module that tests with \`ajs module test\`, run \`pnpm run build\`, then \`pnpm exec ajs module test . -f dist/<path>.test.js\`. Repeat \`-f\` for more files.`;
19
27
  const COMMENTS = `### Comments
20
28
 
21
29
  Say it in code. A constraint belongs in a type, a lint rule, or a test. A public item's contract belongs in TSDoc (\`/** */\`) on that item. The only other comments are lint directives that name their rules, \`@ts-expect-error <reason>\`, \`SAFETY: <reason>\` above a type assertion, \`/*!\` license headers, and bundler or formatter directives.
@@ -45,7 +53,7 @@ Moving a method body into a function keeps how it is called: the same receiver,
45
53
  Verify a boundary against the imports a developer or agent would plausibly write: static and dynamic imports, re-exports, Vue \`src\`, CSS \`@import\`, and worker or child-process entries in normally named files. A construction only an evasion would write, an edit to resolution configuration (\`package.json\` \`browser\`, \`exports\`, \`main\` or \`imports\`, bundler aliases, tsconfig \`paths\`), and a difference observable only by patching private fields or internal methods go under Attention and never block. Public API and ordinary subclass behaviour stay part of the contract.`;
46
54
  const SUPPRESSION_BUDGET = `### Suppression budget
47
55
 
48
- \`guardrails.suppressions.json\` caps the suppressions in authored code: lint directives per rule they name (\`*\` for none), \`@ts-expect-error\`, \`@ts-ignore\` and \`SAFETY:\` comments, and under \`config\` each rule a lint config (\`oxlint.config.*\`, \`.oxlintrc.json\`, \`eslint.config.*\`) switches off or to a warning, keyed by rule and \`files\` glob anchored at the config's directory, so widening or moving a scope is a new ceiling of 0, while narrowing one takes over the room it gives up. Switching a rule off in a config is a suppression too: fix the code its rule reports instead. A suppression over its ceiling fails: fix the code, or remove another suppression of the same kind. A rule that keeps needing suppressions should be changed in the preset. Never raise or remove a number in that file: the check fails a ceiling higher than on the pull request base, and only the operator approves a raise. A directive disabling \`anti-slop/require-safety-comment-for-type-assertion\` is burn-down debt: remove the assertion, or, where it holds, replace the directive with \`SAFETY: <why it holds>\`, which takes over its room without a raise. After you remove suppressions, run \`pnpm run suppressions:update\` and commit the lowered file.`;
56
+ \`guardrails.suppressions.json\` caps the suppressions in authored code, the repository's own files under \`.agents/\`, \`.claude/\` and the other agent directories included (\`agentFiles\`; only what \`antelopejs-sync\` writes there is skipped): lint directives per rule they name (\`*\` for none), \`@ts-expect-error\`, \`@ts-ignore\` and \`SAFETY:\` comments, and under \`config\` each rule a lint config (\`oxlint.config.*\`, \`.oxlintrc.json\`, \`eslint.config.*\`) switches off or to a warning, keyed by rule and \`files\` glob anchored at the config's directory, so widening or moving a scope is a new ceiling of 0, while narrowing one takes over the room it gives up. Switching a rule off in a config is a suppression too: fix the code its rule reports instead. A suppression over its ceiling fails: fix the code, or remove another suppression of the same kind. A rule that keeps needing suppressions should be changed in the preset. Never raise or remove a number in that file: the check fails a ceiling higher than on the pull request base, and only the operator approves a raise. A directive disabling \`anti-slop/require-safety-comment-for-type-assertion\` is burn-down debt: remove the assertion, or, where it holds, replace the directive with \`SAFETY: <why it holds>\`, which takes over its room without a raise. After you remove suppressions, run \`pnpm run suppressions:update\` and commit the lowered file.`;
49
57
  const SHARED_RULES = [
50
58
  ["Formatting", "oxfmt"],
51
59
  ["Lint findings are errors; no rule warns", "oxlint preset"],
@@ -58,6 +66,7 @@ const SHARED_RULES = [
58
66
  ["String-keyed object tables are read through own keys only", "`antelopejs/no-inherited-key-lookup`"],
59
67
  ["A type guard checks each member it narrows to; keys with `Object.hasOwn`", "`antelopejs/no-presence-only-type-guard`"],
60
68
  ["A type guard checks the nested elements and values it claims", "review; no tool"],
69
+ ["Every file type-aware lint reads is listed by a tsconfig", "`antelopejs/require-tsconfig-include`"],
61
70
  ["Params ≤ 5, function ≤ 120 lines, file ≤ 500 lines, depth ≤ 4, complexity ≤ 20", "`eslint/max-*`, `eslint/complexity`"],
62
71
  ["Cleanup preserves declarations, runtime exports and DMS auto-imports", "`antelopejs-api-diff <base-ref>`"],
63
72
  ["Comment-only changes preserve JavaScript emit", "`antelopejs-comment-proof <base-ref>`"],
@@ -72,7 +81,7 @@ const SHARED_RULES = [
72
81
  ["No `any` passed, assigned or returned where a type is declared", "`typescript/no-unsafe-{argument,assignment,return}`"]
73
82
  ];
74
83
  const FULL_RULES = [
75
- ["Files ≤ 20,000 bytes, tests included", "`antelopejs-check-size` (pre-commit)"],
84
+ ["Files ≤ 20,000 bytes, tests and agent files included", "`antelopejs-check-size` (pre-commit)"],
76
85
  ["Suppressions stay within `guardrails.suppressions.json`", "`antelopejs-suppressions` (pre-commit, checks)"],
77
86
  ["No lint config switches off a rule to stay under the budget", "`antelopejs-suppressions` (pre-commit, checks)"],
78
87
  ["No added directive disables the `SAFETY:`, comment or test rules", "`antelopejs-suppressions` (pre-commit, checks)"],
@@ -113,6 +122,8 @@ function fullBody(context) {
113
122
  "",
114
123
  `Finish every change with \`pnpm run checks\`. It runs typecheck, lint, format, knip, tests, size, ${context.ratchet ? "ratchet, " : ""}suppressions, and sync, and prints only what failed. The change is done when it prints no failure.`,
115
124
  "",
125
+ ITERATION,
126
+ "",
116
127
  ...pointers(context).flatMap((line) => [line, ""]),
117
128
  "The tools enforce most rules, listed in the table at the end. The sections below hold the rules no tool checks.",
118
129
  "",
@@ -167,124 +178,6 @@ function agentsBlock(context) {
167
178
  ].join("\n");
168
179
  }
169
180
  //#endregion
170
- //#region src/guardrails/templates.ts
171
- const PRESET_CONFIGS = [
172
- {
173
- path: "oxlint.config.ts",
174
- legacy: [".oxlintrc.json"],
175
- specifier: "@antelopejs/tooling-configs/oxc/lint",
176
- content: "import { defineConfig } from \"oxlint\";\nimport {\n ANTELOPE_IGNORE_PATTERNS,\n antelopePreset,\n} from \"@antelopejs/tooling-configs/oxc/lint\";\n\nexport default defineConfig({\n extends: [antelopePreset()],\n ignorePatterns: ANTELOPE_IGNORE_PATTERNS,\n options: { typeAware: true },\n});\n",
177
- previous: ["import { defineConfig } from \"oxlint\";\nimport { antelopePreset } from \"@antelopejs/tooling-configs/oxc/lint\";\n\nexport default defineConfig({\n extends: [antelopePreset()],\n options: { typeAware: true },\n});\n"]
178
- },
179
- {
180
- path: "oxfmt.config.ts",
181
- legacy: [".oxfmtrc.json"],
182
- specifier: "@antelopejs/tooling-configs/oxc/fmt",
183
- content: "import { antelopeFmtPreset } from \"@antelopejs/tooling-configs/oxc/fmt\";\n\nexport default antelopeFmtPreset();\n"
184
- },
185
- {
186
- path: "knip.config.ts",
187
- legacy: [
188
- "knip.json",
189
- "knip.jsonc",
190
- ".knip.json"
191
- ],
192
- specifier: "@antelopejs/tooling-configs/knip",
193
- content: "import { antelopeKnipConfig } from \"@antelopejs/tooling-configs/knip\";\n\nexport default antelopeKnipConfig();\n"
194
- }
195
- ];
196
- function presetConfig(current, preset, tools) {
197
- const target = tools.presets[preset.path];
198
- const specifier = target.replaceAll("/", "\\/").replaceAll(".", "\\.");
199
- const imported = new RegExp(`(?:\\bfrom\\s*|\\bimport\\s*\\(?\\s*)["']${specifier}["']`);
200
- const fresh = preset.content.replace(preset.specifier, target);
201
- if (current === void 0 || preset.previous?.some((previous) => previous.replace(preset.specifier, target) === current)) return fresh;
202
- if (imported.test(current)) return current;
203
- const importLine = preset.content.split("\n").filter((line) => line.includes(preset.specifier)).join("\n").replace(preset.specifier, target);
204
- throw new Error(`${preset.path} does not import its preset. Add \`${importLine}\` and extend that preset, then rerun antelopejs-sync. The file was not replaced.`);
205
- }
206
- function lefthook(current, manager, tools, ratchet = true) {
207
- const exec = execCommand(manager);
208
- const document = parseDocument(current ?? "{}\n");
209
- if (document.errors.length) throw new Error(`lefthook.yml: ${document.errors.map(({ message }) => message).join("; ")}`);
210
- if (!isMap(document.contents)) throw new Error("lefthook.yml must contain a YAML mapping. Merge the guardrail hooks manually and rerun antelopejs-sync.");
211
- if (current === void 0) document.contents.flow = false;
212
- const glob = "*.{js,mjs,cjs,jsx,ts,mts,cts,tsx,vue}";
213
- const hooks = {
214
- "pre-commit": {
215
- "antelopejs-format": {
216
- run: `${exec} oxfmt --no-error-on-unmatched-pattern {staged_files}`,
217
- stage_fixed: true
218
- },
219
- "antelopejs-lint": {
220
- glob,
221
- run: `${exec} oxlint --no-error-on-unmatched-pattern {staged_files}`
222
- },
223
- "antelopejs-size": { run: `${tools.hookPrefix}${tools.commands.size} --staged {staged_files}` },
224
- "antelopejs-ratchet": {
225
- glob,
226
- run: `${tools.hookPrefix}${tools.commands.ratchet} --staged {staged_files}`
227
- },
228
- "antelopejs-suppressions": {
229
- glob,
230
- run: `${tools.hookPrefix}${tools.commands.suppressions} --staged`
231
- }
232
- },
233
- "pre-push": { "antelopejs-typecheck": { run: `${manager} run typecheck` } }
234
- };
235
- for (const [hook, commands] of Object.entries(hooks)) {
236
- for (const path of [[hook], [hook, "commands"]]) {
237
- if (!document.hasIn(path)) document.setIn(path, document.createNode({}));
238
- if (!isMap(document.getIn(path))) throw new Error(`lefthook.yml: ${path.join(".")} must be a mapping. Preserve the existing hook and merge its commands before rerunning antelopejs-sync.`);
239
- }
240
- for (const [key, command] of Object.entries(commands)) document.setIn([
241
- hook,
242
- "commands",
243
- key
244
- ], document.createNode(command));
245
- }
246
- if (!ratchet) document.deleteIn([
247
- "pre-commit",
248
- "commands",
249
- "antelopejs-ratchet"
250
- ]);
251
- return document.toString({ lineWidth: 0 });
252
- }
253
- const SETUP_SCRIPT = `#!/usr/bin/env bash
254
- set -euo pipefail
255
- cd "$(dirname "$BASH_SOURCE")/.."
256
- export CI=1 COREPACK_ENABLE_DOWNLOAD_PROMPT=0
257
- major="$(tr -d 'v[:space:]' < .nvmrc)"
258
- if [[ "$(node -p 'process.versions.node.split(".")[0]')" != "$major" ]]; then
259
- if command -v fnm >/dev/null 2>&1; then
260
- eval "$(fnm env --shell bash)"
261
- fnm install "$major"
262
- fnm use "$major"
263
- else
264
- export NVM_DIR="\${NVM_DIR:-$HOME/.nvm}"
265
- if [[ ! -s "$NVM_DIR/nvm.sh" ]]; then
266
- git clone --quiet --depth 1 --branch v0.40.3 https://github.com/nvm-sh/nvm.git "$NVM_DIR"
267
- fi
268
- source "$NVM_DIR/nvm.sh" --no-use
269
- nvm install "$major"
270
- nvm use "$major"
271
- fi
272
- fi
273
- pin="$(node -p 'JSON.parse(require("node:fs").readFileSync("package.json", "utf8")).packageManager || "pnpm"')"
274
- manager="\${pin%%@*}"
275
- corepack enable
276
- if [[ "$pin" == *@* ]]; then
277
- corepack prepare "$pin" --activate
278
- fi
279
- case "$manager" in
280
- pnpm) pnpm install --frozen-lockfile ;;
281
- yarn) YARN_ENABLE_IMMUTABLE_INSTALLS=true yarn install --frozen-lockfile ;;
282
- npm) npm ci ;;
283
- bun) bun install --frozen-lockfile ;;
284
- *) printf 'Unsupported package manager %s\\n' "$manager" >&2; exit 1 ;;
285
- esac
286
- `;
287
- //#endregion
288
181
  //#region src/guardrails/backend-boundary.ts
289
182
  /** Where a DMS frontend layer keeps its backend boundary plugin, relative to the layer. */
290
183
  const BACKEND_BOUNDARY_FILE = "build/backend-boundary.ts";
@@ -530,7 +423,10 @@ function checkEntryOnlyConfiguration(root) {
530
423
  //#region src/guardrails/docs-compat.ts
531
424
  const DOCS_COMPAT_START = "<!-- antelopejs-docs-compat:start -->";
532
425
  const DOCS_COMPAT_END = "<!-- antelopejs-docs-compat:end -->";
426
+ const DOCS_NODE_START = "<!-- antelopejs-docs-node:start -->";
427
+ const DOCS_NODE_END = "<!-- antelopejs-docs-node:end -->";
533
428
  const LOCKFILE = "pnpm-lock.yaml";
429
+ const REQUIREMENTS_HEADING = /^##\s+Requirements\s*$/i;
534
430
  const SCOPE = "@antelopejs/";
535
431
  const UNRESOLVED = "—";
536
432
  const LEGACY_MARKER = /^<!--\s*docs-compat:\s*\.\/package\.json#\w+\s*-->\s*$/;
@@ -617,6 +513,30 @@ function placeCompatBlock(current, block) {
617
513
  const before = text.trimEnd();
618
514
  return `${before}${before ? "\n\n" : ""}## Compatibility\n\n${block}`;
619
515
  }
516
+ /** The generated Node prerequisite block for an `engines.node` range, formatted as oxfmt leaves it. */
517
+ function nodeBlock(range) {
518
+ return `${DOCS_NODE_START}\n\nThis package requires Node.js \`${range}\`.\n${DOCS_NODE_END}\n`;
519
+ }
520
+ /** The README with the Node block in place: between its markers, under `## Requirements`, or in a new `## Requirements` section at the end. */
521
+ function placeNodeBlock(current, block) {
522
+ const start = current.indexOf(DOCS_NODE_START);
523
+ const end = current.indexOf(DOCS_NODE_END);
524
+ if (start === -1 !== (end === -1) || end < start) throw new Error("incomplete antelopejs-docs-node markers. Repair or delete them, then rerun antelopejs-sync.");
525
+ if (start !== -1) return `${current.slice(0, start)}${block}${current.slice(end + 33).replace(/^\r?\n/, "")}`;
526
+ const lines = current.split("\n");
527
+ const heading = lines.findIndex((line) => REQUIREMENTS_HEADING.test(line));
528
+ if (heading !== -1) {
529
+ let rest = heading + 1;
530
+ while (rest < lines.length && !lines[rest].trim()) rest++;
531
+ return finalNewline([
532
+ ...lines.slice(0, heading + 1),
533
+ "",
534
+ ...block.trimEnd().split("\n"),
535
+ ...rest < lines.length ? ["", ...lines.slice(rest)] : []
536
+ ].join("\n"));
537
+ }
538
+ return `${current.trimEnd()}\n\n## Requirements\n\n${block}`;
539
+ }
620
540
  function relative$1(directory, name) {
621
541
  return directory ? `${directory}/${name}` : name;
622
542
  }
@@ -682,10 +602,9 @@ function linkedVersion(root, directory, link) {
682
602
  const target = join(root, directory, link);
683
603
  return existsSync(join(target, "package.json")) ? parseManifest(readFileSync(join(target, "package.json"), "utf8")).version : void 0;
684
604
  }
685
- function resolvedVersion(root, lock, directory, name) {
686
- const importer = directory || ".";
605
+ function resolvedVersion(root, { document, importer }, directory, name) {
687
606
  for (const section of RESOLVED_SECTIONS) {
688
- const entry = lock.getIn([
607
+ const entry = document.getIn([
689
608
  "importers",
690
609
  importer,
691
610
  section,
@@ -697,15 +616,56 @@ function resolvedVersion(root, lock, directory, name) {
697
616
  return resolved.startsWith("link:") ? linkedVersion(root, directory, resolved.slice(5)) : resolved;
698
617
  }
699
618
  }
700
- function readLock(root) {
701
- const path = join(root, LOCKFILE);
702
- return existsSync(path) ? parseDocument(readFileSync(path, "utf8")) : void 0;
619
+ const UNSHARED_NPMRC = /^\s*shared-workspace-lockfile\s*=\s*false\s*(?:[#;].*)?$/m;
620
+ /** Whether the workspace keeps one root lockfile, or `shared-workspace-lockfile=false` gives each package its own. */
621
+ function sharesLockfile(root) {
622
+ const npmrc = join(root, ".npmrc");
623
+ if (existsSync(npmrc) && UNSHARED_NPMRC.test(readFileSync(npmrc, "utf8"))) return false;
624
+ const workspace = join(root, "pnpm-workspace.yaml");
625
+ return !(existsSync(workspace) && parseDocument(readFileSync(workspace, "utf8")).get("sharedWorkspaceLockfile") === false);
626
+ }
627
+ /** The lockfile path of a package, relative to the root. A shared lockfile is the root's, indexed by the package directory. */
628
+ function lockPath(shared, directory) {
629
+ return shared ? LOCKFILE : relative$1(directory, LOCKFILE);
630
+ }
631
+ function readLock(root, shared, directory) {
632
+ const path = join(root, lockPath(shared, directory));
633
+ return existsSync(path) ? {
634
+ document: parseDocument(readFileSync(path, "utf8")),
635
+ importer: shared ? directory || "." : "."
636
+ } : void 0;
637
+ }
638
+ /** Adds one package's `docs-files` lines and, when it needs one, its README with the generated blocks. */
639
+ function planPackage(root, plan, lock, standard, { directory, ranges, published, node }) {
640
+ const readme = relative$1(directory, "README.md");
641
+ const docs = relative$1(directory, "docs");
642
+ if (!published) return;
643
+ if (ranges.size > 0 || existsSync(join(root, readme))) plan.docsFiles.push(readme);
644
+ if (isDirectory(root, docs)) plan.docsFiles.push(docs);
645
+ const current = existsSync(join(root, readme)) ? readFileSync(join(root, readme), "utf8") : void 0;
646
+ const nodeRange = standard && current !== void 0 ? node : void 0;
647
+ if (ranges.size === 0 && nodeRange === void 0) return;
648
+ const rows = [...ranges].map(([name, supported]) => ({
649
+ name,
650
+ supported,
651
+ tested: lock && resolvedVersion(root, lock, directory, name)
652
+ }));
653
+ try {
654
+ const withRequirements = nodeRange !== void 0 && current !== void 0 ? placeNodeBlock(current, nodeBlock(nodeRange)) : current;
655
+ plan.readmes.push({
656
+ path: readme,
657
+ current,
658
+ content: rows.length > 0 ? placeCompatBlock(withRequirements, compatBlock(rows)) : withRequirements ?? ""
659
+ });
660
+ } catch (error) {
661
+ plan.errors.push(`${readme}: ${error instanceof Error ? error.message : String(error)}`);
662
+ }
703
663
  }
704
664
  /**
705
665
  * Plans the docs-compat block of the root and of every workspace package that is not private and declares an
706
666
  * `@antelopejs/*` peer, runtime or optional dependency, and the `docs-files` lines covering the root and every workspace
707
667
  * package that is not private.
708
- * Tested with comes from pnpm-lock.yaml; other package managers get a dash.
668
+ * Tested with comes from pnpm-lock.yaml, each package's own when `shared-workspace-lockfile=false`; other package managers get a dash.
709
669
  */
710
670
  function planDocs(root, manager) {
711
671
  const rootManifest = readManifest(root, "");
@@ -714,6 +674,7 @@ function planDocs(root, manager) {
714
674
  return {
715
675
  directory,
716
676
  published: !directory || !manifest.private,
677
+ node: manifest.engines?.node,
717
678
  ranges: manifest.private ? /* @__PURE__ */ new Map() : declaredRanges(manifest)
718
679
  };
719
680
  });
@@ -724,35 +685,15 @@ function planDocs(root, manager) {
724
685
  errors: [],
725
686
  exists: (path) => existsSync(join(root, path))
726
687
  };
727
- const lock = manager === "pnpm" ? readLock(root) : void 0;
728
- if (manager === "pnpm" && qualifying.length && !lock) {
729
- plan.errors.push(`${LOCKFILE} is missing, and the docs-compat block reads Tested with from it: run pnpm install, then rerun antelopejs-sync.`);
688
+ const shared = sharesLockfile(root);
689
+ const locks = new Map(packages.map(({ directory }) => [directory, manager === "pnpm" ? readLock(root, shared, directory) : void 0]));
690
+ const missing = manager === "pnpm" ? qualifying.filter(({ directory }) => !locks.get(directory)) : [];
691
+ if (missing.length) {
692
+ for (const path of new Set(missing.map(({ directory }) => lockPath(shared, directory)))) plan.errors.push(`${path} is missing, and the docs-compat block reads Tested with from it: run pnpm install, then rerun antelopejs-sync.`);
730
693
  return plan;
731
694
  }
732
- for (const { directory, ranges, published } of packages) {
733
- const readme = relative$1(directory, "README.md");
734
- const docs = relative$1(directory, "docs");
735
- const generated = ranges.size > 0;
736
- if (!published) continue;
737
- if (generated || existsSync(join(root, readme))) plan.docsFiles.push(readme);
738
- if (isDirectory(root, docs)) plan.docsFiles.push(docs);
739
- if (!generated) continue;
740
- const rows = [...ranges].map(([name, supported]) => ({
741
- name,
742
- supported,
743
- tested: lock && resolvedVersion(root, lock, directory, name)
744
- }));
745
- const current = existsSync(join(root, readme)) ? readFileSync(join(root, readme), "utf8") : void 0;
746
- try {
747
- plan.readmes.push({
748
- path: readme,
749
- current,
750
- content: placeCompatBlock(current, compatBlock(rows))
751
- });
752
- } catch (error) {
753
- plan.errors.push(`${readme}: ${error instanceof Error ? error.message : String(error)}`);
754
- }
755
- }
695
+ const standard = rootManifest.antelopeJs?.docs?.standard === true;
696
+ for (const item of packages) planPackage(root, plan, locks.get(item.directory), standard, item);
756
697
  return plan;
757
698
  }
758
699
  /** The kind-specific text of each shared skill. */
@@ -880,7 +821,7 @@ ${BIN} clean <run>
880
821
 
881
822
  - \`verify.config.ts\` default-exports a \`VerifyConfig\` from \`@antelopejs/tooling-configs/verify\`:
882
823
  - \`doors\`: one entry per door kind (\`data\`, \`format\`, \`contract\`, \`outbound\`, \`exposure\`, \`publish\`), each \`null\` when it cannot apply or \`{ globs, funnels, containments, why }\`. \`containments\` names the \`feature/journey\` journeys that contain a Data or Format door. Each must fail with that kind's seeded door applied and pass without it: write the journey so one of its checks reads the state the door corrupts.
883
- - \`journeys\`: the repository's journeys by id, each \`{ title, entryPoint, run(context) }\`, using the check helpers the same import exports.
824
+ - \`journeys\`: the repository's journeys by id, each \`{ title, entryPoint, run(context) }\`, using the check helpers the same import exports. A check states what the product must do; an environment that went away is never a failing check. When a journey fails, the harness reruns each service's readiness command, up to four times over about 3.5 s, and looks at every \`ajs project dev\` the journey started, its own readiness probe included. The journey ends NOT VERIFIED, not FAIL, when a service still fails every rerun, an app was killed by SIGKILL, SIGTERM, SIGHUP or SIGINT that the harness did not send, or the app the harness started failed to bind the port the harness gave it (\`EADDRINUSE\` naming that port). An app that exits on its own with an exit code, one that crashes by another signal such as SIGABRT or SIGSEGV, and one that logs \`EADDRINUSE\` for any other port are the product's failure. A break that takes its own service down still reads as an outage: the service stays down, so the journey is NOT VERIFIED and \`seeded\` does not count it. For anything else the journey depends on, such as a process it started with \`context.command\` or an outside endpoint, probe it when a check fails and call \`context.notVerified(reason)\` when it no longer answers.
884
825
  - \`env\`, \`setup\` (commands replacing the build), \`userFacing\` (globs replacing the kind's default) and \`formal\` (formal checks: \`name\`, \`covers\`, \`command\`, \`violation\`, and optionally \`behaviour\` and \`baseCommand\`).
885
826
  ${text.layer}
886
827
  - \`features/<feature>.md\`: frontmatter lists \`covers:\` (source globs), \`docs:\` (pages a verdict judges) and \`journeys:\`, then the sections Sub-features, How to get to it (user POV), Driving it with antelopejs-verify, and Gotchas. \`features/smoke.md\` covers nothing and runs on every verdict; here it runs ${text.smoke}.
@@ -897,7 +838,7 @@ ${BIN} map
897
838
 
898
839
  1. **Run every feature whose \`covers:\` globs the diff touches, plus \`smoke\`.** \`plan\` prints that list as \`run\`.
899
840
  2. **An unmapped surface fails the verdict.** A changed user-facing file no feature covers needs a feature entry, its journeys and its seeded break in the same PR.
900
- 3. **Every registered journey of a feature in \`run\` must have run and passed.** Run whole features. A journey that could not reach the product is NOT VERIFIED, and so is the verdict, whatever else passed: never PASS and never PASS+NOTES.
841
+ 3. **Every registered journey of a feature in \`run\` must have run and passed.** Run whole features. A journey that could not reach the product, or whose environment went away during it, is NOT VERIFIED, and so is the verdict, whatever else passed: never PASS and never PASS+NOTES. Every journey result in the run's evidence counts, also for a feature outside \`run\`: a failed one fails the verdict, because it shows a \`covers:\` glob that misses what the diff broke. A NOT VERIFIED one outside \`run\` is listed under Not verified and caps the result at PASS+NOTES. A journey outside \`run\` that never ran is not required.
901
842
  4. **Docs.** Judge every \`docs:\` page of a touched feature against what the journeys showed. A stale page fails the verdict.
902
843
  5. **Formal checks.** \`${BIN} formal <run>\` runs every formal check of \`verify.config.ts\` that covers the diff, or whose own \`files\` the diff changes, and records it under \`evidence/formal/<name>/\`. For each one it decides, without judgement, whether the diff changed what the covered code does. \`emit\` (the default) compares the structure of the covered files' JavaScript on the base and on HEAD: node kinds, names and literal values, leaving out types, comments, formatting, parentheses and \`export\` keywords. Each use of an imported binding stands for its origin (the resolved module and the imported name), so an import retargeted to another module or alias counts as changed; a function declaration refers to the top-level variables and classes of its own file by file and name, so moving it next to a different variable of the same name counts as changed. Exports are keyed by the origin they export, so a re-export or an \`export { f as run }\` retargeted to another binding counts as changed. Each file must keep its top-level statements and its side-effect imports in order; function declarations, which are hoisted, may move between covered files with their imports. So a type-only edit, a reformat or a moved function declaration counts as unchanged, while reordering statements or moving any other statement counts as changed. \`emit\` judges behaviour, not the public surface: exports are the api-diff's job. \`probe\` runs the check's \`behaviour.command\` with a worktree of each commit and compares what it prints. Then:
903
844
  - a covered check that did not run, or exits non-zero (a tool error, or a check that no longer matches its record), fails the verdict;
@@ -945,7 +886,7 @@ ${BIN} seeded-doors
945
886
  ${BIN} containments
946
887
  \`\`\`
947
888
 
948
- \`seeded\` runs each feature's journeys in a scratch worktree of HEAD without the patch, as the control, and with \`seeded-breaks/<feature>.patch\` applied. It prints \`CAUGHT\` only when a journey that passes in the control fails one of its checks with the patch. Journeys failing in the control and failures without a failing check do not count. \`seeded-doors\` prints \`FLAGGED\` when the path rules flag each patch with its own kind. \`containments\` runs every Data and Format containment journey in a scratch worktree of HEAD without the door, as the control, and with \`seeded-doors/<kind>.patch\` applied. It prints \`CONTAINED\` only when the journey passes in the control and fails one of its checks with the door. \`MISSED\` means it passes with its door, \`UNPROVEN\` that it fails in the control or ends without a failing check, and \`NO-DOOR\` that the kind has no seeded door; the command exits 1 on anything but \`CONTAINED\`.
889
+ \`seeded\` runs each feature's journeys in a scratch worktree of HEAD without the patch, as the control, and with \`seeded-breaks/<feature>.patch\` applied. It prints \`CAUGHT\` only when a journey that passes in the control fails one of its checks with the patch. Journeys failing in the control, failures without a failing check and NOT VERIFIED journeys do not count. A break no journey caught is \`NOT VERIFIED\` when a journey could not reach the product in either run, for example because a service went away, and \`MISSED\` otherwise. The command exits 1 on anything but \`CAUGHT\`. \`seeded-doors\` prints \`FLAGGED\` when the path rules flag each patch with its own kind. \`containments\` runs every Data and Format containment journey in a scratch worktree of HEAD without the door, as the control, and with \`seeded-doors/<kind>.patch\` applied. It prints \`CONTAINED\` only when the journey passes in the control and fails one of its checks with the door. \`MISSED\` means it passes with its door, \`UNPROVEN\` that it fails in the control or ends without a failing check, and \`NO-DOOR\` that the kind has no seeded door; the command exits 1 on anything but \`CONTAINED\`.
949
890
 
950
891
  ## Gotchas
951
892
 
@@ -962,11 +903,14 @@ const SKILL_PACKAGE = `${JSON.stringify({
962
903
  /**
963
904
  * The skill folder's tsconfig.json: it gives the repository's files there the root compiler options with ES module resolution,
964
905
  * so type-aware lint sees real types. The root tsconfig cannot include them: its `rootDir` is usually `src`.
906
+ * `types` names Node: type-aware lint does not discover `@types/node` from this folder, so without it every Node API call
907
+ * in a skill file is error-typed and reported by `typescript/no-unsafe-*` (tooling-configs#93).
965
908
  */
966
909
  const SKILL_TSCONFIG = `${JSON.stringify({
967
910
  extends: "../../../tsconfig.json",
968
911
  compilerOptions: {
969
912
  rootDir: "../../..",
913
+ types: ["node"],
970
914
  module: "nodenext",
971
915
  moduleResolution: "nodenext",
972
916
  allowImportingTsExtensions: true,
@@ -1194,9 +1138,9 @@ const MANAGED_ARTIFACTS = [
1194
1138
  },
1195
1139
  {
1196
1140
  path: "package.json",
1197
- profiles: ["full"],
1141
+ profiles: ["full", "template"],
1198
1142
  desired: (current, context) => ({
1199
- content: managedPackage(current, context.versions, context),
1143
+ content: context.profile === "full" ? managedPackage(current, context.versions, context) : templatePackage(current, context),
1200
1144
  notes: []
1201
1145
  })
1202
1146
  },
@@ -1378,12 +1322,14 @@ function syncRepository(root, options = {}) {
1378
1322
  manifest,
1379
1323
  profile
1380
1324
  });
1325
+ const writing = planDocsSkills(root);
1326
+ const actions = [...verify.actions, ...writing.actions];
1381
1327
  const context = repositoryContext(root, current, profile, verify.verificationSkill);
1382
1328
  const boundaries = backendBoundaryArtifacts(root);
1383
1329
  let plan = [...planSync(current, modes, context), ...boundaries];
1384
1330
  const errors = plan.filter((artifact) => artifact.kind === "error").map(({ message }) => message);
1385
1331
  const entryOnly = checkEntryOnlyConfiguration(root);
1386
- errors.push(...entryOnly.errors, ...verify.errors);
1332
+ errors.push(...entryOnly.errors, ...verify.errors, ...writing.errors);
1387
1333
  const notes = plan.flatMap((artifact) => artifact.kind === "migrated" ? artifact.notes : []);
1388
1334
  (options.check ? errors : notes).push(...repositoryNotices(root, context));
1389
1335
  if (!errors.length && profile === "full" && !options.check && !current.has("guardrails.ratchet.json") && manifest.scripts?.["sync:check"] === void 0) {
@@ -1400,15 +1346,15 @@ function syncRepository(root, options = {}) {
1400
1346
  const writes = plan.filter((artifact) => artifact.kind === "write" || artifact.kind === "migrated");
1401
1347
  if (!options.check && !errors.length) {
1402
1348
  writeArtifacts(root, writes);
1403
- applyVerifyActions(root, verify.actions);
1349
+ applyVerifyActions(root, actions);
1404
1350
  }
1405
1351
  const requiredDependencies = ["lefthook", "knip"];
1406
1352
  if (context.typeAware) requiredDependencies.push("oxlint-tsgolint");
1407
1353
  const dependenciesAdded = profile === "full" && requiredDependencies.some((name) => !manifest.devDependencies?.[name]);
1408
1354
  return {
1409
1355
  artifacts: plan,
1410
- paths: errors.length ? [] : [...writes, ...verify.actions].map(({ path }) => path),
1411
- removed: verify.actions.filter((action) => action.kind === "remove").map(({ path }) => path),
1356
+ paths: errors.length ? [] : [...writes, ...actions].map(({ path }) => path),
1357
+ removed: actions.filter((action) => action.kind === "remove").map(({ path }) => path),
1412
1358
  errors,
1413
1359
  notes,
1414
1360
  verifyNotes: options.check || errors.length ? [] : verify.notes,