@workerstack/repo 0.0.0-stage → 0.1.0

package/cli/fixtures/release-world.ts

@@ -0,0 +1,111 @@
+import path from "node:path";
+import { releaseMain } from "../release/release.ts";
+import { spawnRunner } from "../scripts/ci-wait-run.ts";
+import type { Runner } from "../scripts/ci-wait.ts";
+import { git as plantedGit, tempDir, write } from "./planted-repo.ts";
+
+export const NAME = "@acme/app";
+export const UNRELEASED_ADDED = "# Changelog\n\n## [Unreleased]\n\n### Added\n\n- x\n\n## [0.1.0] - 2026-10-01\n\n### Added\n\n- first\n";
+export const EMPTY_UNRELEASED = "# Changelog\n\n## [Unreleased]\n\n## [0.1.0] - 2026-10-01\n\n### Added\n\n- first\n";
+
+/** A repo at 0.1.0 (tagged unless `tagged` is false) with a bare origin, its first release already out. */
+export type World = { work: string; remote: string };
+
+/** Files the world starts with, written over by `files`. */
+export function world(files: Record<string, unknown> = {}, tagged = true): World {
+  const dir = tempDir();
+  const remote = path.join(dir, "remote.git");
+  const work = path.join(dir, "work");
+  plantedGit(dir, "init", "-q", "--bare", "-b", "main", remote);
+  plantedGit(dir, "init", "-q", "-b", "main", work);
+  // The release commits in this checkout with the process's git, so the identity lives in the repo, not in a global config a runner lacks.
+  plantedGit(work, "config", "user.name", "t");
+  plantedGit(work, "config", "user.email", "t@t");
+  plantedGit(work, "config", "commit.gpgsign", "false");
+  plantedGit(work, "config", "tag.gpgsign", "false");
+  plantedGit(work, "remote", "add", "origin", remote);
+  write(work, {
+    "package.json": { name: NAME, version: "0.1.0" },
+    "workerstack.config.ts": 'export default { packs: ["release"] };\n',
+    "CHANGELOG.md": EMPTY_UNRELEASED,
+    ...files,
+  });
+  plantedGit(work, "add", "-A");
+  plantedGit(work, "commit", "-q", "-m", "chore: init");
+  plantedGit(work, "push", "-q", "-u", "origin", "main");
+  plantedGit(work, "remote", "set-head", "origin", "main");
+  if (tagged) {
+    plantedGit(work, "tag", "-a", `${NAME}@0.1.0`, "-m", "first");
+    plantedGit(work, "push", "-q", "origin", "--tags");
+  }
+  return { work, remote };
+}
+
+/** Writes `files`, commits them as `subject` and pushes. */
+export function commit(w: World, subject: string, files: Record<string, unknown>, push = true): void {
+  write(w.work, files);
+  plantedGit(w.work, "add", "-A");
+  plantedGit(w.work, "commit", "-q", "-m", subject);
+  if (push) plantedGit(w.work, "push", "-q", "origin", "main");
+}
+
+/** A pushed feat with an entry under Unreleased. */
+export function feat(w: World, push = true): void {
+  commit(w, "feat: add x", { "src/x.ts": "export const x = 1;\n", "CHANGELOG.md": UNRELEASED_ADDED }, push);
+}
+
+export const gitIn = (cwd: string, ...args: string[]): string => plantedGit(cwd, ...args).trim();
+/** Where the checkout and its origin stand: enough to prove a refused run wrote nothing. */
+export const snapshot = (w: World) => ({
+  head: gitIn(w.work, "rev-parse", "HEAD"),
+  status: gitIn(w.work, "status", "--porcelain"),
+  tags: gitIn(w.work, "tag", "-l"),
+  remoteTags: gitIn(w.remote, "tag", "-l"),
+  remoteMain: gitIn(w.remote, "rev-parse", "main"),
+});
+
+/** What the fake gh answers: a ci run for any commit, ending as `conclusion`. */
+export type Behavior = {
+  auth?: boolean;
+  run?: boolean;
+  conclusion?: string;
+  /** Called when the run is watched, to see what exists then. */
+  onWatch?: () => void;
+};
+const ok = (stdout = "") => ({ code: 0, stdout, stderr: "" });
+const BAD = { code: 1, stdout: "", stderr: "no" };
+const RUN = { databaseId: 7, createdAt: "2026-11-09T10:00:00Z", headBranch: "main" };
+
+export function fakeGh(b: Behavior = {}): Runner {
+  return (args) => {
+    const key = args.join(" ");
+    if (key === "auth status") return b.auth === false ? BAD : ok();
+    if (key.startsWith("run list --commit")) return ok(JSON.stringify(b.run === false ? [] : [RUN]));
+    if (key.startsWith("run list --branch")) {
+      return ok(JSON.stringify([RUN, { databaseId: 8, createdAt: "2026-11-09T10:05:00Z" }]));
+    }
+    if (key.startsWith("run watch")) return (b.onWatch?.(), ok());
+    if (key.startsWith("run view 7 --json")) {
+      const conclusion = b.conclusion ?? "success";
+      return ok(JSON.stringify({ conclusion, jobs: [{ name: "test", conclusion }] }));
+    }
+    return key.startsWith("run view 7 --log-failed") ? ok("boom\n") : BAD;
+  };
+}
+
+/** Runs `repo release` in the world's checkout; the exit code and what it printed. */
+export async function release(w: World, argv: string[], gh: Runner = fakeGh()) {
+  const out: string[] = [];
+  const err: string[] = [];
+  let clock = Date.UTC(2026, 10, 9);
+  const code = await releaseMain(argv, {
+    cwd: w.work,
+    stdout: (s) => out.push(s),
+    stderr: (s) => err.push(s),
+    git: spawnRunner("git"),
+    gh,
+    now: () => clock,
+    sleep: (ms) => ((clock += ms), Promise.resolve()),
+  });
+  return { code, out: out.join(""), err: err.join("") };
+}

