@workerstack/repo 0.0.0-stage → 0.1.0

package/cli/nightly-config.ts

@@ -0,0 +1,62 @@
+/** The `nightly` section of workerstack.config.ts: how many shards the nightly mutation run has, which secrets its live job gets. */
+import { z } from "zod";
+import {
+  MAX_SHARDS,
+  MIN_SHARDS,
+  RESERVED_PREFIX,
+  SECRETS_ERROR,
+  SECRET_ERROR,
+  SECRET_NAME,
+  SECTION_ERROR,
+  SHARDS_ERROR,
+  TWICE,
+} from "./nightly-config.constants.ts";
+
+/** What the generated nightly workflow reads. */
+export type ResolvedNightly = { readonly shards: number; readonly secrets: readonly string[] };
+
+/** The nightly run a config gets when it omits `nightly` or one of its keys. */
+export const DEFAULT_NIGHTLY: ResolvedNightly = { shards: 1, secrets: [] };
+
+type NightlySchema = z.ZodObject<
+  {
+    shards: z.ZodOptional<z.ZodNumber>;
+    secrets: z.ZodOptional<z.ZodReadonly<z.ZodArray<z.ZodString>>>;
+  },
+  z.core.$strict
+>;
+
+function buildSchema(): NightlySchema {
+  const secret = z
+    .string({ error: SECRET_ERROR })
+    .regex(SECRET_NAME, { error: SECRET_ERROR })
+    .refine((name) => !name.startsWith(RESERVED_PREFIX), { error: SECRET_ERROR });
+  const secrets = z
+    .array(secret, { error: SECRETS_ERROR })
+    .readonly()
+    .superRefine((names, ctx) => {
+      const counts = new Map<string, number>();
+      for (const name of names) counts.set(name, (counts.get(name) ?? 0) + 1);
+      for (const [name, count] of counts) {
+        if (count === 1) continue;
+        const times = count === TWICE ? "twice" : `${count} times`;
+        ctx.addIssue({ code: "custom", message: `${JSON.stringify(name)} is listed ${times}` });
+      }
+    });
+  const shards = z
+    .number({ error: SHARDS_ERROR })
+    .int({ error: SHARDS_ERROR })
+    .min(MIN_SHARDS, { error: SHARDS_ERROR })
+    .max(MAX_SHARDS, { error: SHARDS_ERROR });
+  return z.strictObject({ shards: shards.optional(), secrets: secrets.optional() }, { error: SECTION_ERROR });
+}
+
+export const nightlySchema: NightlySchema = /* @__PURE__ */ buildSchema();
+
+/** The parsed config's `nightly` section with every omitted key filled in. */
+export function nightlyOf(parsed: { nightly?: z.output<typeof nightlySchema> | undefined }): {
+  nightly: ResolvedNightly;
+} {
+  const { shards, secrets } = parsed.nightly ?? {};
+  return { nightly: { shards: shards ?? DEFAULT_NIGHTLY.shards, secrets: secrets ?? DEFAULT_NIGHTLY.secrets } };
+}

package/cli/prompt.test.ts

