@shivaedev/quality 0.21.1 → 0.23.0

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/program.ts

@@ -0,0 +1,50 @@
+import { Console, Effect } from "effect";
+import { parseCommand, USAGE } from "#cli/args.ts";
+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 { pruneBaseline, tightenBaseline } from "#cli/shrink.ts";
+import { SetupFailure } from "#failure.ts";
+import type { Launch } from "#hooks/command.ts";
+import { installHook } from "#hooks/install.ts";
+import { preCommitHook } from "#hooks/preCommit.ts";
+import { uninstallHook } from "#hooks/uninstall.ts";
+
+export interface Invocation {
+	readonly cwd: string;
+	readonly launch: Launch;
+}
+
+export const program = Effect.fn("Cli.program")(function* (args: readonly string[], { cwd, launch }: Invocation) {
+	const parsed = parseCommand(args);
+	if (parsed._tag === "Usage") {
+		return yield* new SetupFailure({ message: `${parsed.problem}\n\n${USAGE}` });
+	}
+	const command = parsed.command;
+	switch (command._tag) {
+		case "Help":
+			return yield* Console.log(USAGE);
+		case "Lint":
+			return yield* lint(cwd, command.config, command.warnings);
+		case "Fix":
+			return yield* fix(cwd, command.config);
+		case "BaselineWrite":
+			return yield* writeBaseline(cwd, command.config, command.rules);
+		case "BaselinePrune":
+			return yield* pruneBaseline(cwd, command.config, command.against);
+		case "BaselineTighten":
+			return yield* tightenBaseline(cwd, command.config, command.staged);
+		case "ExceptionsMigrate":
+			return yield* migrateExceptions(cwd, command.config, command.from);
+		case "BaselineMigrate":
+			return yield* migrateBaseline(cwd, command.config, command.from);
+		case "HooksInstall":
+			return yield* installHook({ config: command.config, cwd, force: command.force, launch });
+		case "HooksUninstall":
+			return yield* uninstallHook(cwd);
+		case "HooksPreCommit":
+			return yield* preCommitHook(cwd, command.config);
+	}
+});

package/src/cli/run-main.ts

@@ -11,23 +11,24 @@ import type { Git } from "#git/command.ts";
 const INTERRUPTED = 130;
 const COULD_NOT_RUN = 2;
 
-const explain = (cause: Cause.Cause<unknown>): Effect.Effect<void> => {
+function explain(cause: Cause.Cause<unknown>): Effect.Effect<void> {
 	const error = Cause.squash(cause);
 	if (error instanceof SetupFailure) {
 		return Console.error(`quality: ${error.message}`);
 	}
 	return Runtime.getErrorReported(error) ? Console.error(`quality: internal error\n${Cause.pretty(cause)}`) : Effect.void;
-};
+}
 
-const exitCodeOf = (error: unknown): number =>
-	typeof error === "object" && error !== null && Runtime.errorExitCode in error ? Runtime.getErrorExitCode(error) : COULD_NOT_RUN;
+function exitCodeOf(error: unknown): number {
+	return typeof error === "object" && error !== null && Runtime.errorExitCode in error ? Runtime.getErrorExitCode(error) : COULD_NOT_RUN;
+}
 
-const exitCode = (exit: Exit.Exit<unknown, unknown>): number => {
+export function exitCode(exit: Exit.Exit<unknown, unknown>): number {
 	if (Exit.isSuccess(exit)) {
 		return 0;
 	}
 	return Cause.hasInterruptsOnly(exit.cause) ? INTERRUPTED : exitCodeOf(Cause.squash(exit.cause));
-};
+}
 
 const teardown: Runtime.Teardown = (exit, onExit) => {
 	process.stdout.write("", () => process.stderr.write("", () => onExit(exitCode(exit))));
@@ -45,11 +46,16 @@ export function quietOnClosedPipe(stream: EventEmitter): void {
 	});
 }
 
-const services = NodeChildProcessSpawner.layer.pipe(Layer.provideMerge(Layer.mergeAll(NodeFileSystem.layer, NodePath.layer)));
+export const services = NodeChildProcessSpawner.layer.pipe(Layer.provideMerge(Layer.mergeAll(NodeFileSystem.layer, NodePath.layer)));
 
-export const runMain = <TValue, TError>(program: Effect.Effect<TValue, TError, FileSystem.FileSystem | Git>): void => {
+export function explained<TValue, TError, TRequirements>(
+	program: Effect.Effect<TValue, TError, TRequirements>,
+): Effect.Effect<TValue, TError, TRequirements> {
+	return Effect.tapCause(program, (cause) => (Cause.hasInterruptsOnly(cause) ? Effect.void : explain(cause)));
+}
+
+export function runMain<TValue, TError>(program: Effect.Effect<TValue, TError, FileSystem.FileSystem | Git>): void {
 	quietOnClosedPipe(process.stdout);
 	quietOnClosedPipe(process.stderr);
-	const explained = Effect.tapCause(program, (cause) => (Cause.hasInterruptsOnly(cause) ? Effect.void : explain(cause)));
-	NodeRuntime.runMain(Effect.provide(explained, services), { disableErrorReporting: true, teardown });
-};
+	NodeRuntime.runMain(Effect.provide(explained(program), services), { disableErrorReporting: true, teardown });
+}

