@avi2dg/checks 0.16.0 → 0.17.0

package/CHANGELOG.md

@@ -2,6 +2,16 @@
 
 Every release of `@avi2dg/checks`, newest first, written by the release from its conventional commits.
 
+## 0.17.0
+
+Released 2026-09-25.
+
+### Features
+
+- **effect-channel:** add a cognitive complexity rule and make it the size budget's (#50)
+- **scripts:** export the refused directive names from comment-matchers (#49)
+- refuse undeclared package imports and deprecated symbol use (#48)
+
 ## 0.16.0
 
 Released 2026-09-25.

package/CONTRIBUTING.md

@@ -65,7 +65,7 @@ To place a change:
    | Path | What it holds |
    | --- | --- |
    | `scripts/` | every bin, and the modules they share |
-   | `effect-channel/` | the Effect error-channel oxlint plugin |
+   | `effect-channel/` | the oxlint plugin with the Effect error-channel and cognitive complexity rules |
    | `dist/` | the committed bundles of the plugin and of `featureRules` |
    | `presets/` | the Effect presets `checks-quality` builds its fragments from |
    | `templates/` | one template per kind of doc file, which `bun run build` renders |

package/README.md

@@ -170,7 +170,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 Effect error-channel plugin and `featureRules` |
+| `dist/` | the compiled oxlint plugin with the Effect error-channel and cognitive complexity rules, and `featureRules` |
 
 <!-- end generated shipped -->
 
@@ -178,6 +178,7 @@ Every path is relative to the installed package, `node_modules/@avi2dg/checks/`.
 
 - [The quality file](docs/configs/quality-file.md)
 - [The Effect rules](docs/configs/effect-rules.md)
+- [The TypeScript rules](docs/configs/typescript-rules.md)
 - [The dependency rules](docs/configs/dependency-rules.md)
 - [The commit message lint](docs/configs/commit-messages.md)
 - [Why it is shaped this way](docs/design.md)

package/dependency-cruiser.config.js

@@ -41,6 +41,14 @@ export default {
         dependencyTypesNot: ["type-only", "npm-peer"],
       },
     },
+    {
+      name: "no-non-package-json",
+      severity: "error",
+      comment:
+        "The import resolves to an installed package the nearest package.json does not declare, so it holds only while something else keeps it hoisted. Declare it in dependencies, devDependencies or peerDependencies.",
+      from: {},
+      to: { dependencyTypes: ["npm-no-pkg", "npm-unknown"] },
+    },
     {
       name: "not-to-unresolvable",
       severity: "error",

package/dist/feature-rules.js

@@ -59,10 +59,11 @@ var STATEMENTS = {
 };
 var COMPLEXITY = {
   key: "complexity",
-  rule: "complexity",
-  options: { variant: "modified" },
-  measured: /has a complexity of (\d+)/,
-  limits: "The highest cyclomatic complexity a function may reach, a switch counted once"
+  rule: "cognitive-complexity",
+  plugin: "effect-channel",
+  options: {},
+  measured: /has a cognitive complexity of (\d+)/,
+  limits: "The highest cognitive complexity a function may reach, a switch counted once"
 };
 var DEPTH = {
   key: "depth",

package/dist/index.js

@@ -1,3 +1,421 @@
+// effect-channel/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"];
+var FUNCTION_TYPES = ["FunctionDeclaration", "FunctionExpression", "TSDeclareFunction", "TSEmptyBodyFunctionExpression", "ArrowFunctionExpression", "StaticBlock"];
+var PLAIN_A_TYPES = ["BlockStatement", "ExpressionStatement", "ReturnStatement", "ThrowStatement", "VariableDeclaration", "VariableDeclarator", "AssignmentPattern", "ObjectPattern", "ArrayPattern", "Property", "RestElement", "TSParameterProperty", "WithStatement", "TSEnumDeclaration", "TSEnumBody", "TSEnumMember"];
+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
+function isControl(node) {
+  return CONTROL_TYPES.includes(node.type);
+}
+function isLoop(node) {
+  return LOOP_TYPES.includes(node.type);
+}
+function isCall(node) {
+  return CALL_TYPES.includes(node.type);
+}
+function isFunction(node) {
+  return FUNCTION_TYPES.includes(node.type);
+}
+function isPlainA(node) {
+  return PLAIN_A_TYPES.includes(node.type);
+}
+function isPlainB(node) {
+  return PLAIN_B_TYPES.includes(node.type);
+}
+function isPlainC(node) {
+  return PLAIN_C_TYPES.includes(node.type);
+}
+function unreachable(_value) {}
+function plainChildrenA(node) {
+  switch (node.type) {
+    case "BlockStatement":
+      return node.body;
+    case "ExpressionStatement":
+      return [node.expression];
+    case "ReturnStatement":
+    case "ThrowStatement":
+      return [node.argument];
+    case "VariableDeclaration":
+      return node.declarations;
+    case "VariableDeclarator":
+      return [node.id, node.init];
+    case "AssignmentPattern":
+      return [node.left, node.right];
+    case "ObjectPattern":
+      return node.properties;
+    case "ArrayPattern":
+      return node.elements;
+    case "Property":
+      return [node.key, node.value];
+    case "RestElement":
+      return [node.argument];
+    case "TSParameterProperty":
+      return [node.parameter];
+    case "WithStatement":
+      return [node.object, node.body];
+    case "TSEnumDeclaration":
+      return [node.body];
+    case "TSEnumBody":
+      return node.members;
+    case "TSEnumMember":
+      return [node.initializer];
+    default:
+      unreachable(node);
+      return [];
+  }
+}
+function plainChildrenB(node) {
+  switch (node.type) {
+    case "ClassDeclaration":
+    case "ClassExpression":
+      return [...node.decorators, node.id, node.superClass, node.body];
+    case "ClassBody":
+      return node.body;
+    case "MethodDefinition":
+    case "TSAbstractMethodDefinition":
+      return [node.key, node.value];
+    case "PropertyDefinition":
+    case "TSAbstractPropertyDefinition":
+    case "AccessorProperty":
+    case "TSAbstractAccessorProperty":
+      return [node.key, node.value];
+    case "ObjectExpression":
+      return node.properties;
+    case "ArrayExpression":
+      return node.elements;
+    default:
+      unreachable(node);
+      return [];
+  }
+}
+function plainChildrenC(node) {
+  switch (node.type) {
+    case "AwaitExpression":
+    case "UnaryExpression":
+    case "UpdateExpression":
+    case "SpreadElement":
+      return [node.argument];
+    case "YieldExpression":
+      return [node.argument];
+    case "BinaryExpression":
+      return [node.left, node.right];
+    case "AssignmentExpression":
+      return [node.left, node.right];
+    case "TSAsExpression":
+    case "TSSatisfiesExpression":
+    case "TSTypeAssertion":
+    case "TSNonNullExpression":
+    case "ChainExpression":
+    case "ParenthesizedExpression":
+    case "Decorator":
+    case "TSInstantiationExpression":
+      return [node.expression];
+    case "MemberExpression":
+    case "JSXMemberExpression":
+      return [node.object, node.property];
+    case "TemplateLiteral":
+      return node.expressions;
+    case "TaggedTemplateExpression":
+      return [node.tag, node.quasi];
+    case "SequenceExpression":
+      return node.expressions;
+    case "JSXElement":
+      return [node.openingElement, ...node.children];
+    case "JSXFragment":
+      return node.children;
+    case "JSXOpeningElement":
+      return node.attributes;
+    case "JSXAttribute":
+      return [node.value];
+    case "JSXExpressionContainer":
+    case "JSXSpreadChild":
+      return [node.expression];
+    case "JSXSpreadAttribute":
+      return [node.argument];
+    default:
+      unreachable(node);
+      return [];
+  }
+}
+
+// effect-channel/cognitive.ts
+function unreachable2(_value) {}
+function scoreList(state, nodes, nesting, parent) {
+  for (const node of nodes) {
+    if (node !== null)
+      score(state, node, nesting, parent);
+  }
+}
+function score(state, node, nesting, parent) {
+  if (isControl(node))
+    return scoreControl(state, node, nesting);
+  if (isLoop(node))
+    return scoreLoop(state, node, nesting);
+  if (isCall(node))
+    return scoreCall(state, node, nesting, parent);
+  if (isFunction(node))
+    return;
+  if (isPlainA(node))
+    return scoreList(state, plainChildrenA(node), nesting, node);
+  if (isPlainB(node))
+    return scoreList(state, plainChildrenB(node), nesting, node);
+  if (isPlainC(node))
+    return scoreList(state, plainChildrenC(node), nesting, node);
+}
+function scoreBranch(state, node, nesting) {
+  score(state, node.test, nesting, node);
+  score(state, node.consequent, nesting + 1, node);
+  const alternate = node.alternate;
+  if (alternate === null)
+    return;
+  state.total += 1;
+  if (alternate.type === "IfStatement")
+    return scoreBranch(state, alternate, nesting);
+  score(state, alternate, nesting + 1, node);
+}
+function scoreIf(state, node, nesting) {
+  state.total += 1 + nesting;
+  scoreBranch(state, node, nesting);
+}
+function scoreControl(state, node, nesting) {
+  switch (node.type) {
+    case "IfStatement": {
+      return scoreIf(state, node, nesting);
+    }
+    case "ConditionalExpression": {
+      state.total += 1 + nesting;
+      score(state, node.test, nesting, node);
+      score(state, node.consequent, nesting + 1, node);
+      score(state, node.alternate, nesting + 1, node);
+      return;
+    }
+    case "SwitchStatement": {
+      state.total += 1 + nesting;
+      score(state, node.discriminant, nesting, node);
+      scoreList(state, node.cases, nesting + 1, node);
+      return;
+    }
+    case "SwitchCase": {
+      if (node.test !== null)
+        score(state, node.test, nesting, node);
+      scoreList(state, node.consequent, nesting, node);
+      return;
+    }
+    case "TryStatement": {
+      score(state, node.block, nesting, node);
+      if (node.handler !== null)
+        score(state, node.handler, nesting, node);
+      if (node.finalizer !== null)
+        score(state, node.finalizer, nesting, node);
+      return;
+    }
+    case "CatchClause": {
+      state.total += 1 + nesting;
+      if (node.param !== null)
+        score(state, node.param, nesting, node);
+      score(state, node.body, nesting + 1, node);
+      return;
+    }
+    default: {
+      return unreachable2(node);
+    }
+  }
+}
+function scoreLoop(state, node, nesting) {
+  switch (node.type) {
+    case "ForStatement": {
+      state.total += 1 + nesting;
+      if (node.init !== null)
+        score(state, node.init, nesting, node);
+      if (node.test !== null)
+        score(state, node.test, nesting, node);
+      if (node.update !== null)
+        score(state, node.update, nesting, node);
+      score(state, node.body, nesting + 1, node);
+      return;
+    }
+    case "ForInStatement":
+    case "ForOfStatement": {
+      state.total += 1 + nesting;
+      score(state, node.left, nesting, node);
+      score(state, node.right, nesting, node);
+      score(state, node.body, nesting + 1, node);
+      return;
+    }
+    case "WhileStatement": {
+      state.total += 1 + nesting;
+      score(state, node.test, nesting, node);
+      score(state, node.body, nesting + 1, node);
+      return;
+    }
+    case "DoWhileStatement": {
+      state.total += 1 + nesting;
+      score(state, node.body, nesting + 1, node);
+      score(state, node.test, nesting, node);
+      return;
+    }
+    case "LabeledStatement": {
+      score(state, node.body, nesting, node);
+      return;
+    }
+    default: {
+      return unreachable2(node);
+    }
+  }
+}
+function insideRun(parent) {
+  return parent !== null && parent.type === "LogicalExpression" && (parent.operator === "&&" || parent.operator === "||");
+}
+function countRuns(node, parentOperator) {
+  if (node.type !== "LogicalExpression")
+    return 0;
+  if (node.operator !== "&&" && node.operator !== "||")
+    return 0;
+  const own = node.operator === parentOperator ? 0 : 1;
+  return own + countRuns(node.left, node.operator) + countRuns(node.right, node.operator);
+}
+function isSelfCall(state, callee) {
+  if (callee.type === "Identifier")
+    return state.names.identifiers.includes(callee.name);
+  if (callee.type === "MemberExpression" && callee.object.type === "ThisExpression" && callee.property.type === "Identifier") {
+    return state.names.members.includes(callee.property.name);
+  }
+  return false;
+}
+function scoreCall(state, node, nesting, parent) {
+  switch (node.type) {
+    case "LogicalExpression": {
+      if (!insideRun(parent) && (node.operator === "&&" || node.operator === "||"))
+        state.total += countRuns(node, null);
+      score(state, node.left, nesting, node);
+      score(state, node.right, nesting, node);
+      return;
+    }
+    case "BreakStatement":
+    case "ContinueStatement": {
+      if (node.label !== null)
+        state.total += 1;
+      return;
+    }
+    case "CallExpression":
+    case "NewExpression": {
+      if (isSelfCall(state, node.callee))
+        state.recursive = true;
+      score(state, node.callee, nesting, node);
+      scoreList(state, node.arguments, nesting, node);
+      return;
+    }
+    case "ImportExpression": {
+      score(state, node.source, nesting, node);
+      if (node.options !== null)
+        score(state, node.options, nesting, node);
+      return;
+    }
+    default: {
+      return unreachable2(node);
+    }
+  }
+}
+function cognitiveComplexity(root, names) {
+  const state = { total: 0, recursive: false, names };
+  if (root.type === "StaticBlock") {
+    scoreList(state, root.body, 0, root);
+    return state.total;
+  }
+  scoreList(state, root.params, 0, root);
+  if (root.type === "ArrowFunctionExpression")
+    score(state, root.body, 0, root);
+  else if (root.body !== null)
+    score(state, root.body, 0, root);
+  return state.recursive ? state.total + 1 : state.total;
+}
+
+// effect-channel/cognitive-complexity.ts
+var DEFAULT_MAX = 15;
+function maxOf(options) {
+  const [first] = options;
+  if (typeof first === "object" && first !== null && "max" in first && typeof first.max === "number" && first.max > 0) {
+    return Math.floor(first.max);
+  }
+  return DEFAULT_MAX;
+}
+function keyName(holder) {
+  if (holder.computed)
+    return;
+  if (holder.key.type === "Identifier")
+    return holder.key.name;
+  if (holder.key.type === "Literal" && typeof holder.key.value === "string")
+    return holder.key.value;
+  return;
+}
+function assignedBinding(target) {
+  if (target.type === "Identifier")
+    return { kind: "identifiers", name: target.name };
+  if (target.type === "MemberExpression" && target.object.type === "ThisExpression" && target.property.type === "Identifier") {
+    return { kind: "members", name: target.property.name };
+  }
+  return;
+}
+function memberBinding(holder) {
+  const name = keyName(holder);
+  return name === undefined ? undefined : { kind: "members", name };
+}
+function binding(node) {
+  const parent = node.parent;
+  if (parent.type === "VariableDeclarator" && parent.init === node && parent.id.type === "Identifier") {
+    return { kind: "identifiers", name: parent.id.name };
+  }
+  if ((parent.type === "Property" || parent.type === "MethodDefinition" || parent.type === "PropertyDefinition" || parent.type === "AccessorProperty") && parent.value === node) {
+    return memberBinding(parent);
+  }
+  if (parent.type === "AssignmentExpression" && parent.right === node)
+    return assignedBinding(parent.left);
+  return;
+}
+function displayName(node) {
+  if (node.type !== "ArrowFunctionExpression" && node.id !== null)
+    return node.id.name;
+  return binding(node)?.name ?? "anonymous";
+}
+function selfNames(node) {
+  const own = node.type === "ArrowFunctionExpression" || node.id === null ? [] : [node.id.name];
+  const bound = binding(node);
+  return {
+    identifiers: bound?.kind === "identifiers" ? [...own, bound.name] : own,
+    members: bound?.kind === "members" ? [bound.name] : []
+  };
+}
+var NO_NAMES = { identifiers: [], members: [] };
+var rule = {
+  meta: {
+    type: "problem",
+    docs: { description: "Hold each function to a cognitive complexity of 15" },
+    schema: [{ type: "object", properties: { max: { type: "number" } }, additionalProperties: false }],
+    defaultOptions: [{ max: DEFAULT_MAX }]
+  },
+  create(context) {
+    const max = maxOf(context.options);
+    const check = (node) => {
+      const score2 = node.type === "StaticBlock" ? cognitiveComplexity(node, NO_NAMES) : cognitiveComplexity(node, selfNames(node));
+      if (score2 <= max)
+        return;
+      const name = node.type === "StaticBlock" ? "static block" : `function \`${displayName(node)}\``;
+      context.report({ node, message: `${name} has a cognitive complexity of ${score2}. Maximum allowed is ${max}.` });
+    };
+    return {
+      FunctionDeclaration: check,
+      FunctionExpression: check,
+      ArrowFunctionExpression: check,
+      StaticBlock: check
+    };
+  }
+};
+var cognitive_complexity_default = rule;
+
 // effect-channel/no-error-channel-escape.ts
 var EFFECT_SOURCES = new Set(["effect", "effect/Effect"]);
 var INSTEAD = {
@@ -19,7 +437,7 @@ var blindToTheError = (handler) => {
     return false;
   return handler.params.every((param) => param.type === "Identifier" && /^_+$/.test(param.name));
 };
-var rule = {
+var rule2 = {
   meta: {
     type: "problem",
     docs: { description: "Disallow the combinators that erase Effect's error channel" }
@@ -67,10 +485,10 @@ var rule = {
     };
   }
 };
-var no_error_channel_escape_default = rule;
+var no_error_channel_escape_default = rule2;
 
 // effect-channel/no-throw.ts
-var rule2 = {
+var rule3 = {
   meta: {
     type: "problem",
     docs: { description: "Disallow throw, which fails outside Effect's error channel" }
@@ -86,10 +504,10 @@ var rule2 = {
     };
   }
 };
-var no_throw_default = rule2;
+var no_throw_default = rule3;
 
 // effect-channel/no-try-catch.ts
-var rule3 = {
+var rule4 = {
   meta: {
     type: "problem",
     docs: { description: "Disallow a try statement with a catch clause, which recovers outside Effect's error channel" }
@@ -105,7 +523,7 @@ var rule3 = {
     };
   }
 };
-var no_try_catch_default = rule3;
+var no_try_catch_default = rule4;
 
 // effect-channel/index.ts
 var plugin = {
@@ -113,7 +531,8 @@ var plugin = {
   rules: {
     "no-error-channel-escape": no_error_channel_escape_default,
     "no-throw": no_throw_default,
-    "no-try-catch": no_try_catch_default
+    "no-try-catch": no_try_catch_default,
+    "cognitive-complexity": cognitive_complexity_default
   }
 };
 var effect_channel_default = plugin;

package/docs/configs/dependency-rules.md

@@ -9,6 +9,7 @@ The shared dependency-cruiser base holds a repository's imports to a set of rule
 - `no-circular`
 - `no-orphans`
 - `not-to-dev-dep`, which refuses shipped source importing a dev-only package, and a package listed in `peerDependencies` too is not dev-only
+- `no-non-package-json`, which refuses an import of an installed package that the nearest `package.json` does not declare
 - `not-to-unresolvable`, which refuses a specifier nothing installed answers
 - `no-deep-imports`, which refuses a subpath the package's exports map does not publish
 

package/docs/configs/effect-rules.md

@@ -43,6 +43,7 @@ effect-tsgo keeps the severities `tsconfig.effect.json` sets when a later config
 
 ## Related topics
 
+- [The TypeScript rules](typescript-rules.md)
 - [checks-quality](../gates/checks-quality.md)
 - [The quality file](quality-file.md)
 - [Why it is shaped this way](../design.md)

package/docs/configs/typescript-rules.md

@@ -0,0 +1,36 @@
+# The TypeScript rules
+
+The oxlint base config holds a repository's TypeScript to a set of rules, and a reader looks it up to learn what each rule refuses and which rules need type information.
+
+## Syntax rules
+
+`oxlintrc.json` turns on the `correctness` and `suspicious` categories as errors, and these rules on top of them:
+
+- `typescript/no-explicit-any` refuses an `any` type written out.
+- `typescript/ban-ts-comment` refuses `@ts-ignore`, `@ts-expect-error` and `@ts-nocheck`.
+- `typescript/no-inferrable-types` refuses a type annotation on a variable or a parameter default whose literal initializer already gives the type.
+- `typescript/explicit-module-boundary-types` refuses an exported function without a return type, and an exported function parameter typed `any`.
+- `typescript/no-non-null-assertion` refuses the non-null assertion `!`.
+- `eslint/no-unused-vars` refuses a variable, a parameter or an import nothing reads, and passes over a variable or a parameter whose name starts with `_` and the siblings of a rest property.
+
+The base turns off `typescript/consistent-return`, which its categories would otherwise turn on.
+It turns on `effect-channel/no-error-channel-escape` as well, and [The Effect rules](effect-rules.md) says what that rule refuses.
+
+## Type-aware rules
+
+These rules read the types, so they run only under `oxlint --type-aware` with `oxlint-tsgolint` installed.
+Without the flag, oxlint skips them and reports nothing about them.
+
+- `typescript/switch-exhaustiveness-check` refuses a `switch` over a union that leaves a member without a case.
+- `typescript/prefer-readonly` refuses a private member that nothing reassigns and that is not `readonly`.
+- `typescript/no-unnecessary-condition` refuses a condition whose type makes its result always the same, such as `??` on a value that cannot be null, and passes over a constant loop condition.
+- `typescript/no-unnecessary-type-parameters` refuses a type parameter the signature uses only once.
+- `typescript/use-unknown-in-catch-callback-variable` refuses a rejection callback whose parameter is not typed `unknown`.
+- `typescript/no-unsafe-type-assertion` refuses an `as` that narrows a value to a type the compiler cannot prove.
+- `typescript/no-deprecated` refuses a use of a symbol whose declaration carries a `@deprecated` tag, in the repository's own code or in a package's types, and repeats the tag's text.
+
+## Related topics
+
+- [The Effect rules](effect-rules.md)
+- [The dependency rules](dependency-rules.md)
+- [Why it is shaped this way](../design.md)

package/docs/design.md

@@ -13,7 +13,9 @@ Each entry below is a choice in the kit's shape and the constraint that forced i
   Node refuses to type-strip a `.ts` plugin under `node_modules`, so the `.ts` source would fail to load from an installed package.
 - `featureRules` ships compiled as `dist/feature-rules.js` for the same reason, with `effect` left out of the bundle so it resolves the consumer's own copy.
   dependency-cruiser uses a config's export as it is and never awaits it, so the declaration decodes synchronously, and `quality.json` exempts that one file from the Effect rules.
-- `checks-size-budget` writes the head commit's files to a temporary directory and runs oxlint there, with a configuration that sets no plugin and turns every category off, so the consumer's own `.oxlintrc.json`, its ignore files and its other rules never reach the count.
+- `checks-size-budget` writes the head commit's files to a temporary directory and runs oxlint there.
+  Its configuration loads the kit's own plugin bundle for the complexity rule and turns every category off.
+  The consumer's own `.oxlintrc.json`, its ignore files and its other rules never reach the count.
 - `checks-size-budget` ratchets against the base of the range rather than a committed baseline such as `oxlint-suppressions.json`.
   A suppression file stores a count of sites per file and rule, and `max-lines` reports a file once however long it grows, so the count stays at one while the file doubles.
   The gate sums how far each site runs over its limit instead, which grows with the file.

package/docs/gates/checks-comment-gate.md

@@ -18,6 +18,8 @@ It passes over a file with any other extension.
 `scripts/comment-matchers.ts` holds the scanner, the comment syntaxes and a synchronous `refused()`, and imports nothing.
 A host such as a hook bundle can therefore copy it alone into a directory with no `node_modules` and import it as `@avi2dg/checks/scripts/comment-matchers.ts`.
 The kit's own dependency cruise fails when that file gains an import.
+`REFUSED_DIRECTIVES` in that file owns the refused directive names, and the checker builds its directive pattern from that list, so the two cannot disagree.
+A consumer reads the same contract by importing `REFUSED_DIRECTIVES` from `@avi2dg/checks/scripts/comment-matchers.ts`.
 `scripts/comments.ts` wraps the same matchers in Effect for the gate and for [checks-backtest](checks-backtest.md).
 
 ## Arguments

package/docs/gates/checks-size-budget.md

@@ -13,7 +13,7 @@ It holds production and test files to the size budget, and lists every other fil
 
 A production file is one under `sources.production`, and a test file is a tracked `.ts` or `.tsx` file under `tests/`.
 A test file keeps to the tests budget, and every other file keeps to the production budget.
-It runs oxlint with a configuration of five rules and nothing else, one for each limit.
+It runs oxlint with a configuration of five rules, one for each limit, and the kit's own plugin bundle, which holds the complexity rule.
 The kit sets each limit:
 
 <!-- generated size-limits: bun run build writes it from SIZE_RULES and SIZE_DEFAULTS in scripts/size-rules.ts and scripts/doc-blocks.ts -->
@@ -23,7 +23,7 @@ The kit sets each limit:
 | `fileLines` | The most lines a file may hold, blank and comment lines counted | `max-lines` | 400 | 600 |
 | `functionLines` | The most lines a function may span, blank and comment lines counted | `max-lines-per-function` | 100 | none |
 | `statements` | The most statements a function may hold | `max-statements` | 30 | 50 |
-| `complexity` | The highest cyclomatic complexity a function may reach, a switch counted once | `complexity` | 15 | 15 |
+| `complexity` | The highest cognitive complexity a function may reach, a switch counted once | `effect-channel/cognitive-complexity` | 15 | 15 |
 | `depth` | The deepest a block may nest inside a function | `max-depth` | 4 | 4 |
 
 <!-- end generated size-limits -->
@@ -88,8 +88,8 @@ With one it is that commit against its parent, or against the empty tree for a r
 size-budget: 2 overrun(s) grew past the base in the production and test files the range adds or changes:
   src/billing/invoice.ts: max-lines over by 31 in total, up from 19
     src/billing/invoice.ts: File has too many lines (431). Maximum allowed is 400.
-  src/billing/ledger.ts: complexity over by 3 in total, up from 0
-    src/billing/ledger.ts:12: function `settle` has a complexity of 18. Maximum allowed is 15.
+  src/billing/ledger.ts: cognitive-complexity over by 3 in total, up from 0
+    src/billing/ledger.ts:12: function `settle` has a cognitive complexity of 18. Maximum allowed is 15.
 size-budget: advisory, 1 overrun(s) where the budget does not hold yet:
   tests/e2e/billing.test.ts: File has too many lines (612). Maximum allowed is 600.
 ```

package/oxlintrc.json

@@ -16,6 +16,7 @@
     "eslint/no-unused-vars": ["error", { "argsIgnorePattern": "^_", "varsIgnorePattern": "^_", "ignoreRestSiblings": true }],
     "typescript/no-unsafe-type-assertion": "error",
     "typescript/no-non-null-assertion": "error",
+    "typescript/no-deprecated": "error",
     "typescript/consistent-return": "off"
   }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@avi2dg/checks",
-  "version": "0.16.0",
+  "version": "0.17.0",
   "description": "Deterministic checks shared across the captain's TypeScript repos",
   "license": "MIT",
   "repository": {

package/quality.schema.json

@@ -178,7 +178,7 @@
             "complexity": {
               "type": "integer",
               "exclusiveMinimum": 0,
-              "description": "The highest cyclomatic complexity a function may reach, a switch counted once; 15 when absent"
+              "description": "The highest cognitive complexity a function may reach, a switch counted once; 15 when absent"
             },
             "depth": {
               "type": "integer",
@@ -205,7 +205,7 @@
             "complexity": {
               "type": "integer",
               "exclusiveMinimum": 0,
-              "description": "The highest cyclomatic complexity a function may reach, a switch counted once; 15 when absent"
+              "description": "The highest cognitive complexity a function may reach, a switch counted once; 15 when absent"
             },
             "depth": {
               "type": "integer",

package/scripts/comment-matchers.ts

@@ -244,6 +244,24 @@ function openingBlock(found: readonly Comment[], source: string): Comment[] {
   return block;
 }
 
+export const REFUSED_DIRECTIVES = [
+  "@ts-expect-error",
+  "@ts-ignore",
+  "biome-ignore",
+  "eslint-disable",
+  "prettier-ignore",
+] as const satisfies readonly string[];
+
+const escapeRegExp = (text: string): string => text.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+
+const directiveSource = (name: string): string => {
+  const escaped = escapeRegExp(name);
+  if (name === "eslint-disable") return `\\b${escaped}[\\w-]*`;
+  return /^[\w]/.test(name) ? `\\b${escaped}\\b` : escaped;
+};
+
+const DIRECTIVE = new RegExp(REFUSED_DIRECTIVES.map(directiveSource).join("|"));
+
 type Check = {
   readonly find: RegExp;
   readonly refusal: (match: string) => string;
@@ -251,7 +269,7 @@ type Check = {
 
 const CHECKS: readonly Check[] = [
   {
-    find: /@ts-expect-error|@ts-ignore|\bprettier-ignore\b|\beslint-disable[\w-]*|\bbiome-ignore\b/,
+    find: DIRECTIVE,
     refusal: (match) =>
       `carries the machine-read directive \`${match}\`. Fix what the tool is reporting, or stop running the tool on this file`,
   },

package/scripts/size-budget.ts

@@ -6,6 +6,8 @@ import { readQuality, renderJson } from "./quality-file.ts";
 import {
   budgetOf,
   budgetsOf,
+  diagnosticCode,
+  qualifiedName,
   SIZE_DEFAULTS,
   SIZE_RULES,
   TESTS_DIRECTORY,
@@ -68,16 +70,17 @@ const decodeReport = Schema.decodeUnknownEffect(Schema.fromJsonString(Schema.Str
 
 function rulesOf(budget: Budget): Record<string, unknown> {
   return Object.fromEntries(
-    SIZE_RULES.map(({ key, rule, options }) => {
-      const max = budget[key];
-      return [rule, max === undefined ? "off" : ["error", { max, ...options }]];
+    SIZE_RULES.map((entry) => {
+      const max = budget[entry.key];
+      return [qualifiedName(entry), max === undefined ? "off" : ["error", { max, ...entry.options }]];
     }),
   );
 }
 
-function sizeConfig({ production, tests }: Budgets): unknown {
+function sizeConfig({ production, tests }: Budgets, plugin: string): unknown {
   return {
     plugins: [],
+    jsPlugins: [plugin],
     categories: { correctness: "off" },
     rules: rulesOf(production),
     overrides: [{ files: [`${TESTS_DIRECTORY}/**`], rules: rulesOf(tests) }],
@@ -116,7 +119,7 @@ const materializeBase = Effect.fn("materializeBase")(function* (root: string, ba
 
 const siteOf = (budgets: Budgets) =>
   Effect.fn("siteOf")(function* ({ code, message, filename, labels }: typeof Diagnostic.Type) {
-    const rule = SIZE_RULES.find((candidate) => code === `eslint(${candidate.rule})`);
+    const rule = SIZE_RULES.find((candidate) => code === diagnosticCode(candidate));
     if (rule === undefined) return [];
     const measured = rule.measured.exec(message)?.[1];
     const max = budgetOf(budgets, filename)[rule.key];
@@ -135,11 +138,11 @@ const siteOf = (budgets: Budgets) =>
     ];
   });
 
-const measure = Effect.fn("measure")(function* (tree: string, budgets: Budgets) {
+const measure = Effect.fn("measure")(function* (tree: string, budgets: Budgets, plugin: string) {
   const fs = yield* FileSystem.FileSystem;
   if (!(yield* fs.exists(tree))) return [];
   // oxlint reads an override's glob from the directory of the config that holds it, so the config sits in the tree.
-  yield* fs.writeFileString((yield* Path.Path).join(tree, CONFIG), renderJson(sizeConfig(budgets)));
+  yield* fs.writeFileString((yield* Path.Path).join(tree, CONFIG), renderJson(sizeConfig(budgets, plugin)));
 
   const { stdout, stderr, exitCode } = yield* collect("oxlint", ["-c", CONFIG, "-f", "json", "."], tree).pipe(
     Effect.mapError((cause) => new OxlintUnreadable({ message: `cannot run oxlint: ${cause.message}` })),
@@ -190,7 +193,8 @@ const runBudget = Effect.fn("runBudget")(
 
     const headTree = path.join(scratch, "head");
     if (held.length + others.length > 0) yield* materializeHead(root, head, [...holds, ...others], headTree);
-    const sites = yield* measure(headTree, budgets);
+    const plugin = path.join(import.meta.dir, "..", "dist", "index.js");
+    const sites = yield* measure(headTree, budgets, plugin);
     const heldSites = sites.filter((site) => holds.has(site.file));
     if (applies !== "ratchet") {
       return { applies, held: held.length, overruns: heldSites, advisory: sites.filter((site) => !holds.has(site.file)) } satisfies Verdict;
@@ -198,7 +202,7 @@ const runBudget = Effect.fn("runBudget")(
 
     const baseTree = path.join(scratch, "base");
     if (held.length > 0) yield* materializeBase(root, base, held, baseTree);
-    const growths = growthsOf(heldSites, yield* measure(baseTree, budgets));
+    const growths = growthsOf(heldSites, yield* measure(baseTree, budgets, plugin));
     const failing = new Set(growths.flatMap((growth) => growth.sites));
     return { applies, held: held.length, growths, advisory: sites.filter((site) => !failing.has(site)) } satisfies Verdict;
   },

package/scripts/size-rules.ts

@@ -30,10 +30,11 @@ const STATEMENTS = {
 
 const COMPLEXITY = {
   key: "complexity",
-  rule: "complexity",
-  options: { variant: "modified" },
-  measured: /has a complexity of (\d+)/,
-  limits: "The highest cyclomatic complexity a function may reach, a switch counted once",
+  rule: "cognitive-complexity",
+  plugin: "effect-channel",
+  options: {},
+  measured: /has a cognitive complexity of (\d+)/,
+  limits: "The highest cognitive complexity a function may reach, a switch counted once",
 } as const;
 
 const DEPTH = {
@@ -49,6 +50,14 @@ export const SIZE_RULES = [FILE_LINES, FUNCTION_LINES, STATEMENTS, COMPLEXITY, D
 export type SizeRule = (typeof SIZE_RULES)[number];
 export type LimitKey = SizeRule["key"];
 
+export function qualifiedName(rule: SizeRule): string {
+  return "plugin" in rule ? `${rule.plugin}/${rule.rule}` : rule.rule;
+}
+
+export function diagnosticCode(rule: SizeRule): string {
+  return "plugin" in rule ? `${rule.plugin}(${rule.rule})` : `eslint(${rule.rule})`;
+}
+
 // An absent limit turns its rule off.
 export type Budget = { readonly [K in LimitKey]?: number };