@antelopejs/tooling-configs 0.2.7 → 0.2.9
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 +31 -18
- package/dist/bin/api-diff.mjs +15 -8
- package/dist/bin/check-size.mjs +4 -3
- package/dist/bin/checks.mjs +2 -1
- package/dist/bin/comment-proof.mjs +3 -2
- package/dist/bin/garden.d.mts +1 -0
- package/dist/bin/garden.mjs +1480 -0
- package/dist/bin/ratchet.mjs +4 -3
- package/dist/bin/suppressions.mjs +11 -5
- package/dist/bin/sync.mjs +37 -34
- package/dist/ci-workflow-BDy6hQJ6.mjs +164 -0
- package/dist/cli-4Tv71vYk.mjs +19 -0
- package/dist/{files-BMxKg5IR.mjs → files-2FikHZ9F.mjs} +1 -11
- package/dist/{ratchet-zzo2tT74.mjs → ratchet-B2qYUs51.mjs} +3 -3
- package/dist/{size-Fp3aWSkN.mjs → size-BVgNbLO6.mjs} +1 -1
- package/dist/{staged-ratchet-CJHjp2kx.mjs → staged-ratchet-BNfjcbih.mjs} +1 -1
- package/dist/suppression-budget-Bq30tJDS.mjs +282 -0
- package/dist/{suppressions-CgGa-kh7.mjs → suppressions-BJAngUxo.mjs} +104 -18
- package/dist/{typescript-DIXhKgXR.mjs → typescript-C54ONh9m.mjs} +63 -14
- package/package.json +2 -1
- package/dist/suppression-budget-N5ONsh2g.mjs +0 -144
package/README.md
CHANGED
|
@@ -17,22 +17,33 @@ The AntelopeJS guardrail pack: shared lint, format and dead-code presets, the co
|
|
|
17
17
|
|
|
18
18
|
## What's in the box
|
|
19
19
|
|
|
20
|
-
| Export | Import | What it gives
|
|
21
|
-
| ------------------ | ------------------------------------------------------------------------- |
|
|
22
|
-
| `./oxc/lint` | `import { antelopePreset } from "@antelopejs/tooling-configs/oxc/lint"` | The oxlint preset
|
|
23
|
-
| `./oxc/fmt` | `import { antelopeFmtPreset } from "@antelopejs/tooling-configs/oxc/fmt"` | The oxfmt preset (house style)
|
|
24
|
-
| `./eslint` | `import { antelopeNuxtConfig } from "@antelopejs/tooling-configs/eslint"` | ESLint for Nuxt layers
|
|
25
|
-
| `./knip` | `import { antelopeKnipConfig } from "@antelopejs/tooling-configs/knip"` | Knip for AntelopeJS modules
|
|
26
|
-
| `./oxc/anti-slop` | Loaded by the oxlint preset as a JS plugin | The vendored [anti-slop](https://github.com/dmmulroy/anti-slop) rules
|
|
27
|
-
| `./oxc/guardrails` | Loaded by the oxlint preset as a JS plugin | The `antelopejs` comment and test-quality rules
|
|
28
|
-
| bin | `antelopejs-sync` | Writes the guardrail pack into a repository; `--check` reports drift
|
|
29
|
-
| bin | `antelopejs-checks` | Runs every check and prints only the failures
|
|
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
|
|
32
|
-
| bin | `antelopejs-check-size` | Fails on authored files over 20,000 bytes and on blanket disable directives
|
|
33
|
-
| bin | `antelopejs-api-diff <base-ref>` | Compares published declaration bundles against committed HEAD
|
|
34
|
-
| bin | `antelopejs-comment-proof <base-ref>` | Compares comment-free JavaScript emit against committed HEAD
|
|
35
|
-
| bin | `antelopejs-check-interface-ranges` | Fails on interface ranges that break module startup
|
|
20
|
+
| Export | Import | What it gives |
|
|
21
|
+
| ------------------ | ------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------- |
|
|
22
|
+
| `./oxc/lint` | `import { antelopePreset } from "@antelopejs/tooling-configs/oxc/lint"` | The oxlint preset |
|
|
23
|
+
| `./oxc/fmt` | `import { antelopeFmtPreset } from "@antelopejs/tooling-configs/oxc/fmt"` | The oxfmt preset (house style) |
|
|
24
|
+
| `./eslint` | `import { antelopeNuxtConfig } from "@antelopejs/tooling-configs/eslint"` | ESLint for Nuxt layers |
|
|
25
|
+
| `./knip` | `import { antelopeKnipConfig } from "@antelopejs/tooling-configs/knip"` | Knip for AntelopeJS modules |
|
|
26
|
+
| `./oxc/anti-slop` | Loaded by the oxlint preset as a JS plugin | The vendored [anti-slop](https://github.com/dmmulroy/anti-slop) rules |
|
|
27
|
+
| `./oxc/guardrails` | Loaded by the oxlint preset as a JS plugin | The `antelopejs` comment and test-quality rules |
|
|
28
|
+
| bin | `antelopejs-sync` | Writes the guardrail pack into a repository; `--check` reports drift |
|
|
29
|
+
| bin | `antelopejs-checks` | Runs every check and prints only the failures |
|
|
30
|
+
| bin | `antelopejs-ratchet` | Fails when recorded debt grows; `--update` lowers the record |
|
|
31
|
+
| bin | `antelopejs-suppressions` | Fails when suppressions exceed their budget or an added one breaks policy; `--update` lowers the budget |
|
|
32
|
+
| bin | `antelopejs-check-size` | Fails on authored files over 20,000 bytes and on blanket disable directives |
|
|
33
|
+
| bin | `antelopejs-api-diff <base-ref>` | Compares published declaration bundles against committed HEAD |
|
|
34
|
+
| bin | `antelopejs-comment-proof <base-ref>` | Compares comment-free JavaScript emit against committed HEAD |
|
|
35
|
+
| bin | `antelopejs-check-interface-ranges` | Fails on interface ranges that break module startup |
|
|
36
|
+
| bin | `antelopejs-garden [--json] [--apply-pauses]` | The Gardener's scans of the organization through the GitHub API and npm |
|
|
37
|
+
|
|
38
|
+
## antelopejs-garden
|
|
39
|
+
|
|
40
|
+
`antelopejs-garden` is the Gardener's deterministic scan. It reads the non-archived AntelopeJS repositories whose `pack` property is `full` or `template` and whose `tier` is N1 to N3, through the GitHub API and the npm registry, authenticated with the token `gh` is logged in with. It never clones.
|
|
41
|
+
|
|
42
|
+
- `--json` prints `{ generatedAt, findings, pauses, skipped }`. A finding is `{ key, repo, check, subject, severity, evidence, doneMeans }` with the key `repo|check|subject`, sorted. `skipped` lists every check whose source does not exist yet, or that could not run.
|
|
43
|
+
- Without `--json` it prints failures only. The exit code is non-zero only when a check could not run.
|
|
44
|
+
- `--apply-pauses` sets the repository variable `NEXT_AUTOMERGE` to `shadow` on repositories where it is `on`, when `checks` is red on `next`, the ratchet file is back on a Clean repository, or governance drifted. It never sets `on` and writes nothing else.
|
|
45
|
+
|
|
46
|
+
`antelopejs-sync` (full profile) writes the weekly mutation caller `.github/workflows/mutation.yml`, and both profiles keep the shared CI caller on the job id `ci`, so the check is reported as `ci / checks`.
|
|
36
47
|
|
|
37
48
|
## Install
|
|
38
49
|
|
|
@@ -198,9 +209,11 @@ When every rule count is zero and `oversizeFiles` is empty, the ratchet is retir
|
|
|
198
209
|
- `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
210
|
- `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
211
|
- `antelopejs-suppressions --update` lowers each ceiling to the current count and keeps rules at zero. No command raises a ceiling.
|
|
212
|
+
- `SAFETY:` comments and directives disabling `anti-slop/require-safety-comment-for-type-assertion` share their room: a `SAFETY:` comment may use what those directives leave below their ceiling, in the full, base and staged checks, and `--update` moves that room to `safety`. Replacing such a directive with a `SAFETY:` comment needs no raise; their sum never rises.
|
|
201
213
|
- `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
214
|
- 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
215
|
- `@ts-ignore` is also a lint error (`typescript/ban-ts-comment`); `@ts-expect-error` fails once its error is gone.
|
|
216
|
+
- Both modes also judge what the change adds, whatever the budget allows: the full check against the same base (HEAD when there is none), the staged check against HEAD. A suppression counts as added when its kind, rule and reason occur more often than on the base, so one moved to another file with its reason is not added, and one whose reason a comment pass rewrote or stripped is. An added directive fails when it names a rule no directive may name (`anti-slop/require-safety-comment-for-type-assertion`, `antelopejs/no-comments`, the four `antelopejs` test rules, `typescript/ban-ts-comment`); the failure names what to do instead. An added directive naming its rules, `@ts-expect-error` or `SAFETY:` comment fails when its reason has fewer than three words, or only words like "safe", "intentional", "legacy" and the rule's own name. A block `oxlint-disable` or `eslint-disable` that no `-enable` closes before the end of its file fails when the change adds it. Suppressions already on the base stay under the budget until a burn-down removes them.
|
|
204
217
|
|
|
205
218
|
### Size
|
|
206
219
|
|
|
@@ -210,11 +223,11 @@ Pass paths to check only those files, as the pre-commit hook does. The command a
|
|
|
210
223
|
|
|
211
224
|
### Cleanup proof
|
|
212
225
|
|
|
213
|
-
A behaviour-preserving cleanup PR shows `antelopejs-api-diff <base-ref>` passing. It checks each tracked package with a `tsconfig.json` that publishes something (not private, and declaring `exports`, `main`, `types`, `typings` or `typesVersions`) and lists the others as `API: skipped <directory>, <reason>.`. Each package is analysed and bundled with its own installed TypeScript, falling back to the one `dts-bundle-generator` brings when the package
|
|
226
|
+
A behaviour-preserving cleanup PR shows `antelopejs-api-diff <base-ref>` passing. It checks each tracked package with a `tsconfig.json` that publishes something (not private, and declaring `exports`, `main`, `types`, `typings` or `typesVersions`) and lists the others as `API: skipped <directory>, <reason>.`. Each package is analysed and bundled with its own installed TypeScript, falling back to the one `dts-bundle-generator` brings only when neither the package nor its workspace root declares `typescript` (the proof then prints `<directory>: declares no typescript; using the pack's TypeScript <version>`). A package that declares `typescript` but cannot resolve it fails with an execution error naming the package and asking for an install, because its declaration half would otherwise pass on a broken install; a TypeScript without the programmatic compiler API (7 and later) is reported as an execution error naming the package, and the other packages are still analysed. Large packages are bundled by several worker processes (up to 8, bounded by cpus and free memory); the output is the same as a single process. It emits declarations without comments, resolves published entries from `exports` (preferring `types`), `main`, `types`/`typings` and `typesVersions`, and bundles each entry's local declaration closure. External packages stay external. Stable top-level ordering ignores declaration moves between internal files while preserving overload order. Members of object type literals, interfaces and classes are compared in a canonical order, because TypeScript can emit an inferred object type's properties in another order after a refactor; overloads, call and construct signatures, tuple elements, parameters, enum members and union constituents keep their written order. Compiler errors fail the proof.
|
|
214
227
|
|
|
215
228
|
A comment-only PR shows `antelopejs-comment-proof <base-ref>` passing instead of a verifier. It includes private packages, ignores type diagnostics and compares comment-free JavaScript emit byte for byte. Both commands exclude test sources, fail on added or removed outputs, and print unified diffs for changes.
|
|
216
229
|
|
|
217
|
-
Pass `--allow-added <glob>` (repeatable) to `antelopejs-api-diff` when a refactor adds helper files that a wildcard export publishes, such as an `internal/` directory under `"./*"`. An added entry passes, in both the declaration and the runtime half, when its published subpath matches a glob (for example `--allow-added '**/internal/**'`, matched against `base/table-view/internal/helper` for `./base/table-view/internal/helper`) and its source module is marked `@internal`: a leading `/** @internal @packageDocumentation */` comment on the module (`@module` and `@fileoverview` also qualify), or an `@internal` tag on every exported declaration. Allowed entries are printed under `Added (allowed): <count
|
|
230
|
+
Pass `--allow-added <glob>` (repeatable) to `antelopejs-api-diff` when a refactor adds helper files that a wildcard export publishes, such as an `internal/` directory under `"./*"`. An added entry passes, in both the declaration and the runtime half, when its published subpath matches a glob (for example `--allow-added '**/internal/**'`, matched against `base/table-view/internal/helper` for `./base/table-view/internal/helper`) and its source module is marked `@internal`: a leading `/** @internal @packageDocumentation */` comment on the module (`@module` and `@fileoverview` also qualify), or an `@internal` tag on every exported declaration. Allowed entries are printed under `Added (allowed): <count>`; nothing is printed when no entry was added. An added entry that matches but is not marked `@internal` fails with the file and the fix. Added entries matching no glob, removed entries and changed entries still fail, matching or not. Without the flag nothing changes.
|
|
218
231
|
|
|
219
232
|
```bash
|
|
220
233
|
pnpm exec antelopejs-api-diff origin/main --allow-added '**/internal/**'
|
package/dist/bin/api-diff.mjs
CHANGED
|
@@ -1,7 +1,8 @@
|
|
|
1
1
|
#!/usr/bin/env node
|
|
2
|
-
import {
|
|
2
|
+
import { t as runCli } from "../cli-4Tv71vYk.mjs";
|
|
3
|
+
import { o as repositoryRoot } from "../files-2FikHZ9F.mjs";
|
|
3
4
|
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-
|
|
5
|
+
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-C54ONh9m.mjs";
|
|
5
6
|
import { createRequire } from "node:module";
|
|
6
7
|
import { copyFileSync, cpSync, existsSync, mkdirSync, readFileSync, readdirSync, rmSync, symlinkSync, writeFileSync } from "node:fs";
|
|
7
8
|
import { basename, dirname, join, relative, resolve } from "node:path";
|
|
@@ -11,7 +12,10 @@ import { availableParallelism, freemem } from "node:os";
|
|
|
11
12
|
//#region src/guardrails/declaration-bundle.ts
|
|
12
13
|
const ENTRIES_PER_WORKER = 16;
|
|
13
14
|
const MAX_WORKERS = 8;
|
|
14
|
-
const
|
|
15
|
+
const MIB = 1024 ** 2;
|
|
16
|
+
const WORKER_MEMORY = 1536 * MIB;
|
|
17
|
+
/** Node options that keep a worker inside `WORKER_MEMORY`: the old-space cap leaves room for the memory V8 holds outside the heap, so a worker's resident size stays under the budget that `workerCount` assumes. */
|
|
18
|
+
const WORKER_NODE_ARGS = [`--max-old-space-size=${(WORKER_MEMORY - 256 * MIB) / MIB}`];
|
|
15
19
|
const WORKER = `
|
|
16
20
|
const { readFileSync, writeFileSync } = require("node:fs");
|
|
17
21
|
const { createRequire } = require("node:module");
|
|
@@ -26,11 +30,11 @@ try {
|
|
|
26
30
|
`;
|
|
27
31
|
const DRIVER = `
|
|
28
32
|
const { spawn } = require("node:child_process");
|
|
29
|
-
const [worker, ...jobs] = process.argv.slice(1);
|
|
33
|
+
const [flags, worker, ...jobs] = process.argv.slice(1);
|
|
30
34
|
let failed = false;
|
|
31
35
|
let pending = jobs.length;
|
|
32
36
|
for (const job of jobs) {
|
|
33
|
-
spawn(process.execPath, [worker, job], { stdio: ["ignore", "inherit", "inherit"] }).on("exit", (code) => {
|
|
37
|
+
spawn(process.execPath, [...JSON.parse(flags), worker, job], { stdio: ["ignore", "inherit", "inherit"] }).on("exit", (code) => {
|
|
34
38
|
failed ||= code !== 0;
|
|
35
39
|
pending -= 1;
|
|
36
40
|
if (pending === 0) process.exit(failed ? 1 : 0);
|
|
@@ -70,6 +74,7 @@ function generateInWorkers(loader, directory, entries, options, workers) {
|
|
|
70
74
|
const run = spawnSync(process.execPath, [
|
|
71
75
|
"-e",
|
|
72
76
|
DRIVER,
|
|
77
|
+
JSON.stringify(WORKER_NODE_ARGS),
|
|
73
78
|
worker,
|
|
74
79
|
...jobs.map(({ file }) => file)
|
|
75
80
|
], {
|
|
@@ -463,9 +468,10 @@ function generatorEntry(file) {
|
|
|
463
468
|
if (alias !== file) copyFileSync(file, alias);
|
|
464
469
|
return alias;
|
|
465
470
|
}
|
|
466
|
-
function bundlePackage(paths, manifest, policy) {
|
|
471
|
+
function bundlePackage(paths, manifest, policy, notices) {
|
|
467
472
|
const { directory, output, scratch } = paths;
|
|
468
473
|
const emitted = emitPackage(directory, scratch, true);
|
|
474
|
+
if (emitted.notice !== void 0) notices?.add(emitted.notice);
|
|
469
475
|
const entries = publishedEntries(directory, manifest, emitted, scratch);
|
|
470
476
|
if (!entries.length) return {
|
|
471
477
|
count: 0,
|
|
@@ -520,6 +526,7 @@ function bundlePackage(paths, manifest, policy) {
|
|
|
520
526
|
}
|
|
521
527
|
function declarationDiff(root, baseRef, policy) {
|
|
522
528
|
const errors = /* @__PURE__ */ new Set();
|
|
529
|
+
const notices = /* @__PURE__ */ new Set();
|
|
523
530
|
const failedPackages = /* @__PURE__ */ new Set();
|
|
524
531
|
const unpublished = /* @__PURE__ */ new Map();
|
|
525
532
|
const result = compareRevisions(root, baseRef, "API", (worktree, output, scratch) => {
|
|
@@ -536,7 +543,7 @@ function declarationDiff(root, baseRef, policy) {
|
|
|
536
543
|
directory: join(worktree, directory),
|
|
537
544
|
output: join(output, key),
|
|
538
545
|
scratch: join(scratch, key)
|
|
539
|
-
}, manifest, policy);
|
|
546
|
+
}, manifest, policy, notices);
|
|
540
547
|
entries += bundled.count;
|
|
541
548
|
published.push(...bundled.published);
|
|
542
549
|
} catch (error) {
|
|
@@ -556,7 +563,7 @@ function declarationDiff(root, baseRef, policy) {
|
|
|
556
563
|
}, policy);
|
|
557
564
|
return {
|
|
558
565
|
different: result.different || errors.size > 0,
|
|
559
|
-
output: (errors.size > 0 && !result.different ? result.output.replace(/^API:[^\n]*\n/u, "API: comparison incomplete due to execution errors.\n") : result.output) + [...unpublished].sort(([a], [b]) => a.localeCompare(b)).map(([directory, reason]) => `API: skipped ${directory}, ${reason}.\n`).join("") + [...errors].join("")
|
|
566
|
+
output: (errors.size > 0 && !result.different ? result.output.replace(/^API:[^\n]*\n/u, "API: comparison incomplete due to execution errors.\n") : result.output) + [...unpublished].sort(([a], [b]) => a.localeCompare(b)).map(([directory, reason]) => `API: skipped ${directory}, ${reason}.\n`).join("") + [...notices].sort().join("") + [...errors].join("")
|
|
560
567
|
};
|
|
561
568
|
}
|
|
562
569
|
/** Compares declarations and built runtime exports, with an optional behavioral probe captured before either build. Added entries whose subpath matches an `allowAdded` glob pass when their module is `@internal`. */
|
package/dist/bin/check-size.mjs
CHANGED
|
@@ -1,7 +1,8 @@
|
|
|
1
1
|
#!/usr/bin/env node
|
|
2
|
-
import {
|
|
3
|
-
import { t as
|
|
4
|
-
import {
|
|
2
|
+
import { t as runCli } from "../cli-4Tv71vYk.mjs";
|
|
3
|
+
import { a as repositoryPath, o as repositoryRoot, t as authoredSizes } from "../files-2FikHZ9F.mjs";
|
|
4
|
+
import { t as checkSize } from "../size-BVgNbLO6.mjs";
|
|
5
|
+
import { a as revisionSuppressions, o as worktreeSuppressions } from "../suppressions-BJAngUxo.mjs";
|
|
5
6
|
import { resolve } from "node:path";
|
|
6
7
|
import { parseArgs } from "node:util";
|
|
7
8
|
//#region src/guardrails/directives.ts
|
package/dist/bin/checks.mjs
CHANGED
|
@@ -1,6 +1,7 @@
|
|
|
1
1
|
#!/usr/bin/env node
|
|
2
2
|
import "../ceilings-BSw9p4YB.mjs";
|
|
3
|
-
import {
|
|
3
|
+
import { t as runCli } from "../cli-4Tv71vYk.mjs";
|
|
4
|
+
import { o as repositoryRoot } from "../files-2FikHZ9F.mjs";
|
|
4
5
|
import { i as parseManifest, r as packageManager } from "../package-Dtjt_lSa.mjs";
|
|
5
6
|
import { existsSync, readFileSync } from "node:fs";
|
|
6
7
|
import { join } from "node:path";
|
|
@@ -1,6 +1,7 @@
|
|
|
1
1
|
#!/usr/bin/env node
|
|
2
|
-
import {
|
|
3
|
-
import {
|
|
2
|
+
import { t as runCli } from "../cli-4Tv71vYk.mjs";
|
|
3
|
+
import { o as repositoryRoot } from "../files-2FikHZ9F.mjs";
|
|
4
|
+
import { c as revisionCounts, i as packagesAt, s as compareRevisions, t as emitPackage } from "../typescript-C54ONh9m.mjs";
|
|
4
5
|
import { copyFileSync, mkdirSync } from "node:fs";
|
|
5
6
|
import { dirname, join, relative } from "node:path";
|
|
6
7
|
//#region src/guardrails/comment-proof.ts
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
export {}
|