@mcuste/pi-diagram 0.0.0

package/src/raster.ts

@@ -0,0 +1,258 @@
+import { mkdtemp, readFile, rm, writeFile } from "node:fs/promises";
+import { createRequire } from "node:module";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { cacheKeyOf, FileCache, type RenderCache } from "./cache.js";
+import {
+  type EmbeddedFont,
+  missingCodePoints,
+  parseEmbeddedFonts,
+  textCodePoints,
+} from "./d2/fonts.js";
+import type { RenderedSvg } from "./d2/runner.js";
+import { CommandCancelledError } from "./process.js";
+
+/**
+ * Draws a D2 SVG as a PNG. D2's own PNG export drives a headless browser it downloads on first
+ * use; resvg needs no browser and no network.
+ */
+
+/** Twice the natural size keeps labels readable once the terminal scales the image to cells. */
+const SCALE = 2;
+const MIN_WIDTH_PX = 480;
+const MAX_WIDTH_PX = 1600;
+const MAX_HEIGHT_PX = 2400;
+const MAX_PNG_BYTES = 4 * 1024 * 1024;
+const DEFAULT_FONT_FAMILY = "Source Sans Pro";
+
+/** Everything besides the SVG and resvg itself that decides the picture. */
+const IMAGE_POLICY = [
+  "png",
+  String(SCALE),
+  String(MIN_WIDTH_PX),
+  String(MAX_WIDTH_PX),
+  String(MAX_HEIGHT_PX),
+  DEFAULT_FONT_FAMILY,
+];
+
+const PNG_SIGNATURE = Buffer.from([0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a]);
+
+declare const renderedPngBrand: unique symbol;
+
+/** Bytes that passed `parseRenderedPng`, so they really are a PNG of a known size. */
+type RenderedPng = Uint8Array & { readonly [renderedPngBrand]: true };
+
+export interface RasterRequest {
+  readonly svg: RenderedSvg;
+  readonly signal: AbortSignal | undefined;
+}
+
+export interface RasterImage {
+  readonly png: RenderedPng;
+  readonly widthPx: number;
+  readonly heightPx: number;
+  /** True when the diagram's own font could not draw every label, so system fonts were added. */
+  readonly systemFonts: boolean;
+}
+
+export interface SvgRasterizer {
+  rasterize(request: RasterRequest): Promise<RasterImage>;
+}
+
+/** The diagram is fine and only the image failed, so the caller shows text rather than failing. */
+export class ImageRenderUnavailableError extends Error {
+  constructor(message: string, options?: ErrorOptions) {
+    super(message, options);
+    this.name = "ImageRenderUnavailableError";
+  }
+}
+
+/** resvg reporting success is not proof the bytes are a usable PNG of the size asked for. */
+export function parseRenderedPng(bytes: Uint8Array, expectedWidthPx: number): RasterImage {
+  if (bytes.length > MAX_PNG_BYTES) {
+    throw new ImageRenderUnavailableError(
+      `The image is ${bytes.length} bytes, past the ${MAX_PNG_BYTES} byte limit.`,
+    );
+  }
+  const buffer = Buffer.from(bytes.buffer, bytes.byteOffset, bytes.byteLength);
+  if (buffer.length < 24 || !buffer.subarray(0, 8).equals(PNG_SIGNATURE)) {
+    throw new ImageRenderUnavailableError("The renderer did not return a PNG.");
+  }
+  if (buffer.toString("ascii", 12, 16) !== "IHDR") {
+    throw new ImageRenderUnavailableError("The PNG does not start with an image header.");
+  }
+  if (buffer.toString("ascii", buffer.length - 8, buffer.length - 4) !== "IEND") {
+    throw new ImageRenderUnavailableError("The PNG is truncated.");
+  }
+
+  const widthPx = buffer.readUInt32BE(16);
+  const heightPx = buffer.readUInt32BE(20);
+  if (widthPx === 0 || heightPx === 0) {
+    throw new ImageRenderUnavailableError("The PNG has no area.");
+  }
+  // A silently ignored size option would otherwise reach the terminal as an unreadable image.
+  if (Math.abs(widthPx - expectedWidthPx) > 1) {
+    throw new ImageRenderUnavailableError(
+      `The PNG is ${widthPx} pixels wide, not the ${expectedWidthPx} that were asked for.`,
+    );
+  }
+  return { png: bytes as RenderedPng, widthPx, heightPx, systemFonts: false };
+}
+
+/** Enough resolution to scale down cleanly, never a pathological canvas. */
+export function parseTargetWidth(naturalWidthPx: number, naturalHeightPx: number): number {
+  if (
+    !Number.isFinite(naturalWidthPx) ||
+    !Number.isFinite(naturalHeightPx) ||
+    naturalWidthPx < 1 ||
+    naturalHeightPx < 1
+  ) {
+    throw new ImageRenderUnavailableError(
+      `The SVG reports a ${naturalWidthPx} by ${naturalHeightPx} canvas.`,
+    );
+  }
+
+  // The limits come last, so a tall diagram is drawn smaller rather than past the canvas bound.
+  const byHeight = (MAX_HEIGHT_PX / naturalHeightPx) * naturalWidthPx;
+  const wanted = Math.max(naturalWidthPx * SCALE, MIN_WIDTH_PX);
+  return Math.max(1, Math.round(Math.min(wanted, MAX_WIDTH_PX, byHeight)));
+}
+
+/** The store holds text, so an image travels as base64 behind the sizes it was drawn at. */
+function formatCachedImage(image: RasterImage): string {
+  const drawn = `${image.widthPx} ${image.heightPx} ${image.systemFonts ? 1 : 0}`;
+  return `${drawn}\n${Buffer.from(image.png).toString("base64")}`;
+}
+
+/** Parsed again on the way out, so a corrupt entry is drawn again rather than displayed. */
+export function parseCachedImage(entry: string): RasterImage {
+  const split = entry.indexOf("\n");
+  const [width, height, fonts] = entry.slice(0, Math.max(split, 0)).split(" ");
+  const widthPx = Number(width);
+  const heightPx = Number(height);
+  const sized =
+    Number.isSafeInteger(widthPx) && widthPx > 0 && Number.isSafeInteger(heightPx) && heightPx > 0;
+  if (split === -1 || !sized || (fonts !== "0" && fonts !== "1")) {
+    throw new ImageRenderUnavailableError("The stored image does not say how it was drawn.");
+  }
+
+  const image = parseRenderedPng(Buffer.from(entry.slice(split + 1), "base64"), widthPx);
+  if (image.heightPx !== heightPx) {
+    throw new ImageRenderUnavailableError(
+      `The stored image is ${image.heightPx} pixels tall, not the ${heightPx} it was drawn at.`,
+    );
+  }
+  return { ...image, systemFonts: fonts === "1" };
+}
+
+type ResvgModule = typeof import("@resvg/resvg-js");
+
+let loaded: Promise<ResvgModule> | undefined;
+let installed: Promise<string | undefined> | undefined;
+
+/** A native binary per platform, loaded lazily so an unsupported one cannot break text diagrams. */
+async function load(): Promise<ResvgModule> {
+  loaded ??= import("@resvg/resvg-js");
+  try {
+    return await loaded;
+  } catch (error) {
+    loaded = undefined;
+    throw new ImageRenderUnavailableError(
+      `The SVG rasterizer could not be loaded: ${(error as Error).message}`,
+      { cause: error },
+    );
+  }
+}
+
+export class ResvgRasterizer implements SvgRasterizer {
+  private readonly cache: RenderCache;
+
+  constructor(dependencies: { readonly cache?: RenderCache } = {}) {
+    this.cache = dependencies.cache ?? new FileCache();
+  }
+
+  async rasterize(request: RasterRequest): Promise<RasterImage> {
+    if (request.signal?.aborted === true) {
+      throw new CommandCancelledError("Drawing the diagram");
+    }
+
+    const key = await imageKey(request.svg);
+    const stored = key === undefined ? undefined : await this.cache.read(key);
+    if (stored !== undefined) {
+      try {
+        return parseCachedImage(stored);
+      } catch {
+        // An entry this build cannot read is no better than a missing one.
+      }
+    }
+
+    const image = await draw(request.svg);
+    if (key !== undefined) {
+      await this.cache.write(key, formatCachedImage(image));
+    }
+    return image;
+  }
+}
+
+/** Undefined when the version is unknown, which keeps that image out of the store. */
+async function imageKey(svg: RenderedSvg): Promise<string | undefined> {
+  const version = await resvgVersion();
+  return version === undefined ? undefined : cacheKeyOf([...IMAGE_POLICY, version, svg]);
+}
+
+/** resvg draws differently between versions, so a stored image belongs to the one that drew it. */
+async function resvgVersion(): Promise<string | undefined> {
+  installed ??= (async (): Promise<string | undefined> => {
+    try {
+      const manifest = createRequire(import.meta.url).resolve("@resvg/resvg-js/package.json");
+      const parsed: unknown = JSON.parse(await readFile(manifest, "utf8"));
+      const found = (parsed as { version?: unknown }).version;
+      return typeof found === "string" ? found : undefined;
+    } catch {
+      return undefined;
+    }
+  })();
+  return installed;
+}
+
+async function draw(svg: RenderedSvg): Promise<RasterImage> {
+  const { Resvg } = await load();
+  const fonts = parseEmbeddedFonts(svg);
+  const missing = missingCodePoints(fonts, textCodePoints(svg));
+  const directory = await mkdtemp(join(tmpdir(), "pi-diagram-fonts-"));
+  try {
+    const fontFiles = await writeFonts(directory, fonts);
+    const font = {
+      fontFiles,
+      // Labels the diagram's own font cannot draw would otherwise be empty boxes.
+      loadSystemFonts: missing.length > 0,
+      defaultFontFamily: DEFAULT_FONT_FAMILY,
+    };
+
+    const probe = new Resvg(svg, { font });
+    const widthPx = parseTargetWidth(probe.width, probe.height);
+    const drawn = new Resvg(svg, { font, fitTo: { mode: "width", value: widthPx } });
+    const image = parseRenderedPng(drawn.render().asPng(), widthPx);
+    return { ...image, systemFonts: missing.length > 0 };
+  } catch (error) {
+    if (error instanceof ImageRenderUnavailableError || error instanceof CommandCancelledError) {
+      throw error;
+    }
+    throw new ImageRenderUnavailableError(
+      `The SVG could not be drawn as an image: ${(error as Error).message}`,
+      { cause: error },
+    );
+  } finally {
+    await rm(directory, { recursive: true, force: true });
+  }
+}
+
+async function writeFonts(directory: string, fonts: readonly EmbeddedFont[]): Promise<string[]> {
+  const paths: string[] = [];
+  for (const [index, font] of fonts.entries()) {
+    const path = join(directory, `face-${index}.ttf`);
+    await writeFile(path, font.bytes, { mode: 0o600 });
+    paths.push(path);
+  }
+  return paths;
+}

