@tanishqkancharla/diffmap 0.1.3

package/src/gist/GistStatus.tsx

@@ -0,0 +1,137 @@
+import type { ReactNode } from "react";
+import {
+  backgroundColor,
+  border,
+  colors,
+  flex,
+  flexItem,
+  Link,
+  P,
+  spacing,
+  text,
+  Thinking,
+} from "maui";
+import { style, useStyles } from "purse-styles";
+import { githubGistUrl } from "./route.ts";
+
+export function GistStatus(props: {
+  title: string;
+  children: ReactNode;
+  gistId?: string;
+  gistUrl?: string;
+}) {
+  const shell = useStyles(styles.shell);
+  const header = useStyles(styles.header);
+  const heading = useStyles(styles.heading);
+  const body = useStyles(styles.body);
+  const title = useStyles(styles.title);
+  const gistUrl =
+    props.gistUrl ??
+    (props.gistId === undefined ? undefined : githubGistUrl(props.gistId));
+
+  return (
+    <div className={shell}>
+      <header className={header}>
+        <div className={heading}>diffmap</div>
+      </header>
+      <main className={body}>
+        <h1 className={title}>{props.title}</h1>
+        {props.children}
+        {gistUrl !== undefined && (
+          <P>
+            <Link href={gistUrl}>Open gist on GitHub</Link>
+          </P>
+        )}
+      </main>
+    </div>
+  );
+}
+
+export function GistLoading() {
+  const row = useStyles(styles.loading);
+  return (
+    <GistStatus title="Loading gist…">
+      <div className={row}>
+        <Thinking />
+      </div>
+    </GistStatus>
+  );
+}
+
+export function GistLanding() {
+  const code = useStyles(styles.code);
+  return (
+    <GistStatus title="diffmap">
+      <P>
+        A hosted viewer for diffmap walkthroughs. This page fetches a GitHub
+        gist in your browser. There is no server holding the markdown.
+      </P>
+      <P>
+        Canonical URL:{" "}
+        <code className={code}>https://diffmap.dev/g/&lt;gistId&gt;</code>.
+        Optional file:{" "}
+        <code className={code}>/g/&lt;gistId&gt;/&lt;file.md&gt;</code>. Heading
+        hashes stay in the fragment, same as the local viewer.
+      </P>
+      <P>
+        Share a secret gist (requires <code className={code}>gh</code>
+        ):
+      </P>
+      <P>
+        <code className={code}>npx diffmap share path/to.md</code>
+      </P>
+      <P>
+        Secret gists are unlisted, not private. Anyone with the id can read
+        them. Unauthenticated GitHub API is 60 requests per hour per IP.
+      </P>
+      <P>
+        <Link href="https://github.com/tanishqkancharla/diffmap">
+          tanishqkancharla/diffmap
+        </Link>
+      </P>
+    </GistStatus>
+  );
+}
+
+const styles = {
+  shell: style(flex({ direction: "column" }), {
+    width: "100%",
+    height: "100vh",
+    minWidth: 0,
+    minHeight: 0,
+    overflow: "hidden",
+    backgroundColor: colors.gray[4],
+  }),
+  header: style(
+    flex({ direction: "row", align: "center", justify: "between" }),
+    spacing.padding({ x: 6, y: 3 }),
+    flexItem({ size: "hug" }),
+    border(["bottom"], "border"),
+    {
+      minWidth: 0,
+      backgroundColor: backgroundColor.app,
+    },
+  ),
+  heading: style(text({ size: "md", fontWeight: 600, color: "highContrast" }), {
+    minWidth: 0,
+  }),
+  body: style(spacing.padding({ x: 12, y: 12 }), {
+    flex: "1 1 auto",
+    minWidth: 0,
+    minHeight: 0,
+    overflowY: "auto",
+    backgroundColor: backgroundColor.app,
+    maxWidth: "72ch",
+    width: "100%",
+    marginInline: "auto",
+  }),
+  title: style(text({ size: "xl", fontWeight: 600, color: "highContrast" }), {
+    marginBottom: spacing.value(4),
+  }),
+  loading: style(flex({ direction: "row", align: "center" }), {
+    minHeight: spacing.value(12),
+  }),
+  code: style(text({ size: "sm", color: "highContrast" }), {
+    fontFamily: "ui-monospace, SFMono-Regular, Menlo, monospace",
+  }),
+};

