@shivaedev/quality 0.21.1 → 0.22.0

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),

package/src/config/load.ts

@@ -1,9 +1,12 @@
 import { basename, dirname, resolve } from "node:path";
 import { pathToFileURL } from "node:url";
-import { Effect, FileSystem } from "effect";
+import { Effect, FileSystem, Schema } from "effect";
 import { validOrFail } from "#decoded.ts";
+import type { ExceptionDeclaration } from "#exceptions/declaration.ts";
 import { SetupFailure } from "#failure.ts";
 import type { InventoryScope } from "#inventory/collect.ts";
+import { ConsumerDeclaration } from "#rules/suppressions/biome/ConsumerDeclaration.ts";
+import type { Declaration } from "#rules/suppressions/biome/declarations.ts";
 import { type ConfigInput, decodeConfig } from "./decode.ts";
 import { CONFIG_FILE } from "./file.ts";
 import { type ResolvedRules, resolveRules } from "./resolve.ts";
@@ -12,6 +15,8 @@ const DEFAULT_EXTENSIONS = [".ts", ".tsx", ".mts", ".cts", ".js", ".jsx", ".mjs"
 
 export interface ResolvedConfig extends ResolvedRules, InventoryScope {
 	readonly baseline: string;
+	readonly biomeDeclarations: readonly Declaration[];
+	readonly exceptions: readonly ExceptionDeclaration[];
 	readonly file: string;
 	readonly registry: string;
 	readonly root: string;
@@ -31,9 +36,18 @@ const importDefault = (file: string): Effect.Effect<unknown, SetupFailure> =>
 				: Effect.fail(new SetupFailure({ message: `${file} has no default export. Export defineConfig({ ... }) as the default.` })),
 	);
 
+const LegacyOptions = Schema.Struct({ declared: Schema.Array(ConsumerDeclaration) });
+function biomeDeclarations(config: ConfigInput): readonly Declaration[] {
+	const setting = config.rules?.["suppressions/biome-overrides"];
+	const options = typeof setting === "object" ? setting.options : undefined;
+	return Schema.is(LegacyOptions)(options) ? options.declared : [];
+}
+
 const resolved = (root: string, file: string, config: ConfigInput, rules: ResolvedRules): ResolvedConfig => ({
 	...rules,
 	baseline: config.baseline ?? "quality/baseline.jsonl",
+	biomeDeclarations: biomeDeclarations(config),
+	exceptions: config.exceptions ?? [],
 	exclude: [],
 	extensions: config.extensions ?? DEFAULT_EXTENSIONS,
 	file,

package/src/config/resolve.ts

@@ -21,6 +21,17 @@ const duplicateIssues = (rules: readonly Rule[]): readonly string[] =>
 		rules.findIndex((other) => other.id === rule.id) === index ? [] : [`local: rule id "${rule.id}" is already defined`],
 	);
 
+function activeRule(rule: Rule, check: ActiveRule["check"]): ActiveRule {
+	return {
+		check,
+		description: rule.description,
+		family: rule.family === true,
+		id: rule.id,
+		level: "error",
+		registrable: rule.registrable !== false,
+	};
+}
+
 const activate = (rule: Rule, setting: Setting | undefined): Effect.Effect<Decoded<ActiveRule>> =>
 	Effect.tryPromise({ catch: messageOf, try: () => rule.configure(optionsOf(setting)) }).pipe(
 		Effect.map(
@@ -29,7 +40,7 @@ const activate = (rule: Rule, setting: Setting | undefined): Effect.Effect<Decod
 					? { _tag: "Invalid", issues: configured.issues.map((issue) => `rules.${rule.id}.options: ${issue}`) }
 					: {
 							_tag: "Valid",
-							value: { check: configured.check, description: rule.description, family: rule.family === true, id: rule.id, level: "error" },
+							value: activeRule(rule, configured.check),
 						},
 		),
 		Effect.catch((failure: string) =>

package/src/config.ts

@@ -1,3 +1,4 @@
+import type { ExceptionDeclaration } from "#exceptions/declaration.ts";
 import type { builtInRules } from "#rules/built-in.ts";
 import type { Rule } from "./rule.ts";
 
@@ -15,6 +16,7 @@ export type BuiltInRules = typeof builtInRules;
 
 export interface QualityConfig<TLocal extends readonly Rule[] = readonly Rule[]> {
 	readonly baseline?: string;
+	readonly exceptions?: readonly ExceptionDeclaration[];
 	readonly extensions?: readonly string[];
 	readonly local?: TLocal;
 	readonly registry?: string;

package/src/engine/run-rules.ts

@@ -11,6 +11,7 @@ export interface ActiveRule {
 	readonly family: boolean;
 	readonly id: string;
 	readonly level: ActiveLevel;
+	readonly registrable?: boolean;
 }
 
 const messageOf = (cause: unknown): string => (cause instanceof Error ? cause.message : String(cause));
@@ -18,24 +19,40 @@ const messageOf = (cause: unknown): string => (cause instanceof Error ? cause.me
 // Registry and baseline entries match on the path, so every finding names its file the same way.
 const repositoryPath = (root: string, file: string): string => posix(isAbsolute(file) ? relative(root, file) : file).replace(/^(\.\/)+/u, "");
 
-const violationOf = (rule: ActiveRule, root: string, finding: Finding): Violation => ({
+function exceptionHint(rule: ActiveRule, finding: Finding, file: string, config: string): string {
+	const id = rule.family && finding.subject !== undefined ? `${rule.id}/${finding.subject}` : rule.id;
+	const biome = /^biome\/(?:lint|assist)\/[a-zA-Z]+\/[a-zA-Z]+$/u.test(id);
+	if (!biome && rule.registrable === false) {
+		return "";
+	}
+	const shape = JSON.stringify({
+		files: [file],
+		reason: "Explain why this exception is permanent.",
+		rules: [id],
+		...(!rule.family && finding.subject !== undefined ? { subject: finding.subject } : {}),
+	});
+	return ` For a permanent exception, add to exceptions in ${config}: ${shape}.`;
+}
+
+const violationOf = (rule: ActiveRule, root: string, finding: Finding, exceptionFile: string): Violation => ({
 	...finding,
 	file: repositoryPath(root, finding.file),
 	level: rule.level,
+	message: finding.message + exceptionHint(rule, finding, repositoryPath(root, finding.file), exceptionFile),
 	rule: rule.family && finding.subject !== undefined ? `${rule.id}/${finding.subject}` : rule.id,
 });
 
-const runRule = (rule: ActiveRule, inputs: RuleInputs): Effect.Effect<readonly Violation[], SetupFailure> =>
+const runRule = (rule: ActiveRule, inputs: RuleInputs, exceptionFile: string): Effect.Effect<readonly Violation[], SetupFailure> =>
 	Effect.map(
 		Effect.tryPromise({
 			catch: (cause) => new SetupFailure({ message: `rule ${rule.id} failed: ${messageOf(cause)}` }),
 			try: () => rule.check(inputs),
 		}),
-		(findings) => findings.map((finding) => violationOf(rule, inputs.root, finding)),
+		(findings) => findings.map((finding) => violationOf(rule, inputs.root, finding, exceptionFile)),
 	);
 
 export const runRules = (rules: readonly ActiveRule[], inputs: RuleInputs): Effect.Effect<readonly Violation[], SetupFailure> =>
 	Effect.map(
-		Effect.forEach(rules, (rule) => runRule(rule, inputs), { concurrency: "unbounded" }),
+		Effect.forEach(rules, (rule) => runRule(rule, inputs, inputs.configFile ?? "quality.config.ts"), { concurrency: "unbounded" }),
 		(results) => results.flat(),
 	);

package/src/engine/session.ts

@@ -1,8 +1,9 @@
-import { resolve } from "node:path";
+import { relative, resolve } from "node:path";
 import { Effect, type FileSystem } from "effect";
 import { loadConfig, type ResolvedConfig } from "#config/load.ts";
 import { validOrFail } from "#decoded.ts";
 import { decodeRegistry, type RegistryEntry } from "#exceptions/registry.ts";
+import { registryEntries } from "#exceptions/registryEntries.ts";
 import { SetupFailure } from "#failure.ts";
 import { collectInventory, type Inventory } from "#inventory/collect.ts";
 import { type FilesystemFailure, readOptionalText } from "#inventory/filesystem.ts";
@@ -27,7 +28,14 @@ export const scan = (config: ResolvedConfig): Effect.Effect<Pick<Session, "inven
 		const inventory = yield* setup(collectInventory(config.root, config));
 		const services = yield* Effect.context<FileSystem.FileSystem>();
 		const readText = (path: string): Promise<string | undefined> => Effect.runPromiseWith(services)(readOptionalText(resolve(config.root, path)));
-		const violations = yield* runRules(config.active, { files: inventory.files, readText, root: config.root, sources: inventory.sources });
+		const violations = yield* runRules(config.active, {
+			configFile: relative(config.root, config.file),
+			exceptions: config.exceptions,
+			files: inventory.files,
+			readText,
+			root: config.root,
+			sources: inventory.sources,
+		});
 		return { inventory, violations };
 	});
 
@@ -38,5 +46,5 @@ export const openSession = (cwd: string, configPath: string | undefined): Effect
 		const registry = yield* validOrFail(config.registry, yield* Effect.promise(() => decodeRegistry(registryRaw)));
 		const baseline = yield* readBaseline(config);
 		const { inventory, violations } = yield* scan(config);
-		return { baseline, config, inventory, registry, violations };
+		return { baseline, config, inventory, registry: [...registry, ...registryEntries(config.exceptions)], violations };
 	});

package/src/exceptions/biomeFindings.ts

@@ -0,0 +1,20 @@
+import type { Finding, RuleInputs } from "#rule.ts";
+
+export async function missingBiomeFiles(inputs: RuleInputs): Promise<readonly Finding[]> {
+	const paths = (inputs.exceptions ?? [])
+		.filter((entry) => entry.rules.some((rule) => rule.startsWith("biome/") && rule !== "biome/files/includes"))
+		.flatMap((entry) => entry.files);
+	const checked = await Promise.all(
+		[...new Set(paths)].map(async (file) =>
+			(await inputs.readText(file)) === undefined
+				? [{ file, message: `This Biome exception names a missing file. Remove it from exceptions in ${inputs.configFile ?? "quality.config.ts"}.` }]
+				: [],
+		),
+	);
+	return checked.flat();
+}
+
+export function biomeExceptionHint(files: readonly string[], rule: string, config = "quality.config.ts"): string {
+	const entry = { files, reason: "Explain why this exception is permanent.", rules: [`biome/${rule}`] };
+	return ` Move this setting into exceptions in ${config}: ${JSON.stringify(entry)}, and remove the setting from the Biome config.`;
+}