@workerstack/repo 0.0.0-stage → 0.1.0

package/cli/red-proof.ts

@@ -0,0 +1,202 @@
+import { spawnSync } from "node:child_process";
+import fs from "node:fs";
+import path from "node:path";
+import { z } from "zod";
+import { childEnv } from "./env.ts";
+import { MAX_BUFFER, REPORT_FAILED, STATUS_ADDED, STATUS_DELETED, STDERR_TAIL_LINES } from "./red-proof.constants.ts";
+import { NESTED_VITEST_FLAGS } from "./nested-vitest-flags.ts";
+import { toolEnv } from "./scripts/lint.ts";
+import { type GitRun, runGit } from "./sync/standards.ts";
+import { isCodeFile, isSource, isTestFile } from "./test-files.ts";
+
+/** One `git diff --cached --name-status --no-renames -z` entry: a status letter (A, M, D, T) and a path. */
+export type NameStatus = { status: string; path: string };
+/** Runs vitest with `args` (after the binary) in `cwd`, giving up after `timeoutMs`; a run that did not finish has a non-zero code. */
+export type VitestRun = (args: string[], cwd: string, timeoutMs: number) => { code: number; stderr: string };
+export type RedProofDeps = { git?: GitRun; vitest?: VitestRun; timeoutMs?: number };
+export type RedProofResult = { ok: true; line: string } | { ok: false; problem: string };
+
+const TIMEOUT_MS = 5 * 60_000;
+const NO_FILE =
+  "red-proof: no changed vitest test file outside e2e/ to run on HEAD; add one that fails without the change";
+
+/** The entries of `git diff --name-status -z` output. */
+export function parseNameStatus(text: string): NameStatus[] {
+  const parts = text.split("\0").filter((part) => part !== "");
+  return Array.from({ length: parts.length / 2 }, (_, n) => ({
+    status: parts[2 * n] /* entries come in status, path pairs */ as string,
+    path: parts[2 * n + 1] /* entries come in status, path pairs */ as string,
+  }));
+}
+
+/** A vitest test file the proof runs: a code file `isTest` matches, outside `e2e/`. */
+const isRunnable = (file: string): boolean => isCodeFile(file) && isTestFile(file) && !/(^|\/)e2e\//.test(file);
+
+/** Vitest from the package at `cwd`, run under bun as the package's own tests would; null-free: a run that ends early reports why. */
+const runVitest: VitestRun = (args, cwd, timeoutMs) => {
+  let manifest: string;
+  try {
+    manifest = Bun.resolveSync("vitest/package.json", cwd);
+  } catch {
+    return { code: 1, stderr: `cannot resolve vitest from ${cwd}` };
+  }
+  const { bin } = JSON.parse(fs.readFileSync(manifest, "utf8")) /* vitest's manifest has a bin map */ as {
+    bin: Record<string, string>;
+  };
+  const script = path.join(path.dirname(manifest), bin["vitest"] /* vitest declares its bin */ as string);
+  const result = spawnSync(process.execPath, ["--bun", script, ...args], {
+    cwd,
+    env: toolEnv(childEnv({ NO_COLOR: "1" })),
+    encoding: "utf8",
+    timeout: timeoutMs,
+    maxBuffer: MAX_BUFFER,
+  });
+  if (result.error) return { code: 1, stderr: `vitest did not finish within ${timeoutMs}ms (${result.error.message})` };
+  return { code: result.status /* null only when result.error is set */ as number, stderr: result.stderr };
+};
+
+/** Unpacks a tar file into `cwd`; shaped like a git runner so a failure reads the same. */
+const untar: GitRun = (cwd, args) => {
+  const result = spawnSync("tar", [...args], { cwd, encoding: "utf8" });
+  return { status: result.status, stdout: result.stdout, stderr: `${result.stderr}` };
+};
+
+/** The result's stdout, or a throw naming `what` and git's reason. */
+function must(what: string, result: ReturnType<GitRun>): string {
+  if (result.status !== 0) throw new Error(`red-proof: ${what} failed: ${result.stderr.trim()}`);
+  return result.stdout;
+}
+
+const ARCHIVE = ".red-proof.tar";
+
+type Tree = { root: string; tree: string; git: GitRun };
+
+/** Unpacks the staged tree into the HEAD tree dir. */
+function unpack({ root, tree, git }: Tree): void {
+  const archive = path.join(tree, ARCHIVE);
+  const sha = must("git write-tree", git(root, ["write-tree"])).trim();
+  // No eol conversion: `git show` in putBack writes the blob as is, so the tree must hold blobs as they are too.
+  must("git archive", git(root, ["-c", "core.autocrlf=false", "archive", "--format=tar", `--output=${archive}`, sha]));
+  // Relative to the tree: GNU tar reads an absolute `C:\\…` as `host:path` and tries to connect to the host `C`.
+  must("tar", untar(tree, ["-xf", ARCHIVE]));
+}
+
+/** Puts every changed source file back from HEAD, or removes it when new. */
+function putBack({ root, tree, git }: Tree, change: NameStatus[]): void {
+  for (const { status, path: file } of change.filter((entry) => isSource(entry.path))) {
+    const target = path.join(tree, file);
+    if (status === STATUS_ADDED) fs.rmSync(target, { force: true });
+    else {
+      fs.mkdirSync(path.dirname(target), { recursive: true });
+      fs.writeFileSync(target, must(`git show HEAD:${file}`, git(root, ["show", `HEAD:${file}`])));
+    }
+  }
+}
+
+/** Links each package dir's checkout `node_modules` into the tree; returns the package dirs (`.` is the root). */
+function linkModules({ root, tree, git }: Tree): Set<string> {
+  const listed = must("git ls-files", git(root, ["ls-files", "-z", "--", ":(glob)**/package.json"]));
+  const dirs = new Set(["."]);
+  for (const manifest of listed.split("\0").filter((entry) => entry !== "")) dirs.add(path.dirname(manifest));
+  for (const dir of dirs) {
+    const modules = path.join(root, dir, "node_modules");
+    if (fs.existsSync(modules) && fs.existsSync(path.join(tree, dir)))
+      fs.symlinkSync(modules, path.join(tree, dir, "node_modules"), "junction"); // no symlink privilege needed on Windows
+  }
+  return dirs;
+}
+
+/** The nearest package dir at or above the file, `.` when none. */
+function ownerOf(file: string, dirs: Set<string>): string {
+  let dir = path.dirname(file);
+  while (dir !== "." && !dirs.has(dir)) dir = path.dirname(dir);
+  return dir;
+}
+
+/** The test files grouped by owner package dir, each path relative to that dir. */
+function groupByOwner(files: string[], dirs: Set<string>): Map<string, string[]> {
+  const groups = new Map<string, string[]>();
+  for (const file of files) {
+    const dir = ownerOf(file, dirs);
+    groups.set(dir, [...(groups.get(dir) ?? []), path.posix.relative(dir, file)]);
+  }
+  return groups;
+}
+
+/** The shape of the vitest json report this reads. */
+const reportSchema = () => z.object({ testResults: z.array(z.object({ name: z.string(), status: z.string() })) });
+
+/** The vitest results in the report file, or null when it is missing, unreadable or not a vitest report. */
+function readReport(file: string): { name: string; status: string }[] | null {
+  try {
+    return reportSchema().parse(JSON.parse(fs.readFileSync(file, "utf8"))).testResults;
+  } catch {
+    return null;
+  }
+}
+
+type Ran = { problem: string } | { failed: string[]; passed: string[] };
+type Run = (args: string[], cwd: string) => ReturnType<VitestRun>;
+
+/** Runs the groups' test files in the HEAD tree; the problem when a run wrote no report, else who failed and who passed. */
+function runGroups(tree: string, groups: Map<string, string[]>, vitest: Run): Ran {
+  const failed: string[] = [];
+  const passed: string[] = [];
+  let n = 0;
+  for (const [dir, files] of groups) {
+    const output = path.join(tree, `.red-proof-report-${n++}.json`);
+    const args = ["run", ...files, ...NESTED_VITEST_FLAGS, "--reporter=json", `--outputFile=${output}`];
+    const ran = vitest(args, path.join(tree, dir));
+    const results = readReport(output);
+    if (results === null) {
+      const tail = ran.stderr.trim().split("\n").slice(STDERR_TAIL_LINES).join(" | ");
+      return { problem: `red-proof: vitest wrote no report in ${dir} (exit ${ran.code}): ${tail}`.trimEnd() };
+    }
+    for (const file of files) {
+      const red = results.some(
+        (r) => r.status === REPORT_FAILED && r.name.split(path.sep).join("/").endsWith(`/${file}`),
+      );
+      (red ? failed : passed).push(path.posix.join(dir, file));
+    }
+  }
+  return { failed, passed };
+}
+
+/** Red when any test file failed on HEAD, else a refusal naming the ones that passed. */
+function verdict(ran: { failed: string[]; passed: string[] }, total: number): RedProofResult {
+  if (ran.failed.length > 0)
+    return { ok: true, line: `red-proof: ${ran.failed.length} of ${total} changed test files failed on HEAD` };
+  const named = ran.passed.join(", ");
+  return {
+    ok: false,
+    problem: `red-proof: no changed test file fails on HEAD's source (${named} passed); a feat or fix needs one that fails without the change`,
+  };
+}
+
+/**
+ * Runs the changed vitest test files against HEAD's source and says whether one fails there. The staged tree is built
+ * under `<root>/.tmp/repo/red-proof-<pid>/` with every changed source file put back; the dir is removed on the way out.
+ */
+export function redProof(root: string, change: NameStatus[], deps: RedProofDeps = {}): RedProofResult {
+  const { git = runGit, vitest = runVitest, timeoutMs = TIMEOUT_MS } = deps;
+  if (git(root, ["rev-parse", "--verify", "--quiet", "HEAD"]).status !== 0)
+    return { ok: true, line: "red-proof: skipped, no HEAD to run against" };
+  const tests = change.filter((entry) => entry.status !== STATUS_DELETED && isRunnable(entry.path));
+  if (tests.length === 0) return { ok: false, problem: NO_FILE };
+  const tree = path.join(root, ".tmp", "repo", `red-proof-${process.pid}`);
+  fs.rmSync(tree, { recursive: true, force: true });
+  fs.mkdirSync(tree, { recursive: true });
+  try {
+    const context = { root, tree, git };
+    unpack(context);
+    putBack(context, change);
+    const groups = groupByOwner(
+      tests.map((entry) => entry.path),
+      linkModules(context),
+    );
+    const ran = runGroups(tree, groups, (args, cwd) => vitest(args, cwd, timeoutMs));
+    return "problem" in ran ? { ok: false, problem: ran.problem } : verdict(ran, tests.length);
+  } finally {
+    fs.rmSync(tree, { recursive: true, force: true });
+  }
+}

