@tanishqkancharla/diffmap 0.2.0 → 0.3.0

package/README.md

@@ -170,9 +170,16 @@ Malformed references produce a parse error.
 
 On a GitHub-hosted spec, commit diffs come from the GitHub API. It returns patch
 hunks only, so only lines near changes are reachable, and the Diff button opens
-the pull request's full diff. `diffmap share` saves every referenced commit to a
-`diffmap-changes.json` file in the gist. Uncommitted references only work in a
-local viewer.
+the pull request's full diff.
+
+A shared gist is a snapshot taken when you run `diffmap share`. It saves every
+referenced commit and every `changes` card, including uncommitted ones, to
+`diffmap-changes.json`. It saves the current contents of every file that a file
+excerpt or a reference without a commit reads to `diffmap-files.json`. In the
+gist, those references open the saved file; symbols resolve to their first
+matching line, and Cmd-click definitions only work in a local viewer. Commit
+your work and point references at the commit before sharing, so the gist shows
+the diff instead of a bare file.
 
 Cmd-click (or Ctrl-click) a TypeScript or JavaScript symbol in the source panel
 to open its definition. Use Back to retrace navigation and return to the reference.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tanishqkancharla/diffmap",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "Serve a spec or code walkthrough as a local page",
   "license": "MIT",
   "author": "Tanishq Kancharla",

package/src/changes.ts

@@ -159,6 +159,12 @@ export type Changes = {
 /** Gist file holding the changes a shared spec references, keyed by rev. */
 export const GIST_CHANGES_FILE = "diffmap-changes.json";
 
+/**
+ * Gist file holding the current contents of files a shared spec reads live,
+ * keyed by path: file excerpts and references without a commit.
+ */
+export const GIST_FILES_FILE = "diffmap-files.json";
+
 export type ChangesResponse = { changes?: Changes; error?: string };
 
 /** jsdiff's default lines of context around each change. */

package/src/gist/GistApp.tsx

@@ -13,6 +13,7 @@ import { ViewerApp } from "../viewer/ViewerApp.tsx";
 import { loadGistMarkdown, type GistDocument } from "./fetchGist.ts";
 import { GistPinContext } from "./pin.ts";
 import { HostHome } from "../host/HostHome.tsx";
+import { HostFilesContext } from "../host/files.ts";
 import { GistLoading, GistStatus } from "./GistStatus.tsx";
 import {
   gistPath,
@@ -166,26 +167,28 @@ export function GistApp() {
         htmlUrl: view.gist.htmlUrl,
       }}
     >
-      <ChangesLoaderContext.Provider value={view.loadChanges}>
-        <ViewerApp
-          key={`${view.gist.id}:${view.file}`}
-          document={view.document}
-          mode="gist"
-          headerActions={
-            <GistHeader
-              gistId={view.gist.id}
-              htmlUrl={view.gist.htmlUrl}
-              files={view.gist.files}
-              current={view.file}
-              onSelect={(file) => {
-                const next = gistPath(view.gist.id, file);
-                window.history.pushState({}, "", next);
-                setRoute(parseGistPath(next));
-              }}
-            />
-          }
-        />
-      </ChangesLoaderContext.Provider>
+      <HostFilesContext.Provider value={view.gist.sourceFiles}>
+        <ChangesLoaderContext.Provider value={view.loadChanges}>
+          <ViewerApp
+            key={`${view.gist.id}:${view.file}`}
+            document={view.document}
+            mode="gist"
+            headerActions={
+              <GistHeader
+                gistId={view.gist.id}
+                htmlUrl={view.gist.htmlUrl}
+                files={view.gist.files}
+                current={view.file}
+                onSelect={(file) => {
+                  const next = gistPath(view.gist.id, file);
+                  window.history.pushState({}, "", next);
+                  setRoute(parseGistPath(next));
+                }}
+              />
+            }
+          />
+        </ChangesLoaderContext.Provider>
+      </HostFilesContext.Provider>
     </GistPinContext.Provider>
   );
 }

package/src/gist/fetchGist.ts

