@shivaedev/quality 0.21.0 → 0.22.0

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);
+}

package/src/exceptions/migrateBiome.ts

@@ -0,0 +1,78 @@
+import ts from "typescript";
+import type { Declaration } from "#rules/suppressions/biome/declarations.ts";
+
+function nameOf(property: ts.ObjectLiteralElementLike): string | undefined {
+	return ts.isPropertyAssignment(property) && ts.isStringLiteral(property.name) ? property.name.text : undefined;
+}
+
+function strip(node: ts.Expression, paths: readonly (readonly string[])[]): ts.Expression {
+	if (!ts.isObjectLiteralExpression(node)) {
+		return node;
+	}
+	const properties = node.properties.flatMap((property) => {
+		const name = nameOf(property);
+		const matching = paths.filter((path) => path[0] === name);
+		if (!ts.isPropertyAssignment(property) || matching.length === 0) {
+			return [property];
+		}
+		if (matching.some((path) => path.length === 1)) {
+			return [];
+		}
+		const value = strip(
+			property.initializer,
+			matching.map((path) => path.slice(1)),
+		);
+		return ts.isObjectLiteralExpression(value) && value.properties.length === 0
+			? []
+			: [ts.factory.updatePropertyAssignment(property, property.name, value)];
+	});
+	return ts.factory.updateObjectLiteralExpression(node, properties);
+}
+
+function settingPath(rule: string): readonly string[] {
+	const [tool = "", group = "", name = ""] = rule.split("/");
+	return tool === "files" ? ["files", "includes"] : [tool === "lint" ? "linter" : "assist", tool === "lint" ? "rules" : "actions", group, name];
+}
+
+export function migrateBiome(text: string, file: string, declarations: readonly Declaration[]): string {
+	const source = ts.parseJsonText(file, text);
+	const root = source.statements[0]?.expression;
+	if (ts.parseConfigFileTextToJson(file, text).error !== undefined || root === undefined || !ts.isObjectLiteralExpression(root)) {
+		throw new Error(`Cannot migrate invalid Biome config ${file}. Repair it, then run quality exceptions migrate again.`);
+	}
+	const globals = declarations.filter((entry) => entry.rule === "files/includes");
+	const stripped = strip(
+		root,
+		globals.map((entry) => settingPath(entry.rule)),
+	);
+	if (!ts.isObjectLiteralExpression(stripped)) {
+		throw new Error(`Cannot migrate ${file}.`);
+	}
+	const properties = stripped.properties.flatMap((property) => {
+		if (nameOf(property) !== "overrides" || !ts.isPropertyAssignment(property) || !ts.isArrayLiteralExpression(property.initializer)) {
+			return [property];
+		}
+		const overrides = property.initializer.elements.flatMap((override) => {
+			if (!ts.isObjectLiteralExpression(override)) {
+				return [override];
+			}
+			const includes = override.properties.find((item) => nameOf(item) === "includes");
+			const paths =
+				includes !== undefined && ts.isPropertyAssignment(includes) && ts.isArrayLiteralExpression(includes.initializer)
+					? includes.initializer.elements.filter(ts.isStringLiteral).map((item) => item.text)
+					: ["**"];
+			const matching = declarations.filter(
+				(entry) => entry.rule !== "files/includes" && entry.includes.length === paths.length && entry.includes.every((path) => paths.includes(path)),
+			);
+			const updated = strip(
+				override,
+				matching.map((entry) => settingPath(entry.rule)),
+			);
+			return ts.isObjectLiteralExpression(updated) && updated.properties.every((item) => nameOf(item) === "includes") ? [] : [updated];
+		});
+		return overrides.length === 0
+			? []
+			: [ts.factory.updatePropertyAssignment(property, property.name, ts.factory.updateArrayLiteralExpression(property.initializer, overrides))];
+	});
+	return `${ts.createPrinter().printNode(ts.EmitHint.Expression, ts.factory.updateObjectLiteralExpression(root, properties), source)}\n`;
+}

