@workerstack/repo 0.0.0-stage → 0.1.0

package/cli/check-tsconfig.ts

@@ -0,0 +1,205 @@
+import { execFileSync } from "node:child_process";
+import fs from "node:fs";
+import path from "node:path";
+import ts from "typescript";
+import { canonicalPath } from "./scripts/workspace-root.ts";
+import { RESET, RUNTIME_CONFIG, SRC_CONFIG } from "./tsconfig.constants.ts";
+
+const TSCONFIG_NAME = /^tsconfig(\..+)?\.json$/;
+const PACKAGE_FILE = "package.json";
+/** `-p x`, `--project x` and `--project=x` in a script; the value is the first capture. */
+const PROJECT_FLAG = /(?:^|\s)(?:-p|--project)(?:=|\s+)(\S+)/g;
+const QUOTES = /^["']|["']$/g;
+const REJECT_FILE = /\.reject\.tsx?$/;
+/** The configs that type-check a package's code, which a reject file must stay out of. */
+const CHECKING_CONFIGS: readonly string[] = [RUNTIME_CONFIG, SRC_CONFIG];
+/** The flags `tsconfig/strict.json` turns on, which a `tsconfig.src.json` must resolve with. */
+const STRICT_FLAGS = [
+  "isolatedDeclarations",
+  "erasableSyntaxOnly",
+  "verbatimModuleSyntax",
+  "exactOptionalPropertyTypes",
+  "noUncheckedIndexedAccess",
+] as const;
+
+/** Tracked and untracked, non-ignored tsconfigs under `cwd`, posix and relative to it; none outside a git repo. */
+function listTsconfigs(cwd: string): string[] {
+  let out: string;
+  try {
+    out = execFileSync("git", ["ls-files", "-z", "-co", "--exclude-standard"], {
+      cwd,
+      encoding: "utf8",
+      stdio: ["ignore", "pipe", "ignore"],
+    });
+  } catch {
+    return [];
+  }
+  // An unmerged path is listed once per stage, and a deleted tracked one stays in the index.
+  const rels = new Set(out.split("\0").filter((rel) => TSCONFIG_NAME.test(path.posix.basename(rel))));
+  return [...rels].filter((rel) => fs.existsSync(path.join(cwd, rel)));
+}
+
+/** The line check prints, and turn repeats, for a folder whose `tsconfig.json` has no strict sibling; `.` is the root. */
+export function missingSrcConfig(dir: string): string {
+  return `tsconfig: ${dir} has no ${SRC_CONFIG}; add one with "extends": ["./tsconfig.json", "@workerstack/repo/tsconfig/strict"] and an "exclude" that repeats tsconfig.json's and adds the tests`;
+}
+
+/** A tsconfig parsed, with what its own text sets, or the line naming why it cannot be read. */
+type Read =
+  | {
+      ok: true;
+      setsFiles: boolean;
+      solution: boolean;
+      parsed: ts.ParsedCommandLine;
+    }
+  | { ok: false; line: string };
+
+/** typescript keys its source files by forward-slash paths and asserts that spelling on win32. */
+function tsPath(cwd: string, rel: string): string {
+  return path.join(cwd, rel).split(path.sep).join("/");
+}
+
+function readTsconfig(cwd: string, rel: string): Read {
+  const file = tsPath(cwd, rel);
+  const read = ts.readConfigFile(file, ts.sys.readFile);
+  if (read.error) {
+    return {
+      ok: false,
+      line: `tsconfig: ${rel}: ${ts.flattenDiagnosticMessageText(read.error.messageText, " ")}`,
+    };
+  }
+  // Without a read error, typescript has parsed the root as a JSON object.
+  const raw: { files?: unknown; references?: unknown } = read.config;
+  // Read before parsing, which writes the inherited "files" into the raw object.
+  const setsFiles = raw.files !== undefined;
+  const solution = Array.isArray(raw.files) && raw.files.length === 0 && raw.references !== undefined;
+  const parsed = ts.parseJsonConfigFileContent(read.config, ts.sys, path.dirname(file), undefined, file);
+  return { ok: true, setsFiles, solution, parsed };
+}
+
+function resetProblem(rel: string, read: Read & { ok: true }, reset: string): string | undefined {
+  if (read.setsFiles) {
+    return `tsconfig: ${rel} sets "files", which replaces the base's reset.d.ts. List sources under "include".`;
+  }
+  const names = read.parsed.fileNames;
+  const keepsReset = names.some((name) => path.basename(name) === RESET && canonicalPath(name) === reset);
+  if (keepsReset) return undefined;
+  return `tsconfig: ${rel} does not extend a base. Extend "@workerstack/repo/tsconfig/base", "bun", "worker" or "web".`;
+}
+
+/** A `tsconfig.src.json` that resolves with any strict flag off. */
+function weakProblem(rel: string, options: ts.CompilerOptions): string | undefined {
+  const off = STRICT_FLAGS.filter((flag) => options[flag] !== true);
+  if (off.length === 0) return undefined;
+  return `tsconfig: ${rel} resolves without ${off.join(", ")}; extend "@workerstack/repo/tsconfig/strict" and drop the override`;
+}
+
+/** One line per reject file a checking config includes, which would fail its type check on purpose. */
+function rejectProblems(cwd: string, rel: string, fileNames: readonly string[]): string[] {
+  if (!CHECKING_CONFIGS.includes(path.posix.basename(rel))) return [];
+  const included = fileNames.filter((name) => REJECT_FILE.test(name));
+  return included.map((name) => {
+    const file = path.relative(cwd, name).split(path.sep).join("/");
+    return `tsconfig: ${rel} includes ${file}; add "**/*.reject.ts" and "**/*.reject.tsx" to its exclude`;
+  });
+}
+
+/** What a check of the tsconfigs under `cwd` reads: every listed one, and the canonical path of the base reset.d.ts. */
+type Scan = { cwd: string; listed: ReadonlySet<string>; reset: string };
+
+function problems({ cwd, listed, reset }: Scan, rel: string): string[] {
+  const read = readTsconfig(cwd, rel);
+  if (!read.ok) return [read.line];
+  if (read.solution) return [];
+  const name = path.posix.basename(rel);
+  const dir = path.posix.dirname(rel);
+  const lines = [resetProblem(rel, read, reset)];
+  if (name === SRC_CONFIG) lines.push(weakProblem(rel, read.parsed.options));
+  if (name === RUNTIME_CONFIG && !listed.has(path.posix.join(dir, SRC_CONFIG))) lines.push(missingSrcConfig(dir));
+  return [...lines.filter((line) => line !== undefined), ...rejectProblems(cwd, rel, read.parsed.fileNames)];
+}
+
+function isObject(value: unknown): value is { path?: unknown } {
+  return value instanceof Object;
+}
+
+/** The raw JSON object at `cwd`/`rel`, empty when it is missing or unreadable. */
+function readRaw(cwd: string, rel: string): { scripts?: unknown; extends?: unknown; references?: unknown } {
+  const read = ts.readConfigFile(tsPath(cwd, rel), ts.sys.readFile);
+  return read.error ? {} : read.config;
+}
+
+/** The config a `-p` value or a reference `path` names from `dir`: the file, or a folder's `tsconfig.json`. */
+function projectFile(dir: string, spec: string): string {
+  const target = path.posix.join(dir, spec.replace(QUOTES, ""));
+  return target.endsWith(".json") ? target : path.posix.join(target, RUNTIME_CONFIG);
+}
+
+/** Every config the scripts of `dir`'s package.json run with `-p` or `--project`, relative to `cwd`. */
+function scriptTargets(cwd: string, dir: string): string[] {
+  const scripts = readRaw(cwd, path.posix.join(dir, PACKAGE_FILE)).scripts;
+  const commands = typeof scripts === "object" && scripts !== null ? Object.values(scripts) : [];
+  const flags = commands
+    .filter((command) => typeof command === "string")
+    .flatMap((command) => [...command.matchAll(PROJECT_FLAG)]);
+  return flags.flatMap((flag) => flag.slice(1).map((spec) => projectFile(dir, spec)));
+}
+
+/** The folders from `rel`'s own up to `cwd` that hold a package.json. */
+function packageDirs(cwd: string, rel: string): string[] {
+  const dirs: string[] = [];
+  for (let dir = path.posix.dirname(rel); ; dir = path.posix.dirname(dir)) {
+    if (fs.existsSync(path.join(cwd, dir, PACKAGE_FILE))) dirs.push(dir);
+    if (dir === ".") return dirs;
+  }
+}
+
+/** The local configs `rel` extends and references; an extends of a package is outside the repo's own files. */
+function linkedConfigs(cwd: string, rel: string): string[] {
+  const raw = readRaw(cwd, rel);
+  const dir = path.posix.dirname(rel);
+  const parents = [raw.extends]
+    .flat()
+    .flatMap((spec) => (typeof spec === "string" && spec.startsWith(".") ? [spec] : []));
+  const refs = Array.isArray(raw.references) ? raw.references : [];
+  const extended = parents.map((spec) => path.posix.join(dir, spec.endsWith(".json") ? spec : `${spec}.json`));
+  const referenced = refs.flatMap((ref) =>
+    isObject(ref) && typeof ref.path === "string" ? [projectFile(dir, ref.path)] : [],
+  );
+  return [...extended, ...referenced];
+}
+
+/** The configs a gate runs: the two by name, those a script names, and all they extend or reference. */
+function runConfigs(cwd: string, rels: readonly string[]): Set<string> {
+  const named = rels.filter((rel) => CHECKING_CONFIGS.includes(path.posix.basename(rel)));
+  const scripted = [...new Set(rels.flatMap((rel) => packageDirs(cwd, rel)))].flatMap((dir) => scriptTargets(cwd, dir));
+  const queue = [...named, ...scripted];
+  const seen = new Set<string>();
+  for (const rel of queue) {
+    if (seen.has(rel)) continue;
+    seen.add(rel);
+    queue.push(...linkedConfigs(cwd, rel));
+  }
+  return seen;
+}
+
+function unrunProblem(rel: string, run: ReadonlySet<string>): string[] {
+  if (run.has(rel)) return [];
+  return [`tsconfig: ${rel} is run by no gate; delete it, or run it from a package.json script with tsc -p ${rel}`];
+}
+
+/**
+ * One stderr line per tsconfig under `cwd` that drops ts-reset (it sets `files`, extends no base from `pkgRoot`, or
+ * cannot be read), per `tsconfig.json` with no `tsconfig.src.json` beside it, and per `tsconfig.src.json` that
+ * resolves with a strict flag off, and per reject file a `tsconfig.json` or `tsconfig.src.json` includes. A
+ * solution-style `{"files": [], "references": [...]}` checks no code and passes. A tsconfig no gate runs gets a line
+ * too: run means named `tsconfig.json` or `tsconfig.src.json`, named by `-p` or `--project` in a script of a
+ * package.json above it, or extended or referenced, transitively, by a run config.
+ */
+export function checkTsconfigs(cwd: string, pkgRoot: string): string[] {
+  const reset = canonicalPath(path.join(pkgRoot, "tsconfig", RESET));
+  const rels = listTsconfigs(cwd);
+  const scan: Scan = { cwd, listed: new Set(rels), reset };
+  const run = runConfigs(cwd, rels);
+  return rels.flatMap((rel) => [...problems(scan, rel), ...unrunProblem(rel, run)]);
+}

package/cli/commands.test.ts

@@ -0,0 +1,114 @@
+import { execFileSync } from "node:child_process";
+import { describe, expect, it, vi } from "vitest";
+import { HOOK_NAMES } from "./scripts/hook-command.ts";
+import { COMMANDS, HOOKS, dispatch, isCommandName, runCommand, type Registry } from "./commands.ts";
+
+describe("registry", () => {
+  it.each(Object.keys(COMMANDS))("command %s loads a main", async (name) => {
+    const entry = COMMANDS[name as keyof typeof COMMANDS];
+    expect(typeof (await entry.load()).main).toBe("function");
+  });
+
+  it.each(HOOK_NAMES)("hook %s loads a main", async (name) => {
+    expect(typeof (await HOOKS[name].load()).main).toBe("function");
+  });
+
+  it("names commands, and nothing else", () => {
+    expect(isCommandName("job")).toBe(true);
+    expect(isCommandName("toString")).toBe(false);
+    expect(isCommandName(undefined)).toBe(false);
+  });
+});
+
+describe("coverage", () => {
+  it("is a command, with the help line Usage shows", () => {
+    expect(isCommandName("coverage")).toBe(true);
+    expect(COMMANDS.coverage.summary).toBe("run the suite with coverage and raise coverage-floors.json; a drop fails");
+  });
+});
+
+describe("mutate", () => {
+  it("is a command, with a help line that names its shards and floors", () => {
+    expect(isCommandName("mutate")).toBe(true);
+    expect(COMMANDS.mutate.summary).toBe(
+      "mutation-test the tracked files in a clone of HEAD (--shard i/n, --report <file>); check <dir> [--write]: score reports against mutation-floors.json",
+    );
+  });
+});
+
+describe("bun repo", () => {
+  it("has no tracked file but the bin that bun would run in its place", () => {
+    const files = execFileSync("git", ["ls-files"], { encoding: "utf8" }).split("\n");
+    expect(files.filter((f) => /(?:^|\/)repo\.(?:[cm]?js|jsx|tsx?)$/.test(f))).toEqual(["bin/repo.ts"]);
+  });
+});
+
+describe("dispatch", () => {
+  const registry = (main: (argv: string[]) => Promise<number>): Registry => {
+    const stub = <T extends Record<string, object>>(table: T) =>
+      Object.fromEntries(Object.entries(table).map(([k, v]) => [k, { ...v, load: async () => ({ main }) }])) as T;
+    return { commands: stub(COMMANDS), hooks: stub(HOOKS) };
+  };
+
+  it.each([
+    ["yolo", ["--dry-run", "--host", "grok"]],
+    ["purge-mcps", ["--apply"]],
+    ["doctor", []],
+    ["setup", ["speak", "--skip-verify"]],
+    ["job", ["--job", "exec", "--query", "echo hi", "-y"]],
+    ["worktree", ["add", "x"]],
+  ])("%s runs in-process with its argv untouched", async (cmd, args) => {
+    const main = vi.fn(async () => 3);
+    expect(await dispatch([cmd, ...args], registry(main))).toBe(3);
+    expect(main).toHaveBeenCalledWith(args);
+  });
+
+  it("hook <name> runs the hook with its fixed argv first", async () => {
+    const main = vi.fn(async () => 0);
+    expect(await dispatch(["hook", "worktree"], registry(main))).toBe(0);
+    expect(main).toHaveBeenCalledWith(["hook"]);
+    expect(await dispatch(["hook", "gate-fat-tools", "x"], registry(main))).toBe(0);
+    expect(main).toHaveBeenLastCalledWith(["x"]);
+  });
+
+  it.each([
+    [
+      [],
+      "repo hook: name a hook; use gate-fat-tools, orchestrate-parent, rtk-grok, scrub-spawn-prompt, session-map or worktree\n",
+    ],
+    [
+      ["nope"],
+      'repo hook: unknown hook "nope"; use gate-fat-tools, orchestrate-parent, rtk-grok, scrub-spawn-prompt, session-map or worktree\n',
+    ],
+  ])("hook %j prints the hook list and exits 1", async (args, message) => {
+    const main = vi.fn(async () => 0);
+    const err = vi.spyOn(process.stderr, "write").mockImplementation(() => true);
+    try {
+      expect(await dispatch(["hook", ...args], registry(main))).toBe(1);
+      expect(err.mock.calls.map((c) => String(c[0])).join("")).toBe(message);
+    } finally {
+      err.mockRestore();
+    }
+    expect(main).not.toHaveBeenCalled();
+  });
+
+  it("leaves every other command to cli/main.ts", async () => {
+    const main = vi.fn(async () => 0);
+    for (const argv of [[], ["init"], ["map", "cli"], ["help"], ["toString"]])
+      expect(await dispatch(argv, registry(main)), argv.join(" ")).toBeNull();
+    expect(main).not.toHaveBeenCalled();
+  });
+
+  it("with no registry given, still leaves a non-command to cli/main.ts", async () => {
+    expect(await dispatch(["init"])).toBeNull();
+  });
+
+  it("runCommand runs the real registry entry by default", async () => {
+    const err = vi.spyOn(process.stderr, "write").mockImplementation(() => true);
+    try {
+      expect(await runCommand("lessons", [])).toBe(1);
+    } finally {
+      err.mockRestore();
+    }
+  });
+});

package/cli/commands.ts

@@ -0,0 +1,218 @@
+/** Every script an agent, a hook or a person runs, behind `repo <cmd>` and `repo hook <name>`. */
+import { HOOK_USAGE, isHookName, type HookName } from "./scripts/hook-command.ts";
+
+export type Main = (argv: string[]) => number | Promise<number>;
+
+export interface Entry {
+  readonly summary: string;
+  readonly load: () => Promise<{ readonly main: Main }>;
+}
+
+export interface HookEntry extends Entry {
+  /** Arguments the hook's `main` gets in front of any the command line adds. */
+  readonly argv: readonly string[];
+}
+
+export type CommandName =
+  | "job"
+  | "worktree"
+  | "persist"
+  | "phase-files"
+  | "lessons"
+  | "browser"
+  | "google-workspace"
+  | "jev"
+  | "listen"
+  | "speak"
+  | "setup"
+  | "doctor"
+  | "clean"
+  | "yolo"
+  | "purge-mcps"
+  | "tasks"
+  | "lint"
+  | "fmt"
+  | "turn"
+  | "ci"
+  | "coverage"
+  | "mutate"
+  | "release"
+  | "commit-msg";
+
+export const COMMANDS: Readonly<Record<CommandName, Entry>> = {
+  job: {
+    summary: "Compressed search, exec, slice, fetch and test dumps (--job search|exec|slice|fetch|test)",
+    load: () => import("./scripts/job.ts"),
+  },
+  worktree: {
+    summary: "Managed worktrees: add, list, finish, remove",
+    load: () => import("./scripts/worktree.ts"),
+  },
+  persist: {
+    summary: "Save a plan, roadmap, handoff, implementation or tmp body from stdin (persist <kind> [--workspace dir])",
+    load: () => import("./scripts/persist.ts"),
+  },
+  "phase-files": {
+    summary: "Map a parallel group's unstaged changes to its phases",
+    load: () => import("./scripts/phase-files.ts"),
+  },
+  lessons: {
+    summary: "Match, hit and list lessons",
+    load: () => import("./scripts/lessons.ts"),
+  },
+  browser: {
+    summary: "Browse with Lightpanda, Chromium when blocked",
+    load: () => import("./scripts/browser.ts"),
+  },
+  "google-workspace": {
+    summary: "Google Sheets, Docs, Slides, Calendar and Gmail",
+    load: () => import("./scripts/google-workspace.ts"),
+  },
+  jev: {
+    summary: "Yes/no or named-option decision on saved text",
+    load: () => import("./scripts/jev.ts"),
+  },
+  listen: {
+    summary: "Speech-to-text from the mic",
+    load: () => import("./scripts/listen.ts"),
+  },
+  speak: {
+    summary: "Text-to-speech",
+    load: () => import("./scripts/speak.ts"),
+  },
+  setup: {
+    summary: "Handheld keys and OAuth (speak, listen, google-workspace, browser, jev)",
+    load: () => import("./scripts/setup.ts"),
+  },
+  doctor: {
+    summary: "Check the tools and versions this repo needs",
+    load: () => import("./scripts/doctor.ts"),
+  },
+  clean: {
+    summary: "Remove scratch and stale generated files (--dry-run lists only)",
+    load: () => import("./scripts/clean.ts"),
+  },
+  yolo: {
+    summary: "Turn on full-permission mode on every host (--check, --dry-run, --host <id>)",
+    load: () => import("./scripts/sync-global-settings.ts"),
+  },
+  "purge-mcps": {
+    summary: "Purge global MCP servers (dry-run; --apply to write)",
+    load: () => import("./scripts/purge-global-mcps.ts"),
+  },
+  tasks: {
+    summary: "Write .vscode/tasks.json from package scripts (VS Code and Cursor)",
+    load: () => import("./scripts/vscode-tasks.ts"),
+  },
+  lint: {
+    summary:
+      "Lint with the standards pack's oxlint config (args go to oxlint; --baseline: lower .repo/lint-baseline.json)",
+    load: () => import("./scripts/lint-main.ts").then(({ lintMain }) => ({ main: lintMain })),
+  },
+  fmt: {
+    summary: "Format with the standards pack's oxfmt config (--check: report only; args go to oxfmt)",
+    load: () => import("./scripts/lint.ts").then(({ fmt }) => ({ main: fmt })),
+  },
+  turn: {
+    summary: "Gate the changed files: fmt, lint, typecheck, related tests, sync, check (--staged: the index)",
+    load: () => import("./scripts/turn.ts"),
+  },
+  ci: {
+    summary: "Run every gate (--report: skipped tests); skips <dir>: tests skipped on every OS; wait: the run for HEAD",
+    load: () => import("./scripts/ci.ts"),
+  },
+  coverage: {
+    summary: "run the suite with coverage and raise coverage-floors.json; a drop fails",
+    load: () => import("./coverage.ts"),
+  },
+  mutate: {
+    summary:
+      "mutation-test the tracked files in a clone of HEAD (--shard i/n, --report <file>); check <dir> [--write]: score reports against mutation-floors.json",
+    load: () => import("./mutate.ts"),
+  },
+  release: {
+    summary:
+      "Release the root package: bump from commits, stamp CHANGELOG.md, commit, push, wait on CI, tag ([--stable | --pre <id>]); wait <name>@<version>: poll npm",
+    load: () => import("./release/main.ts"),
+  },
+  "commit-msg": {
+    summary:
+      "Check a commit message file against the staged change (the commit-msg git hook), or each commit of --range <base>..<head>",
+    load: () => import("./commit-msg.ts"),
+  },
+};
+
+export const HOOKS: Readonly<Record<HookName, HookEntry>> = {
+  "gate-fat-tools": {
+    summary: "Fat-tool gate",
+    argv: [],
+    load: () => import("./scripts/gate-fat-tools.ts"),
+  },
+  "orchestrate-parent": {
+    summary: "Persist, approval and session gate",
+    argv: [],
+    load: () => import("./scripts/orchestrate-parent.ts"),
+  },
+  "rtk-grok": {
+    summary: "rtk rewrite for Grok",
+    argv: [],
+    load: () => import("./scripts/rtk-grok.ts"),
+  },
+  "scrub-spawn-prompt": {
+    summary: "Spawn prompt scrub",
+    argv: [],
+    load: () => import("./scripts/scrub-spawn-prompt.ts"),
+  },
+  "session-map": {
+    summary: "Session-start folder map",
+    argv: [],
+    load: () => import("./scripts/session-map.ts"),
+  },
+  worktree: {
+    summary: "Claude Code worktree create and remove",
+    argv: ["hook"],
+    load: () => import("./scripts/worktree.ts"),
+  },
+};
+
+export function isCommandName(name: string | undefined): name is CommandName {
+  return name !== undefined && Object.hasOwn(COMMANDS, name);
+}
+
+/** The tables `dispatch` runs from; tests pass stubs. */
+export interface Registry {
+  readonly commands: Readonly<Record<CommandName, Entry>>;
+  readonly hooks: Readonly<Record<HookName, HookEntry>>;
+}
+
+const REGISTRY: Registry = { commands: COMMANDS, hooks: HOOKS };
+
+export async function runCommand(
+  name: CommandName,
+  args: string[],
+  { commands }: Registry = REGISTRY,
+): Promise<number> {
+  const { main } = await commands[name].load();
+  return await main(args);
+}
+
+/**
+ * Runs `repo hook <name>` or a registry command in-process and returns its exit code, or null when argv names
+ * neither and `cli/main.ts` owns it. Registry commands own their flags, so they get the raw argv. The bin calls this
+ * before it loads `cli/main.ts`, so a hook pays for its own module only.
+ */
+export async function dispatch(argv: readonly string[], registry: Registry = REGISTRY): Promise<number | null> {
+  const [head, ...rest] = argv;
+  if (head === "hook") {
+    const [name, ...args] = rest;
+    if (!isHookName(name)) {
+      const named = name === undefined ? "name a hook" : `unknown hook "${name}"`;
+      process.stderr.write(`repo hook: ${named}; ${HOOK_USAGE}\n`);
+      return 1;
+    }
+    const hook = registry.hooks[name];
+    const { main } = await hook.load();
+    return await main([...hook.argv, ...args]);
+  }
+  return isCommandName(head) ? await runCommand(head, rest, registry) : null;
+}

package/cli/commit-changelog.ts

@@ -0,0 +1,27 @@
+import type { Owner } from "./tdd-scope.ts";
+
+const CHANGELOG = "CHANGELOG.md";
+/** Commit types that change what a user of a package sees. */
+const USER_FACING: readonly string[] = ["feat", "fix", "perf"];
+
+/** What a message says about itself, as far as the changelog rule reads it. */
+export type Kind = { type: string; breaking: boolean };
+
+/**
+ * The problem when a feat, fix, perf or breaking commit stages a file of a public package but not that package's
+ * CHANGELOG.md; one per package that is missing its entry.
+ */
+export function changelogProblems(kind: Kind, staged: readonly string[], owners: (file: string) => Owner): string[] {
+  if (!kind.breaking && !USER_FACING.includes(kind.type)) return [];
+  const what = kind.breaking ? "a breaking change" : `a ${kind.type}`;
+  const dirs = new Set(
+    staged
+      .map(owners)
+      .filter((owner) => owner.public)
+      .map((owner) => owner.dir),
+  );
+  return [...dirs]
+    .map((dir) => (dir === "." ? CHANGELOG : `${dir}/${CHANGELOG}`))
+    .filter((file) => !staged.includes(file))
+    .map((file) => `${what} changes what users see; add an entry under ## [Unreleased] in ${file} and stage it`);
+}

package/cli/commit-msg-changelog.test.ts

@@ -0,0 +1,93 @@
+import fs from "node:fs";
+import path from "node:path";
+import { afterEach, describe, expect, it } from "vitest";
+import { main } from "./commit-msg.ts";
+import { git, removePlanted, tempDir } from "./fixtures/planted-repo.ts";
+import { plant, stage } from "./fixtures/red-proof-repo.ts";
+
+/** The hook's changelog rule: which commits must stage an entry, and for which package. */
+afterEach(removePlanted);
+
+const PLAIN = { "workerstack.config.ts": "export default {}\n" };
+const SRC = { "src/x.ts": "export const x = 1;\n", "src/x.test.ts": "t\n" };
+const PRIVATE = { ...PLAIN, "package.json": { name: "p", private: true } };
+const MONO = {
+  ...PLAIN,
+  "package.json": { name: "mono", private: true, workspaces: ["packages/*"] },
+  "packages/pub/package.json": { name: "pub" },
+};
+const refusal = (what: string, file = "CHANGELOG.md") =>
+  `commit-msg: the message was refused\n  - ${what} changes what users see; add an entry under ## [Unreleased] in ${file} and stage it\n`;
+
+/** Runs the hook on `message` (or on `range`) with the staged change as is; red-proof passes. */
+async function hook(root: string, message: string, range?: string) {
+  const file = path.join(tempDir(), "message");
+  fs.writeFileSync(file, message);
+  const err: string[] = [];
+  const redProof = () => ({ ok: true as const, line: "red-proof: ok" });
+  const argv = range === undefined ? [file] : ["--range", range];
+  const code = await main(argv, { cwd: root, stderr: (text) => err.push(text), redProof });
+  return { code, stderr: err.join("") };
+}
+
+describe("the commit-msg hook asks for a changelog entry", () => {
+  it.each([
+    ["feat: add x\n", "a feat"],
+    ["fix: handle x\n", "a fix"],
+    ["perf: speed x\n", "a perf"],
+    ["feat(cli)!: drop x\n", "a breaking change"],
+    ["refactor: move x\n\nBREAKING CHANGE: x moved\n", "a breaking change"],
+  ])("for %j in a public package", async (message, what) => {
+    const root = plant(PLAIN);
+    stage(root, SRC);
+    expect(await hook(root, message)).toEqual({ code: 1, stderr: refusal(what) });
+  });
+
+  it("only after the header itself is right", async () => {
+    const root = plant(PLAIN);
+    stage(root, SRC);
+    const got = await hook(root, "added stuff\n");
+    expect(got.stderr).not.toContain("CHANGELOG.md");
+    expect(got.code).toBe(1);
+  });
+
+  it("in the public package that changed, by path", async () => {
+    const root = plant(MONO);
+    stage(root, { "packages/pub/x.ts": "x\n", "packages/pub/x.test.ts": "t\n" });
+    const got = await hook(root, "feat(pub): add x\n");
+    expect(got).toEqual({ code: 1, stderr: refusal("a feat", "packages/pub/CHANGELOG.md") });
+  });
+});
+
+describe("the commit-msg hook lets a commit through", () => {
+  it("once the package's CHANGELOG.md is staged", async () => {
+    const root = plant(MONO);
+    stage(root, { "packages/pub/x.ts": "x\n", "packages/pub/x.test.ts": "t\n", "packages/pub/CHANGELOG.md": "# C\n" });
+    expect(await hook(root, "feat(pub): add x\n")).toEqual({ code: 0, stderr: "red-proof: ok\n" });
+  });
+
+  it.each(["chore: x\n", "docs: x\n", "test: x\n"])("for the type of %j", async (message) => {
+    const root = plant(PLAIN);
+    stage(root, SRC);
+    expect((await hook(root, message)).code).toBe(0);
+  });
+
+  it("for a merge message, which has no type", async () => {
+    const root = plant(PLAIN);
+    stage(root, SRC);
+    expect((await hook(root, "Merge branch 'x'\n")).code).toBe(0);
+  });
+
+  it("for a feat in a private package", async () => {
+    const root = plant(PRIVATE);
+    stage(root, SRC);
+    expect((await hook(root, "feat: add x\n")).code).toBe(0);
+  });
+
+  it("over --range, which CI runs over commits that carry no entry", async () => {
+    const root = plant(PLAIN);
+    stage(root, SRC);
+    git(root, "commit", "-q", "-m", "feat: add x");
+    expect(await hook(root, "", "HEAD~1..HEAD")).toEqual({ code: 0, stderr: "" });
+  });
+});