@workerstack/repo 0.0.0-stage → 0.1.0

package/cli/check-ratchets.ts

@@ -0,0 +1,193 @@
+/**
+ * The ratchets `repo check` holds against main: coverage floors only rise (a rename carries its floor), the
+ * known-failures list only shrinks, a mutation floor never drops, and a lint rule's baseline total never rises for a
+ * rule main already baselines.
+ * Main's copies are read from git; no main ref, or a file absent on main, means nothing to compare.
+ */
+import fs from "node:fs";
+import path from "node:path";
+import { spawnSync } from "node:child_process";
+import {
+  COMMON_BRANCHES,
+  DEFAULT_FLOORS,
+  DEFAULT_MUTATION_FLOORS,
+  DETACHED,
+  NEWLINE,
+  ORIGIN,
+  RENAME,
+  RENAME_COLUMNS,
+  TAB,
+} from "./check-ratchets.constants.ts";
+import { DEFAULT_LIST } from "./known-failures.constants.ts";
+import { childEnv } from "./env.ts";
+import { toolEnv } from "./scripts/lint.ts";
+import { BASELINE_PATH } from "./scripts/lint-baseline.ts";
+import { defaultBranch } from "./scripts/worktree.ts";
+
+/** Where the ratcheted files live, as the config's `coverage` section names them. */
+export type RatchetPaths = { floors?: string; knownFailures?: string; mutationFloors?: string };
+
+type Table = Record<string, Record<string, number>>;
+
+const isRecord = (value: unknown): value is Record<string, unknown> =>
+  typeof value === "object" && value !== null && !Array.isArray(value);
+
+/** git's stdout, or null when it failed; run without any `GIT_*` variable a hook set. */
+function git(root: string, args: string[]): string | null {
+  const run = spawnSync("git", args, { cwd: root, encoding: "utf8", env: toolEnv(childEnv()) });
+  return run.status === 0 ? run.stdout : null;
+}
+
+const hasRef = (root: string, ref: string) =>
+  git(root, ["rev-parse", "--verify", "--quiet", `${ref}^{commit}`]) !== null;
+
+/** The branches a clone without a local main may still have as `origin/<name>`. */
+function originNames(root: string): string[] {
+  const head = git(root, ["symbolic-ref", "--short", `refs/remotes/${ORIGIN}/HEAD`]);
+  return [head?.trim().replace(`${ORIGIN}/`, "") ?? "", ...COMMON_BRANCHES].filter(Boolean);
+}
+
+/**
+ * Main's ref: the local default branch, else `origin/<name>`. The default branch falling back to the current branch
+ * (or HEAD) is no main, since that compares a branch with itself.
+ */
+function mainRef(root: string): string | null {
+  const name = defaultBranch(root);
+  const current = git(root, ["symbolic-ref", "--short", "HEAD"])?.trim();
+  if (name !== DETACHED && name !== current && hasRef(root, name)) return name;
+  const remote = [name, ...originNames(root)].map((n) => `${ORIGIN}/${n}`);
+  return remote.find((ref) => hasRef(root, ref)) ?? null;
+}
+
+function parse(text: string | null): unknown {
+  try {
+    return text === null ? undefined : JSON.parse(text);
+  } catch {
+    return undefined;
+  }
+}
+
+const readMain = (root: string, ref: string, rel: string): unknown => parse(git(root, ["show", `${ref}:${rel}`]));
+const readHere = (root: string, rel: string): unknown => {
+  const file = path.join(root, rel);
+  return parse(fs.existsSync(file) ? fs.readFileSync(file, "utf8") : null);
+};
+
+function asTable(value: unknown): Table | undefined {
+  if (!isRecord(value)) return undefined;
+  const table: Table = {};
+  for (const [key, row] of Object.entries(value)) {
+    if (!isRecord(row)) continue;
+    table[key] = Object.fromEntries(Object.entries(row).filter((e): e is [string, number] => typeof e[1] === "number"));
+  }
+  return table;
+}
+
+const asList = (value: unknown): string[] | undefined =>
+  Array.isArray(value) ? value.filter((item): item is string => typeof item === "string") : undefined;
+
+/** Old path → new path of the renames between main and the working tree. */
+function renames(root: string, ref: string): Map<string, string> {
+  // A failed diff reads as the text "null", which holds no rename.
+  const out = String(git(root, ["diff", "-M", "--name-status", ref]));
+  const pairs = out
+    .split(NEWLINE)
+    .map((line) => line.split(TAB))
+    .filter(
+      (cols): cols is [string, string, string] =>
+        cols.length === RENAME_COLUMNS && cols[0]?.startsWith(RENAME) === true,
+    );
+  return new Map(pairs.map(([, from, to]) => [from, to]));
+}
+
+/** One main file's floors against the checkout's, `rel` being its key on main and `key` its key here. */
+type Row = { rel: string; key: string; file: string };
+
+function fileFloors({ rel, key, file }: Row, was: Record<string, number>, now: Record<string, number>): string[] {
+  const note = key === rel ? "" : ` (renamed from ${rel})`;
+  return Object.entries(was).flatMap(([metric, floor]) => {
+    const has = now[metric];
+    if (has === undefined) return [`${file}: ${key} ${metric} has no floor but main has ${floor}${note}; restore it`];
+    return has < floor ? [`${file}: ${key} ${metric} ${has} is below main's ${floor}${note}; floors only rise`] : [];
+  });
+}
+
+function floorProblems(root: string, ref: string, file: string): string[] {
+  const was = asTable(readMain(root, ref, file));
+  if (was === undefined) return [];
+  const now = asTable(readHere(root, file)) ?? {};
+  const moved = renames(root, ref);
+  return Object.entries(was).flatMap(([rel, metrics]) => {
+    const key = rel in now ? rel : (moved.get(rel) ?? rel);
+    const row = now[key];
+    if (row !== undefined) return fileFloors({ rel, key, file }, metrics, row);
+    return fs.existsSync(path.join(root, key))
+      ? [`${file}: ${key} has no floor but main has one and the file exists; restore it`]
+      : [];
+  });
+}
+
+const asNumbers = (value: unknown): Record<string, number> | undefined =>
+  isRecord(value)
+    ? Object.fromEntries(Object.entries(value).filter((e): e is [string, number] => typeof e[1] === "number"))
+    : undefined;
+
+/** A mutation floor lowered, or dropped while its package dir exists; a package dir that is gone takes its floor. */
+function mutationProblems(root: string, ref: string, file: string): string[] {
+  const was = asNumbers(readMain(root, ref, file));
+  if (was === undefined) return [];
+  const now = asNumbers(readHere(root, file)) ?? {};
+  return Object.entries(was).flatMap(([pkg, floor]) => {
+    const has = now[pkg];
+    if (has === undefined) {
+      return fs.existsSync(path.join(root, pkg)) ? [`${file} drops ${pkg} from ${floor}; floors only rise`] : [];
+    }
+    return has < floor ? [`${file} lowers ${pkg} from ${floor} to ${has} against main; floors only rise`] : [];
+  });
+}
+
+function listProblems(root: string, ref: string, file: string): string[] {
+  const was = asList(readMain(root, ref, file));
+  if (was === undefined) return [];
+  const now = asList(readHere(root, file)) ?? [];
+  return now
+    .filter((entry) => !was.includes(entry))
+    .map((entry) => `${file}: "${entry}" is not on main's list; fix the case instead of listing it`);
+}
+
+/** Per rule, the count summed over every file. */
+function totals(table: Table): Map<string, number> {
+  const sums = new Map<string, number>();
+  for (const row of Object.values(table)) {
+    for (const [rule, count] of Object.entries(row)) sums.set(rule, (sums.get(rule) ?? 0) + count);
+  }
+  return sums;
+}
+
+function baselineProblems(root: string, ref: string): string[] {
+  const was = asTable(readMain(root, ref, BASELINE_PATH));
+  if (was === undefined) return [];
+  const now = totals(asTable(readHere(root, BASELINE_PATH)) ?? {});
+  return [...totals(was)].flatMap(([rule, before]) => {
+    const after = now.get(rule) ?? 0;
+    return after > before
+      ? [`${BASELINE_PATH}: ${rule} totals ${after}, main has ${before}; fix the new hit instead of baselining it`]
+      : [];
+  });
+}
+
+/**
+ * Every way the checkout at `root` loosens a ratchet main holds: a lowered or dropped coverage floor, a known-failure
+ * entry main's list lacks, a lowered mutation floor, a lint rule total above main's. The paths default to
+ * `coverage-floors.json`, `known-failures.json` and `mutation-floors.json`.
+ */
+export function ratchetProblems(root: string, paths: RatchetPaths = {}): string[] {
+  const ref = mainRef(root);
+  if (ref === null) return [];
+  return [
+    ...floorProblems(root, ref, paths.floors ?? DEFAULT_FLOORS),
+    ...listProblems(root, ref, paths.knownFailures ?? DEFAULT_LIST),
+    ...mutationProblems(root, ref, paths.mutationFloors ?? DEFAULT_MUTATION_FLOORS),
+    ...baselineProblems(root, ref),
+  ];
+}

