@antelopejs/tooling-configs 0.2.16 → 0.2.18

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (51) hide show
  1. package/README.md +101 -52
  2. package/dist/bin/api-diff.mjs +430 -107
  3. package/dist/bin/body-check.d.mts +1 -0
  4. package/dist/bin/body-check.mjs +344 -0
  5. package/dist/bin/capture.d.mts +1 -0
  6. package/dist/bin/capture.mjs +559 -0
  7. package/dist/bin/check-size.mjs +3 -3
  8. package/dist/bin/checks.mjs +3 -3
  9. package/dist/bin/comment-proof.mjs +4 -3
  10. package/dist/bin/garden.mjs +6 -6
  11. package/dist/bin/ratchet.mjs +316 -10
  12. package/dist/bin/suppressions.mjs +118 -80
  13. package/dist/bin/sync.mjs +554 -153
  14. package/dist/bin/verify.mjs +240 -127
  15. package/dist/capture/index.d.mts +50 -0
  16. package/dist/capture/index.mjs +2 -0
  17. package/dist/{ceilings-BSw9p4YB.mjs → ceilings-B7KayYIG.mjs} +11 -3
  18. package/dist/{checks-BlWDFYio.mjs → checks-CxkSu2E6.mjs} +1 -1
  19. package/dist/{ci-workflow-DIsoEgMd.mjs → ci-workflow-ChW4He0r.mjs} +84 -3
  20. package/dist/{files-2FikHZ9F.mjs → files-DJ0TeaTU.mjs} +11 -5
  21. package/dist/formal/index.d.mts +40 -0
  22. package/dist/formal/index.mjs +205 -0
  23. package/dist/{json-BqvuCkqr.mjs → json-CG2L7YFl.mjs} +12 -8
  24. package/dist/oxc/anti-slop/index.mjs +869 -21
  25. package/dist/oxc/fmt.mjs +1 -1
  26. package/dist/oxc/guardrails/index.d.mts +1 -1
  27. package/dist/oxc/guardrails/index.mjs +736 -4
  28. package/dist/oxc/lint.d.mts +20 -3
  29. package/dist/oxc/lint.mjs +34 -10
  30. package/dist/oxlint-DIV-lLSS.mjs +98 -0
  31. package/dist/{package-Dtjt_lSa.mjs → package-BRTjkzt5.mjs} +29 -3
  32. package/dist/proof-stamp-DDDC0J6l.mjs +279 -0
  33. package/dist/ratchet-BAcLRYuM.mjs +448 -0
  34. package/dist/{renames-BGO4dWJ8.mjs → renames-L2owF5GD.mjs} +2 -2
  35. package/dist/scenes-DZVXkcxS.mjs +104 -0
  36. package/dist/shared-igPpEDpS.mjs +622 -0
  37. package/dist/{size-BVgNbLO6.mjs → size-DBatLT-F.mjs} +4 -4
  38. package/dist/suppression-base-9L8dlMQK.mjs +120 -0
  39. package/dist/suppression-budget-C0SkPO5R.mjs +535 -0
  40. package/dist/{suppressions-BJAngUxo.mjs → suppressions-DM60NkvL.mjs} +180 -18
  41. package/dist/templates-CypDm-j9.mjs +121 -0
  42. package/dist/typescript-CM0LrVP7.mjs +222 -0
  43. package/dist/verify/index.d.mts +6 -1
  44. package/dist/verify/index.mjs +1 -1
  45. package/package.json +31 -5
  46. package/dist/kinds-Bzyyi9yk.mjs +0 -25
  47. package/dist/ratchet-DRdIYwmv.mjs +0 -80
  48. package/dist/shared-CsXIMK3I.mjs +0 -34
  49. package/dist/staged-ratchet-CjoRfZaM.mjs +0 -236
  50. package/dist/suppression-budget-Yyf5_J5l.mjs +0 -283
  51. package/dist/typescript-C54ONh9m.mjs +0 -433
