@tanishqkancharla/diffmap 0.1.3 → 0.1.4

package/src/github/route.test.ts

@@ -0,0 +1,68 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+import {
+  githubCommitPath,
+  githubPullPath,
+  githubViewerUrl,
+  parseGitHubPath,
+} from "./route.ts";
+
+test("parseGitHubPath reads pull and commit spec URLs", () => {
+  assert.deepEqual(
+    parseGitHubPath(
+      "/tanishqkancharla/diffmap/pull/5/specs/merge-generate-spec-walkthrough.md",
+    ),
+    {
+      kind: "github-pull",
+      owner: "tanishqkancharla",
+      repo: "diffmap",
+      pull: 5,
+      path: "specs/merge-generate-spec-walkthrough.md",
+    },
+  );
+  assert.deepEqual(
+    parseGitHubPath(
+      "/tanishqkancharla/diffmap/commit/0123456789abcdef0123456789abcdef01234567/specs/a.md",
+    ),
+    {
+      kind: "github-commit",
+      owner: "tanishqkancharla",
+      repo: "diffmap",
+      sha: "0123456789abcdef0123456789abcdef01234567",
+      path: "specs/a.md",
+    },
+  );
+  assert.equal(parseGitHubPath("/").kind, "home");
+  assert.equal(
+    parseGitHubPath("/g/0123456789abcdef0123456789abcdef").kind,
+    "home",
+  );
+  assert.equal(
+    parseGitHubPath("/tanishqkancharla/diffmap/pull/5").kind,
+    "github-invalid",
+  );
+  assert.equal(
+    parseGitHubPath("/tanishqkancharla/diffmap/pull/5/src/cli.ts").kind,
+    "github-invalid",
+  );
+});
+
+test("printed GitHub viewer URLs pin pull or commit", () => {
+  assert.equal(
+    githubPullPath(
+      "tanishqkancharla",
+      "diffmap",
+      5,
+      "specs/merge-generate-spec-walkthrough.md",
+    ),
+    "/tanishqkancharla/diffmap/pull/5/specs/merge-generate-spec-walkthrough.md",
+  );
+  assert.equal(
+    githubCommitPath("o", "r", "deadbeef", "docs/a b.md"),
+    "/o/r/commit/deadbeef/docs/a%20b.md",
+  );
+  assert.equal(
+    githubViewerUrl("tanishqkancharla", "diffmap", { pull: 5 }, "specs/x.md"),
+    "https://diffmap.dev/tanishqkancharla/diffmap/pull/5/specs/x.md",
+  );
+});

package/src/github/route.ts

@@ -0,0 +1,175 @@
+/**
+ * GitHub-hosted spec URLs.
+ *
+ * Pin model (locked): a hosted spec is always one commit SHA. The spec markdown
+ * is the blob of `path` at that SHA. Every [[path]], mermaid %% ref, excerpt,
+ * and hunk is loaded from that same SHA — never main / latest. A PR number only
+ * chooses the SHA (head at load time, then pin). Prefer putting the SHA in the
+ * URL; otherwise resolve head once per page load and use that SHA for all fetches.
+ *
+ * v1: /<owner>/<repo>/pull/<n>/<path-to-spec.md>
+ *     /<owner>/<repo>/commit/<sha>/<path-to-spec.md>
+ */
+import { DIFFMAP_ORIGIN } from "../gist/route.ts";
+
+const NAME_PATTERN = /^[A-Za-z0-9._-]+$/;
+const SHA_PATTERN = /^[0-9a-f]{7,40}$/i;
+const PULL_PATTERN = /^[1-9][0-9]{0,9}$/;
+const MARKDOWN_EXT = /\.(?:md|mdx)$/i;
+
+export type GitHubRoute =
+  | {
+      kind: "github-pull";
+      owner: string;
+      repo: string;
+      pull: number;
+      path: string;
+    }
+  | {
+      kind: "github-commit";
+      owner: string;
+      repo: string;
+      sha: string;
+      path: string;
+    }
+  | { kind: "github-invalid"; message: string };
+
+export function parseGitHubPath(
+  pathname: string,
+): GitHubRoute | { kind: "home" } {
+  const parts = normalizePath(pathname)
+    .split("/")
+    .filter((part) => part.length > 0);
+  if (parts.length < 4) return { kind: "home" };
+  const owner = decodePathSegment(parts[0] ?? "");
+  const repo = decodePathSegment(parts[1] ?? "");
+  const kind = parts[2];
+  const id = decodePathSegment(parts[3] ?? "");
+  if (!isRepoName(owner) || !isRepoName(repo)) return { kind: "home" };
+  if (kind !== "pull" && kind !== "commit") return { kind: "home" };
+
+  const specPath = parts.slice(4).map(decodePathSegment).join("/");
+  if (kind === "pull") {
+    if (!PULL_PATTERN.test(id)) {
+      return { kind: "github-invalid", message: "Not a pull request number." };
+    }
+    const pathError = specPathError(specPath);
+    if (pathError !== undefined)
+      return { kind: "github-invalid", message: pathError };
+    return {
+      kind: "github-pull",
+      owner,
+      repo,
+      pull: Number(id),
+      path: specPath,
+    };
+  }
+  if (!SHA_PATTERN.test(id)) {
+    return { kind: "github-invalid", message: "Not a git commit SHA." };
+  }
+  const pathError = specPathError(specPath);
+  if (pathError !== undefined)
+    return { kind: "github-invalid", message: pathError };
+  return {
+    kind: "github-commit",
+    owner,
+    repo,
+    sha: id.toLowerCase(),
+    path: specPath,
+  };
+}
+
+export function githubPullPath(
+  owner: string,
+  repo: string,
+  pull: number,
+  filePath: string,
+) {
+  return `/${encodeName(owner)}/${encodeName(repo)}/pull/${String(pull)}/${encodeSpecPath(filePath)}`;
+}
+
+export function githubCommitPath(
+  owner: string,
+  repo: string,
+  sha: string,
+  filePath: string,
+) {
+  return `/${encodeName(owner)}/${encodeName(repo)}/commit/${sha}/${encodeSpecPath(filePath)}`;
+}
+
+export function githubViewerUrl(
+  owner: string,
+  repo: string,
+  pin: { pull: number } | { sha: string },
+  filePath: string,
+  origin = DIFFMAP_ORIGIN,
+) {
+  const path =
+    "pull" in pin
+      ? githubPullPath(owner, repo, pin.pull, filePath)
+      : githubCommitPath(owner, repo, pin.sha, filePath);
+  return `${origin}${path}`;
+}
+
+export function githubBlobUrl(
+  owner: string,
+  repo: string,
+  sha: string,
+  filePath: string,
+) {
+  return `https://github.com/${owner}/${repo}/blob/${sha}/${filePath
+    .split("/")
+    .map(encodeURIComponent)
+    .join("/")}`;
+}
+
+export function githubPullUrl(owner: string, repo: string, pull: number) {
+  return `https://github.com/${owner}/${repo}/pull/${String(pull)}`;
+}
+
+function isRepoName(value: string) {
+  return (
+    NAME_PATTERN.test(value) &&
+    value !== "." &&
+    value !== ".." &&
+    !value.startsWith(".")
+  );
+}
+
+function specPathError(specPath: string) {
+  if (specPath.length === 0) {
+    return "A hosted spec URL needs a markdown path after the pull or commit.";
+  }
+  if (specPath.split("/").some((part) => part === "." || part === "..")) {
+    return "Spec path is not a repository file.";
+  }
+  if (!MARKDOWN_EXT.test(specPath)) {
+    return "Spec path must be a .md or .mdx file.";
+  }
+  return undefined;
+}
+
+function encodeName(value: string) {
+  return encodeURIComponent(value);
+}
+
+function encodeSpecPath(filePath: string) {
+  return filePath.split("/").map(encodeURIComponent).join("/");
+}
+
+function normalizePath(pathname: string) {
+  if (pathname.length === 0) return "/";
+  try {
+    return decodeURI(pathname);
+  } catch {
+    return pathname;
+  }
+}
+
+function decodePathSegment(value: string) {
+  try {
+    return decodeURIComponent(value);
+  } catch {
+    return value;
+  }
+}

