@avi2dg/checks 0.22.0 → 0.23.0

package/CHANGELOG.md

@@ -2,6 +2,14 @@
 
 Every release of `@avi2dg/checks`, newest first, written by the release from its conventional commits.
 
+## 0.23.0
+
+Released 2026-09-26.
+
+### Breaking changes
+
+- move cognitive-complexity into its own readability oxlint plugin [#74](https://github.com/avi2d/checks/pull/74)
+
 ## 0.22.0
 
 Released 2026-09-26.

package/CONTRIBUTING.md

@@ -26,8 +26,8 @@ Each generated file is committed, and lint, the suite or CI's diff after the bui
 
 To regenerate after an edit:
 
-1. After editing `effect-channel/` or the templates in `scripts/doc-templates.ts`, run `bun run build`.
-   It rewrites `dist/index.js` and `templates/`.
+1. After editing `effect-channel/`, `readability/` or the templates in `scripts/doc-templates.ts`, run `bun run build`.
+   It rewrites `dist/` and `templates/`.
 1. After editing anything a generated block names as its source in its opening marker, run `bun run build`, which rewrites every generated block.
 1. Commit what the command rewrote in the same commit as the edit.
 
@@ -68,8 +68,9 @@ To place a change:
    | Path | What it holds |
    | --- | --- |
    | `scripts/` | every bin, and the modules they share |
-   | `effect-channel/` | the oxlint plugin with the Effect error-channel and cognitive complexity rules |
-   | `dist/` | the committed oxlint plugin bundle |
+   | `effect-channel/` | the oxlint plugin with the Effect error-channel rules |
+   | `readability/` | the oxlint plugin with the readability rules |
+   | `dist/` | the committed oxlint plugin bundles |
    | `presets/` | the Effect rule blocks consumers copy into native configs |
    | `templates/` | one template per kind of doc file, which `bun run build` renders |
    | `CHANGELOG.md` | every release, which `bun run build` writes from the conventional commits |
@@ -83,7 +84,7 @@ To place a change:
    A new bin gets its page under `docs/gates/`, and the suite fails until it has one.
 
 This repository holds itself to the kit, with two exceptions of its own.
-Its `.dependency-cruiser.cjs` redeclares `no-orphans` with the plugin entry added to its `pathNot`.
+Its `.dependency-cruiser.cjs` redeclares `no-orphans` with each plugin entry added to its `pathNot`.
 Its `.oxlintrc.json` lifts `effect-channel/no-throw` from `scripts/comment-matchers.ts`, whose synchronous `refused()` a host loads without `node_modules`.
 
 ## Related topics

package/README.md

@@ -164,7 +164,7 @@ Every path is relative to the installed package, `node_modules/@avi2dg/checks/`.
 | `oxlintrc.json` | the oxlint base config `.oxlintrc.json` extends |
 | `stryker.preset.js` | the Stryker mutation-testing preset |
 | `tsconfig.effect.json` | the tsconfig fragment with the Effect language-service block |
-| `dist/` | the compiled oxlint plugin with the Effect error-channel and cognitive complexity rules |
+| `dist/` | the compiled oxlint plugins, one per purpose |
 
 <!-- end generated shipped -->
 

package/dist/effect-channel/index.js

@@ -0,0 +1,122 @@
+// effect-channel/no-error-channel-escape.ts
+var EFFECT_SOURCES = new Set(["effect", "effect/Effect"]);
+var INSTEAD = {
+  drops: "it drops the failure and the success together, so no caller can tell one from the other. Handle the error by tag, or keep it as a value with Effect.result or Effect.exit",
+  swallows: "a Cause is the typed error plus defects plus interruption, so this swallows the bugs and the cancellations along with it. Catch the errors you named, with Effect.catchTag or Effect.catchTags",
+  blind: "the handler cannot see what it is recovering from, so every error in the channel collapses into one fallback. Name the errors with Effect.catchTag, or take the error and use it"
+};
+var REFUSED = new Map([
+  ["ignore", INSTEAD.drops],
+  ["ignoreCause", INSTEAD.drops],
+  ["catchCause", INSTEAD.swallows],
+  ["catchCauseIf", INSTEAD.swallows],
+  ["catchCauseFilter", INSTEAD.swallows]
+]);
+var blindToTheError = (handler) => {
+  if (!handler)
+    return false;
+  if (handler.type !== "ArrowFunctionExpression" && handler.type !== "FunctionExpression")
+    return false;
+  return handler.params.every((param) => param.type === "Identifier" && /^_+$/.test(param.name));
+};
+var rule = {
+  meta: {
+    type: "problem",
+    docs: { description: "Disallow the combinators that erase Effect's error channel" }
+  },
+  create(context) {
+    const effect = new Set;
+    const named = (node) => {
+      if (!node || node.type !== "MemberExpression" || node.computed)
+        return null;
+      if (node.object.type !== "Identifier" || !effect.has(node.object.name))
+        return null;
+      return node.property.type === "Identifier" ? node.property.name : null;
+    };
+    const refuse = (node, combinator, instead) => {
+      context.report({ node, message: `Effect.${combinator} erases the error channel: ${instead}` });
+    };
+    return {
+      ImportDeclaration(node) {
+        if (!EFFECT_SOURCES.has(node.source.value))
+          return;
+        const module = node.source.value === "effect/Effect";
+        for (const specifier of node.specifiers) {
+          if (specifier.type === "ImportSpecifier") {
+            if (specifier.imported.type === "Identifier" && specifier.imported.name === "Effect")
+              effect.add(specifier.local.name);
+          } else if (module)
+            effect.add(specifier.local.name);
+        }
+      },
+      MemberExpression(node) {
+        const combinator = named(node);
+        if (combinator === null)
+          return;
+        const instead = REFUSED.get(combinator);
+        if (instead !== undefined)
+          refuse(node, combinator, instead);
+      },
+      CallExpression(node) {
+        if (named(node.callee) !== "catch")
+          return;
+        if (!blindToTheError(node.arguments[node.arguments.length - 1]))
+          return;
+        refuse(node, "catch", INSTEAD.blind);
+      }
+    };
+  }
+};
+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,
+    "no-throw": no_throw_default,
+    "no-try-catch": no_try_catch_default
+  }
+};
+var effect_channel_default = plugin;
+export {
+  effect_channel_default as default
+};

