@coldtea/pr-lens-renderer 0.1.0

package/src/design.ts

@@ -0,0 +1,124 @@
+/**
+ * The measurements of the validated prototype, in one place. These are the
+ * design system: change a number here and every diagram moves with it.
+ */
+export const DIAGRAM_MARGIN = 16;
+
+export const LANE_TOP = 44;
+export const LANE_HEADER_BASELINE = 68;
+export const LANE_PADDING_X = 16;
+export const LANE_GAP = 20;
+export const LANE_BOTTOM_PADDING = 20;
+
+/**
+ * Every lane is the same width, and that width is a constant rather than
+ * anything derived from what the lanes hold.
+ *
+ * A lane's width decides where the lane after it starts, so a width drawn
+ * from content couples every column to the contents of the ones before it:
+ * adding one node with a long name to the first lane would slide every card
+ * in every later lane sideways, which is exactly the teleport a reviewer
+ * comparing two pushes must never be shown. The cost is that a lane holding
+ * something narrow is wider than it needs to be. Stability is worth more.
+ *
+ * Sized so that two cards sharing a row still each get a readable width.
+ */
+export const LANE_CONTENT_WIDTH = 372;
+export const LANE_RADIUS = 12;
+export const LANE_LABEL_SIZE = 10;
+export const LANE_LABEL_TRACKING = 0.12;
+
+export const CONTENT_TOP = 92;
+export const ROW_GAP = 52;
+
+export const CARD_RADIUS = 10;
+export const CARD_GAP_X = 12;
+export const CARD_HEIGHT = 52;
+export const CARD_HEIGHT_WITH_SUBTITLE = 62;
+export const CARD_PADDING_X = 14;
+
+export const ICON_CHIP_SIZE = 26;
+export const ICON_CHIP_GAP = 10;
+export const ICON_CHIP_RADIUS = 7;
+/** Below this a card's title steps down a size to keep its room. */
+export const ICON_MIN_CARD_WIDTH = 200;
+
+export const TITLE_SIZE = 13;
+export const TITLE_SIZE_SMALL = 11.5;
+export const SUBTITLE_SIZE = 9.5;
+
+export const BADGE_HEIGHT = 16;
+export const BADGE_PADDING_X = 9;
+export const BADGE_TEXT_SIZE = 8.5;
+export const BADGE_TRACKING = 0.06;
+export const BADGE_GAP = 6;
+export const BADGE_RADIUS = 8;
+/** How far the badge row rides above the top edge of the card it labels. */
+export const BADGE_RISE = 8;
+
+export const PILL_HEIGHT = 15;
+export const PILL_PADDING_X = 8;
+export const PILL_TEXT_SIZE = 9.5;
+/** Two label pills never sit closer than this, in either direction. */
+export const PILL_CLEARANCE = 2;
+
+/**
+ * Routes travel in the gaps of the grid: vertical corridors beside lanes and
+ * horizontal bands between rows. Both gaps are physically 52px across — lane
+ * padding + lane gap + lane padding one way, ROW_GAP the other — and a track
+ * keeps this clearance from the cards on either side, leaving 40px of room.
+ */
+export const TRACK_CLEARANCE = 6;
+/**
+ * Neighbouring tracks in one gap sit this far apart at most; when a gap
+ * carries more traffic than the room allows, the pitch shrinks to fit. An
+ * added route therefore nudges its gap-mates proportionately — an accepted
+ * trade, and one that never moves a card.
+ */
+export const TRACK_PITCH_MAX = 16;
+/**
+ * And never closer than this: below it, parallel runs stop reading as
+ * separate lines. A gap asked to carry more traffic than the floor allows
+ * does not compress further — it widens instead, corridors pushing the lanes
+ * beside them apart and row gaps pushing the rows, in proportion to the
+ * traffic and to nothing else.
+ */
+export const TRACK_PITCH_MIN = 10;
+
+/** Step between neighbouring arrow ports along one card face. */
+export const PORT_PITCH = 16;
+/** Ports keep clear of the card's rounded corners. */
+export const PORT_INSET = 14;
+
+/**
+ * A turn's bend radius comes from the shorter of its two legs, capped here.
+ * Deriving it from the longer leg balloons a route with one short leg and one
+ * long one — the shape every corridor run has — clear out of its corridor.
+ */
+export const BEND_RADIUS_MAX = 34;
+
+/** One turn of the travelling pulse, and of the staggered train. */
+export const PULSE_DURATION = 1.6;
+export const HERO_PULSE_DURATION = 2.1;
+export const HERO_PULSE_COUNT = 3;
+
+/**
+ * A sequence animates one step at a time, in order, because that is the one
+ * thing a sequence has to say. Each pulse owns a slot of the cycle outright
+ * and crosses its arrow for the whole of it, so the drawing always has
+ * exactly one dot in flight — the next arrow lights as the last dot lands.
+ *
+ * This is how long one crossing takes when the flow is short enough to
+ * afford it: brisk enough to read as travelling, slow enough to follow.
+ */
+export const FLOW_STEP_TRAVEL = 1.4;
+/**
+ * A whole sequence should play through in one sitting. Past this the steps
+ * share the ceiling instead, which speeds up a long flow rather than asking
+ * a reader to wait a minute for its last arrow.
+ */
+export const FLOW_CYCLE_MAX = 16;
+/** How much of its own slot a pulse spends fading in, and again fading out. */
+export const FLOW_PULSE_RAMP = 0.08;
+/** More repeats than this and the arrows stop reading as separate calls. */
+export const FLOW_MAX_PULSES_PER_MESSAGE = 3;

