@shivaedev/quality 0.17.0 → 0.18.0

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,6 +34,10 @@ 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: baseline tighten for staged files when preCommit.tighten is set, lint, then each preCommit.run command.
 
 --config <file>  Config file; its directory is the repository root. Defaults to ./quality.config.ts.
 --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.
@@ -36,6 +46,7 @@ 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.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

@@ -28,6 +28,7 @@ const ConfigInput = Schema.Struct({
 	exclude: Schema.optionalKey(Schema.Array(Schema.String)),
 	extensions: Schema.optionalKey(Schema.Array(Schema.String)),
 	local: Schema.optionalKey(Schema.Array(LocalRule)),
+	preCommit: Schema.optionalKey(Schema.Struct({ run: Schema.optionalKey(Schema.Array(Schema.String)), tighten: Schema.optionalKey(Schema.Boolean) })),
 	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,6 +1,7 @@
 import { dirname, resolve } from "node:path";
 import { pathToFileURL } from "node:url";
 import { Effect, FileSystem } from "effect";
+import type { PreCommit } from "#config.ts";
 import { validOrFail } from "#decoded.ts";
 import { SetupFailure } from "#failure.ts";
 import type { InventoryScope } from "#inventory/collect.ts";
@@ -13,6 +14,7 @@ const DEFAULT_EXTENSIONS = [".ts", ".tsx", ".mts", ".cts", ".js", ".jsx", ".mjs"
 export interface ResolvedConfig extends ResolvedRules, InventoryScope {
 	readonly baseline: string;
 	readonly file: string;
+	readonly preCommit: Required<PreCommit>;
 	readonly registry: string;
 	readonly root: string;
 }
@@ -37,6 +39,7 @@ const resolved = (root: string, file: string, config: ConfigInput, rules: Resolv
 	exclude: config.exclude ?? [],
 	extensions: config.extensions ?? DEFAULT_EXTENSIONS,
 	file,
+	preCommit: { run: config.preCommit?.run ?? [], tighten: config.preCommit?.tighten ?? false },
 	registry: config.registry ?? "quality/registry.json",
 	root,
 	sources: config.sources ?? ["."],

package/src/config.ts

@@ -13,11 +13,17 @@ export type RuleSettings<Rules extends readonly Rule[]> = {
 
 export type BuiltInRules = typeof builtInRules;
 
+export interface PreCommit {
+	readonly run?: readonly string[];
+	readonly tighten?: boolean;
+}
+
 export interface QualityConfig<Local extends readonly Rule[] = readonly Rule[]> {
 	readonly baseline?: string;
 	readonly exclude?: readonly string[];
 	readonly extensions?: readonly string[];
 	readonly local?: Local;
+	readonly preCommit?: PreCommit;
 	readonly registry?: string;
 	readonly rules?: RuleSettings<readonly [...BuiltInRules, ...Local]>;
 	readonly sources?: readonly string[];

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;
+});

package/src/hooks/preCommit.ts

@@ -0,0 +1,77 @@
+import { join } from "node:path";
+import { Console, Effect, FileSystem } from "effect";
+import { ChildProcess, ChildProcessSpawner } from "effect/unstable/process";
+import type { Scope } from "#baseline/update.ts";
+import { shrinkBaseline } from "#cli/baseline.ts";
+import { lint } from "#cli/lint.ts";
+import { loadConfig, type ResolvedConfig } from "#config/load.ts";
+import { GateFailed, SetupFailure } from "#failure.ts";
+import { gitOrFail } from "#git/command.ts";
+import { changesSince } from "#git/history.ts";
+
+const COMMIT_AGAIN =
+	"help: fix what the output above reports, then commit again; `quality hooks pre-commit` repeats these checks without committing.";
+
+// A partly staged file is counted as it is on disk, which is not what the commit holds, so its entries wait for a later commit.
+const stagedScope = Effect.fnUntraced(function* (config: ResolvedConfig) {
+	const unstaged = (yield* changesSince(config.root, [])).files;
+	if (unstaged.has(config.baseline)) {
+		return undefined;
+	}
+	const staged = yield* changesSince(config.root, ["--cached"]);
+	const held = new Set([...unstaged, ...[...staged.moves].filter(([, to]) => unstaged.has(to)).map(([from]) => from)]);
+	const scope: Scope = {
+		files: new Set([...staged.files].filter((file) => !held.has(file))),
+		moves: new Map([...staged.moves].filter(([from]) => !held.has(from))),
+	};
+	return scope;
+});
+
+const tighten = Effect.fnUntraced(function* (cwd: string, path: string | undefined, config: ResolvedConfig) {
+	const scope = yield* stagedScope(config);
+	if (scope === undefined) {
+		return yield* Console.error(
+			`quality: left ${config.baseline} as it is, because it has unstaged changes.\nhelp: stage or discard them to tighten it.`,
+		);
+	}
+	yield* shrinkBaseline(cwd, path, () => Effect.succeed(scope));
+	const fs = yield* FileSystem.FileSystem;
+	if (yield* Effect.orElseSucceed(fs.exists(join(config.root, config.baseline)), () => false)) {
+		yield* gitOrFail(config.root, ["add", "--", config.baseline]);
+	}
+});
+
+const shell = Effect.fnUntraced(
+	function* (root: string, command: string) {
+		const spawner = yield* ChildProcessSpawner.ChildProcessSpawner;
+		const child = yield* spawner.spawn(
+			ChildProcess.make("sh", ["-c", command], { cwd: root, stderr: "inherit", stdin: "inherit", stdout: "inherit" }),
+		);
+		return Number(yield* child.exitCode);
+	},
+	Effect.scoped,
+	Effect.mapError((error) => new SetupFailure({ message: `cannot run a pre-commit command: ${error.message}` })),
+);
+
+export const preCommitHook = Effect.fn("Hooks.preCommitHook")(function* (cwd: string, path: string | undefined) {
+	const config = yield* loadConfig(cwd, path);
+	if (config.preCommit.tighten) {
+		yield* tighten(cwd, path, config);
+	}
+	const linted = yield* lint(cwd, path, "summary").pipe(
+		Effect.as(true),
+		Effect.catchTag("GateFailed", () => Effect.succeed(false)),
+	);
+	const failed = linted ? [] : ["quality lint"];
+	for (const command of config.preCommit.run) {
+		yield* Console.log(`quality: running \`${command}\``);
+		const code = yield* shell(config.root, command);
+		if (code !== 0) {
+			failed.push(`\`${command}\` (exit code ${code})`);
+		}
+	}
+	if (failed.length > 0) {
+		yield* Console.error(`quality: pre-commit failed: ${failed.join(", ")}.\n${COMMIT_AGAIN}`);
+		return yield* new GateFailed();
+	}
+});

package/src/hooks/shim.ts

@@ -0,0 +1,28 @@
+import { type HookCommand, shellWords } from "./command.ts";
+
+const OWNER = "# Installed by @shivaedev/quality: `quality hooks install` writes it, `quality hooks uninstall` removes it.";
+
+export function isHookShim(text: string): boolean {
+	return text.split("\n").includes(OWNER);
+}
+
+// The hook moves to the checked-out worktree first, so each worktree commits under its own config and its own quality.
+// Git sets GIT_DIR for a hook in a linked worktree, which makes git take the current folder as the worktree root unless GIT_WORK_TREE names it.
+export function hookShim(directory: string, command: HookCommand): string {
+	const folder = directory === "" ? "" : `/${shellWords([directory])}`;
+	const exec = [shellWords(command.runner), '"$quality"', shellWords(command.args)].filter((part) => part !== "");
+	return [
+		"#!/bin/sh",
+		OWNER,
+		'top="$(git rev-parse --show-toplevel)" || exit 2',
+		'if [ -n "$GIT_DIR" ] && [ -z "$GIT_WORK_TREE" ]; then export GIT_WORK_TREE="$top"; fi',
+		`cd "$top"${folder} || exit 2`,
+		`quality=${shellWords([command.launcher])}`,
+		'if [ ! -e "$quality" ]; then',
+		'\tprintf \'quality: cannot check this commit: %s/%s does not exist.\\nhelp: install the dependencies of this worktree, then commit again.\\n\' "$PWD" "$quality" >&2',
+		"\texit 2",
+		"fi",
+		`exec ${exec.join(" ")}`,
+		"",
+	].join("\n");
+}

package/src/hooks/uninstall.ts

@@ -0,0 +1,19 @@
+import { Console, Effect, FileSystem } from "effect";
+import { SetupFailure } from "#failure.ts";
+import { readOptionalText } from "#inventory/filesystem.ts";
+import { hookLocation } from "./location.ts";
+import { isHookShim } from "./shim.ts";
+
+export const uninstallHook = Effect.fn("Hooks.uninstallHook")(function* (cwd: string) {
+	const fs = yield* FileSystem.FileSystem;
+	const { file } = yield* hookLocation(cwd);
+	const existing = yield* Effect.mapError(readOptionalText(file), (failure) => new SetupFailure({ message: failure.message }));
+	if (existing === undefined) {
+		return yield* Console.log(`quality: there is no pre-commit hook at ${file}.`);
+	}
+	if (!isHookShim(existing)) {
+		return yield* Console.error(`quality: kept ${file}: it is not quality's pre-commit hook.`);
+	}
+	yield* Effect.mapError(fs.remove(file), (error) => new SetupFailure({ message: `cannot remove ${file}: ${error.message}` }));
+	yield* Console.log(`quality: removed the pre-commit hook at ${file}.`);
+});