@antelopejs/tooling-configs 0.2.6 → 0.2.7

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 CHANGED
@@ -28,6 +28,7 @@ The AntelopeJS guardrail pack: shared lint, format and dead-code presets, the co
28
28
  | bin | `antelopejs-sync` | Writes the guardrail pack into a repository; `--check` reports drift |
29
29
  | bin | `antelopejs-checks` | Runs every check and prints only the failures |
30
30
  | bin | `antelopejs-ratchet` | Fails when recorded debt grows; `--update` lowers the record |
31
+ | bin | `antelopejs-suppressions` | Fails when suppressions exceed their budget; `--update` lowers the budget |
31
32
  | bin | `antelopejs-check-size` | Fails on authored files over 20,000 bytes and on blanket disable directives |
32
33
  | bin | `antelopejs-api-diff <base-ref>` | Compares published declaration bundles against committed HEAD |
33
34
  | bin | `antelopejs-comment-proof <base-ref>` | Compares comment-free JavaScript emit against committed HEAD |
@@ -79,15 +80,15 @@ export default defineConfig({
79
80
 
80
81
  ### What the preset turns on
81
82
 
82
- | Group | Rules | Default |
83
- | -------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------- |
84
- | 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 |
85
- | Imports | `import/no-cycle`, `import/no-self-import`, `import/no-duplicates` | error |
86
- | Type-aware | `typescript/no-floating-promises` and eight more type-aware rules | error |
87
- | Complexity | `max-params` 5, `max-lines-per-function` 120, `max-lines` 500, `max-depth` 4, `complexity` 20 | error |
88
- | Anti-slop | all 15 vendored rules | error |
89
- | 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 |
90
- | Import sorting | `perfectionist/sort-imports`, autofixed by `oxlint --fix` | off |
83
+ | Group | Rules | Default |
84
+ | -------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------- |
85
+ | 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 |
86
+ | Imports | `import/no-cycle`, `import/no-self-import`, `import/no-duplicates` | error |
87
+ | Type-aware | `typescript/no-floating-promises` and eight more type-aware rules | error |
88
+ | Complexity | `max-params` 5, `max-lines-per-function` 120, `max-lines` 500, `max-depth` 4, `complexity` 20 | error |
89
+ | Anti-slop | all 15 vendored rules | error |
90
+ | 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 |
91
+ | Import sorting | `perfectionist/sort-imports`, autofixed by `oxlint --fix` | off |
91
92
 
92
93
  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)).
93
94
 
@@ -146,20 +147,21 @@ pnpm exec antelopejs-sync
146
147
  pnpm install
147
148
  ```
148
149
 
149
- | File | What `sync` does |
150
- | ------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
151
- | `oxlint.config.ts`, `oxfmt.config.ts`, `knip.config.ts` | Writes a config that extends the preset, unless the file already imports it |
152
- | `lefthook.yml` | Pre-commit on staged files: oxfmt, oxlint, size. Pre-push: typecheck |
153
- | `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` |
154
- | `.nvmrc` | `24` |
155
- | `.agents/setup` | Orb setup: switches to the `.nvmrc` Node, activates `packageManager` through corepack, installs with the frozen lockfile |
156
- | `AGENTS.md` | Writes the managed block between `<!-- antelopejs-guardrails:start -->` and `:end -->`; text outside the markers stays |
157
- | `CLAUDE.md` | `@AGENTS.md` |
158
- | `guardrails.ratchet.json` | Records non-empty debt on first adoption, before `sync:check` exists |
150
+ | File | What `sync` does |
151
+ | ------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
152
+ | `oxlint.config.ts`, `oxfmt.config.ts`, `knip.config.ts` | Writes a config that extends the preset, unless the file already imports it |
153
+ | `lefthook.yml` | Pre-commit on staged files: oxfmt, oxlint, size, suppressions. Pre-push: typecheck |
154
+ | `package.json` | `prepare` installs lefthook. Sets `checks`, `size`, `ratchet`, `ratchet:update`, `suppressions`, `suppressions:update`, `sync`, `sync:check`; adds missing `typecheck`, `lint`, `format`, `format:check`, `knip`; adds `lefthook` and `knip` |
155
+ | `.nvmrc` | `24` |
156
+ | `.agents/setup` | Orb setup: switches to the `.nvmrc` Node, activates `packageManager` through corepack, installs with the frozen lockfile |
157
+ | `AGENTS.md` | Writes the managed block between `<!-- antelopejs-guardrails:start -->` and `:end -->`; text outside the markers stays |
158
+ | `CLAUDE.md` | `@AGENTS.md` |
159
+ | `guardrails.ratchet.json` | Records non-empty debt on first adoption, before `sync:check` exists |
160
+ | `guardrails.suppressions.json` | Records the current suppression counts when the file is missing; restores the committed file instead when HEAD has one; never rewrites an existing file |
159
161
 
160
162
  `--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.