package/src/errors.ts

@@ -0,0 +1,21 @@
+/**
+ * Codes are the stable half of a failure; the message is for a human. Every
+ * one of these describes a document the renderer cannot draw, never an
+ * internal fault.
+ */
+export type RenderErrorCode =
+  | "UNKNOWN_VIEW"
+  | "LENS_NOT_DECLARED"
+  | "NOTHING_TO_RENDER"
+  | "NO_FLOW_IN_SCOPE"
+  | "TOO_MANY_ASSETS";
+
+export class PrLensRenderError extends Error {
+  readonly code: RenderErrorCode;
+
+  constructor(code: RenderErrorCode, message: string) {
+    super(message);
+    this.name = "PrLensRenderError";
+    this.code = code;
+  }
+}

package/src/geometry.ts

@@ -0,0 +1,22 @@
+export type Point = { x: number; y: number };
+
+export type Box = { x: number; y: number; width: number; height: number };
+
+/** Which face of a box a line meets. */
+export type Side = "top" | "right" | "bottom" | "left";
+
+/**
+ * Every coordinate the renderer writes goes through here. Floating point
+ * arithmetic that differs in the last bit would otherwise change the bytes of
+ * the document without changing the picture, and the render hash with it.
+ */
+export const coord = (value: number): string => {
+  const rounded = Math.round(value * 100) / 100;
+  const normalised = Object.is(rounded, -0) ? 0 : rounded;
+  return String(normalised);
+};
+
+export const boxCentre = (box: Box): Point => ({
+  x: box.x + box.width / 2,
+  y: box.y + box.height / 2,
+});

package/src/glob.ts

@@ -0,0 +1,20 @@
+const escapeRegExp = (value: string): string => value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+
+/**
+ * Path matching for config selectors, with the subset of glob a person
+ * actually writes in one: `**` crosses directory boundaries, `*` and `?` do
+ * not. Every other character is literal.
+ */
+export const matchesGlob = (pattern: string, path: string): boolean => {
+  const source = pattern
+    .split("**")
+    .map((crossing) =>
+      crossing
+        .split("*")
+        .map((segment) => segment.split("?").map(escapeRegExp).join("[^/]"))
+        .join("[^/]*"),
+    )
+    .join(".*");
+
+  return new RegExp(`^${source}$`).test(path);
+};

package/src/index.ts

@@ -0,0 +1,30 @@
+export { RENDERER_NAME, RENDERER_VERSION } from "./version.js";
+
+export {
+  render,
+  renderAll,
+  type RenderAllOptions,
+  type RenderAllResult,
+  type RenderedAsset,
+  type RenderedSvg,
+  type RenderOptions,
+} from "./render.js";
+
+export { PrLensRenderError, type RenderErrorCode } from "./errors.js";
+
+export { paletteFor, THEMES, type Palette, type Theme } from "./theme.js";
+
+export {
+  buildManifest,
+  canonicalJson,
+  contentHash,
+  CONTENT_HASH_LENGTH,
+  graphContentHash,
+  renderAssetFileName,
+  renderAssetId,
+  type AssetAddress,
+} from "./manifest.js";
+
+export { applyCorrections } from "./corrections.js";
+
+export { findView, flattenViews, resolveScope, type ScopedGraph } from "./scope.js";

