@tanishqkancharla/diffmap 0.1.4 → 0.2.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

@@ -0,0 +1,86 @@
+import { useEffect, useState } from "react";
+import { Link, P } from "maui";
+import { init } from "md4x/standalone";
+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";
+import shareSource from "../share.ts?raw";
+import parseViewerSource from "../parseViewer.ts?raw";
+import githubRouteSource from "../github/route.ts?raw";
+
+let parserReady: Promise<void> | undefined;
+
+function readyHostParser() {
+  parserReady ??= init();
+  return parserReady;
+}
+
+const hostFiles = {
+  "src/cli.ts": cliSource,
+  "src/share.ts": shareSource,
+  "src/parseViewer.ts": parseViewerSource,
+  "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" }
+    | { kind: "error"; message: string }
+    | { kind: "ready"; document: ViewerDocument }
+  >({ kind: "loading" });
+
+  useEffect(() => {
+    let cancelled = false;
+    // oxlint-disable-next-line typescript/no-floating-promises -- The effect owns this parse; ignore after unmount.
+    void readyHostParser().then(() => {
+      if (cancelled) return;
+      const parsed = parseViewerDocument(homeSource, "home.md");
+      if (parsed instanceof Error) {
+        setView({ kind: "error", message: parsed.message });
+        return;
+      }
+      setView({ kind: "ready", document: parsed });
+    });
+    return () => {
+      cancelled = true;
+    };
+  }, []);
+
+  if (view.kind === "loading") return <GistLoading title="Loading…" />;
+  if (view.kind === "error") {
+    return (
+      <GistStatus title="Could not parse this walkthrough">
+        <P>{view.message}</P>
+      </GistStatus>
+    );
+  }
+
+  return (
+    <HostFilesContext.Provider value={hostFiles}>
+      <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

@@ -0,0 +1,10 @@
+import { createContext, useContext } from "react";
+
+/** Bundled files for the hosted homepage. `[[path]]` reads these, not GitHub. */
+export type HostFiles = Record<string, string>;
+
+export const HostFilesContext = createContext<HostFiles | undefined>(undefined);
+
+export function useHostFiles() {
+  return useContext(HostFilesContext);
+}

package/src/host/home.md

@@ -0,0 +1,156 @@
+# 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`.
+
+TOC on the left, article here, Diff on the right. Click a stack row or a mermaid node.
+
+## Install the skill
+
+```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
+
+```sh
+npx @tanishqkancharla/diffmap serve specs/<name>.md
+```
+
+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
+
+```sh
+npx @tanishqkancharla/diffmap share specs/<name>.md
+```
+
+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
+
+### System flow
+
+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
+  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]]
+```
+
+````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.
+
+```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
+```
+
+```callstack
+ shareMarkdownFile [[src/share.ts#shareMarkdownFile]]
+-└── print the gist URL
++└── gistViewerUrl  # https://diffmap.dev/g/<id> [[d14ae1a:src/share.ts#L55-L59]]
+```
+
+### Changes
+
+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.
+
+```changes
+dae6b98
+```
+
+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,
+})
+```
+
+### HTML
+
+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.
+
+```html
+<aside>If this renders, the host leaked HTML.</aside>
+```
+
+## 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, 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-diffmap
+ └── specs/name.md
+     └── diffmap serve [[src/cli.ts]]
+```
+
+- [x] Install the skill.
+- [x] Keep one living spec.
+- [x] `diffmap serve` / `list`.
+
+### Phase 2: Share it
+
+```callstack
+ specs/name.md
+-└── localhost only
++├── diffmap share [[d14ae1a:src/share.ts#L55-L59]]
++└── GitHub PR URL [[src/github/route.ts]]
+```
+
+- [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

@@ -0,0 +1,83 @@
+import assert from "node:assert/strict";
+import fs from "node:fs/promises";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import test from "node:test";
+import { parseViewerDocument } from "../parseViewer.ts";
+import type { ViewerNode } from "../parseViewer.ts";
+import type { Fence } from "../parseFence.ts";
+
+const homePath = path.join(
+  path.dirname(fileURLToPath(import.meta.url)),
+  "home.md",
+);
+
+function collectFences(nodes: ViewerNode[]): Fence[] {
+  return nodes.flatMap((node) => {
+    if (node.type === "view") return [node.fence];
+    if (node.type === "element") return collectFences(node.children);
+    return [];
+  });
+}
+
+test("homepage markdown is a real viewer document", async () => {
+  const source = await fs.readFile(homePath, "utf8");
+  const document = parseViewerDocument(source, "home.md");
+  assert.equal(document instanceof Error, false);
+  if (document instanceof Error) return;
+
+  const fences = collectFences(document.nodes);
+  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("changes"), true);
+  assert.equal(kinds.has("file"), true);
+  assert.equal(kinds.has("html"), true);
+
+  const mermaid = fences.find((fence) => fence.kind === "mermaid");
+  assert.notEqual(mermaid, undefined);
+  if (mermaid?.kind !== "mermaid") return;
+  assert.equal(
+    mermaid.annotations.some((link) =>
+      link.annotation.references.some((ref) => ref.kind === "file"),
+    ),
+    true,
+  );
+  assert.equal(
+    mermaid.annotations.some((link) => link.target === "edge"),
+    true,
+  );
+
+  const stacks = fences.filter((fence) => fence.kind === "callstack");
+  assert.equal(
+    stacks.some((fence) =>
+      fence.kind === "callstack"
+        ? fence.lines.some((line) => line.text.startsWith("-")) &&
+          fence.lines.some((line) => line.text.startsWith("+"))
+        : false,
+    ),
+    true,
+  );
+
+  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",
+  );
+  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 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.equal(excerpt.source, slice);
+});

package/src/index.ts

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

package/src/packageVersion.ts

@@ -0,0 +1,7 @@
+import { readFileSync } from "node:fs";
+
+const packageJson = JSON.parse(
+  readFileSync(new URL("../package.json", import.meta.url), "utf8"),
+) as { version: string };
+
+export const packageVersion = packageJson.version;