@antelopejs/tooling-configs 0.0.9 → 0.2.1

package/README.md

@@ -6,23 +6,30 @@
 <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>
 </div>
 
-Shared lint, format and dead-code presets for AntelopeJS repositories, plus a check for the version ranges of interface dependencies.
+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 |
-| bin               | `antelopejs-check-interface-ranges`                                       | Fails on interface ranges that break module startup                   |
+| 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
 
@@ -74,12 +81,25 @@ export default defineConfig({
 | -------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------- |
 | 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` as an error, eight more type-aware rules as warnings                                                                                                                            | on      |
-| Complexity     | `max-params` 5, `max-lines-per-function` 120, `max-lines` 500, `max-depth` 4, `complexity` 20                                                                                                                     | warn    |
-| Anti-slop      | 7 of the 15 vendored rules; the 8 others are listed in `ANTI_SLOP_RULES_OFF_BY_DEFAULT`                                                                                                                           | warn    |
+| 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     |
 
-`correctness` is raised to error on purpose: oxlint reports it as warnings, and warnings never fail the command. Complexity and anti-slop start as warnings so a repository can work through its backlog before raising them to `"error"`.
+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`.
 
 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.
 
@@ -87,9 +107,10 @@ Import sorting is off because it moves value imports across side-effect imports,
 
 ```ts
 antelopePreset({
-  antiSlop: "error", // "warn" (default) | "error" | false
-  importCycles: "warn", // "error" (default) | "warn" | false
-  complexity: { maxParams: 8 }, // override thresholds or severity, or false
+  antiSlop: false, // true (default)
+  guardrails: false, // true (default)
+  importCycles: false, // true (default)
+  complexity: { maxParams: 8 }, // override thresholds, or false
   importSorting: true, // false (default); needs eslint-plugin-perfectionist
   typeAware: false, // true (default); false when the repository has no oxlint-tsgolint
 });
@@ -113,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
@@ -159,7 +224,7 @@ import { antelopeNuxtConfig } from "@antelopejs/tooling-configs/eslint";
 export default antelopeNuxtConfig({ dirs: ["./playground"] });
 ```
 
-`@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`. Pass `rules` to layer your own on top, and declare `@nuxt/eslint-config` in the front end's `package.json`.
+`@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
 
@@ -214,7 +279,7 @@ checks that remain the author's responsibility.
 
 ## Contributing
 
-See [CONTRIBUTING.md](./CONTRIBUTING.md). `pnpm install`, then `pnpm checks` runs the typecheck, lint, format check and tests.
+See [CONTRIBUTING.md](./CONTRIBUTING.md). `pnpm install`, then `pnpm checks` runs the typecheck, lint, format check, tests, size check and ratchet.
 
 ## License
 

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-Bocv-qA8.mjs";
+import { t as checkSize } from "../size-DJ7YSry_.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-Bocv-qA8.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-Bocv-qA8.mjs";
+import { n as ratchet, r as lintDiagnostics } from "../ratchet-B2-4XxAl.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 {}