@shivaedev/quality 0.17.0 → 0.19.0

package/src/biome/report.ts

@@ -1,11 +1,14 @@
+import { relative, sep } from "node:path";
 import { Schema } from "effect";
+import { ignoredTrackedPaths } from "#inventory/trackedPaths.ts";
+import { recognizeDiagnostics } from "./recognizeDiagnostics.ts";
 import { type BiomeRun, runBiome } from "./run.ts";
 
-const Position = Schema.Struct({ line: Schema.Int });
+const Position = Schema.Struct({ column: Schema.optionalKey(Schema.Int), line: Schema.Int });
 
 const Diagnostic = Schema.Struct({
 	category: Schema.optionalKey(Schema.String),
-	location: Schema.Struct({ path: Schema.optionalKey(Schema.String), start: Schema.optionalKey(Position) }),
+	location: Schema.Struct({ end: Schema.optionalKey(Position), path: Schema.optionalKey(Schema.String), start: Schema.optionalKey(Position) }),
 	message: Schema.String,
 	severity: Schema.String,
 });
@@ -21,11 +24,12 @@ export type Report = typeof Report.Type;
 
 const decodeReport = Schema.decodeUnknownOption(Schema.fromJsonString(Report));
 
-const failure = (args: readonly string[], run: BiomeRun): Error =>
-	new Error(`biome ${args.join(" ")} exited ${run.code} without a report:\n${[run.stdout, run.stderr].join("\n").trim()}`);
+function failure(args: readonly string[], run: BiomeRun): Error {
+	return new Error(`biome ${args.join(" ")} exited ${run.code} without a report:\n${[run.stdout, run.stderr].join("\n").trim()}`);
+}
 
