@tanishqkancharla/diffmap 0.3.0 → 0.6.0

package/src/host/home.md

@@ -1,156 +1,201 @@
 # diffmap
 
-A viewer for specs and walkthroughs. Call stacks, mermaid that links into source, and a Diff panel. This page is one — `parseViewerDocument` plus `ViewerApp`, same path as `diffmap serve`.
+**Your coding agent writes more code than you can review.**
 
-TOC on the left, article here, Diff on the right. Click a stack row or a mermaid node.
+**You should be spending time reviewing design decisions and risky changes, not boilerplate.**
 
-## Install the skill
+`diffmap` is an agent skill that lets your agent visually explain their changes to you. Agents can create interactive diagrams that link back to the source code.
 
-```sh
-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.
-
-## Serve locally
+You can try `diffmap` before you install it. In a repository that has changes, paste this prompt into your agent:
 
-```sh
-npx @tanishqkancharla/diffmap serve specs/<name>.md
+```text
+Write a diffmap spec for the changes on this branch. Use the instructions at
+https://raw.githubusercontent.com/tanishqkancharla/diffmap/main/skills/generate-diffmap/SKILL.md
+Then serve the spec with npx @tanishqkancharla/diffmap and send me the link.
 ```
 
-Bare `npx @tanishqkancharla/diffmap specs/<name>.md` is the same as `serve`. `list` shows running viewers — reuse the URL instead of starting a second server.
-
-**Close server** is only on that local page. This host has no process to stop.
-
-## Share
-
-### Gist
+If you like the result, install the skill:
 
 ```sh
-npx @tanishqkancharla/diffmap share specs/<name>.md
+npx skills add tanishqkancharla/diffmap --skill generate-diffmap
 ```
 