package/cli/check-rejections.test.ts

@@ -0,0 +1,220 @@
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { afterEach, expect, it } from "vitest";
+import { rejectionProblems, rejections } from "./check-rejections.ts";
+
+const pkgRoot = path.join(path.dirname(fileURLToPath(import.meta.url)), "..");
+/** Each program parses the default lib, over a second on a fast machine. */
+const SLOW = 60_000;
+
+const temps: string[] = [];
+afterEach(() => {
+  for (const dir of temps.splice(0)) fs.rmSync(dir, { recursive: true, force: true });
+});
+
+/** A temp root holding `files`, a value that is not a string written as JSON. */
+function plant(files: Record<string, string | object>): string {
+  const root = fs.realpathSync(fs.mkdtempSync(path.join(os.tmpdir(), "check-rejections-")));
+  temps.push(root);
+  for (const [rel, content] of Object.entries(files)) {
+    fs.mkdirSync(path.dirname(path.join(root, rel)), { recursive: true });
+    fs.writeFileSync(path.join(root, rel), typeof content === "string" ? content : JSON.stringify(content));
+  }
+  return root;
+}
+
+/** A package at `dir`: a `tsconfig.json` on this checkout's base that excludes reject files, and its strict sibling. */
+function pkg(dir: string, compilerOptions: object = {}): Record<string, object> {
+  const exclude = ["**/*.reject.ts", "**/*.reject.tsx"];
+  return {
+    [path.posix.join(dir, "tsconfig.json")]: {
+      extends: path.join(pkgRoot, "tsconfig", "base.json"),
+      compilerOptions,
+      include: ["src"],
+      exclude,
+    },
+    [path.posix.join(dir, "tsconfig.src.json")]: {
+      extends: ["./tsconfig.json", path.join(pkgRoot, "tsconfig", "strict.json")],
+      exclude,
+    },
+  };
+}
+
+/** The problems of every planted file. */
+function problemsOf(files: Record<string, string | object>): string[] {
+  return rejectionProblems(plant(files), Object.keys(files));
+}
+
+it("applies each mark from the next code line to the end of its block", () => {
+  const source = [
+    "// rejects: first",
+    "",
+    "// a note",
+    "const a = (",
+    "\t1",
+    ")",
+    "",
+    "const b = 2",
+    "// rejects: second",
+    "const c = 3",
+  ].join("\n");
+  expect(rejections(source)).toEqual([
+    { end: 6, line: 4, text: "first" },
+    { end: 10, line: 10, text: "second" },
+  ]);
+});
+
+it("reads a mark written as a block comment and skips block prose", () => {
+  const source = [
+    "/* A rejection file: prose first,",
+    "   over two lines. */",
+    "",
+    "/* rejects: first */",
+    'export const a: number = "x"',
+    "",
+    "/* a note, not a mark */",
+    "/* rejects: second */",
+    "export const b = { }.nope",
+  ].join("\n");
+  expect(rejections(source)).toEqual([
+    { end: 5, line: 5, text: "first" },
+    { end: 9, line: 9, text: "second" },
+  ]);
+});
+
+const WIDE_USER = "export type UserId = string;\nexport function load(id: UserId): UserId {\n  return id;\n}\n";
+const USER_REJECT = [
+  "// src/user.reject.ts — excluded from tsconfig.json and tsconfig.src.json",
+  'import { load } from "./user.ts";',
+  "/* rejects: Argument of type 'string' is not assignable to parameter of type 'UserId' */",
+  'load("u1");',
+  "",
+  'lod("u2");',
+  "",
+  '/* rejects: import("/home/me/app/src/user") */',
+  "load(1);",
+  "",
+].join("\n");
+
+it("prints each Usage problem on its statement's line", { timeout: SLOW }, () => {
+  expect(problemsOf({ ...pkg("."), "src/user.ts": WIDE_USER, "src/user.reject.ts": USER_REJECT })).toEqual([
+    "src/user.reject.ts: line 4 compiles; it must reject: Argument of type 'string' is not assignable to parameter of type 'UserId'",
+    "src/user.reject.ts: line 6 fails unmarked: TS2552: Cannot find name 'lod'. Did you mean 'load'?",
+    "src/user.reject.ts: line 9's mark quotes an absolute import path, which differs per checkout: mark the text before it",
+  ]);
+});
+
+it("passes a file that rejects exactly what it marks, under the owner's strict options", { timeout: SLOW }, () => {
+  const branded = WIDE_USER.replace("= string;", '= string & { readonly brand: "UserId" };');
+  const source = [
+    'import { load } from "./user.ts";',
+    "/* rejects: Argument of type 'string' is not assignable to parameter of type 'UserId' */",
+    'load("u1");',
+    "",
+    "export type Opt = { a?: number };",
+    "/* rejects: with 'exactOptionalPropertyTypes: true' */",
+    "export const opt: Opt = { a: undefined };",
+    "",
+    "/* rejects: Type 'unknown' is not assignable to type 'number' */",
+    'export const parsed: number = JSON.parse("1");',
+    "",
+  ].join("\n");
+  expect(problemsOf({ ...pkg("."), "src/user.ts": branded, "src/user.reject.ts": source })).toEqual([]);
+});
+
+it("names the errors of a marked line that fails without its text", { timeout: SLOW }, () => {
+  const source = "/* rejects: Property 'nope' does not exist */\nexport const wrong: number = \"two\";\n";
+  expect(problemsOf({ ...pkg("."), "src/a.reject.ts": source })).toEqual([
+    `src/a.reject.ts: line 2 fails without "Property 'nope' does not exist": TS2322: Type 'string' is not assignable to type 'number'.`,
+  ]);
+});
+
+it("covers a statement the formatter wrapped through the line before the next blank line", { timeout: SLOW }, () => {
+  const source = [
+    "/* rejects: Type 'string' is not assignable to type 'number' */",
+    "export const list: number[] = [",
+    "  1,",
+    '  "two",',
+    "];",
+    "",
+    "export const after: number = 3;",
+    "",
+  ].join("\n");
+  expect(problemsOf({ ...pkg("."), "src/a.reject.ts": source })).toEqual([]);
+});
+
+it("reports a syntax error as such, never as a marked line that compiles", { timeout: SLOW }, () => {
+  const source = "/* rejects: anything */\nexport const a: number = ;\n";
+  expect(problemsOf({ ...pkg("."), "src/a.reject.ts": source })).toEqual([
+    "src/a.reject.ts: line 2 does not parse, so nothing in the file was type-checked: TS1109: Expression expected.",
+  ]);
+});
+
+it("checks a .tsx reject file with its owner's jsx option and ambient types", { timeout: SLOW }, () => {
+  const jsx =
+    "declare namespace JSX {\n  interface Element {}\n  interface IntrinsicElements {\n    div: { id?: string };\n  }\n}\n";
+  const source = [
+    "/* rejects: Type 'number' is not assignable to type 'string' */",
+    "export const el: JSX.Element = <div id={1} />;",
+    "",
+    "/* rejects: anything */",
+    'export const ok: JSX.Element = <div id="a" />;',
+    "",
+  ].join("\n");
+  const files = { ...pkg(".", { jsx: "preserve" }), "src/jsx.d.ts": jsx, "src/view.reject.tsx": source };
+  expect(problemsOf(files)).toEqual(["src/view.reject.tsx: line 5 compiles; it must reject: anything"]);
+});
+
+it("checks each package's reject files under that package's own options", { timeout: SLOW }, () => {
+  const source = [
+    "export type Opt = { a?: number };",
+    "/* rejects: with 'exactOptionalPropertyTypes: true' */",
+    "export const opt: Opt = { a: undefined };",
+    "",
+  ].join("\n");
+  const loose = pkg("packages/loose");
+  loose["packages/loose/tsconfig.src.json"] = { extends: "./tsconfig.json" };
+  const files = {
+    ...pkg("packages/strict"),
+    ...loose,
+    "packages/strict/src/a.reject.ts": source,
+    "packages/loose/src/a.reject.ts": source,
+  };
+  expect(problemsOf(files)).toEqual([
+    "packages/loose/src/a.reject.ts: line 3 compiles; it must reject: with 'exactOptionalPropertyTypes: true'",
+  ]);
+});
+
+it(
+  "falls back to tsconfig.json without a strict sibling, and to strict defaults with no tsconfig",
+  { timeout: SLOW },
+  () => {
+    const source = [
+      "export type Opt = { a?: number };",
+      "/* rejects: with 'exactOptionalPropertyTypes: true' */",
+      "export const opt: Opt = { a: undefined };",
+      "",
+    ].join("\n");
+    const runtime = pkg("packages/runtime");
+    delete runtime["packages/runtime/tsconfig.src.json"];
+    const bare = "/* rejects: Type 'string' is not assignable to type 'number' */\nexport const n: number = 'x';\n";
+    expect(problemsOf({ ...runtime, "packages/runtime/src/a.reject.ts": source, "scratch/a.reject.ts": bare })).toEqual(
+      ["packages/runtime/src/a.reject.ts: line 3 compiles; it must reject: with 'exactOptionalPropertyTypes: true'"],
+    );
+  },
+);
+
+it("skips a listed reject file that no longer exists", { timeout: SLOW }, () => {
+  expect(rejectionProblems(plant(pkg(".")), ["src/gone.reject.ts"])).toEqual([]);
+});
+
+it("names a tsconfig.src.json it cannot read", () => {
+  const files = { "tsconfig.json": "{}", "tsconfig.src.json": '{ "include": ["src"]\n', "src/a.reject.ts": "" };
+  expect(problemsOf(files)).toEqual(["tsconfig.src.json: '}' expected."]);
+});
+
+it("ignores files that are not reject files", () => {
+  expect(problemsOf({ ...pkg("."), "src/a.ts": "export const a: number = 'x';\n" })).toEqual([]);
+});

