@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/README.md CHANGED
@@ -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,11 @@ 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, so type-aware lint sees the real types of the repository's files there. It never touches the repository's own layer beside them: `verify.config.ts`, `features/`, `seeded-breaks/` and `seeded-doors/`.
53
54
 
54
55
  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
56
 
@@ -99,28 +100,32 @@ export default defineConfig({
99
100
 
100
101
  ### What the preset turns on
101
102
 
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 |
103
+ | Group | Rules | Default |
104
+ | -------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------- |
105
+ | 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 |
106
+ | Imports | `import/no-cycle`, `import/no-self-import`, `import/no-duplicates` | error |
107
+ | 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 |
108
+ | Complexity | `max-params` 5, `max-lines-per-function` 120, `max-lines` 500, `max-depth` 4, `complexity` 20 | error |
109
+ | 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 |
110
+ | Guardrails | `antelopejs/no-comments`, `antelopejs/no-inherited-key-lookup`, `antelopejs/no-presence-only-type-guard`; 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 |
111
+ | Import sorting | `perfectionist/sort-imports`, autofixed by `oxlint --fix` | off |
112
+
113
+ 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)`, and the parameter of a `(reason: unknown) => void` type declared as `reject` or on a `new Promise` executor.
111
114
 
112
115
  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
116
 
114
117
  The guardrail rules:
115
118
 
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 |
119
+ | Rule | Fails on |
120
+ | ----------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
121
+ | `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` |
122
+ | `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 |
123
+ | `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 |
124
+ | `antelopejs/no-fs-read-in-tests` | `readFileSync` or `readdirSync` from `fs` in a test file. Files under `fixtures/`, `helpers/` and `locales/` may read |
125
+ | `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 |
126
+ | `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)` |
127
+ | `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 |
128
+ | `antelopejs/no-typeof-function-only-test` | a test whose only assertions are `toBeTypeOf("function")`, `to.be.a("function")` or equivalents |
124
129
 
125
130
  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
131
 
@@ -128,7 +133,7 @@ Import sorting is off because it moves value imports across side-effect imports,
128
133
 
129
134
  ### Options
130
135
 
131
- ```ts
136
+ ```ts fragment
132
137
  antelopePreset({
133
138
  antiSlop: false, // true (default)
134
139
  guardrails: false, // true (default)
@@ -141,7 +146,7 @@ antelopePreset({
141
146
 
142
147
  ### Add ignore patterns
143
148
 
144
- oxlint does not merge `ignorePatterns` across `extends`: a root config that declares its own replaces the preset's. Spread the shared ones:
149
+ 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
150
 
146
151
  ```ts
147
152
  // oxlint.config.ts
@@ -175,9 +180,11 @@ pnpm install
175
180
  | `.nvmrc` | `24` |
176
181
  | `.agents/setup` | Orb setup: switches to the `.nvmrc` Node, activates `packageManager` through corepack, installs with the frozen lockfile |
177
182
  | `AGENTS.md` | Writes the managed block between `<!-- antelopejs-guardrails:start -->` and `:end -->`; text outside the markers stays |
183
+ | `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
184
  | `CLAUDE.md` | `@AGENTS.md` |
179
185
  | `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 |
186
+ | `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` at today's counts when the file predates it |
187
+ | `<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
188
 
182
189
  `--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.
183
190
 
@@ -189,6 +196,7 @@ pnpm install
189
196
 
190
197
  ```json
191
198
  {
199
+ "pack": "0.2.17",
192
200
  "rules": { "antelopejs/no-comments": 22, "eslint/max-depth": 1 },
193
201
  "oversizeFiles": { "src/legacy.ts": 31250 }
194
202
  }
@@ -196,8 +204,9 @@ pnpm install
196
204
 
197
205
  - 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
206
  - 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.
207
+ - 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.
208
+ - `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.
209
+ - 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, 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
210
 
202
211
  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
212
 
@@ -212,11 +221,13 @@ When every rule count is zero and `oversizeFiles` is empty, the ratchet is retir
212
221
  "rules": { "anti-slop/no-chained-type-assertions": 19, "*": 0 },
213
222
  "tsExpectError": 8,
214
223
  "tsIgnore": 0,
215
- "safety": 2
224
+ "safety": 2,
225
+ "config": { "typescript/unbound-method for src/test/**": 1 }
216
226
  }
217
227
  ```
218
228
 
219
229
  - `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.
230
+ - `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.
220
231
  - `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
232
  - `antelopejs-suppressions --update` lowers each ceiling to the current count and keeps rules at zero. No command raises a ceiling.
222
233
  - `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,6 +235,7 @@ When every rule count is zero and `oversizeFiles` is empty, the ratchet is retir
224
235
  - 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
236
  - `@ts-ignore` is also a lint error (`typescript/ban-ts-comment`); `@ts-expect-error` fails once its error is gone.
226
237
  - 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.
238
+ - 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
239
 
228
240
  ### Size
229
241
 
@@ -245,6 +257,8 @@ Pass `--allow-added <glob>` (repeatable) to `antelopejs-api-diff` when a refacto
245
257
  pnpm exec antelopejs-api-diff origin/main --allow-added '**/internal/**'
246
258
  ```
247
259
 
260
+ 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.
261
+
248
262
  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.
249
263
 
250
264
  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.
@@ -254,6 +268,28 @@ pnpm exec antelopejs-api-diff origin/main
254
268
  pnpm exec antelopejs-comment-proof origin/main
255
269
  ```
256
270
 
271
+ ### PR body check
272
+
273
+ 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.
274
+
275
+ `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.
276
+
277
+ `antelopejs-body-check <body.md>` (`-` reads standard input) checks the body against the repository at HEAD and prints one line per problem:
278
+
279
+ - 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;
280
+ - a suppression table or a proof summary line (`API:`, `Runtime API:`, `Comment proof:`) outside a stamped block;
281
+ - 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;
282
+ - 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);
283
+ - with `--base <sha>`, an api-diff block compared against a revision whose merge-base with HEAD is not the pull request base's.
284
+
285
+ Counts in prose are not checked. Run it on a checkout of the pull request head, with history back to the stamped base:
286
+
287
+ ```bash
288
+ gh pr view <number> --json body --jq .body | pnpm exec antelopejs-body-check -
289
+ ```
290
+
291
+ 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.
292
+
257
293
  ## oxfmt
258
294
 
259
295
  ```ts
@@ -277,7 +313,7 @@ The house style sets every field, so `.editorconfig` files cannot override it: `
277
313
 
278
314
  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
315
 
280
- ```ts
316
+ ```ts fragment
281
317
  // oxfmt.config.ts
282
318
  export default antelopeFmtPreset({
283
319
  ignorePatterns: ["frontend-vue/**"], // added to the shared ignores, not replacing them
@@ -347,10 +383,14 @@ An implementer must never be handed a breaking minor it does not implement. `wor
347
383
  ## Documentation guardrail
348
384
 
349
385
  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
386
+ links, explicitly labeled compatibility tables, and reference-page export
387
+ coverage, and typechecks every TypeScript fence against the repository's own
388
+ source; a fence opts out only with a `fragment` marker. Versions of
389
+ `@antelopejs/*` packages belong only in the block `antelopejs-sync` generates:
390
+ the action fails on version ranges and "requires … or later" claims in prose and
391
+ checks the block against the package.json beside it. Pin
352
392
  `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
393
+ required. The guide includes CI and local commands, marker syntax, and the
354
394
  checks that remain the author's responsibility.
355
395
 
356
396
  ## Contributing