@@ -0,0 +1,202 @@
+import { afterEach, describe, expect, it, vi } from "vitest";
+
+const clackSelect = vi.hoisted(() => vi.fn());
+const clackConfirm = vi.hoisted(() => vi.fn());
+const clackText = vi.hoisted(() => vi.fn());
+const clackPassword = vi.hoisted(() => vi.fn());
+const clackSpinner = vi.hoisted(() => vi.fn());
+const clackIsCancel = vi.hoisted(() => vi.fn());
+const clackCancel = vi.hoisted(() => vi.fn());
+
+vi.mock("@clack/prompts", () => ({
+  select: clackSelect,
+  confirm: clackConfirm,
+  text: clackText,
+  password: clackPassword,
+  spinner: clackSpinner,
+  isCancel: clackIsCancel,
+  cancel: clackCancel,
+}));
+
+import { bailIfCancel, confirm, isInteractive, password, select, spinner, text } from "./prompt.ts";
+
+function tty(isTTY: boolean) {
+  return { isTTY } as NodeJS.ReadStream & NodeJS.WriteStream;
+}
+
+describe("isInteractive", () => {
+  it("true when both TTY, CI unset, no yes flags", () => {
+    expect(
+      isInteractive({
+        argv: [],
+        env: {},
+        stdin: tty(true),
+        stdout: tty(true),
+      }),
+    ).toBe(true);
+  });
+
+  it("true when CI is 0 or false or empty", () => {
+    for (const CI of ["0", "false", ""]) {
+      expect(
+        isInteractive({
+          argv: [],
+          env: { CI },
+          stdin: tty(true),
+          stdout: tty(true),
+        }),
+      ).toBe(true);
+    }
+  });
+
+  it("false when stdin not TTY", () => {
+    expect(
+      isInteractive({
+        argv: [],
+        env: {},
+        stdin: tty(false),
+        stdout: tty(true),
+      }),
+    ).toBe(false);
+  });
+
+  it("false when stdout not TTY", () => {
+    expect(
+      isInteractive({
+        argv: [],
+        env: {},
+        stdin: tty(true),
+        stdout: tty(false),
+      }),
+    ).toBe(false);
+  });
+
+  it("false when stdin isTTY missing", () => {
+    expect(
+      isInteractive({
+        argv: [],
+        env: {},
+        stdin: {} as NodeJS.ReadStream,
+        stdout: tty(true),
+      }),
+    ).toBe(false);
+  });
+
+  it.each(["1", "true", "yes", "CI"])("false when CI=%s", (CI) => {
+    expect(
+      isInteractive({
+        argv: [],
+        env: { CI },
+        stdin: tty(true),
+        stdout: tty(true),
+      }),
+    ).toBe(false);
+  });
+
+  it.each(["--yes", "-y", "--non-interactive"])("false when argv has %s", (flag) => {
+    expect(
+      isInteractive({
+        argv: [flag],
+        env: {},
+        stdin: tty(true),
+        stdout: tty(true),
+      }),
+    ).toBe(false);
+  });
+
+  it("uses process defaults", () => {
+    const stdinDesc = Object.getOwnPropertyDescriptor(process.stdin, "isTTY");
+    const stdoutDesc = Object.getOwnPropertyDescriptor(process.stdout, "isTTY");
+    const argv = process.argv;
+    Object.defineProperty(process.stdin, "isTTY", { configurable: true, value: true });
+    Object.defineProperty(process.stdout, "isTTY", { configurable: true, value: true });
+    process.argv = ["node", "repo"];
+    vi.stubEnv("CI", undefined);
+    try {
+      expect(isInteractive()).toBe(true);
+      process.argv = ["node", "repo", "--yes"];
+      expect(isInteractive()).toBe(false);
+    } finally {
+      process.argv = argv;
+      if (stdinDesc) Object.defineProperty(process.stdin, "isTTY", stdinDesc);
+      else delete (process.stdin as { isTTY?: boolean }).isTTY;
+      if (stdoutDesc) Object.defineProperty(process.stdout, "isTTY", stdoutDesc);
+      else delete (process.stdout as { isTTY?: boolean }).isTTY;
+    }
+  });
+});
+
+describe("bailIfCancel", () => {
+  afterEach(() => {
+    clackIsCancel.mockReset();
+    clackCancel.mockReset();
+  });
+
+  it("returns value when not cancel", () => {
+    clackIsCancel.mockReturnValue(false);
+    expect(bailIfCancel("ok")).toBe("ok");
+    expect(clackCancel).not.toHaveBeenCalled();
+  });
+
+  it("cancel Aborted and exit 0", () => {
+    clackIsCancel.mockReturnValue(true);
+    const exit = vi.spyOn(process, "exit").mockImplementation((() => {
+      throw new Error("EXIT");
+    }) as typeof process.exit);
+    expect(() => bailIfCancel(Symbol("cancel"))).toThrow("EXIT");
+    expect(clackCancel).toHaveBeenCalledWith("Aborted");
+    expect(exit).toHaveBeenCalledWith(0);
+    exit.mockRestore();
+  });
+});
+
+describe("clack wrappers", () => {
+  afterEach(() => {
+    clackSelect.mockReset();
+    clackConfirm.mockReset();
+    clackSpinner.mockReset();
+    clackIsCancel.mockReset();
+    clackCancel.mockReset();
+  });
+
+  it("select bails then returns", async () => {
+    clackSelect.mockResolvedValue("init");
+    clackIsCancel.mockReturnValue(false);
+    await expect(select({ message: "Command" } as Parameters<typeof select>[0])).resolves.toBe("init");
+    expect(clackSelect).toHaveBeenCalledWith({ message: "Command" });
+  });
+
+  it("confirm bails then returns", async () => {
+    clackConfirm.mockResolvedValue(true);
+    clackIsCancel.mockReturnValue(false);
+    await expect(confirm({ message: "Re-init?" })).resolves.toBe(true);
+    expect(clackConfirm).toHaveBeenCalledWith({ message: "Re-init?" });
+  });
+
+  it("select cancel exits 0", async () => {
+    clackSelect.mockResolvedValue("x");
+    clackIsCancel.mockReturnValue(true);
+    const exit = vi.spyOn(process, "exit").mockImplementation((() => {
+      throw new Error("EXIT");
+    }) as typeof process.exit);
+    await expect(select({} as Parameters<typeof select>[0])).rejects.toThrow("EXIT");
+    expect(clackCancel).toHaveBeenCalledWith("Aborted");
+    expect(exit).toHaveBeenCalledWith(0);
+    exit.mockRestore();
+  });
+
+  it("spinner passthrough", () => {
+    const s = { start: vi.fn(), stop: vi.fn() };
+    clackSpinner.mockReturnValue(s);
+    expect(spinner()).toBe(s);
+    expect(clackSpinner).toHaveBeenCalledOnce();
+  });
+
+  it("text and password bail then return", async () => {
+    clackText.mockResolvedValue("proj");
+    clackPassword.mockResolvedValue("sk_x");
+    clackIsCancel.mockReturnValue(false);
+    await expect(text({ message: "Project ID" })).resolves.toBe("proj");
+    await expect(password({ message: "API key" })).resolves.toBe("sk_x");
+  });
+});

