@shivaedev/quality 0.2.0 → 0.3.0

package/src/cli/run-main.ts

@@ -1,7 +1,10 @@
+import * as NodeChildProcessSpawner from "@effect/platform-node/NodeChildProcessSpawner";
 import * as NodeFileSystem from "@effect/platform-node/NodeFileSystem";
+import * as NodePath from "@effect/platform-node/NodePath";
 import * as NodeRuntime from "@effect/platform-node/NodeRuntime";
-import { Cause, Console, Effect, Exit, type FileSystem, Runtime } from "effect";
+import { Cause, Console, Effect, Exit, type FileSystem, Layer, Runtime } from "effect";
 import { SetupFailure } from "../failure.ts";
+import type { Git } from "../git/command.ts";
 
 const INTERRUPTED = 130;
 const COULD_NOT_RUN = 2;
@@ -24,7 +27,9 @@ const teardown: Runtime.Teardown = (exit, onExit) => {
 	return onExit(Cause.hasInterruptsOnly(exit.cause) ? INTERRUPTED : exitCodeOf(Cause.squash(exit.cause)));
 };
 
-export const runMain = <Value, Error>(program: Effect.Effect<Value, Error, FileSystem.FileSystem>): void => {
+const services = NodeChildProcessSpawner.layer.pipe(Layer.provideMerge(Layer.mergeAll(NodeFileSystem.layer, NodePath.layer)));
+
+export const runMain = <Value, Error>(program: Effect.Effect<Value, Error, FileSystem.FileSystem | Git>): void => {
 	const explained = Effect.tapCause(program, (cause) => (Cause.hasInterruptsOnly(cause) ? Effect.void : explain(cause)));
-	NodeRuntime.runMain(Effect.provide(explained, NodeFileSystem.layer), { disableErrorReporting: true, teardown });
+	NodeRuntime.runMain(Effect.provide(explained, services), { disableErrorReporting: true, teardown });
 };

package/src/cli/shrink.ts

@@ -0,0 +1,31 @@
+import { Console, Effect, type FileSystem } from "effect";
+import type { Scope } from "../baseline/update.ts";
+import type { SetupFailure } from "../failure.ts";
+import { resolveBase } from "../git/base.ts";
+import type { Git } from "../git/command.ts";
+import { changesSince } from "../git/history.ts";
+import { shrinkBaseline } from "./baseline.ts";
+
+const followedMoves = (root: string, against: string | undefined): Effect.Effect<Scope, SetupFailure, Git> =>
+	resolveBase(root, against).pipe(
+		Effect.flatMap((base) => changesSince(root, [base.commit])),
+		Effect.map((changes): Scope => ({ moves: changes.moves })),
+		Effect.catchIf(
+			() => against === undefined,
+			(failure) => Effect.as(Console.error(`quality: moved files are not followed: ${failure.message}`), { moves: new Map() }),
+		),
+	);
+
+export const pruneBaseline = (
+	cwd: string,
+	config: string | undefined,
+	against: string | undefined,
+): Effect.Effect<void, SetupFailure, FileSystem.FileSystem | Git> =>
+	shrinkBaseline(cwd, config, (session) => followedMoves(session.config.root, against));
+
+export const tightenBaseline = (
+	cwd: string,
+	config: string | undefined,
+	staged: boolean,
+): Effect.Effect<void, SetupFailure, FileSystem.FileSystem | Git> =>
+	shrinkBaseline(cwd, config, (session) => changesSince(session.config.root, staged ? ["--cached"] : ["HEAD"]));

package/src/cli.ts

@@ -2,9 +2,12 @@
 import process from "node:process";
 import { Console, Effect } from "effect";
 import { parseCommand, USAGE } from "./cli/args.ts";
-import { pruneBaseline, writeBaseline } from "./cli/baseline.ts";
+import { writeBaseline } from "./cli/baseline.ts";
+import { checkBaseline } from "./cli/check.ts";
 import { lint } from "./cli/lint.ts";
+import { migrateBaseline } from "./cli/migrate.ts";
 import { runMain } from "./cli/run-main.ts";
+import { pruneBaseline, tightenBaseline } from "./cli/shrink.ts";
 import { SetupFailure } from "./failure.ts";
 
 const parsed = parseCommand(process.argv.slice(2));
@@ -22,7 +25,13 @@ const program = Effect.gen(function* () {
 		case "BaselineWrite":
 			return yield* writeBaseline(process.cwd(), command.config, command.rules);
 		case "BaselinePrune":
-			return yield* pruneBaseline(process.cwd(), command.config);
+			return yield* pruneBaseline(process.cwd(), command.config, command.against);
+		case "BaselineTighten":
+			return yield* tightenBaseline(process.cwd(), command.config, command.staged);
+		case "BaselineCheck":
+			return yield* checkBaseline(process.cwd(), command.config, command.against);
+		case "BaselineMigrate":
+			return yield* migrateBaseline(process.cwd(), command.config, command.from);
 	}
 });
 