package/cli/fixtures/stub-bin.ts

@@ -0,0 +1,40 @@
+import { spawnSync } from "node:child_process";
+import fs from "node:fs";
+import path from "node:path";
+import { BUN } from "../../dev/test-paths.ts";
+
+/**
+ * Plants a command `name` in `dir` that a product starts by name or from PATH: an executable shebang script
+ * with `sh` as its body, or on win32 `name.cmd` with `cmd` as its batch body (a shebang script cannot start there).
+ * Returns the file written.
+ */
+export function plantStub(dir: string, name: string, body: { sh: string; cmd: string }): string {
+  fs.mkdirSync(dir, { recursive: true });
+  if (process.platform === "win32") {
+    const file = path.join(dir, `${name}.cmd`);
+    fs.writeFileSync(file, `@echo off\r\n${body.cmd.replaceAll("\n", "\r\n")}`);
+    return file;
+  }
+  const file = path.join(dir, name);
+  fs.writeFileSync(file, `#!/bin/sh\n${body.sh}`, { mode: 0o755 });
+  return file;
+}
+
+/**
+ * Plants a command `name` in `dir` that a product starts by its path without a shell, so a `.cmd` will not do on
+ * win32: the `js` program, as a shebang script run by bun, or on win32 compiled to `name.exe`. Returns the file.
+ */
+export function plantProgram(dir: string, name: string, js: string): string {
+  fs.mkdirSync(dir, { recursive: true });
+  const source = path.join(dir, `${name}-source.js`);
+  fs.writeFileSync(source, js);
+  if (process.platform === "win32") {
+    const file = path.join(dir, `${name}.exe`);
+    const built = spawnSync(BUN, ["build", "--compile", source, "--outfile", file], { encoding: "utf8" });
+    if (built.status !== 0) throw new Error(`bun build --compile failed: ${built.stderr}${built.stdout}`);
+    return file;
+  }
+  const file = path.join(dir, name);
+  fs.writeFileSync(file, `#!/bin/sh\nexec ${JSON.stringify(BUN)} ${JSON.stringify(source)} "$@"\n`, { mode: 0o755 });
+  return file;
+}

