@antelopejs/tooling-configs 0.5.0 → 0.5.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -26,7 +26,7 @@ The AntelopeJS guardrail pack: shared lint, format and dead-code presets, the co
26
26
  | `./oxc/anti-slop` | Loaded by the oxlint preset as a JS plugin | The vendored [anti-slop](https://github.com/dmmulroy/anti-slop) rules |
27
27
  | `./oxc/guardrails` | Loaded by the oxlint preset as a JS plugin | The `antelopejs` comment and test-quality rules |
28
28
  | `./verify` | `import type { VerifyConfig } from "@antelopejs/tooling-configs/verify"` | Types and check helpers for a shared verification skill's `verify.config.ts` |
29
- | bin | `antelopejs-sync` | Writes the guardrail pack into a repository; `--check` reports drift |
29
+ | bin | `antelopejs-sync [--init]` | Writes the guardrail pack into a repository; `--check` reports drift; `--init` onboards a bare repository |
30
30
  | bin | `antelopejs-checks [--no-services]` | Runs every check and prints only the failures; starts `.github/compose.yml` services around them |
31
31
  | bin | `antelopejs-ratchet` | Fails when recorded debt grows; `--update` lowers the record and adopts rules a pack release newly enabled |
32
32
  | bin | `antelopejs-suppressions` | Fails when suppressions exceed their budget or an added one breaks policy; `--update` lowers the budget |
@@ -116,36 +116,37 @@ export default defineConfig({
116
116
 
117
117
  ### What the preset turns on
118
118
 
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`, 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 |
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
- 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`.
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: every read of it is the direct argument of a decoder (`parse`, `safeParse`, `parseAsync`, `safeParseAsync`, `decode`, or a `parseX` or `decodeX` helper) read from an import of a schema library (`zod`, `valibot`, `yup`, `joi`, `superstruct`, `io-ts`, `@sinclair/typebox`, `arktype`, `effect`, `@effect/schema`, subpaths included) through members, calls, type wrappers and `const` aliases, the file reassigns no name on that path and writes none of its properties (an assignment, update, `delete`, `Object.assign`, `Object.defineProperty`, `Reflect.set` and the like), the function never mentions `arguments` or `eval`, and it returns that call's result, awaited or read through `.data`, under a declared return type other than `unknown` or `any`. A decoder of any other origin is reported: one written in the file, imported from another file of the repository, handed in as a parameter, or reached through a helper such as `assertValidation` that runs whatever validator it is handed.
130
130
 
131
- `no-runtime-typeof` does not report 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}`)``: the template holds other text, and a `throw`, a bare `assert(...)` or a `log(...)` method that stands as a statement takes it. The `assert`, the object `log` is read from, and the class of a thrown `new` must come from outside the file: a module import, a global that nothing in the file assigns, or a parameter that nothing in the file defaults or assigns, reached through members and type wrappers only. A name read inside a namespace block counts only when the block binds it, as a parameter, because another block of the namespace may declare a member of that name that shadows an import or a global. A function, class, `const`, `let`, `this`, call result or namespace written in the file can compare or store the message, so a `typeof` handed to it stays reported. The same template compared, bound to a name, returned, or handed to any other call (`assert.equal`, `Set#add`, `emit`, a dispatcher) stays reported, because a caller can test it or use it as a key.
131
+ `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.
132
132
 
133
133
  No rule warns. oxlint reports `correctness` as warnings by default, and warnings never fail the command, so the preset raises it to error. A repository with existing findings records them in `guardrails.ratchet.json` instead of lowering a severity (see [Guardrail pack](#guardrail-pack)).
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-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 |
143
- | `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 |
144
- | `antelopejs/no-fs-read-in-tests` | `readFileSync` or `readdirSync` from `fs` in a test file. Files under `fixtures/`, `helpers/` and `locales/` may read |
145
- | `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 |
146
- | `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)` |
147
- | `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 |
148
- | `antelopejs/no-typeof-function-only-test` | a test whose only assertions are `toBeTypeOf("function")`, `to.be.a("function")` or equivalents |
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
 
@@ -188,10 +189,20 @@ export default defineConfig({
188
189
 
189
190
  ## Guardrail pack
190
191
 
191
- Run `antelopejs-sync` at the repository root, then install dependencies. It is idempotent: a second run changes nothing.
192
+ Onboard a repository with one command at its root. The repository needs a `package.json` and a git remote on GitHub.
193
+
194
+ ```bash
195
+ pnpm dlx --package=@antelopejs/tooling-configs antelopejs-sync --init
196
+ npx --package=@antelopejs/tooling-configs antelopejs-sync --init
197
+ ```
198
+
199
+ `--init` adds `node_modules` to `.gitignore` and declares each of `@antelopejs/tooling-configs`, `oxlint`, `oxlint-tsgolint` and `oxfmt` the repository does not declare yet. It installs with the repository's package manager, runs `antelopejs-sync`, installs again when sync added devDependencies, and formats `package.json` with the installed oxfmt. It takes the full profile only and rejects `--check` and `--profile template`. Install output shows only when the install fails.
200
+
201
+ It then sets `delete_branch_on_merge` through `gh` when it can, even when an earlier step failed. When `gh` is missing, unauthenticated or refused, `--init` prints the `gh api -X PATCH repos/{owner}/{repo} -F delete_branch_on_merge=true` command to run and exits 1. After any failure, fix what it printed and rerun `antelopejs-sync --init`. Commit and push to the default branch afterwards, so the first run reports `ci / checks`.
202
+
203
+ Every step is idempotent: a second run changes nothing. Plain `antelopejs-sync` also runs from a repository that already has the devDependencies installed:
192
204
 
193
205
  ```bash
194
- pnpm add -D @antelopejs/tooling-configs oxlint@1.81.0 oxlint-tsgolint oxfmt
195
206
  pnpm exec antelopejs-sync
196
207
  pnpm install
197
208
  ```
@@ -213,17 +224,43 @@ pnpm install
213
224
 
214
225
  `--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
226
 
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.
227
+ `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
228
 
218
229
  - `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
230
  - `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.
220
231
 
221
232
  `ANTELOPEJS_CHECKS_SKIP` accepts both names.
222
233
 
223
- The steps run at the same time, `test` last and alone. When two steps read something one of them builds, such as a workspace package's `dist` that `typecheck` builds and `lint` resolves, 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.
234
+ 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.
224
235
 
225
236
  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
237
 
238
+ ### Module locks update
239
+
240
+ 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.
241
+
242
+ `antelopejs-sync` does not write this caller. Add `.github/workflows/modules-update.yml` to each repository that commits `antelope-lock/`:
243
+
244
+ ```yaml
245
+ name: Modules update
246
+ on:
247
+ schedule:
248
+ - cron: "23 5 * * *"
249
+ workflow_dispatch:
250
+ permissions: {}
251
+ jobs:
252
+ modules-update:
253
+ permissions:
254
+ contents: write
255
+ pull-requests: write
256
+ actions: write
257
+ uses: AntelopeJS/.github/.github/workflows/modules-update.yml@v1
258
+ ```
259
+
260
+ 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.
261
+
262
+ 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).
263
+
227
264
  ### Ratchet
228
265
 
229
266
  `guardrails.ratchet.json` holds the debt a repository had when it adopted the pack:
@@ -249,14 +286,14 @@ When every rule count is zero and `oversizeFiles` is empty, the ratchet is retir
249
286
 
250
287
  ### Lib check coverage
251
288
 
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` and `antelopejs-sync --check` print a `Note:` line naming the file, the script and the fix, and do not fail, when:
289
+ 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
290
 
254
291
  - `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
292
  - 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
293
  - 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): the note says "could not read …" and sync carries on.
294
+ - 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
295
 
259
- These findings are report-only for now: a later release makes `--check` fail on them once the repositories that still miss them are fixed. `antelopejs-checks` hides the output of a step that passes, so the notes show only when `antelopejs-sync` runs directly, which agents do when they bump the pack.
296
+ `antelopejs-checks` runs `sync:check`, so a finding fails it too.
260
297
 
261
298
  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
299
 
@@ -1,9 +1,9 @@
1
1
  #!/usr/bin/env node
2
- import { a as parseManifest, i as packageManager } from "../package-Dn7VTFUW.mjs";
2
+ import { a as packageManager, o as parseManifest } from "../package-DxxcxOzp.mjs";
3
3
  import { t as runCli } from "../cli-4Tv71vYk.mjs";
4
4
  import { c as repositoryRoot, l as resolveRevision } from "../files-DJ0TeaTU.mjs";
5
- import { a as DIRECTORY_LINK, c as revisionCounts, d as createAddedPolicy, f as describeAllowance, i as stampProof, l as workspaceManifests, m as recordVerdict, o as compareRevisions, p as fillStars, u as allowedByGlob } from "../proof-stamp-DLWpPwQE.mjs";
6
- import { c as packagesAt, i as isTestSource, l as unpublishedAt, o as loadTypeScript, r as isExportPath, s as outputRoot, t as emitPackage } from "../typescript-BBbry7uU.mjs";
5
+ import { a as DIRECTORY_LINK, c as revisionCounts, d as createAddedPolicy, f as describeAllowance, i as stampProof, l as workspaceManifests, m as recordVerdict, o as compareRevisions, p as fillStars, u as allowedByGlob } from "../proof-stamp-D9yo2dxU.mjs";
6
+ import { c as packagesAt, i as isTestSource, l as unpublishedAt, o as loadTypeScript, r as isExportPath, s as outputRoot, t as emitPackage } from "../typescript-D7SaSmsl.mjs";
7
7
  import { createRequire } from "node:module";
8
8
  import { copyFileSync, cpSync, existsSync, globSync, mkdirSync, readFileSync, readdirSync, realpathSync, rmSync, statSync, symlinkSync, writeFileSync } from "node:fs";
9
9
  import { basename, dirname, isAbsolute, join, parse, posix, relative, resolve, sep } from "node:path";
@@ -1,8 +1,8 @@
1
1
  #!/usr/bin/env node
2
2
  import { t as runCli } from "../cli-4Tv71vYk.mjs";
3
3
  import { c as repositoryRoot, l as resolveRevision } from "../files-DJ0TeaTU.mjs";
4
- import { t as lintDiagnostics } from "../oxlint-DIV-lLSS.mjs";
5
- import { n as proofDigest, r as proofLines, s as revisionCountRows, t as parseProofStamp } from "../proof-stamp-DLWpPwQE.mjs";
4
+ import { t as lintDiagnostics } from "../oxlint-BbpTFFmf.mjs";
5
+ import { n as proofDigest, r as proofLines, s as revisionCountRows, t as parseProofStamp } from "../proof-stamp-D9yo2dxU.mjs";
6
6
  import { readFileSync } from "node:fs";
7
7
  import { spawnSync } from "node:child_process";
8
8
  import { parseArgs } from "node:util";
@@ -1,17 +1,20 @@
1
1
  #!/usr/bin/env node
2
2
  import { t as CEILINGS_FILE } from "../ceilings-B7KayYIG.mjs";
3
- import { a as parseManifest, i as packageManager } from "../package-Dn7VTFUW.mjs";
3
+ import { a as packageManager, o as parseManifest } from "../package-DxxcxOzp.mjs";
4
4
  import { n as runCliAsync } from "../cli-4Tv71vYk.mjs";
5
5
  import { a as gitFiles, c as repositoryRoot } from "../files-DJ0TeaTU.mjs";
6
+ import { i as workspaceDirectories, n as stepsOf, t as matchingScripts } from "../script-steps-CgH2DSsp.mjs";
6
7
  import { t as accepting } from "../ports-DGP6bPJy.mjs";
7
8
  import { createRequire } from "node:module";
8
- import { existsSync, mkdtempSync, readFileSync, readdirSync, rmSync, writeFileSync } from "node:fs";
9
+ import { existsSync, mkdtempSync, readFileSync, readdirSync, rmSync, statSync, writeFileSync } from "node:fs";
9
10
  import { basename, dirname, join, posix, relative, resolve, sep } from "node:path";
10
11
  import { spawn } from "node:child_process";
11
12
  import { isMap, isScalar, isSeq, parseAllDocuments, parseDocument } from "yaml";
13
+ import ts from "typescript";
12
14
  import { createHash } from "node:crypto";
13
15
  import { tmpdir } from "node:os";
14
16
  import { parseArgs } from "node:util";
17
+ import { minimatch } from "minimatch";
15
18
  //#region src/guardrails/run-command.ts
16
19
  const KILL_GRACE_MS = 5e3;
17
20
  function stopGroup(child, signal) {
@@ -76,6 +79,37 @@ function runCommand(command, args, options) {
76
79
  });
77
80
  }