-export async function biomeReport(root: string, args: readonly string[]): Promise<Report> {
-	const command = [...args, "--reporter=json", "--max-diagnostics=none", "."];
+async function reportFor(root: string, args: readonly string[], paths: readonly string[]): Promise<Report> {
+	const command = [...args, "--reporter=json", "--max-diagnostics=none", ...paths];
 	const run = await runBiome(root, command);
 	const report = decodeReport(run.stdout.trim());
 	if (report._tag === "None") {
@@ -33,3 +37,17 @@ export async function biomeReport(root: string, args: readonly string[]): Promis
 	}
 	return report.value;
 }
+
+export async function biomeReport(root: string, args: readonly string[]): Promise<Report> {
+	const [report, tracked] = await Promise.all([reportFor(root, args, ["."]), ignoredTrackedPaths(root)]);
+	const paths = tracked
+		.map((path) => relative(root, path))
+		.filter((path) => !path.split(sep).some((part) => part === ".git" || part === "node_modules"));
+	const extra = paths.length === 0 ? undefined : await reportFor(root, [...args, "--vcs-enabled=false"], paths);
+	const diagnostics = [...report.diagnostics, ...(extra?.diagnostics ?? [])];
+	const unique = [...new Map(diagnostics.map((diagnostic) => [JSON.stringify(diagnostic), diagnostic])).values()];
+	return {
+		diagnostics: recognizeDiagnostics(root, unique),
+		summary: { changed: report.summary.changed + (extra?.summary.changed ?? 0) },
+	};
+}

package/src/biome/syntax.ts

@@ -0,0 +1,36 @@
+import { readFileSync } from "node:fs";
+import ts from "typescript";
+
+export interface Syntax {
+	readonly checker: ts.TypeChecker;
+	readonly source: ts.SourceFile;
+}
+
+export function syntaxOf(path: string): Syntax {
+	const source = ts.createSourceFile(path, readFileSync(path, "utf8"), ts.ScriptTarget.Latest, true);
+	const options: ts.CompilerOptions = { allowJs: true, noLib: true, noResolve: true };
+	const host = ts.createCompilerHost(options);
+	host.getSourceFile = (file) => (file === path ? source : undefined);
+	const program = ts.createProgram([path], options, host);
+	return { checker: program.getTypeChecker(), source };
+}
+
+export function offsetOf(source: ts.SourceFile, position: { readonly line: number; readonly column?: number }): number | undefined {
+	const start = source.getLineStarts()[position.line - 1];
+	if (start === undefined || position.column === undefined || position.column < 1) {
+		return undefined;
+	}
+	const line = source.text.slice(start, source.getLineStarts()[position.line] ?? source.text.length);
+	const characters = [...line];
+	return position.column <= characters.length + 1 ? start + characters.slice(0, position.column - 1).join("").length : undefined;
+}
+
+export function nodeAt(source: ts.SourceFile, start: number, end: number): ts.Node | undefined {
+	function visit(node: ts.Node): ts.Node | undefined {
+		if (node.getStart(source) > start || node.end < end) {
+			return undefined;
+		}
+		return ts.forEachChild(node, visit) ?? (node.getStart(source) === start && node.end === end ? node : undefined);
+	}
+	return visit(source);
+}

package/src/cli/args.ts

@@ -9,6 +9,9 @@ export type Command =
 	| { readonly _tag: "BaselinePrune"; readonly config: string | undefined; readonly against: string | undefined }
 	| { readonly _tag: "BaselineTighten"; readonly config: string | undefined; readonly staged: boolean }
 	| { readonly _tag: "BaselineMigrate"; readonly config: string | undefined; readonly from: string | undefined }
+	| { readonly _tag: "HooksInstall"; readonly config: string | undefined; readonly force: boolean }
+	| { readonly _tag: "HooksUninstall" }
+	| { readonly _tag: "HooksPreCommit"; readonly config: string | undefined }
 	| { readonly _tag: "Help" };
 
 export type Parsed = { readonly _tag: "Parsed"; readonly command: Command } | { readonly _tag: "Usage"; readonly problem: string };
@@ -20,6 +23,9 @@ export const USAGE = `Usage:
   quality baseline prune [--config <file>] [--against <ref>]
   quality baseline tighten [--config <file>] [--staged]
   quality baseline migrate [--config <file>] [--from <file>]
+  quality hooks install [--config <file>] [--force]
+  quality hooks uninstall
+  quality hooks pre-commit [--config <file>]
 
 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.
@@ -28,14 +34,19 @@ baseline write    Record current error-level violations. Creates the baseline, o
 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.
 baseline migrate  Move a baseline from the earlier JSON format (--from, quality/baseline.json by default) to the configured file.
+hooks install     Install the git pre-commit hook, shared by every worktree, that runs hooks pre-commit. Keeps a hook that is not quality's
+                  unless --force replaces it.
+hooks uninstall   Remove quality's pre-commit hook. Keeps a hook that is not quality's.
+hooks pre-commit  What the hook runs: lint, then package.json scripts typecheck and quality:commit when present.
 
---config <file>  Config file; its directory is the repository root. Defaults to ./quality.config.ts.
+--config <file>  Config file; its directory is the repository root. Without this option, uses ./quality.config.ts when present, otherwise defaults.
 --against <ref>  The branch the work merges into, whose merge base prune follows moves from. Defaults to origin/HEAD, then origin/main, then origin/master.
 Exit codes: 0 passed, 1 failed the gate, 2 could not run.`;
 
 const OPTIONS = {
 	against: { type: "string" },
 	config: { type: "string" },
+	force: { type: "boolean" },
 	from: { type: "string" },
 	help: { short: "h", type: "boolean" },
 	rule: { multiple: true, type: "string" },
@@ -48,13 +59,18 @@ const usage = (problem: string): Parsed => ({ _tag: "Usage", problem });
 const ADOPT_REMOVED =
 	"`quality adopt` was removed in 0.7.0. To record a rule's existing findings in the baseline, run `quality baseline write --rule <id>`; to apply the fixes Biome can make first, run `quality fix`.";
 
+const SUBCOMMANDS: Readonly<Record<string, string>> = {
+	baseline: "baseline takes write, prune, tighten or migrate.",
+	hooks: "hooks takes install, uninstall or pre-commit.",
+};
+
 const parsed = (command: Command): Parsed => ({ _tag: "Parsed", command });
 
 type Values = ReturnType<typeof parseArgs<{ options: typeof OPTIONS; allowPositionals: true }>>["values"];
 
 type Option = Exclude<keyof Values, "config" | "help">;
 
-const COMMAND_OPTIONS: readonly Option[] = ["against", "from", "rule", "staged", "warnings"];
+const COMMAND_OPTIONS: readonly Option[] = ["against", "force", "from", "rule", "staged", "warnings"];
 
 const ACCEPTS: Readonly<Record<string, readonly Option[]>> = {
 	"baseline migrate": ["from"],
@@ -62,6 +78,9 @@ const ACCEPTS: Readonly<Record<string, readonly Option[]>> = {
 	"baseline tighten": ["staged"],
 	"baseline write": ["rule"],
 	fix: [],
+	"hooks install": ["force"],
+	"hooks pre-commit": [],
+	"hooks uninstall": [],
 	lint: ["warnings"],
 };
 
@@ -91,6 +110,12 @@ const commandFor = (name: string, values: Values): Parsed => {
 			return ref(values.against, { _tag: "BaselinePrune", against: values.against, config });
 		case "baseline tighten":
 			return parsed({ _tag: "BaselineTighten", config, staged: values.staged === true });
+		case "hooks install":
+			return parsed({ _tag: "HooksInstall", config, force: values.force === true });
+		case "hooks uninstall":
+			return parsed({ _tag: "HooksUninstall" });
+		case "hooks pre-commit":
+			return parsed({ _tag: "HooksPreCommit", config });
 		default:
 			return parsed({ _tag: "BaselineMigrate", config, from: values.from });
 	}
@@ -114,7 +139,8 @@ export const parseCommand = (args: readonly string[]): Parsed => {
 		return usage(ADOPT_REMOVED);
 	}
 	if (ACCEPTS[name] === undefined) {
-		return usage(command === "baseline" && rest.length < 2 ? "baseline takes write, prune, tighten or migrate." : `unknown command: ${name}`);
+		const subcommands = SUBCOMMANDS[command];
+		return usage(subcommands !== undefined && rest.length < 2 ? subcommands : `unknown command: ${name}`);
 	}
 	const problem = misplaced(name, values);
 	return problem === undefined ? commandFor(name, values) : usage(problem);

package/src/cli/baseline.ts

@@ -46,11 +46,11 @@ const changes = (pruned: Pruned): string => {
 	return `${parts.slice(0, -1).join(", ")} and ${parts.at(-1)}`;
 };
 
-export const shrinkBaseline = <Requirements>(
+export const shrinkBaseline = <TRequirements>(
 	cwd: string,
 	config: string | undefined,
-	scopeOf: (session: Session) => Effect.Effect<Scope, SetupFailure, Requirements>,
-): Effect.Effect<void, SetupFailure, FileSystem.FileSystem | Requirements> =>
+	scopeOf: (session: Session) => Effect.Effect<Scope, SetupFailure, TRequirements>,
+): Effect.Effect<void, SetupFailure, FileSystem.FileSystem | TRequirements> =>
 	Effect.gen(function* () {
 		const session = yield* openSession(cwd, config);
 		if (session.baseline.raw === undefined) {

package/src/cli/fix.ts

@@ -33,21 +33,21 @@ export function snapshotOf(root: string): Effect.Effect<ReadonlyMap<string, stri
 	}).pipe(Effect.mapError((failure) => new SetupFailure({ message: failure.message })));
 }
 
-export interface Pass<Failure, Requirements> {
+export interface Pass<TFailure, TRequirements> {
 	readonly label: string;
-	readonly run: Effect.Effect<number, Failure, Requirements>;
+	readonly run: Effect.Effect<number, TFailure, TRequirements>;
 }
 
-export interface Settling<Failure, Requirements> {
-	readonly passes: ReadonlyArray<Pass<Failure, Requirements>>;
-	readonly snapshot: Effect.Effect<ReadonlyMap<string, string>, Failure, Requirements>;
+export interface Settling<TFailure, TRequirements> {
+	readonly passes: readonly Pass<TFailure, TRequirements>[];
+	readonly snapshot: Effect.Effect<ReadonlyMap<string, string>, TFailure, TRequirements>;
 }
 
 function changedBy(root: string, args: readonly string[]): Effect.Effect<number, SetupFailure> {
 	return Effect.map(biome(root, args), (report) => report.summary.changed);
 }
 
-function biomePasses(root: string): ReadonlyArray<Pass<SetupFailure, never>> {
+function biomePasses(root: string): readonly Pass<SetupFailure, never>[] {
 	return [
 		{
 			label: "with fixes",
@@ -57,11 +57,11 @@ function biomePasses(root: string): ReadonlyArray<Pass<SetupFailure, never>> {
 	];
 }
 
-function round<Failure, Requirements>(
-	passes: ReadonlyArray<Pass<Failure, Requirements>>,
+function round<TFailure, TRequirements>(
+	passes: readonly Pass<TFailure, TRequirements>[],
 	index: number,
-	afterEachPass: Effect.Effect<void, Failure, Requirements>,
-): Effect.Effect<number, Failure, Requirements> {
+	afterEachPass: Effect.Effect<void, TFailure, TRequirements>,
+): Effect.Effect<number, TFailure, TRequirements> {
 	return Effect.gen(function* () {
 		let total = 0;
 		const parts: string[] = [];
@@ -91,14 +91,14 @@ function unsettled(changed: ReadonlySet<string>): SetupFailure {
 					"Run `biome check --write --unsafe --verbose` to name them.",
 				];
 	return new SetupFailure({
-		message: [...named, "Two fixes probably undo each other there. Fix the code by hand, or turn off one of the rules."].join("\n"),
+		message: [...named, "Two fixes probably undo each other there. Repair the conflicting code by hand so both checks pass."].join("\n"),
 	});
 }
 
-export function settle<Failure, Requirements>({
+export function settle<TFailure, TRequirements>({
 	passes,
 	snapshot,
-}: Settling<Failure, Requirements>): Effect.Effect<void, Failure | SetupFailure, Requirements> {
+}: Settling<TFailure, TRequirements>): Effect.Effect<void, TFailure | SetupFailure, TRequirements> {
 	return Effect.gen(function* () {
 		for (let index = 1; index < MAX_FIX_ROUNDS; index += 1) {
 			if ((yield* round(passes, index, Effect.void)) === 0) {

package/src/cli/run-main.ts

@@ -47,7 +47,7 @@ export function quietOnClosedPipe(stream: EventEmitter): 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 => {
+export const runMain = <TValue, TError>(program: Effect.Effect<TValue, TError, FileSystem.FileSystem | Git>): void => {
 	quietOnClosedPipe(process.stdout);
 	quietOnClosedPipe(process.stderr);
 	const explained = Effect.tapCause(program, (cause) => (Cause.hasInterruptsOnly(cause) ? Effect.void : explain(cause)));

package/src/cli.ts

@@ -8,6 +8,9 @@ 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 { installHook } from "#hooks/install.ts";
+import { preCommitHook } from "#hooks/preCommit.ts";
+import { uninstallHook } from "#hooks/uninstall.ts";
 import { SetupFailure } from "./failure.ts";
 
 const parsed = parseCommand(process.argv.slice(2));
@@ -32,6 +35,17 @@ const program = Effect.gen(function* () {
 			return yield* tightenBaseline(process.cwd(), command.config, command.staged);
 		case "BaselineMigrate":
 			return yield* migrateBaseline(process.cwd(), command.config, command.from);
+		case "HooksInstall":
+			return yield* installHook({
+				config: command.config,
+				cwd: process.cwd(),
+				force: command.force,
+				launch: { options: process.execArgv, script: process.argv[1] ?? "" },
+			});
+		case "HooksUninstall":
+			return yield* uninstallHook(process.cwd());
+		case "HooksPreCommit":
+			return yield* preCommitHook(process.cwd(), command.config);
 	}
 });
 

package/src/config/decode.ts

@@ -12,7 +12,7 @@ const isRule = (value: unknown): value is Rule =>
 	&& "configure" in value
 	&& typeof value.configure === "function";
 
-const Level = Schema.Literals(["error", "warn", "off"]);
+const Level = Schema.Literal("error");
 
 const Setting = Schema.Union([Level, Schema.Struct({ level: Schema.optionalKey(Level), options: Schema.optionalKey(Schema.Unknown) })]);
 
@@ -22,12 +22,17 @@ const AdoptRemoved = Schema.Never.annotate({
 	message: "removed in quality 0.7.0. Delete the key, and record a rule's existing findings with `quality baseline write --rule <id>`.",
 });
 
+const PreCommitRemoved = Schema.Never.annotate({
+	message:
+		"removed. Put repository checks in the package.json quality:commit script; the hook also runs typecheck when present. Use `quality baseline tighten --staged` explicitly to lower staged debt.",
+});
+
 const ConfigInput = Schema.Struct({
 	adopt: Schema.optionalKey(AdoptRemoved),
 	baseline: Schema.optionalKey(Schema.String),
-	exclude: Schema.optionalKey(Schema.Array(Schema.String)),
 	extensions: Schema.optionalKey(Schema.Array(Schema.String)),
 	local: Schema.optionalKey(Schema.Array(LocalRule)),
+	preCommit: Schema.optionalKey(PreCommitRemoved),
 	registry: Schema.optionalKey(Schema.String),
 	rules: Schema.optionalKey(Schema.Record(Schema.String, Setting)),
 	sources: Schema.optionalKey(Schema.Array(Schema.String)),

package/src/config/load.ts

@@ -1,4 +1,4 @@
-import { dirname, resolve } from "node:path";
+import { basename, dirname, resolve } from "node:path";
 import { pathToFileURL } from "node:url";
 import { Effect, FileSystem } from "effect";
 import { validOrFail } from "#decoded.ts";
@@ -34,7 +34,7 @@ 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.jsonl",
-	exclude: config.exclude ?? [],
+	exclude: [],
 	extensions: config.extensions ?? DEFAULT_EXTENSIONS,
 	file,
 	registry: config.registry ?? "quality/registry.json",
@@ -46,11 +46,20 @@ export const loadConfig = (cwd: string, path: string | undefined): Effect.Effect
 	Effect.gen(function* () {
 		const fs = yield* FileSystem.FileSystem;
 		const file = resolve(cwd, path ?? CONFIG_FILE);
-		const present = yield* Effect.orElseSucceed(fs.exists(file), () => false);
-		if (!present) {
-			return yield* new SetupFailure({ message: `no config at ${file}. Create ${CONFIG_FILE} exporting defineConfig({ ... }), or pass --config.` });
+		const entries = yield* fs
+			.readDirectory(dirname(file))
+			.pipe(
+				Effect.catchTag("PlatformError", (error) =>
+					error.reason._tag === "NotFound"
+						? Effect.succeed<string[]>([])
+						: Effect.fail(new SetupFailure({ message: `cannot inspect ${file}: ${error.message}` })),
+				),
+			);
+		const present = entries.includes(basename(file));
+		if (!present && path !== undefined) {
+			return yield* new SetupFailure({ message: `no config at ${file}. Check the --config path.` });
 		}
-		const loaded = yield* importDefault(file);
+		const loaded = present ? yield* importDefault(file) : {};
 		const config = yield* validOrFail(file, yield* Effect.promise(() => decodeConfig(loaded)));
 		const rules = yield* validOrFail(file, yield* resolveRules(config));
 		return resolved(dirname(file), file, config, rules);

package/src/config/resolve.ts

@@ -1,5 +1,4 @@
 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 type { RuleIndex } from "#engine/violation.ts";
@@ -15,8 +14,6 @@ type Setting = NonNullable<ConfigInput["rules"]>[string];
 
 const messageOf = (cause: unknown): string => (cause instanceof Error ? cause.message : String(cause));
 
-const levelOf = (setting: Setting | undefined): Level => (typeof setting === "string" ? setting : (setting?.level ?? "error"));
-
 const optionsOf = (setting: Setting | undefined): unknown => (typeof setting === "object" ? setting.options : undefined);
 
 const duplicateIssues = (rules: readonly Rule[]): readonly string[] =>
@@ -24,23 +21,21 @@ const duplicateIssues = (rules: readonly Rule[]): readonly string[] =>
 		rules.findIndex((other) => other.id === rule.id) === index ? [] : [`local: rule id "${rule.id}" is already defined`],
 	);
 
-const activate = (rule: Rule, setting: Setting | undefined): Effect.Effect<Decoded<ActiveRule | undefined>> => {
-	const level = levelOf(setting);
-	if (level === "off") {
-		return Effect.succeed({ _tag: "Valid", value: undefined });
-	}
-	return Effect.tryPromise({ catch: messageOf, try: () => rule.configure(optionsOf(setting)) }).pipe(
+const activate = (rule: Rule, setting: Setting | undefined): Effect.Effect<Decoded<ActiveRule>> =>
+	Effect.tryPromise({ catch: messageOf, try: () => rule.configure(optionsOf(setting)) }).pipe(
 		Effect.map(
-			(configured): Decoded<ActiveRule | undefined> =>
+			(configured): Decoded<ActiveRule> =>
 				configured._tag === "Invalid"
 					? { _tag: "Invalid", issues: configured.issues.map((issue) => `rules.${rule.id}.options: ${issue}`) }
-					: { _tag: "Valid", value: { check: configured.check, description: rule.description, family: rule.family === true, id: rule.id, level } },
+					: {
+							_tag: "Valid",
+							value: { check: configured.check, description: rule.description, family: rule.family === true, id: rule.id, level: "error" },
+						},
 		),
 		Effect.catch((failure: string) =>
-			Effect.succeed<Decoded<ActiveRule | undefined>>({ _tag: "Invalid", issues: [`rules.${rule.id}.options: validation threw: ${failure}`] }),
+			Effect.succeed<Decoded<ActiveRule>>({ _tag: "Invalid", issues: [`rules.${rule.id}.options: validation threw: ${failure}`] }),
 		),
 	);
-};
 
 export const resolveRules = (config: ConfigInput): Effect.Effect<Decoded<ResolvedRules>> =>
 	Effect.gen(function* () {
@@ -58,8 +53,8 @@ export const resolveRules = (config: ConfigInput): Effect.Effect<Decoded<Resolve
 		if (issues.length > 0) {
 			return { _tag: "Invalid", issues };
 		}
-		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 active = activated.flatMap((result) => (result._tag === "Valid" ? [result.value] : []));
+		const levels = new Map(rules.map((rule) => [rule.id, "error" as const]));
 		const unregistrable = new Set(rules.filter((rule) => rule.registrable === false).map((rule) => rule.id));
 		return { _tag: "Valid", value: { active, families, levels, unregistrable } };
 	});

package/src/config.ts

@@ -3,24 +3,23 @@ import type { Rule } from "./rule.ts";
 
 export type Level = "error" | "warn" | "off";
 
-export type RuleSetting<Input> = Level | { readonly level?: Level; readonly options?: Input };
+export type RuleSetting<TInput> = "error" | { readonly level?: "error"; readonly options?: TInput };
 
-type InputOf<Candidate> = Candidate extends Rule<string, infer Input> ? Input : never;
+type InputOf<TCandidate> = TCandidate extends Rule<string, infer TInput> ? TInput : never;
 
-export type RuleSettings<Rules extends readonly Rule[]> = {
-	readonly [Candidate in Rules[number] as Candidate["id"]]?: RuleSetting<InputOf<Candidate>>;
+export type RuleSettings<TRules extends readonly Rule[]> = {
+	readonly [TCandidate in TRules[number] as TCandidate["id"]]?: RuleSetting<InputOf<TCandidate>>;
 };
 
 export type BuiltInRules = typeof builtInRules;
 
-export interface QualityConfig<Local extends readonly Rule[] = readonly Rule[]> {
+export interface QualityConfig<TLocal extends readonly Rule[] = readonly Rule[]> {
 	readonly baseline?: string;
-	readonly exclude?: readonly string[];
 	readonly extensions?: readonly string[];
-	readonly local?: Local;
+	readonly local?: TLocal;
 	readonly registry?: string;
-	readonly rules?: RuleSettings<readonly [...BuiltInRules, ...Local]>;
+	readonly rules?: RuleSettings<readonly [...BuiltInRules, ...TLocal]>;
 	readonly sources?: readonly string[];
 }
 
-export const defineConfig = <const Local extends readonly Rule[] = readonly []>(config: QualityConfig<Local>): QualityConfig<Local> => config;
+export const defineConfig = <const TLocal extends readonly Rule[] = readonly []>(config: QualityConfig<TLocal>): QualityConfig<TLocal> => config;

package/src/decoded.ts

@@ -2,14 +2,14 @@ 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: readonly string[] };
+export type Decoded<TValue> = { readonly _tag: "Valid"; readonly value: TValue } | { readonly _tag: "Invalid"; readonly issues: readonly string[] };
 
-export const decodeWith = async <Output>(schema: StandardSchemaV1<unknown, Output>, value: unknown): Promise<Decoded<Output>> => {
+export const decodeWith = async <TOutput>(schema: StandardSchemaV1<unknown, TOutput>, value: unknown): Promise<Decoded<TOutput>> => {
 	const result = await schema["~standard"].validate(value);
 	return result.issues === undefined ? { _tag: "Valid", value: result.value } : { _tag: "Invalid", issues: result.issues.map(describeIssue) };
 };
 
-export const validOrFail = <Value>(file: string, decoded: Decoded<Value>): Effect.Effect<Value, SetupFailure> =>
+export const validOrFail = <TValue>(file: string, decoded: Decoded<TValue>): Effect.Effect<TValue, SetupFailure> =>
 	decoded._tag === "Valid"
 		? Effect.succeed(decoded.value)
 		: Effect.fail(new SetupFailure({ message: `${file} is invalid:\n${decoded.issues.map((issue) => `  - ${issue}`).join("\n")}` }));

package/src/engine/session.ts

@@ -18,9 +18,9 @@ export interface Session {
 	readonly violations: readonly Violation[];
 }
 
-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 setup = <TValue, TRequirements>(
+	effect: Effect.Effect<TValue, FilesystemFailure, TRequirements>,
+): Effect.Effect<TValue, SetupFailure, TRequirements> => Effect.mapError(effect, (failure) => new SetupFailure({ message: failure.message }));
 
 export const scan = (config: ResolvedConfig): Effect.Effect<Pick<Session, "inventory" | "violations">, SetupFailure, FileSystem.FileSystem> =>
 	Effect.gen(function* () {

package/src/engine/violation.ts

@@ -13,8 +13,8 @@ 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: readonly Item[], key: (item: Item) => string): ReadonlyMap<string, readonly Item[]> => {
-	const groups = new Map<string, Item[]>();
+export const groupBy = <TItem>(items: readonly TItem[], key: (item: TItem) => string): ReadonlyMap<string, readonly TItem[]> => {
+	const groups = new Map<string, TItem[]>();
 	for (const item of items) {
 		const group = groups.get(key(item));
 		if (group === undefined) {

package/src/hooks/command.ts

@@ -0,0 +1,34 @@
+import { isAbsolute, relative, sep } from "node:path";
+
+export interface Launch {
+	readonly options: readonly string[];
+	readonly script: string;
+}
+
+export interface HookCommand {
+	readonly args: readonly string[];
+	readonly launcher: string;
+	readonly runner: readonly string[];
+}
+
+const BIN = "node_modules/.bin/quality";
+const SAFE = /^[\w@%+=:,./-]+$/u;
+
+// A quality run from a file in the repository, such as its own source, is run the same way by the hook; an installed one through its bin.
+export function hookCommand(root: string, launch: Launch, config: string | undefined): HookCommand {
+	const script = relative(root, launch.script);
+	const installed = script.startsWith("..") || isAbsolute(script) || script.split(sep).includes("node_modules");
+	return {
+		args: ["hooks", "pre-commit", ...(config === undefined ? [] : ["--config", config])],
+		launcher: installed ? BIN : script,
+		runner: installed ? [] : ["node", ...launch.options],
+	};
+}
+
+export function commandWords(command: HookCommand): readonly string[] {
+	return [...command.runner, command.launcher, ...command.args];
+}
+
+export function shellWords(words: readonly string[]): string {
+	return words.map((word) => (SAFE.test(word) ? word : `'${word.replaceAll("'", `'\\''`)}'`)).join(" ");
+}

package/src/hooks/install.ts

@@ -0,0 +1,69 @@
+import { basename, dirname, join, relative, resolve } from "node:path";
+import { Console, Effect, FileSystem } from "effect";
+import { CONFIG_FILE } from "#config/file.ts";
+import { loadConfig } from "#config/load.ts";
+import { SetupFailure } from "#failure.ts";
+import { readOptionalText } from "#inventory/filesystem.ts";
+import { commandWords, hookCommand, type Launch, shellWords } from "./command.ts";
+import { type HookLocation, hookLocation } from "./location.ts";
+import { hookShim, isHookShim } from "./shim.ts";
+
+export interface HookInstall {
+	readonly config: string | undefined;
+	readonly cwd: string;
+	readonly force: boolean;
+	readonly launch: Launch;
+}
+
+function failed(error: { readonly message: string }): SetupFailure {
+	return new SetupFailure({ message: error.message });
+}
+
+const realPath = Effect.fnUntraced(function* (path: string) {
+	const fs = yield* FileSystem.FileSystem;
+	return yield* Effect.mapError(fs.realPath(path), failed);
+});
+
+const write = Effect.fnUntraced(function* (file: string, text: string) {
+	const fs = yield* FileSystem.FileSystem;
+	yield* fs.makeDirectory(dirname(file), { recursive: true }).pipe(
+		Effect.andThen(fs.writeFileString(file, text)),
+		Effect.andThen(fs.chmod(file, 0o755)),
+		Effect.mapError((error) => new SetupFailure({ message: `cannot write ${file}: ${error.message}` })),
+	);
+});
+
+function elsewhere(location: HookLocation): Effect.Effect<void> {
+	return location.hooksPath === undefined || resolve(location.toplevel, location.hooksPath) === dirname(location.file)
+		? Effect.void
+		: Console.error(
+				`note: core.hooksPath is ${location.hooksPath}, so git runs the pre-commit hook there; ${location.file} runs only when that hook calls it.`,
+			);
+}
+
+export const installHook = Effect.fn("Hooks.installHook")(function* (install: HookInstall) {
+	const config = yield* loadConfig(install.cwd, install.config);
+	const location = yield* hookLocation(config.root);
+	const root = yield* realPath(config.root);
+	const script = join(yield* realPath(dirname(install.launch.script)), basename(install.launch.script));
+	const name = basename(config.file);
+	const command = hookCommand(root, { options: install.launch.options, script }, name === CONFIG_FILE ? undefined : name);
+	const directory = relative(location.toplevel, root);
+	const shim = hookShim(directory, command);
+	const words = shellWords(commandWords(command));
+	const existing = yield* Effect.mapError(readOptionalText(location.file), failed);
+	const foreign = existing !== undefined && !isHookShim(existing);
+	if (foreign && !install.force) {
+		const call = `${directory === "" ? "" : `cd ${shellWords([directory])} && `}${words}`;
+		yield* Console.error(
+			`quality: kept ${location.file}: it is not quality's pre-commit hook, so quality does not check commits.\nhelp: call \`${call}\` from that hook, or replace it with \`quality hooks install --force\`.`,
+		);
+	} else if (existing === shim) {
+		yield* Console.log(`quality: the pre-commit hook at ${location.file} is up to date.`);
+	} else {
+		yield* write(location.file, shim);
+		const done = foreign ? `replaced ${location.file}, which was not quality's hook` : `installed the pre-commit hook at ${location.file}`;
+		yield* Console.log(`quality: ${done}; each commit runs \`${words}\`.`);
+	}
+	yield* elsewhere(location);
+});

package/src/hooks/location.ts

@@ -0,0 +1,28 @@
+import { join } from "node:path";
+import { Effect } from "effect";
+import { SetupFailure } from "#failure.ts";
+import { git } from "#git/command.ts";
+
+export interface HookLocation {
+	readonly file: string;
+	readonly hooksPath: string | undefined;
+	readonly toplevel: string;
+}
+
+// Hooks live in the common git directory, which every worktree of the repository shares.
+export const hookLocation = Effect.fn("Hooks.hookLocation")(function* (cwd: string) {
+	const paths = yield* git(cwd, ["rev-parse", "--path-format=absolute", "--show-toplevel", "--git-common-dir"]);
+	const [toplevel, common] = paths.stdout.trim().split("\n");
+	if (paths.code !== 0 || toplevel === undefined || common === undefined) {
+		return yield* new SetupFailure({
+			message: `${cwd} is not in a git work tree, so there is no hook to manage.\nhelp: run quality from inside the repository, or run \`git init\` first.`,
+		});
+	}
+	const hooksPath = yield* git(cwd, ["config", "--type=path", "--get", "core.hooksPath"]);
+	const location: HookLocation = {
+		file: join(common, "hooks", "pre-commit"),
+		hooksPath: hooksPath.code === 0 ? hooksPath.stdout.trim() : undefined,
+		toplevel,
+	};
+	return location;
+});