@tanishqkancharla/diffmap 0.1.3 → 0.1.5

package/src/parseViewer.test.ts

@@ -0,0 +1,185 @@
+import assert from "node:assert/strict";
+import { execFile } from "node:child_process";
+import fs from "node:fs/promises";
+import os from "node:os";
+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 { parseViewerDocument } from "./parseViewer.js";
+import { shareMarkdownFile } from "./share.js";
+import { startServer } from "./serve.js";
+
+const execFileAsync = promisify(execFile);
+const srcDir = fileURLToPath(new URL(".", import.meta.url));
+const packageRoot = path.resolve(srcDir, "..");
+const cliPath = path.join(srcDir, "cli.ts");
+const sampleSpec = path.join(packageRoot, "fixtures", "sample-spec.md");
+
+function brokenMermaidSpec(body = "flwochart TD\n  A --> B") {
+  return `# Broken mermaid\n\n\`\`\`mermaid\n${body}\n\`\`\`\n`;
+}
+
+async function withTempSpec(
+  source: string,
+  run: (filePath: string) => Promise<void>,
+) {
+  const dir = await fs.mkdtemp(path.join(os.tmpdir(), "diffmap-mermaid-"));
+  const filePath = path.join(dir, "broken.md");
+  await fs.writeFile(filePath, source);
+  try {
+    await run(filePath);
+  } finally {
+    await fs.rm(dir, { recursive: true, force: true });
+  }
+}
+
+async function runCli(args: string[]) {
+  try {
+    const result = await execFileAsync(
+      process.execPath,
+      ["--import", "tsx", cliPath, ...args],
+      {
+        cwd: packageRoot,
+        timeout: 20_000,
+        maxBuffer: 1_000_000,
+      },
+    );
+    return { exitCode: 0, stdout: result.stdout, stderr: result.stderr };
+  } catch (cause) {
+    if (typeof cause !== "object" || !cause) throw cause;
+    const exitCode =
+      "code" in cause && typeof cause.code === "number"
+        ? cause.code
+        : undefined;
+    const stdout =
+      "stdout" in cause && typeof cause.stdout === "string" ? cause.stdout : "";
+    const stderr =
+      "stderr" in cause && typeof cause.stderr === "string" ? cause.stderr : "";
+    return { exitCode, stdout, stderr };
+  }
+}
+
+test("parseViewerDocument accepts a spec with valid mermaid", async () => {
+  const source = await fs.readFile(sampleSpec, "utf8");
+  const document = parseViewerDocument(source, sampleSpec);
+  assert.equal(document instanceof Error, false);
+  if (document instanceof Error) return;
+  assert.equal(
+    document.nodes.some(
+      (node) => node.type === "view" && node.fence.kind === "mermaid",
+    ),
+    true,
+  );
+});
+
+test("parseViewerDocument fails on broken mermaid with file and diagram", () => {
+  const source = brokenMermaidSpec();
+  const parsed = parseViewerDocument(source, "broken.md");
+  assert.equal(parsed instanceof DiffmapMermaidError, true);
+  if (!(parsed instanceof DiffmapMermaidError)) return;
+  assert.equal(parsed.path, "broken.md");
+  assert.equal(parsed.where, "diagram 1, line 3");
+  assert.match(String(parsed.reason), /Invalid mermaid header: "flwochart TD"/);
+  assert.equal(
+    parsed.message,
+    'diffmap could not parse mermaid in broken.md (diagram 1, line 3): Invalid mermaid header: "flwochart TD". Expected "graph TD", "flowchart LR", "stateDiagram-v2", etc.',
+  );
+});
+
+test("parseViewerDocument names the second mermaid diagram when it is invalid", () => {
+  const source = `# Two diagrams
+
+\`\`\`mermaid
+flowchart TD
+  A --> B
+\`\`\`
+
+\`\`\`mermaid
+not a diagram
+\`\`\`
+`;
+  const parsed = parseViewerDocument(source, "two.md");
+  assert.equal(parsed instanceof DiffmapMermaidError, true);
+  if (!(parsed instanceof DiffmapMermaidError)) return;
+  assert.equal(parsed.where, "diagram 2, line 8");
+  assert.match(parsed.message, /in two\.md \(diagram 2, line 8\)/);
+});
+
+test("parseViewerDocument fails on invalid MDC mermaid", () => {
+  const source = `# MDC
+
+::mermaid
+flwochart TD
+A --> B
+::
+`;
+  const parsed = parseViewerDocument(source, "mdc.md");
+  assert.equal(parsed instanceof DiffmapMermaidError, true);
+  if (!(parsed instanceof DiffmapMermaidError)) return;
+  assert.equal(parsed.where, "diagram 1, line 3");
+});
+
+test("startServer does not listen when mermaid is invalid", async () => {
+  await withTempSpec(brokenMermaidSpec(), async (filePath) => {
+    const started = await startServer({
+      filePath,
+      workspaceRoot: path.dirname(filePath),
+      port: 0,
+    });
+    assert.equal(started instanceof DiffmapMermaidError, true);
+    if (!(started instanceof DiffmapMermaidError)) return;
+    assert.equal(started.path, filePath);
+    assert.equal(started.where, "diagram 1, line 3");
+  });
+});
+
+test("shareMarkdownFile does not call gh when mermaid is invalid", async () => {
+  await withTempSpec(brokenMermaidSpec(), async (filePath) => {
+    const shared = await shareMarkdownFile({
+      filePath,
+      isPublic: false,
+    });
+    assert.equal(shared instanceof DiffmapMermaidError, true);
+    if (!(shared instanceof DiffmapMermaidError)) return;
+    assert.equal(shared.path, filePath);
+  });
+});
+
+function mermaidCliMessage(filePath: string) {
+  return `diffmap could not parse mermaid in ${filePath} (diagram 1, line 3): Invalid mermaid header: "flwochart TD". Expected "graph TD", "flowchart LR", "stateDiagram-v2", etc.`;
+}
+
+test("diffmap serve exits non-zero on broken mermaid", async () => {
+  await withTempSpec(brokenMermaidSpec(), async (filePath) => {
+    const result = await runCli(["serve", filePath]);
+    assert.equal(result.exitCode, 1);
+    assert.equal(
+      `${result.stdout}${result.stderr}`,
+      `Error (DIFFMAP): ${mermaidCliMessage(filePath)}\n`,
+    );
+  });
+});
+
+test("bare diffmap <file.md> exits non-zero on broken mermaid", async () => {
+  await withTempSpec(brokenMermaidSpec(), async (filePath) => {
+    const result = await runCli([filePath]);
+    assert.equal(result.exitCode, 1);
+    assert.equal(
+      `${result.stdout}${result.stderr}`,
+      `Error (DIFFMAP): ${mermaidCliMessage(filePath)}\n`,
+    );
+  });
+});
+
+test("diffmap share exits non-zero on broken mermaid", async () => {
+  await withTempSpec(brokenMermaidSpec(), async (filePath) => {
+    const result = await runCli(["share", filePath]);
+    assert.equal(result.exitCode, 1);
+    assert.equal(
+      `${result.stdout}${result.stderr}`.trimEnd(),
+      `code: DIFFMAP\nmessage: ${JSON.stringify(mermaidCliMessage(filePath))}`,
+    );
+  });
+});