package/src/exceptions/migrateConfig.ts

@@ -0,0 +1,64 @@
+import ts from "typescript";
+import type { ExceptionDeclaration } from "./declaration.ts";
+
+function objectOf(expression: ts.Expression): ts.ObjectLiteralExpression | undefined {
+	if (ts.isObjectLiteralExpression(expression)) {
+		return expression;
+	}
+	if (ts.isCallExpression(expression) && expression.arguments[0] !== undefined) {
+		return objectOf(expression.arguments[0]);
+	}
+	return ts.isSatisfiesExpression(expression) || ts.isAsExpression(expression) || ts.isParenthesizedExpression(expression)
+		? objectOf(expression.expression)
+		: undefined;
+}
+
+function nameOf(property: ts.ObjectLiteralElementLike): string | undefined {
+	const name = property.name;
+	if (name === undefined) {
+		return undefined;
+	}
+	if (ts.isComputedPropertyName(name)) {
+		if (ts.isStringLiteral(name.expression) || ts.isNoSubstitutionTemplateLiteral(name.expression) || ts.isNumericLiteral(name.expression)) {
+			return name.expression.text;
+		}
+		throw new Error("Cannot migrate a computed property automatically. Use literal property keys, then run quality exceptions migrate again.");
+	}
+	return ts.isStringLiteral(name) || ts.isIdentifier(name) || ts.isNumericLiteral(name) ? name.text : undefined;
+}
+
+export function migrateConfig(text: string | undefined, file: string, exceptions: readonly ExceptionDeclaration[], hasDeclarations: boolean): string {
+	if (text === undefined) {
+		return `export default { exceptions: ${JSON.stringify(exceptions, null, "\t")} };\n`;
+	}
+	const source = ts.createSourceFile(file, text, ts.ScriptTarget.Latest, true, ts.ScriptKind.TS);
+	const exported = source.statements.find(ts.isExportAssignment);
+	const object = exported === undefined ? undefined : objectOf(exported.expression);
+	if (object === undefined || object.properties.some(ts.isSpreadAssignment)) {
+		throw new Error(
+			`Cannot migrate ${file} automatically. Export an object or defineConfig({ ... }) without spreads, then run quality exceptions migrate again.`,
+		);
+	}
+	const properties = object.properties.flatMap((property) => {
+		const name = nameOf(property);
+		if (name === "registry" || name === "exceptions") {
+			return [];
+		}
+		if (name !== "rules" || !hasDeclarations) {
+			return [{ name: name ?? "", text: property.getFullText(source).trim() }];
+		}
+		if (
+			!(ts.isPropertyAssignment(property) && ts.isObjectLiteralExpression(property.initializer))
+			|| property.initializer.properties.some(ts.isSpreadAssignment)
+		) {
+			throw new Error(`Inline the rules object in ${file}, then run quality exceptions migrate again.`);
+		}
+		const rules = property.initializer.properties.filter((rule) => nameOf(rule) !== "suppressions/biome-overrides");
+		return rules.length === 0 ? [] : [{ name: "rules", text: `rules: {\n${rules.map((rule) => rule.getFullText(source).trim()).join(",\n")}\n}` }];
+	});
+	const next = properties.map((property) => property.text);
+	const index = properties.findIndex((property) => property.name > "exceptions");
+	next.splice(index < 0 ? next.length : index, 0, `exceptions: ${JSON.stringify(exceptions, null, "\t")}`);
+	const replacement = `{\n${next.join(",\n")}\n}`;
+	return text.slice(0, object.getStart(source)) + replacement + text.slice(object.end);
+}

package/src/exceptions/registryEntries.ts

@@ -0,0 +1,10 @@
+import type { ExceptionDeclaration } from "./declaration.ts";
+import type { RegistryEntry } from "./registry.ts";
+
+export function registryEntries(declarations: readonly ExceptionDeclaration[]): readonly RegistryEntry[] {
+	return declarations.flatMap(({ files, reason, rules, subject }) =>
+		rules
+			.filter((rule) => !rule.startsWith("biome/"))
+			.flatMap((rule) => files.map((file) => ({ file, reason, rule, ...(subject === undefined ? {} : { subject }) }))),
+	);
+}

