@antelopejs/tooling-configs 0.7.2 → 0.7.3

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
@@ -23,28 +23,28 @@ The AntelopeJS guardrail pack: shared lint, format and dead-code presets, the co
23
23
 
24
24
  ## What's in the box
25
25
 
26
- | Export | Import | What it gives |
27
- | ------------------ | ------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- |
28
- | `./oxc/lint` | `import { antelopePreset } from "@antelopejs/tooling-configs/oxc/lint"` | The oxlint preset |
29
- | `./oxc/fmt` | `import { antelopeFmtPreset } from "@antelopejs/tooling-configs/oxc/fmt"` | The oxfmt preset (house style) |
30
- | `./eslint` | `import { antelopeNuxtConfig } from "@antelopejs/tooling-configs/eslint"` | ESLint for Nuxt layers |
31
- | `./knip` | `import { antelopeKnipConfig } from "@antelopejs/tooling-configs/knip"` | Knip for AntelopeJS modules |
32
- | `./oxc/anti-slop` | Loaded by the oxlint preset as a JS plugin | The vendored [anti-slop](https://github.com/dmmulroy/anti-slop) rules |
33
- | `./oxc/guardrails` | Loaded by the oxlint preset as a JS plugin | The `antelopejs` comment and test-quality rules |
34
- | `./verify` | `import type { VerifyConfig } from "@antelopejs/tooling-configs/verify"` | Types and check helpers for a shared verification skill's `verify.config.ts` |
35
- | bin | `antelopejs-sync [--init]` | Writes the guardrail pack into a repository; `--check` reports drift; `--init` onboards a bare repository |
36
- | bin | `antelopejs-checks [--no-services]` | Runs every check and prints only the failures; starts `.github/compose.yml` services around them |
37
- | bin | `antelopejs-ratchet` | Fails when recorded debt grows; `--update` lowers the record and adopts rules a pack release newly enabled |
38
- | bin | `antelopejs-suppressions` | Fails when suppressions exceed their budget or an added one breaks policy; `--update` lowers the budget |
39
- | bin | `antelopejs-check-size` | Fails on authored files over 20,000 bytes and on blanket disable directives |
40
- | bin | `antelopejs-api-diff <base-ref>` | Compares published declaration bundles against committed HEAD |
41
- | bin | `antelopejs-comment-proof <base-ref>` | Compares comment-free JavaScript emit against committed HEAD |
42
- | bin | `antelopejs-body-check <body.md \| -> [--head <sha>] [--base <sha>]` | Checks a PR body's proof and findings blocks against HEAD; `--findings` prints the findings block |
43
- | bin | `antelopejs-readme-strip --kind <kind> --name <label-name>` | Writes a framework repository's README strip banner to `.github/readme/strip.svg` ([docs](docs/documentation-checks.md#framework-strip-banner)) |
44
- | bin | `antelopejs-garden [--json] [--apply] [--apply-prunes]` | The Gardener's scans of the organization through the GitHub API and npm |
45
- | bin | `antelopejs-triage [--json]` | Community Triage's ranked shortlist of untriaged issues |
46
- | bin | `antelopejs-verify <command>` | The harness of the shared `verify-interface`, `verify-module` and `verify-template` skills |
47
- | bin | `antelopejs-lease run \| status \| down \| gc` | Ports, a mongod, logs and tmp per worktree; see [Run a DMS from a git worktree](./docs/agent-worktrees.md) |
26
+ | Export | Import | What it gives |
27
+ | ------------------ | ------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------- |
28
+ | `./oxc/lint` | `import { antelopePreset } from "@antelopejs/tooling-configs/oxc/lint"` | The oxlint preset |
29
+ | `./oxc/fmt` | `import { antelopeFmtPreset } from "@antelopejs/tooling-configs/oxc/fmt"` | The oxfmt preset (house style) |
30
+ | `./eslint` | `import { antelopeNuxtConfig } from "@antelopejs/tooling-configs/eslint"` | ESLint for Nuxt layers |
31
+ | `./knip` | `import { antelopeKnipConfig } from "@antelopejs/tooling-configs/knip"` | Knip for AntelopeJS modules |
32
+ | `./oxc/anti-slop` | Loaded by the oxlint preset as a JS plugin | The vendored [anti-slop](https://github.com/dmmulroy/anti-slop) rules |
33
+ | `./oxc/guardrails` | Loaded by the oxlint preset as a JS plugin | The `antelopejs` comment and test-quality rules |
34
+ | `./verify` | `import type { VerifyConfig } from "@antelopejs/tooling-configs/verify"` | Types and check helpers for a shared verification skill's `verify.config.ts` |
35
+ | bin | `antelopejs-sync [--init]` | Writes the guardrail pack into a repository; `--check` reports drift; `--init` onboards a bare repository |
36
+ | bin | `antelopejs-checks [--no-services]` | Runs every check and prints only the failures and the errors `published:types` declares as known; starts `.github/compose.yml` services around them |
37
+ | bin | `antelopejs-ratchet` | Fails when recorded debt grows; `--update` lowers the record and adopts rules a pack release newly enabled |
38
+ | bin | `antelopejs-suppressions` | Fails when suppressions exceed their budget or an added one breaks policy; `--update` lowers the budget |
39
+ | bin | `antelopejs-check-size` | Fails on authored files over 20,000 bytes and on blanket disable directives |
40
+ | bin | `antelopejs-api-diff <base-ref>` | Compares published declaration bundles against committed HEAD |
41
+ | bin | `antelopejs-comment-proof <base-ref>` | Compares comment-free JavaScript emit against committed HEAD |
42
+ | bin | `antelopejs-body-check <body.md \| -> [--head <sha>] [--base <sha>]` | Checks a PR body's proof and findings blocks against HEAD; `--findings` prints the findings block |
43
+ | bin | `antelopejs-readme-strip --kind <kind> --name <label-name>` | Writes a framework repository's README strip banner to `.github/readme/strip.svg` ([docs](docs/documentation-checks.md#framework-strip-banner)) |
44
+ | bin | `antelopejs-garden [--json] [--apply] [--apply-prunes]` | The Gardener's scans of the organization through the GitHub API and npm |
45
+ | bin | `antelopejs-triage [--json]` | Community Triage's ranked shortlist of untriaged issues |
46
+ | bin | `antelopejs-verify <command>` | The harness of the shared `verify-interface`, `verify-module` and `verify-template` skills |
47
+ | bin | `antelopejs-lease run \| status \| down \| gc` | Ports, a mongod, logs and tmp per worktree; see [Run a DMS from a git worktree](./docs/agent-worktrees.md) |
48
48
 
49
49
  ## antelopejs-garden
50
50
 
@@ -234,7 +234,21 @@ pnpm install
234
234
 
235
235
  `--profile template` writes only what `antelopejs-checks` runs, for template repositories: the three preset configs, `.gitattributes`, in a pnpm template the `pnpm-workspace.yaml` exclusion `lockfile:singletons` needs (see below) without `allowBuilds`, a user-facing `AGENTS.md` block, `guardrails.suppressions.json`, and the `package.json` scripts and devDependencies of the table above without the hooks (no `prepare`, no `lefthook`). It sets `checks`, `size`, `suppressions` and `suppressions:update`, plus `ratchet` and `ratchet:update` once `guardrails.ratchet.json` exists. It adds `typecheck`, `lint`, `format`, `format:check`, `knip`, `sync` and `sync:check` only where the template has none, the sync scripts with `--profile template`. It writes no `guardrails.ratchet.json`. The agent layer, `verify-template` and the writing skills under `.agents/skills/` with their `.claude/skills` links, is synced and checked only in the template source, marked by its `.agents/skills/verify-template/` folder; a project scaffolded from the template ships without it, so the template's `AGENTS.md` block links no skill under `.agents/` or `.claude/skills/`. `antelopejs-sync --check` writes nothing and exits 1 on any drift; `pnpm run checks` runs it.
236
236
 
237
- `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 `guardrails.ratchet.json` exists. When the repository has a verify layer, an `.agents/skills/verify-*` folder holding a `verify.config.ts` or a `tsconfig.json`, it also runs `verify:types` and `verify:lockfiles`, which need no package script. Neither writes a file in the repository, spawns a package manager or fetches anything, so both pass offline after a root install, as CI runs them. When the repository holds a `pnpm-lock.yaml`, outside what `.gitignore` leaves out, it also runs `lockfile:singletons`, which fails when a lockfile resolves an `@antelopejs/interface-*` package at more than one version and names the importers and packages that pull each copy. It reads the lockfiles only. Sync lists `@antelopejs/interface-*` under `minimumReleaseAgeExclude` in a pnpm repository's `pnpm-workspace.yaml`, and in the `pnpm-workspace.yaml` of each folder with its own `pnpm-lock.yaml`, and of each `playground` with a `package.json` that no workspace above lists, before its first install: pnpm installs that folder as a workspace of its own and does not read the root's file. It writes these nested files in a repository whose root npm installs too, there only in folders pnpm installs: one with a `pnpm-lock.yaml`, or a playground with no lockfile and no `package-lock.json` above it. A root that sets no `packageManager` counts as pnpm's unless it holds a `package-lock.json`, `npm-shrinkwrap.json`, `yarn.lock`, `bun.lock` or `bun.lockb` and no `pnpm-lock.yaml`. Without it, pnpm 11 and later resolve each range to an interface release more than a day old where the range admits one, so an install in the day after an interface release locks two copies. When a tracked `package.json` declares an `@antelopejs/*` package, it also runs `dependency:ranges` (see [Dependency ranges](#dependency-ranges)), which reads the manifests, and from the registry the `latest` dist-tag of each `@antelopejs/interface-*` package they take and the newest release of each DMS module. In a git checkout it also runs `git:identity`, which fails when the repository's own git config, the `.git/config` every worktree shares or a worktree's `config.worktree`, sets `user.name` or `user.email`, and names the file and value. An identity from the global config or a `git -c` passes. When the `README.md` of the root or of a workspace package holds a config example whose `package` is an `@antelopejs/*` package, such as `source: { type: "package", package: "@antelopejs/brevo", version: ">=0.0.9 <0.1.0" }`, it also runs `readme:version`. It fails when that example's `version` range does not stop below the next minor of the package's newest version and admit it, as [Dependency ranges](#dependency-ranges) reads a range, and names the README line and the range to use. The newest version of a package of the repository is the `version` in its `package.json`. For any other package it is the `latest` dist-tag on the registry npm is configured with, and the step fails when it cannot read it. A value that is not a range, such as `latest`, passes. When the root or a workspace package is not `private` and names declarations through `types`, `typings` or `exports`, it also runs `published:types`, after `test` and alone. It runs each such package's `prepack` through `pnpm run` or `npm run`, then packs it with lifecycle scripts off, so `prepare` and `postpack` do not run. It installs the tarball alone in a scratch folder without install scripts, together with the package's peers (optional ones included), `typescript` and `@types/node`, both at their latest version unless the package names them as peers. A workspace package it depends on comes from that package's own tarball, not from the registry. Then it runs `tsc` with `skipLibCheck: false`, `strict` and `nodenext` resolution over a file that imports each entry the package's `exports` names, a `*` subpath once per shipped file it matches. A package without `exports` gets its bare name and every declaration file it ships instead. The step fails on any error and names each file as `<package>/<path>`. It needs the registry, so it fails offline unless the package manager's store already holds what the install needs.
237
+ `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, and the errors `published:types` declares as known. Sync adds the ratchet scripts and pre-commit hook only while `guardrails.ratchet.json` exists. When the repository has a verify layer, an `.agents/skills/verify-*` folder holding a `verify.config.ts` or a `tsconfig.json`, it also runs `verify:types` and `verify:lockfiles`, which need no package script. Neither writes a file in the repository, spawns a package manager or fetches anything, so both pass offline after a root install, as CI runs them. When the repository holds a `pnpm-lock.yaml`, outside what `.gitignore` leaves out, it also runs `lockfile:singletons`, which fails when a lockfile resolves an `@antelopejs/interface-*` package at more than one version and names the importers and packages that pull each copy. It reads the lockfiles only. Sync lists `@antelopejs/interface-*` under `minimumReleaseAgeExclude` in a pnpm repository's `pnpm-workspace.yaml`, and in the `pnpm-workspace.yaml` of each folder with its own `pnpm-lock.yaml`, and of each `playground` with a `package.json` that no workspace above lists, before its first install: pnpm installs that folder as a workspace of its own and does not read the root's file. It writes these nested files in a repository whose root npm installs too, there only in folders pnpm installs: one with a `pnpm-lock.yaml`, or a playground with no lockfile and no `package-lock.json` above it. A root that sets no `packageManager` counts as pnpm's unless it holds a `package-lock.json`, `npm-shrinkwrap.json`, `yarn.lock`, `bun.lock` or `bun.lockb` and no `pnpm-lock.yaml`. Without it, pnpm 11 and later resolve each range to an interface release more than a day old where the range admits one, so an install in the day after an interface release locks two copies. When a tracked `package.json` declares an `@antelopejs/*` package, it also runs `dependency:ranges` (see [Dependency ranges](#dependency-ranges)), which reads the manifests, and from the registry the `latest` dist-tag of each `@antelopejs/interface-*` package they take and the newest release of each DMS module. In a git checkout it also runs `git:identity`, which fails when the repository's own git config, the `.git/config` every worktree shares or a worktree's `config.worktree`, sets `user.name` or `user.email`, and names the file and value. An identity from the global config or a `git -c` passes. When the `README.md` of the root or of a workspace package holds a config example whose `package` is an `@antelopejs/*` package, such as `source: { type: "package", package: "@antelopejs/brevo", version: ">=0.0.9 <0.1.0" }`, it also runs `readme:version`. It fails when that example's `version` range does not stop below the next minor of the package's newest version and admit it, as [Dependency ranges](#dependency-ranges) reads a range, and names the README line and the range to use. The newest version of a package of the repository is the `version` in its `package.json`. For any other package it is the `latest` dist-tag on the registry npm is configured with, and the step fails when it cannot read it. A value that is not a range, such as `latest`, passes. When the root or a workspace package is not `private` and names declarations through `types`, `typings` or `exports`, it also runs `published:types`, after `test` and alone. It runs each such package's `prepack` through `pnpm run` or `npm run`, then packs it with lifecycle scripts off, so `prepare` and `postpack` do not run. It installs the tarball alone in a scratch folder without install scripts, together with the package's peers (optional ones included), `typescript` and `@types/node`, both at their latest version unless the package names them as peers. A workspace package it depends on comes from that package's own tarball, not from the registry. Then it runs `tsc` with `skipLibCheck: false`, `strict` and `nodenext` resolution over a file that imports each entry the package's `exports` names, a `*` subpath once per shipped file it matches. A package without `exports` gets its bare name and every declaration file it ships instead. The step fails on any error and names each file as `<package>/<path>`. An error inside the declarations of a dependency the repository does not publish, which the repository cannot fix, is declared in `guardrails.published-types.json` at the root, by the dependency, the file inside it and the code tsc prints:
238
+
239
+ ```json
240
+ {
241
+ "knownFailures": [
242
+ {
243
+ "dependency": "rethinkdb-ts",
244
+ "file": "lib/response/cursor.d.ts",
245
+ "code": "TS2416"
246
+ }
247
+ ]
248
+ }
249
+ ```
250
+
251
+ An entry matches every error with that code in that file, at any line. The step prints each matched error under `errors guardrails.published-types.json declares as known` whether it passes or fails, and passes when every error it found is declared. An error in a package of the repository, or in a file or with a code no entry names, still fails, and an entry may not name a package of the repository. Once tsc ran over every package, an entry that matched no error fails with `<dependency>/<file> <code> no longer occurs. Remove the entry.`, so the entry goes when the dependency fixes its declarations. When the step runs, a malformed file, an entry with a path tsc does not print (such as `./lib/x.d.ts`) or a repeated entry fails it before anything is packed. It needs the registry, so it fails offline unless the package manager's store already holds what the install needs.
238
252
 
239
253
  - `verify:types` type-checks each layer's own code with the repository's own TypeScript, run as `node <typescript>/bin/tsc` without a shell. A repository that installs the TypeScript 6 API as `typescript` (`npm:@typescript/typescript6`) for tools that need it, beside TypeScript 7 as `@typescript/native`, runs `@typescript/native`'s `tsc`. The files are those the layer's `tsconfig.json` includes, minus its `playground` folder and any `node_modules` or `dist` folder: verify compiles a playground itself, with the playground's own config, after installing it. The step writes a config to the system temp folder that extends the layer's, lists those files, keeps the layer's type roots, sets `noEmit` and unsets with `null` the `declaration`, `composite`, `incremental`, `tsBuildInfoFile`, `declarationDir`, `declarationMap`, `emitDeclarationOnly` and `isolatedDeclarations` the layer may inherit, then deletes it. No `.tsbuildinfo` is written, no declaration check runs on code that is never emitted, and `skipLibCheck` keeps the layer's value. `antelopejs-sync` writes the `tsconfig.json` of the shared `verify-interface`, `verify-module` and `verify-template` layers; a repository's own layer, such as a `verify-dms-*` one, keeps the one it wrote. A layer with a `verify.config.ts` and no `tsconfig.json` fails, and so does one whose `tsconfig.json` does not include its `verify.config.ts`.
240
254
  - `verify:lockfiles` compares, in code, the direct dependencies each lockfile records with the `package.json` files it locks, and fails on a difference in either direction, naming the dependency and the command that regenerates the lockfile. It reads each lockfile in a folder under a layer, `node_modules` and `dist` aside, and in the root `playground`. A `pnpm-lock.yaml` is compared importer by importer, for each importer it lists that has a `package.json` on disk; a `package-lock.json` by its root entry. Only `dependencies`, `devDependencies` and `optionalDependencies` are compared, by name and specifier: a name counts as present whichever of the three fields records it, and a `catalog:` or `workspace:` specifier compares as written, as pnpm stores it. A name the lockfile records that `package.json` declares only in `peerDependencies` passes, whether or not peers are auto-installed. A name an override selector in the `pnpm-lock.yaml` mentions is not compared, nor is a `link:` dependency the lockfile leaves out under `excludeLinksFromLockfile`. A lockfile it cannot parse, or of a version before pnpm's 6 or npm's 2, fails as unreadable. A missing lockfile fails only in a layer's `playground` or the root `playground` whose `package.json` has dependencies, unless a folder above it holds a `pnpm-workspace.yaml` or a `package.json` with `workspaces`; the fix it names is npm's when a `package-lock.json` sits in a folder above, pnpm's otherwise. It does not check workspace membership, `overrides`, lockfile `settings`, catalogs, `.npmrc` or user configuration, resolved versions, integrity hashes, transitive entries, npm workspace members, or `yarn.lock` and `bun.lock`: verify's own frozen install still rejects a lockfile stale there.
@@ -1,7 +1,7 @@
1
1
  #!/usr/bin/env node
2
2
  import { n as runCliAsync } from "../cli-4Tv71vYk.mjs";
3
3
  import { c as repositoryRoot } from "../files-C-JJhExM.mjs";
4
- import { r as runChecks, t as CHECKS_SKIP_ENV } from "../checks-DvND3Ngb.mjs";
4
+ import { r as runChecks, t as CHECKS_SKIP_ENV } from "../checks-CSlWvky1.mjs";
5
5
  import { parseArgs } from "node:util";
6
6
  //#region src/bin/checks.ts
7
7
  const SIGNAL_EXIT = /* @__PURE__ */ new Map([
package/dist/bin/sync.mjs CHANGED
@@ -9,7 +9,7 @@ import { _ as placeholderTestScript, f as CI_CONTEXT, g as ciWorkflow, i as hasC
9
9
  import { a as gitFiles, c as repositoryRoot } from "../files-C-JJhExM.mjs";
10
10
  import { n as workspaceDirectories, r as workspacePatterns, t as planDocs } from "../docs-compat-BAZiPLZt.mjs";
11
11
  import { n as shimInvocation } from "../run-command-BlFRPORx.mjs";
12
- import { a as stepsOf, c as installsWithPnpm, d as runPnpm, i as matchingScripts, l as verifyLayers, n as droppedChecksSteps, o as pnpmLockfiles, s as inWorkspace, u as moveDependencyRanges } from "../checks-DvND3Ngb.mjs";
12
+ import { a as stepsOf, c as installsWithPnpm, d as runPnpm, i as matchingScripts, l as verifyLayers, n as droppedChecksSteps, o as pnpmLockfiles, s as inWorkspace, u as moveDependencyRanges } from "../checks-CSlWvky1.mjs";
13
13
  import { i as recordedRelease, t as measureBaseline } from "../ratchet-DLCfeaPY.mjs";
14
14
  import { n as SUPPRESSIONS_FILE, r as adoptedBudget } from "../suppression-budget-CPDSFg4X.mjs";
15
15
  import { u as typescript } from "../suppressions-CxPnh4sC.mjs";
@@ -598,7 +598,130 @@ function entrySpecifiers(name, exports, files, consumer) {
598
598
  };
599
599
  }
600
600
  //#endregion
601
+ //#region src/guardrails/known-failures.ts
602
+ /** The file at the repository root that declares the errors `published:types` reports in a dependency's own declarations. */
603
+ const KNOWN_FAILURES_FILE = "guardrails.published-types.json";
604
+ const ENTRY_KEYS = /* @__PURE__ */ new Set([
605
+ "dependency",
606
+ "file",
607
+ "code"
608
+ ]);
609
+ const CODE = /^TS\d+$/;
610
+ const INSIDE_PACKAGE = /^(?!\.\/|\/)[^\\]+$/;
611
+ const PACKAGE_NAME = /^(?:@[^/\s]+\/)?[^/@\s][^/\s]*$/;
612
+ /** What is wrong with `entry`, or the {@link KnownFailure} it declares. */
613
+ function parseEntry(entry) {
614
+ if (!isObject(entry)) return { problem: "is not an object" };
615
+ const extra = Object.keys(entry).filter((key) => !ENTRY_KEYS.has(key));
616
+ if (extra.length) return { problem: `has unknown key ${extra.join(", ")}` };
617
+ const dependency = optStr(entry, "dependency") ?? "";
618
+ const file = optStr(entry, "file") ?? "";
619
+ const code = optStr(entry, "code") ?? "";
620
+ if (!PACKAGE_NAME.test(dependency)) return { problem: "needs dependency as a package name" };
621
+ if (!INSIDE_PACKAGE.test(file) || file.split("/").includes("..")) return { problem: "needs file as a path inside the package" };
622
+ if (!CODE.test(code)) return { problem: "needs code such as TS2416" };
623
+ return {
624
+ problem: "",
625
+ failure: {
626
+ dependency,
627
+ file,
628
+ code
629
+ }
630
+ };
631
+ }
632
+ const EXPECTED = `expected { "knownFailures": [{ "dependency", "file", "code" }] }`;
633
+ /** The entries `KNOWN_FAILURES_FILE` declares at `root`, none when the file is missing, or what is wrong with it. An entry may not name a package of `ownPackages`, the repository's own, whose declarations the repository fixes instead. */
634
+ function readKnownFailures(root, ownPackages) {
635
+ const path = join(root, KNOWN_FAILURES_FILE);
636
+ if (!existsSync(path)) return {
637
+ failure: "",
638
+ entries: []
639
+ };
640
+ let parsed;
641
+ try {
642
+ parsed = parseJson(readFileSync(path, "utf8"));
643
+ } catch (error) {
644
+ return { failure: `${KNOWN_FAILURES_FILE}: ${String(error)}\n` };
645
+ }
646
+ const list = isObject(parsed) && Object.keys(parsed).length === 1 && Object.hasOwn(parsed, "knownFailures") ? parsed.knownFailures : void 0;
647
+ if (!Array.isArray(list)) return { failure: `${KNOWN_FAILURES_FILE}: ${EXPECTED}.\n` };
648
+ const entries = [];
649
+ let problems = "";
650
+ for (const [index, value] of list.entries()) {
651
+ const parsedEntry = parseEntry(value);
652
+ if ("failure" in parsedEntry && entries.some((entry) => describeEntry(entry) === describeEntry(parsedEntry.failure))) problems += `${KNOWN_FAILURES_FILE}: knownFailures[${index}] repeats an earlier entry.\n`;
653
+ else if ("failure" in parsedEntry && ownPackages.has(parsedEntry.failure.dependency)) problems += `${KNOWN_FAILURES_FILE}: knownFailures[${index}] names ${parsedEntry.failure.dependency}, a package of this repository. Fix its declarations instead.\n`;
654
+ else if ("failure" in parsedEntry) entries.push(parsedEntry.failure);
655
+ else problems += `${KNOWN_FAILURES_FILE}: knownFailures[${index}] ${parsedEntry.problem}.\n`;
656
+ }
657
+ return problems ? { failure: problems } : {
658
+ failure: "",
659
+ entries
660
+ };
661
+ }
662
+ /** The diagnostics of tsc's `--pretty false` output, each its first line and the indented lines that continue it. */
663
+ function diagnosticBlocks(output) {
664
+ const blocks = [];
665
+ for (const line of output.split(/\r?\n/)) {
666
+ if (!line) continue;
667
+ if (/^\s/.test(line) && blocks.length) blocks[blocks.length - 1] += `\n${line}`;
668
+ else blocks.push(line);
669
+ }
670
+ return blocks;
671
+ }
672
+ const LOCATED = /^(.*?)\(\d+,\d+\): error (TS\d+): /;
673
+ const INSTALLED = /^((?:@[^/]+\/)?[^/]+)\/(.+)$/;
674
+ const NODE_MODULES = "node_modules/";
675
+ /** Where `block` is reported, undefined when it names no file under `node_modules`. */
676
+ function installedDiagnostic(block) {
677
+ const [, path = "", code = ""] = LOCATED.exec(block) ?? [];
678
+ const marker = path.lastIndexOf(NODE_MODULES);
679
+ if (marker < 0) return void 0;
680
+ const installed = path.slice(marker + 13);
681
+ const [, dependency = "", file = ""] = INSTALLED.exec(installed) ?? [];
682
+ if (!dependency) return void 0;
683
+ return {
684
+ dependency,
685
+ file,
686
+ code,
687
+ text: `${installed}${block.slice(path.length)}`
688
+ };
689
+ }
690
+ /** `entry` written as tsc names its file, `<dependency>/<file> <code>`. */
691
+ function describeEntry(entry) {
692
+ return `${entry.dependency}/${entry.file} ${entry.code}`;
693
+ }
694
+ /**
695
+ * Splits tsc's `--pretty false` `output` into the diagnostics an entry of `entries` declares and the rest. A diagnostic
696
+ * is declared when it lies in a package's installed declarations and an entry names that package, the file inside it
697
+ * and the code. Each entry that declares one is added to `matched`. A diagnostic in a
698
+ * file under `node_modules` names it as `<package>/<file>`.
699
+ */
700
+ function splitDiagnostics(output, entries, matched) {
701
+ const known = [];
702
+ const unknown = [];
703
+ for (const block of diagnosticBlocks(output)) {
704
+ const diagnostic = installedDiagnostic(block);
705
+ const entry = diagnostic ? entries.find(({ dependency, file, code }) => dependency === diagnostic.dependency && file === diagnostic.file && code === diagnostic.code) : void 0;
706
+ if (entry && diagnostic) {
707
+ matched.add(entry);
708
+ known.push(diagnostic.text);
709
+ } else unknown.push(diagnostic?.text ?? block);
710
+ }
711
+ return {
712
+ known,
713
+ unknown
714
+ };
715
+ }
716
+ //#endregion
601
717
  //#region src/guardrails/published-types.ts
718
+ function unchecked(failure) {
719
+ return {
720
+ failure,
721
+ known: [],
722
+ compiled: false
723
+ };
724
+ }
602
725
  const DECLARATION_FILE = /\.d\.[cm]?ts$/;
603
726
  /** An `exports` map that names declarations: a `types` condition or a `.d.ts`, `.d.mts` or `.d.cts` target. */
604
727
  const TYPED_EXPORTS = /"types"\s*:|\.d\.[cm]?ts"/;
@@ -767,13 +890,23 @@ async function typecheck(run, consumer, typed, manifest) {
767
890
  signal: run.signal,
768
891
  shell: false
769
892
  });
770
- return tsc.status === 0 ? "" : readable(tsc.output, consumer, typed.name);
893
+ if (tsc.status === 0) return {
894
+ failure: "",
895
+ known: [],
896
+ compiled: true
897
+ };
898
+ const { known, unknown } = splitDiagnostics(tsc.output, run.declared, run.matched);
899
+ return {
900
+ failure: unknown.length || !known.length ? readable(unknown.length ? `${unknown.join("\n")}\n` : `tsc exited with status ${String(tsc.status)}.\n`, consumer, typed.name) : "",
901
+ known,
902
+ compiled: true
903
+ };
771
904
  }
772
905
  async function consumerErrors(run, typed, slot) {
773
906
  const packed = await pack(run, typed.name);
774
- if (!("tarball" in packed)) return packed.failure;
907
+ if (!("tarball" in packed)) return unchecked(packed.failure);
775
908
  const siblings = await siblingTarballs(run, typed.name, packed.manifest);
776
- if (siblings.failure) return siblings.failure;
909
+ if (siblings.failure) return unchecked(siblings.failure);
777
910
  const consumer = join(run.scratch, `consumer-${slot}`);
778
911
  mkdirSync(consumer);
779
912
  const overrides = {
@@ -790,38 +923,59 @@ async function consumerErrors(run, typed, slot) {
790
923
  cwd: consumer,
791
924
  signal: run.signal
792
925
  });
793
- if (install.status !== 0) return `Installing the tarball failed:\n${install.output}`;
926
+ if (install.status !== 0) return unchecked(`Installing the tarball failed:\n${install.output}`);
794
927
  return typecheck(run, consumer, typed, packed.manifest);
795
928
  }
796
929
  function packsWithPnpmOrNpm(manager) {
797
930
  return manager === "pnpm" || manager === "npm";
798
931
  }
932
+ /** The line that fails each entry of `run` no error matched, once tsc ran over every package. */
933
+ function staleEntries(run) {
934
+ return run.declared.filter((entry) => !run.matched.has(entry)).map((entry) => `${KNOWN_FAILURES_FILE}: ${describeEntry(entry)} no longer occurs. Remove the entry.\n`).join("");
935
+ }
799
936
  /**
800
937
  * Packs each package `typedPackages` finds, running its `prepack`, and installs the tarball alone in a scratch
801
938
  * directory with its peers, optional ones included, `typescript` and `@types/node` at the latest version unless it
802
939
  * names them as peers, and the tarball of each package of the repository it depends on in place of the registry's.
803
940
  * Then runs `tsc` with `skipLibCheck` off over a consumer file importing each entry its `exports` names, or, without
804
- * `exports`, the package itself and every declaration file it ships. Returns what failed, each package's errors under
805
- * its `package.json`, empty when every package passed.
941
+ * `exports`, the package itself and every declaration file it ships. An error in a dependency's declarations that
942
+ * `guardrails.published-types.json` declares is reported under `notes` instead of failing; an entry no error matched
943
+ * fails once tsc ran over every package. Each package's errors are listed under its `package.json`.
806
944
  */
807
945
  async function checkPublishedTypes(root, signal) {
808
946
  const manager = packageManager(parseManifest(readFileSync(join(root, "package.json"), "utf8")));
809
- if (!packsWithPnpmOrNpm(manager)) return `This check packs with pnpm or npm, not ${manager}.\n`;
947
+ if (!packsWithPnpmOrNpm(manager)) return {
948
+ failure: `This check packs with pnpm or npm, not ${manager}.\n`,
949
+ notes: ""
950
+ };
951
+ const members = new Map(publicPackages(root).map(({ name, directory }) => [name, directory]));
952
+ const declared = readKnownFailures(root, new Set(members.keys()));
953
+ if (!("entries" in declared)) return {
954
+ failure: declared.failure,
955
+ notes: ""
956
+ };
810
957
  const scratch = realpathSync.native(mkdtempSync(join(tmpdir(), "published-types-")));
811
958
  const run = {
812
959
  root,
813
960
  manager,
814
961
  scratch,
815
962
  signal,
816
- members: new Map(publicPackages(root).map(({ name, directory }) => [name, directory])),
817
- packs: /* @__PURE__ */ new Map()
963
+ members,
964
+ packs: /* @__PURE__ */ new Map(),
965
+ declared: declared.entries,
966
+ matched: /* @__PURE__ */ new Set()
818
967
  };
819
- let failures = "";
968
+ let failure = "";
969
+ let notes = "";
970
+ let complete = true;
820
971
  try {
821
972
  for (const [slot, typed] of typedPackages(root).entries()) {
822
973
  if (signal?.aborted) break;
823
- const failure = await consumerErrors(run, typed, slot);
824
- if (failure) failures += `${join(typed.directory, "package.json")}: ${typed.name} as a consumer installs it, checked by tsc with skipLibCheck off:\n${failure}`;
974
+ const checked = await consumerErrors(run, typed, slot);
975
+ complete &&= checked.compiled;
976
+ const header = `${join(typed.directory, "package.json")}: ${typed.name} as a consumer installs it, checked by tsc with skipLibCheck off`;
977
+ if (checked.failure) failure += `${header}:\n${checked.failure}`;
978
+ if (checked.known.length) notes += `${header}, errors ${KNOWN_FAILURES_FILE} declares as known:\n${checked.known.join("\n")}\n`;
825
979
  }
826
980
  } finally {
827
981
  rmSync(scratch, {
@@ -829,7 +983,11 @@ async function checkPublishedTypes(root, signal) {
829
983
  force: true
830
984
  });
831
985
  }
832
- return failures;
986
+ if (complete && !signal?.aborted) failure += staleEntries(run);
987
+ return {
988
+ failure,
989
+ notes
990
+ };
833
991
  }
834
992
  //#endregion
835
993
  //#region src/guardrails/readme-version.ts
@@ -1828,14 +1986,20 @@ const CHECK_STEPS = [
1828
1986
  "readme:version",
1829
1987
  "published:types"
1830
1988
  ];
1831
- /** Steps `antelopejs-checks` runs itself, no package.json script behind them: each returns what failed, empty when it passed. */
1989
+ function failureOnly(check) {
1990
+ return async (root, signal) => ({
1991
+ failure: await check(root, signal),
1992
+ notes: ""
1993
+ });
1994
+ }
1995
+ /** Steps `antelopejs-checks` runs itself, no package.json script behind them. */
1832
1996
  const OWN_STEPS = /* @__PURE__ */ new Map([
1833
- ["verify:types", typecheckLayers],
1834
- ["verify:lockfiles", (root) => Promise.resolve(checkLockfiles(root))],
1835
- ["lockfile:singletons", (root) => Promise.resolve(checkSingletonPackages(root))],
1836
- ["dependency:ranges", checkRepositoryRanges],
1837
- ["git:identity", checkGitIdentity],
1838
- ["readme:version", checkReadmeVersion],
1997
+ ["verify:types", failureOnly(typecheckLayers)],
1998
+ ["verify:lockfiles", failureOnly((root) => Promise.resolve(checkLockfiles(root)))],
1999
+ ["lockfile:singletons", failureOnly((root) => Promise.resolve(checkSingletonPackages(root)))],
2000
+ ["dependency:ranges", failureOnly(checkRepositoryRanges)],
2001
+ ["git:identity", failureOnly(checkGitIdentity)],
2002
+ ["readme:version", failureOnly(checkReadmeVersion)],
1839
2003
  ["published:types", checkPublishedTypes]
1840
2004
  ]);
1841
2005
  function hasWork(root, step) {
@@ -1901,13 +2065,22 @@ function skippedNames(setting) {
1901
2065
  async function runSteps(root, manifest, steps, signal) {
1902
2066
  const manager = packageManager(manifest);
1903
2067
  const runStep = async (step) => {
1904
- if (signal?.aborted) return [];
2068
+ if (signal?.aborted) return {
2069
+ failure: "",
2070
+ notes: ""
2071
+ };
1905
2072
  const own = OWN_STEPS.get(step);
1906
2073
  if (own) {
1907
- const failure = await own(root, signal);
1908
- return failure ? [`[${step}]\n${failure}`] : [];
2074
+ const { failure, notes } = await own(root, signal);
2075
+ return {
2076
+ failure: failure && `[${step}]\n${failure}`,
2077
+ notes: notes && `[${step}]\n${notes}`
2078
+ };
1909
2079
  }
1910
- if (!manifest.scripts?.[step]) return [`[${step}] Missing package.json script "${step}". Run antelopejs-sync.\n`];
2080
+ if (!manifest.scripts?.[step]) return {
2081
+ failure: `[${step}] Missing package.json script "${step}". Run antelopejs-sync.\n`,
2082
+ notes: ""
2083
+ };
1911
2084
  const result = await runCommand(manager, ["run", step], {
1912
2085
  cwd: root,
1913
2086
  env: {
@@ -1916,11 +2089,18 @@ async function runSteps(root, manifest, steps, signal) {
1916
2089
  },
1917
2090
  signal
1918
2091
  });
1919
- return result.status === 0 ? [] : [`[${step}]\n${result.output}`];
2092
+ return {
2093
+ failure: result.status === 0 ? "" : `[${step}]\n${result.output}`,
2094
+ notes: ""
2095
+ };
2096
+ };
2097
+ const reports = /* @__PURE__ */ new Map();
2098
+ for (const phase of phases(root, steps)) await Promise.all(phase.map(async (step) => reports.set(step, await runStep(step))));
2099
+ const listed = (field) => steps.flatMap((step) => reports.get(step)?.[field] || []);
2100
+ return {
2101
+ failures: listed("failure"),
2102
+ notes: listed("notes")
1920
2103
  };
1921
- const failures = /* @__PURE__ */ new Map();
1922
- for (const phase of phases(root, steps)) await Promise.all(phase.map(async (step) => failures.set(step, await runStep(step))));
1923
- return steps.flatMap((step) => failures.get(step) ?? []);
1924
2104
  }
1925
2105
  /** The optional package script run once before the steps, to build what several steps read, such as a workspace package's `dist`. */
1926
2106
  const PREPARE = "checks:prepare";
@@ -1947,8 +2127,8 @@ async function prepare(root, manifest, signal) {
1947
2127
  output: `${failure}Checks: 0 passed, 1 failed.\n`
1948
2128
  };
1949
2129
  }
1950
- function summary(failures, passed, skipped) {
1951
- return `${failures.join("\n")}Checks: ${passed} passed, ${failures.length} failed${skipped ? `, ${skipped} skipped` : ""}.\n`;
2130
+ function summary(reported, failed, passed, skipped) {
2131
+ return `${reported}Checks: ${passed} passed, ${failed} failed${skipped ? `, ${skipped} skipped` : ""}.\n`;
1952
2132
  }
1953
2133
  /**
1954
2134
  * Runs the `checks:prepare` package script first when it exists and a step will run, and stops there if it fails.
@@ -1986,19 +2166,22 @@ async function runChecks(root, options = {}) {
1986
2166
  owned: false
1987
2167
  };
1988
2168
  let failures = [];
2169
+ let notes = [];
1989
2170
  let stopped = "";
1990
2171
  try {
1991
- failures = started.failure ? [`[services]\n${started.failure}`] : await runSteps(root, manifest, steps, signal);
2172
+ if (started.failure) failures = [`[services]\n${started.failure}`];
2173
+ else ({failures, notes} = await runSteps(root, manifest, steps, signal));
1992
2174
  } finally {
1993
2175
  if (started.owned) stopped = await stopServices(root);
1994
2176
  }
1995
2177
  const passed = started.failure ? 0 : steps.length - failures.length;
1996
2178
  if (stopped) failures.push(`[services]\n${stopped}`);
1997
2179
  const interrupted = signal?.aborted ?? false;
2180
+ const reported = [...notes, ...failures].join("\n");
1998
2181
  return {
1999
2182
  failed: failures.length,
2000
2183
  interrupted,
2001
- output: interrupted ? `${failures.join("\n")}Checks interrupted by ${String(signal?.reason)}.\n` : summary(failures, passed, skipped)
2184
+ output: interrupted ? `${reported}Checks interrupted by ${String(signal?.reason)}.\n` : summary(reported, failures.length, passed, skipped)
2002
2185
  };
2003
2186
  }
2004
2187
  //#endregion
package/dist/eslint.mjs CHANGED
@@ -1,5 +1,5 @@
1
1
  import { n as typeAwareRuleSetting, t as TYPE_AWARE_RULES } from "./type-aware-rules-BxhHbizU.mjs";
2
- import { t as guardrailsPlugin } from "./guardrails-PoMIcyGb.mjs";
2
+ import { t as guardrailsPlugin } from "./guardrails-nj7NTglr.mjs";
3
3
  import { createConfigForNuxt } from "@nuxt/eslint-config/flat";
4
4
  //#region src/eslint.ts
5
5
  /** Whether every rule of `plugin` has the `create` function ESLint calls, which `eslintCompatPlugin` gives each oxlint rule. */
@@ -1876,6 +1876,13 @@ function declaresTypeParameters(sfc) {
1876
1876
  const programs = /* @__PURE__ */ new Map();
1877
1877
  /** The source files every program of the lint run shares, parsed once per text and per set of compiler options that change a parse. */
1878
1878
  const documents = ts.createDocumentRegistry(ts.sys.useCaseSensitiveFileNames);
1879
+ /** `options` without `pathsBasePath`, the directory of the config that declares `paths`, which TypeScript adds to the key of a parse in {@link documents} though it changes no parse. The programs of configs that keep `paths` in different directories, as the tsconfig Nuxt generates for each site does, then share the files they all read. */
1880
+ function registrySettings(options) {
1881
+ return {
1882
+ ...options,
1883
+ pathsBasePath: void 0
1884
+ };
1885
+ }
1879
1886
  function normalize(file) {
1880
1887
  return resolve(file).replaceAll("\\", "/");
1881
1888
  }
@@ -1920,10 +1927,11 @@ function build(config, path, view) {
1920
1927
  allowNonTsExtensions: true
1921
1928
  } : parsed.options;
1922
1929
  const host = ts.createCompilerHost(options, true);
1930
+ const settings = registrySettings(options);
1923
1931
  host.getSourceFile = (name, language) => {
1924
1932
  const content = normalize(name) === path ? view : readView(host, name);
1925
1933
  if (content === void 0) return void 0;
1926
- return content.tsx ? tsxView(name, content.text, language) : documents.acquireDocument(name, options, ts.ScriptSnapshot.fromString(content.text), content.text, void 0, language);
1934
+ return content.tsx ? tsxView(name, content.text, language) : documents.acquireDocument(name, settings, ts.ScriptSnapshot.fromString(content.text), content.text, void 0, language);
1927
1935
  };
1928
1936
  const program = ts.createProgram({
1929
1937
  rootNames,
@@ -1,3 +1,3 @@
1
1
  import { n as TEST_FILE_GLOBS, t as ASSERTION_FUNCTION_NAMES } from "../../shared-WC0z3y9F.mjs";
2
- import { t as guardrailsPlugin } from "../../guardrails-PoMIcyGb.mjs";
2
+ import { t as guardrailsPlugin } from "../../guardrails-nj7NTglr.mjs";
3
3
  export { ASSERTION_FUNCTION_NAMES, TEST_FILE_GLOBS, guardrailsPlugin as default };
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@antelopejs/tooling-configs",
3
- "version": "0.7.2",
3
+ "version": "0.7.3",
4
4
  "description": "Shared tooling presets for AntelopeJS repositories: oxlint (with the vendored anti-slop rules), oxfmt, ESLint for Nuxt layers, Knip, and a dependency range check",
5
5
  "keywords": [
6
6
  "antelopejs",