@avi2dg/checks 0.4.0 → 0.6.0

package/README.md

@@ -5,9 +5,10 @@ Deterministic checks shared across my TypeScript repos. One package,
 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 Stryker mutation-testing preset with its
-no-regression comparator, the CI-wiring check, and the Effect
-error-channel plugin compiled to JavaScript.
+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.
 
 Published as `@avi2dg/checks` on the public npm registry.
 
@@ -80,6 +81,48 @@ export default {
 The registry version is pinned by the consumer's lockfile; bump
 `@avi2dg/checks` to adopt a new release.
 
+## Effect rules
+
+The base config loads the `effect-channel` plugin and turns on
+`effect-channel/no-error-channel-escape`, which refuses `Effect.ignore`,
+`Effect.ignoreCause`, the `Effect.catchCause` family, and an
+`Effect.catch` whose handler takes no error or names it `_`.
+
+Two more rules ship off, because a repository writes only some of its
+paths in Effect: code a host loads without `node_modules`, such as a
+hook bundle or this oxlint plugin, cannot import it.
+
+- `effect-channel/no-throw` refuses a `throw` statement.
+- `effect-channel/no-try-catch` refuses a `try` statement with a
+  `catch` clause. `try`/`finally` stays allowed.
+
+Each refusal says what to write instead: a `Schema.TaggedError` failed
+through `Effect.fail`, a throwing call wrapped in `Effect.try` or
+`Effect.tryPromise`, and recovery by tag with `Effect.catchTag`.
+
+A repository turns them on for the paths it writes in Effect through an
+`overrides` entry in its root `.oxlintrc.json`:
+
+```json
+{
+  "extends": ["./node_modules/@avi2dg/checks/oxlintrc.json"],
+  "plugins": ["typescript", "oxc", "eslint", "import"],
+  "overrides": [
+    {
+      "files": ["src/**"],
+      "rules": {
+        "effect-channel/no-throw": "error",
+        "effect-channel/no-try-catch": "error"
+      }
+    }
+  ]
+}
+```
+
+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.
+
 ## Test layout
 
 `checks-test-layout` fails unless the repo holds this shape, and names the
@@ -305,6 +348,58 @@ jobs:
           HEAD_SHA: ${{ github.event.pull_request.head.sha }}
 ```
 
+## Suppressions ratchet
+
+`scripts/suppressions-ratchet.ts` holds oxlint's bulk-suppression
+baseline, `oxlint-suppressions.json`, to counts that only fall. oxlint
+accepts whatever `oxlint --suppress-all` writes, so raising a count to
+let a new site through passes the lint. The ratchet reads the file at a
+base and a head and fails naming each file and rule whose count rose or
+that appeared:
+
+```sh
+bun run checks-suppressions-ratchet <base-ref> <head-ref>
+bun run checks-suppressions-ratchet <ref>
+```
+
+With one argument it compares that commit with its parent, and exits 2
+when the parent is not in the clone. With two it reads the base where
+the head branched off, at their merge-base, so a count the base branch
+lowered since does not read as a rise at the head. A count that fell and
+an entry that went both pass. A commit without the file counts as empty,
+so the commit that first adds a baseline fails with every entry
+appearing. The file is read from the directory the command runs in,
+which is where oxlint writes it. It exits 2 when a ref does not resolve
+or the file is not oxlint's count per rule per file:
+
+```
+suppressions-ratchet: 2 count(s) in oxlint-suppressions.json rose or appeared; fix the site instead of suppressing it:
+  src/added.ts typescript/no-unsafe-type-assertion appeared with 1
+  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 }}
+```
+
 ## CI wiring
 
 `checks-ci-wiring` fails when a command the repository's CI must run no
@@ -527,7 +622,7 @@ a tag off `main` and reruns the build, `dist/` check, lint, typecheck
 and tests before it publishes:
 
 ```sh