package/cli/release/changelog-parse.ts

@@ -0,0 +1,83 @@
+import { FENCE, HEADING, UNRELEASED, VERSION_HASHES, VERSION_HEADING } from "./release.constants.ts";
+import type { Parts } from "./version.ts";
+
+/** A `##` (version) or `###` (section) heading outside a code fence: its line (0-based) and the text after the hashes. */
+export type Heading = { at: number; kind: "version" | "section"; text: string };
+/** A `##` section: its heading line, the version in it (null when it names none) and the lines below. */
+export type Section = { heading: string; version: string | null; body: string[] };
+/** The text before the first section, and each section in file order. */
+export type Parsed = { preamble: string[]; sections: Section[] };
+
+/** The lines of a file, without the newline that ends it. */
+export const linesOf = (text: string): string[] => text.replace(/\n$/, "").split("\n");
+
+/** Every heading of `lines` that is not inside a fenced code block. */
+export function headings(lines: readonly string[]): Heading[] {
+  let fenced = false;
+  const found: Heading[] = [];
+  lines.forEach((line, at) => {
+    if (line.startsWith(FENCE)) fenced = !fenced;
+    const [, hashes, text] = (fenced ? null : HEADING.exec(line)) ?? [];
+    if (text !== undefined) found.push({ at, kind: hashes === VERSION_HASHES ? "version" : "section", text });
+  });
+  return found;
+}
+
+/** Splits a changelog at its `##` headings. */
+export function parseChangelog(text: string): Parsed {
+  const lines = linesOf(text);
+  const starts = headings(lines).filter((heading) => heading.kind === "version");
+  const first = starts[0]?.at ?? lines.length;
+  const sections = starts.map(({ at, text: heading }, i) => ({
+    heading: `${VERSION_HASHES} ${heading}`,
+    version: VERSION_HEADING.exec(heading)?.[1] ?? null,
+    body: lines.slice(at + 1, starts[i + 1]?.at ?? lines.length),
+  }));
+  return { preamble: lines.slice(0, first), sections };
+}
+
+/** The `##` section of `version` in a changelog's text; null when it has none. */
+export function sectionFor(text: string, version: string): Section | null {
+  return parseChangelog(text).sections.find((section) => section.version === version) ?? null;
+}
+
+/** The `###` groups of a section body, in order: the loose text before the first has the name "". */
+export function groupsOf(body: readonly string[]): [string, string[]][] {
+  let current: [string, string[]] = ["", []];
+  const groups = [current];
+  const starts = new Map(
+    headings(body)
+      .filter((h) => h.kind === "section")
+      .map((h) => [h.at, h.text]),
+  );
+  body.forEach((line, at) => {
+    const name = starts.get(at);
+    if (name === undefined) {
+      current[1].push(line);
+      return;
+    }
+    current = [name, []];
+    groups.push(current);
+  });
+  return groups.map(([name, lines]) => [name, trimBlank(lines)]);
+}
+
+/** `lines` without the blank lines at either end. */
+export function trimBlank(lines: readonly string[]): string[] {
+  const text = lines.join("\n").replace(/^\n+|\n+$/g, "");
+  return text === "" ? [] : text.split("\n");
+}
+
+/** Whether the Unreleased section of `parsed` has any entry text. */
+export function unreleasedHasText({ sections }: Parsed): boolean {
+  const unreleased = sections.find((section) => section.version === UNRELEASED);
+  return unreleased?.body.some((line) => line.trim() !== "" && !HEADING.test(line)) ?? false;
+}
+
+/** A positive number when `x` is the newer version, negative when `y` is, 0 when equal; a prerelease is below its release. */
+export function compareVersions(x: Parts, y: Parts): number {
+  const core = Math.sign(x.major - y.major) || Math.sign(x.minor - y.minor) || Math.sign(x.patch - y.patch);
+  if (core !== 0) return core;
+  if (x.id === undefined || y.id === undefined) return Number(x.id === undefined) - Number(y.id === undefined);
+  return x.id === y.id ? x.n - y.n : x.id.localeCompare(y.id);
+}

