@akanjs/devkit 3.1.1-rc.8 → 3.1.1

package/storeWriteScanner.test.ts

@@ -0,0 +1,292 @@
+import { describe, expect, test } from "bun:test";
+import ts from "typescript";
+import type { SourceFileInfo } from "./qualityScanner";
+import { SignalMutationIndex } from "./signalMutationIndex";
+import { StoreWriteScanner } from "./storeWriteScanner";
+import { WritingActionIndex } from "./writingActionIndex";
+
+const fileOf = (file: string, content: string): SourceFileInfo => ({
+  file,
+  absolutePath: `/repo/${file}`,
+  content,
+  sourceFile: ts.createSourceFile(file, content, ts.ScriptTarget.Latest, true, ts.ScriptKind.TS),
+});
+
+const signal = fileOf(
+  "apps/demo/lib/court/court.signal.ts",
+  `
+export class CourtSlice extends slice(srv.court, { guards: { root: Admin, get: Public, cru: User } }, () => ({})) {}
+export class CourtEndpoint extends endpoint(srv.court, ({ query, mutation }) => ({
+  assignCourtPc: mutation(cnst.Court, { guards: [User] }).param("courtId", ID).exec(async function (courtId) {
+    return await this.courtService.assignPc(courtId);
+  }),
+  pushPcCommand: mutation(Boolean, { guards: [User] }).param("courtId", ID).exec(async function (courtId) {
+    return await this.courtService.pushPcCommand(courtId);
+  }),
+  courtCount: query(Int, { guards: [User] }).exec(async function () {
+    return 0;
+  }),
+})) {}
+`,
+);
+
+const storeOf = (body: string) =>
+  fileOf(
+    "apps/demo/lib/court/court.store.ts",
+    `import { store } from "akanjs/store";\nimport * as cnst from "../cnst";\nimport { fetch, sig } from "../useClient";\n\nexport class CourtStore extends store(sig.court, () => ({ count: 0 })) {\n${body}\n}\n`,
+  );
+
+const scan = (store: SourceFileInfo, otherStores: SourceFileInfo[] = []) =>
+  new StoreWriteScanner(new WritingActionIndex(new SignalMutationIndex([signal]), [store, ...otherStores])).scan(store);
+
+const pushStore = fileOf(
+  "apps/demo/lib/push/push.store.ts",
+  `import { fetch, sig } from "../useClient";
+export class PushStore extends store(sig.push, () => ({})) {
+  async pushCommandOnPc(courtId: string) {
+    await fetch.pushPcCommand(courtId);
+  }
+  async countPushes() {
+    return await fetch.courtCount();
+  }
+}
+`,
+);
+
+describe("StoreWriteScanner", () => {
+  test("reports an action sending two mutations at the second one", () => {
+    const writes = scan(
+      storeOf(`  async assignCourtPcOnCourt(courtId: string) {
+    const court = await fetch.assignCourtPc(courtId);
+    await fetch.pushPcCommand(court.id);
+    this.setCourt(court);
+  }`),
+    );
+    expect(writes).toEqual([
+      {
+        action: "assignCourtPcOnCourt",
+        line: 8,
+        writes: ["fetch.assignCourtPc", "fetch.pushPcCommand"],
+        writeCount: 2,
+        isRootChain: false,
+      },
+    ]);
+  });
+
+  test("reads a mutation and a query, or a model read, as one write", () => {
+    const writes = scan(
+      storeOf(`  async refreshCourt(courtId: string) {
+    const court = await fetch.assignCourtPc(courtId);
+    this.set({ count: await fetch.courtCount() });
+    this.setCourt(await fetch.court(court.id));
+  }`),
+    );
+    expect(writes).toEqual([]);
+  });
+
+  test("reads writes on exclusive branches as one", () => {
+    const writes = scan(
+      storeOf(`  async pushOnCourt(courtId: string, many: boolean) {
+    if (many) await fetch.assignCourtPc(courtId);
+    else await fetch.pushPcCommand(courtId);
+  }`),
+    );
+    expect(writes).toEqual([]);
+  });
+
+  test("counts the generated CRUD and a write inside a nested callback", () => {
+    const writes = scan(
+      storeOf(`  async mergeCourts(courtIds: string[]) {
+    await Promise.all(courtIds.map(async (courtId) => fetch.mergeCourt(courtId, {})));
+    setTimeout(() => void fetch["pushPcCommand"](courtIds[0]), 0);
+  }`),
+    );
+    expect(writes.map(({ action, writes }) => ({ action, writes }))).toEqual([
+      { action: "mergeCourts", writes: ["fetch.mergeCourt (per item)", 'fetch["pushPcCommand"]'] },
+    ]);
+  });
+
+  test("reads one write per item as two, in a loop or a per-element callback, but not the list it loops over", () => {
+    const writes = scan(
+      storeOf(`  async removeCourts(courtIds: string[]) {
+    for (const courtId of courtIds) await fetch.mergeCourt(courtId, {});
+  }
+  async pushToEach(courtIds: string[]) {
+    await Promise.all(courtIds.map((courtId) => fetch.pushPcCommand(courtId)));
+  }
+  async assignOnce(courtId: string) {
+    for (const pc of [await fetch.assignCourtPc(courtId)]) this.setCourt(pc);
+  }`),
+    );
+    expect(writes.map(({ action, writes, writeCount }) => ({ action, writes, writeCount }))).toEqual([
+      { action: "removeCourts", writes: ["fetch.mergeCourt (per item)"], writeCount: 2 },
+      { action: "pushToEach", writes: ["fetch.pushPcCommand (per item)"], writeCount: 2 },
+    ]);
+  });
+
+  test("counts a call to another writing action of the same store", () => {
+    const writes = scan(
+      storeOf(`  async pushCommandOnCourt(courtId: string) {
+    await fetch.pushPcCommand(courtId);
+  }
+  async readCourt(courtId: string) {
+    return fetch.court(courtId);
+  }
+  async assignCourtPcOnCourt(courtId: string) {
+    await this.readCourt(courtId);
+    await fetch.assignCourtPc(courtId);
+    await this.pushCommandOnCourt(courtId);
+  }`),
+    );
+    expect(writes).toEqual([
+      {
+        action: "assignCourtPcOnCourt",
+        line: 15,
+        writes: ["fetch.assignCourtPc", "this.pushCommandOnCourt"],
+        writeCount: 2,
+        isRootChain: false,
+      },
+    ]);
+  });
+
+  test("counts a generated CRUD action of the store's own model as its own write", () => {
+    const writes = scan(
+      storeOf(`  async createAndPushCourt(courtId: string) {
+    await this.createCourt({ name: courtId });
+    await fetch.pushPcCommand(courtId);
+  }`),
+    );
+    expect(writes).toMatchObject([
+      { action: "createAndPushCourt", writes: ["this.createCourt", "fetch.pushPcCommand"] },
+    ]);
+    expect(writes[0]?.isRootChain).toBe(false);
+  });
+
+  test("reads another store's writing action through the RootStore cast, an alias of it or a RootStore parameter", () => {
+    const writes = scan(
+      storeOf(`  async assignAndPush(courtId: string) {
+    await fetch.assignCourtPc(courtId);
+    await (this as unknown as RootStore).pushCommandOnPc(courtId);
+  }
+  async assignThroughAlias(courtId: string) {
+    const root = this as unknown as RootStore;
+    await root.countPushes();
+    await fetch.assignCourtPc(courtId);
+    await root.pushCommandOnPc(courtId);
+  }
+  static async assignFrom(root: RootStore, courtId: string) {
+    await root.assignCourtPcOnCourt(courtId);
+    await root.pushCommandOnPc(courtId);
+  }
+  async assignCourtPcOnCourt(courtId: string) {
+    await fetch.assignCourtPc(courtId);
+  }`),
+      [pushStore],
+    );
+    expect(writes.map(({ action, writes, isRootChain }) => ({ action, writes, isRootChain }))).toEqual([
+      {
+        action: "assignAndPush",
+        writes: ["fetch.assignCourtPc", "(this as unknown as RootStore).pushCommandOnPc"],
+        isRootChain: true,
+      },
+      { action: "assignThroughAlias", writes: ["fetch.assignCourtPc", "root.pushCommandOnPc"], isRootChain: true },
+      { action: "assignFrom", writes: ["root.assignCourtPcOnCourt", "root.pushCommandOnPc"], isRootChain: true },
+    ]);
+  });
+
+  test("counts a call to a writing static helper, and the writes a callback hands it", () => {
+    const writes = scan(
+      storeOf(`  static async guarded(root: RootStore, write: () => Promise<void>) {
+    await write();
+    void root.countPushes();
+  }
+  static async assignOnce(root: RootStore, courtId: string) {
+    await fetch.assignCourtPc(courtId);
+  }
+  async assignAndPush(courtId: string) {
+    const root = this as unknown as RootStore;
+    await CourtStore.assignOnce(root, courtId);
+    await CourtStore.guarded(root, () => root.pushCommandOnPc(courtId));
+  }`),
+      [pushStore],
+    );
+    expect(writes).toMatchObject([
+      {
+        action: "assignAndPush",
+        writes: ["CourtStore.assignOnce", "root.pushCommandOnPc"],
+        isRootChain: true,
+      },
+    ]);
+  });
+
+  test("reads the store's own writing static as its own write, not a chain through another store", () => {
+    const writes = scan(
+      storeOf(`  static async assignOnce(courtId: string) {
+    await fetch.assignCourtPc(courtId);
+  }
+  async assignAndPush(courtId: string) {
+    await CourtStore.assignOnce(courtId);
+    await fetch.pushPcCommand(courtId);
+  }`),
+    );
+    expect(writes).toMatchObject([
+      { action: "assignAndPush", writes: ["CourtStore.assignOnce", "fetch.pushPcCommand"], isRootChain: false },
+    ]);
+  });
+
+  test("reads a recursive call as no write, and a static helper's own writes as a chain", () => {
+    const writes = scan(
+      storeOf(`  async undoOnCourt(courtId: string) {
+    await fetch.assignCourtPc(courtId);
+    await this.undoOnCourt(courtId);
+  }
+  static async sync(courtId: string) {
+    await fetch.assignCourtPc(courtId);
+    await fetch.pushPcCommand(courtId);
+  }`),
+    );
+    expect(writes.map(({ action, isRootChain }) => ({ action, isRootChain }))).toEqual([
+      { action: "sync", isRootChain: false },
+    ]);
+  });
+
+  test("ignores getters, class-property arrows and classes that are not stores", () => {
+    const writes = scan(
+      fileOf(
+        "apps/demo/lib/court/court.store.ts",
+        `import { fetch, sig } from "../useClient";
+export class CourtStore extends store(sig.court, () => ({})) {
+  get both() {
+    void fetch.assignCourtPc("a");
+    void fetch.pushPcCommand("a");
+    return true;
+  }
+  assignBoth = async (courtId: string) => {
+    await fetch.assignCourtPc(courtId);
+    await fetch.pushPcCommand(courtId);
+  };
+}
+export class Helper extends Base {
+  async run(courtId: string) {
+    await fetch.assignCourtPc(courtId);
+    await fetch.pushPcCommand(courtId);
+  }
+}`,
+      ),
+    );
+    expect(writes).toEqual([]);
+  });
+
+  test("reads nothing from a store that does not import fetch", () => {
+    const store = fileOf(
+      "apps/demo/lib/court/court.store.ts",
+      `export class CourtStore extends store(sig.court, () => ({})) {
+  async run(courtId: string) {
+    await fetch.assignCourtPc(courtId);
+    await fetch.pushPcCommand(courtId);
+  }
+}`,
+    );
+    expect(scan(store)).toEqual([]);
+  });
+});