package/src/parseViewer.ts

@@ -3,6 +3,7 @@ import { parsePatchFiles, type CodeViewDiffItem } from "@pierre/diffs";
 import { parseAST } from "md4x/napi";
 import type { ComarkElement, ComarkNode } from "md4x/napi";
 import { DiffmapAnnotationError, DiffmapParseError } from "./errors.js";
+import { parseMermaidDiagram } from "./mermaid.js";
 import { parseFence, type Fence } from "./parseFence.js";
 
 export type ViewerDocument = {
@@ -57,7 +58,7 @@ export type ViewerElementAttrs = {
   align: string | undefined;
 };
 
-export function parseViewerDocument(source: string) {
+export function parseViewerDocument(source: string, path = "spec") {
   const tree = errore.try({
     try: () => parseAST(source),
     catch: (cause) => new DiffmapParseError({ cause }),
@@ -106,8 +107,17 @@ export function parseViewerDocument(source: string) {
       return fence.annotations.map((link) => link.annotation);
     return [];
   });
-  for (const fence of fences) {
-    if (fence.kind !== "mermaid") continue;
+  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 targets = new Set<string>();
     for (const link of fence.annotations) {
       const target = `${link.target}:${link.id}`;
@@ -186,6 +196,20 @@ function collectFences(nodes: ViewerNode[]): Fence[] {
   });
 }
 
+function mermaidWhere(source: string, index: number) {
+  const line = mermaidFenceLine(source, 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
+  ];
+  if (match === undefined || match.index === undefined) return undefined;
+  return source.slice(0, match.index).split("\n").length;
+}
+
 const headingTags = new Set(["h1", "h2", "h3", "h4", "h5", "h6"]);
 
 function collectHeadings(nodes: ViewerNode[]): ViewerHeading[] {

package/src/serve.test.ts

@@ -0,0 +1,306 @@
+import assert from "node:assert/strict";
+import { execFile, spawn, type ChildProcess } from "node:child_process";
+import fs from "node:fs/promises";
+import net from "node:net";
+import os from "node:os";
+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 { DiffmapServeError } from "./errors.js";
+import { startServer, type DiffmapServer } from "./serve.js";
+
+const execFileAsync = promisify(execFile);
+const srcDir = fileURLToPath(new URL(".", import.meta.url));
+const packageRoot = path.resolve(srcDir, "..");
+const cliPath = path.join(srcDir, "cli.ts");
+const sampleSpec = path.join(packageRoot, "fixtures", "sample-spec.md");
+const localUrlPattern = /http:\/\/127\.0\.0\.1:\d+/g;
+
+function httpUrlPort(url: string) {
+  const parsed = new URL(url);
+  assert.equal(parsed.hostname, "127.0.0.1");
+  const port = Number(parsed.port);
+  assert.ok(Number.isInteger(port) && port > 0);
+  return port;
+}
+
+function assertStarted(
+  started: Awaited<ReturnType<typeof startServer>>,
+): DiffmapServer {
+  assert.equal(
+    started instanceof Error,
+    false,
+    started instanceof Error ? started.message : "",
+  );
+  if (started instanceof Error) throw started;
+  return started;
+}
+
+async function occupyPort(port: number) {
+  const server = net.createServer();
+  try {
+    await new Promise<void>((resolve, reject) => {
+      server.once("error", reject);
+      server.listen(port, "127.0.0.1", () => resolve());
+    });
+    return server;
+  } catch {
+    server.close();
+    return undefined;
+  }
+}
+
+async function listenEphemeral() {
+  const server = net.createServer();
+  await new Promise<void>((resolve, reject) => {
+    server.once("error", reject);
+    server.listen(0, "127.0.0.1", () => resolve());
+  });
+  return server;
+}
+
+function boundPort(server: net.Server) {
+  const address = server.address();
+  assert.ok(address !== null && typeof address !== "string");
+  return address.port;
+}
+
+async function closeTcp(server: net.Server | undefined) {
+  if (server === undefined) return;
+  await new Promise<void>((resolve) => {
+    server.close(() => resolve());
+  });
+}
+
+async function fetchOk(url: string) {
+  const response = await fetch(url, {
+    headers: { accept: "text/markdown" },
+  });
+  assert.equal(response.ok, true);
+  const body = await response.text();
+  assert.match(body, /Spec fixture/);
+}
+
+async function waitForClosed(server: DiffmapServer, timeoutMs = 10_000) {
+  await Promise.race([
+    server.closed,
+    delay(timeoutMs).then(() => {
+      throw new Error(`server did not close: ${server.url}`);
+    }),
+  ]);
+}
+
+test(
+  "startServer binds distinct free ports when 4177 is taken",
+  { timeout: 90_000 },
+  async () => {
+    const occupied = await occupyPort(4177);
+    try {
+      const first = assertStarted(
+        await startServer({
+          filePath: sampleSpec,
+          workspaceRoot: packageRoot,
+        }),
+      );
+      const second = assertStarted(
+        await startServer({
+          filePath: sampleSpec,
+          workspaceRoot: packageRoot,
+        }),
+      );
+      try {
+        const firstPort = httpUrlPort(first.url);
+        const secondPort = httpUrlPort(second.url);
+        assert.notEqual(firstPort, secondPort);
+        assert.notEqual(firstPort, 4177);
+        assert.notEqual(secondPort, 4177);
+        await fetchOk(first.url);
+        await fetchOk(second.url);
+      } finally {
+        await first.shutdown();
+        await second.shutdown();
+        await waitForClosed(first);
+        await waitForClosed(second);
+      }
+    } finally {
+      await closeTcp(occupied);
+    }
+  },
+);
+
+test(
+  "startServer --port pins and fails when that port is taken",
+  { timeout: 90_000 },
+  async () => {
+    const holder = await listenEphemeral();
+    const port = boundPort(holder);
+
+    const blocked = await startServer({
+      filePath: sampleSpec,
+      workspaceRoot: packageRoot,
+      port,
+    });
+    assert.equal(blocked instanceof DiffmapServeError, true);
+    if (!(blocked instanceof DiffmapServeError)) return;
+    assert.match(blocked.message, /already in use/i);
+
+    await closeTcp(holder);
+
+    const pinned = assertStarted(
+      await startServer({
+        filePath: sampleSpec,
+        workspaceRoot: packageRoot,
+        port,
+      }),
+    );
+    try {
+      assert.equal(httpUrlPort(pinned.url), port);
+      await fetchOk(pinned.url);
+    } finally {
+      await pinned.shutdown();
+      await waitForClosed(pinned);
+    }
+  },
+);
+
+test(
+  "startServer Close server still stops an ephemeral listener",
+  { timeout: 90_000 },
+  async () => {
+    const started = assertStarted(
+      await startServer({
+        filePath: sampleSpec,
+        workspaceRoot: packageRoot,
+      }),
+    );
+    const response = await fetch(`${started.url}/__diffmap/shutdown`, {
+      method: "POST",
+    });
+    assert.equal(response.ok, true);
+    await waitForClosed(started);
+    await assert.rejects(() => fetch(started.url));
+  },
+);
+
+type SpawnedCli = {
+  child: ChildProcess;
+  output: () => string;
+};
+
+function spawnCli(args: string[]) {
+  let stdout = "";
+  let stderr = "";
+  const child = spawn(process.execPath, ["--import", "tsx", cliPath, ...args], {
+    cwd: packageRoot,
+    stdio: ["ignore", "pipe", "pipe"],
+  });
+  child.stdout?.on("data", (chunk: Buffer) => {
+    stdout += chunk.toString();
+  });
+  child.stderr?.on("data", (chunk: Buffer) => {
+    stderr += chunk.toString();
+  });
+  return {
+    child,
+    output: () => `${stdout}${stderr}`,
+  };
+}
+
+function firstLocalUrl(text: string) {
+  return text.match(localUrlPattern)?.[0];
+}
+
+async function waitForLocalUrl(spawned: SpawnedCli, timeoutMs = 60_000) {
+  const start = Date.now();
+  while (Date.now() - start < timeoutMs) {
+    if (spawned.child.exitCode !== null) {
+      throw new Error(
+        `cli exited ${spawned.child.exitCode} before listen:\n${spawned.output()}`,
+      );
+    }
+    const url = firstLocalUrl(spawned.output());
+    if (url !== undefined) return url;
+    await delay(50);
+  }
+  throw new Error(`cli printed no listen url:\n${spawned.output()}`);
+}
+
+async function waitForExit(child: ChildProcess, timeoutMs = 15_000) {
+  if (child.exitCode !== null) return;
+  await Promise.race([
+    new Promise<void>((resolve) => {
+      child.once("exit", () => resolve());
+    }),
+    delay(timeoutMs).then(() => {
+      child.kill("SIGKILL");
+      throw new Error("cli did not exit");
+    }),
+  ]);
+}
+
+async function stopCli(spawned: SpawnedCli, url: string) {
+  const response = await fetch(`${url}/__diffmap/shutdown`, {
+    method: "POST",
+  }).catch(() => undefined);
+  if (response === undefined || !response.ok) {
+    spawned.child.kill("SIGTERM");
+  }
+  await waitForExit(spawned.child);
+}
+
+async function withTempSpecs(
+  run: (firstFile: string, secondFile: string) => Promise<void>,
+) {
+  const dir = await fs.mkdtemp(path.join(os.tmpdir(), "diffmap-serve-"));
+  const firstFile = path.join(dir, "one.md");
+  const secondFile = path.join(dir, "two.md");
+  const source = await fs.readFile(sampleSpec, "utf8");
+  await Promise.all([
+    fs.writeFile(firstFile, source),
+    fs.writeFile(secondFile, source),
+  ]);
+  try {
+    await run(firstFile, secondFile);
+  } finally {
+    await fs.rm(dir, { recursive: true, force: true });
+  }
+}
+
+test(
+  "diffmap serve prints a free port and list tracks both servers",
+  { timeout: 90_000 },
+  async () => {
+    await withTempSpecs(async (firstFile, secondFile) => {
+      const first = spawnCli(["serve", firstFile]);
+      const second = spawnCli([secondFile]);
+      try {
+        const firstUrl = await waitForLocalUrl(first);
+        const secondUrl = await waitForLocalUrl(second);
+        assert.notEqual(firstUrl, secondUrl);
+        await fetchOk(firstUrl);
+        await fetchOk(secondUrl);
+
+        const listed = await execFileAsync(
+          process.execPath,
+          ["--import", "tsx", cliPath, "list"],
+          {
+            cwd: packageRoot,
+            timeout: 20_000,
+            maxBuffer: 1_000_000,
+          },
+        );
+        const listOutput = `${listed.stdout}${listed.stderr}`;
+        assert.equal(listOutput.includes(firstUrl), true);
+        assert.equal(listOutput.includes(secondUrl), true);
+
+        await stopCli(first, firstUrl);
+        await stopCli(second, secondUrl);
+      } finally {
+        first.child.kill("SIGTERM");
+        second.child.kill("SIGTERM");
+      }
+    });
+  },
+);

package/src/serve.ts

@@ -5,6 +5,7 @@ import { createServer, type ViteDevServer } from "vite";
 import { diffmapContentPlugin } from "./contentPlugin.js";
 import { DiffmapFileError, DiffmapServeError } from "./errors.js";
 import { extractTitle } from "./extractDocument.js";
+import { parseViewerDocument } from "./parseViewer.js";
 import { findDefinition, readSourceReference } from "./definitions.js";
 import {
   registerRunningDiffmap,
@@ -21,7 +22,7 @@ export type DiffmapServer = {
 export type StartServerInput = {
   filePath: string;
   workspaceRoot: string;
-  port: number;
+  port?: number;
 };
 
 const packageRoot = path.resolve(fileURLToPath(new URL("..", import.meta.url)));
@@ -44,6 +45,7 @@ function createClosedBarrier() {
 export async function startServer(input: StartServerInput) {
   const filePath = path.resolve(input.filePath);
   const workspaceRoot = path.resolve(input.workspaceRoot);
+  const port = input.port ?? 0;
   const source = await fs.readFile(filePath, "utf8").catch(
     (cause) =>
       new DiffmapFileError({
@@ -54,6 +56,9 @@ export async function startServer(input: StartServerInput) {
   );
   if (source instanceof Error) return source;
 
+  const parsed = parseViewerDocument(source, filePath);
+  if (parsed instanceof Error) return parsed;
+
   const title = extractTitle(source);
 
   let vite: ViteDevServer | undefined;
@@ -78,9 +83,9 @@ export async function startServer(input: StartServerInput) {
     configFile: path.join(packageRoot, "vite.config.ts"),
     root: packageRoot,
     server: {
-      port: input.port,
+      port,
       host: "127.0.0.1",
-      strictPort: input.port !== 0,
+      strictPort: port !== 0,
       fs: {
         allow: [packageRoot, workspaceRoot, path.dirname(filePath)],
       },
@@ -134,7 +139,16 @@ export async function startServer(input: StartServerInput) {
     ],
   });
 
-  await vite.listen(input.port);
+  const listened = await vite.listen(port).catch(
+    (cause) =>
+      new DiffmapServeError({
+        reason: cause instanceof Error ? cause.message : "listen failed",
+      }),
+  );
+  if (listened instanceof Error) {
+    await shutdown();
+    return listened;
+  }
   const localUrl = vite.resolvedUrls?.local[0];
   if (localUrl === undefined) {
     await shutdown();
@@ -258,11 +272,15 @@ async function handleDiffmapRequest(input: {
     return;
   }
   if (parsed.pathname === "/__diffmap/meta" && input.method === "GET") {
+    const source = await fs
+      .readFile(input.filePath, "utf8")
+      .catch(() => undefined);
+    const title = source === undefined ? input.title : extractTitle(source);
     input.res.statusCode = 200;
     input.res.setHeader("content-type", "application/json; charset=utf-8");
     input.res.end(
       JSON.stringify({
-        title: input.title,
+        title,
         file: input.filePath,
         pid: process.pid,
       }),

package/src/share.ts

@@ -5,6 +5,7 @@ import { promisify } from "node:util";
 import { DiffmapFileError, DiffmapShareError } from "./errors.js";
 import { extractTitle } from "./extractDocument.js";
 import { extractGistId, gistViewerUrl } from "./gist/route.ts";
+import { parseViewerDocument } from "./parseViewer.js";
 
 const execFileAsync = promisify(execFile);
 
@@ -17,7 +18,7 @@ export type ShareResult = {
 export async function shareMarkdownFile(input: {
   filePath: string;
   isPublic: boolean;
-}): Promise<ShareResult | DiffmapFileError | DiffmapShareError> {
+}) {
   const filePath = path.resolve(input.filePath);
   const source = await fs.readFile(filePath, "utf8").catch(
     (cause) =>
@@ -29,6 +30,9 @@ export async function shareMarkdownFile(input: {
   );
   if (source instanceof Error) return source;
 
+  const parsed = parseViewerDocument(source, filePath);
+  if (parsed instanceof Error) return parsed;
+
   const auth = await runGh(["auth", "status"]);
   if (auth instanceof DiffmapShareError) return auth;
 

package/src/update.test.ts

@@ -0,0 +1,19 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+import { compareVersions, resolveUpdateArgv } from "./update.js";
+
+test("compareVersions orders versions by semver precedence", () => {
+  assert.equal(compareVersions("0.1.4", "0.1.4"), 0);
+  assert.equal(compareVersions("0.1.4", "0.1.5"), -1);
+  assert.equal(compareVersions("0.1.10", "0.1.9"), 1);
+  assert.equal(compareVersions("1.0.0-rc.1", "1.0.0"), -1);
+});
+
+test("update and --update run the same command", () => {
+  assert.deepEqual(resolveUpdateArgv(["update"]), ["update"]);
+  assert.deepEqual(resolveUpdateArgv(["--update"]), ["update"]);
+  assert.deepEqual(resolveUpdateArgv(["serve", "spec.md"]), [
+    "serve",
+    "spec.md",
+  ]);
+});