161
163
 
162
- `pnpm run checks` runs `typecheck`, `lint`, `format:check`, `knip`, `test`, `size` 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.
164
+ `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.
163
165
 
164
166
  ### Ratchet
165
167
 
@@ -180,11 +182,31 @@ When every rule count is zero and `oversizeFiles` is empty, the ratchet is retir
180
182
 
181
183
  `antelopejs-sync --check` rejects an existing retired file and tells you to run `ratchet:update`. Plain sync reports the same note but leaves deletion to the update command.
182
184
 
185
+ ### Suppression budget
186
+
187
+ `guardrails.suppressions.json` caps the suppressions in authored code files. It is separate from the ratchet and permanent: it stays when its counts reach zero and when the ratchet is retired.
188
+
189
+ ```json
190
+ {
191
+ "rules": { "anti-slop/no-chained-type-assertions": 19, "*": 0 },
192
+ "tsExpectError": 8,
193
+ "tsIgnore": 0,
194
+ "safety": 2
195
+ }
196
+ ```
197
+
198
+ - `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.
199
+ - `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.
200
+ - `antelopejs-suppressions --update` lowers each ceiling to the current count and keeps rules at zero. No command raises a ceiling.
201
+ - `antelopejs-suppressions` also compares the budget with the one on the pull request base: `--base <ref>` when given, else the `GITHUB_BASE_REF` branch in CI (fetched from `origin` into a shallow checkout), else `origin/HEAD`. It fails when a ceiling is higher than on the base or a rule the base lists is removed, so a raise merges only through the operator's ruleset bypass. A base without a budget, a first adoption, passes. Without a base the comparison is skipped.
202
+ - The pre-commit hook runs `antelopejs-suppressions --staged`: it compares the suppressions in the staged files with those files at HEAD, following renames and counting deleted files, and fails a kind that rises by more than the staged budget raises its ceiling. A suppression moved between staged files nets out.
203
+ - `@ts-ignore` is also a lint error (`typescript/ban-ts-comment`); `@ts-expect-error` fails once its error is gone.
204
+
183
205
  ### Size
184
206
 
185
207
  `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.
186
208
 
187
- 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.
209
+ 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.
188
210
 
189
211
  ### Cleanup proof
190
212
 
@@ -198,6 +220,8 @@ Pass `--allow-added <glob>` (repeatable) to `antelopejs-api-diff` when a refacto
198
220
  pnpm exec antelopejs-api-diff origin/main --allow-added '**/internal/**'
199
221
  ```
200
222
 
223
+ Both commands end with a table of suppressions in authored code files at the base and at HEAD, for PR bodies to copy: lint directives per rule they name (`*` for a directive naming none), `@ts-expect-error`, `@ts-ignore` and `SAFETY:` comments. The parser finds every comment, after code on the same line too, and skips strings, template literals and JSX text; `.vue` files contribute their script blocks and template comments. Generated output is left out as the size guard leaves it out.
224
+
201
225
  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.
202
226
 
203
227
  ```bash
@@ -1,7 +1,7 @@
1
1
  #!/usr/bin/env node
2
- import { c as revisionCounts, d as createAddedPolicy, f as describeAllowance, h as runCli, i as repositoryRoot, m as recordVerdict, o as DIRECTORY_LINK, p as fillStars, s as compareRevisions, u as allowedByGlob } from "../files-BOpSsyuD.mjs";
3
- import { i as parseManifest, r as packageManager } from "../package-Ckd7e4tA.mjs";
4
- import { a as unpublishedAt, i as packagesAt, n as isTestSource, r as outputRoot, t as emitPackage } from "../typescript-C8XKk2Ml.mjs";
2
+ import { l as runCli, o as repositoryRoot } from "../files-BMxKg5IR.mjs";
3
+ import { i as parseManifest, r as packageManager } from "../package-Dtjt_lSa.mjs";
4
+ import { a as unpublishedAt, c as revisionCounts, d as describeAllowance, f as fillStars, i as packagesAt, l as allowedByGlob, n as isTestSource, o as DIRECTORY_LINK, p as recordVerdict, r as outputRoot, s as compareRevisions, t as emitPackage, u as createAddedPolicy } from "../typescript-DIXhKgXR.mjs";
5
5
  import { createRequire } from "node:module";