package/cli/prompt.ts

@@ -0,0 +1 @@
+export { bailIfCancel, confirm, isInteractive, password, select, spinner, text } from "./scripts/prompt.ts";

package/cli/red-proof-edges.test.ts

@@ -0,0 +1,78 @@
+import fs from "node:fs";
+import nodePath from "node:path";
+import { afterEach, expect, it, vi } from "vitest";
+import { git, removePlanted } from "./fixtures/planted-repo.ts";
+import { PASS, plant, problemOf, stage } from "./fixtures/red-proof-repo.ts";
+import { parseNameStatus, redProof, type VitestRun } from "./red-proof.ts";
+import { type GitRun, runGit } from "./sync/standards.ts";
+
+/** The real runner's timeout and missing vitest, the outer repo's git env, git failing, and the diff parser. */
+afterEach(removePlanted);
+const change = (...files: [string, string][]) => files.map(([status, file]) => ({ status, path: file }));
+const A_TEST = change(["A", "a.test.ts"]);
+const SLOW = { timeout: 60_000 };
+const never: VitestRun = () => {
+  throw new Error("vitest must not run");
+};
+const ENV_TEST = `import { expect, it } from "vitest";
+it("e", () => expect(Object.keys(process.env).filter((k) => k.startsWith("GIT_") && !k.startsWith("GIT_CONFIG_"))).toEqual([]));
+`;
+
+it("refuses with the timeout reason when vitest outlives the timeout", SLOW, () => {
+  const root = plant({ "s.ts": "head\n" });
+  stage(root, { "a.test.ts": PASS });
+  expect(problemOf(redProof(root, A_TEST, { timeoutMs: 1 }))).toMatch(
+    /^red-proof: vitest wrote no report in \. \(exit 1\): vitest did not finish within 1ms/,
+  );
+});
+
+it("refuses with the reason when the package has no vitest", SLOW, () => {
+  const root = plant({ "s.ts": "head\n" });
+  fs.rmSync(nodePath.join(root, "node_modules"));
+  stage(root, { "a.test.ts": PASS });
+  expect(problemOf(redProof(root, A_TEST))).toMatch(
+    /^red-proof: vitest wrote no report in \. \(exit 1\): cannot resolve vitest/,
+  );
+});
+
+it("strips GIT_* from the nested run and leaves the committed repo's index alone", SLOW, () => {
+  const root = plant({ "s.ts": "head\n" });
+  stage(root, { "e.test.ts": ENV_TEST, "s.ts": "new\n" });
+  const seen = () => ({ index: git(root, "ls-files", "-s"), status: git(root, "status", "--porcelain") });
+  const before = seen();
+  vi.stubEnv("GIT_DIR", nodePath.join(root, ".git"));
+  vi.stubEnv("GIT_INDEX_FILE", nodePath.join(root, ".git", "index"));
+  const result = redProof(root, change(["A", "e.test.ts"], ["M", "s.ts"]));
+  vi.unstubAllEnvs();
+  expect(problemOf(result)).toContain("(e.test.ts passed)");
+  expect(seen()).toEqual(before);
+});
+
+const failing =
+  (word: string, status: number): GitRun =>
+  (root, args, input) =>
+    args.includes(word) ? { status, stdout: "", stderr: "fatal: nope" } : runGit(root, args, input);
+
+it("throws naming the command when write-tree fails, leaving no dir", () => {
+  const root = plant({ "s.ts": "head\n" });
+  stage(root, { "a.test.ts": PASS });
+  const faulty = failing("write-tree", 128);
+  expect(() => redProof(root, A_TEST, { git: faulty, vitest: never })).toThrow(
+    "red-proof: git write-tree failed: fatal: nope",
+  );
+  expect(fs.existsSync(nodePath.join(root, ".tmp", "repo", `red-proof-${process.pid}`))).toBe(false);
+});
+
+it("throws when the archive cannot be unpacked", () => {
+  const root = plant({ "s.ts": "head\n" });
+  stage(root, { "a.test.ts": PASS });
+  const faulty = failing("archive", 0);
+  expect(() => redProof(root, A_TEST, { git: faulty, vitest: never })).toThrow(/^red-proof: tar failed: /);
+});
+
+it("reads the NUL-separated name-status entries", () => {
+  expect(parseNameStatus("M\0a.ts\0A\0dir/b.test.ts\0D\0c.ts\0")).toEqual(
+    change(["M", "a.ts"], ["A", "dir/b.test.ts"], ["D", "c.ts"]),
+  );
+  expect(parseNameStatus("")).toEqual([]);
+});