package/src/config/decode.ts

@@ -24,6 +24,7 @@ const ConfigInput = Schema.Struct({
 	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)),
 	rules: Schema.optionalKey(Schema.Record(Schema.String, Setting)),
 });

package/src/config/file.ts

@@ -0,0 +1 @@
+export const CONFIG_FILE = "quality.config.ts";

package/src/config/load.ts

@@ -5,10 +5,9 @@ import { validOrFail } from "../decoded.ts";
 import { SetupFailure } from "../failure.ts";
 import type { InventoryScope } from "../inventory/collect.ts";
 import { type ConfigInput, decodeConfig } from "./decode.ts";
+import { CONFIG_FILE } from "./file.ts";
 import { type ResolvedRules, resolveRules } from "./resolve.ts";
 
-export const CONFIG_FILE = "quality.config.ts";
-
 const DEFAULT_EXTENSIONS = [".ts", ".tsx", ".mts", ".cts", ".js", ".jsx", ".mjs", ".cjs"];
 
 export interface ResolvedConfig extends ResolvedRules, InventoryScope {
@@ -16,6 +15,7 @@ export interface ResolvedConfig extends ResolvedRules, InventoryScope {
 	readonly file: string;
 	readonly registry: string;
 	readonly baseline: string;
+	readonly adopt: ReadonlyArray<string>;
 }
 
 const messageOf = (cause: unknown): string => (cause instanceof Error ? cause.message : String(cause));
@@ -34,7 +34,8 @@ const importDefault = (file: string): Effect.Effect<unknown, SetupFailure> =>
 
 const resolved = (root: string, file: string, config: ConfigInput, rules: ResolvedRules): ResolvedConfig => ({
 	...rules,
-	baseline: config.baseline ?? "quality/baseline.json",
+	adopt: config.adopt ?? [],
+	baseline: config.baseline ?? "quality/baseline.jsonl",
 	exclude: config.exclude ?? [],
 	extensions: config.extensions ?? DEFAULT_EXTENSIONS,
 	file,

package/src/config/resolve.ts

@@ -9,6 +9,7 @@ import type { ConfigInput } from "./decode.ts";
 export interface ResolvedRules {
 	readonly active: ReadonlyArray<ActiveRule>;
 	readonly levels: ReadonlyMap<string, Level>;
+	readonly unregistrable: ReadonlySet<string>;
 }
 
 type Setting = NonNullable<ConfigInput["rules"]>[string];
@@ -47,14 +48,16 @@ export const resolveRules = (config: ConfigInput): Effect.Effect<Decoded<Resolve
 		const rules: ReadonlyArray<Rule> = [...builtInRules, ...(config.local ?? [])];
 		const settings = config.rules ?? {};
 		const known = new Set(rules.map((rule) => rule.id));
-		const unknown = Object.keys(settings)
-			.filter((id) => !known.has(id))
-			.map((id) => `rules.${id}: no built-in or local rule has this 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 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) {
 			return { _tag: "Invalid", issues };
 		}
 		const active = activated.flatMap((result) => (result._tag === "Valid" && result.value !== undefined ? [result.value] : []));
-		return { _tag: "Valid", value: { active, levels: new Map(rules.map((rule) => [rule.id, levelOf(settings[rule.id])])) } };
+		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 } };
 	});

package/src/config.ts

@@ -1,7 +1,6 @@
 import type { Rule } from "./rule.ts";
 import type { builtInRules } from "./rules/built-in.ts";
 
-/** Every rule defaults to `error`. `warn` is for the transition to a rule and is meant to be temporary. */
 export type Level = "error" | "warn" | "off";
 
 export type RuleSetting<Input> = Level | { readonly level?: Level; readonly options?: Input };
@@ -14,18 +13,15 @@ export type RuleSettings<Rules extends ReadonlyArray<Rule>> = {
 
 export type BuiltInRules = typeof builtInRules;
 
+type IdOf<Rules extends ReadonlyArray<Rule>> = Rules[number]["id"];
+
 export interface QualityConfig<Local extends ReadonlyArray<Rule> = ReadonlyArray<Rule>> {
-	/** Directories or files to check, relative to the config file. Defaults to the whole repository. */
 	readonly sources?: ReadonlyArray<string>;
-	/** Paths never checked, in .gitignore syntax. Ignored files are always skipped. */
 	readonly exclude?: ReadonlyArray<string>;
-	/** Extensions of the source files rules read. Defaults to TypeScript and JavaScript modules. */
 	readonly extensions?: ReadonlyArray<string>;
-	/** Permanent exceptions, each with a reason. Defaults to `quality/registry.json`. */
 	readonly registry?: string;
-	/** Existing violations that may only shrink. Defaults to `quality/baseline.json`. */
 	readonly baseline?: string;
-	/** Repository rules, reported, registered and baselined like the built-in ones. */
+	readonly adopt?: ReadonlyArray<IdOf<readonly [...BuiltInRules, ...Local]>>;
 	readonly local?: Local;
 	readonly rules?: RuleSettings<readonly [...BuiltInRules, ...Local]>;
 }

package/src/engine/baseline-file.ts

@@ -0,0 +1,27 @@
+import { join } from "node:path";
+import { Effect, type FileSystem } from "effect";
+import { type BaselineEntry, decodeBaseline } from "../baseline/format.ts";
+import { LEGACY_BASELINE } from "../baseline/legacy.ts";
+import type { ResolvedConfig } from "../config/load.ts";
+import { validOrFail } from "../decoded.ts";
+import { SetupFailure } from "../failure.ts";
+import { readOptionalText } from "../inventory/filesystem.ts";
+
+export interface BaselineFile {
+	readonly raw: string | undefined;
+	readonly entries: ReadonlyArray<BaselineEntry>;
+}
+
+export const readInput = (root: string, path: string): Effect.Effect<string | undefined, SetupFailure, FileSystem.FileSystem> =>
+	Effect.mapError(readOptionalText(join(root, path)), (failure) => new SetupFailure({ message: failure.message }));
+
+export const readBaseline = (config: ResolvedConfig): Effect.Effect<BaselineFile, SetupFailure, FileSystem.FileSystem> =>
+	Effect.gen(function* () {
+		const raw = yield* readInput(config.root, config.baseline);
+		if (raw === undefined && config.baseline !== LEGACY_BASELINE && (yield* readInput(config.root, LEGACY_BASELINE)) !== undefined) {
+			return yield* new SetupFailure({
+				message: `${LEGACY_BASELINE} holds a baseline in the earlier JSON format. Run \`quality baseline migrate\` to move it to ${config.baseline}.`,
+			});
+		}
+		return { entries: yield* validOrFail(config.baseline, yield* Effect.promise(() => decodeBaseline(raw))), raw };
+	});

