@tanishqkancharla/diffmap 0.1.4 → 0.2.0

package/README.md

@@ -21,17 +21,17 @@ Hosted viewer: `https://diffmap.dev/g/<gistId>` (optional `/<file.md>`; `#headin
 ## Agent skills
 
 ```sh
-npx skills add tanishqkancharla/diffmap --skill generate-spec
+npx skills add tanishqkancharla/diffmap --skill generate-diffmap
 ```
 
 Keeps a spec in `specs/` that stays true to what's planned versus already in the tree. Serve it with diffmap. Share from a GitHub PR (`https://diffmap.dev/<owner>/<repo>/pull/<n>/specs/<name>.md`) or `npx @tanishqkancharla/diffmap share`.
 
 Options:
 
-- `--port <n>` — listen port (default `4177`)
+- `--port <n>` — pin a listen port (default: a free port)
 - `--root <dir>` — workspace root for file excerpts (default the directory you ran the command from)
 
-**Done** in the top right stops the server.
+**Close server** in the top right stops the server. Hosted gist and GitHub viewers have no local server, so they omit this control.
 
 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
@@ -43,11 +43,19 @@ List every running viewer, including viewers using custom ports:
 npx @tanishqkancharla/diffmap list
 ```
 
+Update a global install to the latest `@tanishqkancharla/diffmap` on npm. `diffmap --update` does the same thing:
+
+```sh
+diffmap update
+```
+
+If you are already on the latest version, it says so and exits. Otherwise it runs the global install for the package manager that installed diffmap (`npm install --global`, `pnpm add --global`, or `bun add --global`) and prints the old and new versions. Under `npx`, or when it cannot tell how diffmap was installed, it prints the command to run instead of installing anything.
+
 Request the page with `Accept: text/markdown` to read the current source file
-instead of the rendered HTML:
+instead of the rendered HTML. Use the URL printed by `serve`:
 
 ```sh
-curl -H 'Accept: text/markdown' http://127.0.0.1:4177/
+curl -H 'Accept: text/markdown' http://127.0.0.1:<port>/
 ```
 
 ## Library
@@ -60,7 +68,7 @@ import {
 } from "@tanishqkancharla/diffmap";
 ```
 
-`parseViewerDocument` turns markdown into the page document with [md4x](https://github.com/unjs/md4x). `startServer` listens. The generate-spec skill owns document shape; the viewer does not.
+`parseViewerDocument` turns markdown into the page document with [md4x](https://github.com/unjs/md4x). `startServer` listens. The generate-diffmap skill owns document shape; the viewer does not.
 
 ## Fences
 
@@ -70,6 +78,7 @@ import {
 | `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                                                                      |
+| `changes` with a commit, range, or empty body  | Files changed card with a Review button; empty means uncommitted changes                          |
 | `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`                                                                                  |
@@ -99,6 +108,9 @@ startServer
 ::file{path="src/cli.ts" start="1" end="20"}
 ::
 
+::changes{rev="a1b2c3d"}
+::
+
 ::html
 <aside>Note.</aside>
 ::
@@ -108,58 +120,43 @@ startServer
 
 ## 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.
+Append a reference to a call stack line to link it. Paths are relative to `--root`.
+
+- `[[path/to/file.ts#symbolName]]` links a TypeScript or JavaScript declaration,
+  including qualified names such as `[[src/store.ts#Store.save]]`. Ambiguous
+  names show the qualified names you can use instead.
+- `[[path/to/file]]` links a whole file and `[[path/to/file#L12-L30]]` a line
+  range. These work with any language.
+- `[[<sha>:path/to/file#L12-L30]]` or `[[<sha>:path/to/file]]` links a change
+  in a commit. `<sha>` is a 7–40 character lowercase commit SHA, or a range
+  `<sha>..<sha>`.
 
 ```callstack
- handleRequest [[src/request.ts#handleRequest]]
-+└── validateInput # reject invalid input [[src/validation.ts#validateInput]]
+ shareMarkdownFile [[src/share.ts#shareMarkdownFile]]
++└── gistViewerUrl # print the diffmap.dev link [[d14ae1a:src/share.ts#L55-L59]]
 ```
 
-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.
+A reference without a commit opens the Diff panel on uncommitted changes
+(working tree against HEAD), focused on that file or range. If the file has no
+uncommitted changes, the panel shows the current file.
 
-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.
+A commit reference opens the Diff panel on every file changed in that commit or
+range, with a sticky header per file, scrolled to the linked file and lines.
+Line numbers are the file's lines after the commit. The file must be changed in
+that commit and the range must fit the new file; `serve` and `share` run git and
+fail at startup otherwise. Deleted lines cannot be referenced, and a commit
+cannot be combined with `#symbol`.
 
-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.
+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.
+A `changes` fence shows a commit's files as a card. Each row shows the file name
+and +N −M. **Review** opens the Diff panel on all files; a row focuses that file.
+An empty body (or `working`) means uncommitted changes.
 
 ````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);
- }
+```changes
+a1b2c3d
 ```
 ````
 
@@ -167,36 +164,38 @@ 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.
+Documents without references 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.
+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.
 
 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 @tanishqkancharla/diffmap fixtures/annotations.md` for an example
-with old/new references, multiple files, and unchanged context.
+with commit 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
+and commit 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]]
+  A[ViewerApp] -->|Local mode only| B[CloseServerButton]
+  %% ref node:A [[src/viewer/ViewerApp.tsx#ViewerApp]]
+  %% ref node:B [[dae6b98:src/viewer/CloseServerButton.tsx#L8-L16]]
+  %% ref edge:0 [[dae6b98:src/viewer/ViewerApp.tsx#L219-L227]]
 ```
 
 ```mermaid
@@ -213,3 +212,12 @@ 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).
+
+## Link from prose
+
+Write any reference in a paragraph, list item, or table cell, such as
+`See [[src/store.ts#Store.save]] for the write path.` or
+`Close server landed in [[dae6b98:src/viewer/CloseServerButton.tsx]].` It
+renders as clickable inline code labeled with the file name and fragment
+(`store.ts#Store.save`) and opens the same source panel. References inside code spans and link text stay
+literal, so `` `[[path]]` `` shows the syntax itself.

package/index.html

@@ -27,6 +27,24 @@
 
         document.documentElement.dataset.theme = theme;
         document.documentElement.style.colorScheme = theme;
+
+        var scale = "system";
+        try {
+          var storedScale = window.localStorage.getItem("maui-scale");
+          if (
+            storedScale === "system" ||
+            storedScale === "medium" ||
+            storedScale === "large"
+          ) {
+            scale = storedScale;
+          }
+        } catch {}
+        document.documentElement.dataset.scale =
+          scale === "system"
+            ? window.matchMedia("(pointer: coarse)").matches
+              ? "large"
+              : "medium"
+            : scale;
       })();
     </script>
     <title>diffmap</title>

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tanishqkancharla/diffmap",
-  "version": "0.1.4",
+  "version": "0.2.0",
   "description": "Serve a spec or code walkthrough as a local page",
   "license": "MIT",
   "author": "Tanishq Kancharla",
@@ -15,7 +15,8 @@
     "bin.js",
     "index.html",
     "src",
-    "vite.config.ts"
+    "vite.config.ts",
+    "vite.gist.config.ts"
   ],
   "type": "module",
   "exports": {
@@ -33,20 +34,21 @@
     "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/parseViewer.test.ts src/gist/route.test.ts src/github/route.test.ts src/github/patch.test.ts src/github/fetchRepo.test.ts src/viewer/sourceHeader.test.ts",
+    "test": "tsx --test src/cli.test.ts src/update.test.ts src/parseViewer.test.ts src/git.test.ts src/serve.test.ts src/gist/route.test.ts src/github/route.test.ts src/github/patch.test.ts src/github/fetchRepo.test.ts src/viewer/sourceHeader.test.ts src/host/home.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",
+    "@pierre/diffs": "1.6.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",
+    "maui": "npm:@tanishqkancharla/maui@0.0.47",
     "md4x": "^0.0.29",
+    "motion": "^13.4.0",
     "purse-styles": "^0.2.3",
     "react": "^19.2.8",
     "react-dom": "^19.2.8",

package/src/annotations.ts

@@ -1,20 +1,27 @@
-type DiffReference = {
-  kind: "diff";
-  id: string;
-  side: "old" | "new";
-  start: number;
-  end: number;
-};
+import { isCommitRev, shortRev, type Rev } from "./changes.js";
 
+/**
+ * A file, symbol, or line range. With a commit `rev`, the panel opens that
+ * commit's changes and line numbers refer to the file after the commit.
+ * Without one, it opens uncommitted changes, or the current file when the
+ * file has none.
+ */
 type FileReference = {
   kind: "file";
+  rev?: Rev;
   path: string;
   symbol?: string;
   start?: number;
   end?: number;
 };
 
-export type SourceReference = DiffReference | FileReference;
+/** Every file in a rev, such as a changes card's Review button. */
+type ChangesReference = {
+  kind: "changes";
+  rev: Rev;
+};
+
+export type SourceReference = FileReference | ChangesReference;
 
 export type SourceAnnotation = {
   text: string;
@@ -39,41 +46,41 @@ export function parseAnnotation(line: string): SourceAnnotation {
   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);
+export function parseReference(value: string): SourceReference | undefined {
+  const revMatch = /^([^:#[\]\n]+):(.+)$/.exec(value);
+  const rev =
+    revMatch !== null && isCommitRev(revMatch[1]!) ? revMatch[1] : undefined;
+  const target = rev === undefined ? value : revMatch![2]!;
+  const file = /^([^#:[\]\n]+)(?:#(.+))?$/.exec(target);
   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 base =
+    rev === undefined
+      ? { kind: "file" as const, path }
+      : { kind: "file" as const, rev, path };
+  if (fragment === undefined) return base;
   const range = /^L([1-9]\d*)(?:-L?([1-9]\d*))?$/.exec(fragment);
   if (range !== null)
     return {
-      kind: "file",
-      path,
+      ...base,
       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 };
+  return { ...base, symbol: fragment };
 }
 
-export function referenceLabel(reference: SourceReference) {
-  if (reference.kind === "diff")
-    return `${reference.id} · ${reference.side} ${reference.start}–${reference.end}`;
+/** Short label; pass `basename` for inline prose. */
+export function referenceLabel(reference: SourceReference, basename = false) {
+  if (reference.kind === "changes") return shortRev(reference.rev);
+  const path = basename ? reference.path.split("/").pop()! : reference.path;
+  const rev = reference.rev === undefined ? "" : `${shortRev(reference.rev)}:`;
   if (reference.symbol !== undefined)
-    return `${reference.path}#${reference.symbol}`;
+    return `${rev}${path}#${reference.symbol}`;
   if (reference.start !== undefined)
-    return `${reference.path}#L${reference.start}-L${reference.end}`;
-  return reference.path;
+    return `${rev}${path}#L${reference.start}-L${reference.end}`;
+  return `${rev}${path}`;
 }
 
 export type SourceNavigation = {

package/src/changes.ts

@@ -0,0 +1,229 @@
+import {
+  parseDiffFromFile,
+  parsePatchFiles,
+  type CodeViewDiffItem,
+} from "@pierre/diffs";
+
+/**
+ * A set of changes the diff panel can show: one commit (`a1b2c3d`), a commit
+ * range (`a1b2c3d..e4f5a6b`), uncommitted changes (`working`, `staged`,
+ * `unstaged`), a range that ends in them (`a1b2c3d..staged`,
+ * `a1b2c3d..working`), or `all` changes the range picker lists.
+ */
+export type Rev = string;
+
+export const WORKING: Rev = "working";
+export const STAGED: Rev = "staged";
+export const UNSTAGED: Rev = "unstaged";
+export const ALL: Rev = "all";
+
+const shaPattern = "[0-9a-f]{7,40}";
+const commitRevPattern = new RegExp(`^${shaPattern}(?:\\.\\.${shaPattern})?$`);
+const revPattern = new RegExp(
+  `^(?:working|staged|unstaged|all|${shaPattern}(?:\\.\\.(?:${shaPattern}|staged|working))?)$`,
+);
+
+/** Revs a reference can name: commits and commit ranges. */
+export function isCommitRev(value: string) {
+  return commitRevPattern.test(value);
+}
+
+export function isRev(value: string) {
+  return revPattern.test(value);
+}
+
+export function shortRev(rev: Rev) {
+  if (rev === WORKING) return "Uncommitted";
+  if (rev === STAGED) return "Staged";
+  if (rev === UNSTAGED) return "Unstaged";
+  if (rev === ALL) return "All commits";
+  return rev
+    .split("..")
+    .map((part) =>
+      part === STAGED || part === WORKING ? part : part.slice(0, 7),
+    )
+    .join("..");
+}
+
+/** One row of the range picker, newest first: unstaged, staged, then commits. */
+export type Delta =
+  | { kind: "unstaged" | "staged"; additions: number; deletions: number }
+  | {
+      kind: "commit";
+      sha: string;
+      /** First parent, or the empty tree for a root commit. */
+      parent: string;
+      subject: string;
+      additions: number;
+      deletions: number;
+    };
+
+export type DeltasResponse = { deltas?: Delta[]; error?: string };
+
+/** Picked rows, as indexes into the delta list: `newest <= oldest`. */
+export type DeltaWindow = { newest: number; oldest: number };
+
+/**
+ * The rev for picked rows. A window is always explicit, even when it covers
+ * every row: `all` is resolved against the default list, which may be shorter
+ * than one extended to reach an older rev.
+ */
+export function windowRev(deltas: Delta[], window: DeltaWindow): Rev {
+  const newest = deltas[window.newest]!;
+  const oldest = deltas[window.oldest]!;
+  if (window.newest === window.oldest)
+    return newest.kind === "commit" ? newest.sha : newest.kind;
+  // Only unstaged through staged: everything uncommitted.
+  if (oldest.kind !== "commit") return WORKING;
+  const head =
+    newest.kind === "commit"
+      ? newest.sha
+      : newest.kind === "staged"
+        ? STAGED
+        : WORKING;
+  return `${oldest.parent}..${head}`;
+}
+
+const same = (full: string, short: string) => full.startsWith(short);
+
+/** The rows a rev covers, or undefined when the list cannot show it. */
+export function revWindow(deltas: Delta[], rev: Rev): DeltaWindow | undefined {
+  if (rev === ALL) return { newest: 0, oldest: deltas.length - 1 };
+  if (rev === UNSTAGED) return { newest: 0, oldest: 0 };
+  if (rev === STAGED) return { newest: 1, oldest: 1 };
+  if (rev === WORKING) return { newest: 0, oldest: 1 };
+  const [first, second] = rev.split("..");
+  if (second === undefined) {
+    const index = deltas.findIndex(
+      (delta) => delta.kind === "commit" && same(delta.sha, first!),
+    );
+    return index === -1 ? undefined : { newest: index, oldest: index };
+  }
+  const oldest = deltas.findIndex(
+    (delta) => delta.kind === "commit" && same(delta.parent, first!),
+  );
+  const newest =
+    second === WORKING
+      ? 0
+      : second === STAGED
+        ? 1
+        : deltas.findIndex(
+            (delta) => delta.kind === "commit" && same(delta.sha, second),
+          );
+  if (oldest === -1 || newest === -1 || newest > oldest) return undefined;
+  return { newest, oldest };
+}
+
+function deltaName(delta: Delta) {
+  if (delta.kind === "commit") return delta.sha.slice(0, 7);
+  return delta.kind === "staged" ? "Staged" : "Unstaged";
+}
+
+/** "All commits", one commit's title, Unstaged or Staged, or `<oldest>…<newest>` for a range. */
+export function windowLabel(deltas: Delta[], window: DeltaWindow) {
+  if (window.newest === 0 && window.oldest === deltas.length - 1)
+    return "All commits";
+  const newest = deltas[window.newest]!;
+  if (window.newest === window.oldest)
+    return newest.kind === "commit" ? newest.subject : deltaName(newest);
+  return `${deltaName(deltas[window.oldest]!)}…${deltaName(newest)}`;
+}
+
+export type ChangedFile = {
+  path: string;
+  /** Present when git detected a rename. */
+  prevPath?: string;
+  status: "added" | "deleted" | "modified" | "renamed";
+  additions: number;
+  deletions: number;
+  binary: boolean;
+  /**
+   * Full contents make every line reachable. Hosted GitHub viewers only get
+   * the hunk patch from the API.
+   */
+  /** A missing side means the file did not exist there. */
+  contents?: { old?: string; new?: string };
+  patch?: string;
+};
+
+export type Changes = {
+  rev: Rev;
+  title: string;
+  /** Web page for these changes, such as a GitHub commit. */
+  url?: string;
+  /** GitHub listed only the first files; `url` has the rest. */
+  truncated?: boolean;
+  files: ChangedFile[];
+};
+
+/** Gist file holding the changes a shared spec references, keyed by rev. */
+export const GIST_CHANGES_FILE = "diffmap-changes.json";
+
+export type ChangesResponse = { changes?: Changes; error?: string };
+
+/** jsdiff's default lines of context around each change. */
+const CONTEXT = 4;
+
+/**
+ * Binary files have neither contents nor a patch, so they have no diff item.
+ * With `focus`, the diff keeps enough unchanged context to show those new-side
+ * lines; its version is the context it needed.
+ */
+export function changedFileItem(
+  file: ChangedFile,
+  focus?: { start: number; end: number },
+): CodeViewDiffItem | undefined {
+  if (file.contents === undefined) {
+    const fileDiff =
+      file.patch === undefined
+        ? undefined
+        : parsePatchFiles(file.patch, undefined, false)[0]?.files[0];
+    return fileDiff === undefined
+      ? undefined
+      : { id: file.path, type: "diff", fileDiff };
+  }
+  const { old, new: next } = file.contents;
+  const parse = (context: number) =>
+    parseDiffFromFile(
+      old === undefined
+        ? // oxlint-disable-next-line unicorn/no-null -- Pierre uses null for a missing side.
+          null
+        : { name: file.prevPath ?? file.path, contents: old },
+      next === undefined
+        ? // oxlint-disable-next-line unicorn/no-null -- Pierre uses null for a missing side.
+          null
+        : { name: file.path, contents: next },
+      { context },
+    );
+  let context = CONTEXT;
+  let fileDiff = parse(context);
+  const lines = next === undefined ? 0 : next.split("\n").length;
+  if (focus !== undefined) {
+    while (context < lines && !shows(fileDiff.hunks, focus)) {
+      context *= 4;
+      fileDiff = parse(context);
+    }
+  }
+  return {
+    id: file.path,
+    type: "diff",
+    fileDiff,
+    ...(context === CONTEXT ? {} : { version: context }),
+  };
+}
+
+/** Whether every focused new-side line falls inside a hunk, rather than a collapsed gap. */
+function shows(
+  hunks: { additionStart: number; additionCount: number }[],
+  focus: { start: number; end: number },
+) {
+  for (let line = focus.start; line <= focus.end; line++) {
+    const inside = hunks.some(
+      (hunk) =>
+        line >= hunk.additionStart &&
+        line < hunk.additionStart + hunk.additionCount,
+    );
+    if (!inside) return false;
+  }
+  return true;
+}

package/src/cli.test.ts

@@ -0,0 +1,50 @@
+import assert from "node:assert/strict";
+import { execFile } from "node:child_process";
+import fs from "node:fs/promises";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { promisify } from "node:util";
+import test from "node:test";
+
+const execFileAsync = promisify(execFile);
+const srcDir = fileURLToPath(new URL(".", import.meta.url));
+const packageRoot = path.resolve(srcDir, "..");
+const cliPath = path.join(srcDir, "cli.ts");
+
+async function runCli(args: string[]) {
+  try {
+    const result = await execFileAsync(
+      process.execPath,
+      ["--import", "tsx", cliPath, ...args],
+      {
+        cwd: packageRoot,
+        timeout: 20_000,
+        maxBuffer: 1_000_000,
+      },
+    );
+    return { exitCode: 0, stdout: result.stdout, stderr: result.stderr };
+  } catch (cause) {
+    if (typeof cause !== "object" || !cause) throw cause;
+    const exitCode =
+      "code" in cause && typeof cause.code === "number"
+        ? cause.code
+        : undefined;
+    const stdout =
+      "stdout" in cause && typeof cause.stdout === "string" ? cause.stdout : "";
+    const stderr =
+      "stderr" in cause && typeof cause.stderr === "string" ? cause.stderr : "";
+    return { exitCode, stdout, stderr };
+  }
+}
+
+test("diffmap --version matches package.json", async () => {
+  const pkg = JSON.parse(
+    await fs.readFile(path.join(packageRoot, "package.json"), "utf8"),
+  ) as { version: string };
+  const source = await fs.readFile(cliPath, "utf8");
+  assert.doesNotMatch(source, /version:\s*["'`]\d+\.\d+\.\d+/);
+  const result = await runCli(["--version"]);
+  assert.equal(result.exitCode, 0, result.stderr);
+  const printed = `${result.stdout}${result.stderr}`.trim();
+  assert.equal(printed, pkg.version);
+});