@avi2dg/checks 0.16.0 → 0.18.0

package/CHANGELOG.md

@@ -2,6 +2,28 @@
 
 Every release of `@avi2dg/checks`, newest first, written by the release from its conventional commits.
 
+## 0.18.0
+
+Released 2026-09-26.
+
+### Features
+
+- **scripts:** generate commitlint and CI workflows with checks-quality (#54)
+
+### Fixes
+
+- **scripts:** make checks-quality refuse a config that drops the kit's extends (#55)
+
+## 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/commit-messages.md

@@ -10,24 +10,8 @@ It arrives with the kit, since `@commitlint/cli` and `@commitlint/config-convent
 ## Workflow
 
 The lint runs in CI on pull requests, because `jj` never fires a git hook.
-A repository adds this workflow:
-
-```yaml
-on:
-  pull_request:
-    types: [opened, edited, synchronize, reopened]
-jobs:
-  commitlint:
-    runs-on: ubuntu-latest
-    steps:
-      - uses: actions/checkout@v5
-      - uses: oven-sh/setup-bun@v2
-      - run: bun install --frozen-lockfile
-      - run: printf '%s' "$PR_TITLE (#0000)" > "$RUNNER_TEMP/pr-title"
-        env:
-          PR_TITLE: ${{ github.event.pull_request.title }}
-      - run: ./node_modules/.bin/commitlint --config ./node_modules/@avi2dg/checks/commitlint.config.js --edit "$RUNNER_TEMP/pr-title"
-```
+`checks-quality generate` writes the workflow whole into `.github/workflows/commitlint.yml`, as [checks-quality](../gates/checks-quality.md) says.
+The workflow lints with the installed kit's `commitlint.config.js`, so every repository holds titles to the same rules.
 
 ## What it lints
 

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/quality-file.md

@@ -39,8 +39,8 @@ The kit's bins find the file at the git root and read it there:
 
 | Key | Read by | Holds |
 | --- | --- | --- |
-| `defaultBranch` | `checks-lint`, `checks-ci-wiring` | the branch pull requests merge into, `main` when absent |
-| `gates.ci` | `checks-ci-wiring` | the commands CI runs on every pull request, as [checks-ci-wiring](../gates/checks-ci-wiring.md) says |
+| `defaultBranch` | `checks-lint`, `checks-ci-wiring`, `checks-quality` | the branch pull requests merge into, `main` when absent |
+| `gates.ci` | `checks-ci-wiring`, `checks-quality` | the commands CI runs on every pull request, as [checks-ci-wiring](../gates/checks-ci-wiring.md) says |
 | `gates.scheduled` | `checks-ci-wiring` | the commands a schedule runs |
 | `gates.lint` | `checks-lint`, `checks-ci-wiring` | the gates `checks-lint` runs when not all apply, as [Gate selection](../gates/checks-lint.md#gate-selection) says |
 | `commitIdentity.authors` | `checks-commit-identity` | the identities allowed to author and commit, as [checks-commit-identity](../gates/checks-commit-identity.md) says |

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.