package/src/engine/evaluate.ts

@@ -9,24 +9,26 @@ export interface Outcome {
 	readonly warnings: ReadonlyArray<Violation>;
 	readonly regressions: ReadonlyArray<Regression>;
 	readonly staleBaseline: ReadonlyArray<StaleBaselineEntry>;
+	readonly looseBaseline: ReadonlyArray<StaleBaselineEntry>;
 	readonly staleRegistry: ReadonlyArray<StaleRegistryEntry>;
 	readonly baselined: number;
 	readonly registered: number;
 }
 
-/** Registered exceptions apply first; the baseline then covers what is left, per rule and file. */
 export const evaluate = (
 	violations: ReadonlyArray<Violation>,
 	registry: ReadonlyArray<RegistryEntry>,
 	baseline: ReadonlyArray<BaselineEntry>,
 	levels: ReadonlyMap<string, Level>,
+	unregistrable: ReadonlySet<string>,
 ): Outcome => {
-	const registered = applyRegistry(violations, registry, levels);
+	const registered = applyRegistry(violations, registry, levels, unregistrable);
 	const baselined = applyBaseline(registered.kept, baseline, levels);
 	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,
 		staleBaseline: baselined.stale,

package/src/engine/session.ts

@@ -1,12 +1,12 @@
-import { join, resolve } from "node:path";
+import { resolve } from "node:path";
 import { Effect, type FileSystem } from "effect";
-import { type BaselineEntry, decodeBaseline } from "../baseline/format.ts";
 import { loadConfig, type ResolvedConfig } from "../config/load.ts";
 import { validOrFail } from "../decoded.ts";
 import { decodeRegistry, type RegistryEntry } from "../exceptions/registry.ts";
 import { SetupFailure } from "../failure.ts";
 import { collectInventory, type Inventory } from "../inventory/collect.ts";
 import { type FilesystemFailure, readOptionalText } from "../inventory/filesystem.ts";
+import { type BaselineFile, readBaseline, readInput } from "./baseline-file.ts";
 import { runRules } from "./run-rules.ts";
 import type { Violation } from "./violation.ts";
 
@@ -15,26 +15,28 @@ export interface Session {
 	readonly inventory: Inventory;
 	readonly violations: ReadonlyArray<Violation>;
 	readonly registry: ReadonlyArray<RegistryEntry>;
-	readonly baseline: { readonly raw: string | undefined; readonly entries: ReadonlyArray<BaselineEntry> };
+	readonly baseline: BaselineFile;
 }
 
 const setup = <Value, Requirements>(
 	effect: Effect.Effect<Value, FilesystemFailure, Requirements>,
 ): Effect.Effect<Value, SetupFailure, Requirements> => Effect.mapError(effect, (failure) => new SetupFailure({ message: failure.message }));
 
-const readInput = (root: string, path: string): Effect.Effect<string | undefined, SetupFailure, FileSystem.FileSystem> =>
-	setup(readOptionalText(join(root, path)));
+export const scan = (config: ResolvedConfig): Effect.Effect<Pick<Session, "inventory" | "violations">, SetupFailure, FileSystem.FileSystem> =>
+	Effect.gen(function* () {
+		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 });
+		return { inventory, violations };
+	});
 
 export const openSession = (cwd: string, configPath: string | undefined): Effect.Effect<Session, SetupFailure, FileSystem.FileSystem> =>
 	Effect.gen(function* () {
 		const config = yield* loadConfig(cwd, configPath);
-		const inventory = yield* setup(collectInventory(config.root, config));
 		const registryRaw = yield* readInput(config.root, config.registry);
 		const registry = yield* validOrFail(config.registry, yield* Effect.promise(() => decodeRegistry(registryRaw)));
-		const baselineRaw = yield* readInput(config.root, config.baseline);
-		const baseline = yield* validOrFail(config.baseline, yield* Effect.promise(() => decodeBaseline(baselineRaw)));
-		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 });
-		return { baseline: { entries: baseline, raw: baselineRaw }, config, inventory, registry, violations };
+		const baseline = yield* readBaseline(config);
+		const { inventory, violations } = yield* scan(config);
+		return { baseline, config, inventory, registry, violations };
 	});

