@tanishqkancharla/diffmap 0.1.3 → 0.1.4

package/src/github/GitHubApp.tsx

@@ -0,0 +1,235 @@
+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 { loadPinnedSpec, type PinnedSpec } from "./fetchRepo.ts";
+import { GitHubPinContext } from "./pin.ts";
+import {
+  githubBlobUrl,
+  githubCommitPath,
+  githubPullUrl,
+  parseGitHubPath,
+  type GitHubRoute,
+} from "./route.ts";
+
+let parserReady: Promise<void> | undefined;
+
+function readyParser() {
+  parserReady ??= init();
+  return parserReady;
+}
+
+type GitHubView =
+  | { kind: "not-found" }
+  | { kind: "forbidden" }
+  | { kind: "error"; message: string }
+  | { kind: "parse-error"; htmlUrl: string; message: string }
+  | { kind: "ready"; spec: PinnedSpec; document: ViewerDocument };
+
+export function GitHubApp() {
+  const [route, setRoute] = useState(readGitHubRoute);
+  const routeKey = gitHubRouteKey(route);
+  const [loaded, setLoaded] = useState<{ key: string; view: GitHubView }>();
+
+  useEffect(() => {
+    const onPop = () => setRoute(readGitHubRoute());
+    window.addEventListener("popstate", onPop);
+    return () => window.removeEventListener("popstate", onPop);
+  }, []);
+
+  useEffect(() => {
+    if (route.kind === "github-invalid") return;
+    const key = gitHubRouteKey(route);
+    const abort = new AbortController();
+    // oxlint-disable-next-line typescript/no-floating-promises -- The effect owns this load; abort on cleanup.
+    void loadView(route, abort.signal).then(
+      (next) => {
+        if (!abort.signal.aborted) setLoaded({ key, view: next });
+      },
+      (cause: unknown) => {
+        if (abort.signal.aborted) return;
+        setLoaded({
+          key,
+          view: {
+            kind: "error",
+            message:
+              cause instanceof Error
+                ? cause.message
+                : "Failed to load this spec.",
+          },
+        });
+      },
+    );
+    return () => abort.abort();
+  }, [route]);
+
+  if (route.kind === "github-invalid") {
+    return (
+      <GistStatus title="Not a hosted spec">
+        <P>{route.message}</P>
+        <P>
+          Use{" "}
+          <code>
+            /&lt;owner&gt;/&lt;repo&gt;/pull/&lt;n&gt;/&lt;path.md&gt;
+          </code>{" "}
+          or{" "}
+          <code>
+            /&lt;owner&gt;/&lt;repo&gt;/commit/&lt;sha&gt;/&lt;path.md&gt;
+          </code>
+          .
+        </P>
+      </GistStatus>
+    );
+  }
+
+  if (loaded === undefined || loaded.key !== routeKey) {
+    return <GistLoading title="Loading spec…" />;
+  }
+  const view = loaded.view;
+  if (view.kind === "not-found") {
+    return (
+      <GistStatus title="Spec not found">
+        <P>
+          GitHub has no public file at this pull or commit. Private repos are
+          out of scope.
+        </P>
+      </GistStatus>
+    );
+  }
+  if (view.kind === "forbidden") {
+    return (
+      <GistStatus title="Failed to load">
+        <P>
+          GitHub refused this request. Unauthenticated API calls are limited to
+          60 per hour per IP. Wait and refresh, or open the file on GitHub.
+        </P>
+      </GistStatus>
+    );
+  }
+  if (view.kind === "error") {
+    return (
+      <GistStatus title="Failed to load">
+        <P>{view.message}</P>
+      </GistStatus>
+    );
+  }
+  if (view.kind === "parse-error") {
+    return (
+      <GistStatus
+        title="Could not parse this walkthrough"
+        gistUrl={view.htmlUrl}
+        linkLabel="Open file on GitHub"
+      >
+        <P>{view.message}</P>
+      </GistStatus>
+    );
+  }
+
+  const spec = view.spec;
+  return (
+    <GitHubPinContext.Provider value={spec}>
+      <ViewerApp
+        key={`${spec.owner}/${spec.repo}@${spec.sha}:${spec.path}`}
+        document={view.document}
+        mode="github"
+        headerActions={
+          <GitHubHeader
+            owner={spec.owner}
+            repo={spec.repo}
+            sha={spec.sha}
+            path={spec.path}
+            pullNumber={spec.pullNumber}
+            pullUrl={spec.pullUrl}
+          />
+        }
+      />
+    </GitHubPinContext.Provider>
+  );
+}
+
+async function loadView(
+  route: Exclude<GitHubRoute, { kind: "github-invalid" }>,
+  signal: AbortSignal,
+): Promise<GitHubView> {
+  await readyParser();
+  const loaded = await loadPinnedSpec({
+    owner: route.owner,
+    repo: route.repo,
+    path: route.path,
+    sha: route.kind === "github-commit" ? route.sha : undefined,
+    pull: route.kind === "github-pull" ? route.pull : undefined,
+    signal,
+  });
+  if (loaded.status === "not-found") return { kind: "not-found" };
+  if (loaded.status === "forbidden") return { kind: "forbidden" };
+  if (loaded.status === "error") {
+    return { kind: "error", message: loaded.message };
+  }
+
+  const spec = loaded.spec;
+  if (route.kind === "github-pull") {
+    const pinned = githubCommitPath(spec.owner, spec.repo, spec.sha, spec.path);
+    if (window.location.pathname !== pinned) {
+      window.history.replaceState({}, "", `${pinned}${window.location.hash}`);
+    }
+  }
+
+  const parsed = parseViewerDocument(spec.content, spec.path);
+  if (parsed instanceof Error) {
+    return {
+      kind: "parse-error",
+      htmlUrl: spec.htmlUrl,
+      message: parsed.message,
+    };
+  }
+  const document =
+    parsed.sourceDiffs.length > 0
+      ? parsed
+      : { ...parsed, sourceDiffs: spec.pullDiffs };
+  return { kind: "ready", spec, document };
+}
+
+function readGitHubRoute(): GitHubRoute {
+  const parsed = parseGitHubPath(window.location.pathname);
+  if (parsed.kind === "home") {
+    return {
+      kind: "github-invalid",
+      message: "Not a GitHub-hosted spec URL.",
+    };
+  }
+  return parsed;
+}
+
+function gitHubRouteKey(route: GitHubRoute) {
+  if (route.kind === "github-invalid") return `invalid:${route.message}`;
+  if (route.kind === "github-pull") {
+    return `pull:${route.owner}/${route.repo}/${String(route.pull)}/${route.path}`;
+  }
+  return `commit:${route.owner}/${route.repo}/${route.sha}/${route.path}`;
+}
+
+function GitHubHeader(props: {
+  owner: string;
+  repo: string;
+  sha: string;
+  path: string;
+  pullNumber?: number;
+  pullUrl?: string;
+}) {
+  const shortSha = props.sha.slice(0, 7);
+  const blobUrl = githubBlobUrl(props.owner, props.repo, props.sha, props.path);
+  const pullHref =
+    props.pullUrl ??
+    (props.pullNumber === undefined
+      ? undefined
+      : githubPullUrl(props.owner, props.repo, props.pullNumber));
+  return (
+    <>
+      {pullHref !== undefined && <Link href={pullHref}>PR</Link>}
+      <Link href={blobUrl}>{`${props.owner}/${props.repo}@${shortSha}`}</Link>
+    </>
+  );
+}