package/src/gist/fetchGist.ts

@@ -0,0 +1,128 @@
+import { githubGistUrl, markdownFileNames, pickMarkdownFile } from "./route.ts";
+
+export type GistMarkdownFile = {
+  name: string;
+  content: string;
+};
+
+export type GistDocument = {
+  id: string;
+  htmlUrl: string;
+  files: GistMarkdownFile[];
+  chosen: GistMarkdownFile;
+};
+
+export type GistLoadResult =
+  | { status: "ok"; gist: GistDocument }
+  | { status: "not-found" }
+  | { status: "forbidden" }
+  | { status: "no-markdown"; htmlUrl: string }
+  | { status: "missing-file"; htmlUrl: string; files: GistMarkdownFile[] }
+  | { status: "error"; message: string };
+
+type GistApiFile = {
+  filename?: string;
+  truncated?: boolean;
+  content?: string;
+  raw_url?: string;
+};
+
+type GistApiResponse = {
+  id?: string;
+  html_url?: string;
+  files?: Record<string, GistApiFile>;
+};
+
+export async function loadGistMarkdown(
+  gistId: string,
+  fileName: string | undefined,
+  signal?: AbortSignal,
+): Promise<GistLoadResult> {
+  const response = await fetch(`https://api.github.com/gists/${gistId}`, {
+    headers: { Accept: "application/vnd.github+json" },
+    signal,
+  }).catch((cause: unknown) => cause);
+
+  if (response instanceof Error) {
+    if (response.name === "AbortError") throw response;
+    return { status: "error", message: "Failed to load this gist." };
+  }
+  if (!(response instanceof Response)) {
+    return { status: "error", message: "Failed to load this gist." };
+  }
+  if (response.status === 404) return { status: "not-found" };
+  if (response.status === 403) return { status: "forbidden" };
+  if (!response.ok) {
+    return {
+      status: "error",
+      message: `GitHub returned ${String(response.status)}.`,
+    };
+  }
+
+  const payload = (await response.json().catch(() => undefined)) as
+    | GistApiResponse
+    | undefined;
+  if (payload === undefined) {
+    return { status: "error", message: "GitHub returned an invalid gist." };
+  }
+
+  const htmlUrl =
+    typeof payload.html_url === "string" && payload.html_url.length > 0
+      ? payload.html_url
+      : githubGistUrl(gistId);
+  const apiFiles = payload.files ?? {};
+  const names = markdownFileNames(Object.keys(apiFiles));
+  if (names.length === 0) return { status: "no-markdown", htmlUrl };
+
+  const files: GistMarkdownFile[] = [];
+  for (const name of names) {
+    const file = apiFiles[name];
+    if (file === undefined) continue;
+    const content = await readGistFile(file, signal);
+    if (content instanceof Error) {
+      return { status: "error", message: content.message };
+    }
+    files.push({ name, content });
+  }
+  if (files.length === 0) return { status: "no-markdown", htmlUrl };
+
+  const chosenName = pickMarkdownFile(
+    files.map((file) => file.name),
+    fileName,
+  );
+  const chosen = files.find((file) => file.name === chosenName);
+  if (chosen === undefined) {
+    return { status: "missing-file", htmlUrl, files };
+  }
+
+  return {
+    status: "ok",
+    gist: {
+      id: typeof payload.id === "string" ? payload.id : gistId,
+      htmlUrl,
+      files,
+      chosen,
+    },
+  };
+}
+
+async function readGistFile(file: GistApiFile, signal?: AbortSignal) {
+  const name = file.filename ?? "file";
+  if (file.truncated !== true && typeof file.content === "string") {
+    return file.content;
+  }
+  if (file.raw_url === undefined || file.raw_url.length === 0) {
+    return new Error(`Gist file "${name}" is truncated and has no raw URL.`);
+  }
+  const raw = await fetch(file.raw_url, { signal }).catch(
+    (cause: unknown) => cause,
+  );
+  if (raw instanceof Error) {
+    if (raw.name === "AbortError") throw raw;
+    return new Error(`Could not fetch gist file "${name}".`);
+  }
+  if (!(raw instanceof Response) || !raw.ok) {
+    return new Error(`Could not fetch gist file "${name}".`);
+  }
+  return raw.text();
+}

