@tanishqkancharla/diffmap 0.1.3

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Tanishq Kancharla
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,212 @@
+# diffmap
+
+<img width="2031" height="1212" alt="Screenshot 2026-09-10 at 10 41 03 AM" src="https://github.com/user-attachments/assets/8650f8be-44ca-4c21-b9bf-4ce938b4083e" />
+
+diffmap is a set of personal skills as well as a web-viewer for Markdown files. It has a unique form of showing diffs using a mixture of callstack diffs and mermaid diagram links, which I've found to be personally extremely helpful in understanding massive diffs.
+
+```sh
+npx diffmap path/to/file.md
+```
+
+Share a secret gist and print a `diffmap.dev` link (requires [`gh`](https://cli.github.com/) logged in). Does not start a local server:
+
+```sh
+npx diffmap share path/to.md
+```
+
+Hosted viewer: `https://diffmap.dev/g/<gistId>` (optional `/<file.md>`; `#heading` is the table of contents). The page fetches the gist in the browser from `api.github.com`. Gists are unlisted, not private.
+
+## Agent skills
+
+Install skills from this repository:
+
+```sh
+npx skills add tanishqkancharla/diffmap --skill code-walkthrough
+npx skills add tanishqkancharla/diffmap --skill generate-spec
+```
+
+`code-walkthrough` explains landed changes. `generate-spec` writes a phased spec for work that has not happened yet, then serves `specs/<name>.md` with diffmap.
+
+Options:
+
+- `--port <n>` — listen port (default `4177`)
+- `--root <dir>` — workspace root for file excerpts (default the directory you ran the command from)
+
+**Done** in the top right stops the server.
+
+The server also stops after 24 hours without a page or source request.
+Loading or refreshing the page resets the timer; background health checks and
+Vite connections do not keep it alive.
+
+List every running viewer, including viewers using custom ports:
+
+```sh
+npx diffmap list
+```
+
+Request the page with `Accept: text/markdown` to read the current source file
+instead of the rendered HTML:
+
+```sh
+curl -H 'Accept: text/markdown' http://127.0.0.1:4177/
+```
+
+## Library
+
+```ts
+import { startServer, parseFence, parseViewerDocument } from "diffmap";
+```
+
+`parseViewerDocument` turns markdown into the page document with [md4x](https://github.com/unjs/md4x). `startServer` listens. The generate-spec and code-walkthrough skills own spec vs walkthrough section order; the viewer does not.
+
+## Fences
+
+| Fence info string                              | Viewer                                                                                            |
+| ---------------------------------------------- | ------------------------------------------------------------------------------------------------- |
+| `mermaid`                                      | Beautiful Mermaid                                                                                 |
+| `callstack` or `diff` containing `└──` / `├──` | Interactive stack rows, no file header                                                            |
+| `diff` or `diff:path` with a file path         | Pierre patch with Pierre’s file header                                                            |
+| `diff` with no path                            | Pierre patch, no file header                                                                      |
+| `start:end:path`                               | Pierre file excerpt with Pierre’s file header                                                     |
+| `html`                                         | Trusted HTML from this file. diffmap does not sanitize it. Only use it for local files you wrote. |
+| other langs                                    | Maui `CodeBlock`                                                                                  |
+
+Fences keep whitespace. Use them for mermaid, call stacks, and diffs.
+
+## MDC
+
+md4x Comark components map to the same views:
+
+```md
+::mermaid
+flowchart TD
+A --> B
+::
+
+::callstack
+startServer
++└── createViteServer
+::
+
+::diff{path="src/cli.ts"}
+--- a/src/cli.ts
++++ b/src/cli.ts
+::
+
+::file{path="src/cli.ts" start="1" end="20"}
+::
+
+::html
+<aside>Note.</aside>
+::
+```
+
+`.md` and `.mdx` are both markdown. Curly braces in prose are plain text.
+
+## Link call stacks to source changes
+
+Append `[[path/to/file.ts#symbolName]]` to a call stack line to link a symbol.
+Paths are relative to `--root`. Symbol lookup supports TypeScript and JavaScript
+declarations, including qualified names such as `[[src/store.ts#Store.save]]`.
+Ambiguous names show the qualified names you can use instead.
+
+```callstack
+ handleRequest [[src/request.ts#handleRequest]]
++└── validateInput # reject invalid input [[src/validation.ts#validateInput]]
+```
+
+The panel highlights the declaration in the current workspace file. If an
+included source patch overlaps that declaration and its new-side text matches
+the workspace, the panel highlights the patch instead. Symbol references do not
+require a `source-diff` fence. Use `[[path/to/file]]` for a whole file or
+`[[path/to/file#L12-L30]]` for a file range; these work with other languages too.
+
+To reference an exact change, including removed code, use the patch syntax below.
+Symbol names resolve against current files; use an `old` reference for a deleted
+symbol or a historical version.
+
+Append `[[id:side:start-end]]` to a call stack line. `side` is `old` or `new`;
+line numbers refer to that version of the source file, not the patch. A single
+line can use `[[id:new:12]]`. Multiple references on one stack line are allowed.
+The references are hidden in the rendered stack, and linked rows support mouse
+clicks and keyboard activation.
+
+Define each ID once in a `source-diff:id:path` fence anywhere in the document.
+Copy the file's actual Git patch, including its `diff --git`, file headers, and
+`@@` hunk headers. Keep enough context to explain the change. Each reference
+range must fit within one included hunk. Use the new path for renamed files and
+the old path for deleted files.
+
+````md
+```callstack
+ handleRequest
+-└── saveUnchecked [[request:old:12]]
++├── validateInput # reject invalid input [[request:new:12-13]]
+ └── saveRecord
+```
+
+```source-diff:request:src/request.ts
+diff --git a/src/request.ts b/src/request.ts
+--- a/src/request.ts
++++ b/src/request.ts
+@@ -10,5 +10,6 @@
+ export function handleRequest(input: Input) {
+   const record = input.record;
+-  saveUnchecked(record);
++  const error = validateInput(record);
++  if (error instanceof Error) return error;
+   return saveRecord(record);
+ }
+```
+````
+
+References open in one shared panel beside the walkthrough. Selecting a stack
+line or diagram element highlights it and scrolls the panel to the linked code
+range. When a target has several references, buttons above the source viewer
+select among them. On narrow windows the source panel sits below the walkthrough.
+Documents without references or source patches keep the single-panel layout.
+
+Unknown IDs, duplicate definitions, malformed references, mismatched paths, and
+ranges outside the included hunks produce a parse error. Source patches are
+embedded snapshots; the viewer does not regenerate them from the working tree.
+
+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.
+Resolution uses the workspace's TypeScript configuration and current files.
+Deleted files and lines that no longer match the workspace show a message;
+their call stack references still highlight the embedded old-side diff.
+
+Run `npx diffmap fixtures/annotations.md` for an example
+with old/new references, multiple files, and unchanged context.
+
+## Link Mermaid nodes and edges
+
+Inside a Mermaid fence, add `%% ref node:<id> [[reference]]` to link a node or
+participant, or `%% ref edge:<index> [[reference]]` to link an edge or sequence
+message. Edge indices start at zero in declaration order. The same file, symbol,
+and old/new patch references work here. Keep one directive per target; append
+multiple references to that directive when needed.
+
+````md
+```mermaid
+flowchart LR
+  A[Request] -->|Validate| B[Validation]
+  %% ref node:A [[src/request.ts#handleRequest]]
+  %% ref node:B [[src/validation.ts#validateInput]]
+  %% ref edge:0 [[request:new:12-13]]
+```
+
+```mermaid
+sequenceDiagram
+  participant App
+  participant Store
+  App->>Store: Save record
+  %% ref node:Store [[src/store.ts#Store]]
+  %% ref edge:0 [[src/store.ts#Store.save]]
+```
+````
+
+Click a linked shape, edge line, or edge label, or focus it with Tab and press
+Enter or Space. Directives are Mermaid comments, so they remain hidden and do
+not change the diagram when rendered by other Mermaid tools. Missing diagram
+targets display an error. See [the runnable example](fixtures/references.md).

package/bin.js

@@ -0,0 +1,5 @@
+#!/usr/bin/env node
+import { register } from "tsx/esm/api";
+
+register();
+await import("./src/cli.ts");

package/index.html

@@ -0,0 +1,38 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <meta name="theme-color" content="#ffffff" />
+    <script>
+      (function () {
+        var preference = "system";
+        try {
+          var storedPreference = window.localStorage.getItem("maui-theme");
+          if (
+            storedPreference === "system" ||
+            storedPreference === "light" ||
+            storedPreference === "dark"
+          ) {
+            preference = storedPreference;
+          }
+        } catch {}
+
+        var theme =
+          preference === "system"
+            ? window.matchMedia("(prefers-color-scheme: dark)").matches
+              ? "dark"
+              : "light"
+            : preference;
+
+        document.documentElement.dataset.theme = theme;
+        document.documentElement.style.colorScheme = theme;
+      })();
+    </script>
+    <title>diffmap</title>
+  </head>
+  <body>
+    <div id="root"></div>
+    <script type="module" src="/src/viewer/main.tsx"></script>
+  </body>
+</html>

package/package.json

@@ -0,0 +1,71 @@
+{
+  "name": "@tanishqkancharla/diffmap",
+  "version": "0.1.3",
+  "description": "Serve a spec or code walkthrough as a local page",
+  "license": "MIT",
+  "author": "Tanishq Kancharla",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/tanishqkancharla/diffmap.git"
+  },
+  "bin": {
+    "diffmap": "bin.js"
+  },
+  "files": [
+    "bin.js",
+    "index.html",
+    "src",
+    "vite.config.ts"
+  ],
+  "type": "module",
+  "exports": {
+    ".": "./src/index.ts"
+  },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "scripts": {
+    "cli": "node --import tsx src/cli.ts",
+    "format": "oxfmt .",
+    "format:check": "oxfmt --check .",
+    "lint": "oxlint --deny-warnings src vite.config.ts vite.gist.config.ts bin.js",
+    "lint:fix": "oxlint --fix src vite.config.ts vite.gist.config.ts bin.js",
+    "prepublishOnly": "npm run typecheck && npm run lint && npm run format:check",
+    "release": "npm publish",
+    "test": "tsx --test src/gist/route.test.ts",
+    "typecheck": "tsc --noEmit",
+    "build": "vite build",
+    "build:gist": "vite build",
+    "preview:gist": "vite preview --config vite.gist.config.ts --host 127.0.0.1 --port 4178"
+  },
+  "dependencies": {
+    "@pierre/diffs": "1.4.1",
+    "@vitejs/plugin-react": "^6.1.1",
+    "beautiful-mermaid": "^1.1.3",
+    "errore": "^0.14.1",
+    "incur": "^0.4.20",
+    "maui": "npm:@tanishqkancharla/maui@0.0.16",
+    "md4x": "^0.0.29",
+    "purse-styles": "^0.2.3",
+    "react": "^19.2.8",
+    "react-dom": "^19.2.8",
+    "tsx": "^4.23.13",
+    "vite": "^8.2.2"
+  },
+  "devDependencies": {
+    "@types/node": "^22.20.1",
+    "@types/react": "19.2.18",
+    "@types/react-dom": "19.2.5",
+    "oxfmt": "^0.65.0",
+    "oxlint": "^1.80.0",
+    "typescript": "7.0.2"
+  },
+  "peerDependencies": {
+    "typescript": "^7.0.2"
+  },
+  "engines": {
+    "node": ">=22"
+  },
+  "packageManager": "npm@11.5.1"
+}

package/src/annotations.ts

@@ -0,0 +1,82 @@
+type DiffReference = {
+  kind: "diff";
+  id: string;
+  side: "old" | "new";
+  start: number;
+  end: number;
+};
+
+type FileReference = {
+  kind: "file";
+  path: string;
+  symbol?: string;
+  start?: number;
+  end?: number;
+};
+
+export type SourceReference = DiffReference | FileReference;
+
+export type SourceAnnotation = {
+  text: string;
+  references: SourceReference[];
+};
+
+export function parseCallStack(source: string): SourceAnnotation[] {
+  return source.split("\n").map(parseAnnotation);
+}
+
+export function parseAnnotation(line: string): SourceAnnotation {
+  const references: SourceReference[] = [];
+  const text = line.replace(
+    /\s*\[\[([^[\]\n]+)\]\]/g,
+    (match, value: string) => {
+      const reference = parseReference(value);
+      if (reference === undefined) return match;
+      references.push(reference);
+      return "";
+    },
+  );
+  return { text, references };
+}
+
+function parseReference(value: string): SourceReference | undefined {
+  const diff = /^([\w-]+):(old|new):([1-9]\d*)(?:-([1-9]\d*))?$/.exec(value);
+  if (diff !== null)
+    return {
+      kind: "diff",
+      id: diff[1]!,
+      side: diff[2] === "old" ? "old" : "new",
+      start: Number(diff[3]),
+      end: Number(diff[4] === undefined ? diff[3] : diff[4]),
+    };
+  const file = /^([^#:[\]\n]+)(?:#(.+))?$/.exec(value);
+  if (file === null || file[1]!.trim().length === 0) return undefined;
+  const path = file[1]!.trim();
+  const fragment = file[2];
+  if (fragment === undefined) return { kind: "file", path };
+  const range = /^L([1-9]\d*)(?:-L?([1-9]\d*))?$/.exec(fragment);
+  if (range !== null)
+    return {
+      kind: "file",
+      path,
+      start: Number(range[1]),
+      end: Number(range[2] === undefined ? range[1] : range[2]),
+    };
+  if (!/^[\w$]+(?:\.[\w$]+)*$/.test(fragment)) return undefined;
+  return { kind: "file", path, symbol: fragment };
+}
+
+export function referenceLabel(reference: SourceReference) {
+  if (reference.kind === "diff")
+    return `${reference.id} · ${reference.side} ${reference.start}–${reference.end}`;
+  if (reference.symbol !== undefined)
+    return `${reference.path}#${reference.symbol}`;
+  if (reference.start !== undefined)
+    return `${reference.path}#L${reference.start}-L${reference.end}`;
+  return reference.path;
+}
+
+export type SourceNavigation = {
+  selectedAnnotation: SourceAnnotation | undefined;
+  onSelectAnnotation: (annotation: SourceAnnotation) => void;
+};

package/src/cli.ts

@@ -0,0 +1,94 @@
+#!/usr/bin/env -S node --import tsx
+
+import { Cli, z } from "incur";
+import { resolveFromInvokeCwd } from "./invokeCwd.js";
+import { listRunningDiffmaps } from "./registry.js";
+import { startServer } from "./serve.js";
+import { shareMarkdownFile } from "./share.js";
+
+const cli = Cli.create("diffmap", {
+  description: "Serve a spec or code walkthrough as a local page",
+  version: "0.1.3",
+  args: z.object({
+    file: z.string().describe("Path to the markdown file"),
+  }),
+  options: z.object({
+    port: z.coerce.number().optional().describe("Port (default 4177)"),
+    root: z.string().optional().describe("Workspace root for file excerpts"),
+  }),
+  output: z.object({
+    url: z.string(),
+    file: z.string(),
+  }),
+  async *run(c) {
+    const started = await startServer({
+      filePath: resolveFromInvokeCwd(c.args.file),
+      workspaceRoot:
+        c.options.root === undefined
+          ? resolveFromInvokeCwd(".")
+          : resolveFromInvokeCwd(c.options.root),
+      port: c.options.port === undefined ? 4177 : c.options.port,
+    });
+    if (started instanceof Error) {
+      return c.error({
+        code: "DIFFMAP",
+        message: started.message,
+      });
+    }
+    yield { url: started.url, file: started.filePath };
+    await started.closed;
+    return { url: started.url, file: started.filePath };
+  },
+})
+  .command("list", {
+    description: "List running diffmap viewers",
+    output: z.object({
+      instances: z.array(
+        z.object({
+          pid: z.number(),
+          title: z.string(),
+          url: z.string(),
+          file: z.string(),
+        }),
+      ),
+    }),
+    async run(c) {
+      const instances = await listRunningDiffmaps();
+      if (instances instanceof Error) {
+        return c.error({
+          code: "DIFFMAP",
+          message: instances.message,
+        });
+      }
+      return c.ok({ instances });
+    },
+  })
+  .command("share", {
+    description: "Upload a walkthrough gist and print the diffmap.dev URL",
+    args: z.object({
+      file: z.string().describe("Path to the markdown file"),
+    }),
+    options: z.object({
+      public: z.boolean().optional().describe("Create a public gist"),
+    }),
+    output: z.object({
+      gistId: z.string(),
+      gistUrl: z.string(),
+      viewerUrl: z.string(),
+    }),
+    async run(c) {
+      const shared = await shareMarkdownFile({
+        filePath: resolveFromInvokeCwd(c.args.file),
+        isPublic: c.options.public === true,
+      });
+      if (shared instanceof Error) {
+        return c.error({
+          code: "DIFFMAP",
+          message: shared.message,
+        });
+      }
+      return c.ok(shared);
+    },
+  });
+
+await cli.serve();

package/src/codeFont.ts

@@ -0,0 +1,2 @@
+export const codeFontFamily =
+  'ui-monospace, "SF Mono", SFMono-Regular, Menlo, Monaco, Consolas, "Liberation Mono", monospace';

package/src/contentPlugin.ts

@@ -0,0 +1,47 @@
+import fs from "node:fs/promises";
+import type { Plugin } from "vite";
+import { parseViewerDocument } from "./parseViewer.js";
+
+export function diffmapContentPlugin(input: {
+  filePath: string;
+  title: string;
+}): Plugin {
+  const virtualId = "\0virtual:diffmap";
+  return {
+    name: "diffmap-content",
+    resolveId(id) {
+      if (id === "virtual:diffmap") return virtualId;
+    },
+    async load(id) {
+      if (id !== virtualId) return;
+      const source = await fs.readFile(input.filePath, "utf8");
+      const document = parseViewerDocument(source);
+      if (document instanceof Error) throw document;
+      return `export const viewerDocument = ${JSON.stringify(document)};`;
+    },
+    transformIndexHtml(html) {
+      return html.replaceAll(
+        "<title>diffmap</title>",
+        `<title>${escapeHtml(input.title)}</title>`,
+      );
+    },
+    configureServer(server) {
+      server.watcher.add(input.filePath);
+      server.watcher.on("change", (file) => {
+        if (file !== input.filePath) return;
+        const mod = server.moduleGraph.getModuleById(virtualId);
+        if (mod === undefined) return;
+        // oxlint-disable-next-line typescript/no-floating-promises -- Vite watcher callbacks cannot await module reloads.
+        void server.reloadModule(mod);
+      });
+    },
+  };
+}
+
+function escapeHtml(value: string) {
+  return value
+    .replaceAll("&", "&amp;")
+    .replaceAll("<", "&lt;")
+    .replaceAll(">", "&gt;")
+    .replaceAll('"', "&quot;");
+}