@tanishqkancharla/diffmap 0.1.3

package/src/definitions.ts

@@ -0,0 +1,320 @@
+import { readFileSync } from "node:fs";
+import path from "node:path";
+import {
+  isClassDeclaration,
+  isEnumDeclaration,
+  isEnumMember,
+  isFunctionDeclaration,
+  isGetAccessorDeclaration,
+  isInterfaceDeclaration,
+  isMethodDeclaration,
+  isMethodSignatureDeclaration,
+  isModuleDeclaration,
+  isPropertyDeclaration,
+  isPropertySignatureDeclaration,
+  isSetAccessorDeclaration,
+  isTypeAliasDeclaration,
+  isVariableDeclaration,
+  type Node,
+  type SourceFile,
+} from "typescript/unstable/ast";
+import {
+  API,
+  SymbolFlags,
+  type Project,
+  type Symbol as TypeScriptSymbol,
+} from "typescript/unstable/sync";
+import * as errore from "errore";
+import { DiffmapDefinitionError } from "./errors.js";
+
+export type SourceDefinition = {
+  path: string;
+  contents: string;
+  start: number;
+  end: number;
+};
+
+export type DefinitionResponse = {
+  definition?: SourceDefinition;
+  error?: string;
+};
+
+export function findDefinition(workspaceRoot: string, params: URLSearchParams) {
+  const requestedPath = params.get("path");
+  const line = Number(params.get("line"));
+  const column = Number(params.get("column"));
+  const lineText = params.get("text");
+  if (
+    requestedPath === null ||
+    lineText === null ||
+    !Number.isSafeInteger(line) ||
+    line < 1 ||
+    !Number.isSafeInteger(column) ||
+    column < 0
+  )
+    return new DiffmapDefinitionError({ reason: "Invalid source position." });
+
+  const fileName = path.resolve(workspaceRoot, requestedPath);
+  if (!fileName.startsWith(workspaceRoot + path.sep)) {
+    return new DiffmapDefinitionError({
+      reason: "Path escapes the workspace.",
+    });
+  }
+  if (!/\.[cm]?[jt]sx?$/i.test(fileName)) {
+    return new DiffmapDefinitionError({
+      reason: "Definition navigation supports TypeScript and JavaScript.",
+    });
+  }
+  const contents = readSource(
+    fileName,
+    "This file is no longer in the workspace.",
+  );
+  if (contents instanceof Error) return contents;
+  const lines = contents.split(/\r?\n/);
+  if (lines[line - 1] !== lineText || column >= lineText.length) {
+    return new DiffmapDefinitionError({
+      reason:
+        "This diff line differs from the current workspace. Its definition cannot be resolved.",
+    });
+  }
+  return withProject(workspaceRoot, fileName, (project, source) => {
+    const position = source.getPositionOfLineAndCharacter(line - 1, column);
+    let symbol = project.checker.getSymbolAtPosition(fileName, position);
+    if (symbol === undefined) return undefined;
+    if ((symbol.flags & SymbolFlags.Alias) !== 0) {
+      symbol = project.checker.getAliasedSymbol(symbol);
+    }
+    const handle = symbol.valueDeclaration ?? symbol.declarations[0];
+    const declaration = handle?.resolve();
+    if (declaration === undefined) return undefined;
+    const target = declaration.getSourceFile();
+    const name = declarationName(declaration);
+    const start = name?.getStart(target) ?? declaration.getStart(target);
+    const end = name?.getEnd() ?? declaration.getEnd();
+    return {
+      path: path.relative(workspaceRoot, target.fileName),
+      contents: target.text,
+      start: target.getLineAndCharacterOfPosition(start).line + 1,
+      end: target.getLineAndCharacterOfPosition(end).line + 1,
+    } satisfies SourceDefinition;
+  });
+}
+
+export function readSourceReference(
+  workspaceRoot: string,
+  params: URLSearchParams,
+) {
+  const requestedPath = params.get("path");
+  if (requestedPath === null || requestedPath.length === 0)
+    return new DiffmapDefinitionError({ reason: "Missing file path." });
+  const fileName = path.resolve(workspaceRoot, requestedPath);
+  if (!fileName.startsWith(workspaceRoot + path.sep))
+    return new DiffmapDefinitionError({
+      reason: "Path escapes the workspace.",
+    });
+  const contents = readSource(fileName, `Could not read ${requestedPath}.`);
+  if (contents instanceof Error) return contents;
+  const symbol = params.get("symbol");
+  if (symbol !== null) {
+    if (!/\.[cm]?[jt]sx?$/i.test(fileName))
+      return new DiffmapDefinitionError({
+        reason: "Symbol references support TypeScript and JavaScript.",
+      });
+    return withProject(workspaceRoot, fileName, (project, sourceFile) => {
+      const matches = sourceDeclarations(project, sourceFile, symbol);
+      if (matches.length === 0)
+        return new DiffmapDefinitionError({
+          reason: `Symbol "${symbol}" was not found in ${requestedPath}.`,
+        });
+      if (matches.length > 1)
+        return new DiffmapDefinitionError({
+          reason: `Symbol "${symbol}" is ambiguous. Use a qualified name: ${matches.map((match) => match.name).join(", ")}.`,
+        });
+      const match = matches[0]!;
+      const start = Math.min(
+        ...match.nodes.map((node) => node.getStart(sourceFile)),
+      );
+      const end = Math.max(...match.nodes.map((node) => node.getEnd()));
+      return {
+        path: path.relative(workspaceRoot, fileName),
+        contents,
+        start: sourceFile.getLineAndCharacterOfPosition(start).line + 1,
+        end:
+          sourceFile.getLineAndCharacterOfPosition(Math.max(start, end - 1))
+            .line + 1,
+      } satisfies SourceDefinition;
+    });
+  }
+  const lineCount = contents.split("\n").length;
+  const start = params.has("start") ? Number(params.get("start")) : 1;
+  const end = params.has("end") ? Number(params.get("end")) : lineCount;
+  if (
+    !Number.isSafeInteger(start) ||
+    !Number.isSafeInteger(end) ||
+    start < 1 ||
+    end < start ||
+    end > lineCount
+  )
+    return new DiffmapDefinitionError({
+      reason: `Invalid line range for ${requestedPath}.`,
+    });
+  return {
+    path: path.relative(workspaceRoot, fileName),
+    contents,
+    start,
+    end,
+  } satisfies SourceDefinition;
+}
+
+function readSource(fileName: string, reason: string) {
+  return errore.try({
+    try: () => readFileSync(fileName, "utf8"),
+    catch: (cause) => new DiffmapDefinitionError({ reason, cause }),
+  });
+}
+
+function withProject<T>(
+  workspaceRoot: string,
+  fileName: string,
+  run: (project: Project, source: SourceFile) => T,
+) {
+  return errore.try({
+    try: () => {
+      using resources = new errore.DisposableStack();
+      const api = new API({ cwd: workspaceRoot });
+      resources.defer(() => api.close());
+      const snapshot = api.updateSnapshot({ openFiles: [fileName] });
+      resources.defer(() => snapshot.dispose());
+      const project = snapshot.getDefaultProjectForFile(fileName);
+      const source = project?.program.getSourceFile(fileName);
+      if (project === undefined || source === undefined)
+        return new DiffmapDefinitionError({
+          reason: "TypeScript could not open this source file.",
+        });
+      return run(project, source);
+    },
+    catch: (cause) =>
+      new DiffmapDefinitionError({
+        reason: "TypeScript could not resolve this source file.",
+        cause,
+      }),
+  });
+}
+
+type SourceDeclaration = {
+  name: string;
+  nodes: Node[];
+};
+
+function sourceDeclarations(
+  project: Project,
+  source: SourceFile,
+  requestedName: string,
+): SourceDeclaration[] {
+  const resolved = resolveSourceSymbol(project, source, requestedName);
+  if (resolved.length > 0) return resolved;
+
+  const matches = new Map<string, Node[]>();
+  const visit = (node: Node, parents: string[]) => {
+    const nameNode = isSourceDeclaration(node)
+      ? declarationName(node)
+      : undefined;
+    const name =
+      nameNode === undefined
+        ? undefined
+        : declarationNameText(nameNode, source);
+    const qualifiedName =
+      name === undefined ? undefined : [...parents, name].join(".");
+    if (
+      qualifiedName !== undefined &&
+      (qualifiedName === requestedName ||
+        qualifiedName.endsWith(`.${requestedName}`))
+    ) {
+      const declarations = matches.get(qualifiedName) ?? [];
+      declarations.push(node);
+      matches.set(qualifiedName, declarations);
+    }
+    const childParents =
+      name !== undefined && isDeclarationContainer(node)
+        ? [...parents, name]
+        : parents;
+    node.forEachChild((child) => visit(child, childParents));
+  };
+  source.forEachChild((child) => visit(child, []));
+  return [...matches].map(([name, nodes]) => ({ name, nodes }));
+}
+
+function resolveSourceSymbol(
+  project: Project,
+  source: SourceFile,
+  requestedName: string,
+): SourceDeclaration[] {
+  const [rootName, ...memberNames] = requestedName.split(".");
+  if (rootName === undefined || rootName.length === 0) return [];
+  let symbol = project.checker.resolveName(
+    rootName,
+    SymbolFlags.Value | SymbolFlags.Type | SymbolFlags.Namespace,
+    { document: source.fileName, position: 0 },
+  );
+  for (const memberName of memberNames) {
+    if (symbol === undefined) return [];
+    symbol = symbolMember(symbol, memberName);
+  }
+  if (symbol === undefined) return [];
+  const nodes = symbol.declarations.flatMap((handle) => {
+    const node = handle.resolve();
+    if (node === undefined || node.getSourceFile().fileName !== source.fileName)
+      return [];
+    return [node];
+  });
+  return nodes.length === 0 ? [] : [{ name: requestedName, nodes }];
+}
+
+function symbolMember(symbol: TypeScriptSymbol, name: string) {
+  return (
+    [...symbol.getMembers()].find(([memberName]) => memberName === name)?.[1] ??
+    [...symbol.getExports()].find(([exportName]) => exportName === name)?.[1]
+  );
+}
+
+function declarationName(node: Node): Node | undefined {
+  if (!("name" in node)) return undefined;
+  return (node as Node & { readonly name?: Node }).name;
+}
+
+function declarationNameText(name: Node, source: SourceFile) {
+  if ("text" in name) {
+    const text = (name as Node & { readonly text?: unknown }).text;
+    if (typeof text === "string") return text;
+  }
+  return name.getText(source);
+}
+
+function isSourceDeclaration(node: Node) {
+  return (
+    isClassDeclaration(node) ||
+    isEnumDeclaration(node) ||
+    isEnumMember(node) ||
+    isFunctionDeclaration(node) ||
+    isGetAccessorDeclaration(node) ||
+    isInterfaceDeclaration(node) ||
+    isMethodDeclaration(node) ||
+    isMethodSignatureDeclaration(node) ||
+    isModuleDeclaration(node) ||
+    isPropertyDeclaration(node) ||
+    isPropertySignatureDeclaration(node) ||
+    isSetAccessorDeclaration(node) ||
+    isTypeAliasDeclaration(node) ||
+    isVariableDeclaration(node)
+  );
+}
+
+function isDeclarationContainer(node: Node) {
+  return (
+    isClassDeclaration(node) ||
+    isEnumDeclaration(node) ||
+    isFunctionDeclaration(node) ||
+    isInterfaceDeclaration(node) ||
+    isModuleDeclaration(node)
+  );
+}

