@avi2dg/checks 0.21.0 → 0.23.0

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

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

package/docs/configs/commit-messages.md

@@ -1,3 +1,7 @@
+---
+kind: reference
+audience: consumers
+---
 # The commit message lint
 
 The shared commitlint config holds each pull request title to conventional commits, and a reader looks it up to wire the lint into a repository's CI.
@@ -10,7 +14,7 @@ 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.
-`checks-quality generate` writes the workflow whole into `.github/workflows/commitlint.yml`, as [checks-quality](../gates/checks-quality.md) says.
+Each repository owns `.github/workflows/commitlint.yml` and runs the installed `commitlint` binary in a pull request step.
 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

@@ -1,3 +1,7 @@
+---
+kind: reference
+audience: consumers
+---
 # The dependency rules
 
 The shared dependency-cruiser base holds a repository's imports to a set of rules every repository shares, and a reader looks it up to add a boundary of its own.
@@ -35,7 +39,7 @@ module.exports = {
 
 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 that declares feature owners spreads the rules `quality.json` compiles to into the same `forbidden`, as [checks-feature-owners](../gates/checks-feature-owners.md#import-boundary) says.
+A repository with an import boundary writes its rule directly under `forbidden`.
 
 ## Running it
 
@@ -59,5 +63,4 @@ jobs:
 
 ## Related topics
 
-- [checks-feature-owners](../gates/checks-feature-owners.md)
 - [Why it is shaped this way](../design.md)

package/docs/configs/effect-rules.md

@@ -1,49 +1,48 @@
+---
+kind: reference
+audience: consumers
+---
 # The Effect rules
 
-The oxlint base config and the tsconfig fragment hold a repository's Effect code to its error channel and to Effect-native IO, and a reader looks them up to learn what each rule refuses and how a path opts in.
+The oxlint base and Effect language service check paths a repository writes with Effect.
 
-## Base config
+## Oxlint override
 
-The base config, `oxlintrc.json`, loads the `effect-channel` plugin and turns on `effect-channel/no-error-channel-escape`.
-That rule refuses `Effect.ignore`, `Effect.ignoreCause`, the `Effect.catchCause` family, and an `Effect.catch` whose handler takes no error or names it `_`.
-
-Two more rules ship off, because a repository writes only some of its paths in Effect, and code a host loads without `node_modules`, such as a hook bundle or this oxlint plugin, cannot import it:
-
-- `effect-channel/no-throw` refuses a `throw` statement.
-- `effect-channel/no-try-catch` refuses a `try` statement with a `catch` clause, and `try`/`finally` stays allowed.
-
-Each refusal says what to write instead: a `Schema.TaggedError` failed through `Effect.fail`, a throwing call wrapped in `Effect.try` or `Effect.tryPromise`, and recovery by tag with `Effect.catchTag`.
-
-## Effect paths
-
-A repository turns the rules on for the paths it writes in Effect by declaring those paths in `quality.json` and extending the fragments [checks-quality](../gates/checks-quality.md) generates:
+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:
 
 ```json
-"sources": {
-  "effect": { "paths": ["src/**/*.ts"], "exempt": ["src/host/*.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"
+    }
+  }]
 }
 ```
 
-The fragment's override carries the kit's Effect rule block, `presets/effect.oxlint.json`.
-It holds the two rules above, plus `node/no-sync`, `oxc/no-async-await`, `promise/avoid-new` and `unicorn/no-process-exit`.
-Files under `exempt` answer to none of them.
-
-oxlint resolves `files` against the directory of the config that holds the override, so a config passed with `-c` from outside the repository matches nothing and reports nothing.
-
-`unicorn/no-process-exit` passes over any file that opens with a shebang.
-A repository whose bins open with one bans `process.exit` itself with `no-restricted-properties` in its own `.oxlintrc.json`, as the kit's own repository does.
-The preset leaves that rule out because a repository's own `no-restricted-properties` list for the same files would replace it, or be replaced by it.
-Sites standing when the declaration lands go in oxlint's own baseline, `oxlint --suppress-all`, so their count can only fall, as [checks-suppressions-ratchet](../gates/checks-suppressions-ratchet.md) holds.
+The kit ships the rule block in `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 language service holds the same paths to Effect-native IO through the tsconfig fragment's override, whose severities are `presets/effect.language-service.json`.
-`nodeBuiltinImport`, `asyncFunction`, `newPromise` and `extendsNativeError` are all errors.
-effect-tsgo keeps the severities `tsconfig.effect.json` sets when a later config in `extends` restates the plugin with only its overrides.
+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 `presets/effect.language-service.json` for the override's `options`.
+The kit's `tsconfig.effect.json` keeps the shared language service diagnostics.
 
 ## 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)
+- [Native settings](native-settings.md)

package/docs/configs/native-settings.md

@@ -0,0 +1,74 @@
+---
+kind: reference
+audience: consumers
+---
+# Native settings
+
+A consuming repository puts each setting in the file its tool reads.
+
+## Settings by file
+
+| 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-suppressions.json` | The existing violations oxlint suppresses, per file and rule | oxlint and `checks-suppressions-ratchet` |
+| `.jscpd.json` | The `path` and `ignore` globs of the files repetition is measured in | jscpd and `checks-repetition` |
+| `tsconfig.json` | Effect language service scope and severity | 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` |
+
+Every page under `docs/` names its mode in `kind` front matter, whatever directory holds it.
+A page whose front matter sets `audience: consumers` names commands a consuming repository runs, so `checks-docs` does not hold them to this `package.json`.
+Every other living doc names commands this repository runs, and `checks-docs` holds each one to its `package.json`.
+
+## Consumer migration
+
+The following table maps the former fields to their owners.
+
+| Former field | New owner |
+| --- | --- |
+| `defaultBranch` | Git's `refs/remotes/origin/HEAD`, or the pull request base or event repository in CI |
+| `runsOn`, `gates.ci`, `gates.scheduled` | `runs-on` and `run` steps in `.github/workflows/*.yml` |
+| `gates.lint` | `checks-lint` runs every kit gate |
+| `commitIdentity.authors` | `author` and `contributors` in `package.json` |
+| `sources.production` | `path` and `ignore` in `.jscpd.json` |
+| `size.production`, `size.tests` | File overrides and native size rules in `.oxlintrc.json` |
+| `sources.effect.paths`, `sources.effect.exempt` | Overrides in `.oxlintrc.json` and `tsconfig.json` |
+| `sources.libraries` | `checks-vendor` arguments in the `prepare` script of `package.json` |
+| `docs.pages` | `kind` front matter on each page |
+| `docs.forConsumers` | `audience: consumers` front matter on each page |
+| `features`, `changeSignal`, `agentRules` | No active declarations used these fields |
+
+The kit has no general configuration manifest or generated workflow.
+`checks-ci-wiring` requires title lint on opened and synchronized pull requests.
+It also requires lint, build, typecheck and test for each of those scripts that `package.json` defines, and a clean git diff after a build.
+`checks-repetition` runs jscpd with the repository's own `.jscpd.json`, so its `path` and `ignore` globs decide which files are measured.
+
+## Size limits
+
+The size rules are plain oxlint rules at `error` in `.oxlintrc.json`, and `bun run lint` enforces them on the whole tree.
+A repository records its existing violations with `oxlint --suppress-all`, which writes them to `oxlint-suppressions.json`.
+`checks-suppressions-ratchet` refuses any count in that file that rises, so the recorded debt only falls.
+The kit's own `.oxlintrc.json` sets these limits for each size override, and a repository may copy them:
+
+<!-- generated size-limits: bun run build writes it from .oxlintrc.json, SIZE_RULES in scripts/size-rules.ts and scripts/doc-blocks.ts -->
+
+| Limits | oxlint rule | `effect-channel/**/*.ts`, `readability/**/*.ts`, `scripts/**/*.ts` | `tests/**/*.ts` |
+| --- | --- | --- | --- |
+| The most lines a file may hold, blank and comment lines counted | `max-lines` | 400 | 600 |
+| The most lines a function may span, blank and comment lines counted | `max-lines-per-function` | 100 | off |
+| The most statements a function may hold | `max-statements` | 30 | 50 |
+| The highest cognitive complexity a function may reach, a switch counted once | `readability/cognitive-complexity` | 15 | 15 |
+| The deepest a block may nest inside a function | `max-depth` | 4 | 4 |
+
+<!-- end generated size-limits -->
+
+## Related topics
+
+- [The Effect rules](effect-rules.md)
+- [The CI wiring check](../gates/checks-ci-wiring.md)
+- [The suppressions ratchet](../gates/checks-suppressions-ratchet.md)

package/docs/configs/typescript-rules.md

@@ -1,3 +1,7 @@
+---
+kind: reference
+audience: consumers
+---
 # 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.

package/docs/design.md

@@ -1,32 +1,30 @@
+---
+kind: explanation
+---
 # Why it is shaped this way
 
 Each entry below is a choice in the kit's shape and the constraint that forced it.
 
 - Every config in an oxlint `extends` chain brings its own `plugins`, and one that sets none brings oxlint's default plugins, whose category rules the base's `categories` then turn on across the tree.
   `rules`, `categories` and `jsPlugins` inherit as expected.
-  That is why the consumer snippet restates `plugins` and nothing else, and why the generated fragment always sets them.
+  That is why the consumer config and each override restate `plugins`.
 - `node_modules/` is excluded through the consumer's `.gitignore`, not `ignorePatterns`: oxlint still walks the installed package when only `ignorePatterns` names it.
 - `files` in package.json is the published surface: `tests/`, `AGENTS.md` and the `.ts` plugin source never reach an install.
   npm adds `package.json`, `README` and `LICENSE` to the tarball whatever `files` says.
   `bun pm pack` builds the same tarball the registry serves, which is what the packed-tarball consumer e2e test installs.
-- The plugin ships compiled as `dist/index.js`, built with `bun build effect-channel/index.ts --outdir dist --target node --format esm`.
+- Each plugin ships compiled under `dist/`, built with `bun build <name>/index.ts --outdir dist/<name> --target node --format esm`.
   Node refuses to type-strip a `.ts` plugin under `node_modules`, so the `.ts` source would fail to load from an installed package.
-- `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.
-  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.
-  The base commit already holds that sum, so nothing is generated, committed or pruned.
-- `checks-repetition` writes the production files of both ends of the range to temporary directories and runs jscpd in each, so the consumer's `.jscpd.json` and ignore files never reach the count.
+- The size rules are plain oxlint rules at `error` in `.oxlintrc.json`, and `bun run lint` enforces them on the whole tree.
+  A repository records its existing violations with `oxlint --suppress-all`, and `checks-suppressions-ratchet` refuses any count that rises.
+  The kit runs no size script of its own, since restating how oxlint reads its config and compares sites left corners the native rules never had.
+  The suppression count lets a file or function already over its limit grow without a new site, which was accepted in exchange for dropping that script, and each repository is to work its counts down to zero.
+- `checks-repetition` writes both ends of the range to temporary directories and runs jscpd in each with the head's `.jscpd.json`, so its `path` and `ignore` globs decide the files at both ends.
   It compares each file's count of repeated lines rather than using jscpd's `--baseline-from-ref`.
   That flag reports a repeated block as new once its text changes, so a change that shortens a grandfathered block would fail.
 - `dist/` is committed.
   No `prepack` or `prepublishOnly` builds it, so a publish ships whatever bundle the publishing worktree holds.
   Rebuild it after pulling with `bun run build`.
-  `bun run build` also emits `quality.schema.json`, `templates/` and `CHANGELOG.md`, which are committed the same way.
+  `bun run build` also emits `templates/` and `CHANGELOG.md`, which are committed the same way.
   CI runs `git diff --exit-code` over the whole tree after the build, because a test that compares a generated file with its source passes on the copy the build just rewrote.
 - `CHANGELOG.md` is generated, so a release commit carries it and the tarball ships it.
   The commit that bumps package.json `version` closes its release, and the `v*` tag goes on that commit, so commits merged after it wait for the next release.
@@ -36,12 +34,13 @@ Each entry below is a choice in the kit's shape and the constraint that forced i
   A section keeps the date it was written with, since the squash merge that lands the release commit may fall on another day.
   Entries come from commit subjects, the squash-merged pull request titles commitlint holds to the conventional format.
   The bodies are the branch's own messages, which nothing lints.
-  The release path needs no `contents: write`: the changelog arrives in the release commit's pull request, not from a workflow that pushes.
-- `quality.json` is JSON, not TOML or a TypeScript module: a bun bin, a hook running without `node_modules`, a `.cjs` or `.mjs` config and `jq` all parse it with nothing installed, and nobody runs a repository's own code to learn its policy.
-  It holds declarations only.
-  The kit's bins read it directly.
-  oxlint and tsc read nothing but their own JSON, so they extend generated fragments, which `checks-quality --check` holds to the declarations.
-- `quality.json` refuses a key its schema does not name, so a kit that cannot enforce a newer key refuses it rather than let the repository believe it enforced.
+  The changelog still arrives in the release commit's pull request, not from a workflow that pushes.
+  The release path writes to the repository only through the `github-release` job's `contents: write`, which creates or updates the GitHub release from the tag's `CHANGELOG.md` section.
+- Workflow YAML owns CI execution, and the kit owns the required commands, but a repository is held only to the commands its own `package.json` can run.
+  `checks-ci-wiring` requires `bun run` with each of `lint`, `build`, `typecheck` and `test` that `package.json` defines as a script, `git diff --exit-code` when a `build` script exists, and commitlint always.
+  The target branch comes from git's own record in `refs/remotes/origin/HEAD`, or in CI from the pull request base or the default branch GitHub's event names, and never from a guess at the workflow files, and `checks-lint` starts its local range from the same branch.
+  Oxlint and TypeScript read their own overrides directly, so the consumer can change a rule where its tool reads it.
+  The Effect scopes occur in two native files, and the installed consumer test checks both independently.
 - The base parses with swc because typescript 7, which is tsgo, has no compiler API for dependency-cruiser to use.
   Without `@swc/core` installed the cruise silently skips every `.ts` file, so this repo's test asserts its own TypeScript is cruised.
 - `bunfig.toml` has no `extends` and no include: bun ignores an unknown top-level key in silence, so a preset cannot be inherited and the consumer's copy is compared key by key against the installed one instead.
@@ -52,11 +51,11 @@ Each entry below is a choice in the kit's shape and the constraint that forced i
   `@effect/platform-node-shared` is a direct dependency at the same exact version only to pin it: `@effect/platform-bun` asks for it with a `^` range, and a newer rc peers on a newer `effect` than consumers install, so all three move together.
 - Each runnable script ships a `checks-` bin entry, so consumer `package.json` scripts call the short name, which the package manager puts on `PATH` only there.
   A shell runs it through `bun run`, which never falls back to the registry the way `bunx` does.
-  The `.ts` checks keep a `bun` shebang, which needs no build step and no `dist/` entry, unlike the oxlint plugin that node loads.
+  The `.ts` checks keep a `bun` shebang, which needs no build step and no `dist/` entry, unlike the oxlint plugins that node loads.
 - `checks-lint` runs each gate as its own bin in a child process rather than importing it, so a gate behaves the same called alone or through the entry point, and `lint-coverage.sh` stays a shell script.
   The gates run one at a time with their output passed straight through, so each report reads whole and in the table's order.
-- A gate selection is checked against the repository's contents rather than trusted, so it cannot skip a gate that applies.
-  ci-wiring does that check, which is why a selection without it, or without another gate that applies everywhere, is refused as `checks-lint` reads it: nothing would check the selection otherwise.
+- `checks-lint` determines applicable gates from tracked files instead of accepting a repository selection.
+  A TypeScript gate starts running as soon as TypeScript source is tracked.
 - `checks-test` runs bun itself rather than reading a report some other run left: a skip taken only on CI is visible only in CI's own run, and an earlier run's report may be stale or narrowed.
   It reads the JUnit report bun writes to a temporary directory, since bun has no other per-test output meant for a program.
 - `checks-ci-wiring` runs inside `lint`, not in a workflow of its own: deleting the step that runs a check is the violation it catches, so the local `lint` is where it has to fail.
@@ -75,9 +74,9 @@ Each entry below is a choice in the kit's shape and the constraint that forced i
   That is the entry-point and layer recipe under Boundaries in [The dependency rules](configs/dependency-rules.md).
 - The templates in `templates/` are rendered from `scripts/doc-templates.ts`, the spec `checks-docs` reads.
   A template written by hand beside the check agrees with it only until someone edits one of them.
-- A page's Diátaxis mode is declared in `quality.json` rather than read from the page.
-  Whether a page teaches, walks a task, describes or explains is a judgment no program makes, so the repository states it once and the check holds the page to it.
-- `checks-docs` holds a doc file to its template when a change touches it, the way `checks-size-budget` holds a file to its budget.
+- A page's Diátaxis mode comes from `kind` front matter on the page, whatever directory holds it.
+  The repository makes the judgment beside the page, and the check holds it to that template.
+- `checks-docs` holds a doc file to its template when a change touches it, the way `checks-comment-gate` judges the comments a change adds.
   A repository adopts the templates as its files change, and an untouched file is listed as advisory rather than failing a change that never read it.
 - A task heading is verb first, and review holds it there rather than the check.
   No word list tells `Test layout` from `Test the layout`, and a check that passes the noun is worse than none.
@@ -95,8 +94,8 @@ Each entry below is a choice in the kit's shape and the constraint that forced i
   A reference goes stale when the code it names moves far more often than when its own line is edited, so a gate on edited lines alone would miss the usual break.
 - A path under a top directory the repository lacks names a file in another repository, such as a consumer's, and no program tells that from a typo.
   A directory the range deletes still counts as this repository's, so a path under it reads as stale rather than foreign.
-- The command check passes over the docs a repository declares under `docs.forConsumers`.
-  This kit's README and reference pages speak to a consuming repository, whose scripts are not this one's, and no program tells an example for a consumer from an instruction for a contributor.
+- The command check passes over a page whose front matter sets `audience: consumers`.
+  Such a page speaks to a consuming repository, whose scripts are not this one's.
 
 ## Related topics
 

package/docs/gates/checks-backtest.md

@@ -1,3 +1,7 @@
+---
+kind: reference
+audience: consumers
+---
 # checks-backtest
 
 `checks-backtest` is the report of what the comment check would have refused at each recent commit, and a reader looks it up to measure a repository's own history before adopting the check.