6
6
  import { copyFileSync, cpSync, existsSync, mkdirSync, readFileSync, readdirSync, rmSync, symlinkSync, writeFileSync } from "node:fs";
7
7
  import { basename, dirname, join, relative, resolve } from "node:path";
@@ -1,38 +1,14 @@
1
1
  #!/usr/bin/env node
2
- import { h as runCli, i as repositoryRoot, r as repositoryPath, t as authoredSizes } from "../files-BOpSsyuD.mjs";
3
- import { t as checkSize } from "../size-tl9vdWs0.mjs";
4
- import { existsSync, readFileSync } from "node:fs";
5
- import { join, resolve } from "node:path";
6
- import { spawnSync } from "node:child_process";
2
+ import { a as repositoryPath, l as runCli, o as repositoryRoot, t as authoredSizes } from "../files-BMxKg5IR.mjs";
3
+ import { t as checkSize } from "../size-Fp3aWSkN.mjs";
4
+ import { n as revisionSuppressions, r as worktreeSuppressions } from "../suppressions-CgGa-kh7.mjs";
5
+ import { resolve } from "node:path";
7
6
  import { parseArgs } from "node:util";
8
7
  //#region src/guardrails/directives.ts
9
- const CODE_FILE = /\.(?:[cm]?[jt]sx?|vue)$/u;
10
- const BLANKET_DISABLE = /(?:\/\*|\/\/)\s*((?:eslint|oxlint)-disable(?:-line|-next-line)?)\s*(?:--[^\n]*?)?(?:\*\/|$)/gmu;
11
- function fileText(root, file, staged) {
12
- if (!staged) {
13
- const path = join(root, file);
14
- return existsSync(path) ? readFileSync(path, "utf8") : "";
15
- }
16
- const result = spawnSync("git", ["show", `:${file}`], {
17
- cwd: root,
18
- encoding: "utf8",
19
- maxBuffer: 67108864
20
- });
21
- if (result.error) throw result.error;
22
- return result.status === 0 ? result.stdout : "";
23
- }
24
8
  /** Reports disable directives without a rule list: oxlint honours them before any rule runs, so they also silence no-comments. */
25
9
  function checkBlanketDisables(root, files, staged = false) {
26
- const failures = [];
27
- for (const file of authoredSizes(root, files, staged).keys()) {
28
- if (!CODE_FILE.test(file)) continue;
29
- const text = fileText(root, file, staged);
30
- for (const match of text.matchAll(BLANKET_DISABLE)) {
31
- const line = text.slice(0, match.index).split("\n").length;
32
- 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.`);
33
- }
34
- }
35
- return failures;
10
+ const authored = [...authoredSizes(root, files, staged).keys()];
11
+ return (staged ? revisionSuppressions(root, "", authored) : worktreeSuppressions(root, authored)).flatMap((suppression) => suppression.kind === "rule" && suppression.rule === "*" ? [`${suppression.file}:${suppression.line}: \`${suppression.directive}\` 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.`] : []);
36
12
  }
37
13
  //#endregion
38
14
  //#region src/bin/check-size.ts
@@ -1,7 +1,7 @@
1
1
  #!/usr/bin/env node
2
2
  import "../ceilings-BSw9p4YB.mjs";
3
- import { h as runCli, i as repositoryRoot } from "../files-BOpSsyuD.mjs";
4
- import { i as parseManifest, r as packageManager } from "../package-Ckd7e4tA.mjs";
3
+ import { l as runCli, o as repositoryRoot } from "../files-BMxKg5IR.mjs";
4
+ import { i as parseManifest, r as packageManager } from "../package-Dtjt_lSa.mjs";
5
5
  import { existsSync, readFileSync } from "node:fs";