package/src/layout/architecture.ts

@@ -0,0 +1,324 @@
+import type { Delta, GraphNode, Lane, LayoutHints } from "@coldtea/pr-lens-schema";
+import { assertNever } from "@coldtea/pr-lens-schema";
+import {
+  BADGE_GAP,
+  BADGE_HEIGHT,
+  BADGE_PADDING_X,
+  BADGE_RISE,
+  BADGE_TEXT_SIZE,
+  BADGE_TRACKING,
+  CARD_GAP_X,
+  CARD_HEIGHT,
+  CARD_HEIGHT_WITH_SUBTITLE,
+  CARD_PADDING_X,
+  CONTENT_TOP,
+  DIAGRAM_MARGIN,
+  ICON_MIN_CARD_WIDTH,
+  LANE_BOTTOM_PADDING,
+  LANE_GAP,
+  LANE_LABEL_SIZE,
+  LANE_LABEL_TRACKING,
+  LANE_CONTENT_WIDTH,
+  LANE_PADDING_X,
+  LANE_TOP,
+  ROW_GAP,
+  TITLE_SIZE,
+  TITLE_SIZE_SMALL,
+} from "../design.js";
+import type { Box } from "../geometry.js";
+import type { ScopedGraph } from "../scope.js";
+import { measure, type Face } from "../text.js";
+import { seatNodes, type SeatedRow } from "./seating.js";
+
+export const deltaBadgeText = (delta: Delta): string | undefined => {
+  switch (delta) {
+    case "added":
+      return "NEW";
+    case "modified":
+      return "CHANGED";
+    case "removed":
+      return "REMOVED";
+    case "unchanged":
+      return undefined;
+    default:
+      return assertNever(delta, "Unhandled delta");
+  }
+};
+
+/** Width of tracked text: letter-spacing adds a fixed step after every glyph. */
+const trackedWidth = (
+  text: string,
+  face: Face,
+  fontSize: number,
+  tracking: number,
+): number => measure(text, face, fontSize) + [...text].length * tracking * fontSize;
+
+export const badgeWidth = (text: string): number =>
+  trackedWidth(text, "sans-bold", BADGE_TEXT_SIZE, BADGE_TRACKING) + BADGE_PADDING_X * 2;
+
+/** Every badge a card carries, its own first and the delta badge last. */
+export const cardBadges = (node: GraphNode): string[] => {
+  const delta = deltaBadgeText(node.delta);
+  return delta === undefined ? [...node.badges] : [...node.badges, delta];
+};
+
+export type PlacedNode = {
+  node: GraphNode;
+  box: Box;
+  /** Wide enough for the kind glyph to earn its place. */
+  showIcon: boolean;
+  titleSize: number;
+  row: number;
+  laneIndex: number;
+};
+
+export type PlacedLane = { lane: Lane; box: Box };
+
+/**
+ * The badges a card actually shows and the strip they occupy above it.
+ *
+ * When the row is wider than the card the badges the author added give way
+ * first: the delta badge is the one a reviewer is scanning for. Nothing is
+ * returned when the card carries no badge, and the strip counts as occupied
+ * space so an edge label does not settle on top of it.
+ */
+export const badgeRow = (placed: PlacedNode): { badges: string[]; box: Box } | undefined => {
+  const all = cardBadges(placed.node);
+  if (all.length === 0) return undefined;
+
+  const room = placed.box.width - CARD_PADDING_X;
+  const shown: string[] = [];
+  let used = 0;
+  for (const text of [...all].reverse()) {
+    const next = used + badgeWidth(text) + (shown.length > 0 ? BADGE_GAP : 0);
+    if (next > room) break;
+    used = next;
+    shown.unshift(text);
+  }
+  if (shown.length === 0) return undefined;
+
+  const right = placed.box.x + placed.box.width - CARD_PADDING_X / 2;
+  return {
+    badges: shown,
+    box: {
+      x: right - used,
+      y: placed.box.y - BADGE_RISE,
+      width: used,
+      height: BADGE_HEIGHT,
+    },
+  };
+};
+
+/**
+ * The gaps of the grid, for the router: the vertical corridors beside each
+ * lane's cards and the horizontal extents of every row. Corridor `i` runs to
+ * the left of lane `i`; the extra corridor after the last lane is where
+ * retired pathways are exiled to.
+ */
+export type LayoutGrid = {
+  rows: { top: number; height: number }[];
+  corridors: { left: number; right: number }[];
+  /** Where lane content ends — the floor of the last band under the last row. */
+  laneBottom: number;
+  /** First row of the dead band; absent when nothing was removed. */
+  deadFromRow: number | undefined;
+};
+
+/**
+ * Extra room granted to individual gaps, keyed by corridor or band index —
+ * how the layout widens where traffic would otherwise compress track pitch
+ * through the floor. Expanding a corridor moves every lane after it sideways
+ * by the same amount; expanding a band moves every row after it down. Cards
+ * travel with their lane and row — nothing re-seats, nothing reorders.
+ */
+export type GapExpansions = {
+  corridors: ReadonlyMap<number, number>;
+  bands: ReadonlyMap<number, number>;
+};
+
+export type ArchitectureLayout = {
+  width: number;
+  height: number;
+  lanes: PlacedLane[];
+  nodes: PlacedNode[];
+  grid: LayoutGrid;
+};
+
+const cardHeight = (node: GraphNode): number =>
+  node.subtitle === undefined ? CARD_HEIGHT : CARD_HEIGHT_WITH_SUBTITLE;
+
+/**
+ * Lane order: the document's explicit list first, for the lanes it names,
+ * then whatever is left by declared order and finally by the order they were
+ * written in. `order` may be absent, and two lanes may share one, so the
+ * document's own array is the tie-break that keeps this stable.
+ */
+const orderLanes = (lanes: readonly Lane[], hints: LayoutHints | undefined): Lane[] => {
+  const named = hints?.laneOrder ?? [];
+  const byId = new Map(lanes.map((lane) => [lane.id, lane]));
+  const ordered: Lane[] = [];
+  const taken = new Set<string>();
+
+  for (const id of named) {
+    const lane = byId.get(id);
+    if (lane === undefined || taken.has(id)) continue;
+    ordered.push(lane);
+    taken.add(id);
+  }
+
+  const rest = lanes
+    .map((lane, index) => ({ lane, index }))
+    .filter(({ lane }) => !taken.has(lane.id))
+    .sort((a, b) => (a.lane.order ?? Number.MAX_SAFE_INTEGER) - (b.lane.order ?? Number.MAX_SAFE_INTEGER) || a.index - b.index)
+    .map(({ lane }) => lane);
+
+  return [...ordered, ...rest];
+};
+
+/**
+ * A pair divides its row into equal halves. Splitting in proportion to what
+ * each card's text asked for would mean a rename moves its neighbour — and a
+ * rename moving anything is exactly what the seating guarantee rules out.
+ */
+const rowWidths = (contentWidth: number, row: SeatedRow): number[] => {
+  if (row.nodes.length < 2) return [contentWidth];
+  const half = Math.round((contentWidth - CARD_GAP_X) / 2);
+  return [half, contentWidth - CARD_GAP_X - half];
+};
+
+export const layoutArchitecture = (
+  graph: ScopedGraph,
+  hints: LayoutHints | undefined,
+  expansions?: GapExpansions,
+): ArchitectureLayout => {
+  const corridorExtra = (index: number): number => expansions?.corridors.get(index) ?? 0;
+  const bandExtra = (index: number): number => expansions?.bands.get(index) ?? 0;
+
+  const ordered = orderLanes(graph.lanes, hints);
+  const seating = seatNodes(ordered, graph.nodes, graph.edges, hints?.rank ?? {});
+
+  const lanes = ordered.flatMap((lane) => {
+    const rows = seating.rowsByLane.get(lane.id);
+    return rows === undefined ? [] : [{ lane, rows }];
+  });
+
+  const laneBoxWidth = LANE_CONTENT_WIDTH + LANE_PADDING_X * 2;
+
+  const gridHeights = new Map<number, number>();
+  for (const { rows } of lanes)
+    for (const { grid, nodes } of rows) {
+      const height = Math.max(...nodes.map(cardHeight));
+      gridHeights.set(grid, Math.max(gridHeights.get(grid) ?? 0, height));
+    }
+
+  // Every row of the shared grid is occupied by whichever card created it, so
+  // walking 0..rowCount visits exactly the keys collected above.
+  const gridRows: { top: number; height: number }[] = [];
+  let cursor = CONTENT_TOP;
+  for (let grid = 0; grid < seating.rowCount; grid += 1) {
+    if (grid > 0) cursor += bandExtra(grid);
+    const height = gridHeights.get(grid) ?? 0;
+    gridRows.push({ top: cursor, height });
+    cursor += height + ROW_GAP;
+  }
+  const contentBottom = cursor - ROW_GAP;
+
+  const laneBottom = contentBottom + LANE_BOTTOM_PADDING + bandExtra(seating.rowCount);
+  const placedLanes: PlacedLane[] = [];
+  const placedNodes: PlacedNode[] = [];
+  let laneX = DIAGRAM_MARGIN;
+
+  lanes.forEach(({ lane, rows }, laneIndex) => {
+    laneX += corridorExtra(laneIndex);
+    const contentX = laneX + LANE_PADDING_X;
+    const contentWidth = LANE_CONTENT_WIDTH;
+
+    placedLanes.push({
+      lane,
+      box: { x: laneX, y: LANE_TOP, width: laneBoxWidth, height: laneBottom - LANE_TOP },
+    });
+
+    for (const row of rows) {
+      const top = gridRows[row.grid]?.top ?? CONTENT_TOP;
+      const widths = rowWidths(contentWidth, row);
+
+      let x = contentX;
+      row.nodes.forEach((node, index) => {
+        const width = widths[index] ?? contentWidth;
+        placedNodes.push({
+          node,
+          box: { x, y: top, width, height: cardHeight(node) },
+          // Every kind draws something, on every card: the chip is reserved
+          // space and the title truncates, so recognition wins at any width.
+          showIcon: true,
+          titleSize: width >= ICON_MIN_CARD_WIDTH ? TITLE_SIZE : TITLE_SIZE_SMALL,
+          row: row.grid,
+          laneIndex,
+        });
+        x += width + CARD_GAP_X;
+      });
+    }
+
+    laneX += laneBoxWidth + LANE_GAP;
+  });
+
+  const gutter = LANE_PADDING_X * 2 + LANE_GAP;
+  const corridors = placedLanes.map(({ box }, index) => ({
+    left: box.x + LANE_PADDING_X - gutter - corridorExtra(index),
+    right: box.x + LANE_PADDING_X,
+  }));
+  const lastContentRight =
+    (placedLanes[placedLanes.length - 1]?.box.x ?? DIAGRAM_MARGIN) +
+    LANE_PADDING_X +
+    LANE_CONTENT_WIDTH;
+  corridors.push({
+    left: lastContentRight,
+    right: lastContentRight + gutter + corridorExtra(placedLanes.length),
+  });
+
+  return {
+    // Whole numbers: the canvas is reported to the comment composer as pixels,
+    // and half a pixel of diagram is not a thing a reviewer can be shown.
+    width: Math.ceil(laneX - LANE_GAP + DIAGRAM_MARGIN),
+    height: Math.ceil(laneBottom + DIAGRAM_MARGIN),
+    lanes: placedLanes,
+    nodes: placedNodes,
+    grid: { rows: gridRows, corridors, laneBottom, deadFromRow: seating.deadFromRow },
+  };
+};
+
+/**
+ * The lane's own name over its band. Lanes never widen to fit their
+ * headers — that would put content in charge of where the next lane
+ * starts — so a header longer than the band gives up its tail instead.
+ */
+export const laneHeaderText = (lane: Lane): string => {
+  const full = (
+    lane.subtitle === undefined ? lane.label : `${lane.label} · ${lane.subtitle}`
+  ).toUpperCase();
+
+  return truncateTracked(full, LANE_LABEL_SIZE, LANE_LABEL_TRACKING, LANE_CONTENT_WIDTH);
+};
+
+const ELLIPSIS = "…";
+
+/** `truncate`, but counting the extra step letter-spacing puts after each glyph. */
+const truncateTracked = (
+  text: string,
+  fontSize: number,
+  tracking: number,
+  maxWidth: number,
+): string => {
+  const width = (value: string) => trackedWidth(value, "sans-bold", fontSize, tracking);
+  if (width(text) <= maxWidth) return text;
+
+  const characters = [...text];
+  let kept = 0;
+  while (kept < characters.length) {
+    const next = characters.slice(0, kept + 1).join("") + ELLIPSIS;
+    if (width(next) > maxWidth) break;
+    kept += 1;
+  }
+
+  return kept === 0 ? ELLIPSIS : characters.slice(0, kept).join("").trimEnd() + ELLIPSIS;
+};

