@tanishqkancharla/diffmap 0.1.3 → 0.1.5

package/src/github/route.test.ts

@@ -0,0 +1,68 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+import {
+  githubCommitPath,
+  githubPullPath,
+  githubViewerUrl,
+  parseGitHubPath,
+} from "./route.ts";
+
+test("parseGitHubPath reads pull and commit spec URLs", () => {
+  assert.deepEqual(
+    parseGitHubPath(
+      "/tanishqkancharla/diffmap/pull/5/specs/merge-generate-spec-walkthrough.md",
+    ),
+    {
+      kind: "github-pull",
+      owner: "tanishqkancharla",
+      repo: "diffmap",
+      pull: 5,
+      path: "specs/merge-generate-spec-walkthrough.md",
+    },
+  );
+  assert.deepEqual(
+    parseGitHubPath(
+      "/tanishqkancharla/diffmap/commit/0123456789abcdef0123456789abcdef01234567/specs/a.md",
+    ),
+    {
+      kind: "github-commit",
+      owner: "tanishqkancharla",
+      repo: "diffmap",
+      sha: "0123456789abcdef0123456789abcdef01234567",
+      path: "specs/a.md",
+    },
+  );
+  assert.equal(parseGitHubPath("/").kind, "home");
+  assert.equal(
+    parseGitHubPath("/g/0123456789abcdef0123456789abcdef").kind,
+    "home",
+  );
+  assert.equal(
+    parseGitHubPath("/tanishqkancharla/diffmap/pull/5").kind,
+    "github-invalid",
+  );
+  assert.equal(
+    parseGitHubPath("/tanishqkancharla/diffmap/pull/5/src/cli.ts").kind,
+    "github-invalid",
+  );
+});
+
+test("printed GitHub viewer URLs pin pull or commit", () => {
+  assert.equal(
+    githubPullPath(
+      "tanishqkancharla",
+      "diffmap",
+      5,
+      "specs/merge-generate-spec-walkthrough.md",
+    ),
+    "/tanishqkancharla/diffmap/pull/5/specs/merge-generate-spec-walkthrough.md",
+  );
+  assert.equal(
+    githubCommitPath("o", "r", "deadbeef", "docs/a b.md"),
+    "/o/r/commit/deadbeef/docs/a%20b.md",
+  );
+  assert.equal(
+    githubViewerUrl("tanishqkancharla", "diffmap", { pull: 5 }, "specs/x.md"),
+    "https://diffmap.dev/tanishqkancharla/diffmap/pull/5/specs/x.md",
+  );
+});

package/src/github/route.ts

