@antelopejs/tooling-configs 0.7.3 → 0.7.5-next.356.g0d472b3
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 +63 -80
- package/dist/bin/api-diff.mjs +29 -49
- package/dist/bin/capture.mjs +4 -4
- package/dist/bin/check-size.mjs +12 -3
- package/dist/bin/checks.mjs +2 -2
- package/dist/bin/comment-proof.mjs +3 -4
- package/dist/bin/garden.mjs +45 -170
- package/dist/bin/readme-strip.mjs +2 -2
- package/dist/bin/suppressions.mjs +212 -9
- package/dist/bin/sync.mjs +318 -210
- package/dist/bin/tsc.mjs +24 -0
- package/dist/bin/verify.mjs +91 -671
- package/dist/{checks-CSlWvky1.mjs → checks-C60vMFin.mjs} +155 -310
- package/dist/{docs-compat-BAZiPLZt.mjs → docs-compat-CdgBviGf.mjs} +2 -2
- package/dist/eslint.mjs +1 -1
- package/dist/{files-C-JJhExM.mjs → files-BbzJEk-L.mjs} +5 -4
- package/dist/formal/index.mjs +1 -1
- package/dist/{guardrails-nj7NTglr.mjs → guardrails-Dron1AbR.mjs} +67 -673
- package/dist/{installed-typescript-6MtIWlE4.mjs → installed-typescript-CF_FR9DV.mjs} +17 -17
- package/dist/{map-BYkmnvNw.mjs → map-CbNbypUa.mjs} +2 -2
- package/dist/oxc/anti-slop/index.mjs +22 -964
- package/dist/oxc/guardrails/index.d.mts +1 -1
- package/dist/oxc/guardrails/index.mjs +1 -1
- package/dist/oxc/lint.d.mts +2 -14
- package/dist/oxc/lint.mjs +3 -20
- package/dist/{package-DDG3YH7W.mjs → package-7oylgBeT.mjs} +6 -19
- package/dist/{workflow-C-oBwL2H.mjs → renovate-D0su_v9p.mjs} +191 -91
- package/dist/{suppression-budget-CPDSFg4X.mjs → suppression-budget-De9nUzlD.mjs} +33 -13
- package/dist/{suppressions-CxPnh4sC.mjs → suppressions-CfJwL0fN.mjs} +6 -2
- package/dist/{templates-HG0fel2S.mjs → templates-DLW0Ubfk.mjs} +26 -29
- package/dist/typescript-C7eU-cig.mjs +581 -0
- package/dist/typescript-version-CptQKjGz.mjs +18 -0
- package/dist/typescript6-BWqCcXGY.mjs +2 -0
- package/dist/typescript6-HdyOMBv3.mjs +8 -0
- package/dist/verify/index.d.mts +5 -24
- package/package.json +27 -7
- package/dist/bin/body-check.mjs +0 -350
- package/dist/bin/ratchet.d.mts +0 -1
- package/dist/bin/ratchet.mjs +0 -375
- package/dist/ceilings-B7KayYIG.mjs +0 -76
- package/dist/oxlint-CIeonWMB.mjs +0 -133
- package/dist/proof-stamp-BFV7JTZT.mjs +0 -342
- package/dist/ratchet-DLCfeaPY.mjs +0 -453
- package/dist/renames-L2owF5GD.mjs +0 -59
- package/dist/size-CCGLY4Ke.mjs +0 -18
- package/dist/suppression-base-CYaLZAq7.mjs +0 -120
- package/dist/typescript-QfxkJYzd.mjs +0 -292
- /package/dist/bin/{body-check.d.mts → tsc.d.mts} +0 -0
package/README.md
CHANGED
|
@@ -19,7 +19,7 @@ The AntelopeJS guardrail pack: shared lint, format and dead-code presets, the co
|
|
|
19
19
|
- [Knip](https://knip.dev) learns the entry points of an AntelopeJS module.
|
|
20
20
|
- Every preset is a function: options adjust it without copying it.
|
|
21
21
|
- `antelopejs-sync` writes the configs, hooks, scripts and agent instructions into a repository, and `antelopejs-sync --check` fails CI when they drift.
|
|
22
|
-
- Every lint rule is an error or off.
|
|
22
|
+
- Every lint rule is an error or off.
|
|
23
23
|
|
|
24
24
|
## What's in the box
|
|
25
25
|
|
|
@@ -34,12 +34,11 @@ The AntelopeJS guardrail pack: shared lint, format and dead-code presets, the co
|
|
|
34
34
|
| `./verify` | `import type { VerifyConfig } from "@antelopejs/tooling-configs/verify"` | Types and check helpers for a shared verification skill's `verify.config.ts` |
|
|
35
35
|
| bin | `antelopejs-sync [--init]` | Writes the guardrail pack into a repository; `--check` reports drift; `--init` onboards a bare repository |
|
|
36
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
37
|
| bin | `antelopejs-suppressions` | Fails when suppressions exceed their budget or an added one breaks policy; `--update` lowers the budget |
|
|
39
38
|
| bin | `antelopejs-check-size` | Fails on authored files over 20,000 bytes and on blanket disable directives |
|
|
40
39
|
| bin | `antelopejs-api-diff <base-ref>` | Compares published declaration bundles against committed HEAD |
|
|
41
40
|
| bin | `antelopejs-comment-proof <base-ref>` | Compares comment-free JavaScript emit against committed HEAD |
|
|
42
|
-
| bin | `antelopejs-
|
|
41
|
+
| bin | `antelopejs-tsc <tsc arguments>` | Runs the pack's own TypeScript 7 with `tsc`'s arguments, for `build` and `typecheck` ([TypeScript 7](#typescript-7-for-build-and-typecheck)) |
|
|
43
42
|
| 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
43
|
| bin | `antelopejs-garden [--json] [--apply] [--apply-prunes]` | The Gardener's scans of the organization through the GitHub API and npm |
|
|
45
44
|
| bin | `antelopejs-triage [--json]` | Community Triage's ranked shortlist of untriaged issues |
|
|
@@ -134,11 +133,11 @@ export default defineConfig({
|
|
|
134
133
|
| Guardrails | `antelopejs/no-comments`, `antelopejs/no-inherited-key-lookup`, `antelopejs/no-presence-only-type-guard`, `antelopejs/no-read-then-insert`, and with type-aware lint `antelopejs/no-unrun-query`, `antelopejs/no-unsafe-object-assign` and `antelopejs/require-tsconfig-include`; in test files `antelopejs/no-fs-read-in-tests`, `antelopejs/no-self-import-in-tests`, `antelopejs/no-constant-value-assertion`, `antelopejs/no-typeof-function-only-test` and `antelopejs/require-assertion` | error |
|
|
135
134
|
| Import sorting | `perfectionist/sort-imports`, autofixed by `oxlint --fix` | off |
|
|
136
135
|
|
|
137
|
-
Three anti-slop rules skip a value at its boundary. `no-runtime-typeof` also counts a `.js`/`.mjs` function documented `@returns {x is T}` as a type guard. `no-unsafe-dictionary-type` allows `Record<string, unknown>` as a `value is T` target or inside a type-guard body. `no-unknown-parameters` skips a `this` parameter, a parameter decorated `@JSONBody`, `@JsonBody` or `@Parameter`, the reason of a callback passed directly to `.catch(...)` or as `.then(_, onRejected)`, the parameter of a `(reason: unknown) => void` type declared as `reject` or on a `new Promise` executor
|
|
136
|
+
Three anti-slop rules skip a value at its boundary. `no-runtime-typeof` also counts a `.js`/`.mjs` function documented `@returns {x is T}` as a type guard. `no-unsafe-dictionary-type` allows `Record<string, unknown>` as a `value is T` target or inside a type-guard body. `no-unknown-parameters` skips a `this` parameter, a parameter decorated `@JSONBody`, `@JsonBody` or `@Parameter`, the reason of a callback passed directly to `.catch(...)` or as `.then(_, onRejected)`, and the parameter of a `(reason: unknown) => void` type declared as `reject` or on a `new Promise` executor.
|
|
138
137
|
|
|
139
138
|
`no-runtime-typeof` also reports a `typeof` that only fills in the text of a message, such as ``throw new Error(`received ${typeof value}`)`` or ``assert(ok, `received ${typeof value}`)``: one file cannot see what catches, compares or records the message.
|
|
140
139
|
|
|
141
|
-
No rule warns. oxlint reports `correctness` as warnings by default, and warnings never fail the command, so the preset raises it to error.
|
|
140
|
+
No rule warns. oxlint reports `correctness` as warnings by default, and warnings never fail the command, so the preset raises it to error.
|
|
142
141
|
|
|
143
142
|
The guardrail rules:
|
|
144
143
|
|
|
@@ -216,25 +215,28 @@ pnpm exec antelopejs-sync
|
|
|
216
215
|
pnpm install
|
|
217
216
|
```
|
|
218
217
|
|
|
219
|
-
| File | What `sync` does
|
|
220
|
-
| ------------------------------------------------------- |
|
|
221
|
-
| `oxlint.config.ts`, `oxfmt.config.ts`, `knip.config.ts` | Writes a config that extends the preset, unless the file already imports it
|
|
222
|
-
| `lefthook.yml` | Pre-commit on staged files: oxfmt, oxlint, size, suppressions
|
|
223
|
-
| `package.json` | `prepare` installs lefthook. Sets `checks`, `size`, `
|
|
224
|
-
| `renovate.json` | Writes one extending `github>AntelopeJS/.github:renovate.json5` when the repository has no Renovate config at any path Renovate reads (including a `renovate` key in `package.json`). An existing config stays as it is; sync and `--check` fail one that does not extend the preset. Under `--profile template`, only in the template source, so a scaffold may keep, change or delete the copy it gets
|
|
225
|
-
| `.
|
|
226
|
-
| `.
|
|
227
|
-
| `.
|
|
228
|
-
| `
|
|
229
|
-
| `
|
|
230
|
-
| `
|
|
231
|
-
| `
|
|
232
|
-
| `
|
|
233
|
-
|
|
|
234
|
-
|
|
235
|
-
|
|
236
|
-
|
|
237
|
-
|
|
218
|
+
| File | What `sync` does |
|
|
219
|
+
| ------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
220
|
+
| `oxlint.config.ts`, `oxfmt.config.ts`, `knip.config.ts` | Writes a config that extends the preset, unless the file already imports it |
|
|
221
|
+
| `lefthook.yml` | Pre-commit on staged files: oxfmt, oxlint. Removes the ratchet, size, suppressions and typecheck hooks of earlier releases; CI runs those checks |
|
|
222
|
+
| `package.json` | `prepare` installs lefthook. Sets `checks`, `size`, `suppressions`, `suppressions:update`, `sync`, `sync:check`; adds missing `typecheck`, `lint`, `format`, `format:check`, `knip`; adds `lefthook` and `knip` |
|
|
223
|
+
| `renovate.json` | Writes one extending `github>AntelopeJS/.github:renovate.json5` when the repository has no Renovate config at any path Renovate reads (including a `renovate` key in `package.json`). An existing config stays as it is; sync and `--check` fail one that does not extend the preset. Under `--profile template`, only in the template source, so a scaffold may keep, change or delete the copy it gets |
|
|
224
|
+
| `.github/workflows/ci.yml` | Keeps the ci-node.yml caller on job `ci`, and calls ci-node.yml and ci-renovate-sync.yml at `@v2` whatever ref they had. Declares exactly the three-tier triggers: `pull_request` (opened, synchronize, reopened, ready_for_review), `push` on `next` (`develop` in cloud), a nightly `schedule`, `workflow_dispatch`. Outside antelopejs and cloud-sdk, drops `windows: true` and `windows-pull-requests` |
|
|
225
|
+
| `.github/workflows/next-sync.yml` | Full profile only. Calls next-sync.yml at `@v2` on each push to `main`, with `issues: write`, `RELEASE_GITHUB_TOKEN` and `NOTION_TOKEN`, so `main` is merged back into `next` (`develop` in cloud) |
|
|
226
|
+
| `.github/workflows/release.yml` | When a workflow calls release-npm-public.yml or release-npm-private.yml, gathers every such caller into this one file at `@v2`: a preview on each push to `next` (`develop` in cloud), and the stable release the release train dispatches with `release-version`, `release-commit`, `dependency-ranges` and, for a package below the root, `package-directory`. Several packages get one job each. Keeps `install-core`; drops `channel`, `services-compose-file`, other jobs such as `validate`, and the other caller files, and names each in a note |
|
|
227
|
+
| Other `.github/workflows/*.yml` | Moves each call to a shared workflow the `v2` tag of `AntelopeJS/.github` ships (`ci-node.yml`, `ci-renovate-sync.yml`, `next-sync.yml`, `release-npm-public.yml`, `release-npm-private.yml`, `stale.yml`) to `@v2`, and leaves the rest of the file as it is. A call to a workflow `v2` does not ship keeps its ref |
|
|
228
|
+
| `.gitattributes` | Adds `* text=auto eol=lf` as the first line when no line holds it, so text files check out with LF on Windows whatever `core.autocrlf` says and a shell script still runs. Patterns the file already lists stay after it and override it |
|
|
229
|
+
| `.nvmrc` | `24` |
|
|
230
|
+
| `.agents/setup` | Orb setup: switches to the `.nvmrc` Node, activates `packageManager` through corepack, installs with the frozen lockfile |
|
|
231
|
+
| `AGENTS.md` | Writes the managed block between `<!-- antelopejs-guardrails:start -->` and `:end -->`; text outside the markers stays |
|
|
232
|
+
| `README.md` of each `@antelopejs` package | Writes the generated compatibility block (see [Generated compatibility block](./docs/documentation-checks.md#generated-compatibility-block)); prose outside its markers stays |
|
|
233
|
+
| `CLAUDE.md` | `@AGENTS.md` |
|
|
234
|
+
| `guardrails.suppressions.json` | Records the current suppression counts when the file is missing; restores the committed file instead when HEAD has one; otherwise only adds `config` and `agentFiles` at today's counts when the file predates them |
|
|
235
|
+
| `<layer>/build/backend-boundary.ts` | Where a DMS frontend layer tracks one, restores the pack's backend boundary plugin for the package that holds the layer. A formatter's rewrite is not drift; any other edit is |
|
|
236
|
+
|
|
237
|
+
`--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`. It adds `typecheck`, `lint`, `format`, `format:check`, `knip`, `sync` and `sync:check` only where the template has none, the sync scripts with `--profile template`. 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.
|
|
238
|
+
|
|
239
|
+
`pnpm run checks` runs `typecheck`, `lint`, `format:check`, `knip`, `test`, `size`, `suppressions` and `sync:check`. It prints only the output of the steps that failed, and the errors `published:types` declares as known. 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`, which needs no package script. It writes no file in the repository, spawns no package manager and fetches nothing, so it passes offline after a root install, as CI runs it. 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
240
|
|
|
239
241
|
```json
|
|
240
242
|
{
|
|
@@ -250,10 +252,9 @@ pnpm install
|
|
|
250
252
|
|
|
251
253
|
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.
|
|
252
254
|
|
|
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.
|
|
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.
|
|
255
|
+
- `verify:types` type-checks each layer's own code with the repository's own TypeScript, run as `node <typescript>/bin/tsc` without a shell. It never runs another package's `tsc`, so it stays on the TypeScript 6 the repository declares when `build` and `typecheck` run `antelopejs-tsc`, and a `typescript` without a `tsc` bin counts as not installed. 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`.
|
|
255
256
|
|
|
256
|
-
`ANTELOPEJS_CHECKS_SKIP` accepts
|
|
257
|
+
`ANTELOPEJS_CHECKS_SKIP` accepts its name.
|
|
257
258
|
|
|
258
259
|
The steps run at the same time, `test` last and alone. When `typecheck` writes files, it runs first and the other steps start after it, so `lint` never resolves a workspace package's `dist` that `typecheck` is rebuilding. `typecheck` writes files when the scripts it runs reach a `build` script or a `tsc` that leaves `noEmit` unset on its command line and in its tsconfig chain, following `--filter`, `--dir` and `-r` into workspace packages. A package-manager target it cannot resolve, such as a `--dir` read from a variable or a dependency `--filter` like `pkg...`, counts as writing. A build that a wrapper script runs, such as `node scripts/run.mjs pnpm build`, is not seen. When a wrapper hides the build, or two other steps share what one of them builds, add a `checks:prepare` package script that builds it. `pnpm run checks` runs it once before any step and after it checks that Docker Compose can run, whenever at least one step runs. Its output is printed only when it fails, and then no step runs. It counts as a step only when it fails, and a repository without it runs as before.
|
|
259
260
|
|
|
@@ -285,34 +286,11 @@ A project needs no `with`: the default `refresh-command` is `pnpm exec ajs proje
|
|
|
285
286
|
|
|
286
287
|
A push made with `GITHUB_TOKEN` starts no workflow, so the workflow then dispatches `ci.yml` on the branch. Sync keeps `workflow_dispatch` on the `ci.yml` it owns, so `ci / checks` runs on the new head. A repository whose checks live in another workflow passes its file as `ci-workflow`. `GITHUB_TOKEN` opens the pull request only where the repository allows GitHub Actions to create pull requests; otherwise pass a `token` secret that may, and its push starts the checks with nothing dispatched. Without either, the run pushes the branch and fails with a link to open the pull request by hand. The other inputs and the failure rules are in [Module locks update](https://github.com/AntelopeJS/.github#module-locks-update).
|
|
287
288
|
|
|
288
|
-
### Ratchet
|
|
289
|
-
|
|
290
|
-
`guardrails.ratchet.json` holds the debt a repository had when it adopted the pack:
|
|
291
|
-
|
|
292
|
-
```json
|
|
293
|
-
{
|
|
294
|
-
"pack": "0.2.17",
|
|
295
|
-
"rules": { "antelopejs/no-comments": 22, "eslint/max-depth": 1 },
|
|
296
|
-
"oversizeFiles": { "src/legacy.ts": 31250 }
|
|
297
|
-
}
|
|
298
|
-
```
|
|
299
|
-
|
|
300
|
-
- A rule listed under `rules` is off for `oxlint`, so editors, hooks and `lint` stay green. `antelopejs-ratchet` counts it with every rule on, and fails when a count rises. It prints the findings in the files the change touched.
|
|
301
|
-
- A file listed under `oversizeFiles` may exceed 20,000 bytes and `max-lines`, up to its recorded size. Any other file over either limit fails. When git sees a listed file renamed (`git mv`, or a staged delete and add), the allowance moves to the new path and never exceeds the old one; a copy or a new file inherits nothing. `antelopejs-ratchet --base <ref>` detects renames against that revision instead of `HEAD`, for a rename that was committed before the file was updated.
|
|
302
|
-
- The pre-commit hook runs `antelopejs-ratchet --staged`: for each rule under `rules` it counts the findings in every staged file as the index holds it (a file whose working copy differs or was deleted after staging is linted from a checkout of the index), and in those files at HEAD and at the merge-base of HEAD with the pull request base (`origin/$GITHUB_BASE_REF`, else `origin/HEAD`), rename sources and deleted files included, linted under the staged configuration. A merge-base finding counts only for a staged finding of the same rule on the same line, unchanged since the merge-base, and only while the files the branch changed hold no more findings of that rule than at the merge-base. It fails a rule whose staged count is above both, and lists the findings on lines that differ from HEAD and from the merge-base. Code moved between staged files, a legacy line that is reformatted or edited, a line restored byte for byte to its base form, a `SAFETY:` comment the branch added and the commit removes, or an edit of a file a legacy finding moved into earlier on the branch, nets out; a new finding does not, even next to a moved block. Locally the base is always `origin/HEAD`, so a branch stacked on another branch is compared with HEAD and the default branch, not with its parent branch. Without `origin/HEAD` (`git remote set-head origin --auto` sets it) or a merge-base, it compares with HEAD only and says so when it fails.
|
|
303
|
-
- With `APPROVED_RAISES="<rule>=<max> ..."` in the environment, `antelopejs-ratchet --staged` accepts the findings of exactly those rules while this commit raises the rule's ceiling in the staged `guardrails.ratchet.json` above HEAD's, to exactly `<max>`, and the commit holds at most `<max>` findings of it, counted from a checkout of the index, so ignore files and a file whose working copy differs cannot hide it; the commit is refused while any tracked file is `skip-worktree` (a sparse checkout) or `assume-unchanged`, because those files can differ from the index unseen. The variable is split on space and tab only, so a non-breaking space or a newline makes it malformed. The count takes the higher of a checkout of the index and the working tree for each rule, so generated types that only the working tree has are not lost, and an untracked file with a finding still counts. When the commit also stages a code file, a raised ceiling for a rule the variable does not list is refused too. A commit that stages only `guardrails.ratchet.json` skips the hook through its glob, as it does without the variable, and the CI gate refuses that raise. `<max>` is what `antelopejs-ratchet` measures, the same as the CI gate: files it does not measure (a force-added gitignored file, a file under a gitignored path, a nested lint config, a non-UTF-8 file name) do not count, and a stale or partial build can change a type-aware count. The `oxlint` preset ignores the variable: it already turns off the rules in the ceiling file, and the approved commit writes that ceiling. Each accepted raise is printed as `APPROVED RAISE ACCEPTED`. A rule the variable does not list, a ceiling that is not raised to `<max>`, a count above `<max>`, tracked files with unstaged changes and a malformed variable (a bare rule, a non-numeric max, a rule listed twice) are refused, and with the variable unset nothing changes. The variable is the operator's approval: it does not make CI accept the raise.
|
|
304
|
-
- `antelopejs-ratchet --update` lowers each number to the current count and removes what reached zero. It never raises a number. The only entries it adds are rules a pack release enabled after the release recorded under `pack`: `PACK_NEW_RULES` in `src/guardrails/adoption.ts` lists each such rule with the release that enabled it. After a pack upgrade, the update records today's count of each one that has findings, then moves `pack` forward, so a rule fixed to zero and later broken again is never adopted twice. Without `pack`, the repository's adopted release is the pack its lockfile installs at the pull request base (pnpm or npm), and an unknown one predates every listed rule. A clean repository with findings for such a rule gets a ratchet file holding only those rules; run `antelopejs-sync` afterwards for the ratchet scripts and hook. Commit the file. The same update records the size of each oversize file under the agent directories (`.agents/`, `.claude/`, `.amp/` and the others) that has no allowance, once, in a repository whose adopted release predates 0.2.18, the release that began counting the repository's own files there; `antelopejs-ratchet --base` accepts those allowances for files that exist at the base, at no more than their size there, and no other.
|
|
305
|
-
- Against the pull request base (`GITHUB_BASE_REF` in CI, else `origin/HEAD`, or `--base <ref>`), `antelopejs-ratchet` fails an entry added or raised by hand: a rule the pack did not newly enable, a pack-new rule above its count or above its count in the base tree, an oversize allowance for a file that is not a rename of one, and a lowered or dropped `pack`. A first adoption (no ratchet file and no suppression budget at the base) passes.
|
|
306
|
-
|
|
307
|
-
When every rule count is zero and `oversizeFiles` is empty, the ratchet is retired. `antelopejs-ratchet --update` deletes the file and asks you to run `antelopejs-sync`. Sync then removes `ratchet`, `ratchet:update`, the ratchet hook and the Debt instructions. Commit those changes together. An empty baseline on first adoption creates no file. Later syncs never recreate it because the `sync:check` script marks adoption.
|
|
308
|
-
|
|
309
|
-
`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.
|
|
310
|
-
|
|
311
289
|
### Lib check coverage
|
|
312
290
|
|
|
313
291
|
No repository sets `skipLibCheck` globally. `typecheck` runs a full `tsc --noEmit` over the program that covers the sources, and `build` may pass `--skipLibCheck` only over a program `typecheck` checks in full, so nothing `typecheck` skipped goes unchecked. `antelopejs-sync --check` fails with a line naming the file, the script and the fix, and plain `antelopejs-sync` prints the same line as a `Note:` and carries on, when:
|
|
314
292
|
|
|
315
|
-
- `build` passes `--skipLibCheck` (in any letter case) to a `tsc` program (`-p`/`--project`, `tsconfig.json` when absent) that no `tsc` run of `typecheck` covers without `--skipLibCheck`. `./tsconfig.build.json` and `tsconfig.build.json`, `-p .` and no `-p` are the same program. `pre<script>` scripts count with their script, and `&&` chains, parentheses, `cross-env` and environment prefixes, `run-s` and `npm-run-all`, and scripts run through `pnpm`, `npm`, `yarn` or `bun` (`--filter <x>`, `-C <dir>` and other options with a value included) are followed to five levels. `tsc` is recognised as `tsc`, `npx tsc`, `npx -p typescript tsc`, `pnpm exec tsc` and `node ./node_modules/typescript/bin/tsc`.
|
|
293
|
+
- `build` passes `--skipLibCheck` (in any letter case) to a `tsc` program (`-p`/`--project`, `tsconfig.json` when absent) that no `tsc` run of `typecheck` covers without `--skipLibCheck`. `./tsconfig.build.json` and `tsconfig.build.json`, `-p .` and no `-p` are the same program. `pre<script>` scripts count with their script, and `&&` chains, parentheses, `cross-env` and environment prefixes, `run-s` and `npm-run-all`, and scripts run through `pnpm`, `npm`, `yarn` or `bun` (`--filter <x>`, `-C <dir>` and other options with a value included) are followed to five levels. `tsc` is recognised as `tsc`, `npx tsc`, `npx -p typescript tsc`, `pnpm exec tsc` and `node ./node_modules/typescript/bin/tsc`. `antelopejs-tsc` is recognised wherever `tsc` is: on its own, through `npx`, `pnpm exec` or a package manager, and as `node_modules/.bin/antelopejs-tsc`.
|
|
316
294
|
- A tsconfig the scripts use through `tsc`, or the root `tsconfig.json`, ends up with `compilerOptions.skipLibCheck: true`, set directly or through a local `extends` chain (`.json` or `.jsonc`, a later duplicate key winning as in tsc). `tsc -b` reads the config it names and the projects they reference. Presets extended from a package are not read. When the file that sets it is one git ignores, such as Nuxt's generated `.nuxt/tsconfig.json`, the note names the first tracked tsconfig of the chain and asks for `skipLibCheck: false` there; when none is tracked, nothing is reported.
|
|
317
295
|
- A `release` script exists and does not run `typecheck`, directly or through a script it runs, its `prerelease`, or a release-it hook that runs before publishing (`before:init`, `before:bump`, `before:release` and their plugin-scoped forms), read from `.release-it.json` and from `release-it.hooks` in `package.json`.
|
|
318
296
|
- A file the check needs cannot be read (a directory where a tsconfig is expected, a permission error): both commands print a `Note:` that says "could not read …" and neither fails on it.
|
|
@@ -321,9 +299,36 @@ No repository sets `skipLibCheck` globally. `typecheck` runs a full `tsc --noEmi
|
|
|
321
299
|
|
|
322
300
|
Known blind spots, none of them read: `|| true` or a background `&` after a `typecheck`, a `typecheck` placed after `release-it` in `release`, a `typecheck` that checks nothing, `vue-tsc`, release-it configs other than JSON (`.release-it.js`, `.yaml`, `.toml`), presets extended from a package, and workspace packages.
|
|
323
301
|
|
|
302
|
+
### TypeScript 7 for build and typecheck
|
|
303
|
+
|
|
304
|
+
A repository keeps TypeScript 6 as its `typescript` package and can build and type-check with TypeScript 7, the native compiler. The pack lists TypeScript 7's native compiler packages, `@typescript/typescript-<platform>-<arch>` at `~7.0.2`, as optional dependencies, so the package manager installs the one for the platform it runs on, and `antelopejs-tsc` runs that compiler with its arguments unchanged. Installing the pack leaves the repository's `tsc` the one its own `typescript` ships, whatever its version, under npm, pnpm, yarn and bun. npm links into `node_modules/.bin` the `tsc` of a package at the root of `node_modules`, the first in name order when several ship one, so a package that ships a `tsc` under another name than `typescript` can replace the repository's. The pack installs none: its compiler packages have no bin, and its TypeScript 6 is a plain `typescript` dependency, which the package manager may share with the repository's `typescript` when that one satisfies `^6.0.2` and otherwise installs under the pack, never in the root `typescript` the repository owns. An override of `typescript` in the repository (`overrides` under npm, bun and pnpm, `resolutions` under yarn) reaches the pack's dependency too; the pack's commands then stop with a message that names the version found and the scoped override that exempts the pack, such as `"overrides": { "@antelopejs/tooling-configs": { "typescript": "^6.0.2" } }` under npm. Under yarn 1 the exemption, `"**/@antelopejs/tooling-configs/typescript": "^6.0.2"`, must come before any other `resolutions` key that matches `typescript`, because yarn 1 applies the first one that matches.
|
|
305
|
+
|
|
306
|
+
To opt in, call `antelopejs-tsc` in place of `tsc` in `build` and `typecheck`, with the same arguments. To back out, call `tsc` again.
|
|
307
|
+
|
|
308
|
+
```json
|
|
309
|
+
{
|
|
310
|
+
"scripts": {
|
|
311
|
+
"build": "antelopejs-tsc",
|
|
312
|
+
"typecheck": "antelopejs-tsc --noEmit"
|
|
313
|
+
}
|
|
314
|
+
}
|
|
315
|
+
```
|
|
316
|
+
|
|
317
|
+
Before opting in, remove from the tsconfig chain the options TypeScript 6 deprecated: `baseUrl`, `moduleResolution` set to `node`, `node10` or `classic`, `target` set to `es5`, `downlevelIteration`, `outFile`, `module` set to `amd`, `umd` or `system`, and `esModuleInterop`, `allowSyntheticDefaultImports` or `alwaysStrict` set to `false`. TypeScript 7 refuses each one with an error that names it, such as `error TS5102: Option 'baseUrl' has been removed`, and exits non-zero. `ignoreDeprecations: "6.0"` does not bring them back.
|
|
318
|
+
|
|
319
|
+
Only `build` and `typecheck` change. TypeScript 7.0 ships no compiler API, so everything that loads one stays on TypeScript 6: the `antelopejs` lint rules, `antelopejs-api-diff`, `antelopejs-comment-proof`, the auto-import checks and dts-bundle-generator load the pack's own `typescript` 6 dependency, and `verify:types`, vue-tsc, `nuxi typecheck`, ts-node and editors use the repository's `typescript`. Sync reads `antelopejs-tsc` wherever it reads `tsc`, so [Lib check coverage](#lib-check-coverage) holds for a repository that opted in.
|
|
320
|
+
|
|
321
|
+
Known differences between the two compilers' output:
|
|
322
|
+
|
|
323
|
+
- JavaScript is the same, except for a class that names itself in one of its member decorators: TypeScript 7 emits a `<Name>_1` alias assigned in a `static {}` block where TypeScript 6 names the class.
|
|
324
|
+
- Declarations describe the same types. Without `stableTypeOrdering`, TypeScript 6 can print union members in another order. With `stableTypeOrdering: true` in the tsconfig, which TypeScript 7 accepts, the order matches, and what remains is a type one compiler prints through an alias and the other spells out, such as `value is string` for `value is TypeofTags["string"]`.
|
|
325
|
+
- Source maps differ.
|
|
326
|
+
|
|
327
|
+
`antelopejs-api-diff` emits both revisions' declarations with TypeScript 6 from the repository's tsconfig, so it reports any change to the API between them whichever compiler builds the package. It does not compare those declarations with the ones TypeScript 7 ships; `stableTypeOrdering` brings the two to the same order. Its runtime check runs the package's `build`, so it compares the JavaScript TypeScript 7 emits once the repository opted in.
|
|
328
|
+
|
|
324
329
|
### Suppression budget
|
|
325
330
|
|
|
326
|
-
`guardrails.suppressions.json` caps the suppressions in authored code files. It is
|
|
331
|
+
`guardrails.suppressions.json` caps the suppressions in authored code files. It is permanent: it stays when its counts reach zero.
|
|
327
332
|
|
|
328
333
|
```json
|
|
329
334
|
{
|
|
@@ -342,20 +347,20 @@ Known blind spots, none of them read: `|| true` or a background `&` after a `typ
|
|
|
342
347
|
- `antelopejs-suppressions --update` lowers each ceiling to the current count and keeps rules at zero. No command raises a ceiling.
|
|
343
348
|
- `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.
|
|
344
349
|
- `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.
|
|
345
|
-
-
|
|
350
|
+
- `antelopejs-suppressions --staged` 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.
|
|
346
351
|
- `@ts-ignore` is also a lint error (`typescript/ban-ts-comment`); `@ts-expect-error` fails once its error is gone.
|
|
347
352
|
- 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 five `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.
|
|
348
|
-
- Both modes also hold each lint directive in a file the change touches to two rules, whether the directive was added or already on the base. It must suppress something: one extra `oxlint --report-unused-disable-directives` run over the touched files that contain a directive, under the repository's own lint configuration
|
|
353
|
+
- Both modes also hold each lint directive in a file the change touches to two rules, whether the directive was added or already on the base. It must suppress something: one extra `oxlint --report-unused-disable-directives` run over the touched files that contain a directive, under the repository's own lint configuration, so a directive for a rule the preset does not run is dead. A dead directive fails with its `file:line`, naming the rule to drop when the directive names several, or telling you to delete it. It must also give a reason: a directive naming rules with no ` -- <reason>` fails whenever its file is touched, though the added-suppression policy above only judges the reason of an added one. Touched files are the staged files with `--staged`, and in the full check the working tree against the merge-base with the pull request base (the base itself when there is no merge-base, as in a shallow checkout), untracked files included, or against HEAD without a base. A file the change does not touch is not read, so upgrading the pack fails no existing file; its dead and reasonless directives surface when a change next touches the file. `eslint-` directives in a directory with an ESLint config are left to ESLint, and `.vue` files are not read by oxlint. Deleting a dead directive lowers the budget: run `suppressions:update`.
|
|
349
354
|
|
|
350
355
|
### Size
|
|
351
356
|
|
|
352
|
-
`antelopejs-check-size` fails on an authored file over 20,000 bytes, tests included. The repository's own files under the agent directories count; the files `antelopejs-sync` writes there (the `SYNCED_AGENT_PATTERNS` that lint skips) do not. 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.
|
|
357
|
+
`antelopejs-check-size` fails on an authored file over 20,000 bytes, tests included. The repository's own files under the agent directories count; the files `antelopejs-sync` writes there (the `SYNCED_AGENT_PATTERNS` that lint skips) do not. 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.
|
|
353
358
|
|
|
354
|
-
Pass paths to check only those files
|
|
359
|
+
Pass paths to check only those files. 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.
|
|
355
360
|
|
|
356
361
|
### Cleanup proof
|
|
357
362
|
|
|
358
|
-
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 the pack's own TypeScript 6
|
|
363
|
+
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 the pack's own TypeScript 6, its `typescript` dependency, never a `typescript` of another major the repository installs, so a repository on TypeScript 7, which has no compiler API, is proven like any other. The package's config is read as the TypeScript it installs reads it: on TypeScript 5, each option whose default TypeScript 6 changed (`strict`, `alwaysStrict`, `types`, `module`, `moduleResolution`, `esModuleInterop`, `allowSyntheticDefaultImports`, `noUncheckedSideEffectImports`, `target`) keeps its TypeScript 5 default when the config leaves it unset, the options TypeScript 6 deprecated, such as `baseUrl`, still compile, and the output is laid out under the common directory of the sources when no `rootDir` is set. A package that declares `typescript` but cannot resolve it fails with an execution error naming the package and asking for an install, because the pack cannot tell which defaults it builds with; one that declares none is read with TypeScript 6's defaults. 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. The bundles of both revisions are compared as one `declarations.d.ts`: an index of every published entry, then each distinct declaration text once, under one `// In` line per entry that carries it (`// In every entry` when all do). A change shared by many entries is printed once. The first hunk that changes a declaration below its `// In` lines names its entries in the hunk header, and an added or removed entry prints one index line and one `// In` line per declaration it shares. 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.
|
|
359
364
|
|
|
360
365
|
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.
|
|
361
366
|
|
|
@@ -380,28 +385,6 @@ pnpm exec antelopejs-api-diff origin/main
|
|
|
380
385
|
pnpm exec antelopejs-comment-proof origin/main
|
|
381
386
|
```
|
|
382
387
|
|
|
383
|
-
### PR body check
|
|
384
|
-
|
|
385
|
-
Both proof commands end their output with a `<!-- antelopejs-proof ... -->` line that stamps the base, the committed head, the command, the number of lines printed and a digest of them. Paste the whole output down to that line, which renders invisibly; indenting it, wrapping it in a code fence or re-padding the tables keeps it valid. The check reads the stamped number of non-blank lines above the stamp as the copy.
|
|
386
|
-
|
|
387
|
-
`antelopejs-body-check --findings` prints every lint finding of the working tree as a block between `<!-- antelopejs-findings begin -->` and `<!-- antelopejs-findings end -->`, one ``- `path:line` `rule`: <why>`` line per finding under a `` `rule` (count): `` line. Paste it under the findings-left heading, replace each `<why>` with the reason the finding stays, and delete the rules the pull request does not report on. Lines may be regrouped under prose bullets.
|
|
388
|
-
|
|
389
|
-
`antelopejs-body-check <body.md>` (`-` reads standard input) checks the body against the repository at HEAD and prints one line per problem:
|
|
390
|
-
|
|
391
|
-
- a proof block whose lines no longer match its digest, whose head is not in the branch, or, for api-diff, whose head tree is not HEAD's; a suppression table that no longer matches the counts at HEAD against the stamped base. A comment-proof block may be stamped at an earlier commit of the branch, so a comment-only commit can be proven under a later code commit;
|
|
392
|
-
- a suppression table or a proof summary line (`API:`, `Runtime API:`, `Comment proof:`) outside a stamped block;
|
|
393
|
-
- in a findings block: a line that is not a live diagnostic of that rule at that line, a listed rule with a live finding the block leaves out, a finding with no reason, a `path:line` written outside the item form, and a count such as ``(9 `no-unknown-parameters`)`` that differs from the items of that rule under it;
|
|
394
|
-
- a code file named (`path.ts`, with or without `:line`, or a range) in a findings-left section outside a findings block. A section opens at a heading, or at a plain or bold title line, that says what is left, kept or remaining under the ratchet or in findings (`## Findings left under the ratchet`, `Findings left under the ratchet:`, `**Left under the ratchet**`, `## Kept under the ratchet`, `## Not fixed`), and ends at the next heading of its level or above (the next heading of any level for a plain or bold line);
|
|
395
|
-
- with `--base <sha>`, an api-diff block compared against a revision whose merge-base with HEAD is not the pull request base's.
|
|
396
|
-
|
|
397
|
-
Counts in prose are not checked. Run it on a checkout of the pull request head, with history back to the stamped base:
|
|
398
|
-
|
|
399
|
-
```bash
|
|
400
|
-
gh pr view <number> --json body --jq .body | pnpm exec antelopejs-body-check -
|
|
401
|
-
```
|
|
402
|
-
|
|
403
|
-
In CI, run it in a `pull_request` job (types `opened`, `edited`, `synchronize`) that checks out `github.event.pull_request.head.sha` with `fetch-depth: 0`, installs dependencies, and passes the body through the environment rather than inline in the script: `printf '%s' "$PR_BODY" | pnpm exec antelopejs-body-check - --head "$HEAD_SHA"`. `--head` fails when the checkout is not that commit. Add `--base "$BASE_SHA"` (`github.event.pull_request.base.sha`) so an api-diff block cannot be taken against HEAD itself.
|
|
404
|
-
|
|
405
388
|
## oxfmt
|
|
406
389
|
|
|
407
390
|
```ts
|
|
@@ -505,7 +488,7 @@ checks that remain the author's responsibility.
|
|
|
505
488
|
|
|
506
489
|
## Contributing
|
|
507
490
|
|
|
508
|
-
See [CONTRIBUTING.md](./CONTRIBUTING.md). `pnpm install`, then `pnpm checks` runs the typecheck, lint, format check, Knip, tests, size and sync checks.
|
|
491
|
+
See [CONTRIBUTING.md](./CONTRIBUTING.md). `pnpm install`, then `pnpm checks` runs the typecheck, lint, format check, Knip, tests, size and sync checks.
|
|
509
492
|
|
|
510
493
|
## Part of AntelopeJS
|
|
511
494
|
|
package/dist/bin/api-diff.mjs
CHANGED
|
@@ -1,16 +1,15 @@
|
|
|
1
1
|
#!/usr/bin/env node
|
|
2
|
-
import { o as packageManager, s as parseManifest } from "../package-
|
|
3
|
-
import {
|
|
2
|
+
import { o as packageManager, s as parseManifest } from "../package-7oylgBeT.mjs";
|
|
3
|
+
import { t as typescript6_default } from "../typescript6-HdyOMBv3.mjs";
|
|
4
|
+
import { r as installedTypeScriptMajor, t as asInstalledCompilerReads } from "../installed-typescript-CF_FR9DV.mjs";
|
|
4
5
|
import { t as runCli } from "../cli-4Tv71vYk.mjs";
|
|
5
|
-
import { c as
|
|
6
|
+
import { c as resolveRevision, s as repositoryRoot } from "../files-BbzJEk-L.mjs";
|
|
6
7
|
import { n as shimInvocation } from "../run-command-BlFRPORx.mjs";
|
|
7
|
-
import {
|
|
8
|
-
import { c as unpublishedAt, i as isTestSource, o as outputRoot, r as isExportPath, s as packagesAt, t as emitPackage } from "../typescript-QfxkJYzd.mjs";
|
|
8
|
+
import { _ as recordVerdict, c as unpublishedAt, d as revisionCounts, f as workspaceManifests, g as fillStars, h as describeAllowance, i as isTestSource, l as DIRECTORY_LINK, m as createAddedPolicy, o as outputRoot, p as allowedByGlob, r as isExportPath, s as packagesAt, t as emitPackage, u as compareRevisions } from "../typescript-C7eU-cig.mjs";
|
|
9
9
|
import { createRequire } from "node:module";
|
|
10
10
|
import { copyFileSync, cpSync, existsSync, globSync, mkdirSync, readFileSync, readdirSync, realpathSync, rmSync, statSync, symlinkSync, writeFileSync } from "node:fs";
|
|
11
11
|
import { basename, dirname, isAbsolute, join, parse, posix, relative, resolve, sep } from "node:path";
|
|
12
12
|
import { execFileSync, spawnSync } from "node:child_process";
|
|
13
|
-
import ts from "@typescript/typescript6";
|
|
14
13
|
import { availableParallelism, freemem } from "node:os";
|
|
15
14
|
import { parseArgs } from "node:util";
|
|
16
15
|
//#region src/guardrails/auto-import-globals.ts
|
|
@@ -370,10 +369,10 @@ function describe(compiler, checker, name, exported, source) {
|
|
|
370
369
|
/** The auto-import surface of one frontend module: one sorted line per name and meaning that unimport would expose from its scanned files. Exports are read with the module's compiler, so `export *` and inferred types resolve as the frontend workspace types them. */
|
|
371
370
|
function moduleSurface(worktree, directory) {
|
|
372
371
|
const moduleRoot = join(worktree, directory);
|
|
373
|
-
const files = scannedFiles(moduleRoot, declaredDirectories(
|
|
374
|
-
const options = compilerOptions(
|
|
375
|
-
const presets = presetModules(
|
|
376
|
-
const plain =
|
|
372
|
+
const files = scannedFiles(moduleRoot, declaredDirectories(typescript6_default, join(moduleRoot, BUILD_FILE), posix.join(directory, BUILD_FILE)));
|
|
373
|
+
const options = compilerOptions(typescript6_default, moduleRoot);
|
|
374
|
+
const presets = presetModules(typescript6_default, moduleRoot, options);
|
|
375
|
+
const plain = typescript6_default.createProgram([...files, ...presets.map(({ file }) => file)], options);
|
|
377
376
|
const scanned = new Map(files.flatMap((file) => {
|
|
378
377
|
const source = plain.getSourceFile(file);
|
|
379
378
|
return source === void 0 ? [] : [[source.fileName, source]];
|
|
@@ -389,13 +388,13 @@ function moduleSurface(worktree, directory) {
|
|
|
389
388
|
specifier: sourceSpecifier(source.fileName)
|
|
390
389
|
}))];
|
|
391
390
|
const imports = autoImports(plain.getTypeChecker(), sources);
|
|
392
|
-
const program =
|
|
391
|
+
const program = typescript6_default.createProgram(files, options, injectingHost(typescript6_default, options, scanned, imports));
|
|
393
392
|
const checker = program.getTypeChecker();
|
|
394
393
|
const lines = /* @__PURE__ */ new Set();
|
|
395
394
|
for (const file of files) {
|
|
396
395
|
const source = program.getSourceFile(file);
|
|
397
396
|
if (source === void 0) continue;
|
|
398
|
-
for (const { name, symbol } of exportedNames(checker, source)) for (const line of describe(
|
|
397
|
+
for (const { name, symbol } of exportedNames(checker, source)) for (const line of describe(typescript6_default, checker, name, symbol, source)) lines.add(line.split(worktree).join("<root>"));
|
|
399
398
|
}
|
|
400
399
|
return [...lines].sort();
|
|
401
400
|
}
|
|
@@ -455,11 +454,11 @@ for (const job of jobs) {
|
|
|
455
454
|
});
|
|
456
455
|
}
|
|
457
456
|
`;
|
|
458
|
-
/** Places a copy of `dts-bundle-generator` beside a `typescript` link to the pack's
|
|
457
|
+
/** Places a copy of `dts-bundle-generator` beside a `typescript` link to the pack's own `typescript` 6. The generator requires `typescript` by name, and the one it was installed with may be TypeScript 7, which has no compiler API, so this makes it drive the pack's TypeScript 6. Returns a path to require the copy from. */
|
|
459
458
|
function installGenerator(scratch) {
|
|
460
459
|
const require = createRequire(import.meta.url);
|
|
461
460
|
const source = dirname(require.resolve("dts-bundle-generator/package.json"));
|
|
462
|
-
const compilerRoot = dirname(require.resolve("
|
|
461
|
+
const compilerRoot = dirname(require.resolve("typescript/package.json"));
|
|
463
462
|
const modules = join(scratch, "generator", "node_modules");
|
|
464
463
|
mkdirSync(modules, { recursive: true });
|
|
465
464
|
cpSync(source, join(modules, "dts-bundle-generator"), {
|
|
@@ -792,11 +791,6 @@ function childFailure(result) {
|
|
|
792
791
|
function formatJson(json) {
|
|
793
792
|
return `${JSON.stringify(JSON.parse(json), null, 2)}\n`;
|
|
794
793
|
}
|
|
795
|
-
function childJson(args, cwd) {
|
|
796
|
-
const result = runChild(args, cwd);
|
|
797
|
-
if (result.status !== 0) throw childFailure(result);
|
|
798
|
-
return formatJson(result.stdout);
|
|
799
|
-
}
|
|
800
794
|
/** Describes one built entry into `destination`, away from the entry's own stdout, with the exit code of an entry that ends with a non-zero code or exits while it loads; an uncaught error is a failure. */
|
|
801
795
|
function describeEntry(describe, file, destination, cwd) {
|
|
802
796
|
rmSync(destination, { force: true });
|
|
@@ -939,8 +933,8 @@ function buildPackage(directory, manager, output, manifest, describe) {
|
|
|
939
933
|
skipped
|
|
940
934
|
};
|
|
941
935
|
}
|
|
942
|
-
/** Builds both committed revisions and compares published runtime metadata
|
|
943
|
-
function runtimeDiff(root, baseRef,
|
|
936
|
+
/** Builds both committed revisions and compares published runtime metadata. */
|
|
937
|
+
function runtimeDiff(root, baseRef, policy) {
|
|
944
938
|
const errors = [];
|
|
945
939
|
const failedPackages = /* @__PURE__ */ new Set();
|
|
946
940
|
const skippedPackages = /* @__PURE__ */ new Set();
|
|
@@ -981,11 +975,6 @@ function runtimeDiff(root, baseRef, probe, policy) {
|
|
|
981
975
|
recursive: true,
|
|
982
976
|
force: true
|
|
983
977
|
});
|
|
984
|
-
if (probe !== void 0) {
|
|
985
|
-
const script = join(scratch, "probe.cjs");
|
|
986
|
-
writeFileSync(script, probe);
|
|
987
|
-
writeFileSync(join(output, "probe.json"), childJson([script, worktree], worktree));
|
|
988
|
-
}
|
|
989
978
|
return {
|
|
990
979
|
packages: packages.map(({ directory }) => directory),
|
|
991
980
|
entries,
|
|
@@ -1192,13 +1181,13 @@ function bundlePackage(paths, manifest, policy) {
|
|
|
1192
1181
|
for (const [index, { entry }] of entries.entries()) {
|
|
1193
1182
|
const path = join(output, entry);
|
|
1194
1183
|
mkdirSync(dirname(path), { recursive: true });
|
|
1195
|
-
writeFileSync(path, normalizeBundle(
|
|
1184
|
+
writeFileSync(path, normalizeBundle(typescript6_default, bundles[index]));
|
|
1196
1185
|
}
|
|
1197
1186
|
if (policy !== void 0) for (const { file, subpath } of entries) {
|
|
1198
1187
|
if (!allowedByGlob(policy, subpath)) continue;
|
|
1199
1188
|
const emittedFile = join(scratch, file);
|
|
1200
1189
|
const module = emitted.modules.get(resolve(emittedFile)) ?? emittedFile;
|
|
1201
|
-
recordVerdict(policy,
|
|
1190
|
+
recordVerdict(policy, typescript6_default, {
|
|
1202
1191
|
directory: paths.name,
|
|
1203
1192
|
subpath,
|
|
1204
1193
|
module,
|
|
@@ -1254,7 +1243,7 @@ function declarationDiff(root, baseRef, policy) {
|
|
|
1254
1243
|
};
|
|
1255
1244
|
}, {
|
|
1256
1245
|
policy,
|
|
1257
|
-
collate: (output) => collateDeclarations(
|
|
1246
|
+
collate: (output) => collateDeclarations(typescript6_default, output),
|
|
1258
1247
|
annotate: labelHunks
|
|
1259
1248
|
});
|
|
1260
1249
|
return {
|
|
@@ -1262,15 +1251,14 @@ function declarationDiff(root, baseRef, policy) {
|
|
|
1262
1251
|
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("") + [...skippedTests].sort().join("") + [...errors].join("")
|
|
1263
1252
|
};
|
|
1264
1253
|
}
|
|
1265
|
-
/** Compares declarations, built runtime exports and the auto-import surface of DMS frontend modules
|
|
1266
|
-
function apiDiff(root, baseRef,
|
|
1254
|
+
/** Compares declarations, built runtime exports and the auto-import surface of DMS frontend modules. Added entries whose subpath matches an `allowAdded` glob pass when their module is `@internal`. */
|
|
1255
|
+
function apiDiff(root, baseRef, allowAdded = []) {
|
|
1267
1256
|
const policy = allowAdded.length ? createAddedPolicy(allowAdded) : void 0;
|
|
1268
|
-
const probe = probeFile === void 0 ? void 0 : readFileSync(resolve(root, probeFile));
|
|
1269
1257
|
const results = [];
|
|
1270
1258
|
const errors = [];
|
|
1271
1259
|
for (const compare of [
|
|
1272
1260
|
() => declarationDiff(root, baseRef, policy),
|
|
1273
|
-
() => runtimeDiff(root, baseRef,
|
|
1261
|
+
() => runtimeDiff(root, baseRef, policy),
|
|
1274
1262
|
() => autoImportDiff(root, baseRef)
|
|
1275
1263
|
]) try {
|
|
1276
1264
|
const result = compare();
|
|
@@ -1278,31 +1266,23 @@ function apiDiff(root, baseRef, probeFile, allowAdded = []) {
|
|
|
1278
1266
|
} catch (error) {
|
|
1279
1267
|
errors.push(`Execution error: ${error instanceof Error ? error.message : String(error)}\n`);
|
|
1280
1268
|
}
|
|
1281
|
-
const command = [
|
|
1282
|
-
`antelopejs-api-diff ${baseRef}`,
|
|
1283
|
-
...probeFile === void 0 ? [] : [`--probe ${probeFile}`],
|
|
1284
|
-
...allowAdded.map((glob) => `--allow-added '${glob}'`)
|
|
1285
|
-
].join(" ");
|
|
1286
1269
|
return {
|
|
1287
1270
|
different: errors.length > 0 || results.some((result) => result.different) || (policy?.problems.size ?? 0) > 0,
|
|
1288
|
-
output:
|
|
1271
|
+
output: results.map((result) => result.output).join("") + (policy === void 0 ? "" : describeAllowance(policy)) + errors.join("") + revisionCounts(root, baseRef)
|
|
1289
1272
|
};
|
|
1290
1273
|
}
|
|
1291
1274
|
//#endregion
|
|
1292
1275
|
//#region src/bin/api-diff.ts
|
|
1293
|
-
const USAGE = "Usage: antelopejs-api-diff <base-ref> [--
|
|
1276
|
+
const USAGE = "Usage: antelopejs-api-diff <base-ref> [--allow-added <glob>]...";
|
|
1294
1277
|
function parse$1(args) {
|
|
1295
1278
|
try {
|
|
1296
1279
|
const { positionals, values } = parseArgs({
|
|
1297
1280
|
args,
|
|
1298
1281
|
allowPositionals: true,
|
|
1299
|
-
options: {
|
|
1300
|
-
|
|
1301
|
-
|
|
1302
|
-
|
|
1303
|
-
multiple: true
|
|
1304
|
-
}
|
|
1305
|
-
}
|
|
1282
|
+
options: { "allow-added": {
|
|
1283
|
+
type: "string",
|
|
1284
|
+
multiple: true
|
|
1285
|
+
} }
|
|
1306
1286
|
});
|
|
1307
1287
|
if (positionals.length !== 1) throw new Error(USAGE);
|
|
1308
1288
|
return {
|
|
@@ -1314,8 +1294,8 @@ function parse$1(args) {
|
|
|
1314
1294
|
}
|
|
1315
1295
|
}
|
|
1316
1296
|
runCli(() => {
|
|
1317
|
-
const { baseRef,
|
|
1318
|
-
const result = apiDiff(repositoryRoot(), baseRef,
|
|
1297
|
+
const { baseRef, "allow-added": allowAdded } = parse$1(process.argv.slice(2));
|
|
1298
|
+
const result = apiDiff(repositoryRoot(), baseRef, allowAdded);
|
|
1319
1299
|
process.stdout.write(result.output);
|
|
1320
1300
|
return result.different ? 1 : 0;
|
|
1321
1301
|
});
|
package/dist/bin/capture.mjs
CHANGED
|
@@ -2,14 +2,14 @@
|
|
|
2
2
|
import { a as isString, c as object, f as parseJson, i as isObject, m as strings, r as flag, t as child, u as optStr } from "../json-CG2L7YFl.mjs";
|
|
3
3
|
import { n as parseScenes, r as selectScenes } from "../scenes-d-VQ0LOm.mjs";
|
|
4
4
|
import { n as runCliAsync } from "../cli-4Tv71vYk.mjs";
|
|
5
|
-
import {
|
|
5
|
+
import { s as repositoryRoot } from "../files-BbzJEk-L.mjs";
|
|
6
6
|
import { t as relativeSlashed } from "../slash-BEgSnfYw.mjs";
|
|
7
7
|
import { t as killTree } from "../launch-D5cylwvb.mjs";
|
|
8
|
+
import { parse, stringify } from "yaml";
|
|
8
9
|
import { cpSync, existsSync, mkdirSync, mkdtempSync, readFileSync, readdirSync, rmSync, writeFileSync } from "node:fs";
|
|
9
10
|
import { dirname, join } from "node:path";
|
|
10
|
-
import { execFileSync, spawn, spawnSync } from "node:child_process";
|
|
11
|
-
import { parse as parse$1, stringify } from "yaml";
|
|
12
11
|
import { pathToFileURL } from "node:url";
|
|
12
|
+
import { execFileSync, spawn, spawnSync } from "node:child_process";
|
|
13
13
|
import { tmpdir } from "node:os";
|
|
14
14
|
import { parseArgs } from "node:util";
|
|
15
15
|
import { setTimeout as setTimeout$1 } from "node:timers/promises";
|
|
@@ -94,7 +94,7 @@ function packageOverrides(root) {
|
|
|
94
94
|
* demo keeps in `package.json` must be in the workspace file too.
|
|
95
95
|
*/
|
|
96
96
|
function workspaceWithOverrides(text, overrides, builds) {
|
|
97
|
-
const existing = text.trim() === "" ? {} : object(parse
|
|
97
|
+
const existing = text.trim() === "" ? {} : object(parse(text), "pnpm-workspace.yaml");
|
|
98
98
|
const settings = {
|
|
99
99
|
...existing,
|
|
100
100
|
overrides: {
|