@antelopejs/tooling-configs 0.2.16 → 0.2.17

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (41) hide show
  1. package/README.md +88 -48
  2. package/dist/bin/api-diff.mjs +409 -97
  3. package/dist/bin/body-check.d.mts +1 -0
  4. package/dist/bin/body-check.mjs +344 -0
  5. package/dist/bin/check-size.mjs +3 -3
  6. package/dist/bin/checks.mjs +3 -3
  7. package/dist/bin/comment-proof.mjs +4 -3
  8. package/dist/bin/garden.mjs +5 -5
  9. package/dist/bin/ratchet.mjs +267 -7
  10. package/dist/bin/suppressions.mjs +118 -80
  11. package/dist/bin/sync.mjs +490 -35
  12. package/dist/bin/verify.mjs +5 -5
  13. package/dist/{ceilings-BSw9p4YB.mjs → ceilings-B7KayYIG.mjs} +11 -3
  14. package/dist/{checks-BlWDFYio.mjs → checks-CxkSu2E6.mjs} +1 -1
  15. package/dist/{ci-workflow-DIsoEgMd.mjs → ci-workflow-ChW4He0r.mjs} +84 -3
  16. package/dist/{files-2FikHZ9F.mjs → files-Bc036sJW.mjs} +2 -2
  17. package/dist/{json-BqvuCkqr.mjs → json-CG2L7YFl.mjs} +12 -8
  18. package/dist/oxc/anti-slop/index.mjs +160 -13
  19. package/dist/oxc/fmt.mjs +1 -1
  20. package/dist/oxc/guardrails/index.d.mts +1 -1
  21. package/dist/oxc/guardrails/index.mjs +645 -1
  22. package/dist/oxc/lint.d.mts +11 -3
  23. package/dist/oxc/lint.mjs +21 -8
  24. package/dist/oxlint-Bltmk8-6.mjs +94 -0
  25. package/dist/{package-Dtjt_lSa.mjs → package-DTxLPNDu.mjs} +3 -2
  26. package/dist/proof-stamp-w-3j47A-.mjs +279 -0
  27. package/dist/ratchet-DwRj9h4L.mjs +275 -0
  28. package/dist/{renames-BGO4dWJ8.mjs → renames-L2owF5GD.mjs} +2 -2
  29. package/dist/shared-CoUt4GUm.mjs +73 -0
  30. package/dist/{size-BVgNbLO6.mjs → size-DNtWruCO.mjs} +3 -3
  31. package/dist/suppression-base-DAfCXwjL.mjs +95 -0
  32. package/dist/{suppression-budget-Yyf5_J5l.mjs → suppression-budget-Bd2GqMYb.mjs} +248 -33
  33. package/dist/{suppressions-BJAngUxo.mjs → suppressions-BD_f8f7L.mjs} +180 -18
  34. package/dist/typescript-BmS5BmrS.mjs +222 -0
  35. package/dist/verify/index.mjs +1 -1
  36. package/package.json +4 -2
  37. package/dist/kinds-Bzyyi9yk.mjs +0 -25
  38. package/dist/ratchet-DRdIYwmv.mjs +0 -80
  39. package/dist/shared-CsXIMK3I.mjs +0 -34
  40. package/dist/staged-ratchet-CjoRfZaM.mjs +0 -236
  41. package/dist/typescript-C54ONh9m.mjs +0 -433
package/dist/bin/sync.mjs CHANGED
@@ -1,17 +1,18 @@
1
1
  #!/usr/bin/env node
2
- import { a as formatCeilings, o as isRetired, s as readCeilings, t as CEILINGS_FILE } from "../ceilings-BSw9p4YB.mjs";
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
4
  import { t as runCli } from "../cli-4Tv71vYk.mjs";
4
- import { o as repositoryRoot } from "../files-2FikHZ9F.mjs";
5
- import { a as repositoryTools, i as parseManifest, n as managedPackage, o as toolingVersions, r as packageManager, t as execCommand } from "../package-Dtjt_lSa.mjs";
6
- import { t as measureBaseline } from "../ratchet-DRdIYwmv.mjs";
7
- import { n as SUPPRESSIONS_FILE, r as adoptedBudget } from "../suppression-budget-Yyf5_J5l.mjs";
8
- 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-DIsoEgMd.mjs";
9
- import { a as skillFolder, i as isVerifyKind, n as claudeLink, r as claudeLinkTarget, t as VERIFY_KINDS } from "../kinds-Bzyyi9yk.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";
9
+ 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
10
  import { chmodSync, existsSync, lstatSync, mkdirSync, readFileSync, readdirSync, readlinkSync, rmdirSync, statSync, symlinkSync, unlinkSync, writeFileSync } from "node:fs";
11
11
  import { dirname, join, resolve } from "node:path";
12
12
  import { execFileSync } from "node:child_process";
13
13
  import { parseArgs } from "node:util";
14
- import { isMap, parseDocument } from "yaml";
14
+ import { isMap, isScalar, isSeq, parseDocument } from "yaml";
15
+ import ts from "typescript";
15
16
  //#region src/guardrails/agents-block.ts
16
17
  const AGENTS_BLOCK_START = "<!-- antelopejs-guardrails:start -->";
17
18
  const AGENTS_BLOCK_END = "<!-- antelopejs-guardrails:end -->";
