@avi2dg/checks 0.36.0 → 0.38.0

package/dist/presets/oxlint.js

@@ -0,0 +1,145 @@
+// src/quality/presets/oxlint.ts
+import { fileURLToPath } from "node:url";
+var SIZE_RULES = ["max-lines", "max-lines-per-function", "max-statements", "readability/cognitive-complexity", "max-depth"];
+var SOURCE_LIMITS = {
+  "max-lines": 400,
+  "max-lines-per-function": 100,
+  "max-statements": 30,
+  "readability/cognitive-complexity": 15,
+  "max-depth": 4
+};
+var TEST_LIMITS = {
+  "max-lines": 600,
+  "max-lines-per-function": "off",
+  "max-statements": 50,
+  "readability/cognitive-complexity": 15,
+  "max-depth": 4
+};
+var SOURCES = ["**/*.ts", "**/*.tsx", "**/*.mts", "**/*.cts"];
+var TESTS = ["tests/**", "**/*.test.ts", "**/*.test.tsx"];
+var PLUGINS = ["typescript", "oxc", "eslint", "import"];
+var EFFECT_ONLY_PLUGINS = ["node", "promise", "unicorn"];
+var EFFECT_PLUGINS = [...PLUGINS, ...EFFECT_ONLY_PLUGINS];
+var JS_PLUGINS = ["dist/effect-channel/index.js", "dist/readability/index.js", "dist/data-shape/index.js"];
+var EFFECT_RULES = {
+  "node/no-sync": "error",
+  "oxc/no-async-await": "error",
+  "promise/avoid-new": "error",
+  "unicorn/no-process-exit": "error",
+  "effect-channel/no-throw": "error",
+  "effect-channel/no-try-catch": "error"
+};
+var LINE_RULES = new Set(["max-lines", "max-lines-per-function"]);
+var REFUSED_EFFECT = "@avi2dg/checks/oxlint: set effect to true, false, or { files, excludeFiles } with at least one glob in files";
+function packagePath(path) {
+  return fileURLToPath(new URL(`../../${path}`, import.meta.url));
+}
+var BASE = {
+  plugins: [...PLUGINS],
+  jsPlugins: JS_PLUGINS.map(packagePath),
+  categories: { correctness: "error", suspicious: "error" },
+  rules: {
+    "effect-channel/no-error-channel-escape": "error",
+    "typescript/no-explicit-any": "error",
+    "typescript/ban-ts-comment": ["error", { "ts-expect-error": true }],
+    "typescript/no-inferrable-types": "error",
+    "typescript/explicit-module-boundary-types": "error",
+    "typescript/switch-exhaustiveness-check": "error",
+    "typescript/prefer-readonly": "error",
+    "typescript/no-unnecessary-condition": ["error", { allowConstantLoopConditions: true }],
+    "typescript/no-unnecessary-type-parameters": "error",
+    "typescript/use-unknown-in-catch-callback-variable": "error",
+    "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"
+  },
+  overrides: [
+    {
+      files: ["**/*.ts", "**/*.tsx"],
+      rules: { "data-shape/readonly-collection-param": "error" }
+    },
+    {
+      files: ["**/*.ts", "**/*.tsx"],
+      excludeFiles: ["tests/**"],
+      rules: {
+        "data-shape/schema-twin": "error",
+        "typescript/no-unsafe-assignment": "error",
+        "typescript/no-unsafe-member-access": "error",
+        "typescript/no-unsafe-argument": "error",
+        "typescript/no-unsafe-return": "error",
+        "typescript/no-unsafe-call": "error"
+      }
+    },
+    {
+      files: ["**/*.astro"],
+      rules: { "readability/thin-astro": "error", "import/no-unassigned-import": "off" }
+    }
+  ]
+};
+var base = BASE;
+function sizeSetting(rule, limit) {
+  if (limit === "off")
+    return "off";
+  return LINE_RULES.has(rule) ? ["error", { max: limit, skipBlankLines: false, skipComments: false }] : ["error", { max: limit }];
+}
+function sizeBudget(files, limits, excludeFiles = []) {
+  const rules = Object.fromEntries(SIZE_RULES.map((rule) => [rule, sizeSetting(rule, limits[rule])]));
+  return { files: [...files], excludeFiles: [...excludeFiles], rules };
+}
+function effectRules(files, excludeFiles = []) {
+  return { files: [...files], excludeFiles: [...excludeFiles], plugins: [...EFFECT_PLUGINS], rules: { ...EFFECT_RULES } };
+}
+function isGlobList(value) {
+  return Array.isArray(value) && value.every((glob) => typeof glob === "string" && glob !== "");
+}
+function effectOverrides(effect) {
+  if (effect === true)
+    return [effectRules(SOURCES, TESTS)];
+  if (effect === false)
+    return [];
+  if (typeof effect !== "object" || effect === null)
+    throw new TypeError(REFUSED_EFFECT);
+  const files = "files" in effect ? effect.files : undefined;
+  const excludeFiles = "excludeFiles" in effect ? effect.excludeFiles : [];
+  if (!isGlobList(excludeFiles))
+    throw new TypeError(REFUSED_EFFECT);
+  if (files === undefined)
+    return [effectRules(SOURCES, [...TESTS, ...excludeFiles])];
+  if (!isGlobList(files) || files.length === 0)
+    throw new TypeError(REFUSED_EFFECT);
+  return [effectRules(files, excludeFiles)];
+}
+function withRulePlugins(override) {
+  const rules = Object.keys(override.rules ?? {});
+  const namesEffectOnlyRule = rules.some((rule) => EFFECT_ONLY_PLUGINS.some((plugin) => rule.startsWith(`${plugin}/`)));
+  if (!namesEffectOnlyRule)
+    return override;
+  return { ...override, plugins: [...new Set([...EFFECT_PLUGINS, ...override.plugins ?? []])] };
+}
+function defineConfig({ effect, rules, overrides = [], options, ...rest }) {
+  return {
+    ...BASE,
+    ...rest,
+    options: { typeAware: true, ...options },
+    rules: { ...BASE.rules, ...rules },
+    overrides: [
+      ...BASE.overrides,
+      sizeBudget(SOURCES, SOURCE_LIMITS, TESTS),
+      sizeBudget(TESTS, TEST_LIMITS),
+      ...effectOverrides(effect),
+      ...overrides.map(withRulePlugins)
+    ]
+  };
+}
+export {
+  SOURCES,
+  SOURCE_LIMITS,
+  TESTS,
+  TEST_LIMITS,
+  base,
+  defineConfig,
+  effectRules,
+  sizeBudget
+};