package/dist/{index.js → readability/index.js}

@@ -1,4 +1,4 @@
-// effect-channel/cognitive-nodes.ts
+// readability/cognitive-nodes.ts
 var CONTROL_TYPES = ["IfStatement", "ConditionalExpression", "SwitchStatement", "SwitchCase", "TryStatement", "CatchClause"];
 var LOOP_TYPES = ["ForStatement", "ForInStatement", "ForOfStatement", "WhileStatement", "DoWhileStatement", "LabeledStatement"];
 var CALL_TYPES = ["LogicalExpression", "BreakStatement", "ContinueStatement", "CallExpression", "NewExpression", "ImportExpression"];
@@ -7,7 +7,7 @@ var PLAIN_A_TYPES = ["BlockStatement", "ExpressionStatement", "ReturnStatement",
 var PLAIN_B_TYPES = ["ClassDeclaration", "ClassExpression", "ClassBody", "MethodDefinition", "TSAbstractMethodDefinition", "PropertyDefinition", "TSAbstractPropertyDefinition", "AccessorProperty", "TSAbstractAccessorProperty", "ObjectExpression", "ArrayExpression"];
 var PLAIN_C_TYPES = ["AwaitExpression", "UnaryExpression", "UpdateExpression", "SpreadElement", "YieldExpression", "BinaryExpression", "AssignmentExpression", "TSAsExpression", "TSSatisfiesExpression", "TSTypeAssertion", "TSNonNullExpression", "ChainExpression", "ParenthesizedExpression", "Decorator", "TSInstantiationExpression", "MemberExpression", "JSXMemberExpression", "TemplateLiteral", "TaggedTemplateExpression", "SequenceExpression", "JSXElement", "JSXFragment", "JSXOpeningElement", "JSXAttribute", "JSXExpressionContainer", "JSXSpreadChild", "JSXSpreadAttribute"];
 
-// effect-channel/cognitive-plain.ts
+// readability/cognitive-plain.ts
 function isControl(node) {
   return CONTROL_TYPES.includes(node.type);
 }
@@ -142,7 +142,7 @@ function plainChildrenC(node) {
   }
 }
 
