@avi2dg/checks 0.6.0 → 0.8.0

package/README.md

@@ -1,14 +1,14 @@
 # checks
 
 Deterministic checks shared across my TypeScript repos. One package,
-`@avi2dg/checks`: the oxlint base config, the tsconfig fragment with the
-Effect language-service block, the shared commitlint config, the shared
-dependency-cruiser base, the test-layout check with its bunfig preset,
-the commit-identity check with its workflow, the comment gate with its
-workflow and backtest, the oxlint suppressions ratchet, the Stryker
-mutation-testing preset with its no-regression comparator, the
-CI-wiring check, and the Effect error-channel plugin compiled to
-JavaScript.
+`@avi2dg/checks`: the `checks-lint` entry point that runs every lint gate
+below over a range it resolves itself, the oxlint base config, the
+tsconfig fragment with the Effect language-service block, the shared
+commitlint config, the shared dependency-cruiser base, the test-layout
+check with its bunfig preset, the commit-identity check, the comment
+gate with its backtest, the oxlint suppressions ratchet, the Stryker
+mutation-testing preset with its no-regression comparator, the CI-wiring
+check, and the Effect error-channel plugin compiled to JavaScript.
 
 Published as `@avi2dg/checks` on the public npm registry.
 
@@ -17,7 +17,7 @@ Published as `@avi2dg/checks` on the public npm registry.
 From the consuming repo:
 
 ```sh
-bun add -d @avi2dg/checks oxlint@1.83.0 oxlint-tsgolint@7.0.2002 @effect/tsgo@0.45.0 typescript@7.0.2 dependency-cruiser@18.4.0 @swc/core@1.16.2
+bun add -d @avi2dg/checks effect@4.0.0-rc.115 oxlint@1.83.0 oxlint-tsgolint@7.0.2002 @effect/tsgo@0.45.0 typescript@7.0.2 dependency-cruiser@18.4.0 @swc/core@1.16.2
 ```
 
 `.oxlintrc.json`:
@@ -52,11 +52,14 @@ cp node_modules/@avi2dg/checks/bunfig.toml bunfig.toml
 `package.json` gains three scripts:
 
 ```json
-"lint": "oxlint --type-aware && checks-lint-coverage && checks-test-layout && checks-commit-identity HEAD",
+"lint": "oxlint --type-aware && checks-lint",
 "typecheck": "tsc --noEmit && effect-tsgo diagnostics --project tsconfig.json --format text --strict",
 "test": "bun test --randomize"
 ```
 
+`checks-lint` runs every kit gate a lint needs; see "Lint entry point"
+below. Three of them:
+
 `lint-coverage.sh` fails when oxlint silently skips a tracked `.ts` or
 `.tsx` file, for example through a stray `.gitignore` entry. It compares
 `git ls-files` against oxlint's own file walk and names the missing files.