@@ -0,0 +1,175 @@
+/**
+ * GitHub-hosted spec URLs.
+ *
+ * Pin model (locked): a hosted spec is always one commit SHA. The spec markdown
+ * is the blob of `path` at that SHA. Every [[path]], mermaid %% ref, excerpt,
+ * and hunk is loaded from that same SHA — never main / latest. A PR number only
+ * chooses the SHA (head at load time, then pin). Prefer putting the SHA in the
+ * URL; otherwise resolve head once per page load and use that SHA for all fetches.
+ *
+ * v1: /<owner>/<repo>/pull/<n>/<path-to-spec.md>
+ *     /<owner>/<repo>/commit/<sha>/<path-to-spec.md>
+ */
+import { DIFFMAP_ORIGIN } from "../gist/route.ts";
+
+const NAME_PATTERN = /^[A-Za-z0-9._-]+$/;
+const SHA_PATTERN = /^[0-9a-f]{7,40}$/i;
+const PULL_PATTERN = /^[1-9][0-9]{0,9}$/;
+const MARKDOWN_EXT = /\.(?:md|mdx)$/i;
+
+export type GitHubRoute =
+  | {
+      kind: "github-pull";
+      owner: string;
+      repo: string;
+      pull: number;
+      path: string;
+    }
+  | {
+      kind: "github-commit";
+      owner: string;
+      repo: string;
+      sha: string;
+      path: string;
+    }
+  | { kind: "github-invalid"; message: string };
+
+export function parseGitHubPath(
+  pathname: string,
+): GitHubRoute | { kind: "home" } {
+  const parts = normalizePath(pathname)
+    .split("/")
+    .filter((part) => part.length > 0);
+  if (parts.length < 4) return { kind: "home" };
+  const owner = decodePathSegment(parts[0] ?? "");
+  const repo = decodePathSegment(parts[1] ?? "");
+  const kind = parts[2];
+  const id = decodePathSegment(parts[3] ?? "");
+  if (!isRepoName(owner) || !isRepoName(repo)) return { kind: "home" };
+  if (kind !== "pull" && kind !== "commit") return { kind: "home" };
+
+  const specPath = parts.slice(4).map(decodePathSegment).join("/");
+  if (kind === "pull") {
+    if (!PULL_PATTERN.test(id)) {
+      return { kind: "github-invalid", message: "Not a pull request number." };
+    }
+    const pathError = specPathError(specPath);
+    if (pathError !== undefined)
+      return { kind: "github-invalid", message: pathError };
+    return {
+      kind: "github-pull",
+      owner,
+      repo,
+      pull: Number(id),
+      path: specPath,
+    };
+  }
+  if (!SHA_PATTERN.test(id)) {
+    return { kind: "github-invalid", message: "Not a git commit SHA." };
+  }
+  const pathError = specPathError(specPath);
+  if (pathError !== undefined)
+    return { kind: "github-invalid", message: pathError };
+  return {
+    kind: "github-commit",
+    owner,
+    repo,
+    sha: id.toLowerCase(),
+    path: specPath,
+  };
+}
+
+export function githubPullPath(
+  owner: string,
+  repo: string,
+  pull: number,
+  filePath: string,
+) {
+  return `/${encodeName(owner)}/${encodeName(repo)}/pull/${String(pull)}/${encodeSpecPath(filePath)}`;
+}
+
+export function githubCommitPath(
+  owner: string,
+  repo: string,
+  sha: string,
+  filePath: string,
+) {
+  return `/${encodeName(owner)}/${encodeName(repo)}/commit/${sha}/${encodeSpecPath(filePath)}`;
+}
+
+export function githubViewerUrl(
+  owner: string,
+  repo: string,
+  pin: { pull: number } | { sha: string },
+  filePath: string,
+  origin = DIFFMAP_ORIGIN,
+) {
+  const path =
+    "pull" in pin
+      ? githubPullPath(owner, repo, pin.pull, filePath)
+      : githubCommitPath(owner, repo, pin.sha, filePath);
+  return `${origin}${path}`;
+}
+
+export function githubBlobUrl(
+  owner: string,
+  repo: string,
+  sha: string,
+  filePath: string,
+) {
+  return `https://github.com/${owner}/${repo}/blob/${sha}/${filePath
+    .split("/")
+    .map(encodeURIComponent)
+    .join("/")}`;
+}
+
+export function githubPullUrl(owner: string, repo: string, pull: number) {
+  return `https://github.com/${owner}/${repo}/pull/${String(pull)}`;
+}
+
+function isRepoName(value: string) {
+  return (
+    NAME_PATTERN.test(value) &&
+    value !== "." &&
+    value !== ".." &&
+    !value.startsWith(".")
+  );
+}
+
+function specPathError(specPath: string) {
+  if (specPath.length === 0) {
+    return "A hosted spec URL needs a markdown path after the pull or commit.";
+  }
+  if (specPath.split("/").some((part) => part === "." || part === "..")) {
+    return "Spec path is not a repository file.";
+  }
+  if (!MARKDOWN_EXT.test(specPath)) {
+    return "Spec path must be a .md or .mdx file.";
+  }
+  return undefined;
+}
+
+function encodeName(value: string) {
+  return encodeURIComponent(value);
+}
+
+function encodeSpecPath(filePath: string) {
+  return filePath.split("/").map(encodeURIComponent).join("/");
+}
+
+function normalizePath(pathname: string) {
+  if (pathname.length === 0) return "/";
+  try {
+    return decodeURI(pathname);
+  } catch {
+    return pathname;
+  }
+}
+
+function decodePathSegment(value: string) {
+  try {
+    return decodeURIComponent(value);
+  } catch {
+    return value;
+  }
+}

package/src/host/HostApp.tsx

@@ -0,0 +1,22 @@
+import { useEffect, useState } from "react";
+import { GistApp } from "../gist/GistApp.tsx";
+import { GitHubApp } from "../github/GitHubApp.tsx";
+import { parseGitHubPath } from "../github/route.ts";
+
+function isGitHubPath(pathname: string) {
+  return parseGitHubPath(pathname).kind !== "home";
+}
+
+export function HostApp() {
+  const [github, setGithub] = useState(() =>
+    isGitHubPath(window.location.pathname),
+  );
+
+  useEffect(() => {
+    const onPop = () => setGithub(isGitHubPath(window.location.pathname));
+    window.addEventListener("popstate", onPop);
+    return () => window.removeEventListener("popstate", onPop);
+  }, []);
+
+  return github ? <GitHubApp /> : <GistApp />;
+}

package/src/host/HostHome.tsx