package/src/cli.ts

@@ -1,52 +1,6 @@
 #!/usr/bin/env node
 import process from "node:process";
-import { Console, Effect } from "effect";
-import { parseCommand, USAGE } from "#cli/args.ts";
-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 { program } from "#cli/program.ts";
 import { runMain } from "#cli/run-main.ts";
-import { pruneBaseline, tightenBaseline } from "#cli/shrink.ts";
-import { installHook } from "#hooks/install.ts";
-import { preCommitHook } from "#hooks/preCommit.ts";
-import { uninstallHook } from "#hooks/uninstall.ts";
-import { SetupFailure } from "./failure.ts";
 
-const parsed = parseCommand(process.argv.slice(2));
-
-const program = Effect.gen(function* () {
-	if (parsed._tag === "Usage") {
-		return yield* new SetupFailure({ message: `${parsed.problem}\n\n${USAGE}` });
-	}
-	const command = parsed.command;
-	switch (command._tag) {
-		case "Help":
-			return yield* Console.log(USAGE);
-		case "Lint":
-			return yield* lint(process.cwd(), command.config, command.warnings);
-		case "Fix":
-			return yield* fix(process.cwd(), command.config);
-		case "BaselineWrite":
-			return yield* writeBaseline(process.cwd(), command.config, command.rules);
-		case "BaselinePrune":
-			return yield* pruneBaseline(process.cwd(), command.config, command.against);
-		case "BaselineTighten":
-			return yield* tightenBaseline(process.cwd(), command.config, command.staged);
-		case "BaselineMigrate":
-			return yield* migrateBaseline(process.cwd(), command.config, command.from);
-		case "HooksInstall":
-			return yield* installHook({
-				config: command.config,
-				cwd: process.cwd(),
-				force: command.force,
-				launch: { options: process.execArgv, script: process.argv[1] ?? "" },
-			});
-		case "HooksUninstall":
-			return yield* uninstallHook(process.cwd());
-		case "HooksPreCommit":
-			return yield* preCommitHook(process.cwd(), command.config);
-	}
-});
-
-runMain(program);
+runMain(program(process.argv.slice(2), { cwd: process.cwd(), launch: { options: process.execArgv, script: process.argv[1] ?? "" } }));

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.`;
+}

package/src/exceptions/declaration.ts

@@ -0,0 +1,38 @@
+import { Schema } from "effect";
+import { type Decoded, decodeWith } from "#decoded.ts";
+import { ConsumerDeclaration } from "#rules/suppressions/biome/ConsumerDeclaration.ts";
+
+const FILE = /^(?!\.\/)(?!\/)(?!.*(?:^|\/)\.\.(?:\/|$))[^*!?[\]{}\\]+$/u;
+
+export const ExceptionDeclaration = Schema.Struct({
+	files: Schema.NonEmptyArray(Schema.NonEmptyString),
+	reason: Schema.String.check(Schema.isPattern(/\S/u, { expected: "a reason that says why the exception is permanent" })),
+	rules: Schema.NonEmptyArray(Schema.NonEmptyString),
+	subject: Schema.optionalKey(Schema.NonEmptyString),
+}).check(
+	Schema.makeFilter(
+		({ files, reason, rules, subject }) =>
+			rules.every((rule) => {
+				if (rule.startsWith("biome/")) {
+					return (
+						subject === undefined
+						&& (rule === "biome/files/includes" || files.every((file) => FILE.test(file)))
+						&& Schema.is(ConsumerDeclaration)({ includes: files, reason, rule: rule.slice(6) })
+					);
+				}
+				return files.every((file) => FILE.test(file));
+			}),
+		{
+			message:
+				"Exceptions name explicit repository files and individual rules. Biome rules use biome/lint/<group>/<rule> or biome/assist/<group>/<action>, without a subject. Only biome/files/includes accepts ** and named directory exclusions.",
+		},
+	),
+);
+
+export type ExceptionDeclaration = typeof ExceptionDeclaration.Type;
+
+const standard = Schema.toStandardSchemaV1(Schema.Array(ExceptionDeclaration), { parseOptions: { errors: "all", onExcessProperty: "error" } });
+
+export function decodeExceptions(value: unknown): Promise<Decoded<readonly ExceptionDeclaration[]>> {
+	return decodeWith(standard, value);
+}