package/cli/release/changelog.test.ts

@@ -0,0 +1,141 @@
+import { describe, expect, it } from "vitest";
+import { changelogFormatProblems, hasUnreleased, stampChangelog } from "./changelog.ts";
+
+const HEAD = "# Changelog\n\nAll notable changes.\n\n";
+
+describe("changelogFormatProblems headings", () => {
+  it("passes a changelog in the Keep a Changelog format", () => {
+    const text = `${HEAD}## [Unreleased]\n\n### Added\n\n- x\n\n## [0.2.0] - 2026-11-01\n\n### Fixed\n\n- y\n\n## [0.1.0] - 2026-10-01\n\n### Added\n\n- z\n`;
+    expect(changelogFormatProblems(text)).toEqual([]);
+  });
+
+  it("says a missing file is missing", () => {
+    expect(changelogFormatProblems(null)).toEqual(["CHANGELOG.md is missing; add one in the Keep a Changelog format"]);
+  });
+
+  it("asks for an Unreleased section", () => {
+    expect(changelogFormatProblems(`${HEAD}## [0.1.0] - 2026-10-01\n`)).toEqual([
+      "CHANGELOG.md has no ## [Unreleased] section; add it above the newest version",
+    ]);
+  });
+
+  it("wants a date on every version", () => {
+    const text = `${HEAD}## [Unreleased]\n\n## [0.2.0]\n\n### Added\n\n- x\n`;
+    expect(changelogFormatProblems(text)).toEqual([
+      'CHANGELOG.md:7: "## [0.2.0]" needs a date; write ## [0.2.0] - YYYY-MM-DD',
+    ]);
+  });
+
+  it("accepts only the six Keep a Changelog sections", () => {
+    const text = `${HEAD}## [Unreleased]\n\n### Improved\n\n- x\n\n### Security\n\n- y\n`;
+    expect(changelogFormatProblems(text)).toEqual([
+      'CHANGELOG.md:7: "### Improved" is not a section; use Added, Changed, Deprecated, Removed, Fixed or Security',
+    ]);
+  });
+});
+
+describe("changelogFormatProblems order", () => {
+  it("lists versions newest first, a prerelease below its release", () => {
+    const text = `${HEAD}## [Unreleased]\n\n## [0.2.0] - 2026-11-01\n\n## [0.3.0] - 2026-11-02\n\n## [0.3.0-rc.0] - 2026-11-01\n`;
+    expect(changelogFormatProblems(text)).toEqual(["CHANGELOG.md:9: 0.3.0 is below 0.2.0; list versions newest first"]);
+    const ok = `${HEAD}## [Unreleased]\n\n## [1.0.0] - 2026-11-02\n\n## [1.0.0-rc.1] - 2026-11-01\n\n## [1.0.0-rc.0] - 2026-10-30\n`;
+    expect(changelogFormatProblems(ok)).toEqual([]);
+  });
+});
+
+describe("changelogFormatProblems prereleases", () => {
+  it("puts a release above its prereleases and orders other prerelease ids by name", () => {
+    const pre = `${HEAD}## [Unreleased]\n\n## [1.0.0-rc.0] - 2026-11-01\n\n## [1.0.0] - 2026-11-02\n`;
+    expect(changelogFormatProblems(pre)).toEqual([
+      "CHANGELOG.md:9: 1.0.0 is below 1.0.0-rc.0; list versions newest first",
+    ]);
+    const ids = `${HEAD}## [Unreleased]\n\n## [1.0.0-beta.0] - 2026-11-01\n\n## [1.0.0-rc.0] - 2026-11-02\n`;
+    expect(changelogFormatProblems(ids)).toEqual([
+      "CHANGELOG.md:9: 1.0.0-rc.0 is below 1.0.0-beta.0; list versions newest first",
+    ]);
+  });
+
+  it("names a version listed twice", () => {
+    const text = `${HEAD}## [Unreleased]\n\n## [0.2.0] - 2026-11-01\n\n## [0.2.0] - 2026-11-01\n`;
+    expect(changelogFormatProblems(text)).toEqual(["CHANGELOG.md:9: 0.2.0 is listed twice; merge the sections"]);
+  });
+
+  it("asks for a version heading where a section has another name", () => {
+    expect(changelogFormatProblems(`${HEAD}## [Unreleased]\n\n## Notes\n`)).toEqual([
+      'CHANGELOG.md:7: "## Notes" is not a version; write ## [x.y.z] - YYYY-MM-DD',
+    ]);
+  });
+
+  it("does not read headings inside a code fence", () => {
+    const text = `${HEAD}## [Unreleased]\n\n\`\`\`md\n### Improved\n## [9.9.9]\n\`\`\`\n`;
+    expect(changelogFormatProblems(text)).toEqual([]);
+  });
+});
+
+describe("hasUnreleased", () => {
+  it("is true when Unreleased holds any text under a heading", () => {
+    expect(hasUnreleased(`${HEAD}## [Unreleased]\n\n### Added\n\n- x\n\n## [0.1.0] - 2026-10-01\n`)).toBe(true);
+  });
+
+  it("is false for an empty Unreleased, a heading with no entries and a missing section", () => {
+    expect(hasUnreleased(`${HEAD}## [Unreleased]\n\n## [0.1.0] - 2026-10-01\n\n- old\n`)).toBe(false);
+    expect(hasUnreleased(`${HEAD}## [Unreleased]\n\n### Added\n\n`)).toBe(false);
+    expect(hasUnreleased(HEAD)).toBe(false);
+  });
+});
+
+const unreleased = "## [Unreleased]\n\n### Added\n\n- a\n\n### Fixed\n\n- f\n\n";
+
+describe("stampChangelog", () => {
+  it("moves the Unreleased entries under the new version, leaving an empty Unreleased", () => {
+    const text = `${HEAD}${unreleased}## [0.1.0] - 2026-10-01\n\n### Added\n\n- old\n`;
+    expect(stampChangelog(text, "0.1.1", "2026-11-09")).toBe(
+      `${HEAD}## [Unreleased]\n\n## [0.1.1] - 2026-11-09\n\n### Added\n\n- a\n\n### Fixed\n\n- f\n\n## [0.1.0] - 2026-10-01\n\n### Added\n\n- old\n`,
+    );
+  });
+
+  it("works on a changelog with no older version", () => {
+    expect(stampChangelog(`${HEAD}${unreleased}`, "0.1.0", "2026-11-09")).toBe(
+      `${HEAD}## [Unreleased]\n\n## [0.1.0] - 2026-11-09\n\n### Added\n\n- a\n\n### Fixed\n\n- f\n`,
+    );
+  });
+
+  it("folds Unreleased into an existing section by heading, in Keep a Changelog order", () => {
+    const text = `${HEAD}## [Unreleased]\n\n### Security\n\n- s\n\n### Added\n\n- new\n\n## [0.1.1] - 2026-11-08\n\n### Fixed\n\n- f\n\n### Added\n\n- old\n\n## [0.1.0] - 2026-10-01\n`;
+    expect(stampChangelog(text, "0.1.1", "2026-11-09")).toBe(
+      `${HEAD}## [Unreleased]\n\n## [0.1.1] - 2026-11-08\n\n### Added\n\n- new\n- old\n\n### Fixed\n\n- f\n\n### Security\n\n- s\n\n## [0.1.0] - 2026-10-01\n`,
+    );
+  });
+});
+
+describe("stampChangelog edge cases", () => {
+  it("changes nothing in the section when Unreleased is empty", () => {
+    const text = `${HEAD}## [Unreleased]\n\n## [0.1.1] - 2026-11-08\n\n### Added\n\n- old\n`;
+    expect(stampChangelog(text, "0.1.1", "2026-11-09")).toBe(text);
+  });
+
+  it("folds the prerelease sections of the same base into the release", () => {
+    const text = `${HEAD}## [Unreleased]\n\n### Fixed\n\n- last\n\n## [1.1.0-rc.1] - 2026-11-02\n\n### Fixed\n\n- two\n\n## [1.1.0-rc.0] - 2026-11-01\n\n### Added\n\n- one\n\n## [1.0.0] - 2026-10-01\n\n### Added\n\n- base\n`;
+    expect(stampChangelog(text, "1.1.0", "2026-11-09")).toBe(
+      `${HEAD}## [Unreleased]\n\n## [1.1.0] - 2026-11-09\n\n### Added\n\n- one\n\n### Fixed\n\n- last\n- two\n\n## [1.0.0] - 2026-10-01\n\n### Added\n\n- base\n`,
+    );
+  });
+
+  it("keeps text outside any ### heading and an unknown heading after the known ones", () => {
+    const text = `${HEAD}## [Unreleased]\n\nLoose note.\n\n### Extras\n\n- e\n\n### Added\n\n- a\n`;
+    expect(stampChangelog(text, "0.1.0", "2026-11-09")).toBe(
+      `${HEAD}## [Unreleased]\n\n## [0.1.0] - 2026-11-09\n\nLoose note.\n\n### Added\n\n- a\n\n### Extras\n\n- e\n`,
+    );
+  });
+
+  it("keeps a section that names no version where it was", () => {
+    const text = `${HEAD}## [Unreleased]\n\n### Added\n\n- a\n\n## Notes\n\nSee below.\n`;
+    expect(stampChangelog(text, "0.1.0", "2026-11-09")).toBe(
+      `${HEAD}## [Unreleased]\n\n## [0.1.0] - 2026-11-09\n\n### Added\n\n- a\n\n## Notes\n\nSee below.\n`,
+    );
+  });
+
+  it("adds Unreleased when the file has none", () => {
+    expect(stampChangelog(HEAD, "0.1.0", "2026-11-09")).toBe(`${HEAD}## [Unreleased]\n\n## [0.1.0] - 2026-11-09\n`);
+  });
+});