package/cli/check-rejections.ts

@@ -0,0 +1,153 @@
+/**
+ * Type-level tests: code that must not compile, without `@ts-` directives. A `*.reject.ts(x)` file sits outside its
+ * package's type check (tsconfig `exclude`) and marks each statement that must fail with a `rejects: <text>` comment
+ * above it. The check type-checks it in-process with its owner's `tsconfig.src.json` options: every marked statement
+ * fails with an error containing its text, and nothing else fails. A mark covers its statement's lines up to the next
+ * blank line, so the formatter can wrap it.
+ */
+import fs from "node:fs";
+import path from "node:path";
+import ts from "typescript";
+import { RUNTIME_CONFIG, SRC_CONFIG } from "./tsconfig.constants.ts";
+import { ownerOf, posix, setupOf } from "./ts-program.ts";
+
+/** A statement that must not compile (its first and last one-based lines), and the text its error must contain. */
+export type Rejection = { line: number; end: number; text: string };
+/** A type error on a one-based line, as `TS<code>: <text>`. */
+type TypeError = { line: number; message: string };
+/** A problem's line, for sorting, and its text without the file. */
+type Problem = { line: number; text: string };
+
+/* Both comment forms are read: the line form is what the harness was written for, and `repo/no-line-comment` leaves
+   only the block form in a repo that bans line comments. */
+const MARK = /^\s*(?:\/\/|\/\*)\s*rejects:\s*(.*?)\s*(?:\*\/)?$/;
+const REJECT_FILE = /\.reject\.tsx?$/;
+const DECLARATION = /\.d\.[cm]?ts$/;
+const LINE_COMMENT = "//";
+const BLOCK_OPEN = "/*";
+const BLOCK_CLOSE = "*/";
+/** The start of a module's printed type, which carries the path of the checkout it was checked in. */
+const ABSOLUTE_IMPORT = 'import("/';
+
+/** Where the reader of `rejections` is: the marks waiting for a statement, the statements still growing. */
+type Scan = { found: Rejection[]; pending: string[]; open: Rejection[]; inBlock: boolean };
+
+const isCode = (text: string): boolean => text !== "" && !text.startsWith(LINE_COMMENT) && !text.startsWith(BLOCK_OPEN);
+
+/** A code line: it extends the open statements, and starts one for the marks waiting. */
+function scanCode(scan: Scan, number: number): void {
+  for (const rejection of scan.open) rejection.end = number;
+  if (scan.pending.length === 0) return;
+  scan.open = scan.pending.map((pending) => ({ end: number, line: number, text: pending }));
+  scan.found.push(...scan.open);
+  scan.pending = [];
+}
+
+function scanLine(scan: Scan, line: string, number: number): void {
+  const text = line.trim();
+  if (scan.inBlock) {
+    scan.inBlock = !text.includes(BLOCK_CLOSE);
+    return;
+  }
+  const mark = MARK.exec(line)?.[1];
+  if (mark || text === "") scan.open = [];
+  if (text.startsWith(BLOCK_OPEN) && !text.includes(BLOCK_CLOSE)) scan.inBlock = true;
+  if (mark) scan.pending.push(mark.trim());
+  else if (isCode(text)) scanCode(scan, number);
+}
+
+/**
+ * The marked statements: each `rejects:` comment applies to the next line that is not a comment or blank, through the
+ * line before the next blank line or mark. Prose in a block comment over several lines is not code a mark applies to.
+ */
+export function rejections(source: string): Rejection[] {
+  const scan: Scan = { found: [], pending: [], open: [], inBlock: false };
+  for (const [index, line] of source.split("\n").entries()) scanLine(scan, line, index + 1);
+  return scan.found;
+}
+
+const lineOf = (diagnostic: ts.DiagnosticWithLocation): number =>
+  diagnostic.file.getLineAndCharacterOfPosition(diagnostic.start).line + 1;
+
+const messageOf = (diagnostic: ts.Diagnostic): string =>
+  `TS${diagnostic.code}: ${ts.flattenDiagnosticMessageText(diagnostic.messageText, " ")}`;
+
+/** What is wrong with one mark, given the errors of the file. */
+function markProblem(rejection: Rejection, errors: readonly TypeError[]): Problem | undefined {
+  const { line, text } = rejection;
+  /* The compiler prints a module's type with the path of the checkout it ran in, so a mark quoting one passes in that
+     checkout alone: a worktree or CI prints another. */
+  if (text.includes(ABSOLUTE_IMPORT)) {
+    return {
+      line,
+      text: `line ${line}'s mark quotes an absolute import path, which differs per checkout: mark the text before it`,
+    };
+  }
+  const onLine = errors.filter((error) => error.line >= line && error.line <= rejection.end);
+  if (onLine.length === 0) return { line, text: `line ${line} compiles; it must reject: ${text}` };
+  if (onLine.some((error) => error.message.includes(text))) return undefined;
+  return { line, text: `line ${line} fails without "${text}": ${onLine.map((error) => error.message).join("; ")}` };
+}
+
+/** A file's problems in line order: marks its errors do not match, and errors no mark covers. */
+function fileProblems(source: string, errors: readonly TypeError[]): string[] {
+  const marked = rejections(source);
+  const problems = marked.map((rejection) => markProblem(rejection, errors)).filter((p) => p !== undefined);
+  for (const error of errors) {
+    const covered = marked.some((rejection) => error.line >= rejection.line && error.line <= rejection.end);
+    if (!covered) problems.push({ line: error.line, text: `line ${error.line} fails unmarked: ${error.message}` });
+  }
+  return problems.sort((a, b) => a.line - b.line).map((problem) => problem.text);
+}
+
+/** The errors tsc would print for `file` under the program's options. */
+function typeErrors(program: ts.Program, file: ts.SourceFile): TypeError[] {
+  const declarations = program.getCompilerOptions().declaration === true ? program.getDeclarationDiagnostics(file) : [];
+  return [...program.getSemanticDiagnostics(file), ...declarations]
+    .filter((diagnostic): diagnostic is ts.DiagnosticWithLocation => diagnostic.start !== undefined)
+    .map((diagnostic) => ({ line: lineOf(diagnostic), message: messageOf(diagnostic) }));
+}
+
+/** One reject file's problems, each prefixed with its root-relative path. */
+function fileProblemsOf(program: ts.Program, root: string, file: ts.SourceFile): string[] {
+  const rel = path.posix.relative(root, file.fileName);
+  /* A syntax error leaves no statement checked: report it, never "compiles". */
+  const syntax = program.getSyntacticDiagnostics(file);
+  if (syntax.length > 0) {
+    return syntax.map(
+      (d) => `${rel}: line ${lineOf(d)} does not parse, so nothing in the file was type-checked: ${messageOf(d)}`,
+    );
+  }
+  return fileProblems(file.text, typeErrors(program, file)).map((problem) => `${rel}: ${problem}`);
+}
+
+/** The owner's strict config when it has one; else its `tsconfig.json`, whose missing sibling `checkTsconfigs` names. */
+function configOf(root: string, dir: string): string {
+  return fs.existsSync(path.join(root, dir, SRC_CONFIG)) ? SRC_CONFIG : RUNTIME_CONFIG;
+}
+
+/** The problems of one owner's reject files, from one program over them and the declarations its config lists. */
+function groupProblems(root: string, dir: string | null, targets: readonly string[]): string[] {
+  const setup = setupOf(root, dir, dir === null ? SRC_CONFIG : configOf(root, dir));
+  if (!setup.ok) return setup.errors;
+  const ambient = setup.value.fileNames.filter((fileName) => DECLARATION.test(fileName));
+  const program = ts.createProgram({ rootNames: [...ambient, ...targets], options: setup.value.options });
+  /* A reject file deleted since it was listed is not in the program, and has nothing left to check. */
+  const read = program.getSourceFiles().filter((file) => targets.includes(file.fileName));
+  return read.flatMap((file) => fileProblemsOf(program, root, file));
+}
+
+/**
+ * What is wrong with the reject files among `files` (root-relative POSIX paths), one line each, by file then line: a
+ * marked statement that compiles or fails without its text, a mark quoting a checkout's path, an error no mark
+ * covers, and a file that does not parse. Empty when every file rejects exactly what it marks.
+ */
+export function rejectionProblems(root: string, files: readonly string[]): string[] {
+  const real = posix(fs.realpathSync(root));
+  const groups = new Map<string | null, string[]>();
+  for (const rel of files.filter((file) => REJECT_FILE.test(file)).sort()) {
+    const dir = ownerOf(real, rel);
+    groups.set(dir, [...(groups.get(dir) ?? []), path.posix.join(real, rel)]);
+  }
+  return [...groups].flatMap(([dir, targets]) => groupProblems(real, dir, targets));
+}