package/cli/red-proof-failures.test.ts

@@ -0,0 +1,82 @@
+import fs from "node:fs";
+import { afterEach, expect, it } from "vitest";
+import { removePlanted } from "./fixtures/planted-repo.ts";
+import { PASS, fakeVitest, outputOf, plant, stage } from "./fixtures/red-proof-repo.ts";
+import { redProof, type VitestRun } from "./red-proof.ts";
+
+/** Refusals with no test to run, and vitest runs that leave no report, through the injected runner. */
+afterEach(removePlanted);
+const change = (...files: [string, string][]) => files.map(([status, file]) => ({ status, path: file }));
+const never: VitestRun = () => {
+  throw new Error("vitest must not run");
+};
+const NO_FILE = {
+  ok: false,
+  problem: "red-proof: no changed vitest test file outside e2e/ to run on HEAD; add one that fails without the change",
+};
+const A_TEST = change(["A", "a.test.ts"]);
+
+it("refuses a change with only e2e tests and source, without running vitest", () => {
+  const root = plant({ "s.ts": "head\n" });
+  stage(root, { "e2e/a.test.ts": PASS, "s.ts": "new\n" });
+  const files = change(["A", "e2e/a.test.ts"], ["M", "s.ts"]);
+  expect(redProof(root, files, { vitest: never })).toEqual(NO_FILE);
+});
+
+it("refuses a change with no test, a deleted test or nothing, without running vitest", () => {
+  const root = plant({ "s.ts": "head\n", "d.test.ts": PASS });
+  expect(redProof(root, change(["M", "s.ts"]), { vitest: never })).toEqual(NO_FILE);
+  expect(redProof(root, change(["D", "d.test.ts"]), { vitest: never })).toEqual(NO_FILE);
+  expect(redProof(root, [], { vitest: never })).toEqual(NO_FILE);
+});
+
+it("refuses when vitest crashed, quoting the last stderr lines", () => {
+  const root = plant({ "s.ts": "head\n" });
+  stage(root, { "a.test.ts": PASS });
+  const crash: VitestRun = () => ({ code: 1, stderr: "one\ntwo\nthree\nfour\nfive\n" });
+  expect(redProof(root, A_TEST, { vitest: crash })).toEqual({
+    ok: false,
+    problem: "red-proof: vitest wrote no report in . (exit 1): three | four | five",
+  });
+});
+
+it("names the package dir when its run timed out", () => {
+  const root = plant({ "cli/package.json": { name: "c" } });
+  stage(root, { "cli/a.test.ts": PASS });
+  const timeout: VitestRun = () => ({ code: 1, stderr: "vitest timed out after 5ms" });
+  expect(redProof(root, change(["A", "cli/a.test.ts"]), { vitest: timeout })).toEqual({
+    ok: false,
+    problem: "red-proof: vitest wrote no report in cli (exit 1): vitest timed out after 5ms",
+  });
+});
+
+it.each(["{nope", "{}", '{"testResults":[{"name":1}]}'])("refuses a report that reads %s", (text) => {
+  const root = plant({ "s.ts": "head\n" });
+  stage(root, { "a.test.ts": PASS });
+  const writes: VitestRun = (args) => {
+    fs.writeFileSync(outputOf(args), text);
+    return { code: 3, stderr: "bad\n" };
+  };
+  expect(redProof(root, A_TEST, { vitest: writes })).toEqual({
+    ok: false,
+    problem: "red-proof: vitest wrote no report in . (exit 3): bad",
+  });
+});
+
+it("hands the runner the nested flags, a json report, no coverage and the default timeout", () => {
+  const root = plant({ "s.ts": "head\n" });
+  stage(root, { "a.test.ts": PASS });
+  const seen: { args: string[]; timeout: number }[] = [];
+  const run: VitestRun = (args, cwd, timeout) => {
+    seen.push({ args, timeout });
+    return fakeVitest(() => true)(args, cwd, timeout);
+  };
+  redProof(root, A_TEST, { vitest: run });
+  const joined = seen.map((call) => call.args.join(" ")).join("");
+  expect(seen.map((call) => call.args.slice(0, 4))).toEqual([
+    ["run", "a.test.ts", "--fsModuleCache=false", "--reporter=json"],
+  ]);
+  expect(joined).toMatch(/--outputFile=\S*red-proof-\d+\S*\.json$/);
+  expect(joined).not.toContain("overage");
+  expect(seen.map((call) => call.timeout)).toEqual([300_000]);
+});