@@ -0,0 +1,73 @@
+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 { 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,
+};
+
+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}>
+      <ViewerApp
+        document={view.document}
+        mode="host"
+        headerActions={
+          <Link href="https://github.com/tanishqkancharla/diffmap">GitHub</Link>
+        }
+      />
+    </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,194 @@
+# 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-spec
+```
+
+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`, excerpt, and hunk load from that commit, not `main`. A PR number only chooses the SHA (head at load, then pin). Refresh stays on the commit URL.
+
+## What the fences are
+
+### System flow
+
+Click a node. `%% ref` is a mermaid comment; `[[path]]` and `[[path#symbol]]` are the same references as on a stack row.
+
+```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 [[cli:new:50]]
+```
+
+````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, retarget `[[path]]` to a hunk: `[[id:old:…]]` / `[[id:new:…]]`.
+
+```callstack
+ ViewerApp
+-└── CloseServerButton  # every hosted page tried to stop a server [[close:old:217]]
++└── CloseServerButton  # local mode only [[close:new:217-224]]
+     └── DiffButton
+```
+
+```callstack
+ shareMarkdownFile [[src/share.ts#shareMarkdownFile]]
+-└── print gist URL [[share:old:62]]
++└── gistViewerUrl  # https://diffmap.dev/g/<id> [[share:new:62]]
+```
+
+### Source patches
+
+Define each id once. Copy the real `git diff` (`diff --git`, `---`, `+++`, `@@`). Ranges have to sit inside an included hunk.
+
+```source-diff:cli:src/cli.ts
+diff --git a/src/cli.ts b/src/cli.ts
+--- a/src/cli.ts
++++ b/src/cli.ts
+@@ -49,4 +49,4 @@
+ const cli = Cli.create("diffmap", {
+-  description: "Serve a walkthrough",
++  description: "Serve a spec locally, or share it as a gist",
+   version: "0.1.3",
+   args: serveArgs,
+```
+
+```source-diff:share:src/share.ts
+diff --git a/src/share.ts b/src/share.ts
+--- a/src/share.ts
++++ b/src/share.ts
+@@ -59,6 +59,6 @@
+   return {
+     gistId,
+     gistUrl,
+-    viewerUrl: gistUrl,
++    viewerUrl: gistViewerUrl(gistId, undefined, process.env.DIFFMAP_ORIGIN),
+   };
+ }
+```
+
+```source-diff:close:src/viewer/ViewerApp.tsx
+diff --git a/src/viewer/ViewerApp.tsx b/src/viewer/ViewerApp.tsx
+--- a/src/viewer/ViewerApp.tsx
++++ b/src/viewer/ViewerApp.tsx
+@@ -216,3 +216,10 @@
+             {props.headerActions}
+-            <CloseServerButton onClick={() => setShutDown(true)} />
++            {props.mode === "local" && (
++              <CloseServerButton
++                onClick={() => {
++                  setShutDown(true);
++                  void closeViewer();
++                }}
++              />
++            )}
+           </div>
+```
+
+### 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, paste the patch and retarget the links so the Diff panel opens the change, not just the file.
+
+### Phase 1: Spec and serve
+
+```callstack
+ generate-spec
+ └── 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 [[share:new:62]]
++└── 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,82 @@
+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("source-diff"), 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.sourceDiffs.length >= 3);
+  assert.equal(document.hasReferences, true);
+
+  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

@@ -17,6 +17,7 @@ export type {
   ViewerView,
 } from "./parseViewer.js";
 export { gistViewerUrl } from "./gist/route.js";
+export { githubViewerUrl } from "./github/route.js";
 export { shareMarkdownFile } from "./share.js";
 export { startServer } from "./serve.js";
 export type { FileExcerpt, StartServerInput, DiffmapServer } from "./serve.js";

package/src/mermaid.ts

@@ -2,6 +2,28 @@ import { renderMermaidSVG } from "beautiful-mermaid";
 import * as errore from "errore";
 import { DiffmapMermaidError } from "./errors.js";
 
+function mermaidReason(cause: unknown) {
+  if (cause instanceof Error && cause.message !== "") return cause.message;
+  return "unknown error";
+}
+
+export function parseMermaidDiagram(input: {
+  source: string;
+  path: string;
+  where: string;
+}) {
+  return errore.try({
+    try: () => renderMermaidSVG(input.source),
+    catch: (cause) =>
+      new DiffmapMermaidError({
+        path: input.path,
+        where: input.where,
+        reason: mermaidReason(cause),
+        cause,
+      }),
+  });
+}
+
 export function mermaidSvg(input: {
   source: string;
   bg: string;
@@ -24,6 +46,12 @@ export function mermaidSvg(input: {
         font: input.font,
         transparent: true,
       }),
-    catch: (cause) => new DiffmapMermaidError({ cause }),
+    catch: (cause) =>
+      new DiffmapMermaidError({
+        path: "spec",
+        where: "diagram 1",
+        reason: mermaidReason(cause),
+        cause,
+      }),
   });
 }

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;