@antelopejs/tooling-configs 0.5.0 → 0.5.1
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 +52 -25
- package/dist/bin/checks.mjs +36 -2
- package/dist/bin/garden.mjs +6 -1
- package/dist/bin/lease.mjs +48 -11
- package/dist/bin/ratchet.mjs +1 -1
- package/dist/bin/sync.mjs +126 -40
- package/dist/bin/verify.mjs +211 -54
- package/dist/oxc/anti-slop/index.mjs +106 -366
- package/dist/oxc/guardrails/index.d.mts +1 -1
- package/dist/oxc/guardrails/index.mjs +279 -10
- package/dist/oxc/lint.d.mts +6 -0
- package/dist/oxc/lint.mjs +3 -1
- package/dist/{ratchet-BTiPMqam.mjs → ratchet-ClfblHNJ.mjs} +1 -0
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -116,15 +116,15 @@ export default defineConfig({
|
|
|
116
116
|
|
|
117
117
|
### What the preset turns on
|
|
118
118
|
|
|
119
|
-
| Group | Rules
|
|
120
|
-
| -------------- |
|
|
121
|
-
| oxc | the `correctness` category, with the `eslint`, `typescript`, `node`, `oxc`, `import` and `promise` plugins; `no-unused-vars` (`_` prefix allowed), `eqeqeq` (`== null` allowed), `radix`, `prefer-regex-literals`, `typescript/ban-ts-comment` for `@ts-ignore` only
|
|
122
|
-
| Imports | `import/no-cycle`, `import/no-self-import`, `import/no-duplicates`
|
|
123
|
-
| Type-aware | `typescript/no-floating-promises` and thirteen more type-aware rules, including `no-unnecessary-type-parameters`, `no-unsafe-argument`, `no-unsafe-assignment`, `no-unsafe-return` and `use-unknown-in-catch-callback-variable`
|
|
124
|
-
| Complexity | `max-params` 5, `max-lines-per-function` 120, `max-lines` 500, `max-depth` 4, `complexity` 20
|
|
125
|
-
| Anti-slop | all 15 vendored rules; `no-runtime-typeof` with `allowInTypeGuards`, so a `typeof` (or `.constructor === String`) inside a type predicate or assertion function passes
|
|
126
|
-
| Guardrails | `antelopejs/no-comments`, `antelopejs/no-inherited-key-lookup`, `antelopejs/no-presence-only-type-guard`, and with type-aware lint `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 |
|
|
127
|
-
| Import sorting | `perfectionist/sort-imports`, autofixed by `oxlint --fix`
|
|
119
|
+
| Group | Rules | Default |
|
|
120
|
+
| -------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------- |
|
|
121
|
+
| oxc | the `correctness` category, with the `eslint`, `typescript`, `node`, `oxc`, `import` and `promise` plugins; `no-unused-vars` (`_` prefix allowed), `eqeqeq` (`== null` allowed), `radix`, `prefer-regex-literals`, `typescript/ban-ts-comment` for `@ts-ignore` only | error |
|
|
122
|
+
| Imports | `import/no-cycle`, `import/no-self-import`, `import/no-duplicates` | error |
|
|
123
|
+
| Type-aware | `typescript/no-floating-promises` and thirteen more type-aware rules, including `no-unnecessary-type-parameters`, `no-unsafe-argument`, `no-unsafe-assignment`, `no-unsafe-return` and `use-unknown-in-catch-callback-variable` | error |
|
|
124
|
+
| Complexity | `max-params` 5, `max-lines-per-function` 120, `max-lines` 500, `max-depth` 4, `complexity` 20 | error |
|
|
125
|
+
| Anti-slop | all 15 vendored rules; `no-runtime-typeof` with `allowInTypeGuards`, so a `typeof` (or `.constructor === String`) inside a type predicate or assertion function passes | error |
|
|
126
|
+
| 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-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 |
|
|
127
|
+
| Import sorting | `perfectionist/sort-imports`, autofixed by `oxlint --fix` | off |
|
|
128
128
|
|
|
129
129
|
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, the `unknown` parameters of a function type that annotates a plain callback parameter which the function only calls (and tests for existence), at least once, passing a never-reassigned catch variable in each `unknown` position (a callback that is stored, passed on, never called or called with any other value stays reported), a parameter typed exactly `unknown` of a function whose declared return type is primitive and whose only use of it is to read a symbol-keyed member (`value[BRAND]`, `BRAND in value`) of a `const` bound to `Symbol(...)` or `Symbol.for(...)` in the file, directly, through a `const` alias, or through a function declared in the file that does the same, behind type guards declared in the file, where the member is only read and what is read reaches nothing but the result (it may be tested, compared, negated, read further, passed to `Boolean(...)` or held in a `const` that obeys the same rule; a write, `delete`, update, call of the member, or an argument to any other call refuses), the brand probe, and a parameter typed exactly `unknown` at a parse boundary: the function only passes it to a schema or decoder that is not written in the same file, meaning its root, followed through members, calls, `const` aliases, `import x = Namespace.member` aliases, parameter and destructuring defaults, assignments and type wrappers, is a module import, a global that nothing in the file assigns, or a parameter that nothing in the file defaults or assigns, and not a name that the file may merge or write (a name read inside a namespace block that the block does not bind itself, which another block of the namespace may declare as a member that shadows an import or a global), a function, class, namespace, object literal, `let`, a `this` that is not the class's own (the `this` of an object-literal method or a nested function), a class element of another name, kind or static-ness, or a call handed an object, an array or a `this` that holds a function written here, or a call on a global (`Object.freeze`, `Array.from`, `Promise.resolve`) handed any function written here (`parse`, `safeParse`, `parseAsync`, `safeParseAsync`, `decode`, a `parseX` or `decodeX` helper, `assertValidation`), never mentions `arguments` or `eval`, and returns that call's result under a declared return type other than `unknown` or `any`.
|
|
130
130
|
|
|
@@ -134,18 +134,19 @@ No rule warns. oxlint reports `correctness` as warnings by default, and warnings
|
|
|
134
134
|
|
|
135
135
|
The guardrail rules:
|
|
136
136
|
|
|
137
|
-
| Rule | Fails on
|
|
138
|
-
| ----------------------------------------- |
|
|
139
|
-
| `antelopejs/no-comments` | `//` and `/* */` comments. Allowed: TSDoc `/** */`, `SAFETY: <reason>` (one block, or a run of `//` lines), `/*!` license headers, `@ts-expect-error <reason>`, oxlint/eslint directives that name their rules, `/// <reference />`, `#__PURE__`/`@__PURE__`, `@vite-ignore` and webpack magic comments, `prettier-ignore`/`oxfmt-ignore`
|
|
140
|
-
| `antelopejs/no-inherited-key-lookup` | `table[key]` (or `table[key] += ...`) with a computed key, or `key in table`, where `table` is declared in the same file as a string-keyed dictionary (`Record<string, V>`, `Record<PropertyKey, V>`, a string index signature, `Readonly`/`Partial` of one, a union with `undefined` or `null`, a local alias or `typeof` another table, `satisfies` or `as Record<string, V>`, a class field read as `this.field[key]`), or an untyped object literal read with an asserted key (`table[key as keyof typeof table]`). Inherited keys such as `constructor` answer `Object.prototype` members. Not reported: literal keys, `typeof x` keys, same-file `const` keys (`KEY`, `LABELS.name` of a literal-valued object), keys iterated from an array of string literals or from `Object.keys(table)`, `Object.entries(table)` or `for...in` of the same table (through `filter`, `sort` and similar), writes and `delete`, a read in a function that calls `Object.hasOwn(table, key)` or `hasOwnProperty`, null-prototype tables (`Object.create(null)`, `{ __proto__: null }`). Imported constants and keys iterated from another table are reported. Use a `Map` instead
|
|
141
|
-
| `antelopejs/no-presence-only-type-guard` | in a type predicate or assertion function narrowing `x`: `x in table` (also true for inherited keys; use `Object.hasOwn(table, x)` or a `Map`/`Set`); `"k" in x`, `Object.hasOwn(x, "k")`, `hasOwnProperty.call(x, "k")` or `Reflect.has(x, "k")` with no read of `x.k` (presence only; check the value; a read through a cast such as `(x as T).k` or `(<T>x).k` counts); a member of a type declared in the same file that the guard never reads. Members typed `unknown` and parameters typed as a union of object types (`pet: Cat \| Dog`, a discriminating `in`) are not reported, and a call to another local guard with `x` counts as checking that guard's members
|
|
142
|
-
| `antelopejs/no-
|
|
143
|
-
| `antelopejs/
|
|
144
|
-
| `antelopejs/
|
|
145
|
-
| `antelopejs/no-
|
|
146
|
-
| `antelopejs/
|
|
147
|
-
| `antelopejs/
|
|
148
|
-
| `antelopejs/no-
|
|
137
|
+
| Rule | Fails on |
|
|
138
|
+
| ----------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
139
|
+
| `antelopejs/no-comments` | `//` and `/* */` comments. Allowed: TSDoc `/** */`, `SAFETY: <reason>` (one block, or a run of `//` lines), `/*!` license headers, `@ts-expect-error <reason>`, oxlint/eslint directives that name their rules, `/// <reference />`, `#__PURE__`/`@__PURE__`, `@vite-ignore` and webpack magic comments, `prettier-ignore`/`oxfmt-ignore` |
|
|
140
|
+
| `antelopejs/no-inherited-key-lookup` | `table[key]` (or `table[key] += ...`) with a computed key, or `key in table`, where `table` is declared in the same file as a string-keyed dictionary (`Record<string, V>`, `Record<PropertyKey, V>`, a string index signature, `Readonly`/`Partial` of one, a union with `undefined` or `null`, a local alias or `typeof` another table, `satisfies` or `as Record<string, V>`, a class field read as `this.field[key]`), or an untyped object literal read with an asserted key (`table[key as keyof typeof table]`). Inherited keys such as `constructor` answer `Object.prototype` members. Not reported: literal keys, `typeof x` keys, same-file `const` keys (`KEY`, `LABELS.name` of a literal-valued object), keys iterated from an array of string literals or from `Object.keys(table)`, `Object.entries(table)` or `for...in` of the same table (through `filter`, `sort` and similar), writes and `delete`, a read in a function that calls `Object.hasOwn(table, key)` or `hasOwnProperty`, null-prototype tables (`Object.create(null)`, `{ __proto__: null }`). Imported constants and keys iterated from another table are reported. Use a `Map` instead |
|
|
141
|
+
| `antelopejs/no-presence-only-type-guard` | in a type predicate or assertion function narrowing `x`: `x in table` (also true for inherited keys; use `Object.hasOwn(table, x)` or a `Map`/`Set`); `"k" in x`, `Object.hasOwn(x, "k")`, `hasOwnProperty.call(x, "k")` or `Reflect.has(x, "k")` with no read of `x.k` (presence only; check the value; a read through a cast such as `(x as T).k` or `(<T>x).k` counts); a member of a type declared in the same file that the guard never reads. Members typed `unknown` and parameters typed as a union of object types (`pet: Cat \| Dog`, a discriminating `in`) are not reported, and a call to another local guard with `x` counts as checking that guard's members |
|
|
142
|
+
| `antelopejs/no-read-then-insert` | a call to `insert`, `insertOne` or `insertMany` on a table an earlier `get`, `getBy`, `getAll`, `count`, `find` or `findOne` read in the same function. A callback that runs while its caller waits belongs to that caller: one handed to `map`, `forEach`, `then` and the like, or to a call whose value is awaited or returned (through arrays, arguments, `?.`, `.then` or an inline arrow's body), such as `await withRetry(() => model.getAll())` or `Promise.all(rows.map((row) => limit(() => model.insert(row))))`. A nested function, a handler `app.post(...)` registers, or one `export const POST = withAuth(...)` wraps is its own function. One table: the insert's receiver lies on the read's chain (`table.filter(q).count()` reads `table`), or it is the read model's raw table (`model.get` then `model.table.insert`); `db.table("a")` and `db.table("b")`, or `this.get` and `this.audit.insert`, stay apart. Two replicas that boot on an empty table both read nothing and both insert. Not reported: an insert inside a `try` whose `catch` rethrows (`throw` or `Promise.reject`) nothing, or can finish without rethrowing (a `return`, `continue` or `break` of its own that returns no rejection, or every `throw` in a branch) and either reads the same table back or checks for a duplicate outside a `throw` (a name matching `duplicate`, `unique` or `conflict`, `11000`, `E11000`, `23505`, `ER_DUP_ENTRY`, or such a message in a string or template literal); a `.catch(callback)` on the insert or on its `.run()` that does the same, or `.catch(handler)` with a handler named for duplicates; an upsert, an options argument after the row with `conflict` other than `"error"`; an insert in a callback handed to a call that also takes the table, such as `insertRowOnce(model, id, () => model.insert(row))`, or through a parameter that shadows the read's receiver, when the read sits outside that callback. Off in test files. Purely syntactic: it does not read types, follow aliases or see a lock, so code that serializes the read and the insert takes a directive whose reason names the lock. The rule's shapes are frozen: a new edge case takes a directive with its reason, not a rule change |
|
|
143
|
+
| `antelopejs/no-unsafe-object-assign` | `Object.assign(target, ...sources)` where a source writes over a property the target's type declares: a source typed `unknown` or `any`, or holding such values under a `string` index signature (`Object.fromEntries` of `[string, unknown]` pairs) while the target has a field that does not take `unknown`; a property typed `unknown` or `any`, or holding `any` in its elements (`[value]` with `value: any`); a property whose type neither the target property nor its setter accepts. A value written in the source keeps the types a direct assignment gives it: `{ status: "loading" }`, `{ modes: ["a"] }` and nested literals keep their literal types (required properties, undeclared properties and tuple lengths still count), and a shorthand property reads its variable. A union source such as `flag && { stages }` is checked member by member, an optional source property is compared without its `undefined` (kept under `exactOptionalPropertyTypes`) but keeps `null`, and a `this` or generic target is read through its constraint. `Object.assign<T, U>` returns `T & U`, so TypeScript never compares the two and the call is an unchecked assertion. Not reported: properties the target does not declare (`Object.assign(new Error(message), { code })`), fields typed `unknown` or `any`, setters declared in a generic class, interface or type alias, spread sources and targets with no properties. Types come from the TypeScript program of the tsconfig that lists the file. On only with type-aware lint |
|
|
144
|
+
| `antelopejs/require-tsconfig-include` | a file type-aware lint reads that no `tsconfig.json` or `jsconfig.json` lists: not the nearest one, not a config it references, not one above. `oxlint-tsgolint` reads such a file in its inferred program, without the repository's compiler options or `types`, so Node and test-runner globals are error types: `typescript/no-unsafe-*` reports there are false, and findings that need those types go missing. List the file in a tsconfig that names its `types`: one beside it that extends the root tsconfig, or, for a file at the root, a composite tsconfig (`emitDeclarationOnly`, `outDir` under `node_modules/.cache`) that the root tsconfig references, which `tsc -p .` leaves unbuilt. The root `oxlint.config.ts`, `oxfmt.config.ts` and `knip.config.ts` that `antelopejs-sync` writes are exempt. On only with type-aware lint |
|
|
145
|
+
| `antelopejs/no-fs-read-in-tests` | `readFileSync` or `readdirSync` from `fs` in a test file. Files under `fixtures/`, `helpers/` and `locales/` may read |
|
|
146
|
+
| `antelopejs/no-self-import-in-tests` | a test file that imports its own package name (`@antelopejs/<self>`, a subpath, `require`, dynamic `import()` or a re-export; `import type` is fine) unless that resolves to local code: the `exports` map publishes the subpath and `node_modules/<name>` is a link back to the package (a workspace self-link such as `link:.`). Otherwise the import resolves to the installed published copy and the test never runs local code. In a package whose `antelopeJs.test` is set, `ajs module test` resolves the name through its own module resolver, so a self-link is no proof there and every self-import is reported. Import the module by relative path instead |
|
|
147
|
+
| `antelopejs/require-assertion` | a test with no assertion. Counts: calls named `expect*` or `assert*`, `sinon.assert.*`, supertest `.expect(...)`, and should-style `x.should…` or `should(x)` |
|
|
148
|
+
| `antelopejs/no-constant-value-assertion` | `expect(X).toBe(literal)` where the root of `X` is an UPPER_SNAKE constant (`MAX_ITEMS`, `NAMES.if`, not `process.env.NODE_ENV`); also `.toEqual`, `.to.equal`, `.to.eq`, `.eql` and synonyms |
|
|
149
|
+
| `antelopejs/no-typeof-function-only-test` | a test whose only assertions are `toBeTypeOf("function")`, `to.be.a("function")` or equivalents |
|
|
149
150
|
|
|
150
151
|
`antelopejs/no-presence-only-type-guard` passes `x in table` when `x` is typed `` `prefix${string}` `` and no `Object.prototype` member starts with that prefix, because such a key cannot name an inherited member. The prefix is read as TypeScript reads it, so `\x63onstructor${string}` is `constructor${string}` and stays reported.
|
|
151
152
|
|
|
@@ -213,7 +214,7 @@ pnpm install
|
|
|
213
214
|
|
|
214
215
|
`--profile template` writes only what `antelopejs-checks` runs, for template repositories: the three preset configs, 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.
|
|
215
216
|
|
|
216
|
-
`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.
|
|
217
|
+
`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. 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.
|
|
217
218
|
|
|
218
219
|
- `verify:types` type-checks each layer's own code with the repository's own TypeScript, run as `node <typescript>/bin/tsc` without a shell. 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`.
|
|
219
220
|
- `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.
|
|
@@ -224,6 +225,32 @@ The steps run at the same time, `test` last and alone. When two steps read somet
|
|
|
224
225
|
|
|
225
226
|
When the repository has `.github/compose.yml`, the file the shared CI starts through its `services-compose-file` input, and the `test` step runs, `pnpm run checks` runs `docker compose -f .github/compose.yml up -d --wait` before the steps and `docker compose -f .github/compose.yml down -v` after them, also when a step fails or the run is interrupted (SIGINT, SIGTERM or SIGHUP stops the running step or `up`, removes the services and exits 130, 143 or 129; a repeated signal does not cut the teardown short). The compose project is `COMPOSE_PROJECT_NAME` when set, else the file's own `name:`, else one named after the repository root, so checkouts never share the `github` project compose would derive from the file's directory. Services are left alone when every port the file publishes already accepts connections, so a stack you started yourself is reused and kept. A run's project that already had containers before the run is started but not removed. When Docker Compose cannot run, the run fails before any step, naming the compose file, because the tests that need those services would wait for them forever. On GitHub Actions (`GITHUB_ACTIONS=true`) the workflow owns the services, and `--no-services` skips all of this anywhere.
|
|
226
227
|
|
|
228
|
+
### Module locks update
|
|
229
|
+
|
|
230
|
+
A repository that commits `antelope-lock/` installs each module from its recorded lock, so its modules and their dependencies move only when someone records the locks again. Renovate does not read `antelope-lock/`. The shared `modules-update.yml` workflow of `AntelopeJS/.github` records the locks again and opens or updates one pull request per base branch, from `antelopejs/modules-update/<base>`. Its body lists the modules that moved from which version to which, the direct dependencies of each, and the npm advisories it fixes or leaves. A scheduled run refreshes on its `weekday` (Monday by default), and on any other day only when the npm advisory API reports an advisory not seen since the last successful run; a manual run always refreshes.
|
|
231
|
+
|
|
232
|
+
`antelopejs-sync` does not write this caller. Add `.github/workflows/modules-update.yml` to each repository that commits `antelope-lock/`:
|
|
233
|
+
|
|
234
|
+
```yaml
|
|
235
|
+
name: Modules update
|
|
236
|
+
on:
|
|
237
|
+
schedule:
|
|
238
|
+
- cron: "23 5 * * *"
|
|
239
|
+
workflow_dispatch:
|
|
240
|
+
permissions: {}
|
|
241
|
+
jobs:
|
|
242
|
+
modules-update:
|
|
243
|
+
permissions:
|
|
244
|
+
contents: write
|
|
245
|
+
pull-requests: write
|
|
246
|
+
actions: write
|
|
247
|
+
uses: AntelopeJS/.github/.github/workflows/modules-update.yml@v1
|
|
248
|
+
```
|
|
249
|
+
|
|
250
|
+
A project needs no `with`: the default `refresh-command` is `pnpm exec ajs project modules update`. That command refuses to run in a module repository, so a module passes `refresh-command: rm -rf antelope-lock && pnpm run test`, which records the locks of its test configuration.
|
|
251
|
+
|
|
252
|
+
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).
|
|
253
|
+
|
|
227
254
|
### Ratchet
|
|
228
255
|
|
|
229
256
|
`guardrails.ratchet.json` holds the debt a repository had when it adopted the pack:
|
|
@@ -249,14 +276,14 @@ When every rule count is zero and `oversizeFiles` is empty, the ratchet is retir
|
|
|
249
276
|
|
|
250
277
|
### Lib check coverage
|
|
251
278
|
|
|
252
|
-
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
|
|
279
|
+
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:
|
|
253
280
|
|
|
254
281
|
- `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`.
|
|
255
282
|
- 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.
|
|
256
283
|
- 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`.
|
|
257
|
-
- A file the check needs cannot be read (a directory where a tsconfig is expected, a permission error):
|
|
284
|
+
- 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.
|
|
258
285
|
|
|
259
|
-
|
|
286
|
+
`antelopejs-checks` runs `sync:check`, so a finding fails it too.
|
|
260
287
|
|
|
261
288
|
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.
|
|
262
289
|
|
package/dist/bin/checks.mjs
CHANGED
|
@@ -76,6 +76,37 @@ function runCommand(command, args, options) {
|
|
|
76
76
|
});
|
|
77
77
|
}
|
|
78
78
|
//#endregion
|
|
79
|
+
//#region src/guardrails/git-identity.ts
|
|
80
|
+
/** Config scopes stored inside the repository, which every checkout and agent sharing it commits under. */
|
|
81
|
+
const SHARED_SCOPES = /* @__PURE__ */ new Set(["local", "worktree"]);
|
|
82
|
+
/** Whether `root` is a git checkout, a `.git` folder or a linked worktree's `.git` file. */
|
|
83
|
+
function isGitCheckout(root) {
|
|
84
|
+
return existsSync(join(root, ".git"));
|
|
85
|
+
}
|
|
86
|
+
/**
|
|
87
|
+
* Fails when the repository's own git config, its `.git/config` shared by every worktree or a worktree's
|
|
88
|
+
* `config.worktree`, sets `user.name` or `user.email`: whoever commits in any checkout of it then signs as that identity.
|
|
89
|
+
* Global, system and command-line settings pass. Returns what failed, naming each file and value, empty when it passed.
|
|
90
|
+
*/
|
|
91
|
+
async function checkGitIdentity(root, signal) {
|
|
92
|
+
const result = await runCommand("git", [
|
|
93
|
+
"config",
|
|
94
|
+
"--show-scope",
|
|
95
|
+
"--show-origin",
|
|
96
|
+
"--get-regexp",
|
|
97
|
+
String.raw`^user\.(name|email)$`
|
|
98
|
+
], {
|
|
99
|
+
cwd: root,
|
|
100
|
+
signal,
|
|
101
|
+
shell: false
|
|
102
|
+
});
|
|
103
|
+
if (result.status === 1) return "";
|
|
104
|
+
if (result.status !== 0) return result.output;
|
|
105
|
+
const shared = result.stdout.split("\n").filter((line) => SHARED_SCOPES.has(line.split(" ")[0] ?? ""));
|
|
106
|
+
if (!shared.length) return "";
|
|
107
|
+
return `The repository's git config sets a commit identity, so every checkout and agent sharing it commits as that identity:\n${shared.map((line) => ` ${line.split(" ").slice(1).join(" ")}\n`).join("")}Remove it with git config --local --unset-all user.name and git config --local --unset-all user.email (--worktree for a config.worktree), and set an identity with --global or per command with git -c.\n`;
|
|
108
|
+
}
|
|
109
|
+
//#endregion
|
|
79
110
|
//#region src/guardrails/services.ts
|
|
80
111
|
/** The compose file the shared CI starts through its `services-compose-file` input, relative to the repository root. */
|
|
81
112
|
const COMPOSE_FILE = ".github/compose.yml";
|
|
@@ -615,19 +646,22 @@ const CHECK_STEPS = [
|
|
|
615
646
|
"sync:check",
|
|
616
647
|
"verify:types",
|
|
617
648
|
"verify:lockfiles",
|
|
618
|
-
"lockfile:singletons"
|
|
649
|
+
"lockfile:singletons",
|
|
650
|
+
"git:identity"
|
|
619
651
|
];
|
|
620
652
|
/** Steps `antelopejs-checks` runs itself, no package.json script behind them: each returns what failed, empty when it passed. */
|
|
621
653
|
const OWN_STEPS = /* @__PURE__ */ new Map([
|
|
622
654
|
["verify:types", typecheckLayers],
|
|
623
655
|
["verify:lockfiles", (root) => Promise.resolve(checkLockfiles(root))],
|
|
624
|
-
["lockfile:singletons", (root) => Promise.resolve(checkSingletonPackages(root))]
|
|
656
|
+
["lockfile:singletons", (root) => Promise.resolve(checkSingletonPackages(root))],
|
|
657
|
+
["git:identity", checkGitIdentity]
|
|
625
658
|
]);
|
|
626
659
|
function hasWork(root, step) {
|
|
627
660
|
if (step === "ratchet") return existsSync(join(root, CEILINGS_FILE));
|
|
628
661
|
if (step === "verify:types") return verifyLayers(root).length > 0;
|
|
629
662
|
if (step === "verify:lockfiles") return verifyInstallFolders(root).length > 0;
|
|
630
663
|
if (step === "lockfile:singletons") return pnpmLockfiles(root).length > 0;
|
|
664
|
+
if (step === "git:identity") return isGitCheckout(root);
|
|
631
665
|
return true;
|
|
632
666
|
}
|
|
633
667
|
/** The step that runs after the others, never beside them: tests often hold time limits that CPU contention would break. */
|
package/dist/bin/garden.mjs
CHANGED
|
@@ -770,6 +770,8 @@ async function tooling(context) {
|
|
|
770
770
|
const CHECK$1 = "conformance";
|
|
771
771
|
const DAY$2 = 864e5;
|
|
772
772
|
const MEND_EXEMPT = /* @__PURE__ */ new Set(["k8s-gitops-infra"]);
|
|
773
|
+
/** Repositories whose ci.yml runs its own jobs: tooling-configs shards its tests and checks its docs action at HEAD, which ci-node.yml cannot do. */
|
|
774
|
+
const CI_CALLER_EXEMPT = /* @__PURE__ */ new Set(["tooling-configs"]);
|
|
773
775
|
function problem(repo, subject, evidence, doneMeans) {
|
|
774
776
|
return finding({
|
|
775
777
|
repo: repo.name,
|
|
@@ -778,6 +780,7 @@ function problem(repo, subject, evidence, doneMeans) {
|
|
|
778
780
|
}, evidence, doneMeans);
|
|
779
781
|
}
|
|
780
782
|
async function ciCaller(context, repo) {
|
|
783
|
+
if (CI_CALLER_EXEMPT.has(repo.name)) return [];
|
|
781
784
|
const text = await context.file(repo, CI_PATH);
|
|
782
785
|
if (text === void 0) return [problem(repo, "ci-caller", `${CI_PATH} does not exist.`, `${CI_PATH} has a job calling ${CI_NODE_REF}.`)];
|
|
783
786
|
const callers = ciNodeCallers(text);
|
|
@@ -803,7 +806,9 @@ async function installed(context, repo, range) {
|
|
|
803
806
|
return (await context.file(repo, "pnpm-lock.yaml"))?.match(LOCK_ENTRY)?.[1] ?? range.replace(/^[^\d]*/, "");
|
|
804
807
|
}
|
|
805
808
|
async function toolingVersion(context, repo) {
|
|
806
|
-
const
|
|
809
|
+
const manifests = await context.packages(repo);
|
|
810
|
+
if (manifests.some(({ name }) => name === "@antelopejs/tooling-configs")) return [];
|
|
811
|
+
const range = manifests.map(({ tooling: declared }) => declared).find((declared) => declared !== void 0);
|
|
807
812
|
const latest = await tooling(context);
|
|
808
813
|
const done = `@antelopejs/tooling-configs is ${latest} or a Renovate PR bumping it is under 7 days old.`;
|
|
809
814
|
if (range === void 0) return [problem(repo, "tooling-configs", "@antelopejs/tooling-configs is not a dependency.", done)];
|
package/dist/bin/lease.mjs
CHANGED
|
@@ -122,15 +122,15 @@ function launch(command, env) {
|
|
|
122
122
|
const STAT_AFTER_COMM = 2;
|
|
123
123
|
const STAT_PPID = 1;
|
|
124
124
|
const STAT_PGID = 2;
|
|
125
|
-
const STAT_START = 19;
|
|
126
|
-
const DEAD_STATES = /* @__PURE__ */ new Set(["Z", "X"]);
|
|
125
|
+
const STAT_START$1 = 19;
|
|
126
|
+
const DEAD_STATES$1 = /* @__PURE__ */ new Set(["Z", "X"]);
|
|
127
127
|
function fromProc(pid) {
|
|
128
128
|
const stat = readFileSync(`/proc/${pid}/stat`, "utf8");
|
|
129
129
|
const fields = stat.slice(stat.lastIndexOf(")") + STAT_AFTER_COMM).split(" ");
|
|
130
|
-
if (DEAD_STATES.has(fields[0] ?? "")) return void 0;
|
|
130
|
+
if (DEAD_STATES$1.has(fields[0] ?? "")) return void 0;
|
|
131
131
|
return {
|
|
132
132
|
pid,
|
|
133
|
-
start: `${readFileSync("/proc/sys/kernel/random/boot_id", "utf8").trim()}:${fields[STAT_START]}`,
|
|
133
|
+
start: `${readFileSync("/proc/sys/kernel/random/boot_id", "utf8").trim()}:${fields[STAT_START$1]}`,
|
|
134
134
|
uid: statSync(`/proc/${pid}`).uid,
|
|
135
135
|
pgid: Number(fields[STAT_PGID]),
|
|
136
136
|
ppid: Number(fields[STAT_PPID])
|
|
@@ -150,7 +150,7 @@ function fromPs(pid) {
|
|
|
150
150
|
"ignore"
|
|
151
151
|
]
|
|
152
152
|
}).trim().split(/\s+/u);
|
|
153
|
-
if (state === void 0 || DEAD_STATES.has(state.slice(0, 1))) return void 0;
|
|
153
|
+
if (state === void 0 || DEAD_STATES$1.has(state.slice(0, 1))) return void 0;
|
|
154
154
|
return {
|
|
155
155
|
pid,
|
|
156
156
|
start: started.join(" "),
|
|
@@ -184,6 +184,8 @@ function assertSignallable(pid) {
|
|
|
184
184
|
const READY_TIMEOUT_MS = 3e4;
|
|
185
185
|
const KILL_WAIT_MS$1 = 2e3;
|
|
186
186
|
const POLL_MS$1 = 50;
|
|
187
|
+
const STAT_START = 19;
|
|
188
|
+
const DEAD_STATES = /* @__PURE__ */ new Set(["Z", "X"]);
|
|
187
189
|
const CACHED_BINARY = /^mongod-.+-(\d+)\.(\d+)\.(\d+)$/u;
|
|
188
190
|
function executable(path) {
|
|
189
191
|
try {
|
|
@@ -259,11 +261,44 @@ function mongodPid(dbpath) {
|
|
|
259
261
|
function serves(pid, dbpath) {
|
|
260
262
|
return commandLine(pid).includes(dbpath);
|
|
261
263
|
}
|
|
262
|
-
/**
|
|
263
|
-
|
|
264
|
+
/** The fields of `/proc/<path>/stat` after the command name, the state first; `undefined` when it cannot be read. */
|
|
265
|
+
function statFields(path) {
|
|
266
|
+
try {
|
|
267
|
+
const stat = readFileSync(`/proc/${path}/stat`, "utf8");
|
|
268
|
+
return stat.slice(stat.lastIndexOf(")") + 2).split(" ");
|
|
269
|
+
} catch {
|
|
270
|
+
return;
|
|
271
|
+
}
|
|
272
|
+
}
|
|
273
|
+
/** True while some thread of `pid` has not exited, a main thread that exited before the others included. */
|
|
274
|
+
function anyThreadRuns(pid) {
|
|
275
|
+
let tids;
|
|
276
|
+
try {
|
|
277
|
+
tids = readdirSync(`/proc/${pid}/task`);
|
|
278
|
+
} catch {
|
|
279
|
+
return false;
|
|
280
|
+
}
|
|
281
|
+
return tids.some((tid) => {
|
|
282
|
+
const state = statFields(`${pid}/task/${tid}`)?.[0];
|
|
283
|
+
return state !== void 0 && !DEAD_STATES.has(state);
|
|
284
|
+
});
|
|
285
|
+
}
|
|
286
|
+
/**
|
|
287
|
+
* A check that answers whether the mongod `pid` serving `dbpath` still runs. On Linux it holds
|
|
288
|
+
* until no thread of the process started at the same time as `pid` now runs: the command line
|
|
289
|
+
* reads empty from the moment mongod drops its memory, while its threads still hold its port. A
|
|
290
|
+
* reused pid has another start time. Elsewhere it holds while the command line names `dbpath`.
|
|
291
|
+
*/
|
|
292
|
+
function runningCheck(pid, dbpath) {
|
|
293
|
+
if (process.platform !== "linux") return () => serves(pid, dbpath);
|
|
294
|
+
const start = statFields(String(pid))?.[STAT_START];
|
|
295
|
+
return () => start !== void 0 && statFields(String(pid))?.[STAT_START] === start && anyThreadRuns(pid);
|
|
296
|
+
}
|
|
297
|
+
/** Waits up to `ms` for `runs` to answer false; answers whether it did. */
|
|
298
|
+
async function untilGone$1(runs, ms) {
|
|
264
299
|
const deadline = Date.now() + ms;
|
|
265
|
-
while (
|
|
266
|
-
return !
|
|
300
|
+
while (runs() && Date.now() < deadline) await setTimeout(POLL_MS$1);
|
|
301
|
+
return !runs();
|
|
267
302
|
}
|
|
268
303
|
function signal$1(pid, name) {
|
|
269
304
|
assertSignallable(pid);
|
|
@@ -280,12 +315,14 @@ function signal$1(pid, name) {
|
|
|
280
315
|
async function stopMongod(dbpath, graceMs) {
|
|
281
316
|
const pid = mongodPid(dbpath);
|
|
282
317
|
if (pid === void 0) return;
|
|
318
|
+
const runs = runningCheck(pid, dbpath);
|
|
319
|
+
if (!runs()) return;
|
|
283
320
|
if (graceMs > 0) {
|
|
284
321
|
signal$1(pid, "SIGTERM");
|
|
285
|
-
if (await untilGone$1(
|
|
322
|
+
if (await untilGone$1(runs, graceMs)) return;
|
|
286
323
|
}
|
|
287
324
|
signal$1(pid, "SIGKILL");
|
|
288
|
-
if (await untilGone$1(
|
|
325
|
+
if (await untilGone$1(runs, KILL_WAIT_MS$1)) return;
|
|
289
326
|
throw new Error(`antelopejs-lease: mongod ${pid} was still running ${KILL_WAIT_MS$1 / 1e3} s after SIGKILL`);
|
|
290
327
|
}
|
|
291
328
|
async function holder(port) {
|
package/dist/bin/ratchet.mjs
CHANGED
|
@@ -3,7 +3,7 @@ import { c as parseCeilings, l as readCeilings, t as CEILINGS_FILE } from "../ce
|
|
|
3
3
|
import { n as renamedPaths } from "../renames-L2owF5GD.mjs";
|
|
4
4
|
import { t as runCli } from "../cli-4Tv71vYk.mjs";
|
|
5
5
|
import { c as repositoryRoot, l as resolveRevision, t as LINT_CONFIG } from "../files-DJ0TeaTU.mjs";
|
|
6
|
-
import { n as ratchet, r as withPreviousTree } from "../ratchet-
|
|
6
|
+
import { n as ratchet, r as withPreviousTree } from "../ratchet-ClfblHNJ.mjs";
|
|
7
7
|
import { t as lintDiagnostics } from "../oxlint-DIV-lLSS.mjs";
|
|
8
8
|
import { d as stagedAdditions, f as stagedChanges, u as previousLine } from "../suppression-budget-Dvb_IqBo.mjs";
|
|
9
9
|
import { n as suppressionBase } from "../suppression-base-Drnl6Y7F.mjs";
|