package/src/diagramAnnotations.ts

@@ -0,0 +1,34 @@
+import { parseAnnotation, type SourceAnnotation } from "./annotations.js";
+
+export type DiagramAnnotation = {
+  target: "node" | "edge";
+  id: string;
+  annotation: SourceAnnotation;
+};
+
+export function parseDiagramAnnotations(source: string): DiagramAnnotation[] {
+  return source.split("\n").flatMap((line) => {
+    const directive = /^\s*%%\s+ref\s+(node|edge):([^\s]+)\s+(.+)$/.exec(line);
+    if (directive === null) {
+      if (/^\s*%%\s+ref\b/.test(line))
+        return [
+          {
+            target: "node",
+            id: "",
+            annotation: { text: line, references: [] },
+          },
+        ];
+      return [];
+    }
+    const annotation = parseAnnotation(directive[3]!);
+    if (annotation.text.trim().length === 0)
+      annotation.text = `${directive[1]} ${directive[2]}`;
+    return [
+      {
+        target: directive[1] === "node" ? "node" : "edge",
+        id: directive[2]!,
+        annotation,
+      },
+    ];
+  });
+}

package/src/errors.ts

@@ -0,0 +1,41 @@
+import * as errore from "errore";
+
+export class DiffmapServeError extends errore.createTaggedError({
+  name: "DiffmapServeError",
+  message: "diffmap server failed: $reason",
+}) {}
+
+export class DiffmapFileError extends errore.createTaggedError({
+  name: "DiffmapFileError",
+  message: "diffmap could not read $path: $reason",
+}) {}
+
+export class DiffmapRegistryError extends errore.createTaggedError({
+  name: "DiffmapRegistryError",
+  message: "diffmap registry failed: $reason",
+}) {}
+
+export class DiffmapMermaidError extends errore.createTaggedError({
+  name: "DiffmapMermaidError",
+  message: "diffmap could not render mermaid",
+}) {}
+
+export class DiffmapParseError extends errore.createTaggedError({
+  name: "DiffmapParseError",
+  message: "diffmap could not parse markdown",
+}) {}
+
+export class DiffmapAnnotationError extends errore.createTaggedError({
+  name: "DiffmapAnnotationError",
+  message: "diffmap source annotation: $reason",
+}) {}
+
+export class DiffmapDefinitionError extends errore.createTaggedError({
+  name: "DiffmapDefinitionError",
+  message: "$reason",
+}) {}
+
+export class DiffmapShareError extends errore.createTaggedError({
+  name: "DiffmapShareError",
+  message: "diffmap share failed: $reason",
+}) {}

