@antelopejs/tooling-configs 0.2.17 → 0.2.18
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +27 -18
- package/dist/bin/api-diff.mjs +25 -14
- package/dist/bin/body-check.mjs +3 -3
- package/dist/bin/capture.d.mts +1 -0
- package/dist/bin/capture.mjs +559 -0
- package/dist/bin/check-size.mjs +3 -3
- package/dist/bin/checks.mjs +2 -2
- package/dist/bin/comment-proof.mjs +3 -3
- package/dist/bin/garden.mjs +1 -1
- package/dist/bin/ratchet.mjs +146 -100
- package/dist/bin/suppressions.mjs +5 -5
- package/dist/bin/sync.mjs +115 -169
- package/dist/bin/verify.mjs +238 -125
- package/dist/capture/index.d.mts +50 -0
- package/dist/capture/index.mjs +2 -0
- package/dist/{files-Bc036sJW.mjs → files-DJ0TeaTU.mjs} +10 -4
- package/dist/formal/index.d.mts +40 -0
- package/dist/formal/index.mjs +205 -0
- package/dist/oxc/anti-slop/index.mjs +717 -16
- package/dist/oxc/fmt.mjs +1 -1
- package/dist/oxc/guardrails/index.d.mts +1 -1
- package/dist/oxc/guardrails/index.mjs +93 -5
- package/dist/oxc/lint.d.mts +9 -0
- package/dist/oxc/lint.mjs +14 -3
- package/dist/{oxlint-Bltmk8-6.mjs → oxlint-DIV-lLSS.mjs} +7 -3
- package/dist/{package-DTxLPNDu.mjs → package-BRTjkzt5.mjs} +26 -1
- package/dist/{proof-stamp-w-3j47A-.mjs → proof-stamp-DDDC0J6l.mjs} +3 -3
- package/dist/{ratchet-DwRj9h4L.mjs → ratchet-BAcLRYuM.mjs} +194 -21
- package/dist/scenes-DZVXkcxS.mjs +104 -0
- package/dist/shared-igPpEDpS.mjs +622 -0
- package/dist/{size-DNtWruCO.mjs → size-DBatLT-F.mjs} +2 -2
- package/dist/{suppression-base-DAfCXwjL.mjs → suppression-base-9L8dlMQK.mjs} +36 -11
- package/dist/{suppression-budget-Bd2GqMYb.mjs → suppression-budget-C0SkPO5R.mjs} +56 -19
- package/dist/{suppressions-BD_f8f7L.mjs → suppressions-DM60NkvL.mjs} +1 -1
- package/dist/templates-CypDm-j9.mjs +121 -0
- package/dist/{typescript-BmS5BmrS.mjs → typescript-CM0LrVP7.mjs} +2 -2
- package/dist/verify/index.d.mts +6 -1
- package/package.json +28 -4
- package/dist/shared-CoUt4GUm.mjs +0 -73
package/README.md
CHANGED
|
@@ -3,7 +3,7 @@
|
|
|
3
3
|
<div align="center">
|
|
4
4
|
<a href="https://www.npmjs.com/package/@antelopejs/tooling-configs"><img alt="npm" src="https://img.shields.io/npm/v/@antelopejs/tooling-configs?style=for-the-badge&labelColor=000000&color=000000"></a>
|
|
5
5
|
<a href="./LICENSE"><img alt="License" src="https://img.shields.io/npm/l/@antelopejs/tooling-configs?style=for-the-badge&labelColor=000000&color=000000"></a>
|
|
6
|
-
<a href="https://discord.gg/
|
|
6
|
+
<a href="https://discord.gg/g4pFt6eXqu"><img src="https://img.shields.io/badge/Discord-18181B?logo=discord&style=for-the-badge&color=000000" alt="Discord"></a>
|
|
7
7
|
</div>
|
|
8
8
|
|
|
9
9
|
The AntelopeJS guardrail pack: shared lint, format and dead-code presets, the commands that install and enforce them in a repository, and a check for the version ranges of interface dependencies.
|
|
@@ -50,7 +50,9 @@ The AntelopeJS guardrail pack: shared lint, format and dead-code presets, the co
|
|
|
50
50
|
|
|
51
51
|
## Shared verification skills
|
|
52
52
|
|
|
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
|
+
`antelopejs-sync` writes one shared verification skill into a repository: `verify-interface` for an interface, `verify-module` for an implementation module (inferred from `antelopeJs.implements`) and `verify-template` under `--profile template`. Pass `--verify interface|module|template` to choose, or `--verify custom` for a repository that keeps its own `.agents/skills/verify-<repo>/`. Sync writes `SKILL.md`, `package.json` and `tsconfig.json` in `.agents/skills/verify-<kind>/` with a `.claude/skills/verify-<kind>` link, and `--check` reports them as drift. The `tsconfig.json` extends the root one with ES module resolution and loads the Node types, so type-aware lint sees the real types of the repository's files there, Node APIs included. It never touches the repository's own layer beside them: `verify.config.ts`, `features/`, `seeded-breaks/` and `seeded-doors/`.
|
|
54
|
+
|
|
55
|
+
`antelopejs-sync` also installs the `technical-writing` and `unslop` skills in every repository, under both profiles. Each is `.agents/skills/<name>/SKILL.md` with a `.claude/skills/<name>` link. The text is vendored unchanged from Upd4ting/agent-config `claude/skills/<name>/SKILL.md` at commit 4e0a848, and `--check` reports an edited file as drift. Write documentation with them: `technical-writing` picks the page's mode and sets the sentence rules, and `unslop` lists the patterns to cut.
|
|
54
56
|
|
|
55
57
|
Every deterministic step of a verification is an `antelopejs-verify` command: `map`, `plan`, `new`, `doctor`, `journey`, `formal`, `doors`, `seeded`, `seeded-doors`, `clean`, `verdict` and `publish`. The synced `SKILL.md` documents each one for the agent that verifies.
|
|
56
58
|
|
|
@@ -100,17 +102,19 @@ export default defineConfig({
|
|
|
100
102
|
|
|
101
103
|
### What the preset turns on
|
|
102
104
|
|
|
103
|
-
| Group | Rules
|
|
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
|
|
106
|
-
| Imports | `import/no-cycle`, `import/no-self-import`, `import/no-duplicates`
|
|
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`
|
|
108
|
-
| Complexity | `max-params` 5, `max-lines-per-function` 120, `max-lines` 500, `max-depth` 4, `complexity` 20
|
|
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
|
|
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`
|
|
105
|
+
| Group | Rules | Default |
|
|
106
|
+
| -------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------- |
|
|
107
|
+
| oxc | the `correctness` category, with the `eslint`, `typescript`, `node`, `oxc`, `import` and `promise` plugins; `no-unused-vars` (`_` prefix allowed), `eqeqeq` (`== null` allowed), `radix`, `prefer-regex-literals`, `typescript/ban-ts-comment` for `@ts-ignore` only | error |
|
|
108
|
+
| Imports | `import/no-cycle`, `import/no-self-import`, `import/no-duplicates` | error |
|
|
109
|
+
| Type-aware | `typescript/no-floating-promises` and thirteen more type-aware rules, including `no-unnecessary-type-parameters`, `no-unsafe-argument`, `no-unsafe-assignment`, `no-unsafe-return` and `use-unknown-in-catch-callback-variable` | error |
|
|
110
|
+
| Complexity | `max-params` 5, `max-lines-per-function` 120, `max-lines` 500, `max-depth` 4, `complexity` 20 | error |
|
|
111
|
+
| Anti-slop | all 15 vendored rules; `no-runtime-typeof` with `allowInTypeGuards`, so a `typeof` (or `.constructor === String`) inside a type predicate or assertion function passes | error |
|
|
112
|
+
| Guardrails | `antelopejs/no-comments`, `antelopejs/no-inherited-key-lookup`, `antelopejs/no-presence-only-type-guard`, and with type-aware lint `antelopejs/require-tsconfig-include`; in test files `antelopejs/no-fs-read-in-tests`, `antelopejs/no-self-import-in-tests`, `antelopejs/no-constant-value-assertion`, `antelopejs/no-typeof-function-only-test` and `antelopejs/require-assertion` | error |
|
|
113
|
+
| Import sorting | `perfectionist/sort-imports`, autofixed by `oxlint --fix` | off |
|
|
114
|
+
|
|
115
|
+
Three anti-slop rules skip a value at its boundary. `no-runtime-typeof` also counts a `.js`/`.mjs` function documented `@returns {x is T}` as a type guard. `no-unsafe-dictionary-type` allows `Record<string, unknown>` as a `value is T` target or inside a type-guard body. `no-unknown-parameters` skips a `this` parameter, a parameter decorated `@JSONBody`, `@JsonBody` or `@Parameter`, the reason of a callback passed directly to `.catch(...)` or as `.then(_, onRejected)`, the parameter of a `(reason: unknown) => void` type declared as `reject` or on a `new Promise` executor, the `unknown` parameters of a function type that annotates a plain callback parameter which the function only calls (and tests for existence), at least once, passing a never-reassigned catch variable in each `unknown` position (a callback that is stored, passed on, never called or called with any other value stays reported), a parameter typed exactly `unknown` of a function whose declared return type is primitive and whose only use of it is to read a symbol-keyed member (`value[BRAND]`, `BRAND in value`) of a `const` bound to `Symbol(...)` or `Symbol.for(...)` in the file, directly, through a `const` alias, or through a function declared in the file that does the same, behind type guards declared in the file, where the member is only read and what is read reaches nothing but the result (it may be tested, compared, negated, read further, passed to `Boolean(...)` or held in a `const` that obeys the same rule; a write, `delete`, update, call of the member, or an argument to any other call refuses), the brand probe, and a parameter typed exactly `unknown` at a parse boundary: the function only passes it to a schema or decoder that is not written in the same file, meaning its root, followed through members, calls, `const` aliases, `import x = Namespace.member` aliases, parameter and destructuring defaults, assignments and type wrappers, is a module import, a global that nothing in the file assigns, or a parameter that nothing in the file defaults or assigns, and not a name that the file may merge or write (a name read inside a namespace block that the block does not bind itself, which another block of the namespace may declare as a member that shadows an import or a global), a function, class, namespace, object literal, `let`, a `this` that is not the class's own (the `this` of an object-literal method or a nested function), a class element of another name, kind or static-ness, or a call handed an object, an array or a `this` that holds a function written here, or a call on a global (`Object.freeze`, `Array.from`, `Promise.resolve`) handed any function written here (`parse`, `safeParse`, `parseAsync`, `safeParseAsync`, `decode`, a `parseX` or `decodeX` helper, `assertValidation`), never mentions `arguments` or `eval`, and returns that call's result under a declared return type other than `unknown` or `any`.
|
|
112
116
|
|
|
113
|
-
|
|
117
|
+
`no-runtime-typeof` does not report a `typeof` that only fills in the text of a message, such as ``throw new Error(`received ${typeof value}`)`` or ``assert(ok, `received ${typeof value}`)``: the template holds other text, and a `throw`, a bare `assert(...)` or a `log(...)` method that stands as a statement takes it. The `assert`, the object `log` is read from, and the class of a thrown `new` must come from outside the file: a module import, a global that nothing in the file assigns, or a parameter that nothing in the file defaults or assigns, reached through members and type wrappers only. A name read inside a namespace block counts only when the block binds it, as a parameter, because another block of the namespace may declare a member of that name that shadows an import or a global. A function, class, `const`, `let`, `this`, call result or namespace written in the file can compare or store the message, so a `typeof` handed to it stays reported. The same template compared, bound to a name, returned, or handed to any other call (`assert.equal`, `Set#add`, `emit`, a dispatcher) stays reported, because a caller can test it or use it as a key.
|
|
114
118
|
|
|
115
119
|
No rule warns. oxlint reports `correctness` as warnings by default, and warnings never fail the command, so the preset raises it to error. A repository with existing findings records them in `guardrails.ratchet.json` instead of lowering a severity (see [Guardrail pack](#guardrail-pack)).
|
|
116
120
|
|
|
@@ -121,12 +125,15 @@ The guardrail rules:
|
|
|
121
125
|
| `antelopejs/no-comments` | `//` and `/* */` comments. Allowed: TSDoc `/** */`, `SAFETY: <reason>` (one block, or a run of `//` lines), `/*!` license headers, `@ts-expect-error <reason>`, oxlint/eslint directives that name their rules, `/// <reference />`, `#__PURE__`/`@__PURE__`, `@vite-ignore` and webpack magic comments, `prettier-ignore`/`oxfmt-ignore` |
|
|
122
126
|
| `antelopejs/no-inherited-key-lookup` | `table[key]` (or `table[key] += ...`) with a computed key, or `key in table`, where `table` is declared in the same file as a string-keyed dictionary (`Record<string, V>`, `Record<PropertyKey, V>`, a string index signature, `Readonly`/`Partial` of one, a union with `undefined` or `null`, a local alias or `typeof` another table, `satisfies` or `as Record<string, V>`, a class field read as `this.field[key]`), or an untyped object literal read with an asserted key (`table[key as keyof typeof table]`). Inherited keys such as `constructor` answer `Object.prototype` members. Not reported: literal keys, `typeof x` keys, same-file `const` keys (`KEY`, `LABELS.name` of a literal-valued object), keys iterated from an array of string literals or from `Object.keys(table)`, `Object.entries(table)` or `for...in` of the same table (through `filter`, `sort` and similar), writes and `delete`, a read in a function that calls `Object.hasOwn(table, key)` or `hasOwnProperty`, null-prototype tables (`Object.create(null)`, `{ __proto__: null }`). Imported constants and keys iterated from another table are reported. Use a `Map` instead |
|
|
123
127
|
| `antelopejs/no-presence-only-type-guard` | in a type predicate or assertion function narrowing `x`: `x in table` (also true for inherited keys; use `Object.hasOwn(table, x)` or a `Map`/`Set`); `"k" in x`, `Object.hasOwn(x, "k")`, `hasOwnProperty.call(x, "k")` or `Reflect.has(x, "k")` with no read of `x.k` (presence only; check the value; a read through a cast such as `(x as T).k` or `(<T>x).k` counts); a member of a type declared in the same file that the guard never reads. Members typed `unknown` and parameters typed as a union of object types (`pet: Cat \| Dog`, a discriminating `in`) are not reported, and a call to another local guard with `x` counts as checking that guard's members |
|
|
128
|
+
| `antelopejs/require-tsconfig-include` | a file type-aware lint reads that no `tsconfig.json` or `jsconfig.json` lists: not the nearest one, not a config it references, not one above. `oxlint-tsgolint` reads such a file in its inferred program, without the repository's compiler options or `types`, so Node and test-runner globals are error types: `typescript/no-unsafe-*` reports there are false, and findings that need those types go missing. List the file in a tsconfig that names its `types`: one beside it that extends the root tsconfig, or, for a file at the root, a composite tsconfig (`emitDeclarationOnly`, `outDir` under `node_modules/.cache`) that the root tsconfig references, which `tsc -p .` leaves unbuilt. The root `oxlint.config.ts`, `oxfmt.config.ts` and `knip.config.ts` that `antelopejs-sync` writes are exempt. On only with type-aware lint |
|
|
124
129
|
| `antelopejs/no-fs-read-in-tests` | `readFileSync` or `readdirSync` from `fs` in a test file. Files under `fixtures/`, `helpers/` and `locales/` may read |
|
|
125
130
|
| `antelopejs/no-self-import-in-tests` | a test file that imports its own package name (`@antelopejs/<self>`, a subpath, `require`, dynamic `import()` or a re-export; `import type` is fine) unless that resolves to local code: the `exports` map publishes the subpath and `node_modules/<name>` is a link back to the package (a workspace self-link such as `link:.`). Otherwise the import resolves to the installed published copy and the test never runs local code. Import the module by relative path instead |
|
|
126
131
|
| `antelopejs/require-assertion` | a test with no assertion. Counts: calls named `expect*` or `assert*`, `sinon.assert.*`, supertest `.expect(...)`, and should-style `x.should…` or `should(x)` |
|
|
127
132
|
| `antelopejs/no-constant-value-assertion` | `expect(X).toBe(literal)` where the root of `X` is an UPPER_SNAKE constant (`MAX_ITEMS`, `NAMES.if`, not `process.env.NODE_ENV`); also `.toEqual`, `.to.equal`, `.to.eq`, `.eql` and synonyms |
|
|
128
133
|
| `antelopejs/no-typeof-function-only-test` | a test whose only assertions are `toBeTypeOf("function")`, `to.be.a("function")` or equivalents |
|
|
129
134
|
|
|
135
|
+
`antelopejs/no-presence-only-type-guard` passes `x in table` when `x` is typed `` `prefix${string}` `` and no `Object.prototype` member starts with that prefix, because such a key cannot name an inherited member. The prefix is read as TypeScript reads it, so `\x63onstructor${string}` is `constructor${string}` and stays reported.
|
|
136
|
+
|
|
130
137
|
Test files are `*.test.*`, `*.spec.*`, and files under `test/`, `tests/` and `__tests__/`, whatever the framework. The preset keeps four framework-neutral Jest-plugin rules: `no-disabled-tests`, `no-focused-tests`, `valid-describe-callback` and `valid-title`.
|
|
131
138
|
|
|
132
139
|
Import sorting is off because it moves value imports across side-effect imports, and in an AntelopeJS module `import "./components"` is what registers the decorated classes. Turn it on only where import order does not matter.
|
|
@@ -183,10 +190,10 @@ pnpm install
|
|
|
183
190
|
| `README.md` of each `@antelopejs` package | Writes the generated compatibility block (see [Generated compatibility block](./docs/documentation-checks.md#generated-compatibility-block)); prose outside its markers stays |
|
|
184
191
|
| `CLAUDE.md` | `@AGENTS.md` |
|
|
185
192
|
| `guardrails.ratchet.json` | Records non-empty debt on first adoption, before `sync:check` exists |
|
|
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
|
|
193
|
+
| `guardrails.suppressions.json` | Records the current suppression counts when the file is missing; restores the committed file instead when HEAD has one; otherwise only adds `config` and `agentFiles` at today's counts when the file predates them |
|
|
187
194
|
| `<layer>/build/backend-boundary.ts` | Where a DMS frontend layer tracks one, restores the pack's backend boundary plugin for the package that holds the layer. A formatter's rewrite is not drift; any other edit is |
|
|
188
195
|
|
|
189
|
-
`--profile template` writes only the three preset configs
|
|
196
|
+
`--profile template` writes only the three preset configs, a user-facing `AGENTS.md` block and the `suppressions` package scripts (plus `ratchet` once `guardrails.ratchet.json` exists) that `antelopejs-checks` requires, for template repositories. `antelopejs-sync --check` writes nothing and exits 1 on any drift; `pnpm run checks` runs it.
|
|
190
197
|
|
|
191
198
|
`pnpm run checks` runs `typecheck`, `lint`, `format:check`, `knip`, `test`, `size`, `suppressions` and `sync:check`, plus `ratchet` when `guardrails.ratchet.json` exists. It prints only the output of the steps that failed. Sync adds the ratchet scripts and pre-commit hook only while that file exists.
|
|
192
199
|
|
|
@@ -205,8 +212,9 @@ pnpm install
|
|
|
205
212
|
- A rule listed under `rules` is off for `oxlint`, so editors, hooks and `lint` stay green. `antelopejs-ratchet` counts it with every rule on, and fails when a count rises. It prints the findings in the files the change touched.
|
|
206
213
|
- A file listed under `oversizeFiles` may exceed 20,000 bytes and `max-lines`, up to its recorded size. Any other file over either limit fails. When git sees a listed file renamed (`git mv`, or a staged delete and add), the allowance moves to the new path and never exceeds the old one; a copy or a new file inherits nothing. `antelopejs-ratchet --base <ref>` detects renames against that revision instead of `HEAD`, for a rename that was committed before the file was updated.
|
|
207
214
|
- The pre-commit hook runs `antelopejs-ratchet --staged`: for each rule under `rules` it counts the findings in the staged files and in those files at HEAD and at the merge-base of HEAD with the pull request base (`origin/$GITHUB_BASE_REF`, else `origin/HEAD`), rename sources and deleted files included, linted under the staged configuration. A merge-base finding counts only for a staged finding of the same rule on the same line, unchanged since the merge-base, and only while the files the branch changed hold no more findings of that rule than at the merge-base. It fails a rule whose staged count is above both, and lists the findings on lines that differ from HEAD and from the merge-base. Code moved between staged files, a legacy line that is reformatted or edited, a line restored byte for byte to its base form, a `SAFETY:` comment the branch added and the commit removes, or an edit of a file a legacy finding moved into earlier on the branch, nets out; a new finding does not, even next to a moved block. Locally the base is always `origin/HEAD`, so a branch stacked on another branch is compared with HEAD and the default branch, not with its parent branch. Without `origin/HEAD` (`git remote set-head origin --auto` sets it) or a merge-base, it compares with HEAD only and says so when it fails.
|
|
208
|
-
- `antelopejs-ratchet --
|
|
209
|
-
-
|
|
215
|
+
- With `APPROVED_RAISES="<rule>=<max> ..."` in the environment, `antelopejs-ratchet --staged` accepts the findings of exactly those rules while this commit raises the rule's ceiling in the staged `guardrails.ratchet.json` above HEAD's, to exactly `<max>`, and the commit holds at most `<max>` findings of it, counted from a checkout of the index, so ignore files and a file whose working copy differs cannot hide it; the commit is refused while any tracked file is `skip-worktree` (a sparse checkout) or `assume-unchanged`, because those files can differ from the index unseen. The variable is split on space and tab only, so a non-breaking space or a newline makes it malformed. The count takes the higher of a checkout of the index and the working tree for each rule, so generated types that only the working tree has are not lost, and an untracked file with a finding still counts. When the commit also stages a code file, a raised ceiling for a rule the variable does not list is refused too. A commit that stages only `guardrails.ratchet.json` skips the hook through its glob, as it does without the variable, and the CI gate refuses that raise. `<max>` is what `antelopejs-ratchet` measures, the same as the CI gate: files it does not measure (a force-added gitignored file, a file under a gitignored path, a nested lint config, a non-UTF-8 file name) do not count, and a stale or partial build can change a type-aware count. The `oxlint` preset ignores the variable: it already turns off the rules in the ceiling file, and the approved commit writes that ceiling. Each accepted raise is printed as `APPROVED RAISE ACCEPTED`. A rule the variable does not list, a ceiling that is not raised to `<max>`, a count above `<max>`, tracked files with unstaged changes and a malformed variable (a bare rule, a non-numeric max, a rule listed twice) are refused, and with the variable unset nothing changes. The variable is the operator's approval: it does not make CI accept the raise.
|
|
216
|
+
- `antelopejs-ratchet --update` lowers each number to the current count and removes what reached zero. It never raises a number. The only entries it adds are rules a pack release enabled after the release recorded under `pack`: `PACK_NEW_RULES` in `src/guardrails/adoption.ts` lists each such rule with the release that enabled it. After a pack upgrade, the update records today's count of each one that has findings, then moves `pack` forward, so a rule fixed to zero and later broken again is never adopted twice. Without `pack`, the repository's adopted release is the pack its lockfile installs at the pull request base (pnpm or npm), and an unknown one predates every listed rule. A clean repository with findings for such a rule gets a ratchet file holding only those rules; run `antelopejs-sync` afterwards for the ratchet scripts and hook. Commit the file. The same update records the size of each oversize file under the agent directories (`.agents/`, `.claude/`, `.amp/` and the others) that has no allowance, once, in a repository whose adopted release predates 0.2.18, the release that began counting the repository's own files there; `antelopejs-ratchet --base` accepts those allowances for files that exist at the base, at no more than their size there, and no other.
|
|
217
|
+
- Against the pull request base (`GITHUB_BASE_REF` in CI, else `origin/HEAD`, or `--base <ref>`), `antelopejs-ratchet` fails an entry added or raised by hand: a rule the pack did not newly enable, a pack-new rule above its count or above its count in the base tree, an oversize allowance for a file that is not a rename of one, and a lowered or dropped `pack`. A first adoption (no ratchet file and no suppression budget at the base) passes.
|
|
210
218
|
|
|
211
219
|
When every rule count is zero and `oversizeFiles` is empty, the ratchet is retired. `antelopejs-ratchet --update` deletes the file and asks you to run `antelopejs-sync`. Sync then removes `ratchet`, `ratchet:update`, the ratchet hook and the Debt instructions. Commit those changes together. An empty baseline on first adoption creates no file. Later syncs never recreate it because the `sync:check` script marks adoption.
|
|
212
220
|
|
|
@@ -228,6 +236,7 @@ When every rule count is zero and `oversizeFiles` is empty, the ratchet is retir
|
|
|
228
236
|
|
|
229
237
|
- `rules` holds lint directives (`oxlint-disable`, `eslint-disable`, their `-line` and `-next-line` forms, in line or block comments, after code too) per rule they name; a directive naming several rules counts once per rule, and one naming none counts under `*`. A rule missing from `rules` has ceiling 0. The other fields count `@ts-expect-error`, `@ts-ignore` and `SAFETY:` comments. The counter is the one behind the proof tables: it reads comments from the parser, so strings and template literals are never counted, and it skips generated output as the size guard does.
|
|
230
238
|
- `config` holds the rules a lint config switches off, to `allow` or to a warning, keyed `<rule> for <glob>`: in `oxlint.config.*`, `.oxlintrc.json`, `.oxlintrc.jsonc` and `eslint.config.*` at any depth, every `rules` and `categories` map (a category as `category:<name>`) and an ESLint composer's `overrideRules` argument, one key per glob of the block's `files` (`*` when it has none). A nested config's globs are anchored at its directory and its blocks without `files` are `<dir>/**`, so a rule-off moved between config files is a new key. Rule maps, severities and globs held in same-file variables or spread from them count where they are used; the pack's presets are not in the file, so they never count. A glob is a key of its own, so adding, widening or renaming a glob, deleting `files`, or moving an override's rules to the top level creates a key at ceiling 0 and fails. Narrowing or splitting a scope is burn-down: a key may use the room a same-rule key whose glob contains its glob gives up (`*`, `**` and `**/*` contain every glob; a single-segment `*` never contains `**`; other glob syntax counts only when equal), in the full, staged and base checks, and `--update` moves that ceiling to the narrower key. A scope split into several narrower globs gives each the old ceiling, so the `config` total can rise while the files it covers do not; read totals per key, not as a measure of scope. `.` and `..` segments count only when equal. A failure names the fix: delete the entry and fix the code its rule reports, or put the exception on the line that needs it as a directive with a reason. A config entry switching off a rule no directive may name fails as an added directive does. Sync adds `config` at today's counts to a budget that predates it; until then config rule-offs are not capped.
|
|
239
|
+
- `agentFiles` is `true` once the budget counts the repository's own files under the agent directories (`.agents/`, `.claude/`, `.amp/` and the others), skipping only what `antelopejs-sync` writes there, which is what lint skips. A budget without it counts none of them, so upgrading fails nothing: `antelopejs-sync` adds each key's count in those files to its ceiling and sets the field. `antelopejs-suppressions --base` allows that one rise on a base without the field, by no more than the count in those files at the base per key (a directive the same branch adds there is not adoptable), and fails a budget that drops the field once the base has it.
|
|
231
240
|
- `antelopejs-suppressions` fails when a count is above its ceiling, printing each `file:line` in the files the change touched and the fix: fix the code, or remove another suppression of the same kind; a rule that keeps needing suppressions should be changed in the preset. It prints nothing on success.
|
|
232
241
|
- `antelopejs-suppressions --update` lowers each ceiling to the current count and keeps rules at zero. No command raises a ceiling.
|
|
233
242
|
- `SAFETY:` comments and directives disabling `anti-slop/require-safety-comment-for-type-assertion` share their room: a `SAFETY:` comment may use what those directives leave below their ceiling, in the full, base and staged checks, and `--update` moves that room to `safety`. Replacing such a directive with a `SAFETY:` comment needs no raise; their sum never rises.
|
|
@@ -239,7 +248,7 @@ When every rule count is zero and `oversizeFiles` is empty, the ratchet is retir
|
|
|
239
248
|
|
|
240
249
|
### Size
|
|
241
250
|
|
|
242
|
-
`antelopejs-check-size` fails on an authored file over 20,000 bytes, tests included. Generated code (`dist`, `coverage`, `.nuxt`, `.output`, and `build` or `output` at the repository root or a package root, never under `src/` or `test/`), fixtures, lockfiles, `CHANGELOG.md`, Markdown and binary assets are excluded. JSON is data, never code: every `*.json`, `*.jsonc` and `*.json5` file is excluded, wherever it lives. Lint and format still cover it. Files over the limit with a NUL byte in their first 8,000 bytes are binary even without a known extension. Staged checks inspect the index blob. Excluded files are also removed from recorded size allowances on ratchet update.
|
|
251
|
+
`antelopejs-check-size` fails on an authored file over 20,000 bytes, tests included. The repository's own files under the agent directories count; the files `antelopejs-sync` writes there (the `SYNCED_AGENT_PATTERNS` that lint skips) do not. Generated code (`dist`, `coverage`, `.nuxt`, `.output`, and `build` or `output` at the repository root or a package root, never under `src/` or `test/`), fixtures, lockfiles, `CHANGELOG.md`, Markdown and binary assets are excluded. JSON is data, never code: every `*.json`, `*.jsonc` and `*.json5` file is excluded, wherever it lives. Lint and format still cover it. Files over the limit with a NUL byte in their first 8,000 bytes are binary even without a known extension. Staged checks inspect the index blob. Excluded files are also removed from recorded size allowances on ratchet update.
|
|
243
252
|
|
|
244
253
|
Pass paths to check only those files, as the pre-commit hook does. The command also fails on an `oxlint-disable` or `eslint-disable` directive (line, next-line or file form) that names no rule: oxlint applies such a directive before any rule runs, so `no-comments` cannot report it. It reads real comments only, with the same counter as the proof tables, so directive text inside a string is not reported.
|
|
245
254
|
|
|
@@ -259,7 +268,7 @@ pnpm exec antelopejs-api-diff origin/main --allow-added '**/internal/**'
|
|
|
259
268
|
|
|
260
269
|
A DMS frontend module publishes more than its package entries: every export of a file under a directory its `dms.frontend.build.ts` passes to `registerAutoImports` is auto-imported into every frontend module, `@internal` or not, and the package itself is usually private. For each tracked `dms.frontend.build.ts`, the proof reads the declared directories (string literals only; anything else is an execution error naming the form to write), drops `app/build/` and directories outside the module as `@antelopejs/dms-frontend` does, and lists one `<name> (value|type): <signature>` line per auto-imported name under `Auto-imports:`. Names are read statically with the module's TypeScript, which resolves `export *` and the `#<layer>/*` aliases; no Vite build runs. Each scanned module is typed with the imports unimport would inject for the names it uses without importing them: dms-frontend's `templates/vue/frontend-module.ts` exports, `vue`'s exports and the module's own auto-imports. A composable returning `ref<T>()` or `useDmsState<T>()` therefore prints `T`, not `any`. Types re-exported from a `.vue` file, `@nuxt/ui` auto-imports and another module's auto-imports are not modelled and print as `any` on both sides. Values print their type, types their structure, both in the canonical member and union order of the declaration half, so moving an export between scanned files or changing an unexported helper passes. A removed, added or changed line fails, and `--allow-added` never applies to it: move a helper that must stay private under `app/build/`. Repositories without a `dms.frontend.build.ts` print no `Auto-imports:` line.
|
|
261
270
|
|
|
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
|
|
271
|
+
Both commands end with a table of suppressions in authored code files at the base and at HEAD, for PR bodies to copy: lint directives per rule they name (`*` for a directive naming none), `@ts-expect-error`, `@ts-ignore` and `SAFETY:` comments. The parser finds every comment, after code on the same line too, and skips strings, template literals and JSX text; `.vue` files contribute their script blocks and template comments. Generated output and the agent files `antelopejs-sync` writes are left out as the size guard leaves them out.
|
|
263
272
|
|
|
264
273
|
Both commands compare **committed HEAD**, not staged or working-tree edits. They check out the base and HEAD in temporary detached worktrees, reuse the current checkout's root and package `node_modules`, and remove the worktrees afterwards. Install the consumer's dependencies before running them.
|
|
265
274
|
|
package/dist/bin/api-diff.mjs
CHANGED
|
@@ -1,15 +1,15 @@
|
|
|
1
1
|
#!/usr/bin/env node
|
|
2
|
+
import { i as parseManifest, r as packageManager } from "../package-BRTjkzt5.mjs";
|
|
2
3
|
import { t as runCli } from "../cli-4Tv71vYk.mjs";
|
|
3
|
-
import {
|
|
4
|
-
import { i as
|
|
5
|
-
import { a as
|
|
6
|
-
import { a as outputRoot, i as loadTypeScript, n as isExportPath, o as packagesAt, r as isTestSource, s as unpublishedAt, t as emitPackage } from "../typescript-BmS5BmrS.mjs";
|
|
4
|
+
import { c as repositoryRoot, l as resolveRevision } from "../files-DJ0TeaTU.mjs";
|
|
5
|
+
import { a as DIRECTORY_LINK, c as revisionCounts, d as describeAllowance, f as fillStars, i as stampProof, l as allowedByGlob, o as compareRevisions, p as recordVerdict, u as createAddedPolicy } from "../proof-stamp-DDDC0J6l.mjs";
|
|
6
|
+
import { a as outputRoot, i as loadTypeScript, n as isExportPath, o as packagesAt, r as isTestSource, s as unpublishedAt, t as emitPackage } from "../typescript-CM0LrVP7.mjs";
|
|
7
7
|
import { createRequire } from "node:module";
|
|
8
8
|
import { copyFileSync, cpSync, existsSync, globSync, mkdirSync, readFileSync, readdirSync, rmSync, statSync, symlinkSync, writeFileSync } from "node:fs";
|
|
9
9
|
import { basename, dirname, isAbsolute, join, parse, posix, relative, resolve } from "node:path";
|
|
10
10
|
import { execFileSync, spawnSync } from "node:child_process";
|
|
11
|
-
import { parseArgs } from "node:util";
|
|
12
11
|
import { availableParallelism, freemem } from "node:os";
|
|
12
|
+
import { parseArgs } from "node:util";
|
|
13
13
|
//#region src/guardrails/auto-import-globals.ts
|
|
14
14
|
/** Where the generated Vite config takes the dms-frontend auto-imports from, relative to the `@antelopejs/dms-frontend` package. */
|
|
15
15
|
const FRONTEND_MODULE = join("node_modules", "@antelopejs", "dms-frontend", "templates", "vue", "frontend-module.ts");
|
|
@@ -502,7 +502,7 @@ const DESCRIBE = `
|
|
|
502
502
|
const { readFileSync, existsSync } = require("node:fs");
|
|
503
503
|
const { dirname, join, extname } = require("node:path");
|
|
504
504
|
const { pathToFileURL } = require("node:url");
|
|
505
|
-
const file = process.argv[
|
|
505
|
+
const file = process.argv[2];
|
|
506
506
|
let directory = dirname(file);
|
|
507
507
|
while (!existsSync(join(directory, "package.json")) && dirname(directory) !== directory) directory = dirname(directory);
|
|
508
508
|
const manifest = existsSync(join(directory, "package.json")) ? JSON.parse(readFileSync(join(directory, "package.json"), "utf8")) : {};
|
|
@@ -617,7 +617,7 @@ function childJson(args, cwd) {
|
|
|
617
617
|
if (result.status !== 0) throw new Error(result.stderr || `Runtime child exited with ${result.status ?? result.signal}.`);
|
|
618
618
|
return `${JSON.stringify(JSON.parse(result.stdout), null, 2)}\n`;
|
|
619
619
|
}
|
|
620
|
-
function buildPackage(directory, output, manifest) {
|
|
620
|
+
function buildPackage(directory, output, manifest, describe) {
|
|
621
621
|
const buildManifest = parseManifest(readFileSync(join(directory, "package.json"), "utf8"));
|
|
622
622
|
if (buildManifest.scripts?.build) execFileSync(packageManager(buildManifest), ["run", "build"], {
|
|
623
623
|
cwd: directory,
|
|
@@ -644,11 +644,7 @@ function buildPackage(directory, output, manifest) {
|
|
|
644
644
|
const { entries, skipped } = built;
|
|
645
645
|
for (const { entry, file } of entries) {
|
|
646
646
|
const destination = join(output, `${encodeURIComponent(entry)}.json`);
|
|
647
|
-
const metadata = childJson([
|
|
648
|
-
"-e",
|
|
649
|
-
DESCRIBE,
|
|
650
|
-
file
|
|
651
|
-
], directory);
|
|
647
|
+
const metadata = childJson([describe, file], directory);
|
|
652
648
|
mkdirSync(dirname(destination), { recursive: true });
|
|
653
649
|
writeFileSync(destination, metadata);
|
|
654
650
|
}
|
|
@@ -668,10 +664,13 @@ function runtimeDiff(root, baseRef, probe, policy) {
|
|
|
668
664
|
const packages = packagesAt(worktree, true);
|
|
669
665
|
const published = [];
|
|
670
666
|
let entries = 0;
|
|
667
|
+
mkdirSync(scratch, { recursive: true });
|
|
668
|
+
const describe = join(scratch, "describe.cjs");
|
|
669
|
+
writeFileSync(describe, DESCRIBE);
|
|
671
670
|
for (const { directory, manifest } of packages) {
|
|
672
671
|
const folder = encodeURIComponent(directory).replaceAll(".", "%2E");
|
|
673
672
|
try {
|
|
674
|
-
const built = buildPackage(join(worktree, directory), join(output, folder), manifest);
|
|
673
|
+
const built = buildPackage(join(worktree, directory), join(output, folder), manifest, describe);
|
|
675
674
|
if (built === void 0) skippedPackages.add(directory);
|
|
676
675
|
else {
|
|
677
676
|
entries += built.count;
|
|
@@ -692,7 +691,6 @@ function runtimeDiff(root, baseRef, probe, policy) {
|
|
|
692
691
|
force: true
|
|
693
692
|
});
|
|
694
693
|
if (probe !== void 0) {
|
|
695
|
-
mkdirSync(scratch, { recursive: true });
|
|
696
694
|
const script = join(scratch, "probe.cjs");
|
|
697
695
|
writeFileSync(script, probe);
|
|
698
696
|
writeFileSync(join(output, "probe.json"), childJson([script, worktree], worktree));
|
|
@@ -764,6 +762,15 @@ function entryPatterns(manifest) {
|
|
|
764
762
|
function targetPattern(target) {
|
|
765
763
|
return new RegExp(`^${target.split("*").map((part) => part.replace(/[.*+?^${}()|[\]\\]/gu, "\\$&")).join("(.*)")}$`, "u");
|
|
766
764
|
}
|
|
765
|
+
/** A published target outside the build output is no compiler emit; the package's own declaration at that path stands for it. */
|
|
766
|
+
function authoredDeclaration(directory, target, path, scratch) {
|
|
767
|
+
const source = resolve(directory, target);
|
|
768
|
+
if (!path.startsWith("../") || path.includes("*") || !existsSync(source)) return void 0;
|
|
769
|
+
const file = `.published/${relative(directory, source).split("\\").join("/")}`;
|
|
770
|
+
mkdirSync(dirname(join(scratch, file)), { recursive: true });
|
|
771
|
+
copyFileSync(source, join(scratch, file));
|
|
772
|
+
return file;
|
|
773
|
+
}
|
|
767
774
|
function publishedEntries(directory, manifest, emitted, scratch) {
|
|
768
775
|
const outputRoot = resolve(directory, emitted.options.outDir ?? ".");
|
|
769
776
|
const files = emitted.files.map((file) => relative(scratch, file).split("\\").join("/"));
|
|
@@ -777,6 +784,10 @@ function publishedEntries(directory, manifest, emitted, scratch) {
|
|
|
777
784
|
const path = relative(outputRoot, resolve(directory, target)).split("\\").join("/");
|
|
778
785
|
const pattern = targetPattern(path);
|
|
779
786
|
const found = files.filter((file) => pattern.test(file));
|
|
787
|
+
if (!found.length) {
|
|
788
|
+
const authored = authoredDeclaration(directory, target, path, scratch);
|
|
789
|
+
if (authored !== void 0) found.push(authored);
|
|
790
|
+
}
|
|
780
791
|
if (!found.length && !path.includes("*")) throw new Error(`${directory}: published target ${target} has no emitted declaration.`);
|
|
781
792
|
const matches = found.filter((file) => !isTestSource(outputRoot, join(outputRoot, file)));
|
|
782
793
|
if (matches.length < found.length) skipped.push(target);
|
package/dist/bin/body-check.mjs
CHANGED
|
@@ -1,8 +1,8 @@
|
|
|
1
1
|
#!/usr/bin/env node
|
|
2
2
|
import { t as runCli } from "../cli-4Tv71vYk.mjs";
|
|
3
|
-
import {
|
|
4
|
-
import { t as lintDiagnostics } from "../oxlint-
|
|
5
|
-
import { n as proofDigest, r as proofLines, s as revisionCountRows, t as parseProofStamp } from "../proof-stamp-
|
|
3
|
+
import { c as repositoryRoot, l as resolveRevision } from "../files-DJ0TeaTU.mjs";
|
|
4
|
+
import { t as lintDiagnostics } from "../oxlint-DIV-lLSS.mjs";
|
|
5
|
+
import { n as proofDigest, r as proofLines, s as revisionCountRows, t as parseProofStamp } from "../proof-stamp-DDDC0J6l.mjs";
|
|
6
6
|
import { readFileSync } from "node:fs";
|
|
7
7
|
import { spawnSync } from "node:child_process";
|
|
8
8
|
import { parseArgs } from "node:util";
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
export {}
|