@tanishqkancharla/diffmap 0.1.5 → 0.3.0

package/src/github/fetchRepo.ts

@@ -4,8 +4,8 @@
  * fetch `ref=main` / latest for spec markdown, [[path]] targets, excerpts, or
  * hunks. Private repos are out of scope (GitHub 404).
  */
-import type { CodeViewDiffItem } from "@pierre/diffs";
-import { pullFilesToSourceDiffs, type GitHubPullFile } from "./patch.ts";
+import { WORKING, type Changes, type Rev } from "../changes.ts";
+import { githubChangedFiles, type GitHubFile } from "./patch.ts";
 
 const GITHUB_API = "https://api.github.com";
 const GITHUB_JSON = {
@@ -21,7 +21,8 @@ export type PinnedSpec = {
   htmlUrl: string;
   pullNumber?: number;
   pullUrl?: string;
-  pullDiffs: CodeViewDiffItem[];
+  /** `base..head` of the pull request, for the Diff panel's default view. */
+  pullRev?: Rev;
 };
 
 export type GitHubSpecResult =
@@ -33,6 +34,20 @@ export type GitHubSpecResult =
 type PullApi = {
   html_url?: string;
   head?: { sha?: string };
+  base?: { sha?: string };
+};
+
+type CommitApi = {
+  sha?: string;
+  html_url?: string;
+  commit?: { message?: string };
+  files?: GitHubFile[];
+};
+
+type CompareApi = {
+  html_url?: string;
+  total_commits?: number;
+  files?: GitHubFile[];
 };
 
 type ContentsApi = {
@@ -56,6 +71,7 @@ export async function loadPinnedSpec(input: {
   let sha = input.sha;
   let pullNumber = input.pull;
   let pullUrl: string | undefined;
+  let pullRev: Rev | undefined;
   if (sha === undefined) {
     if (pullNumber === undefined) {
       return { status: "error", message: "Need a pull number or commit SHA." };
@@ -69,6 +85,10 @@ export async function loadPinnedSpec(input: {
     if (resolved.status !== "ok") return resolved;
     sha = resolved.sha;
     pullUrl = resolved.htmlUrl;
+    pullRev =
+      resolved.baseSha === undefined
+        ? undefined
+        : `${resolved.baseSha}..${sha}`;
   }
 
   const blob = await fetchPinnedBlob(
@@ -82,24 +102,6 @@ export async function loadPinnedSpec(input: {
     return { status: "error", message: blob.message };
   }
 
-  let pullDiffs: CodeViewDiffItem[] = [];
-  if (pullNumber !== undefined) {
-    const files = await fetchPullFiles(
-      input.owner,
-      input.repo,
-      pullNumber,
-      input.signal,
-    );
-    if (files instanceof Error) {
-      if (files.message === "forbidden") return { status: "forbidden" };
-      if (files.message !== "not-found") {
-        return { status: "error", message: files.message };
-      }
-    } else {
-      pullDiffs = pullFilesToSourceDiffs(files);
-    }
-  }
-
   return {
     status: "ok",
     spec: {
@@ -111,7 +113,7 @@ export async function loadPinnedSpec(input: {
       htmlUrl: `https://github.com/${input.owner}/${input.repo}/blob/${sha}/${input.path}`,
       pullNumber,
       pullUrl,
-      pullDiffs,
+      pullRev,
     },
   };
 }
@@ -161,7 +163,7 @@ async function resolvePullHead(
   pull: number,
   signal?: AbortSignal,
 ): Promise<
-  | { status: "ok"; sha: string; htmlUrl: string }
+  | { status: "ok"; sha: string; baseSha: string | undefined; htmlUrl: string }
   | { status: "not-found" }
   | { status: "forbidden" }
   | { status: "error"; message: string }
@@ -181,9 +183,11 @@ async function resolvePullHead(
       message: "GitHub did not return a pull head SHA.",
     };
   }
+  const baseSha = payload?.base?.sha;
   return {
     status: "ok",
     sha,
+    baseSha: typeof baseSha === "string" ? baseSha : undefined,
     htmlUrl:
       typeof payload?.html_url === "string"
         ? payload.html_url
@@ -191,31 +195,83 @@ async function resolvePullHead(
   };
 }
 
-async function fetchPullFiles(
-  owner: string,
-  repo: string,
-  pull: number,
-  signal?: AbortSignal,
-): Promise<GitHubPullFile[] | Error> {
-  const files: GitHubPullFile[] = [];
-  for (let page = 1; page <= 10; page++) {
-    const response = await githubFetch(
-      `/repos/${encodeURIComponent(owner)}/${encodeURIComponent(repo)}/pulls/${String(pull)}/files?per_page=100&page=${String(page)}`,
-      signal,
+const changesCache = new Map<string, Promise<Changes | Error>>();
+
+/** Commit or compare changes from the GitHub API. Patches only, no full contents. */
+export function fetchGitHubChanges(
+  repo: { owner: string; repo: string },
+  rev: Rev,
+): Promise<Changes | Error> {
+  if (rev === WORKING)
+    return Promise.resolve(
+      new Error("Uncommitted changes are only available in a local viewer."),
     );
-    if (response.status === "not-found") return new Error("not-found");
-    if (response.status === "forbidden") return new Error("forbidden");
+  const key = `${repo.owner}/${repo.repo}@${rev}`;
+  const pending = changesCache.get(key);
+  if (pending !== undefined) return pending;
+  const request = readGitHubChanges(repo, rev);
+  changesCache.set(key, request);
+  return request;
+}
+
+/** GitHub pages a commit's files up to 3000; a compare lists only its first 300. */
+const COMMIT_FILES_MAX = 3000;
+const COMPARE_FILES_MAX = 300;
+
+async function readGitHubChanges(
+  repo: { owner: string; repo: string },
+  rev: Rev,
+): Promise<Changes | Error> {
+  const base = `/repos/${encodeURIComponent(repo.owner)}/${encodeURIComponent(repo.repo)}`;
+  const [from, to] = rev.split("..");
+  const files: GitHubFile[] = [];
+  let first: (CommitApi & CompareApi) | undefined;
+  let next: string | undefined =
+    to === undefined
+      ? `${base}/commits/${from!}`
+      : `${base}/compare/${from!}...${to}`;
+  while (next !== undefined) {
+    const response = await githubFetch(next);
+    if (response.status === "not-found")
+      return new Error(
+        `GitHub has no commit ${rev} in ${repo.owner}/${repo.repo}.`,
+      );
+    if (response.status === "forbidden")
+      return new Error("GitHub rate-limited this request. Wait and refresh.");
     if (response.status === "error") return new Error(response.message);
     const payload = (await response.body.json().catch(() => undefined)) as
-      | GitHubPullFile[]
+      | (CommitApi & CompareApi)
       | undefined;
-    if (!Array.isArray(payload)) {
-      return new Error("GitHub returned invalid pull files.");
-    }
-    files.push(...payload);
-    if (payload.length < 100) break;
+    if (payload?.files === undefined)
+      return new Error("GitHub returned invalid changes.");
+    first ??= payload;
+    files.push(...payload.files);
+    // Compare pages list commits, not more files.
+    next = to === undefined ? nextPage(response.body) : undefined;
   }
-  return files;
+  const subject = first?.commit?.message?.split("\n", 1)[0] ?? "";
+  const truncated =
+    files.length >= (to === undefined ? COMMIT_FILES_MAX : COMPARE_FILES_MAX);
+  return {
+    rev,
+    title:
+      to === undefined
+        ? subject
+        : `${from!.slice(0, 7)}..${to.slice(0, 7)} · ${String(first?.total_commits ?? 0)} commits`,
+    ...(first?.html_url === undefined ? {} : { url: first.html_url }),
+    ...(truncated ? { truncated } : {}),
+    files: githubChangedFiles(files),
+  };
+}
+
+/** The API path of the `rel="next"` page in a GitHub `Link` header. */
+function nextPage(response: Response) {
+  const link = /<([^>]+)>;\s*rel="next"/.exec(
+    response.headers.get("link") ?? "",
+  );
+  if (link === null) return undefined;
+  const url = new URL(link[1]!);
+  return `${url.pathname}${url.search}`;
 }
 
 async function readContents(

package/src/github/patch.test.ts

@@ -1,10 +1,11 @@
 import assert from "node:assert/strict";
 import test from "node:test";
 import { parsePatchFiles } from "@pierre/diffs";
-import { pullFilesToSourceDiffs, wrapGitHubPullPatch } from "./patch.ts";
+import { changedFileItem } from "../changes.ts";
+import { githubChangedFiles, wrapGitHubPatch } from "./patch.ts";
 
-test("wrapGitHubPullPatch builds a unified diff Pierre can parse", () => {
-  const wrapped = wrapGitHubPullPatch({
+test("wrapGitHubPatch builds a unified diff Pierre can parse", () => {
+  const wrapped = wrapGitHubPatch({
     filename: "src/cli.ts",
     status: "modified",
     patch: ["@@ -1,3 +1,4 @@", " line", "+added", " line", " line"].join("\n"),
@@ -15,16 +16,24 @@ test("wrapGitHubPullPatch builds a unified diff Pierre can parse", () => {
   assert.ok((patches[0]?.files[0]?.hunks.length ?? 0) > 0);
 });
 
-test("pullFilesToSourceDiffs skips files without a patch", () => {
-  const diffs = pullFilesToSourceDiffs([
-    { filename: "icon.png", status: "added" },
+test("githubChangedFiles keeps files without a patch as binary, with no diff item", () => {
+  const files = githubChangedFiles([
+    { filename: "icon.png", status: "added", additions: 0, deletions: 0 },
     {
       filename: "src/cli.ts",
       status: "modified",
+      additions: 1,
+      deletions: 0,
       patch: ["@@ -1,2 +1,3 @@", " a", "+b", " c"].join("\n"),
     },
   ]);
-  assert.equal(diffs.length, 1);
-  assert.equal(diffs[0]?.id, "pr:src/cli.ts");
-  assert.equal(diffs[0]?.fileDiff.name, "src/cli.ts");
+  assert.deepEqual(
+    files.map((file) => [file.path, file.binary, file.additions]),
+    [
+      ["icon.png", true, 0],
+      ["src/cli.ts", false, 1],
+    ],
+  );
+  assert.equal(changedFileItem(files[0]!), undefined);
+  assert.equal(changedFileItem(files[1]!)?.fileDiff.name, "src/cli.ts");
 });

package/src/github/patch.ts

@@ -1,14 +1,17 @@
-import { parsePatchFiles, type CodeViewDiffItem } from "@pierre/diffs";
+import type { ChangedFile } from "../changes.ts";
 
-export type GitHubPullFile = {
+/** A file from GitHub's commit, compare, or pull-files APIs. */
+export type GitHubFile = {
   filename: string;
   previous_filename?: string;
   status: string;
+  additions?: number;
+  deletions?: number;
   patch?: string;
 };
 
-/** Wrap a GitHub pull-files `patch` (hunks only) as a unified diff Pierre can parse. */
-export function wrapGitHubPullPatch(file: GitHubPullFile) {
+/** Wrap a GitHub file `patch` (hunks only) as a unified diff Pierre can parse. */
+export function wrapGitHubPatch(file: GitHubFile) {
   if (file.patch === undefined || file.patch.length === 0) return undefined;
   const oldPath = file.previous_filename ?? file.filename;
   const newPath = file.filename;
@@ -22,19 +25,27 @@ export function wrapGitHubPullPatch(file: GitHubPullFile) {
   ].join("\n");
 }
 
-export function pullFilesToSourceDiffs(files: GitHubPullFile[]) {
-  const diffs: CodeViewDiffItem[] = [];
-  for (const file of files) {
-    const unified = wrapGitHubPullPatch(file);
-    if (unified === undefined) continue;
-    const patches = parsePatchFiles(unified, undefined, false);
-    const fileDiff = patches[0]?.files[0];
-    if (fileDiff === undefined || fileDiff.hunks.length === 0) continue;
-    diffs.push({
-      id: `pr:${file.filename}`,
-      type: "diff",
-      fileDiff,
-    });
-  }
-  return diffs;
+export function githubChangedFiles(files: GitHubFile[]): ChangedFile[] {
+  return files.map((file) => {
+    const patch = wrapGitHubPatch(file);
+    return {
+      path: file.filename,
+      ...(file.previous_filename === undefined
+        ? {}
+        : { prevPath: file.previous_filename }),
+      status:
+        file.status === "added"
+          ? "added"
+          : file.status === "removed"
+            ? "deleted"
+            : file.status === "renamed"
+              ? "renamed"
+              : "modified",
+      additions: file.additions ?? 0,
+      deletions: file.deletions ?? 0,
+      // GitHub omits the patch for binary and very large files.
+      binary: patch === undefined,
+      ...(patch === undefined ? {} : { patch }),
+    };
+  });
 }

package/src/host/HostHome.tsx

@@ -5,6 +5,11 @@ import { parseViewerDocument } from "../parseViewer.ts";
 import type { ViewerDocument } from "../parseViewer.ts";
 import { ViewerApp } from "../viewer/ViewerApp.tsx";
 import { GistLoading, GistStatus } from "../gist/GistStatus.tsx";
+import { fetchGitHubChanges } from "../github/fetchRepo.ts";
+import {
+  ChangesLoaderContext,
+  type ChangesLoader,
+} from "../viewer/changesSource.ts";
 import { HostFilesContext } from "./files.ts";
 import homeSource from "./home.md?raw";
 import cliSource from "../cli.ts?raw";
@@ -26,6 +31,10 @@ const hostFiles = {
   "src/github/route.ts": githubRouteSource,
 };
 
+/** The homepage walks through diffmap's own commits, read from GitHub. */
+const loadHostChanges: ChangesLoader = (rev) =>
+  fetchGitHubChanges({ owner: "tanishqkancharla", repo: "diffmap" }, rev);
+
 export function HostHome() {
   const [view, setView] = useState<
     | { kind: "loading" }
@@ -61,13 +70,17 @@ export function HostHome() {
 
   return (
     <HostFilesContext.Provider value={hostFiles}>
-      <ViewerApp
-        document={view.document}
-        mode="host"
-        headerActions={
-          <Link href="https://github.com/tanishqkancharla/diffmap">GitHub</Link>
-        }
-      />
+      <ChangesLoaderContext.Provider value={loadHostChanges}>
+        <ViewerApp
+          document={view.document}
+          mode="host"
+          headerActions={
+            <Link href="https://github.com/tanishqkancharla/diffmap">
+              GitHub
+            </Link>
+          }
+        />
+      </ChangesLoaderContext.Provider>
     </HostFilesContext.Provider>
   );
 }

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/host/home.md

@@ -7,7 +7,7 @@ TOC on the left, article here, Diff on the right. Click a stack row or a mermaid
 ## Install the skill
 
 ```sh
-npx skills add tanishqkancharla/diffmap --skill generate-spec
+npx skills add tanishqkancharla/diffmap --skill generate-diffmap
 ```
 
 That keeps a living spec in `specs/<name>.md`. Same file for the life of the work: what’s already in the tree, and what’s still planned. Don’t start a second walkthrough later.
@@ -42,13 +42,13 @@ Pinned commit:
 
 `https://diffmap.dev/<owner>/<repo>/commit/<sha>/specs/<name>.md`
 
-The pin is one SHA. The markdown and every `[[path]]`, mermaid `%% ref`, excerpt, and hunk load from that commit, not `main`. A PR number only chooses the SHA (head at load, then pin). Refresh stays on the commit URL.
+The pin is one SHA. The markdown and every `[[path]]`, mermaid `%% ref`, and excerpt load from that commit, not `main`. Commit references load their diffs from the GitHub API. A PR number only chooses the SHA (head at load, then pin). Refresh stays on the commit URL.
 
 ## What the fences are
 
 ### System flow
 
-Click a node. `%% ref` is a mermaid comment; `[[path]]` and `[[path#symbol]]` are the same references as on a stack row.
+Click a node. `%% ref` is a mermaid comment; `[[path]]`, `[[path#symbol]]`, and `[[<sha>:path#L12-L30]]` are the same references as on a stack row.
 
 ```mermaid
 flowchart LR
@@ -59,7 +59,7 @@ flowchart LR
   %% ref node:Serve [[src/cli.ts]]
   %% ref node:Share [[src/share.ts#shareMarkdownFile]]
   %% ref node:Pin [[src/github/route.ts]]
-  %% ref edge:0 [[cli:new:50]]
+  %% ref edge:0 [[1257fe8:src/cli.ts#L49-L50]]
 ```
 
 ````md
@@ -72,68 +72,30 @@ flowchart LR
 
 ### Call stacks
 
-`-` is current, `+` is proposed. After a phase lands, retarget `[[path]]` to a hunk: `[[id:old:…]]` / `[[id:new:…]]`.
+`-` is current, `+` is proposed. After a phase lands, commit it and retarget `[[path]]` to the commit: `[[<sha>:path#L12-L30]]`. Line numbers are the file after the commit.
 
 ```callstack
  ViewerApp
--└── CloseServerButton  # every hosted page tried to stop a server [[close:old:217]]
-+└── CloseServerButton  # local mode only [[close:new:217-224]]
+-└── DoneButton  # a loud Done control
++└── CloseServerButton  # quiet, local mode only [[dae6b98:src/viewer/ViewerApp.tsx#L219-L227]] [[dae6b98:src/viewer/CloseServerButton.tsx#L8-L16]]
      └── DiffButton
 ```
 
 ```callstack
  shareMarkdownFile [[src/share.ts#shareMarkdownFile]]
--└── print gist URL [[share:old:62]]
-+└── gistViewerUrl  # https://diffmap.dev/g/<id> [[share:new:62]]
+-└── print the gist URL
++└── gistViewerUrl  # https://diffmap.dev/g/<id> [[d14ae1a:src/share.ts#L55-L59]]
 ```
 
-### Source patches
+### Changes
 
-Define each id once. Copy the real `git diff` (`diff --git`, `---`, `+++`, `@@`). Ranges have to sit inside an included hunk.
+A `changes` fence names a commit. It renders a card with every file that commit changed. **Review** opens the Diff panel on all of them, with a sticky header per file; a row jumps to its file. An empty body means uncommitted changes.
 
-```source-diff:cli:src/cli.ts
-diff --git a/src/cli.ts b/src/cli.ts
---- a/src/cli.ts
-+++ b/src/cli.ts
-@@ -49,4 +49,4 @@
- const cli = Cli.create("diffmap", {
--  description: "Serve a walkthrough",
-+  description: "Serve a spec locally, or share it as a gist",
-   version: "0.1.3",
-   args: serveArgs,
+```changes
+dae6b98
 ```
 
-```source-diff:share:src/share.ts
-diff --git a/src/share.ts b/src/share.ts
---- a/src/share.ts
-+++ b/src/share.ts
-@@ -59,6 +59,6 @@
-   return {
-     gistId,
-     gistUrl,
--    viewerUrl: gistUrl,
-+    viewerUrl: gistViewerUrl(gistId, undefined, process.env.DIFFMAP_ORIGIN),
-   };
- }
-```
-
-```source-diff:close:src/viewer/ViewerApp.tsx
-diff --git a/src/viewer/ViewerApp.tsx b/src/viewer/ViewerApp.tsx
---- a/src/viewer/ViewerApp.tsx
-+++ b/src/viewer/ViewerApp.tsx
-@@ -216,3 +216,10 @@
-             {props.headerActions}
--            <CloseServerButton onClick={() => setShutDown(true)} />
-+            {props.mode === "local" && (
-+              <CloseServerButton
-+                onClick={() => {
-+                  setShutDown(true);
-+                  void closeViewer();
-+                }}
-+              />
-+            )}
-           </div>
-```
+Commit references must name a file the commit changed, and the range must fit the file after the commit. `serve` and `share` check this at startup.
 
 ### File excerpts
 
@@ -167,12 +129,12 @@ Local `serve` trusts `html` in the file you pointed at. This host does not. Gist
 
 ## How a spec stays alive
 
-Write `specs/<name>.md`. Serve it while you plan. When the plan changes, edit this file. When a phase lands, paste the patch and retarget the links so the Diff panel opens the change, not just the file.
+Write `specs/<name>.md`. Serve it while you plan. When the plan changes, edit this file. When a phase lands, commit it, add a `changes` fence, and retarget the links to the commit so the Diff panel opens the change, not just the file.
 
 ### Phase 1: Spec and serve
 
 ```callstack
- generate-spec
+ generate-diffmap
  └── specs/name.md
      └── diffmap serve [[src/cli.ts]]
 ```
@@ -186,7 +148,7 @@ Write `specs/<name>.md`. Serve it while you plan. When the plan changes, edit th
 ```callstack
  specs/name.md
 -└── localhost only
-+├── diffmap share [[share:new:62]]
++├── diffmap share [[d14ae1a:src/share.ts#L55-L59]]
 +└── GitHub PR URL [[src/github/route.ts]]
 ```
 

package/src/host/home.test.ts

@@ -30,7 +30,7 @@ test("homepage markdown is a real viewer document", async () => {
   const kinds = new Set(fences.map((fence) => fence.kind));
   assert.equal(kinds.has("mermaid"), true);
   assert.equal(kinds.has("callstack"), true);
-  assert.equal(kinds.has("source-diff"), true);
+  assert.equal(kinds.has("changes"), true);
   assert.equal(kinds.has("file"), true);
   assert.equal(kinds.has("html"), true);
 
@@ -63,8 +63,9 @@ test("homepage markdown is a real viewer document", async () => {
   assert.equal(levels.has(1), true);
   assert.equal(levels.has(2), true);
   assert.equal(levels.has(3), true);
-  assert.ok(document.sourceDiffs.length >= 3);
-  assert.equal(document.hasReferences, true);
+  assert.ok(
+    document.references.filter((ref) => ref.rev !== undefined).length >= 3,
+  );
 
   const excerpt = fences.find(
     (fence) => fence.kind === "file" && fence.path === "src/cli.ts",

package/src/index.ts

@@ -13,6 +13,7 @@ export type {
   ViewerHeading,
   ViewerHtml,
   ViewerNode,
+  ViewerReference,
   ViewerText,
   ViewerView,
 } from "./parseViewer.js";

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,
     };
   }