@coldtea/pr-lens-renderer 0.1.0

package/src/render.ts

@@ -0,0 +1,190 @@
+import type { Config, GraphDoc, Lens, RenderAsset, RenderManifest, View, ViewScope } from "@coldtea/pr-lens-schema";
+import { assertNever, MAX_RENDER_ASSETS } from "@coldtea/pr-lens-schema";
+import { applyCorrections } from "./corrections.js";
+import { PrLensRenderError } from "./errors.js";
+import { buildManifest, contentHash, renderAssetFileName, renderAssetId } from "./manifest.js";
+import { findView, flattenViews, resolveScope, type ScopedGraph } from "./scope.js";
+import { paletteFor, THEMES, type Theme } from "./theme.js";
+import { paintArchitecture } from "./svg/architecture.js";
+import { paintDataFlow } from "./svg/dataflow.js";
+import { svgDocument } from "./svg/document.js";
+
+export type RenderOptions = {
+  lens: Lens;
+  theme: Theme;
+  /** Id of the drill-down section to draw. Omitted renders the whole document. */
+  view?: string;
+  /** The repository's corrections, applied as an overlay before layout. */
+  config?: Config;
+};
+
+export type RenderedSvg = {
+  svg: string;
+  width: number;
+  height: number;
+  lens: Lens;
+  theme: Theme;
+  view: string | undefined;
+  animated: boolean;
+};
+
+const WHOLE_DOCUMENT: ViewScope = { kind: "all" };
+
+const prepare = (doc: GraphDoc, config: Config | undefined): GraphDoc =>
+  config === undefined ? doc : applyCorrections(doc, config.map);
+
+const paint = (
+  lens: Lens,
+  graph: ScopedGraph,
+  doc: GraphDoc,
+  theme: Theme,
+): { width: number; height: number; body: string; animated: boolean } => {
+  const palette = paletteFor(theme);
+
+  switch (lens) {
+    case "architecture": {
+      if (graph.nodes.length === 0)
+        throw new PrLensRenderError("NOTHING_TO_RENDER", "no nodes are in scope for this view");
+      const painting = paintArchitecture(graph, doc.layout, palette);
+      return { ...painting, animated: graph.edges.some((edge) => edge.animated) };
+    }
+    case "data-flow": {
+      if (graph.flows.length === 0)
+        throw new PrLensRenderError("NO_FLOW_IN_SCOPE", "the data-flow lens needs a flow to draw");
+      const painting = paintDataFlow(graph.flows, doc.nodes, palette);
+      return {
+        ...painting,
+        animated: graph.flows.some((flow) => flow.messages.some((message) => message.animated)),
+      };
+    }
+    default:
+      return assertNever(lens, "Unhandled lens");
+  }
+};
+
+/**
+ * A schema-valid document in, one self-contained SVG out.
+ *
+ * Nothing here reads a clock, a file or a random number: the same document
+ * and options produce the same bytes, on any machine, in any order. That is
+ * what lets a render be addressed by its own hash, and what keeps a diagram
+ * from rearranging itself between two pushes that barely changed anything.
+ */
+export const render = (doc: GraphDoc, options: RenderOptions): RenderedSvg => {
+  const prepared = prepare(doc, options.config);
+
+  if (!prepared.lenses.includes(options.lens))
+    throw new PrLensRenderError(
+      "LENS_NOT_DECLARED",
+      `this document does not declare the '${options.lens}' lens`,
+    );
+
+  const view =
+    options.view === undefined ? undefined : requireView(prepared.views, options.view);
+  const scope = view?.scope ?? WHOLE_DOCUMENT;
+  const graph = resolveScope(prepared, scope);
+
+  const { width, height, body, animated } = paint(options.lens, graph, prepared, options.theme);
+
+  const svg = svgDocument({
+    width,
+    height,
+    palette: paletteFor(options.theme),
+    title: view?.title ?? prepared.title,
+    description: view?.summary ?? prepared.summary,
+    body,
+  });
+
+  return { svg, width, height, lens: options.lens, theme: options.theme, view: view?.id, animated };
+};
+
+const requireView = (views: readonly View[], id: string): View => {
+  const view = findView(views, id);
+  if (view === undefined)
+    throw new PrLensRenderError("UNKNOWN_VIEW", `this document has no view '${id}'`);
+  return view;
+};
+
+export type RenderAllOptions = {
+  config?: Config;
+  /** Which halves of the theme pair to produce. Both, by default. */
+  themes?: readonly Theme[];
+};
+
+export type RenderedAsset = RenderedSvg & { asset: RenderAsset };
+
+export type RenderAllResult = {
+  assets: RenderedAsset[];
+  manifest: RenderManifest;
+};
+
+/**
+ * Every drill-down section a comment will show, in both themes.
+ *
+ * A document with no sections still renders: it gets one diagram per lens it
+ * declares, which is what a comment falls back to when extraction found
+ * nothing worth splitting into a tree.
+ */
+export const renderAll = (doc: GraphDoc, options: RenderAllOptions = {}): RenderAllResult => {
+  const prepared = prepare(doc, options.config);
+  const themes = options.themes ?? THEMES;
+
+  const targets: { lens: Lens; view: View | undefined }[] =
+    prepared.views.length > 0
+      ? flattenViews(prepared.views)
+          .filter((view) => prepared.lenses.includes(view.lens))
+          .map((view) => ({ lens: view.lens, view }))
+      : prepared.lenses
+          .filter((lens) => lens !== "data-flow" || prepared.flows.length > 0)
+          .map((lens) => ({ lens, view: undefined }));
+
+  /**
+   * The contract caps a view tree at the number of views a two-theme render
+   * fits inside a manifest, so a parsed document cannot reach this. A
+   * hand-built one can: the cap lives in a refinement, and a refinement does
+   * not survive into the inferred type. This is a postcondition on what is
+   * about to be produced rather than a re-reading of what came in — the count
+   * depends on how many themes the caller asked for, which no document knows.
+   */
+  if (targets.length * themes.length > MAX_RENDER_ASSETS)
+    throw new PrLensRenderError(
+      "TOO_MANY_ASSETS",
+      `this document asks for ${targets.length * themes.length} pictures across ${targets.length} views ` +
+        `and ${themes.length} themes, and a render manifest carries at most ${MAX_RENDER_ASSETS}`,
+    );
+
+  const assets: RenderedAsset[] = [];
+
+  for (const target of targets)
+    for (const theme of themes) {
+      const rendered = render(prepared, {
+        lens: target.lens,
+        theme,
+        view: target.view?.id,
+      });
+      const address = { lens: target.lens, theme, view: target.view?.id };
+      const hash = contentHash(rendered.svg);
+
+      assets.push({
+        ...rendered,
+        asset: {
+          id: renderAssetId(address),
+          lens: target.lens,
+          theme,
+          view: target.view?.id,
+          mediaType: "image/svg+xml",
+          contentHash: hash,
+          bytes: Buffer.byteLength(rendered.svg, "utf8"),
+          width: rendered.width,
+          height: rendered.height,
+          animated: rendered.animated,
+          path: renderAssetFileName(address, hash),
+        },
+      });
+    }
+
+  if (assets.length === 0)
+    throw new PrLensRenderError("NOTHING_TO_RENDER", "this document declares no renderable view");
+
+  return { assets, manifest: buildManifest(prepared, assets.map(({ asset }) => asset)) };
+};

