@tanishqkancharla/diffmap 0.1.3

package/src/parseFence.ts

@@ -0,0 +1,91 @@
+import { parseCallStack, type SourceAnnotation } from "./annotations.js";
+import {
+  parseDiagramAnnotations,
+  type DiagramAnnotation,
+} from "./diagramAnnotations.js";
+
+export type Fence =
+  | { kind: "mermaid"; source: string; annotations: DiagramAnnotation[] }
+  | { kind: "html"; source: string }
+  | { kind: "callstack"; source: string; lines: SourceAnnotation[] }
+  | { kind: "source-diff"; id: string; path: string; source: string }
+  | { kind: "file"; path: string; start: number; end: number; source: string }
+  | { kind: "diff"; path: string | undefined; source: string }
+  | { kind: "code"; lang: string; source: string };
+
+const fileRefPattern = /^(\d+):(\d+):(.+)$/;
+const diffPathPattern = /^diff:(.+)$/;
+
+export function isCallStackSource(source: string) {
+  return source.includes("└──") || source.includes("├──");
+}
+
+export function pathFromDiffSource(source: string) {
+  const plus = /^\+\+\+ [ab]\/(.+)$/m.exec(source);
+  if (plus?.[1] !== undefined) return plus[1];
+  const minus = /^--- [ab]\/(.+)$/m.exec(source);
+  if (minus?.[1] !== undefined) return minus[1];
+  const comment = /^\/\/ (.+\S)\s*$/m.exec(source);
+  if (comment?.[1] !== undefined) return comment[1];
+  return undefined;
+}
+
+export function parseFence(lang: string, source: string): Fence {
+  const trimmed = source.replace(/\n$/, "");
+  if (lang === "mermaid")
+    return {
+      kind: "mermaid",
+      source: trimmed,
+      annotations: parseDiagramAnnotations(trimmed),
+    };
+  if (lang === "html") return { kind: "html", source: trimmed };
+  if (lang === "callstack")
+    return {
+      kind: "callstack",
+      source: trimmed,
+      lines: parseCallStack(trimmed),
+    };
+
+  const sourceDiff = /^source-diff:([\w-]+):(.+)$/.exec(lang);
+  if (sourceDiff !== null) {
+    return {
+      kind: "source-diff",
+      id: sourceDiff[1]!,
+      path: sourceDiff[2]!,
+      source: trimmed,
+    };
+  }
+
+  const fileRef = fileRefPattern.exec(lang);
+  if (fileRef !== null) {
+    return {
+      kind: "file",
+      start: Number(fileRef[1]),
+      end: Number(fileRef[2]),
+      path: fileRef[3]!,
+      source: trimmed,
+    };
+  }
+
+  const diffPath = diffPathPattern.exec(lang);
+  if (lang === "diff" || diffPath !== null) {
+    if (isCallStackSource(trimmed)) {
+      return {
+        kind: "callstack",
+        source: trimmed,
+        lines: parseCallStack(trimmed),
+      };
+    }
+    return {
+      kind: "diff",
+      path: diffPath === null ? pathFromDiffSource(trimmed) : diffPath[1],
+      source: trimmed,
+    };
+  }
+
+  return {
+    kind: "code",
+    lang: lang.length === 0 ? "text" : lang,
+    source: trimmed,
+  };
+}

package/src/parseViewer.ts

