@tanishqkancharla/diffmap 0.4.0 → 0.6.0

package/src/parseViewer.test.ts

@@ -22,9 +22,9 @@ function brokenMermaidSpec(body = "flwochart TD\n  A --> B") {
   return `# Broken mermaid\n\n\`\`\`mermaid\n${body}\n\`\`\`\n`;
 }
 
-function parseServicesSpec(body: string[]) {
+function parseServicesSpec(body: string[], info = "services") {
   return parseViewerDocument(
-    ["# Flow", "", "```services", ...body, "```", ""].join("\n"),
+    ["# Flow", "", `\`\`\`${info}`, ...body, "```", ""].join("\n"),
     "spec.md",
   );
 }
@@ -196,7 +196,7 @@ test("parseViewerDocument reads commit references and changes fences", () => {
 test("parseViewerDocument reads code highlights and trailing notes", () => {
   const document = parseViewerDocument(
     [
-      "```py {2}",
+      "```py [src/save.py] {2}",
       "def save(record):",
       "    storage.save(record)",
       "",
@@ -225,6 +225,7 @@ test("parseViewerDocument reads code highlights and trailing notes", () => {
           text: "Writes `record` to disk.",
         },
       ],
+      title: "src/save.py",
     },
   });
   // Symbols match whole words, so `save` is not found inside `saveAll`.
@@ -243,7 +244,7 @@ test("parseViewerDocument reads code highlights and trailing notes", () => {
   // Call stacks number rows, and a symbol must appear in visible row text.
   const stack = parseViewerDocument(
     [
-      "```callstack {2}",
+      "```callstack {2} [Save flow]",
       " run() [[src/a.ts#run]]",
       "+└── save(record)",
       "# [!note save] Writes the record.",
@@ -258,6 +259,17 @@ test("parseViewerDocument reads code highlights and trailing notes", () => {
   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." },
   ]);
@@ -284,6 +296,8 @@ test("parseViewerDocument reads services, steps, and their references", () => {
       "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.",
@@ -318,6 +332,10 @@ test("parseViewerDocument reads services, steps, and their references", () => {
   );
   // 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.",
@@ -353,6 +371,122 @@ test("parseViewerDocument reads services, steps, and their references", () => {
   ]);
 });
 
+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",
@@ -370,6 +504,15 @@ test("parseViewerDocument fails on services errors with the file line", () => {
   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/);
 });

package/src/parseViewer.ts

@@ -84,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") {
@@ -162,12 +164,21 @@ export function parseViewerDocument(source: string, path = "spec") {
   );
   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}`;
@@ -374,14 +385,29 @@ function fromElement(
   if (tag === "template")
     return children.flatMap((child) => fromNode(child, literalChildren));
   if (tag === "pre") {
+    // 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 === "mermaid")
+    return fenceView(
+      "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);
@@ -425,10 +451,18 @@ function fenceView(
   lang: string | undefined,
   source: string,
   highlights?: number[],
+  title?: string,
+  meta?: string,
 ): ViewerView {
   return {
     type: "view",
-    fence: parseFence(lang === undefined ? "" : lang, source, highlights),
+    fence: parseFence(
+      lang === undefined ? "" : lang,
+      source,
+      highlights,
+      title,
+      meta,
+    ),
   };
 }
 
@@ -479,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"),
   };
 }
 

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 },

package/src/services.ts

@@ -7,9 +7,22 @@ import { parseAnnotation, type SourceAnnotation } from "./annotations.js";
  */
 export type ServiceDiagram = {
   services: Service[];
+  /** From `start "caption"`: what the declared state shows, before step 1. */
+  start: { caption: string; description: string | undefined } | undefined;
   steps: ServiceStep[];
+  /** From ```services diff: items carry `+` or `-` signs. */
+  diff: boolean;
 };
 
+/**
+ * In a `services diff`, `-` marks an item that exists only Today and `+` one
+ * that exists only in the Proposed version. Items inherit the sign of the
+ * service or step they sit in.
+ */
+export type Sign = "+" | "-" | " ";
+
+export type Side = "today" | "proposed";
+
 export type Service = {
   name: string;
   label: string | undefined;
@@ -17,12 +30,17 @@ export type Service = {
   state: ServiceState[];
   children: Service[];
   annotation: SourceAnnotation | undefined;
+  sign: Sign;
 };
 
 export type ServiceState = {
   key: string;
+  /** The Proposed initial value. */
   value: string;
+  /** Set when a `-` and a `+` line declare the key with different values. */
+  todayValue: string | undefined;
   description: string | undefined;
+  sign: Sign;
 };
 
 export type ServiceStep = {
@@ -31,6 +49,7 @@ export type ServiceStep = {
   description: string | undefined;
   events: ServiceEvent[];
   updates: ServiceUpdate[];
+  sign: Sign;
 };
 
 export type ServiceEvent = {
@@ -40,6 +59,7 @@ export type ServiceEvent = {
   /** Shown beside the event's label while its step is current. */
   note: string | undefined;
   annotation: SourceAnnotation | undefined;
+  sign: Sign;
 };
 
 export type ServiceUpdate = {
@@ -48,6 +68,7 @@ export type ServiceUpdate = {
   value: string;
   /** Shown beside the changed state while its step is current. */
   note: string | undefined;
+  sign: Sign;
 };
 
 export type ServicesParse =
@@ -60,6 +81,7 @@ const serviceLine = new RegExp(
 );
 const stateLine = new RegExp(String.raw`^state\s+(${name})\s*=\s*(.+)$`);
 const stepLine = /^step\b(?:\s+"([^"]*)")?\s*$/;
+const startLine = /^start\b(?:\s+"([^"]*)")?\s*$/;
 const eventLine = new RegExp(
   String.raw`^(${name})\s*->\s*(${name})(?:\s*:\s*(.*))?$`,
 );
@@ -77,10 +99,14 @@ const updateLine = new RegExp(String.raw`^(${name})\.(${name})\s*=\s*(.+)$`);
  *   Auth.attempts = 1
  * ```
  */
-export function parseServiceDiagram(source: string): ServicesParse {
+export function parseServiceDiagram(
+  source: string,
+  diff = false,
+): ServicesParse {
   const services: Service[] = [];
   const byName = new Map<string, Service>();
   const steps: ServiceStep[] = [];
+  let start: ServiceDiagram["start"];
   // Open services, innermost last, with the indent of their `service` line.
   const open: { indent: number; service: Service }[] = [];
   // Where a `>` line's text goes: a description on a service, state, or
@@ -104,16 +130,35 @@ export function parseServiceDiagram(source: string): ServicesParse {
     };
   };
   const lines = source.split("\n");
-  for (const [index, raw] of lines.entries()) {
+  for (const [index, row] of lines.entries()) {
     const line = index + 1;
     const fail = (reason: string): ServicesParse => ({
       ok: false,
       line,
       reason,
     });
+    if (row.trim().length === 0 || row.trim().startsWith("%%")) continue;
+    // A diff's first column is its sign, so indentation counts from column 1.
+    if (diff && !/^[+ -]/.test(row))
+      return fail("Start every line of a services diff with +, -, or a space.");
+    // SAFETY: the test above limits a diff row's first character to a Sign.
+    const own: Sign = diff ? (row[0] as Sign) : " ";
+    const raw = diff ? row.slice(1) : row;
     const text = raw.trim();
-    if (text.length === 0 || text.startsWith("%%")) continue;
+    if (text.length === 0) continue;
     const indent = raw.replace(/\t/g, "  ").search(/\S/);
+    // An item takes the sign of the service or step it sits in.
+    const signWithin = (
+      container: { sign: Sign } | undefined,
+      kind: string,
+    ) => {
+      const outer = container?.sign ?? " ";
+      if (outer === " " || own === " " || own === outer)
+        return outer === " " ? own : outer;
+      return fail(
+        `A ${own} line can't sit inside a ${outer === "-" ? "removed" : "added"} ${kind}.`,
+      );
+    };
     if (text.startsWith(">")) {
       if (described === undefined || indent <= described.indent)
         return fail(
@@ -135,6 +180,8 @@ export function parseServiceDiagram(source: string): ServicesParse {
       if (byName.has(serviceName))
         return fail(`Service ${serviceName} is declared twice.`);
       while (open.length > 0 && open.at(-1)!.indent >= indent) open.pop();
+      const sign = signWithin(open.at(-1)?.service, "service");
+      if (typeof sign !== "string") return sign;
       const service: Service = {
         name: serviceName,
         label: serviceMatch[2],
@@ -145,6 +192,7 @@ export function parseServiceDiagram(source: string): ServicesParse {
           annotation === undefined
             ? undefined
             : { ...annotation, text: serviceName },
+        sign,
       };
       (open.at(-1)?.service.children ?? services).push(service);
       byName.set(serviceName, service);
@@ -164,18 +212,54 @@ export function parseServiceDiagram(source: string): ServicesParse {
       if (owner === undefined)
         return fail("Indent state under the service that owns it.");
       const key = stateMatch[1]!;
-      if (owner.state.some((entry) => entry.key === key))
-        return fail(`${owner.name}.${key} is declared twice.`);
-      const entry = {
+      const value = stateMatch[2]!.trim();
+      const sign = signWithin(owner, "service");
+      if (typeof sign !== "string") return sign;
+      const declared = owner.state.find((entry) => entry.key === key);
+      if (declared !== undefined) {
+        // A `-` and a `+` declaration of one key change its initial value.
+        if (
+          declared.todayValue !== undefined ||
+          declared.sign === " " ||
+          sign === " " ||
+          declared.sign === sign
+        )
+          return fail(`${owner.name}.${key} is declared twice.`);
+        declared.todayValue = declared.sign === "-" ? declared.value : value;
+        declared.value = declared.sign === "+" ? declared.value : value;
+        declared.sign = " ";
+        describe(indent, declared);
+        continue;
+      }
+      const entry: ServiceState = {
         key,
-        value: stateMatch[2]!.trim(),
+        value,
+        todayValue: undefined,
         description: undefined,
+        sign,
       };
       owner.state.push(entry);
       describe(indent, entry);
       continue;
     }
 
+    const startMatch = startLine.exec(text);
+    if (startMatch !== null) {
+      if (indent !== 0) return fail("Start the start line at column 0.");
+      if (step !== undefined || start !== undefined)
+        return fail("Write one start line, before the first step.");
+      if (own !== " ")
+        return fail("The start line describes both versions; drop its sign.");
+      const caption = startMatch[1]?.trim();
+      if (caption === undefined || caption === "")
+        return fail(
+          'Give the start a caption that says what the initial state shows, like start "Alice is signed out".',
+        );
+      start = { caption, description: undefined };
+      describe(indent, start);
+      continue;
+    }
+
     const stepMatch = stepLine.exec(text);
     if (stepMatch !== null) {
       if (indent !== 0) return fail("Start step lines at column 0.");
@@ -189,6 +273,7 @@ export function parseServiceDiagram(source: string): ServicesParse {
         description: undefined,
         events: [],
         updates: [],
+        sign: own,
       };
       steps.push(next);
       describe(indent, next);
@@ -201,6 +286,8 @@ export function parseServiceDiagram(source: string): ServicesParse {
         for (const service of [event[1]!, event[2]!])
           if (!byName.has(service)) return fail(`Unknown service ${service}.`);
         const label = (event[3] ?? "").trim();
+        const sign = signWithin(step, "step");
+        if (typeof sign !== "string") return sign;
         const entry: ServiceEvent = {
           from: event[1]!,
           to: event[2]!,
@@ -213,6 +300,7 @@ export function parseServiceDiagram(source: string): ServicesParse {
                   ...annotation,
                   text: `${event[1]} → ${event[2]}${label === "" ? "" : `: ${label}`}`,
                 },
+          sign,
         };
         step.events.push(entry);
         annotate(indent, entry);
@@ -226,11 +314,14 @@ export function parseServiceDiagram(source: string): ServicesParse {
           return fail(
             `${owner.name} has no state ${update[2]}. Declare it with state ${update[2]} = <initial value>.`,
           );
+        const sign = signWithin(step, "step");
+        if (typeof sign !== "string") return sign;
         const entry: ServiceUpdate = {
           service: owner.name,
           key: update[2]!,
           value: update[3]!.trim(),
           note: undefined,
+          sign,
         };
         step.updates.push(entry);
         annotate(indent, entry);
@@ -242,12 +333,12 @@ export function parseServiceDiagram(source: string): ServicesParse {
     }
 
     return fail(
-      `Expected service <Name>, state <key> = <value>, or step "<caption>", got "${text}".`,
+      `Expected service <Name>, state <key> = <value>, start "<caption>", or step "<caption>", got "${text}".`,
     );
   }
   if (services.length === 0)
     return { ok: false, line: 1, reason: "Declare at least one service." };
-  return { ok: true, diagram: { services, steps } };
+  return { ok: true, diagram: { services, start, steps, diff } };
 }
 
 /** Every service in declaration order, with its parent. */
@@ -261,17 +352,33 @@ export function flattenServices(
   ]);
 }
 
-/** State after the first `step` steps; step 0 is the declared state. */
-export function serviceStateAt(diagram: ServiceDiagram, step: number) {
+/**
+ * State after the first `step` steps; step 0 is the declared state. In a
+ * diff, Today skips `+` items and Proposed skips `-` items.
+ */
+export function serviceStateAt(
+  diagram: ServiceDiagram,
+  step: number,
+  side: Side = "proposed",
+) {
+  const skip: Sign = side === "today" ? "+" : "-";
   const state = new Map(
     flattenServices(diagram.services).map(({ service }) => [
       service.name,
-      new Map(service.state.map((entry) => [entry.key, entry.value])),
+      new Map(
+        service.state
+          .filter((entry) => entry.sign !== skip)
+          .map((entry) => [
+            entry.key,
+            side === "today" ? (entry.todayValue ?? entry.value) : entry.value,
+          ]),
+      ),
     ]),
   );
   for (const { updates } of diagram.steps.slice(0, step))
     for (const update of updates)
-      state.get(update.service)!.set(update.key, update.value);
+      if (update.sign !== skip)
+        state.get(update.service)!.set(update.key, update.value);
   return state;
 }