@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.
- package/README.md +88 -48
- package/dist/bin/api-diff.mjs +409 -97
- package/dist/bin/body-check.d.mts +1 -0
- package/dist/bin/body-check.mjs +344 -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 +5 -5
- package/dist/bin/ratchet.mjs +267 -7
- package/dist/bin/suppressions.mjs +118 -80
- package/dist/bin/sync.mjs +490 -35
- package/dist/bin/verify.mjs +5 -5
- 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-Bc036sJW.mjs} +2 -2
- package/dist/{json-BqvuCkqr.mjs → json-CG2L7YFl.mjs} +12 -8
- package/dist/oxc/anti-slop/index.mjs +160 -13
- package/dist/oxc/fmt.mjs +1 -1
- package/dist/oxc/guardrails/index.d.mts +1 -1
- package/dist/oxc/guardrails/index.mjs +645 -1
- package/dist/oxc/lint.d.mts +11 -3
- package/dist/oxc/lint.mjs +21 -8
- package/dist/oxlint-Bltmk8-6.mjs +94 -0
- package/dist/{package-Dtjt_lSa.mjs → package-DTxLPNDu.mjs} +3 -2
- package/dist/proof-stamp-w-3j47A-.mjs +279 -0
- package/dist/ratchet-DwRj9h4L.mjs +275 -0
- package/dist/{renames-BGO4dWJ8.mjs → renames-L2owF5GD.mjs} +2 -2
- package/dist/shared-CoUt4GUm.mjs +73 -0
- package/dist/{size-BVgNbLO6.mjs → size-DNtWruCO.mjs} +3 -3
- package/dist/suppression-base-DAfCXwjL.mjs +95 -0
- package/dist/{suppression-budget-Yyf5_J5l.mjs → suppression-budget-Bd2GqMYb.mjs} +248 -33
- package/dist/{suppressions-BJAngUxo.mjs → suppressions-BD_f8f7L.mjs} +180 -18
- package/dist/typescript-BmS5BmrS.mjs +222 -0
- package/dist/verify/index.mjs +1 -1
- package/package.json +4 -2
- 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/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
|
|
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,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 `
|
|
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
|
|
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`
|
|
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-
|
|
120
|
-
| `antelopejs/no-
|
|
121
|
-
| `antelopejs/
|
|
122
|
-
| `antelopejs/no-
|
|
123
|
-
| `antelopejs/
|
|
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
|
|
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;
|
|
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
|
|
200
|
-
- `antelopejs-ratchet --update` lowers each number to the current count and removes what reached zero. It never raises a number
|
|
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
|
|
351
|
-
|
|
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,
|
|
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
|