@shivaedev/quality 0.18.0 → 0.19.0

package/docs/rules.md

@@ -0,0 +1,308 @@
+# Rule reference
+
+Use the [README](../README.md) for the gate's mental model and workflow. Quality owns the shared policy; consuming repositories adopt its defaults. This reference gives each built-in rule's scope, findings and accepted options, including the exposed local-rule API. An option being accepted is not a recommendation to tune the shared standard. Supply repository facts, such as generated locations and import boundaries, when a check needs them. The [naming reference](./naming.md) covers names and test layout; [shared tooling](./tooling.md) covers the Biome, Vitest and TypeScript setup.
+
+## File size
+
+`structure/max-lines` keeps each module to one job: a source file may have 150 lines and [test code](./naming.md#test-code) 300, counted the way an editor numbers them. Declaration files are exempt. Its options are `source` and `test`: positive integer limits no greater than 150 and 300 respectively. Test code is identified by its conventional name or `test-support` folder; custom test-file patterns are rejected. A file over its limit counts one violation for each line above it: 168 lines under a limit of 150 count 18.
+
+### Comments
+
+A comment says why, never what the code already says or what it used to be. Seven rules hold every comment to that:
+
+| Rule | Reports | Options |
+| --- | --- | --- |
+| `comments/no-jsdoc` | Every `/** */` block, except a tool pragma the config allows | `allow` |
+| `comments/no-line-reference` | A line number: `file.ts:42`, `file.ts#L42`, `line 42` | none |
+| `comments/no-pr-reference` | A pull request or issue: `#123`, `PR 123`, `MR 123`, `pull request 123`, `merge request 123`, `issue 123`, `ticket 123`, `/pull/123`, `/pulls/123`, `/issues/123`, `/merge_requests/123`, `GH-123` | none |
+| `comments/no-banner` | A banner, divider or region: a line that starts or ends with three or more of `- = * # ~ _ + / \ ─ ━ ═ ┄ ┈`, `#region`, `#endregion` | none |
+| `comments/no-todo` | `TODO`, `FIXME`, `XXX` and `@todo` | none |
+| `comments/no-environment-pragma` | A test environment set by a `@vitest-environment` or `@jest-environment` pragma (and its `-options`); name the file `*.dom.test.ts` instead, see [Vitest projects](./tooling.md#vitest-projects) | none |
+| `comments/max-per-file` | A file with more than `max` comments, 2 by default | `max` (an integer from 0 to 2), `allow` |
+
+The rules find comments with the TypeScript parser, so text inside strings, template literals, regular expressions and JSX never counts as a comment. They read the TypeScript and JavaScript modules among the sources and skip declaration files and the directives listed below. Each finding names the line its comment starts on.
+
+Write a comment only for what the code cannot show, such as a constraint or a reason. The default limit of two comments is a tripwire against runaway commentary, not a budget to fill.
+
+`comments/max-per-file` counts comments this way:
+
+- A block comment counts once, however many lines it spans.
+- Line comments that each stand alone on adjacent lines form one run and count once. A blank line, code, a directive, or a comment after code on the same line starts a new one.
+- Allowed tool pragmas and directives are not counted: compiler and linter directives (`@ts-…`, triple-slash directives such as `/// <reference …>`, `biome-ignore…`, `eslint-disable…`, `eslint-enable…`, `oxlint-…`, `stylelint-…`, `deno-lint-ignore…`, `tslint:disable…`, `prettier-ignore`, Flow's `$FlowFixMe`, `$FlowIgnore`, `$FlowExpectedError`, `$FlowIssue` and `@noflow`), bundler annotations (`#__PURE__`, `@__PURE__`, `#__NO_SIDE_EFFECTS__`, `@__NO_SIDE_EFFECTS__`) and coverage hints (`c8 ignore`, `v8 ignore`, `istanbul ignore`). The suppression rules below report the directives that silence a check.
+
+A file over the limit counts one violation for each comment above it: 5 comments against a limit of 2 count 3. A finding names the first comment over the limit.
+
+A tool pragma is a comment whose every line starts with an allowed tag, such as `/** @jsxImportSource preact */`. `allow` lists the tags and is empty by default, so a pragma counts as a comment until the config allows its tag. Settings that a pragma would repeat in each file belong in the tool's config. `comments/no-jsdoc` and `comments/max-per-file` each take their own list, so give both the same one:
+
+```ts
+const pragmas = ["@jsxImportSource", "@license"];
+
+export default defineConfig({
+	rules: {
+		"comments/no-jsdoc": { options: { allow: pragmas } },
+		"comments/max-per-file": { options: { allow: pragmas } },
+	},
+});
+```
+
+A repository with existing comments adopts the rules through the baseline, for example `quality baseline write --rule comments/no-jsdoc --rule comments/max-per-file`.
+
+### Suppressions
+
+A check that is silenced at one site hides the problem instead of fixing it. Five rules close the escape hatches, and none of them takes registry exceptions: a registry entry that names one fails the gate as stale. A repository with existing suppressions adopts the rules through the baseline.
+
+| Rule | Reports | Options |
+| --- | --- | --- |
+| `suppressions/no-inline` | Every comment directive that silences a linter, the compiler or a formatter, except `@ts-expect-error` in a type test | none |
+| `suppressions/no-double-cast` | A cast through `unknown`, `any` or `never`: `x as unknown as T`, `x as any as T`, `x as never as T`, `<T><unknown>x` | none |
+| `suppressions/biome-overrides` | A Biome setting that turns a check off or down, or keeps files out of it, without a declaration, and a declaration that matches no setting | `declared` |
+| `suppressions/biome-recommended` | A rule the installed Biome recommends that the [Biome preset](./tooling.md#biome-preset) neither sets to `error` nor declares | none |
+| `suppressions/no-ignore-deprecations` | `compilerOptions.ignoreDeprecations` in a tsconfig, which silences TypeScript's errors for deprecated options | none |
+
+`suppressions/no-inline` reports these directives, wherever a line of a comment starts with one:
+
+- Biome: `biome-ignore`, `biome-ignore-all` and `biome-ignore-start`, for lint, assist and format alike. The `biome-ignore-end` that closes a range is not reported again.
+- TypeScript: `@ts-ignore`, `@ts-expect-error` and `@ts-nocheck`. `@ts-check` turns checking on and is allowed.
+- Other linters: `eslint-disable`, `eslint-disable-line`, `eslint-disable-next-line` and inline rule settings such as `/* eslint no-console: "off" */`; the same `-disable` forms of `oxlint` and `stylelint`; `deno-lint-ignore` and `deno-lint-ignore-file`; `tslint:disable…`.
+- Formatters: `prettier-ignore`, since `prettier --check` fails on the code it skips.
+- Flow: `$FlowFixMe`, `$FlowIgnore`, `$FlowExpectedError`, `$FlowIssue` and `@noflow`.
+
+Coverage hints (`c8 ignore`, `v8 ignore`, `istanbul ignore`) are allowed: they leave code out of a coverage measure and silence no linter or compiler. The rule reads the TypeScript and JavaScript modules among the sources, declaration files included, and every `.css`, `.scss` and `.less` file among the checked files, whatever `extensions` says. Each finding names the line its comment starts on and has the directive as its subject.
+
+`suppressions/no-ignore-deprecations` reads every JSON file in the repository whose `compilerOptions` sets `ignoreDeprecations`, whatever the file is named, so a shared config such as `tsconfig/base.json` counts as much as a `tsconfig.json`. Like `manifests/sorted`, it walks the whole repository, not only the sources, and skips untracked files ignored by git and `node_modules`. Each finding names the line of the setting. Replace the deprecated option it hides, then remove it.
+
+#### Type tests
+
+A type test proves that an API rejects what its types forbid, and TypeScript asserts a compile error only through `@ts-expect-error`, which fails as soon as the error it expects goes away. So `@ts-expect-error`, and no other directive, is allowed in a type test: a file named `*.typecheck.test.ts`, `*.typecheck.spec.ts` or `typecheck.test.ts` (or `.tsx`). The compiler checks these files; [Vitest projects](./tooling.md#vitest-projects) never run them. `@ts-ignore`, `@ts-nocheck` and every linter and formatter directive stay reported in them. A test that must pass a rejected value at run time, to prove the runtime refuses it too, calls the API through `Reflect.apply` instead of a directive.
+
+`suppressions/no-double-cast` finds casts with the TypeScript parser, through parentheses and in either assertion syntax. A single cast is left to the linter, and `as const` is not a cast.
+
+#### Declared Biome overrides
+
+Consumer declarations cover one lint rule or assist action on explicit file paths, with a reason. Globs, whole checks and rule groups cannot be declared. A `files/includes` declaration must retain `**` and add only negative patterns naming a concrete directory, such as `!**/test-support/generated`. These patterns may start with `**/` and use `*` for an intermediate directory, as in `!**/test-support/*/generated`. Every other segment names a directory without dots except an optional leading dot; the final segment must be a name. File patterns, nested `**` and wildcard suffixes are rejected. Shipped preset declarations describe Quality's internal policy and are not subject to the consumer scope restriction.
+
+Quality ships reasons for its own internal Biome exceptions. Extend the shared configuration and use the baseline for debt. `suppressions/biome-overrides` reads `biome.json` or `biome.jsonc` at the root, every nested `biome.json` and `biome.jsonc` among the checked files, and the configs each of them `extends`, resolved the way Biome resolves them (see [Shared presets](#shared-presets)). These settings count as overrides, at the top level and in every `overrides` entry:
+
+| Setting | Detected as |
+| --- | --- |
+| A lint rule at `off`, `warn` or `info`, as a string or a `level` | `lint/<group>/<rule>` |
+| A lint group at `off`, `warn` or `info`, or with `recommended: false` or `preset: "none"` | `lint/<group>` |
+| `linter.rules` with `recommended: false` or `preset: "none"` | `lint/recommended` |
+| A domain at `none` | `lint/domains/<domain>` |
+| `linter.enabled: false` | `lint` |
+| An assist action at `off`, such as `useSortedKeys` or `organizeImports` | `assist/<group>/<action>` |
+| `assist.actions` with `recommended: false` or `preset: "none"` | `assist/recommended` |
+| `assist.enabled: false` | `assist` |
+| `formatter.enabled: false` | `format` |
+| `enabled: false` in a language's `linter`, `assist` or `formatter`, such as `css.linter` | `<language>/lint`, `<language>/assist`, `<language>/format` |
+| An `includes` list in `files`, `linter`, `assist` or `formatter` that excludes a pattern with `!` or lacks `**` | `files/includes`, `lint/includes`, `assist/includes`, `format/includes` |
+
+Biome runs assist actions, key sorting among them, as part of `biome check` and reports what they would change, so turning one off is an override. Formatter options such as `indentStyle` or `lineWidth` choose a style, not an exception, and are not overrides. Settings that raise a rule or enable it are not overrides either. Rule options are not read, so an option that loosens a rule, such as a higher complexity limit, is left to review.
+
+```ts
+export default defineConfig({
+	rules: {
+		"suppressions/biome-overrides": {
+			options: {
+				declared: [
+					{
+						rule: "lint/style/noDefaultExport",
+						includes: ["scripts/tool.config.ts"],
+						reason: "Tools load their config files through the default export.",
+					},
+					{
+						rule: "lint/suspicious/noConsole",
+						includes: ["scripts/report.ts"],
+						reason: "Scripts report to the terminal they run in.",
+					},
+				],
+			},
+		},
+	},
+});
+```
+
+A declaration covers a setting when its `rule` and its `includes` match the setting's exactly, in any order. An `includes` list that keeps files out is declared as the whole list, so every pattern added to it needs the declaration to change too. A setting at the top level of the root config has the scope `["**"]`, and an `overrides` entry has its own `includes` (`["**"]` when it has none). Paths in a nested config are relative to its folder, so a rule scoped to `"src/a.ts"` in `packages/web/biome.json` is declared as `"packages/web/src/a.ts"`. Top-level and globbed rule scopes cannot be declared by consumers. A setting without a declaration is reported at its line in the Biome config; a declaration that no setting matches is reported against the root config, so the list cannot outlive the overrides it explains.
+
+#### Shared presets
+
+A config `extends` its entries the way Biome does:
+
+- An entry that starts with `./` or `../` is a file next to the config. Any other entry is first a file at the repository root, then a package in the root's `node_modules`, resolved through its `exports` (with the `biome` and `default` conditions, and `*` patterns), then its `main`, then a file inside it. A package may also name itself through the repository's own `package.json` `exports`. `"//"` in a nested config extends the root config, which is read on its own.
+- Biome reads only the entries of the config it loads: the `extends` of an extended config are not followed, so they are not read here either.
+- The extended configs apply from left to right and the config itself last. A later setting of a rule, a group, `recommended` or `enabled` replaces an earlier one, so a preset's weakening that the repository sets back to `error` is no override. A group set as a whole (`"suspicious": "error"`) replaces the settings of its rules; a rule set inside a group the preset turned off leaves the rest of the group off.
+- Lists are appended, not replaced: `overrides`, `plugins` and every `includes` list, `files.includes` among them. A repository's `files.includes` adds to the preset's, so each list is declared by whoever wrote it.
+- Patterns in an extended config resolve against the repository root, or against the folder of a nested config that extends it, as patterns in the config itself do.
+
+A package that ships a preset declares the weakenings the preset makes in a `declarations.json` beside the preset file, as an array of the same `{ rule, includes, reason }` entries the `declared` option takes. Its `includes` are written relative to the repository that extends the preset. Those weakenings count as declared, so the repository adds nothing for them:
+
+```json
+[
+	{
+		"rule": "lint/style/noDefaultExport",
+		"includes": ["**/*.config.ts"],
+		"reason": "Tools load their config files through the default export."
+	}
+]
+```
+
+A weakening the preset makes without such a declaration is reported at the line of the repository's `extends` entry, and the repository's own declaration covers it. A weakening the repository adds beyond the preset needs its own declaration, and a repository declaration that repeats one the preset ships is reported until it is removed. A preset entry that cannot be resolved or read, or whose `declarations.json` is invalid, is reported at the `extends` entry as well.
+
+#### Recommended Biome rules
+
+`suppressions/biome-recommended` holds the [Biome preset](./tooling.md#biome-preset) to every rule Biome recommends, so a Biome upgrade that adds a recommended rule, or recommends one the preset leaves below `error`, fails the gate until the preset takes a position on it. It asks the installed Biome, the one `quality` runs, which rules its `recommended` preset enables, through `biome rage --linter`, so the list is never written down. When the root Biome config extends `@shivaedev/quality/biome`, it reads that preset and its `declarations.json`, resolved from the repository root as under [Shared presets](#shared-presets); a repository that does not extend the preset is left to the `biome` rule, which asks for it. A recommended rule is in order when the preset's `linter.rules` sets it to `error`, directly or through its group's severity, or when a declaration names it, whatever the declaration's `includes`. Every other recommended rule is reported at the preset, one finding per rule: set it to `error` and repair the code it reports.
+
+### Imports
+
+Six rules check the imports of the TypeScript and JavaScript modules among the sources. `imports/cycles`, `imports/resolvable`, `imports/manifest`, `imports/no-test-code` and `imports/fences` with declared fences build a graph resolved by the TypeScript compiler. `imports/aliased` checks relative path syntax.
+
+| Rule | Reports | Options |
+| --- | --- | --- |
+| `imports/cycles` | Modules that import each other at run time | none |
+| `imports/resolvable` | An import that resolves to nothing | `generated` |
+| `imports/manifest` | A workspace import missing from the importing package’s shipped dependencies, or present only in `devDependencies` in shipped code | none |
+| `imports/fences` | An import that crosses a fence the config declares | `fences` |
+| `imports/aliased` | A relative import that leaves its own folder | none |
+| `imports/no-test-code` | A production module importing a test file or anything under `test-support/` | none |
+
+Each graph edge resolves the way the compiler resolves it, with the options of the nearest `tsconfig.json` and the projects it references, under bundler resolution: `paths`, `package.json` `imports` and `exports` and the `source` condition hold, so a workspace package resolves to its source. The graph reads literal specifiers in static and dynamic imports, `export ... from`, `require()`, `require.resolve()`, `import.meta.resolve()` of a bare specifier (a relative one is URL arithmetic that never checks the path), `import()` types, `/// <reference types>`, `/// <reference path>` and JSDoc `@import` tags. Computed specifiers are outside this check.
+
+- An import of a stylesheet, an image or JSON resolves to the file, and only when the file exists, whatever declaration describes it. A Node builtin resolves.
+- A runtime import must resolve to code: a declaration file (`.d.ts`, `.d.mts`, `.d.cts`, or an asset declaration such as `.d.css.ts`) satisfies only `import type` and `export type`, however the import reaches it, so a package that has only its `@types` package installed, or an `exports` entry that points at a declaration, is reported.
+- A bare import resolves when a declaration file of the importer's tsconfig project declares the module in a script (`declare module "virtual:*"`). A relative import always needs a real file, `declare module "*"` and patterns with more than one `*` never count, and a `declare module` inside a module is an augmentation, which declares nothing new.
+- A relative import or a `#` package import of a missing file resolves only inside a folder that `generated` names, such as a client a generator writes before the tests run. A `#` import lands where its `imports` entry in `package.json` points once the file exists. Each folder must be ignored by git, or at least every file an import names in it must be, hold no file git tracks but a `.gitkeep` or `.keep` placeholder, lie outside `node_modules` and hold a file that an import names. The import stays an edge to its path, so fences apply to it before the file exists.
+- A module that resolves into `node_modules` or outside the root is external, and its package is the one it resolves into, whatever alias the import uses. A `@types` package counts as the package it describes: `@types/hast` is `hast`, `@types/scope__name` is `@scope/name`.
+
+```ts
+import { defineConfig } from "@shivaedev/quality/config.ts";
+
+export default defineConfig({
+	rules: { "imports/resolvable": { options: { generated: ["packages/db/src/test-support/generated"] } } },
+});
+```
+
+`imports/cycles` reports each group of modules that import each other at run time once, at the alphabetically first of them, with one loop through the group. Its count is the number of modules in the group. `import type`, `export type`, type references and imports in declaration files are left out; `import { type X }` stays a runtime import. Dynamic `import()` and `require()` count; `require.resolve()` does not. It takes no registry exceptions. Each finding of `imports/resolvable` has the import as its subject.
+
+When the sources hold no module at all, the graph-building rules stop the run instead of passing on an empty graph. Point `sources` at the code; do not disable the checks to conceal an empty inventory. `imports/aliased` does not require a graph, and `imports/fences` does nothing when no fences are declared.
+
+#### Runtime folders
+
+`imports/runtime` adopts a package automatically when it has `src/client/` or `src/server/`, including folders outside `sources`. In an adopted package, code in `src/client/` is browser code, code in `src/server/` is server code, and code anywhere else is shared. A package without either folder retains its existing policies. Existing explicit fences keep running in either case.
+
+Client code may not import server code or Node built-ins. Shared code may import neither client nor server code and may neither import Node built-ins nor use browser globals. Client and server code may import shared code. The rule uses the resolved import graph, including type imports, re-exports, dynamic imports and literal `require()` calls; missing file targets still carry their runtime folder. Test files and `test-support/` are outside the shipped runtime policy.
+
+Browser-global checks report direct, shorthand and literal `globalThis` property uses, with lexical bindings respected. Property names, comments, strings and type annotations do not count as global value uses. Browser-specific globals come from TypeScript's DOM declarations, excluding the standard web APIs that Node also supplies. Worker browser APIs such as `indexedDB` and `caches` remain browser globals. Portable web APIs such as `URL`, `fetch` and `AbortController` remain available to shared code. This is a static source check, not proof of a deployment's runtime behavior. Each finding has the imported specifier or browser global as its subject. Move runtime-dependent code to its runtime folder or pass a value into shared code.
+
+#### Manifest dependencies
+
+`imports/manifest` discovers named workspace members from `pnpm-workspace.yaml` or the root manifest's `workspaces`, with no package scope convention or fence configuration. It discovers manifests across the repository, independently of `sources`, skipping files ignored by git and `node_modules`. Selecting only a member's `src` folder still checks its imports of members outside that selection against its own manifest. Each import of another member must appear in the importing member's `dependencies`, `peerDependencies` or `optionalDependencies`. The workspace root uses its own manifest for code outside a member. Self-imports and packages outside the workspace do not need a workspace declaration under this rule.
+
+Tests and files under `test-support/` may also use `devDependencies`. Tooling means files under a `script/`, `scripts/` or `tooling/` folder directly below the importing package's root, or a config file directly at that root, named `config.ts`, `vitest.config.ts` or another `*.config.*` with a JavaScript or TypeScript extension. A folder or config file nested under `src/` still counts as shipped code. Source modules explicitly blocked by a null package export may use development dependencies when no runtime module reaches them in the scanned import graph. A more specific public export, an export under another name or an executable entry point keeps its imports in the runtime boundary. The rule follows imports, re-exports and type references through blocked helpers; a blocked public subpath alone cannot hide a runtime dependency.
+
+The rule checks type imports as well as value imports. Resolved aliases and relative paths use the target's workspace owner; unresolved bare package names and subpaths still require a declaration. A nested manifest that is not a workspace member does not replace its owner's dependency policy. Malformed dependency objects stop the run. Add the dependency to the correct manifest field or remove the import; the rule does not edit manifests.
+
+#### Aliases
+
+A relative import names only a file in its own folder, such as `./format.ts`: the folder is one module. Every other import goes through an alias, so moving a file never rewrites a chain of `../`:
+
+- the `imports` of the importer's nearest `package.json`, such as `"#lib/*": "./src/lib/*"`, or `"#shared/*": "@demo/shared/*"`, which names another workspace package;
+- the name of another workspace package, as far as its `exports` reach.
+
+An import that already goes through a tsconfig `paths` alias is not relative, so the rule leaves it alone.
+
+`imports/aliased` reports a relative import that goes up (`../format.ts`) or down into a subfolder (`./parts/deeper.ts`, or `./widgets` for `widgets/index.ts`). It reads literal specifiers in static imports, `export ... from`, side-effect imports, `import()`, `require()`, `import()` types, JSDoc `@import` tags and the paths of `vi.mock`, `vi.doMock`, `vi.unmock`, `vi.doUnmock`, `vi.importActual` and `vi.importMock`, so a mock keeps pointing at the module it replaces. An escaped path, such as `"\x2e\x2e/format.ts"`, counts as the path it spells. Each finding has the import as its subject. Its message names the fix for where the import lands:
+
+- inside its own package: import through a `#` alias from the `imports` of the package's `package.json`, and declare one if none fits;
+- inside another workspace package: import it by that package's name, through a path its `exports` lists;
+- inside an installed package under `node_modules`: import that package by its name.
+
+The rule only reports; nothing rewrites the import. Whoever writes the import picks the alias, because only they know which conditions their runtimes, bundler and tests use.
+
+#### Fences
+
+A fence is one prohibition. A package declares stronger promises than its manifest in `quality.fences.config.ts` beside `package.json`. Quality discovers this file at the root and in workspace members without a root-config list, independently of the source inventory:
+
+```ts
+import { external, folders, packages } from "@shivaedev/quality/imports/fences/selectors.ts";
+import { fence } from "@shivaedev/quality/imports/fences/dsl.ts";
+
+const fences = [
+	fence("ui-never-imports-server")
+		.because("The UI ships to browsers.")
+		.from(folders("packages/ui/src"))
+		.mayNotImport(packages("server"))
+		.demonstratedBy({
+			illegal: ["packages/ui/src/app.ts", "packages/server/src/db.ts"],
+			legal: ["packages/ui/src/app.ts", external("effect")],
+		}),
+];
+
+export default fences;
+```
+
+A fence has a name, a reason, the modules it holds (`from`) and one prohibition:
+
+- `mayNotImport(target)`: no module it holds imports the target.
+- `mayNotReach(target)`: nothing a module it holds imports, directly or through other modules of the repository, is the target. The finding names the path.
+- `mayImportOnly(...subjects).of(unit)`: the modules it holds import only the named modules or folders directly in a package's `src` folder (or the package folder) or in a folder.
+
+Targets are `packages(...)` (workspace packages by name, with or without their scope; a workspace package is a named `package.json` that `pnpm-workspace.yaml` or the root `package.json` `workspaces` includes, with `*`, `**`, `?`, `{a,b}` and `[...]` in its patterns, none of which match a folder whose name starts with `.` unless the pattern spells the dot, and a `packages` list or pattern the gate cannot read stops the run, and it holds every file below it that no deeper workspace package holds), `folders(...)`, `files(...)`, `modules(...)` (external packages by package name, and Node builtins), `scopes(...)` (every external package of a scope), `anyOf(...)`, `workspace` (every workspace package) and `anything`. Each takes `.except(...)`.
+
+The DSL does not compile without `demonstratedBy`, and the rule checks the examples against the combined discovered and config-supplied policy: each is a chain of imports from a file of the repository, which may end in `external(name)`. The illegal example must cross this fence and no other; the legal example must cross none. Every name a fence uses must exist: a package, a folder that holds checked files, a checked file, a subject of the unit. Two fences may not share a name, and each needs a reason. A policy that breaks any of this stops the run. Fences count type imports too.
+
+Fences guard shipped code, and [test code](./naming.md#test-code) ships nowhere, so a fence never holds it: a test file or a file under `test-support/` may import across every fence. There is no option to check them.
+
+A finding has its fence's name as its subject, so a registry entry with that subject excuses one file from one fence.
+
+`imports/no-test-code` checks every file edge from a production module to a test file or a file under `test-support/`, including type imports, re-exports and test assets. It rejects missing relative paths under `test-support/` too. Test importers may still import production code and other test code. Move shared code into a production module and import it from both production and tests. The rule takes no registry exceptions.
+
+### Manifests
+
+`manifests/sorted` keeps every `package.json` in the repository in the key order of [sort-package-json](https://github.com/keithamus/sort-package-json), a dependency of this package. It walks the whole repository, not only the sources, and skips untracked files ignored by git and `node_modules`. A manifest that is not valid JSON is reported too. `quality fix` sorts the manifests, and the rule takes no registry exceptions.
+
+## Local-rule API
+
+The API allows a local rule to receive checked source text and return findings. This is an extension reference, not a step every repository must complete; reusable quality policy belongs in the shared package. This example is the same text-scanning rule exercised by the package's CLI tests:
+
+```ts
+import { defineRule } from "@shivaedev/quality/rule.ts";
+
+export const noLog = defineRule({
+	check: ({ sources }) =>
+		sources
+			.filter((file) => file.text.includes("console.log"))
+			.map((file) => ({ file: file.path, message: "logs to the console." })),
+	description: "Log through the logger.",
+	id: "local/no-console-log",
+});
+```
+
+It reports a file whose text contains `console.log`; it does not parse calls or distinguish a string from code. Use a syntax-aware check when the policy needs that distinction. Register it in the config:
+
+```ts
+import { defineConfig } from "@shivaedev/quality/config.ts";
+import { noLog } from "./quality/noLog.ts";
+
+export default defineConfig({ local: [noLog], sources: ["src"] });
+```
+
+`check` may return findings directly or asynchronously. For options, provide a [Standard Schema](https://standardschema.dev) validator; the check receives the decoded result. An absent options object is validated as `{}`, so defaults belong in the schema:
+
+```ts
+import { Effect, Schema } from "effect";
+import { defineRule } from "@shivaedev/quality/rule.ts";
+
+const Limit = Schema.Struct({
+	max: Schema.Int.pipe(Schema.withDecodingDefaultKey(Effect.succeed(2))),
+});
+
+export const limited = defineRule({
+	check: async ({ files, options }) =>
+		files.length > options.max ? [{ file: ".", message: `${files.length} files exceed ${options.max}.` }] : [],
+	description: "Keep the repository small.",
+	id: "local/max-files",
+	options: Schema.toStandardSchemaV1(Limit, { parseOptions: { onExcessProperty: "error" } }),
+});
+```
+
+This is the option-bearing rule the package tests. It defaults to two files and validates a configured `max` before the asynchronous check runs. A rule without an options schema refuses options. Set `registrable: false` when a rule must never be excused by a registry entry.

package/docs/tooling.md

@@ -0,0 +1,120 @@
+# Shared tooling
+
+Quality's shared policy includes Biome and TypeScript configuration and Vitest project helpers alongside the gate. These connect the native tools to one opinionated set of conventions; consumers do not need to choose a rule set for each tool. Use the [README](../README.md) to configure the gate; use this page to wire the tools that check, format, compile and run the repository.
+
+## Biome preset
+
+`@shivaedev/quality/biome` supplies the shared Biome configuration. Quality includes and runs Biome; the root `biome.json` extends the shared configuration:
+
+```json
+{
+	"$schema": "./node_modules/@biomejs/biome/configuration_schema.json",
+	"extends": ["@shivaedev/quality/biome"]
+}
+```
+
+The preset sets:
+
+- **Formatting:** tabs, a line width of 150, double quotes, semicolons, trailing commas and operators at the start of a wrapped line. An object key keeps its quotes, because a quoted key marks a [foreign name](./naming.md#foreign-names).
+- **Lint:** recommended rules are set to `error` or explained in the preset's declarations. Stricter settings include `noUnsafeTypeAssertion`, `useBlockStatements`, `useNumericSeparators`, `useUnicodeRegex`, `useLiteralKeys`, `noFloatingPromises`, `useExhaustiveDependencies`, `useConsistentTestIt`, `noNonScalableViewport`, function declaration style, interface style, a cognitive complexity limit of 15, `noNestedTernary` and the [naming rules](./naming.md).
+- **Imports:** organized in five groups: Node and Bun builtins, packages, `@shivaedev/*` packages, aliases and relative paths. Biome counts as an alias a specifier that starts with `#`, `@/`, `~`, `$` or `%`; a tsconfig path such as `@app/*` sorts with the packages, and Biome's `noUndeclaredDependencies` takes it for one, so name aliases in a form Biome recognizes.
+- **Assist:** organized imports and checks for sorted keys, attributes, enum members, interface members and properties. The key-sorting check applies to JSON and object literals, but `quality fix` skips its fix. `package.json` is left out of that check because `manifests/sorted` supplies its key order.
+- **Plugins:** GritQL rules that ban ambient time, randomness, `console` and `process.env` for Effect's services, and the naming plugins under [Naming](./naming.md). They load from `./node_modules/@shivaedev/quality/biome/plugins`, so the package must be installed at the repository root.
+- Files ignored by git are skipped.
+
+The preset turns off `noUnusedVariables` and `noUnusedFunctionParameters`, because the tsconfig presets report them through TypeScript. It allows default exports in `*.config.*` files, which tools load through the default export, and turns off `useComponentExportOnlyModules` in `*.test.*` and `*.spec.*` files, where tests define their harness components.
+
+The preset reports `useSortedClasses` at `error` with its fix enabled for class attributes and calls to `cn`, `clsx` and `cva`. Tailwind output does not depend on the order of classes in an attribute, so sorting is safe.
+
+The preset sets `noDelete` to `off` because its fix changed behavior or did not finish on real code. `noUndeclaredClasses` is off because its class resolution does not cover aliases and Tailwind utilities; `noInlineStyles` is off because computed values need inline styles. Quality owns these choices and ships their reasons in `declarations.json`. They do not require consumer declarations. The exposed consumer-declaration API is described under [declared Biome overrides](./rules.md#declared-biome-overrides); use the shared defaults for adoption.
+
+The preset keeps the following rules at `error` with their fixes off so the author decides the repair: `noAccessKey`, `noAriaHiddenOnFocusable`, `noAutofocus`, `noInteractiveElementToNoninteractiveRole`, `noNoninteractiveElementToInteractiveRole`, `noNoninteractiveTabindex`, `noRedundantRoles`, `useValidAriaProps`, `useValidAriaRole`, `noImportantStyles`, `noConstAssign`, `noProcessGlobal`, `useJsonImportAttributes`, `noUnusedPrivateClassMembers`, `useExhaustiveDependencies`, `noFloatingPromises`, `noMisusedPromises`, `useExhaustiveSwitchCases`, `noEqualsToNull`, `useConsistentArrayType`, `useConsistentCurlyBraces`, `useConsistentTestIt`, `useRegexpTest`, `useUnicodeRegex`, `noNonNullAssertion`, `useAtIndex`, `noParametersOnlyUsedInRecursion`, `noSkippedTests` and `useNamingConvention`. The fix command also skips `noDuplicateObjectKeys` and `useSortedKeys`. Import `process` from `node:process` in Node code or use the application's Effect service. Write JSON imports with `with { type: "json" }` for Node 24; the fixer leaves both choices to the author.
+
+- `useConsistentArrayType`: its fix rewrites locally defined `Array<T>` and `ReadonlyArray<T>` types as built-in arrays; check the type binding before writing shorthand.
+- `useConsistentCurlyBraces`: its fix can replace escaped newlines in JSX strings with literal backslash text; preserve rendered text when removing braces.
+- `noMisusedPromises`: awaiting a promise changes timing, conditional results and rejection handling; make the callback contract accept its promise when the caller awaits it, or handle completion and rejection explicitly.
+- `useExhaustiveSwitchCases`: adding cases that fall through to default conflicts with `noUselessSwitchCase`; write every case with its intended result, preserving a default fallback where needed.
+- `noEqualsToNull`: replacing loose null equality with strict equality loses the `undefined` case; write explicit checks for both `null` and `undefined`.
+
+`noSkippedTests` has no automatic fix because enabling a skipped test can change which setup and bodies run; the author must repair the test or remove a claim it cannot prove.
+
+The `biome` rule runs `biome check` with the repository's config and reports each finding as `biome/<category>`, such as `biome/lint/style/useBlockStatements`, `biome/assist/source/useSortedKeys`, `biome/format` or `biome/plugin`, so Biome's findings go through the baseline like any other rule's. `quality baseline write --rule biome` takes in every Biome category at once. A finding below `error` is not reported; a consumer exception for an individual rule therefore needs an explicit file scope and a reason. Whole-check, group and blanket-scope declarations are rejected; see [configuration limits](../README.md#configuration-limits). The rule also asks for a root `biome.json` or `biome.jsonc` that extends the preset, and it takes no registry exceptions. A Biome config that Biome cannot load stops the run with Biome's message.
+
+`quality fix` sorts the discovered manifests, then runs `biome check --write --unsafe`, with the two skipped fixes above. It then runs Biome's formatter, because a lint fix can leave code unformatted. One fix can make room for another, so it repeats both passes until a round rewrites nothing, at most five rounds. When files still change in the fifth round, it names the changed text files it can discover and exits 2; when those files are outside its inventory, the error gives a verbose Biome command to name them. An unsafe fix can change behavior, such as `==` becoming `===`, so review what it changed.
+
+## Vitest projects
+
+`@shivaedev/quality/vitest.ts` sets up the tests of a package by file name, so no test file sets its environment with a pragma. It needs `vitest`, and `happy-dom` for DOM tests. A package's `vitest.config.ts` reads:
+
+```ts
+import { testProjects } from "@shivaedev/quality/vitest.ts";
+import { defineConfig } from "vitest/config";
+
+export default defineConfig({ test: testProjects() });
+```
+
+| Project | Files | Environment | Runs |
+| --- | --- | --- | --- |
+| `unit` | `*.test.ts`, `*.spec.ts` and the other test and spec files | Node | By default |
+| `dom` | `*.dom.test.tsx`, `*.dom.spec.tsx` and the other `.dom` files | happy-dom | By default |
+| `slow` | `*.slow.test.ts`, `*.slow.spec.ts` and the other `.slow` files | Node | Only with `vitest run --project slow` |
+
+Type tests (`*.typecheck.test.ts`, `*.typecheck.spec.ts` and `typecheck.test.ts`) are in no project: the compiler checks them. A test that is too slow for every run goes into the slow project instead of being skipped.
+
+`testProjects()` takes no options. Every conventionally named suite runs in its project regardless of its folder; exclusion options are rejected.
+
+### Inherited tags
+
+Vitest gives an inline project only the [tags](https://vitest.dev/guide/test-tags) it declares itself, never those of a config file it `extends`. A test tagged in that file then fails with `cannot apply "<tag>" tag for this test` as soon as a root config runs it. A root config that gathers the projects of several packages, or whose projects extend a shared base config, passes them through `inheritTags`:
+
+```ts
+import { inheritTags } from "@shivaedev/quality/vitest.ts";
+import { defineConfig } from "vitest/config";
+
+const bakery = { extends: "./packages/bakery/vitest.config.ts", root: "./packages/bakery", test: { name: "bakery" } };
+
+export default defineConfig(async () => ({ test: { projects: await inheritTags([bakery], import.meta.dirname) } }));
+```
+
+`inheritTags(projects, root)` loads the config file of each inline project whose `extends` is a path, resolved against `root`, and adds the tags that file declares to the project's own, so `vitest run --tags-filter=<tag>` works across the workspace. A tag the project declares itself wins over an inherited one of the same name. Config objects and config functions are supported. A project that extends `true`, and a glob or file path, comes back unchanged. The extended files load with Node's own `import`, so each must be a module Node runs without a bundler.
+
+## tsconfig presets
+
+Two presets supply a shared strict TypeScript setup for type-checking and package builds.
+
+| Preset | Use |
+| --- | --- |
+| `@shivaedev/quality/tsconfig/base.json` | Type-checking with `noEmit`: applications, tests and scripts. |
+| `@shivaedev/quality/tsconfig/package.json` | Building a package: the base plus `declaration`, `declarationMap`, `sourceMap` and `rewriteRelativeImportExtensions`, so relative `.ts` imports are emitted as `.js`. |
+
+```json
+{
+	"extends": "@shivaedev/quality/tsconfig/base.json",
+	"compilerOptions": {
+		"lib": ["ESNext", "DOM"],
+		"types": ["node"]
+	},
+	"include": ["src"]
+}
+```
+
+The base sets:
+
+- **Language:** `target` and `lib` are `ESNext`.
+- **Modules:** `module` ESNext, `moduleResolution` bundler, `moduleDetection` force, `verbatimModuleSyntax`, `isolatedModules`, `allowImportingTsExtensions`, `resolveJsonModule`, `noUncheckedSideEffectImports`, `forceConsistentCasingInFileNames` and `libReplacement: false`.
+- **JavaScript:** `allowJs` and `checkJs`, so JavaScript files are type-checked with the TypeScript ones.
+- **Erasable syntax only:** `erasableSyntaxOnly` rejects syntax that type stripping cannot erase, such as parameter properties.
+- **Checks:** `strict`, with `noImplicitAny`, `strictBuiltinIteratorReturn` and `useUnknownInCatchVariables` stated explicitly, `noUncheckedIndexedAccess`, `exactOptionalPropertyTypes`, `noImplicitOverride`, `noImplicitReturns`, `noFallthroughCasesInSwitch`, `noUnusedLocals`, `noUnusedParameters`, `allowUnreachableCode: false` and `allowUnusedLabels: false`.
+- **Compiler settings:** `stableTypeOrdering` and `skipLibCheck`.
+
+`noPropertyAccessFromIndexSignature` stays off, so a map-like key is read with dot access, and `isolatedDeclarations` stays off, so exported values keep their inferred types. `types`, `jsx`, `paths`, `include` and the output directories belong to each project. A project that needs more built-ins, such as the DOM, sets `lib` itself and keeps `ESNext` in it.
+
+A package that type-checks its tests with one config and builds `src` with another extends both, the package preset last:
+
+```json
+{
+	"extends": ["./tsconfig.json", "@shivaedev/quality/tsconfig/package.json"],
+	"compilerOptions": { "outDir": "dist", "rootDir": "src" },
+	"include": ["src"]
+}
+```

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@shivaedev/quality",
-  "version": "0.18.0",
+  "version": "0.19.0",
   "description": "Repository quality gate with typed rules, a baseline of existing debt and a registry of reasoned exceptions",
   "homepage": "https://github.com/ShivaeDev/platform/tree/main/packages/quality#readme",
   "bugs": {
@@ -32,7 +32,8 @@
     "./biome": "./biome/preset.json",
     "./tsconfig/base.json": "./tsconfig/base.json",
     "./tsconfig/package.json": "./tsconfig/package.json",
-    "./package.json": "./package.json"
+    "./package.json": "./package.json",
+    "./rules/imports/bundleInputs.ts": null
   },
   "bin": {
     "quality": "./dist/cli.js"
@@ -45,13 +46,14 @@
     "!src/**/*.spec.ts",
     "!src/**/test-support",
     "tsconfig",
+    "docs",
     "CHANGELOG.md",
     "README.md"
   ],
   "dependencies": {
-    "@biomejs/biome": "2.5.14",
+    "@biomejs/biome": "2.5.15",
     "@shivaedev/types": "0.2.0",
-    "ignore": "7.0.6",
+    "ignore": "7.0.12",
     "sort-package-json": "4.0.0",
     "typescript": "npm:@typescript/typescript6@6.0.2"
   },
@@ -59,7 +61,7 @@
     "@effect/platform-node": "4.0.0-rc.112",
     "@effect/platform-node-shared": "4.0.0-rc.112",
     "@effect/vitest": "4.0.0-rc.112",
-    "@types/node": "24.10.1",
+    "@types/node": "24.19.1",
     "@typescript/native": "npm:typescript@7.0.2",
     "effect": "4.0.0-rc.112",
     "vitest": "4.1.11"

package/src/biome/nativeEffectCall.ts

@@ -0,0 +1,45 @@
+import ts from "typescript";
+import type { Syntax } from "./syntax.ts";
+
+function importedFrom(node: ts.Node, module: string): boolean {
+	for (let current: ts.Node | undefined = node; current !== undefined; current = current.parent) {
+		if (ts.isImportDeclaration(current)) {
+			return !current.importClause?.isTypeOnly && ts.isStringLiteral(current.moduleSpecifier) && current.moduleSpecifier.text === module;
+		}
+	}
+	return false;
+}
+
+function effectNamespace(node: ts.Expression, checker: ts.TypeChecker): boolean {
+	if (!ts.isIdentifier(node)) {
+		return false;
+	}
+	return (checker.getSymbolAtLocation(node)?.declarations ?? []).some(
+		(declaration) =>
+			(ts.isImportSpecifier(declaration)
+				&& !declaration.isTypeOnly
+				&& (declaration.propertyName ?? declaration.name).text === "Effect"
+				&& importedFrom(declaration, "effect"))
+			|| (ts.isNamespaceImport(declaration) && importedFrom(declaration, "effect/Effect")),
+	);
+}
+
+export function nativeEffectCall(node: ts.Node, name: string, { checker }: Syntax): node is ts.CallExpression {
+	if (!ts.isCallExpression(node)) {
+		return false;
+	}
+	const callee = node.expression;
+	if (ts.isPropertyAccessExpression(callee)) {
+		return callee.name.text === name && effectNamespace(callee.expression, checker);
+	}
+	return (
+		ts.isIdentifier(callee)
+		&& (checker.getSymbolAtLocation(callee)?.declarations ?? []).some(
+			(declaration) =>
+				ts.isImportSpecifier(declaration)
+				&& !declaration.isTypeOnly
+				&& (declaration.propertyName ?? declaration.name).text === name
+				&& importedFrom(declaration, "effect/Effect"),
+		)
+	);
+}

package/src/biome/recognizeDiagnostics.ts

@@ -0,0 +1,67 @@
+import { resolve } from "node:path";
+import ts from "typescript";
+import { nativeEffectCall } from "./nativeEffectCall.ts";
+import type { Diagnostic } from "./report.ts";
+import { nodeAt, offsetOf, type Syntax, syntaxOf } from "./syntax.ts";
+
+const RECOGNIZED: ReadonlySet<string> = new Set(["lint/nursery/noComponentHookFactories", "lint/style/noDoneCallback"]);
+
+function generatorParameter(node: ts.Node): boolean {
+	const parameter = node.parent;
+	const callback = parameter.parent;
+	return (
+		ts.isParameter(parameter)
+		&& parameter.name === node
+		&& ts.isFunctionExpression(callback)
+		&& callback.asteriskToken !== undefined
+		&& ts.isCallExpression(callback.parent)
+		&& callback.parent.arguments.includes(callback)
+	);
+}
+
+function tagHandler(node: ts.Node, syntax: Syntax): boolean {
+	const property = node.parent;
+	if (!ts.isPropertyAssignment(property) || property.name !== node || !ts.isObjectLiteralExpression(property.parent)) {
+		return false;
+	}
+	const handlers = property.parent;
+	const call = handlers.parent;
+	return (
+		nativeEffectCall(call, "catchTags", syntax)
+		&& call.arguments.includes(handlers)
+		&& ts.isArrowFunction(property.initializer)
+		&& nativeEffectCall(property.initializer.body, "fail", syntax)
+	);
+}
+
+function misclassified(diagnostic: Diagnostic, syntax: Syntax): boolean {
+	const { start, end } = diagnostic.location;
+	const from = start === undefined ? undefined : offsetOf(syntax.source, start);
+	const to = end === undefined ? undefined : offsetOf(syntax.source, end);
+	const node = from === undefined || to === undefined ? undefined : nodeAt(syntax.source, from, to);
+	if (node === undefined) {
+		return false;
+	}
+	switch (diagnostic.category) {
+		case "lint/style/noDoneCallback":
+			return generatorParameter(node);
+		case "lint/nursery/noComponentHookFactories":
+			return tagHandler(node, syntax);
+		default:
+			return false;
+	}
+}
+
+export function recognizeDiagnostics(root: string, diagnostics: readonly Diagnostic[]): readonly Diagnostic[] {
+	const sources = new Map<string, Syntax>();
+	return diagnostics.filter((diagnostic) => {
+		const path = diagnostic.location.path;
+		if (!RECOGNIZED.has(diagnostic.category ?? "") || path === undefined) {
+			return true;
+		}
+		const file = resolve(root, path);
+		const syntax = sources.get(file) ?? syntaxOf(file);
+		sources.set(file, syntax);
+		return !misclassified(diagnostic, syntax);
+	});
+}