package/src/host/HostApp.tsx

@@ -0,0 +1,22 @@
+import { useEffect, useState } from "react";
+import { GistApp } from "../gist/GistApp.tsx";
+import { GitHubApp } from "../github/GitHubApp.tsx";
+import { parseGitHubPath } from "../github/route.ts";
+
+function isGitHubPath(pathname: string) {
+  return parseGitHubPath(pathname).kind !== "home";
+}
+
+export function HostApp() {
+  const [github, setGithub] = useState(() =>
+    isGitHubPath(window.location.pathname),
+  );
+
+  useEffect(() => {
+    const onPop = () => setGithub(isGitHubPath(window.location.pathname));
+    window.addEventListener("popstate", onPop);
+    return () => window.removeEventListener("popstate", onPop);
+  }, []);
+
+  return github ? <GitHubApp /> : <GistApp />;
+}

package/src/index.ts

@@ -17,6 +17,7 @@ export type {
   ViewerView,
 } from "./parseViewer.js";
 export { gistViewerUrl } from "./gist/route.js";
+export { githubViewerUrl } from "./github/route.js";
 export { shareMarkdownFile } from "./share.js";
 export { startServer } from "./serve.js";
 export type { FileExcerpt, StartServerInput, DiffmapServer } from "./serve.js";

package/src/mermaid.ts

@@ -2,6 +2,28 @@ import { renderMermaidSVG } from "beautiful-mermaid";
 import * as errore from "errore";
 import { DiffmapMermaidError } from "./errors.js";
 
+function mermaidReason(cause: unknown) {
+  if (cause instanceof Error && cause.message !== "") return cause.message;
+  return "unknown error";
+}
+
+export function parseMermaidDiagram(input: {
+  source: string;
+  path: string;
+  where: string;
+}) {
+  return errore.try({
+    try: () => renderMermaidSVG(input.source),
+    catch: (cause) =>
+      new DiffmapMermaidError({
+        path: input.path,
+        where: input.where,
+        reason: mermaidReason(cause),
+        cause,
+      }),
+  });
+}
+
 export function mermaidSvg(input: {
   source: string;
   bg: string;
@@ -24,6 +46,12 @@ export function mermaidSvg(input: {
         font: input.font,
         transparent: true,
       }),
-    catch: (cause) => new DiffmapMermaidError({ cause }),
+    catch: (cause) =>
+      new DiffmapMermaidError({
+        path: "spec",
+        where: "diagram 1",
+        reason: mermaidReason(cause),
+        cause,
+      }),
   });
 }

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.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,
@@ -54,6 +55,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;
@@ -258,11 +262,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;