@shivaedev/quality 0.2.0 → 0.3.1

package/src/cli/check.ts

@@ -0,0 +1,51 @@
+import { relative } from "node:path";
+import { Console, Effect, type FileSystem } from "effect";
+import { type BaselineEntry, decodeBaseline } from "../baseline/format.ts";
+import { guardBaseline } from "../baseline/guard.ts";
+import { convertLegacy, decodeLegacyBaseline, LEGACY_BASELINE, measured } from "../baseline/legacy.ts";
+import { loadConfig, type ResolvedConfig } from "../config/load.ts";
+import { validOrFail } from "../decoded.ts";
+import { readBaseline } from "../engine/baseline-file.ts";
+import { scan } from "../engine/session.ts";
+import { GateFailed, type SetupFailure } from "../failure.ts";
+import { type Base, resolveBase } from "../git/base.ts";
+import type { Git } from "../git/command.ts";
+import { changesSince, readAt } from "../git/history.ts";
+import { renderGuard } from "../report/guard.ts";
+
+const baseEntries = (
+	config: ResolvedConfig,
+	base: Base,
+	path: string,
+): Effect.Effect<ReadonlyArray<BaselineEntry>, SetupFailure, FileSystem.FileSystem | Git> =>
+	Effect.gen(function* () {
+		const raw = yield* readAt(config.root, base.commit, path);
+		if (raw !== undefined) {
+			return yield* validOrFail(`${path} at ${base.ref}`, yield* Effect.promise(() => decodeBaseline(raw)));
+		}
+		const legacyRaw = yield* readAt(config.root, base.commit, LEGACY_BASELINE);
+		if (legacyRaw === undefined) {
+			return [];
+		}
+		const legacy = yield* validOrFail(`${LEGACY_BASELINE} at ${base.ref}`, yield* Effect.promise(() => decodeLegacyBaseline(legacyRaw)));
+		return measured(legacy) ? convertLegacy(legacy, (yield* scan(config)).violations) : legacy;
+	});
+
+export const checkBaseline = (
+	cwd: string,
+	configPath: string | undefined,
+	against: string | undefined,
+): Effect.Effect<void, SetupFailure | GateFailed, FileSystem.FileSystem | Git> =>
+	Effect.gen(function* () {
+		const config = yield* loadConfig(cwd, configPath);
+		const working = yield* readBaseline(config);
+		const base = yield* resolveBase(config.root, against);
+		const { moves } = yield* changesSince(config.root, [base.commit]);
+		const renames = new Map([...moves].map(([from, to]) => [to, from]));
+		const before = yield* baseEntries(config, base, renames.get(config.baseline) ?? config.baseline);
+		const result = guardBaseline(before, working.entries, renames, config.adopt);
+		yield* Console.log(renderGuard(result, { base, baseline: config.baseline, config: relative(config.root, config.file) }));
+		if (result.problems.length > 0) {
+			return yield* new GateFailed();
+		}
+	});

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);
+		const outcome = evaluate(session.violations, session.registry, session.baseline.entries, session.config.levels, session.config.unregistrable);
 		yield* Console.log(
 			render(outcome, {
 				baseline: session.config.baseline,

package/src/cli/migrate.ts

@@ -0,0 +1,36 @@
+import { join } from "node:path";
+import { Console, Effect, FileSystem } from "effect";
+import { encodeBaseline } from "../baseline/format.ts";
+import { convertLegacy, decodeLegacyBaseline, LEGACY_BASELINE } from "../baseline/legacy.ts";
+import { loadConfig } from "../config/load.ts";
+import { validOrFail } from "../decoded.ts";
+import { readInput } from "../engine/baseline-file.ts";
+import { scan } from "../engine/session.ts";
+import { SetupFailure } from "../failure.ts";
+import { writeText } from "../inventory/filesystem.ts";
+import { plural } from "../report/plural.ts";
+
+export const migrateBaseline = (
+	cwd: string,
+	configPath: string | undefined,
+	from: string | undefined,
+): Effect.Effect<void, SetupFailure, FileSystem.FileSystem> =>
+	Effect.gen(function* () {
+		const config = yield* loadConfig(cwd, configPath);
+		const source = from ?? LEGACY_BASELINE;
+		if (source === config.baseline || (yield* readInput(config.root, config.baseline)) !== undefined) {
+			return yield* new SetupFailure({ message: `${config.baseline} already exists. Migrate into a baseline file that does not exist yet.` });
+		}
+		const raw = yield* readInput(config.root, source);
+		if (raw === undefined) {
+			return yield* new SetupFailure({ message: `no baseline at ${source} to migrate. Name it with --from <file>.` });
+		}
+		const legacy = yield* validOrFail(source, yield* Effect.promise(() => decodeLegacyBaseline(raw)));
+		const entries = convertLegacy(legacy, (yield* scan(config)).violations);
+		const fs = yield* FileSystem.FileSystem;
+		const written = Effect.andThen(writeText(join(config.root, config.baseline), encodeBaseline(entries)), fs.remove(join(config.root, source)));
+		yield* Effect.mapError(written, (failure) => new SetupFailure({ message: failure.message }));
+		const fixed = legacy.length - entries.length;
+		const dropped = fixed > 0 ? `, dropping ${plural(fixed, "fixed entry", "fixed entries")}` : "";
+		yield* Console.log(`quality: moved ${plural(entries.length, "entry", "entries")} from ${source} to ${config.baseline}${dropped}.`);
+	});

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,89 @@
+import { Console, 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 isShallow = (root: string): Effect.Effect<boolean, SetupFailure, Git> =>
+	Effect.map(git(root, ["rev-parse", "--is-shallow-repository"]), (result) => result.stdout.trim() === "true");
+
+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> =>
+	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");
+		return remotes.filter((remote) => remote !== "" && name.startsWith(`refs/remotes/${remote}/`)).slice(0, 1);
+	});
+
+const unshallow = (root: string, ref: string): Effect.Effect<void, SetupFailure, Git> =>
+	Effect.gen(function* () {
+		const remote = yield* remoteOf(root, ref);
+		yield* Console.error(`quality: the clone is shallow; fetching its full history to find the merge base of HEAD and ${ref}.`);
+		yield* git(root, ["fetch", "--quiet", "--unshallow", ...remote], { GIT_TERMINAL_PROMPT: "0" });
+	});
+
+const missingMergeBase = (root: string, ref: string): Effect.Effect<never, SetupFailure, Git> =>
+	Effect.flatMap(isShallow(root), (shallow) =>
+		fail(
+			shallow
+				? `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.`,
+		),
+	);
+
+const reachMergeBase = (root: string, ref: string): Effect.Effect<string, SetupFailure, Git> =>
+	Effect.gen(function* () {
+		const found = yield* mergeBase(root, ref);
+		if (found !== undefined) {
+			return found;
+		}
+		if (yield* isShallow(root)) {
+			yield* unshallow(root, ref);
+			const deepened = yield* mergeBase(root, ref);
+			if (deepened !== undefined) {
+				return deepened;
+			}
+		}
+		return yield* missingMergeBase(root, ref);
+	});
+
+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>.`);
+		}
+		return { commit: yield* reachMergeBase(root, ref), 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>, env?: Readonly<Record<string, 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, env, extendEnv: true, 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)