package/cli/red-proof-tree.test.ts

@@ -0,0 +1,157 @@
+import fs from "node:fs";
+import nodePath from "node:path";
+import { afterEach, expect, it } from "vitest";
+import { git, removePlanted } from "./fixtures/planted-repo.ts";
+import { PASS, fakeVitest, plant, plantUnborn, stage, staged } from "./fixtures/red-proof-repo.ts";
+import { redProof } from "./red-proof.ts";
+
+/** What the HEAD tree holds when vitest runs in it, seen through a stand-in runner on planted repos. */
+afterEach(removePlanted);
+const change = (...files: [string, string][]) => files.map(([status, file]) => ({ status, path: file }));
+const read = (cwd: string, file: string) =>
+  fs.existsSync(nodePath.join(cwd, file)) ? fs.readFileSync(nodePath.join(cwd, file), "utf8") : null;
+
+const BASE = { "s.ts": "head\n", "gone.ts": "gone\n", "fixtures/f.ts": "old\n", "__snapshots__/a.snap": "old\n" };
+const STAGED = {
+  "s.ts": "staged\n",
+  "new.ts": "new\n",
+  "fixtures/f.ts": "newer\n",
+  "fixtures/helper.ts": "h\n",
+  "__snapshots__/a.snap": "newer\n",
+  "app.config.ts": "cfg\n",
+  "a.test.ts": PASS,
+  "notes.md": "n\n",
+};
+const MIXED = change(
+  ["M", "s.ts"],
+  ["A", "new.ts"],
+  ["D", "gone.ts"],
+  ["M", "fixtures/f.ts"],
+  ["A", "fixtures/helper.ts"],
+  ["M", "__snapshots__/a.snap"],
+  ["A", "app.config.ts"],
+  ["A", "a.test.ts"],
+  ["A", "notes.md"],
+);
+const WATCHED = ["s.ts", "new.ts", "gone.ts", "fixtures/f.ts", "fixtures/helper.ts", "__snapshots__/a.snap"];
+
+it("puts a changed source file back and removes a new one on the HEAD tree", () => {
+  const root = plant(BASE);
+  stage(root, STAGED);
+  git(root, "rm", "-q", "gone.ts");
+  const seen: Record<string, string | null> = {};
+  const run = fakeVitest(
+    () => true,
+    (cwd) => {
+      for (const file of [...WATCHED, "app.config.ts", "notes.md"]) seen[file] = read(cwd, file);
+    },
+  );
+  expect(redProof(root, MIXED, { vitest: run })).toMatchObject({ ok: true });
+  expect(seen).toMatchObject({ "s.ts": "head\n", "new.ts": null, "gone.ts": "gone\n" });
+});
+
+it("keeps fixtures, snapshots, configs and other files as staged", () => {
+  const root = plant(BASE);
+  stage(root, STAGED);
+  const seen: Record<string, string | null> = {};
+  const run = fakeVitest(
+    () => true,
+    (cwd) => {
+      for (const file of [...WATCHED, "app.config.ts", "notes.md"]) seen[file] = read(cwd, file);
+    },
+  );
+  redProof(root, MIXED, { vitest: run });
+  expect(seen).toMatchObject({
+    "fixtures/f.ts": "newer\n",
+    "fixtures/helper.ts": "h\n",
+    "__snapshots__/a.snap": "newer\n",
+    "app.config.ts": "cfg\n",
+    "notes.md": "n\n",
+  });
+  expect(git(root, "status", "--porcelain")).toContain("M  s.ts");
+});
+
+it("puts a renamed file's old path back", () => {
+  const root = plant({ "old.ts": "old\n" });
+  git(root, "mv", "old.ts", "new.ts");
+  stage(root, { "a.test.ts": PASS });
+  const seen: (string | null)[] = [];
+  const run = fakeVitest(
+    () => true,
+    (cwd) => seen.push(read(cwd, "old.ts"), read(cwd, "new.ts")),
+  );
+  const files = change(["D", "old.ts"], ["A", "new.ts"], ["A", "a.test.ts"]);
+  expect(redProof(root, files, { vitest: run }).ok).toBe(true);
+  expect(seen).toEqual(["old\n", null]);
+});
+
+it("runs two packages each in their own HEAD-tree dir with their modules linked", () => {
+  const root = plant({ "pkg-a/package.json": { name: "a" }, "pkg-b/package.json": { name: "b" } });
+  fs.mkdirSync(nodePath.join(root, "pkg-a", "node_modules"));
+  stage(root, { "pkg-a/a.test.ts": PASS, "pkg-b/b.test.ts": PASS, "pkg-b/c.test.ts": PASS });
+  const calls: unknown[] = [];
+  const run = fakeVitest(
+    (file) => file === "a.test.ts",
+    (cwd, args) =>
+      calls.push({
+        cwd: nodePath.relative(root, cwd),
+        files: args.filter((arg) => arg.endsWith(".ts")),
+        linked: fs.existsSync(nodePath.join(cwd, "node_modules")),
+        rootLinked: fs.existsSync(nodePath.join(cwd, "..", "node_modules")),
+      }),
+  );
+  const files = change(["A", "pkg-a/a.test.ts"], ["A", "pkg-b/b.test.ts"], ["A", "pkg-b/c.test.ts"]);
+  expect(redProof(root, files, { vitest: run })).toEqual({
+    ok: true,
+    line: "red-proof: 1 of 3 changed test files failed on HEAD",
+  });
+  const name = nodePath.join(".tmp", "repo", `red-proof-${process.pid}`);
+  expect(calls).toEqual([
+    { cwd: nodePath.join(name, "pkg-a"), files: ["a.test.ts"], linked: true, rootLinked: true },
+    { cwd: nodePath.join(name, "pkg-b"), files: ["b.test.ts", "c.test.ts"], linked: false, rootLinked: true },
+  ]);
+});
+
+it("removes its dir after a pass and after a throw", () => {
+  const root = plant({ "s.ts": "head\n" });
+  stage(root, { "a.test.ts": PASS });
+  const tree = nodePath.join(root, ".tmp", "repo", `red-proof-${process.pid}`);
+  const seen: boolean[] = [];
+  const run = fakeVitest(
+    () => true,
+    () => seen.push(fs.existsSync(tree)),
+  );
+  redProof(root, change(["A", "a.test.ts"]), { vitest: run });
+  expect(seen).toEqual([true]);
+  expect(fs.existsSync(tree)).toBe(false);
+  const boom = () => {
+    throw new Error("boom");
+  };
+  expect(() => redProof(root, change(["A", "a.test.ts"]), { vitest: boom })).toThrow("boom");
+  expect(fs.existsSync(tree)).toBe(false);
+});
+
+it("skips with a line when there is no HEAD", () => {
+  const root = plantUnborn({ "a.test.ts": PASS });
+  expect(redProof(root, change(["A", "a.test.ts"]), { vitest: fakeVitest(() => true) })).toEqual({
+    ok: true,
+    line: "red-proof: skipped, no HEAD to run against",
+  });
+  expect(staged(root)).toBe("A\ta.test.ts\n");
+});
+
+it("owns a nested test by the nearest package dir above it", () => {
+  const root = plant({ "cli/package.json": { name: "c" } });
+  stage(root, { "cli/sub/deep/a.test.ts": PASS, "top/b.test.ts": PASS });
+  const calls: unknown[] = [];
+  const run = fakeVitest(
+    () => false,
+    (cwd, args) => calls.push([nodePath.relative(root, cwd), args[1]]),
+  );
+  redProof(root, change(["A", "cli/sub/deep/a.test.ts"], ["A", "top/b.test.ts"]), { vitest: run });
+  const name = nodePath.join(".tmp", "repo", `red-proof-${process.pid}`);
+  expect(calls).toEqual([
+    [nodePath.join(name, "cli"), "sub/deep/a.test.ts"],
+    [name, "top/b.test.ts"],
+  ]);
+});