package/src/render.ts

@@ -0,0 +1,338 @@
+import {
+  type ArtifactFormat,
+  parseArtifactNames,
+  parseArtifactTarget,
+  type WrittenArtifact,
+  writeArtifacts,
+} from "./artifacts.js";
+import { type Diagnostic, DiagramSourceError } from "./d2/diagnostics.js";
+import { parseSafeSource, type SafeD2Source } from "./d2/preflight.js";
+import { type ProfileName, parseProfile } from "./d2/profiles.js";
+import {
+  type AsciiMode,
+  type D2Renderer,
+  type SupportedD2Version,
+  TextRenderUnavailableError,
+} from "./d2/runner.js";
+import { normalizeSource, parseTitle, type SafeTitle } from "./normalize.js";
+import {
+  ImageRenderUnavailableError,
+  type RasterImage,
+  ResvgRasterizer,
+  type SvgRasterizer,
+} from "./raster.js";
+
+/**
+ * D2's text renderer is beta, so a diagram it cannot draw has to fail in a way the user can
+ * understand rather than turning into broken box art or a different graph.
+ */
+
+/** How the diagram is drawn as text. */
+export type Representation = "unicode" | "ascii" | "source";
+
+/** Bounds for one transcript diagram. */
+const MAX_LINES = 300;
+const MAX_COLUMNS = 400;
+const MAX_BYTES = 32 * 1024;
+
+export interface DiagramRequest {
+  readonly source: unknown;
+  readonly title?: unknown;
+  readonly profile?: unknown;
+  readonly render?: unknown;
+  readonly formats?: unknown;
+  readonly save?: unknown;
+  readonly cwd?: unknown;
+  /** Whether the host can display an image at all. Only `true` enables the raster path. */
+  readonly images?: unknown;
+  readonly signal?: AbortSignal | undefined;
+}
+
+interface DiagramImage {
+  /** Absolute path in the temp store. */
+  readonly path: string;
+  readonly widthPx: number;
+  readonly heightPx: number;
+}
+
+export interface DiagramRendering {
+  readonly profile: ProfileName;
+  readonly renderedAs: Representation;
+  readonly text: string;
+  /** The D2 source that was drawn, for the expanded view. */
+  readonly source: string;
+  /** Why the text came out the way it did. Empty when nothing went wrong. */
+  readonly diagnostics: readonly Diagnostic[];
+  readonly image: DiagramImage | undefined;
+  readonly title: SafeTitle | undefined;
+  readonly sourceHash: string;
+  readonly lineCount: number;
+  readonly widthCells: number;
+  readonly d2Version: SupportedD2Version | undefined;
+  readonly saved: readonly WrittenArtifact[];
+  readonly notes: readonly string[];
+}
+
+/**
+ * `image` and `auto` choose the text that goes with the image. Whether a terminal can show one is
+ * only decided when the result is displayed, so both are always prepared.
+ */
+export function parseRepresentation(requested: unknown): Representation {
+  switch (requested) {
+    case undefined:
+    case "auto":
+    case "image":
+    case "unicode":
+      return "unicode";
+    case "ascii":
+      return "ascii";
+    case "source":
+      return "source";
+    default:
+      throw new DiagramSourceError("Unsupported render mode.", [
+        {
+          code: "D2_SOURCE",
+          message: `${JSON.stringify(requested)} is not a render mode.`,
+          hint: "Use auto, image, unicode, ascii, or source.",
+        },
+      ]);
+  }
+}
+
+/** Asking for a text representation suppresses the image, rather than producing both. */
+function wantsImage(request: DiagramRequest): boolean {
+  if (request.images !== true) {
+    return false;
+  }
+  return request.render === undefined || request.render === "auto" || request.render === "image";
+}
+
+export async function renderDiagram(
+  request: DiagramRequest,
+  renderer: D2Renderer,
+  rasterizer: SvgRasterizer = new ResvgRasterizer(),
+): Promise<DiagramRendering> {
+  const normalized = normalizeSource(request.source);
+  const source = parseSafeSource(normalized.text);
+  const representation = parseRepresentation(request.render);
+  const profile = parseProfile(request.profile);
+  const title = parseTitle(request.title);
+  // Everything the request asks for is parsed before D2 starts, so a bad save path costs nothing.
+  const wantsFiles = request.save !== undefined || request.formats !== undefined;
+  const names = wantsFiles
+    ? parseArtifactNames(
+        { formats: request.formats, save: request.save },
+        { title, hash: normalized.hash },
+      )
+    : undefined;
+  const target = names === undefined ? undefined : await parseArtifactTarget(request.cwd, names);
+
+  const notes: string[] = [];
+  const showsImage = wantsImage(request);
+  const savesPng = names?.formats.includes("png") === true;
+  const wantsText = representation !== "source" || names?.formats.includes("txt") === true;
+  let mode: AsciiMode = representation === "ascii" ? "standard" : "extended";
+  let drawn = wantsText ? await tryRender(renderer, source, mode, request.signal) : undefined;
+
+  if (drawn instanceof TextRenderUnavailableError && mode === "extended") {
+    // Exactly one fallback attempt, so a beta renderer cannot be retried indefinitely.
+    const retry = await tryRender(renderer, source, "standard", request.signal);
+    if (!(retry instanceof TextRenderUnavailableError)) {
+      notes.push("Unicode output failed, so this diagram is drawn in plain ASCII.");
+      mode = "standard";
+      drawn = retry;
+    }
+  }
+
+  const textFailure = drawn instanceof TextRenderUnavailableError ? drawn : undefined;
+  const text = drawn instanceof TextRenderUnavailableError ? undefined : drawn?.text;
+
+  const svg =
+    names?.formats.includes("svg") === true || showsImage || savesPng
+      ? await renderer.renderSvg({ source, profile, signal: request.signal })
+      : undefined;
+
+  let raster: RasterImage | undefined;
+  if (svg !== undefined && (showsImage || savesPng)) {
+    raster = await tryRasterize(rasterizer, svg.svg, request.signal, notes);
+  }
+
+  let saved: readonly WrittenArtifact[] = [];
+  if (target !== undefined && names !== undefined) {
+    // Every text artifact ends with a newline, the way any other checked-in text file does.
+    const contents = new Map<ArtifactFormat, string | Uint8Array>([
+      ["source", await sourceToSave(renderer, source, request.signal)],
+    ]);
+    if (svg !== undefined) {
+      contents.set("svg", `${svg.svg}\n`);
+    }
+    if (raster !== undefined) {
+      contents.set("png", raster.png);
+    } else if (savesPng) {
+      notes.push("No .png was written, because the diagram could not be drawn as an image.");
+    }
+    if (text !== undefined) {
+      contents.set("txt", `${text}\n`);
+    } else if (names.formats.includes("txt")) {
+      notes.push("No .txt was written, because D2 could not draw this diagram as text.");
+    }
+    saved = await writeArtifacts(target, contents);
+  }
+
+  const image =
+    raster === undefined || !showsImage
+      ? undefined
+      : await keepImage(raster, title, normalized.hash, notes);
+
+  // Work that came out fine is not discarded because the text renderer choked.
+  if (textFailure !== undefined && representation !== "source") {
+    if (saved.length === 0 && image === undefined) {
+      throw explain(textFailure);
+    }
+    notes.push("The diagram is shown as source, because D2 could not draw it as text.");
+    return {
+      title,
+      profile: profile.name,
+      sourceHash: normalized.hash,
+      ...measure(source, MAX_COLUMNS),
+      renderedAs: "source",
+      text: source,
+      source,
+      diagnostics: textFailure.diagnostics,
+      image,
+      d2Version: svg?.version,
+      saved,
+      notes,
+    };
+  }
+
+  // Text may have been drawn only to write a .txt sidecar, which must not override the
+  // representation the caller asked for.
+  const showSource = representation === "source" || text === undefined;
+  return {
+    title,
+    profile: profile.name,
+    sourceHash: normalized.hash,
+    ...measure(showSource ? source : (text as string), MAX_COLUMNS),
+    renderedAs: showSource ? "source" : mode === "standard" ? "ascii" : "unicode",
+    text: showSource ? source : (text as string),
+    source,
+    diagnostics: [],
+    image,
+    d2Version:
+      drawn instanceof TextRenderUnavailableError ? svg?.version : (drawn?.version ?? svg?.version),
+    saved,
+    notes,
+  };
+}
+
+/** A checked-in `.d2` is read and edited by people later, so it is saved formatted. */
+async function sourceToSave(
+  renderer: D2Renderer,
+  source: SafeD2Source,
+  signal: AbortSignal | undefined,
+): Promise<string> {
+  try {
+    const formatted = await renderer.formatSource({ source, signal });
+    // Parsed again, because nothing reaches the workspace without passing the safe subset.
+    return `${parseSafeSource(normalizeSource(formatted).text)}\n`;
+  } catch {
+    // Formatting is cosmetic, so what the model wrote is saved as it is.
+    return `${source}\n`;
+  }
+}
+
+/** An image that cannot be drawn is a display fallback, not a failure the model should correct. */
+async function tryRasterize(
+  rasterizer: SvgRasterizer,
+  svg: Parameters<SvgRasterizer["rasterize"]>[0]["svg"],
+  signal: AbortSignal | undefined,
+  notes: string[],
+): Promise<RasterImage | undefined> {
+  try {
+    const raster = await rasterizer.rasterize({ svg, signal });
+    if (raster.systemFonts) {
+      notes.push(
+        "Some labels use characters the diagram's own font does not carry, so the image was " +
+          "drawn with the fonts installed on this machine.",
+      );
+    }
+    return raster;
+  } catch (error) {
+    if (!(error instanceof ImageRenderUnavailableError)) {
+      throw error;
+    }
+    notes.push(`${error.message} The diagram is shown as text instead.`);
+    return undefined;
+  }
+}
+
+/** The temp store keeps the bytes out of the model's context and out of the repository. */
+async function keepImage(
+  raster: RasterImage,
+  title: SafeTitle | undefined,
+  hash: string,
+  notes: string[],
+): Promise<DiagramImage | undefined> {
+  try {
+    const names = parseArtifactNames({ formats: ["png"] }, { title, hash });
+    const target = await parseArtifactTarget(undefined, names);
+    const [written] = await writeArtifacts(target, new Map([["png", raster.png]]));
+    if (written === undefined) {
+      return undefined;
+    }
+    return { path: written.path, widthPx: raster.widthPx, heightPx: raster.heightPx };
+  } catch (error) {
+    notes.push(`The image could not be stored: ${(error as Error).message}`);
+    return undefined;
+  }
+}
+
+/**
+ * Returns a text-renderer failure as a value so the caller can decide whether to retry.
+ * Everything else, including source errors and cancellation, still throws.
+ */
+async function tryRender(
+  renderer: D2Renderer,
+  source: SafeD2Source,
+  asciiMode: AsciiMode,
+  signal: AbortSignal | undefined,
+): Promise<Awaited<ReturnType<D2Renderer["renderText"]>> | TextRenderUnavailableError> {
+  try {
+    return await renderer.renderText({ source, asciiMode, signal });
+  } catch (error) {
+    if (error instanceof TextRenderUnavailableError) {
+      return error;
+    }
+    throw error;
+  }
+}
+
+function explain(failure: TextRenderUnavailableError): TextRenderUnavailableError {
+  return new TextRenderUnavailableError(
+    `${failure.message} D2's text renderer is beta and cannot draw every diagram. ` +
+      'Try a simpler diagram, or ask for `render: "source"` to see the D2 source instead.',
+    failure.diagnostics,
+  );
+}
+
+/** Throws if the drawing is too big to belong in a transcript. */
+function measure(text: string, maxColumns: number): { lineCount: number; widthCells: number } {
+  const lines = text.split("\n");
+  let widthCells = 0;
+  for (const line of lines) {
+    widthCells = Math.max(widthCells, Array.from(line).length);
+  }
+
+  const bytes = Buffer.byteLength(text, "utf8");
+  if (lines.length > MAX_LINES || widthCells > maxColumns || bytes > MAX_BYTES) {
+    throw new DiagramSourceError("The rendered diagram is too big for the transcript.", [
+      {
+        code: "D2_TOO_LARGE",
+        message: `It is ${lines.length} lines by ${widthCells} columns (${bytes} bytes); the limit is ${MAX_LINES} by ${maxColumns} (${MAX_BYTES} bytes).`,
+        hint: "Show fewer nodes, shorten labels, or split it into several diagrams.",
+      },
+    ]);
+  }
+  return { lineCount: lines.length, widthCells };
+}