package/src/exceptions/registry.ts

@@ -33,6 +33,8 @@ export interface RegistryCheck {
 const covers = (entry: RegistryEntry, violation: Violation): boolean =>
 	entry.rule === violation.rule && entry.file === violation.file && (entry.subject === undefined || entry.subject === violation.subject);
 
+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 matching = entries.filter((entry) => covers(entry, violation));
 	return matching.find((entry) => entry.subject !== undefined) ?? matching[0];
@@ -42,10 +44,12 @@ 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));
 	const used = new Set<RegistryEntry>();
 	const kept = violations.filter((violation) => {
-		const entry = coveringEntry(entries, violation);
+		const entry = coveringEntry(usable, violation);
 		if (entry !== undefined) {
 			used.add(entry);
 		}
@@ -53,6 +57,9 @@ export const applyRegistry = (
 	});
 	const stale = entries
 		.filter((entry) => !used.has(entry))
-		.map((entry) => ({ entry, problem: unusedEntryProblem(levels, entry.rule, "matches no violation") }));
+		.map((entry) => ({
+			entry,
+			problem: unregistrable.has(entry.rule) ? UNREGISTRABLE : unusedEntryProblem(levels, entry.rule, "matches no violation"),
+		}));
 	return { kept, registered: violations.length - kept.length, stale };
 };