@@ -81,6 +84,81 @@ export default {
 The registry version is pinned by the consumer's lockfile; bump
 `@avi2dg/checks` to adopt a new release.
 
+## Lint entry point
+
+`checks-lint` runs each of the kit's lint gates in turn and names every
+one that fails, rather than stopping at the first:
+
+| Gate | Reads |
+| --- | --- |
+| `checks-lint-coverage` | the working tree |
+| `checks-test-layout` | the working tree |
+| `checks-commit-identity` | the range |
+| `checks-comment-gate` | the range |
+| `checks-suppressions-ratchet` | the range |
+| `checks-ci-wiring` | the working tree |
+
+```sh
+checks-lint
+checks-lint <base-ref> <head-ref>
+```
+
+It resolves the range once and hands the same one to every range gate.
+Locally, and on any event other than a pull request, the range ends at
+`HEAD` and starts where `HEAD` branched from the origin default branch:
+`origin/HEAD`, or when `origin/HEAD` is not set, as in an
+`actions/checkout` clone, `origin/<ciWiring.defaultBranch>` from the
+repository's `package.json` (see "CI wiring"), and `origin/main` when
+that is not declared. In a GitHub Actions pull request, where
+`GITHUB_EVENT_NAME` is `pull_request`, it ends
+at the event's head sha and starts where that branched from
+`origin/<base branch>`, so GitHub's merge commit is never in it. The
+base branch is read from the fetch, not from the event's recorded base
+sha, which GitHub leaves stale once the base branch advances after the
+pull request opens. Explicit base and head arguments override both.
+
+The range always starts at the merge base, never at the base branch's
+tip: commits the base branch gained after the head branched off would
+otherwise count against the head. When the head is the merge base, as
+on a push to the default branch or a local run on it, the range would be
+empty, so each range gate is handed that tip commit alone and checks it
+against its parent:
+
+```
+checks-lint: tip 10ba7d8935b73ed72624120a1542e51bd21ca7c7 from HEAD against origin/main
+```
+
+It prints the range, each gate's own report, then its verdict:
+
+```
+checks-lint: range 2504acf098d120e73a8ece3c96f22b934f35c6a8..10ba7d8935b73ed72624120a1542e51bd21ca7c7 from HEAD against origin/main
+...
+checks-lint: 3 of 6 gate(s) failed: checks-commit-identity, checks-comment-gate, checks-suppressions-ratchet
+```
+
+It exits 1 when any gate found a violation, and 2 when the range does
+not resolve or no failing gate could decide. Every gate runs, so a
+repository on `checks-lint` declares `ciWiring.gates` (see "CI wiring")
+and holds the test layout.
+
+CI runs it through `lint`. The checkout fetches the whole history, which
+the merge base needs:
+
+```yaml
+on:
+  pull_request:
+jobs:
+  lint:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v5
+        with:
+          fetch-depth: 0
+      - uses: oven-sh/setup-bun@v2
+      - run: bun install --frozen-lockfile
+      - run: bun run lint
+```
+
 ## Effect rules
 
 The base config loads the `effect-channel` plugin and turns on
@@ -123,6 +201,45 @@ oxlint resolves `files` against the directory of the config that holds
 the override, so a config passed with `-c` from outside the repository
 matches nothing and reports nothing.
 
+This repository's own override for `scripts/**` adds `node/no-sync`,
+`oxc/no-async-await`, `promise/avoid-new` and `unicorn/no-process-exit`,
+which need the `node`, `promise` and `unicorn` plugins in the override's
+`plugins`. `unicorn/no-process-exit` passes over any file that opens with
+a shebang, so a bin also needs `no-restricted-properties` on
+`process.exit`. Sites standing when the override lands go in oxlint's own
+baseline, `oxlint --suppress-all`, so their count can only fall.
+
+The language service holds the same paths to Effect-native IO through
+`overrides` in the plugin block of `tsconfig.json`. effect-tsgo keeps the
+severities `tsconfig.effect.json` sets when the child config restates the
+plugin with only its overrides:
+
+```json
+{
+  "extends": "@avi2dg/checks/tsconfig.effect.json",
+  "compilerOptions": {
+    "plugins": [
+      {
+        "name": "@effect/language-service",
+        "overrides": [
+          {
+            "include": ["src/**/*.ts"],
+            "options": {
+              "diagnosticSeverity": {
+                "nodeBuiltinImport": "error",
+                "asyncFunction": "error",
+                "newPromise": "error",
+                "extendsNativeError": "error"
+              }
+            }
+          }
+        ]
+      }
+    ]
+  }
+}
+```
+
 ## Test layout
 
 `checks-test-layout` fails unless the repo holds this shape, and names the
@@ -146,7 +263,7 @@ file and the path to move it to when it does not:
   with swc and reads import specifiers and identifier use, so a test that
   only carries `"node:child_process"` as a string is not a violation.
 - `scripts.test` is exactly `bun test --randomize` and `scripts.lint` runs
-  this check.
+  this check, itself or through `checks-lint` called by its bare bin name.
 - `bunfig.toml` carries every `[test]` key of the shipped preset with the
   same value, and `[test].pathIgnorePatterns` is always
   `["**/tests/quarantine/**"]`: the check pins it itself, so this repo,
@@ -262,11 +379,10 @@ bun run checks-commit-identity <base-ref> <head-ref>
 bun run checks-commit-identity <ref>
 ```
 
-With one argument it checks that commit alone, which is the form the
-`lint` script above runs on `HEAD`. It refuses a commit whose author or
-committer is outside the allowlist, and one whose trailer block carries
-a `Co-authored-by:` trailer as git parses it, and it names the offending
-commit and reason. Other trailers and prose mentioning an address in the
+With one argument it checks that commit alone. It refuses a commit
+whose author or committer is outside the allowlist, and one whose
+trailer block carries a `Co-authored-by:` trailer as git parses it, and
+it names the offending commit and reason. Other trailers and prose mentioning an address in the
 body are left alone. `GitHub <noreply@github.com>` is allowed as
 committer only, since that is who writes a squash merge.
 
@@ -279,31 +395,7 @@ owners restates it in `package.json`:
 }
 ```
 
-Enforcement runs on pull requests, where the range from the base branch's
-current tip to the head is visible:
-
-```yaml
-on:
-  pull_request:
-    types: [opened, edited, synchronize, reopened]
-jobs:
-  commit-identity:
-    runs-on: ubuntu-latest
-    steps:
-      - uses: actions/checkout@v5
-        with:
-          fetch-depth: 0
-      - uses: oven-sh/setup-bun@v2
-      - run: bun install --frozen-lockfile
-      - run: bunx checks-commit-identity "origin/$BASE_REF" "$HEAD_SHA"
-        env:
-          BASE_REF: ${{ github.event.pull_request.base.ref }}
-          HEAD_SHA: ${{ github.event.pull_request.head.sha }}
-```
-
-The checkout fetches the full history and the range starts at the
-fetched base branch, not the event's recorded base sha, which GitHub
-leaves stale once the base branch advances after the pull request opens.
+`checks-lint` runs it over each pull request's range; see "Lint entry point".
 
 ## Comment gate
 
@@ -326,27 +418,7 @@ pointer, a doc block, and a file opening with a rationale block over
 three lines, licence headers excepted; `scripts/comments.ts` holds the
 scanner the gate and the backtest share.
 
-Enforcement runs on pull requests, where the range from the base branch's
-current tip to the head is visible:
-
-```yaml
-on:
-  pull_request:
-    types: [opened, edited, synchronize, reopened]
-jobs:
-  comment-gate:
-    runs-on: ubuntu-latest
-    steps:
-      - uses: actions/checkout@v5
-        with:
-          fetch-depth: 0
-      - uses: oven-sh/setup-bun@v2
-      - run: bun install --frozen-lockfile
-      - run: bunx checks-comment-gate "origin/$BASE_REF" "$HEAD_SHA"
-        env:
-          BASE_REF: ${{ github.event.pull_request.base.ref }}
-          HEAD_SHA: ${{ github.event.pull_request.head.sha }}
-```
+`checks-lint` runs it over each pull request's range; see "Lint entry point".
 
 ## Suppressions ratchet
 
@@ -378,27 +450,7 @@ suppressions-ratchet: 2 count(s) in oxlint-suppressions.json rose or appeared; f
   src/dispatch.ts typescript/no-non-null-assertion rose from 12 to 13
 ```
 
-Enforcement runs on pull requests, where the range from the base branch's
-current tip to the head is visible:
-
-```yaml
-on:
-  pull_request:
-    types: [opened, edited, synchronize, reopened]
-jobs:
-  suppressions-ratchet:
-    runs-on: ubuntu-latest
-    steps:
-      - uses: actions/checkout@v5
-        with:
-          fetch-depth: 0
-      - uses: oven-sh/setup-bun@v2
-      - run: bun install --frozen-lockfile
-      - run: bunx checks-suppressions-ratchet "origin/$BASE_REF" "$HEAD_SHA"
-        env:
-          BASE_REF: ${{ github.event.pull_request.base.ref }}
-          HEAD_SHA: ${{ github.event.pull_request.head.sha }}
-```
+`checks-lint` runs it over each pull request's range; see "Lint entry point".
 
 ## CI wiring
 
@@ -408,14 +460,14 @@ that: a workflow whose lint step became a no-op leaves `bun run lint`
 green.
 
 The repository declares its gates once, in `package.json`, and `lint`
-runs the check:
+runs the check through `checks-lint`:
 
 ```json
 "ciWiring": {
   "gates": ["bun run lint", "bun run typecheck", "bun run test"]
 },
 "scripts": {
-  "lint": "oxlint --type-aware && checks-lint-coverage && checks-test-layout && checks-ci-wiring"
+  "lint": "oxlint --type-aware && checks-lint"
 }
 ```
 
@@ -450,8 +502,17 @@ supported way to wire a gate: it is not read, so a gate must run as a
 `run:` step, such as `bunx checks-comment-gate`, in the repo's own
 workflows.
 
+A step running `checks-lint` also counts for a declared gate that calls
+one of the gates `checks-lint` runs by its bare bin name, when the step
+calls `checks-lint` the same way: `bunx checks-lint` counts for
+`bunx checks-comment-gate "origin/$BASE_REF" "$HEAD_SHA"`. A step running `bun run lint` counts only for the `bun run lint` gate,
+since the check never reads what a package script runs. So once `lint`
+runs `checks-lint`, the per-gate entries can leave `ciWiring.gates`
+along with the workflows that ran them.
+
 The default branch is `main`; a repo with another one sets
-`"defaultBranch"` beside `"gates"`.
+`"defaultBranch"` beside `"gates"`, which `checks-lint` also reads when
+`origin/HEAD` is not set.
 
 It exits 1 naming each gap, with every step that runs the gate and why
 that step does not count:
@@ -577,12 +638,23 @@ The shared Stryker preset's `json` reporter writes
   not resolve `extends` in a JSON config, but a `.mjs` config that
   spreads an imported object consumes it. Keys the consumer sets after
   the spread win.
+- The `.ts` bins are written in Effect, so `effect` is a peer dependency
+  and `@effect/platform-bun`, which only the bins use, is a dependency.
+  `@effect/platform-node-shared` is a direct dependency at the same exact
+  version only to pin it: `@effect/platform-bun` asks for it with a `^`
+  range, and a newer rc peers on a newer `effect` than consumers install,
+  so all three move together.
 - Each runnable script ships a `checks-` bin entry, so consumer
   `package.json` scripts call the short name, which the package manager
   puts on `PATH` only there; a shell runs it through `bun run`, which
   never falls back to the registry the way `bunx` does. The `.ts` checks
   keep a `bun` shebang, which needs no build step and no `dist/`
   entry, unlike the oxlint plugin that node loads.
+- `checks-lint` runs each gate as its own bin in a child process rather
+  than importing it, so a gate behaves the same called alone or through
+  the entry point, and `lint-coverage.sh` stays a shell script. The
+  gates run one at a time with their output passed straight through, so
+  each report reads whole and in the table's order.
 - `checks-ci-wiring` runs inside `lint`, not in a workflow of its own:
   deleting the step that runs a check is the violation it catches, so the
   local `lint` is where it has to fail.
@@ -593,10 +665,11 @@ The shared Stryker preset's `json` reporter writes
   `@types/bun`, which would otherwise make every runtime `bun` import look
   like a dev-only dependency.
 - The pull request merge commit GitHub builds is authored by `GitHub
-  <noreply@github.com>`, which commit-identity refuses as an author. A
-  consumer that runs the check inside `lint` checks out
-  `github.event.pull_request.head.sha` instead of the default merge ref,
-  as this repo's `ci.yml` does.
+  <noreply@github.com>`, which commit-identity refuses as an author.
+  `checks-lint` ends a pull request's range at the event's head sha, so
+  the merge commit is never in it. A `lint` that calls
+  `checks-commit-identity HEAD` itself checks out
+  `github.event.pull_request.head.sha` instead of the default merge ref.
 - `no-deep-imports` judges the import specifier, never the resolved file.
   The base honours `exports` maps, so a subpath the map publishes resolves
   and passes, one it omits fails to resolve and is reported, and a package
@@ -622,7 +695,7 @@ a tag off `main` and reruns the build, `dist/` check, lint, typecheck
 and tests before it publishes:
 
 ```sh
-git tag v0.6.0 && git push origin v0.6.0
+git tag v0.8.0 && git push origin v0.8.0
 ```
 
 The `release` workflow publishes the tagged version through npm

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@avi2dg/checks",
-  "version": "0.6.0",
+  "version": "0.8.0",
   "description": "Deterministic checks shared across the captain's TypeScript repos",
   "license": "MIT",
   "repository": {
@@ -16,6 +16,10 @@
     "commitlint.config.js",
     "dependency-cruiser.config.js",
     "scripts/lint-coverage.sh",
+    "scripts/main.ts",
+    "scripts/git.ts",
+    "scripts/gates.ts",
+    "scripts/lint.ts",
     "scripts/test-layout.ts",
     "scripts/commit-identity.ts",
     "scripts/mutation-compare.ts",
@@ -34,6 +38,7 @@
     "./commitlint.config.js": "./commitlint.config.js",
     "./dependency-cruiser.config.js": "./dependency-cruiser.config.js",
     "./scripts/lint-coverage.sh": "./scripts/lint-coverage.sh",
+    "./scripts/lint.ts": "./scripts/lint.ts",
     "./scripts/test-layout.ts": "./scripts/test-layout.ts",
     "./scripts/commit-identity.ts": "./scripts/commit-identity.ts",
     "./scripts/mutation-compare.ts": "./scripts/mutation-compare.ts",
@@ -48,6 +53,7 @@
     "./dist/index.js": "./dist/index.js"
   },
   "bin": {
+    "checks-lint": "scripts/lint.ts",
     "checks-lint-coverage": "scripts/lint-coverage.sh",
     "checks-test-layout": "scripts/test-layout.ts",
     "checks-commit-identity": "scripts/commit-identity.ts",
@@ -59,7 +65,7 @@
   },
   "scripts": {
     "build": "bun build effect-channel/index.ts --outdir dist --target node --format esm",
-    "lint": "oxlint --type-aware && ./scripts/lint-coverage.sh && bun scripts/test-layout.ts && bun scripts/commit-identity.ts HEAD && bun scripts/comment-gate.ts HEAD && bun scripts/ci-wiring.ts && depcruise --config .dependency-cruiser.cjs effect-channel scripts tests commitlint.config.js dependency-cruiser.config.js stryker.preset.js .dependency-cruiser.cjs",
+    "lint": "oxlint --type-aware && bun scripts/lint.ts && depcruise --config .dependency-cruiser.cjs effect-channel scripts tests commitlint.config.js dependency-cruiser.config.js stryker.preset.js .dependency-cruiser.cjs",
     "typecheck": "tsc --noEmit && effect-tsgo diagnostics --project tsconfig.json --format text --strict",
     "test": "bun test --randomize"
   },
@@ -70,15 +76,14 @@
       "bun run lint",
       "bun run typecheck",
       "bun run test",
-      "./node_modules/.bin/commitlint",
-      "bun .checks/scripts/commit-identity.ts",
-      "bun .checks/scripts/comment-gate.ts"
+      "./node_modules/.bin/commitlint"
     ]
   },
   "peerDependencies": {
     "@swc/core": "1.16.2",
     "dependency-cruiser": "18.4.0",
     "@effect/tsgo": "0.45.0",
+    "effect": "4.0.0-rc.115",
     "oxlint": "1.83.0",
     "oxlint-tsgolint": "7.0.2002"
   },
