@antelopejs/tooling-configs 0.2.16 → 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 (51) hide show
  1. package/README.md +101 -52
  2. package/dist/bin/api-diff.mjs +430 -107
  3. package/dist/bin/body-check.d.mts +1 -0
  4. package/dist/bin/body-check.mjs +344 -0
  5. package/dist/bin/capture.d.mts +1 -0
  6. package/dist/bin/capture.mjs +559 -0
  7. package/dist/bin/check-size.mjs +3 -3
  8. package/dist/bin/checks.mjs +3 -3
  9. package/dist/bin/comment-proof.mjs +4 -3
  10. package/dist/bin/garden.mjs +6 -6
  11. package/dist/bin/ratchet.mjs +316 -10
  12. package/dist/bin/suppressions.mjs +118 -80
  13. package/dist/bin/sync.mjs +554 -153
  14. package/dist/bin/verify.mjs +240 -127
  15. package/dist/capture/index.d.mts +50 -0
  16. package/dist/capture/index.mjs +2 -0
  17. package/dist/{ceilings-BSw9p4YB.mjs → ceilings-B7KayYIG.mjs} +11 -3
  18. package/dist/{checks-BlWDFYio.mjs → checks-CxkSu2E6.mjs} +1 -1
  19. package/dist/{ci-workflow-DIsoEgMd.mjs → ci-workflow-ChW4He0r.mjs} +84 -3
  20. package/dist/{files-2FikHZ9F.mjs → files-DJ0TeaTU.mjs} +11 -5
  21. package/dist/formal/index.d.mts +40 -0
  22. package/dist/formal/index.mjs +205 -0
  23. package/dist/{json-BqvuCkqr.mjs → json-CG2L7YFl.mjs} +12 -8
  24. package/dist/oxc/anti-slop/index.mjs +869 -21
  25. package/dist/oxc/fmt.mjs +1 -1
  26. package/dist/oxc/guardrails/index.d.mts +1 -1
  27. package/dist/oxc/guardrails/index.mjs +736 -4
  28. package/dist/oxc/lint.d.mts +20 -3
  29. package/dist/oxc/lint.mjs +34 -10
  30. package/dist/oxlint-DIV-lLSS.mjs +98 -0
  31. package/dist/{package-Dtjt_lSa.mjs → package-BRTjkzt5.mjs} +29 -3
  32. package/dist/proof-stamp-DDDC0J6l.mjs +279 -0
  33. package/dist/ratchet-BAcLRYuM.mjs +448 -0
  34. package/dist/{renames-BGO4dWJ8.mjs → renames-L2owF5GD.mjs} +2 -2
  35. package/dist/scenes-DZVXkcxS.mjs +104 -0
  36. package/dist/shared-igPpEDpS.mjs +622 -0
  37. package/dist/{size-BVgNbLO6.mjs → size-DBatLT-F.mjs} +4 -4
  38. package/dist/suppression-base-9L8dlMQK.mjs +120 -0
  39. package/dist/suppression-budget-C0SkPO5R.mjs +535 -0
  40. package/dist/{suppressions-BJAngUxo.mjs → suppressions-DM60NkvL.mjs} +180 -18
  41. package/dist/templates-CypDm-j9.mjs +121 -0
  42. package/dist/typescript-CM0LrVP7.mjs +222 -0
  43. package/dist/verify/index.d.mts +6 -1
  44. package/dist/verify/index.mjs +1 -1
  45. package/package.json +31 -5
  46. package/dist/kinds-Bzyyi9yk.mjs +0 -25
  47. package/dist/ratchet-DRdIYwmv.mjs +0 -80
  48. package/dist/shared-CsXIMK3I.mjs +0 -34
  49. package/dist/staged-ratchet-CjoRfZaM.mjs +0 -236
  50. package/dist/suppression-budget-Yyf5_J5l.mjs +0 -283
  51. package/dist/typescript-C54ONh9m.mjs +0 -433
package/README.md CHANGED
@@ -3,7 +3,7 @@
3
3
  <div align="center">
4
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
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/sjK28QHrA7"><img src="https://img.shields.io/badge/Discord-18181B?logo=discord&style=for-the-badge&color=000000" alt="Discord"></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>
7
7
  </div>
8
8
 
9
9
  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.
@@ -17,25 +17,26 @@ The AntelopeJS guardrail pack: shared lint, format and dead-code presets, the co
17
17
 
18
18
  ## What's in the box
19
19
 
