@coldtea/pr-lens-renderer 0.1.0

package/src/svg/icons.ts

@@ -0,0 +1,121 @@
+import type { NodeKind } from "@coldtea/pr-lens-schema";
+import { assertNever } from "@coldtea/pr-lens-schema";
+import { coord } from "../geometry.js";
+import { MONO_STACK } from "../text.js";
+import { lines, tag, textNode, wrap } from "./primitives.js";
+
+const stroked = (path: string): string => tag("path", { class: "glyph-stroke", d: path });
+
+const glyphText = (cx: number, cy: number, content: string, style: string): string =>
+  textNode(
+    {
+      class: "glyph",
+      x: coord(cx),
+      y: coord(cy + 4.5),
+      "text-anchor": "middle",
+      style,
+    },
+    content,
+  );
+
+const box = (cx: number, cy: number, width: number, height: number, radius?: number): string =>
+  tag("rect", {
+    class: "glyph-stroke",
+    x: coord(cx - width / 2),
+    y: coord(cy - height / 2),
+    width: coord(width),
+    height: coord(height),
+    rx: radius === undefined ? undefined : coord(radius),
+  });
+
+/**
+ * The chip glyph for a node's kind, centred on a point.
+ *
+ * These say "what sort of thing is this" at a glance and nothing more, which
+ * is why the kind enum is coarse. Every kind draws something: a card with an
+ * empty chip reads as a rendering fault rather than as an unknown kind.
+ */
+const kindGlyph = (kind: NodeKind, cx: number, cy: number): string => {
+  switch (kind) {
+    case "service":
+      return lines([
+        box(cx, cy, 13, 13, 3),
+        tag("circle", { class: "glyph", cx: coord(cx), cy: coord(cy), r: 2 }),
+      ]);
+    case "app":
+      return lines([
+        box(cx, cy, 14, 12, 2),
+        stroked(`M${coord(cx - 7)},${coord(cy - 2)} h14`),
+      ]);
+    case "module":
+      return glyphText(cx, cy, "{ }", `font-size:11px;font-family:${MONO_STACK}`);
+    case "function":
+      return glyphText(cx, cy, "ƒ", "font-size:14px;font-style:italic;font-family:Georgia,serif");
+    case "route":
+      return tag("path", {
+        class: "glyph",
+        d: `M${coord(cx - 7)},${coord(cy - 6)} L${coord(cx + 7)},${coord(cy)} L${coord(cx - 7)},${coord(cy + 6)} Z`,
+      });
+    case "job":
+      return lines([
+        tag("circle", { class: "glyph-stroke", cx: coord(cx), cy: coord(cy), r: 6.5 }),
+        stroked(`M${coord(cx)},${coord(cy - 3.5)} V${coord(cy)} H${coord(cx + 3)}`),
+      ]);
+    case "queue":
+      return lines([
+        stroked(`M${coord(cx - 6.5)},${coord(cy - 4.5)} h13`),
+        stroked(`M${coord(cx - 6.5)},${coord(cy)} h13`),
+        stroked(`M${coord(cx - 6.5)},${coord(cy + 4.5)} h13`),
+      ]);
+    case "datastore":
+      return lines([
+        tag("ellipse", { class: "glyph-stroke", cx: coord(cx), cy: coord(cy - 4.5), rx: 6.5, ry: 2.6 }),
+        stroked(
+          `M${coord(cx - 6.5)},${coord(cy - 4.5)} v9 a6.5,2.6 0 0 0 13 0 v-9`,
+        ),
+      ]);
+    case "cache":
+      return tag("path", {
+        class: "glyph",
+        d: `M${coord(cx + 1)},${coord(cy - 7)} L${coord(cx - 6)},${coord(cy + 1)} H${coord(cx - 1)} L${coord(cx - 1)},${coord(cy + 7)} L${coord(cx + 6)},${coord(cy - 1)} H${coord(cx + 1)} Z`,
+      });
+    case "external":
+      return lines([
+        box(cx, cy, 16, 12, 2),
+        stroked(`M${coord(cx - 8)},${coord(cy - 4)} l8,6 8,-6`),
+      ]);
+    case "ui":
+      return lines([
+        box(cx, cy, 14, 12, 2),
+        stroked(`M${coord(cx - 2.5)},${coord(cy - 6)} v12`),
+      ]);
+    case "config":
+      return lines([
+        stroked(`M${coord(cx - 7)},${coord(cy - 4)} h14`),
+        stroked(`M${coord(cx - 7)},${coord(cy + 4)} h14`),
+        tag("circle", { class: "glyph", cx: coord(cx - 2), cy: coord(cy - 4), r: 2.2 }),
+        tag("circle", { class: "glyph", cx: coord(cx + 3), cy: coord(cy + 4), r: 2.2 }),
+      ]);
+    case "test":
+      return stroked(`M${coord(cx - 6)},${coord(cy)} l4,4 l8,-8`);
+    case "package":
+      return lines([
+        stroked(
+          `M${coord(cx)},${coord(cy - 7)} l6.5,3.5 v7 l-6.5,3.5 l-6.5,-3.5 v-7 Z`,
+        ),
+        stroked(`M${coord(cx - 6.5)},${coord(cy - 3.5)} l6.5,3.5 l6.5,-3.5`),
+        stroked(`M${coord(cx)},${coord(cy)} v7`),
+      ]);
+    case "other":
+      return lines([
+        tag("circle", { class: "glyph", cx: coord(cx - 5), cy: coord(cy), r: 1.8 }),
+        tag("circle", { class: "glyph", cx: coord(cx), cy: coord(cy), r: 1.8 }),
+        tag("circle", { class: "glyph", cx: coord(cx + 5), cy: coord(cy), r: 1.8 }),
+      ]);
+    default:
+      return assertNever(kind, "Unhandled node kind");
+  }
+};
+
+export const glyphGroup = (kind: NodeKind, cx: number, cy: number): string =>
+  wrap("g", {}, kindGlyph(kind, cx, cy));

