@shivaedev/quality 0.4.0 → 0.5.0

package/src/cli/args.ts

@@ -4,7 +4,8 @@ import type { WarningDetail } from "../report/render.ts";
 
 export type Command =
 	| { readonly _tag: "Lint"; readonly config: string | undefined; readonly warnings: WarningDetail }
-	| { readonly _tag: "BaselineWrite"; readonly config: string | undefined; readonly rules: ReadonlyArray<string> }
+	| { 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 }
 	| { readonly _tag: "BaselineCheck"; readonly config: string | undefined; readonly against: string | undefined }
 	| { readonly _tag: "BaselineTighten"; readonly config: string | undefined; readonly staged: boolean }
@@ -15,6 +16,7 @@ export type Parsed = { readonly _tag: "Parsed"; readonly command: Command } | {
 
 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]
@@ -23,6 +25,7 @@ export const USAGE = `Usage:
 
 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               Apply Biome's safe fixes, assist actions and formatting.
 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.
@@ -51,15 +54,16 @@ type Values = ReturnType<typeof parseArgs<{ options: typeof OPTIONS; allowPositi
 
 type Option = Exclude<keyof Values, "config" | "help">;
 
-const COMMAND_OPTIONS: ReadonlyArray<Option> = ["against", "from", "rule", "staged", "warnings"];
+const COMMAND_OPTIONS: readonly Option[] = ["against", "from", "rule", "staged", "warnings"];
 
-const ACCEPTS: Readonly<Record<string, ReadonlyArray<Option>>> = {
-	lint: ["warnings"],
-	"baseline write": ["rule"],
-	"baseline prune": ["against"],
-	"baseline tighten": ["staged"],
+const ACCEPTS: Readonly<Record<string, readonly Option[]>> = {
 	"baseline check": ["against"],
 	"baseline migrate": ["from"],
+	"baseline prune": ["against"],
+	"baseline tighten": ["staged"],
+	"baseline write": ["rule"],
+	fix: [],
+	lint: ["warnings"],
 };
 
 const misplaced = (name: string, values: Values): string | undefined => {
@@ -80,6 +84,8 @@ const commandFor = (name: string, values: Values): Parsed => {
 				? parsed({ _tag: "Lint", config, warnings })
 				: usage(`--warnings takes summary or all, not "${warnings}".`);
 		}
+		case "fix":
+			return parsed({ _tag: "Fix", config });
 		case "baseline write":
 			return parsed({ _tag: "BaselineWrite", config, rules: values.rule ?? [] });
 		case "baseline prune":
@@ -93,7 +99,7 @@ const commandFor = (name: string, values: Values): Parsed => {
 	}
 };
 
-export const parseCommand = (args: ReadonlyArray<string>): Parsed => {
+export const parseCommand = (args: readonly string[]): Parsed => {
 	const result = Result.try({
 		catch: (error) => (error instanceof Error ? error.message : String(error)),
 		try: () => parseArgs({ allowPositionals: true, args: [...args], options: OPTIONS, strict: true }),

package/src/cli/baseline.ts

@@ -9,24 +9,23 @@ import { SetupFailure } from "../failure.ts";
 import { writeText } from "../inventory/filesystem.ts";
 import { plural } from "../report/plural.ts";
 
-const save = (session: Session, entries: ReadonlyArray<BaselineEntry>): Effect.Effect<void, SetupFailure, FileSystem.FileSystem> =>
+const save = (session: Session, entries: readonly BaselineEntry[]): Effect.Effect<void, SetupFailure, FileSystem.FileSystem> =>
 	Effect.mapError(
 		writeText(join(session.config.root, session.config.baseline), rewriteBaseline(session.baseline.raw, session.baseline.entries, entries)),
 		(failure) => new SetupFailure({ message: failure.message }),
 	);
 
-const unregistered = (session: Session) =>
-	applyRegistry(session.violations, session.registry, session.config.levels, session.config.unregistrable).kept;
+const unregistered = (session: Session) => applyRegistry(session.violations, session.registry, session.config).kept;
 
 export const writeBaseline = (
 	cwd: string,
 	config: string | undefined,
-	rules: ReadonlyArray<string>,
+	rules: readonly string[],
 ): Effect.Effect<void, SetupFailure, FileSystem.FileSystem> =>
 	Effect.gen(function* () {
 		const session = yield* openSession(cwd, config);
 		const existing = session.baseline.raw === undefined ? undefined : session.baseline.entries;
-		const adoption = adopt(existing, rules, unregistered(session), session.config.levels);
+		const adoption = adopt(existing, rules, unregistered(session), session.config);
 		if (adoption._tag === "Refused") {
 			return yield* new SetupFailure({ message: `baseline write refused:\n${adoption.reasons.map((reason) => `  - ${reason}`).join("\n")}` });
 		}
@@ -57,7 +56,7 @@ export const shrinkBaseline = <Requirements>(
 		if (session.baseline.raw === undefined) {
 			return yield* Console.log(`quality: no baseline at ${session.config.baseline}; nothing to lower.`);
 		}
-		const pruned = prune(session.baseline.entries, unregistered(session), session.config.levels, yield* scopeOf(session));
+		const pruned = prune(session.baseline.entries, unregistered(session), session.config, yield* scopeOf(session));
 		if (pruned.removed === 0 && pruned.lowered === 0 && pruned.moved === 0) {
 			return yield* Console.log(`quality: ${session.config.baseline} is current.`);
 		}

package/src/cli/check.ts

@@ -17,7 +17,7 @@ const baseEntries = (
 	config: ResolvedConfig,
 	base: Base,
 	path: string,
-): Effect.Effect<ReadonlyArray<BaselineEntry>, SetupFailure, FileSystem.FileSystem | Git> =>
+): Effect.Effect<readonly BaselineEntry[], SetupFailure, FileSystem.FileSystem | Git> =>
 	Effect.gen(function* () {
 		const raw = yield* readAt(config.root, base.commit, path);
 		if (raw !== undefined) {

package/src/cli/fix.ts

@@ -0,0 +1,19 @@
+import { Console, Effect, type FileSystem } from "effect";
+import { biomeReport } from "../biome/report.ts";
+import { loadConfig } from "../config/load.ts";
+import { SetupFailure } from "../failure.ts";
+import { sortManifests } from "../manifests/sorted.ts";
+import { plural } from "../report/plural.ts";
+
+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 sorted = yield* Effect.mapError(sortManifests(root), (failure) => new SetupFailure({ message: failure.message }));
+		yield* Console.log(`quality: sort-package-json rewrote ${plural(sorted, "manifest")}.`);
+		const report = yield* Effect.tryPromise({
+			catch: (cause) => new SetupFailure({ message: cause instanceof Error ? cause.message : String(cause) }),
+			try: () => biomeReport(root, ["check", "--write"]),
+		});
+		yield* Console.log(`quality: Biome rewrote ${plural(report.summary.changed, "file")}.`);
+	});
+}

package/src/cli/lint.ts

@@ -11,7 +11,7 @@ export const lint = (
 ): Effect.Effect<void, SetupFailure | GateFailed, FileSystem.FileSystem> =>
 	Effect.gen(function* () {
 		const session = yield* openSession(cwd, config);
-		const outcome = evaluate(session.violations, session.registry, session.baseline.entries, session.config.levels, session.config.unregistrable);
+		const outcome = evaluate(session.violations, session.registry, session.baseline.entries, session.config);
 		yield* Console.log(
 			render(outcome, {
 				baseline: session.config.baseline,

package/src/cli/run-main.ts

@@ -1,3 +1,4 @@
+import process from "node:process";
 import * as NodeChildProcessSpawner from "@effect/platform-node/NodeChildProcessSpawner";
 import * as NodeFileSystem from "@effect/platform-node/NodeFileSystem";
 import * as NodePath from "@effect/platform-node/NodePath";
@@ -20,11 +21,15 @@ const explain = (cause: Cause.Cause<unknown>): Effect.Effect<void> => {
 const exitCodeOf = (error: unknown): number =>
 	typeof error === "object" && error !== null && Runtime.errorExitCode in error ? Runtime.getErrorExitCode(error) : COULD_NOT_RUN;
 
-const teardown: Runtime.Teardown = (exit, onExit) => {
+const exitCode = (exit: Exit.Exit<unknown, unknown>): number => {
 	if (Exit.isSuccess(exit)) {
-		return onExit(0);
+		return 0;
 	}
-	return onExit(Cause.hasInterruptsOnly(exit.cause) ? INTERRUPTED : exitCodeOf(Cause.squash(exit.cause)));
+	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))));
 };
 
 const services = NodeChildProcessSpawner.layer.pipe(Layer.provideMerge(Layer.mergeAll(NodeFileSystem.layer, NodePath.layer)));

package/src/cli.ts

@@ -4,6 +4,7 @@ import { Console, Effect } from "effect";
 import { parseCommand, USAGE } from "./cli/args.ts";
 import { writeBaseline } from "./cli/baseline.ts";
 import { checkBaseline } from "./cli/check.ts";
+import { fix } from "./cli/fix.ts";
 import { lint } from "./cli/lint.ts";
 import { migrateBaseline } from "./cli/migrate.ts";
 import { runMain } from "./cli/run-main.ts";
@@ -22,6 +23,8 @@ const program = Effect.gen(function* () {
 			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":

package/src/config/decode.ts

@@ -3,14 +3,14 @@ import { type Decoded, decodeWith } from "../decoded.ts";
 import type { Rule } from "../rule.ts";
 
 const isRule = (value: unknown): value is Rule =>
-	typeof value === "object" &&
-	value !== null &&
-	"id" in value &&
-	typeof value.id === "string" &&
-	"description" in value &&
-	typeof value.description === "string" &&
-	"configure" in value &&
-	typeof value.configure === "function";
+	typeof value === "object"
+	&& value !== null
+	&& "id" in value
+	&& typeof value.id === "string"
+	&& "description" in value
+	&& typeof value.description === "string"
+	&& "configure" in value
+	&& typeof value.configure === "function";
 
 const Level = Schema.Literals(["error", "warn", "off"]);
 
@@ -19,14 +19,14 @@ const Setting = Schema.Union([Level, Schema.Struct({ level: Schema.optionalKey(L
 const LocalRule = Schema.declare(isRule, { expected: "a rule made with defineRule" });
 
 const ConfigInput = Schema.Struct({
-	sources: Schema.optionalKey(Schema.Array(Schema.String)),
+	adopt: Schema.optionalKey(Schema.Array(Schema.String)),
+	baseline: Schema.optionalKey(Schema.String),
 	exclude: Schema.optionalKey(Schema.Array(Schema.String)),
 	extensions: Schema.optionalKey(Schema.Array(Schema.String)),
-	registry: Schema.optionalKey(Schema.String),
-	baseline: Schema.optionalKey(Schema.String),
-	adopt: Schema.optionalKey(Schema.Array(Schema.String)),
 	local: Schema.optionalKey(Schema.Array(LocalRule)),
+	registry: Schema.optionalKey(Schema.String),
 	rules: Schema.optionalKey(Schema.Record(Schema.String, Setting)),
+	sources: Schema.optionalKey(Schema.Array(Schema.String)),
 });
 
 export type ConfigInput = typeof ConfigInput.Type;

package/src/config/load.ts

@@ -11,11 +11,11 @@ import { type ResolvedRules, resolveRules } from "./resolve.ts";
 const DEFAULT_EXTENSIONS = [".ts", ".tsx", ".mts", ".cts", ".js", ".jsx", ".mjs", ".cjs"];
 
 export interface ResolvedConfig extends ResolvedRules, InventoryScope {
-	readonly root: string;
+	readonly adopt: readonly string[];
+	readonly baseline: string;
 	readonly file: string;
 	readonly registry: string;
-	readonly baseline: string;
-	readonly adopt: ReadonlyArray<string>;
+	readonly root: string;
 }
 
 const messageOf = (cause: unknown): string => (cause instanceof Error ? cause.message : String(cause));
@@ -23,8 +23,8 @@ const messageOf = (cause: unknown): string => (cause instanceof Error ? cause.me
 const importDefault = (file: string): Effect.Effect<unknown, SetupFailure> =>
 	Effect.flatMap(
 		Effect.tryPromise({
-			try: async (): Promise<unknown> => import(pathToFileURL(file).href),
 			catch: (cause) => new SetupFailure({ message: `cannot load ${file}: ${messageOf(cause)}` }),
+			try: async (): Promise<unknown> => import(pathToFileURL(file).href),
 		}),
 		(loaded) =>
 			typeof loaded === "object" && loaded !== null && "default" in loaded

package/src/config/resolve.ts

@@ -2,14 +2,13 @@ import { Effect } from "effect";
 import type { Level } from "../config.ts";
 import type { Decoded } from "../decoded.ts";
 import type { ActiveRule } from "../engine/run-rules.ts";
+import { covers, type RuleIndex } from "../engine/violation.ts";
 import type { Rule } from "../rule.ts";
 import { builtInRules } from "../rules/built-in.ts";
 import type { ConfigInput } from "./decode.ts";
 
-export interface ResolvedRules {
-	readonly active: ReadonlyArray<ActiveRule>;
-	readonly levels: ReadonlyMap<string, Level>;
-	readonly unregistrable: ReadonlySet<string>;
+export interface ResolvedRules extends RuleIndex {
+	readonly active: readonly ActiveRule[];
 }
 
 type Setting = NonNullable<ConfigInput["rules"]>[string];
@@ -20,7 +19,7 @@ const levelOf = (setting: Setting | undefined): Level => (typeof setting === "st
 
 const optionsOf = (setting: Setting | undefined): unknown => (typeof setting === "object" ? setting.options : undefined);
 
-const duplicateIssues = (rules: ReadonlyArray<Rule>): ReadonlyArray<string> =>
+const duplicateIssues = (rules: readonly Rule[]): readonly string[] =>
 	rules.flatMap((rule, index) =>
 		rules.findIndex((other) => other.id === rule.id) === index ? [] : [`local: rule id "${rule.id}" is already defined`],
 	);
@@ -35,7 +34,7 @@ const activate = (rule: Rule, setting: Setting | undefined): Effect.Effect<Decod
 			(configured): Decoded<ActiveRule | undefined> =>
 				configured._tag === "Invalid"
 					? { _tag: "Invalid", issues: configured.issues.map((issue) => `rules.${rule.id}.options: ${issue}`) }
-					: { _tag: "Valid", value: { check: configured.check, description: rule.description, id: rule.id, level } },
+					: { _tag: "Valid", value: { check: configured.check, description: rule.description, family: rule.family === true, id: rule.id, level } },
 		),
 		Effect.catch((failure: string) =>
 			Effect.succeed<Decoded<ActiveRule | undefined>>({ _tag: "Invalid", issues: [`rules.${rule.id}.options: validation threw: ${failure}`] }),
@@ -45,12 +44,17 @@ const activate = (rule: Rule, setting: Setting | undefined): Effect.Effect<Decod
 
 export const resolveRules = (config: ConfigInput): Effect.Effect<Decoded<ResolvedRules>> =>
 	Effect.gen(function* () {
-		const rules: ReadonlyArray<Rule> = [...builtInRules, ...(config.local ?? [])];
+		const rules: readonly Rule[] = [...builtInRules, ...(config.local ?? [])];
 		const settings = config.rules ?? {};
 		const known = new Set(rules.map((rule) => rule.id));
-		const unknown = [...Object.keys(settings).map((id) => `rules.${id}`), ...(config.adopt ?? []).map((id) => `adopt.${id}`)]
-			.filter((path) => !known.has(path.slice(path.indexOf(".") + 1)))
-			.map((path) => `${path}: no built-in or local rule has this id`);
+		const families = new Set(rules.filter((rule) => rule.family === true).map((rule) => rule.id));
+		const adoptable = (id: string): boolean => known.has(id) || [...families].some((family) => covers(family, id));
+		const unknown = [
+			...Object.keys(settings)
+				.filter((id) => !known.has(id))
+				.map((id) => `rules.${id}`),
+			...(config.adopt ?? []).filter((id) => !adoptable(id)).map((id) => `adopt.${id}`),
+		].map((path) => `${path}: no built-in or local rule has this id`);
 		const activated = yield* Effect.forEach(rules, (rule) => activate(rule, settings[rule.id]));
 		const issues = [...duplicateIssues(rules), ...unknown, ...activated.flatMap((result) => (result._tag === "Invalid" ? result.issues : []))];
 		if (issues.length > 0) {
@@ -59,5 +63,5 @@ export const resolveRules = (config: ConfigInput): Effect.Effect<Decoded<Resolve
 		const active = activated.flatMap((result) => (result._tag === "Valid" && result.value !== undefined ? [result.value] : []));
 		const levels = new Map(rules.map((rule) => [rule.id, levelOf(settings[rule.id])]));
 		const unregistrable = new Set(rules.filter((rule) => rule.registrable === false).map((rule) => rule.id));
-		return { _tag: "Valid", value: { active, levels, unregistrable } };
+		return { _tag: "Valid", value: { active, families, levels, unregistrable } };
 	});

package/src/config.ts

@@ -7,23 +7,23 @@ export type RuleSetting<Input> = Level | { readonly level?: Level; readonly opti
 
 type InputOf<Candidate> = Candidate extends Rule<string, infer Input> ? Input : never;
 
-export type RuleSettings<Rules extends ReadonlyArray<Rule>> = {
+export type RuleSettings<Rules extends readonly Rule[]> = {
 	readonly [Candidate in Rules[number] as Candidate["id"]]?: RuleSetting<InputOf<Candidate>>;
 };
 
 export type BuiltInRules = typeof builtInRules;
 
-type IdOf<Rules extends ReadonlyArray<Rule>> = Rules[number]["id"];
+type IdOf<Rules extends readonly Rule[]> = Rules[number]["id"];
 
-export interface QualityConfig<Local extends ReadonlyArray<Rule> = ReadonlyArray<Rule>> {
-	readonly sources?: ReadonlyArray<string>;
-	readonly exclude?: ReadonlyArray<string>;
-	readonly extensions?: ReadonlyArray<string>;
-	readonly registry?: string;
+export interface QualityConfig<Local extends readonly Rule[] = readonly Rule[]> {
+	readonly adopt?: readonly IdOf<readonly [...BuiltInRules, ...Local]>[];
 	readonly baseline?: string;
-	readonly adopt?: ReadonlyArray<IdOf<readonly [...BuiltInRules, ...Local]>>;
+	readonly exclude?: readonly string[];
+	readonly extensions?: readonly string[];
 	readonly local?: Local;
+	readonly registry?: string;
 	readonly rules?: RuleSettings<readonly [...BuiltInRules, ...Local]>;
+	readonly sources?: readonly string[];
 }
 
-export const defineConfig = <const Local extends ReadonlyArray<Rule> = readonly []>(config: QualityConfig<Local>): QualityConfig<Local> => config;
+export const defineConfig = <const Local extends readonly Rule[] = readonly []>(config: QualityConfig<Local>): QualityConfig<Local> => config;

package/src/decoded.ts

@@ -2,7 +2,7 @@ import { Effect } from "effect";
 import { SetupFailure } from "./failure.ts";
 import { describeIssue, type StandardSchemaV1 } from "./standard-schema.ts";
 
-export type Decoded<Value> = { readonly _tag: "Valid"; readonly value: Value } | { readonly _tag: "Invalid"; readonly issues: ReadonlyArray<string> };
+export type Decoded<Value> = { readonly _tag: "Valid"; readonly value: Value } | { readonly _tag: "Invalid"; readonly issues: readonly string[] };
 
 export const decodeWith = async <Output>(schema: StandardSchemaV1<unknown, Output>, value: unknown): Promise<Decoded<Output>> => {
 	const result = await schema["~standard"].validate(value);

package/src/engine/baseline-file.ts

@@ -8,8 +8,8 @@ import { SetupFailure } from "../failure.ts";
 import { readOptionalText } from "../inventory/filesystem.ts";
 
 export interface BaselineFile {
+	readonly entries: readonly BaselineEntry[];
 	readonly raw: string | undefined;
-	readonly entries: ReadonlyArray<BaselineEntry>;
 }
 
 export const readInput = (root: string, path: string): Effect.Effect<string | undefined, SetupFailure, FileSystem.FileSystem> =>

package/src/engine/evaluate.ts

@@ -1,36 +1,34 @@
 import { applyBaseline, type Regression, type StaleBaselineEntry } from "../baseline/compare.ts";
 import type { BaselineEntry } from "../baseline/format.ts";
-import type { Level } from "../config.ts";
 import { applyRegistry, type RegistryEntry, type StaleRegistryEntry } from "../exceptions/registry.ts";
-import { byLocation, type Violation } from "./violation.ts";
+import { byLocation, type RuleIndex, type Violation } from "./violation.ts";
 
 export interface Outcome {
-	readonly errors: ReadonlyArray<Violation>;
-	readonly warnings: ReadonlyArray<Violation>;
-	readonly regressions: ReadonlyArray<Regression>;
-	readonly staleBaseline: ReadonlyArray<StaleBaselineEntry>;
-	readonly looseBaseline: ReadonlyArray<StaleBaselineEntry>;
-	readonly staleRegistry: ReadonlyArray<StaleRegistryEntry>;
 	readonly baselined: number;
+	readonly errors: readonly Violation[];
+	readonly looseBaseline: readonly StaleBaselineEntry[];
 	readonly registered: number;
+	readonly regressions: readonly Regression[];
+	readonly staleBaseline: readonly StaleBaselineEntry[];
+	readonly staleRegistry: readonly StaleRegistryEntry[];
+	readonly warnings: readonly Violation[];
 }
 
 export const evaluate = (
-	violations: ReadonlyArray<Violation>,
-	registry: ReadonlyArray<RegistryEntry>,
-	baseline: ReadonlyArray<BaselineEntry>,
-	levels: ReadonlyMap<string, Level>,
-	unregistrable: ReadonlySet<string>,
+	violations: readonly Violation[],
+	registry: readonly RegistryEntry[],
+	baseline: readonly BaselineEntry[],
+	rules: RuleIndex,
 ): Outcome => {
-	const registered = applyRegistry(violations, registry, levels, unregistrable);
-	const baselined = applyBaseline(registered.kept, baseline, levels);
+	const registered = applyRegistry(violations, registry, rules);
+	const baselined = applyBaseline(registered.kept, baseline, rules);
 	const kept = [...baselined.kept].sort(byLocation);
 	return {
 		baselined: baselined.baselined,
 		errors: kept.filter((violation) => violation.level === "error"),
 		looseBaseline: baselined.loose,
-		regressions: baselined.regressions,
 		registered: registered.registered,
+		regressions: baselined.regressions,
 		staleBaseline: baselined.stale,
 		staleRegistry: registered.stale,
 		warnings: kept.filter((violation) => violation.level === "warn"),

package/src/engine/run-rules.ts

@@ -6,34 +6,35 @@ import type { Finding, Findings, RuleInputs } from "../rule.ts";
 import type { ActiveLevel, Violation } from "./violation.ts";
 
 export interface ActiveRule {
-	readonly id: string;
+	readonly check: (inputs: RuleInputs) => Promise<Findings>;
 	readonly description: string;
+	readonly family: boolean;
+	readonly id: string;
 	readonly level: ActiveLevel;
-	readonly check: (inputs: RuleInputs) => Promise<Findings>;
 }
 
 const messageOf = (cause: unknown): string => (cause instanceof Error ? cause.message : String(cause));
 
 // 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(/^(\.\/)+/, "");
+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 => ({
 	...finding,
 	file: repositoryPath(root, finding.file),
 	level: rule.level,
-	rule: rule.id,
+	rule: rule.family && finding.subject !== undefined ? `${rule.id}/${finding.subject}` : rule.id,
 });
 
-const runRule = (rule: ActiveRule, inputs: RuleInputs): Effect.Effect<ReadonlyArray<Violation>, SetupFailure> =>
+const runRule = (rule: ActiveRule, inputs: RuleInputs): Effect.Effect<readonly Violation[], SetupFailure> =>
 	Effect.map(
 		Effect.tryPromise({
-			try: () => rule.check(inputs),
 			catch: (cause) => new SetupFailure({ message: `rule ${rule.id} failed: ${messageOf(cause)}` }),
+			try: () => rule.check(inputs),
 		}),
 		(findings) => findings.map((finding) => violationOf(rule, inputs.root, finding)),
 	);
 
-export const runRules = (rules: ReadonlyArray<ActiveRule>, inputs: RuleInputs): Effect.Effect<ReadonlyArray<Violation>, SetupFailure> =>
+export const runRules = (rules: readonly ActiveRule[], inputs: RuleInputs): Effect.Effect<readonly Violation[], SetupFailure> =>
 	Effect.map(
 		Effect.forEach(rules, (rule) => runRule(rule, inputs), { concurrency: "unbounded" }),
 		(results) => results.flat(),

package/src/engine/session.ts

@@ -11,11 +11,11 @@ import { runRules } from "./run-rules.ts";
 import type { Violation } from "./violation.ts";
 
 export interface Session {
+	readonly baseline: BaselineFile;
 	readonly config: ResolvedConfig;
 	readonly inventory: Inventory;
-	readonly violations: ReadonlyArray<Violation>;
-	readonly registry: ReadonlyArray<RegistryEntry>;
-	readonly baseline: BaselineFile;
+	readonly registry: readonly RegistryEntry[];
+	readonly violations: readonly Violation[];
 }
 
 const setup = <Value, Requirements>(

package/src/engine/violation.ts

@@ -4,8 +4,8 @@ import type { Finding } from "../rule.ts";
 export type ActiveLevel = "error" | "warn";
 
 export interface Violation extends Finding {
-	readonly rule: string;
 	readonly level: ActiveLevel;
+	readonly rule: string;
 }
 
 export const keyOf = (rule: string, file: string): string => `${rule}\u0000${file}`;
@@ -13,7 +13,7 @@ export const keyOf = (rule: string, file: string): string => `${rule}\u0000${fil
 export const byLocation = (left: Violation, right: Violation): number =>
 	left.rule.localeCompare(right.rule) || left.file.localeCompare(right.file) || (left.line ?? 0) - (right.line ?? 0);
 
-export const groupBy = <Item>(items: ReadonlyArray<Item>, key: (item: Item) => string): ReadonlyMap<string, ReadonlyArray<Item>> => {
+export const groupBy = <Item>(items: readonly Item[], key: (item: Item) => string): ReadonlyMap<string, readonly Item[]> => {
 	const groups = new Map<string, Item[]>();
 	for (const item of items) {
 		const group = groups.get(key(item));
@@ -26,8 +26,22 @@ export const groupBy = <Item>(items: ReadonlyArray<Item>, key: (item: Item) => s
 	return groups;
 };
 
-export const unusedEntryProblem = (levels: ReadonlyMap<string, Level>, rule: string, unused: string): string => {
-	const level = levels.get(rule);
+export interface RuleIndex {
+	readonly families: ReadonlySet<string>;
+	readonly levels: ReadonlyMap<string, Level>;
+	readonly unregistrable: ReadonlySet<string>;
+}
+
+export const covers = (name: string, rule: string): boolean => rule === name || rule.startsWith(`${name}/`);
+
+const ownerOf = (index: RuleIndex, rule: string): string => [...index.families].find((family) => covers(family, rule)) ?? rule;
+
+export const levelOf = (index: RuleIndex, rule: string): Level | undefined => index.levels.get(ownerOf(index, rule));
+
+export const registrable = (index: RuleIndex, rule: string): boolean => !index.unregistrable.has(ownerOf(index, rule));
+
+export const unusedEntryProblem = (index: RuleIndex, rule: string, unused: string): string => {
+	const level = levelOf(index, rule);
 	if (level === undefined) {
 		return "names no known rule";
 	}

package/src/exceptions/registry.ts

@@ -1,13 +1,12 @@
 import { Schema } from "effect";
-import type { Level } from "../config.ts";
 import { type Decoded, decodeWith } from "../decoded.ts";
-import { unusedEntryProblem, type Violation } from "../engine/violation.ts";
+import { type RuleIndex, registrable, unusedEntryProblem, type Violation } from "../engine/violation.ts";
 
 const RegistryEntry = Schema.Struct({
-	rule: Schema.NonEmptyString,
 	file: Schema.NonEmptyString,
+	reason: Schema.String.check(Schema.isPattern(/\S/u, { expected: "a reason that says why the exception is permanent" })),
+	rule: Schema.NonEmptyString,
 	subject: Schema.optionalKey(Schema.NonEmptyString),
-	reason: Schema.String.check(Schema.isPattern(/\S/, { expected: "a reason that says why the exception is permanent" })),
 });
 
 export type RegistryEntry = typeof RegistryEntry.Type;
@@ -16,7 +15,7 @@ const standard = Schema.toStandardSchemaV1(Schema.fromJsonString(Schema.Array(Re
 	parseOptions: { errors: "all", onExcessProperty: "error" },
 });
 
-export const decodeRegistry = (raw: string | undefined): Promise<Decoded<ReadonlyArray<RegistryEntry>>> =>
+export const decodeRegistry = (raw: string | undefined): Promise<Decoded<readonly RegistryEntry[]>> =>
 	raw === undefined ? Promise.resolve({ _tag: "Valid", value: [] }) : decodeWith(standard, raw);
 
 export interface StaleRegistryEntry {
@@ -25,9 +24,9 @@ export interface StaleRegistryEntry {
 }
 
 export interface RegistryCheck {
-	readonly kept: ReadonlyArray<Violation>;
+	readonly kept: readonly Violation[];
 	readonly registered: number;
-	readonly stale: ReadonlyArray<StaleRegistryEntry>;
+	readonly stale: readonly StaleRegistryEntry[];
 }
 
 const covers = (entry: RegistryEntry, violation: Violation): boolean =>
@@ -35,18 +34,13 @@ const covers = (entry: RegistryEntry, violation: Violation): boolean =>
 
 const UNREGISTRABLE = "names a rule that takes no exceptions. Fix the code, or baseline the violations while the repository adopts the rule";
 
-const coveringEntry = (entries: ReadonlyArray<RegistryEntry>, violation: Violation): RegistryEntry | undefined => {
+const coveringEntry = (entries: readonly RegistryEntry[], violation: Violation): RegistryEntry | undefined => {
 	const matching = entries.filter((entry) => covers(entry, violation));
 	return matching.find((entry) => entry.subject !== undefined) ?? matching[0];
 };
 
-export const applyRegistry = (
-	violations: ReadonlyArray<Violation>,
-	entries: ReadonlyArray<RegistryEntry>,
-	levels: ReadonlyMap<string, Level>,
-	unregistrable: ReadonlySet<string>,
-): RegistryCheck => {
-	const usable = entries.filter((entry) => !unregistrable.has(entry.rule));
+export const applyRegistry = (violations: readonly Violation[], entries: readonly RegistryEntry[], rules: RuleIndex): RegistryCheck => {
+	const usable = entries.filter((entry) => registrable(rules, entry.rule));
 	const used = new Set<RegistryEntry>();
 	const kept = violations.filter((violation) => {
 		const entry = coveringEntry(usable, violation);
@@ -59,7 +53,7 @@ export const applyRegistry = (
 		.filter((entry) => !used.has(entry))
 		.map((entry) => ({
 			entry,
-			problem: unregistrable.has(entry.rule) ? UNREGISTRABLE : unusedEntryProblem(levels, entry.rule, "matches no violation"),
+			problem: registrable(rules, entry.rule) ? unusedEntryProblem(rules, entry.rule, "matches no violation") : UNREGISTRABLE,
 		}));
 	return { kept, registered: violations.length - kept.length, stale };
 };

package/src/git/base.ts

@@ -3,8 +3,8 @@ import { SetupFailure } from "../failure.ts";
 import { type Git, git } from "./command.ts";
 
 export interface Base {
-	readonly ref: string;
 	readonly commit: string;
+	readonly ref: string;
 }
 
 const FALLBACK_BRANCHES = ["origin/main", "origin/master"];
@@ -36,7 +36,7 @@ const isShallow = (root: string): Effect.Effect<boolean, SetupFailure, Git> =>
 const mergeBase = (root: string, ref: string): Effect.Effect<string | undefined, SetupFailure, Git> =>
 	Effect.map(git(root, ["merge-base", "HEAD", ref]), (result) => (result.code === 0 ? result.stdout.trim() : undefined));
 
-const remoteOf = (root: string, ref: string): Effect.Effect<ReadonlyArray<string>, SetupFailure, Git> =>
+const remoteOf = (root: string, ref: string): Effect.Effect<readonly string[], SetupFailure, Git> =>
 	Effect.gen(function* () {
 		const name = (yield* git(root, ["rev-parse", "--symbolic-full-name", ref])).stdout.trim();
 		const remotes = (yield* git(root, ["remote"])).stdout.split("\n");