package/cli/red-proof-verdict.test.ts

@@ -0,0 +1,44 @@
+import { afterEach, expect, it } from "vitest";
+import { git, removePlanted } from "./fixtures/planted-repo.ts";
+import { FAIL, NEEDS_X, PASS, plant, stage } from "./fixtures/red-proof-repo.ts";
+import { redProof } from "./red-proof.ts";
+
+/** The verdict on a real vitest run against HEAD's source in a planted repo. */
+const SLOW = { timeout: 60_000 };
+afterEach(removePlanted);
+const change = (...files: [string, string][]) => files.map(([status, file]) => ({ status, path: file }));
+const readsV = (n: number) =>
+  `import { expect, it } from "vitest";\nimport { v } from "./v.ts";\nit("v", () => expect(v).toBe(${n}));\n`;
+const RED = (failed: number, total: number) => ({
+  ok: true,
+  line: `red-proof: ${failed} of ${total} changed test files failed on HEAD`,
+});
+
+it("proves red when a changed test fails on HEAD's source", SLOW, () => {
+  const root = plant({ "v.ts": "export const v = 1;\n", "v.test.ts": readsV(1) });
+  stage(root, { "v.ts": "export const v = 2;\n", "v.test.ts": readsV(2) });
+  expect(redProof(root, change(["M", "v.ts"], ["M", "v.test.ts"]))).toEqual(RED(1, 1));
+  expect(git(root, "status", "--porcelain")).toBe("M  v.test.ts\nM  v.ts\n");
+});
+
+it("refuses a changed test that also passes on HEAD, naming it", SLOW, () => {
+  const root = plant({ "v.ts": "export const v = 1;\n" });
+  stage(root, { "v.ts": "export const v = 2;\n", "a.test.ts": PASS });
+  expect(redProof(root, change(["M", "v.ts"], ["A", "a.test.ts"]))).toEqual({
+    ok: false,
+    problem:
+      "red-proof: no changed test file fails on HEAD's source (a.test.ts passed); a feat or fix needs one that fails without the change",
+  });
+});
+
+it("fails a test of a new source file, which is absent on HEAD", SLOW, () => {
+  const root = plant({ "keep.txt": "k\n" });
+  stage(root, { "x.ts": "export const x = () => 1;\n", "x.test.ts": NEEDS_X });
+  expect(redProof(root, change(["A", "x.ts"], ["A", "x.test.ts"]))).toEqual(RED(1, 1));
+});
+
+it("counts a failing test and a passing one apart", SLOW, () => {
+  const root = plant({ "keep.txt": "k\n" });
+  stage(root, { "a.test.ts": FAIL, "b.test.ts": PASS });
+  expect(redProof(root, change(["A", "a.test.ts"], ["A", "b.test.ts"]))).toEqual(RED(1, 2));
+});

package/cli/red-proof.constants.ts

@@ -0,0 +1,14 @@
+/** The names `repo red-proof` reads from git and vitest. */
+
+/** The `git diff --name-status` letter of a path the change adds. */
+export const STATUS_ADDED = "A";
+/** The `git diff --name-status` letter of a path the change deletes. */
+export const STATUS_DELETED = "D";
+/** The status vitest's json report gives a test file with a failing test. */
+export const REPORT_FAILED = "failed";
+/** The bytes in a kibibyte. */
+const KIB = 1024;
+/** The most output a vitest run may print before it is cut off: 64 MiB. */
+export const MAX_BUFFER: number = 64 * KIB * KIB;
+/** How many trailing stderr lines a missing-report problem quotes. */
+export const STDERR_TAIL_LINES = -3;