@@ -0,0 +1,399 @@
+import * as errore from "errore";
+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 { parseFence, type Fence } from "./parseFence.js";
+
+export type ViewerDocument = {
+  nodes: ViewerNode[];
+  headings: ViewerHeading[];
+  sourceDiffs: CodeViewDiffItem[];
+  hasReferences: boolean;
+};
+
+export type ViewerHeading = {
+  level: 1 | 2 | 3 | 4 | 5 | 6;
+  text: string;
+  id: string;
+};
+
+export type ViewerNode = ViewerText | ViewerElement | ViewerHtml | ViewerView;
+
+export type ViewerText = {
+  type: "text";
+  value: string;
+};
+
+export type ViewerElement = {
+  type: "element";
+  tag: string;
+  attrs: ViewerElementAttrs;
+  children: ViewerNode[];
+};
+
+export type ViewerHtml = {
+  type: "html";
+  block: boolean;
+  source: string;
+};
+
+export type ViewerView = {
+  type: "view";
+  fence: Fence;
+};
+
+export type ViewerElementAttrs = {
+  id: string | undefined;
+  href: string | undefined;
+  src: string | undefined;
+  alt: string | undefined;
+  title: string | undefined;
+  className: string | undefined;
+  start: number | undefined;
+  checked: boolean | undefined;
+  task: boolean | undefined;
+  alertType: string | undefined;
+  align: string | undefined;
+};
+
+export function parseViewerDocument(source: string) {
+  const tree = errore.try({
+    try: () => parseAST(source),
+    catch: (cause) => new DiffmapParseError({ cause }),
+  });
+  if (tree instanceof Error) return tree;
+  const nodes = tree.nodes.flatMap(fromNode);
+  const fences = collectFences(nodes);
+  const sourceDiffs: CodeViewDiffItem[] = [];
+  for (const fence of fences) {
+    if (fence.kind !== "source-diff") continue;
+    if (sourceDiffs.some((diff) => diff.id === fence.id)) {
+      return new DiffmapAnnotationError({
+        reason: `Duplicate source diff ID "${fence.id}"`,
+      });
+    }
+    const patches = errore.try({
+      try: () => parsePatchFiles(fence.source, undefined, true),
+      catch: (cause) =>
+        new DiffmapAnnotationError({
+          reason: `Invalid patch "${fence.id}"`,
+          cause,
+        }),
+    });
+    if (patches instanceof Error) return patches;
+    const files = patches.flatMap((patch) => patch.files);
+    const fileDiff = files[0];
+    if (
+      files.length !== 1 ||
+      fileDiff === undefined ||
+      fileDiff.hunks.length === 0
+    ) {
+      return new DiffmapAnnotationError({
+        reason: `Source diff "${fence.id}" must contain one file with unified diff hunks`,
+      });
+    }
+    if (fileDiff.name !== fence.path) {
+      return new DiffmapAnnotationError({
+        reason: `Source diff "${fence.id}" path does not match its patch (${fileDiff.name})`,
+      });
+    }
+    sourceDiffs.push({ id: fence.id, type: "diff", fileDiff });
+  }
+  const annotations = fences.flatMap((fence) => {
+    if (fence.kind === "callstack") return fence.lines;
+    if (fence.kind === "mermaid")
+      return fence.annotations.map((link) => link.annotation);
+    return [];
+  });
+  for (const fence of fences) {
+    if (fence.kind !== "mermaid") continue;
+    const targets = new Set<string>();
+    for (const link of fence.annotations) {
+      const target = `${link.target}:${link.id}`;
+      if (
+        targets.has(target) ||
+        link.annotation.references.length === 0 ||
+        (link.target === "edge" && !/^(0|[1-9]\d*)$/.test(link.id))
+      ) {
+        return new DiffmapAnnotationError({
+          reason: `Invalid or duplicate Mermaid reference for ${target}`,
+        });
+      }
+      targets.add(target);
+    }
+  }
+  for (const line of annotations) {
+    if (line.text.includes("[[")) {
+      return new DiffmapAnnotationError({
+        reason: `Invalid reference in "${line.text}". Use [[id:old|new:start-end]] or [[path#symbol]]`,
+      });
+    }
+    for (const ref of line.references) {
+      if (ref.kind === "file") {
+        if (
+          ref.start !== undefined &&
+          (!Number.isSafeInteger(ref.start) ||
+            !Number.isSafeInteger(ref.end) ||
+            ref.end! < ref.start)
+        ) {
+          return new DiffmapAnnotationError({
+            reason: `Invalid file range in "${ref.path}"`,
+          });
+        }
+        continue;
+      }
+      const diff = sourceDiffs.find((item) => item.id === ref.id);
+      if (diff === undefined) {
+        return new DiffmapAnnotationError({
+          reason: `Unknown source diff "${ref.id}"`,
+        });
+      }
+      const inHunk = diff.fileDiff.hunks.some((hunk) => {
+        const start =
+          ref.side === "old" ? hunk.deletionStart : hunk.additionStart;
+        const count =
+          ref.side === "old" ? hunk.deletionCount : hunk.additionCount;
+        return ref.start >= start && ref.end < start + count;
+      });
+      if (
+        !Number.isSafeInteger(ref.start) ||
+        !Number.isSafeInteger(ref.end) ||
+        ref.end < ref.start ||
+        !inHunk
+      ) {
+        return new DiffmapAnnotationError({
+          reason: `Range ${ref.side}:${ref.start}-${ref.end} is not in a hunk of "${ref.id}"`,
+        });
+      }
+    }
+  }
+  return {
+    nodes,
+    headings: collectHeadings(nodes),
+    sourceDiffs,
+    hasReferences: annotations.some(
+      (annotation) => annotation.references.length > 0,
+    ),
+  };
+}
+
+function collectFences(nodes: ViewerNode[]): Fence[] {
+  return nodes.flatMap((node) => {
+    if (node.type === "view") return [node.fence];
+    if (node.type === "element") return collectFences(node.children);
+    return [];
+  });
+}
+
+const headingTags = new Set(["h1", "h2", "h3", "h4", "h5", "h6"]);
+
+function collectHeadings(nodes: ViewerNode[]): ViewerHeading[] {
+  const headings: ViewerHeading[] = [];
+  const usedIds = new Set<string>();
+  walkHeadings(nodes, headings, usedIds);
+  return headings;
+}
+
+function walkHeadings(
+  nodes: ViewerNode[],
+  headings: ViewerHeading[],
+  usedIds: Set<string>,
+) {
+  for (const node of nodes) {
+    if (node.type !== "element") continue;
+    if (headingTags.has(node.tag)) {
+      const text = viewerNodeText(node);
+      const id = ensureHeadingId(node, text, usedIds);
+      headings.push({
+        level: headingLevel(node.tag),
+        text,
+        id,
+      });
+      continue;
+    }
+    walkHeadings(node.children, headings, usedIds);
+  }
+}
+
+function headingLevel(tag: string): ViewerHeading["level"] {
+  if (tag === "h1") return 1;
+  if (tag === "h2") return 2;
+  if (tag === "h3") return 3;
+  if (tag === "h4") return 4;
+  if (tag === "h5") return 5;
+  return 6;
+}
+
+function ensureHeadingId(
+  node: ViewerElement,
+  text: string,
+  usedIds: Set<string>,
+) {
+  const existing = node.attrs.id;
+  if (existing !== undefined && existing !== "") {
+    usedIds.add(existing);
+    return existing;
+  }
+  const id = uniqueHeadingId(text, usedIds);
+  node.attrs.id = id;
+  return id;
+}
+
+function uniqueHeadingId(text: string, usedIds: Set<string>) {
+  const base =
+    text
+      .toLowerCase()
+      .normalize("NFKD")
+      .replace(/[^\p{Letter}\p{Number}]+/gu, "-")
+      .replace(/^-+|-+$/g, "") || "heading";
+  let id = base;
+  let n = 1;
+  while (usedIds.has(id)) {
+    id = `${base}-${n}`;
+    n += 1;
+  }
+  usedIds.add(id);
+  return id;
+}
+
+function viewerNodeText(node: ViewerNode): string {
+  if (node.type === "text") return node.value;
+  if (node.type !== "element") return "";
+  return node.children.map(viewerNodeText).join("");
+}
+
+function fromNode(node: ComarkNode): ViewerNode[] {
+  if (!Array.isArray(node)) {
+    return [{ type: "text", value: node }];
+  }
+  const converted = fromElement(node);
+  if (converted === undefined) return [];
+  if (Array.isArray(converted)) return converted;
+  return [converted];
+}
+
+function fromElement(
+  element: ComarkElement,
+): ViewerNode | ViewerNode[] | undefined {
+  const [tag, , ...children] = element;
+  if (tag === null) return undefined;
+  if (tag === "template") return children.flatMap(fromNode);
+  if (tag === "pre") {
+    return fenceView(stringAttr(element, "language"), comarkText(children));
+  }
+  if (tag === "mermaid") return fenceView("mermaid", comarkText(children));
+  if (tag === "callstack") return fenceView("callstack", comarkText(children));
+  if (tag === "diff") {
+    const path = stringAttr(element, "path");
+    const lang = path === undefined ? "diff" : `diff:${path}`;
+    return fenceView(lang, comarkText(children));
+  }
+  if (tag === "file") return fileView(element, children);
+  if (tag === "html") return htmlView(element, children);
+  const convertedChildren = children.flatMap(fromNode);
+  return {
+    type: "element",
+    tag,
+    attrs: elementAttrs(element),
+    children:
+      tag === "li" && element[1].task === true
+        ? unwrapTaskParagraph(convertedChildren)
+        : convertedChildren,
+  };
+}
+
+function unwrapTaskParagraph(children: ViewerNode[]): ViewerNode[] {
+  const first = children[0];
+  if (
+    children.length === 1 &&
+    first !== undefined &&
+    first.type === "element" &&
+    first.tag === "p"
+  ) {
+    return first.children;
+  }
+  return children;
+}
+
+function fenceView(lang: string | undefined, source: string): ViewerView {
+  return {
+    type: "view",
+    fence: parseFence(lang === undefined ? "" : lang, source),
+  };
+}
+
+function fileView(
+  element: ComarkElement,
+  children: ComarkNode[],
+): ViewerView | ViewerNode[] {
+  const path = stringAttr(element, "path");
+  if (path === undefined) return children.flatMap(fromNode);
+  const start = lineAttr(element, "start");
+  const end = lineAttr(element, "end");
+  // MDC ::file with no range loads the whole file.
+  return fenceView(
+    `${start === undefined ? 1 : start}:${end === undefined ? Number.MAX_SAFE_INTEGER : end}:${path}`,
+    comarkText(children),
+  );
+}
+
+function htmlView(
+  element: ComarkElement,
+  children: ComarkNode[],
+): ViewerHtml | ViewerView {
+  const source = comarkText(children);
+  if (children.every((child) => !Array.isArray(child))) {
+    return {
+      type: "html",
+      block: element[1].block === true,
+      source,
+    };
+  }
+  return {
+    type: "view",
+    fence: parseFence("html", source),
+  };
+}
+
+function elementAttrs(element: ComarkElement): ViewerElementAttrs {
+  const checked = element[1].checked;
+  return {
+    id: stringAttr(element, "id"),
+    href: stringAttr(element, "href"),
+    src: stringAttr(element, "src"),
+    alt: stringAttr(element, "alt"),
+    title: stringAttr(element, "title"),
+    className: stringAttr(element, "class"),
+    start: lineAttr(element, "start"),
+    checked: checked === true ? true : checked === false ? false : undefined,
+    task: element[1].task === true ? true : undefined,
+    alertType: stringAttr(element, "type"),
+    align: stringAttr(element, "align"),
+  };
+}
+
+function stringAttr(element: ComarkElement, key: string) {
+  const value = element[1][key];
+  if (value === undefined) return undefined;
+  // SAFETY: md4x string attributes are JSON strings.
+  return value as string;
+}
+
+function lineAttr(element: ComarkElement, key: string) {
+  const value = stringAttr(element, key);
+  if (value === undefined) return undefined;
+  const parsed = Number(value);
+  if (!Number.isInteger(parsed) || parsed < 1) return undefined;
+  return parsed;
+}
+
+function comarkText(nodes: ComarkNode[]): string {
+  return nodes
+    .map((node) => {
+      if (!Array.isArray(node)) return node;
+      const [, , ...children] = node;
+      return comarkText(children);
+    })
+    .join("");
+}