package/cli/release/changelog.ts

@@ -0,0 +1,106 @@
+import {
+  compareVersions,
+  groupsOf,
+  headings,
+  linesOf,
+  parseChangelog,
+  trimBlank,
+  unreleasedHasText,
+  type Parsed,
+  type Section,
+} from "./changelog-parse.ts";
+import {
+  CHANGELOG_FILE,
+  DATE_FORMAT,
+  DATED,
+  SECTION_LIST,
+  SECTIONS,
+  UNRELEASED,
+  VERSION_HEADING,
+} from "./release.constants.ts";
+import { parseSemver, type Parts } from "./version.ts";
+
+/** Whether the file's Unreleased section holds any entry. */
+export function hasUnreleased(text: string): boolean {
+  return unreleasedHasText(parseChangelog(text));
+}
+
+/** The versions listed so far, and the one listed last. */
+type Listed = { seen: Set<string>; previous: { version: string; parts: Parts } | null };
+
+/** The problem with one `##` heading, given the versions listed above it. */
+function versionProblem(text: string, line: number, state: Listed): string | null {
+  const where = `${CHANGELOG_FILE}:${line}`;
+  const version = VERSION_HEADING.exec(text)?.[1] ?? "";
+  if (version === UNRELEASED) return null;
+  const parts = parseSemver(version);
+  if (parts === null) return `${where}: "## ${text}" is not a version; write ## [x.y.z] - ${DATE_FORMAT}`;
+  if (!DATED.test(text)) return `${where}: "## ${text}" needs a date; write ## [${version}] - ${DATE_FORMAT}`;
+  const { seen, previous } = state;
+  const twice = seen.has(version);
+  const newer = previous !== null && compareVersions(parts, previous.parts) > 0 ? previous.version : null;
+  seen.add(version);
+  state.previous = { version, parts };
+  if (twice) return `${where}: ${version} is listed twice; merge the sections`;
+  return newer === null ? null : `${where}: ${version} is below ${newer}; list versions newest first`;
+}
+
+/** One line per way the changelog text strays from Keep a Changelog; the single line "is missing" for no file. */
+export function changelogFormatProblems(text: string | null): string[] {
+  if (text === null) return [`${CHANGELOG_FILE} is missing; add one in the Keep a Changelog format`];
+  const state: Listed = { seen: new Set(), previous: null };
+  const problems: string[] = [];
+  for (const { at, kind, text: heading } of headings(linesOf(text))) {
+    if (kind === "section" && !SECTIONS.includes(heading)) {
+      problems.push(`${CHANGELOG_FILE}:${at + 1}: "### ${heading}" is not a section; use ${SECTION_LIST}`);
+    }
+    const problem = kind === "version" ? versionProblem(heading, at + 1, state) : null;
+    if (problem !== null) problems.push(problem);
+  }
+  if (!parseChangelog(text).sections.some(({ version }) => version === UNRELEASED)) {
+    problems.push(`${CHANGELOG_FILE} has no ## [${UNRELEASED}] section; add it above the newest version`);
+  }
+  return problems;
+}
+
+/** The `###` groups of `bodies` merged by name: loose text, then the Keep a Changelog sections, then other names. */
+function mergeBodies(bodies: readonly (readonly string[])[]): string {
+  const merged = new Map<string, string[]>();
+  for (const body of bodies) {
+    for (const [name, lines] of groupsOf(body)) {
+      if (lines.length > 0) merged.set(name, [...(merged.get(name) ?? []), ...lines]);
+    }
+  }
+  const known = ["", ...SECTIONS];
+  const rank = (name: string): number => (known.includes(name) ? known.indexOf(name) : known.length);
+  return [...merged]
+    .sort(([a], [b]) => rank(a) - rank(b))
+    .map(([name, lines]) => (name === "" ? "" : `### ${name}\n\n`) + lines.join("\n"))
+    .join("\n\n");
+}
+
+/** Whether `section` is a prerelease of the stable `version`. */
+const prereleaseOf = (section: Section, version: string): boolean =>
+  !version.includes("-") && section.version !== null && section.version.startsWith(`${version}-`);
+
+/** Text of one section as a block: the heading, a blank line, the body. */
+const block = (heading: string, body: readonly string[]): string =>
+  [heading, ...(trimBlank(body).length > 0 ? ["", ...trimBlank(body)] : [])].join("\n");
+
+/**
+ * The changelog with its Unreleased entries moved under `## [version] - date` and an empty Unreleased above it. A
+ * section for the version already there takes the entries by `###` heading, and for a stable version the sections of
+ * its prereleases fold in and go.
+ */
+export function stampChangelog(text: string, version: string, date: string): string {
+  const { preamble, sections }: Parsed = parseChangelog(text);
+  const unreleased = sections.find((section) => section.version === UNRELEASED);
+  const existing = sections.find((section) => section.version === version);
+  const folded = sections.filter((section) => prereleaseOf(section, version));
+  const taken = new Set<Section | undefined>([unreleased, existing, ...folded]);
+  const bodies = [unreleased, existing, ...folded].filter((section) => section !== undefined).map((s) => s.body);
+  const stamped = block(existing?.heading ?? `## [${version}] - ${date}`, mergeBodies(bodies).split("\n"));
+  const rest = sections.filter((section) => !taken.has(section)).map(({ heading, body }) => block(heading, body));
+  const head = trimBlank(preamble).join("\n");
+  return `${[head, `## [${UNRELEASED}]`, stamped, ...rest].filter((part) => part !== "").join("\n\n")}\n`;
+}