package/storeWriteScanner.ts

@@ -0,0 +1,50 @@
+import type ts from "typescript";
+import type { SourceFileInfo } from "./qualityScanner";
+import { type StoreCallTarget, StoreSource } from "./storeSource";
+import { WritePath } from "./writePath";
+import type { WritingActionIndex } from "./writingActionIndex";
+
+export interface StoreMultiWrite {
+  action: string;
+  line: number;
+  writes: string[];
+  writeCount: number;
+  isRootChain: boolean;
+}
+
+export class StoreWriteScanner {
+  readonly #index: WritingActionIndex;
+
+  constructor(index: WritingActionIndex) {
+    this.#index = index;
+  }
+
+  scan({ file, sourceFile }: Pick<SourceFileInfo, "file" | "sourceFile">): StoreMultiWrite[] {
+    const source = new StoreSource({ file, sourceFile });
+    return source.methods.flatMap((method) => {
+      const targets = new Map<ts.CallExpression, StoreCallTarget>();
+      const path = new WritePath((call) => {
+        const target = this.#index.writeOf(source, method, call);
+        if (target) targets.set(call, target);
+        return !!target;
+      });
+      const writes = path.along(method.body);
+      const writeCount = path.countOf(writes);
+      const second = writes[1] ?? writes[0];
+      if (writeCount < 2 || !second) return [];
+      return [
+        {
+          action: method.name,
+          line: sourceFile.getLineAndCharacterOfPosition(second.getStart(sourceFile)).line + 1,
+          writes: writes.map((call) => path.labelOf(call, sourceFile)),
+          writeCount,
+          isRootChain: writes.some((call) => StoreWriteScanner.#crossesStores(targets.get(call), method.store)),
+        },
+      ];
+    });
+  }
+
+  static #crossesStores(target: StoreCallTarget | undefined, ownStore: string) {
+    return (target?.kind === "static" && target.store !== ownStore) || (target?.kind === "action" && !target.isOwn);
+  }
+}