6
6
  import { join } from "node:path";
7
7
  import { spawnSync } from "node:child_process";
@@ -14,6 +14,7 @@ const CHECK_STEPS = [
14
14
  "test",
15
15
  "size",
16
16
  "ratchet",
17
+ "suppressions",
17
18
  "sync:check"
18
19
  ];
19
20
  function runChecks(root) {
@@ -1,6 +1,6 @@
1
1
  #!/usr/bin/env node
2
- import { c as revisionCounts, h as runCli, i as repositoryRoot, s as compareRevisions } from "../files-BOpSsyuD.mjs";
3
- import { i as packagesAt, t as emitPackage } from "../typescript-C8XKk2Ml.mjs";
2
+ import { l as runCli, o as repositoryRoot } from "../files-BMxKg5IR.mjs";
3
+ import { c as revisionCounts, i as packagesAt, s as compareRevisions, t as emitPackage } from "../typescript-DIXhKgXR.mjs";
4
4
  import { copyFileSync, mkdirSync } from "node:fs";
5
5
  import { dirname, join, relative } from "node:path";
6
6
  //#region src/guardrails/comment-proof.ts
@@ -1,49 +1,10 @@
1
1
  #!/usr/bin/env node
2
- import { s as readCeilings, t as CEILINGS_FILE } from "../ceilings-BSw9p4YB.mjs";
3
- import { n as renamedPaths } from "../renames-BGO4dWJ8.mjs";
4
- import { a as resolveRevision, h as runCli, i as repositoryRoot, r as repositoryPath } from "../files-BOpSsyuD.mjs";
5
- import { n as ratchet, r as lintDiagnostics } from "../ratchet-EwpOUzaZ.mjs";
2
+ import { t as CEILINGS_FILE } from "../ceilings-BSw9p4YB.mjs";
3
+ import { a as repositoryPath, l as runCli, o as repositoryRoot, s as resolveRevision } from "../files-BMxKg5IR.mjs";
4
+ import { n as stagedRatchet } from "../staged-ratchet-CJHjp2kx.mjs";
5
+ import { n as ratchet } from "../ratchet-zzo2tT74.mjs";
6
6
  import { resolve } from "node:path";
7
- import { execFileSync } from "node:child_process";
8
7
  import { parseArgs } from "node:util";
9
- //#region src/guardrails/staged-ratchet.ts
10
- function stagedRatchet(root, files) {
11
- const targets = files ?? execFileSync("git", [
12
- "diff",
13
- "--cached",
14
- "--name-only",
15
- "--diff-filter=ACMR",
16
- "-z"
17
- ], {
18
- cwd: root,
19
- encoding: "utf8"
20
- }).split("\0").filter(Boolean);
21
- if (!targets.length) return [];
22
- const renames = renamedPaths(root, true);
23
- const additions = /* @__PURE__ */ new Map();
24
- for (const file of targets) {
25
- const diff = execFileSync("git", [
26
- "diff",
27
- "--cached",
28
- "--no-ext-diff",
29
- "--no-color",
30
- "--unified=0",
31
- "--find-renames",
32
- "--",
33
- ...[renames.get(file), file].filter((path) => path !== void 0)
34
- ], {
35
- cwd: root,
36
- encoding: "utf8"
37
- });
38
- additions.set(file, Array.from(diff.matchAll(/^@@ -\d+(?:,\d+)? \+(\d+)(?:,(\d+))? @@/gm), ([, line, count]) => ({
39
- start: Number(line),
40
- end: Number(line) + Number(count ?? 1) - 1
41
- })));
42
- }
43
- const ceilings = readCeilings(root);
44
- 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."}`);
45
- }
46
- //#endregion
47
8
  //#region src/bin/ratchet.ts
48
9
  runCli(() => {
49
10
  const { values, positionals } = parseArgs({
@@ -0,0 +1 @@
1
+ export {}
@@ -0,0 +1,101 @@
1
+ #!/usr/bin/env node
2
+ import { l as runCli, o as repositoryRoot, s as resolveRevision } from "../files-BMxKg5IR.mjs";
3
+ import { a as stagedSuppressions, i as parseBudget, r as checkSuppressions, t as SUPPRESSIONS_FILE } from "../suppression-budget-N5ONsh2g.mjs";
4
+ import { readFileSync } from "node:fs";
5
+ import { join } from "node:path";
6
+ import { execFileSync, spawnSync } from "node:child_process";
7
+ import { parseArgs } from "node:util";
8
+ //#region src/guardrails/suppression-base.ts
9
+ function verified(root, ref) {
10
+ const result = spawnSync("git", [
11
+ "rev-parse",
12
+ "--verify",
13
+ "--quiet",
14
+ "--end-of-options",
15
+ `${ref}^{commit}`
16
+ ], {
17
+ cwd: root,
18
+ encoding: "utf8"
19
+ });
20
+ return result.status === 0 ? result.stdout.trim() : void 0;
21
+ }
22
+ /**
23
+ * The commit a pull request merges into: `base` when given; in CI the
24
+ * `GITHUB_BASE_REF` branch, fetched from `origin` when a shallow checkout
25
+ * lacks it; otherwise `origin/HEAD`, the remote's default branch. A requested
26
+ * base that cannot be resolved is an error; without one, a repository with no
27
+ * `origin/HEAD` has no base.
28
+ */
29
+ function suppressionBase(root, base) {
30
+ if (base !== void 0) return resolveRevision(root, base);
31
+ const branch = process.env.GITHUB_BASE_REF;
32
+ if (branch) {
33
+ const remote = `refs/remotes/origin/${branch}`;
34
+ if (verified(root, remote) === void 0) execFileSync("git", [
35
+ "fetch",
36
+ "--quiet",
37
+ "--no-tags",
38
+ "--depth=1",
39
+ "origin",
40
+ `+refs/heads/${branch}:${remote}`
41
+ ], {
42
+ cwd: root,
43
+ stdio: [
44
+ "ignore",
45
+ "ignore",
46
+ "pipe"
47
+ ]
48
+ });
49
+ return resolveRevision(root, remote);
50
+ }
51
+ return verified(root, "refs/remotes/origin/HEAD");
52
+ }
53
+ /**
54
+ * Fails each ceiling of the working-tree budget that is higher than on
55
+ * `revision`, and each rule that `revision` lists but the working tree
56
+ * dropped. A base without a budget, a first adoption, passes.
57
+ */
58
+ function raisedCeilings(root, revision) {
59
+ const committed = spawnSync("git", ["show", `${revision}:${SUPPRESSIONS_FILE}`], {
60
+ cwd: root,
61
+ encoding: "utf8"
62
+ });
63
+ if (committed.status !== 0) return [];
64
+ const label = `${revision.slice(0, 12)}:${SUPPRESSIONS_FILE}`;
65
+ const base = parseBudget(committed.stdout, label);
66
+ const current = parseBudget(readFileSync(join(root, SUPPRESSIONS_FILE), "utf8"), SUPPRESSIONS_FILE);
67
+ const failures = [];
68
+ const compare = (key, before, after) => {
69
+ if (after === void 0) failures.push(`${SUPPRESSIONS_FILE}: removes ${key}, which has ceiling ${before} on the base. Keep the key; lower it with suppressions:update.`);
70
+ else if (after > before) failures.push(`${SUPPRESSIONS_FILE}: raises ${key} from ${before} on the base to ${after}.`);
71
+ };
72
+ for (const rule of /* @__PURE__ */ new Set([...Object.keys(base.rules), ...Object.keys(current.rules)])) compare(`lint rule \`${rule}\``, base.rules[rule] ?? 0, Object.hasOwn(base.rules, rule) ? current.rules[rule] : current.rules[rule] ?? 0);
73
+ compare("`@ts-expect-error`", base.tsExpectError, current.tsExpectError);
74
+ compare("`@ts-ignore`", base.tsIgnore, current.tsIgnore);
75
+ compare("`SAFETY:` comments", base.safety, current.safety);
76
+ return failures.length ? [...failures, "Ceilings only go down. Fix the code, or remove another suppression of the same kind; raising a ceiling needs the operator's approval through the ruleset bypass."] : [];
77
+ }
78
+ //#endregion
79
+ //#region src/bin/suppressions.ts
80
+ function fullCheck(root, update, base) {
81
+ const failures = checkSuppressions(root, update);
82
+ const revision = suppressionBase(root, base);
83
+ return revision === void 0 ? failures : [...raisedCeilings(root, revision), ...failures];
84
+ }
85
+ runCli(() => {
86
+ const { values } = parseArgs({
87
+ options: {
88
+ update: { type: "boolean" },
89
+ staged: { type: "boolean" },
90
+ base: { type: "string" }
91
+ },
92
+ allowPositionals: true
93
+ });
94
+ if (values.staged && (values.update || values.base !== void 0)) throw new Error("--staged cannot be combined with --update or --base.");
95
+ const root = repositoryRoot();
96
+ const failures = values.staged ? stagedSuppressions(root) : fullCheck(root, values.update, values.base);
97
+ for (const failure of failures) process.stderr.write(`${failure}\n`);
98
+ return failures.length ? 1 : 0;
99
+ });
100
+ //#endregion
101
+ export {};
package/dist/bin/sync.mjs CHANGED
@@ -1,8 +1,9 @@
1
1
  #!/usr/bin/env node
2
2
  import { a as formatCeilings, o as isRetired, s as readCeilings, t as CEILINGS_FILE } from "../ceilings-BSw9p4YB.mjs";
3
- import { h as runCli, i as repositoryRoot } from "../files-BOpSsyuD.mjs";
4
- import { a as repositoryTools, i as parseManifest, n as managedPackage, o as toolingVersions, r as packageManager, t as execCommand } from "../package-Ckd7e4tA.mjs";
5
- import { t as measureBaseline } from "../ratchet-EwpOUzaZ.mjs";
3
+ import { l as runCli, o as repositoryRoot } from "../files-BMxKg5IR.mjs";
4
+ import { a as repositoryTools, i as parseManifest, n as managedPackage, o as toolingVersions, r as packageManager, t as execCommand } from "../package-Dtjt_lSa.mjs";
5
+ import { t as measureBaseline } from "../ratchet-zzo2tT74.mjs";
6
+ import { n as adoptedBudget, t as SUPPRESSIONS_FILE } from "../suppression-budget-N5ONsh2g.mjs";
6
7
  import { chmodSync, existsSync, lstatSync, mkdirSync, readFileSync, readdirSync, readlinkSync, statSync, unlinkSync, writeFileSync } from "node:fs";
7
8
  import { dirname, join, resolve } from "node:path";
8
9
  import { execFileSync } from "node:child_process";
@@ -29,11 +30,14 @@ const CLEANUP_PROOF = `### Cleanup proof
29
30
 
30
31
  A behaviour-preserving cleanup PR shows \`antelopejs-api-diff <base-ref>\` passing. Published declarations and built runtime exports stay unchanged; pass \`--allow-added <glob>\` (repeatable, e.g. \`'**/internal/**'\`) to let added entries under that glob pass when their module is \`@internal\`, and copy its "Added (allowed)" list. A comment-only PR shows \`antelopejs-comment-proof <base-ref>\` passing instead of a verifier. Both compare committed HEAD.
31
32
 
32
- Copy counts from the proof's base and HEAD table. Never type counts by hand. Keep the command and the committed head beside the copied output. Directive lines are not individual suppressed rules.
33
+ Copy counts from the proof's base and HEAD table. Never type counts by hand. Keep the command and the committed head beside the copied output. The table counts a lint directive once per rule it names, inline directives included.
33
34
 
34
35
  Pass \`--probe <file.cjs>\` to api-diff when changing receivers, positional calls, or modules that no published entry reaches. The same captured script runs against both worktree roots, supplied as \`argv[2]\`, and prints JSON observations. Matching metadata alone does not prove those behaviours.
35
36
 
36
37
  An entry-only rule exempts only its own module. Add a second module entry rather than exempting another importer. A no-upward rule must reject peers in the same tier as well as higher tiers. Probe the rank decision with an import, not just a reading of the configuration.`;
38
+ const SUPPRESSION_BUDGET = `### Suppression budget
39
+
40
+ \`guardrails.suppressions.json\` caps the suppressions in authored code: lint directives per rule they name (\`*\` for none), \`@ts-expect-error\`, \`@ts-ignore\` and \`SAFETY:\` comments. A suppression over its ceiling fails: fix the code, or remove another suppression of the same kind. A rule that keeps needing suppressions should be changed in the preset. Never raise or remove a number in that file: the check fails a ceiling higher than on the pull request base, and only the operator approves a raise. After you remove suppressions, run \`pnpm run suppressions:update\` and commit the lowered file.`;
37
41
  const SHARED_RULES = [
38
42
  ["Formatting", "oxfmt"],
39
43
  ["Lint findings are errors; no rule warns", "oxlint preset"],
@@ -48,10 +52,12 @@ const SHARED_RULES = [
48
52
  ["PR-body counts come from tracked code files", "api-diff and comment-proof tables"],
49
53
  ["Receiver, positional and unpublished-module behaviour", "`antelopejs-api-diff <base-ref> --probe <file.cjs>`"],
50
54
  ["Type suppressions and directive reasons are justified", "review; no tool"],
51
- ["No-upward rules reject same-tier peers", "review and import probes"]
55
+ ["No-upward rules reject same-tier peers", "review and import probes"],
56
+ ["No `@ts-ignore`", "`typescript/ban-ts-comment`"]
52
57
  ];
53
58
  const FULL_RULES = [
54
59
  ["Files ≤ 20,000 bytes, tests included", "`antelopejs-check-size` (pre-commit)"],
60
+ ["Suppressions stay within `guardrails.suppressions.json`", "`antelopejs-suppressions` (pre-commit, checks)"],
55
61
  ["Types check", "`tsc` (pre-push)"],
56
62
  ["No dead files, exports, or dependencies", "knip"],
57
63
  ["Managed files match the pack", "`antelopejs-sync --check`"],
@@ -82,7 +88,7 @@ function fullBody(context) {
82
88
  return [
83
89
  "## Guardrails",
84
90
  "",
85
- `Finish every change with \`pnpm run checks\`. It runs typecheck, lint, format, knip, tests, size, ${context.ratchet ? "ratchet, " : ""}and sync, and prints only what failed. The change is done when it prints no failure.`,
91
+ `Finish every change with \`pnpm run checks\`. It runs typecheck, lint, format, knip, tests, size, ${context.ratchet ? "ratchet, " : ""}suppressions, and sync, and prints only what failed. The change is done when it prints no failure.`,
86
92
  "",
87
93
  ...pointers(context).flatMap((line) => [line, ""]),
88
94
  "The tools enforce most rules, listed in the table at the end. The sections below hold the rules no tool checks.",
@@ -93,6 +99,8 @@ function fullBody(context) {
93
99
  "",
94
100
  CLEANUP_PROOF,
95
101
  "",
102
+ SUPPRESSION_BUDGET,
103
+ "",
96
104
  ...context.ratchet ? [
97
105
  "### Debt",
98
106
  "",
@@ -191,6 +199,10 @@ function lefthook(current, manager, tools, ratchet = true) {
191
199
  "antelopejs-ratchet": {
192
200
  glob,
193
201
  run: `${tools.hookPrefix}${tools.commands.ratchet} --staged {staged_files}`
202
+ },
203
+ "antelopejs-suppressions": {
204
+ glob,
205
+ run: `${tools.hookPrefix}${tools.commands.suppressions} --staged`
194
206
  }
195
207
  },
196
208
  "pre-push": { "antelopejs-typecheck": { run: `${manager} run typecheck` } }
@@ -428,6 +440,14 @@ const MANAGED_ARTIFACTS = [
428
440
  content: current ?? context.baseline,
429
441
  notes: []
430
442
  })
443
+ },
444
+ {
445
+ path: SUPPRESSIONS_FILE,
446
+ profiles: ["full"],
447
+ desired: (current, context) => ({
448
+ content: current ?? context.suppressionBudget,
449
+ notes: []
450
+ })
431
451
  }
432
452
  ];
433
453
  function planSync(current, modes, context) {
@@ -522,6 +542,7 @@ function repositoryContext(root, current, profile) {
522
542
  nuxt: Boolean(manifest.dependencies?.nuxt || manifest.devDependencies?.nuxt || readdirSync(root).some((name) => name.startsWith("nuxt.config."))),
523
543
  claude: profile === "full" ? claudeProse(root, current) : "",
524
544
  baseline: "",
545
+ suppressionBudget: profile === "full" && !current.has("guardrails.suppressions.json") ? adoptedBudget(root) : "",
525
546
  verificationSkill: verificationSkill(root),
526
547
  glossary: ["GLOSSARY.md", "docs/GLOSSARY.md"].find((file) => existsSync(join(root, file)))
527
548
  };