@coldtea/pr-lens-renderer 0.1.0

package/src/layout/labels.ts

@@ -0,0 +1,192 @@
+import { assertNever } from "@coldtea/pr-lens-schema";
+import { PILL_CLEARANCE, PILL_HEIGHT, PILL_PADDING_X, PILL_TEXT_SIZE } from "../design.js";
+import type { Box, Point } from "../geometry.js";
+import { measure } from "../text.js";
+import type { Curve, RoutedEdge } from "./edges.js";
+
+/**
+ * Tracks separate the lines, but nothing in the router separates the pills
+ * riding them: when several labelled runs share a gap, track pitch is far
+ * finer than a pill, and the pills stack. This pass settles every pill so
+ * that no two intersect, preferring a nudge along the pill's own run — the
+ * label stays on its own line, just off the crowded spot — over anything
+ * that would loosen the tie between a label and its line.
+ */
+
+type Size = { width: number; height: number };
+
+/** A straight run of a route, described by its slide axis. */
+type Run = {
+  axis: "x" | "y";
+  /** The coordinate the run holds fixed — y of a horizontal run, x of a vertical one. */
+  cross: number;
+  lo: number;
+  hi: number;
+};
+
+const EPSILON = 0.01;
+
+/**
+ * The longest straight run of a route — the run the router pins the label to,
+ * and the only one collision handling may slide it along. Earlier segments
+ * win a tie, matching how the anchor itself is chosen.
+ */
+const longestRun = (curve: Curve): Run | undefined => {
+  let best: { run: Run; length: number } | undefined;
+  let start = curve.from;
+  for (const segment of curve.segments) {
+    const end = segment.to;
+    if (segment.kind === "line") {
+      const horizontal = Math.abs(end.y - start.y) < EPSILON;
+      const [lo, hi] = horizontal
+        ? [Math.min(start.x, end.x), Math.max(start.x, end.x)]
+        : [Math.min(start.y, end.y), Math.max(start.y, end.y)];
+      if (best === undefined || hi - lo > best.length)
+        best = {
+          run: { axis: horizontal ? "x" : "y", cross: horizontal ? start.y : start.x, lo, hi },
+          length: hi - lo,
+        };
+    }
+    start = end;
+  }
+  return best?.run;
+};
+
+const centred = (centre: Point, size: Size): Box => ({
+  x: centre.x - size.width / 2,
+  y: centre.y - size.height / 2,
+  width: size.width,
+  height: size.height,
+});
+
+const centreOn = (run: Run, along: number): Point => {
+  switch (run.axis) {
+    case "x":
+      return { x: along, y: run.cross };
+    case "y":
+      return { x: run.cross, y: along };
+    default:
+      return assertNever(run.axis, "Unhandled run axis");
+  }
+};
+
+/** Exactly PILL_CLEARANCE of air is enough, so the comparisons are strict. */
+const collides = (a: Box, b: Box): boolean =>
+  a.x < b.x + b.width + PILL_CLEARANCE &&
+  b.x < a.x + a.width + PILL_CLEARANCE &&
+  a.y < b.y + b.height + PILL_CLEARANCE &&
+  b.y < a.y + a.height + PILL_CLEARANCE;
+
+/**
+ * The position along the run closest to its midpoint where the pill clears
+ * everything already settled, or undefined when the run offers no room. A
+ * pill wider than a short run may only take the midpoint — overhanging both
+ * ends evenly, which is what the router always did with short runs. `reach`
+ * lets a second, more desperate pass push the pill up to that far past the
+ * run's ends — still square on its own line, at the line's foot.
+ */
+const slideAlong = (
+  run: Run,
+  size: Size,
+  settled: readonly Box[],
+  reach: number,
+): number | undefined => {
+  const halfAlong = (run.axis === "x" ? size.width : size.height) / 2;
+  const preferred = (run.lo + run.hi) / 2;
+  const lo = Math.min(run.lo + halfAlong - reach, preferred);
+  const hi = Math.max(run.hi - halfAlong + reach, preferred);
+
+  const blocked = settled
+    .flatMap((box) => {
+      const [alongLo, alongHi, crossLo, crossHi] =
+        run.axis === "x"
+          ? [box.x, box.x + box.width, box.y, box.y + box.height]
+          : [box.y, box.y + box.height, box.x, box.x + box.width];
+      const halfCross = (run.axis === "x" ? size.height : size.width) / 2;
+      if (run.cross - halfCross >= crossHi + PILL_CLEARANCE) return [];
+      if (run.cross + halfCross <= crossLo - PILL_CLEARANCE) return [];
+      return [{ from: alongLo - PILL_CLEARANCE - halfAlong, to: alongHi + PILL_CLEARANCE + halfAlong }];
+    });
+
+  let best: number | undefined;
+  const consider = (candidate: number) => {
+    if (candidate < lo || candidate > hi) return;
+    if (blocked.some((b) => b.from < candidate && candidate < b.to)) return;
+    if (
+      best === undefined ||
+      Math.abs(candidate - preferred) < Math.abs(best - preferred) ||
+      (Math.abs(candidate - preferred) === Math.abs(best - preferred) && candidate < best)
+    )
+      best = candidate;
+  };
+
+  consider(preferred);
+  for (const b of blocked) {
+    consider(b.from);
+    consider(b.to);
+  }
+  return best;
+};
+
+/**
+ * The tiebreak for a pill none of its runs can host: hold the anchor's
+ * position along the line and step square off it, nearer side first, until
+ * the pill clears — it ends up beside its own line rather than on it, but
+ * never more than a step or two away, and always in the same place for the
+ * same document.
+ */
+const stepAside = (anchor: Point, axis: "x" | "y", size: Size, settled: readonly Box[]): Box => {
+  const step = (axis === "x" ? size.height : size.width) + PILL_CLEARANCE;
+  for (let k = 1; ; k += 1)
+    for (const sign of [-1, 1]) {
+      const centre =
+        axis === "x"
+          ? { x: anchor.x, y: anchor.y + sign * k * step }
+          : { x: anchor.x + sign * k * step, y: anchor.y };
+      const box = centred(centre, size);
+      if (!settled.some((other) => collides(box, other))) return box;
+    }
+};
+
+const settle = (
+  curve: Curve,
+  anchor: Point,
+  size: Size,
+  settled: readonly Box[],
+): Box => {
+  const run = longestRun(curve);
+  if (run !== undefined)
+    for (const reach of [0, PILL_HEIGHT]) {
+      const along = slideAlong(run, size, settled, reach);
+      if (along !== undefined) return centred(centreOn(run, along), size);
+    }
+
+  // A route that only bends — a self-loop — has no run to slide along; its
+  // anchor still stands wherever it is clear.
+  const atAnchor = centred(anchor, size);
+  if (!settled.some((other) => collides(atAnchor, other))) return atAnchor;
+  return stepAside(anchor, run?.axis ?? "x", size, settled);
+};
+
+/**
+ * A pill box for every labelled route, none intersecting any other. Routes
+ * settle in document order, and a pill whose anchor is already clear stays
+ * exactly where the router put it, so an uncrowded diagram is untouched.
+ */
+export const placeLabelPills = (routed: readonly RoutedEdge[]): Map<string, Box> => {
+  const settled: Box[] = [];
+  const boxes = new Map<string, Box>();
+
+  for (const { edge, curve, labelAnchor } of routed) {
+    if (edge.label === undefined || labelAnchor === undefined) continue;
+    const size = {
+      width: measure(edge.label, "sans-bold", PILL_TEXT_SIZE) + PILL_PADDING_X * 2,
+      height: PILL_HEIGHT,
+    };
+    const box = settle(curve, labelAnchor, size, settled);
+    settled.push(box);
+    boxes.set(edge.id, box);
+  }
+
+  return boxes;
+};