package/cli/guard-diagnostics.test.ts

@@ -0,0 +1,157 @@
+import { afterEach, expect, it } from "vitest";
+import { guardDiagnostics } from "./guard-diagnostics.ts";
+import { cleanTemps, plant, SLOW } from "./magic/fixtures/magic-repo.ts";
+import { cleanTemps as cleanRepos, consumer, SLOW as TURN, turn, write } from "./scripts/fixtures/turn-repo.ts";
+import type { Diagnostic } from "./scripts/lint-baseline.ts";
+
+afterEach(() => {
+  cleanTemps();
+  cleanRepos();
+});
+
+const RULE = "repo(guard-rejects)";
+const TSCONFIG = JSON.stringify({
+  compilerOptions: { strict: true, module: "preserve", moduleResolution: "bundler", allowImportingTsExtensions: true },
+  include: ["src"],
+});
+const USER = [
+  "export type User = { name: string };",
+  "",
+  "export function isUser(value: unknown): value is User {",
+  '  return typeof value === "object" && value !== null && "name" in value;',
+  "}",
+  "",
+  'export const isName = (value: unknown): value is string => typeof value === "string";',
+  "",
+].join("\n");
+
+/** A guard no test imports. */
+const OTHER = 'export const isOther = (value: unknown): value is number => typeof value === "number";\n';
+
+/** The diagnostic for an untested guard `name` at `at`, `<file>:<line>:<column>`. */
+const untested = (at: string, name: string): Diagnostic => ({
+  file: at.slice(0, at.indexOf(":")),
+  rule: RULE,
+  line: `${at}: error ${RULE}: ${name} is never asserted false; add expect(${name}(<an input it must reject>)).toBe(false) to a test`,
+});
+
+const VITEST = 'import { expect, it } from "vitest";\n';
+
+/** A test file over `src/user.ts` with `imports` and `body` in one `it`. */
+const test = (imports: string, body: string): string => `${VITEST}${imports}\n\nit("guards", () => {\n${body}\n});\n`;
+
+/** The guard hits of `files` planted beside a tsconfig.json, checking `checked` (all of them by default). */
+function guardsOf(files: Record<string, string>, checked: readonly string[] = Object.keys(files)): Diagnostic[] {
+  const found = guardDiagnostics(plant({ "tsconfig.json": TSCONFIG, ...files }), checked);
+  if (!found.ok) throw new Error(found.errors.join("\n"));
+  return found.value;
+}
+
+it("reports each exported guard no test asserts false, a true-only test included", { timeout: SLOW }, () => {
+  const inferred = [
+    'export const isCount = (value: unknown) => typeof value === "number";',
+    'export const isWord = function (value: unknown): value is string { return typeof value === "string"; };',
+    "",
+  ].join("\n");
+  const only = test(
+    'import { isUser, isName } from "./user.ts";',
+    '  expect(isUser({ name: "a" })).toBe(true);\n  expect(isName("a")).toBeTruthy();',
+  );
+  expect(guardsOf({ "src/user.ts": `${USER}${inferred}`, "src/user.test.ts": only })).toEqual([
+    untested("src/user.ts:3:17", "isUser"),
+    untested("src/user.ts:7:14", "isName"),
+    untested("src/user.ts:8:14", "isCount"),
+    untested("src/user.ts:9:14", "isWord"),
+  ]);
+});
+
+it.each(["toBe(false)", "toBeFalsy()", "toEqual(false)"])("passes a guard asserted .%s", { timeout: SLOW }, (form) => {
+  const body = `  expect(isUser(1)).${form};\n  expect(isName(1)).${form};`;
+  const files = { "src/user.ts": USER, "src/user.test.ts": test('import { isUser, isName } from "./user.ts";', body) };
+  expect(guardsOf(files)).toEqual([]);
+});
+
+it("follows a renamed import and a namespace import to the guard", { timeout: SLOW }, () => {
+  const renamed = test(
+    'import { isUser as looksLikeUser } from "./user.ts";',
+    "  expect(looksLikeUser(1)).toBe(false);",
+  );
+  const namespace = test('import * as user from "./user.ts";', "  expect(user.isName(1)).toBeFalsy();");
+  const files = { "src/user.ts": USER, "src/a.test.ts": renamed, "src/b.test.ts": namespace };
+  expect(guardsOf(files, ["src/user.ts"])).toEqual([]);
+});
+
+it("counts only a guard called as the argument of expect(…) itself", { timeout: SLOW }, () => {
+  const body = [
+    "  const rejected = isUser(1);",
+    "  expect(rejected).toBe(false);",
+    "  expect.soft(isUser(1)).toBe(false);",
+    "  check(isUser(1)).toBe(false);",
+    "  expect().toBe(false);",
+    "  rejected.toBe(false);",
+    "  expect(isUser(1)).toBe(false, 1);",
+    "  expect(isName(1)).toBe(false);",
+  ].join("\n");
+  const files = { "src/user.ts": USER, "src/user.test.ts": test('import { isUser, isName } from "./user.ts";', body) };
+  expect(guardsOf(files)).toEqual([untested("src/user.ts:3:17", "isUser")]);
+});
+
+it(
+  "skips a guard that is not exported or has no name of its own, an assertion function and a plain boolean function",
+  { timeout: SLOW },
+  () => {
+    const source = [
+      "function isText(value: unknown): value is string {",
+      '  return typeof value === "string";',
+      "}",
+      "",
+      "export function assertText(value: unknown): asserts value is string {",
+      '  if (!isText(value)) throw new Error("not text");',
+      "}",
+      "",
+      "export const isEmpty = (text: string): boolean => text.length === 0;",
+      'const isLocal = (value: unknown): value is string => typeof value === "string";',
+      "export const local = isLocal;",
+      'export const { length } = "abc";',
+      "export let pending: ((value: unknown) => value is string) | undefined;",
+      "export default function (value: unknown): value is number {",
+      '  return typeof value === "number";',
+      "}",
+      "",
+    ].join("\n");
+    expect(guardsOf({ "src/text.ts": source })).toEqual([]);
+  },
+);
+
+it("re-checks the guards of the sources a changed test imports, when only the test changed", { timeout: SLOW }, () => {
+  const trueOnly = test(
+    'import { isUser, isName } from "./user.ts";',
+    "  expect(isUser(1)).toBe(true);\n  expect(isName(1)).toBe(false);",
+  );
+  const files = { "src/user.ts": USER, "src/user.test.ts": trueOnly, "src/other.ts": OTHER };
+  expect(guardsOf(files, ["src/user.test.ts"])).toEqual([untested("src/user.ts:3:17", "isUser")]);
+});
+
+it("reports a tsconfig.json typescript cannot read", () => {
+  const root = plant({ "pkg/tsconfig.json": "{", "pkg/a.ts": USER });
+  const found = guardDiagnostics(root, ["pkg/a.ts"]);
+  expect(found.ok ? [] : found.errors).toEqual([expect.stringMatching(/^pkg\/tsconfig\.json: .+/)]);
+});
+
+it("fails a turn that touches only a test and drops the last false assert", { timeout: TURN }, async () => {
+  const asserted = test(
+    'import { isUser, isName } from "./user.ts";',
+    "  expect(isUser(1)).toBe(false);\n  expect(isName(1)).toBe(false);",
+    // The consumer installs no vitest, and the boundaries rule refuses an undeclared import; the globals stand in.
+  ).replace(VITEST, "");
+  const root = consumer({ "src/user.ts": USER, "src/user.test.ts": asserted });
+  write(root, {
+    "src/user.test.ts": asserted.replace("expect(isUser(1)).toBe(false)", "expect(isUser(1)).toBe(true)"),
+  });
+  const result = await turn(root, [], { tsc: () => ({ code: 0, stdout: "", stderr: "" }), vitest: () => null });
+  expect(result.err).toBe(
+    `${untested("src/user.ts:3:17", "isUser").line}\nrepo turn: src/user.ts has 1 repo(guard-rejects), the baseline allows 0; fix the new one\n`,
+  );
+  expect(result.out).toMatch(/^turn: 1 file · fmt ok · comments ok · lint 1 over baseline · /);
+  expect(result.code).toBe(1);
+});

