@shivaedev/quality 0.17.0 → 0.19.0

package/src/inventory/walk.ts

@@ -1,20 +1,22 @@
-import { join, relative, sep } from "node:path";
+import { dirname, join, relative, sep } from "node:path";
 import { Effect, FileSystem } from "effect";
-import { type FilesystemFailure, orWhenAbsent, readOptionalText } from "./filesystem.ts";
+import { FilesystemFailure, orWhenAbsent, readOptionalText } from "./filesystem.ts";
 import { emptyScope, type IgnoreScope, insideKept, verdictFor, withIgnoreFile } from "./ignore-scope.ts";
+import { trackedPaths } from "./trackedPaths.ts";
 
 const SKIPPED = new Set([".git", "node_modules"]);
 
-export const ignoreScopeAt = (
+export function ignoreScopeAt(
 	dir: string,
 	inherited: IgnoreScope = emptyScope,
-): Effect.Effect<IgnoreScope, FilesystemFailure, FileSystem.FileSystem> =>
-	Effect.map(readOptionalText(join(dir, ".gitignore")), (contents) =>
+): Effect.Effect<IgnoreScope, FilesystemFailure, FileSystem.FileSystem> {
+	return Effect.map(readOptionalText(join(dir, ".gitignore")), (contents) =>
 		contents === undefined || contents === "" ? inherited : withIgnoreFile(inherited, dir, contents),
 	);
+}
 
 // The walk itself never visits the directories between the root and a source, so their ignore files are read here.
-export const scopeAbove = (root: string, dir: string): Effect.Effect<IgnoreScope, FilesystemFailure, FileSystem.FileSystem> => {
+export function scopeAbove(root: string, dir: string): Effect.Effect<IgnoreScope, FilesystemFailure, FileSystem.FileSystem> {
 	const parts = relative(root, dir)
 		.split(sep)
 		.filter((part) => part !== "");
@@ -22,37 +24,64 @@ export const scopeAbove = (root: string, dir: string): Effect.Effect<IgnoreScope
 	return Effect.reduce(
 		ancestors,
 		() => emptyScope,
-		(scope, ancestor) => ignoreScopeAt(ancestor, scope),
+		(scope, ancestor) => (verdictFor(scope, ancestor, true) === "ignored" ? Effect.succeed(scope) : ignoreScopeAt(ancestor, scope)),
 	);
-};
+}
 
-export const walk = (dir: string, inherited: IgnoreScope = emptyScope): Effect.Effect<readonly string[], FilesystemFailure, FileSystem.FileSystem> =>
-	Effect.gen(function* () {
-		const fs = yield* FileSystem.FileSystem;
-		const scope = yield* ignoreScopeAt(dir, inherited);
-		const entries = yield* orWhenAbsent<readonly string[]>(dir, fs.readDirectory(dir), []);
-		const nested = yield* Effect.forEach(
-			entries.filter((entry) => !SKIPPED.has(entry)),
-			(entry) => walkEntry(join(dir, entry), scope),
-			{ concurrency: 1 },
-		);
-		return nested.flat();
+export const walk = Effect.fnUntraced(function* (
+	dir: string,
+	inherited: IgnoreScope = emptyScope,
+): Effect.fn.Return<readonly string[], FilesystemFailure, FileSystem.FileSystem> {
+	const fs = yield* FileSystem.FileSystem;
+	if ((yield* orWhenAbsent<FileSystem.File.Info | undefined>(dir, fs.stat(dir), undefined)) === undefined) {
+		return [];
+	}
+	const paths = yield* Effect.tryPromise({
+		catch: (cause) => new FilesystemFailure({ message: `cannot list tracked files in ${dir}: ${String(cause)}`, path: dir }),
+		try: () => trackedPaths(dir),
 	});
-
-const walkEntry = (path: string, scope: IgnoreScope): Effect.Effect<readonly string[], FilesystemFailure, FileSystem.FileSystem> =>
-	Effect.gen(function* () {
-		const fs = yield* FileSystem.FileSystem;
-		const info = yield* orWhenAbsent<FileSystem.File.Info | undefined>(path, fs.stat(path), undefined);
-		if (info === undefined) {
-			return [];
-		}
-		const directory = info.type === "Directory";
-		const verdict = verdictFor(scope, path, directory);
-		if (verdict === "ignored") {
-			return [];
-		}
-		if (!directory) {
-			return [path];
+	const tracked = new Set(paths);
+	for (const path of paths) {
+		for (let folder = dirname(path); folder !== dir && folder !== dirname(folder); folder = dirname(folder)) {
+			tracked.add(folder);
 		}
-		return yield* walk(path, verdict === "kept" ? insideKept(scope, path) : scope);
-	});
+	}
+	return yield* walkDirectory(dir, inherited, tracked);
+});
+
+const walkDirectory = Effect.fnUntraced(function* (
+	dir: string,
+	inherited: IgnoreScope,
+	tracked: ReadonlySet<string>,
+): Effect.fn.Return<readonly string[], FilesystemFailure, FileSystem.FileSystem> {
+	const fs = yield* FileSystem.FileSystem;
+	const scope = verdictFor(inherited, dir, true) === "ignored" ? inherited : yield* ignoreScopeAt(dir, inherited);
+	const entries = yield* orWhenAbsent<readonly string[]>(dir, fs.readDirectory(dir), []);
+	const nested = yield* Effect.forEach(
+		entries.filter((entry) => !SKIPPED.has(entry)),
+		(entry) => walkEntry(join(dir, entry), scope, tracked),
+		{ concurrency: 1 },
+	);
+	return nested.flat();
+});
+
+const walkEntry = Effect.fnUntraced(function* (
+	path: string,
+	scope: IgnoreScope,
+	tracked: ReadonlySet<string>,
+): Effect.fn.Return<readonly string[], FilesystemFailure, FileSystem.FileSystem> {
+	const fs = yield* FileSystem.FileSystem;
+	const info = yield* orWhenAbsent<FileSystem.File.Info | undefined>(path, fs.stat(path), undefined);
+	if (info === undefined) {
+		return [];
+	}
+	const directory = info.type === "Directory";
+	const verdict = verdictFor(scope, path, directory);
+	if (verdict === "ignored" && !tracked.has(path)) {
+		return [];
+	}
+	if (!directory) {
+		return [path];
+	}
+	return yield* walkDirectory(path, verdict === "kept" ? insideKept(scope, path) : scope, tracked);
+});

package/src/rules/built-in.ts

@@ -11,7 +11,10 @@ import { otherNames } from "#rules/files/otherNames.ts";
 import { importsAliased } from "#rules/imports/aliased.ts";
 import { importCycles } from "#rules/imports/cycles.ts";
 import { importFences } from "#rules/imports/fences.ts";
+import { importsManifest } from "#rules/imports/manifest.ts";
+import { noTestCode } from "#rules/imports/noTestCode.ts";
 import { importsResolvable } from "#rules/imports/resolvable.ts";
+import { importsRuntime } from "#rules/imports/runtime.ts";
 import { storySetup } from "#rules/stories/setup.ts";
 import { biomeOverrides } from "#rules/suppressions/biome-overrides.ts";
 import { biomeRecommended } from "#rules/suppressions/biomeRecommended.ts";
@@ -41,8 +44,11 @@ export const builtInRules = [
 	biome,
 	importCycles,
 	importFences,
+	importsRuntime,
 	importsResolvable,
+	importsManifest,
 	importsAliased,
+	noTestCode,
 	manifestsSorted,
 	namedAfterExport,
 	folderNames,

package/src/rules/comments/max-per-file.ts

@@ -6,7 +6,7 @@ import { commentsOf, type SourceComment } from "./scan.ts";
 
 const MaxPerFileOptions = Schema.Struct({
 	allow: Pragmas,
-	max: Schema.Int.check(Schema.isGreaterThanOrEqualTo(0)).pipe(Schema.withDecodingDefaultKey(Effect.succeed(2))),
+	max: Schema.Int.check(Schema.isGreaterThanOrEqualTo(0), Schema.isLessThanOrEqualTo(2)).pipe(Schema.withDecodingDefaultKey(Effect.succeed(2))),
 });
 
 const continues = (previous: SourceComment | undefined, comment: SourceComment): boolean =>

package/src/rules/files/folderNames.ts

@@ -5,7 +5,7 @@ import { packageLayout } from "#naming/packageLayout.ts";
 import { KEBAB, PASCAL } from "#naming/words.ts";
 import { defineRule, type Finding } from "#rule.ts";
 
-const DEFAULT_TOOL_OWNED: readonly string[] = ["generated/", "migrations/"];
+const DEFAULT_TOOL_OWNED: readonly string[] = ["migrations/"];
 
 const SNAKE = /^[a-z0-9]+(?:_[a-z0-9]+)*$/u;
 

package/src/rules/files/otherNames.ts

@@ -5,16 +5,7 @@ import { CAMEL, KEBAB } from "#naming/words.ts";
 import { defineRule, type Finding } from "#rule.ts";
 import { stylesheetImporters } from "./stylesheetImporters.ts";
 
-const DEFAULT_TOOL_OWNED: readonly string[] = [
-	".*",
-	"package.json",
-	"tsconfig*.json",
-	"biome.json",
-	"biome.jsonc",
-	"*.config.*",
-	"migrations/",
-	"generated/",
-];
+const DEFAULT_TOOL_OWNED: readonly string[] = [".*", "package.json", "tsconfig*.json", "biome.json", "biome.jsonc", "*.config.*", "migrations/"];
 
 const CONVENTIONAL: ReadonlySet<string> = new Set(["AGENTS", "CHANGELOG", "CLAUDE", "CONTRIBUTING", "LICENSE", "README", "SECURITY", "SKILL"]);
 

package/src/rules/imports/bundleInputs.ts

@@ -0,0 +1,94 @@
+import { posix } from "node:path";
+import { outgoing } from "#imports/fences/reach.ts";
+import type { ImportGraph } from "#imports/graph.ts";
+import { packageOf, type WorkspacePackage } from "#imports/workspace.ts";
+
+function blocked(exports: unknown, subpath: string): boolean {
+	if (typeof exports !== "object" || exports === null || Array.isArray(exports)) {
+		return false;
+	}
+	const entries = Object.entries(exports);
+	const exact = entries.find(([key]) => key === subpath);
+	if (exact !== undefined) {
+		return exact[1] === null;
+	}
+	const matching = entries.filter(([key]) => {
+		const [prefix = "", suffix, ...rest] = key.split("*");
+		return (
+			suffix !== undefined
+			&& rest.length === 0
+			&& subpath.length > prefix.length + suffix.length
+			&& subpath.startsWith(prefix)
+			&& subpath.endsWith(suffix)
+		);
+	});
+	const best = matching.toSorted(([left], [right]) => right.indexOf("*") - left.indexOf("*") || right.length - left.length)[0];
+	return best?.[1] === null;
+}
+
+function targets(value: unknown): string[] {
+	if (typeof value === "string") {
+		return [value];
+	}
+	return typeof value === "object" && value !== null ? Object.values(value).flatMap(targets) : [];
+}
+
+function exported(exports: unknown, local: string): boolean {
+	if (typeof exports !== "object" || exports === null) {
+		return false;
+	}
+	const paths = [
+		`./${local}`,
+		`./${local.replace(/^src\//u, "dist/").replace(/\.(?<mode>[cm]?)tsx?$/u, ".$<mode>js")}`,
+		`./${local.replace(/^src\//u, "dist/").replace(/\.(?<mode>[cm]?)tsx?$/u, ".d.$<mode>ts")}`,
+	];
+	return Object.entries(exports).some(([key, value]) =>
+		targets(value).some((target) =>
+			paths.some((path) => {
+				const [prefix = "", suffix] = target.split("*");
+				if (suffix === undefined) {
+					return path === target && !blocked(exports, key);
+				}
+				if (!(path.startsWith(prefix) && path.endsWith(suffix)) || path.length <= prefix.length + suffix.length) {
+					return false;
+				}
+				const star = path.slice(prefix.length, path.length - suffix.length);
+				return !blocked(exports, key.replace("*", star));
+			}),
+		),
+	);
+}
+
+function executable(manifest: object, local: string): boolean {
+	const binTargets = targets(Reflect.get(manifest, "bin"));
+	const built = local.replace(/^src\//u, "dist/").replace(/\.(?<mode>[cm]?)tsx?$/u, ".$<mode>js");
+	return binTargets.some((target) => typeof target === "string" && [local, built].includes(posix.normalize(target)));
+}
+
+export function bundleInputs(graph: ImportGraph, owner: WorkspacePackage, manifest: object, developmentFile: (path: string) => boolean) {
+	const modules = graph.modules.filter((path) => (packageOf(graph.packages, path) ?? (owner.directory === "." ? owner : undefined)) === owner);
+	const privateFiles = new Set(
+		modules.filter((path) => {
+			const local = posix.relative(owner.directory, path);
+			return (
+				local.startsWith("src/")
+				&& blocked(Reflect.get(manifest, "exports"), `./${local.slice(4)}`)
+				&& !exported(Reflect.get(manifest, "exports"), local)
+			);
+		}),
+	);
+	const queue = modules.filter(
+		(path) => executable(manifest, posix.relative(owner.directory, path)) || !(developmentFile(path) || privateFiles.has(path)),
+	);
+	const runtime = new Set(queue);
+	const edges = outgoing(graph.edges);
+	for (const path of queue) {
+		for (const edge of edges.get(path) ?? []) {
+			if (edge.to.kind === "file" && !runtime.has(edge.to.path)) {
+				runtime.add(edge.to.path);
+				queue.push(edge.to.path);
+			}
+		}
+	}
+	return { privateFiles, runtime };
+}

package/src/rules/imports/fences.ts

@@ -1,26 +1,14 @@
 import { Effect, Schema } from "effect";
-import type { Fence } from "#imports/fences/model.ts";
-import { compilePolicy } from "#imports/fences/policy.ts";
-import { importGraph } from "#imports/graph.ts";
+import { checkFences } from "#imports/fences/check.ts";
+import { Declarations } from "#imports/fences/declarations.ts";
 import { defineRule } from "#rule.ts";
 
-function isFence(value: unknown): value is Fence {
-	return typeof value === "object" && value !== null && "_tag" in value && value._tag === "Fence";
-}
-
 const FencesOptions = Schema.Struct({
-	fences: Schema.Array(Schema.declare(isFence, { expected: "a fence made with fence()" })).pipe(Schema.withDecodingDefaultKey(Effect.succeed([]))),
+	fences: Declarations.pipe(Schema.withDecodingDefaultKey(Effect.succeed([]))),
 });
 
 export const importFences = defineRule({
-	check: async ({ options, ...inputs }) => {
-		if (options.fences.length === 0) {
-			return [];
-		}
-		const graph = await importGraph(inputs);
-		const policy = compilePolicy(options.fences, { files: inputs.files, packages: graph.packages });
-		return policy.flatMap((compiled) => compiled.evaluate(graph));
-	},
+	check: ({ options, ...inputs }) => checkFences(inputs, options.fences),
 	description:
 		"Imports of shipped code respect the fences the repository declares; a test file ships nowhere, so no fence holds it. Move the code to the side of the fence its imports belong to.",
 	id: "imports/fences",

package/src/rules/imports/manifest.ts

@@ -0,0 +1,116 @@
+import { posix } from "node:path";
+import { type ImportGraph, importGraph } from "#imports/graph.ts";
+import { builtinName } from "#imports/resolve.ts";
+import { packageOf, type WorkspacePackage } from "#imports/workspace.ts";
+import { isTestCode } from "#naming/testName.ts";
+import { defineRule, type RuleInputs } from "#rule.ts";
+import { bundleInputs } from "./bundleInputs.ts";
+
+const QUERY = /\?.*$/u;
+
+function packageName(specifier: string): string {
+	const bare = specifier.replace(QUERY, "");
+	return (
+		builtinName(bare)
+		?? bare
+			.split("/")
+			.slice(0, bare.startsWith("@") ? 2 : 1)
+			.join("/")
+	);
+}
+
+interface ManifestDependencies {
+	readonly development: ReadonlySet<string>;
+	readonly privateFiles: ReadonlySet<string>;
+	readonly runtime: ReadonlySet<string>;
+	readonly shipped: ReadonlySet<string>;
+}
+
+function names(manifest: object, field: string): readonly string[] {
+	const value: unknown = Reflect.get(manifest, field);
+	if (value === undefined) {
+		return [];
+	}
+	if (typeof value !== "object" || value === null || Array.isArray(value)) {
+		throw new Error(`${field} must be an object`);
+	}
+	return Object.keys(value);
+}
+
+async function manifestDependencies(inputs: RuleInputs, owner: WorkspacePackage, graph: ImportGraph): Promise<ManifestDependencies> {
+	const path = posix.join(owner.directory, "package.json");
+	try {
+		const text = await inputs.readText(path);
+		if (text === undefined) {
+			throw new Error("the manifest is missing");
+		}
+		const manifest: unknown = JSON.parse(text);
+		if (typeof manifest !== "object" || manifest === null || Array.isArray(manifest)) {
+			throw new Error("the manifest must be an object");
+		}
+		return {
+			...bundleInputs(graph, owner, manifest, (candidate) => developmentFile(owner, candidate)),
+			development: new Set(names(manifest, "devDependencies")),
+			shipped: new Set(["dependencies", "peerDependencies", "optionalDependencies"].flatMap((field) => names(manifest, field))),
+		};
+	} catch (cause) {
+		throw new Error(`cannot read dependency policy at ${path}: ${cause instanceof Error ? cause.message : String(cause)}`, { cause });
+	}
+}
+
+const TOOL_FOLDERS = new Set(["script", "scripts", "tooling"]);
+
+const CONFIG_FILE = /(?:^|\.)config\.[cm]?[jt]sx?$/u;
+
+function developmentFile(owner: WorkspacePackage, path: string): boolean {
+	if (isTestCode(path)) {
+		return true;
+	}
+	const local = posix.relative(owner.directory, path);
+	const [folder = ""] = local.split("/");
+	return TOOL_FOLDERS.has(folder) || (!local.includes("/") && CONFIG_FILE.test(local));
+}
+
+function developmentImport(policy: ManifestDependencies | undefined, owner: WorkspacePackage, path: string, runtime: ReadonlySet<string>) {
+	if (runtime.has(path)) {
+		return false;
+	}
+	return developmentFile(owner, path) || policy?.privateFiles.has(path);
+}
+
+export const importsManifest = defineRule({
+	check: async (inputs) => {
+		const graph = await importGraph(inputs);
+		const root: WorkspacePackage | undefined = (await inputs.readText("package.json")) === undefined ? undefined : { directory: ".", name: "." };
+		const owners = [...graph.packages, ...(root === undefined ? [] : [root])];
+		const policies = new Map(await Promise.all(owners.map(async (owner) => [owner, await manifestDependencies(inputs, owner, graph)] as const)));
+		const runtime = new Set([...policies.values()].flatMap((policy) => [...policy.runtime]));
+		const named = new Map(graph.packages.map((owner) => [owner.name, owner]));
+		const requests = [...graph.edges, ...graph.unresolved.filter((request) => request.missing === undefined)];
+		return requests.flatMap((request) => {
+			const owner = packageOf(graph.packages, request.from) ?? root;
+			const target =
+				("to" in request && request.to.kind === "file" ? packageOf(graph.packages, request.to.path) : undefined)
+				?? named.get(packageName(request.specifier));
+			if (owner === undefined || target === undefined || owner === target) {
+				return [];
+			}
+			const policy = policies.get(owner);
+			const development = developmentImport(policy, owner, request.from, runtime);
+			if (policy?.shipped.has(target.name) || (development && policy?.development.has(target.name))) {
+				return [];
+			}
+			return [
+				{
+					file: request.from,
+					line: request.line,
+					message: `Imports workspace package "${target.name}" without declaring it in ${posix.join(owner.directory, "package.json")}. Add it to dependencies, peerDependencies or optionalDependencies, or remove the import.${development ? " Tooling, test code and export-blocked bundle inputs may also use devDependencies." : " devDependencies are only available to tests, test support, tooling and export-blocked bundle inputs unreachable from runtime code."}`,
+					subject: target.name,
+				},
+			];
+		});
+	},
+	description:
+		"Workspace imports follow the importing package's manifest; devDependencies are available only outside runtime code, including export-blocked bundle inputs.",
+	id: "imports/manifest",
+});

package/src/rules/imports/noTestCode.ts

@@ -0,0 +1,18 @@
+import { importGraph } from "#imports/graph.ts";
+import { isTestCode } from "#naming/testName.ts";
+import { defineRule } from "#rule.ts";
+
+export const noTestCode = defineRule({
+	check: async (inputs) =>
+		(await importGraph(inputs)).edges
+			.filter((edge) => !isTestCode(edge.from) && edge.to.kind === "file" && isTestCode(edge.to.path))
+			.map((edge) => ({
+				file: edge.from,
+				line: edge.line,
+				message: `Imports test code through "${edge.specifier}". Move the shared code into a production module and import it from both production and tests.`,
+				subject: edge.specifier,
+			})),
+	description: "Production modules import production code. Move shared code out of test files and test-support/ into a production module.",
+	id: "imports/no-test-code",
+	registrable: false,
+});

package/src/rules/imports/runtime.ts

@@ -0,0 +1,43 @@
+import { browserGlobals } from "#imports/browserGlobals.ts";
+import { importGraph } from "#imports/graph.ts";
+import { builtinName } from "#imports/resolve.ts";
+import { type Runtime, runtimeOf } from "#imports/runtime.ts";
+import { isTestCode } from "#naming/testName.ts";
+import { defineRule } from "#rule.ts";
+
+function forbiddenImport(from: Runtime, to: Runtime | undefined, builtin: boolean): boolean {
+	if (from === "shared") {
+		return to === "client" || to === "server" || builtin;
+	}
+	return from === "client" && (to === "server" || builtin);
+}
+
+export const importsRuntime = defineRule({
+	check: async (inputs) => {
+		const graph = await importGraph(inputs);
+		const runtime = runtimeOf(inputs, graph.packages);
+		const imports = graph.edges.flatMap((edge) => {
+			const from = runtime(edge.from);
+			if (from === undefined || isTestCode(edge.from)) {
+				return [];
+			}
+			const to = edge.to.kind === "file" ? runtime(edge.to.path) : undefined;
+			const builtin = edge.to.kind === "external" && builtinName(edge.to.specifier) !== undefined;
+			if (!forbiddenImport(from, to, builtin)) {
+				return [];
+			}
+			return [
+				{
+					file: edge.from,
+					line: edge.line,
+					message: `${from === "client" ? "Client" : "Shared"} code imports ${builtin ? "Node built-in" : `${to} code`} through "${edge.specifier}". Move runtime-dependent code into src/client/ or src/server/ and keep shared code independent of both runtimes.`,
+					subject: edge.specifier,
+				},
+			];
+		});
+		return [...imports, ...inputs.sources.filter((file) => !isTestCode(file.path) && runtime(file.path) === "shared").flatMap(browserGlobals)];
+	},
+	description:
+		"In packages with src/client/ or src/server/, folder names define runtime boundaries. Shared code runs in either runtime without browser globals or Node built-ins.",
+	id: "imports/runtime",
+});

package/src/rules/max-lines.ts

@@ -1,5 +1,4 @@
 import { Effect, Schema } from "effect";
-import ignore from "ignore";
 import { isTestCode } from "#naming/testName.ts";
 import { defineRule, type Finding, type SourceFile } from "#rule.ts";
 
@@ -8,9 +7,8 @@ const DECLARATION = /\.d\.[cm]?ts$/u;
 const Limit = Schema.Int.check(Schema.isGreaterThan(0));
 
 const MaxLinesOptions = Schema.Struct({
-	source: Limit.pipe(Schema.withDecodingDefaultKey(Effect.succeed(150))),
-	test: Limit.pipe(Schema.withDecodingDefaultKey(Effect.succeed(300))),
-	testFiles: Schema.Array(Schema.String).pipe(Schema.withDecodingDefaultKey(Effect.succeed([]))),
+	source: Limit.check(Schema.isLessThanOrEqualTo(150)).pipe(Schema.withDecodingDefaultKey(Effect.succeed(150))),
+	test: Limit.check(Schema.isLessThanOrEqualTo(300)).pipe(Schema.withDecodingDefaultKey(Effect.succeed(300))),
 });
 
 const oversized = (file: SourceFile, limit: number): readonly Finding[] =>
@@ -26,12 +24,8 @@ const oversized = (file: SourceFile, limit: number): readonly Finding[] =>
 			];
 
 export const maxLines = defineRule({
-	check: ({ options, sources }) => {
-		const suites = ignore().add([...options.testFiles]);
-		return sources
-			.filter((file) => !DECLARATION.test(file.path))
-			.flatMap((file) => oversized(file, isTestCode(file.path) || suites.ignores(file.path) ? options.test : options.source));
-	},
+	check: ({ options, sources }) =>
+		sources.filter((file) => !DECLARATION.test(file.path)).flatMap((file) => oversized(file, isTestCode(file.path) ? options.test : options.source)),
 	description: "Keep each module to one job. Split a long file along its responsibilities; never golf it under the limit.",
 	id: "structure/max-lines",
 	options: Schema.toStandardSchemaV1(MaxLinesOptions, { parseOptions: { errors: "all", onExcessProperty: "error" } }),

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

@@ -4,8 +4,30 @@ import { biomeConfigs, type Chain } from "#rules/suppressions/biome/configs.ts";
 import { Declaration, 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(Declaration).pipe(Schema.withDecodingDefaultKey(Effect.succeed([]))),
+	declared: Schema.Array(ConsumerDeclaration).pipe(Schema.withDecodingDefaultKey(Effect.succeed([]))),
 });
 
 interface Shipped extends Scoped {
@@ -21,11 +43,16 @@ const shippedBy = ({ base, layers }: Chain): readonly Shipped[] =>
 
 const undeclared = ({ includes, layer, line, rule }: Weakening): Finding =>
 	layer.preset === undefined
-		? { file: layer.path, line, message: `Weakens "${rule}" for ${scopeText(includes)} without a declaration.`, subject: rule }
+		? {
+				file: layer.path,
+				line,
+				message: `Weakens "${rule}" for ${scopeText(includes)} without a declaration. Repair the code and remove the weakening setting.`,
+				subject: rule,
+			}
 		: {
 				file: layer.preset.file,
 				line: layer.preset.line,
-				message: `Extends "${layer.preset.specifier}", which weakens "${rule}" for ${scopeText(includes)} without a declaration.`,
+				message: `Extends "${layer.preset.specifier}", which weakens "${rule}" for ${scopeText(includes)} without a declaration. Repair the code and restore the check in the preset.`,
 				subject: rule,
 			};
 
@@ -63,7 +90,7 @@ export const biomeOverrides = defineRule({
 		];
 	},
 	description:
-		"A Biome setting that turns a check off or down, or keeps files out of it, is an exception for every file it covers. Fix the code and remove the setting, or declare its rule, includes and reason under this rule's declared option.",
+		"A Biome setting that turns a check off or down, or keeps files out of it, hides findings for every file it covers. Repair the code and remove the weakening setting.",
 	id: "suppressions/biome-overrides",
 	options: Schema.toStandardSchemaV1(BiomeOverridesOptions, { parseOptions: { errors: "all", onExcessProperty: "error" } }),
 	registrable: false,

package/src/rules/suppressions/biomeRecommended.ts

@@ -22,7 +22,7 @@ function settingOf(rules: Json | undefined, rule: string): Setting {
 	return { level: textOf(node) ?? textOf(member(node, "level")), line: node?.line };
 }
 
-const FIX = `Set it to "error" in the preset, or declare why not in its ${PRESET_DECLARATIONS}.`;
+const FIX = 'Set it to "error" in the preset and repair the code it reports.';
 
 function looseRule(file: string, rule: string, { level, line }: Setting): Finding {
 	const state = level === undefined ? "leaves at Biome's default level" : `sets to "${level}"`;
@@ -65,7 +65,7 @@ export function biomeRecommendedFrom(recommended: () => Promise<readonly string[
 	return defineRule({
 		check: ({ readText }) => check(readText, recommended),
 		description:
-			"Every rule the installed Biome recommends is at error in the shared preset, or the preset declares why not, so a Biome upgrade that adds or changes a recommended rule cannot slip in at Biome's default level.",
+			"Every recommended Biome rule without a shipped internal exception runs at error in the shared preset. Set missing rules to error in the preset and repair the code they report.",
 		id: "suppressions/biome-recommended",
 		registrable: false,
 	});

package/src/rules/suppressions/no-inline.ts

@@ -33,7 +33,7 @@ export const noInline = defineRule({
 			(site) => !allowed(site),
 		),
 	description:
-		"A suppression silences a check at one site instead of fixing the cause. Fix the code; where a lint rule truly cannot apply, turn it off for that scope in the Biome config and declare it under suppressions/biome-overrides. A type test asserts a compile error with @ts-expect-error in a *.typecheck.test.ts or *.typecheck.spec.ts file.",
+		"A suppression silences a check at one site instead of fixing the cause. Repair the code that fails the check and remove the suppression. A type test asserts a compile error with @ts-expect-error in a *.typecheck.test.ts or *.typecheck.spec.ts file.",
 	id: "suppressions/no-inline",
 	registrable: false,
 });

package/src/standard-schema.ts

@@ -16,7 +16,15 @@ export interface StandardIssue {
 	readonly path?: ReadonlyArray<PropertyKey | { readonly key: PropertyKey }> | undefined;
 }
 
-const segment = (part: PropertyKey | { readonly key: PropertyKey }): string => String(typeof part === "object" ? part.key : part);
+// Biome's noBaseToString does not narrow the ternary in segment, so the key is stringified behind a PropertyKey parameter.
+function keyText(key: PropertyKey): string {
+	return key.toString();
+}
+
+function segment(part: PropertyKey | { readonly key: PropertyKey }): string {
+	return keyText(typeof part === "object" ? part.key : part);
+}
 
-export const describeIssue = (issue: StandardIssue): string =>
-	issue.path === undefined || issue.path.length === 0 ? issue.message : `${issue.path.map(segment).join(".")}: ${issue.message}`;
+export function describeIssue(issue: StandardIssue): string {
+	return issue.path === undefined || issue.path.length === 0 ? issue.message : `${issue.path.map(segment).join(".")}: ${issue.message}`;
+}