-Prints `https://diffmap.dev/g/<gistId>` (optional `/<file.md>`). Secret gist: unlisted, not private. Anyone with the id can read it. Does not start a local server.
-
-### GitHub PR vs commit
-
-A spec on a public PR:
-
-`https://diffmap.dev/<owner>/<repo>/pull/<n>/specs/<name>.md`
-
-Pinned commit:
-
-`https://diffmap.dev/<owner>/<repo>/commit/<sha>/specs/<name>.md`
-
-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
+`diffmap` is [open source](https://github.com/tanishqkancharla/diffmap) and MIT licensed. Diffmaps are hosted locally by default, but you can choose to [upload a diffmap as a secret gist](#share-a-spec-with-a-link) and open it on diffmap.dev.
+
+## See the main ideas
+
+Your agent selects the best diagram for each idea. Each part of the diagram has a link to its code.
+
+### Service diagrams
+
+A service diagram shows each service and its state. Each step shows one event and the state that the event changes. Thus, you do not have to remember the state.
+
+To see how `diffmap serve` opens a spec, press **Play**. To read about a name with a dotted line, put the pointer on the name:
+
+```services
+service Laptop
+  > This is your computer. diffmap serve reads files here and does not upload them.
+  service Agent "coding agent"
+    > The agent writes the spec and runs diffmap for you.
+  service CLI "diffmap serve" [[src/serve.ts#startServer]]
+    > This small server uses git to read your repository.
+    state url = none
+  service Repo "your repository"
+    > The repository contains the spec and the commits that the spec refers to.
+service Browser
+  service Page "the spec" [[src/viewer/ViewerApp.tsx#ViewerApp]]
+    state page = empty
+  service Panel "Diff panel" [[src/viewer/SourceDiffPanel.tsx#SourceDiffPanel]]
+    > The Diff panel opens next to the spec. It shows the code for the link that you clicked.
+    state shows = none
+
+start "diffmap serve opens a spec in your browser"
+  > The agent has written the spec, but nothing serves it yet.
+
+step "The agent serves the spec"
+  > Your agent runs diffmap serve with the path of the spec.
+  Agent -> CLI: serve specs/search.md
+step "serve examines each commit in the spec"
+  > Before the server starts, it uses git to read each commit and line range that the spec refers to.
+  CLI -> Repo: readDocumentChanges [[src/git.ts#readDocumentChanges]]
+    > If a SHA or a line range is wrong, the command stops here. Thus, the page has no broken links.
+step "serve prints a URL for you"
+  > The server starts on your computer and gives the agent a local URL.
+  CLI -> Agent: localhost URL
+  CLI.url = localhost:4321
+step "You open the page"
+  > Your browser gets the spec from the server and shows it as a page.
+  Page -> CLI: GET /
+  CLI -> Page: spec
+  Page.page = rendered
+step "You click a call stack row"
+  > The Diff panel asks the server for the code that the row refers to.
+  Panel -> CLI: /__diffmap/source
+  CLI -> Repo: git show
+    > The server reads the file from the commit in the row, not from the working tree.
+step "The Diff panel shows the code"
+  > The server sends the lines, and the Diff panel shows them next to the spec.
+  CLI -> Panel: lines
+  Panel.shows = code
+```
 
-### System flow
+### Mermaid diagrams
 
-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.
+The page shows Mermaid diagrams. Each node and each arrow can have a link to its code. This diagram shows what occurs when you click a link:
 
 ```mermaid
 flowchart LR
-  Spec[Living spec] --> Serve[serve]
-  Spec --> Share[share]
-  Spec --> Pin[GitHub pin]
-  %% ref node:Spec [[src/parseViewer.ts#parseViewerDocument]]
-  %% ref node:Serve [[src/cli.ts]]
-  %% ref node:Share [[src/share.ts#shareMarkdownFile]]
-  %% ref node:Pin [[src/github/route.ts]]
-  %% ref edge:0 [[1257fe8:src/cli.ts#L49-L50]]
+  Click[Click a link] --> Find[useSourceReference]
+  Find -->|diffmap serve| Local[Read the repo with git]
+  Find -->|diffmap.dev| GitHub[fetchPinnedBlob]
+  Local --> Panel[SourceDiffPanel]
+  GitHub --> Panel
+  %% ref node:Find [[src/viewer/sourceNavigation.ts#useSourceReference]]
+  %% ref node:GitHub [[src/github/fetchRepo.ts#fetchPinnedBlob]]
+  %% ref node:Panel [[src/viewer/SourceDiffPanel.tsx#SourceDiffPanel]]
+  %% ref edge:1 [[src/viewer/sourceNavigation.ts#requestSource]]
 ```
 
-````md
-```mermaid
-flowchart LR
-  Spec[Living spec] --> Serve[serve]
-  %% ref node:Serve [[src/cli.ts]]
-```
-````
-
 ### Call stacks
 
-`-` 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.
+Each row has the form `result = call(inputs)`. Thus, you can follow the data from one call to the next call. A `+` row is new code, and a `−` row is old code that the change removes. Each row has a link to its code.
 
-```callstack
- ViewerApp
--└── 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
-```
+This call stack shows how `diffmap` draws call stacks:
 
 ```callstack
- shareMarkdownFile [[src/share.ts#shareMarkdownFile]]
--└── print the gist URL
-+└── gistViewerUrl  # https://diffmap.dev/g/<id> [[d14ae1a:src/share.ts#L55-L59]]
+ fence = parseFence(lang, source) [[src/parseFence.ts#parseFence]]
++└── lines = parseCallStack(source) # one row per line, with its links [[src/annotations.ts#parseCallStack]]
+ view = Fence({ fence }) [[src/viewer/Fence.tsx#Fence]]
+-└── return CodeBlock(fence.source) # the tree as plain text
++├── if fence.kind === "callstack":
++│   └── return CallStackDiff(fence.lines) # rows with + and − marks [[src/viewer/CallStackDiff.tsx#CallStackDiff]]
++└── return CodeBlock(fence.source) # other languages stay pseudocode
 ```
 
-### Changes
+## Open the code
 
-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.
+A function name in a sentence can also be a link, for example [[src/share.ts#shareMarkdownFile]].
+
+When the work is complete, the spec shows a card for the commit. The links in the spec then refer to that commit. These links always show the code from that commit, also when the file changes later.
 
 ```changes
-dae6b98
+6e4b5d3
 ```
 
-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
-
-`start:end:path`. Locally the server reads the workspace file. Here the bundled file is sliced the same way.
-
-```58:72:src/cli.ts
-const cli = Cli.create("diffmap", {
-  description: "Serve a spec locally, or share it as a gist",
-  version: packageVersion,
-  args: serveArgs,
-  options: serveOptions,
-  output: serveOutput,
-  hint: "`serve <spec.md>` runs the local viewer. `share <spec.md>` publishes a secret gist. `update` (or `--update`) installs the latest diffmap.",
-  examples: [
-    {
-      args: { file: "spec.md" },
-      description: "Same as `diffmap serve spec.md`",
-    },
-  ],
-  run: runServe,
-})
+```callstack
+ nodes = fromNode(text) [[6e4b5d3:src/parseViewer.ts#L318-L326]]
+-└── return [{ type: "text", value: text }] # prose stays plain text
++└── return proseText(text) [[6e4b5d3:src/parseViewer.ts#L329-L353]]
++    ├── reference = parseReference(match) # each link in double brackets
++    └── return [...textBefore, { type: "reference", annotation }]
+ element = renderNode(node) [[6e4b5d3:src/viewer/ComarkView.tsx#L64-L68]]
++└── if node.type === "reference":
++    └── return InlineReference(node.annotation) # a code button that opens the Diff panel [[6e4b5d3:src/viewer/ComarkView.tsx#L173-L189]]
 ```
 
-### HTML
+## Share a spec with a link
 
-Local `serve` trusts `html` in the file you pointed at. This host does not. Gist and GitHub pages are the same — no `dangerouslySetInnerHTML` from untrusted markdown.
+A teammate can read your spec without a copy of your branch. One command uploads the spec as a secret GitHub gist and prints the link:
 
-```html
-<aside>If this renders, the host leaked HTML.</aside>
+```sh
+npx @tanishqkancharla/diffmap share specs/search.md
+# prints https://diffmap.dev/g/<gistId>
 ```
 
-## How a spec stays alive
+::details{summary="How sharing works"}
+The shared page cannot use git or a copy of your repository. Thus, the gist also contains the data that the spec uses:
 
-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.
+- A snapshot of each commit that the spec refers to
+- The current contents of each file that the spec quotes.
 
-### Phase 1: Spec and serve
+Because of this data, this page can show code:
 
-```callstack
- generate-diffmap
- └── specs/name.md
-     └── diffmap serve [[src/cli.ts]]
+```mermaid
+flowchart LR
+  subgraph Gist
+    Spec[spec.md]
+    Changes[diffmap-changes.json]
+    Files[diffmap-files.json]
+  end
+  Spec -->|Markdown| Page[The spec page]
+  Changes -->|commits| Cards[Changes cards and commit links]
+  Files -->|file contents| Excerpts[Excerpts and plain links]
+  %% ref node:Changes [[2f96051:src/share.ts#L44-L53]]
+  %% ref node:Files [[2f96051:src/share.ts#L105-L125]]
+  %% ref node:Excerpts [[src/host/files.ts#HostFilesContext]]
 ```
 
-- [x] Install the skill.
-- [x] Keep one living spec.
-- [x] `diffmap serve` / `list`.
+```changes
+2f96051
+```
 
-### Phase 2: Share it
+`share` makes the two snapshots before it calls `gh`. Thus, `diffmap` does not keep a GitHub token:
 
 ```callstack
- specs/name.md
--└── localhost only
-+├── diffmap share [[d14ae1a:src/share.ts#L55-L59]]
-+└── GitHub PR URL [[src/github/route.ts]]
+ result = shareMarkdownFile({ filePath, workspaceRoot }) [[2f96051:src/share.ts#L26-L103]]
+ ├── parsed = parseViewerDocument(source)
+ ├── if parsed is an error: return parsed # a broken diagram stops here
+ ├── changes = readDocumentChanges(workspaceRoot, parsed) # each linked commit
++├── files = readDocumentFiles(workspaceRoot, parsed) # each quoted file [[2f96051:src/share.ts#L105-L125]]
+ ├── await gh("auth", "status")
+-├── created = await gh("gist", "create", spec, changes)
++├── created = await gh("gist", "create", spec, changes, files)
+ └── return { gistId, viewerUrl: gistViewerUrl(gistId) }
+```
+
+This excerpt is from one of the quoted files. Thus, a shared copy of this page also shows it:
+
+```54:63:src/share.ts
+  // 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;
+
+  const args = ["gist", "create"];
+  if (input.isPublic) args.push("--public");
+  args.push("--desc", extractTitle(source), filePath);
 ```
 
-- [x] Gist URL for a snapshot.
-- [x] PR URL when the spec lives in the repo (pin to one SHA).
+::

package/src/host/home.test.ts

@@ -32,7 +32,7 @@ test("homepage markdown is a real viewer document", async () => {
   assert.equal(kinds.has("callstack"), true);
   assert.equal(kinds.has("changes"), true);
   assert.equal(kinds.has("file"), true);
-  assert.equal(kinds.has("html"), true);
+  assert.equal(kinds.has("services"), true);
 
   const mermaid = fences.find((fence) => fence.kind === "mermaid");
   assert.notEqual(mermaid, undefined);
@@ -62,22 +62,20 @@ test("homepage markdown is a real viewer document", async () => {
   const levels = new Set(document.headings.map((heading) => heading.level));
   assert.equal(levels.has(1), true);
   assert.equal(levels.has(2), true);
-  assert.equal(levels.has(3), 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",
+    (fence) => fence.kind === "file" && fence.path === "src/share.ts",
   );
   assert.equal(excerpt?.kind, "file");
   if (excerpt?.kind !== "file") return;
-  const cliPath = path.join(path.dirname(homePath), "..", "cli.ts");
-  const cli = await fs.readFile(cliPath, "utf8");
-  const lines = cli.split(/\n/);
+  const sharePath = path.join(path.dirname(homePath), "..", "share.ts");
+  const share = await fs.readFile(sharePath, "utf8");
+  const lines = share.split(/\n/);
   const slice = lines.slice(excerpt.start - 1, excerpt.end).join("\n");
   assert.equal(lines[excerpt.start - 1]?.trim().length !== 0, true);
-  assert.match(slice, /packageVersion/);
-  assert.match(slice, /\}\)\s*$/);
+  assert.match(slice, /"gist", "create"/);
   assert.equal(excerpt.source, slice);
 });

package/src/parseFence.ts

@@ -1,18 +1,60 @@
 import { parseCallStack, type SourceAnnotation } from "./annotations.js";
 import { WORKING, type Rev } from "./changes.js";
+import { parseCodeNotes, type CodeNote } from "./codeNotes.js";
 import {
   parseDiagramAnnotations,
   type DiagramAnnotation,
 } from "./diagramAnnotations.js";
+import { parseServiceDiagram, type ServicesParse } from "./services.js";
 
 export type Fence =
-  | { kind: "mermaid"; source: string; annotations: DiagramAnnotation[] }
+  | {
+      kind: "mermaid";
+      /** In a diff, every line with its sign removed; see mermaidFence. */
+      source: string;
+      annotations: DiagramAnnotation[];
+      /** From ```mermaid diff: the diagram without `+` lines, and without `-` lines. */
+      sides: { today: string; proposed: string } | undefined;
+      /** From the info string, as in ```mermaid [Request flow]. */
+      title: string | undefined;
+    }
+  | {
+      kind: "services";
+      source: string;
+      parsed: ServicesParse;
+    }
   | { kind: "html"; source: string }
-  | { kind: "callstack"; source: string; lines: SourceAnnotation[] }
-  | { kind: "changes"; rev: Rev; source: string }
+  | {
+      kind: "callstack";
+      /** Rows with trailing note lines removed. */
+      source: string;
+      lines: SourceAnnotation[];
+      /** 1-based rows from the info string, as in ```callstack {2}. */
+      highlights: number[];
+      notes: CodeNote[];
+      /** From the info string, as in ```callstack [Request flow]. */
+      title: string | undefined;
+    }
+  | {
+      kind: "changes";
+      rev: Rev;
+      /** Paths to review first, in order; other changed files fold away. */
+      review: 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 };
+  | {
+      kind: "code";
+      lang: string;
+      /** Code with trailing note lines removed. */
+      source: string;
+      /** 1-based lines from the info string, as in ```ts {2,4-6}. */
+      highlights: number[];
+      notes: CodeNote[];
+      /** From the info string, as in ```ts [src/request.ts]. */
+      title: string | undefined;
+    };
 
 const fileRefPattern = /^(\d+):(\d+):(.+)$/;
 const diffPathPattern = /^diff:(.+)$/;
@@ -31,27 +73,33 @@ export function pathFromDiffSource(source: string) {
   return undefined;
 }
 
-export function parseFence(lang: string, source: string): Fence {
+export function parseFence(
+  lang: string,
+  source: string,
+  highlights: number[] = [],
+  title?: string,
+  /** The info string after the language and highlights, as in ```mermaid diff. */
+  meta?: string,
+): Fence {
   const trimmed = source.replace(/\n$/, "");
-  if (lang === "mermaid")
+  const diff = meta?.split(/\s+/).includes("diff") ?? false;
+  if (lang === "mermaid") return mermaidFence(trimmed, diff, title);
+  if (lang === "services")
     return {
-      kind: "mermaid",
+      kind: "services",
       source: trimmed,
-      annotations: parseDiagramAnnotations(trimmed),
+      parsed: parseServiceDiagram(trimmed, diff),
     };
   if (lang === "html") return { kind: "html", source: trimmed };
-  if (lang === "callstack")
-    return {
-      kind: "callstack",
-      source: trimmed,
-      lines: parseCallStack(trimmed),
-    };
+  if (lang === "callstack") return callStackFence(trimmed, highlights, title);
 
+  // The first line is the rev (blank for uncommitted); each later line is a path to review.
   if (lang === "changes") {
-    const rev = trimmed.trim();
+    const [rev = "", ...paths] = trimmed.split("\n").map((line) => line.trim());
     return {
       kind: "changes",
       rev: rev.length === 0 ? WORKING : rev,
+      review: paths.filter((line) => line.length > 0),
       source: trimmed,
     };
   }
@@ -69,13 +117,8 @@ export function parseFence(lang: string, source: string): Fence {
 
   const diffPath = diffPathPattern.exec(lang);
   if (lang === "diff" || diffPath !== null) {
-    if (isCallStackSource(trimmed)) {
-      return {
-        kind: "callstack",
-        source: trimmed,
-        lines: parseCallStack(trimmed),
-      };
-    }
+    if (isCallStackSource(trimmed))
+      return callStackFence(trimmed, highlights, title);
     return {
       kind: "diff",
       path: diffPath === null ? pathFromDiffSource(trimmed) : diffPath[1],
@@ -83,9 +126,75 @@ export function parseFence(lang: string, source: string): Fence {
     };
   }
 
+  const { code, notes } = parseCodeNotes(trimmed);
   return {
     kind: "code",
     lang: lang.length === 0 ? "text" : lang,
-    source: trimmed,
+    source: code,
+    highlights,
+    notes,
+    title,
+  };
+}
+
+/**
+ * A diff's lines start with `-` (Today only), `+` (Proposed only), or
+ * anything else (both). The viewer draws every line, then marks what each
+ * side lacks, so Mermaid syntax never needs parsing here.
+ */
+function mermaidFence(
+  source: string,
+  diff: boolean,
+  title: string | undefined,
+): Fence {
+  if (!diff)
+    return {
+      kind: "mermaid",
+      source,
+      annotations: parseDiagramAnnotations(source),
+      sides: undefined,
+      title,
+    };
+  const rows = source.split("\n").map((line) => ({
+    sign: line[0],
+    text: line.replace(/^[+ -]/, ""),
+  }));
+  const without = (sign: string) =>
+    rows
+      .filter((row) => row.sign !== sign)
+      .map((row) => row.text)
+      .join("\n");
+  // Mermaid keeps a node's first label, so within each run of changed lines
+  // the `+` lines come first and a relabeled node shows its Proposed label.
+  const merged: string[] = [];
+  const removed: string[] = [];
+  for (const row of rows) {
+    if (row.sign === "-") removed.push(row.text);
+    else if (row.sign === "+") merged.push(row.text);
+    else merged.push(...removed.splice(0), row.text);
+  }
+  merged.push(...removed);
+  return {
+    kind: "mermaid",
+    source: merged.join("\n"),
+    annotations: parseDiagramAnnotations(merged.join("\n")),
+    sides: { today: without("+"), proposed: without("-") },
+    title,
+  };
+}
+
+function callStackFence(
+  source: string,
+  highlights: number[],
+  title: string | undefined,
+): Fence {
+  const { code, notes } = parseCodeNotes(source);
+  return {
+    kind: "callstack",
+    source: code,
+    lines: parseCallStack(code),
+    highlights,
+    notes,
+    title,
   };
 }