78
81
  //#endregion
82
+ //#region src/guardrails/git-identity.ts
83
+ /** Config scopes stored inside the repository, which every checkout and agent sharing it commits under. */
84
+ const SHARED_SCOPES = /* @__PURE__ */ new Set(["local", "worktree"]);
85
+ /** Whether `root` is a git checkout, a `.git` folder or a linked worktree's `.git` file. */
86
+ function isGitCheckout(root) {
87
+ return existsSync(join(root, ".git"));
88
+ }
89
+ /**
90
+ * Fails when the repository's own git config, its `.git/config` shared by every worktree or a worktree's
91
+ * `config.worktree`, sets `user.name` or `user.email`: whoever commits in any checkout of it then signs as that identity.
92
+ * Global, system and command-line settings pass. Returns what failed, naming each file and value, empty when it passed.
93
+ */
94
+ async function checkGitIdentity(root, signal) {
95
+ const result = await runCommand("git", [
96
+ "config",
97
+ "--show-scope",
98
+ "--show-origin",
99
+ "--get-regexp",
100
+ String.raw`^user\.(name|email)$`
101
+ ], {
102
+ cwd: root,
103
+ signal,
104
+ shell: false
105
+ });
106
+ if (result.status === 1) return "";
107
+ if (result.status !== 0) return result.output;
108
+ const shared = result.stdout.split("\n").filter((line) => SHARED_SCOPES.has(line.split(" ")[0] ?? ""));
109
+ if (!shared.length) return "";
110
+ 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`;
111
+ }
112
+ //#endregion
79
113
  //#region src/guardrails/services.ts
80
114
  /** The compose file the shared CI starts through its `services-compose-file` input, relative to the repository root. */
81
115
  const COMPOSE_FILE = ".github/compose.yml";
@@ -602,6 +636,107 @@ function checkSingletonPackages(root) {
602
636
  }).join("");
603
637
  }
604
638
  //#endregion
639
+ //#region src/guardrails/typecheck-writes.ts
640
+ const MAX_DEPTH = 5;
641
+ const BUILD = "build";
642
+ const UNRESOLVED_SELECTOR = /^!|\.\.\.|\^|\[|\$/u;
643
+ function scriptsIn(directory) {
644
+ const file = join(directory, "package.json");
645
+ if (!existsSync(file)) return /* @__PURE__ */ new Map();
646
+ const { scripts = {} } = parseManifest(readFileSync(file, "utf8"));
647
+ return new Map(Object.entries(scripts));
648
+ }
649
+ function workspacePackages(walk) {
650
+ walk.packages ??= workspaceDirectories(walk.root).map((path) => {
651
+ const directory = join(walk.root, path);
652
+ const { name } = parseManifest(readFileSync(join(directory, "package.json"), "utf8"));
653
+ return {
654
+ directory,
655
+ path,
656
+ name
657
+ };
658
+ });
659
+ return walk.packages;
660
+ }
661
+ /** The workspace packages a `--filter` or `--workspace` selector matches by name or by path, `undefined` for one this does not model. */
662
+ function selected(walk, from, selector) {
663
+ if (UNRESOLVED_SELECTOR.test(selector)) return void 0;
664
+ const path = relative(walk.root, resolve(from, selector.replace(/^\{|\}$/gu, "")));
665
+ const matches = workspacePackages(walk).filter((item) => item.name !== void 0 && minimatch(item.name, selector) || minimatch(item.path, path)).map((item) => item.directory);
666
+ return matches.length ? matches : void 0;
667
+ }
668
+ function targetDirectories(walk, from, target) {
669
+ if (target.kind === "all") return workspacePackages(walk).map((item) => item.directory);
670
+ if (target.kind === "select") return selected(walk, from, target.selector);
671
+ const directory = resolve(from, target.path);
672
+ return target.path.includes("$") || !existsSync(join(directory, "package.json")) ? void 0 : [directory];
673
+ }
674
+ /** The package directories a script step runs in, `undefined` when a target cannot be resolved. */
675
+ function stepDirectories(walk, from, targets) {
676
+ if (targets.length === 0) return [from];
677
+ const directories = /* @__PURE__ */ new Set();
678
+ for (const target of targets) {
679
+ const found = targetDirectories(walk, from, target);
680
+ if (found === void 0) return void 0;
681
+ for (const directory of found) directories.add(directory);
682
+ }
683
+ return [...directories];
684
+ }
685
+ function configFile(directory, project) {
686
+ const path = resolve(directory, project);
687
+ return existsSync(path) && statSync(path).isDirectory() ? join(path, "tsconfig.json") : path;
688
+ }
689
+ /** Whether a `tsc` command line writes output: `-b`, or a run whose command line or tsconfig chain leaves `noEmit` unset. */
690
+ function tscWrites(directory, args) {
691
+ if (/^--?b(?:uild)?$/iu.test(args[0] ?? "")) return true;
692
+ const { options } = ts.parseCommandLine([...args]);
693
+ if (options.noEmit !== void 0) return !options.noEmit;
694
+ const file = configFile(directory, options.project ?? ".");
695
+ if (!existsSync(file)) return true;
696
+ return ts.getParsedCommandLineOfConfigFile(file, {}, {
697
+ ...ts.sys,
698
+ onUnRecoverableConfigFileDiagnostic: () => void 0
699
+ })?.options.noEmit !== true;
700
+ }
701
+ /** Whether one step, run from `directory`, writes: a `tsc` that emits, or a script that reaches one or a `build`. */
702
+ function stepWrites(walk, directory, step, depth) {
703
+ const directories = stepDirectories(walk, directory, step.targets);
704
+ if (directories === void 0) return true;
705
+ if (step.kind === "tsc") return directories.some((target) => tscWrites(target, step.args));
706
+ return directories.some((target) => matchingScripts(step.names, scriptsIn(target).keys()).some((script) => scriptWrites(walk, target, script, depth + 1)));
707
+ }
708
+ /** Whether a script or the `pre` and `post` hooks the package manager runs around it write, its lines run from where each `cd` left them. */
709
+ function scriptWrites(walk, directory, name, depth) {
710
+ const key = `${directory}\0${name}`;
711
+ const text = scriptsIn(directory).get(name);
712
+ if (text === void 0 || walk.seen.has(key)) return false;
713
+ walk.seen.add(key);
714
+ if (name === BUILD || depth > MAX_DEPTH) return true;
715
+ if (scriptWrites(walk, directory, `pre${name}`, depth) || scriptWrites(walk, directory, `post${name}`, depth)) return true;
716
+ let current = directory;
717
+ for (const step of stepsOf(text)) if (step.kind === "cd") {
718
+ if (step.path.includes("$") || step.path.startsWith("~")) return true;
719
+ current = resolve(current, step.path);
720
+ } else if (stepWrites(walk, current, step, depth)) return true;
721
+ return false;
722
+ }
723
+ /**
724
+ * Whether the `typecheck` script of the package at `root` can write files other steps read: it reaches a `build`
725
+ * script or a `tsc` run that emits, in this package or a workspace package it points the package manager at. A
726
+ * target it cannot resolve, such as a `--dir` read from a variable or a dependency `--filter`, counts as writing, and
727
+ * so does a workspace whose manifests cannot be read.
728
+ */
729
+ function typecheckWrites(root) {
730
+ try {
731
+ return scriptWrites({
732
+ root,
733
+ seen: /* @__PURE__ */ new Set()
734
+ }, root, "typecheck", 0);
735
+ } catch {
736
+ return true;
737
+ }
738
+ }
739
+ //#endregion
605
740
  //#region src/guardrails/checks.ts
606
741
  const CHECK_STEPS = [
607
742
  "typecheck",
@@ -615,23 +750,38 @@ const CHECK_STEPS = [
615
750
  "sync:check",
616
751
  "verify:types",
617
752
  "verify:lockfiles",
618
- "lockfile:singletons"
753
+ "lockfile:singletons",
754
+ "git:identity"
619
755
  ];
620
756
  /** Steps `antelopejs-checks` runs itself, no package.json script behind them: each returns what failed, empty when it passed. */
621
757
  const OWN_STEPS = /* @__PURE__ */ new Map([
622
758
  ["verify:types", typecheckLayers],
623
759
  ["verify:lockfiles", (root) => Promise.resolve(checkLockfiles(root))],
624
- ["lockfile:singletons", (root) => Promise.resolve(checkSingletonPackages(root))]
760
+ ["lockfile:singletons", (root) => Promise.resolve(checkSingletonPackages(root))],
761
+ ["git:identity", checkGitIdentity]
625
762
  ]);
626
763
  function hasWork(root, step) {
627
764
  if (step === "ratchet") return existsSync(join(root, CEILINGS_FILE));
628
765
  if (step === "verify:types") return verifyLayers(root).length > 0;
629
766
  if (step === "verify:lockfiles") return verifyInstallFolders(root).length > 0;
630
767
  if (step === "lockfile:singletons") return pnpmLockfiles(root).length > 0;
768
+ if (step === "git:identity") return isGitCheckout(root);
631
769
  return true;
632
770
  }
633
771
  /** The step that runs after the others, never beside them: tests often hold time limits that CPU contention would break. */
634
772
  const RUNS_ALONE = "test";
773
+ /** The step that runs before the others when it writes files, such as a workspace package's `dist`, that they read. */
774
+ const RUNS_FIRST = "typecheck";
775
+ /** The groups of steps that run one after another, the steps of a group at the same time. */
776
+ function phases(root, steps) {
777
+ const first = steps.includes(RUNS_FIRST) && typecheckWrites(root) ? [RUNS_FIRST] : [];
778
+ const last = steps.includes(RUNS_ALONE) ? [RUNS_ALONE] : [];
779
+ return [
780
+ first,
781
+ steps.filter((step) => !first.includes(step) && !last.includes(step)),
782
+ last
783
+ ].filter((phase) => phase.length > 0);
784
+ }
635
785
  /** The environment variable naming, comma-separated, the steps `runChecks` leaves to another CI job. */
636
786
  const CHECKS_SKIP_ENV = "ANTELOPEJS_CHECKS_SKIP";
637
787
  function skippedNames(setting) {
@@ -658,8 +808,7 @@ async function runSteps(root, manifest, steps, signal) {
658
808
  return result.status === 0 ? [] : [`[${step}]\n${result.output}`];
659
809
  };
660
810
  const failures = /* @__PURE__ */ new Map();
661
- await Promise.all(steps.filter((step) => step !== RUNS_ALONE).map(async (step) => failures.set(step, await runStep(step))));
662
- if (steps.includes(RUNS_ALONE)) failures.set(RUNS_ALONE, await runStep(RUNS_ALONE));
811
+ for (const phase of phases(root, steps)) await Promise.all(phase.map(async (step) => failures.set(step, await runStep(step))));
663
812
  return steps.flatMap((step) => failures.get(step) ?? []);
664
813
  }
665
814
  /** The optional package script run once before the steps, to build what several steps read, such as a workspace package's `dist`. */
@@ -692,7 +841,8 @@ function summary(failures, passed, skipped) {
692
841
  }
693
842
  /**
694
843
  * Runs the `checks:prepare` package script first when it exists and a step will run, and stops there if it fails.
695
- * Then runs every check step except `test` at the same time, then `test` alone, and reports only what failed, each step's
844
+ * Then runs `typecheck` first when it writes files the other steps read (see `typecheckWrites`), every other check step
845
+ * except `test` at the same time, then `test` alone, and reports only what failed, each step's
696
846
  * output buffered and listed in step order whichever step finishes first. `skipSetting` is the comma-separated value of
697
847
  * `ANTELOPEJS_CHECKS_SKIP`: the steps it names are not run and are counted as skipped, never as passed, and a name that
698
848
  * is not a step fails the run before any step starts so a typo cannot skip nothing. Unless `services` is false, the
@@ -1,8 +1,8 @@
1
1
  #!/usr/bin/env node
2
2
  import { t as runCli } from "../cli-4Tv71vYk.mjs";
3
3
  import { c as repositoryRoot } from "../files-DJ0TeaTU.mjs";
4
- import { c as revisionCounts, i as stampProof, o as compareRevisions } from "../proof-stamp-DLWpPwQE.mjs";
5
- import { a as listsNoFiles, c as packagesAt, n as extendedConfigs, t as emitPackage } from "../typescript-BBbry7uU.mjs";
4
+ import { c as revisionCounts, i as stampProof, o as compareRevisions } from "../proof-stamp-D9yo2dxU.mjs";
5
+ import { a as listsNoFiles, c as packagesAt, n as extendedConfigs, t as emitPackage } from "../typescript-D7SaSmsl.mjs";
6
6
  import { copyFileSync, existsSync, mkdirSync } from "node:fs";
7
7
  import { dirname, isAbsolute, join, relative, resolve, sep } from "node:path";
8
8
  //#region src/guardrails/comment-proof.ts