@antelopejs/tooling-configs 0.4.1 → 0.5.1
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 +68 -29
- package/dist/bin/api-diff.mjs +235 -37
- package/dist/bin/body-check.mjs +14 -11
- package/dist/bin/capture.mjs +173 -54
- package/dist/bin/check-size.mjs +1 -1
- package/dist/bin/checks.mjs +166 -11
- package/dist/bin/comment-proof.mjs +29 -7
- package/dist/bin/garden.mjs +8 -58
- package/dist/bin/lease.mjs +48 -11
- package/dist/bin/ratchet.mjs +48 -14
- package/dist/bin/suppressions.mjs +3 -3
- package/dist/bin/sync.mjs +199 -80
- package/dist/bin/verify.mjs +1163 -474
- package/dist/capture/index.d.mts +6 -1
- package/dist/capture/index.mjs +1 -1
- package/dist/{ci-workflow-37qJa9LX.mjs → ci-workflow-COJUT12b.mjs} +121 -1
- package/dist/eslint.d.mts +16 -3
- package/dist/eslint.mjs +21 -6
- package/dist/formal/index.d.mts +20 -4
- package/dist/formal/index.mjs +71 -19
- package/dist/{map-B23_WMGE.mjs → map-DRyYz_Fw.mjs} +20 -1
- package/dist/oxc/anti-slop/index.mjs +156 -421
- package/dist/oxc/guardrails/index.d.mts +1 -1
- package/dist/oxc/guardrails/index.mjs +789 -103
- package/dist/oxc/lint.d.mts +13 -15
- package/dist/oxc/lint.mjs +19 -29
- package/dist/{package-CqqBgE8Y.mjs → package-Dn7VTFUW.mjs} +71 -17
- package/dist/{proof-stamp-DDDC0J6l.mjs → proof-stamp-DLWpPwQE.mjs} +72 -10
- package/dist/{ratchet-Q-JXuZIX.mjs → ratchet-ClfblHNJ.mjs} +18 -15
- package/dist/require-safety-comment-for-type-assertion-mnb0CIxa.mjs +181 -0
- package/dist/{scenes-DZVXkcxS.mjs → scenes-d-VQ0LOm.mjs} +4 -1
- package/dist/semver-BDxeEcP_.mjs +57 -0
- package/dist/{suppression-base-9L8dlMQK.mjs → suppression-base-Drnl6Y7F.mjs} +2 -2
- package/dist/{suppression-budget-C0SkPO5R.mjs → suppression-budget-Dvb_IqBo.mjs} +1 -1
- package/dist/{suppressions-DM60NkvL.mjs → suppressions-BroaaGJ_.mjs} +1 -1
- package/dist/{templates-BKZv-BRw.mjs → templates-lJBZFskp.mjs} +8 -3
- package/dist/type-aware-rules-DMuN6sHb.mjs +30 -0
- package/dist/{typescript-DAgQIAAR.mjs → typescript-BBbry7uU.mjs} +123 -27
- package/dist/verify/index.d.mts +60 -15
- package/package.json +3 -1
- package/dist/require-safety-comment-for-type-assertion-BBQ669kj.mjs +0 -83
package/README.md
CHANGED
|
@@ -9,7 +9,7 @@
|
|
|
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.
|
|
10
10
|
|
|
11
11
|
- [oxlint](https://oxc.rs) and [oxfmt](https://oxc.rs) replace Biome: lint, format and Tailwind class sorting, `.vue` included.
|
|
12
|
-
- ESLint stays for the Nuxt front ends, from a shared config
|
|
12
|
+
- ESLint stays for the Nuxt front ends, from a shared config: oxlint runs no Vue template rule and no type-aware rule on `.vue` files.
|
|
13
13
|
- [Knip](https://knip.dev) learns the entry points of an AntelopeJS module.
|
|
14
14
|
- Every preset is a function: options adjust it without copying it.
|
|
15
15
|
- `antelopejs-sync` writes the configs, hooks, scripts and agent instructions into a repository, and `antelopejs-sync --check` fails CI when they drift.
|
|
@@ -116,15 +116,15 @@ export default defineConfig({
|
|
|
116
116
|
|
|
117
117
|
### What the preset turns on
|
|
118
118
|
|
|
119
|
-
| Group | Rules
|
|
120
|
-
| -------------- |
|
|
121
|
-
| 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
|
|
122
|
-
| Imports | `import/no-cycle`, `import/no-self-import`, `import/no-duplicates`
|
|
123
|
-
| 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`
|
|
124
|
-
| Complexity | `max-params` 5, `max-lines-per-function` 120, `max-lines` 500, `max-depth` 4, `complexity` 20
|
|
125
|
-
| 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
|
|
126
|
-
| 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 |
|
|
127
|
-
| Import sorting | `perfectionist/sort-imports`, autofixed by `oxlint --fix`
|
|
119
|
+
| Group | Rules | Default |
|
|
120
|
+
| -------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------- |
|
|
121
|
+
| 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 |
|
|
122
|
+
| Imports | `import/no-cycle`, `import/no-self-import`, `import/no-duplicates` | error |
|
|
123
|
+
| 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 |
|
|
124
|
+
| Complexity | `max-params` 5, `max-lines-per-function` 120, `max-lines` 500, `max-depth` 4, `complexity` 20 | error |
|
|
125
|
+
| 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 |
|
|
126
|
+
| Guardrails | `antelopejs/no-comments`, `antelopejs/no-inherited-key-lookup`, `antelopejs/no-presence-only-type-guard`, `antelopejs/no-read-then-insert`, and with type-aware lint `antelopejs/no-unsafe-object-assign` and `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 |
|
|
127
|
+
| Import sorting | `perfectionist/sort-imports`, autofixed by `oxlint --fix` | off |
|
|
128
128
|
|
|
129
129
|
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`.
|
|
130
130
|
|
|
@@ -134,17 +134,19 @@ No rule warns. oxlint reports `correctness` as warnings by default, and warnings
|
|
|
134
134
|
|
|
135
135
|
The guardrail rules:
|
|
136
136
|
|
|
137
|
-
| Rule | Fails on
|
|
138
|
-
| ----------------------------------------- |
|
|
139
|
-
| `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`
|
|
140
|
-
| `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
|
|
141
|
-
| `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
|
|
142
|
-
| `antelopejs/
|
|
143
|
-
| `antelopejs/no-
|
|
144
|
-
| `antelopejs/
|
|
145
|
-
| `antelopejs/
|
|
146
|
-
| `antelopejs/no-
|
|
147
|
-
| `antelopejs/
|
|
137
|
+
| Rule | Fails on |
|
|
138
|
+
| ----------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
139
|
+
| `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` |
|
|
140
|
+
| `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 |
|
|
141
|
+
| `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 |
|
|
142
|
+
| `antelopejs/no-read-then-insert` | a call to `insert`, `insertOne` or `insertMany` on a table an earlier `get`, `getBy`, `getAll`, `count`, `find` or `findOne` read in the same function. A callback that runs while its caller waits belongs to that caller: one handed to `map`, `forEach`, `then` and the like, or to a call whose value is awaited or returned (through arrays, arguments, `?.`, `.then` or an inline arrow's body), such as `await withRetry(() => model.getAll())` or `Promise.all(rows.map((row) => limit(() => model.insert(row))))`. A nested function, a handler `app.post(...)` registers, or one `export const POST = withAuth(...)` wraps is its own function. One table: the insert's receiver lies on the read's chain (`table.filter(q).count()` reads `table`), or it is the read model's raw table (`model.get` then `model.table.insert`); `db.table("a")` and `db.table("b")`, or `this.get` and `this.audit.insert`, stay apart. Two replicas that boot on an empty table both read nothing and both insert. Not reported: an insert inside a `try` whose `catch` rethrows (`throw` or `Promise.reject`) nothing, or can finish without rethrowing (a `return`, `continue` or `break` of its own that returns no rejection, or every `throw` in a branch) and either reads the same table back or checks for a duplicate outside a `throw` (a name matching `duplicate`, `unique` or `conflict`, `11000`, `E11000`, `23505`, `ER_DUP_ENTRY`, or such a message in a string or template literal); a `.catch(callback)` on the insert or on its `.run()` that does the same, or `.catch(handler)` with a handler named for duplicates; an upsert, an options argument after the row with `conflict` other than `"error"`; an insert in a callback handed to a call that also takes the table, such as `insertRowOnce(model, id, () => model.insert(row))`, or through a parameter that shadows the read's receiver, when the read sits outside that callback. Off in test files. Purely syntactic: it does not read types, follow aliases or see a lock, so code that serializes the read and the insert takes a directive whose reason names the lock. The rule's shapes are frozen: a new edge case takes a directive with its reason, not a rule change |
|
|
143
|
+
| `antelopejs/no-unsafe-object-assign` | `Object.assign(target, ...sources)` where a source writes over a property the target's type declares: a source typed `unknown` or `any`, or holding such values under a `string` index signature (`Object.fromEntries` of `[string, unknown]` pairs) while the target has a field that does not take `unknown`; a property typed `unknown` or `any`, or holding `any` in its elements (`[value]` with `value: any`); a property whose type neither the target property nor its setter accepts. A value written in the source keeps the types a direct assignment gives it: `{ status: "loading" }`, `{ modes: ["a"] }` and nested literals keep their literal types (required properties, undeclared properties and tuple lengths still count), and a shorthand property reads its variable. A union source such as `flag && { stages }` is checked member by member, an optional source property is compared without its `undefined` (kept under `exactOptionalPropertyTypes`) but keeps `null`, and a `this` or generic target is read through its constraint. `Object.assign<T, U>` returns `T & U`, so TypeScript never compares the two and the call is an unchecked assertion. Not reported: properties the target does not declare (`Object.assign(new Error(message), { code })`), fields typed `unknown` or `any`, setters declared in a generic class, interface or type alias, spread sources and targets with no properties. Types come from the TypeScript program of the tsconfig that lists the file. On only with type-aware lint |
|
|
144
|
+
| `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 |
|
|
145
|
+
| `antelopejs/no-fs-read-in-tests` | `readFileSync` or `readdirSync` from `fs` in a test file. Files under `fixtures/`, `helpers/` and `locales/` may read |
|
|
146
|
+
| `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. In a package whose `antelopeJs.test` is set, `ajs module test` resolves the name through its own module resolver, so a self-link is no proof there and every self-import is reported. Import the module by relative path instead |
|
|
147
|
+
| `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)` |
|
|
148
|
+
| `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 |
|
|
149
|
+
| `antelopejs/no-typeof-function-only-test` | a test whose only assertions are `toBeTypeOf("function")`, `to.be.a("function")` or equivalents |
|
|
148
150
|
|
|
149
151
|
`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.
|
|
150
152
|
|
|
@@ -165,6 +167,8 @@ antelopePreset({
|
|
|
165
167
|
});
|
|
166
168
|
```
|
|
167
169
|
|
|
170
|
+
`oxlint-tsgolint` reads only TypeScript files, so the type-aware rules do not run on the script blocks of `.vue` files, and oxlint reports nothing about it. `antelopeNuxtConfig({ typeAware })` runs the same rules there from ESLint; see [ESLint](#eslint-nuxt-front-ends).
|
|
171
|
+
|
|
168
172
|
### Add ignore patterns
|
|
169
173
|
|
|
170
174
|
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:
|
|
@@ -208,17 +212,45 @@ pnpm install
|
|
|
208
212
|
| `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 |
|
|
209
213
|
| `<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 |
|
|
210
214
|
|
|
211
|
-
`--profile template` writes only the three preset configs, a user-facing `AGENTS.md` block and the `suppressions`
|
|
215
|
+
`--profile template` writes only what `antelopejs-checks` runs, for template repositories: the three preset configs, a user-facing `AGENTS.md` block, `guardrails.suppressions.json`, and the `package.json` scripts and devDependencies of the table above without the hooks (no `prepare`, no `lefthook`). It sets `checks`, `size`, `suppressions` and `suppressions:update`, plus `ratchet` and `ratchet:update` once `guardrails.ratchet.json` exists. It adds `typecheck`, `lint`, `format`, `format:check`, `knip`, `sync` and `sync:check` only where the template has none, the sync scripts with `--profile template`. It writes no `guardrails.ratchet.json`. The agent layer, `verify-template` and the writing skills under `.agents/skills/` with their `.claude/skills` links, is synced and checked only in the template source, marked by its `.agents/skills/verify-template/` folder; a project scaffolded from the template ships without it, so the template's `AGENTS.md` block links no skill under `.agents/` or `.claude/skills/`. `antelopejs-sync --check` writes nothing and exits 1 on any drift; `pnpm run checks` runs it.
|
|
212
216
|
|
|
213
|
-
`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 `guardrails.ratchet.json` exists. When the repository has a verify layer, an `.agents/skills/verify-*` folder holding a `verify.config.ts` or a `tsconfig.json`, it also runs `verify:types` and `verify:lockfiles`, which need no package script. Neither writes a file in the repository, spawns a package manager or fetches anything, so both pass offline after a root install, as CI runs them.
|
|
217
|
+
`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 `guardrails.ratchet.json` exists. When the repository has a verify layer, an `.agents/skills/verify-*` folder holding a `verify.config.ts` or a `tsconfig.json`, it also runs `verify:types` and `verify:lockfiles`, which need no package script. Neither writes a file in the repository, spawns a package manager or fetches anything, so both pass offline after a root install, as CI runs them. When the repository holds a `pnpm-lock.yaml`, outside what `.gitignore` leaves out, it also runs `lockfile:singletons`, which fails when a lockfile resolves an `@antelopejs/interface-*` package at more than one version and names the importers and packages that pull each copy. It reads the lockfiles only. In a git checkout it also runs `git:identity`, which fails when the repository's own git config, the `.git/config` every worktree shares or a worktree's `config.worktree`, sets `user.name` or `user.email`, and names the file and value. An identity from the global config or a `git -c` passes.
|
|
214
218
|
|
|
215
219
|
- `verify:types` type-checks each layer's own code with the repository's own TypeScript, run as `node <typescript>/bin/tsc` without a shell. The files are those the layer's `tsconfig.json` includes, minus its `playground` folder and any `node_modules` or `dist` folder: verify compiles a playground itself, with the playground's own config, after installing it. The step writes a config to the system temp folder that extends the layer's, lists those files, keeps the layer's type roots, sets `noEmit` and unsets with `null` the `declaration`, `composite`, `incremental`, `tsBuildInfoFile`, `declarationDir`, `declarationMap`, `emitDeclarationOnly` and `isolatedDeclarations` the layer may inherit, then deletes it. No `.tsbuildinfo` is written, no declaration check runs on code that is never emitted, and `skipLibCheck` keeps the layer's value. `antelopejs-sync` writes the `tsconfig.json` of the shared `verify-interface`, `verify-module` and `verify-template` layers; a repository's own layer, such as a `verify-dms-*` one, keeps the one it wrote. A layer with a `verify.config.ts` and no `tsconfig.json` fails, and so does one whose `tsconfig.json` does not include its `verify.config.ts`.
|
|
216
220
|
- `verify:lockfiles` compares, in code, the direct dependencies each lockfile records with the `package.json` files it locks, and fails on a difference in either direction, naming the dependency and the command that regenerates the lockfile. It reads each lockfile in a folder under a layer, `node_modules` and `dist` aside, and in the root `playground`. A `pnpm-lock.yaml` is compared importer by importer, for each importer it lists that has a `package.json` on disk; a `package-lock.json` by its root entry. Only `dependencies`, `devDependencies` and `optionalDependencies` are compared, by name and specifier: a name counts as present whichever of the three fields records it, and a `catalog:` or `workspace:` specifier compares as written, as pnpm stores it. A name the lockfile records that `package.json` declares only in `peerDependencies` passes, whether or not peers are auto-installed. A name an override selector in the `pnpm-lock.yaml` mentions is not compared, nor is a `link:` dependency the lockfile leaves out under `excludeLinksFromLockfile`. A lockfile it cannot parse, or of a version before pnpm's 6 or npm's 2, fails as unreadable. A missing lockfile fails only in a layer's `playground` or the root `playground` whose `package.json` has dependencies, unless a folder above it holds a `pnpm-workspace.yaml` or a `package.json` with `workspaces`; the fix it names is npm's when a `package-lock.json` sits in a folder above, pnpm's otherwise. It does not check workspace membership, `overrides`, lockfile `settings`, catalogs, `.npmrc` or user configuration, resolved versions, integrity hashes, transitive entries, npm workspace members, or `yarn.lock` and `bun.lock`: verify's own frozen install still rejects a lockfile stale there.
|
|
217
221
|
|
|
218
222
|
`ANTELOPEJS_CHECKS_SKIP` accepts both names.
|
|
219
223
|
|
|
224
|
+
The steps run at the same time, `test` last and alone. When two steps read something one of them builds, such as a workspace package's `dist` that `typecheck` builds and `lint` resolves, add a `checks:prepare` package script that builds it. `pnpm run checks` runs it once before any step and after it checks that Docker Compose can run, whenever at least one step runs. Its output is printed only when it fails, and then no step runs. It counts as a step only when it fails, and a repository without it runs as before.
|
|
225
|
+
|
|
220
226
|
When the repository has `.github/compose.yml`, the file the shared CI starts through its `services-compose-file` input, and the `test` step runs, `pnpm run checks` runs `docker compose -f .github/compose.yml up -d --wait` before the steps and `docker compose -f .github/compose.yml down -v` after them, also when a step fails or the run is interrupted (SIGINT, SIGTERM or SIGHUP stops the running step or `up`, removes the services and exits 130, 143 or 129; a repeated signal does not cut the teardown short). The compose project is `COMPOSE_PROJECT_NAME` when set, else the file's own `name:`, else one named after the repository root, so checkouts never share the `github` project compose would derive from the file's directory. Services are left alone when every port the file publishes already accepts connections, so a stack you started yourself is reused and kept. A run's project that already had containers before the run is started but not removed. When Docker Compose cannot run, the run fails before any step, naming the compose file, because the tests that need those services would wait for them forever. On GitHub Actions (`GITHUB_ACTIONS=true`) the workflow owns the services, and `--no-services` skips all of this anywhere.
|
|
221
227
|
|
|
228
|
+
### Module locks update
|
|
229
|
+
|
|
230
|
+
A repository that commits `antelope-lock/` installs each module from its recorded lock, so its modules and their dependencies move only when someone records the locks again. Renovate does not read `antelope-lock/`. The shared `modules-update.yml` workflow of `AntelopeJS/.github` records the locks again and opens or updates one pull request per base branch, from `antelopejs/modules-update/<base>`. Its body lists the modules that moved from which version to which, the direct dependencies of each, and the npm advisories it fixes or leaves. A scheduled run refreshes on its `weekday` (Monday by default), and on any other day only when the npm advisory API reports an advisory not seen since the last successful run; a manual run always refreshes.
|
|
231
|
+
|
|
232
|
+
`antelopejs-sync` does not write this caller. Add `.github/workflows/modules-update.yml` to each repository that commits `antelope-lock/`:
|
|
233
|
+
|
|
234
|
+
```yaml
|
|
235
|
+
name: Modules update
|
|
236
|
+
on:
|
|
237
|
+
schedule:
|
|
238
|
+
- cron: "23 5 * * *"
|
|
239
|
+
workflow_dispatch:
|
|
240
|
+
permissions: {}
|
|
241
|
+
jobs:
|
|
242
|
+
modules-update:
|
|
243
|
+
permissions:
|
|
244
|
+
contents: write
|
|
245
|
+
pull-requests: write
|
|
246
|
+
actions: write
|
|
247
|
+
uses: AntelopeJS/.github/.github/workflows/modules-update.yml@v1
|
|
248
|
+
```
|
|
249
|
+
|
|
250
|
+
A project needs no `with`: the default `refresh-command` is `pnpm exec ajs project modules update`. That command refuses to run in a module repository, so a module passes `refresh-command: rm -rf antelope-lock && pnpm run test`, which records the locks of its test configuration.
|
|
251
|
+
|
|
252
|
+
A push made with `GITHUB_TOKEN` starts no workflow, so the workflow then dispatches `ci.yml` on the branch. Sync keeps `workflow_dispatch` on the `ci.yml` it owns, so `ci / checks` runs on the new head. A repository whose checks live in another workflow passes its file as `ci-workflow`. `GITHUB_TOKEN` opens the pull request only where the repository allows GitHub Actions to create pull requests; otherwise pass a `token` secret that may, and its push starts the checks with nothing dispatched. Without either, the run pushes the branch and fails with a link to open the pull request by hand. The other inputs and the failure rules are in [Module locks update](https://github.com/AntelopeJS/.github#module-locks-update).
|
|
253
|
+
|
|
222
254
|
### Ratchet
|
|
223
255
|
|
|
224
256
|
`guardrails.ratchet.json` holds the debt a repository had when it adopted the pack:
|
|
@@ -233,7 +265,7 @@ When the repository has `.github/compose.yml`, the file the shared CI starts thr
|
|
|
233
265
|
|
|
234
266
|
- 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.
|
|
235
267
|
- 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.
|
|
236
|
-
- The pre-commit hook runs `antelopejs-ratchet --staged`: for each rule under `rules` it counts the findings in
|
|
268
|
+
- The pre-commit hook runs `antelopejs-ratchet --staged`: for each rule under `rules` it counts the findings in every staged file as the index holds it (a file whose working copy differs or was deleted after staging is linted from a checkout of the index), 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.
|
|
237
269
|
- 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.
|
|
238
270
|
- `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.
|
|
239
271
|
- 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.
|
|
@@ -244,14 +276,14 @@ When every rule count is zero and `oversizeFiles` is empty, the ratchet is retir
|
|
|
244
276
|
|
|
245
277
|
### Lib check coverage
|
|
246
278
|
|
|
247
|
-
No repository sets `skipLibCheck` globally. `typecheck` runs a full `tsc --noEmit` over the program that covers the sources, and `build` may pass `--skipLibCheck` only over a program `typecheck` checks in full, so nothing `typecheck` skipped goes unchecked. `antelopejs-sync
|
|
279
|
+
No repository sets `skipLibCheck` globally. `typecheck` runs a full `tsc --noEmit` over the program that covers the sources, and `build` may pass `--skipLibCheck` only over a program `typecheck` checks in full, so nothing `typecheck` skipped goes unchecked. `antelopejs-sync --check` fails with a line naming the file, the script and the fix, and plain `antelopejs-sync` prints the same line as a `Note:` and carries on, when:
|
|
248
280
|
|
|
249
281
|
- `build` passes `--skipLibCheck` (in any letter case) to a `tsc` program (`-p`/`--project`, `tsconfig.json` when absent) that no `tsc` run of `typecheck` covers without `--skipLibCheck`. `./tsconfig.build.json` and `tsconfig.build.json`, `-p .` and no `-p` are the same program. `pre<script>` scripts count with their script, and `&&` chains, parentheses, `cross-env` and environment prefixes, `run-s` and `npm-run-all`, and scripts run through `pnpm`, `npm`, `yarn` or `bun` (`--filter <x>`, `-C <dir>` and other options with a value included) are followed to five levels. `tsc` is recognised as `tsc`, `npx tsc`, `npx -p typescript tsc`, `pnpm exec tsc` and `node ./node_modules/typescript/bin/tsc`.
|
|
250
282
|
- A tsconfig the scripts use through `tsc`, or the root `tsconfig.json`, ends up with `compilerOptions.skipLibCheck: true`, set directly or through a local `extends` chain (`.json` or `.jsonc`, a later duplicate key winning as in tsc). `tsc -b` reads the config it names and the projects they reference. Presets extended from a package are not read. When the file that sets it is one git ignores, such as Nuxt's generated `.nuxt/tsconfig.json`, the note names the first tracked tsconfig of the chain and asks for `skipLibCheck: false` there; when none is tracked, nothing is reported.
|
|
251
283
|
- A `release` script exists and does not run `typecheck`, directly or through a script it runs, its `prerelease`, or a release-it hook that runs before publishing (`before:init`, `before:bump`, `before:release` and their plugin-scoped forms), read from `.release-it.json` and from `release-it.hooks` in `package.json`.
|
|
252
|
-
- A file the check needs cannot be read (a directory where a tsconfig is expected, a permission error):
|
|
284
|
+
- A file the check needs cannot be read (a directory where a tsconfig is expected, a permission error): both commands print a `Note:` that says "could not read …" and neither fails on it.
|
|
253
285
|
|
|
254
|
-
|
|
286
|
+
`antelopejs-checks` runs `sync:check`, so a finding fails it too.
|
|
255
287
|
|
|
256
288
|
Known blind spots, none of them read: `|| true` or a background `&` after a `typecheck`, a `typecheck` placed after `release-it` in `release`, a `typecheck` that checks nothing, `vue-tsc`, release-it configs other than JSON (`.release-it.js`, `.yaml`, `.toml`), presets extended from a package, and workspace packages.
|
|
257
289
|
|
|
@@ -293,6 +325,8 @@ A behaviour-preserving cleanup PR shows `antelopejs-api-diff <base-ref>` passing
|
|
|
293
325
|
|
|
294
326
|
A comment-only PR shows `antelopejs-comment-proof <base-ref>` passing instead of a verifier. It includes private packages, ignores type diagnostics and compares comment-free JavaScript emit byte for byte. Both commands exclude test sources, fail on added or removed outputs, and print unified diffs for changes.
|
|
295
327
|
|
|
328
|
+
The runtime half loads each built entry in a child process and writes its description to a file, so an entry that prints on import, such as a CLI under a wildcard export, is described like any other. An entry that exits while it loads, or sets a non-zero `process.exitCode`, has its exit code recorded (`"exit": 2`), so a changed exit code is a difference. An entry that throws, while it loads or afterwards, is an execution error.
|
|
329
|
+
|
|
296
330
|
Test-helper entries are outside both halves. A published entry whose built file is test output relative to `outDir` (under `test/`, `tests/` or `__tests__/`, or named `*.test.*` or `*.spec.*`) is neither bundled nor loaded, because helpers such as `./tests/*` import a test runner that the proof does not run. This applies the same way to the declaration and the runtime half, to wildcard and plain targets, and to files a general wildcard such as `./*` matches. Each half prints `API: skipped test-helper entry <target> in <directory>` or `Runtime API: skipped test-helper entry <target> in <directory>`; a package whose only wildcard export is `./tests/*` still has its other entries compared in both halves.
|
|
297
331
|
|
|
298
332
|
Pass `--allow-added <glob>` (repeatable) to `antelopejs-api-diff` when a refactor adds helper files that a wildcard export publishes, such as an `internal/` directory under `"./*"`. An added entry passes, in both the declaration and the runtime half, when its published subpath matches a glob (for example `--allow-added '**/internal/**'`, matched against `base/table-view/internal/helper` for `./base/table-view/internal/helper`) and its source module is marked `@internal`: a leading `/** @internal @packageDocumentation */` comment on the module (`@module` and `@fileoverview` also qualify), or an `@internal` tag on every exported declaration. Allowed entries are printed under `Added (allowed): <count>`; nothing is printed when no entry was added. An added entry that matches but is not marked `@internal` fails with the file and the fix. Added entries matching no glob, removed entries and changed entries still fail, matching or not. Without the flag nothing changes.
|
|
@@ -371,15 +405,20 @@ Delete `biome.json` and the `@biomejs/biome` dependency, point `lint`, `lint:fix
|
|
|
371
405
|
|
|
372
406
|
## ESLint (Nuxt front ends)
|
|
373
407
|
|
|
374
|
-
oxlint
|
|
408
|
+
oxlint runs no Vue template rule and no type-aware rule on `.vue` files, so the front end stays on ESLint:
|
|
375
409
|
|
|
376
410
|
```js
|
|
377
411
|
// frontend-vue/eslint.config.mjs
|
|
378
412
|
import { antelopeNuxtConfig } from "@antelopejs/tooling-configs/eslint";
|
|
379
413
|
|
|
380
|
-
export default antelopeNuxtConfig({
|
|
414
|
+
export default antelopeNuxtConfig({
|
|
415
|
+
dirs: ["./playground"],
|
|
416
|
+
typeAware: { tsconfigRootDir: import.meta.dirname },
|
|
417
|
+
});
|
|
381
418
|
```
|
|
382
419
|
|
|
420
|
+
`typeAware` runs the oxlint preset's type-aware rules, as `@typescript-eslint/<rule>`, on the script blocks of `.vue` files, which `oxlint-tsgolint` cannot read. Off when omitted. TypeScript files are left to oxlint, so nothing is type-checked twice. `tsconfigRootDir` is the project root. Each `.vue` file must be listed by its nearest `tsconfig.json`, as the root one that extends or references `.nuxt/` lists the app; a file outside it, such as a playground no tsconfig includes, fails to parse. Types flow from the `.ts` files a component imports. Without Volar, a type imported from another `.vue` file is an error type: `no-unsafe-*` reports code that uses it, which `rules` can switch off, and a `lang="tsx"` block fails to parse.
|
|
421
|
+
|
|
383
422
|
`@nuxt/eslint-config` supplies the Vue and TypeScript rules. The preset only records where AntelopeJS layers differ: single-word page components, `any` and `{}` allowed, `_`-prefixed unused bindings, and import order left alone. It sets no formatting rule, since oxfmt formats `.vue`. Every rule the resolved config sets to warn becomes an error, so no rule warns there either. Pass `rules` to layer your own on top, and declare `@nuxt/eslint-config` in the front end's `package.json`.
|
|
384
423
|
|
|
385
424
|
## Knip
|