@@ -31,9 +32,9 @@ Hold every test you write or keep to this checklist:
31
32
  - An invariant over many files is a lint rule, not a test.`;
32
33
  const CLEANUP_PROOF = `### Cleanup proof
33
34
 
34
- A behaviour-preserving cleanup PR shows \`antelopejs-api-diff <base-ref>\` passing. Published declarations and built runtime exports stay unchanged; pass \`--allow-added <glob>\` (repeatable, e.g. \`'**/internal/**'\`) to let added entries under that glob pass when their module is \`@internal\`, and copy its "Added (allowed)" list. A comment-only PR shows \`antelopejs-comment-proof <base-ref>\` passing instead of a verifier. Both compare committed HEAD.
35
+ A behaviour-preserving cleanup PR shows \`antelopejs-api-diff <base-ref>\` passing. Published declarations, built runtime exports and the names and signatures a DMS frontend module auto-imports stay unchanged; pass \`--allow-added <glob>\` (repeatable, e.g. \`'**/internal/**'\`) to let added entries under that glob pass when their module is \`@internal\`, and copy its "Added (allowed)" list. Every export under a directory that \`dms.frontend.build.ts\` auto-imports is published, \`@internal\` or not; a helper that must stay private goes under \`app/build/\`. A comment-only PR shows \`antelopejs-comment-proof <base-ref>\` passing instead of a verifier. Both compare committed HEAD.
35
36
 
36
- Copy counts from the proof's base and HEAD table. Never type counts by hand. Keep the command and the committed head beside the copied output. The table counts a lint directive once per rule it names, inline directives included.
37
+ Copy the proof's whole output into the PR body, down to its closing \`<!-- antelopejs-proof ... -->\` line, which stamps the command, base, committed head and a digest. Never type counts by hand. List the lint findings a PR leaves in place by pasting the block \`antelopejs-body-check --findings\` prints and replacing each \`<why>\`. \`antelopejs-body-check <body.md>\` fails an edited or stale proof block, proof output outside one, and a findings line that is not a live diagnostic at HEAD; counts in prose are not checked, so leave them out. The table counts a lint directive once per rule it names, inline directives included.
37
38
 
38
39
  Pass \`--probe <file.cjs>\` to api-diff when changing receivers, positional calls, or modules that no published entry reaches. The same captured script runs against both worktree roots, supplied as \`argv[2]\`, and prints JSON observations. Matching metadata alone does not prove those behaviours.
39
40
 
@@ -44,7 +45,7 @@ Moving a method body into a function keeps how it is called: the same receiver,
44
45
  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.`;