package/src/registry.ts

@@ -0,0 +1,121 @@
+import fs from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+import * as errore from "errore";
+import { DiffmapRegistryError } from "./errors.js";
+
+type RunningDiffmap = {
+  pid: number;
+  title: string;
+  url: string;
+  file: string;
+};
+
+const registryDirectory = path.join(
+  os.tmpdir(),
+  `diffmap-${os.userInfo().uid}`,
+);
+
+export async function registerRunningDiffmap(entry: RunningDiffmap) {
+  const created = await fs
+    .mkdir(registryDirectory, { recursive: true, mode: 0o700 })
+    .catch(
+      (cause) =>
+        new DiffmapRegistryError({ reason: "create directory", cause }),
+    );
+  if (created instanceof Error) return created;
+
+  const registryPath = path.join(registryDirectory, `${entry.pid}.json`);
+  const written = await fs
+    .writeFile(registryPath, JSON.stringify(entry), { mode: 0o600 })
+    .catch(
+      (cause) => new DiffmapRegistryError({ reason: "write entry", cause }),
+    );
+  if (written instanceof Error) return written;
+  return registryPath;
+}
+
+export async function unregisterRunningDiffmap(registryPath: string) {
+  return await fs
+    .unlink(registryPath)
+    .catch(
+      (cause) => new DiffmapRegistryError({ reason: "remove entry", cause }),
+    );
+}
+
+export async function listRunningDiffmaps() {
+  const names = await fs.readdir(registryDirectory).catch((cause: unknown) => {
+    if (isFileSystemError(cause) && cause.code === "ENOENT") return [];
+    return new DiffmapRegistryError({ reason: "read directory", cause });
+  });
+  if (names instanceof Error) return names;
+
+  const [entries, readErrors] = errore.partition(
+    await Promise.all(
+      names
+        .filter((name) => name.endsWith(".json"))
+        .map((name) => readRegistryEntry(path.join(registryDirectory, name))),
+    ),
+  );
+  const readError = readErrors.at(0);
+  if (readError !== undefined) return readError;
+
+  const [running, cleanupErrors] = errore.partition(
+    await Promise.all(
+      entries.map(async (entry) => {
+        const reachable = await isRunning(entry);
+        if (reachable) return entry;
+
+        const removed = await unregisterRunningDiffmap(
+          path.join(registryDirectory, `${entry.pid}.json`),
+        );
+        if (removed instanceof Error) return removed;
+        return undefined;
+      }),
+    ),
+  );
+  const cleanupError = cleanupErrors.at(0);
+  if (cleanupError !== undefined) return cleanupError;
+  return running.filter((entry) => entry !== undefined);
+}
+
+async function readRegistryEntry(registryPath: string) {
+  const source = await fs
+    .readFile(registryPath, "utf8")
+    .catch(
+      (cause) => new DiffmapRegistryError({ reason: "read entry", cause }),
+    );
+  if (source instanceof Error) return source;
+  return errore.try({
+    // SAFETY: registerRunningDiffmap is the only writer for registry entries.
+    try: () => JSON.parse(source) as RunningDiffmap,
+    catch: (cause) =>
+      new DiffmapRegistryError({ reason: "parse entry", cause }),
+  });
+}
+
+async function isRunning(entry: RunningDiffmap) {
+  const response = await fetch(`${entry.url}/__diffmap/meta`, {
+    signal: AbortSignal.timeout(500),
+  }).catch(
+    (cause) => new DiffmapRegistryError({ reason: "reach server", cause }),
+  );
+  if (response instanceof Error) return false;
+  if (!response.ok) return false;
+
+  // SAFETY: diffmap serves this shape from its private metadata endpoint.
+  const meta = await (
+    response.json() as Promise<{
+      pid: number;
+      file: string;
+    }>
+  ).catch(
+    (cause) => new DiffmapRegistryError({ reason: "read server", cause }),
+  );
+  if (meta instanceof Error) return false;
+  return meta.pid === entry.pid && meta.file === entry.file;
+}
+
+function isFileSystemError(cause: unknown): cause is NodeJS.ErrnoException {
+  return cause instanceof Error && "code" in cause;
+}