@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.
- package/README.md +101 -52
- package/dist/bin/api-diff.mjs +430 -107
- package/dist/bin/body-check.d.mts +1 -0
- package/dist/bin/body-check.mjs +344 -0
- package/dist/bin/capture.d.mts +1 -0
- package/dist/bin/capture.mjs +559 -0
- package/dist/bin/check-size.mjs +3 -3
- package/dist/bin/checks.mjs +3 -3
- package/dist/bin/comment-proof.mjs +4 -3
- package/dist/bin/garden.mjs +6 -6
- package/dist/bin/ratchet.mjs +316 -10
- package/dist/bin/suppressions.mjs +118 -80
- package/dist/bin/sync.mjs +554 -153
- package/dist/bin/verify.mjs +240 -127
- package/dist/capture/index.d.mts +50 -0
- package/dist/capture/index.mjs +2 -0
- package/dist/{ceilings-BSw9p4YB.mjs → ceilings-B7KayYIG.mjs} +11 -3
- package/dist/{checks-BlWDFYio.mjs → checks-CxkSu2E6.mjs} +1 -1
- package/dist/{ci-workflow-DIsoEgMd.mjs → ci-workflow-ChW4He0r.mjs} +84 -3
- package/dist/{files-2FikHZ9F.mjs → files-DJ0TeaTU.mjs} +11 -5
- package/dist/formal/index.d.mts +40 -0
- package/dist/formal/index.mjs +205 -0
- package/dist/{json-BqvuCkqr.mjs → json-CG2L7YFl.mjs} +12 -8
- package/dist/oxc/anti-slop/index.mjs +869 -21
- package/dist/oxc/fmt.mjs +1 -1
- package/dist/oxc/guardrails/index.d.mts +1 -1
- package/dist/oxc/guardrails/index.mjs +736 -4
- package/dist/oxc/lint.d.mts +20 -3
- package/dist/oxc/lint.mjs +34 -10
- package/dist/oxlint-DIV-lLSS.mjs +98 -0
- package/dist/{package-Dtjt_lSa.mjs → package-BRTjkzt5.mjs} +29 -3
- package/dist/proof-stamp-DDDC0J6l.mjs +279 -0
- package/dist/ratchet-BAcLRYuM.mjs +448 -0
- package/dist/{renames-BGO4dWJ8.mjs → renames-L2owF5GD.mjs} +2 -2
- package/dist/scenes-DZVXkcxS.mjs +104 -0
- package/dist/shared-igPpEDpS.mjs +622 -0
- package/dist/{size-BVgNbLO6.mjs → size-DBatLT-F.mjs} +4 -4
- package/dist/suppression-base-9L8dlMQK.mjs +120 -0
- package/dist/suppression-budget-C0SkPO5R.mjs +535 -0
- package/dist/{suppressions-BJAngUxo.mjs → suppressions-DM60NkvL.mjs} +180 -18
- package/dist/templates-CypDm-j9.mjs +121 -0
- package/dist/typescript-CM0LrVP7.mjs +222 -0
- package/dist/verify/index.d.mts +6 -1
- package/dist/verify/index.mjs +1 -1
- package/package.json +31 -5
- package/dist/kinds-Bzyyi9yk.mjs +0 -25
- package/dist/ratchet-DRdIYwmv.mjs +0 -80
- package/dist/shared-CsXIMK3I.mjs +0 -34
- package/dist/staged-ratchet-CjoRfZaM.mjs +0 -236
- package/dist/suppression-budget-Yyf5_J5l.mjs +0 -283
- 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/
|
|
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
|
|
37
|
-
| bin | `antelopejs-
|
|
38
|
-
| bin | `antelopejs-
|
|
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 `
|
|
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
|
|
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
|
|
105
|
-
| Imports | `import/no-cycle`, `import/no-self-import`, `import/no-duplicates`
|
|
106
|
-
| Type-aware | `typescript/no-floating-promises` and
|
|
107
|
-
| Complexity | `max-params` 5, `max-lines-per-function` 120, `max-lines` 500, `max-depth` 4, `complexity` 20
|
|
108
|
-
| Anti-slop | all 15 vendored rules; `no-runtime-typeof` with `allowInTypeGuards`, so a `typeof` inside a type predicate or assertion function passes
|
|
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`
|
|
110
|
-
| Import sorting | `perfectionist/sort-imports`, autofixed by `oxlint --fix`
|
|
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-
|
|
120
|
-
| `antelopejs/no-
|
|
121
|
-
| `antelopejs/require-
|
|
122
|
-
| `antelopejs/no-
|
|
123
|
-
| `antelopejs/no-
|
|
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
|
|
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;
|
|
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
|
|
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
|
|
200
|
-
- `antelopejs-ratchet --
|
|
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
|
-
|
|
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
|
|
351
|
-
|
|
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,
|
|
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
|