@avi2dg/checks 0.18.0 → 0.20.0

package/scripts/subsumed-tests.ts

@@ -0,0 +1,208 @@
+#!/usr/bin/env bun
+import { Console, Effect, FileSystem } from "effect";
+import { runMain, Usage } from "./main.ts";
+import { type KillRun, parseKillRun, ReportError } from "./mutation-compare.ts";
+
+export type KillSets = ReadonlyMap<string, ReadonlySet<string>>;
+
+export type Subsumed = {
+  readonly test: string;
+  readonly kills: number;
+  readonly subsumedBy: string;
+  readonly subsumerKills: number;
+};
+
+export type IdenticalGroup = {
+  readonly tests: readonly string[];
+  readonly kills: number;
+};
+
+export type Cover = {
+  readonly members: readonly string[];
+  readonly tests: number;
+  readonly kills: number;
+};
+
+export type Report = {
+  readonly files: readonly string[];
+  readonly subsumed: readonly Subsumed[];
+  readonly identical: readonly IdenticalGroup[];
+  readonly cover: Cover;
+};
+
+export type Options = {
+  readonly reportPath: string;
+};
+
+const USAGE = "usage: subsumed-tests.ts <mutation-report>";
+
+export function killSetsOf(run: KillRun): KillSets {
+  const kills = new Map<string, Set<string>>();
+  for (const file of run.testFiles.values()) for (const test of file.tests) kills.set(test.id, new Set<string>());
+  for (const [path, file] of run.files) {
+    file.mutants.forEach((mutant, index) => {
+      for (const test of mutant.killedBy ?? []) {
+        let set = kills.get(test);
+        if (set === undefined) {
+          set = new Set<string>();
+          kills.set(test, set);
+        }
+        set.add(`${path}#${index}`);
+      }
+    });
+  }
+  return kills;
+}
+
+function isSuperset(candidate: ReadonlySet<string>, other: ReadonlySet<string>): boolean {
+  if (candidate.size <= other.size) return false;
+  for (const kill of other) if (!candidate.has(kill)) return false;
+  return true;
+}
+
+function subsumerOf(test: string, kills: ReadonlySet<string>, sets: KillSets): { readonly name: string; readonly size: number } | undefined {
+  let best: { readonly name: string; readonly size: number } | undefined;
+  for (const [other, otherKills] of sets) {
+    if (other !== test && isSuperset(otherKills, kills) && (best === undefined || otherKills.size > best.size || (otherKills.size === best.size && other < best.name))) best = { name: other, size: otherKills.size };
+  }
+  return best;
+}
+
+export function findSubsumed(sets: KillSets): readonly Subsumed[] {
+  const subsumed: Subsumed[] = [];
+  for (const [test, kills] of sets) {
+    if (kills.size === 0) continue;
+    const subsumer = subsumerOf(test, kills, sets);
+    if (subsumer !== undefined) subsumed.push({ test, kills: kills.size, subsumedBy: subsumer.name, subsumerKills: subsumer.size });
+  }
+  return subsumed;
+}
+
+export function findIdentical(sets: KillSets): readonly IdenticalGroup[] {
+  const groups = new Map<string, string[]>();
+  for (const [test, kills] of sets) {
+    if (kills.size === 0) continue;
+    const key = [...kills].toSorted().join("\n");
+    const group = groups.get(key);
+    if (group === undefined) groups.set(key, [test]);
+    else group.push(test);
+  }
+  return [...groups.values()].filter((tests) => tests.length > 1).map((tests) => ({ tests, kills: sets.get(tests[0] ?? "")?.size ?? 0 }));
+}
+
+function uncoveredCount(kills: ReadonlySet<string>, uncovered: ReadonlySet<string>): number {
+  let count = 0;
+  for (const kill of kills) if (uncovered.has(kill)) count++;
+  return count;
+}
+
+function bestAddition(candidates: readonly (readonly [string, ReadonlySet<string>])[], members: readonly string[], uncovered: ReadonlySet<string>): readonly [string, ReadonlySet<string>] | undefined {
+  let best: readonly [string, ReadonlySet<string>] | undefined;
+  let bestCount = 0;
+  for (const candidate of candidates) {
+    if (members.includes(candidate[0])) continue;
+    const count = uncoveredCount(candidate[1], uncovered);
+    if (count > bestCount) {
+      best = candidate;
+      bestCount = count;
+    }
+  }
+  return best;
+}
+
+export function greedyCover(sets: KillSets): Cover {
+  const uncovered = new Set<string>();
+  for (const kills of sets.values()) for (const kill of kills) uncovered.add(kill);
+  const total = uncovered.size;
+  const members: string[] = [];
+  const candidates = [...sets].toSorted(([a], [b]) => (a < b ? -1 : 1));
+  while (uncovered.size > 0) {
+    const best = bestAddition(candidates, members, uncovered);
+    if (best === undefined) break;
+    members.push(best[0]);
+    for (const kill of best[1]) uncovered.delete(kill);
+  }
+  return { members, tests: sets.size, kills: total };
+}
+
+function testNames(run: KillRun): ReadonlyMap<string, string> {
+  const names = new Map<string, string>();
+  for (const [path, file] of run.testFiles) for (const test of file.tests) names.set(test.id, qualified(path, test.name));
+  return names;
+}
+
+// The bun runner writes names that already open with their file.
+function qualified(path: string, name: string): string {
+  return path === "" || name.startsWith(`${path} > `) ? name : `${path} > ${name}`;
+}
+
+const byName = (a: string, b: string) => (a < b ? -1 : 1);
+
+export function analyze(run: KillRun): Report {
+  const sets = killSetsOf(run);
+  const names = testNames(run);
+  const name = (id: string) => names.get(id) ?? id;
+  const cover = greedyCover(sets);
+  return {
+    files: [...run.files.keys()].toSorted(),
+    subsumed: findSubsumed(sets)
+      .map((one) => ({ ...one, test: name(one.test), subsumedBy: name(one.subsumedBy) }))
+      .toSorted((a, b) => byName(a.test, b.test)),
+    identical: findIdentical(sets)
+      .map((group) => ({ ...group, tests: group.tests.map(name).toSorted(byName) }))
+      .toSorted((a, b) => byName(a.tests[0] ?? "", b.tests[0] ?? "")),
+    cover: { ...cover, members: cover.members.map(name) },
+  };
+}
+
+function describeTest(test: string, kills: number): string {
+  return `${JSON.stringify(test)} (${kills} kill${kills === 1 ? "" : "s"})`;
+}
+
+export function formatReport(report: Report): string {
+  const lines = [`subsumed-tests: ${report.files.length} file(s) mutated`];
+  for (const file of report.files) lines.push(`  mutated ${file}`);
+  lines.push(`subsumed tests (${report.subsumed.length}):`);
+  for (const one of report.subsumed) lines.push(`  ${describeTest(one.test, one.kills)} subsumed by ${describeTest(one.subsumedBy, one.subsumerKills)}`);
+  lines.push(`identical kill sets (${report.identical.length} group(s)):`);
+  for (const group of report.identical) lines.push(`  ${group.tests.map((test) => describeTest(test, group.kills)).join(" = ")}`);
+  lines.push(`greedy cover: ${report.cover.members.length} of ${report.cover.tests} test(s) keep all ${report.cover.kills} kill(s)`);
+  for (const member of report.cover.members) lines.push(`  cover ${JSON.stringify(member)}`);
+  return lines.join("\n");
+}
+
+export const bailWarning = (source: string, run: KillRun): Effect.Effect<string | undefined, ReportError> => {
+  if (run.bail === "on")
+    return Effect.fail(
+      new ReportError({
+        message: `${source} was built with bail on, since its config.disableBail is not true, so each mutant records only its first killer: rerun Stryker with \`bunx stryker run --disableBail\` and pass the report it writes`,
+      }),
+    );
+  if (run.bail === "unrecorded") return Effect.succeed(`${source} records no config, so nothing shows whether bail was off: build it with \`bunx stryker run --disableBail\``);
+  return Effect.succeed(undefined);
+};
+
+export const parseArgs = Effect.fnUntraced(function* (argv: readonly string[]): Effect.fn.Return<Options, Usage> {
+  const [reportPath, ...extra] = argv.filter((arg) => !arg.startsWith("--"));
+  const flag = argv.find((arg) => arg.startsWith("--"));
+  if (flag !== undefined) return yield* new Usage({ message: `${USAGE}: unknown flag ${flag}` });
+  if (reportPath === undefined || extra.length > 0) return yield* new Usage({ message: USAGE });
+  return { reportPath };
+});
+
+const load = Effect.fn("load")(function* (path: string) {
+  const fs = yield* FileSystem.FileSystem;
+  const text = yield* fs.readFileString(path).pipe(Effect.mapError(() => new ReportError({ message: `cannot read ${path}` })));
+  const run = yield* parseKillRun(path, text);
+  const warning = yield* bailWarning(path, run);
+  if (warning !== undefined) yield* Console.error(`subsumed-tests: warning: ${warning}`);
+  return run;
+});
+
+const report = Effect.gen(function* () {
+  const options = yield* parseArgs(process.argv.slice(2));
+  yield* Console.log(formatReport(analyze(yield* load(options.reportPath))));
+  return true;
+});
+
+if (import.meta.main) runMain("subsumed-tests", report);