package/cli/check-reports.ts

@@ -0,0 +1,37 @@
+/** `repo mutate check <dir>`: merges the shard reports of one run, scores each package and holds it to its floor. */
+import path from "node:path";
+import { fail, type MutateConfig, type MutateDeps } from "./mutate-deps.ts";
+import { failures, label, plural, raised, readFloors, tally, verdicts, type Floors } from "./mutate-floors.ts";
+import type { FileScore, ShardReport } from "./mutate-report.ts";
+import { loadShards, shortOf } from "./mutate-shards.ts";
+import { JSON_INDENT, NEWLINE, OK, SEPARATOR } from "./mutate.constants.ts";
+
+const text = (floors: Floors): string => `${JSON.stringify(floors, null, JSON_INDENT)}${NEWLINE}`;
+
+type Check = { dir: string; write: boolean; config: MutateConfig; reports: ShardReport[]; floors: Floors };
+
+/** The score lines, then a failure line per package below its floor; with `write`, the raised floors file. */
+function settle({ dir, write, config, reports, floors }: Check, deps: MutateDeps): number {
+  const files: Record<string, FileScore> = Object.fromEntries(reports.flatMap((r) => Object.entries(r.files)));
+  const vs = verdicts(tally(files, deps.packages(config.root)), floors);
+  const lines = failures(vs, config.floors, dir);
+  const next = raised(floors, vs);
+  const writes = write && lines.length === 0 && text(next) !== text(floors);
+  const head = `${plural(reports.length, "shard")} of ${shortOf(reports.reduce((_, report) => report.head, ""))}`;
+  const scores = vs.map((v) => label(v, write)).join(SEPARATOR);
+  const wrote = writes ? `${SEPARATOR}wrote ${config.floors}` : "";
+  deps.out(`mutate: ${head}${SEPARATOR}${scores}${wrote}${NEWLINE}`);
+  if (writes) deps.fs.write(path.join(config.root, config.floors), text(next));
+  return lines.length > 0 ? fail(deps, ...lines) : OK;
+}
+
+/** Scores the merged `dir` of reports against the floors; with `write`, raises the floors file when none is below. */
+export async function checkReports(dir: string, write: boolean, deps: MutateDeps): Promise<number> {
+  const config = await deps.config(deps.cwd);
+  if (Array.isArray(config)) return fail(deps, ...config);
+  const reports = loadShards(dir, deps);
+  if (typeof reports === "string") return fail(deps, reports);
+  const floors = readFloors(deps, config.root, config.floors);
+  if (!floors.ok) return fail(deps, `${config.floors} is not a floors file: ${floors.reason}`);
+  return settle({ dir, write, config, reports, floors: floors.value }, deps);
+}