package/src/extractDocument.ts

@@ -0,0 +1,20 @@
+import { parseFence, type Fence } from "./parseFence.js";
+
+const fencePattern = /^```([^\n]*)\r?\n([\s\S]*?)^```/gm;
+const titlePattern = /^#\s+(.+)$/m;
+
+export function extractTitle(source: string) {
+  const match = titlePattern.exec(source);
+  if (match?.[1] === undefined) return "diffmap";
+  return match[1];
+}
+
+export function extractFences(source: string) {
+  const fences: Fence[] = [];
+  for (const match of source.matchAll(fencePattern)) {
+    const lang = match[1] ?? "";
+    const body = match[2] ?? "";
+    fences.push(parseFence(lang.trim(), body));
+  }
+  return fences;
+}

package/src/gist/GistApp.tsx

@@ -0,0 +1,292 @@
+import { useEffect, useState } from "react";
+import { Button, Link, P } from "maui";
+import { style, useStyles } from "purse-styles";
+import { init } from "md4x/standalone";
+import { parseViewerDocument } from "../parseViewer.ts";
+import type { ViewerDocument } from "../parseViewer.ts";
+import { ViewerApp } from "../viewer/ViewerApp.tsx";
+import { loadGistMarkdown, type GistDocument } from "./fetchGist.ts";
+import { GistLanding, GistLoading, GistStatus } from "./GistStatus.tsx";
+import {
+  gistPath,
+  parseGistPath,
+  rewritePiGistUrl,
+  type GistRoute,
+} from "./route.ts";
+
+let parserReady: Promise<void> | undefined;
+
+function readyGistParser() {
+  parserReady ??= init();
+  return parserReady;
+}
+
+type GistView =
+  | { kind: "not-found"; gistId: string }
+  | { kind: "forbidden"; gistId: string }
+  | { kind: "no-markdown"; gistId: string; htmlUrl: string }
+  | {
+      kind: "missing-file";
+      gistId: string;
+      htmlUrl: string;
+      files: { name: string }[];
+      file: string;
+    }
+  | { kind: "error"; gistId: string; message: string }
+  | { kind: "parse-error"; gistId: string; htmlUrl: string; message: string }
+  | {
+      kind: "ready";
+      gist: GistDocument;
+      file: string;
+      document: ViewerDocument;
+    };
+
+export function GistApp() {
+  const [route, setRoute] = useState(readRoute);
+  const gistKey =
+    route.kind === "gist" ? `${route.gistId}:${route.file ?? ""}` : undefined;
+  const [loaded, setLoaded] = useState<{ key: string; view: GistView }>();
+
+  useEffect(() => {
+    const onPop = () => setRoute(readRoute());
+    window.addEventListener("popstate", onPop);
+    return () => window.removeEventListener("popstate", onPop);
+  }, []);
+
+  useEffect(() => {
+    if (route.kind !== "gist") return;
+    const gistId = route.gistId;
+    const file = route.file;
+    const key = `${gistId}:${file ?? ""}`;
+    const abort = new AbortController();
+    // oxlint-disable-next-line typescript/no-floating-promises -- The effect owns this load; abort on cleanup.
+    void loadView(gistId, file, abort.signal).then(
+      (next) => {
+        if (!abort.signal.aborted) setLoaded({ key, view: next });
+      },
+      (cause: unknown) => {
+        if (abort.signal.aborted) return;
+        setLoaded({
+          key,
+          view: {
+            kind: "error",
+            gistId,
+            message:
+              cause instanceof Error
+                ? cause.message
+                : "Failed to load this gist.",
+          },
+        });
+      },
+    );
+    return () => abort.abort();
+  }, [route]);
+
+  if (route.kind === "home") return <GistLanding />;
+  if (route.kind === "invalid") {
+    return (
+      <GistStatus title="Not a gist id">
+        <P>
+          <code>{route.value}</code> is not a 32-character GitHub gist id. Use
+          the path <code>/g/&lt;gistId&gt;</code>.
+        </P>
+      </GistStatus>
+    );
+  }
+
+  if (loaded === undefined || loaded.key !== gistKey) return <GistLoading />;
+  const view = loaded.view;
+  if (view.kind === "not-found") {
+    return (
+      <GistStatus title="Gist not found" gistId={view.gistId}>
+        <P>GitHub has no gist with this id, or it is no longer available.</P>
+      </GistStatus>
+    );
+  }
+  if (view.kind === "forbidden") {
+    return (
+      <GistStatus title="Failed to load" gistId={view.gistId}>
+        <P>
+          GitHub refused this request. Unauthenticated API calls are limited to
+          60 per hour per IP. Wait and refresh, or open the gist on GitHub.
+        </P>
+      </GistStatus>
+    );
+  }
+  if (view.kind === "no-markdown") {
+    return (
+      <GistStatus title="No markdown" gistUrl={view.htmlUrl}>
+        <P>
+          This gist has no <code>.md</code> or <code>.mdx</code> file.
+        </P>
+      </GistStatus>
+    );
+  }
+  if (view.kind === "missing-file") {
+    return (
+      <GistStatus title="File not found" gistUrl={view.htmlUrl}>
+        <P>
+          <code>{view.file}</code> is not a markdown file in this gist.
+        </P>
+        <FileLinks gistId={view.gistId} files={view.files} />
+      </GistStatus>
+    );
+  }
+  if (view.kind === "error") {
+    return (
+      <GistStatus title="Failed to load" gistId={view.gistId}>
+        <P>{view.message}</P>
+      </GistStatus>
+    );
+  }
+  if (view.kind === "parse-error") {
+    return (
+      <GistStatus
+        title="Could not parse this walkthrough"
+        gistUrl={view.htmlUrl}
+      >
+        <P>{view.message}</P>
+      </GistStatus>
+    );
+  }
+
+  return (
+    <ViewerApp
+      key={`${view.gist.id}:${view.file}`}
+      document={view.document}
+      mode="gist"
+      headerActions={
+        <GistHeader
+          gistId={view.gist.id}
+          htmlUrl={view.gist.htmlUrl}
+          files={view.gist.files}
+          current={view.file}
+          onSelect={(file) => {
+            const next = gistPath(view.gist.id, file);
+            window.history.pushState({}, "", next);
+            setRoute(parseGistPath(next));
+          }}
+        />
+      }
+    />
+  );
+}
+
+async function loadView(
+  gistId: string,
+  file: string | undefined,
+  signal: AbortSignal,
+): Promise<GistView> {
+  await readyGistParser();
+  const loaded = await loadGistMarkdown(gistId, file, signal);
+  if (loaded.status === "not-found") return { kind: "not-found", gistId };
+  if (loaded.status === "forbidden") return { kind: "forbidden", gistId };
+  if (loaded.status === "error") {
+    return { kind: "error", gistId, message: loaded.message };
+  }
+  if (loaded.status === "no-markdown") {
+    return { kind: "no-markdown", gistId, htmlUrl: loaded.htmlUrl };
+  }
+  if (loaded.status === "missing-file") {
+    return {
+      kind: "missing-file",
+      gistId,
+      htmlUrl: loaded.htmlUrl,
+      files: loaded.files,
+      file: file ?? "",
+    };
+  }
+  const parsed = parseViewerDocument(loaded.gist.chosen.content);
+  if (parsed instanceof Error) {
+    return {
+      kind: "parse-error",
+      gistId,
+      htmlUrl: loaded.gist.htmlUrl,
+      message: parsed.message,
+    };
+  }
+  return {
+    kind: "ready",
+    gist: loaded.gist,
+    file: loaded.gist.chosen.name,
+    document: parsed,
+  };
+}
+
+function readRoute(): GistRoute {
+  const rewritten = rewritePiGistUrl(
+    window.location.pathname,
+    window.location.hash,
+  );
+  if (rewritten !== undefined) return parseGistPath(rewritten);
+  const parsed = parseGistPath(window.location.pathname);
+  if (parsed.kind === "empty") return { kind: "home" };
+  return parsed;
+}
+
+function GistHeader(props: {
+  gistId: string;
+  htmlUrl: string;
+  files: { name: string }[];
+  current: string;
+  onSelect: (file: string) => void;
+}) {
+  return (
+    <>
+      {props.files.length > 1 && (
+        <FileLinks
+          gistId={props.gistId}
+          files={props.files}
+          current={props.current}
+          onSelect={props.onSelect}
+        />
+      )}
+      <Link href={props.htmlUrl}>Gist</Link>
+    </>
+  );
+}
+
+function FileLinks(props: {
+  gistId: string;
+  files: { name: string }[];
+  current?: string;
+  onSelect?: (file: string) => void;
+}) {
+  const group = useStyles(fileStyles.group);
+  return (
+    <div className={group} aria-label="Markdown files">
+      {props.files.map((file) => {
+        const href = gistPath(props.gistId, file.name);
+        const current = file.name === props.current;
+        const select = props.onSelect;
+        if (select === undefined) {
+          return (
+            <Link key={file.name} href={href}>
+              {file.name}
+            </Link>
+          );
+        }
+        return (
+          <Button
+            key={file.name}
+            variant={current ? "primary" : "quiet"}
+            onClick={() => {
+              select(file.name);
+            }}
+          >
+            {file.name}
+          </Button>
+        );
+      })}
+    </div>
+  );
+}
+
+const fileStyles = {
+  group: style({
+    display: "flex",
+    flexWrap: "wrap",
+    gap: "6px",
+    alignItems: "center",
+  }),
+};