package/docs/configs/dependency-rules.md

@@ -4,34 +4,40 @@ audience: consumers
 ---
 # The dependency rules
 
-The shared dependency-cruiser base holds a repository's imports to a set of rules, and a repository adds its own boundaries on top.
+The kit's dependency-cruiser rules hold a repository's imports, and a repository adds its own boundaries on top.
 
 ## Base rules
 
-`.dependency-cruiser.cjs` extends the shared base, which carries these rules:
+`defineConfig` from `@avi2dg/checks/dependency-cruiser` returns these rules, with or without a config of the repository's own:
 
 - `no-circular`
-- `no-orphans`
+- `no-orphans`, which a repository that depends on `astro` gets only by listing its own, as [checks-imports](../gates/checks-imports.md) explains
 - `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, and counts a peer that `peerDependenciesMeta` marks optional as declared
 - `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
 
-The base parses with swc, so it needs `@swc/core` installed, and without it the cruise silently skips every `.ts` file.
+A test file, a config file and every path under `tests/` may import a dev-only package.
+
+The rules parse with swc, so the cruise needs `@swc/core` installed, and without it the cruise silently skips every `.ts` file.
 
 `no-deep-imports` judges the import specifier, never the file it resolves to.
-The base honours `exports` maps, so a subpath the map publishes resolves and passes, and a subpath it omits fails to resolve and is reported.
+The rules honour `exports` maps, so a subpath the map publishes resolves and passes, and a subpath it omits fails to resolve and is reported.
 A package without an `exports` map publishes every file.
 A bare import always passes, whatever file its entry lives in.
-A repository that sets its own `options.enhancedResolveOptions` replaces the base's, and restates `exportsFields` and `conditionNames` in it.
+A repository that sets its own `options.enhancedResolveOptions` replaces the kit's, and restates `exportsFields` and `conditionNames` in it.
+
+## A repository's own config
 
-## Boundaries
+A repository writes `dependency-cruiser.config.ts` when the defaults do not fit:
 
