@shivaedev/quality 0.25.0 → 0.27.0

package/docs/roadmap.md

@@ -1,37 +0,0 @@
-# Roadmap
-
-This page owns Quality's shared policy, tooling, CLI and hook implementation status and the policy questions below. The [framework roadmap](https://github.com/ShivaeDev/platform/blob/main/docs/framework/roadmap.md) owns adoption across packages and hosts, integration and deployment validation; it links here for quality implementation work.
-
-## Built
-
-- [x] Error-only engine and report, with no CLI warning-report controls; old-debt adoption stays in the baseline.
-- [x] Optional typed and runtime-validated config with config-free defaults; built-in and local rules enforced at `error`; local-rule and Standard Schema option APIs; one checked inventory and one report grouped by rule.
-- [x] The public config rejects `warn`, `off`, raised thresholds, inventory exclusions and custom test-file patterns. Vitest projects reject suite exclusions. Reasoned Biome declarations cover individual rules on explicit files and named directory exclusions.
-- [x] A JSON Lines baseline with counted debt, explicit named-rule recording, lowering and pruning, tracked-move handling and preservation of unrelated lines.
-- [x] One reasoned config exception list for Quality and Biome, generated native Biome settings at lint and fix time, legacy migration, optional Quality subjects, stale entries and rules that refuse exceptions.
-- [x] File-size and comment rules; inline-suppression, double-cast, deprecation-setting and declared-Biome-override checks.
-- [x] A shared Biome preset and bridge whose error findings use the gate's baseline; enforcement of the installed Biome's recommended rules; bounded fix rounds and selected fixes left to the author.
-- [x] Static import resolution, rejection of production imports of test code, runtime-cycle checks, same-folder relative imports and direct, transitive and vocabulary fences with validated examples.
-- [x] Manifest sorting and identifier, file, folder, content, test-layout and story-setup conventions.
-- [x] Shared type-check and package-build TypeScript presets; Vitest unit, DOM and opt-in slow projects, excluded type tests and inherited project tags.
-- [x] Opt-in pre-commit hooks with per-worktree config and dependencies, conventional `typecheck` and `quality:commit` scripts, and explicit installation.
-- [x] Seeded-repository and real-command tests for the gate, import policies, Biome, baseline and git hooks, plus packed consumer checks for the CLI and presets.
-- [x] Separate shipped Biome declarations from consumer exceptions; reject whole-check, group and blanket-scope consumer declarations.
-- [x] Shared nesting-depth and index-module checks; Platform's catalog, manifest and Codecov checks use the local-rule API and the same inventory, report and baseline.
-
-## Next
-
-- [ ] Reduce policy-tuning inputs to the ones checks need about a repository. Thresholds can only be lowered; local-rule APIs remain exposed. Review the remaining extension boundary.
-- [ ] Split Grit implementation modules by the checks they own, without making consumers select competing presets; route Platform's remaining static checks through Quality.
-- [ ] Define the Effect-boundary rule's source and test scope before porting the repository's `try`/`async` restrictions.
-- [ ] Define the service-parameter policy before enforcing it against public helpers that accept services or `Context`.
-
-## Open questions
-
-The whole-policy direction is settled: Quality selects which checks run, and enabled checks should fail on uncovered findings; repositories adopt its defaults. The questions below concern how to implement that policy and where checks apply.
-
-- **Extension policy.** Which repository-specific local-rule APIs and Biome declarations should remain public? Consumer rule switches, raised limits and exclusions are rejected immediately with a migration fragment.
-- **Effect boundaries in tests.** Should tests follow the same Effect-only boundaries as shipped code, use a test-specific adapter scope, or remain exempt? The repository rule and test fixture patterns do not settle this policy.
-- **Services as parameters.** Should a rule cover only service implementation methods, allow explicit integration helpers, or require public APIs that accept services or `Context` to change? The maintainer owns those API decisions before a reusable rule can enforce them.
-- **Strict boolean expressions.** Should the preset enable Biome's nursery `useStrictBooleanExpressions`? It reports truthiness checks whose falsy cases differ, such as `if (value)` on `string | undefined`, where an empty string reads as missing. It has 63 findings across this repository, mostly in `work-fleet` and `work-board`, and some of them rely on `||` treating `""` as absent on purpose. The open choice is whether to adopt it with the existing findings in the baseline or fix them first, and whether to wait until Biome's reworked type inference behind the rule settles.
-- **Module exports.** The `./*.ts` export pattern makes implementation modules accessible alongside config, rules, fences and Vitest helpers. Which of those modules should consumers treat as extension APIs? Documentation lists the current exports; changing their public boundary requires a maintainer decision.

package/docs/rules.md

@@ -1,299 +0,0 @@
-# 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 structure
-
-### 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.
-
-### Nesting and module structure
-
-`nesting/max-depth` reports each source line that starts with eight or more tabs. Extract a named function or component. Declaration files are exempt; indentation with spaces is outside this text check. It takes no options.
-
-`structure/no-barrel` rejects every source module named `index.ts` or `index.tsx`, including modules that define their own exports. Name the module after its purpose. It takes no options. The shared Biome preset separately rejects re-exports regardless of the file name.
-
-### 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 exceptions: an exception 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 exceptions belong in `quality.config.ts`'s `exceptions` list, as `{ files, rules, reason, subject? }`. A single entry covers Quality rules and individual `biome/lint/<group>/<rule>` or `biome/assist/<group>/<action>` rules on explicit file paths. Quality applies the native Biome settings at lint and fix time; do not mirror them in `biome.json`. See [exceptions and upgrades](./debt-and-hooks.md#exceptions).
-
-Globs, whole checks and rule groups cannot be excepted. A `biome/files/includes` entry 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.
-
-A manual setting without a legacy declaration is reported at its line in the Biome config. The compatibility reader matches the old `{ rule, includes, reason }` declarations to settings with the same rule and exact scope, in any order, and reports stale or repeated declarations. Run `quality exceptions migrate` to replace both with the single config entry. A generated override never makes a checked-in manual override declared.
-
-#### 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 `{ rule, includes, reason }` entries. 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 must repair the preset or replace that setting with a config exception. 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 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 except package-root tooling. A package with a nonempty `bin` entry and no runtime folders is server code throughout; runtime folders take precedence over `bin`. A Node library without a CLI uses `src/server/`. `engines.node` alone does not identify Node-only code. Other packages retain their existing source policies. Existing explicit fences keep running in either case.
-
-Package-root tooling is server code in every package, including the workspace root: top-level `script/`, `scripts/` and `tooling/` folders and top-level JavaScript or TypeScript config files. A tooling folder or config file nested under `src/` follows the source runtime policy.
-
-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 config exception 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 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 exceptions.
-
-`manifests/source-first` reports each condition block in the `exports` or `imports` of a `package.json` that names the `source` condition after another condition, nested blocks included. TypeScript takes the first condition that matches, and `types` always matches, so once built output exists a block that lists `types` first sends TypeScript to the built declarations instead of the sources. Each finding names the line of the block. Move `source` to the top of it. Like `manifests/sorted`, the rule walks the whole repository and takes no 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 config exception.

package/docs/tooling.md

@@ -1,105 +0,0 @@
-# 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 config exception 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 lives in the config exceptions list with explicit files and a reason. Quality applies its Biome settings during lint and fix. 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 refuses legacy 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/testProjects.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/testProjects.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.
-
-## 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"]
-}
-```