package/scripts/suppressions-ratchet.ts

@@ -1,6 +1,6 @@
 #!/usr/bin/env bun
 import { Console, Effect, Schema } from "effect";
-import { git, parentOrEmptyTree, refArgs } from "./git.ts";
+import { git, commitOf, parentOrEmptyTree, refArgs } from "./git.ts";
 import { runMain } from "./main.ts";
 
 export const SUPPRESSIONS = "oxlint-suppressions.json";
@@ -87,10 +87,6 @@ export function report({ counted, lowered, rises }: Ratchet): string {
   ].join("\n");
 }
 
-const commitOf = Effect.fn("commitOf")(function* (rev: string) {
-  return (yield* git(["rev-parse", "--verify", `${rev}^{commit}`])).trim();
-});
-
 const mergeBase = Effect.fn("mergeBase")(function* (base: string, head: string) {
   const commit = yield* git(["merge-base", base, head]).pipe(
     Effect.mapError(() => new SuppressionsError({ message: `${base} and ${head} share no commit` })),

package/scripts/test-layout.ts

@@ -3,7 +3,8 @@ import { parse } from "@swc/core";
 import { Console, Effect, FileSystem, Path, Schema } from "effect";
 import { git } from "./git.ts";
 import { runMain } from "./main.ts";
-import { ENTRY_POINT, TEST_ENTRY_POINT } from "./gates.ts";
+import { ENTRY_POINT, QUALITY_FILE, TEST_ENTRY_POINT } from "./gates.ts";
+import { readQuality } from "./quality-file.ts";
 
 export type Violation = {
   readonly file: string;
@@ -16,7 +17,7 @@ const E2E = "tests/e2e/";
 const HELPER_DIRS = ["tests/lib/", "tests/fixtures/"] as const;
 const DATA_DIR = "tests/fixtures/";
 
-const TEST_FILE = /(?:[.](?:test|spec)|_test)[.](tsx?)$/;
+export const TEST_FILE = /(?:[.](?:test|spec)|_test)[.](tsx?)$/;
 const TARGET_FILE = /^tests\/(?:[^/]+\/)*[^/]+[.]test[.]tsx?$/;
 const TYPESCRIPT = /[.]tsx?$/;
 
@@ -39,9 +40,14 @@ const BANNED_BUN_NAMES: readonly string[] = [
 ];
 const BANNED_GLOBAL_CALLS: readonly string[] = ["fetch"];
 
-const REQUIRED_TEST_TABLE: Record<string, unknown> = {
-  pathIgnorePatterns: ["**/tests/quarantine/**"],
-};
+const IGNORES_KEY = "pathIgnorePatterns";
+const QUARANTINE = "**/tests/quarantine/**";
+const VENDORED = "repos/**";
+const PRESET_IGNORES: readonly string[] = [QUARANTINE, VENDORED];
+
+function acceptedIgnores(vendors: boolean): readonly (readonly string[])[] {
+  return vendors ? [PRESET_IGNORES] : [PRESET_IGNORES, [QUARANTINE]];
+}
 export const LAYOUT_CHECK_MARK = "scripts/test-layout.ts";
 export const LAYOUT_CHECK_BIN = "checks-test-layout";
 const OWN_ENTRY_POINT = `scripts/${ENTRY_POINT.script}`;
@@ -245,7 +251,7 @@ export function scriptViolations(manifest: unknown): readonly Violation[] {
   return violations;
 }
 
-export function bunfigViolations(consumer: unknown, preset: unknown): readonly Violation[] {
+export function bunfigViolations(consumer: unknown, preset: unknown, vendors: boolean): readonly Violation[] {
   const file = "bunfig.toml";
   const copy = "bun has no bunfig extends, so copy node_modules/@avi2dg/checks/bunfig.toml";
   if (consumer === undefined) {
@@ -255,18 +261,21 @@ export function bunfigViolations(consumer: unknown, preset: unknown): readonly V
   if (!isRecord(presetTest)) {
     return [{ file, line: undefined, message: "the shipped bunfig preset has no [test] table" }];
   }
-  const expected = { ...presetTest, ...REQUIRED_TEST_TABLE };
   const consumerTest = isRecord(consumer) ? consumer["test"] : undefined;
+  const found = (key: string): unknown => (isRecord(consumerTest) ? consumerTest[key] : undefined);
+  const drifted = (key: string, wanted: string, fix: string): Violation => ({
+    file,
+    line: undefined,
+    message: `[test].${key} must be ${wanted}, found ${JSON.stringify(found(key) ?? null)}; ${fix}`,
+  });
   const violations: Violation[] = [];
-  for (const [key, value] of Object.entries(expected)) {
-    const found = isRecord(consumerTest) ? consumerTest[key] : undefined;
-    if (!Bun.deepEquals(found, value)) {
-      violations.push({
-        file,
-        line: undefined,
-        message: `[test].${key} must be ${JSON.stringify(value)}, found ${JSON.stringify(found ?? null)}; ${copy}`,
-      });
-    }
+  for (const [key, value] of Object.entries(presetTest)) {
+    if (key !== IGNORES_KEY && !Bun.deepEquals(found(key), value)) violations.push(drifted(key, JSON.stringify(value), copy));
+  }
+  const accepted = acceptedIgnores(vendors);
+  if (!accepted.some((ignores) => Bun.deepEquals(found(IGNORES_KEY), ignores))) {
+    const wanted = accepted.map((ignores) => JSON.stringify(ignores)).join(" or ");
+    violations.push(drifted(IGNORES_KEY, wanted, `the check pins it, requiring ${VENDORED} where ${QUALITY_FILE} declares sources.libraries`));
   }
   return violations;
 }
@@ -321,7 +330,9 @@ export const run = Effect.fn("run")(function* (root: string, presetPath: string)
 
   const bunfig = path.join(root, "bunfig.toml");
   const consumerBunfig = (yield* fs.exists(bunfig)) ? yield* parsedToml(bunfig) : undefined;
-  violations.push(...bunfigViolations(consumerBunfig, yield* parsedToml(presetPath)));
+  const { quality } = yield* readQuality(root);
+  const vendors = (quality.sources?.libraries ?? []).length > 0;
+  violations.push(...bunfigViolations(consumerBunfig, yield* parsedToml(presetPath), vendors));
 
   return { files: files.length, violations };
 });

package/scripts/vendor.ts

@@ -0,0 +1,337 @@
+#!/usr/bin/env bun
+import { Console, Effect, FileSystem, Option, Path, Schema } from "effect";
+import { QUALITY_FILE } from "./gates.ts";
+import { git } from "./git.ts";
+import { runMain, Usage } from "./main.ts";
+import { readQuality, type Library } from "./quality-file.ts";
+
+const NAME = "checks-vendor";
+const USAGE = `usage: ${NAME} takes no arguments, since quality.json names the libraries`;
+const CACHE_HOME = ".cache/avi2dg-checks";
+const RECORD_SUFFIX = ".commit";
+const LINKS = "repos";
+const VERSION_TOKEN = "{version}";
+// bun runs prepare under umask 0, so a mode left to the umask lets any local user swap the shared tree.
+const DIRECTORY_MODE = 0o755;
+const RECORD_MODE = 0o644;
+
+export class VendorError extends Schema.TaggedError<VendorError>()("VendorError", {
+  message: Schema.String,
+}) {}
+
+export class Unreachable extends Schema.TaggedError<Unreachable>()("Unreachable", {
+  message: Schema.String,
+}) {}
+
+export function tagFor(template: string, version: string): string {
+  return template.replaceAll(VERSION_TOKEN, version);
+}
+
+const SCHEMED = /^([a-z][a-z0-9+.-]*):\/\/(?:[^/@]+@)?([^/:]+)(?::\d+)?\/(.+)$/i;
+const SCP_LIKE = /^(?:[^@/:]+@)?([^:/]+):(.+)$/;
+
+function urlSegments(host: string, rest: string): readonly string[] {
+  const parts = rest.split("/").filter((part) => part !== "");
+  return [host, ...parts.slice(0, -1), (parts[parts.length - 1] ?? "").replace(/\.git$/, "")];
+}
+
+export function remoteSegments(remote: string): readonly string[] {
+  const cleaned = remote.replace(/\/+$/, "");
+  const schemed = SCHEMED.exec(cleaned);
+  if (schemed !== null) {
+    const [, , host, rest] = schemed;
+    if (host !== undefined && rest !== undefined) return urlSegments(host, rest);
+  }
+  const scp = SCP_LIKE.exec(cleaned);
+  if (scp !== null) {
+    const [, host, rest] = scp;
+    if (host !== undefined && rest !== undefined) return urlSegments(host, rest);
+  }
+  const escaped = cleaned
+    .replaceAll("_", "__")
+    .replaceAll("/", "_")
+    .replaceAll(":", "_")
+    .replace(/^\.+/, (dots) => "_".repeat(dots.length));
+  return ["local", escaped];
+}
+
+export function listsTag(output: string, tag: string): boolean {
+  return output.split("\n").some((line) => line.split("\t")[1] === `refs/tags/${tag}`);
+}
+
+const PackageManifest = Schema.Struct({ version: Schema.NonEmptyString });
+const decodeManifest = Schema.decodeUnknownEffect(Schema.fromJsonString(PackageManifest));
+
+const manifestVersion = Effect.fn("manifestVersion")(function* (file: string, missing: string) {
+  const fs = yield* FileSystem.FileSystem;
+  if (!(yield* fs.exists(file))) return yield* new VendorError({ message: missing });
+  const { version } = yield* fs.readFileString(file).pipe(
+    Effect.flatMap(decodeManifest),
+    Effect.mapError((cause) => new VendorError({ message: `${file} carries no version: ${cause.message}` })),
+  );
+  return version;
+});
+
+const headOf = Effect.fn("headOf")(function* (dir: string) {
+  return (yield* git(["rev-parse", "HEAD"], dir).pipe(
+    Effect.mapError((cause) => new VendorError({ message: `${dir} names no commit: ${cause.message}` })),
+  )).trim();
+});
+
+const confirmTag = Effect.fn("confirmTag")(function* (remote: string, tag: string) {
+  const output = yield* git(["ls-remote", remote, `refs/tags/${tag}*`]).pipe(
+    Effect.mapError((cause) => new Unreachable({ message: `cannot list ${tag} on ${remote}: ${cause.message}` })),
+  );
+  if (!listsTag(output, tag)) {
+    return yield* new VendorError({ message: `${remote} holds no tag ${tag}, so the installed version points nowhere` });
+  }
+});
+
+const isLink = Effect.fn("isLink")(function* (entry: string) {
+  const fs = yield* FileSystem.FileSystem;
+  return Option.isSome(yield* fs.readLink(entry).pipe(Effect.option));
+});
+
+type EntryMode = {
+  readonly entry: string;
+  readonly mode: number;
+};
+
+const modes = Effect.fn("modes")(function* (dir: string) {
+  const fs = yield* FileSystem.FileSystem;
+  const path = yield* Path.Path;
+  const found: EntryMode[] = [];
+  const pending = [dir];
+  for (const entry of pending) {
+    if (yield* isLink(entry)) continue;
+    const info = yield* fs.stat(entry).pipe(
+      Effect.mapError((cause) => new VendorError({ message: `cannot stat ${entry}: ${cause.message}` })),
+    );
+    found.push({ entry, mode: info.mode });
+    if (info.type !== "Directory") continue;
+    const children = yield* fs.readDirectory(entry).pipe(
+      Effect.mapError((cause) => new VendorError({ message: `cannot list ${entry}: ${cause.message}` })),
+    );
+    pending.push(...children.map((child) => path.join(entry, child)));
+  }
+  return found;
+});
+
+const WRITE_BITS = 0o222;
+const OWNER_WRITE = 0o200;
+
+function clearing(dir: string): string {
+  return `clear it with \`chmod -R u+w ${dir} && rm -rf ${dir}\` and rerun ${NAME}`;
+}
+
+const freeze = Effect.fn("freeze")(function* (dir: string) {
+  const fs = yield* FileSystem.FileSystem;
+  for (const { entry, mode } of yield* modes(dir)) {
+    yield* fs.chmod(entry, mode & ~WRITE_BITS).pipe(
+      Effect.mapError((cause) => new VendorError({ message: `cannot freeze ${entry}: ${cause.message}` })),
+    );
+  }
+});
+
+function discard(dir: string) {
+  return Effect.gen(function* () {
+    const fs = yield* FileSystem.FileSystem;
+    if (!(yield* fs.exists(dir))) return;
+    for (const { entry, mode } of yield* modes(dir)) yield* fs.chmod(entry, mode | OWNER_WRITE);
+    yield* fs.remove(dir, { recursive: true });
+  }).pipe(Effect.catch((cause) => Console.error(`${NAME}: cannot clear the staging tree ${dir}: ${cause.message}`)));
+}
+
+const checkVersion = Effect.fn("checkVersion")(function* (dir: string, library: Library, installed: string, tag: string) {
+  const path = yield* Path.Path;
+  const manifest = path.join(dir, library.path ?? "package.json");
+  const landed = yield* manifestVersion(manifest, `${manifest} is missing, so ${tag} cannot prove it holds ${installed}`);
+  if (landed !== installed) {
+    return yield* new VendorError({ message: `${tag} holds version ${landed}, not the installed ${installed}` });
+  }
+});
+
+function recordOf(dir: string): string {
+  return `${dir}${RECORD_SUFFIX}`;
+}
+
+const recorded = Effect.fn("recorded")(function* (dir: string) {
+  const fs = yield* FileSystem.FileSystem;
+  const record = recordOf(dir);
+  if (!(yield* fs.exists(record))) return Option.none<string>();
+  const text = yield* fs.readFileString(record).pipe(
+    Effect.mapError((cause) => new VendorError({ message: `cannot read ${record}: ${cause.message}` })),
+  );
+  return Option.some(text.trim());
+});
+
+const verify = Effect.fn("verify")(function* (dir: string, library: Library, installed: string, tag: string) {
+  const held = yield* recorded(dir);
+  if (Option.isNone(held)) {
+    return yield* new VendorError({ message: `${recordOf(dir)} is missing, so ${dir} has no commit to hold to; ${clearing(dir)}` });
+  }
+  const record = held.value;
+  const head = yield* headOf(dir);
+  if (head !== record) {
+    return yield* new VendorError({ message: `${dir} sits on ${head}, not the recorded ${record}; ${clearing(dir)}` });
+  }
+  yield* checkVersion(dir, library, installed, tag);
+  const tampered = (yield* modes(dir)).filter(({ mode }) => (mode & WRITE_BITS) !== 0).map(({ entry }) => entry);
+  if (tampered.length > 0) {
+    const [first = dir] = tampered;
+    return yield* new VendorError({
+      message: `${dir} leaves ${tampered.length} paths writable, starting with ${first}; ${clearing(dir)}`,
+    });
+  }
+  const status = yield* git(["status", "--porcelain", "--ignored"], dir).pipe(
+    Effect.mapError((cause) => new VendorError({ message: `${dir} reports no status: ${cause.message}` })),
+  );
+  if (status.trim() !== "") {
+    const [first = ""] = status.trim().split("\n");
+    return yield* new VendorError({ message: `${dir} holds writes outside the recorded commit, starting with ${first}; ${clearing(dir)}` });
+  }
+});
+
+const ensureLink = Effect.fn("ensureLink")(function* (root: string, library: Library, dir: string) {
+  const fs = yield* FileSystem.FileSystem;
+  const path = yield* Path.Path;
+  const parent = path.join(root, LINKS);
+  yield* fs.makeDirectory(parent, { recursive: true, mode: DIRECTORY_MODE }).pipe(
+    Effect.mapError((cause) => new VendorError({ message: `cannot hold ${parent}: ${cause.message}` })),
+  );
+  const at = path.join(parent, library.name);
+  const current = yield* fs.readLink(at).pipe(Effect.option);
+  if (Option.isSome(current)) {
+    if (current.value === dir) return;
+    yield* fs.remove(at).pipe(
+      Effect.mapError((cause) => new VendorError({ message: `cannot move ${at} aside: ${cause.message}` })),
+    );
+  } else if (yield* fs.exists(at)) {
+    return yield* new VendorError({ message: `${at} is not a link, so ${NAME} leaves it alone; move it away and rerun` });
+  }
+  yield* fs.symlink(dir, at).pipe(
+    Effect.mapError((cause) => new VendorError({ message: `cannot link ${at} to ${dir}: ${cause.message}` })),
+  );
+});
+
+const unlink = Effect.fn("unlink")(function* (root: string, library: Library) {
+  const fs = yield* FileSystem.FileSystem;
+  const path = yield* Path.Path;
+  const at = path.join(root, LINKS, library.name);
+  if (Option.isNone(yield* fs.readLink(at).pipe(Effect.option))) return;
+  yield* fs.remove(at).pipe(
+    Effect.mapError((cause) => new VendorError({ message: `cannot drop ${at}: ${cause.message}` })),
+  );
+  yield* Console.error(`${NAME}: dropped ${LINKS}/${library.name}, so readers fall back to node_modules/${library.package}`);
+});
+
+const stage = Effect.fn("stage")(function* (staging: string, library: Library, installed: string, tag: string, dir: string) {
+  const fs = yield* FileSystem.FileSystem;
+  yield* git(["clone", "--no-local", "--branch", tag, "--depth", "1", "--", library.repository, staging]).pipe(
+    Effect.mapError((cause) => new Unreachable({ message: `cannot clone ${tag} from ${library.repository}: ${cause.message}` })),
+  );
+  const head = yield* headOf(staging);
+  const held = yield* recorded(dir);
+  if (Option.isSome(held) && held.value !== head) {
+    return yield* new VendorError({
+      message: `${tag} on ${library.repository} lands on ${head}, not the recorded ${held.value}; delete ${recordOf(dir)} to accept the move`,
+    });
+  }
+  yield* checkVersion(staging, library, installed, tag);
+  if (Option.isNone(held)) {
+    yield* fs.writeFileString(recordOf(dir), `${head}\n`, { mode: RECORD_MODE }).pipe(
+      Effect.mapError((cause) => new VendorError({ message: `cannot record the fetch beside ${dir}: ${cause.message}` })),
+    );
+  }
+  yield* freeze(staging);
+  return yield* fs.rename(staging, dir).pipe(
+    Effect.as(true),
+    Effect.catchTag("PlatformError", (cause) =>
+      Effect.flatMap(fs.exists(dir), (raced) =>
+        raced ? Effect.succeed(false) : Effect.fail(new VendorError({ message: `cannot move ${staging} into ${dir}: ${cause.message}` })),
+      ),
+    ),
+  );
+});
+
+const land = Effect.fn("land")(function* (library: Library, installed: string, tag: string, dir: string) {
+  const fs = yield* FileSystem.FileSystem;
+  const path = yield* Path.Path;
+  const parent = path.dirname(dir);
+  yield* confirmTag(library.repository, tag);
+  yield* fs.makeDirectory(parent, { recursive: true, mode: DIRECTORY_MODE }).pipe(
+    Effect.mapError((cause) => new VendorError({ message: `cannot hold ${dir}: ${cause.message}` })),
+  );
+  const staging = yield* fs.makeTempDirectory({ directory: parent, prefix: `.${path.basename(dir)}-` }).pipe(
+    Effect.mapError((cause) => new VendorError({ message: `cannot stage ${dir}: ${cause.message}` })),
+  );
+  return yield* stage(staging, library, installed, tag, dir).pipe(Effect.ensuring(discard(staging)));
+});
+
+const vend = Effect.fn("vend")(function* (root: string, cache: string, library: Library) {
+  const fs = yield* FileSystem.FileSystem;
+  const path = yield* Path.Path;
+  const installed = yield* manifestVersion(
+    path.join(root, "node_modules", ...library.package.split("/"), "package.json"),
+    `node_modules/${library.package}/package.json is missing, so the installed version of ${library.package} is unknown; install first`,
+  );
+  const tag = tagFor(library.tag, installed);
+  const dir = path.join(cache, LINKS, ...remoteSegments(library.repository), tag);
+  if (!(yield* fs.exists(dir)) && (yield* land(library, installed, tag, dir))) {
+    yield* Console.error(`${NAME}: cloned ${tag} from ${library.repository} and linked ${LINKS}/${library.name}`);
+  } else {
+    yield* verify(dir, library, installed, tag);
+    yield* Console.error(`${NAME}: ${LINKS}/${library.name} still holds ${tag}, verified against its recorded commit`);
+  }
+  yield* ensureLink(root, library, dir);
+});
+
+const cacheRoot = Effect.fn("cacheRoot")(function* () {
+  const path = yield* Path.Path;
+  const home = process.env.HOME;
+  if (home === undefined || home === "") {
+    return yield* new VendorError({ message: "HOME is missing, so the shared cache has no root" });
+  }
+  return path.join(home, CACHE_HOME);
+});
+
+const main = Effect.gen(function* () {
+  const [extra] = process.argv.slice(2);
+  if (extra !== undefined) return yield* new Usage({ message: USAGE });
+  const toplevel = yield* git(["rev-parse", "--show-toplevel"]).pipe(
+    Effect.map((output) => Option.some(output.trim())),
+    Effect.catchTag("GitFailure", (failure) =>
+      Console.error(`${NAME}: ${failure.message}, so no checkout holds ${LINKS}/ and readers stay on node_modules`).pipe(
+        Effect.as(Option.none<string>()),
+      ),
+    ),
+  );
+  if (Option.isNone(toplevel)) return true;
+  const root = toplevel.value;
+  const { quality } = yield* readQuality(root);
+  const libraries = quality.sources?.libraries ?? [];
+  if (libraries.length === 0) {
+    yield* Console.error(`${NAME}: ${QUALITY_FILE} declares no libraries, so nothing is pinned`);
+    return true;
+  }
+  const cache = yield* cacheRoot();
+  let passed = true;
+  for (const library of libraries) {
+    const vended = yield* vend(root, cache, library).pipe(
+      Effect.as(true),
+      Effect.catchTags({
+        VendorError: (failure) =>
+          Console.error(`${NAME}: ${failure.message}`).pipe(Effect.andThen(unlink(root, library)), Effect.as(false)),
+        Unreachable: (failure) =>
+          Console.error(`${NAME}: ${failure.message}, so ${LINKS}/${library.name} stays unlinked until a run can fetch it`).pipe(
+            Effect.andThen(unlink(root, library)),
+            Effect.as(true),
+          ),
+      }),
+    );
+    passed = passed && vended;
+  }
+  return passed;
+});
+
+if (import.meta.main) runMain(NAME, main);