package/src/svg/primitives.ts

@@ -0,0 +1,50 @@
+/**
+ * Code points XML 1.0 has no spelling for: most control characters, the
+ * surrogate halves, and the two non-characters at the end of the basic plane.
+ * They are dropped rather than escaped, because there is no escape — a
+ * document containing one is not merely ugly, it does not parse.
+ *
+ * Labels reach here from an extraction model by way of the schema, which
+ * constrains their length but not their alphabet, so this is the last place
+ * such a character can be stopped. Matching by code point rather than by code
+ * unit is what keeps a well-formed astral character — which is a pair of
+ * surrogates in memory — from being mistaken for two lone halves.
+ */
+const FORBIDDEN_IN_XML =
+  /[\u0000-\u0008\u000B\u000C\u000E-\u001F\uD800-\uDFFF\uFFFE\uFFFF]/gu;
+
+/**
+ * XML escaping for text nodes and attribute values alike. Attributes are
+ * always written in double quotes, so the single quote does not need an
+ * entity, but `<` and `&` do in both positions.
+ */
+export const escapeXml = (value: string): string =>
+  value
+    .replace(FORBIDDEN_IN_XML, "")
+    .replace(/&/g, "&amp;")
+    .replace(/</g, "&lt;")
+    .replace(/>/g, "&gt;")
+    .replace(/"/g, "&quot;");
+
+export type Attributes = Readonly<Record<string, string | number | undefined>>;
+
+const serialiseAttributes = (attributes: Attributes): string =>
+  Object.entries(attributes)
+    .filter((entry): entry is [string, string | number] => entry[1] !== undefined)
+    .map(([name, value]) => ` ${name}="${escapeXml(String(value))}"`)
+    .join("");
+
+export const tag = (name: string, attributes: Attributes): string =>
+  `<${name}${serialiseAttributes(attributes)}/>`;
+
+export const wrap = (name: string, attributes: Attributes, children: string): string =>
+  `<${name}${serialiseAttributes(attributes)}>${children}</${name}>`;
+
+export const textNode = (
+  attributes: Attributes,
+  content: string,
+): string => wrap("text", attributes, escapeXml(content));
+
+/** Joins emitted fragments with newlines, dropping the ones that produced nothing. */
+export const lines = (fragments: readonly string[]): string =>
+  fragments.filter((fragment) => fragment.length > 0).join("\n");

package/src/svg/pulse.ts

@@ -0,0 +1,48 @@
+import { HERO_PULSE_DURATION, PULSE_DURATION } from "../design.js";
+import { coord } from "../geometry.js";
+import { lines, tag, wrap } from "./primitives.js";
+
+/**
+ * The travelling pulse: the mark that says a connection carries traffic
+ * rather than merely existing. Both lenses draw it from here, because a
+ * reader moving between them is reading one language — an architecture edge
+ * and a sequence message differ in what they connect, not in how they live.
+ *
+ * A line running behind the drawing's clock says so with a negative `begin`,
+ * which starts its motion that far into its own turn. A positive delay would
+ * describe the same steady state and lie for the seconds after load: an
+ * animation has no effect before it begins, so the dot waiting for its turn
+ * would sit at the canvas origin, in the corner, in full view.
+ */
+/** The dot itself, so both lenses draw the same mark whatever clock moves it. */
+export const PULSE_RADIUS = 2.6;
+export const TRAIN_RADIUS = 3;
+
+export const travellingPulses = (pulse: {
+  path: string;
+  colour: string;
+  /** Dots riding this line at once, spread evenly around the turn. */
+  count: number;
+  /** How far this line runs behind the drawing's clock, in seconds. */
+  lag: number;
+}): string => {
+  const { path, colour, count, lag } = pulse;
+  const train = count > 1;
+  const duration = train ? HERO_PULSE_DURATION : PULSE_DURATION;
+
+  return lines(
+    Array.from({ length: count }, (_, index) => {
+      const behind = (lag + (duration / count) * index) % duration;
+      return wrap(
+        "circle",
+        { r: train ? TRAIN_RADIUS : PULSE_RADIUS, fill: colour },
+        tag("animateMotion", {
+          dur: `${coord(duration)}s`,
+          begin: behind === 0 ? undefined : `${coord(behind - duration)}s`,
+          repeatCount: "indefinite",
+          path,
+        }),
+      );
+    }),
+  );
+};

package/src/text.ts

@@ -0,0 +1,92 @@
+import { assertNever } from "@coldtea/pr-lens-schema";
+
+/**
+ * The renderer never asks a font engine how wide a string is: it must produce
+ * the same geometry on a CI runner with no fonts installed as on a laptop
+ * with all of them. Widths come from a table instead, and every box is sized
+ * with enough slack that the small error against a real face stays invisible.
+ */
+export type Face = "sans" | "sans-bold" | "mono";
+
+export const SANS_STACK =
+  '-apple-system, BlinkMacSystemFont, "Segoe UI", "Noto Sans", Helvetica, Arial, sans-serif';
+export const MONO_STACK =
+  'ui-monospace, SFMono-Regular, "SF Mono", Menlo, Consolas, monospace';
+
+/** Advance widths per 1000 units of em, for the regular sans face. */
+const SANS_ADVANCE: Readonly<Record<string, number>> = {
+  " ": 278, "!": 278, '"': 355, "#": 556, $: 556, "%": 889, "&": 667, "'": 191,
+  "(": 333, ")": 333, "*": 389, "+": 584, ",": 278, "-": 333, ".": 278, "/": 278,
+  "0": 556, "1": 556, "2": 556, "3": 556, "4": 556, "5": 556, "6": 556, "7": 556,
+  "8": 556, "9": 556, ":": 278, ";": 278, "<": 584, "=": 584, ">": 584, "?": 556,
+  "@": 1015, A: 667, B: 667, C: 722, D: 722, E: 667, F: 611, G: 778, H: 722,
+  I: 278, J: 500, K: 667, L: 556, M: 833, N: 722, O: 778, P: 667, Q: 778, R: 722,
+  S: 667, T: 611, U: 722, V: 667, W: 944, X: 667, Y: 667, Z: 611, "[": 278,
+  "\\": 278, "]": 278, "^": 469, _: 556, "`": 333, a: 556, b: 556, c: 500, d: 556,
+  e: 556, f: 278, g: 556, h: 556, i: 222, j: 222, k: 500, l: 222, m: 833, n: 556,
+  o: 556, p: 556, q: 556, r: 333, s: 500, t: 278, u: 556, v: 500, w: 722, x: 500,
+  y: 500, z: 500, "{": 334, "|": 260, "}": 334, "~": 584,
+};
+
+/** What a character outside the table is assumed to cost, in the same units. */
+const FALLBACK_ADVANCE = 600;
+
+/**
+ * The bold face of the same family runs a little wider at every weight step.
+ * One factor over the regular table is close enough for boxes that already
+ * carry padding, and it keeps a second table from drifting out of sync.
+ */
+const BOLD_WIDENING = 1.06;
+
+const MONO_ADVANCE = 600;
+
+const advanceFor = (face: Face, character: string): number => {
+  switch (face) {
+    case "sans":
+      return SANS_ADVANCE[character] ?? FALLBACK_ADVANCE;
+    case "sans-bold":
+      return (SANS_ADVANCE[character] ?? FALLBACK_ADVANCE) * BOLD_WIDENING;
+    case "mono":
+      return MONO_ADVANCE;
+    default:
+      return assertNever(face, "Unhandled font face");
+  }
+};
+
+/** Width of `text` in user units at `fontSize`, to a hundredth of a unit. */
+export const measure = (text: string, face: Face, fontSize: number): number => {
+  let thousandths = 0;
+  for (const character of text) thousandths += advanceFor(face, character);
+  return Math.round((thousandths / 1000) * fontSize * 100) / 100;
+};
+
+const ELLIPSIS = "…";
+
+/**
+ * Shortens `text` until it fits `maxWidth`, ellipsis included. Cutting by
+ * code point rather than by UTF-16 unit keeps a surrogate pair from being
+ * split into a replacement character.
+ */
+export const truncate = (
+  text: string,
+  face: Face,
+  fontSize: number,
+  maxWidth: number,
+): string => {
+  if (measure(text, face, fontSize) <= maxWidth) return text;
+
+  const characters = [...text];
+  const ellipsisWidth = measure(ELLIPSIS, face, fontSize);
+  let width = 0;
+  let kept = 0;
+
+  for (const character of characters) {
+    const next = width + measure(character, face, fontSize);
+    if (next + ellipsisWidth > maxWidth) break;
+    width = next;
+    kept += 1;
+  }
+
+  if (kept === 0) return ELLIPSIS;
+  return `${characters.slice(0, kept).join("").trimEnd()}${ELLIPSIS}`;
+};

package/src/theme.ts

@@ -0,0 +1,107 @@
+import { assertNever, THEMES, type Theme } from "@coldtea/pr-lens-schema";
+
+/**
+ * The two halves of a GitHub `<picture>` pair. A comment ships both and the
+ * client picks; neither half may depend on the page it lands in, because an
+ * SVG served as an image cannot see it.
+ *
+ * The contract owns the pair, because the number of themes is one half of the
+ * arithmetic that bounds a document's view tree. Re-exported here so a caller
+ * rendering a diagram does not have to reach into the schema for it.
+ */
+export { THEMES, type Theme };
+
+/**
+ * Every colour the renderer can paint, resolved to a literal before it
+ * reaches the document. CSS custom properties would be shorter, but GitHub
+ * serves these files through an image proxy where nothing outside the file
+ * exists, so the palette is baked in per theme.
+ */
+export type Palette = {
+  background: string;
+  dot: string;
+  lane: string;
+  card: string;
+  cardBorder: string;
+  foreground: string;
+  muted: string;
+  edge: string;
+  chip: string;
+  pill: string;
+  pillBorder: string;
+  lifeline: string;
+  added: string;
+  addedFill: string;
+  addedBorder: string;
+  modified: string;
+  modifiedFill: string;
+  modifiedBorder: string;
+  removed: string;
+  removedFill: string;
+  removedBorder: string;
+  neutralFill: string;
+  shadow: string;
+};
+
+const LIGHT: Palette = {
+  background: "#ffffff",
+  dot: "rgba(140,149,159,.35)",
+  lane: "#f6f8fa",
+  card: "#ffffff",
+  cardBorder: "#d1d9e0",
+  foreground: "#1f2328",
+  muted: "#59636e",
+  edge: "#8c959f",
+  chip: "#f6f8fa",
+  pill: "#ffffff",
+  pillBorder: "#d8dee4",
+  lifeline: "#d1d9e0",
+  added: "#1a7f37",
+  addedFill: "#dafbe1",
+  addedBorder: "rgba(31,136,61,.4)",
+  modified: "#9a6700",
+  modifiedFill: "#fff8c5",
+  modifiedBorder: "rgba(154,103,0,.35)",
+  removed: "#d1242f",
+  removedFill: "#ffebe9",
+  removedBorder: "rgba(209,36,47,.35)",
+  neutralFill: "#f6f8fa",
+  shadow: "rgba(31,35,40,.14)",
+};
+
+const DARK: Palette = {
+  background: "#0d1117",
+  dot: "rgba(110,118,129,.22)",
+  lane: "rgba(110,118,129,.07)",
+  card: "#1c2128",
+  cardBorder: "#3d444d",
+  foreground: "#e6edf3",
+  muted: "#9198a1",
+  edge: "#6e7681",
+  chip: "rgba(110,118,129,.18)",
+  pill: "#0d1117",
+  pillBorder: "#21262d",
+  lifeline: "#30363d",
+  added: "#3fb950",
+  addedFill: "rgba(46,160,67,.15)",
+  addedBorder: "rgba(63,185,80,.4)",
+  modified: "#d29922",
+  modifiedFill: "rgba(187,128,9,.15)",
+  modifiedBorder: "rgba(210,153,34,.4)",
+  removed: "#f85149",
+  removedFill: "rgba(248,81,73,.12)",
+  removedBorder: "rgba(248,81,73,.4)",
+  neutralFill: "rgba(110,118,129,.18)",
+  shadow: "rgba(0,0,0,.28)",
+};
+
+export const paletteFor = (theme: Theme): Palette => {
+  switch (theme) {
+    case "light":
+      return LIGHT;
+    case "dark":
+      return DARK;
+    default:
+      return assertNever(theme, "Unhandled theme");
+  }
+};

package/src/version.ts

@@ -0,0 +1,9 @@
+/**
+ * Stamped into every render manifest so a stored diagram can be traced to the
+ * code that drew it. Kept in step with package.json by a test, since a
+ * package cannot read its own manifest without doing I/O the renderer does
+ * not otherwise need.
+ */
+export const RENDERER_NAME = "@coldtea/pr-lens-renderer";
+
+export const RENDERER_VERSION = "0.1.0";