package/testOnlyExportScanner.test.ts

@@ -0,0 +1,83 @@
+import { describe, expect, test } from "bun:test";
+import ts from "typescript";
+import type { SourceFileInfo } from "./qualityScanner";
+import { TestOnlyExportScanner } from "./testOnlyExportScanner";
+
+const fileOf = (file: string, content: string): SourceFileInfo => ({
+  file,
+  absolutePath: `/repo/${file}`,
+  content,
+  sourceFile: ts.createSourceFile(
+    file,
+    content,
+    ts.ScriptTarget.Latest,
+    true,
+    file.endsWith(".tsx") ? ts.ScriptKind.TSX : ts.ScriptKind.TS,
+  ),
+});
+
+const scan = (files: Record<string, string>) =>
+  new TestOnlyExportScanner().scan(Object.entries(files).map(([file, content]) => fileOf(file, content)));
+
+const layout = [
+  "export const groupLabelHeight = 30;",
+  "export const computeGroupBoxes = () => [groupLabelHeight];",
+  "export const groupEdgeStrips = (pad: number): number[] => (pad > 0 ? groupEdgeStrips(pad - 1) : []);",
+  "export const layoutBoard = () => 1;",
+  "",
+].join("\n");
+
+const layoutTest = [
+  'import { computeGroupBoxes, groupEdgeStrips, groupLabelHeight, layoutBoard } from "./boardLayout";',
+  "test(() => [computeGroupBoxes(), groupEdgeStrips(1), groupLabelHeight, layoutBoard()]);",
+  "",
+].join("\n");
+
+describe("TestOnlyExportScanner", () => {
+  test("flags an export only tests reference, even when it calls itself", () => {
+    const warnings = scan({
+      "apps/demo/webkit/boardLayout.ts": layout,
+      "apps/demo/webkit/boardLayout.test.ts": layoutTest,
+      "apps/demo/ui/Board.tsx":
+        'import { layoutBoard } from "@apps/demo/webkit";\nexport const Board = () => layoutBoard();\n',
+    });
+
+    expect(warnings.map((warning) => warning.message)).toEqual([
+      'Exported "computeGroupBoxes" is referenced only by tests: apps/demo/webkit/boardLayout.test.ts.',
+      'Exported "groupEdgeStrips" is referenced only by tests: apps/demo/webkit/boardLayout.test.ts.',
+    ]);
+    expect(warnings[0]).toMatchObject({
+      rule: "akan.global.test-only-export",
+      scope: "global",
+      file: "apps/demo/webkit/boardLayout.ts",
+      line: 2,
+      locations: [{ file: "apps/demo/webkit/boardLayout.test.ts", line: 1 }],
+    });
+  });
+
+  test("passes an export another source file uses, or that a function in its own file uses", () => {
+    const warnings = scan({
+      "apps/demo/webkit/boardLayout.ts": layout,
+      "apps/demo/webkit/boardLayout.test.ts": layoutTest,
+      "apps/demo/ui/Board.tsx": [
+        'import * as webkit from "@apps/demo/webkit";',
+        "export const Board = () => [webkit.computeGroupBoxes(), webkit.groupEdgeStrips(2), webkit.layoutBoard()];",
+        "",
+      ].join("\n"),
+    });
+
+    expect(warnings).toEqual([]);
+  });
+
+  test("passes an export no test references, and leaves lib facets and lib modules alone", () => {
+    expect(
+      scan({
+        "apps/demo/common/unused.ts": "export const unused = 1;\n",
+        "libs/demo/webkit/signedIn.ts": "export const signedIn = () => true;\n",
+        "libs/demo/webkit/signedIn.test.ts": 'import { signedIn } from "./signedIn";\ntest(() => signedIn());\n',
+        "apps/demo/lib/post/post.constant.ts": "export class PostInput {}\n",
+        "apps/demo/lib/post/post.signal.test.ts": "const input = new PostInput();\n",
+      }),
+    ).toEqual([]);
+  });
+});