@@ -95,6 +100,8 @@
   },
   "dependencies": {
     "@commitlint/cli": "21.2.3",
-    "@commitlint/config-conventional": "21.2.3"
+    "@commitlint/config-conventional": "21.2.3",
+    "@effect/platform-bun": "4.0.0-rc.115",
+    "@effect/platform-node-shared": "4.0.0-rc.115"
   }
 }

package/scripts/backtest.ts

@@ -1,5 +1,8 @@
 #!/usr/bin/env bun
+import { Console, Effect, Option } from "effect";
 import { comments, refused, SYNTAXES } from "./comments.ts";
+import { git } from "./git.ts";
+import { runMain, Usage } from "./main.ts";
 
 type Landed = {
   readonly sha: string;
@@ -13,37 +16,21 @@ const USAGE = "usage: backtest.ts [commit-count]";
 
 const EXCLUDED = ["generated/", "vendor/", "repos/", "node_modules/", "dist/"];
 
-function die(message: string): never {
-  console.error(message);
-  process.exit(2);
-}
-
-function git(...args: readonly string[]): string {
-  const result = Bun.spawnSync(["git", ...args], { stdout: "pipe", stderr: "pipe" });
-  if (!result.success) {
-    die(`backtest: git ${args.join(" ")}: ${result.stderr.toString().trim()}`);
-  }
-  return result.stdout.toString();
-}
-
 function readable(path: string): boolean {
   if (EXCLUDED.some((prefix) => path.startsWith(prefix))) return false;
   const extension = path.slice(path.lastIndexOf(".") + 1);
   return extension in SYNTAXES;
 }
 
-async function at(sha: string, path: string): Promise<string | undefined> {
-  const result = Bun.spawnSync(["git", "show", `${sha}:${path}`], { stdout: "pipe", stderr: "pipe" });
-  return result.success ? result.stdout.toString() : undefined;
-}
+const at = (sha: string, path: string) => git(["show", `${sha}:${path}`]).pipe(Effect.option);
 
 function withoutLine(refusal: string): string {
   return refusal.replace(/^(\S+?):\d+ /, "$1 ");
 }
 
-export async function backtest(count: string): Promise<string> {
+export const backtest = Effect.fn("backtest")(function* (count: string) {
   const lines: string[] = [];
-  const commits = git("log", "--first-parent", "--format=%H%x09%P%x09%s", "-n", count)
+  const commits = (yield* git(["log", "--first-parent", "--format=%H%x09%P%x09%s", "-n", count]))
     .trim()
     .split("\n")
     .map((row) => {
@@ -55,13 +42,13 @@ export async function backtest(count: string): Promise<string> {
   const landed: Landed[] = [];
 
   for (const { sha, parent, subject } of commits) {
-    const changed = git("diff", "--name-only", "--diff-filter=d", parent, sha)
+    const changed = (yield* git(["diff", "--name-only", "--diff-filter=d", parent, sha]))
       .trim()
       .split("\n")
       .filter((path) => path !== "" && readable(path));
     if (changed.length === 0) continue;
 
-    const numstat = git("diff", "--numstat", parent, sha, "--", ...changed).trim();
+    const numstat = (yield* git(["diff", "--numstat", parent, sha, "--", ...changed])).trim();
     const added =
       numstat === ""
         ? 0
@@ -71,17 +58,17 @@ export async function backtest(count: string): Promise<string> {
     const refusals: string[] = [];
 
     for (const path of changed) {
-      const after = await at(sha, path);
-      if (after === undefined) continue;
-      const before = (await at(parent, path)) ?? "";
+      const after = yield* at(sha, path);
+      if (Option.isNone(after)) continue;
+      const before = Option.getOrElse(yield* at(parent, path), () => "");
 
-      const wasRefused = new Set(refused(path, before).map(withoutLine));
-      for (const refusal of refused(path, after)) {
+      const wasRefused = new Set((yield* refused(path, before)).map(withoutLine));
+      for (const refusal of yield* refused(path, after.value)) {
         if (!wasRefused.has(withoutLine(refusal))) refusals.push(refusal);
       }
 
-      const wasComment = new Set(comments(path, before).map((one) => one.text));
-      for (const one of comments(path, after)) {
+      const wasComment = new Set((yield* comments(path, before)).map((one) => one.text));
+      for (const one of yield* comments(path, after.value)) {
         if (!wasComment.has(one.text)) commentLines += one.text.split("\n").length;
       }
     }
@@ -108,10 +95,13 @@ export async function backtest(count: string): Promise<string> {
     for (const refusal of one.refusals) lines.push(`    ${refusal}`);
   }
   return lines.join("\n");
-}
+});
 
-if (import.meta.main) {
+const main = Effect.gen(function* () {
   const [count = "60", ...extra] = process.argv.slice(2);
-  if (extra.length > 0) die(USAGE);
-  console.log(await backtest(count));
-}
+  if (extra.length > 0) return yield* new Usage({ message: USAGE });
+  yield* Console.log(yield* backtest(count));
+  return true;
+});
+
+if (import.meta.main) runMain("backtest", main);