@@ -1,283 +0,0 @@
1
- import { n as renamedPaths } from "./renames-BGO4dWJ8.mjs";
2
- import { n as changedFiles } from "./files-2FikHZ9F.mjs";
3
- import { t as stagedAdditions } from "./staged-ratchet-CjoRfZaM.mjs";
4
- import { a as revisionSuppressions, i as openDisablesIn, n as countSuppressions, o as worktreeSuppressions, r as inWorktree, t as atRevision } from "./suppressions-BJAngUxo.mjs";
5
- import { existsSync, readFileSync, writeFileSync } from "node:fs";
6
- import { join } from "node:path";
7
- import { execFileSync, spawnSync } from "node:child_process";
8
- //#region src/guardrails/suppression-policy.ts
9
- /** Rules a directive may never name, each with what to do instead. */
10
- const NEVER_SUPPRESSED = /* @__PURE__ */ new Map([
11
- ["anti-slop/require-safety-comment-for-type-assertion", "remove the assertion (a type guard, a schema parse at the boundary, an inferred or owner-derived type), or, where it really holds, write `SAFETY: <why it holds>` above it"],
12
- ["antelopejs/no-comments", "say it in code, move a public contract into TSDoc, or delete the comment"],
13
- ["antelopejs/no-constant-value-assertion", "assert on a value the code under test computes, or delete the test"],
14
- ["antelopejs/no-fs-read-in-tests", "drive the behaviour through the public interface, or read from fixtures/"],
15
- ["antelopejs/no-self-import-in-tests", "import the module under test by relative path, or publish the subpath in exports and link the package to itself"],
16
- ["antelopejs/no-typeof-function-only-test", "assert on what the function returns or does, or delete the test"],
17
- ["antelopejs/require-assertion", "assert on the behaviour, or delete the test"],
18
- ["typescript/ban-ts-comment", "use `@ts-expect-error <reason>`"]
19
- ]);
20
- const MIN_REASON_WORDS = 3;
21
- /** Words that say a suppression is wanted without saying why the code needs it. */
22
- const VAGUE_WORDS = new Set(`a an the this that it its is are be was here there we for of to as and or not no
23
- ok okay fine safe safely correct valid works working intended intentional intentionally
24
- needed necessary required expected known false positive legacy existing old behavior behaviour
25
- preserve preserved preserves preserving keep kept compat compatibility workaround hack
26
- temporary todo fixme later ignore ignored disable disabled suppress suppressed lint rule
27
- type types typing typescript cast casting assert assertion by design trust trusted me`.split(/\s+/u));
28
- function words(text) {
29
- return text.toLowerCase().split(/[^\p{L}\p{N}]+/u).filter(Boolean);
30
- }
31
- /** A reason too short or too vague to tell a reader why this code needs its suppression. */
32
- function genericReason(suppression) {
33
- const said = words(suppression.reason);
34
- if (said.length < MIN_REASON_WORDS) return true;
35
- const named = new Set(suppression.kind === "rule" ? words(suppression.rule) : []);
36
- return said.every((word) => VAGUE_WORDS.has(word) || named.has(word));
37
- }
38
- function identity(suppression) {
39
- return [
40
- suppression.kind,
41
- suppression.kind === "rule" ? suppression.rule : "",
42
- suppression.reason
43
- ].join("\0");
44
- }
45
- /** Takes one occurrence of `key` from `counts`, reporting whether one was left. */
46
- function take(counts, key) {
47
- const left = counts.get(key) ?? 0;
48
- if (left > 0) counts.set(key, left - 1);
49
- return left > 0;
50
- }
51
- /**
52
- * The items of `after` that `before` does not account for, as multisets of
53
- * `key`: an item is matched first in its own file, then in any file, so a
54
- * moved item is not added and an added one is reported where it was added.
55
- */
56
- function unmatched(before, after, key) {
57
- const sameFile = /* @__PURE__ */ new Map();
58
- for (const item of before) {
59
- const local = `${item.file}\0${key(item)}`;
60
- sameFile.set(local, (sameFile.get(local) ?? 0) + 1);
61
- }
62
- const elsewhere = after.filter((item) => !take(sameFile, `${item.file}\0${key(item)}`));
63
- const anyFile = /* @__PURE__ */ new Map();
64
- for (const [local, count] of sameFile) {
65
- const global = local.slice(local.indexOf("\0") + 1);
66
- anyFile.set(global, (anyFile.get(global) ?? 0) + count);
67
- }
68
- return elsewhere.filter((item) => !take(anyFile, key(item)));
69
- }
70
- /**
71
- * The suppressions of `after` that `before` does not account for, by kind,
72
- * rule and reason, so a suppression moved to another file with its reason is
73
- * not added, and one whose reason changed is.
74
- */
75
- function addedSuppressions(before, after) {
76
- return unmatched(before, after, identity);
77
- }
78
- function label(suppression) {
79
- if (suppression.kind === "rule") return `\`${suppression.directive} ${suppression.rule}\``;
80
- if (suppression.kind === "safety") return "`SAFETY:`";
81
- return suppression.kind === "tsIgnore" ? "`@ts-ignore`" : "`@ts-expect-error`";
82
- }
83
- /**
84
- * Fails each added suppression that names a rule no directive may name, and
85
- * each whose reason is empty or generic. Suppressions already on the base
86
- * are left to the burn-down the budget tracks.
87
- */
88
- function policyFailures(added) {
89
- return added.flatMap((suppression) => {
90
- const at = `${suppression.file}:${suppression.line}`;
91
- const instead = suppression.kind === "rule" ? NEVER_SUPPRESSED.get(suppression.rule) : void 0;
92
- if (instead !== void 0) return [`${at}: ${label(suppression)}: this rule is never suppressed. Fix: ${instead}.`];
93
- if (suppression.kind === "rule" && suppression.rule === "*") return [];
94
- if (!genericReason(suppression)) return [];
95
- const quoted = suppression.reason ? `"${suppression.reason}"` : "none";
96
- return [`${at}: ${label(suppression)} reason ${quoted} does not say why this code needs it. Fix: state the fact about this line that makes the suppression hold (at least ${MIN_REASON_WORDS} words${suppression.kind === "rule" ? ", after ` -- `" : ""}), or fix the code.`];
97
- });
98
- }
99
- /** Fails each block disable left open at the end of its file. */
100
- function openDisableFailures(open) {
101
- return open.map(({ directive, rule, file, line }) => `${file}:${line}: \`${directive}${rule === "*" ? "" : ` ${rule}`}\` is never closed, so it also silences every line added below it. Fix: add \`${directive.replace("disable", "enable")}${rule === "*" ? "" : ` ${rule}`}\` right after the last line that needs it, or use \`${directive}-next-line\`.`);
102
- }
103
- /** The open blocks of `after` beyond those of `before`, by directive and rule. */
104
- function addedOpenDisables(before, after) {
105
- return unmatched(before, after, ({ directive, rule }) => [directive, rule].join("\0"));
106
- }
107
- function hasCommit(root, revision) {
108
- return spawnSync("git", [
109
- "rev-parse",
110
- "--verify",
111
- "--quiet",
112
- `${revision}^{commit}`
113
- ], { cwd: root }).status === 0;
114
- }
115
- /**
116
- * Fails what the working tree adds against `revision` (HEAD when none is
117
- * given): a suppression that names a never-suppressed rule or gives no
118
- * specific reason, and a block disable left open.
119
- */
120
- function checkPolicy(root, revision = "HEAD") {
121
- if (!hasCommit(root, revision)) return [];
122
- return [...policyFailures(addedSuppressions(revisionSuppressions(root, revision), worktreeSuppressions(root))), ...openDisableFailures(addedOpenDisables(atRevision(root, revision, openDisablesIn), inWorktree(root, openDisablesIn)))];
123
- }
124
- /** The same policy for a commit: the staged files against their HEAD versions, rename sources and deleted files included. */
125
- function checkStagedPolicy(root, staged, previous) {
126
- if (!hasCommit(root, "HEAD")) return [];
127
- return [...policyFailures(addedSuppressions(revisionSuppressions(root, "HEAD", previous), revisionSuppressions(root, "", staged))), ...openDisableFailures(addedOpenDisables(atRevision(root, "HEAD", openDisablesIn, previous), atRevision(root, "", openDisablesIn, staged)))];
128
- }
129
- //#endregion
130
- //#region src/guardrails/suppression-budget.ts
131
- /** The per-repository suppression budget, at the repository root. It is permanent: nothing deletes it, even at zero. */
132
- const SUPPRESSIONS_FILE = "guardrails.suppressions.json";
133
- /** What a failure tells the author to do. */
134
- const SUPPRESSION_FIX = "Fix: fix the code, or remove another suppression of the same kind; a rule that keeps needing suppressions should be changed in the preset.";
135
- const LABELS = {
136
- tsExpectError: "`@ts-expect-error`",
137
- tsIgnore: "`@ts-ignore`",
138
- safety: "`SAFETY:` comments"
139
- };
140
- function labelOf(suppression) {
141
- return suppression.kind === "rule" ? `lint rule \`${suppression.rule}\`` : LABELS[suppression.kind];
142
- }
143
- /** The rule a SAFETY comment satisfies, so a directive disabling it may become a SAFETY comment without a raise. */
144
- const SAFETY_RULE = "anti-slop/require-safety-comment-for-type-assertion";
145
- /** The safety ceiling plus the room the directives disabling the SAFETY rule leave below theirs, so the two only ever shrink together. */
146
- function safetyCeiling(budget, disables) {
147
- return budget.safety + Math.max(0, (budget.rules["anti-slop/require-safety-comment-for-type-assertion"] ?? 0) - disables);
148
- }
149
- function limitOf(budget, suppression) {
150
- return suppression.kind === "rule" ? budget.rules[suppression.rule] ?? 0 : budget[suppression.kind];
151
- }
152
- function count(value, source) {
153
- if (value === void 0) throw new Error(`${source} is missing`);
154
- if (!Number.isInteger(value) || value < 0) throw new Error(`${source} must be a non-negative integer`);
155
- return value;
156
- }
157
- /** Parses a budget, rejecting a missing field and anything but non-negative integer ceilings. */
158
- function parseBudget(text, source) {
159
- const parsed = JSON.parse(text);
160
- if (parsed === null || Array.isArray(parsed)) throw new Error(`${source}: expected an object with "rules"`);
161
- const rules = parsed.rules ?? {};
162
- if (rules === null || Array.isArray(rules)) throw new Error(`${source}: rules must be an object of counts`);
163
- return {
164
- rules: Object.fromEntries(Object.entries(rules).map(([rule, limit]) => [rule, count(limit, `${source}: rules "${rule}"`)])),
165
- tsExpectError: count(parsed.tsExpectError, `${source}: tsExpectError`),
166
- tsIgnore: count(parsed.tsIgnore, `${source}: tsIgnore`),
167
- safety: count(parsed.safety, `${source}: safety`)
168
- };
169
- }
170
- /** Serializes a budget with sorted rules, zero ceilings kept, so rewriting an unchanged budget is a no-op. */
171
- function formatBudget(budget) {
172
- const rules = Object.fromEntries(Object.entries(budget.rules).sort(([a], [b]) => a.localeCompare(b)));
173
- return `${JSON.stringify({
174
- ...budget,
175
- rules
176
- }, null, 2)}\n`;
177
- }
178
- /** The budget sync writes at adoption: the committed one when the file was only deleted, so recreating it never raises a ceiling, else the current counts. */
179
- function adoptedBudget(root) {
180
- const committed = spawnSync("git", ["show", `HEAD:${SUPPRESSIONS_FILE}`], {
181
- cwd: root,
182
- encoding: "utf8"
183
- });
184
- if (committed.status === 0) return committed.stdout;
185
- return formatBudget(countSuppressions(worktreeSuppressions(root)));
186
- }
187
- function groupByKey(suppressions) {
188
- const groups = /* @__PURE__ */ new Map();
189
- for (const suppression of suppressions) {
190
- const key = labelOf(suppression);
191
- groups.set(key, [...groups.get(key) ?? [], suppression]);
192
- }
193
- return groups;
194
- }
195
- function lowered(budget, current) {
196
- return {
197
- rules: Object.fromEntries(Object.entries(budget.rules).map(([rule, limit]) => [rule, Math.min(limit, current.rules[rule] ?? 0)])),
198
- tsExpectError: Math.min(budget.tsExpectError, current.tsExpectError),
199
- tsIgnore: Math.min(budget.tsIgnore, current.tsIgnore),
200
- safety: Math.min(safetyCeiling(budget, current.rules["anti-slop/require-safety-comment-for-type-assertion"] ?? 0), current.safety)
201
- };
202
- }
203
- /**
204
- * Fails each budget key whose count in the working tree is above its ceiling,
205
- * listing the suppressions in the files this change touches (all of them when
206
- * it touches none). SAFETY comments may also use the room the
207
- * directives disabling the SAFETY rule leave below their ceiling. `update`
208
- * lowers every ceiling to its current count, moving that room to `safety`;
209
- * no command ever raises the two together.
210
- */
211
- function checkSuppressions(root, update = false) {
212
- const path = join(root, SUPPRESSIONS_FILE);
213
- if (!existsSync(path)) throw new Error(`${SUPPRESSIONS_FILE} is missing. Run antelopejs-sync.`);
214
- const budget = parseBudget(readFileSync(path, "utf8"), SUPPRESSIONS_FILE);
215
- const suppressions = worktreeSuppressions(root);
216
- const counts = countSuppressions(suppressions);
217
- const changed = changedFiles(root);
218
- const failures = [];
219
- for (const [key, found] of groupByKey(suppressions)) {
220
- const limit = found[0].kind === "safety" ? safetyCeiling(budget, counts.rules["anti-slop/require-safety-comment-for-type-assertion"] ?? 0) : limitOf(budget, found[0]);
221
- if (found.length <= limit) continue;
222
- const inChanged = found.filter(({ file }) => changed.has(file));
223
- const shown = inChanged.length ? inChanged : found;
224
- failures.push(`${SUPPRESSIONS_FILE}: ${key}: ${found.length} exceeds ceiling ${limit}.`, ...shown.map(({ file, line }) => ` ${file}:${line}`), ...shown.length < found.length ? [` ...and ${found.length - shown.length} in files this change does not touch.`] : []);
225
- }
226
- if (update) writeFileSync(path, formatBudget(lowered(budget, counts)));
227
- return failures.length ? [...failures, SUPPRESSION_FIX] : [];
228
- }
229
- function budgetAt(root, revision) {
230
- const result = spawnSync("git", ["show", `${revision}:${SUPPRESSIONS_FILE}`], {
231
- cwd: root,
232
- encoding: "utf8"
233
- });
234
- return result.status === 0 ? parseBudget(result.stdout, `${revision || "index"}:${SUPPRESSIONS_FILE}`) : void 0;
235
- }
236
- function stagedNames(root, filter) {
237
- return execFileSync("git", [
238
- "diff",
239
- "--cached",
240
- "--name-only",
241
- "--find-renames",
242
- `--diff-filter=${filter}`,
243
- "-z"
244
- ], {
245
- cwd: root,
246
- encoding: "utf8"
247
- }).split("\0").filter(Boolean);
248
- }
249
- /**
250
- * Compares the staged files' suppressions with those files at HEAD, rename
251
- * sources and deleted files included, and fails each key that rises by more
252
- * than the staged budget raises its ceiling, then applies the suppression
253
- * policy to what the commit adds. A commit that first adds the budget is
254
- * not compared.
255
- */
256
- function stagedSuppressions(root) {
257
- const renames = renamedPaths(root, true);
258
- const staged = stagedNames(root, "ACMR");
259
- const previous = [...staged.map((file) => renames.get(file) ?? file), ...stagedNames(root, "D")];
260
- return [...stagedBudget(root, staged, previous), ...checkStagedPolicy(root, staged, previous)];
261
- }
262
- function stagedBudget(root, staged, previous) {
263
- const head = budgetAt(root, "HEAD");
264
- if (head === void 0) return [];
265
- const index = budgetAt(root, "") ?? head;
266
- const before = groupByKey(revisionSuppressions(root, "HEAD", previous));
267
- const after = groupByKey(revisionSuppressions(root, "", staged));
268
- const additions = stagedAdditions(root, [...new Set([...after.values()].flat().map(({ file }) => file))]);
269
- const failures = [];
270
- const safetyRule = `lint rule \`${SAFETY_RULE}\``;
271
- const converted = Math.max(0, (before.get(safetyRule)?.length ?? 0) - (after.get(safetyRule)?.length ?? 0));
272
- const freed = (head.rules["anti-slop/require-safety-comment-for-type-assertion"] ?? 0) - (index.rules["anti-slop/require-safety-comment-for-type-assertion"] ?? 0);
273
- for (const [key, found] of after) {
274
- const rise = found.length - (before.get(key)?.length ?? 0);
275
- const raised = limitOf(index, found[0]) - limitOf(head, found[0]);
276
- if (rise <= (found[0].kind === "safety" ? converted + Math.max(0, raised - Math.max(0, freed)) : Math.max(0, raised))) continue;
277
- const added = found.filter(({ file, line }) => additions.get(file)?.some(({ start, end }) => line >= start && line <= end));
278
- failures.push(`${key}: this commit adds ${rise} to the staged files.`, ...(added.length ? added : found).map(({ file, line }) => ` ${file}:${line}`));
279
- }
280
- return failures.length ? [...failures, SUPPRESSION_FIX] : [];
281
- }
282
- //#endregion
283
- export { parseBudget as a, checkPolicy as c, checkSuppressions as i, SUPPRESSIONS_FILE as n, safetyCeiling as o, adoptedBudget as r, stagedSuppressions as s, SAFETY_RULE as t };