package/cli/guard-diagnostics.ts

@@ -0,0 +1,195 @@
+/**
+ * Type guards proven with an input they must reject: an exported function whose return type is a type predicate needs
+ * a test that asserts it returns false, else a lint diagnostic `repo(guard-rejects)` the baseline counts. A guard
+ * tested only on what it accepts still passes a guard that accepts everything. The tests are read with the type
+ * checker, so an import renamed or through a namespace still reaches the guard.
+ */
+import fs from "node:fs";
+import path from "node:path";
+import ts from "typescript";
+import { GUARD_REJECTS } from "./lint/script-rules.ts";
+import type { Diagnostic, Result } from "./scripts/lint-baseline.ts";
+import { codeOf } from "./scripts/lint-skips.ts";
+import { RUNTIME_CONFIG } from "./tsconfig.constants.ts";
+import { isChecked, isTest, ownerOf, posix, setupOf } from "./ts-program.ts";
+
+/** An exported guard: its declared name node and the symbol a call resolves to. */
+type Guard = { name: ts.Identifier; symbol: ts.Symbol };
+/** One tsconfig's files, as program paths: the sources to report in and the changed tests whose imports join them. */
+type Group = { root: string; dir: string | null; sources: string[]; tests: string[] };
+type FunctionLike = ts.FunctionDeclaration | ts.ArrowFunction | ts.FunctionExpression;
+
+const RULE = /* @__PURE__ */ codeOf(GUARD_REJECTS);
+/** The asserts that a call returned false; a test file without one cannot prove a guard rejects. */
+const FALSE_ASSERT = /\.(?:toBe|toEqual)\(\s*false\s*\)|\.toBeFalsy\(\s*\)/;
+/** Each matcher that can assert false, by the argument count that does: `toBe(false)` and `toBeFalsy()`. */
+const FALSE_MATCHERS: ReadonlyMap<string, number> = /* @__PURE__ */ new Map([
+  ["toBe", 1],
+  ["toEqual", 1],
+  ["toBeFalsy", 0],
+]);
+/** vitest's `expect`, as the checker spells an identifier. */
+const EXPECT: ts.__String = /* @__PURE__ */ ts.escapeLeadingUnderscores("expect");
+
+const message = (name: string): string =>
+  `${name} is never asserted false; add expect(${name}(<an input it must reject>)).toBe(false) to a test`;
+
+const isExported = (node: ts.Declaration): boolean =>
+  (ts.getCombinedModifierFlags(node) & ts.ModifierFlags.Export) !== 0;
+
+/** Whether `fn` returns `x is T` or `this is T`, written or inferred; an `asserts` function is no guard. */
+function isGuard(fn: FunctionLike, checker: ts.TypeChecker): boolean {
+  const signature = checker.getSignatureFromDeclaration(fn);
+  const predicate = signature && checker.getTypePredicateOfSignature(signature);
+  const kind = predicate?.kind;
+  return kind === ts.TypePredicateKind.Identifier || kind === ts.TypePredicateKind.This;
+}
+
+/** The exported function declarations and `const` function values of a statement, with their names. */
+function functionsOf(statement: ts.Statement): { name: ts.Identifier; fn: FunctionLike }[] {
+  if (ts.isFunctionDeclaration(statement) && statement.name && isExported(statement))
+    return [{ name: statement.name, fn: statement }];
+  if (!ts.isVariableStatement(statement)) return [];
+  return statement.declarationList.declarations.flatMap((declaration) => {
+    const init = declaration.initializer;
+    const isFunction = init !== undefined && (ts.isArrowFunction(init) || ts.isFunctionExpression(init));
+    if (!isFunction || !ts.isIdentifier(declaration.name) || !isExported(declaration)) return [];
+    return [{ name: declaration.name, fn: init }];
+  });
+}
+
+function guardsOf(file: ts.SourceFile, checker: ts.TypeChecker): Guard[] {
+  return file.statements.flatMap((statement) =>
+    functionsOf(statement).flatMap(({ name, fn }) => {
+      const symbol = checker.getSymbolAtLocation(name);
+      return symbol !== undefined && isGuard(fn, checker) ? [{ name, symbol }] : [];
+    }),
+  );
+}
+
+/** The symbol an imported name finally declares, through renames, namespaces and re-exports. */
+function resolved(symbol: ts.Symbol, checker: ts.TypeChecker): ts.Symbol {
+  return (symbol.flags & ts.SymbolFlags.Alias) === 0 ? symbol : checker.getAliasedSymbol(symbol);
+}
+
+/** Whether `call` is a matcher asserting false: `.toBe(false)`, `.toEqual(false)` or `.toBeFalsy()`. */
+function assertsFalse(
+  call: ts.CallExpression,
+): call is ts.CallExpression & { expression: ts.PropertyAccessExpression } {
+  if (!ts.isPropertyAccessExpression(call.expression)) return false;
+  const count = FALSE_MATCHERS.get(call.expression.name.text);
+  if (count !== call.arguments.length) return false;
+  const [arg] = call.arguments;
+  return arg === undefined || arg.kind === ts.SyntaxKind.FalseKeyword;
+}
+
+/** The function `call` asserts false the result of, as in `expect(isUser(input)).toBe(false)`. */
+function falseCallee(call: ts.CallExpression): ts.Node | undefined {
+  if (!assertsFalse(call)) return undefined;
+  const expected = call.expression.expression;
+  if (!ts.isCallExpression(expected) || !ts.isIdentifier(expected.expression)) return undefined;
+  if (expected.expression.escapedText !== EXPECT) return undefined;
+  const [subject] = expected.arguments;
+  if (subject === undefined || !ts.isCallExpression(subject)) return undefined;
+  const callee = subject.expression;
+  return ts.isPropertyAccessExpression(callee) ? callee.name : callee;
+}
+
+/** Every symbol a test file asserts a call of returns false. */
+function assertedFalse(file: ts.SourceFile, checker: ts.TypeChecker): ts.Symbol[] {
+  const found: ts.Symbol[] = [];
+  const visit = (node: ts.Node): void => {
+    const callee = ts.isCallExpression(node) ? falseCallee(node) : undefined;
+    const symbol = callee && checker.getSymbolAtLocation(callee);
+    if (symbol) found.push(resolved(symbol, checker));
+    ts.forEachChild(node, visit);
+  };
+  visit(file);
+  return found;
+}
+
+/** The program paths of the modules `file` imports. */
+function importsOf(file: ts.SourceFile, checker: ts.TypeChecker): string[] {
+  return file.statements.flatMap((statement) => {
+    if (!ts.isImportDeclaration(statement)) return [];
+    const declaration = checker.getSymbolAtLocation(statement.moduleSpecifier)?.valueDeclaration;
+    return declaration !== undefined && ts.isSourceFile(declaration) ? [declaration.fileName] : [];
+  });
+}
+
+/** The tsconfig's tests that assert some call false, read as text first so a program parses only those. */
+function falseTests(group: Group, fileNames: readonly string[]): string[] {
+  const owned = fileNames.filter((fileName) => {
+    const rel = path.posix.relative(group.root, fileName);
+    return isTest(rel) && ownerOf(group.root, rel) === group.dir;
+  });
+  return owned.filter((fileName) => FALSE_ASSERT.test(fs.readFileSync(fileName, "utf8")));
+}
+
+/** The sources to report in: the group's, and those its changed tests import from the same tsconfig. */
+function targetsOf(group: Group, program: ts.Program): string[] {
+  const checker = program.getTypeChecker();
+  const tests = program.getSourceFiles().filter((file) => group.tests.includes(file.fileName));
+  const imported = tests.flatMap((file) => importsOf(file, checker));
+  const owned = imported.filter((fileName) => {
+    const rel = path.posix.relative(group.root, fileName);
+    return isChecked(rel) && ownerOf(group.root, rel) === group.dir;
+  });
+  return [...new Set([...group.sources, ...owned])];
+}
+
+/** The guards declared in `targets`. */
+function guardsIn(program: ts.Program, targets: readonly string[]): Guard[] {
+  const checker = program.getTypeChecker();
+  const files = program.getSourceFiles().filter((file) => targets.includes(file.fileName));
+  return files.flatMap((file) => guardsOf(file, checker));
+}
+
+/**
+ * One group's untested guards. A first program finds the targets and whether they declare a guard; only then a second
+ * adds the tests that could assert one false, reusing what the first parsed.
+ */
+function groupGuards(group: Group): Result<Guard[]> {
+  const setup = setupOf(group.root, group.dir, RUNTIME_CONFIG);
+  if (!setup.ok) return setup;
+  const { options } = setup.value;
+  const first = ts.createProgram({ rootNames: [...group.sources, ...group.tests], options });
+  const targets = targetsOf(group, first);
+  if (guardsIn(first, targets).length === 0) return { ok: true, value: [] };
+  const tests = [...new Set([...falseTests(group, setup.value.fileNames), ...group.tests])];
+  const program = ts.createProgram({ rootNames: [...targets, ...tests], options, oldProgram: first });
+  const checker = program.getTypeChecker();
+  const testFiles = program.getSourceFiles().filter((file) => tests.includes(file.fileName));
+  const asserted = new Set(testFiles.flatMap((file) => assertedFalse(file, checker)));
+  return { ok: true, value: guardsIn(program, targets).filter((guard) => !asserted.has(guard.symbol)) };
+}
+
+function diagnosticOf(root: string, { name }: Guard): Diagnostic {
+  const file = name.getSourceFile();
+  const rel = path.posix.relative(root, file.fileName);
+  const { line, character } = file.getLineAndCharacterOfPosition(name.getStart());
+  return { file: rel, rule: RULE, line: `${rel}:${line + 1}:${character + 1}: error ${RULE}: ${message(name.text)}` };
+}
+
+/**
+ * The untested exported guards of the checked sources among `files` (root-relative POSIX paths), and of the sources
+ * the tests among them import, in oxlint's line form; or why a tsconfig.json could not be read. A guard passes when a
+ * test of its tsconfig asserts a call of it false.
+ */
+export function guardDiagnostics(root: string, files: readonly string[]): Result<Diagnostic[]> {
+  const real = posix(fs.realpathSync(root));
+  const groups = new Map<string | null, Group>();
+  for (const rel of files.filter((file) => isChecked(file) || isTest(file))) {
+    const dir = ownerOf(real, rel);
+    const group = groups.get(dir) ?? { root: real, dir, sources: [], tests: [] };
+    (isTest(rel) ? group.tests : group.sources).push(path.posix.join(real, rel));
+    groups.set(dir, group);
+  }
+  const diagnostics: Diagnostic[] = [];
+  for (const group of groups.values()) {
+    const found = groupGuards(group);
+    if (!found.ok) return found;
+    diagnostics.push(...found.value.map((guard) => diagnosticOf(real, guard)));
+  }
+  return { ok: true, value: diagnostics };
+}