@tanishqkancharla/diffmap 0.3.0 → 0.4.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[]) {
+  return parseViewerDocument(
+    ["# Flow", "", "```services", ...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,187 @@ test("parseViewerDocument reads commit references and changes fences", () => {
   );
 });
 
+test("parseViewerDocument reads code highlights and trailing notes", () => {
+  const document = parseViewerDocument(
+    [
+      "```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.",
+        },
+      ],
+    },
+  });
+  // 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}",
+      " 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.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",
+      "",
+      '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.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("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 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;
@@ -85,30 +94,69 @@ 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] : [],
   );
@@ -164,7 +212,7 @@ export function parseViewerDocument(source: string, path = "spec") {
     nodes,
     headings: collectHeadings(nodes),
     references: annotations.flatMap((annotation) => annotation.references),
-    changeRevs,
+    changeCards,
   };
 }
 
@@ -185,15 +233,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 +374,19 @@ function fromElement(
   if (tag === "template")
     return children.flatMap((child) => fromNode(child, literalChildren));
   if (tag === "pre") {
-    return fenceView(stringAttr(element, "language"), comarkText(children));
+    return fenceView(
+      stringAttr(element, "language"),
+      comarkText(children),
+      highlightsAttr(element),
+    );
   }
   if (tag === "mermaid") return fenceView("mermaid", comarkText(children));
   if (tag === "callstack") return fenceView("callstack", comarkText(children));
-  if (tag === "changes")
-    return fenceView(
-      "changes",
-      stringAttr(element, "rev") ?? comarkText(children),
-    );
+  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 +421,14 @@ function unwrapTaskParagraph(children: ViewerNode[]): ViewerNode[] {
   return children;
 }
 
-function fenceView(lang: string | undefined, source: string): ViewerView {
+function fenceView(
+  lang: string | undefined,
+  source: string,
+  highlights?: number[],
+): ViewerView {
   return {
     type: "view",
-    fence: parseFence(lang === undefined ? "" : lang, source),
+    fence: parseFence(lang === undefined ? "" : lang, source, highlights),
   };
 }
 
@@ -430,6 +489,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;