package/src/layout/rank.ts

@@ -0,0 +1,95 @@
+import type { GraphEdge, GraphNode } from "@coldtea/pr-lens-schema";
+
+/**
+ * Layer index per node: how far down the diagram it sits.
+ *
+ * Longest path from a source, so an arrow always points at a node below the
+ * one it left. Real dependency graphs contain cycles, and a cycle has no
+ * such ordering, so the edges that close one are dropped first — the arrow
+ * still gets drawn, it just runs back up the page.
+ *
+ * `hints` are the document's preferences, applied as a floor rather than an
+ * answer: a hint can push a node further down, never above something that
+ * feeds it. A stale hint from an extraction model therefore cannot invert an
+ * edge, only leave a gap.
+ */
+export const rankNodes = (
+  nodes: readonly GraphNode[],
+  edges: readonly GraphEdge[],
+  hints: Readonly<Record<string, number>>,
+): Map<string, number> => {
+  const forward = new Map<string, string[]>();
+  const backward = new Map<string, string[]>();
+  for (const node of nodes) {
+    forward.set(node.id, []);
+    backward.set(node.id, []);
+  }
+
+  const withinGraph = edges.filter(
+    (edge) => edge.from !== edge.to && forward.has(edge.from) && forward.has(edge.to),
+  );
+  for (const edge of withinGraph) forward.get(edge.from)?.push(edge.to);
+
+  for (const [from, to] of forwardEdgesWithoutCycles(nodes, forward)) backward.get(to)?.push(from);
+
+  const ranks = new Map<string, number>();
+  const settle = (id: string): number => {
+    const known = ranks.get(id);
+    if (known !== undefined) return known;
+
+    let rank = hints[id] ?? 0;
+    for (const predecessor of backward.get(id) ?? []) rank = Math.max(rank, settle(predecessor) + 1);
+    ranks.set(id, rank);
+    return rank;
+  };
+
+  for (const node of nodes) settle(node.id);
+  return ranks;
+};
+
+/**
+ * Depth-first from every node in document order, dropping any edge that
+ * reaches a node still open on the stack. Which edge closes a cycle depends
+ * on where the walk started, so the walk order is fixed by the document
+ * rather than by iteration order of a map.
+ */
+const forwardEdgesWithoutCycles = (
+  nodes: readonly GraphNode[],
+  forward: ReadonlyMap<string, readonly string[]>,
+): [string, string][] => {
+  const kept: [string, string][] = [];
+  const open = new Set<string>();
+  const closed = new Set<string>();
+
+  for (const root of nodes) {
+    if (closed.has(root.id)) continue;
+
+    const stack: { id: string; next: number }[] = [{ id: root.id, next: 0 }];
+    open.add(root.id);
+
+    while (stack.length > 0) {
+      const frame = stack[stack.length - 1];
+      if (frame === undefined) break;
+
+      const successors = forward.get(frame.id) ?? [];
+      if (frame.next >= successors.length) {
+        open.delete(frame.id);
+        closed.add(frame.id);
+        stack.pop();
+        continue;
+      }
+
+      const successor = successors[frame.next];
+      frame.next += 1;
+      if (successor === undefined || open.has(successor)) continue;
+
+      kept.push([frame.id, successor]);
+      if (closed.has(successor)) continue;
+
+      open.add(successor);
+      stack.push({ id: successor, next: 0 });
+    }
+  }
+
+  return kept;
+};