-// effect-channel/cognitive.ts
+// readability/cognitive.ts
 function unreachable2(_value) {}
 function scoreList(state, nodes, nesting, parent) {
   for (const node of nodes) {
@@ -334,7 +334,7 @@ function cognitiveComplexity(root, names) {
   return state.recursive ? state.total + 1 : state.total;
 }
 
-// effect-channel/cognitive-complexity.ts
+// readability/cognitive-complexity.ts
 var DEFAULT_MAX = 15;
 function maxOf(options) {
   const [first] = options;
@@ -416,126 +416,14 @@ var rule = {
 };
 var cognitive_complexity_default = rule;
 
-// effect-channel/no-error-channel-escape.ts
-var EFFECT_SOURCES = new Set(["effect", "effect/Effect"]);
-var INSTEAD = {
-  drops: "it drops the failure and the success together, so no caller can tell one from the other. Handle the error by tag, or keep it as a value with Effect.result or Effect.exit",
-  swallows: "a Cause is the typed error plus defects plus interruption, so this swallows the bugs and the cancellations along with it. Catch the errors you named, with Effect.catchTag or Effect.catchTags",
-  blind: "the handler cannot see what it is recovering from, so every error in the channel collapses into one fallback. Name the errors with Effect.catchTag, or take the error and use it"
-};
-var REFUSED = new Map([
-  ["ignore", INSTEAD.drops],
-  ["ignoreCause", INSTEAD.drops],
-  ["catchCause", INSTEAD.swallows],
-  ["catchCauseIf", INSTEAD.swallows],
-  ["catchCauseFilter", INSTEAD.swallows]
-]);
-var blindToTheError = (handler) => {
-  if (!handler)
-    return false;
-  if (handler.type !== "ArrowFunctionExpression" && handler.type !== "FunctionExpression")
-    return false;
-  return handler.params.every((param) => param.type === "Identifier" && /^_+$/.test(param.name));
-};
-var rule2 = {
-  meta: {
-    type: "problem",
-    docs: { description: "Disallow the combinators that erase Effect's error channel" }
-  },
-  create(context) {
-    const effect = new Set;
-    const named = (node) => {
-      if (!node || node.type !== "MemberExpression" || node.computed)
-        return null;
-      if (node.object.type !== "Identifier" || !effect.has(node.object.name))
-        return null;
-      return node.property.type === "Identifier" ? node.property.name : null;
-    };
-    const refuse = (node, combinator, instead) => {
-      context.report({ node, message: `Effect.${combinator} erases the error channel: ${instead}` });
-    };
-    return {
-      ImportDeclaration(node) {
-        if (!EFFECT_SOURCES.has(node.source.value))
-          return;
-        const module = node.source.value === "effect/Effect";
-        for (const specifier of node.specifiers) {
-          if (specifier.type === "ImportSpecifier") {
-            if (specifier.imported.type === "Identifier" && specifier.imported.name === "Effect")
-              effect.add(specifier.local.name);
-          } else if (module)
-            effect.add(specifier.local.name);
-        }
-      },
-      MemberExpression(node) {
-        const combinator = named(node);
-        if (combinator === null)
-          return;
-        const instead = REFUSED.get(combinator);
-        if (instead !== undefined)
-          refuse(node, combinator, instead);
-      },
-      CallExpression(node) {
-        if (named(node.callee) !== "catch")
-          return;
-        if (!blindToTheError(node.arguments[node.arguments.length - 1]))
-          return;
-        refuse(node, "catch", INSTEAD.blind);
-      }
-    };
-  }
-};
-var no_error_channel_escape_default = rule2;
-
-// effect-channel/no-throw.ts
-var rule3 = {
-  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 = rule3;
-
-// effect-channel/no-try-catch.ts
-var rule4 = {
-  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 = rule4;
-
-// effect-channel/index.ts
+// readability/index.ts
 var plugin = {
-  meta: { name: "effect-channel" },
+  meta: { name: "readability" },
   rules: {
-    "no-error-channel-escape": no_error_channel_escape_default,
-    "no-throw": no_throw_default,
-    "no-try-catch": no_try_catch_default,
     "cognitive-complexity": cognitive_complexity_default
   }
 };
-var effect_channel_default = plugin;
+var readability_default = plugin;
 export {
-  effect_channel_default as default
+  readability_default as default
 };

package/docs/configs/native-settings.md

@@ -57,12 +57,12 @@ The kit's own `.oxlintrc.json` sets these limits for each size override, and a r
 
 <!-- generated size-limits: bun run build writes it from .oxlintrc.json, SIZE_RULES in scripts/size-rules.ts and scripts/doc-blocks.ts -->
 
-| Limits | oxlint rule | `effect-channel/**/*.ts`, `scripts/**/*.ts` | `tests/**/*.ts` |
+| Limits | oxlint rule | `effect-channel/**/*.ts`, `readability/**/*.ts`, `scripts/**/*.ts` | `tests/**/*.ts` |
 | --- | --- | --- | --- |
 | The most lines a file may hold, blank and comment lines counted | `max-lines` | 400 | 600 |
 | The most lines a function may span, blank and comment lines counted | `max-lines-per-function` | 100 | off |
 | The most statements a function may hold | `max-statements` | 30 | 50 |
-| The highest cognitive complexity a function may reach, a switch counted once | `effect-channel/cognitive-complexity` | 15 | 15 |
+| The highest cognitive complexity a function may reach, a switch counted once | `readability/cognitive-complexity` | 15 | 15 |
 | The deepest a block may nest inside a function | `max-depth` | 4 | 4 |
 
 <!-- end generated size-limits -->

package/docs/design.md

@@ -12,7 +12,7 @@ Each entry below is a choice in the kit's shape and the constraint that forced i
 - `files` in package.json is the published surface: `tests/`, `AGENTS.md` and the `.ts` plugin source never reach an install.
   npm adds `package.json`, `README` and `LICENSE` to the tarball whatever `files` says.
   `bun pm pack` builds the same tarball the registry serves, which is what the packed-tarball consumer e2e test installs.
-- The plugin ships compiled as `dist/index.js`, built with `bun build effect-channel/index.ts --outdir dist --target node --format esm`.
+- Each plugin ships compiled under `dist/`, built with `bun build <name>/index.ts --outdir dist/<name> --target node --format esm`.
   Node refuses to type-strip a `.ts` plugin under `node_modules`, so the `.ts` source would fail to load from an installed package.
 - The size rules are plain oxlint rules at `error` in `.oxlintrc.json`, and `bun run lint` enforces them on the whole tree.
   A repository records its existing violations with `oxlint --suppress-all`, and `checks-suppressions-ratchet` refuses any count that rises.
@@ -51,7 +51,7 @@ Each entry below is a choice in the kit's shape and the constraint that forced i
   `@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.
+  The `.ts` checks keep a `bun` shebang, which needs no build step and no `dist/` entry, unlike the oxlint plugins 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-lint` determines applicable gates from tracked files instead of accepting a repository selection.

package/docs/gates/checks-repetition.md

@@ -16,6 +16,7 @@ A file that repeats lines without a rise is advisory.
 ## What it reads
 
 jscpd reads the head's `.jscpd.json` at both ends, so its `path` and `ignore` globs select the files to measure.
+A `path` entry the base revision lacks reads as empty there, so a newly measured folder never fails the scan.
 
 ```json
 { "path": ["src"], "format": ["typescript"], "ignore": ["**/*.d.ts"] }

package/oxlintrc.json

@@ -1,6 +1,6 @@
 {
   "plugins": ["typescript", "oxc", "eslint", "import"],
-  "jsPlugins": ["./dist/index.js"],
+  "jsPlugins": ["./dist/effect-channel/index.js", "./dist/readability/index.js"],
   "categories": { "correctness": "error", "suspicious": "error" },
   "rules": {
     "effect-channel/no-error-channel-escape": "error",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@avi2dg/checks",
-  "version": "0.22.0",
+  "version": "0.23.0",
   "description": "Deterministic checks shared across the captain's TypeScript repos",
   "license": "MIT",
   "repository": {
@@ -58,7 +58,8 @@
     "oxlintrc.json",
     "stryker.preset.js",
     "tsconfig.effect.json",
-    "dist/index.js"
+    "dist/effect-channel/index.js",
+    "dist/readability/index.js"
   ],
   "exports": {
     "./bunfig.toml": "./bunfig.toml",
@@ -98,7 +99,8 @@
     "./oxlintrc.json": "./oxlintrc.json",
     "./stryker.preset.js": "./stryker.preset.js",
     "./tsconfig.effect.json": "./tsconfig.effect.json",
-    "./dist/index.js": "./dist/index.js"
+    "./dist/effect-channel/index.js": "./dist/effect-channel/index.js",
+    "./dist/readability/index.js": "./dist/readability/index.js"
   },
   "bin": {
     "checks-lint": "scripts/lint.ts",
@@ -120,7 +122,7 @@
   },
   "scripts": {
     "prepare": "bun scripts/vendor.ts --library effect --package effect --repository https://github.com/Effect-TS/effect.git --tag 'effect@{version}' --path packages/effect/package.json",
-    "build": "bun build effect-channel/index.ts --outdir dist --target node --format esm && bun scripts/doc-templates-write.ts && bun scripts/changelog-write.ts && bun scripts/doc-blocks-write.ts",
+    "build": "bun build effect-channel/index.ts --outdir dist/effect-channel --target node --format esm && bun build readability/index.ts --outdir dist/readability --target node --format esm && bun scripts/doc-templates-write.ts && bun scripts/changelog-write.ts && bun scripts/doc-blocks-write.ts",
     "lint": "oxlint --type-aware && bun scripts/lint.ts && depcruise --config .dependency-cruiser.cjs .",
     "typecheck": "tsc --noEmit && effect-tsgo diagnostics --project tsconfig.json --format text --strict",
     "test": "bun scripts/test.ts"

package/scripts/repetition.ts

@@ -48,6 +48,10 @@ const decodeReport = Schema.decodeUnknownEffect(
   ),
 );
 
+const decodeConfigPaths = Schema.decodeUnknownEffect(
+  Schema.fromJsonString(Schema.Struct({ path: Schema.optional(Schema.Array(Schema.String)) })),
+);
+
 type Scan = { readonly sources: number; readonly clones: readonly Clone[] };
 
 function fragmentOf(file: (name: string) => string, { name, start, end }: typeof Location.Type): Fragment {
@@ -66,8 +70,9 @@ export function repeatedLines(clones: readonly Clone[]): ReadonlyMap<string, num
 
 // jscpd reads files from disk, and the working tree need not hold the revision: a merge checkout or an uncommitted edit.
 // Both ends scan under the head's config, so a changed file set never reads as a change in repetition.
+// jscpd refuses a missing path, so a path in `emptied` the revision lacks is created empty.
 const scan = Effect.fn("scan")(
-  function* (root: string, rev: string, config: string) {
+  function* (root: string, rev: string, config: string, emptied: readonly string[]) {
     const files = yield* pathsAt(rev, [], root);
     if (files.length === 0) return { sources: 0, clones: [] } satisfies Scan;
     const fs = yield* FileSystem.FileSystem;
@@ -75,6 +80,9 @@ const scan = Effect.fn("scan")(
     const scratch = yield* fs.makeTempDirectoryScoped({ prefix: "checks-repetition-" });
     const tree = yield* checkoutFiles(rev, files, scratch, root);
     yield* fs.writeFileString(path.join(tree, CONFIG), config);
+    for (const absent of emptied.map((entry) => path.join(tree, entry))) {
+      if (!(yield* fs.exists(absent))) yield* fs.makeDirectory(absent, { recursive: true });
+    }
     const output = path.join(scratch, "report");
     const flags = ["--silent", "--no-tips", "--no-gitignore", "--absolute", "--reporters", "json", "--output", output];
     const thresholds = ["--min-tokens", `${MIN_TOKENS}`, "--min-lines", `${MIN_LINES}`];
@@ -137,8 +145,11 @@ const runHold = Effect.fn("runHold")(function* (root: string, config: string, ba
   const formerPath = new Map(
     (yield* changedPaths(base, head, [], root)).flatMap((change) => (change.kind === "renamed" ? [[change.path, change.from]] : [])),
   );
-  const before = repeatedLines((yield* scan(root, base, config)).clones);
-  const { sources, clones } = yield* scan(root, head, config);
+  const { path: configPaths = [] } = yield* decodeConfigPaths(config).pipe(
+    Effect.mapError((cause) => new JscpdUnreadable({ message: `cannot read ${CONFIG}: ${cause.message}` })),
+  );
+  const before = repeatedLines((yield* scan(root, base, config, configPaths)).clones);
+  const { sources, clones } = yield* scan(root, head, config, []);
   const after = repeatedLines(clones);
   const rises = risesOf([...after.keys()], before, after, formerPath, clones);
   return heldOf(sources, rises, after) satisfies Held;