@@ -1,4 +1,10 @@
-import { GIST_CHANGES_FILE, type Changes, type Rev } from "../changes.ts";
+import {
+  GIST_CHANGES_FILE,
+  GIST_FILES_FILE,
+  type Changes,
+  type Rev,
+} from "../changes.ts";
+import type { HostFiles } from "../host/files.ts";
 import { githubGistUrl, markdownFileNames, pickMarkdownFile } from "./route.ts";
 
 export type GistMarkdownFile = {
@@ -11,8 +17,10 @@ export type GistDocument = {
   htmlUrl: string;
   files: GistMarkdownFile[];
   chosen: GistMarkdownFile;
-  /** Snapshot `diffmap share` saved for each commit the spec references. */
+  /** Snapshot `diffmap share` saved for each commit and changes card the spec references. */
   changes: Record<Rev, Changes>;
+  /** Files excerpts and references without a commit read, as they were when shared. */
+  sourceFiles: HostFiles;
 };
 
 export type GistLoadResult =
@@ -98,23 +106,21 @@ export async function loadGistMarkdown(
     return { status: "missing-file", htmlUrl, files };
   }
 
-  const snapshotFile = apiFiles[GIST_CHANGES_FILE];
-  const snapshot =
-    snapshotFile === undefined
-      ? "{}"
-      : await readGistFile(snapshotFile, signal);
-  if (snapshot instanceof Error) {
-    return { status: "error", message: snapshot.message };
+  // SAFETY: diffmap share writes this file from readDocumentChanges.
+  const changes = (await readSnapshot(apiFiles, GIST_CHANGES_FILE, signal)) as
+    | Record<Rev, Changes>
+    | Error;
+  if (changes instanceof Error) {
+    return { status: "error", message: changes.message };
   }
-  let changes: Record<Rev, Changes>;
-  try {
-    // SAFETY: diffmap share writes this file from readDocumentChanges.
-    changes = JSON.parse(snapshot) as Record<Rev, Changes>;
-  } catch {
-    return {
-      status: "error",
-      message: `${GIST_CHANGES_FILE} is not valid JSON.`,
-    };
+  // SAFETY: diffmap share writes this file as path to contents.
+  const sourceFiles = (await readSnapshot(
+    apiFiles,
+    GIST_FILES_FILE,
+    signal,
+  )) as HostFiles | Error;
+  if (sourceFiles instanceof Error) {
+    return { status: "error", message: sourceFiles.message };
   }
 
   return {
@@ -125,10 +131,28 @@ export async function loadGistMarkdown(
       files,
       chosen,
       changes,
+      sourceFiles,
     },
   };
 }
 
+/** A JSON file `diffmap share` wrote, or `{}` when the gist predates it. */
+async function readSnapshot(
+  apiFiles: Record<string, GistApiFile>,
+  name: string,
+  signal?: AbortSignal,
+): Promise<unknown> {
+  const file = apiFiles[name];
+  if (file === undefined) return {};
+  const text = await readGistFile(file, signal);
+  if (text instanceof Error) return text;
+  try {
+    return JSON.parse(text) as unknown;
+  } catch {
+    return new Error(`${name} is not valid JSON.`);
+  }
+}
+
 async function readGistFile(file: GistApiFile, signal?: AbortSignal) {
   const name = file.filename ?? "file";
   if (file.truncated !== true && typeof file.content === "string") {

package/src/host/files.ts

@@ -1,6 +1,10 @@
 import { createContext, useContext } from "react";
 
-/** Bundled files for the hosted homepage. `[[path]]` reads these, not GitHub. */
+/**
+ * Files a hosted viewer has without a server: the homepage's bundled sources,
+ * or the files `diffmap share` saved in a gist. `[[path]]` and file excerpts
+ * read these, not GitHub.
+ */
 export type HostFiles = Record<string, string>;
 
 export const HostFilesContext = createContext<HostFiles | undefined>(undefined);

package/src/parseViewer.test.ts

@@ -234,6 +234,59 @@ test("shareMarkdownFile does not call gh when mermaid is invalid", async () => {
   });
 });
 
+test("shareMarkdownFile uploads the files excerpts and rev-less references read", async () => {
+  const spec = [
+    "# Shared",
+    "",
+    "See [[src/share.ts#shareMarkdownFile]].",
+    "",
+    "```1:3:src/changes.ts",
+    "```",
+    "",
+  ].join("\n");
+  await withTempSpec(spec, async (filePath) => {
+    const dir = path.dirname(filePath);
+    const uploaded = path.join(dir, "uploaded");
+    await fs.mkdir(uploaded);
+    const gh = path.join(dir, "gh");
+    await fs.writeFile(
+      gh,
+      [
+        "#!/bin/sh",
+        'if [ "$1" = auth ]; then exit 0; fi',
+        `for arg; do case "$arg" in *.json) cp "$arg" ${JSON.stringify(uploaded)};; esac; done`,
+        "echo https://gist.github.com/0123456789abcdef0123456789abcdef",
+      ].join("\n"),
+      { mode: 0o755 },
+    );
+    const originalPath = process.env.PATH;
+    process.env.PATH = `${dir}${path.delimiter}${originalPath ?? ""}`;
+    try {
+      const shared = await shareMarkdownFile({
+        workspaceRoot: packageRoot,
+        filePath,
+        isPublic: false,
+      });
+      assert.equal(shared instanceof Error, false, String(shared));
+    } finally {
+      process.env.PATH = originalPath;
+    }
+    const files: unknown = JSON.parse(
+      await fs.readFile(path.join(uploaded, "diffmap-files.json"), "utf8"),
+    );
+    assert.deepEqual(files, {
+      "src/share.ts": await fs.readFile(
+        path.join(packageRoot, "src/share.ts"),
+        "utf8",
+      ),
+      "src/changes.ts": await fs.readFile(
+        path.join(packageRoot, "src/changes.ts"),
+        "utf8",
+      ),
+    });
+  });
+});
+
 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.`;
 }

package/src/parseViewer.ts

@@ -168,7 +168,7 @@ export function parseViewerDocument(source: string, path = "spec") {
   };
 }
 
-function collectFences(nodes: ViewerNode[]): Fence[] {
+export function collectFences(nodes: ViewerNode[]): Fence[] {
   return nodes.flatMap((node) => {
     if (node.type === "view") return [node.fence];
     if (node.type === "element") return collectFences(node.children);

package/src/share.ts

@@ -6,9 +6,14 @@ import { promisify } from "node:util";
 import { DiffmapFileError, DiffmapShareError } from "./errors.js";
 import { extractTitle } from "./extractDocument.js";
 import { extractGistId, gistViewerUrl } from "./gist/route.ts";
-import { GIST_CHANGES_FILE } from "./changes.js";
-import { readDocumentChanges } from "./git.js";
-import { parseViewerDocument } from "./parseViewer.js";
+import { GIST_CHANGES_FILE, GIST_FILES_FILE } from "./changes.js";
+import { readSourceReference } from "./definitions.js";
+import { readChanges, readDocumentChanges } from "./git.js";
+import {
+  collectFences,
+  parseViewerDocument,
+  type ViewerDocument,
+} from "./parseViewer.js";
 
 const execFileAsync = promisify(execFile);
 
@@ -39,6 +44,16 @@ export async function shareMarkdownFile(input: {
   // The hosted viewer has no git, so the gist carries a snapshot of each commit.
   const changes = await readDocumentChanges(input.workspaceRoot, parsed);
   if (changes instanceof Error) return changes;
+  // An uncommitted changes card shows the tree as it is when you share.
+  for (const rev of parsed.changeRevs) {
+    if (changes.has(rev)) continue;
+    const loaded = await readChanges(input.workspaceRoot, rev);
+    if (loaded instanceof Error) return loaded;
+    changes.set(rev, loaded);
+  }
+  // It has no files either, so excerpts and references without a commit read these.
+  const files = readDocumentFiles(input.workspaceRoot, parsed);
+  if (files instanceof Error) return files;
 
   const auth = await runGh(["auth", "status"]);
   if (auth instanceof DiffmapShareError) return auth;
@@ -46,14 +61,20 @@ export async function shareMarkdownFile(input: {
   const args = ["gist", "create"];
   if (input.isPublic) args.push("--public");
   args.push("--desc", extractTitle(source), filePath);
+  const snapshots = [
+    { name: GIST_CHANGES_FILE, value: Object.fromEntries(changes) },
+    { name: GIST_FILES_FILE, value: files },
+  ].filter((snapshot) => Object.keys(snapshot.value).length > 0);
   const snapshotDir =
-    changes.size === 0
+    snapshots.length === 0
       ? undefined
       : await fs.mkdtemp(path.join(os.tmpdir(), "diffmap-share-"));
   if (snapshotDir !== undefined) {
-    const snapshot = path.join(snapshotDir, GIST_CHANGES_FILE);
-    await fs.writeFile(snapshot, JSON.stringify(Object.fromEntries(changes)));
-    args.push(snapshot);
+    for (const snapshot of snapshots) {
+      const snapshotPath = path.join(snapshotDir, snapshot.name);
+      await fs.writeFile(snapshotPath, JSON.stringify(snapshot.value));
+      args.push(snapshotPath);
+    }
   }
 
   const created = await runGh(args);
@@ -81,6 +102,28 @@ export async function shareMarkdownFile(input: {
   };
 }
 
+/** Current contents of every file an excerpt or a reference without a commit reads, by path. */
+function readDocumentFiles(root: string, document: ViewerDocument) {
+  const paths = new Set<string>();
+  for (const reference of document.references) {
+    if (reference.kind === "file" && reference.rev === undefined)
+      paths.add(reference.path);
+  }
+  for (const fence of collectFences(document.nodes)) {
+    if (fence.kind === "file") paths.add(fence.path);
+  }
+  const files: Record<string, string> = {};
+  for (const filePath of paths) {
+    const read = readSourceReference(
+      root,
+      new URLSearchParams({ path: filePath }),
+    );
+    if (read instanceof Error) return read;
+    files[filePath] = read.contents;
+  }
+  return files;
+}
+
 async function runGh(args: string[]) {
   try {
     return await execFileAsync("gh", args, {

package/src/viewer/SourceDiffPanel.tsx

@@ -112,7 +112,8 @@ export function SourceDiffPanel(props: {
       ? navigation.status
       : source instanceof Error
         ? source.message
-        : changes instanceof Error
+        : // A shown file replaces the changes, so their error is moot, as in a gist without uncommitted changes.
+          changes instanceof Error && file === undefined
           ? changes.message
           : changes === undefined
             ? "Loading changes…"