package/src/layout/seating.ts

@@ -0,0 +1,189 @@
+import type { GraphEdge, GraphNode, Lane } from "@coldtea/pr-lens-schema";
+import { rankNodes } from "./rank.js";
+
+/** One occupied row of one lane: a single card, or two side by side. */
+export type SeatedRow = { grid: number; nodes: GraphNode[] };
+
+export type Seating = {
+  rowsByLane: Map<string, SeatedRow[]>;
+  rowCount: number;
+  /** First row of the dead band; absent when nothing was removed. */
+  deadFromRow: number | undefined;
+};
+
+/**
+ * Where every card sits: a row grid shared across all lanes.
+ *
+ * Ranks are compressed globally rather than per lane, so a card and the card
+ * it converses with across a lane boundary land on comparable rows — that is
+ * what lets their connection run straight. The cost is honest: a lane that
+ * enters the story late leaves its upper rows empty, and the diagram gets
+ * taller. Stability is the invariant this trades nothing of: seating reads
+ * connections and document order, never a label, so a rename moves nothing.
+ *
+ * What was removed drops out of the living graph entirely, into a band of
+ * rows below everything alive, keeping its internal structure. Living ranks
+ * are computed over living connections only, so a retired pathway cannot
+ * push a living card down the page.
+ */
+export const seatNodes = (
+  orderedLanes: readonly Lane[],
+  nodes: readonly GraphNode[],
+  edges: readonly GraphEdge[],
+  rankHints: Readonly<Record<string, number>>,
+): Seating => {
+  const laneIndex = new Map(orderedLanes.map((lane, index) => [lane.id, index]));
+  const docIndex = new Map(nodes.map((node, index) => [node.id, index]));
+
+  const living = nodes.filter((node) => node.delta !== "removed");
+  const dead = nodes.filter((node) => node.delta === "removed");
+  const livingEdges = edges.filter((edge) => edge.delta !== "removed");
+
+  const livingRanks = rankNodes(living, livingEdges, rankHints);
+  const livingRowOfRank = compressRanks(living, livingRanks);
+  const keys = barycenters(living, livingEdges, livingRanks, laneIndex);
+
+  const rowsByLane = new Map<string, SeatedRow[]>();
+  let lastRow = -1;
+
+  for (const lane of orderedLanes) {
+    const members = living.filter((node) => node.lane === lane.id);
+    if (members.length === 0) continue;
+    const rows = seatLane(members, livingRanks, livingRowOfRank, -1, keys, docIndex);
+    rowsByLane.set(lane.id, rows);
+    lastRow = Math.max(lastRow, rows[rows.length - 1]?.grid ?? -1);
+  }
+
+  const deadFromRow = dead.length === 0 ? undefined : lastRow + 1;
+  if (deadFromRow !== undefined) {
+    const deadRanks = rankNodes(dead, edges, {});
+    const deadRowOfRank = compressRanks(dead, deadRanks);
+    const deadKeys = barycenters(dead, edges, deadRanks, laneIndex);
+
+    for (const lane of orderedLanes) {
+      const members = dead.filter((node) => node.lane === lane.id);
+      if (members.length === 0) continue;
+      const rows = seatLane(members, deadRanks, deadRowOfRank, deadFromRow - 1, deadKeys, docIndex);
+      const seated = rowsByLane.get(lane.id);
+      if (seated === undefined) rowsByLane.set(lane.id, rows);
+      else seated.push(...rows);
+      lastRow = Math.max(lastRow, rows[rows.length - 1]?.grid ?? -1);
+    }
+  }
+
+  return { rowsByLane, rowCount: lastRow + 1, deadFromRow };
+};
+
+/** Rank values in use, in order, mapped onto contiguous rows. */
+const compressRanks = (
+  nodes: readonly GraphNode[],
+  ranks: ReadonlyMap<string, number>,
+): Map<number, number> => {
+  const used = [...new Set(nodes.map((node) => ranks.get(node.id) ?? 0))].sort((a, b) => a - b);
+  return new Map(used.map((rank, index) => [rank, index]));
+};
+
+type Barycenters = {
+  /** Mean rank of a card's partners: decides who falls when a rank collides. */
+  fall: Map<string, number>;
+  /** Mean lane of a card's partners: decides who sits left in a shared row. */
+  side: Map<string, number>;
+};
+
+const barycenters = (
+  nodes: readonly GraphNode[],
+  edges: readonly GraphEdge[],
+  ranks: ReadonlyMap<string, number>,
+  laneIndex: ReadonlyMap<string, number>,
+): Barycenters => {
+  const laneOf = new Map(nodes.map((node) => [node.id, laneIndex.get(node.lane) ?? 0]));
+  const partners = new Map<string, string[]>(nodes.map((node) => [node.id, []]));
+  for (const edge of edges) {
+    if (edge.from === edge.to || !laneOf.has(edge.from) || !laneOf.has(edge.to)) continue;
+    partners.get(edge.from)?.push(edge.to);
+    partners.get(edge.to)?.push(edge.from);
+  }
+
+  const fall = new Map<string, number>();
+  const side = new Map<string, number>();
+  for (const node of nodes) {
+    const linked = partners.get(node.id) ?? [];
+    fall.set(node.id, mean(linked.map((id) => ranks.get(id) ?? 0)) ?? ranks.get(node.id) ?? 0);
+    side.set(
+      node.id,
+      mean(linked.map((id) => laneOf.get(id) ?? 0)) ?? laneOf.get(node.id) ?? 0,
+    );
+  }
+  return { fall, side };
+};
+
+const mean = (values: readonly number[]): number | undefined =>
+  values.length === 0
+    ? undefined
+    : values.reduce((sum, value) => sum + value, 0) / values.length;
+
+/**
+ * One lane's members onto the shared grid.
+ *
+ * A card sits at its rank's row unless an earlier card of the same lane
+ * already claimed it, in which case it falls to the next free one — a lane
+ * never overlaps itself. Two cards share a row only at the same rank in the
+ * same sub-group, so a pair always reads as "these happen alongside each
+ * other". Who falls, and who sits left in a pair, is decided by where each
+ * card's partners are — the card leaning toward its neighbours stays put —
+ * with document order as the stable tiebreak.
+ */
+const seatLane = (
+  members: readonly GraphNode[],
+  ranks: ReadonlyMap<string, number>,
+  rowOfRank: ReadonlyMap<number, number>,
+  floor: number,
+  keys: Barycenters,
+  docIndex: ReadonlyMap<string, number>,
+): SeatedRow[] => {
+  const doc = (node: GraphNode): number => docIndex.get(node.id) ?? 0;
+  const sorted = [...members].sort((a, b) => {
+    const row =
+      (rowOfRank.get(ranks.get(a.id) ?? 0) ?? 0) - (rowOfRank.get(ranks.get(b.id) ?? 0) ?? 0);
+    if (row !== 0) return row;
+    const fall = (keys.fall.get(a.id) ?? 0) - (keys.fall.get(b.id) ?? 0);
+    if (fall !== 0) return fall;
+    return doc(a) - doc(b);
+  });
+
+  const rows: { grid: number; rank: number; nodes: GraphNode[] }[] = [];
+  let previous = floor;
+
+  for (const node of sorted) {
+    const rank = ranks.get(node.id) ?? 0;
+    const open = rows[rows.length - 1];
+
+    if (
+      open !== undefined &&
+      open.nodes.length === 1 &&
+      open.rank === rank &&
+      (open.nodes[0]?.group ?? "") === (node.group ?? "")
+    ) {
+      const first = open.nodes[0];
+      if (first !== undefined && leansLeft(node, first, keys, doc)) open.nodes.unshift(node);
+      else open.nodes.push(node);
+      continue;
+    }
+
+    previous = Math.max(previous + 1, floor + 1 + (rowOfRank.get(rank) ?? 0));
+    rows.push({ grid: previous, rank, nodes: [node] });
+  }
+
+  return rows.map(({ grid, nodes }) => ({ grid, nodes }));
+};
+
+const leansLeft = (
+  node: GraphNode,
+  other: GraphNode,
+  keys: Barycenters,
+  doc: (node: GraphNode) => number,
+): boolean => {
+  const side = (keys.side.get(node.id) ?? 0) - (keys.side.get(other.id) ?? 0);
+  if (side !== 0) return side < 0;
+  return doc(node) < doc(other);
+};