package/src/rule.ts

@@ -1,4 +1,5 @@
 import type { Bivariant } from "@shivaedev/types/bivariant.ts";
+import type { ExceptionDeclaration } from "#exceptions/declaration.ts";
 import { describeIssue, type StandardSchemaV1 } from "./standard-schema.ts";
 
 export interface Finding {
@@ -19,6 +20,8 @@ export interface SourceFile {
 }
 
 export interface RuleInputs {
+	readonly configFile?: string;
+	readonly exceptions?: readonly ExceptionDeclaration[];
 	readonly files: readonly string[];
 	readonly readText: (path: string) => Promise<string | undefined>;
 	readonly root: string;

package/src/rules/biome.ts

@@ -43,8 +43,8 @@ async function presetFinding(readText: RuleInputs["readText"]): Promise<readonly
 }
 
 const bridge = defineRule({
-	check: async ({ readText, root }) => {
-		const [preset, report] = await Promise.all([presetFinding(readText), biomeReport(root, ["check"])]);
+	check: async ({ exceptions, readText, root }) => {
+		const [preset, report] = await Promise.all([presetFinding(readText), biomeReport(root, ["check"], exceptions)]);
 		return [...preset, ...report.diagnostics.filter((diagnostic) => FAILING.has(diagnostic.severity)).map(findingOf)];
 	},
 	description:

package/src/rules/files/namedAfterExport.ts

@@ -9,7 +9,15 @@ import { CAMEL, KEBAB, sameWord, wordsOf } from "#naming/words.ts";
 import { defineRule, type Finding, type SourceFile } from "#rule.ts";
 import { parse } from "#rules/syntax.ts";
 
-const DEFAULT_TOOL_OWNED: readonly string[] = ["*.config.*", "*.d.ts", "*.d.mts", "*.d.cts"];
+const DEFAULT_TOOL_OWNED: readonly string[] = [
+	"*.config.*",
+	"*.d.ts",
+	"*.d.mts",
+	"*.d.cts",
+	"**/.railway/railway.ts",
+	"**/.railway/railway.py",
+	"**/.railway/railway.go",
+];
 
 const TEST = /\.(?:test|spec)\.[cm]?[jt]sx?$/u;
 

package/src/rules/suppressions/biome/ConsumerDeclaration.ts

@@ -0,0 +1,24 @@
+import { Schema } from "effect";
+import { Declaration } from "./declarations.ts";
+
+const GLOB = /[*!?[\]{}]/u;
+const DIRECTORY = /^\.?[^./\\*!?[\]{}]+$/u;
+const INDIVIDUAL = /^(?:lint|assist)\/(?!domains\/)[a-zA-Z]+\/[a-zA-Z]+$/u;
+
+function namedExclusion(pattern: string): boolean {
+	const segments = pattern.slice(pattern.startsWith("!**/") ? 4 : 1).split("/");
+	return pattern.startsWith("!") && DIRECTORY.test(segments.at(-1) ?? "") && segments.every((segment) => segment === "*" || DIRECTORY.test(segment));
+}
+
+export const ConsumerDeclaration = Declaration.check(
+	Schema.makeFilter(
+		({ includes, rule }) =>
+			rule === "files/includes"
+				? includes.includes("**") && includes.length > 1 && includes.every((pattern) => pattern === "**" || namedExclusion(pattern))
+				: INDIVIDUAL.test(rule) && includes.every((path) => !GLOB.test(path) && /[^/]+\.[^/]+$/u.test(path)),
+		{
+			message:
+				"Declare one lint rule or assist action for explicit files, or files/includes with ** and named directory exclusions. Whole checks, groups and blanket scopes cannot be weakened.",
+		},
+	),
+);

package/src/rules/suppressions/biome-overrides.ts

@@ -1,31 +1,11 @@
 import { Effect, Schema } from "effect";
+import { biomeExceptionHint, missingBiomeFiles } from "#exceptions/biomeFindings.ts";
 import { defineRule, type Finding } from "#rule.ts";
+import { ConsumerDeclaration } from "#rules/suppressions/biome/ConsumerDeclaration.ts";
 import { biomeConfigs, type Chain } from "#rules/suppressions/biome/configs.ts";
-import { Declaration, matches, type Scoped, scoped, scopeText } from "#rules/suppressions/biome/declarations.ts";
+import { matches, type Scoped, scoped, scopeText } from "#rules/suppressions/biome/declarations.ts";
 import { type Weakening, weakeningsOf } from "#rules/suppressions/biome/weakenings.ts";
 
-const GLOB = /[*!?[\]{}]/u;
-const DIRECTORY = /^\.?[^./\\*!?[\]{}]+$/u;
-const INDIVIDUAL = /^(?:lint|assist)\/(?!domains\/)[a-zA-Z]+\/[a-zA-Z]+$/u;
-
-function namedExclusion(pattern: string): boolean {
-	const segments = pattern.slice(pattern.startsWith("!**/") ? 4 : 1).split("/");
-	return pattern.startsWith("!") && DIRECTORY.test(segments.at(-1) ?? "") && segments.every((segment) => segment === "*" || DIRECTORY.test(segment));
-}
-
-const ConsumerDeclaration = Declaration.check(
-	Schema.makeFilter(
-		({ includes, rule }) =>
-			rule === "files/includes"
-				? includes.includes("**") && includes.length > 1 && includes.every((pattern) => pattern === "**" || namedExclusion(pattern))
-				: INDIVIDUAL.test(rule) && includes.every((path) => !GLOB.test(path) && /[^/]+\.[^/]+$/u.test(path)),
-		{
-			message:
-				"Declare one lint rule or assist action for explicit files, or files/includes with ** and named directory exclusions. Whole checks, groups and blanket scopes cannot be weakened.",
-		},
-	),
-);
-
 const BiomeOverridesOptions = Schema.Struct({
 	declared: Schema.Array(ConsumerDeclaration).pipe(Schema.withDecodingDefaultKey(Effect.succeed([]))),
 });
@@ -41,12 +21,12 @@ const shippedBy = ({ base, layers }: Chain): readonly Shipped[] =>
 			: preset.declared.map(({ includes, rule }) => ({ includes: includes.map((glob) => scoped(base, glob)), rule, specifier: preset.specifier })),
 	);
 
-const undeclared = ({ includes, layer, line, rule }: Weakening): Finding =>
+const undeclared = ({ includes, layer, line, rule }: Weakening, configFile: string): Finding =>
 	layer.preset === undefined
 		? {
 				file: layer.path,
 				line,
-				message: `Weakens "${rule}" for ${scopeText(includes)} without a declaration. Repair the code and remove the weakening setting.`,
+				message: `Weakens "${rule}" for ${scopeText(includes)} without a declaration. Repair the code and remove the weakening setting.${Schema.is(ConsumerDeclaration)({ includes, reason: "Permanent exception.", rule }) ? biomeExceptionHint(includes, rule, configFile) : ""}`,
 				subject: rule,
 			}
 		: {
@@ -85,7 +65,8 @@ export const biomeOverrides = defineRule({
 		const covered = (weakening: Weakening): boolean => [...declared, ...shipped].some((declaration) => matches(declaration, weakening));
 		return [
 			...problems,
-			...weakenings.filter((weakening) => !covered(weakening)).map(undeclared),
+			...(await missingBiomeFiles(inputs)),
+			...weakenings.filter((weakening) => !covered(weakening)).map((weakening) => undeclared(weakening, inputs.configFile ?? "quality.config.ts")),
 			...declared.flatMap(staleOrRepeated(root, weakenings, shipped)),
 		];
 	},