45
46
  const SUPPRESSION_BUDGET = `### Suppression budget
46
47
 
47
- \`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. 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.`;
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.`;
48
49
  const SHARED_RULES = [
49
50
  ["Formatting", "oxfmt"],
50
51
  ["Lint findings are errors; no rule warns", "oxlint preset"],
@@ -54,26 +55,36 @@ const SHARED_RULES = [
54
55
  ["Tests import the code under test from local source, not their own package name", "`antelopejs/no-self-import-in-tests`"],
55
56
  ["No assertion that restates a constant", "`antelopejs/no-constant-value-assertion`"],
56
57
  ["No test whose only check is \"is a function\"", "`antelopejs/no-typeof-function-only-test`"],
58
+ ["String-keyed object tables are read through own keys only", "`antelopejs/no-inherited-key-lookup`"],
59
+ ["A type guard checks each member it narrows to; keys with `Object.hasOwn`", "`antelopejs/no-presence-only-type-guard`"],
60
+ ["A type guard checks the nested elements and values it claims", "review; no tool"],
57
61
  ["Params ≤ 5, function ≤ 120 lines, file ≤ 500 lines, depth ≤ 4, complexity ≤ 20", "`eslint/max-*`, `eslint/complexity`"],
58
- ["Cleanup preserves declarations and built runtime export metadata", "`antelopejs-api-diff <base-ref>`"],
62
+ ["Cleanup preserves declarations, runtime exports and DMS auto-imports", "`antelopejs-api-diff <base-ref>`"],
59
63
  ["Comment-only changes preserve JavaScript emit", "`antelopejs-comment-proof <base-ref>`"],
60
- ["PR-body counts come from tracked code files", "api-diff and comment-proof tables"],
64
+ ["PR-body proof tables are copied unedited from the current head", "`antelopejs-body-check <body.md>`"],
65
+ ["PR-body findings-left lines are live diagnostics at HEAD", "`antelopejs-body-check <body.md>`"],
61
66
  ["Receiver, positional and unpublished-module behaviour", "`antelopejs-api-diff <base-ref> --probe <file.cjs>`"],
62
67
  ["Directive and `SAFETY:` reasons are true of the code", "review; no tool"],
63
68
  ["Evasion-only and patched-internal findings go under Attention", "review; no tool"],
64
69
  ["No-upward rules reject same-tier peers", "review and import probes"],
65
- ["No `@ts-ignore`", "`typescript/ban-ts-comment`"]
70
+ ["No `@ts-ignore`", "`typescript/ban-ts-comment`"],
71
+ ["No once-used type parameter standing in for `unknown`", "`typescript/no-unnecessary-type-parameters`"],
72
+ ["No `any` passed, assigned or returned where a type is declared", "`typescript/no-unsafe-{argument,assignment,return}`"]
66
73
  ];
67
74
  const FULL_RULES = [
68
75
  ["Files ≤ 20,000 bytes, tests included", "`antelopejs-check-size` (pre-commit)"],
69
76
  ["Suppressions stay within `guardrails.suppressions.json`", "`antelopejs-suppressions` (pre-commit, checks)"],
77
+ ["No lint config switches off a rule to stay under the budget", "`antelopejs-suppressions` (pre-commit, checks)"],
70
78
  ["No added directive disables the `SAFETY:`, comment or test rules", "`antelopejs-suppressions` (pre-commit, checks)"],
71
79
  ["An added suppression gives a specific reason", "`antelopejs-suppressions` (pre-commit, checks)"],
80
+ ["A directive in a file a change touches suppresses something and gives a reason", "`antelopejs-suppressions` (pre-commit, checks)"],
72
81
  ["A block disable is closed in its file", "`antelopejs-suppressions` (pre-commit, checks)"],
73
82
  ["Types check", "`tsc` (pre-push)"],
74
83
  ["No dead files, exports, or dependencies", "knip"],
75
84
  ["Managed files match the pack", "`antelopejs-sync --check`"],
85
+ ["A CI gate reads `needs.<id>` only of jobs in its `needs`", "`antelopejs-sync --check`"],
76
86
  ["Entry-only rules exempt no tracked outsider", "`antelopejs-sync --check`"],
87
+ ["A DMS layer's `build/backend-boundary.ts` is the pack's plugin", "`antelopejs-sync --check`"],
77
88
  ["A test names the wrong implementation it catches", "review; no tool"]
78
89
  ];
79
90
  /** Pads each column the way oxfmt does, so formatting AGENTS.md never reports sync drift. */
@@ -116,7 +127,7 @@ function fullBody(context) {
116
127
  ...context.ratchet ? [
117
128
  "### Debt",
118
129
  "",
119
- "`guardrails.ratchet.json` records the lint findings and oversize files this repository already had. Its numbers only go down. After you remove debt, run `pnpm run ratchet:update` and commit the lowered file. A rule listed there is off for `oxlint`. The ratchet counts it instead, and the pre-commit hook rejects it on every line you add.",
130
+ "`guardrails.ratchet.json` records the lint findings and oversize files this repository already had. Its numbers only go down. After you remove debt, or after a pack upgrade, run `pnpm run ratchet:update` and commit the file: it lowers the numbers and adds only the rules the new pack release enabled, at today's count. Never edit the numbers by hand; CI fails one added or raised against the base. A rule listed there is off for `oxlint`. The ratchet counts it instead, and the pre-commit hook rejects it on every line you add.",
120
131
  ""
121
132
  ] : [],
122
133
  ruleTable([
@@ -162,7 +173,8 @@ const PRESET_CONFIGS = [
162
173
  path: "oxlint.config.ts",
163
174
  legacy: [".oxlintrc.json"],
164
175
  specifier: "@antelopejs/tooling-configs/oxc/lint",
165
- content: "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"
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"]
166
178
  },
167
179
  {
168
180
  path: "oxfmt.config.ts",
@@ -185,7 +197,8 @@ function presetConfig(current, preset, tools) {
185
197
  const target = tools.presets[preset.path];
186
198
  const specifier = target.replaceAll("/", "\\/").replaceAll(".", "\\.");
187
199
  const imported = new RegExp(`(?:\\bfrom\\s*|\\bimport\\s*\\(?\\s*)["']${specifier}["']`);
188
- if (current === void 0) return preset.content.replace(preset.specifier, target);
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;
189
202
  if (imported.test(current)) return current;
190
203
  const importLine = preset.content.split("\n").filter((line) => line.includes(preset.specifier)).join("\n").replace(preset.specifier, target);
191
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.`);
@@ -272,6 +285,178 @@ case "$manager" in
272
285
  esac
273
286
  `;
274
287
  //#endregion
288
+ //#region src/guardrails/backend-boundary.ts
289
+ /** Where a DMS frontend layer keeps its backend boundary plugin, relative to the layer. */
290
+ const BACKEND_BOUNDARY_FILE = "build/backend-boundary.ts";
291
+ /** The backend boundary plugin a DMS frontend layer registers in `dms.frontend.build.ts`, for the package that holds the layer. */
292
+ function backendBoundarySource(backendPackage) {
293
+ return `import { existsSync, readFileSync, realpathSync } from 'node:fs'
294
+ import { dirname, isAbsolute, join, relative, sep } from 'node:path'
295
+ import type { DmsVitePluginEntry } from '#dms/frontend-build'
296
+
297
+ type VitePlugin = Extract<DmsVitePluginEntry, { name: string }>
298
+
299
+ const BACKEND_PACKAGE = ${JSON.stringify(backendPackage)}
300
+ const BACKEND_SOURCE = 'src'
301
+ const QUERY_OR_HASH = /[?#].*$/
302
+
303
+ const backendRoots = new Map<string, string | null>()
304
+
305
+ /** Whether a parsed manifest names its package. */
306
+ function isNamedManifest(value: unknown): value is { name: string } {
307
+ return (
308
+ typeof value === 'object' &&
309
+ value !== null &&
310
+ 'name' in value &&
311
+ typeof value.name === 'string'
312
+ )
313
+ }
314
+
315
+ /** The package name a \`package.json\` declares, or \`undefined\`. */
316
+ function packageName(manifest: string): string | undefined {
317
+ try {
318
+ const parsed: unknown = JSON.parse(readFileSync(manifest, 'utf8'))
319
+ return isNamedManifest(parsed) ? parsed.name : undefined
320
+ } catch {
321
+ return undefined
322
+ }
323
+ }
324
+
325
+ /** The directory of the backend package that holds \`directory\`, or null. */
326
+ function backendRoot(directory: string): string | null {
327
+ const known = backendRoots.get(directory)
328
+ if (known !== undefined) {
329
+ return known
330
+ }
331
+ const manifest = join(directory, 'package.json')
332
+ const parent = dirname(directory)
333
+ let root: string | null = null
334
+ if (existsSync(manifest)) {
335
+ root = packageName(manifest) === BACKEND_PACKAGE ? directory : null
336
+ } else if (parent !== directory) {
337
+ root = backendRoot(parent)
338
+ }
339
+ backendRoots.set(directory, root)
340
+ return root
341
+ }
342
+
343
+ /**
344
+ * The real path of a resolved module id when it lies under the \`src\`
345
+ * directory of the backend package, or \`undefined\`. The package that owns the
346
+ * file decides, not a path, so the answer is the same in the repository and in
347
+ * the build workspace. Virtual ids and ids that are not files are ignored.
348
+ */
349
+ function backendSourceFile(id: string): string | undefined {
350
+ const path = id.replace(QUERY_OR_HASH, '')
351
+ if (!isAbsolute(path)) {
352
+ return undefined
353
+ }
354
+ let real: string
355
+ try {
356
+ real = realpathSync(path)
357
+ } catch {
358
+ return undefined
359
+ }
360
+ const root = backendRoot(dirname(real))
361
+ if (root === null) {
362
+ return undefined
363
+ }
364
+ return relative(root, real).split(sep)[0] === BACKEND_SOURCE
365
+ ? real
366
+ : undefined
367
+ }
368
+
369
+ /**
370
+ * Fails the build and the dev server when a module of the frontend resolves to
371
+ * a file under the \`src\` of the backend package: the browser reaches the
372
+ * backend only through its HTTP interface. It checks what the whole resolution
373
+ * chain returns, an id marked external included, so an alias is seen through
374
+ * and a symlink the resolver returns is followed to its real path, and it runs
375
+ * before the other plugins (\`enforce: "pre"\`). Vite builds workers with their
376
+ * own plugin list, so the plugin adds itself there too.
377
+ *
378
+ * antelopejs-sync writes this file from \`@antelopejs/tooling-configs\` and
379
+ * restores it on every run: change the plugin in the pack, not here.
380
+ */
381
+ export function backendBoundary(): VitePlugin {
382
+ return {
383
+ ...boundaryCheck(),
384
+ config: () => ({ worker: { plugins: () => [boundaryCheck()] } }),
385
+ }
386
+ }
387
+
388
+ /** The check alone, as a worker build runs it. */
389
+ function boundaryCheck(): VitePlugin {
390
+ return {
391
+ name: \`\${BACKEND_PACKAGE}:backend-boundary\`,
392
+ enforce: 'pre',
393
+ async resolveId(source, importer, options) {
394
+ const resolved = await this.resolve(source, importer, {
395
+ ...options,
396
+ skipSelf: true,
397
+ })
398
+ if (resolved === null) {
399
+ return resolved
400
+ }
401
+ const file = backendSourceFile(resolved.id)
402
+ if (file === undefined) {
403
+ return resolved
404
+ }
405
+ const from =
406
+ importer === undefined
407
+ ? 'an entry point'
408
+ : importer.replace(QUERY_OR_HASH, '')
409
+ return this.error(
410
+ \`Backend boundary: \${from} imports \${file}, which is under the src of \${BACKEND_PACKAGE}. The frontend reaches the backend only through its HTTP interface.\`,
411
+ )
412
+ },
413
+ }
414
+ }
415
+ `;
416
+ }
417
+ /** The syntax tree of `text` without trivia, parentheses or quote style, so a formatter's rewrite compares equal to the original. */
418
+ function formatFreeProgram(text) {
419
+ const parts = [];
420
+ const visit = (node) => {
421
+ if (ts.isParenthesizedExpression(node) || ts.isParenthesizedTypeNode(node)) return void ts.forEachChild(node, visit);
422
+ parts.push(ts.SyntaxKind[node.kind]);
423
+ if (ts.isIdentifier(node) || ts.isPrivateIdentifier(node) || ts.isLiteralExpression(node) || ts.isTemplateHead(node) || ts.isTemplateMiddle(node) || ts.isTemplateTail(node)) parts.push(JSON.stringify(node.text));
424
+ ts.forEachChild(node, visit);
425
+ };
426
+ visit(ts.createSourceFile("backend-boundary.ts", text, ts.ScriptTarget.Latest, false, ts.ScriptKind.TS));
427
+ return parts.join(" ");
428
+ }
429
+ /** The sync plan for every tracked backend boundary plugin under `root`: each one is the pack's plugin for the package that holds its layer, in any formatting. */
430
+ function backendBoundaryArtifacts(root) {
431
+ return execFileSync("git", [
432
+ "ls-files",
433
+ "-z",
434
+ "--",
435
+ `:(glob)**/${BACKEND_BOUNDARY_FILE}`
436
+ ], {
437
+ cwd: root,
438
+ encoding: "utf8"
439
+ }).split("\0").filter((path) => path && dirname(dirname(path)) !== ".").map((path) => {
440
+ const manifest = join(dirname(dirname(dirname(path))), "package.json");
441
+ const name = existsSync(join(root, manifest)) ? parseManifest(readFileSync(join(root, manifest), "utf8")).name : void 0;
442
+ if (!name) return {
443
+ kind: "error",
444
+ path,
445
+ message: `${path} guards the backend package ${manifest}, which has no name. Name that package, then rerun antelopejs-sync.`
446
+ };
447
+ const content = backendBoundarySource(name);
448
+ return formatFreeProgram(existsSync(join(root, path)) ? readFileSync(join(root, path), "utf8") : "") === formatFreeProgram(content) ? {
449
+ kind: "unchanged",
450
+ path
451
+ } : {
452
+ kind: "write",
453
+ path,
454
+ content,
455
+ mode: void 0
456
+ };
457
+ });
458
+ }
459
+ //#endregion
275
460
  //#region src/guardrails/entry-only.ts
276
461
  const LOAD_RULES = `
277
462
  const advisories = [];
@@ -341,6 +526,235 @@ function checkEntryOnlyConfiguration(root) {
341
526
  advisories
342
527
  };
343
528
  }
529
+ //#endregion
530
+ //#region src/guardrails/docs-compat.ts
531
+ const DOCS_COMPAT_START = "<!-- antelopejs-docs-compat:start -->";
532
+ const DOCS_COMPAT_END = "<!-- antelopejs-docs-compat:end -->";
533
+ const LOCKFILE = "pnpm-lock.yaml";
534
+ const SCOPE = "@antelopejs/";
535
+ const UNRESOLVED = "—";
536
+ const LEGACY_MARKER = /^<!--\s*docs-compat:\s*\.\/package\.json#\w+\s*-->\s*$/;
537
+ const COMPATIBILITY_HEADING = /^##\s+Compatibility\s*$/i;
538
+ const RESOLVED_SECTIONS = [
539
+ "dependencies",
540
+ "optionalDependencies",
541
+ "devDependencies"
542
+ ];
543
+ /** The generated block, rows sorted by package name, formatted as oxfmt leaves it. */
544
+ function compatBlock(rows) {
545
+ const table = [[
546
+ "Package",
547
+ "Supported",
548
+ "Tested with"
549
+ ], ...[...rows].sort((a, b) => a.name < b.name ? -1 : a.name > b.name ? 1 : 0).map(({ name, supported, tested }) => [
550
+ `\`${name}\``,
551
+ `\`${supported.replaceAll("|", "\\|")}\``,
552
+ tested === void 0 ? UNRESOLVED : `\`${tested}\``
553
+ ])];
554
+ const widths = [
555
+ 0,
556
+ 1,
557
+ 2
558
+ ].map((column) => Math.max(3, ...table.map((row) => row[column].length)));
559
+ const line = (cells) => `| ${cells.map((cell, column) => cell.padEnd(widths[column])).join(" | ")} |`;
560
+ return [
561
+ DOCS_COMPAT_START,
562
+ "",
563
+ line(table[0]),
564
+ line(widths.map((width) => "-".repeat(width))),
565
+ ...table.slice(1).map(line),
566
+ "",
567
+ DOCS_COMPAT_END,
568
+ ""
569
+ ].join("\n");
570
+ }
571
+ function legacySpanEnd(lines, marker) {
572
+ let index = marker + 1;
573
+ while (index < lines.length && !lines[index].trim()) index++;
574
+ while (index < lines.length && lines[index].trimStart().startsWith("|")) index++;
575
+ while (index < lines.length && !lines[index].trim()) index++;
576
+ return index;
577
+ }
578
+ function replaceLegacyTables(lines, block) {
579
+ const placed = [];
580
+ let replaced = false;
581
+ for (let index = 0; index < lines.length;) {
582
+ if (!LEGACY_MARKER.test(lines[index])) {
583
+ placed.push(lines[index]);
584
+ index++;
585
+ continue;
586
+ }
587
+ if (!replaced) placed.push(...block.split("\n"));
588
+ replaced = true;
589
+ index = legacySpanEnd(lines, index);
590
+ }
591
+ return replaced ? placed : void 0;
592
+ }
593
+ function finalNewline(text) {
594
+ return text.endsWith("\n") ? text : `${text}\n`;
595
+ }
596
+ /** The README with the block in place: replacing the markers, a legacy `docs-compat` table, or under `## Compatibility`. */
597
+ function placeCompatBlock(current, block) {
598
+ const text = current ?? "";
599
+ const start = text.indexOf(DOCS_COMPAT_START);
600
+ const end = text.indexOf(DOCS_COMPAT_END);
601
+ if (start === -1 !== (end === -1) || end < start) throw new Error("incomplete antelopejs-docs-compat markers. Repair or delete them, then rerun antelopejs-sync.");
602
+ if (start !== -1) return `${text.slice(0, start)}${block}${text.slice(end + 35).replace(/^\r?\n/, "")}`;
603
+ const lines = text.split("\n");
604
+ const legacy = replaceLegacyTables(lines, block);
605
+ if (legacy) return finalNewline(legacy.join("\n"));
606
+ const heading = lines.findIndex((line) => COMPATIBILITY_HEADING.test(line));
607
+ if (heading !== -1) {
608
+ let rest = heading + 1;
609
+ while (rest < lines.length && !lines[rest].trim()) rest++;
610
+ return finalNewline([
611
+ ...lines.slice(0, heading + 1),
612
+ "",
613
+ ...block.split("\n"),
614
+ ...lines.slice(rest)
615
+ ].join("\n"));
616
+ }
617
+ const before = text.trimEnd();
618
+ return `${before}${before ? "\n\n" : ""}## Compatibility\n\n${block}`;
619
+ }
620
+ function relative$1(directory, name) {
621
+ return directory ? `${directory}/${name}` : name;
622
+ }
623
+ function isDirectory(root, path) {
624
+ return statSync(join(root, path), { throwIfNoEntry: false })?.isDirectory() === true;
625
+ }
626
+ function subdirectories(root, directory) {
627
+ return readdirSync(join(root, directory), { withFileTypes: true }).filter((entry) => entry.isDirectory() && entry.name !== "node_modules" && !entry.name.startsWith(".")).map((entry) => relative$1(directory, entry.name));
628
+ }
629
+ function descendants(root, directory) {
630
+ return subdirectories(root, directory).flatMap((child) => [child, ...descendants(root, child)]);
631
+ }
632
+ function globExpression(pattern) {
633
+ const source = pattern.split("/").map((segment) => segment === "**" ? "(?:.*)" : segment.replace(/[.+^${}()|[\]\\]/g, "\\$&").replaceAll("*", "[^/]*").replaceAll("?", "[^/]")).join("/").replaceAll("(?:.*)/", "(?:.*/)?");
634
+ return new RegExp(`^${source}$`);
635
+ }
636
+ function expand(root, pattern) {
637
+ let directories = [""];
638
+ for (const segment of pattern.split("/")) if (segment === "**") directories = directories.flatMap((directory) => [directory, ...descendants(root, directory)]);
639
+ else if (/[*?]/.test(segment)) {
640
+ const expression = globExpression(segment);
641
+ directories = directories.flatMap((directory) => subdirectories(root, directory).filter((child) => expression.test(child.slice(child.lastIndexOf("/") + 1))));
642
+ } else directories = directories.map((directory) => relative$1(directory, segment)).filter((directory) => isDirectory(root, directory));
643
+ return directories;
644
+ }
645
+ function normalizePattern(pattern) {
646
+ return pattern.replace(/^(?:\.\/)+/, "").replace(/\/+$/, "").replace(/^\.$/, "");
647
+ }
648
+ function scalarItems(document, path) {
649
+ const node = document.getIn(path, true);
650
+ return isSeq(node) ? node.items.flatMap((item) => isScalar(item) ? [String(item.value)] : []) : [];
651
+ }
652
+ /** pnpm-workspace.yaml `packages`, else package.json `workspaces` as an array or as `{ packages }`; JSON parses as YAML. */
653
+ function workspacePatterns(root) {
654
+ const pnpm = join(root, "pnpm-workspace.yaml");
655
+ if (existsSync(pnpm)) return scalarItems(parseDocument(readFileSync(pnpm, "utf8")), ["packages"]);
656
+ const manifest = parseDocument(readFileSync(join(root, "package.json"), "utf8"));
657
+ return scalarItems(manifest, isMap(manifest.get("workspaces", true)) ? ["workspaces", "packages"] : ["workspaces"]);
658
+ }
659
+ function workspaceDirectories(root) {
660
+ const patterns = workspacePatterns(root);
661
+ const excluded = patterns.filter((pattern) => pattern.startsWith("!")).map((pattern) => globExpression(normalizePattern(pattern.slice(1))));
662
+ const found = /* @__PURE__ */ new Set();
663
+ for (const pattern of patterns.filter((item) => !item.startsWith("!"))) {
664
+ const normalized = normalizePattern(pattern);
665
+ for (const directory of normalized ? expand(root, normalized) : [""]) if (directory && !excluded.some((expression) => expression.test(directory)) && existsSync(join(root, directory, "package.json"))) found.add(directory);
666
+ }
667
+ return [...found].sort();
668
+ }
669
+ function declaredRanges(manifest) {
670
+ const ranges = /* @__PURE__ */ new Map();
671
+ for (const field of [
672
+ manifest.optionalDependencies,
673
+ manifest.dependencies,
674
+ manifest.peerDependencies
675
+ ]) for (const [name, range] of Object.entries(field ?? {})) if (name.startsWith(SCOPE)) ranges.set(name, range);
676
+ return ranges;
677
+ }
678
+ function readManifest(root, directory) {
679
+ return parseManifest(readFileSync(join(root, directory, "package.json"), "utf8"));
680
+ }
681
+ function linkedVersion(root, directory, link) {
682
+ const target = join(root, directory, link);
683
+ return existsSync(join(target, "package.json")) ? parseManifest(readFileSync(join(target, "package.json"), "utf8")).version : void 0;
684
+ }
685
+ function resolvedVersion(root, lock, directory, name) {
686
+ const importer = directory || ".";
687
+ for (const section of RESOLVED_SECTIONS) {
688
+ const entry = lock.getIn([
689
+ "importers",
690
+ importer,
691
+ section,
692
+ name
693
+ ], true);
694
+ const version = isMap(entry) ? entry.get("version", true) : entry;
695
+ if (!isScalar(version)) continue;
696
+ const resolved = String(version.value).split("(")[0];
697
+ return resolved.startsWith("link:") ? linkedVersion(root, directory, resolved.slice(5)) : resolved;
698
+ }
699
+ }
700
+ function readLock(root) {
701
+ const path = join(root, LOCKFILE);
702
+ return existsSync(path) ? parseDocument(readFileSync(path, "utf8")) : void 0;
703
+ }
704
+ /**
705
+ * Plans the docs-compat block of the root and of every workspace package that is not private and declares an
706
+ * `@antelopejs/*` peer, runtime or optional dependency, and the `docs-files` lines covering the root and every workspace
707
+ * package that is not private.
708
+ * Tested with comes from pnpm-lock.yaml; other package managers get a dash.
709
+ */
710
+ function planDocs(root, manager) {
711
+ const rootManifest = readManifest(root, "");
712
+ const packages = ["", ...workspaceDirectories(root)].map((directory) => {
713
+ const manifest = directory ? readManifest(root, directory) : rootManifest;
714
+ return {
715
+ directory,
716
+ published: !directory || !manifest.private,
717
+ ranges: manifest.private ? /* @__PURE__ */ new Map() : declaredRanges(manifest)
718
+ };
719
+ });
720
+ const qualifying = packages.filter(({ ranges }) => ranges.size > 0);
721
+ const plan = {
722
+ readmes: [],
723
+ docsFiles: [],
724
+ errors: [],
725
+ exists: (path) => existsSync(join(root, path))
726
+ };
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.`);
730
+ return plan;
731
+ }
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
+ }
756
+ return plan;
757
+ }
344
758
  /** The kind-specific text of each shared skill. */
345
759
  const KIND_TEXT = {
346
760
  interface: {
@@ -421,7 +835,7 @@ description: ${JSON.stringify(text.description)}
421
835
 
422
836
  ${text.user} Every deterministic step is an \`antelopejs-verify\` command: you choose which journeys to run and judge what they show. Never replace a command with a shell recipe. When a journey you need does not exist, add it to \`verify.config.ts\`, name it in its feature file, then run it.
423
837
 
424
- \`antelopejs-sync\` writes this file and \`package.json\` here, and keeps them in sync. Everything else in \`${folder}/\` is the repository's own layer, which sync never touches.
838
+ \`antelopejs-sync\` writes this file, \`package.json\` and \`tsconfig.json\` here, and keeps them in sync. Everything else in \`${folder}/\` is the repository's own layer, which sync never touches.
425
839
 
426
840
  ## Launch
427
841
 
@@ -545,15 +959,33 @@ const SKILL_PACKAGE = `${JSON.stringify({
545
959
  private: true,
546
960
  type: "module"
547
961
  }, null, 2)}\n`;
962
+ /**
963
+ * The skill folder's tsconfig.json: it gives the repository's files there the root compiler options with ES module resolution,
964
+ * so type-aware lint sees real types. The root tsconfig cannot include them: its `rootDir` is usually `src`.
965
+ */
966
+ const SKILL_TSCONFIG = `${JSON.stringify({
967
+ extends: "../../../tsconfig.json",
968
+ compilerOptions: {
969
+ rootDir: "../../..",
970
+ module: "nodenext",
971
+ moduleResolution: "nodenext",
972
+ allowImportingTsExtensions: true,
973
+ composite: false,
974
+ noEmit: true
975
+ },
976
+ include: ["**/*.ts"]
977
+ }, null, 2)}\n`;
548
978
  /** Every file of a kind's synced layer, by path relative to the repository root. */
549
979
  function syncedFiles(kind) {
550
- return [{
551
- path: `${skillFolder(kind)}/SKILL.md`,
552
- content: skillText(kind)
553
- }, {
554
- path: `${skillFolder(kind)}/package.json`,
555
- content: SKILL_PACKAGE
556
- }];
980
+ const content = {
981
+ "SKILL.md": skillText(kind),
982
+ "package.json": SKILL_PACKAGE,
983
+ "tsconfig.json": SKILL_TSCONFIG
984
+ };
985
+ return SYNCED_SKILL_FILES.map((file) => ({
986
+ path: `${skillFolder(kind)}/${file}`,
987
+ content: content[file]
988
+ }));
557
989
  }
558
990
  //#endregion
559
991
  //#region src/guardrails/verify-skill.ts
@@ -747,8 +1179,8 @@ const MANAGED_ARTIFACTS = [
747
1179
  {
748
1180
  path: CI_PATH,
749
1181
  profiles: ["full", "template"],
750
- desired: (current) => ({
751
- content: ciWorkflow(current, current === void 0 ? [] : ciNodeCallers(current), current === void 0 ? [] : ciRenovateSyncCallers(current)),
1182
+ desired: (current, context) => ({
1183
+ content: ciWorkflow(current, current === void 0 ? [] : ciNodeCallers(current), current === void 0 ? [] : ciRenovateSyncCallers(current), context.docs),
752
1184
  notes: []
753
1185
  })
754
1186
  },
@@ -809,8 +1241,8 @@ const MANAGED_ARTIFACTS = [
809
1241
  {
810
1242
  path: SUPPRESSIONS_FILE,
811
1243
  profiles: ["full"],
812
- desired: (current, context) => ({
813
- content: current ?? context.suppressionBudget,
1244
+ desired: (_current, context) => ({
1245
+ content: context.suppressionBudget,
814
1246
  notes: []
815
1247
  })
816
1248
  }
@@ -854,8 +1286,25 @@ function planSync(current, modes, context) {
854
1286
  });
855
1287
  }
856
1288
  }
1289
+ plan.push(...plannedDocs(context.docs));
857
1290
  return plan;
858
1291
  }
1292
+ function plannedDocs(docs) {
1293
+ if (!docs) return [];
1294
+ return [...docs.errors.map((message) => ({
1295
+ kind: "error",
1296
+ path: "README.md",
1297
+ message
1298
+ })), ...docs.readmes.map(({ path, current, content }) => current === content ? {
1299
+ kind: "unchanged",
1300
+ path
1301
+ } : {
1302
+ kind: "write",
1303
+ path,
1304
+ content,
1305
+ mode: void 0
1306
+ })];
1307
+ }
859
1308
  function repositorySnapshot(root) {
860
1309
  const current = /* @__PURE__ */ new Map();
861
1310
  const modes = /* @__PURE__ */ new Map();
@@ -885,21 +1334,23 @@ function repositoryContext(root, current, profile, verificationSkill) {
885
1334
  const manifest = parseManifest(current.get("package.json") ?? "{}");
886
1335
  const lint = PRESET_CONFIGS[0];
887
1336
  const desiredLint = current.get(lint.path) ?? lint.content;
1337
+ const manager = packageManager(manifest);
888
1338
  return {
889
1339
  profile,
890
1340
  ratchet: current.has(CEILINGS_FILE),
891
- manager: packageManager(manifest),
1341
+ manager,
892
1342
  versions: toolingVersions(),
893
1343
  tools: repositoryTools(manifest),
894
1344
  typeAware: /\btypeAware["']?\s*:\s*true\b/.test(desiredLint),
895
1345
  nuxt: Boolean(manifest.dependencies?.nuxt || manifest.devDependencies?.nuxt || readdirSync(root).some((name) => name.startsWith("nuxt.config."))),
896
1346
  claude: profile === "full" ? claudeProse(root, current) : "",
897
1347
  baseline: "",
898
- suppressionBudget: profile === "full" && !current.has("guardrails.suppressions.json") ? adoptedBudget(root) : "",
1348
+ suppressionBudget: profile === "full" ? adoptedBudget(root, current.get(SUPPRESSIONS_FILE)) : "",
899
1349
  packageName: manifest.name ?? "",
900
1350
  managesCi: current.has(".github/workflows/ci.yml") || !hasChecksWorkflow(root),
901
1351
  verificationSkill,
902
- glossary: ["GLOSSARY.md", "docs/GLOSSARY.md"].find((file) => existsSync(join(root, file)))
1352
+ glossary: ["GLOSSARY.md", "docs/GLOSSARY.md"].find((file) => existsSync(join(root, file))),
1353
+ docs: profile === "full" && current.has("package.json") ? planDocs(root, manager) : void 0
903
1354
  };
904
1355
  }
905
1356
  function writeArtifacts(root, artifacts) {
@@ -928,7 +1379,8 @@ function syncRepository(root, options = {}) {
928
1379
  profile
929
1380
  });
930
1381
  const context = repositoryContext(root, current, profile, verify.verificationSkill);
931
- let plan = planSync(current, modes, context);
1382
+ const boundaries = backendBoundaryArtifacts(root);
1383
+ let plan = [...planSync(current, modes, context), ...boundaries];
932
1384
  const errors = plan.filter((artifact) => artifact.kind === "error").map(({ message }) => message);
933
1385
  const entryOnly = checkEntryOnlyConfiguration(root);
934
1386
  errors.push(...entryOnly.errors, ...verify.errors);
@@ -939,8 +1391,11 @@ function syncRepository(root, options = {}) {
939
1391
  const desired = presetConfig(current.get(lint.path), lint, context.tools);
940
1392
  const baseline = measureBaseline(root, desired === current.get(lint.path) ? void 0 : desired);
941
1393
  context.ratchet = !isRetired(baseline);
942
- context.baseline = formatCeilings(baseline);
943
- plan = planSync(current, modes, context);
1394
+ context.baseline = formatCeilings({
1395
+ ...baseline,
1396
+ pack: recordedRelease(void 0)
1397
+ });
1398
+ plan = [...planSync(current, modes, context), ...boundaries];
944
1399
  }
945
1400
  const writes = plan.filter((artifact) => artifact.kind === "write" || artifact.kind === "migrated");
946
1401
  if (!options.check && !errors.length) {