@tanishqkancharla/diffmap 0.3.0 → 0.6.0

package/src/parseViewer.test.ts

@@ -6,8 +6,9 @@ import path from "node:path";
 import { fileURLToPath } from "node:url";
 import { promisify } from "node:util";
 import test from "node:test";
-import { DiffmapMermaidError } from "./errors.js";
+import { DiffmapMermaidError, DiffmapServicesError } from "./errors.js";
 import { parseViewerDocument } from "./parseViewer.js";
+import { serviceStateAt } from "./services.js";
 import { shareMarkdownFile } from "./share.js";
 import { startServer } from "./serve.js";
 
@@ -21,6 +22,17 @@ function brokenMermaidSpec(body = "flwochart TD\n  A --> B") {
   return `# Broken mermaid\n\n\`\`\`mermaid\n${body}\n\`\`\`\n`;
 }
 
+function parseServicesSpec(body: string[], info = "services") {
+  return parseViewerDocument(
+    ["# Flow", "", `\`\`\`${info}`, ...body, "```", ""].join("\n"),
+    "spec.md",
+  );
+}
+
+function codeFenceProblem(lines: string[]) {
+  return String(parseViewerDocument(["```ts", ...lines, "```", ""].join("\n")));
+}
+
 async function withTempSpec(
   source: string,
   run: (filePath: string) => Promise<void>,
@@ -128,13 +140,30 @@ test("parseViewerDocument reads commit references and changes fences", () => {
       "```changes",
       "```",
       "",
+      "```changes",
+      "a1b2c3d",
+      "src/store.ts",
+      "  src/request.ts  ",
+      "```",
+      "",
+      "```changes",
+      "",
+      "src/store.ts",
+      "```",
+      "",
       "See [[a1b2c3d:src/store.ts#L12-L30]] and [[src/store.ts#L3]].",
       "",
     ].join("\n"),
   );
   assert.equal(document instanceof Error, false);
   if (document instanceof Error) return;
-  assert.deepEqual(document.changeRevs, ["a1b2c3d..e4f5a6b", "working"]);
+  // Lines after the rev list files to review in order; a blank rev is uncommitted.
+  assert.deepEqual(document.changeCards, [
+    { rev: "a1b2c3d..e4f5a6b", review: [] },
+    { rev: "working", review: [] },
+    { rev: "a1b2c3d", review: ["src/store.ts", "src/request.ts"] },
+    { rev: "working", review: ["src/store.ts"] },
+  ]);
   assert.deepEqual(document.references, [
     { kind: "file", rev: "a1b2c3d", path: "src/store.ts", start: 12, end: 30 },
     { kind: "file", path: "src/store.ts", start: 3, end: 3 },
@@ -149,6 +178,10 @@ test("parseViewerDocument reads commit references and changes fences", () => {
     parseViewerDocument("```changes\nmain\n```\n") instanceof Error,
     true,
   );
+  assert.match(
+    String(parseViewerDocument("```changes\na1b2c3d\na.ts\na.ts\n```\n")),
+    /lists a\.ts twice/,
+  );
   // The removed patch fence fails instead of rendering as code.
   assert.match(
     String(
@@ -160,6 +193,330 @@ test("parseViewerDocument reads commit references and changes fences", () => {
   );
 });
 
+test("parseViewerDocument reads code highlights and trailing notes", () => {
+  const document = parseViewerDocument(
+    [
+      "```py [src/save.py] {2}",
+      "def save(record):",
+      "    storage.save(record)",
+      "",
+      "# [!note L1-L2] Saves the record.",
+      "# [!note storage.save] Writes `record` to disk.",
+      "```",
+      "",
+    ].join("\n"),
+  );
+  assert.equal(document instanceof Error, false);
+  if (document instanceof Error) return;
+  assert.deepEqual(document.nodes[0], {
+    type: "view",
+    fence: {
+      kind: "code",
+      lang: "py",
+      source: "def save(record):\n    storage.save(record)",
+      highlights: [2],
+      notes: [
+        {
+          target: { kind: "lines", start: 1, end: 2 },
+          text: "Saves the record.",
+        },
+        {
+          target: { kind: "symbol", symbol: "storage.save" },
+          text: "Writes `record` to disk.",
+        },
+      ],
+      title: "src/save.py",
+    },
+  });
+  // Symbols match whole words, so `save` is not found inside `saveAll`.
+  assert.match(
+    codeFenceProblem(["store.saveAll(x);", "// [!note save] Saves."]),
+    /"save" does not appear/,
+  );
+  assert.match(
+    codeFenceProblem(["const x = 1;", "// [!note L1-L2] Too long."]),
+    /outside the 1-line code fence/,
+  );
+  assert.match(
+    String(parseViewerDocument("```ts {3}\nconst x = 1;\n```\n")),
+    /Highlighted line 3 is outside/,
+  );
+  // Call stacks number rows, and a symbol must appear in visible row text.
+  const stack = parseViewerDocument(
+    [
+      "```callstack {2} [Save flow]",
+      " run() [[src/a.ts#run]]",
+      "+└── save(record)",
+      "# [!note save] Writes the record.",
+      "```",
+      "",
+    ].join("\n"),
+  );
+  if (stack instanceof Error) throw stack;
+  const fence =
+    stack.nodes[0]?.type === "view" ? stack.nodes[0].fence : undefined;
+  assert.equal(fence?.kind, "callstack");
+  if (fence?.kind !== "callstack") return;
+  assert.equal(fence.lines.length, 2);
+  assert.deepEqual(fence.highlights, [2]);
+  assert.equal(fence.title, "Save flow");
+  const mdc = parseViewerDocument(
+    '::callstack{title="Save flow"}\n run()\n└── save(record)\n::\n',
+  );
+  if (mdc instanceof Error) throw mdc;
+  assert.deepEqual(
+    mdc.nodes[0]?.type === "view" && mdc.nodes[0].fence.kind === "callstack"
+      ? mdc.nodes[0].fence.title
+      : undefined,
+    "Save flow",
+  );
+  assert.deepEqual(fence.notes, [
+    { target: { kind: "symbol", symbol: "save" }, text: "Writes the record." },
+  ]);
+  assert.match(
+    String(
+      parseViewerDocument(
+        "```callstack\n run() [[src/a.ts#Store.save]]\n# [!note save] Hidden.\n```\n",
+      ),
+    ),
+    /"save" does not appear/,
+  );
+});
+
+test("parseViewerDocument reads services, steps, and their references", () => {
+  const document = parseViewerDocument(
+    [
+      "```services",
+      "service API [[src/api.ts]]",
+      "  > Routes requests.",
+      "  service Auth",
+      "    state attempts = 0",
+      "      > Failures since the last success.",
+      "      > Five locks the account.",
+      "service Store",
+      "  state rows = none",
+      "",
+      'start "Alice has not logged in"',
+      "  > No rows yet.",
+      'step "Verify"',
+      "  API -> Auth: verify(alice) [[src/api.ts#login]]",
+      "    > Sends the password hash.",
+      "  Auth.attempts = 1",
+      "    > One failure so far.",
+      'step "Auth stores the row"',
+      "  Auth -> Store: insert",
+      "  Store.rows = 1 row",
+      "  Auth.attempts = 0",
+      "```",
+      "",
+    ].join("\n"),
+  );
+  assert.equal(document instanceof Error, false);
+  if (document instanceof Error) return;
+  const fence = document.nodes[0];
+  assert.equal(fence?.type === "view" && fence.fence.kind, "services");
+  if (fence?.type !== "view" || fence.fence.kind !== "services") return;
+  assert.equal(fence.fence.parsed.ok, true);
+  if (!fence.fence.parsed.ok) return;
+  const diagram = fence.fence.parsed.diagram;
+  // Dedenting after Auth's state closes both Auth and API.
+  assert.deepEqual(
+    diagram.services.map((service) => [
+      service.name,
+      service.children.map((child) => child.name),
+    ]),
+    [
+      ["API", ["Auth"]],
+      ["Store", []],
+    ],
+  );
+  // A description belongs to the line above it and joins continued lines.
+  assert.equal(diagram.services[0]!.description, "Routes requests.");
+  assert.deepEqual(diagram.start, {
+    caption: "Alice has not logged in",
+    description: "No rows yet.",
+  });
+  assert.equal(
+    diagram.services[0]!.children[0]!.state[0]!.description,
+    "Failures since the last success. Five locks the account.",
+  );
+  assert.equal(diagram.steps[0]!.events[0]!.note, "Sends the password hash.");
+  assert.equal(diagram.steps[0]!.updates[0]!.note, "One failure so far.");
+  assert.equal(diagram.steps[1]!.updates[0]!.note, undefined);
+  const at = (step: number) =>
+    Object.fromEntries(
+      [...serviceStateAt(diagram, step)].map(([name, state]) => [
+        name,
+        Object.fromEntries(state),
+      ]),
+    );
+  assert.deepEqual(at(0), {
+    API: {},
+    Auth: { attempts: "0" },
+    Store: { rows: "none" },
+  });
+  assert.deepEqual(at(1), {
+    API: {},
+    Auth: { attempts: "1" },
+    Store: { rows: "none" },
+  });
+  assert.deepEqual(at(2), {
+    API: {},
+    Auth: { attempts: "0" },
+    Store: { rows: "1 row" },
+  });
+  assert.deepEqual(document.references, [
+    { kind: "file", path: "src/api.ts" },
+    { kind: "file", path: "src/api.ts", symbol: "login" },
+  ]);
+});
+
+test("a services diff replays Today and Proposed separately", () => {
+  const document = parseViewerDocument(
+    [
+      "```services diff",
+      " service API",
+      "-  state count = 0",
+      "+  state count = 1",
+      "-service Cache",
+      "   state hits = 0",
+      "+service Queue",
+      "+  state jobs = 0",
+      "",
+      ' step "Handle"',
+      "-  API -> Cache: get",
+      "+  API -> Queue: push",
+      "-  Cache.hits = 1",
+      "+  Queue.jobs = 1",
+      "   API.count = 5",
+      '-step "Old cleanup"',
+      "   API.count = 9",
+      "```",
+      "",
+    ].join("\n"),
+  );
+  if (document instanceof Error) throw document;
+  const fence = document.nodes[0];
+  if (fence?.type !== "view" || fence.fence.kind !== "services")
+    throw new Error("expected a services fence");
+  if (!fence.fence.parsed.ok) throw new Error(fence.fence.parsed.reason);
+  const diagram = fence.fence.parsed.diagram;
+  // Unmarked lines inside a removed service or step take its sign.
+  assert.equal(diagram.services[1]!.state[0]!.sign, "-");
+  assert.equal(diagram.steps[1]!.updates[0]!.sign, "-");
+  assert.deepEqual(
+    diagram.steps[0]!.events.map((event) => event.sign),
+    ["-", "+"],
+  );
+  const at = (step: number, side: "today" | "proposed") =>
+    Object.fromEntries(
+      [...serviceStateAt(diagram, step, side)].map(([name, state]) => [
+        name,
+        Object.fromEntries(state),
+      ]),
+    );
+  // A - and a + declaration of one key give each side its own start value.
+  assert.deepEqual(at(0, "today"), {
+    API: { count: "0" },
+    Cache: { hits: "0" },
+    Queue: {},
+  });
+  assert.deepEqual(at(0, "proposed"), {
+    API: { count: "1" },
+    Cache: {},
+    Queue: { jobs: "0" },
+  });
+  assert.deepEqual(at(2, "today"), {
+    API: { count: "9" },
+    Cache: { hits: "1" },
+    Queue: {},
+  });
+  assert.deepEqual(at(2, "proposed"), {
+    API: { count: "5" },
+    Cache: {},
+    Queue: { jobs: "1" },
+  });
+});
+
+test("a services diff rejects unmarked lines and contradictory signs", () => {
+  assert.match(
+    String(
+      parseServicesSpec([" service API", "service Store"], "services diff"),
+    ),
+    /line 5\): Start every line of a services diff/,
+  );
+  assert.match(
+    String(
+      parseServicesSpec(
+        [" service API", '-step "Old"', "+  API -> API: new"],
+        "services diff",
+      ),
+    ),
+    /line 6\): A \+ line can't sit inside a removed step/,
+  );
+});
+
+test("a mermaid diff keeps every line and splits out each side", () => {
+  const document = parseViewerDocument(
+    [
+      "```mermaid diff [Request flow]",
+      " flowchart LR",
+      "-  A --> B[Old]",
+      "+  A --> B[New]",
+      "+  A --> C",
+      "   %% ref node:A [[src/a.ts]]",
+      "```",
+      "",
+    ].join("\n"),
+  );
+  if (document instanceof Error) throw document;
+  const fence = document.nodes[0];
+  if (fence?.type !== "view" || fence.fence.kind !== "mermaid")
+    throw new Error("expected a mermaid fence");
+  // Mermaid keeps a node's first label, so a change's + lines come first.
+  assert.equal(
+    fence.fence.source,
+    "flowchart LR\n  A --> B[New]\n  A --> C\n  A --> B[Old]\n  %% ref node:A [[src/a.ts]]",
+  );
+  assert.deepEqual(fence.fence.sides, {
+    today: "flowchart LR\n  A --> B[Old]\n  %% ref node:A [[src/a.ts]]",
+    proposed:
+      "flowchart LR\n  A --> B[New]\n  A --> C\n  %% ref node:A [[src/a.ts]]",
+  });
+  assert.equal(fence.fence.annotations.length, 1);
+  assert.equal(fence.fence.title, "Request flow");
+});
+
+test("parseViewerDocument fails on services errors with the file line", () => {
+  const unknown = parseServicesSpec([
+    "service API",
+    "",
+    'step "Say hi"',
+    "  API -> Auth: hi",
+  ]);
+  assert.equal(unknown instanceof DiffmapServicesError, true);
+  assert.match(String(unknown), /spec\.md \(line 7\): Unknown service Auth/);
+  const undeclared = parseServicesSpec([
+    "service API",
+    'step "Count"',
+    "  API.count = 1",
+  ]);
+  assert.match(String(undeclared), /line 6\): API has no state count/);
+  const uncaptioned = parseServicesSpec(["service API", "step"]);
+  assert.match(String(uncaptioned), /line 5\): Give the step a caption/);
+  const lateStart = parseServicesSpec([
+    "service API",
+    'step "Go"',
+    'start "Too late"',
+  ]);
+  assert.match(
+    String(lateStart),
+    /line 6\): Write one start line, before the first step/,
+  );
+  const orphan = parseServicesSpec(["service API", "> Not indented."]);
+  assert.match(String(orphan), /line 5\): Put a > line directly below/);
+});
+
 test("parseViewerDocument fails on broken mermaid with file and diagram", () => {
   const source = brokenMermaidSpec();
   const parsed = parseViewerDocument(source, "broken.md");

package/src/parseViewer.ts

@@ -8,19 +8,28 @@ import {
   type SourceReference,
 } from "./annotations.js";
 import { isRev, type Rev } from "./changes.js";
-import { DiffmapAnnotationError, DiffmapParseError } from "./errors.js";
+import { notesProblem } from "./codeNotes.js";
+import {
+  DiffmapAnnotationError,
+  DiffmapParseError,
+  DiffmapServicesError,
+} from "./errors.js";
 import { parseMermaidDiagram } from "./mermaid.js";
 import { parseFence, type Fence } from "./parseFence.js";
+import { serviceAnnotations } from "./services.js";
 
 export type ViewerDocument = {
   nodes: ViewerNode[];
   headings: ViewerHeading[];
   /** Every reference in stacks, diagrams, and prose. */
   references: SourceReference[];
-  /** Revs of `changes` fences, in document order. */
-  changeRevs: Rev[];
+  /** `changes` fences, in document order. */
+  changeCards: ChangeCard[];
 };
 
+/** A `changes` fence's rev and the paths it lists to review first. */
+export type ChangeCard = { rev: Rev; review: string[] };
+
 export type ViewerHeading = {
   level: 1 | 2 | 3 | 4 | 5 | 6;
   text: string;
@@ -75,6 +84,8 @@ export type ViewerElementAttrs = {
   task: boolean | undefined;
   alertType: string | undefined;
   align: string | undefined;
+  /** The label of an MDC `::details{summary="…"}` toggle. */
+  summary: string | undefined;
 };
 
 export function parseViewerDocument(source: string, path = "spec") {
@@ -85,41 +96,89 @@ export function parseViewerDocument(source: string, path = "spec") {
   if (tree instanceof Error) return tree;
   const nodes = tree.nodes.flatMap((node) => fromNode(node));
   const fences = collectFences(nodes);
-  const changeRevs: Rev[] = [];
+  const changeCards: ChangeCard[] = [];
   for (const fence of fences) {
     if (fence.kind === "code" && fence.lang.startsWith("source-diff")) {
       return new DiffmapAnnotationError({
         reason: `"${fence.lang}" fences were removed. Commit the change, then use a changes fence with the commit SHA and link lines with [[<sha>:path#L12-L30]]`,
       });
     }
+    if (fence.kind === "code" || fence.kind === "callstack") {
+      const problem = notesProblem({
+        // Call stack symbols must appear in the row text readers see, not in a hidden [[reference]].
+        lines:
+          fence.kind === "code"
+            ? fence.source.split("\n")
+            : fence.lines.map((line) => line.text),
+        highlights: fence.highlights,
+        notes: fence.notes,
+      });
+      if (problem !== undefined)
+        return new DiffmapAnnotationError({ reason: problem });
+      continue;
+    }
     if (fence.kind !== "changes") continue;
     if (!isRev(fence.rev)) {
       return new DiffmapAnnotationError({
         reason: `Invalid changes "${fence.rev}". Use a commit SHA, a SHA range (a1b2c3d..e4f5a6b), or leave it empty for uncommitted changes`,
       });
     }
-    changeRevs.push(fence.rev);
+    const duplicate = fence.review.find(
+      (reviewPath, index) => fence.review.indexOf(reviewPath) !== index,
+    );
+    if (duplicate !== undefined) {
+      return new DiffmapAnnotationError({
+        reason: `changes "${fence.rev}" lists ${duplicate} twice. List each file to review once`,
+      });
+    }
+    changeCards.push({ rev: fence.rev, review: fence.review });
   }
   const annotations = [
     ...fences.flatMap((fence) => {
       if (fence.kind === "callstack") return fence.lines;
       if (fence.kind === "mermaid")
         return fence.annotations.map((link) => link.annotation);
+      if (fence.kind === "services" && fence.parsed.ok)
+        return serviceAnnotations(fence.parsed.diagram);
       return [];
     }),
     ...collectReferences(nodes),
   ];
+  const servicesFences = fences.flatMap((fence) =>
+    fence.kind === "services" ? [fence] : [],
+  );
+  for (const [offset, fence] of servicesFences.entries()) {
+    if (fence.parsed.ok) continue;
+    const start = fenceLine(source, "services", offset + 1);
+    return new DiffmapServicesError({
+      path,
+      where:
+        start === undefined
+          ? `diagram ${offset + 1}, line ${fence.parsed.line}`
+          : `line ${start + fence.parsed.line}`,
+      reason: fence.parsed.reason,
+    });
+  }
   const mermaidFences = fences.flatMap((fence) =>
     fence.kind === "mermaid" ? [fence] : [],
   );
   for (const [offset, fence] of mermaidFences.entries()) {
     const mermaidIndex = offset + 1;
-    const parsedMermaid = parseMermaidDiagram({
-      source: fence.source,
-      path,
-      where: mermaidWhere(source, mermaidIndex),
-    });
-    if (parsedMermaid instanceof Error) return parsedMermaid;
+    const where = mermaidWhere(source, mermaidIndex);
+    // A diff draws every line, and each side must also stand on its own.
+    for (const [side, diagram] of [
+      ["", fence.source],
+      [", Today side", fence.sides?.today],
+      [", Proposed side", fence.sides?.proposed],
+    ] as const) {
+      if (diagram === undefined) continue;
+      const parsedMermaid = parseMermaidDiagram({
+        source: diagram,
+        path,
+        where: `${where}${side}`,
+      });
+      if (parsedMermaid instanceof Error) return parsedMermaid;
+    }
     const targets = new Set<string>();
     for (const link of fence.annotations) {
       const target = `${link.target}:${link.id}`;
@@ -164,7 +223,7 @@ export function parseViewerDocument(source: string, path = "spec") {
     nodes,
     headings: collectHeadings(nodes),
     references: annotations.flatMap((annotation) => annotation.references),
-    changeRevs,
+    changeCards,
   };
 }
 
@@ -185,15 +244,18 @@ function collectReferences(nodes: ViewerNode[]): SourceAnnotation[] {
 }
 
 function mermaidWhere(source: string, index: number) {
-  const line = mermaidFenceLine(source, index);
+  const line = fenceLine(source, "mermaid", index);
   if (line === undefined) return `diagram ${index}`;
   return `diagram ${index}, line ${line}`;
 }
 
-function mermaidFenceLine(source: string, index: number) {
-  const match = [...source.matchAll(/^[ \t]*(`{3,}mermaid\b|::mermaid\b)/gm)][
-    index - 1
-  ];
+/** Line of the `index`th (1-based) fence or MDC block named `lang`. */
+function fenceLine(source: string, lang: string, index: number) {
+  const pattern = new RegExp(
+    String.raw`^[ \t]*(\`{3,}${lang}\b|::${lang}\b)`,
+    "gm",
+  );
+  const match = [...source.matchAll(pattern)][index - 1];
   if (match === undefined || match.index === undefined) return undefined;
   return source.slice(0, match.index).split("\n").length;
 }
@@ -323,15 +385,34 @@ function fromElement(
   if (tag === "template")
     return children.flatMap((child) => fromNode(child, literalChildren));
   if (tag === "pre") {
-    return fenceView(stringAttr(element, "language"), comarkText(children));
+    // md4x parses ```ts [src/request.ts] into `filename`; diffmap shows it as the title.
+    return fenceView(
+      stringAttr(element, "language"),
+      comarkText(children),
+      highlightsAttr(element),
+      stringAttr(element, "filename"),
+      stringAttr(element, "meta"),
+    );
   }
-  if (tag === "mermaid") return fenceView("mermaid", comarkText(children));
-  if (tag === "callstack") return fenceView("callstack", comarkText(children));
-  if (tag === "changes")
+  if (tag === "mermaid")
     return fenceView(
-      "changes",
-      stringAttr(element, "rev") ?? comarkText(children),
+      "mermaid",
+      comarkText(children),
+      undefined,
+      stringAttr(element, "title"),
     );
+  if (tag === "callstack")
+    return fenceView(
+      "callstack",
+      comarkText(children),
+      undefined,
+      stringAttr(element, "title"),
+    );
+  if (tag === "changes") {
+    const rev = stringAttr(element, "rev");
+    const body = comarkText(children);
+    return fenceView("changes", rev === undefined ? body : `${rev}\n${body}`);
+  }
   if (tag === "diff") {
     const path = stringAttr(element, "path");
     const lang = path === undefined ? "diff" : `diff:${path}`;
@@ -366,10 +447,22 @@ function unwrapTaskParagraph(children: ViewerNode[]): ViewerNode[] {
   return children;
 }
 
-function fenceView(lang: string | undefined, source: string): ViewerView {
+function fenceView(
+  lang: string | undefined,
+  source: string,
+  highlights?: number[],
+  title?: string,
+  meta?: string,
+): ViewerView {
   return {
     type: "view",
-    fence: parseFence(lang === undefined ? "" : lang, source),
+    fence: parseFence(
+      lang === undefined ? "" : lang,
+      source,
+      highlights,
+      title,
+      meta,
+    ),
   };
 }
 
@@ -420,6 +513,7 @@ function elementAttrs(element: ComarkElement): ViewerElementAttrs {
     task: element[1].task === true ? true : undefined,
     alertType: stringAttr(element, "type"),
     align: stringAttr(element, "align"),
+    summary: stringAttr(element, "summary"),
   };
 }
 
@@ -430,6 +524,13 @@ function stringAttr(element: ComarkElement, key: string) {
   return value as string;
 }
 
+/** md4x parses ```ts {2,4-5} into `highlights: [2, 4, 5]`. */
+function highlightsAttr(element: ComarkElement) {
+  const value = element[1].highlights;
+  if (!Array.isArray(value)) return undefined;
+  return value.filter((line): line is number => typeof line === "number");
+}
+
 function lineAttr(element: ComarkElement, key: string) {
   const value = stringAttr(element, key);
   if (value === undefined) return undefined;

package/src/serve.test.ts

@@ -7,7 +7,7 @@ import path from "node:path";
 import { fileURLToPath } from "node:url";
 import { promisify } from "node:util";
 import { setTimeout as delay } from "node:timers/promises";
-import test from "node:test";
+import test, { before } from "node:test";
 import { DiffmapServeError } from "./errors.js";
 import { startServer, type DiffmapServer } from "./serve.js";
 
@@ -92,6 +92,27 @@ async function waitForClosed(server: DiffmapServer, timeoutMs = 10_000) {
   ]);
 }
 
+// These tests run several servers at once. On a cold or stale cache each one
+// prebundles dependencies on its own, at over 1 GB each, which can exhaust the
+// machine's memory. Vite holds requests for a prebundled file until the bundle
+// is on disk, so fetching one here leaves a warm cache for the servers below.
+before(async () => {
+  const server = assertStarted(
+    await startServer({ filePath: sampleSpec, workspaceRoot: packageRoot }),
+  );
+  try {
+    const entry = await fetch(`${server.url}/src/viewer/main.tsx`);
+    const dep = /"(\/node_modules\/\.vite\/deps\/[^"]+)"/.exec(
+      await entry.text(),
+    )?.[1];
+    assert.ok(dep !== undefined, "viewer entry imports no prebundled module");
+    assert.equal((await fetch(`${server.url}${dep}`)).ok, true);
+  } finally {
+    await server.shutdown();
+    await waitForClosed(server);
+  }
+});
+
 test(
   "startServer binds distinct free ports when 4177 is taken",
   { timeout: 90_000 },