package/src/gist/main.tsx

@@ -0,0 +1,25 @@
+import { StrictMode } from "react";
+import { createRoot } from "react-dom/client";
+import { MauiProvider } from "maui";
+import { rewritePiGistUrl } from "./route.ts";
+import { GistApp } from "./GistApp.tsx";
+import "../viewer/styles.css";
+
+const rewritten = rewritePiGistUrl(
+  window.location.pathname,
+  window.location.hash,
+);
+if (rewritten !== undefined) {
+  window.history.replaceState({}, "", rewritten);
+}
+
+const root = document.getElementById("root");
+if (root === null) throw new Error("diffmap root element is missing");
+
+createRoot(root).render(
+  <StrictMode>
+    <MauiProvider>
+      <GistApp />
+    </MauiProvider>
+  </StrictMode>,
+);

package/src/gist/route.test.ts

@@ -0,0 +1,90 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+import {
+  extractGistId,
+  gistPath,
+  gistViewerUrl,
+  parseGistPath,
+  parsePiGistHash,
+  pickMarkdownFile,
+  rewritePiGistUrl,
+} from "./route.ts";
+
+const id = "0123456789abcdef0123456789abcdef";
+
+test("extractGistId accepts hex and gist URLs", () => {
+  assert.equal(extractGistId(id), id);
+  assert.equal(extractGistId(`https://gist.github.com/tanishq/${id}`), id);
+  assert.equal(extractGistId(`gist.github.com/${id}`), id);
+  assert.equal(extractGistId("not-a-gist"), undefined);
+  assert.equal(extractGistId("abcd"), undefined);
+});
+
+test("parseGistPath reads /g/:id/:file and heading-safe home", () => {
+  assert.deepEqual(parseGistPath("/"), { kind: "home" });
+  assert.deepEqual(parseGistPath("/g"), { kind: "empty" });
+  assert.deepEqual(parseGistPath("/g/"), { kind: "empty" });
+  assert.deepEqual(parseGistPath(`/g/${id}`), {
+    kind: "gist",
+    gistId: id,
+    file: undefined,
+  });
+  assert.deepEqual(parseGistPath(`/g/${id}/walkthrough.md`), {
+    kind: "gist",
+    gistId: id,
+    file: "walkthrough.md",
+  });
+  assert.deepEqual(parseGistPath(`/g/${id}/nested/spec.md`), {
+    kind: "gist",
+    gistId: id,
+    file: "nested/spec.md",
+  });
+  assert.equal(parseGistPath("/g/not-an-id").kind, "invalid");
+  assert.deepEqual(parseGistPath(`/g/https://gist.github.com/tanishq/${id}`), {
+    kind: "gist",
+    gistId: id,
+    file: undefined,
+  });
+});
+
+test("Pi-shaped hash rewrites once to the canonical path", () => {
+  assert.deepEqual(parsePiGistHash(`#${id}`), { gistId: id, file: undefined });
+  assert.deepEqual(parsePiGistHash(`#${id}/README.md`), {
+    gistId: id,
+    file: "README.md",
+  });
+  assert.equal(parsePiGistHash("#implementation"), undefined);
+  assert.equal(rewritePiGistUrl(`/g/${id}`, `#${id}`), undefined);
+  assert.equal(rewritePiGistUrl("/g", `#${id}`), `/g/${id}`);
+  assert.equal(
+    rewritePiGistUrl("/g", `#${id}/spec.md&leafId=1`),
+    `/g/${id}/spec.md`,
+  );
+});
+
+test("pickMarkdownFile prefers README, then only md, then walkthrough/spec", () => {
+  assert.equal(
+    pickMarkdownFile(["notes.txt", "README.md", "a.md"], undefined),
+    "README.md",
+  );
+  assert.equal(pickMarkdownFile(["only.md"], undefined), "only.md");
+  assert.equal(
+    pickMarkdownFile(["z.md", "walkthrough.md"], undefined),
+    "walkthrough.md",
+  );
+  assert.equal(pickMarkdownFile(["b.md", "a.md"], undefined), "a.md");
+  assert.equal(
+    pickMarkdownFile(["README.md", "spec.md"], "spec.md"),
+    "spec.md",
+  );
+  assert.equal(pickMarkdownFile(["README.md"], "missing.md"), undefined);
+});
+
+test("printed viewer URL keeps gist id in the path", () => {
+  assert.equal(gistPath(id), `/g/${id}`);
+  assert.equal(gistViewerUrl(id), `https://diffmap.dev/g/${id}`);
+  assert.equal(
+    gistViewerUrl(id, "Phase 1.md"),
+    `https://diffmap.dev/g/${id}/Phase%201.md`,
+  );
+});

