@shivaedev/quality 0.21.0 → 0.22.0

package/docs/rules.md

@@ -49,7 +49,7 @@ A repository with existing comments adopts the rules through the baseline, for e
 
 ### 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.
+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 |
 | --- | --- | --- |
@@ -79,7 +79,9 @@ A type test proves that an API rejects what its types forbid, and TypeScript ass
 
 #### 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.
+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:
 
@@ -99,30 +101,7 @@ Quality ships reasons for its own internal Biome exceptions. Extend the shared c
 
 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.
+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
 
@@ -134,7 +113,7 @@ A config `extends` its entries the way Biome does:
 - 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:
+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
 [
@@ -146,7 +125,7 @@ A package that ships a preset declares the weakenings the preset makes in a `dec
 ]
 ```
 
-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.
+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
 
@@ -181,7 +160,7 @@ export default defineConfig({
 });
 ```
 
-`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.
+`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.
 
@@ -254,13 +233,13 @@ The DSL does not compile without `demonstratedBy`, and the rule checks the examp
 
 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.
+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 registry exceptions.
+`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 registry exceptions.
+`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.
 
 ## Local-rule API
 
@@ -307,4 +286,4 @@ export const limited = defineRule({
 });
 ```
 
-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.
+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

@@ -26,7 +26,7 @@ The preset turns off `noUnusedVariables` and `noUnusedFunctionParameters`, becau
 
 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 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.
 
@@ -38,7 +38,7 @@ The preset keeps the following rules at `error` with their fixes off so the auth
 
 `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.
+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.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@shivaedev/quality",
-  "version": "0.21.0",
+  "version": "0.22.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": {

package/src/biome/exceptionConfig.ts

@@ -0,0 +1,70 @@
+import { randomUUID } from "node:crypto";
+import { access, readFile, rm, writeFile } from "node:fs/promises";
+import { join } from "node:path";
+import { Schema } from "effect";
+import ts from "typescript";
+import type { ExceptionDeclaration } from "#exceptions/declaration.ts";
+
+function nativeOverride(files: readonly string[], rule: string): unknown {
+	const [, tool, group = "", name = ""] = rule.split("/");
+	const key = tool === "lint" ? "linter" : "assist";
+	const settings = tool === "lint" ? "rules" : "actions";
+	return { includes: files, [key]: { [settings]: { [group]: { [name]: "off" } } } };
+}
+
+export function exceptionConfig(declarations: readonly ExceptionDeclaration[]): {
+	readonly includes: readonly string[];
+	readonly overrides: readonly unknown[];
+} {
+	const includes = declarations.filter((entry) => entry.rules.includes("biome/files/includes")).flatMap((entry) => entry.files);
+	return {
+		includes: includes.length === 0 ? [] : ["**", ...includes.filter((pattern) => pattern !== "**")],
+		overrides: declarations.flatMap(({ files, rules }) =>
+			rules.filter((rule) => /^biome\/(?:lint|assist)\//u.test(rule)).map((rule) => nativeOverride(files, rule)),
+		),
+	};
+}
+
+export async function withExceptionConfig<TValue>(
+	root: string,
+	declarations: readonly ExceptionDeclaration[],
+	run: (args: readonly string[]) => Promise<TValue>,
+): Promise<TValue> {
+	const { includes, overrides } = exceptionConfig(declarations);
+	if (includes.length === 0 && overrides.length === 0) {
+		return run([]);
+	}
+	const name = `.quality-biome-${randomUUID()}.json`;
+	const path = join(root, name);
+	const config = await access(join(root, "biome.json")).then(
+		() => "biome.json",
+		() => "biome.jsonc",
+	);
+	const text = await readFile(join(root, config), "utf8");
+	const parsed = ts.parseConfigFileTextToJson(config, text);
+	if (parsed.error !== undefined) {
+		throw new Error(`Cannot load ${config}: ${ts.flattenDiagnosticMessageText(parsed.error.messageText, " ")}`);
+	}
+	const own = Schema.decodeUnknownSync(Schema.Record(Schema.String, Schema.Unknown))(parsed.config);
+	const files = Schema.is(Schema.Record(Schema.String, Schema.Unknown))(own.files) ? own.files : {};
+	if (
+		(own.files !== undefined && !Schema.is(Schema.Record(Schema.String, Schema.Unknown))(own.files))
+		|| (files.includes !== undefined && !Array.isArray(files.includes))
+		|| (own.overrides !== undefined && !Array.isArray(own.overrides))
+	) {
+		throw new Error(`Cannot merge exceptions into invalid ${config}: files, includes or overrides has the wrong shape.`);
+	}
+	const previousIncludes = Array.isArray(files.includes) ? files.includes : ["**"];
+	const previousOverrides = Array.isArray(own.overrides) ? own.overrides : [];
+	const generated = {
+		...own,
+		files: { ...files, includes: [...previousIncludes, ...includes.filter((pattern) => pattern !== "**"), `!${name}`] },
+		overrides: [...previousOverrides, ...overrides],
+	};
+	try {
+		await writeFile(path, JSON.stringify(generated), { flag: "wx" });
+		return await run([`--config-path=${path}`]);
+	} finally {
+		await rm(path, { force: true });
+	}
+}

package/src/biome/report.ts

@@ -1,5 +1,6 @@
 import { relative, sep } from "node:path";
 import { Schema } from "effect";
+import type { ExceptionDeclaration } from "#exceptions/declaration.ts";
 import { ignoredTrackedPaths } from "#inventory/trackedPaths.ts";
 import { recognizeDiagnostics } from "./recognizeDiagnostics.ts";
 import { type BiomeRun, runBiome } from "./run.ts";
@@ -28,9 +29,14 @@ function failure(args: readonly string[], run: BiomeRun): Error {
 	return new Error(`biome ${args.join(" ")} exited ${run.code} without a report:\n${[run.stdout, run.stderr].join("\n").trim()}`);
 }
 
-async function reportFor(root: string, args: readonly string[], paths: readonly string[]): Promise<Report> {
+async function reportFor(
+	root: string,
+	args: readonly string[],
+	paths: readonly string[],
+	exceptions: readonly ExceptionDeclaration[],
+): Promise<Report> {
 	const command = [...args, "--reporter=json", "--max-diagnostics=none", ...paths];
-	const run = await runBiome(root, command);
+	const run = await runBiome(root, command, exceptions);
 	const report = decodeReport(run.stdout.trim());
 	if (report._tag === "None") {
 		throw failure(command, run);
@@ -38,12 +44,12 @@ async function reportFor(root: string, args: readonly string[], paths: readonly
 	return report.value;
 }
 
-export async function biomeReport(root: string, args: readonly string[]): Promise<Report> {
-	const [report, tracked] = await Promise.all([reportFor(root, args, ["."]), ignoredTrackedPaths(root)]);
+export async function biomeReport(root: string, args: readonly string[], exceptions: readonly ExceptionDeclaration[] = []): Promise<Report> {
+	const [report, tracked] = await Promise.all([reportFor(root, args, ["."], exceptions), ignoredTrackedPaths(root)]);
 	const paths = tracked
 		.map((path) => relative(root, path))
 		.filter((path) => !path.split(sep).some((part) => part === ".git" || part === "node_modules"));
-	const extra = paths.length === 0 ? undefined : await reportFor(root, [...args, "--vcs-enabled=false"], paths);
+	const extra = paths.length === 0 ? undefined : await reportFor(root, [...args, "--vcs-enabled=false"], paths, exceptions);
 	const diagnostics = [...report.diagnostics, ...(extra?.diagnostics ?? [])];
 	const unique = [...new Map(diagnostics.map((diagnostic) => [JSON.stringify(diagnostic), diagnostic])).values()];
 	return {

package/src/biome/run.ts

@@ -1,6 +1,8 @@
 import { execFile } from "node:child_process";
 import { createRequire } from "node:module";
 import process from "node:process";
+import type { ExceptionDeclaration } from "#exceptions/declaration.ts";
+import { withExceptionConfig } from "./exceptionConfig.ts";
 
 export interface BiomeRun {
 	readonly code: number;
@@ -10,14 +12,19 @@ export interface BiomeRun {
 
 const BIN = createRequire(import.meta.url).resolve("@biomejs/biome/bin/biome");
 
-export function runBiome(root: string, args: readonly string[]): Promise<BiomeRun> {
-	return new Promise((resolve, reject) => {
-		execFile(process.execPath, [BIN, ...args, "--colors=off"], { cwd: root, maxBuffer: 2 ** 30 }, (error, stdout, stderr) => {
-			if (error !== null && typeof error.code !== "number") {
-				reject(error);
-				return;
-			}
-			resolve({ code: error === null ? 0 : Number(error.code), stderr, stdout });
-		});
-	});
+export function runBiome(root: string, args: readonly string[], exceptions: readonly ExceptionDeclaration[] = []): Promise<BiomeRun> {
+	return withExceptionConfig(
+		root,
+		exceptions,
+		(configArgs) =>
+			new Promise((resolve, reject) => {
+				execFile(process.execPath, [BIN, ...args, ...configArgs, "--colors=off"], { cwd: root, maxBuffer: 2 ** 30 }, (error, stdout, stderr) => {
+					if (error !== null && typeof error.code !== "number") {
+						reject(error);
+						return;
+					}
+					resolve({ code: error === null ? 0 : Number(error.code), stderr, stdout });
+				});
+			}),
+	);
 }

package/src/cli/args.ts

@@ -1,9 +1,11 @@
 import { parseArgs } from "node:util";
 import { Result } from "effect";
 import type { WarningDetail } from "#report/render.ts";
+import { ADOPT_REMOVED, USAGE as COMMAND_USAGE } from "./messages.ts";
 
 export type Command =
 	| { readonly _tag: "Lint"; readonly config: string | undefined; readonly warnings: WarningDetail }
+	| { readonly _tag: "ExceptionsMigrate"; readonly config: string | undefined; readonly from: string | undefined }
 	| { readonly _tag: "Fix"; readonly config: string | undefined }
 	| { readonly _tag: "BaselineWrite"; readonly config: string | undefined; readonly rules: readonly string[] }
 	| { readonly _tag: "BaselinePrune"; readonly config: string | undefined; readonly against: string | undefined }
@@ -16,32 +18,7 @@ export type Command =
 
 export type Parsed = { readonly _tag: "Parsed"; readonly command: Command } | { readonly _tag: "Usage"; readonly problem: string };
 
-export const USAGE = `Usage:
-  quality lint [--config <file>] [--warnings summary|all]
-  quality fix [--config <file>]
-  quality baseline write [--config <file>] [--rule <id>]...
-  quality baseline prune [--config <file>] [--against <ref>]
-  quality baseline tighten [--config <file>] [--staged]
-  quality baseline migrate [--config <file>] [--from <file>]
-  quality hooks install [--config <file>] [--force]
-  quality hooks uninstall
-  quality hooks pre-commit [--config <file>]
-
-lint              Run every rule. Exits 1 on an error-level violation, a file over its baseline, a stale registry entry
-                  or a baseline entry for a rule that is off or unknown.
-fix               Sort every package.json, apply Biome's lint fixes, unsafe ones included, its assist actions and formatting, then format again.
-baseline write    Record current error-level violations. Creates the baseline, or records the named rules again, replacing their entries.
-baseline prune    Drop fixed debt, lower entries to what is left and carry entries to files git saw move. Never adds or raises an entry.
-baseline tighten  Prune only the entries of files changed since HEAD, or with --staged, in the index.
-baseline migrate  Move a baseline from the earlier JSON format (--from, quality/baseline.json by default) to the configured file.
-hooks install     Install the git pre-commit hook, shared by every worktree, that runs hooks pre-commit. Keeps a hook that is not quality's
-                  unless --force replaces it.
-hooks uninstall   Remove quality's pre-commit hook. Keeps a hook that is not quality's.
-hooks pre-commit  What the hook runs: lint, then package.json scripts typecheck and quality:commit when present.
-
---config <file>  Config file; its directory is the repository root. Without this option, uses ./quality.config.ts when present, otherwise defaults.
---against <ref>  The branch the work merges into, whose merge base prune follows moves from. Defaults to origin/HEAD, then origin/main, then origin/master.
-Exit codes: 0 passed, 1 failed the gate, 2 could not run.`;
+export const USAGE = COMMAND_USAGE;
 
 const OPTIONS = {
 	against: { type: "string" },
@@ -56,11 +33,9 @@ const OPTIONS = {
 
 const usage = (problem: string): Parsed => ({ _tag: "Usage", problem });
 
-const ADOPT_REMOVED =
-	"`quality adopt` was removed in 0.7.0. To record a rule's existing findings in the baseline, run `quality baseline write --rule <id>`; to apply the fixes Biome can make first, run `quality fix`.";
-
 const SUBCOMMANDS: Readonly<Record<string, string>> = {
 	baseline: "baseline takes write, prune, tighten or migrate.",
+	exceptions: "exceptions takes migrate.",
 	hooks: "hooks takes install, uninstall or pre-commit.",
 };
 
@@ -77,6 +52,7 @@ const ACCEPTS: Readonly<Record<string, readonly Option[]>> = {
 	"baseline prune": ["against"],
 	"baseline tighten": ["staged"],
 	"baseline write": ["rule"],
+	"exceptions migrate": ["from"],
 	fix: [],
 	"hooks install": ["force"],
 	"hooks pre-commit": [],
@@ -102,6 +78,8 @@ const commandFor = (name: string, values: Values): Parsed => {
 				? parsed({ _tag: "Lint", config, warnings })
 				: usage(`--warnings takes summary or all, not "${warnings}".`);
 		}
+		case "exceptions migrate":
+			return parsed({ _tag: "ExceptionsMigrate", config, from: values.from });
 		case "fix":
 			return parsed({ _tag: "Fix", config });
 		case "baseline write":

package/src/cli/fix.ts

@@ -2,6 +2,7 @@ import { relative } from "node:path";
 import { Console, Effect, FileSystem } from "effect";
 import { biomeReport, type Report } from "#biome/report.ts";
 import { loadConfig } from "#config/load.ts";
+import type { ExceptionDeclaration } from "#exceptions/declaration.ts";
 import { SetupFailure } from "#failure.ts";
 import { posix } from "#inventory/ignore-scope.ts";
 import { walk } from "#inventory/walk.ts";
@@ -10,10 +11,10 @@ import { plural } from "#report/plural.ts";
 
 export const MAX_FIX_ROUNDS = 5;
 
-function biome(root: string, args: readonly string[]): Effect.Effect<Report, SetupFailure> {
+function biome(root: string, args: readonly string[], exceptions: readonly ExceptionDeclaration[]): Effect.Effect<Report, SetupFailure> {
 	return Effect.tryPromise({
 		catch: (cause) => new SetupFailure({ message: cause instanceof Error ? cause.message : String(cause) }),
-		try: () => biomeReport(root, args),
+		try: () => biomeReport(root, args, exceptions),
 	});
 }
 
@@ -43,17 +44,21 @@ export interface Settling<TFailure, TRequirements> {
 	readonly snapshot: Effect.Effect<ReadonlyMap<string, string>, TFailure, TRequirements>;
 }
 
-function changedBy(root: string, args: readonly string[]): Effect.Effect<number, SetupFailure> {
-	return Effect.map(biome(root, args), (report) => report.summary.changed);
+function changedBy(root: string, args: readonly string[], exceptions: readonly ExceptionDeclaration[]): Effect.Effect<number, SetupFailure> {
+	return Effect.map(biome(root, args, exceptions), (report) => report.summary.changed);
 }
 
-function biomePasses(root: string): readonly Pass<SetupFailure, never>[] {
+function biomePasses(root: string, exceptions: readonly ExceptionDeclaration[]): readonly Pass<SetupFailure, never>[] {
 	return [
 		{
 			label: "with fixes",
-			run: changedBy(root, ["check", "--write", "--unsafe", "--skip=assist/source/useSortedKeys", "--skip=lint/suspicious/noDuplicateObjectKeys"]),
+			run: changedBy(
+				root,
+				["check", "--write", "--unsafe", "--skip=assist/source/useSortedKeys", "--skip=lint/suspicious/noDuplicateObjectKeys"],
+				exceptions,
+			),
 		},
-		{ label: "with the format pass", run: changedBy(root, ["format", "--write"]) },
+		{ label: "with the format pass", run: changedBy(root, ["format", "--write"], exceptions) },
 	];
 }
 
@@ -122,9 +127,9 @@ export function settle<TFailure, TRequirements>({
 
 export function fix(cwd: string, config: string | undefined): Effect.Effect<void, SetupFailure, FileSystem.FileSystem> {
 	return Effect.gen(function* () {
-		const { root } = yield* loadConfig(cwd, config);
+		const { root, exceptions } = yield* loadConfig(cwd, config);
 		const sorted = yield* Effect.mapError(sortManifests(root), (failure) => new SetupFailure({ message: failure.message }));
 		yield* Console.log(`quality: sort-package-json rewrote ${plural(sorted, "manifest")}.`);
-		yield* settle({ passes: biomePasses(root), snapshot: snapshotOf(root) });
+		yield* settle({ passes: biomePasses(root, exceptions), snapshot: snapshotOf(root) });
 	});
 }

package/src/cli/lint.ts

@@ -1,3 +1,4 @@
+import { relative } from "node:path";
 import { Console, Effect, type FileSystem } from "effect";
 import { evaluate, passes } from "#engine/evaluate.ts";
 import { openSession } from "#engine/session.ts";
@@ -17,7 +18,8 @@ export const lint = (
 				baseline: session.config.baseline,
 				checked: session.inventory.sources.length,
 				descriptions: new Map(session.config.active.map((rule) => [rule.id, rule.description])),
-				registry: session.config.registry,
+				registry:
+					session.config.exceptions.length === 0 ? session.config.registry : `${relative(session.config.root, session.config.file)} exceptions`,
 				warnings,
 			}),
 		);

package/src/cli/messages.ts

@@ -0,0 +1,31 @@
+export const USAGE = `Usage:
+  quality lint [--config <file>] [--warnings summary|all]
+  quality fix [--config <file>]
+  quality exceptions migrate [--config <file>] [--from <registry>]
+  quality baseline write [--config <file>] [--rule <id>]...
+  quality baseline prune [--config <file>] [--against <ref>]
+  quality baseline tighten [--config <file>] [--staged]
+  quality baseline migrate [--config <file>] [--from <file>]
+  quality hooks install [--config <file>] [--force]
+  quality hooks uninstall
+  quality hooks pre-commit [--config <file>]
+
+lint              Run every rule. Exits 1 on an error-level violation, a file over its baseline, a stale registry entry
+                  or a baseline entry for a rule that is off or unknown.
+fix               Sort every package.json, apply Biome's lint fixes, unsafe ones included, its assist actions and formatting, then format again.
+exceptions migrate Move legacy registry entries and Biome declarations into quality.config.ts exceptions and remove matching root overrides.
+baseline write    Record current error-level violations. Creates the baseline, or records the named rules again, replacing their entries.
+baseline prune    Drop fixed debt, lower entries to what is left and carry entries to files git saw move. Never adds or raises an entry.
+baseline tighten  Prune only the entries of files changed since HEAD, or with --staged, in the index.
+baseline migrate  Move a baseline from the earlier JSON format (--from, quality/baseline.json by default) to the configured file.
+hooks install     Install the git pre-commit hook, shared by every worktree, that runs hooks pre-commit. Keeps a hook that is not quality's
+                  unless --force replaces it.
+hooks uninstall   Remove quality's pre-commit hook. Keeps a hook that is not quality's.
+hooks pre-commit  What the hook runs: lint, then package.json scripts typecheck and quality:commit when present.
+
+--config <file>  Config file; its directory is the repository root. Without this option, uses ./quality.config.ts when present, otherwise defaults.
+--against <ref>  The branch the work merges into, whose merge base prune follows moves from. Defaults to origin/HEAD, then origin/main, then origin/master.
+Exit codes: 0 passed, 1 failed the gate, 2 could not run.`;
+
+export const ADOPT_REMOVED =
+	"`quality adopt` was removed in 0.7.0. To record a rule's existing findings in the baseline, run `quality baseline write --rule <id>`; to apply the fixes Biome can make first, run `quality fix`.";

package/src/cli/migrateExceptions.ts

@@ -0,0 +1,87 @@
+import { join } from "node:path";
+import { Console, Effect, FileSystem } from "effect";
+import { loadConfig } from "#config/load.ts";
+import { validOrFail } from "#decoded.ts";
+import { readInput } from "#engine/baseline-file.ts";
+import { decodeExceptions, type ExceptionDeclaration } from "#exceptions/declaration.ts";
+import { migrateBiome } from "#exceptions/migrateBiome.ts";
+import { migrateConfig } from "#exceptions/migrateConfig.ts";
+import { decodeRegistry } from "#exceptions/registry.ts";
+import { SetupFailure } from "#failure.ts";
+import { writeText } from "#inventory/filesystem.ts";
+
+function merge(entries: readonly ExceptionDeclaration[]): readonly ExceptionDeclaration[] {
+	const merged: ExceptionDeclaration[] = [];
+	for (const entry of entries) {
+		const index = merged.findIndex(
+			(other) =>
+				other.reason === entry.reason
+				&& other.subject === entry.subject
+				&& other.files.length === entry.files.length
+				&& other.files.every((file) => entry.files.includes(file)),
+		);
+		const previous = merged[index];
+		if (previous === undefined) {
+			merged.push(entry);
+		} else {
+			merged[index] = {
+				...previous,
+				rules: [previous.rules[0], ...new Set([...previous.rules.slice(1), ...entry.rules.filter((rule) => rule !== previous.rules[0])])],
+			};
+		}
+	}
+	return merged;
+}
+
+export const migrateExceptions = Effect.fnUntraced(function* (
+	cwd: string,
+	configPath: string | undefined,
+	from: string | undefined,
+): Effect.fn.Return<void, SetupFailure, FileSystem.FileSystem> {
+	const config = yield* loadConfig(cwd, configPath);
+	const registryPath = from ?? config.registry;
+	const raw = yield* readInput(config.root, registryPath);
+	if (from !== undefined && raw === undefined) {
+		return yield* new SetupFailure({ message: `${registryPath} does not exist. Pass an existing registry file with --from.` });
+	}
+	const registry = yield* validOrFail(registryPath, yield* Effect.promise(() => decodeRegistry(raw)));
+	const entries = merge([
+		...config.exceptions,
+		...registry.map(
+			({ file, reason, rule, subject }): ExceptionDeclaration => ({
+				files: [file],
+				reason,
+				rules: [rule],
+				...(subject === undefined ? {} : { subject }),
+			}),
+		),
+		...config.biomeDeclarations.map(({ includes, reason, rule }): ExceptionDeclaration => ({ files: includes, reason, rules: [`biome/${rule}`] })),
+	]);
+	yield* validOrFail(config.file, yield* Effect.promise(() => decodeExceptions(entries)));
+	const text = yield* readInput("", config.file);
+	const next = yield* Effect.try({
+		catch: (cause) => new SetupFailure({ message: String(cause) }),
+		try: () => migrateConfig(text, config.file, entries, config.biomeDeclarations.length > 0),
+	});
+	const updates: Array<{ readonly path: string; readonly text: string }> = [{ path: config.file, text: next }];
+	if (config.biomeDeclarations.length > 0) {
+		for (const file of ["biome.json", "biome.jsonc"]) {
+			const biome = yield* readInput(config.root, file);
+			if (biome !== undefined) {
+				const updated = yield* Effect.try({
+					catch: (cause) => new SetupFailure({ message: String(cause) }),
+					try: () => migrateBiome(biome, file, config.biomeDeclarations),
+				});
+				updates.push({ path: join(config.root, file), text: updated });
+			}
+		}
+	}
+	for (const update of updates) {
+		yield* writeText(update.path, update.text).pipe(Effect.mapError((failure) => new SetupFailure({ message: failure.message })));
+	}
+	if (raw !== undefined) {
+		const fs = yield* FileSystem.FileSystem;
+		yield* fs.remove(join(config.root, registryPath)).pipe(Effect.mapError((failure) => new SetupFailure({ message: failure.message })));
+	}
+	yield* Console.log(`quality: moved exceptions to ${config.file}. Run quality fix and review the changes; remove unused declaration imports.`);
+});

package/src/cli.ts

@@ -6,6 +6,7 @@ import { writeBaseline } from "#cli/baseline.ts";
 import { fix } from "#cli/fix.ts";
 import { lint } from "#cli/lint.ts";
 import { migrateBaseline } from "#cli/migrate.ts";
+import { migrateExceptions } from "#cli/migrateExceptions.ts";
 import { runMain } from "#cli/run-main.ts";
 import { pruneBaseline, tightenBaseline } from "#cli/shrink.ts";
 import { installHook } from "#hooks/install.ts";
@@ -33,6 +34,8 @@ const program = Effect.gen(function* () {
 			return yield* pruneBaseline(process.cwd(), command.config, command.against);
 		case "BaselineTighten":
 			return yield* tightenBaseline(process.cwd(), command.config, command.staged);
+		case "ExceptionsMigrate":
+			return yield* migrateExceptions(process.cwd(), command.config, command.from);
 		case "BaselineMigrate":
 			return yield* migrateBaseline(process.cwd(), command.config, command.from);
 		case "HooksInstall":

package/src/config/decode.ts

@@ -1,5 +1,6 @@
 import { Schema } from "effect";
 import { type Decoded, decodeWith } from "#decoded.ts";
+import { ExceptionDeclaration } from "#exceptions/declaration.ts";
 import type { Rule } from "#rule.ts";
 
 const isRule = (value: unknown): value is Rule =>
@@ -30,6 +31,7 @@ const PreCommitRemoved = Schema.Never.annotate({
 const ConfigInput = Schema.Struct({
 	adopt: Schema.optionalKey(AdoptRemoved),
 	baseline: Schema.optionalKey(Schema.String),
+	exceptions: Schema.optionalKey(Schema.Array(ExceptionDeclaration)),
 	extensions: Schema.optionalKey(Schema.Array(Schema.String)),
 	local: Schema.optionalKey(Schema.Array(LocalRule)),
 	preCommit: Schema.optionalKey(PreCommitRemoved),