@antelopejs/tooling-configs 0.5.1 → 0.5.3

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -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 |
@@ -35,7 +35,7 @@ The AntelopeJS guardrail pack: shared lint, format and dead-code presets, the co
35
35
  | bin | `antelopejs-comment-proof <base-ref>` | Compares comment-free JavaScript emit against committed HEAD |
36
36
  | 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 |
37
37
  | bin | `antelopejs-check-interface-ranges` | Fails on interface ranges that break module startup |
38
- | bin | `antelopejs-garden [--json] [--apply-pauses] [--apply] [--apply-prunes]` | The Gardener's scans of the organization through the GitHub API and npm |
38
+ | bin | `antelopejs-garden [--json] [--apply] [--apply-prunes]` | The Gardener's scans of the organization through the GitHub API and npm |
39
39
  | bin | `antelopejs-triage [--json]` | Community Triage's ranked shortlist of untriaged issues |
40
40
  | bin | `antelopejs-verify <command>` | The harness of the shared `verify-interface`, `verify-module` and `verify-template` skills |
41
41
  | bin | `antelopejs-lease run \| status \| down \| gc` | Ports, a mongod, logs and tmp per worktree; see [Run a DMS from a git worktree](./docs/agent-worktrees.md) |
@@ -44,9 +44,11 @@ The AntelopeJS guardrail pack: shared lint, format and dead-code presets, the co
44
44
 
45
45
  `antelopejs-garden` is the Gardener's deterministic scan. It reads the non-archived AntelopeJS repositories whose `pack` property is `full` or `template` and whose `tier` is N1 to N3, through the GitHub API and the npm registry, authenticated with the token `gh` is logged in with. It never clones.
46
46
 
47
- - `--json` prints `{ generatedAt, findings, pauses, 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.
47
+ - `--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.
48
48
  - Without `--json` it prints failures only. The exit code is non-zero only when a check could not run.
49
- - `--apply-pauses` sets the repository variable `NEXT_AUTOMERGE` to `shadow` on repositories where it is `on`, when `checks` is red on `next`, the ratchet file is back on a Clean repository, or governance drifted. It never sets `on` and writes nothing else.
49
+ - 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.
50
+ - 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>`).
51
+ - 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.
50
52
  - `--apply` turns `delete_branch_on_merge` on for each repository the `conformance` check reports it off on, and writes nothing else.
51
53
  - The `stale-branches` check lists, in one finding per repository, the branches other than the default, `next` and protected ones that head a merged or closed pull request at their current commit, or have no open pull request and no commit for 30 days. A branch that heads or receives an open pull request is never listed. `prunes` holds one `{ repo, branch, reason }` per listed branch, and `--apply-prunes` deletes exactly those refs.
52
54
 
@@ -126,9 +128,9 @@ export default defineConfig({
126
128
  | 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
129
  | Import sorting | `perfectionist/sort-imports`, autofixed by `oxlint --fix` | off |
128
130
 
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`.
131
+ 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
132
 
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.
133
+ `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
134
 
133
135
  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
136
 
@@ -189,10 +191,20 @@ export default defineConfig({
189
191
 
190
192
  ## Guardrail pack
191
193
 
192
- Run `antelopejs-sync` at the repository root, then install dependencies. It is idempotent: a second run changes nothing.
194
+ Onboard a repository with one command at its root. The repository needs a `package.json` and a git remote on GitHub.
195
+
196
+ ```bash
197
+ pnpm dlx --package=@antelopejs/tooling-configs antelopejs-sync --init
198
+ npx --package=@antelopejs/tooling-configs antelopejs-sync --init
199
+ ```
200
+
201
+ `--init` adds `node_modules` to `.gitignore` and declares each of `@antelopejs/tooling-configs`, `oxlint`, `oxlint-tsgolint` and `oxfmt` the repository does not declare yet. In a pnpm or npm workspace, it sets each member's declared pack tools to the root's ranges, so the workspace installs one copy of the pack, and moves the `options` of a member's oxlint config, which oxlint accepts only in the root config, to the same flags on the member's `oxlint` scripts. It stops before installing when an option has no command-line flag. 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.
202
+
203
+ 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`.
204
+
205
+ Every step is idempotent: a second run changes nothing. Plain `antelopejs-sync` also runs from a repository that already has the devDependencies installed:
193
206
 
194
207
  ```bash
195
- pnpm add -D @antelopejs/tooling-configs oxlint@1.81.0 oxlint-tsgolint oxfmt
196
208
  pnpm exec antelopejs-sync
197
209
  pnpm install
198
210
  ```
@@ -221,7 +233,7 @@ pnpm install
221
233
 
222
234
  `ANTELOPEJS_CHECKS_SKIP` accepts both names.
223
235
 
224
- 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.
236
+ 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.
225
237
 
226
238
  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.
227
239
 
@@ -1,9 +1,9 @@
1
1
  #!/usr/bin/env node
2
- import { a as parseManifest, i as packageManager } from "../package-Dn7VTFUW.mjs";
2
+ import { o as packageManager, s as parseManifest } from "../package-DiaBP7bI.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-BPIdT5ik.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-DJzdex32.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-BPIdT5ik.mjs";
6
6
  import { readFileSync } from "node:fs";
7
7
  import { spawnSync } from "node:child_process";
8
8
  import { parseArgs } from "node:util";
@@ -1,7 +1,7 @@
1
1
  #!/usr/bin/env node
2
2
  import { t as runCli } from "../cli-4Tv71vYk.mjs";
3
3
  import { c as repositoryRoot, n as authoredSizes, s as repositoryPath } from "../files-DJ0TeaTU.mjs";
4
- import { l as worktreeSuppressions, o as revisionSuppressions } from "../suppressions-BroaaGJ_.mjs";
4
+ import { l as worktreeSuppressions, o as revisionSuppressions } from "../suppressions-CQTcKCi1.mjs";
5
5
  import { t as checkSize } from "../size-DBatLT-F.mjs";
6
6
  import { resolve } from "node:path";
7
7
  import { parseArgs } from "node:util";