package/src/scope.ts

@@ -0,0 +1,67 @@
+import type { Flow, GraphDoc, GraphEdge, GraphNode, Lane, View, ViewScope } from "@coldtea/pr-lens-schema";
+import { assertNever } from "@coldtea/pr-lens-schema";
+
+/** The slice of a document one SVG draws. */
+export type ScopedGraph = {
+  lanes: Lane[];
+  nodes: GraphNode[];
+  edges: GraphEdge[];
+  flows: Flow[];
+};
+
+export const findView = (views: readonly View[], id: string): View | undefined => {
+  for (const view of views) {
+    if (view.id === id) return view;
+    const nested = findView(view.children, id);
+    if (nested) return nested;
+  }
+  return undefined;
+};
+
+export const flattenViews = (views: readonly View[]): View[] =>
+  views.flatMap((view) => [view, ...flattenViews(view.children)]);
+
+/**
+ * Turns a view's scope into the elements to draw.
+ *
+ * A selection pulls in what its members need to make sense: the lanes its
+ * nodes sit in, and both ends of every edge it names, since half an arrow is
+ * worse than none. Edges are the one place the author keeps full control —
+ * name any and exactly those are drawn, name none and the connections between
+ * the selected nodes come along.
+ */
+export const resolveScope = (doc: GraphDoc, scope: ViewScope): ScopedGraph => {
+  switch (scope.kind) {
+    case "all":
+      return { lanes: [...doc.lanes], nodes: [...doc.nodes], edges: [...doc.edges], flows: [...doc.flows] };
+    case "selection": {
+      const selectedLanes = new Set(scope.lanes);
+      const selectedEdges = new Set(scope.edges);
+      const selectedFlows = new Set(scope.flows);
+      const flows = doc.flows.filter((flow) => selectedFlows.has(flow.id));
+
+      const nodeIds = new Set<string>(scope.nodes);
+      for (const node of doc.nodes) if (selectedLanes.has(node.lane)) nodeIds.add(node.id);
+      for (const edge of doc.edges) {
+        if (!selectedEdges.has(edge.id)) continue;
+        nodeIds.add(edge.from);
+        nodeIds.add(edge.to);
+      }
+      for (const flow of flows)
+        for (const participant of flow.participants) nodeIds.add(participant.node);
+
+      const nodes = doc.nodes.filter((node) => nodeIds.has(node.id));
+      const edges =
+        scope.edges.length > 0
+          ? doc.edges.filter((edge) => selectedEdges.has(edge.id))
+          : doc.edges.filter((edge) => nodeIds.has(edge.from) && nodeIds.has(edge.to));
+
+      const laneIds = new Set<string>(scope.lanes);
+      for (const node of nodes) laneIds.add(node.lane);
+
+      return { lanes: doc.lanes.filter((lane) => laneIds.has(lane.id)), nodes, edges, flows };
+    }
+    default:
+      return assertNever(scope, "Unhandled view scope");
+  }
+};