package/src/failure.ts

@@ -1,12 +1,10 @@
 import { Data, Runtime } from "effect";
 
-/** The check could not run: invalid configuration, unreadable input or a crashed rule. Exits 2. */
 export class SetupFailure extends Data.TaggedError("SetupFailure")<{ readonly message: string }> {
 	override readonly [Runtime.errorReported] = false;
 	override readonly [Runtime.errorExitCode] = 2;
 }
 
-/** The check ran and the repository fails the gate. The report is already printed. Exits 1. */
 export class GateFailed extends Data.TaggedError("GateFailed") {
 	override readonly [Runtime.errorReported] = false;
 	override readonly [Runtime.errorExitCode] = 1;

package/src/git/base.ts

@@ -0,0 +1,54 @@
+import { Effect } from "effect";
+import { SetupFailure } from "../failure.ts";
+import { type Git, git } from "./command.ts";
+
+export interface Base {
+	readonly ref: string;
+	readonly commit: string;
+}
+
+const FALLBACK_BRANCHES = ["origin/main", "origin/master"];
+
+const fail = (message: string) => Effect.fail(new SetupFailure({ message }));
+
+const isCommit = (root: string, ref: string): Effect.Effect<boolean, SetupFailure, Git> =>
+	Effect.map(git(root, ["rev-parse", "--verify", "--quiet", `${ref}^{commit}`]), (result) => result.code === 0);
+
+const defaultBranch = (root: string): Effect.Effect<string, SetupFailure, Git> =>
+	Effect.gen(function* () {
+		const head = yield* git(root, ["symbolic-ref", "--quiet", "--short", "refs/remotes/origin/HEAD"]);
+		if (head.code === 0) {
+			return head.stdout.trim();
+		}
+		for (const candidate of FALLBACK_BRANCHES) {
+			if (yield* isCommit(root, candidate)) {
+				return candidate;
+			}
+		}
+		return yield* fail(
+			"cannot find the default branch: origin/HEAD, origin/main and origin/master are missing. Pass --against <ref>, or run `git remote set-head origin --auto`.",
+		);
+	});
+
+const missingMergeBase = (root: string, ref: string): Effect.Effect<never, SetupFailure, Git> =>
+	Effect.flatMap(git(root, ["rev-parse", "--is-shallow-repository"]), (shallow) =>
+		fail(
+			shallow.stdout.trim() === "true"
+				? `the clone is shallow and does not reach the merge base of HEAD and ${ref}. Fetch the history first: \`git fetch --unshallow\`, or fetch-depth: 0 in actions/checkout.`
+				: `HEAD and ${ref} share no history.`,
+		),
+	);
+
+export const resolveBase = (root: string, against: string | undefined): Effect.Effect<Base, SetupFailure, Git> =>
+	Effect.gen(function* () {
+		const inside = yield* git(root, ["rev-parse", "--is-inside-work-tree"]);
+		if (inside.code !== 0 || inside.stdout.trim() !== "true") {
+			return yield* fail(`${root} is not in a git work tree; the baseline is compared with its version in git history.`);
+		}
+		const ref = against ?? (yield* defaultBranch(root));
+		if (!(yield* isCommit(root, ref))) {
+			return yield* fail(`${ref} names no commit in this clone. Fetch it first, or pass another --against <ref>.`);
+		}
+		const merged = yield* git(root, ["merge-base", "HEAD", ref]);
+		return merged.code === 0 ? { commit: merged.stdout.trim(), ref } : yield* missingMergeBase(root, ref);
+	});

package/src/git/command.ts

@@ -0,0 +1,31 @@
+import { Effect, Stream } from "effect";
+import { ChildProcess, ChildProcessSpawner } from "effect/unstable/process";
+import { SetupFailure } from "../failure.ts";
+
+export interface GitResult {
+	readonly code: number;
+	readonly stdout: string;
+	readonly stderr: string;
+}
+
+export type Git = ChildProcessSpawner.ChildProcessSpawner;
+
+export const git = (cwd: string, args: ReadonlyArray<string>): Effect.Effect<GitResult, SetupFailure, Git> =>
+	Effect.scoped(
+		Effect.gen(function* () {
+			const spawner = yield* ChildProcessSpawner.ChildProcessSpawner;
+			const child = yield* spawner.spawn(ChildProcess.make("git", [...args], { cwd, stdin: "ignore" }));
+			const [stdout, stderr, code] = yield* Effect.all(
+				[Stream.mkString(Stream.decodeText(child.stdout)), Stream.mkString(Stream.decodeText(child.stderr)), child.exitCode],
+				{ concurrency: "unbounded" },
+			);
+			return { code: Number(code), stderr, stdout };
+		}),
+	).pipe(Effect.mapError((error) => new SetupFailure({ message: `cannot run git: ${error.message}` })));
+
+export const gitOrFail = (cwd: string, args: ReadonlyArray<string>): Effect.Effect<string, SetupFailure, Git> =>
+	Effect.flatMap(git(cwd, args), (result) =>
+		result.code === 0
+			? Effect.succeed(result.stdout)
+			: Effect.fail(new SetupFailure({ message: `git ${args[0]} failed: ${result.stderr.trim() || `exit code ${result.code}`}` })),
+	);

package/src/git/history.ts

@@ -0,0 +1,41 @@
+import { Effect } from "effect";
+import type { SetupFailure } from "../failure.ts";
+import { type Git, git, gitOrFail } from "./command.ts";
+
+export interface Changes {
+	readonly files: ReadonlySet<string>;
+	readonly moves: ReadonlyMap<string, string>;
+}
+
+export const readAt = (root: string, commit: string, path: string): Effect.Effect<string | undefined, SetupFailure, Git> =>
+	Effect.gen(function* () {
+		const object = `${commit}:./${path}`;
+		const present = yield* git(root, ["cat-file", "-e", object]);
+		return present.code === 0 ? yield* gitOrFail(root, ["cat-file", "blob", object]) : undefined;
+	});
+
+const parse = (output: string): Changes => {
+	const fields = output.split("\0");
+	const files = new Set<string>();
+	const moves = new Map<string, string>();
+	for (let index = 0; index < fields.length - 1; ) {
+		const status = fields[index] ?? "";
+		const paths = fields.slice(index + 1, index + (/^[RC]/.test(status) ? 3 : 2));
+		for (const path of paths) {
+			files.add(path);
+		}
+		const [from, to] = paths;
+		if (status.startsWith("R") && from !== undefined && to !== undefined) {
+			moves.set(from, to);
+		}
+		index += paths.length + 1;
+	}
+	return { files, moves };
+};
+
+// Paths are relative to the root, and only tracked files count: a move is seen once both of its sides are staged.
+export const changesSince = (root: string, revision: ReadonlyArray<string>): Effect.Effect<Changes, SetupFailure, Git> =>
+	Effect.map(
+		gitOrFail(root, ["diff", "--no-color", "--no-ext-diff", "--find-renames", "--name-status", "-z", "--relative", ...revision, "--"]),
+		parse,
+	);

package/src/inventory/ignore-scope.ts

@@ -39,6 +39,5 @@ const matcherVerdict = (matcher: IgnoreMatcher, boundary: string | undefined, pa
 	return result.unignored ? "kept" : "unknown";
 };
 
-// The deepest ignore file with an opinion wins.
 export const verdictFor = (scope: IgnoreScope, path: string, directory: boolean): Verdict =>
 	scope.matchers.map((matcher) => matcherVerdict(matcher, scope.boundary, path, directory)).findLast((verdict) => verdict !== "unknown") ?? "unknown";

package/src/inventory/walk.ts

@@ -13,7 +13,7 @@ export const ignoreScopeAt = (
 		contents === undefined || contents === "" ? inherited : withIgnoreFile(inherited, dir, contents),
 	);
 
-/** The ignore files of every directory between the root and a walked directory, which the walk itself does not visit. */
+// 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> => {
 	const parts = relative(root, dir)
 		.split(sep)

package/src/report/guard.ts

@@ -0,0 +1,46 @@
+import type { GuardProblem, GuardResult } from "../baseline/guard.ts";
+import type { Base } from "../git/base.ts";
+import { plural } from "./plural.ts";
+
+export interface GuardContext {
+	readonly baseline: string;
+	readonly config: string;
+	readonly base: Base;
+}
+
+const problemLine = (problem: GuardProblem, context: GuardContext): string => {
+	switch (problem._tag) {
+		case "Added":
+			return `${problem.entry.rule} ${problem.entry.file} is new, at ${problem.entry.count}.`;
+		case "Raised":
+			return `${problem.entry.rule} ${problem.entry.file} rose to ${problem.entry.count} from ${problem.base.count}.`;
+		case "Unadopted":
+			return `${problem.rule} is newly baselined in ${plural(problem.entries, "file")} without being named under \`adopt\` in ${context.config}.`;
+		case "NothingAdopted":
+			return `\`adopt\` in ${context.config} names ${problem.rule}, which has nothing baselined. Remove it.`;
+	}
+};
+
+const against = (base: Base): string => `${base.ref} (merge base ${base.commit.slice(0, 12)})`;
+
+const held = (result: GuardResult): string =>
+	[
+		...(result.moved > 0 ? [`${plural(result.moved, "entry", "entries")} followed moved files`] : []),
+		...(result.adopted.length > 0 ? [`adopted ${result.adopted.join(", ")}`] : []),
+	]
+		.map((part) => `; ${part}`)
+		.join("");
+
+export const renderGuard = (result: GuardResult, context: GuardContext): string => {
+	if (result.problems.length === 0) {
+		return `quality: ${context.baseline} holds against ${against(context.base)}${held(result)}.`;
+	}
+	return [
+		[
+			`error ${context.baseline} grew against ${against(context.base)}`,
+			`  The baseline only shrinks. Fix new violations instead of baselining them; a rule enters the baseline for the first time only while \`adopt\` names it.`,
+			...result.problems.map((problem) => `  ${problemLine(problem, context)}`),
+		].join("\n"),
+		`quality: baseline check failed with ${plural(result.problems.length, "problem")}.`,
+	].join("\n\n");
+};

package/src/report/render.ts

@@ -1,4 +1,4 @@
-import { describeEntry, describeTally, type Regression } from "../baseline/compare.ts";
+import type { Regression } from "../baseline/compare.ts";
 import { type Outcome, passes } from "../engine/evaluate.ts";
 import { groupBy, keyOf, type Violation } from "../engine/violation.ts";
 import { plural } from "./plural.ts";
@@ -19,7 +19,7 @@ const LISTED_FILES = 5;
 const locate = (violation: Violation): string => (violation.line === undefined ? violation.file : `${violation.file}:${violation.line}`);
 
 const regressionNote = (regression: Regression): string =>
-	`  ${regression.entry.file} is over its baseline: ${describeTally(regression.tally)} against ${describeEntry(regression.entry)} baselined.`;
+	`  ${regression.entry.file} is over its baseline: ${regression.count} against ${regression.entry.count} baselined.`;
 
 const heading = (label: string, rule: string, violations: ReadonlyArray<Violation>, context: ReportContext): ReadonlyArray<string> => {
 	const description = context.descriptions.get(rule);

package/src/report/stale.ts

@@ -8,8 +8,8 @@ interface StaleFiles {
 	readonly baseline: string;
 }
 
-const section = (file: string, guidance: string, lines: ReadonlyArray<string>): ReadonlyArray<string> =>
-	lines.length === 0 ? [] : [[`error ${file}: ${plural(lines.length, "stale entry", "stale entries")}`, `  ${guidance}`, ...lines].join("\n")];
+const section = (label: string, file: string, guidance: string, lines: ReadonlyArray<string>): ReadonlyArray<string> =>
+	lines.length === 0 ? [] : [[`${label} ${file}: ${plural(lines.length, "stale entry", "stale entries")}`, `  ${guidance}`, ...lines].join("\n")];
 
 const baselineLine = ({ entry, problem }: StaleBaselineEntry): string => `  ${entry.rule} ${entry.file} ${problem}.`;
 
@@ -18,11 +18,19 @@ const registryLine = ({ entry, problem }: StaleRegistryEntry): string =>
 
 export const staleSections = (outcome: Outcome, files: StaleFiles): ReadonlyArray<string> => [
 	...section(
+		"error",
 		files.baseline,
-		"The baseline only shrinks. Run `quality baseline prune` to drop fixed debt; prune never adds or raises an entry.",
+		"An entry for a rule that is off or unknown covers nothing. Run `quality baseline prune` to drop it.",
 		outcome.staleBaseline.map(baselineLine),
 	),
 	...section(
+		"note",
+		files.baseline,
+		"These pass, and `quality baseline tighten` lowers them when their files change. `quality baseline prune` lowers them all.",
+		outcome.looseBaseline.map(baselineLine),
+	),
+	...section(
+		"error",
 		files.registry,
 		"Every registered exception must still apply. Remove the entries whose exception is gone.",
 		outcome.staleRegistry.map(registryLine),

package/src/rule.ts

@@ -4,10 +4,9 @@ export interface Finding {
 	readonly file: string;
 	readonly line?: number | undefined;
 	readonly message: string;
-	/** Tells apart exceptions of one rule in one file, such as which Biome rule an override turns off. */
 	readonly subject?: string | undefined;
-	/** A size where larger is worse, such as a file's line count. A baselined file may not grow past it. */
-	readonly measure?: number | undefined;
+	readonly count?: number | undefined;
+	readonly threshold?: number | undefined;
 }
 
 export type Findings = ReadonlyArray<Finding>;
@@ -36,6 +35,7 @@ export type Configured =
 export interface Rule<Id extends string = string, Input = unknown> {
 	readonly id: Id;
 	readonly description: string;
+	readonly registrable?: boolean;
 	// Method syntax keeps rules with different options in one list; configure validates its input at runtime.
 	configure(options: Input | undefined): Promise<Configured>;
 }
@@ -43,6 +43,7 @@ export interface Rule<Id extends string = string, Input = unknown> {
 interface RuleDefinition<Id extends string, Options> {
 	readonly id: Id;
 	readonly description: string;
+	readonly registrable?: false;
 	readonly check: (context: RuleContext<Options>) => Findings | PromiseLike<Findings>;
 }
 
@@ -73,10 +74,6 @@ const configureWith =
 		return { _tag: "Ready", check: async (inputs) => check({ ...inputs, options: value }) };
 	};
 
-/**
- * Defines a rule. Options are an object validated by a Standard Schema; a rule the config gives no options validates `{}`,
- * so give each option a default or make it optional.
- */
 export function defineRule<const Id extends string, Input, Options>(definition: RuleDefinitionWithOptions<Id, Input, Options>): Rule<Id, Input>;
 export function defineRule<const Id extends string>(definition: RuleDefinitionWithoutOptions<Id>): Rule<Id, undefined>;
 export function defineRule<const Id extends string, Input, Options>(
@@ -86,5 +83,5 @@ export function defineRule<const Id extends string, Input, Options>(
 		definition.options === undefined
 			? configureWith(noOptions, definition.check, undefined)
 			: configureWith(definition.options, definition.check, {});
-	return { configure, description: definition.description, id: definition.id };
+	return { configure, description: definition.description, id: definition.id, registrable: definition.registrable ?? true };
 }