@antelopejs/tooling-configs 0.5.8 → 0.7.0
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 +39 -49
- package/dist/{api-CCOiLN3w.mjs → api-BQLrI_S1.mjs} +19 -2
- package/dist/bin/api-diff.mjs +155 -37
- package/dist/bin/body-check.mjs +6 -3
- package/dist/bin/check-size.mjs +1 -1
- package/dist/bin/checks.mjs +1 -1
- package/dist/bin/comment-proof.mjs +3 -5
- package/dist/bin/garden.mjs +86 -34
- package/dist/bin/lease.mjs +314 -26
- package/dist/bin/ratchet.mjs +4 -4
- package/dist/bin/readme-strip.mjs +1 -1
- package/dist/bin/suppressions.mjs +10 -6
- package/dist/bin/sync.mjs +23 -98
- package/dist/bin/triage.mjs +1 -1
- package/dist/bin/verify.mjs +1 -1
- package/dist/{checks-BC-F8bsv.mjs → checks-BefrkjiT.mjs} +729 -25
- package/dist/{docs-compat-Ft1r2sf0.mjs → docs-compat-CSljVi3O.mjs} +13 -8
- package/dist/eslint.d.mts +13 -4
- package/dist/eslint.mjs +48 -6
- package/dist/guardrails-BfGwehVj.mjs +2414 -0
- package/dist/installed-typescript-6MtIWlE4.mjs +84 -0
- package/dist/oxc/anti-slop/index.mjs +541 -34
- package/dist/oxc/guardrails/index.d.mts +1 -1
- package/dist/oxc/guardrails/index.mjs +2 -1854
- package/dist/oxc/lint.d.mts +10 -1
- package/dist/oxc/lint.mjs +13 -5
- package/dist/{oxlint-CCOJqj3d.mjs → oxlint-CkHhK5K_.mjs} +33 -11
- package/dist/{package-DnxZ2CXZ.mjs → package-DDG3YH7W.mjs} +10 -5
- package/dist/{ports-DGP6bPJy.mjs → ports-DAeEJsYh.mjs} +22 -0
- package/dist/{proof-stamp-lyD84zmj.mjs → proof-stamp-BFV7JTZT.mjs} +5 -4
- package/dist/{ratchet-SQ7vTR0i.mjs → ratchet-2FeMs1kh.mjs} +4 -3
- package/dist/{suppression-base-whhvw-IJ.mjs → suppression-base-CYaLZAq7.mjs} +2 -2
- package/dist/{suppression-budget-CtIYSoDO.mjs → suppression-budget-CPDSFg4X.mjs} +1 -1
- package/dist/{suppressions-C79kRvYI.mjs → suppressions-CxPnh4sC.mjs} +2 -2
- package/dist/{templates-Dg188oRC.mjs → templates-HG0fel2S.mjs} +1 -1
- package/dist/{type-aware-rules-DMuN6sHb.mjs → type-aware-rules-Da3769fI.mjs} +9 -1
- package/dist/{typescript--_8og8AM.mjs → typescript-CxfNxyr2.mjs} +59 -98
- package/dist/{workflow-CPcNc8KL.mjs → workflow-C-oBwL2H.mjs} +25 -1
- package/package.json +9 -5
- package/dist/bin/check-interface-ranges.d.mts +0 -1
- package/dist/bin/check-interface-ranges.mjs +0 -44
- package/dist/interface-ranges-CcVSr59f.mjs +0 -116
package/README.md
CHANGED
|
@@ -40,7 +40,6 @@ The AntelopeJS guardrail pack: shared lint, format and dead-code presets, the co
|
|
|
40
40
|
| bin | `antelopejs-api-diff <base-ref>` | Compares published declaration bundles against committed HEAD |
|
|
41
41
|
| bin | `antelopejs-comment-proof <base-ref>` | Compares comment-free JavaScript emit against committed HEAD |
|
|
42
42
|
| bin | `antelopejs-body-check <body.md \| -> [--head <sha>] [--base <sha>]` | Checks a PR body's proof and findings blocks against HEAD; `--findings` prints the findings block |
|
|
43
|
-
| bin | `antelopejs-check-interface-ranges` | Fails on interface ranges that break module startup |
|
|
44
43
|
| bin | `antelopejs-readme-strip --kind <kind> --name <label-name>` | Writes a framework repository's README strip banner to `.github/readme/strip.svg` ([docs](docs/documentation-checks.md#framework-strip-banner)) |
|
|
45
44
|
| bin | `antelopejs-garden [--json] [--apply] [--apply-prunes]` | The Gardener's scans of the organization through the GitHub API and npm |
|
|
46
45
|
| bin | `antelopejs-triage [--json]` | Community Triage's ranked shortlist of untriaged issues |
|
|
@@ -53,7 +52,7 @@ The AntelopeJS guardrail pack: shared lint, format and dead-code presets, the co
|
|
|
53
52
|
|
|
54
53
|
- `--json` prints `{ generatedAt, findings, prunes, skipped }`. A finding is `{ key, repo, check, subject, severity, evidence, doneMeans }` with the key `repo|check|subject`, sorted. `skipped` lists every check whose source does not exist yet, or that could not run.
|
|
55
54
|
- Without `--json` it prints failures only. The exit code is non-zero only when a check could not run.
|
|
56
|
-
- The `branch-governance` check reads the rules in force on the default branch of every in-scope repository. It reports an `urgent` finding for each missing `deletion`, `non_fast_forward`, `required_linear_history` and `pull_request` rule (subject `<branch>:rule:<type>`), and a `normal` one when no rule requires `ci / checks` from GitHub Actions (`<branch>:checks`). It reads each ruleset that contributes a rule and reports an `urgent` `<branch>:bypass` finding when its bypass list holds an actor other than the admin repository role or an organization administrator, in any bypass mode. A repository ruleset that still lets the Maintain role bypass is reported this way.
|
|
55
|
+
- The `branch-governance` check reads the rules in force on the default branch of every in-scope repository. It reports an `urgent` finding for each missing `deletion`, `non_fast_forward`, `required_linear_history` and `pull_request` rule (subject `<branch>:rule:<type>`), and a `normal` one when no rule requires `ci / checks` from GitHub Actions (`<branch>:checks`). It reads each ruleset that contributes a rule through the repository rulesets endpoint, which serves organization rulesets without the `admin:org` scope, and reports an `urgent` `<branch>:bypass` finding when its bypass list holds an actor other than the admin repository role or an organization administrator, in any bypass mode. A repository ruleset that still lets the Maintain role bypass is reported this way.
|
|
57
56
|
- The `repo-admins` check reads the collaborators of every non-archived repository (`affiliation=all`, so direct, team and organization-owner access) and reports one `normal` finding per login that holds the `admin` role outside `Upd4ting`, `mwesto`, `dada-sudo`, `Thomasims` and `alessaloisio`. The finding has `repo` set to the organization, the subject `repo-admin:<login>` and the repositories in its evidence, so a person is one finding however many repositories they administer. The Maintain role is not read: it has no bypass on a default branch ruleset. The separate `governance-drift` check reports each organization owner outside `Upd4ting`, `mwesto` and `dada-sudo` (subject `org-admin:<login>`).
|
|
58
57
|
- The `org-checks-ruleset` check reads the organization rulesets and reports an `urgent` finding, with `repo` set to the organization, when `Default branch protection` or `Required CI` is missing or has drifted. `Default branch protection` must be active, target branches, match `~DEFAULT_BRANCH` and apply to `~ALL` repositories. `Required CI` must be active, target branches, match `~DEFAULT_BRANCH`, apply to the `pack` property values `full` and `template`, and require `ci / checks` from GitHub Actions.
|
|
59
58
|
- `--apply` turns `delete_branch_on_merge` on for each repository the `conformance` check reports it off on, and writes nothing else.
|
|
@@ -125,17 +124,17 @@ export default defineConfig({
|
|
|
125
124
|
|
|
126
125
|
### What the preset turns on
|
|
127
126
|
|
|
128
|
-
| Group | Rules
|
|
129
|
-
| -------------- |
|
|
130
|
-
| 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
|
|
131
|
-
| Imports | `import/no-cycle`, `import/no-self-import`, `import/no-duplicates`
|
|
132
|
-
| 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`
|
|
133
|
-
| Complexity | `max-params` 5, `max-lines-per-function` 120, `max-lines` 500, `max-depth` 4, `complexity` 20
|
|
134
|
-
| 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
|
|
135
|
-
| 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 |
|
|
136
|
-
| Import sorting | `perfectionist/sort-imports`, autofixed by `oxlint --fix`
|
|
127
|
+
| Group | Rules | Default |
|
|
128
|
+
| -------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------- |
|
|
129
|
+
| 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 |
|
|
130
|
+
| Imports | `import/no-cycle`, `import/no-self-import`, `import/no-duplicates` | error |
|
|
131
|
+
| 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 |
|
|
132
|
+
| Complexity | `max-params` 5, `max-lines-per-function` 120, `max-lines` 500, `max-depth` 4, `complexity` 20 | error |
|
|
133
|
+
| 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 |
|
|
134
|
+
| Guardrails | `antelopejs/no-comments`, `antelopejs/no-inherited-key-lookup`, `antelopejs/no-presence-only-type-guard`, `antelopejs/no-read-then-insert`, and with type-aware lint `antelopejs/no-unrun-query`, `antelopejs/no-unsafe-object-assign` and `antelopejs/require-tsconfig-include`; in test files `antelopejs/no-fs-read-in-tests`, `antelopejs/no-self-import-in-tests`, `antelopejs/no-constant-value-assertion`, `antelopejs/no-typeof-function-only-test` and `antelopejs/require-assertion` | error |
|
|
135
|
+
| Import sorting | `perfectionist/sort-imports`, autofixed by `oxlint --fix` | off |
|
|
137
136
|
|
|
138
|
-
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.
|
|
137
|
+
Three anti-slop rules skip a value at its boundary. `no-runtime-typeof` also counts a `.js`/`.mjs` function documented `@returns {x is T}` as a type guard. `no-unsafe-dictionary-type` allows `Record<string, unknown>` as a `value is T` target or inside a type-guard body. `no-unknown-parameters` skips a `this` parameter, a parameter decorated `@JSONBody`, `@JsonBody` or `@Parameter`, the reason of a callback passed directly to `.catch(...)` or as `.then(_, onRejected)`, the parameter of a `(reason: unknown) => void` type declared as `reject` or on a `new Promise` executor, 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. It also skips a parameter typed exactly `unknown` that a function only classifies: the function declares a return type other than `unknown`, `any`, `boolean` or `void`, promised or not, never reassigns the parameter, never mentions `arguments` or `eval`, tests its type or converts it to text at least once, and reads it only as the argument of a type guard (`Array.isArray`, a function declared in the file whose type predicate names that argument, or an `isX` or `IsX` imported from another module and called with that argument alone, so a comparator such as `isDeepStrictEqual(value, other)` is not one), the left of `instanceof`, the operand of `typeof`, a side of `===`, `!==`, `==` or `!=`, an argument of a call to the function itself at the parameter's own position, the first argument, as is, of the global `String(...)` or `JSON.stringify(...)` (both take any value, as `no-base-to-string` with `checkUnknown: false` agrees), or anywhere a type test on it holds. A test holds in the branch of an `if` or `?:`, or on the right of `&&` or `||`, that the guard call, `instanceof` or `typeof value === "..."` (or its negation, joined by `&&` and `||`) selects, and in the statements after an `if` with no `else` that returns or throws unless the test holds, arrows, function expressions and object methods inside them included, but not a function declaration, which is hoisted above the test, nor a class body with its methods, accessors and property initializers; a comparison with `null` or `undefined` narrows nothing. `typeof value` against a primitive's name, a predicate declared in the file and an imported `isX` narrow precisely. `Array.isArray`, `instanceof` and `typeof value` against `"object"` or `"function"` narrow loosely, to `any[]`, a class whose type arguments are `any`, `object` or `Function`, which TypeScript lets into a narrower type unchecked: where only such a test holds, the value may not be returned, yielded, called, constructed, assigned or held in a `const` with no annotation, directly or through `?:`, `&&`, `||`, `??` and `await`. A cast of the parameter (`as`, `<T>`, `satisfies`, `!`) or holding it in a `let`, a `var` or a `const` annotated with anything but `unknown[]` is reported wherever it sits, because TypeScript lets an `object` into a type whose members are all optional without checking one; so is a property read, a call argument, a store or a return where no test holds, a call of a local `isX` that declares no type predicate, a template literal, `value.toString()`, `new String(value)`, `JSON.parse(value)`, and a function that answers a verdict, `boolean`, `true | false` (also with `undefined`, `null` or `void`), or a type predicate or `asserts` clause on another parameter (declare `value is T` instead), or `void`. Two gaps remain. A loosely narrowed value passed as an argument to a function whose parameter is narrower, put in an object or array literal, or read from (`value[0]` after `Array.isArray`, `value.get(key)` after `instanceof Map`) reaches a narrower type as `any` or `object` unseen. An imported one-argument `isX` that is not a type predicate, such as lodash `isEmpty`, or whose predicate names a loose type, and a same-file predicate that names a loose type, such as `v is object`, still count as precise guards. Last, it skips a parameter typed exactly `unknown` that a function only forwards: under the same conditions on reassignment, `arguments` and `eval`, and a declared return type other than `unknown`, `any` or a verdict (`void` passes), every read of it is a direct argument, not spread, cast or the callee, of a call that is neither the function itself, a type guard, `String(...)`, `JSON.stringify(...)`, nor a callee named as a decoder or validator (`parse`, `decode`, `assert`, `validate` and their forms, which the parse-boundary rule above judges). The callee is a member call (`this.lifecycle.construct(config)`, `this.callbacks?.provide?.(config)`) that is not a collection store (`set`, `add`, `push`, `unshift`, `splice`), not a property writer (`Object.assign`, `Object.defineProperty`, `Object.defineProperties`, `Object.setPrototypeOf`, `Reflect.set`, `Reflect.defineProperty`, `Reflect.setPrototypeOf`), and not rooted at another parameter, directly or through a variable initialized, destructured or assigned from one, an imported function, or a function declared in the file whose parameter at that position is exactly `unknown` and itself exempt. TypeScript rejects an `unknown` argument to any parameter narrower than `unknown` or `any`, so an unseen callee takes one of those two; one that takes `any`, such as an import whose parameter is `any`, is not caught. A forward to a global the file never declares or imports, to a callee another parameter hands in, to a same-file function whose parameter is `any`, untyped or reported, or around a cycle of forwards back to the same parameter, and a function that forwards the value and also reads it any other way are reported. A bodiless signature, such as `construct?(config: unknown)` in an interface, has nothing to forward and stays reported.
|
|
139
138
|
|
|
140
139
|
`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.
|
|
141
140
|
|
|
@@ -143,19 +142,20 @@ No rule warns. oxlint reports `correctness` as warnings by default, and warnings
|
|
|
143
142
|
|
|
144
143
|
The guardrail rules:
|
|
145
144
|
|
|
146
|
-
| Rule | Fails on
|
|
147
|
-
| ----------------------------------------- |
|
|
148
|
-
| `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`
|
|
149
|
-
| `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
|
|
150
|
-
| `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
|
|
151
|
-
| `antelopejs/no-read-then-insert` | a call to `insert`, `insertOne` or `insertMany` on a table an earlier `get`, `
|
|
152
|
-
| `antelopejs/no-
|
|
153
|
-
| `antelopejs/
|
|
154
|
-
| `antelopejs/no-
|
|
155
|
-
| `antelopejs/no-
|
|
156
|
-
| `antelopejs/
|
|
157
|
-
| `antelopejs/
|
|
158
|
-
| `antelopejs/no-
|
|
145
|
+
| Rule | Fails on |
|
|
146
|
+
| ----------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
147
|
+
| `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` |
|
|
148
|
+
| `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 |
|
|
149
|
+
| `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 |
|
|
150
|
+
| `antelopejs/no-read-then-insert` | a call to `insert`, `insertOne` or `insertMany` on a table an earlier `get`, `getAll`, `count`, `find`, `findOne`, `getBy…` or `findBy…` (`getBy`, `getByEmail`, `findByKey`) read in the same function. Also an insert, on any table, that a function of the same file makes when an awaited read (directly or through `.run()` or `.then`, so not `Map.get` or `headers.get`) found nothing before the call to it: the call sits in the branch an `if`, `?:`, `&&`, `\ |
|
|
151
|
+
| `antelopejs/no-unrun-query` | an `@antelopejs/interface-database` query left unrun in what a caller awaits: returned from an async function or from a function handed to `then`, `catch` or `finally`, inline or by name, or passed to the `resolve` of a `new Promise` executor, inline or by name, such as `async () => table.count()`, `.then(countRows)` or `resolve(table.count())`. The query may sit behind `Promise.resolve`, or at any depth in arrays, tuples, object literals and the interfaces and object types the project declares, such as `async () => ({ total: table.count() })`. A held `Table` is a handle, not a pending query, so `async () => ({ table })` is not reported, nor is a class instance. A query is not thenable, so the caller awaits the query object and nothing reaches the database; `table.count().run()` is not reported, nor is a query a plain function returns to its caller. A query is a type whose `run` the installed `@antelopejs/interface-database` declares, read from the TypeScript program of the tsconfig that lists the file. On only with type-aware lint |
|
|
152
|
+
| `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 |
|
|
153
|
+
| `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. Also an import in a TypeScript or `.vue` file that the tsconfig listing it cannot resolve: a static `import` with a specifier, an `export … from`, or `import("…")` of a string literal. The program types everything imported through it as an error type, so `typescript/no-unsafe-*` reports there are false and rules that need the types find none. Not reported: a side-effect `import "./x.css"`, an import in a JavaScript file, an untyped package, a module a `declare module` in a listed file declares, and a `.vue` component, which only Volar resolves. List the file in a tsconfig that resolves the import through its `paths`, `baseUrl` or `node_modules`; in a Nuxt layer, a `tsconfig.json` that extends the generated `.nuxt/tsconfig.json`, with the lint script running `nuxt prepare` first. On only with type-aware lint |
|
|
154
|
+
| `antelopejs/no-fs-read-in-tests` | `readFileSync` or `readdirSync` from `fs` in a test file. Files under `fixtures/`, `helpers/` and `locales/` may read |
|
|
155
|
+
| `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 |
|
|
156
|
+
| `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)` |
|
|
157
|
+
| `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 |
|
|
158
|
+
| `antelopejs/no-typeof-function-only-test` | a test whose only assertions are `toBeTypeOf("function")`, `to.be.a("function")` or equivalents |
|
|
159
159
|
|
|
160
160
|
`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.
|
|
161
161
|
|
|
@@ -222,6 +222,7 @@ pnpm install
|
|
|
222
222
|
| `lefthook.yml` | Pre-commit on staged files: oxfmt, oxlint, size, suppressions. Pre-push: typecheck |
|
|
223
223
|
| `package.json` | `prepare` installs lefthook. Sets `checks`, `size`, `ratchet`, `ratchet:update`, `suppressions`, `suppressions:update`, `sync`, `sync:check`; adds missing `typecheck`, `lint`, `format`, `format:check`, `knip`; adds `lefthook` and `knip` |
|
|
224
224
|
| `renovate.json` | Writes one extending `github>AntelopeJS/.github:renovate.json5` when the repository has no Renovate config at any path Renovate reads (including a `renovate` key in `package.json`). An existing config stays as it is; sync and `--check` fail one that does not extend the preset. Under `--profile template`, only in the template source, so a scaffold may keep, change or delete the copy it gets |
|
|
225
|
+
| `.gitattributes` | Adds `* text=auto eol=lf` as the first line when no line holds it, so text files check out with LF on Windows whatever `core.autocrlf` says and a shell script still runs. Patterns the file already lists stay after it and override it |
|
|
225
226
|
| `.nvmrc` | `24` |
|
|
226
227
|
| `.agents/setup` | Orb setup: switches to the `.nvmrc` Node, activates `packageManager` through corepack, installs with the frozen lockfile |
|
|
227
228
|
| `AGENTS.md` | Writes the managed block between `<!-- antelopejs-guardrails:start -->` and `:end -->`; text outside the markers stays |
|
|
@@ -231,11 +232,11 @@ pnpm install
|
|
|
231
232
|
| `guardrails.suppressions.json` | Records the current suppression counts when the file is missing; restores the committed file instead when HEAD has one; otherwise only adds `config` and `agentFiles` at today's counts when the file predates them |
|
|
232
233
|
| `<layer>/build/backend-boundary.ts` | Where a DMS frontend layer tracks one, restores the pack's backend boundary plugin for the package that holds the layer. A formatter's rewrite is not drift; any other edit is |
|
|
233
234
|
|
|
234
|
-
`--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.
|
|
235
|
+
`--profile template` writes only what `antelopejs-checks` runs, for template repositories: the three preset configs, `.gitattributes`, 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.
|
|
235
236
|
|
|
236
|
-
`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.
|
|
237
|
+
`pnpm run checks` runs `typecheck`, `lint`, `format:check`, `knip`, `test`, `size`, `suppressions` and `sync:check`, plus `ratchet` when `guardrails.ratchet.json` exists. It prints only the output of the steps that failed. Sync adds the ratchet scripts and pre-commit hook only while `guardrails.ratchet.json` exists. When the repository has a verify layer, an `.agents/skills/verify-*` folder holding a `verify.config.ts` or a `tsconfig.json`, it also runs `verify:types` and `verify:lockfiles`, which need no package script. Neither writes a file in the repository, spawns a package manager or fetches anything, so both pass offline after a root install, as CI runs them. When the repository holds a `pnpm-lock.yaml`, outside what `.gitignore` leaves out, it also runs `lockfile:singletons`, which fails when a lockfile resolves an `@antelopejs/interface-*` package at more than one version and names the importers and packages that pull each copy. It reads the lockfiles only. When a tracked `package.json` declares an `@antelopejs/*` package, it also runs `dependency:ranges` (see [Dependency ranges](#dependency-ranges)), which reads the manifests 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. When the `README.md` of the root or of a workspace package holds a config example whose `package` is the `name` in the root's or a workspace package's `package.json`, such as `source: { type: "package", package: "@antelopejs/brevo", version: ">=0.0.9 <0.1.0" }`, it also runs `readme:version`. It fails when that example's `version` range, read as npm reads it, does not admit the `version` in that `package.json`, and names the README line. A value that is not a range, such as `latest`, passes. When the root or a workspace package is not `private` and names declarations through `types`, `typings` or `exports`, it also runs `published:types`, after `test` and alone. It packs each such package with pnpm or npm, which runs its `prepack`. It installs the tarball alone in a scratch folder without install scripts, together with the package's peers (optional ones included), `typescript` and `@types/node`, both at their latest version unless the package names them as peers. A workspace package it depends on comes from that package's own tarball, not from the registry. Then it runs `tsc` with `skipLibCheck: false`, `strict` and `nodenext` resolution over a file that imports each entry the package's `exports` names, a `*` subpath once per shipped file it matches. A package without `exports` gets its bare name and every declaration file it ships instead. The step fails on any error and names each file as `<package>/<path>`. It needs the registry, so it fails offline unless the package manager's store already holds what the install needs.
|
|
237
238
|
|
|
238
|
-
- `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`.
|
|
239
|
+
- `verify:types` type-checks each layer's own code with the repository's own TypeScript, run as `node <typescript>/bin/tsc` without a shell. A repository that installs the TypeScript 6 API as `typescript` (`npm:@typescript/typescript6`) for tools that need it, beside TypeScript 7 as `@typescript/native`, runs `@typescript/native`'s `tsc`. The files are those the layer's `tsconfig.json` includes, minus its `playground` folder and any `node_modules` or `dist` folder: verify compiles a playground itself, with the playground's own config, after installing it. The step writes a config to the system temp folder that extends the layer's, lists those files, keeps the layer's type roots, sets `noEmit` and unsets with `null` the `declaration`, `composite`, `incremental`, `tsBuildInfoFile`, `declarationDir`, `declarationMap`, `emitDeclarationOnly` and `isolatedDeclarations` the layer may inherit, then deletes it. No `.tsbuildinfo` is written, no declaration check runs on code that is never emitted, and `skipLibCheck` keeps the layer's value. `antelopejs-sync` writes the `tsconfig.json` of the shared `verify-interface`, `verify-module` and `verify-template` layers; a repository's own layer, such as a `verify-dms-*` one, keeps the one it wrote. A layer with a `verify.config.ts` and no `tsconfig.json` fails, and so does one whose `tsconfig.json` does not include its `verify.config.ts`.
|
|
239
240
|
- `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.
|
|
240
241
|
|
|
241
242
|
`ANTELOPEJS_CHECKS_SKIP` accepts both names.
|
|
@@ -340,7 +341,7 @@ Pass paths to check only those files, as the pre-commit hook does. The command a
|
|
|
340
341
|
|
|
341
342
|
### Cleanup proof
|
|
342
343
|
|
|
343
|
-
A behaviour-preserving cleanup PR shows `antelopejs-api-diff <base-ref>` passing. It checks each tracked package with a `tsconfig.json` that publishes something (not private, and declaring `exports`, `main`, `types`, `typings` or `typesVersions`) and lists the others as `API: skipped <directory>, <reason>.`. Each package is analysed and bundled with
|
|
344
|
+
A behaviour-preserving cleanup PR shows `antelopejs-api-diff <base-ref>` passing. It checks each tracked package with a `tsconfig.json` that publishes something (not private, and declaring `exports`, `main`, `types`, `typings` or `typesVersions`) and lists the others as `API: skipped <directory>, <reason>.`. Each package is analysed and bundled with the pack's own TypeScript 6 (`@typescript/typescript6`), never the `typescript` the repository installs, so a repository on TypeScript 7, which has no compiler API, is proven like any other. The package's config is read as the TypeScript it installs reads it: on TypeScript 5, each option whose default TypeScript 6 changed (`strict`, `alwaysStrict`, `types`, `module`, `moduleResolution`, `esModuleInterop`, `allowSyntheticDefaultImports`, `noUncheckedSideEffectImports`, `target`) keeps its TypeScript 5 default when the config leaves it unset, the options TypeScript 6 deprecated, such as `baseUrl`, still compile, and the output is laid out under the common directory of the sources when no `rootDir` is set. A package that declares `typescript` but cannot resolve it fails with an execution error naming the package and asking for an install, because the pack cannot tell which defaults it builds with; one that declares none is read with TypeScript 6's defaults. Large packages are bundled by several worker processes (up to 8, bounded by cpus and free memory); the output is the same as a single process. It emits declarations without comments, resolves published entries from `exports` (preferring `types`), `main`, `types`/`typings` and `typesVersions`, and bundles each entry's local declaration closure. External packages stay external. The bundles of both revisions are compared as one `declarations.d.ts`: an index of every published entry, then each distinct declaration text once, under one `// In` line per entry that carries it (`// In every entry` when all do). A change shared by many entries is printed once. The first hunk that changes a declaration below its `// In` lines names its entries in the hunk header, and an added or removed entry prints one index line and one `// In` line per declaration it shares. Stable top-level ordering ignores declaration moves between internal files while preserving overload order. Members of object type literals, interfaces and classes are compared in a canonical order, because TypeScript can emit an inferred object type's properties in another order after a refactor; overloads, call and construct signatures, tuple elements, parameters, enum members and union constituents keep their written order. Compiler errors fail the proof.
|
|
344
345
|
|
|
345
346
|
A comment-only PR shows `antelopejs-comment-proof <base-ref>` passing instead of a verifier. It includes private packages, ignores type diagnostics and compares comment-free JavaScript emit byte for byte. Both commands exclude test sources, fail on added or removed outputs, and print unified diffs for changes.
|
|
346
347
|
|
|
@@ -436,7 +437,7 @@ export default antelopeNuxtConfig({
|
|
|
436
437
|
});
|
|
437
438
|
```
|
|
438
439
|
|
|
439
|
-
`typeAware` runs the oxlint preset's type-aware rules, as `@typescript-eslint/<rule>`, on the script blocks of `.vue` files, which `oxlint-tsgolint` cannot read
|
|
440
|
+
`typeAware` runs the oxlint preset's type-aware rules, as `@typescript-eslint/<rule>`, on the script blocks of `.vue` files, which `oxlint-tsgolint` cannot read, and with them `antelopejs/no-unsafe-object-assign` and `antelopejs/require-tsconfig-include`. Off when omitted. TypeScript files are left to oxlint, so nothing is type-checked twice. `tsconfigRootDir` is the project root. Each `.vue` file must be listed by its nearest `tsconfig.json`; a file outside it, such as a playground no tsconfig includes, fails to parse. In a Nuxt layer that tsconfig is a `tsconfig.json` that extends the generated `.nuxt/tsconfig.json`, which lists the app and carries the `paths` of the layer's aliases such as `#dms-core/*`, and the lint script runs `nuxt prepare` first so the file exists. An import the tsconfig cannot resolve is reported by `antelopejs/require-tsconfig-include`: everything imported through it is an error type, so `no-unsafe-*` would report code that is not unsafe. Types flow from the `.ts` files a component imports. Without Volar, a type imported from another `.vue` file is an error type: `no-unsafe-*` reports code that uses it, which `rules` can switch off, and a `lang="tsx"` block fails to parse. `antelopejs/no-unsafe-object-assign` skips a component with `generic` type parameters, which only Vue's compiler brings into scope.
|
|
440
441
|
|
|
441
442
|
`@nuxt/eslint-config` supplies the Vue and TypeScript rules. The preset only records where AntelopeJS layers differ: single-word page components, `any` and `{}` allowed, `_`-prefixed unused bindings, and import order left alone. It sets no formatting rule, since oxfmt formats `.vue`. Every rule the resolved config sets to warn becomes an error, so no rule warns there either. Pass `rules` to layer your own on top, and declare `@nuxt/eslint-config` in the front end's `package.json`.
|
|
442
443
|
|
|
@@ -456,29 +457,18 @@ The defaults declare what Knip cannot infer for an AntelopeJS module:
|
|
|
456
457
|
|
|
457
458
|
`entry`, `project`, `ignore`, `ignoreDependencies` and `ignoreBinaries` options are appended to the defaults. `frontend-vue/` stays out of `project`, so a repository can opt it in through Knip's `workspaces`.
|
|
458
459
|
|
|
459
|
-
##
|
|
460
|
+
## Dependency ranges
|
|
460
461
|
|
|
461
|
-
`@antelopejs
|
|
462
|
+
An `@antelopejs/*` package ships breaking changes in minor releases, so a range open past the next minor lets an install resolve a breaking release its dependent was never built against. `pnpm run checks` runs `dependency:ranges`, which fails on each `@antelopejs/*` range in `dependencies`, `devDependencies`, `peerDependencies` or `optionalDependencies`, in every `package.json` git tracks, that does not stop below the next minor of its floor, and prints the range to use:
|
|
462
463
|
|
|
463
|
-
|
|
464
|
+
| The floor is… | declare | also accepted |
|
|
465
|
+
| ------------- | ---------------- | ------------------ |
|
|
466
|
+
| 0.x | `>=0.4.0 <0.5.0` | `^0.4.0`, `~0.4.0` |
|
|
467
|
+
| 1.0 or later | `~1.2.0` | `>=1.2.0 <1.3.0` |
|
|
464
468
|
|
|
465
|
-
|
|
466
|
-
| ------------------------------------------------- | -------------------------------------------- |
|
|
467
|
-
| consumes the interface | `>=<floor> <1.0.0` (`<next major>` from 1.0) |
|
|
468
|
-
| implements it (listed in `antelopeJs.implements`) | `>=<floor> <0.<minor + 1>.0` while it is 0.x |
|
|
469
|
+
A narrower range fails too: `@antelopejs/core` keeps one copy of each interface and refuses to start a module whose range that copy falls outside, so an exact pin (`0.1.7`) breaks startup at the next patch release. `file:` and `link:` specs are skipped. A `workspace:` spec is read as pnpm publishes it, `workspace:^` on a sibling at `1.2.3` as `^1.2.3`, so declare `workspace:~`; it is skipped in a `private` manifest, which is never published. The step runs only in a git checkout whose tracked manifests declare an `@antelopejs/*` package.
|
|
469
470
|
|
|
470
|
-
|
|
471
|
-
|
|
472
|
-
When the interface sits in the same repository, as in a DMS monorepo, `antelopejs-sync` moves the implementer's range for you: a minor interface release from `0.6.1` to `0.7.0` moves `>=0.6.0 <0.7.0` to `>=0.7.0 <0.8.0`, then sync runs `pnpm install --lockfile-only` so the lockfile follows. The interface is not on npm yet when the release hook runs, so the workspace must link it: set `link-workspace-packages=true` in `.npmrc` or `linkWorkspacePackages: true` in `pnpm-workspace.yaml`. When the relock fails, sync leaves the ranges unmoved and exits 1. An interface `.release-it.json` whose `after:bump` hook runs `pnpm --dir ../.. run sync` and `git add -u ../..` commits both with the release. `antelopejs-sync --check` reports the stale range as drift.
|
|
473
|
-
|
|
474
|
-
```jsonc
|
|
475
|
-
// package.json
|
|
476
|
-
{
|
|
477
|
-
"scripts": {
|
|
478
|
-
"lint": "oxlint && antelopejs-check-interface-ranges",
|
|
479
|
-
},
|
|
480
|
-
}
|
|
481
|
-
```
|
|
471
|
+
When the package sits in the same repository, as in a DMS monorepo, its range must also admit the version there, and `antelopejs-sync` moves it for you: a minor release of a sibling from `0.6.1` to `0.7.0` moves every `>=0.6.0 <0.7.0` on it to `>=0.7.0 <0.8.0`, then sync runs `pnpm install --lockfile-only` so the lockfile follows. The package is not on npm yet when the release hook runs, so the workspace must link it: set `link-workspace-packages=true` in `.npmrc` or `linkWorkspacePackages: true` in `pnpm-workspace.yaml`. When the relock fails, sync leaves the ranges unmoved and exits 1. An interface `.release-it.json` whose `after:bump` hook runs `pnpm --dir ../.. run sync` and `git add -u ../..` commits both with the release. `antelopejs-sync --check` reports the stale range as drift.
|
|
482
472
|
|
|
483
473
|
## Vendored anti-slop
|
|
484
474
|
|
|
@@ -7,9 +7,12 @@ import { homedir, tmpdir } from "node:os";
|
|
|
7
7
|
/** A GitHub or npm answer that is not a success. */
|
|
8
8
|
var ApiError = class extends Error {
|
|
9
9
|
status;
|
|
10
|
-
|
|
10
|
+
/** The OAuth scopes GitHub accepts for the call, when the token holds none of them; empty otherwise. */
|
|
11
|
+
missingScopes;
|
|
12
|
+
constructor(status, message, missingScopes = []) {
|
|
11
13
|
super(message);
|
|
12
14
|
this.status = status;
|
|
15
|
+
this.missingScopes = missingScopes;
|
|
13
16
|
}
|
|
14
17
|
};
|
|
15
18
|
const GITHUB = "https://api.github.com";
|
|
@@ -85,6 +88,17 @@ function githubHeaders(token) {
|
|
|
85
88
|
"User-Agent": "antelopejs-garden"
|
|
86
89
|
};
|
|
87
90
|
}
|
|
91
|
+
function scopeList(header) {
|
|
92
|
+
return (header ?? "").split(",").map((scope) => scope.trim()).filter(Boolean);
|
|
93
|
+
}
|
|
94
|
+
/** The scopes a refused answer (403 or 404) accepts when the classic token it went to holds none; empty for any other answer or a token GitHub lists no scopes for. */
|
|
95
|
+
function missingScopes(response) {
|
|
96
|
+
const held = response.headers.get("x-oauth-scopes");
|
|
97
|
+
if (held === null || response.status !== 403 && response.status !== 404) return [];
|
|
98
|
+
const accepted = scopeList(response.headers.get("x-accepted-oauth-scopes"));
|
|
99
|
+
const holds = new Set(scopeList(held));
|
|
100
|
+
return accepted.some((scope) => holds.has(scope)) ? [] : accepted;
|
|
101
|
+
}
|
|
88
102
|
/** Retries a rate-limited or gateway answer up to four times and returns the last answer. */
|
|
89
103
|
async function request(headers, url, init) {
|
|
90
104
|
for (let attempt = 1;; attempt++) {
|
|
@@ -127,7 +141,10 @@ function createApi(token) {
|
|
|
127
141
|
async function get(path, accept) {
|
|
128
142
|
const url = path.startsWith("http") ? path : `${GITHUB}${path}`;
|
|
129
143
|
const response = await request(headers, url, { headers: accept ? { Accept: accept } : {} });
|
|
130
|
-
if (!response.ok)
|
|
144
|
+
if (!response.ok) {
|
|
145
|
+
const missing = missingScopes(response);
|
|
146
|
+
throw new ApiError(response.status, missing.length ? `GET ${path}: HTTP ${response.status}, the token lacks the ${missing.join(" or ")} scope` : `GET ${path}: HTTP ${response.status} ${(await response.text()).slice(0, 200)}`, missing);
|
|
147
|
+
}
|
|
131
148
|
return response;
|
|
132
149
|
}
|
|
133
150
|
return {
|