package/src/svg/architecture.ts

@@ -0,0 +1,293 @@
+import type { GraphEdge, GraphNode, LayoutHints } from "@coldtea/pr-lens-schema";
+import { assertNever } from "@coldtea/pr-lens-schema";
+import {
+  BADGE_GAP,
+  BADGE_HEIGHT,
+  BADGE_RADIUS,
+  BADGE_RISE,
+  CARD_PADDING_X,
+  CARD_RADIUS,
+  HERO_PULSE_COUNT,
+  ICON_CHIP_GAP,
+  ICON_CHIP_RADIUS,
+  ICON_CHIP_SIZE,
+  LANE_HEADER_BASELINE,
+  LANE_PADDING_X,
+  LANE_RADIUS,
+  SUBTITLE_SIZE,
+} from "../design.js";
+import { canvasFor, union } from "../bounds.js";
+import { DIAGRAM_MARGIN } from "../design.js";
+import { coord, type Box } from "../geometry.js";
+import {
+  badgeRow,
+  badgeWidth,
+  cardBadges,
+  deltaBadgeText,
+  laneHeaderText,
+  type PlacedNode,
+} from "../layout/architecture.js";
+import { relieveCongestion } from "../layout/congestion.js";
+import { curveBounds, type RoutedEdge } from "../layout/edges.js";
+import { placeLabelPills } from "../layout/labels.js";
+import type { ScopedGraph } from "../scope.js";
+import { truncate } from "../text.js";
+import type { Palette } from "../theme.js";
+import { markerFor, shifted, toneColour, toneFor, type Tone } from "./document.js";
+import { glyphGroup } from "./icons.js";
+import { lines, tag, textNode, wrap } from "./primitives.js";
+import { travellingPulses } from "./pulse.js";
+
+const badgeTone = (node: GraphNode, text: string): Tone =>
+  text === deltaBadgeText(node.delta) ? toneFor(node.delta) : "neutral";
+
+/** The badge row, laid left to right across the strip the layout reserved. */
+const paintBadges = (placed: PlacedNode): string => {
+  const row = badgeRow(placed);
+  if (row === undefined) return "";
+
+  let x = row.box.x;
+  return lines(
+    row.badges.map((text) => {
+      const width = badgeWidth(text);
+      const painted = wrap(
+        "g",
+        { class: `bdg bdg-${badgeTone(placed.node, text)}` },
+        tag("rect", {
+          x: coord(x),
+          y: coord(row.box.y),
+          width: coord(width),
+          height: BADGE_HEIGHT,
+          rx: BADGE_RADIUS,
+        }) +
+          textNode(
+            {
+              x: coord(x + width / 2),
+              y: coord(row.box.y + BADGE_HEIGHT / 2 + 3),
+              "text-anchor": "middle",
+            },
+            text,
+          ),
+      );
+      x += width + BADGE_GAP;
+      return painted;
+    }),
+  );
+};
+
+const cardOutlineClass = (node: GraphNode): string => {
+  switch (node.delta) {
+    case "added":
+      return "card card-added";
+    case "modified":
+      return "card card-modified";
+    case "removed":
+    case "unchanged":
+      return "card";
+    default:
+      return assertNever(node.delta, "Unhandled delta");
+  }
+};
+
+export const paintCard = (placed: PlacedNode): string => {
+  const { node, box, showIcon, titleSize } = placed;
+  const textX = box.x + CARD_PADDING_X + (showIcon ? ICON_CHIP_SIZE + ICON_CHIP_GAP : 0);
+  const textWidth = box.x + box.width - CARD_PADDING_X - textX;
+  const hasSubtitle = node.subtitle !== undefined;
+  const titleBaseline = box.y + (hasSubtitle ? 27 : 31);
+
+  const chip = showIcon
+    ? tag("rect", {
+        class: "chip",
+        x: coord(box.x + CARD_PADDING_X),
+        y: coord(box.y + (box.height - ICON_CHIP_SIZE) / 2),
+        width: ICON_CHIP_SIZE,
+        height: ICON_CHIP_SIZE,
+        rx: ICON_CHIP_RADIUS,
+      }) +
+      glyphGroup(
+        node.kind,
+        box.x + CARD_PADDING_X + ICON_CHIP_SIZE / 2,
+        box.y + box.height / 2,
+      )
+    : "";
+
+  const title = textNode(
+    {
+      class: node.delta === "removed" ? "ntitle strike" : "ntitle",
+      x: coord(textX),
+      y: coord(titleBaseline),
+      "font-size": titleSize,
+    },
+    truncate(node.label, "sans-bold", titleSize, textWidth),
+  );
+
+  const subtitle =
+    node.subtitle === undefined
+      ? ""
+      : textNode(
+          { class: "nsub", x: coord(textX), y: coord(box.y + 45) },
+          truncate(node.subtitle, "mono", SUBTITLE_SIZE, textWidth),
+        );
+
+  const groupClass =
+    node.delta === "removed" ? "cardsh ghost" : node.delta === "unchanged" ? "cardsh context" : "cardsh";
+
+  return wrap(
+    "g",
+    { class: groupClass },
+    lines([
+      tag("rect", {
+        class: cardOutlineClass(node),
+        x: coord(box.x),
+        y: coord(box.y),
+        width: coord(box.width),
+        height: coord(box.height),
+        rx: CARD_RADIUS,
+      }),
+      chip,
+      title,
+      subtitle,
+      paintBadges(placed),
+    ]),
+  );
+};
+
+const pulses = (edge: GraphEdge, path: string, palette: Palette): string =>
+  edge.animated
+    ? travellingPulses({
+        path,
+        colour: toneColour(palette, toneFor(edge.delta)),
+        count: edge.emphasis === "hero" ? HERO_PULSE_COUNT : 1,
+        lag: 0,
+      })
+    : "";
+
+/**
+ * Paints one edge and the pill settled onto it. Every edge carries at most
+ * one label, and the layout already chose its place — on the route's longest
+ * straight run, nudged clear of every other pill — so a reader traces a line
+ * to its own words.
+ *
+ * The line and the label come back separately because they belong to
+ * different layers: a line passes behind a card, and a pill — which is opaque
+ * precisely so that it can be read wherever it lands — passes in front of one.
+ */
+const paintEdge = (
+  routed: RoutedEdge,
+  palette: Palette,
+  label: Box | undefined,
+): { markup: string; pill: string } => {
+  const { edge, path } = routed;
+  const tone = toneFor(edge.delta);
+  const hero = edge.emphasis === "hero";
+
+  const classes = ["edge", `edge-${tone}`];
+  if (hero) classes.push("hero");
+  if (edge.emphasis === "muted") classes.push("faded");
+  if (edge.delta === "unchanged") classes.push("context");
+
+  const glow = hero
+    ? tag("path", { class: "glow", stroke: toneColour(palette, tone), d: path })
+    : "";
+
+  return {
+    markup: lines([
+      glow,
+      tag("path", { class: classes.join(" "), d: path, "marker-end": markerFor(tone) }),
+      pulses(edge, path, palette),
+    ]),
+    pill:
+      label === undefined || edge.label === undefined
+        ? ""
+        : paintLabelPill(edge.label, label, tone),
+  };
+};
+
+export const paintLabelPill = (text: string, box: Box, tone: Tone): string =>
+  wrap(
+    "g",
+    {},
+    tag("rect", {
+      class: "lpill",
+      x: coord(box.x),
+      y: coord(box.y),
+      width: coord(box.width),
+      height: coord(box.height),
+      rx: box.height / 2,
+    }) +
+      textNode(
+        {
+          class: tone === "neutral" ? "ltext" : `ltext ltext-${tone}`,
+          x: coord(box.x + box.width / 2),
+          y: coord(box.y + box.height / 2 + 3.5),
+          "text-anchor": "middle",
+        },
+        text,
+      ),
+  );
+
+export type ArchitecturePainting = { width: number; height: number; body: string };
+
+export const paintArchitecture = (
+  graph: ScopedGraph,
+  hints: LayoutHints | undefined,
+  palette: Palette,
+): ArchitecturePainting => {
+  const { layout, routed } = relieveCongestion(graph, hints);
+  const pills = placeLabelPills(routed);
+
+  const drawn: Box[] = layout.nodes.flatMap((node) => {
+    const row = badgeRow(node);
+    return row === undefined ? [node.box] : [node.box, row.box];
+  });
+  const edgeMarkup: string[] = [];
+  const pillMarkup: string[] = [];
+  for (const edge of routed) {
+    const label = pills.get(edge.edge.id);
+    const { markup, pill } = paintEdge(edge, palette, label);
+    edgeMarkup.push(markup);
+    pillMarkup.push(pill);
+    if (label !== undefined) drawn.push(label);
+  }
+
+  const lanes = layout.lanes.map(({ lane, box }) =>
+    lines([
+      tag("rect", {
+        class: "lanebox",
+        x: coord(box.x),
+        y: coord(box.y),
+        width: coord(box.width),
+        height: coord(box.height),
+        rx: LANE_RADIUS,
+      }),
+      textNode(
+        { class: "lanelabel", x: coord(box.x + LANE_PADDING_X), y: LANE_HEADER_BASELINE },
+        laneHeaderText(lane),
+      ),
+    ]),
+  );
+
+  const canvas = canvasFor(
+    layout,
+    union([
+      ...layout.lanes.map(({ box }) => box),
+      ...drawn,
+      ...routed.map(({ curve }) => curveBounds(curve)),
+    ]),
+    DIAGRAM_MARGIN,
+  );
+
+  const painted = lines([
+    wrap("g", {}, lines(lanes)),
+    wrap("g", {}, lines(edgeMarkup)),
+    wrap("g", {}, lines(layout.nodes.map(paintCard))),
+    wrap("g", {}, lines(pillMarkup)),
+  ]);
+
+  return {
+    width: canvas.width,
+    height: canvas.height,
+    body: shifted(canvas, painted),
+  };
+};