package/src/github/fetchRepo.test.ts

@@ -0,0 +1,17 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+import { findSymbolLineRange } from "./fetchRepo.ts";
+
+test("findSymbolLineRange highlights a function declaration", () => {
+  const source = ["const x = 1;", "export function startServer() {", "}"].join(
+    "\n",
+  );
+  assert.deepEqual(findSymbolLineRange(source, "startServer"), {
+    start: 2,
+    end: 2,
+  });
+  assert.deepEqual(findSymbolLineRange(source, "Serve.startServer"), {
+    start: 2,
+    end: 2,
+  });
+});

package/src/github/fetchRepo.ts

@@ -0,0 +1,300 @@
+/**
+ * Pin model (locked): fetch the spec and every referenced file from one commit
+ * SHA. A PR number is only used to choose that SHA (head at load time). Never
+ * 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";
+
+const GITHUB_API = "https://api.github.com";
+const GITHUB_JSON = {
+  Accept: "application/vnd.github+json",
+};
+
+export type PinnedSpec = {
+  owner: string;
+  repo: string;
+  sha: string;
+  path: string;
+  content: string;
+  htmlUrl: string;
+  pullNumber?: number;
+  pullUrl?: string;
+  pullDiffs: CodeViewDiffItem[];
+};
+
+export type GitHubSpecResult =
+  | { status: "ok"; spec: PinnedSpec }
+  | { status: "not-found" }
+  | { status: "forbidden" }
+  | { status: "error"; message: string };
+
+type PullApi = {
+  html_url?: string;
+  head?: { sha?: string };
+};
+
+type ContentsApi = {
+  type?: string;
+  encoding?: string;
+  content?: string;
+  download_url?: string | null;
+  size?: number;
+};
+
+const blobCache = new Map<string, Promise<string | Error>>();
+
+export async function loadPinnedSpec(input: {
+  owner: string;
+  repo: string;
+  path: string;
+  sha?: string;
+  pull?: number;
+  signal?: AbortSignal;
+}): Promise<GitHubSpecResult> {
+  let sha = input.sha;
+  let pullNumber = input.pull;
+  let pullUrl: string | undefined;
+  if (sha === undefined) {
+    if (pullNumber === undefined) {
+      return { status: "error", message: "Need a pull number or commit SHA." };
+    }
+    const resolved = await resolvePullHead(
+      input.owner,
+      input.repo,
+      pullNumber,
+      input.signal,
+    );
+    if (resolved.status !== "ok") return resolved;
+    sha = resolved.sha;
+    pullUrl = resolved.htmlUrl;
+  }
+
+  const blob = await fetchPinnedBlob(
+    { owner: input.owner, repo: input.repo, sha },
+    input.path,
+    input.signal,
+  );
+  if (blob instanceof Error) {
+    if (blob.message === "not-found") return { status: "not-found" };
+    if (blob.message === "forbidden") return { status: "forbidden" };
+    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: {
+      owner: input.owner,
+      repo: input.repo,
+      sha,
+      path: input.path,
+      content: blob,
+      htmlUrl: `https://github.com/${input.owner}/${input.repo}/blob/${sha}/${input.path}`,
+      pullNumber,
+      pullUrl,
+      pullDiffs,
+    },
+  };
+}
+
+export async function fetchPinnedBlob(
+  pin: { owner: string; repo: string; sha: string },
+  filePath: string,
+  signal?: AbortSignal,
+): Promise<string | Error> {
+  const key = `${pin.owner}/${pin.repo}@${pin.sha}:${filePath}`;
+  const pending = blobCache.get(key);
+  if (pending !== undefined) return pending;
+
+  const request = readContents(pin, filePath, signal).catch(
+    (cause: unknown) => {
+      blobCache.delete(key);
+      if (cause instanceof Error && cause.name === "AbortError") throw cause;
+      return cause instanceof Error
+        ? cause
+        : new Error("Failed to load this file from GitHub.");
+    },
+  );
+  blobCache.set(key, request);
+  return request;
+}
+
+export function findSymbolLineRange(contents: string, symbol: string) {
+  const name = symbol.includes(".")
+    ? symbol.slice(symbol.lastIndexOf(".") + 1)
+    : symbol;
+  const lines = contents.split(/\r?\n/);
+  const escaped = name.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+  const pattern = new RegExp(
+    `(?:function|class|const|let|var|type|interface|enum|#)\\s+${escaped}\\b|\\b${escaped}\\s*[=:(]`,
+  );
+  for (let index = 0; index < lines.length; index++) {
+    if (pattern.test(lines[index]!)) {
+      return { start: index + 1, end: index + 1 };
+    }
+  }
+  return { start: 1, end: Math.max(1, lines.length) };
+}
+
+async function resolvePullHead(
+  owner: string,
+  repo: string,
+  pull: number,
+  signal?: AbortSignal,
+): Promise<
+  | { status: "ok"; sha: string; htmlUrl: string }
+  | { status: "not-found" }
+  | { status: "forbidden" }
+  | { status: "error"; message: string }
+> {
+  const response = await githubFetch(
+    `/repos/${encodeURIComponent(owner)}/${encodeURIComponent(repo)}/pulls/${String(pull)}`,
+    signal,
+  );
+  if (response.status !== "ok") return response;
+  const payload = (await response.body.json().catch(() => undefined)) as
+    | PullApi
+    | undefined;
+  const sha = payload?.head?.sha;
+  if (typeof sha !== "string" || sha.length === 0) {
+    return {
+      status: "error",
+      message: "GitHub did not return a pull head SHA.",
+    };
+  }
+  return {
+    status: "ok",
+    sha,
+    htmlUrl:
+      typeof payload?.html_url === "string"
+        ? payload.html_url
+        : `https://github.com/${owner}/${repo}/pull/${String(pull)}`,
+  };
+}
+
+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,
+    );
+    if (response.status === "not-found") return new Error("not-found");
+    if (response.status === "forbidden") return new Error("forbidden");
+    if (response.status === "error") return new Error(response.message);
+    const payload = (await response.body.json().catch(() => undefined)) as
+      | GitHubPullFile[]
+      | undefined;
+    if (!Array.isArray(payload)) {
+      return new Error("GitHub returned invalid pull files.");
+    }
+    files.push(...payload);
+    if (payload.length < 100) break;
+  }
+  return files;
+}
+
+async function readContents(
+  pin: { owner: string; repo: string; sha: string },
+  filePath: string,
+  signal?: AbortSignal,
+): Promise<string | Error> {
+  const encodedPath = filePath.split("/").map(encodeURIComponent).join("/");
+  const response = await githubFetch(
+    `/repos/${encodeURIComponent(pin.owner)}/${encodeURIComponent(pin.repo)}/contents/${encodedPath}?ref=${encodeURIComponent(pin.sha)}`,
+    signal,
+  );
+  if (response.status === "not-found") return new Error("not-found");
+  if (response.status === "forbidden") return new Error("forbidden");
+  if (response.status === "error") return new Error(response.message);
+  const payload = (await response.body.json().catch(() => undefined)) as
+    | ContentsApi
+    | ContentsApi[]
+    | undefined;
+  if (Array.isArray(payload)) {
+    return new Error(`"${filePath}" is a directory at this commit.`);
+  }
+  if (payload === undefined) {
+    return new Error(`Could not read "${filePath}" at this commit.`);
+  }
+  if (payload.type !== undefined && payload.type !== "file") {
+    return new Error(`"${filePath}" is not a file at this commit.`);
+  }
+  if (payload.encoding === "base64" && typeof payload.content === "string") {
+    return decodeBase64(payload.content.replace(/\n/g, ""));
+  }
+  if (
+    typeof payload.download_url === "string" &&
+    payload.download_url.length > 0
+  ) {
+    const raw = await fetch(payload.download_url, { signal }).catch(
+      (cause: unknown) => cause,
+    );
+    if (raw instanceof Error) {
+      if (raw.name === "AbortError") throw raw;
+      return new Error(`Could not fetch "${filePath}" at this commit.`);
+    }
+    if (!(raw instanceof Response) || !raw.ok) {
+      return new Error(`Could not fetch "${filePath}" at this commit.`);
+    }
+    return raw.text();
+  }
+  return new Error(`Could not read "${filePath}" at this commit.`);
+}
+
+function decodeBase64(value: string) {
+  try {
+    const binary = atob(value);
+    const bytes = Uint8Array.from(binary, (char) => char.charCodeAt(0));
+    return new TextDecoder().decode(bytes);
+  } catch (cause) {
+    return new Error("GitHub returned invalid file encoding.", { cause });
+  }
+}
+
+async function githubFetch(path: string, signal?: AbortSignal) {
+  const response = await fetch(`${GITHUB_API}${path}`, {
+    headers: GITHUB_JSON,
+    signal,
+  }).catch((cause: unknown) => cause);
+  if (response instanceof Error) {
+    if (response.name === "AbortError") throw response;
+    return { status: "error" as const, message: "Failed to reach GitHub." };
+  }
+  if (!(response instanceof Response)) {
+    return { status: "error" as const, message: "Failed to reach GitHub." };
+  }
+  if (response.status === 404) return { status: "not-found" as const };
+  if (response.status === 403) return { status: "forbidden" as const };
+  if (!response.ok) {
+    return {
+      status: "error" as const,
+      message: `GitHub returned ${String(response.status)}.`,
+    };
+  }
+  return { status: "ok" as const, body: response };
+}

package/src/github/patch.test.ts

@@ -0,0 +1,30 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+import { parsePatchFiles } from "@pierre/diffs";
+import { pullFilesToSourceDiffs, wrapGitHubPullPatch } from "./patch.ts";
+
+test("wrapGitHubPullPatch builds a unified diff Pierre can parse", () => {
+  const wrapped = wrapGitHubPullPatch({
+    filename: "src/cli.ts",
+    status: "modified",
+    patch: ["@@ -1,3 +1,4 @@", " line", "+added", " line", " line"].join("\n"),
+  });
+  assert.equal(typeof wrapped, "string");
+  const patches = parsePatchFiles(wrapped!, undefined, true);
+  assert.equal(patches[0]?.files[0]?.name, "src/cli.ts");
+  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" },
+    {
+      filename: "src/cli.ts",
+      status: "modified",
+      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");
+});

package/src/github/patch.ts

@@ -0,0 +1,40 @@
+import { parsePatchFiles, type CodeViewDiffItem } from "@pierre/diffs";
+
+export type GitHubPullFile = {
+  filename: string;
+  previous_filename?: string;
+  status: string;
+  patch?: string;
+};
+
+/** Wrap a GitHub pull-files `patch` (hunks only) as a unified diff Pierre can parse. */
+export function wrapGitHubPullPatch(file: GitHubPullFile) {
+  if (file.patch === undefined || file.patch.length === 0) return undefined;
+  const oldPath = file.previous_filename ?? file.filename;
+  const newPath = file.filename;
+  const oldHeader = file.status === "added" ? "/dev/null" : `a/${oldPath}`;
+  const newHeader = file.status === "removed" ? "/dev/null" : `b/${newPath}`;
+  return [
+    `diff --git a/${oldPath} b/${newPath}`,
+    `--- ${oldHeader}`,
+    `+++ ${newHeader}`,
+    file.patch,
+  ].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;
+}

package/src/github/pin.ts

@@ -0,0 +1,14 @@
+import { createContext, useContext } from "react";
+
+/** Pinned commit: every blob fetch for this page uses this SHA, never main. */
+export type GitHubPin = {
+  owner: string;
+  repo: string;
+  sha: string;
+};
+
+export const GitHubPinContext = createContext<GitHubPin | undefined>(undefined);
+
+export function useGitHubPin() {
+  return useContext(GitHubPinContext);
+}