-git tag v0.4.0 && git push origin v0.4.0
+git tag v0.6.0 && git push origin v0.6.0
 ```
 
 The `release` workflow publishes the tagged version through npm

package/dist/index.js

@@ -69,10 +69,52 @@ var rule = {
 };
 var no_error_channel_escape_default = rule;
 
+// effect-channel/no-throw.ts
+var rule2 = {
+  meta: {
+    type: "problem",
+    docs: { description: "Disallow throw, which fails outside Effect's error channel" }
+  },
+  create(context) {
+    return {
+      ThrowStatement(node) {
+        context.report({
+          node,
+          message: "throw escapes the error channel: no type records the failure, so no caller has to answer for it. Define the failure with Schema.TaggedError and fail with it through Effect.fail, so it stays in E for Effect.catchTag to handle"
+        });
+      }
+    };
+  }
+};
+var no_throw_default = rule2;
+
+// effect-channel/no-try-catch.ts
+var rule3 = {
+  meta: {
+    type: "problem",
+    docs: { description: "Disallow a try statement with a catch clause, which recovers outside Effect's error channel" }
+  },
+  create(context) {
+    return {
+      CatchClause(node) {
+        context.report({
+          node,
+          message: "catch recovers outside the error channel: it takes whatever was thrown as unknown, bugs included. Wrap the throwing call in Effect.try or Effect.tryPromise, whose catch maps the cause to a Schema.TaggedError, and recover by tag with Effect.catchTag"
+        });
+      }
+    };
+  }
+};
+var no_try_catch_default = rule3;
+
 // effect-channel/index.ts
 var plugin = {
   meta: { name: "effect-channel" },
-  rules: { "no-error-channel-escape": no_error_channel_escape_default }
+  rules: {
+    "no-error-channel-escape": no_error_channel_escape_default,
+    "no-throw": no_throw_default,
+    "no-try-catch": no_try_catch_default
+  }
 };
 var effect_channel_default = plugin;
 export {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@avi2dg/checks",
-  "version": "0.4.0",
+  "version": "0.6.0",
   "description": "Deterministic checks shared across the captain's TypeScript repos",
   "license": "MIT",
   "repository": {
@@ -22,6 +22,7 @@
     "scripts/ci-wiring.ts",
     "scripts/comments.ts",
     "scripts/comment-gate.ts",
+    "scripts/suppressions-ratchet.ts",
     "scripts/backtest.ts",
     "oxlintrc.json",
     "stryker.preset.js",
@@ -39,6 +40,7 @@
     "./scripts/ci-wiring.ts": "./scripts/ci-wiring.ts",
     "./scripts/comments.ts": "./scripts/comments.ts",
     "./scripts/comment-gate.ts": "./scripts/comment-gate.ts",
+    "./scripts/suppressions-ratchet.ts": "./scripts/suppressions-ratchet.ts",
     "./scripts/backtest.ts": "./scripts/backtest.ts",
     "./oxlintrc.json": "./oxlintrc.json",
     "./stryker.preset.js": "./stryker.preset.js",
@@ -52,6 +54,7 @@
     "checks-mutation-compare": "scripts/mutation-compare.ts",
     "checks-ci-wiring": "scripts/ci-wiring.ts",
     "checks-comment-gate": "scripts/comment-gate.ts",
+    "checks-suppressions-ratchet": "scripts/suppressions-ratchet.ts",
     "checks-backtest": "scripts/backtest.ts"
   },
   "scripts": {

package/scripts/suppressions-ratchet.ts

@@ -0,0 +1,142 @@
+#!/usr/bin/env bun
+export const SUPPRESSIONS = "oxlint-suppressions.json";
+
+export type Suppressions = ReadonlyMap<string, ReadonlyMap<string, number>>;
+
+export type Rise =
+  | { readonly kind: "rose"; readonly file: string; readonly rule: string; readonly base: number; readonly head: number }
+  | { readonly kind: "appeared"; readonly file: string; readonly rule: string; readonly head: number };
+
+export type Ratchet = {
+  readonly counted: number;
+  readonly lowered: number;
+  readonly rises: readonly Rise[];
+};
+
+export class SuppressionsError extends Error {}
+
+const USAGE = "usage: suppressions-ratchet.ts <ref> | <base-ref> <head-ref>";
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+function isCount(value: unknown): value is number {
+  return typeof value === "number" && Number.isInteger(value) && value >= 0;
+}
+
+export function parseSuppressions(text: string, where: string): Suppressions {
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(text);
+  } catch {
+    throw new SuppressionsError(`suppressions-ratchet: ${where} is not valid JSON`);
+  }
+  if (!isRecord(parsed)) {
+    throw new SuppressionsError(`suppressions-ratchet: ${where} is not an object of files`);
+  }
+  const files = new Map<string, ReadonlyMap<string, number>>();
+  for (const [file, rules] of Object.entries(parsed)) {
+    if (!isRecord(rules)) {
+      throw new SuppressionsError(`suppressions-ratchet: ${where} holds ${file} without an object of rules`);
+    }
+    const counts = new Map<string, number>();
+    for (const [rule, entry] of Object.entries(rules)) {
+      if (!isRecord(entry) || !isCount(entry["count"])) {
+        throw new SuppressionsError(`suppressions-ratchet: ${where} holds ${file} ${rule} without a whole count`);
+      }
+      counts.set(rule, entry["count"]);
+    }
+    files.set(file, counts);
+  }
+  return files;
+}
+
+export function compareSuppressions(base: Suppressions, head: Suppressions): Ratchet {
+  const rises: Rise[] = [];
+  let counted = 0;
+  for (const [file, rules] of head) {
+    for (const [rule, count] of rules) {
+      counted += 1;
+      const before = base.get(file)?.get(rule);
+      if (before === undefined) {
+        if (count > 0) rises.push({ kind: "appeared", file, rule, head: count });
+      } else if (count > before) {
+        rises.push({ kind: "rose", file, rule, base: before, head: count });
+      }
+    }
+  }
+  let lowered = 0;
+  for (const [file, rules] of base) {
+    for (const [rule, count] of rules) {
+      if ((head.get(file)?.get(rule) ?? 0) < count) lowered += 1;
+    }
+  }
+  rises.sort((a, b) => a.file.localeCompare(b.file) || a.rule.localeCompare(b.rule));
+  return { counted, lowered, rises };
+}
+
+function describeRise(rise: Rise): string {
+  const change = rise.kind === "rose" ? `rose from ${rise.base} to ${rise.head}` : `appeared with ${rise.head}`;
+  return `${rise.file} ${rise.rule} ${change}`;
+}
+
+export function report({ counted, lowered, rises }: Ratchet): string {
+  if (rises.length === 0) {
+    return `suppressions-ratchet: no count in ${SUPPRESSIONS} rose or appeared (${counted} at the head, ${lowered} lowered)`;
+  }
+  return [
+    `suppressions-ratchet: ${rises.length} count(s) in ${SUPPRESSIONS} rose or appeared; fix the site instead of suppressing it:`,
+    ...rises.map((rise) => `  ${describeRise(rise)}`),
+  ].join("\n");
+}
+
+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(`suppressions-ratchet: git ${args.join(" ")}: ${result.stderr.toString().trim()}`);
+  }
+  return result.stdout.toString();
+}
+
+function commitOf(rev: string): string {
+  return git("rev-parse", "--verify", `${rev}^{commit}`).trim();
+}
+
+function mergeBase(base: string, head: string): string {
+  const result = Bun.spawnSync(["git", "merge-base", base, head], { stdout: "pipe", stderr: "pipe" });
+  if (!result.success) die(`suppressions-ratchet: ${base} and ${head} share no commit`);
+  return result.stdout.toString().trim();
+}
+
+function suppressionsAt(commit: string): Suppressions {
+  const blob = git("ls-tree", "--object-only", commit, "--", SUPPRESSIONS).trim();
+  if (blob === "") return new Map();
+  try {
+    return parseSuppressions(git("cat-file", "blob", blob), `${SUPPRESSIONS} at ${commit}`);
+  } catch (error) {
+    return die(error instanceof SuppressionsError ? error.message : `suppressions-ratchet: ${String(error)}`);
+  }
+}
+
+export function runRange(base: string, head: string): Ratchet {
+  const headCommit = commitOf(head);
+  // At the base tip, a count the base branch lowered after the head branched off would read as a rise at the head.
+  const branchPoint = mergeBase(commitOf(base), headCommit);
+  return compareSuppressions(suppressionsAt(branchPoint), suppressionsAt(headCommit));
+}
+
+if (import.meta.main) {
+  const [first, second, ...extra] = process.argv.slice(2);
+  if (first === undefined || extra.length > 0) die(USAGE);
+
+  const ratchet = second !== undefined ? runRange(first, second) : runRange(`${first}^`, first);
+
+  console.log(report(ratchet));
+  process.exit(ratchet.rises.length === 0 ? 0 : 1);
+}