package/src/gist/route.ts

@@ -0,0 +1,134 @@
+export const DIFFMAP_ORIGIN = "https://diffmap.dev";
+export const GIST_ID_PATTERN = /^[0-9a-f]{32}$/i;
+const GIST_URL_PATTERN =
+  /(?:https?:\/\/)?gist\.github\.com\/(?:[^/]+\/)?([0-9a-f]{32})/i;
+const MARKDOWN_EXT = /\.(?:md|mdx)$/i;
+
+export type GistRoute =
+  | { kind: "home" }
+  | { kind: "empty" }
+  | { kind: "invalid"; value: string }
+  | { kind: "gist"; gistId: string; file: string | undefined };
+
+export function extractGistId(value: string) {
+  const trimmed = value.trim();
+  if (trimmed.length === 0) return undefined;
+  if (GIST_ID_PATTERN.test(trimmed)) return trimmed.toLowerCase();
+  const fromUrl = GIST_URL_PATTERN.exec(trimmed);
+  if (fromUrl?.[1] !== undefined) return fromUrl[1].toLowerCase();
+  try {
+    const decoded = decodeURIComponent(trimmed);
+    if (decoded !== trimmed) return extractGistId(decoded);
+  } catch {
+    return undefined;
+  }
+  return undefined;
+}
+
+export function parsePiGistHash(hash: string) {
+  const raw = hash.replace(/^#/, "").split("&", 1)[0] ?? "";
+  if (raw.length === 0) return undefined;
+  const [idPart, ...fileParts] = raw.split("/");
+  const gistId = extractGistId(idPart ?? "");
+  if (gistId === undefined) return undefined;
+  const file =
+    fileParts.length === 0
+      ? undefined
+      : fileParts.map(decodePathSegment).join("/");
+  return { gistId, file };
+}
+
+export function parseGistPath(pathname: string): GistRoute {
+  const path = normalizePath(pathname);
+  const parts = path.split("/").filter((part) => part.length > 0);
+  if (parts.length === 0) return { kind: "home" };
+  if (parts[0] !== "g") return { kind: "home" };
+  if (parts.length === 1) return { kind: "empty" };
+
+  const rest = parts.slice(1).join("/");
+  const nestedId = extractGistId(rest) ?? extractGistId(path);
+  const firstId = extractGistId(decodePathSegment(parts[1] ?? ""));
+  const gistId = firstId ?? nestedId;
+  if (gistId === undefined) {
+    return { kind: "invalid", value: decodePathSegment(parts[1] ?? "") };
+  }
+  const file =
+    firstId === undefined || parts.length === 2
+      ? undefined
+      : parts.slice(2).map(decodePathSegment).join("/");
+  return {
+    kind: "gist",
+    gistId,
+    file: file === undefined || file.length === 0 ? undefined : file,
+  };
+}
+
+export function rewritePiGistUrl(pathname: string, hash: string) {
+  const parsed = parseGistPath(pathname);
+  if (parsed.kind !== "empty") return undefined;
+  const pi = parsePiGistHash(hash);
+  if (pi === undefined) return undefined;
+  return gistPath(pi.gistId, pi.file);
+}
+
+export function gistPath(gistId: string, file?: string) {
+  if (file === undefined || file.length === 0) return `/g/${gistId}`;
+  return `/g/${gistId}/${file.split("/").map(encodeURIComponent).join("/")}`;
+}
+
+export function gistViewerUrl(
+  gistId: string,
+  file?: string,
+  origin = DIFFMAP_ORIGIN,
+) {
+  return `${origin}${gistPath(gistId, file)}`;
+}
+
+export function githubGistUrl(gistId: string) {
+  return `https://gist.github.com/${gistId}`;
+}
+
+export function markdownFileNames(files: string[]) {
+  return files
+    .filter((name) => MARKDOWN_EXT.test(name))
+    .toSorted((a, b) => a.localeCompare(b));
+}
+
+export function pickMarkdownFile(
+  files: string[],
+  requested: string | undefined,
+) {
+  const markdown = markdownFileNames(files);
+  if (requested !== undefined && requested.length > 0) {
+    const exact = files.find((name) => name === requested);
+    if (exact !== undefined && MARKDOWN_EXT.test(exact)) return exact;
+    return markdown.find(
+      (name) => name.toLowerCase() === requested.toLowerCase(),
+    );
+  }
+  const readme = markdown.find((name) => name.toLowerCase() === "readme.md");
+  if (readme !== undefined) return readme;
+  if (markdown.length === 1) return markdown[0];
+  for (const preferred of ["walkthrough.md", "spec.md"]) {
+    const found = markdown.find((name) => name.toLowerCase() === preferred);
+    if (found !== undefined) return found;
+  }
+  return markdown[0];
+}
+
+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/index.ts

@@ -0,0 +1,22 @@
+export { extractFences, extractTitle } from "./extractDocument.js";
+export {
+  isCallStackSource,
+  parseFence,
+  pathFromDiffSource,
+} from "./parseFence.js";
+export type { Fence } from "./parseFence.js";
+export { parseViewerDocument } from "./parseViewer.js";
+export type {
+  ViewerDocument,
+  ViewerElement,
+  ViewerElementAttrs,
+  ViewerHeading,
+  ViewerHtml,
+  ViewerNode,
+  ViewerText,
+  ViewerView,
+} from "./parseViewer.js";
+export { gistViewerUrl } from "./gist/route.js";
+export { shareMarkdownFile } from "./share.js";
+export { startServer } from "./serve.js";
+export type { FileExcerpt, StartServerInput, DiffmapServer } from "./serve.js";

package/src/invokeCwd.ts

@@ -0,0 +1,10 @@
+import path from "node:path";
+
+function invokeWorkingDirectory() {
+  if (process.env.INIT_CWD === undefined) return process.cwd();
+  return process.env.INIT_CWD;
+}
+
+export function resolveFromInvokeCwd(filePath: string) {
+  return path.resolve(invokeWorkingDirectory(), filePath);
+}

package/src/mermaid.ts

@@ -0,0 +1,29 @@
+import { renderMermaidSVG } from "beautiful-mermaid";
+import * as errore from "errore";
+import { DiffmapMermaidError } from "./errors.js";
+
+export function mermaidSvg(input: {
+  source: string;
+  bg: string;
+  fg: string;
+  accent: string;
+  muted: string;
+  surface: string;
+  border: string;
+  font: string;
+}) {
+  return errore.try({
+    try: () =>
+      renderMermaidSVG(input.source, {
+        bg: input.bg,
+        fg: input.fg,
+        accent: input.accent,
+        muted: input.muted,
+        surface: input.surface,
+        border: input.border,
+        font: input.font,
+        transparent: true,
+      }),
+    catch: (cause) => new DiffmapMermaidError({ cause }),
+  });
+}

package/src/normalizeDiff.ts

@@ -0,0 +1,39 @@
+export function toUnifiedDiff(source: string, path: string) {
+  if (/^--- /m.test(source) && /^\+\+\+ /m.test(source)) return source;
+
+  const lines = source.split("\n");
+  const first = lines[0];
+  const body =
+    first !== undefined && first.startsWith("// ") ? lines.slice(1) : lines;
+  const normalized = body.map((line) => {
+    if (
+      line.startsWith("+") ||
+      line.startsWith("-") ||
+      line.startsWith(" ") ||
+      line.startsWith("\\")
+    ) {
+      return line;
+    }
+    return ` ${line}`;
+  });
+
+  let oldCount = 0;
+  let newCount = 0;
+  for (const line of normalized) {
+    if (line.startsWith("+")) {
+      newCount += 1;
+      continue;
+    }
+    if (line.startsWith("-")) {
+      oldCount += 1;
+      continue;
+    }
+    if (line.startsWith("\\")) continue;
+    oldCount += 1;
+    newCount += 1;
+  }
+
+  const oldRange = oldCount === 0 ? "-0,0" : `-1,${oldCount}`;
+  const newRange = newCount === 0 ? "+0,0" : `+1,${newCount}`;
+  return `--- a/${path}\n+++ b/${path}\n@@ ${oldRange} ${newRange} @@\n${normalized.join("\n")}\n`;
+}