package/testOnlyExportScanner.ts

@@ -0,0 +1,124 @@
+import ts from "typescript";
+import type { QualityWarning, SourceFileInfo } from "./qualityScanner";
+
+interface ExportedDeclaration {
+  name: string;
+  line: number;
+  statement: ts.Statement;
+}
+
+interface TestReference {
+  file: string;
+  line: number;
+}
+
+export class TestOnlyExportScanner {
+  static readonly rule = "akan.global.test-only-export";
+  static #facets = new Set(["common", "webkit", "srvkit", "ui"]);
+
+  scan(sourceFiles: SourceFileInfo[]): QualityWarning[] {
+    const liveFileNumByName = new Map<string, number>();
+    const testRefsByName = new Map<string, TestReference[]>();
+    for (const { file, sourceFile } of sourceFiles) {
+      const isTest = TestOnlyExportScanner.#isTest(file);
+      for (const [name, line] of TestOnlyExportScanner.#identifierLinesOf(sourceFile)) {
+        if (!isTest) liveFileNumByName.set(name, (liveFileNumByName.get(name) ?? 0) + 1);
+        else if (testRefsByName.has(name)) testRefsByName.get(name)?.push({ file, line });
+        else testRefsByName.set(name, [{ file, line }]);
+      }
+    }
+    return sourceFiles
+      .filter(({ file }) => TestOnlyExportScanner.#isFacetSource(file))
+      .flatMap(({ file, sourceFile }) => {
+        const declarations = TestOnlyExportScanner.#exportedDeclarationsOf(sourceFile);
+        return declarations
+          .filter(({ name }) => (liveFileNumByName.get(name) ?? 0) <= 1)
+          .filter(({ name }) => !TestOnlyExportScanner.#isUsedInFile(sourceFile, name, declarations))
+          .flatMap(({ name, line }) => {
+            const testRefs = testRefsByName.get(name);
+            if (!testRefs?.length) return [];
+            return [
+              {
+                rule: TestOnlyExportScanner.rule,
+                scope: "global" as const,
+                severity: "warning" as const,
+                file,
+                line,
+                message: `Exported "${name}" is referenced only by tests: ${testRefs.map((ref) => ref.file).join(", ")}.`,
+                locations: testRefs,
+              },
+            ];
+          });
+      });
+  }
+
+  static #isTest(file: string) {
+    return /\.(test|spec)\.tsx?$/.test(file);
+  }
+
+  //? A lib's facets are public API for every workspace that installs it, so an export no app here calls is not dead.
+  static #isFacetSource(file: string) {
+    const segments = file.split("/");
+    if (segments[0] !== "apps") return false;
+    return TestOnlyExportScanner.#facets.has(segments[2] ?? "") && !TestOnlyExportScanner.#isTest(file);
+  }
+
+  static #identifierLinesOf(sourceFile: ts.SourceFile) {
+    const lines = new Map<string, number>();
+    const visit = (node: ts.Node) => {
+      if (ts.isIdentifier(node) && !lines.has(node.text))
+        lines.set(node.text, sourceFile.getLineAndCharacterOfPosition(node.getStart(sourceFile)).line + 1);
+      ts.forEachChild(node, visit);
+    };
+    visit(sourceFile);
+    return lines;
+  }
+
+  static #exportedDeclarationsOf(sourceFile: ts.SourceFile): ExportedDeclaration[] {
+    return sourceFile.statements.flatMap((statement) => {
+      if (!TestOnlyExportScanner.#isNamedExport(statement)) return [];
+      return TestOnlyExportScanner.#declaredNamesOf(statement).map((identifier) => ({
+        name: identifier.text,
+        line: sourceFile.getLineAndCharacterOfPosition(identifier.getStart(sourceFile)).line + 1,
+        statement,
+      }));
+    });
+  }
+
+  static #isNamedExport(statement: ts.Statement) {
+    if (!ts.canHaveModifiers(statement)) return false;
+    const modifiers = ts.getModifiers(statement) ?? [];
+    return (
+      modifiers.some((modifier) => modifier.kind === ts.SyntaxKind.ExportKeyword) &&
+      !modifiers.some((modifier) => modifier.kind === ts.SyntaxKind.DefaultKeyword)
+    );
+  }
+
+  static #declaredNamesOf(statement: ts.Statement): ts.Identifier[] {
+    if (ts.isVariableStatement(statement))
+      return statement.declarationList.declarations
+        .map((declaration) => declaration.name)
+        .filter((name): name is ts.Identifier => ts.isIdentifier(name));
+    if (
+      ts.isFunctionDeclaration(statement) ||
+      ts.isClassDeclaration(statement) ||
+      ts.isInterfaceDeclaration(statement) ||
+      ts.isTypeAliasDeclaration(statement) ||
+      ts.isEnumDeclaration(statement)
+    )
+      return statement.name ? [statement.name] : [];
+    return [];
+  }
+
+  static #isUsedInFile(sourceFile: ts.SourceFile, name: string, declarations: ExportedDeclaration[]) {
+    const ownStatements = new Set(declarations.filter((entry) => entry.name === name).map((entry) => entry.statement));
+    let used = false;
+    const visit = (node: ts.Node) => {
+      if (used || ownStatements.has(node as ts.Statement)) return;
+      if (ts.isIdentifier(node) && node.text === name) used = true;
+      else ts.forEachChild(node, visit);
+    };
+    visit(sourceFile);
+    return used;
+  }
+}