-A repository appends a named rule per boundary it owns:
+```ts
+import { defineConfig } from "@avi2dg/checks/dependency-cruiser";
 
-```js
-module.exports = {
-  extends: "./node_modules/@avi2dg/checks/dependency-cruiser.config.js",
+export default defineConfig({
+  // A launcher script loads the bin by path, so nothing imports it.
+  orphans: ["^src/bin[.]ts$"],
+  devOnly: ["^(?:evals|tests)/"],
   forbidden: [
     {
       name: "ui-cannot-reach-server",
@@ -40,33 +46,24 @@ module.exports = {
       to: { path: "^src/server" },
     },
   ],
-};
+  options: { exclude: { path: ["^dist/"] } },
+});
 ```
 
-A rule that restates a base name overrides it field by field.
-That is how an entry point stops being an orphan: redeclare `no-orphans` with the entry added to its `pathNot`.
-A repository with an import boundary writes its rule directly under `forbidden`.
+The builder takes dependency-cruiser's own config without `extends`, plus two keys of its own:
 
-## Running it
+- `devOnly` lists the paths that may import a dev dependency, and replaces the default `["^tests/"]`.
+- `orphans` lists the entry points `no-orphans` passes over.
 
-`package.json` gains the script:
+A rule under `forbidden` that takes a kit rule's name replaces that rule whole, and any other rule is added after the kit's.
+`options.exclude` joins the kit's `^repos/`, which keeps the cruise out of the libraries `checks-vendor` links, and every other option replaces the kit's of the same name.
+`tsc` refuses an `extends` key and a severity dependency-cruiser does not know.
 
-```json
-"lint:deps": "depcruise --config .dependency-cruiser.cjs src"
-```
-
-CI runs it beside the other checks:
+## Running it
 
-```yaml
-jobs:
-  lint:
-    steps:
-      - uses: actions/checkout@v5
-      - uses: oven-sh/setup-bun@v2
-      - run: bun install --frozen-lockfile
-      - run: bun run lint:deps
-```
+`checks-lint` runs [checks-imports](../gates/checks-imports.md), which cruises every tracked TypeScript file against `dependency-cruiser.config.ts`, or against the kit's defaults when the repository holds no config.
 
 ## Related topics
 
+- [checks-imports](../gates/checks-imports.md)
 - [Why it is shaped this way](../design.md)

package/docs/configs/effect-rules.md

@@ -8,38 +8,59 @@ The oxlint base and Effect language service check paths a repository writes with
 
 ## Oxlint override
 
-The shared `oxlintrc.json` loads `effect-channel/no-error-channel-escape` across the tree.
-The repo's `.oxlintrc.json` owns its Effect paths and exemptions in an override:
+The kit's oxlint `base` loads `effect-channel/no-error-channel-escape` across the tree.
+`effect` in `oxlint.config.ts` names the paths that hold the six Effect rules, and has no default:
 
-```json
+| `effect` | The Effect rules hold |
+| --- | --- |
+| `true` | every source file outside the tests |
+| `false` | no file |
+| `{ excludeFiles }` | every source file outside the tests, less these globs |
+| `{ files, excludeFiles }` | these globs, less `excludeFiles`, with at least one glob in `files` |
+
+`files` and `excludeFiles` read as they do in an oxlint override.
+Every source file is `SOURCES`, the `.ts`, `.tsx`, `.mts` and `.cts` files, and the tests are `TESTS`, the files under `tests/` and each `*.test.ts` or `*.test.tsx`.
+A comment beside an excluded glob says why that path stays outside Effect:
+
+```ts
+import { defineConfig } from "@avi2dg/checks/oxlint";
+
+export default defineConfig({
+  effect: {
+    excludeFiles: [
+      // Launchd runs the renamer, and it cannot import Effect v4.
+      "home/.config/renamer/**",
+    ],
+  },
+});
+```
+
+A config that leaves `effect` out, sets it to a string or gives `files` no glob fails `tsc`, and oxlint refuses it again when it loads the file.
+`effectRules(files, excludeFiles)` from the same module returns the override itself:
+
+```ts
 {
-  "extends": ["./node_modules/@avi2dg/checks/oxlintrc.json"],
-  "plugins": ["typescript", "oxc", "eslint", "import"],
-  "overrides": [{
-    "files": ["src/**/*.ts"],
-    "excludeFiles": ["src/host/*.ts"],
-    "plugins": ["typescript", "oxc", "eslint", "import", "node", "promise", "unicorn"],
-    "rules": {
-      "node/no-sync": "error",
-      "oxc/no-async-await": "error",
-      "promise/avoid-new": "error",
-      "unicorn/no-process-exit": "error",
-      "effect-channel/no-throw": "error",
-      "effect-channel/no-try-catch": "error"
-    }
-  }]
+  files: ["src/**/*.ts"],
+  excludeFiles: ["src/host/*.ts"],
+  plugins: ["typescript", "oxc", "eslint", "import", "node", "promise", "unicorn"],
+  rules: {
+    "node/no-sync": "error",
+    "oxc/no-async-await": "error",
+    "promise/avoid-new": "error",
+    "unicorn/no-process-exit": "error",
+    "effect-channel/no-throw": "error",
+    "effect-channel/no-try-catch": "error"
+  }
 }
 ```
 
-The kit ships the rule block in `src/quality/presets/effect.oxlint.json` for copying into the override.
-Each config in an oxlint `extends` chain sets `plugins` explicitly, because an omitted list enables defaults across the chain.
 `unicorn/no-process-exit` does not check a shebang script, so a bin can use `eslint/no-restricted-properties` for `process.exit`.
 
 ## Language service
 
 The repository's `tsconfig.json` holds its Effect override under `compilerOptions.plugins`.
-The override includes the same source paths and excludes the same exempt paths as oxlint.
-The kit ships severity values in `src/quality/presets/effect.language-service.json` for the override's `options`.
+[checks-effect-scope](../gates/checks-effect-scope.md) writes that override from `oxlint.config.ts`, so it includes and excludes the same paths as oxlint.
+The override takes its `options` from the severity values the kit ships in `src/quality/presets/effect.language-service.json`.
 The preset turns these diagnostics to errors:
 
 - `nodeBuiltinImport` refuses an import of a Node built-in module that has an Effect counterpart.
@@ -50,9 +71,12 @@ The preset turns these diagnostics to errors:
 - `processEnvInEffect` refuses a read of `process.env` inside an Effect generator.
 
 Effect's `Config` reads the environment in place of `process.env`.
-The kit's `tsconfig.effect.json` keeps the shared language service diagnostics.
+The kit's `tsconfig.effect.json` holds the shared language service diagnostics.
+A plugin entry in the repository's `tsconfig.json` stands in for the kit's, so `checks-effect-scope` writes those severities into it on every run.
+The kit owns the severities of its own keys, and a repository adds keys of its own but does not change the kit's.
 
 ## Related topics
 
 - [The TypeScript rules](typescript-rules.md)
 - [Native settings](native-settings.md)
+- [checks-effect-scope](../gates/checks-effect-scope.md)

package/docs/configs/native-settings.md

@@ -11,15 +11,15 @@ A consuming repository puts each setting in the file its tool reads, and no mani
 | File | Setting | Reader |
 | --- | --- | --- |
 | `.github/workflows/*.yml` | Pull request commands, scheduled commands, runner labels | GitHub Actions and `checks-ci-wiring` |
-| `.oxlintrc.json` | Effect paths, exemptions, file size, function size, statements, cognitive complexity and depth | oxlint |
+| `oxlint.config.ts` | Effect paths and their exemptions, ignore patterns, and any rule or budget the repository sets over the kit's defaults | oxlint and `checks-effect-scope` |
 | `oxlint-suppressions.json` | The existing violations oxlint suppresses, per file and rule | oxlint and `checks-suppressions-ratchet` |
 | `exports-baseline.json` | The existing unused exports and types, per file, kind and name | `checks-exports` |
 | `.jscpd.json` | The `path` and `ignore` globs of the files repetition is measured in | jscpd and `checks-repetition` |
-| `knip.config.ts` | The `entry` globs Knip traces unreferenced files from, spread over the kit's `knip-base.json` | Knip, `checks-unused` and `checks-exports` |
-| `tsconfig.json` | Effect language service scope and severity | TypeScript and Effect language service |
+| `knip.config.ts` | The `entry` globs Knip traces unreferenced files from | Knip, `checks-unused` and `checks-exports` |
+| `dependency-cruiser.config.ts` | Entry points nothing imports, paths that may import dev dependencies, and import boundaries, when the kit's defaults do not fit | `checks-imports` |
+| `tsconfig.json` | Compiler options, and the Effect language service plugin whose `overrides` and kit severities `checks-effect-scope` writes, keeping every other key | TypeScript and Effect language service |
 | `package.json` | `scripts` with the `checks-vendor` arguments in `prepare`, `author` and `contributors` | Bun, `checks-commit-identity` and `checks-vendor` |
 | `bunfig.toml` | Test discovery and quarantine exclusion | Bun and `checks-test-layout` |
-| `.dependency-cruiser.cjs` | Import rules | dependency-cruiser |
 | `stryker.conf.mjs` | Mutation settings | Stryker |
 | Each page under `docs/` | Diátaxis mode in `kind` front matter, and `audience: consumers` on a page that speaks to a consuming repository | `checks-docs` |
 
@@ -27,16 +27,66 @@ Every page under `docs/` names its mode in `kind` front matter, whatever directo
 A page whose front matter sets `audience: consumers` names commands that a consuming repository runs.
 `checks-docs` skips the `bun run` commands on such a page, and resolves those in every other living doc or agent file as [Paths, links and commands](../gates/checks-docs.md#paths-links-and-commands) says.
 
+## The config builders
+
+The kit ships a `defineConfig` for oxlint, Knip and dependency-cruiser.
+Each takes the tool's own config type, less the keys the kit owns, and returns the whole config with a default for every kit rule.
+A key only the repository knows has no default, so `tsc` refuses a config that leaves it out.
+The builder throws when the tool loads such a config anyway.
+
+| Builder | Required | The kit owns |
+| --- | --- | --- |
+| `@avi2dg/checks/oxlint` | `effect` | `extends`, `plugins`, `jsPlugins` and `categories` |
+| `@avi2dg/checks/knip` | `entry`, where `[]` means the package scripts and tests name every entry | `include` |
+| `@avi2dg/checks/dependency-cruiser` | nothing | `extends` |
+
+A repository whose sources are Effect programs writes `oxlint.config.ts`:
+
+```ts
+import { defineConfig } from "@avi2dg/checks/oxlint";
+
+export default defineConfig({
+  effect: true,
+  ignorePatterns: ["src/crawler-extract.js"],
+});
+```
+
+`ignorePatterns`, `rules`, `overrides`, `settings`, `env`, `globals` and `options` mean what they mean in oxlint's own docs.
+The kit's rules come first, and the repository's `rules` and `overrides` land after them.
+An override that sets a `node/`, `promise/` or `unicorn/` rule gets the Effect override's `plugins`, since the kit loads those plugins only there.
+[The Effect rules](effect-rules.md) lists what `effect` accepts.
+`defineConfig` sets `options.typeAware`, so a plain `oxlint` runs the type-aware rules.
+The module also exports the blocks the config is built from: `base`, `sizeBudget`, `effectRules`, `SOURCE_LIMITS`, `TEST_LIMITS`, `SOURCES` and `TESTS`.
+
+`knip.config.ts` names the files nothing imports:
+
+```ts
+import { defineConfig } from "@avi2dg/checks/knip";
+
+export default defineConfig({ entry: ["src/index.ts"] });
+```
+
+`dependency-cruiser.config.ts` is optional, since `checks-imports` cruises against the kit's defaults without one:
+
+```ts
+import { defineConfig } from "@avi2dg/checks/dependency-cruiser";
+
+export default defineConfig({ devOnly: ["^(?:evals|tests)/"] });
+```
+
+[The dependency rules](dependency-rules.md) lists its keys.
+`tsconfig.json` keeps the three config files in its program, so `bun run typecheck` holds them to the builders' types.
+
 ## Size limits
 
-The size rules are oxlint's own rules at `error` in `.oxlintrc.json`, so `bun run lint` fails on any file over them.
+The size rules are oxlint's own rules at `error`, which every `oxlint.config.ts` built with `defineConfig` sets over the whole tree, so `bun run lint` fails on any file over them.
 A repository records its existing violations with `oxlint --suppress-all`, which writes them to `oxlint-suppressions.json`.
 `checks-suppressions-ratchet` refuses any count in that file that rises.
-The kit's own `.oxlintrc.json` sets these limits for each size override, and a repository may copy them:
+`SOURCE_LIMITS` holds the limits for sources and `TEST_LIMITS` the limits for tests:
 
-<!-- generated size-limits: bun run build writes it from .oxlintrc.json, SIZE_RULES in src/complexity/size-rules.ts and scripts/doc-blocks.ts -->
+<!-- generated size-limits: bun run build writes it from SOURCE_LIMITS, TEST_LIMITS, SOURCES and TESTS in src/quality/presets/oxlint.ts and scripts/doc-blocks.ts -->
 
-| Limits | oxlint rule | `src/**/*.ts`, `scripts/**/*.ts` | `tests/**/*.ts` |
+| Limits | oxlint rule | `**/*.ts`, `**/*.tsx`, `**/*.mts`, `**/*.cts` outside the tests | `tests/**`, `**/*.test.ts`, `**/*.test.tsx` |
 | --- | --- | --- | --- |
 | 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 |
@@ -46,9 +96,16 @@ The kit's own `.oxlintrc.json` sets these limits for each size override, and a r
 
 <!-- end generated size-limits -->
 
+A file a repository holds to another limit gets an ordinary override in `oxlint.config.ts`:
+
+```ts
+overrides: [{ files: ["src/lib/server.ts"], rules: { "max-lines": ["error", { max: 600 }] } }],
+```
+
 ## Related topics
 
 - [The Effect rules](effect-rules.md)
+- [The dependency rules](dependency-rules.md)
 - [checks-ci-wiring](../gates/checks-ci-wiring.md)
 - [checks-suppressions-ratchet](../gates/checks-suppressions-ratchet.md)
 - [checks-docs](../gates/checks-docs.md)

package/docs/configs/typescript-rules.md

@@ -4,11 +4,11 @@ audience: consumers
 ---
 # The TypeScript rules
 
-The oxlint base config and the tsconfig fragment hold a repository's TypeScript to a set of rules, and some of them need type information.
+The kit's oxlint base and the tsconfig fragment hold a repository's TypeScript to a set of rules, and some of them need type information.
 
 ## Syntax rules
 
-`oxlintrc.json` turns on the `correctness` and `suspicious` categories as errors, and these rules on top of them:
+`base` from `@avi2dg/checks/oxlint`, which every config its `defineConfig` returns starts from, 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`.
@@ -22,8 +22,8 @@ It turns on `effect-channel/no-error-channel-escape` as well, and [The Effect ru
 
 ## 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.
+These rules read the types, so they run only with `oxlint-tsgolint` installed and type-aware linting on.
+`defineConfig` turns it on through `options.typeAware`, so a plain `oxlint` runs 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`.
@@ -45,7 +45,7 @@ The base loads the kit's `data-shape` plugin from `dist/` with one rule for ever
 
 ## Astro rules
 
-An override in `oxlintrc.json` turns on one rule of the kit's `readability` plugin in each `.astro` file:
+An override in `base` turns on one rule of the kit's `readability` plugin in each `.astro` file:
 
 - `readability/thin-astro` refuses a statement in the frontmatter or a script block that is neither an import, a re-export from another module, a type or interface declaration, nor a variable read from `Astro.props`.
 - A default inside an `Astro.props` destructuring passes only when it is a literal, a `-` or `+` on a numeric literal, or a name read from `Astro.props` earlier, in the same pattern or a statement before it, so `const { title = "Home", heading = title } = Astro.props;` passes and a call or `await` in a default is refused.
@@ -55,7 +55,7 @@ An override in `oxlintrc.json` turns on one rule of the kit's `readability` plug
 
 ## Rules outside tests
 
-An override in `oxlintrc.json` turns on these type-aware rules in each `.ts` and `.tsx` file outside `tests/`:
+An override in `base` turns on these type-aware rules in each `.ts` and `.tsx` file outside `tests/`:
 
 - `typescript/no-unsafe-assignment` refuses assigning an `any` value to a variable, a property or a destructured name.
 - `typescript/no-unsafe-member-access` refuses reading a member of an `any` value.
@@ -63,7 +63,7 @@ An override in `oxlintrc.json` turns on these type-aware rules in each `.ts` and
 - `typescript/no-unsafe-return` refuses returning an `any` value from a function, unless the function returns `unknown`.
 - `typescript/no-unsafe-call` refuses calling an `any` value.
 
-A consumer inherits the override through `extends`, and a file under `tests/` answers to none of the five.
+Every config `defineConfig` returns carries the override, and a file under `tests/` answers to none of the five.
 
 ## Compiler options
 

package/docs/design.md

@@ -8,14 +8,25 @@ Each section names the limit and what the obvious alternative would break.
 
 ## Each tool reads its own config
 
-A repository keeps each setting in the file its tool reads, such as `.oxlintrc.json`, `tsconfig.json` or `.jscpd.json`.
+A repository keeps each setting in the file its tool reads, such as `oxlint.config.ts`, `tsconfig.json` or `.jscpd.json`.
 A developer then changes a rule where the tool reads it, and the tool's own docs describe that file.
-The Effect paths sit in two of those files, `.oxlintrc.json` and `tsconfig.json`, and the installed consumer test checks each one on its own.
+
+oxlint, Knip and dependency-cruiser each read a TypeScript config, so the kit ships a `defineConfig` for each over the tool's own config type.
+A repository writes the shape that tool's docs describe, and adds to the kit's rules through the tool's own keys.
+Each builder sets a default for every kit rule, and every glob in it covers the whole tree, so no unlisted directory escapes a rule.
+A rule set copied by hand would miss whatever the copy left out, and would fail on a path the copy forgot.
+A fact only the repository knows has no default, `effect` for oxlint and `entry` for Knip.
+Defaulting `effect` on fails a repository whose code is deliberately outside Effect, and defaulting it off leaves an Effect repository unchecked, so its type is required.
+Neither oxlint nor Knip typechecks the config it loads, so each builder also throws when it gets a config without that fact.
+Both tools read a config's default export synchronously, so a throw is the one refusal open to the builder.
+
+The Effect paths sit in `oxlint.config.ts` alone.
+`tsconfig.json` cannot import a TypeScript module, so `checks-effect-scope` writes the Effect language service override in `tsconfig.json` from them, and fails `checks-lint` when the two differ.
 
 oxlint does not pass `plugins` down an `extends` chain.
 A config in the chain that sets no `plugins` gets oxlint's default plugins, and the base's `categories` then turn on their rules across the tree.
-So a consumer's `.oxlintrc.json` and each of its overrides list `plugins` again.
-`rules`, `categories` and `jsPlugins` pass down the chain as expected.
+So `defineConfig` returns the whole root config with `plugins` set, and a repository adds its own keys rather than extending a kit object.
+oxlint reads a relative `jsPlugins` path against the consumer's config, so `base` names each plugin bundle by its absolute path in the installed kit.
 `.gitignore` keeps oxlint out of `node_modules/`, because oxlint still walks the installed package when only `ignorePatterns` names it.
 
 The base turns `data-shape/readonly-collection-param` on for every TypeScript file and `data-shape/schema-twin` on for production files only.
@@ -29,9 +40,9 @@ An empty `--path-ignore-patterns` flag overrides the copied `[test] pathIgnorePa
 Stryker 10 does not resolve `extends` in a JSON config.
 So the Stryker preset is a JavaScript module that a repository's `stryker.conf.mjs` spreads, and a key set after the spread wins.
 
-The dependency-cruiser base parses with swc, because TypeScript 7, which is tsgo, has no compiler API that dependency-cruiser can use.
+The dependency-cruiser rules parse with swc, because TypeScript 7, which is tsgo, has no compiler API that dependency-cruiser can use.
 Without `@swc/core` installed, the cruise skips every `.ts` file without a warning, so the kit's own suite asserts that its TypeScript is cruised.
-The base counts `bun` as a built-in module.
+The rules count `bun` as a built-in module.
 Only `@types/bun` resolves it, and that package is a dev dependency, so every runtime `bun` import would otherwise read as dev only.
 
 ## The shared configs close gaps in the types
@@ -39,7 +50,7 @@ Only `@types/bun` resolves it, and that package is a dev dependency, so every ru
 The shared configs refuse four places where a value's type says less than the value does.
 Each sits in a file a consumer already extends or copies.
 
-The base `oxlintrc.json` turns on the five `typescript/no-unsafe-*` rules in an override for `.ts` and `.tsx` files outside `tests/`, so every consumer gets them through `extends`.
+The oxlint `base` turns on the five `typescript/no-unsafe-*` rules in an override for `.ts` and `.tsx` files outside `tests/`, so every config `defineConfig` returns carries them.
 `typescript/no-explicit-any` and `strict` already refuse an `any` someone writes, so the `any` left is one nobody wrote.
 `Array.isArray` narrows an `unknown` to `any[]`, `JSON.parse` returns `any`, `Object.entries` lists `any` values from an `object`, and a defaulted parameter in a generator passed to `Effect.fnUntraced` is typed `any`.
 Tests stay out because bun:test types its asymmetric matchers, such as `expect.arrayContaining`, as returning `any`.
@@ -86,7 +97,8 @@ A path read without the resolver, such as `node_modules/@avi2dg/checks/scripts/t
 npm adds `package.json`, `README.md` and `LICENSE` whatever `files` says.
 `bun pm pack` builds the same tarball the registry serves, and the consumer e2e test installs that tarball.
 
-Each oxlint plugin ships compiled under `dist/`, because Node refuses to strip types from a `.ts` file under `node_modules`.
+Each oxlint plugin and each config builder ships compiled under `dist/`, because Node refuses to strip types from a `.ts` file under `node_modules`.
+oxlint loads `oxlint.config.ts` under Node, so the builders ship as JavaScript beside a `.d.ts` that `tsc` reads.
 `@oxlint/plugins` ships no RuleTester, so each `effect-channel`, `readability` and `data-shape` rule is proven red and green against an installed consumer in `tests/e2e/consumer.test.ts`, except `readability/thin-astro`, which `tests/e2e/astro-consumer.test.ts` proves against a consumer tree linked to the checkout.
 `dist/` is committed, with the doc templates in `dist/templates/`, and so is `CHANGELOG.md`, which the same build writes.
 No `prepack` or `prepublishOnly` script rebuilds them, so a publish ships the committed files.
@@ -112,6 +124,11 @@ The gates run one at a time and pass their output straight through, so each repo
 `checks-lint` picks the gates that apply from the tracked files, and a repository cannot select gates.
 A TypeScript gate runs as soon as the repository tracks TypeScript source, and `checks-lint-coverage` and `checks-unused` also run on tracked Astro source.
 
+dependency-cruiser runs as the `checks-imports` gate rather than as a script each repository adds to `lint`, so no repository can leave it out.
+A repository with no config of its own is cruised against the kit's defaults, since every rule has one.
+The gate cruises the tracked TypeScript, so a build output or a linked library outside git never reaches the cruise.
+It runs dependency-cruiser under Bun, which loads a TypeScript config wherever it sits, the kit's defaults under `node_modules` among them.
+
 GitHub authors the pull request merge commit it builds as `GitHub <noreply@github.com>`, and `checks-commit-identity` refuses that author.
 So `checks-lint` ends a pull request's range at the event's head commit, and the merge commit is never in it.
 A `lint` that calls `checks-commit-identity HEAD` directly checks out `github.event.pull_request.head.sha` rather than the default merge ref.

package/docs/gates/checks-effect-scope.md

@@ -0,0 +1,63 @@
+---
+kind: reference
+audience: consumers
+---
+# checks-effect-scope
+
+`checks-effect-scope` writes the Effect paths of `oxlint.config.ts` and the kit's severities into the Effect language service plugin in `tsconfig.json`.
+As a gate it fails when either differs from what it would write.
+
+## What it checks
+
+It loads `oxlint.config.ts` and takes the `files` and `excludeFiles` of the override holding the six Effect rules, the one the `effect` key of `defineConfig` builds.
+Each such override becomes one entry under `overrides` of the `@effect/language-service` plugin in `tsconfig.json`, with `files` as its `include`, `excludeFiles` as its `exclude`, and the severities in `src/quality/presets/effect.language-service.json` as its `options`.
+The `overrides` of that plugin and the kit's keys in its `diagnosticSeverity` belong to it, and every other key of `tsconfig.json` stays as the repository wrote it.
+With `effect: false` the plugin holds no `overrides`.
+With `--check` it fails when the override or the kit's severities in `tsconfig.json` differ from what it would write, and writes nothing.
+
+## What it reads
+
+It reads `oxlint.config.ts` and `tsconfig.json` at the repository root.
+It reads `tsconfig.json` as TypeScript does, so a comment or a trailing comma parses, and refuses one that does not parse as a JSONC object.
+It rewrites only the `overrides` value of the `@effect/language-service` plugin and the kit's keys in its `diagnosticSeverity`, as JSON with two spaces of indent.
+When that value is missing it adds the member, and the plugin, `plugins` or `compilerOptions` holding it, after the last member of each.
+Each key of the `diagnosticSeverity` in the kit's `tsconfig.effect.json` gets the kit's value, and a key the repository added stays.
+A key a release drops from `tsconfig.effect.json` stays in the repository's entry until the repository removes it.
+It refuses a `compilerOptions` or `plugins` set to `null`, or a `diagnosticSeverity` that is not an object, which would leave no place for what it writes.
+With `effect: false` it deletes the `overrides` member and its comma, and leaves the comments beside it.
+Every other byte of `tsconfig.json` stays as the repository wrote it.
+A repository without `tsconfig.json` has no language service to hold the paths, so it passes.
+
+## Arguments
+
+```sh
+checks-effect-scope
+checks-effect-scope --check
+```
+
+With no argument it writes `tsconfig.json`.
+With `--check` it only compares.
+
+## Exit codes
+
+| Code | When |
+| --- | --- |
+| 0 | `tsconfig.json` holds the Effect paths and the kit's severities, or was written to hold them |
+| 1 | with `--check`, `tsconfig.json` holds other Effect paths or other severities for the kit's keys |
+| 2 | `oxlint.config.ts` does not load, or `tsconfig.json` does not parse, sets `compilerOptions` or `plugins` to `null`, or holds a `diagnosticSeverity` that is not an object |
+
+## Sample output
+
+```
+effect-scope: the @effect/language-service entry in tsconfig.json differs from the Effect paths of oxlint.config.ts or the kit's severities; run checks-effect-scope to rewrite them
+```
+
+## When it runs
+
+A repository runs `checks-effect-scope` from its `build` script, so CI's `git diff --exit-code` after the build fails on a stale `tsconfig.json` too.
+`checks-lint` runs it with `--check` when the repository tracks `oxlint.config.ts`.
+
+## Related topics
+
+- [The Effect rules](../configs/effect-rules.md)
+- [checks-lint](checks-lint.md)