package/src/manifest.ts

@@ -0,0 +1,118 @@
+import { createHash } from "node:crypto";
+import type { GraphDoc, Lens, RenderAsset, RenderManifest } from "@coldtea/pr-lens-schema";
+import { SCHEMA_VERSION } from "@coldtea/pr-lens-schema";
+import type { Theme } from "./theme.js";
+import { RENDERER_NAME, RENDERER_VERSION } from "./version.js";
+
+/**
+ * How many hex characters of the digest an address carries. Long enough that
+ * two different renders will not collide inside one repository's history,
+ * short enough to read in a URL.
+ */
+export const CONTENT_HASH_LENGTH = 32;
+
+/**
+ * The one place render bytes become an address.
+ *
+ * GitHub proxies comment images and caches them hard, so a changed diagram
+ * has to arrive as a different URL rather than as new bytes at the old one.
+ * Every surface that builds such a URL — the action writing files, the hosted
+ * app uploading them — must hash through here, or the two will disagree about
+ * what the same render is called.
+ */
+export const contentHash = (bytes: string): string =>
+  createHash("sha256").update(bytes, "utf8").digest("hex").slice(0, CONTENT_HASH_LENGTH);
+
+/** JSON with object keys in sorted order, so equal documents hash equal. */
+export const canonicalJson = (value: unknown): string => {
+  if (value === null || typeof value !== "object") return JSON.stringify(value) ?? "null";
+  if (Array.isArray(value)) return `[${value.map(canonicalJson).join(",")}]`;
+
+  const entries = Object.entries(value)
+    .filter(([, nested]) => nested !== undefined)
+    .sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0));
+
+  return `{${entries.map(([key, nested]) => `${JSON.stringify(key)}:${canonicalJson(nested)}`).join(",")}}`;
+};
+
+export const graphContentHash = (doc: GraphDoc): string => contentHash(canonicalJson(doc));
+
+export type AssetAddress = { lens: Lens; theme: Theme; view: string | undefined };
+
+/**
+ * How the characters a view id may contain but a file name may not are spelled.
+ *
+ * View ids are authored by an extraction model, and the contract lets one
+ * contain `/`, `:` and `.` — so `a/../../elsewhere` is a perfectly valid id.
+ * Surfaces join an asset's path to an output directory, and that id would walk
+ * straight out of it. The mapping is one-to-one rather than a scrub, so two
+ * different views can never be handed the same address: `_` names itself
+ * first, which is what keeps the other three from colliding with text that
+ * was already there.
+ */
+const FILE_NAME_ESCAPES: readonly [string, string][] = [
+  ["_", "_u"],
+  ["/", "_s"],
+  [":", "_c"],
+  [".", "_d"],
+];
+
+const escapeForFileName = (id: string): string =>
+  FILE_NAME_ESCAPES.reduce((text, [character, escape]) => text.split(character).join(escape), id);
+
+/** The contract's ceiling on an `Id`, which an asset id has to stay under. */
+const ASSET_ID_MAX = 128;
+const THEME_SUFFIX_MAX = "-light".length;
+const STEM_MAX = ASSET_ID_MAX - THEME_SUFFIX_MAX;
+const DIGEST_LENGTH = 12;
+
+/**
+ * `_h` cannot occur in an escaped id — every `_` there opens one of the four
+ * escapes above — so it can mark the digest without ever being mistaken for
+ * text that was already in the id.
+ */
+const DIGEST_MARKER = "_h";
+const PREFIX_MAX = STEM_MAX - DIGEST_MARKER.length - DIGEST_LENGTH;
+
+/**
+ * A view id spelled so that it is both a legal file name and a legal `Id`.
+ *
+ * Escaping can double the length of an id that is already near the contract's
+ * limit, so a stem that would overflow keeps a readable prefix and ends in a
+ * digest of the whole original. The digest is what preserves the one property
+ * that matters: two different views can never be handed the same address.
+ */
+const fileNameSafe = (id: string): string => {
+  const escaped = escapeForFileName(id);
+  if (escaped.length <= STEM_MAX) return escaped;
+
+  const prefix = escaped.slice(0, PREFIX_MAX).replace(/_$/, "");
+  return `${prefix}${DIGEST_MARKER}${contentHash(id).slice(0, DIGEST_LENGTH)}`;
+};
+
+/**
+ * The identity of one rendered SVG within a render: the drill-down section it
+ * belongs to and the half of the theme pair it is. A render with no sections
+ * falls back to the lens, which is unique across the same render.
+ *
+ * This doubles as the stem of the file name, so it is spelled in the alphabet
+ * a file name can carry.
+ */
+export const renderAssetId = ({ lens, theme, view }: AssetAddress): string =>
+  `${fileNameSafe(view ?? lens)}-${theme}`;
+
+/** The file name an asset is written or published under. */
+export const renderAssetFileName = (address: AssetAddress, hash: string): string =>
+  `${renderAssetId(address)}-${hash}.svg`;
+
+export const buildManifest = (doc: GraphDoc, assets: readonly RenderAsset[]): RenderManifest => ({
+  schemaVersion: SCHEMA_VERSION,
+  kind: "render-manifest",
+  graph: {
+    id: doc.id,
+    headSha: doc.provenance.head.sha,
+    contentHash: graphContentHash(doc),
+  },
+  renderer: { name: RENDERER_NAME, version: RENDERER_VERSION },
+  assets: [...assets],
+});