@antelopejs/tooling-configs 0.0.8 → 0.2.0

package/README.md

@@ -1,41 +1,55 @@
 # @antelopejs/tooling-configs
 
 <div align="center">
-<a href="https://www.npmjs.com/package/@antelopejs/tooling-configs"><img alt="NPM version" src="https://img.shields.io/npm/v/@antelopejs/tooling-configs.svg?style=for-the-badge&labelColor=000000"></a>
-<a href="./LICENSE"><img alt="License" src="https://img.shields.io/npm/l/@antelopejs/tooling-configs.svg?style=for-the-badge&labelColor=000000"></a>
+<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>
+<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>
 <a href="https://discord.gg/sjK28QHrA7"><img src="https://img.shields.io/badge/Discord-18181B?logo=discord&style=for-the-badge&color=000000" alt="Discord"></a>
-<a href="https://antelopejs.com"><img src="https://img.shields.io/badge/Docs-18181B?style=for-the-badge&color=000000" alt="Documentation"></a>
 </div>
 
-Shared tooling presets for AntelopeJS repositories: [oxlint](https://oxc.rs) (including
-the vendored [anti-slop](https://github.com/dmmulroy/anti-slop) rules), [oxfmt](https://oxc.rs)
-and [Knip](https://knip.dev).
-
-Together they replace Biome outright — lint, format and import order — and Prettier in the
-Nuxt layers, since oxfmt formats `.vue` and sorts Tailwind classes natively. The front end
-keeps ESLint for linting, from a shared config here.
-
-## Requirements
-
-Node **24** (or at least 22.18). oxlint reads `oxlint.config.ts` and loads JS plugins by
-executing TypeScript, which earlier runtimes cannot do.
+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.
+
+- [oxlint](https://oxc.rs) and [oxfmt](https://oxc.rs) replace Biome: lint, format and Tailwind class sorting, `.vue` included.
+- ESLint stays for the Nuxt front ends, from a shared config, until oxlint lints `.vue` files.
+- [Knip](https://knip.dev) learns the entry points of an AntelopeJS module.
+- Every preset is a function: options adjust it without copying it.
+- `antelopejs-sync` writes the configs, hooks, scripts and agent instructions into a repository, and `antelopejs-sync --check` fails CI when they drift.
+- Every lint rule is an error or off. Existing debt is recorded per repository and may only shrink.
+
+## What's in the box
+
+| Export             | Import                                                                    | What it gives                                                               |
+| ------------------ | ------------------------------------------------------------------------- | --------------------------------------------------------------------------- |
+| `./oxc/lint`       | `import { antelopePreset } from "@antelopejs/tooling-configs/oxc/lint"`   | The oxlint preset                                                           |
+| `./oxc/fmt`        | `import { antelopeFmtPreset } from "@antelopejs/tooling-configs/oxc/fmt"` | The oxfmt preset (house style)                                              |
+| `./eslint`         | `import { antelopeNuxtConfig } from "@antelopejs/tooling-configs/eslint"` | ESLint for Nuxt layers                                                      |
+| `./knip`           | `import { antelopeKnipConfig } from "@antelopejs/tooling-configs/knip"`   | Knip for AntelopeJS modules                                                 |
+| `./oxc/anti-slop`  | Loaded by the oxlint preset as a JS plugin                                | The vendored [anti-slop](https://github.com/dmmulroy/anti-slop) rules       |
+| `./oxc/guardrails` | Loaded by the oxlint preset as a JS plugin                                | The `antelopejs` comment and test-quality rules                             |
+| bin                | `antelopejs-sync`                                                         | Writes the guardrail pack into a repository; `--check` reports drift        |
+| bin                | `antelopejs-checks`                                                       | Runs every check and prints only the failures                               |
+| bin                | `antelopejs-ratchet`                                                      | Fails when recorded debt grows; `--update` lowers the record                |
+| bin                | `antelopejs-check-size`                                                   | Fails on authored files over 20,000 bytes and on blanket disable directives |
+| bin                | `antelopejs-check-interface-ranges`                                       | Fails on interface ranges that break module startup                         |
 
 ## Install
 
+Node.js 24, or at least 22.18: oxlint reads `oxlint.config.ts` and loads JS plugins by executing TypeScript.
+
 ```bash
-pnpm add -D oxlint@1.81.0 oxfmt @antelopejs/tooling-configs
+pnpm add -D @antelopejs/tooling-configs oxlint@1.81.0 oxfmt
 ```
 
-Add `eslint-plugin-perfectionist` too unless you turn import sorting off — it is an
-optional peer dependency because it pulls ESLint and typescript-eslint along with it:
+The tools are optional peer dependencies, so add only the ones a repository uses:
 
-```bash
-pnpm add -D eslint-plugin-perfectionist
-```
+| Tool                    | Packages to add                                                                  |
+| ----------------------- | -------------------------------------------------------------------------------- |
+| oxlint                  | `oxlint@1.81.0`, plus `oxlint-tsgolint` for the type-aware rules (on by default) |
+| oxfmt                   | `oxfmt@^0.66.0`                                                                  |
+| ESLint                  | `@nuxt/eslint-config`                                                            |
+| Knip                    | `knip@>=6`                                                                       |
+| Import sorting (opt-in) | `eslint-plugin-perfectionist`                                                    |
 
-Pin `oxlint` to the exact version this package depends on for `@oxlint/plugins`
-(currently **1.81.0**). The JS plugin API is still alpha and the two packages must move
-together.
+Pin `oxlint` to the exact version this package uses for `@oxlint/plugins` (currently **1.81.0**): the JS plugin API is still alpha and the two must move together.
 
 ## oxlint
 
@@ -46,7 +60,7 @@ import { antelopePreset } from "@antelopejs/tooling-configs/oxc/lint";
 
 export default defineConfig({
   extends: [antelopePreset()],
-  // Only read from the root config, never from a preset.
+  // oxlint reads this field only from the root config, never from a preset.
   options: { typeAware: true },
 });
 ```
@@ -61,50 +75,54 @@ export default defineConfig({
 }
 ```
 
-Type-aware rules (`typescript/no-floating-promises`) also need the tsgolint binary:
+### What the preset turns on
 
-```bash
-pnpm add -D oxlint-tsgolint
-```
+| Group          | Rules                                                                                                                                                                                                             | Default |
+| -------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------- |
+| 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` | error   |
+| Imports        | `import/no-cycle`, `import/no-self-import`, `import/no-duplicates`                                                                                                                                                | error   |
+| Type-aware     | `typescript/no-floating-promises` and eight more type-aware rules                                                                                                                                                 | error   |
+| Complexity     | `max-params` 5, `max-lines-per-function` 120, `max-lines` 500, `max-depth` 4, `complexity` 20                                                                                                                     | error   |
+| Anti-slop      | all 15 vendored rules                                                                                                                                                                                             | error   |
+| Guardrails     | `antelopejs/no-comments`; in test files `antelopejs/no-fs-read-in-tests`, `antelopejs/no-constant-value-assertion`, `antelopejs/no-typeof-function-only-test` and `antelopejs/require-assertion`                  | error   |
+| Import sorting | `perfectionist/sort-imports`, autofixed by `oxlint --fix`                                                                                                                                                         | off     |
 
-### What the preset turns on
+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)).
+
+The guardrail rules:
+
+| Rule                                      | Fails on                                                                                                                                                                                                                                                                                                                                  |
+| ----------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `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` |
+| `antelopejs/no-fs-read-in-tests`          | `readFileSync` or `readdirSync` from `fs` in a test file. Files under `fixtures/`, `helpers/` and `locales/` may read                                                                                                                                                                                                                     |
+| `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)`                                                                                                                                                                             |
+| `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                                                                                                                                             |
+| `antelopejs/no-typeof-function-only-test` | a test whose only assertions are `toBeTypeOf("function")`, `to.be.a("function")` or equivalents                                                                                                                                                                                                                                           |
+
+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`.
 
-| Group          | Contents                                                                                                    |
-| -------------- | ----------------------------------------------------------------------------------------------------------- |
-| oxc defaults   | the `correctness` category, plus the `eslint`, `typescript`, `node`, `oxc`, `import` and `promise` plugins  |
-| imports        | `import/no-cycle`, `import/no-self-import`, `import/no-duplicates` as errors                                |
-|                | (a repository with existing cycles starts with `importCycles: "warn"`)                                      |
-| import sorting | `perfectionist/sort-imports`, autofixed by `oxlint --fix`                                                   |
-| complexity     | `max-params` 5, `max-lines-per-function` 120, `max-lines` 500, `max-depth` 4, `complexity` 20 — as warnings |
-| anti-slop      | all 15 generic rules, as warnings                                                                           |
-| type-aware     | `typescript/no-floating-promises` as an error                                                               |
+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.
 
 ### Options
 
 ```ts
 antelopePreset({
-  antiSlop: "error", // "warn" (default) | "error" | false
-  importCycles: "warn", // "error" (default) | "warn" | false
+  antiSlop: false, // true (default)
+  guardrails: false, // true (default)
+  importCycles: false, // true (default)
   complexity: { maxParams: 8 }, // override thresholds, or false
-  importSorting: false, // leave imports alone
-  typeAware: false, // no tsgolint in this repository
+  importSorting: true, // false (default); needs eslint-plugin-perfectionist
+  typeAware: false, // true (default); false when the repository has no oxlint-tsgolint
 });
 ```
 
-`correctness` is raised to error deliberately. oxlint reports it as warnings, and warnings
-do not fail the command — a preset that left it alone could never fail a pipeline, while
-Biome was failing the build on the same rules.
+### Add ignore patterns
 
-`antiSlop` and `complexity` default to warnings on purpose: a repository adopting them
-has findings to work through, and a red pipeline on day one teaches the team to ignore
-the pipeline. Raise them to `"error"` once the backlog is clear.
-
-### Adding your own ignore patterns
-
-oxlint does not merge `ignorePatterns` across `extends`. A root config that declares its
-own **replaces** the preset's, so spread them:
+oxlint does not merge `ignorePatterns` across `extends`: a root config that declares its own replaces the preset's. Spread the shared ones:
 
 ```ts
+// oxlint.config.ts
+import { defineConfig } from "oxlint";
 import {
   ANTELOPE_IGNORE_PATTERNS,
   antelopePreset,
@@ -116,6 +134,50 @@ export default defineConfig({
 });
 ```
 
+## Guardrail pack
+
+Run `antelopejs-sync` at the repository root, then install dependencies. It is idempotent: a second run changes nothing.
+
+```bash
+pnpm add -D @antelopejs/tooling-configs oxlint@1.81.0 oxlint-tsgolint oxfmt
+pnpm exec antelopejs-sync
+pnpm install
+```
+
+| File                                                    | What `sync` does                                                                                                                                                                                      |
+| ------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `oxlint.config.ts`, `oxfmt.config.ts`, `knip.config.ts` | Writes a config that extends the preset, unless the file already imports it                                                                                                                           |
+| `lefthook.yml`                                          | Pre-commit on staged files: oxfmt, oxlint, size. Pre-push: typecheck                                                                                                                                  |
+| `package.json`                                          | `prepare` installs lefthook. Sets `checks`, `size`, `ratchet`, `ratchet:update`, `sync`, `sync:check`; adds missing `typecheck`, `lint`, `format`, `format:check`, `knip`; adds `lefthook` and `knip` |
+| `.nvmrc`                                                | `24`                                                                                                                                                                                                  |
+| `.agents/setup`                                         | Orb setup: switches to the `.nvmrc` Node, activates `packageManager` through corepack, installs with the frozen lockfile                                                                              |
+| `AGENTS.md`                                             | Writes the managed block between `<!-- antelopejs-guardrails:start -->` and `:end -->`; text outside the markers stays                                                                                |
+| `CLAUDE.md`                                             | `@AGENTS.md`                                                                                                                                                                                          |
+| `guardrails.ratchet.json`                               | Records the current findings, once, when the file is missing                                                                                                                                          |
+
+`--profile template` writes only the three preset configs and a user-facing `AGENTS.md` block, for template repositories. `antelopejs-sync --check` writes nothing and exits 1 on any drift; `pnpm run checks` runs it.
+
+`pnpm run checks` runs `typecheck`, `lint`, `format:check`, `knip`, `test`, `size`, `ratchet` and `sync:check`, and prints only the output of the steps that failed.
+
+### Ratchet
+
+`guardrails.ratchet.json` holds the debt a repository had when it adopted the pack:
+
+```json
+{
+  "rules": { "antelopejs/no-comments": 22, "eslint/max-depth": 1 },
+  "oversizeFiles": { "src/legacy.ts": 31250 }
+}
+```
+
+- 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.
+- 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.
+- `antelopejs-ratchet --update` lowers each number to the current count and removes what reached zero. It never raises a number or adds an entry. Commit the lowered file.
+
+### Size
+
+`antelopejs-check-size` fails on an authored file over 20,000 bytes, tests included. Generated code, fixtures, lockfiles, `CHANGELOG.md`, Markdown and binary assets are excluded. Pass paths to check only those files, as the pre-commit hook does. It 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.
+
 ## oxfmt
 
 ```ts
@@ -135,55 +197,23 @@ export default antelopeFmtPreset();
 }
 ```
 
-### The house style
-
-| Option                 | Value      |
-| ---------------------- | ---------- |
-| `printWidth`           | 80         |
-| `tabWidth` / `useTabs` | 2 / spaces |
-| `semi`                 | true       |
-| `singleQuote`          | false      |
-| `trailingComma`        | `"all"`    |
-
-Every field is set explicitly, including those that already match oxfmt's defaults.
-Repositories carry `.editorconfig` files that contradict each other — five declare tabs,
-two declare spaces, which is why the codebases drifted apart in the first place — and
-oxfmt falls back to `.editorconfig` for any field a config leaves unset. Stating all of
-them is what makes the style identical everywhere. Fix the repository's `.editorconfig`
-to match anyway, so editors agree with the formatter.
-
-Import order is not part of it: `perfectionist/sort-imports` owns that on the lint side.
-Enabling oxfmt's `sortImports` as well would have two tools sorting the same imports
-differently, each undoing the other on every save.
-
-The preset also leaves `CHANGELOG.md` alone. changelogen writes it during a release and
-the release commit lands unformatted, so checking it would turn the default branch red
-after every release with a breaking change.
+The house style sets every field, so `.editorconfig` files cannot override it: `printWidth` 80, 2 spaces, semicolons, double quotes, `trailingComma: "all"`. Fix the repository's `.editorconfig` to match anyway, so editors agree with the formatter.
 
-Extra ignores are **added** to the shared ones rather than replacing them, so a repository
-adopting oxfmt in stages can park a directory without losing the rest:
-
-```ts
-export default antelopeFmtPreset({ ignorePatterns: ["frontend-vue/**"] });
-```
-
-In a front end, pass the theme stylesheet to replace `prettier-plugin-tailwindcss`:
+The preset leaves import order to the linter and ignores `CHANGELOG.md`, which changelogen writes unformatted on every release. Other options of oxfmt pass through. Two are specific:
 
 ```ts
+// oxfmt.config.ts
 export default antelopeFmtPreset({
-  tailwindStylesheet: "./assets/css/main.css",
+  ignorePatterns: ["frontend-vue/**"], // added to the shared ignores, not replacing them
+  tailwindStylesheet: "./assets/css/main.css", // sorts Tailwind classes, replacing prettier-plugin-tailwindcss
 });
 ```
 
-### Replacing Biome
+### Replace Biome
 
-Per repository: delete `biome.json` and the `@biomejs/biome` dependency, point `lint`,
-`lint:fix` and `format` at oxlint and oxfmt, and port anything the Biome config carried
-that the preset does not (`noRestrictedImports` guards become `import/no-cycle`). Reformat
-in its own commit and record it in `.git-blame-ignore-revs`, which GitHub honours, so the
-pass does not bury the history.
+Delete `biome.json` and the `@biomejs/biome` dependency, point `lint`, `lint:fix` and `format` at oxlint and oxfmt, and port what the Biome config carried that the preset does not. Reformat in its own commit and list it in `.git-blame-ignore-revs`, which GitHub honours.
 
-## ESLint (front ends)
+## ESLint (Nuxt front ends)
 
 oxlint does not lint `.vue` files yet, so the front end stays on ESLint:
 
@@ -194,15 +224,7 @@ import { antelopeNuxtConfig } from "@antelopejs/tooling-configs/eslint";
 export default antelopeNuxtConfig({ dirs: ["./playground"] });
 ```
 
-`@nuxt/eslint` supplies the Vue and TypeScript rules; the preset only records where
-AntelopeJS layers differ from it — single-word page components, `any` and `{}` as
-load-bearing types in the interface layer, `_`-prefixed unused bindings, and import order
-left to the formatter.
-
-Formatting rules are deliberately absent, `vue/max-attributes-per-line` included: oxfmt
-formats `.vue`, and a lint rule that also reflows markup would fight it on every save.
-Declare `@nuxt/eslint-config` explicitly — nine layers use it today through
-`@nuxt/eslint` without declaring it.
+`@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`.
 
 ## Knip
 
@@ -213,39 +235,25 @@ import { antelopeKnipConfig } from "@antelopejs/tooling-configs/knip";
 export default antelopeKnipConfig();
 ```
 
-The defaults declare what Knip cannot infer for an AntelopeJS module: the interface
-subpaths as public API, and `src/test/**` plus a root `antelope.test.ts` as entry points,
-since `ajs module test` is not a runner Knip has a plugin for. Without them, Knip reports
-the whole test suite as dead code.
+The defaults declare what Knip cannot infer for an AntelopeJS module:
 
-`src/index.ts` is not among them on purpose: Knip already maps the `main`/`bin` of
-package.json (`dist/index.js`) back onto `src/index.ts`, ahead of the `dist/**` ignore, so
-repeating it only earns a "redundant pattern" hint.
+- entry points: `src/interfaces/**/*.ts` (public API), `src/test/**` and `antelope.test.ts` (run by `ajs module test`), and `scripts/**`;
+- ignored: `dist/**`, `playground/**`, `.antelope/**`, and the `@antelopejs/*` dependencies, which the runtime loads by name.
 
-The front end is left out of `project` rather than ignored, so a repository that wants
-`frontend-vue/` analysed can add it under Knip's `workspaces` without the preset
-overriding the choice.
+`entry`, `project`, `ignore`, `ignoreDependencies` and `ignoreBinaries` options are appended to the defaults. `frontend-vue/` stays out of `project`, so a repository can opt it in through Knip's `workspaces`.
 
 ## Interface ranges
 
-`@antelopejs/core` keeps one copy of each `@antelopejs/interface-*` package at startup, the
-one its implementing module installed, and refuses to start when a loaded module declares a
-range that copy falls outside. An exact pin (`0.1.7`) or a 0.x caret (`^0.1.2` stops at
-`0.2.0`) therefore breaks a module's startup at the next interface release, with no change to
-the module.
+`@antelopejs/core` keeps one copy of each `@antelopejs/interface-*` package, the one its implementing module installed, and refuses to start when a module declares a range that copy falls outside. An exact pin (`0.1.7`) or a 0.x caret (`^0.1.2` stops at `0.2.0`) therefore breaks startup at the next interface release.
 
-`antelopejs-check-interface-ranges` fails on such a range in `dependencies` or
-`optionalDependencies`, in every `package.json` git tracks in the repository (playgrounds and
-front-end layers included), whatever directory it runs from:
+`antelopejs-check-interface-ranges` fails on such a range in `dependencies` or `optionalDependencies`, in every `package.json` git tracks in the repository, from any directory:
 
 | The package…                                      | must declare                                 |
 | ------------------------------------------------- | -------------------------------------------- |
 | consumes the interface                            | `>=<floor> <1.0.0` (`<next major>` from 1.0) |
 | implements it (listed in `antelopeJs.implements`) | `>=<floor> <0.<minor + 1>.0` while it is 0.x |
 
-An implementer is the opposite case on purpose: it must never be handed a breaking minor it
-does not implement. When the implemented interface sits in the same repository, its version is
-the floor to use. `workspace:`, `file:` and `link:` specs are left alone.
+An implementer must never be handed a breaking minor it does not implement. `workspace:`, `file:` and `link:` specs are skipped. Pass paths to check only those manifests.
 
 ```jsonc
 // package.json
@@ -256,12 +264,23 @@ the floor to use. `workspace:`, `file:` and `link:` specs are left alone.
 }
 ```
 
-Pass paths to check only those manifests.
-
 ## Vendored anti-slop
 
-`src/oxc/anti-slop/` is a copy of upstream, kept byte-identical so it can be diffed
-against new releases. See `src/oxc/anti-slop/VENDORED.md` for the commit it came from and
-any local edits. It is excluded from this repository's own formatting and linting.
+`src/oxc/anti-slop/` is a byte-identical copy of upstream, so it can be diffed against new releases; `src/oxc/anti-slop/VENDORED.md` records the commit and any local edit. This repository does not format or lint it. Upstream is MIT (`src/oxc/anti-slop/LICENSE`).
+
+## Documentation guardrail
+
+The [documentation action](./docs/documentation-checks.md) checks local Markdown
+links and explicitly labeled compatibility tables. Consumers can also opt in
+complete TypeScript examples and reference-page export coverage. Pin
+`AntelopeJS/tooling-configs/actions/docs` to a full commit SHA; no npm release is
+required. The guide includes CI and local commands, annotation syntax, and the
+checks that remain the author's responsibility.
+
+## Contributing
+
+See [CONTRIBUTING.md](./CONTRIBUTING.md). `pnpm install`, then `pnpm checks` runs the typecheck, lint, format check, tests, size check and ratchet.
+
+## License
 
-Upstream is MIT (`src/oxc/anti-slop/LICENSE`); the rest of this repository is Apache-2.0.
+[Apache-2.0](./LICENSE), except the vendored anti-slop rules (MIT).

package/dist/bin/check-interface-ranges.mjs

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
-import { execFileSync } from "node:child_process";
 import { readFileSync } from "node:fs";
 import { join, relative } from "node:path";
+import { execFileSync } from "node:child_process";
 //#region src/interface-ranges.ts
 /**
 * At startup `@antelopejs/core` keeps one copy of each interface package, the
@@ -18,11 +18,13 @@ import { join, relative } from "node:path";
 * is 0.x.
 */
 const INTERFACE_PACKAGE_PREFIX = "@antelopejs/interface-";
+/** A module's own interface linked from the workspace is the copy it builds against, not a release it resolves. */
 const LOCAL_SPEC_PREFIXES = [
 	"workspace:",
 	"file:",
 	"link:"
 ];
+/** The fields `@antelopejs/core` checks at startup. */
 const CHECKED_FIELDS = ["dependencies", "optionalDependencies"];
 const BOUNDED_RANGE = /^>=(\d+)\.(\d+)\.(\d+) <(\d+)\.(\d+)\.(\d+)$/;
 const SINGLE_VERSION = /^[\^~=]?v?(\d+)\.(\d+)\.(\d+)$/;
@@ -66,6 +68,7 @@ function readFloor(spec) {
 function compareVersions(a, b) {
 	return a[0] - b[0] || a[1] - b[1] || a[2] - b[2];
 }
+/** A range is accepted when it is bounded for its role and admits the interface this package builds against. */
 function isAcceptedRange(spec, role, local) {
 	const bounded = BOUNDED_RANGE.exec(spec);
 	if (!bounded) return false;
@@ -109,6 +112,12 @@ function describeViolation(violation) {
 }
 //#endregion
 //#region src/bin/check-interface-ranges.ts
+/**
+* Every manifest in the repository by default, whatever directory the lint
+* runs from: playgrounds and front-end layers are loaded by the runtime too, a
+* playground is where a stale interface range first broke a startup, and an
+* implemented interface usually sits in a sibling package.
+*/
 function trackedManifests() {
 	const git = (args) => execFileSync("git", args, { encoding: "utf8" }).trim();
 	const root = git(["rev-parse", "--show-toplevel"]);

package/dist/bin/check-size.d.mts

@@ -0,0 +1 @@
+export {}

package/dist/bin/check-size.mjs

@@ -0,0 +1,51 @@
+#!/usr/bin/env node
+import { a as repositoryRoot, i as repositoryPath, o as runCli, t as authoredSizes } from "../files-BSl0U8lT.mjs";
+import { t as checkSize } from "../size-DRCgYCLA.mjs";
+import { existsSync, readFileSync } from "node:fs";
+import { join, resolve } from "node:path";
+import { spawnSync } from "node:child_process";
+import { parseArgs } from "node:util";
+//#region src/guardrails/directives.ts
+const CODE_FILE = /\.(?:[cm]?[jt]sx?|vue)$/u;
+const BLANKET_DISABLE = /(?:\/\*|\/\/)\s*((?:eslint|oxlint)-disable(?:-line|-next-line)?)\s*(?:--[^\n]*?)?(?:\*\/|$)/gmu;
+function fileText(root, file, staged) {
+	if (!staged) {
+		const path = join(root, file);
+		return existsSync(path) ? readFileSync(path, "utf8") : "";
+	}
+	const result = spawnSync("git", ["show", `:${file}`], {
+		cwd: root,
+		encoding: "utf8",
+		maxBuffer: 67108864
+	});
+	if (result.error) throw result.error;
+	return result.status === 0 ? result.stdout : "";
+}
+/** Reports disable directives without a rule list: oxlint honours them before any rule runs, so they also silence no-comments. */
+function checkBlanketDisables(root, files, staged = false) {
+	const failures = [];
+	for (const file of authoredSizes(root, files, staged).keys()) {
+		if (!CODE_FILE.test(file)) continue;
+		const text = fileText(root, file, staged);
+		for (const match of text.matchAll(BLANKET_DISABLE)) {
+			const line = text.slice(0, match.index).split("\n").length;
+			failures.push(`${file}:${line}: \`${match[1]}\` without a rule list disables every rule, the comment ban included. Name the rule(s) and give a reason, for example: oxlint-disable-next-line no-debugger -- debugging this operation.`);
+		}
+	}
+	return failures;
+}
+//#endregion
+//#region src/bin/check-size.ts
+runCli(() => {
+	const root = repositoryRoot();
+	const { values, positionals } = parseArgs({
+		options: { staged: { type: "boolean" } },
+		allowPositionals: true
+	});
+	const files = positionals.length ? positionals.map((file) => repositoryPath(root, resolve(file))) : void 0;
+	const failures = [...checkSize(root, files, values.staged), ...checkBlanketDisables(root, files, values.staged)];
+	for (const failure of failures) process.stderr.write(`${failure}\n`);
+	return failures.length ? 1 : 0;
+});
+//#endregion
+export {};

package/dist/bin/checks.d.mts

@@ -0,0 +1 @@
+export {}

package/dist/bin/checks.mjs

@@ -0,0 +1,51 @@
+#!/usr/bin/env node
+import { a as repositoryRoot, o as runCli } from "../files-BSl0U8lT.mjs";
+import { i as parseManifest, r as packageManager } from "../package-B1aipTbn.mjs";
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+import { spawnSync } from "node:child_process";
+//#region src/guardrails/checks.ts
+const CHECK_STEPS = [
+	"typecheck",
+	"lint",
+	"format:check",
+	"knip",
+	"test",
+	"size",
+	"ratchet",
+	"sync:check"
+];
+function runChecks(root) {
+	const manifest = parseManifest(readFileSync(join(root, "package.json"), "utf8"));
+	const manager = packageManager(manifest);
+	const failures = [];
+	for (const step of CHECK_STEPS) {
+		if (!manifest.scripts?.[step]) {
+			failures.push(`[${step}] Missing package.json script "${step}". Run antelopejs-sync.\n`);
+			continue;
+		}
+		const result = spawnSync(manager, ["run", step], {
+			cwd: root,
+			encoding: "utf8",
+			env: {
+				...process.env,
+				CI: "1"
+			},
+			maxBuffer: 67108864
+		});
+		if (result.status !== 0) failures.push(`[${step}]\n${result.stdout ?? ""}${result.stderr ?? ""}${result.error ? `${result.error.message}\n` : ""}${result.signal ? `Terminated by ${result.signal}\n` : ""}`);
+	}
+	return {
+		failed: failures.length,
+		output: `${failures.join("\n")}Checks: ${CHECK_STEPS.length - failures.length} passed, ${failures.length} failed.\n`
+	};
+}
+//#endregion
+//#region src/bin/checks.ts
+runCli(() => {
+	const result = runChecks(repositoryRoot());
+	process.stdout.write(result.output);
+	return result.failed ? 1 : 0;
+});
+//#endregion
+export {};

package/dist/bin/ratchet.d.mts

@@ -0,0 +1 @@
+export {}

package/dist/bin/ratchet.mjs

@@ -0,0 +1,66 @@
+#!/usr/bin/env node
+import { o as readCeilings } from "../ceilings--pJmhSde.mjs";
+import { a as repositoryRoot, i as repositoryPath, o as runCli } from "../files-BSl0U8lT.mjs";
+import { n as ratchet, r as lintDiagnostics } from "../ratchet-DNsVZH9s.mjs";
+import { resolve } from "node:path";
+import { execFileSync } from "node:child_process";
+import { parseArgs } from "node:util";
+//#region src/guardrails/staged-ratchet.ts
+function stagedRatchet(root, files) {
+	const targets = files ?? execFileSync("git", [
+		"diff",
+		"--cached",
+		"--name-only",
+		"--diff-filter=ACMR",
+		"-z"
+	], {
+		cwd: root,
+		encoding: "utf8"
+	}).split("\0").filter(Boolean);
+	if (!targets.length) return [];
+	const additions = /* @__PURE__ */ new Map();
+	for (const file of targets) {
+		const diff = execFileSync("git", [
+			"diff",
+			"--cached",
+			"--no-ext-diff",
+			"--no-color",
+			"--unified=0",
+			"--",
+			file
+		], {
+			cwd: root,
+			encoding: "utf8"
+		});
+		additions.set(file, Array.from(diff.matchAll(/^@@ -\d+(?:,\d+)? \+(\d+)(?:,(\d+))? @@/gm), ([, line, count]) => ({
+			start: Number(line),
+			end: Number(line) + Number(count ?? 1) - 1
+		})));
+	}
+	const ceilings = readCeilings(root);
+	return lintDiagnostics(root, void 0, targets).filter(({ rule, file, line }) => Object.hasOwn(ceilings.rules, rule) && line !== void 0 && additions.get(file)?.some(({ start, end }) => line >= start && line <= end)).map((diagnostic) => `${diagnostic.location}: ${diagnostic.message} [${diagnostic.rule}]\n  Fix: ${diagnostic.help ?? "Resolve this finding on the added line; the ceiling covers only legacy findings on untouched lines."}`);
+}
+//#endregion
+//#region src/bin/ratchet.ts
+runCli(() => {
+	const { values, positionals } = parseArgs({
+		options: {
+			update: { type: "boolean" },
+			staged: { type: "boolean" }
+		},
+		allowPositionals: true
+	});
+	const root = repositoryRoot();
+	if (values.update && values.staged) throw new Error("--staged cannot be combined with --update.");
+	if (positionals.length && !values.staged) throw new Error("File arguments require --staged.");
+	const result = values.staged ? {
+		failures: stagedRatchet(root, positionals.length ? positionals.map((file) => repositoryPath(root, resolve(file))) : void 0),
+		lowered: []
+	} : ratchet(root, values.update);
+	for (const message of result.lowered) process.stdout.write(`Lowered ${message}\n`);
+	for (const message of result.failures) process.stderr.write(`${message}\n`);
+	if (!result.failures.length) process.stdout.write("Ratchet: within ceilings.\n");
+	return result.failures.length ? 1 : 0;
+});
+//#endregion
+export {};

package/dist/bin/sync.d.mts

@@ -0,0 +1 @@
+export {}