render-diagram-draw.mjs

Functions

Imports

It imports render-diagram.mjs. No module of this repo imports it.

Source

1// Draws the assets render-diagram.mjs names: one SVG per theme, ahead of time, in Node. Layout needs real font metrics, so
2// this drives Mermaid's own renderer in a headless browser; the site build then only reads the committed files. Each site
3// gives its colours by role; the role map, Mermaid's configuration, the drawing and the colour audit are shared here.
4
5import { existsSync } from "node:fs";
6import { mkdir, readdir, unlink, writeFile } from "node:fs/promises";
7import { basename, join } from "node:path";
8
9import { renderMermaid } from "@mermaid-js/mermaid-cli";
10import { parseHTML } from "linkedom";
11import puppeteer from "puppeteer";
12
13import { DIAGRAM_THEMES, diagramAssetPath } from "./render-diagram.mjs";
14
15/**
16 * Every Mermaid theme variable a diagram paints with, by the role its colour plays. Everything khroma would otherwise
17 * derive is supplied; what is not still gets derived, which is why every drawing is audited rather than trusting this
18 * list to be complete.
19 */
20export const DIAGRAM_ROLES = {
21  background: "paper",
22  primaryColor: "paper",
23  primaryBorderColor: "borderStrong",
24  primaryTextColor: "text",
25  secondaryColor: "raised",
26  secondaryBorderColor: "border",
27  secondaryTextColor: "text",
28  tertiaryColor: "tint",
29  tertiaryBorderColor: "border",
30  tertiaryTextColor: "text",
31  lineColor: "borderStrong",
32  textColor: "text",
33  titleColor: "heading",
34  errorBkgColor: "dangerTint",
35  errorTextColor: "danger",
36
37  mainBkg: "paper",
38  nodeBorder: "borderStrong",
39  nodeTextColor: "text",
40  clusterBkg: "tint",
41  clusterBorder: "border",
42  // An edge crosses page background, so the label plate must match it or the line shows through.
43  edgeLabelBackground: "paper",
44  arrowheadColor: "borderStrong",
45
46  actorBkg: "paper",
47  actorBorder: "borderStrong",
48  actorTextColor: "text",
49  actorLineColor: "border",
50  signalColor: "borderStrong",
51  signalTextColor: "text",
52  labelBoxBkgColor: "paper",
53  labelBoxBorderColor: "borderStrong",
54  labelTextColor: "text",
55  loopTextColor: "text",
56  noteBkgColor: "raised",
57  noteBorderColor: "border",
58  noteTextColor: "text",
59  activationBkgColor: "raised",
60  activationBorderColor: "borderStrong",
61  sequenceNumberColor: "onAccent",
62  altBackground: "paper",
63};
64
65/** The roles a site must colour, each once per theme. */
66export const DIAGRAM_ROLE_NAMES = [...new Set(Object.values(DIAGRAM_ROLES))];
67
68/**
69 * An SVG inside an `<img>` may not load external resources, so the viewer's font may differ from the one the drawing was
70 * measured with, which is why the padding below is generous.
71 */
72const FONT_FAMILY = 'ui-sans-serif, system-ui, -apple-system, "Segoe UI", Roboto, sans-serif';
73
74/** Set explicitly so the bytes do not move if the tool's default does. */
75const SVG_ID = "diagram";
76
77/** Fixed, so nothing about the output depends on the machine it was built on. */
78const VIEWPORT = { width: 1200, height: 800, deviceScaleFactor: 1 };
79
80/**
81 * @param {"light" | "dark"} theme
82 * @param {Record<string, string>} colours one hex colour per name in DIAGRAM_ROLE_NAMES
83 */
84export function mermaidConfig(theme, colours) {
85  const missing = DIAGRAM_ROLE_NAMES.filter((role) => !/^#[0-9a-f]{3}(?:[0-9a-f]{3})?$/i.test(colours[role] ?? ""));
86  if (missing.length > 0) throw new Error(`the ${theme} diagram colours lack a hex colour for ${missing.join(", ")}`);
87  /** @type {Record<string, string | boolean>} */
88  const themeVariables = { darkMode: theme === "dark", fontFamily: FONT_FAMILY };
89  for (const [variable, role] of Object.entries(DIAGRAM_ROLES)) themeVariables[variable] = /** @type {string} */ (colours[role]);
90  return {
91    // "base" is the only built-in theme whose variables are fully overridable; every other one hardcodes part of its palette.
92    theme: "base",
93    themeVariables,
94    // Labels as real text, never `<foreignObject>`: a foreignObject is not rendered at all through `<img>`, so every node
95    // would come out blank on the page while looking correct standalone.
96    htmlLabels: false,
97    flowchart: { htmlLabels: false, padding: 12, useMaxWidth: false },
98    // Tightened from the defaults, for layout rather than taste: a wider drawing is scaled down and takes its type with
99    // it, and narrowing the gaps shrinks the drawing without shrinking the text.
100    sequence: {
101      useMaxWidth: false,
102      wrap: false,
103      actorMargin: 24,
104      width: 120,
105      boxMargin: 8,
106      noteMargin: 8,
107      messageMargin: 28,
108      // The mirrored row of actors at the foot repeats what the head already said and costs height a figure cannot spare.
109      mirrorActors: false,
110    },
111  };
112}
113
114/**
115 * Inside an `<img>` a percentage width means no intrinsic width, so the viewBox size is copied onto the root. A targeted
116 * rewrite rather than re-serializing, because an `.svg` is parsed strictly.
117 *
118 * @param {string} svg
119 * @param {string} label
120 */
121function sizeRoot(svg, label) {
122  const openTag = svg.match(/<svg\b[^>]*>/)?.[0];
123  if (!openTag) throw new Error(`${label}: no <svg> root tag`);
124  const viewBox = openTag.match(/viewBox="([\d.\-\s]+)"/)?.[1];
125  if (!viewBox) throw new Error(`${label}: root <svg> has no viewBox to size from`);
126  const [, , width = 0, height = 0] = viewBox.trim().split(/\s+/).map(Number);
127  if (!Number.isFinite(width) || !Number.isFinite(height) || width <= 0 || height <= 0) {
128    throw new Error(`${label}: viewBox "${viewBox}" has no usable size`);
129  }
130  const rewritten = openTag
131    .replace(/\swidth="[^"]*"/, "")
132    .replace(/\sheight="[^"]*"/, "")
133    .replace(/max-width:\s*[^;"]+;?\s*/, "")
134    .replace(/<svg\b/, `<svg width="${Math.ceil(width)}" height="${Math.ceil(height)}"`);
135  return svg.replace(openTag, rewritten);
136}
137
138/**
139 * Draws what is missing (or everything, with `force`), audits each drawing before writing it, and deletes nothing: it
140 * returns the files no diagram names, for the caller to prune by its own rules. The browser is only launched when there
141 * is something to draw, so a build with every asset current needs no Chromium. PUPPETEER_EXECUTABLE_PATH points
142 * Puppeteer at an installed Chromium; MERMAID_PUPPETEER_CONFIG is JSON launch options, for example
143 * {"args":["--no-sandbox"]} in a container that runs as root.
144 *
145 * @param {{
146 *   diagrams: Array<{ key: string, source: string, label?: string }>,
147 *   dir: string,
148 *   assetPrefix: string,
149 *   colours: Record<"light" | "dark", Record<string, string>>,
150 *   force?: boolean,
151 *   log?: (line: string) => void,
152 * }} options
153 * @returns {Promise<{ written: string[], current: number, stale: string[] }>}
154 */
155export async function drawDiagrams({ diagrams, dir, assetPrefix, colours, force = false, log = console.log }) {
156  const themes = /** @type {Array<"light" | "dark">} */ (DIAGRAM_THEMES);
157  const configs = { light: mermaidConfig("light", colours.light), dark: mermaidConfig("dark", colours.dark) };
158  const fileName = (/** @type {string} */ key, /** @type {string} */ theme) => basename(diagramAssetPath(key, theme, assetPrefix));
159
160  await mkdir(dir, { recursive: true });
161  const outstanding = diagrams.flatMap((diagram) =>
162    themes.filter((theme) => force || !existsSync(join(dir, fileName(diagram.key, theme)))).map((theme) => ({ diagram, theme })),
163  );
164
165  /** @type {string[]} */
166  const written = [];
167  const launchOptions = process.env.MERMAID_PUPPETEER_CONFIG ? JSON.parse(process.env.MERMAID_PUPPETEER_CONFIG) : {};
168  const browser = outstanding.length > 0 ? await puppeteer.launch(launchOptions) : null;
169  try {
170    for (const { diagram, theme } of outstanding) {
171      const name = fileName(diagram.key, theme);
172      const label = `${name}${diagram.label ? ` (${diagram.label})` : ""}`;
173      // The renderer's API rather than its command line: Node will not spawn the shim without a shell, and a shell joins
174      // an argument array without quoting.
175      const { data } = await renderMermaid(/** @type {import("puppeteer").Browser} */ (browser), diagram.source, "svg", {
176        backgroundColor: "transparent",
177        mermaidConfig: /** @type {any} */ (configs[theme]),
178        svgId: SVG_ID,
179        viewport: VIEWPORT,
180      });
181      const svg = sizeRoot(Buffer.from(data).toString("utf8"), label);
182      // Audited before it is written, so a colour Mermaid derived rather than took from the palette stops the build
183      // instead of shipping.
184      const audit = auditDiagramSvg(svg, Object.values(colours[theme]));
185      if (audit.problems.length > 0) {
186        throw new Error(`${label} uses colours that are not the site's:\n${audit.problems.map((p) => `    ${p}`).join("\n")}`);
187      }
188      await writeFile(join(dir, name), svg, "utf8");
189      written.push(name);
190      log(`  wrote ${name} (${Math.round(svg.length / 1024)} kB, ${audit.checked} colours checked)`);
191    }
192  } finally {
193    await browser?.close();
194  }
195
196  const live = new Set(diagrams.flatMap((d) => themes.map((t) => fileName(d.key, t))));
197  const stale = (await readdir(dir)).filter((name) => name.endsWith(".svg") && !live.has(name));
198  return { written, current: diagrams.length * themes.length - outstanding.length, stale };
199}
200
201/**
202 * Deletes the named files from `dir`.
203 *
204 * @param {string} dir
205 * @param {string[]} names
206 */
207export async function pruneDiagrams(dir, names) {
208  for (const name of names) await unlink(join(dir, name));
209}
210
211const COLOUR_PROPERTIES = new Set([
212  "fill",
213  "stroke",
214  "color",
215  "background",
216  "background-color",
217  "stop-color",
218  "flood-color",
219  "border",
220  "border-color",
221  "outline",
222  "outline-color",
223]);
224
225// `currentColor` is safe because it resolves to `color`, which is itself audited.
226const NON_COLOUR_VALUES = new Set(["none", "transparent", "currentcolor", "inherit", "initial", "unset", "revert"]);
227
228/** @param {string} hex */
229function normalizeHex(hex) {
230  const h = hex.toLowerCase();
231  return h.length === 4 ? `#${h[1]}${h[1]}${h[2]}${h[2]}${h[3]}${h[3]}` : h;
232}
233
234/**
235 * By brace depth, not splitting on `}`: Mermaid's stylesheet opens with nested at-rules. Unbalanced braces throw: a stray
236 * `}` drove the depth negative and every later rule was silently lost.
237 *
238 * @param {string} text
239 * @returns {Array<{ selector: string, body: string }>}
240 */
241function cssRules(text) {
242  /** @type {Array<{ selector: string, body: string }>} */
243  const out = [];
244  let depth = 0;
245  let start = 0;
246  let selectorEnd = -1;
247  for (let i = 0; i < text.length; i += 1) {
248    const c = text[i];
249    if (c === "{") {
250      if (depth === 0) selectorEnd = i;
251      depth += 1;
252    } else if (c === "}") {
253      depth -= 1;
254      if (depth < 0) throw new Error(`unbalanced stylesheet: a "}" at offset ${i} closes nothing`);
255      if (depth === 0) {
256        out.push({ selector: text.slice(start, selectorEnd).trim(), body: text.slice(selectorEnd + 1, i) });
257        start = i + 1;
258      }
259    }
260  }
261  if (depth !== 0) throw new Error(`unbalanced stylesheet: ${depth} "{" never closed`);
262  return out;
263}
264
265/** At-rules whose body is more rules, applied when a condition holds, so their rules are audited. */
266const GROUPING_AT_RULES = /^@(media|supports|layer|container|document|scope)\b/i;
267
268/** @param {string} body */
269function colourDeclarations(body) {
270  /** @type {Array<{ property: string, value: string }>} */
271  const out = [];
272  for (const m of body.matchAll(/([a-zA-Z-]+)\s*:\s*([^;{}]+)/g)) {
273    const property = (m[1] ?? "").toLowerCase();
274    if (COLOUR_PROPERTIES.has(property)) out.push({ property, value: (m[2] ?? "").trim() });
275  }
276  return out;
277}
278
279/**
280 * Allowlist, not a hex hunt, so rgb(), hsl() and named colours are caught too.
281 *
282 * @param {string} value
283 * @param {Set<string>} palette
284 */
285function colourProblem(value, palette) {
286  const cleaned = value.replace(/!important/gi, "").trim();
287  const lower = cleaned.toLowerCase();
288  if (cleaned === "" || NON_COLOUR_VALUES.has(lower) || lower.startsWith("url(")) return null;
289  if (/^#[0-9a-fA-F]{3}(?:[0-9a-fA-F]{3})?$/.test(cleaned)) {
290    return palette.has(normalizeHex(cleaned)) ? null : `${cleaned} is not one of the palette's colours`;
291  }
292  return `${cleaned} is not a palette colour`;
293}
294
295/**
296 * Every colour a drawing can paint must be one of the palette's: in its `<style>` (rules inside conditional group rules
297 * included, `@keyframes` audited whole, a rule no element matches skipped and counted), in `style` attributes, and in
298 * presentation attributes no stylesheet rule overrides, on every element except unreferenced `<defs>` children.
299 *
300 * @param {string} svg
301 * @param {string[]} paletteHexes
302 * @returns {{ checked: number, skippedRules: number, overridden: number, problems: string[] }}
303 */
304export function auditDiagramSvg(svg, paletteHexes) {
305  const palette = new Set(paletteHexes.map(normalizeHex));
306  const { document } = parseHTML(`<!DOCTYPE html><html><body>${svg}</body></html>`);
307  const root = document.querySelector("svg");
308  if (!root) return { checked: 0, skippedRules: 0, overridden: 0, problems: ["no <svg> element"] };
309
310  /** @type {string[]} */
311  const problems = [];
312  let checked = 0;
313  let skippedRules = 0;
314  let overridden = 0;
315  /** @type {Array<{ selectors: string[], properties: Set<string> }>} */
316  const styling = [];
317
318  /**
319   * @param {string} where
320   * @param {Array<{ property: string, value: string }>} declarations
321   */
322  const check = (where, declarations) => {
323    for (const { property, value } of declarations) {
324      checked += 1;
325      const problem = colourProblem(value, palette);
326      if (problem) problems.push(`${where} ${property}: ${problem}`);
327    }
328  };
329
330  /** @param {string} text */
331  const auditRules = (text) => {
332    for (const rule of cssRules(text)) {
333      if (GROUPING_AT_RULES.test(rule.selector)) {
334        auditRules(rule.body);
335        continue;
336      }
337      const declarations = colourDeclarations(rule.body);
338      if (declarations.length === 0) continue;
339      if (rule.selector.startsWith("@")) {
340        check(rule.selector, declarations);
341        continue;
342      }
343      const selectors = rule.selector.split(",").map((s) => s.trim()).filter(Boolean);
344      styling.push({ selectors, properties: new Set(declarations.map((d) => d.property)) });
345      const reachable = selectors.some((one) => {
346        try {
347          return Boolean(document.querySelector(one));
348        } catch {
349          // Unparseable selectors count as reachable, so the rule is audited rather than skipped.
350          return true;
351        }
352      });
353      if (reachable) check(rule.selector, declarations);
354      else skippedRules += 1;
355    }
356  };
357  for (const style of document.querySelectorAll("style")) auditRules(style.textContent ?? "");
358
359  // Unreferenced <defs> children, and everything under them, are never painted. A reference is url(#id) (markers,
360  // gradients) or an href to #id (<use>), and both keep the target audited.
361  const serialized = root.toString();
362  const all = [root, ...root.querySelectorAll("*")];
363  const hrefs = new Set(
364    all.flatMap((el) => ["href", "xlink:href"].map((n) => el.getAttribute(n) ?? "")).filter((v) => v.startsWith("#")).map((v) => v.slice(1)),
365  );
366  const dead = new Set();
367  for (const defs of document.querySelectorAll("defs")) {
368    for (const child of defs.children) {
369      const id = child.getAttribute("id");
370      if (!id || (!serialized.includes(`url(#${id})`) && !hrefs.has(id))) {
371        for (const el of [child, ...child.querySelectorAll("*")]) dead.add(el);
372      }
373    }
374  }
375
376  /**
377   * A presentation attribute a stylesheet rule overrides is never painted.
378   *
379   * @param {any} element
380   * @param {string} property
381   */
382  const styledBy = (element, property) =>
383    styling.some(
384      (rule) =>
385        rule.properties.has(property) &&
386        rule.selectors.some((selector) => {
387          try {
388            return element.matches(selector);
389          } catch {
390            return false;
391          }
392        }),
393    );
394
395  // The root carries attributes too: Mermaid writes its background into `style`.
396  for (const element of all) {
397    if (dead.has(element)) continue;
398    for (const attribute of element.attributes) {
399      const name = attribute.name.toLowerCase();
400      if (name === "style") check(`<${element.localName} style>`, colourDeclarations(attribute.value));
401      else if (!COLOUR_PROPERTIES.has(name)) continue;
402      else if (styledBy(element, name)) overridden += 1;
403      else check(`<${element.localName}>`, [{ property: name, value: attribute.value }]);
404    }
405  }
406
407  return { checked, skippedRules, overridden, problems };
408}