package/typeChecker.ts

@@ -13,6 +13,16 @@ export interface ProjectTypecheckResult {
   message: string;
 }
 
+export interface TypecheckRecord {
+  /** Relative to the workspace root, `/`-separated; `null` for a diagnostic tied to no file. */
+  file: string | null;
+  line: number;
+  col: number;
+  code: string;
+  severity: "error" | "warning";
+  message: string;
+}
+
 export class TypeChecker {
   readonly configPath: string;
   readonly configFile: { config?: any; error?: ts.Diagnostic };
@@ -198,6 +208,28 @@ export class TypeChecker {
     return parsedConfig;
   }
 
+  static toRecords(diagnostics: ts.Diagnostic[], root: string): TypecheckRecord[] {
+    return diagnostics
+      .filter(
+        (diagnostic) =>
+          diagnostic.category === ts.DiagnosticCategory.Error || diagnostic.category === ts.DiagnosticCategory.Warning,
+      )
+      .map((diagnostic) => {
+        const position =
+          diagnostic.file && diagnostic.start !== undefined
+            ? diagnostic.file.getLineAndCharacterOfPosition(diagnostic.start)
+            : null;
+        return {
+          file: diagnostic.file ? path.relative(root, diagnostic.file.fileName).split(path.sep).join("/") : null,
+          line: position ? position.line + 1 : 0,
+          col: position ? position.character + 1 : 0,
+          code: `TS${diagnostic.code}`,
+          severity: diagnostic.category === ts.DiagnosticCategory.Error ? "error" : "warning",
+          message: ts.flattenDiagnosticMessageText(diagnostic.messageText, "\n"),
+        };
+      });
+  }
+
   static formatDiagnosticMessages(diagnostics: ts.Diagnostic[]): string {
     return ts.formatDiagnosticsWithColorAndContext(diagnostics, {
       getCanonicalFileName: (fileName) => fileName,

package/typecheck/projectTypecheck.test.ts

@@ -2,6 +2,7 @@ import { describe, expect, test } from "bun:test";
 import path from "node:path";
 import { tempDirs, writeText as write } from "../testHelpers";
 import { ProjectTypecheck } from "./projectTypecheck";
+import { TypecheckFailure } from "./typecheckFailure";
 
 const makeTempRoot = tempDirs("akan-devkit-project-typecheck-");
 
@@ -29,4 +30,21 @@ describe("ProjectTypecheck", () => {
     expect((error as Error).message).toContain("lib/user/user.signal.test.ts");
     expect((error as Error).message).not.toContain("old.test.ts");
   }, 60_000);
+
+  test("hands back one record per diagnostic when asked for records", async () => {
+    const { root, dir } = await project();
+    const error = await new ProjectTypecheck(dir, root, { ...process.env })
+      .run(["../../server.ts"], { tests: true, report: "records" })
+      .catch((e: unknown) => e);
+    expect(error).toBeInstanceOf(TypecheckFailure);
+    const [record, ...rest] = (error as TypecheckFailure).records;
+    expect(rest).toEqual([]);
+    expect(record).toMatchObject({
+      file: "libs/demo/lib/user/user.signal.test.ts",
+      line: 1,
+      col: 14,
+      code: "TS2322",
+      severity: "error",
+    });
+  }, 60_000);
 });