package/cli/release/gate-refusals.test.ts

@@ -0,0 +1,85 @@
+import { afterEach, describe, expect, it } from "vitest";
+import { ghFor, refused, runGate, tagRelease } from "../fixtures/gate-world.ts";
+import { removePlanted } from "../fixtures/planted-repo.ts";
+import { commit, gitIn, NAME, world } from "../fixtures/release-world.ts";
+
+afterEach(removePlanted);
+
+describe("repo release gate refuses a tag that disagrees with its commit", () => {
+  it("whose version differs from package.json at its commit", async () => {
+    const w = world({}, false);
+    const short = tagRelease(w, { version: "0.1.5", tagVersion: "0.2.0" });
+    expect(await runGate(w, [`${NAME}@0.2.0`])).toEqual(
+      refused(
+        `the tag says 0.2.0 but package.json at ${short} says 0.1.5; a tag is never moved, so release the next version`,
+      ),
+    );
+  });
+
+  it("whose package name differs from package.json at its commit", async () => {
+    const w = world({}, false);
+    const short = tagRelease(w, { version: "0.2.0" });
+    gitIn(w.work, "tag", "-a", "@other/app@0.2.0", "-m", "t");
+    expect(await runGate(w, ["@other/app@0.2.0"])).toEqual(
+      refused(`the tag names @other/app but package.json at ${short} names ${NAME}`),
+    );
+  });
+});
+
+describe("repo release gate refuses a tag whose commit lacks what a release needs", () => {
+  it("a version with no changelog section", async () => {
+    const w = world({}, false);
+    const short = tagRelease(w, { version: "0.2.0", changelog: false });
+    expect(await runGate(w, [`${NAME}@0.2.0`])).toEqual(
+      refused(`CHANGELOG.md at ${short} has no ## [0.2.0] section; publish is refused without one`),
+    );
+  });
+
+  it("a package.json that is not a manifest", async () => {
+    const w = world({}, false);
+    commit(w, "chore: release", { "package.json": "{}\n" });
+    gitIn(w.work, "tag", "-a", `${NAME}@0.2.0`, "-m", "t");
+    const short = gitIn(w.work, "rev-parse", "--short=7", "HEAD");
+    expect(await runGate(w, [`${NAME}@0.2.0`])).toEqual(refused(`package.json at ${short} needs a name and a version`));
+  });
+});
+
+describe("repo release gate refuses a commit that is not on the default branch", () => {
+  it("when gh names another branch", async () => {
+    const w = world({}, false);
+    const short = tagRelease(w, { version: "0.2.0" });
+    expect(await runGate(w, [`${NAME}@0.2.0`], ghFor("trunk"))).toEqual(
+      refused(`${short} is not on trunk; tag a commit on trunk after its CI passed`),
+    );
+  });
+
+  it("when it was never pushed", async () => {
+    const w = world({}, false);
+    const short = tagRelease(w, { version: "0.2.0", push: false });
+    expect(await runGate(w, [`${NAME}@0.2.0`])).toEqual(
+      refused(`${short} is not on main; tag a commit on main after its CI passed`),
+    );
+  });
+
+  it("when gh cannot name the default branch", async () => {
+    const w = world({}, false);
+    tagRelease(w, { version: "0.2.0" });
+    expect(await runGate(w, [`${NAME}@0.2.0`], ghFor(null))).toEqual(
+      refused("gh could not read the default branch (not found); check gh auth status"),
+    );
+  });
+});
+
+describe("repo release gate refuses its arguments", () => {
+  it("a tag that does not exist", async () => {
+    expect(await runGate(world({}, false), [`${NAME}@0.2.0`])).toEqual(
+      refused(`the tag ${NAME}@0.2.0 does not exist here; fetch the tags`),
+    );
+  });
+
+  it("a missing or malformed tag with the tag format", async () => {
+    const line = "name the tag as <name>@<version>, e.g. @workerstack/repo@1.0.0";
+    expect(await runGate(world(), [])).toEqual(refused(line));
+    expect(await runGate(world(), ["x", "y"])).toEqual(refused(line));
+  });
+});