package/src/layout/congestion.ts

@@ -0,0 +1,76 @@
+import type { LayoutHints } from "@coldtea/pr-lens-schema";
+import {
+  LANE_BOTTOM_PADDING,
+  LANE_GAP,
+  LANE_PADDING_X,
+  ROW_GAP,
+  TRACK_CLEARANCE,
+  TRACK_PITCH_MIN,
+} from "../design.js";
+import type { ScopedGraph } from "../scope.js";
+import {
+  layoutArchitecture,
+  type ArchitectureLayout,
+  type GapExpansions,
+  type LayoutGrid,
+} from "./architecture.js";
+import { channelTraffic, routeEdges, type ChannelTraffic, type RoutedEdge } from "./edges.js";
+
+/**
+ * Layout and routing with the pitch floor held: any gap whose traffic would
+ * compress its tracks below TRACK_PITCH_MIN is widened to exactly what that
+ * traffic needs, and the graph is laid out again around the wider gap. The
+ * extra room is a pure function of the traffic count, so one added route
+ * moves the lanes or rows beside a saturated gap by one pitch step — a small
+ * change staying a small move — and an uncrowded document is laid out
+ * exactly as if this pass did not exist.
+ */
+export const relieveCongestion = (
+  graph: ScopedGraph,
+  hints: LayoutHints | undefined,
+): { layout: ArchitectureLayout; routed: RoutedEdge[] } => {
+  let expansions: GapExpansions = { corridors: new Map(), bands: new Map() };
+  let layout = layoutArchitecture(graph, hints, expansions);
+
+  // Widening never changes which gaps the routes choose — plans are made of
+  // lane and row indices, and cards keep their in-lane positions — so the
+  // second round sees the same traffic and settles. The bound is a backstop.
+  for (let round = 0; round < 3; round += 1) {
+    const needed = expansionsFor(channelTraffic(graph.edges, layout), layout.grid);
+    if (sameExpansions(needed, expansions)) break;
+    expansions = needed;
+    layout = layoutArchitecture(graph, hints, expansions);
+  }
+
+  return { layout, routed: routeEdges(graph.edges, layout) };
+};
+
+/** Room for this many tracks at the floor pitch, plus clearance to the cards. */
+const widthNeeded = (traffic: number): number =>
+  (traffic - 1) * TRACK_PITCH_MIN + TRACK_CLEARANCE * 2;
+
+const CORRIDOR_WIDTH = LANE_PADDING_X * 2 + LANE_GAP;
+
+const expansionsFor = (traffic: ChannelTraffic, grid: LayoutGrid): GapExpansions => {
+  const corridors = new Map<number, number>();
+  for (const [index, count] of traffic.corridors) {
+    const extra = widthNeeded(count) - CORRIDOR_WIDTH;
+    if (extra > 0) corridors.set(index, extra);
+  }
+
+  const bands = new Map<number, number>();
+  for (const [index, count] of traffic.bands) {
+    // The band after the last row is the sliver of lane bottom padding.
+    const width = index === grid.rows.length ? LANE_BOTTOM_PADDING : ROW_GAP;
+    const extra = widthNeeded(count) - width;
+    if (extra > 0) bands.set(index, extra);
+  }
+
+  return { corridors, bands };
+};
+
+const sameExpansions = (a: GapExpansions, b: GapExpansions): boolean =>
+  sameEntries(a.corridors, b.corridors) && sameEntries(a.bands, b.bands);
+
+const sameEntries = (a: ReadonlyMap<number, number>, b: ReadonlyMap<number, number>): boolean =>
+  a.size === b.size && [...a].every(([key, value]) => b.get(key) === value);