@tanishqkancharla/diffmap 0.1.4 → 0.2.0

package/src/parseFence.ts

@@ -1,4 +1,5 @@
 import { parseCallStack, type SourceAnnotation } from "./annotations.js";
+import { WORKING, type Rev } from "./changes.js";
 import {
   parseDiagramAnnotations,
   type DiagramAnnotation,
@@ -8,7 +9,7 @@ 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: "changes"; rev: Rev; 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 };
@@ -46,12 +47,11 @@ export function parseFence(lang: string, source: string): Fence {
       lines: parseCallStack(trimmed),
     };
 
-  const sourceDiff = /^source-diff:([\w-]+):(.+)$/.exec(lang);
-  if (sourceDiff !== null) {
+  if (lang === "changes") {
+    const rev = trimmed.trim();
     return {
-      kind: "source-diff",
-      id: sourceDiff[1]!,
-      path: sourceDiff[2]!,
+      kind: "changes",
+      rev: rev.length === 0 ? WORKING : rev,
       source: trimmed,
     };
   }

package/src/parseViewer.test.ts

@@ -74,6 +74,92 @@ test("parseViewerDocument accepts a spec with valid mermaid", async () => {
   );
 });
 
+test("parseViewerDocument turns prose [[path#symbol]] into a short reference", () => {
+  const source =
+    "See [[packages/server/src/agent/Thread.ts#Thread.attach]] here, not `[[path]]` or [x [[a.ts]]](https://x.dev).\n";
+  const document = parseViewerDocument(source);
+  assert.equal(document instanceof Error, false);
+  if (document instanceof Error) return;
+  assert.equal(document.references.length, 1);
+  const paragraph = document.nodes[0];
+  assert.equal(paragraph?.type, "element");
+  if (paragraph?.type !== "element") return;
+  assert.deepEqual(
+    paragraph.children.map((node) =>
+      node.type === "element"
+        ? { tag: node.tag, children: node.children }
+        : node,
+    ),
+    [
+      { type: "text", value: "See " },
+      {
+        type: "reference",
+        annotation: {
+          text: "Thread.ts#Thread.attach",
+          references: [
+            {
+              kind: "file",
+              path: "packages/server/src/agent/Thread.ts",
+              symbol: "Thread.attach",
+            },
+          ],
+        },
+      },
+      { type: "text", value: " here, not " },
+      { tag: "code", children: [{ type: "text", value: "[[path]]" }] },
+      { type: "text", value: " or " },
+      { tag: "a", children: [{ type: "text", value: "x [[a.ts]]" }] },
+      { type: "text", value: "." },
+    ],
+  );
+  assert.equal(
+    parseViewerDocument("See [[missing:new:1]].\n") instanceof Error,
+    true,
+  );
+});
+
+test("parseViewerDocument reads commit references and changes fences", () => {
+  const document = parseViewerDocument(
+    [
+      "```changes",
+      "a1b2c3d..e4f5a6b",
+      "```",
+      "",
+      "```changes",
+      "```",
+      "",
+      "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"]);
+  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 },
+  ]);
+  // A commit with a symbol, or a changes fence that is not a SHA, is an error.
+  assert.equal(
+    parseViewerDocument("See [[a1b2c3d:src/store.ts#save]].\n") instanceof
+      Error,
+    true,
+  );
+  assert.equal(
+    parseViewerDocument("```changes\nmain\n```\n") instanceof Error,
+    true,
+  );
+  // The removed patch fence fails instead of rendering as code.
+  assert.match(
+    String(
+      parseViewerDocument(
+        "```source-diff:store:src/store.ts\ndiff --git a/x b/x\n```\n",
+      ),
+    ),
+    /source-diff:store:src\/store\.ts" fences were removed/,
+  );
+});
+
 test("parseViewerDocument fails on broken mermaid with file and diagram", () => {
   const source = brokenMermaidSpec();
   const parsed = parseViewerDocument(source, "broken.md");
@@ -138,6 +224,7 @@ test("startServer does not listen when mermaid is invalid", async () => {
 test("shareMarkdownFile does not call gh when mermaid is invalid", async () => {
   await withTempSpec(brokenMermaidSpec(), async (filePath) => {
     const shared = await shareMarkdownFile({
+      workspaceRoot: packageRoot,
       filePath,
       isPublic: false,
     });

package/src/parseViewer.ts

@@ -1,7 +1,13 @@
 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 {
+  parseReference,
+  referenceLabel,
+  type SourceAnnotation,
+  type SourceReference,
+} from "./annotations.js";
+import { isRev, type Rev } from "./changes.js";
 import { DiffmapAnnotationError, DiffmapParseError } from "./errors.js";
 import { parseMermaidDiagram } from "./mermaid.js";
 import { parseFence, type Fence } from "./parseFence.js";
@@ -9,8 +15,10 @@ import { parseFence, type Fence } from "./parseFence.js";
 export type ViewerDocument = {
   nodes: ViewerNode[];
   headings: ViewerHeading[];
-  sourceDiffs: CodeViewDiffItem[];
-  hasReferences: boolean;
+  /** Every reference in stacks, diagrams, and prose. */
+  references: SourceReference[];
+  /** Revs of `changes` fences, in document order. */
+  changeRevs: Rev[];
 };
 
 export type ViewerHeading = {
@@ -19,7 +27,12 @@ export type ViewerHeading = {
   id: string;
 };
 
-export type ViewerNode = ViewerText | ViewerElement | ViewerHtml | ViewerView;
+export type ViewerNode =
+  | ViewerText
+  | ViewerElement
+  | ViewerHtml
+  | ViewerView
+  | ViewerReference;
 
 export type ViewerText = {
   type: "text";
@@ -44,6 +57,12 @@ export type ViewerView = {
   fence: Fence;
 };
 
+/** A `[[path#symbol]]` in prose. The annotation text is the short label. */
+export type ViewerReference = {
+  type: "reference";
+  annotation: SourceAnnotation;
+};
+
 export type ViewerElementAttrs = {
   id: string | undefined;
   href: string | undefined;
@@ -64,49 +83,32 @@ export function parseViewerDocument(source: string, path = "spec") {
     catch: (cause) => new DiffmapParseError({ cause }),
   });
   if (tree instanceof Error) return tree;
-  const nodes = tree.nodes.flatMap(fromNode);
+  const nodes = tree.nodes.flatMap((node) => fromNode(node));
   const fences = collectFences(nodes);
-  const sourceDiffs: CodeViewDiffItem[] = [];
+  const changeRevs: Rev[] = [];
   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
-    ) {
+    if (fence.kind === "code" && fence.lang.startsWith("source-diff")) {
       return new DiffmapAnnotationError({
-        reason: `Source diff "${fence.id}" must contain one file with unified diff hunks`,
+        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 (fileDiff.name !== fence.path) {
+    if (fence.kind !== "changes") continue;
+    if (!isRev(fence.rev)) {
       return new DiffmapAnnotationError({
-        reason: `Source diff "${fence.id}" path does not match its patch (${fileDiff.name})`,
+        reason: `Invalid changes "${fence.rev}". Use a commit SHA, a SHA range (a1b2c3d..e4f5a6b), or leave it empty for uncommitted changes`,
       });
     }
-    sourceDiffs.push({ id: fence.id, type: "diff", fileDiff });
+    changeRevs.push(fence.rev);
   }
-  const annotations = fences.flatMap((fence) => {
-    if (fence.kind === "callstack") return fence.lines;
-    if (fence.kind === "mermaid")
-      return fence.annotations.map((link) => link.annotation);
-    return [];
-  });
+  const annotations = [
+    ...fences.flatMap((fence) => {
+      if (fence.kind === "callstack") return fence.lines;
+      if (fence.kind === "mermaid")
+        return fence.annotations.map((link) => link.annotation);
+      return [];
+    }),
+    ...collectReferences(nodes),
+  ];
   const mermaidFences = fences.flatMap((fence) =>
     fence.kind === "mermaid" ? [fence] : [],
   );
@@ -136,44 +138,24 @@ export function parseViewerDocument(source: string, path = "spec") {
   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]]`,
+        reason: `Invalid reference in "${line.text}". Use [[path]], [[path#symbol]], [[path#L12-L30]], or [[<commit>:path#L12-L30]]; source-diff patch references were removed`,
       });
     }
     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) {
+      if (ref.kind !== "file") continue;
+      if (ref.rev !== undefined && ref.symbol !== undefined) {
         return new DiffmapAnnotationError({
-          reason: `Unknown source diff "${ref.id}"`,
+          reason: `Symbol references read current files. Use a line range with a commit: [[${ref.rev}:${ref.path}#L12-L30]]`,
         });
       }
-      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
+        ref.start !== undefined &&
+        (!Number.isSafeInteger(ref.start) ||
+          !Number.isSafeInteger(ref.end) ||
+          ref.end! < ref.start)
       ) {
         return new DiffmapAnnotationError({
-          reason: `Range ${ref.side}:${ref.start}-${ref.end} is not in a hunk of "${ref.id}"`,
+          reason: `Invalid file range in "${ref.path}"`,
         });
       }
     }
@@ -181,10 +163,8 @@ export function parseViewerDocument(source: string, path = "spec") {
   return {
     nodes,
     headings: collectHeadings(nodes),
-    sourceDiffs,
-    hasReferences: annotations.some(
-      (annotation) => annotation.references.length > 0,
-    ),
+    references: annotations.flatMap((annotation) => annotation.references),
+    changeRevs,
   };
 }
 
@@ -196,6 +176,14 @@ function collectFences(nodes: ViewerNode[]): Fence[] {
   });
 }
 
+function collectReferences(nodes: ViewerNode[]): SourceAnnotation[] {
+  return nodes.flatMap((node) => {
+    if (node.type === "reference") return [node.annotation];
+    if (node.type === "element") return collectReferences(node.children);
+    return [];
+  });
+}
+
 function mermaidWhere(source: string, index: number) {
   const line = mermaidFenceLine(source, index);
   if (line === undefined) return `diagram ${index}`;
@@ -283,31 +271,67 @@ function uniqueHeadingId(text: string, usedIds: Set<string>) {
 
 function viewerNodeText(node: ViewerNode): string {
   if (node.type === "text") return node.value;
+  if (node.type === "reference") return node.annotation.text;
   if (node.type !== "element") return "";
   return node.children.map(viewerNodeText).join("");
 }
 
-function fromNode(node: ComarkNode): ViewerNode[] {
+function fromNode(node: ComarkNode, literal = false): ViewerNode[] {
   if (!Array.isArray(node)) {
-    return [{ type: "text", value: node }];
+    return literal ? [{ type: "text", value: node }] : proseText(node);
   }
-  const converted = fromElement(node);
+  const converted = fromElement(node, literal);
   if (converted === undefined) return [];
   if (Array.isArray(converted)) return converted;
   return [converted];
 }
 
+/** Splits `[[path#symbol]]` references out of prose text. */
+function proseText(value: string): ViewerNode[] {
+  const nodes: ViewerNode[] = [];
+  let last = 0;
+  for (const match of value.matchAll(/\[\[([^[\]\n]+)\]\]/g)) {
+    const reference = parseReference(match[1]!);
+    // The removed `[[id:old|new:N]]` patch syntax must fail, not render as text.
+    const removed =
+      reference === undefined && /^[\w-]+:(old|new):\d/.test(match[1]!);
+    if (reference === undefined && !removed) continue;
+    if (match.index > last)
+      nodes.push({ type: "text", value: value.slice(last, match.index) });
+    nodes.push({
+      type: "reference",
+      annotation:
+        reference === undefined
+          ? { text: match[0], references: [] }
+          : { text: referenceLabel(reference, true), references: [reference] },
+    });
+    last = match.index + match[0].length;
+  }
+  if (last < value.length)
+    nodes.push({ type: "text", value: value.slice(last) });
+  return nodes;
+}
+
 function fromElement(
   element: ComarkElement,
+  literal: boolean,
 ): ViewerNode | ViewerNode[] | undefined {
   const [tag, , ...children] = element;
   if (tag === null) return undefined;
-  if (tag === "template") return children.flatMap(fromNode);
+  // Code spans show the syntax literally; links cannot nest a button.
+  const literalChildren = literal || tag === "code" || tag === "a";
+  if (tag === "template")
+    return children.flatMap((child) => fromNode(child, literalChildren));
   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 === "changes")
+    return fenceView(
+      "changes",
+      stringAttr(element, "rev") ?? comarkText(children),
+    );
   if (tag === "diff") {
     const path = stringAttr(element, "path");
     const lang = path === undefined ? "diff" : `diff:${path}`;
@@ -315,7 +339,9 @@ function fromElement(
   }
   if (tag === "file") return fileView(element, children);
   if (tag === "html") return htmlView(element, children);
-  const convertedChildren = children.flatMap(fromNode);
+  const convertedChildren = children.flatMap((child) =>
+    fromNode(child, literalChildren),
+  );
   return {
     type: "element",
     tag,
@@ -352,7 +378,7 @@ function fileView(
   children: ComarkNode[],
 ): ViewerView | ViewerNode[] {
   const path = stringAttr(element, "path");
-  if (path === undefined) return children.flatMap(fromNode);
+  if (path === undefined) return children.flatMap((child) => fromNode(child));
   const start = lineAttr(element, "start");
   const end = lineAttr(element, "end");
   // MDC ::file with no range loads the whole file.