20
- | Export | Import | What it gives |
21
- | ------------------ | ------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------- |
22
- | `./oxc/lint` | `import { antelopePreset } from "@antelopejs/tooling-configs/oxc/lint"` | The oxlint preset |
23
- | `./oxc/fmt` | `import { antelopeFmtPreset } from "@antelopejs/tooling-configs/oxc/fmt"` | The oxfmt preset (house style) |
24
- | `./eslint` | `import { antelopeNuxtConfig } from "@antelopejs/tooling-configs/eslint"` | ESLint for Nuxt layers |
25
- | `./knip` | `import { antelopeKnipConfig } from "@antelopejs/tooling-configs/knip"` | Knip for AntelopeJS modules |
26
- | `./oxc/anti-slop` | Loaded by the oxlint preset as a JS plugin | The vendored [anti-slop](https://github.com/dmmulroy/anti-slop) rules |
27
- | `./oxc/guardrails` | Loaded by the oxlint preset as a JS plugin | The `antelopejs` comment and test-quality rules |
28
- | `./verify` | `import type { VerifyConfig } from "@antelopejs/tooling-configs/verify"` | Types and check helpers for a shared verification skill's `verify.config.ts` |
29
- | bin | `antelopejs-sync` | Writes the guardrail pack into a repository; `--check` reports drift |
30
- | bin | `antelopejs-checks` | Runs every check and prints only the failures |
31
- | bin | `antelopejs-ratchet` | Fails when recorded debt grows; `--update` lowers the record |
32
- | bin | `antelopejs-suppressions` | Fails when suppressions exceed their budget or an added one breaks policy; `--update` lowers the budget |
33
- | bin | `antelopejs-check-size` | Fails on authored files over 20,000 bytes and on blanket disable directives |
34
- | bin | `antelopejs-api-diff <base-ref>` | Compares published declaration bundles against committed HEAD |
35
- | bin | `antelopejs-comment-proof <base-ref>` | Compares comment-free JavaScript emit against committed HEAD |
36
- | bin | `antelopejs-check-interface-ranges` | Fails on interface ranges that break module startup |
37
- | bin | `antelopejs-garden [--json] [--apply-pauses]` | The Gardener's scans of the organization through the GitHub API and npm |
38
- | bin | `antelopejs-verify <command>` | The harness of the shared `verify-interface`, `verify-module` and `verify-template` skills |
20
+ | Export | Import | What it gives |
21
+ | ------------------ | ------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------- |
22
+ | `./oxc/lint` | `import { antelopePreset } from "@antelopejs/tooling-configs/oxc/lint"` | The oxlint preset |
23
+ | `./oxc/fmt` | `import { antelopeFmtPreset } from "@antelopejs/tooling-configs/oxc/fmt"` | The oxfmt preset (house style) |
24
+ | `./eslint` | `import { antelopeNuxtConfig } from "@antelopejs/tooling-configs/eslint"` | ESLint for Nuxt layers |
25
+ | `./knip` | `import { antelopeKnipConfig } from "@antelopejs/tooling-configs/knip"` | Knip for AntelopeJS modules |
26
+ | `./oxc/anti-slop` | Loaded by the oxlint preset as a JS plugin | The vendored [anti-slop](https://github.com/dmmulroy/anti-slop) rules |
27
+ | `./oxc/guardrails` | Loaded by the oxlint preset as a JS plugin | The `antelopejs` comment and test-quality rules |
28
+ | `./verify` | `import type { VerifyConfig } from "@antelopejs/tooling-configs/verify"` | Types and check helpers for a shared verification skill's `verify.config.ts` |
29
+ | bin | `antelopejs-sync` | Writes the guardrail pack into a repository; `--check` reports drift |
30
+ | bin | `antelopejs-checks` | Runs every check and prints only the failures |
31
+ | bin | `antelopejs-ratchet` | Fails when recorded debt grows; `--update` lowers the record and adopts rules a pack release newly enabled |
32
+ | bin | `antelopejs-suppressions` | Fails when suppressions exceed their budget or an added one breaks policy; `--update` lowers the budget |
33
+ | bin | `antelopejs-check-size` | Fails on authored files over 20,000 bytes and on blanket disable directives |
34
+ | bin | `antelopejs-api-diff <base-ref>` | Compares published declaration bundles against committed HEAD |
35
+ | bin | `antelopejs-comment-proof <base-ref>` | Compares comment-free JavaScript emit against committed HEAD |
36
+ | bin | `antelopejs-body-check <body.md \| -> [--head <sha>] [--base <sha>]` | Checks a PR body's proof and findings blocks against HEAD; `--findings` prints the findings block |
37
+ | bin | `antelopejs-check-interface-ranges` | Fails on interface ranges that break module startup |
38
+ | bin | `antelopejs-garden [--json] [--apply-pauses]` | The Gardener's scans of the organization through the GitHub API and npm |
39
+ | bin | `antelopejs-verify <command>` | The harness of the shared `verify-interface`, `verify-module` and `verify-template` skills |
39
40
 
40
41
  ## antelopejs-garden
41
42
 
@@ -45,11 +46,13 @@ The AntelopeJS guardrail pack: shared lint, format and dead-code presets, the co
45
46
  - Without `--json` it prints failures only. The exit code is non-zero only when a check could not run.
46
47
  - `--apply-pauses` sets the repository variable `NEXT_AUTOMERGE` to `shadow` on repositories where it is `on`, when `checks` is red on `next`, the ratchet file is back on a Clean repository, or governance drifted. It never sets `on` and writes nothing else.
47
48
 
48
- `antelopejs-sync` (full profile) writes the weekly mutation caller `.github/workflows/mutation.yml`, and both profiles keep the shared CI caller on the job id `ci`, so the check is reported as `ci / checks`. The `ci` job is read-only (`contents: read`) and passes `renovate-sync: false`; the `contents: write` and `actions: write` grants that let the Renovate sync push its commit and dispatch the caller live on a separate `renovate-sync` job calling `ci-renovate-sync.yml`, which sync adds when it is missing and never re-pins.
49
+ `antelopejs-sync` (full profile) writes the weekly mutation caller `.github/workflows/mutation.yml`, and both profiles keep the shared CI caller on the job id `ci`, so the check is reported as `ci / checks`. The `ci` job is read-only (`contents: read`) and passes `renovate-sync: false`; the `contents: write` and `actions: write` grants that let the Renovate sync push its commit and dispatch the caller live on a separate `renovate-sync` job calling `ci-renovate-sync.yml`, which sync adds when it is missing and never re-pins. Under the full profile it also sets the `docs-files` input of every ci-node caller to the existing `README.md` and `docs` of the root and of each workspace package that is not private, then keeps the caller's other listed paths that still exist. Renaming a caller to `ci` also rewrites `needs:` lists and `needs.<old-id>` reads in expressions, and sync (and `--check`) fails a caller in which a job needs a job that does not exist or reads `needs.<id>` of a job missing from its own `needs:`, since GitHub evaluates that read to null and a gate like `needs.checks.result == 'skipped'` then never fails.
49
50
 
50
51
  ## Shared verification skills
51
52
 
52
- `antelopejs-sync` writes one shared verification skill into a repository: `verify-interface` for an interface, `verify-module` for an implementation module (inferred from `antelopeJs.implements`) and `verify-template` under `--profile template`. Pass `--verify interface|module|template` to choose, or `--verify custom` for a repository that keeps its own `.agents/skills/verify-<repo>/`. Sync writes `SKILL.md` and `package.json` in `.agents/skills/verify-<kind>/` with a `.claude/skills/verify-<kind>` link, and `--check` reports them as drift. It never touches the repository's own layer beside them: `verify.config.ts`, `features/`, `seeded-breaks/` and `seeded-doors/`.
53
+ `antelopejs-sync` writes one shared verification skill into a repository: `verify-interface` for an interface, `verify-module` for an implementation module (inferred from `antelopeJs.implements`) and `verify-template` under `--profile template`. Pass `--verify interface|module|template` to choose, or `--verify custom` for a repository that keeps its own `.agents/skills/verify-<repo>/`. Sync writes `SKILL.md`, `package.json` and `tsconfig.json` in `.agents/skills/verify-<kind>/` with a `.claude/skills/verify-<kind>` link, and `--check` reports them as drift. The `tsconfig.json` extends the root one with ES module resolution and loads the Node types, so type-aware lint sees the real types of the repository's files there, Node APIs included. It never touches the repository's own layer beside them: `verify.config.ts`, `features/`, `seeded-breaks/` and `seeded-doors/`.
54
+
55
+ `antelopejs-sync` also installs the `technical-writing` and `unslop` skills in every repository, under both profiles. Each is `.agents/skills/<name>/SKILL.md` with a `.claude/skills/<name>` link. The text is vendored unchanged from Upd4ting/agent-config `claude/skills/<name>/SKILL.md` at commit 4e0a848, and `--check` reports an edited file as drift. Write documentation with them: `technical-writing` picks the page's mode and sets the sentence rules, and `unslop` lists the patterns to cut.
53
56
 
54
57
  Every deterministic step of a verification is an `antelopejs-verify` command: `map`, `plan`, `new`, `doctor`, `journey`, `formal`, `doors`, `seeded`, `seeded-doors`, `clean`, `verdict` and `publish`. The synced `SKILL.md` documents each one for the agent that verifies.
55
58
 
@@ -99,28 +102,37 @@ export default defineConfig({
99
102
 
100
103
  ### What the preset turns on
101
104
 
102
- | Group | Rules | Default |
103
- | -------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------- |
104
- | oxc | the `correctness` category, with the `eslint`, `typescript`, `node`, `oxc`, `import` and `promise` plugins; `no-unused-vars` (`_` prefix allowed), `eqeqeq` (`== null` allowed), `radix`, `prefer-regex-literals`, `typescript/ban-ts-comment` for `@ts-ignore` only | error |
105
- | Imports | `import/no-cycle`, `import/no-self-import`, `import/no-duplicates` | error |
106
- | Type-aware | `typescript/no-floating-promises` and eight more type-aware rules | error |
107
- | Complexity | `max-params` 5, `max-lines-per-function` 120, `max-lines` 500, `max-depth` 4, `complexity` 20 | error |
108
- | Anti-slop | all 15 vendored rules; `no-runtime-typeof` with `allowInTypeGuards`, so a `typeof` inside a type predicate or assertion function passes | error |
109
- | Guardrails | `antelopejs/no-comments`; in test files `antelopejs/no-fs-read-in-tests`, `antelopejs/no-self-import-in-tests`, `antelopejs/no-constant-value-assertion`, `antelopejs/no-typeof-function-only-test` and `antelopejs/require-assertion` | error |
110
- | Import sorting | `perfectionist/sort-imports`, autofixed by `oxlint --fix` | off |
105
+ | Group | Rules | Default |
106
+ | -------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------- |
107
+ | oxc | the `correctness` category, with the `eslint`, `typescript`, `node`, `oxc`, `import` and `promise` plugins; `no-unused-vars` (`_` prefix allowed), `eqeqeq` (`== null` allowed), `radix`, `prefer-regex-literals`, `typescript/ban-ts-comment` for `@ts-ignore` only | error |
108
+ | Imports | `import/no-cycle`, `import/no-self-import`, `import/no-duplicates` | error |
109
+ | Type-aware | `typescript/no-floating-promises` and thirteen more type-aware rules, including `no-unnecessary-type-parameters`, `no-unsafe-argument`, `no-unsafe-assignment`, `no-unsafe-return` and `use-unknown-in-catch-callback-variable` | error |
110
+ | Complexity | `max-params` 5, `max-lines-per-function` 120, `max-lines` 500, `max-depth` 4, `complexity` 20 | error |
111
+ | Anti-slop | all 15 vendored rules; `no-runtime-typeof` with `allowInTypeGuards`, so a `typeof` (or `.constructor === String`) inside a type predicate or assertion function passes | error |
112
+ | Guardrails | `antelopejs/no-comments`, `antelopejs/no-inherited-key-lookup`, `antelopejs/no-presence-only-type-guard`, and with type-aware lint `antelopejs/require-tsconfig-include`; in test files `antelopejs/no-fs-read-in-tests`, `antelopejs/no-self-import-in-tests`, `antelopejs/no-constant-value-assertion`, `antelopejs/no-typeof-function-only-test` and `antelopejs/require-assertion` | error |
113
+ | Import sorting | `perfectionist/sort-imports`, autofixed by `oxlint --fix` | off |
114
+
115
+ Three anti-slop rules skip a value at its boundary. `no-runtime-typeof` also counts a `.js`/`.mjs` function documented `@returns {x is T}` as a type guard. `no-unsafe-dictionary-type` allows `Record<string, unknown>` as a `value is T` target or inside a type-guard body. `no-unknown-parameters` skips a `this` parameter, a parameter decorated `@JSONBody`, `@JsonBody` or `@Parameter`, the reason of a callback passed directly to `.catch(...)` or as `.then(_, onRejected)`, the parameter of a `(reason: unknown) => void` type declared as `reject` or on a `new Promise` executor, the `unknown` parameters of a function type that annotates a plain callback parameter which the function only calls (and tests for existence), at least once, passing a never-reassigned catch variable in each `unknown` position (a callback that is stored, passed on, never called or called with any other value stays reported), a parameter typed exactly `unknown` of a function whose declared return type is primitive and whose only use of it is to read a symbol-keyed member (`value[BRAND]`, `BRAND in value`) of a `const` bound to `Symbol(...)` or `Symbol.for(...)` in the file, directly, through a `const` alias, or through a function declared in the file that does the same, behind type guards declared in the file, where the member is only read and what is read reaches nothing but the result (it may be tested, compared, negated, read further, passed to `Boolean(...)` or held in a `const` that obeys the same rule; a write, `delete`, update, call of the member, or an argument to any other call refuses), the brand probe, and a parameter typed exactly `unknown` at a parse boundary: the function only passes it to a schema or decoder that is not written in the same file, meaning its root, followed through members, calls, `const` aliases, `import x = Namespace.member` aliases, parameter and destructuring defaults, assignments and type wrappers, is a module import, a global that nothing in the file assigns, or a parameter that nothing in the file defaults or assigns, and not a name that the file may merge or write (a name read inside a namespace block that the block does not bind itself, which another block of the namespace may declare as a member that shadows an import or a global), a function, class, namespace, object literal, `let`, a `this` that is not the class's own (the `this` of an object-literal method or a nested function), a class element of another name, kind or static-ness, or a call handed an object, an array or a `this` that holds a function written here, or a call on a global (`Object.freeze`, `Array.from`, `Promise.resolve`) handed any function written here (`parse`, `safeParse`, `parseAsync`, `safeParseAsync`, `decode`, a `parseX` or `decodeX` helper, `assertValidation`), never mentions `arguments` or `eval`, and returns that call's result under a declared return type other than `unknown` or `any`.
116
+
117
+ `no-runtime-typeof` does not report a `typeof` that only fills in the text of a message, such as ``throw new Error(`received ${typeof value}`)`` or ``assert(ok, `received ${typeof value}`)``: the template holds other text, and a `throw`, a bare `assert(...)` or a `log(...)` method that stands as a statement takes it. The `assert`, the object `log` is read from, and the class of a thrown `new` must come from outside the file: a module import, a global that nothing in the file assigns, or a parameter that nothing in the file defaults or assigns, reached through members and type wrappers only. A name read inside a namespace block counts only when the block binds it, as a parameter, because another block of the namespace may declare a member of that name that shadows an import or a global. A function, class, `const`, `let`, `this`, call result or namespace written in the file can compare or store the message, so a `typeof` handed to it stays reported. The same template compared, bound to a name, returned, or handed to any other call (`assert.equal`, `Set#add`, `emit`, a dispatcher) stays reported, because a caller can test it or use it as a key.
111
118
 
112
119
  No rule warns. oxlint reports `correctness` as warnings by default, and warnings never fail the command, so the preset raises it to error. A repository with existing findings records them in `guardrails.ratchet.json` instead of lowering a severity (see [Guardrail pack](#guardrail-pack)).
113
120
 
114
121
  The guardrail rules:
115
122
 
116
- | Rule | Fails on |
117
- | ----------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
118
- | `antelopejs/no-comments` | `//` and `/* */` comments. Allowed: TSDoc `/** */`, `SAFETY: <reason>` (one block, or a run of `//` lines), `/*!` license headers, `@ts-expect-error <reason>`, oxlint/eslint directives that name their rules, `/// <reference />`, `#__PURE__`/`@__PURE__`, `@vite-ignore` and webpack magic comments, `prettier-ignore`/`oxfmt-ignore` |
119
- | `antelopejs/no-fs-read-in-tests` | `readFileSync` or `readdirSync` from `fs` in a test file. Files under `fixtures/`, `helpers/` and `locales/` may read |
120
- | `antelopejs/no-self-import-in-tests` | a test file that imports its own package name (`@antelopejs/<self>`, a subpath, `require`, dynamic `import()` or a re-export; `import type` is fine) unless that resolves to local code: the `exports` map publishes the subpath and `node_modules/<name>` is a link back to the package (a workspace self-link such as `link:.`). Otherwise the import resolves to the installed published copy and the test never runs local code. Import the module by relative path instead |
121
- | `antelopejs/require-assertion` | a test with no assertion. Counts: calls named `expect*` or `assert*`, `sinon.assert.*`, supertest `.expect(...)`, and should-style `x.should…` or `should(x)` |
122
- | `antelopejs/no-constant-value-assertion` | `expect(X).toBe(literal)` where the root of `X` is an UPPER_SNAKE constant (`MAX_ITEMS`, `NAMES.if`, not `process.env.NODE_ENV`); also `.toEqual`, `.to.equal`, `.to.eq`, `.eql` and synonyms |
123
- | `antelopejs/no-typeof-function-only-test` | a test whose only assertions are `toBeTypeOf("function")`, `to.be.a("function")` or equivalents |
123
+ | Rule | Fails on |
124
+ | ----------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
125
+ | `antelopejs/no-comments` | `//` and `/* */` comments. Allowed: TSDoc `/** */`, `SAFETY: <reason>` (one block, or a run of `//` lines), `/*!` license headers, `@ts-expect-error <reason>`, oxlint/eslint directives that name their rules, `/// <reference />`, `#__PURE__`/`@__PURE__`, `@vite-ignore` and webpack magic comments, `prettier-ignore`/`oxfmt-ignore` |
126
+ | `antelopejs/no-inherited-key-lookup` | `table[key]` (or `table[key] += ...`) with a computed key, or `key in table`, where `table` is declared in the same file as a string-keyed dictionary (`Record<string, V>`, `Record<PropertyKey, V>`, a string index signature, `Readonly`/`Partial` of one, a union with `undefined` or `null`, a local alias or `typeof` another table, `satisfies` or `as Record<string, V>`, a class field read as `this.field[key]`), or an untyped object literal read with an asserted key (`table[key as keyof typeof table]`). Inherited keys such as `constructor` answer `Object.prototype` members. Not reported: literal keys, `typeof x` keys, same-file `const` keys (`KEY`, `LABELS.name` of a literal-valued object), keys iterated from an array of string literals or from `Object.keys(table)`, `Object.entries(table)` or `for...in` of the same table (through `filter`, `sort` and similar), writes and `delete`, a read in a function that calls `Object.hasOwn(table, key)` or `hasOwnProperty`, null-prototype tables (`Object.create(null)`, `{ __proto__: null }`). Imported constants and keys iterated from another table are reported. Use a `Map` instead |
127
+ | `antelopejs/no-presence-only-type-guard` | in a type predicate or assertion function narrowing `x`: `x in table` (also true for inherited keys; use `Object.hasOwn(table, x)` or a `Map`/`Set`); `"k" in x`, `Object.hasOwn(x, "k")`, `hasOwnProperty.call(x, "k")` or `Reflect.has(x, "k")` with no read of `x.k` (presence only; check the value; a read through a cast such as `(x as T).k` or `(<T>x).k` counts); a member of a type declared in the same file that the guard never reads. Members typed `unknown` and parameters typed as a union of object types (`pet: Cat \| Dog`, a discriminating `in`) are not reported, and a call to another local guard with `x` counts as checking that guard's members |
128
+ | `antelopejs/require-tsconfig-include` | a file type-aware lint reads that no `tsconfig.json` or `jsconfig.json` lists: not the nearest one, not a config it references, not one above. `oxlint-tsgolint` reads such a file in its inferred program, without the repository's compiler options or `types`, so Node and test-runner globals are error types: `typescript/no-unsafe-*` reports there are false, and findings that need those types go missing. List the file in a tsconfig that names its `types`: one beside it that extends the root tsconfig, or, for a file at the root, a composite tsconfig (`emitDeclarationOnly`, `outDir` under `node_modules/.cache`) that the root tsconfig references, which `tsc -p .` leaves unbuilt. The root `oxlint.config.ts`, `oxfmt.config.ts` and `knip.config.ts` that `antelopejs-sync` writes are exempt. On only with type-aware lint |
129
+ | `antelopejs/no-fs-read-in-tests` | `readFileSync` or `readdirSync` from `fs` in a test file. Files under `fixtures/`, `helpers/` and `locales/` may read |
130
+ | `antelopejs/no-self-import-in-tests` | a test file that imports its own package name (`@antelopejs/<self>`, a subpath, `require`, dynamic `import()` or a re-export; `import type` is fine) unless that resolves to local code: the `exports` map publishes the subpath and `node_modules/<name>` is a link back to the package (a workspace self-link such as `link:.`). Otherwise the import resolves to the installed published copy and the test never runs local code. Import the module by relative path instead |
131
+ | `antelopejs/require-assertion` | a test with no assertion. Counts: calls named `expect*` or `assert*`, `sinon.assert.*`, supertest `.expect(...)`, and should-style `x.should…` or `should(x)` |
132
+ | `antelopejs/no-constant-value-assertion` | `expect(X).toBe(literal)` where the root of `X` is an UPPER_SNAKE constant (`MAX_ITEMS`, `NAMES.if`, not `process.env.NODE_ENV`); also `.toEqual`, `.to.equal`, `.to.eq`, `.eql` and synonyms |
133
+ | `antelopejs/no-typeof-function-only-test` | a test whose only assertions are `toBeTypeOf("function")`, `to.be.a("function")` or equivalents |
134
+
135
+ `antelopejs/no-presence-only-type-guard` passes `x in table` when `x` is typed `` `prefix${string}` `` and no `Object.prototype` member starts with that prefix, because such a key cannot name an inherited member. The prefix is read as TypeScript reads it, so `\x63onstructor${string}` is `constructor${string}` and stays reported.
124
136
 
125
137
  Test files are `*.test.*`, `*.spec.*`, and files under `test/`, `tests/` and `__tests__/`, whatever the framework. The preset keeps four framework-neutral Jest-plugin rules: `no-disabled-tests`, `no-focused-tests`, `valid-describe-callback` and `valid-title`.
126
138
 
@@ -128,7 +140,7 @@ Import sorting is off because it moves value imports across side-effect imports,
128
140
 
129
141
  ### Options
130
142
 
131
- ```ts
143
+ ```ts fragment
132
144
  antelopePreset({
133
145
  antiSlop: false, // true (default)
134
146
  guardrails: false, // true (default)
@@ -141,7 +153,7 @@ antelopePreset({
141
153
 
142
154
  ### Add ignore patterns
143
155
 
144
- oxlint does not merge `ignorePatterns` across `extends`: a root config that declares its own replaces the preset's. Spread the shared ones:
156
+ oxlint reads `ignorePatterns` only from the root config, never from `extends`, so the synced `oxlint.config.ts` sets `ignorePatterns: ANTELOPE_IGNORE_PATTERNS`, and sync replaces the earlier template that did not. `ANTELOPE_IGNORE_PATTERNS` holds generated output and what sync writes under the agent directories: the synced files of each shared skill and its `.claude/skills` link, which shows the repository's own files a second time. The repository's own files under `.agents/` and `.claude/` are linted. Spread the shared patterns when adding your own:
145
157
 
146
158
  ```ts
147
159
  // oxlint.config.ts
@@ -175,11 +187,13 @@ pnpm install
175
187
  | `.nvmrc` | `24` |
176
188
  | `.agents/setup` | Orb setup: switches to the `.nvmrc` Node, activates `packageManager` through corepack, installs with the frozen lockfile |
177
189
  | `AGENTS.md` | Writes the managed block between `<!-- antelopejs-guardrails:start -->` and `:end -->`; text outside the markers stays |
190
+ | `README.md` of each `@antelopejs` package | Writes the generated compatibility block (see [Generated compatibility block](./docs/documentation-checks.md#generated-compatibility-block)); prose outside its markers stays |
178
191
  | `CLAUDE.md` | `@AGENTS.md` |
179
192
  | `guardrails.ratchet.json` | Records non-empty debt on first adoption, before `sync:check` exists |
180
- | `guardrails.suppressions.json` | Records the current suppression counts when the file is missing; restores the committed file instead when HEAD has one; never rewrites an existing file |
193
+ | `guardrails.suppressions.json` | Records the current suppression counts when the file is missing; restores the committed file instead when HEAD has one; otherwise only adds `config` and `agentFiles` at today's counts when the file predates them |
194
+ | `<layer>/build/backend-boundary.ts` | Where a DMS frontend layer tracks one, restores the pack's backend boundary plugin for the package that holds the layer. A formatter's rewrite is not drift; any other edit is |
181
195
 
182
- `--profile template` writes only the three preset configs and a user-facing `AGENTS.md` block, for template repositories. `antelopejs-sync --check` writes nothing and exits 1 on any drift; `pnpm run checks` runs it.
196
+ `--profile template` writes only the three preset configs, a user-facing `AGENTS.md` block and the `suppressions` package scripts (plus `ratchet` once `guardrails.ratchet.json` exists) that `antelopejs-checks` requires, for template repositories. `antelopejs-sync --check` writes nothing and exits 1 on any drift; `pnpm run checks` runs it.
183
197
 
184
198
  `pnpm run checks` runs `typecheck`, `lint`, `format:check`, `knip`, `test`, `size`, `suppressions` and `sync:check`, plus `ratchet` when `guardrails.ratchet.json` exists. It prints only the output of the steps that failed. Sync adds the ratchet scripts and pre-commit hook only while that file exists.
185
199
 
@@ -189,6 +203,7 @@ pnpm install
189
203
 
190
204
  ```json
191
205
  {
206
+ "pack": "0.2.17",
192
207
  "rules": { "antelopejs/no-comments": 22, "eslint/max-depth": 1 },
193
208
  "oversizeFiles": { "src/legacy.ts": 31250 }
194
209
  }
@@ -196,8 +211,10 @@ pnpm install
196
211
 
197
212
  - A rule listed under `rules` is off for `oxlint`, so editors, hooks and `lint` stay green. `antelopejs-ratchet` counts it with every rule on, and fails when a count rises. It prints the findings in the files the change touched.
198
213
  - A file listed under `oversizeFiles` may exceed 20,000 bytes and `max-lines`, up to its recorded size. Any other file over either limit fails. When git sees a listed file renamed (`git mv`, or a staged delete and add), the allowance moves to the new path and never exceeds the old one; a copy or a new file inherits nothing. `antelopejs-ratchet --base <ref>` detects renames against that revision instead of `HEAD`, for a rename that was committed before the file was updated.
199
- - The pre-commit hook runs `antelopejs-ratchet --staged`: for each rule under `rules` it compares the findings in the staged files with those files at HEAD (rename sources and deleted files included, linted under the staged configuration) and fails a rule whose net count rises. Code moved between staged files, or a legacy line that is reformatted or edited, nets out; a new finding does not, even next to a moved block.
200
- - `antelopejs-ratchet --update` lowers each number to the current count and removes what reached zero. It never raises a number or adds an entry. Commit the lowered file.
214
+ - The pre-commit hook runs `antelopejs-ratchet --staged`: for each rule under `rules` it counts the findings in the staged files and in those files at HEAD and at the merge-base of HEAD with the pull request base (`origin/$GITHUB_BASE_REF`, else `origin/HEAD`), rename sources and deleted files included, linted under the staged configuration. A merge-base finding counts only for a staged finding of the same rule on the same line, unchanged since the merge-base, and only while the files the branch changed hold no more findings of that rule than at the merge-base. It fails a rule whose staged count is above both, and lists the findings on lines that differ from HEAD and from the merge-base. Code moved between staged files, a legacy line that is reformatted or edited, a line restored byte for byte to its base form, a `SAFETY:` comment the branch added and the commit removes, or an edit of a file a legacy finding moved into earlier on the branch, nets out; a new finding does not, even next to a moved block. Locally the base is always `origin/HEAD`, so a branch stacked on another branch is compared with HEAD and the default branch, not with its parent branch. Without `origin/HEAD` (`git remote set-head origin --auto` sets it) or a merge-base, it compares with HEAD only and says so when it fails.
215
+ - With `APPROVED_RAISES="<rule>=<max> ..."` in the environment, `antelopejs-ratchet --staged` accepts the findings of exactly those rules while this commit raises the rule's ceiling in the staged `guardrails.ratchet.json` above HEAD's, to exactly `<max>`, and the commit holds at most `<max>` findings of it, counted from a checkout of the index, so ignore files and a file whose working copy differs cannot hide it; the commit is refused while any tracked file is `skip-worktree` (a sparse checkout) or `assume-unchanged`, because those files can differ from the index unseen. The variable is split on space and tab only, so a non-breaking space or a newline makes it malformed. The count takes the higher of a checkout of the index and the working tree for each rule, so generated types that only the working tree has are not lost, and an untracked file with a finding still counts. When the commit also stages a code file, a raised ceiling for a rule the variable does not list is refused too. A commit that stages only `guardrails.ratchet.json` skips the hook through its glob, as it does without the variable, and the CI gate refuses that raise. `<max>` is what `antelopejs-ratchet` measures, the same as the CI gate: files it does not measure (a force-added gitignored file, a file under a gitignored path, a nested lint config, a non-UTF-8 file name) do not count, and a stale or partial build can change a type-aware count. The `oxlint` preset ignores the variable: it already turns off the rules in the ceiling file, and the approved commit writes that ceiling. Each accepted raise is printed as `APPROVED RAISE ACCEPTED`. A rule the variable does not list, a ceiling that is not raised to `<max>`, a count above `<max>`, tracked files with unstaged changes and a malformed variable (a bare rule, a non-numeric max, a rule listed twice) are refused, and with the variable unset nothing changes. The variable is the operator's approval: it does not make CI accept the raise.
216
+ - `antelopejs-ratchet --update` lowers each number to the current count and removes what reached zero. It never raises a number. The only entries it adds are rules a pack release enabled after the release recorded under `pack`: `PACK_NEW_RULES` in `src/guardrails/adoption.ts` lists each such rule with the release that enabled it. After a pack upgrade, the update records today's count of each one that has findings, then moves `pack` forward, so a rule fixed to zero and later broken again is never adopted twice. Without `pack`, the repository's adopted release is the pack its lockfile installs at the pull request base (pnpm or npm), and an unknown one predates every listed rule. A clean repository with findings for such a rule gets a ratchet file holding only those rules; run `antelopejs-sync` afterwards for the ratchet scripts and hook. Commit the file. The same update records the size of each oversize file under the agent directories (`.agents/`, `.claude/`, `.amp/` and the others) that has no allowance, once, in a repository whose adopted release predates 0.2.18, the release that began counting the repository's own files there; `antelopejs-ratchet --base` accepts those allowances for files that exist at the base, at no more than their size there, and no other.
217
+ - Against the pull request base (`GITHUB_BASE_REF` in CI, else `origin/HEAD`, or `--base <ref>`), `antelopejs-ratchet` fails an entry added or raised by hand: a rule the pack did not newly enable, a pack-new rule above its count or above its count in the base tree, an oversize allowance for a file that is not a rename of one, and a lowered or dropped `pack`. A first adoption (no ratchet file and no suppression budget at the base) passes.
201
218
 
202
219
  When every rule count is zero and `oversizeFiles` is empty, the ratchet is retired. `antelopejs-ratchet --update` deletes the file and asks you to run `antelopejs-sync`. Sync then removes `ratchet`, `ratchet:update`, the ratchet hook and the Debt instructions. Commit those changes together. An empty baseline on first adoption creates no file. Later syncs never recreate it because the `sync:check` script marks adoption.
203
220
 
@@ -212,11 +229,14 @@ When every rule count is zero and `oversizeFiles` is empty, the ratchet is retir
212
229
  "rules": { "anti-slop/no-chained-type-assertions": 19, "*": 0 },
213
230
  "tsExpectError": 8,
214
231
  "tsIgnore": 0,
215
- "safety": 2
232
+ "safety": 2,
233
+ "config": { "typescript/unbound-method for src/test/**": 1 }
216
234
  }
217
235
  ```
218
236
 
219
237
  - `rules` holds lint directives (`oxlint-disable`, `eslint-disable`, their `-line` and `-next-line` forms, in line or block comments, after code too) per rule they name; a directive naming several rules counts once per rule, and one naming none counts under `*`. A rule missing from `rules` has ceiling 0. The other fields count `@ts-expect-error`, `@ts-ignore` and `SAFETY:` comments. The counter is the one behind the proof tables: it reads comments from the parser, so strings and template literals are never counted, and it skips generated output as the size guard does.
238
+ - `config` holds the rules a lint config switches off, to `allow` or to a warning, keyed `<rule> for <glob>`: in `oxlint.config.*`, `.oxlintrc.json`, `.oxlintrc.jsonc` and `eslint.config.*` at any depth, every `rules` and `categories` map (a category as `category:<name>`) and an ESLint composer's `overrideRules` argument, one key per glob of the block's `files` (`*` when it has none). A nested config's globs are anchored at its directory and its blocks without `files` are `<dir>/**`, so a rule-off moved between config files is a new key. Rule maps, severities and globs held in same-file variables or spread from them count where they are used; the pack's presets are not in the file, so they never count. A glob is a key of its own, so adding, widening or renaming a glob, deleting `files`, or moving an override's rules to the top level creates a key at ceiling 0 and fails. Narrowing or splitting a scope is burn-down: a key may use the room a same-rule key whose glob contains its glob gives up (`*`, `**` and `**/*` contain every glob; a single-segment `*` never contains `**`; other glob syntax counts only when equal), in the full, staged and base checks, and `--update` moves that ceiling to the narrower key. A scope split into several narrower globs gives each the old ceiling, so the `config` total can rise while the files it covers do not; read totals per key, not as a measure of scope. `.` and `..` segments count only when equal. A failure names the fix: delete the entry and fix the code its rule reports, or put the exception on the line that needs it as a directive with a reason. A config entry switching off a rule no directive may name fails as an added directive does. Sync adds `config` at today's counts to a budget that predates it; until then config rule-offs are not capped.
239
+ - `agentFiles` is `true` once the budget counts the repository's own files under the agent directories (`.agents/`, `.claude/`, `.amp/` and the others), skipping only what `antelopejs-sync` writes there, which is what lint skips. A budget without it counts none of them, so upgrading fails nothing: `antelopejs-sync` adds each key's count in those files to its ceiling and sets the field. `antelopejs-suppressions --base` allows that one rise on a base without the field, by no more than the count in those files at the base per key (a directive the same branch adds there is not adoptable), and fails a budget that drops the field once the base has it.
220
240
  - `antelopejs-suppressions` fails when a count is above its ceiling, printing each `file:line` in the files the change touched and the fix: fix the code, or remove another suppression of the same kind; a rule that keeps needing suppressions should be changed in the preset. It prints nothing on success.
221
241
  - `antelopejs-suppressions --update` lowers each ceiling to the current count and keeps rules at zero. No command raises a ceiling.
222
242
  - `SAFETY:` comments and directives disabling `anti-slop/require-safety-comment-for-type-assertion` share their room: a `SAFETY:` comment may use what those directives leave below their ceiling, in the full, base and staged checks, and `--update` moves that room to `safety`. Replacing such a directive with a `SAFETY:` comment needs no raise; their sum never rises.
@@ -224,10 +244,11 @@ When every rule count is zero and `oversizeFiles` is empty, the ratchet is retir
224
244
  - The pre-commit hook runs `antelopejs-suppressions --staged`: it compares the suppressions in the staged files with those files at HEAD, following renames and counting deleted files, and fails a kind that rises by more than the staged budget raises its ceiling. A suppression moved between staged files nets out.
225
245
  - `@ts-ignore` is also a lint error (`typescript/ban-ts-comment`); `@ts-expect-error` fails once its error is gone.
226
246
  - Both modes also judge what the change adds, whatever the budget allows: the full check against the same base (HEAD when there is none), the staged check against HEAD. A suppression counts as added when its kind, rule and reason occur more often than on the base, so one moved to another file with its reason is not added, and one whose reason a comment pass rewrote or stripped is. An added directive fails when it names a rule no directive may name (`anti-slop/require-safety-comment-for-type-assertion`, `antelopejs/no-comments`, the five `antelopejs` test rules, `typescript/ban-ts-comment`); the failure names what to do instead. An added directive naming its rules, `@ts-expect-error` or `SAFETY:` comment fails when its reason has fewer than three words, or only words like "safe", "intentional", "legacy" and the rule's own name. A block `oxlint-disable` or `eslint-disable` that no `-enable` closes before the end of its file fails when the change adds it. Suppressions already on the base stay under the budget until a burn-down removes them.
247
+ - Both modes also hold each lint directive in a file the change touches to two rules, whether the directive was added or already on the base. It must suppress something: one extra `oxlint --report-unused-disable-directives` run over the touched files that contain a directive, under the repository's own lint configuration with every ratchet rule enabled, so a directive for a rule the ratchet turns off is live while the rule still reports there, and a directive for a rule the preset does not run is dead. A dead directive fails with its `file:line`, naming the rule to drop when the directive names several, or telling you to delete it. It must also give a reason: a directive naming rules with no ` -- <reason>` fails whenever its file is touched, though the added-suppression policy above only judges the reason of an added one. Touched files are the staged files in the pre-commit hook, and in the full check the working tree against the merge-base with the pull request base (the base itself when there is no merge-base, as in a shallow checkout), untracked files included, or against HEAD without a base. A file the change does not touch is not read, so upgrading the pack fails no existing file; its dead and reasonless directives surface when a change next touches the file. `eslint-` directives in a directory with an ESLint config are left to ESLint, and `.vue` files are not read by oxlint. Deleting a dead directive lowers the budget: run `suppressions:update`.
227
248
 
228
249
  ### Size
229
250
 
230
- `antelopejs-check-size` fails on an authored file over 20,000 bytes, tests included. Generated code (`dist`, `coverage`, `.nuxt`, `.output`, and `build` or `output` at the repository root or a package root, never under `src/` or `test/`), fixtures, lockfiles, `CHANGELOG.md`, Markdown and binary assets are excluded. JSON is data, never code: every `*.json`, `*.jsonc` and `*.json5` file is excluded, wherever it lives. Lint and format still cover it. Files over the limit with a NUL byte in their first 8,000 bytes are binary even without a known extension. Staged checks inspect the index blob. Excluded files are also removed from recorded size allowances on ratchet update.
251
+ `antelopejs-check-size` fails on an authored file over 20,000 bytes, tests included. The repository's own files under the agent directories count; the files `antelopejs-sync` writes there (the `SYNCED_AGENT_PATTERNS` that lint skips) do not. Generated code (`dist`, `coverage`, `.nuxt`, `.output`, and `build` or `output` at the repository root or a package root, never under `src/` or `test/`), fixtures, lockfiles, `CHANGELOG.md`, Markdown and binary assets are excluded. JSON is data, never code: every `*.json`, `*.jsonc` and `*.json5` file is excluded, wherever it lives. Lint and format still cover it. Files over the limit with a NUL byte in their first 8,000 bytes are binary even without a known extension. Staged checks inspect the index blob. Excluded files are also removed from recorded size allowances on ratchet update.
231
252
 
232
253
  Pass paths to check only those files, as the pre-commit hook does. The command also fails on an `oxlint-disable` or `eslint-disable` directive (line, next-line or file form) that names no rule: oxlint applies such a directive before any rule runs, so `no-comments` cannot report it. It reads real comments only, with the same counter as the proof tables, so directive text inside a string is not reported.
233
254
 
@@ -245,7 +266,9 @@ Pass `--allow-added <glob>` (repeatable) to `antelopejs-api-diff` when a refacto
245
266
  pnpm exec antelopejs-api-diff origin/main --allow-added '**/internal/**'
246
267
  ```
247
268
 
248
- Both commands end with a table of suppressions in authored code files at the base and at HEAD, for PR bodies to copy: lint directives per rule they name (`*` for a directive naming none), `@ts-expect-error`, `@ts-ignore` and `SAFETY:` comments. The parser finds every comment, after code on the same line too, and skips strings, template literals and JSX text; `.vue` files contribute their script blocks and template comments. Generated output is left out as the size guard leaves it out.
269
+ A DMS frontend module publishes more than its package entries: every export of a file under a directory its `dms.frontend.build.ts` passes to `registerAutoImports` is auto-imported into every frontend module, `@internal` or not, and the package itself is usually private. For each tracked `dms.frontend.build.ts`, the proof reads the declared directories (string literals only; anything else is an execution error naming the form to write), drops `app/build/` and directories outside the module as `@antelopejs/dms-frontend` does, and lists one `<name> (value|type): <signature>` line per auto-imported name under `Auto-imports:`. Names are read statically with the module's TypeScript, which resolves `export *` and the `#<layer>/*` aliases; no Vite build runs. Each scanned module is typed with the imports unimport would inject for the names it uses without importing them: dms-frontend's `templates/vue/frontend-module.ts` exports, `vue`'s exports and the module's own auto-imports. A composable returning `ref<T>()` or `useDmsState<T>()` therefore prints `T`, not `any`. Types re-exported from a `.vue` file, `@nuxt/ui` auto-imports and another module's auto-imports are not modelled and print as `any` on both sides. Values print their type, types their structure, both in the canonical member and union order of the declaration half, so moving an export between scanned files or changing an unexported helper passes. A removed, added or changed line fails, and `--allow-added` never applies to it: move a helper that must stay private under `app/build/`. Repositories without a `dms.frontend.build.ts` print no `Auto-imports:` line.
270
+
271
+ Both commands end with a table of suppressions in authored code files at the base and at HEAD, for PR bodies to copy: lint directives per rule they name (`*` for a directive naming none), `@ts-expect-error`, `@ts-ignore` and `SAFETY:` comments. The parser finds every comment, after code on the same line too, and skips strings, template literals and JSX text; `.vue` files contribute their script blocks and template comments. Generated output and the agent files `antelopejs-sync` writes are left out as the size guard leaves them out.
249
272
 
250
273
  Both commands compare **committed HEAD**, not staged or working-tree edits. They check out the base and HEAD in temporary detached worktrees, reuse the current checkout's root and package `node_modules`, and remove the worktrees afterwards. Install the consumer's dependencies before running them.
251
274
 
@@ -254,6 +277,28 @@ pnpm exec antelopejs-api-diff origin/main
254
277
  pnpm exec antelopejs-comment-proof origin/main
255
278
  ```
256
279
 
280
+ ### PR body check
281
+
282
+ Both proof commands end their output with a `<!-- antelopejs-proof ... -->` line that stamps the base, the committed head, the command, the number of lines printed and a digest of them. Paste the whole output down to that line, which renders invisibly; indenting it, wrapping it in a code fence or re-padding the tables keeps it valid. The check reads the stamped number of non-blank lines above the stamp as the copy.
283
+
284
+ `antelopejs-body-check --findings` prints every lint finding of the working tree as a block between `<!-- antelopejs-findings begin -->` and `<!-- antelopejs-findings end -->`, one ``- `path:line` `rule`: <why>`` line per finding under a `` `rule` (count): `` line. Paste it under the findings-left heading, replace each `<why>` with the reason the finding stays, and delete the rules the pull request does not report on. Lines may be regrouped under prose bullets.
285
+
286
+ `antelopejs-body-check <body.md>` (`-` reads standard input) checks the body against the repository at HEAD and prints one line per problem:
287
+
288
+ - a proof block whose lines no longer match its digest, whose head is not in the branch, or, for api-diff, whose head tree is not HEAD's; a suppression table that no longer matches the counts at HEAD against the stamped base. A comment-proof block may be stamped at an earlier commit of the branch, so a comment-only commit can be proven under a later code commit;
289
+ - a suppression table or a proof summary line (`API:`, `Runtime API:`, `Comment proof:`) outside a stamped block;
290
+ - in a findings block: a line that is not a live diagnostic of that rule at that line, a listed rule with a live finding the block leaves out, a finding with no reason, a `path:line` written outside the item form, and a count such as ``(9 `no-unknown-parameters`)`` that differs from the items of that rule under it;
291
+ - a code file named (`path.ts`, with or without `:line`, or a range) in a findings-left section outside a findings block. A section opens at a heading, or at a plain or bold title line, that says what is left, kept or remaining under the ratchet or in findings (`## Findings left under the ratchet`, `Findings left under the ratchet:`, `**Left under the ratchet**`, `## Kept under the ratchet`, `## Not fixed`), and ends at the next heading of its level or above (the next heading of any level for a plain or bold line);
292
+ - with `--base <sha>`, an api-diff block compared against a revision whose merge-base with HEAD is not the pull request base's.
293
+
294
+ Counts in prose are not checked. Run it on a checkout of the pull request head, with history back to the stamped base:
295
+
296
+ ```bash
297
+ gh pr view <number> --json body --jq .body | pnpm exec antelopejs-body-check -
298
+ ```
299
+
300
+ In CI, run it in a `pull_request` job (types `opened`, `edited`, `synchronize`) that checks out `github.event.pull_request.head.sha` with `fetch-depth: 0`, installs dependencies, and passes the body through the environment rather than inline in the script: `printf '%s' "$PR_BODY" | pnpm exec antelopejs-body-check - --head "$HEAD_SHA"`. `--head` fails when the checkout is not that commit. Add `--base "$BASE_SHA"` (`github.event.pull_request.base.sha`) so an api-diff block cannot be taken against HEAD itself.
301
+
257
302
  ## oxfmt
258
303
 
259
304
  ```ts
@@ -277,7 +322,7 @@ The house style sets every field, so `.editorconfig` files cannot override it: `
277
322
 
278
323
  The preset leaves import order to the linter and ignores `CHANGELOG.md`, which changelogen writes unformatted on every release. Other options of oxfmt pass through. Two are specific:
279
324
 
280
- ```ts
325
+ ```ts fragment
281
326
  // oxfmt.config.ts
282
327
  export default antelopeFmtPreset({
283
328
  ignorePatterns: ["frontend-vue/**"], // added to the shared ignores, not replacing them
@@ -347,10 +392,14 @@ An implementer must never be handed a breaking minor it does not implement. `wor
347
392
  ## Documentation guardrail
348
393
 
349
394
  The [documentation action](./docs/documentation-checks.md) checks local Markdown
350
- links and explicitly labeled compatibility tables. Consumers can also opt in
351
- complete TypeScript examples and reference-page export coverage. Pin
395
+ links, explicitly labeled compatibility tables, and reference-page export
396
+ coverage, and typechecks every TypeScript fence against the repository's own
397
+ source; a fence opts out only with a `fragment` marker. Versions of
398
+ `@antelopejs/*` packages belong only in the block `antelopejs-sync` generates:
399
+ the action fails on version ranges and "requires … or later" claims in prose and
400
+ checks the block against the package.json beside it. Pin
352
401
  `AntelopeJS/tooling-configs/actions/docs` to a full commit SHA; no npm release is
353
- required. The guide includes CI and local commands, annotation syntax, and the
402
+ required. The guide includes CI and local commands, marker syntax, and the
354
403
  checks that remain the author's responsibility.
355
404
 
356
405
  ## Contributing