@jpeakai/mermaidjs-lint 0.4.2 → 0.5.0

package/dist/testing.js

@@ -215,6 +215,7 @@ var getMermaid = async () => {
   mermaidCore = (await import("mermaid")).default;
   return mermaidCore;
 };
+var getMermaidCore = async () => await getMermaid();
 var LANGIUM_TYPES = {
   "architecture-beta": "architecture",
   architecture: "architecture",
@@ -1070,6 +1071,139 @@ var scoreForProfile = (directives, profile, keyword) => {
     return scoreMkdocs(directives);
   return keyword === "erDiagram" ? scoreEr(directives) : scoreGithub(directives);
 };
+var SEQUENCE_THEMES = ["base", "default", "dark", "forest", "neutral"];
+var LINE = { NOTE: 2, ACTIVE_START: 17, RECT_START: 22, AUTONUMBER: 26 };
+var FRAME_STARTS = new Set([10, 12, 15, 19, 27, 30, 32]);
+var sequenceFeatures = (db) => {
+  const messages = db.getMessages();
+  const has = (type) => messages.some((m) => m.type === type);
+  return {
+    humanActor: [...db.getActors().values()].some((a) => a.type === "actor"),
+    note: has(LINE.NOTE),
+    frame: messages.some((m) => FRAME_STARTS.has(m.type)),
+    activation: has(LINE.ACTIVE_START),
+    numbered: messages.some((m) => m.type === LINE.AUTONUMBER && m.message?.visible !== false),
+    rects: messages.filter((m) => m.type === LINE.RECT_START).map((m) => String(m.message))
+  };
+};
+var resolveVariables = (mermaid, config, themes) => {
+  const prior = mermaid.mermaidAPI.getSiteConfig();
+  try {
+    const out = {};
+    for (const t of THEMES) {
+      mermaid.initialize({ ...structuredClone(config), theme: themes[t] });
+      out[t] = { ...mermaid.mermaidAPI.getSiteConfig().themeVariables };
+    }
+    return out;
+  } finally {
+    mermaid.initialize(prior);
+  }
+};
+var themeVariable = (selector, line) => ({
+  kind: "themeVariables",
+  selector,
+  properties: {},
+  spans: {},
+  line
+});
+var scoreSequence = async (source, profile) => {
+  const pairs = [];
+  const skipped = [];
+  const lines = source.split(`
+`);
+  const keywordLine = lines.findIndex((l) => /^\s*sequenceDiagram\b/.test(l)) + 1;
+  const lineOf = (key) => {
+    const found = lines.findLastIndex((l) => new RegExp(`\\b${key}["']?\\s*:`).test(l));
+    return found < 0 ? keywordLine : found + 1;
+  };
+  const rectLines = lines.flatMap((l, i) => /^\s*rect\s/.test(l) ? [i + 1] : []);
+  const mermaid = await getMermaidCore();
+  let config;
+  let db;
+  try {
+    config = (await mermaid.parse(source)).config;
+    db = (await mermaid.mermaidAPI.getDiagramFromText(source)).db;
+  } catch {
+    return { pairs, skipped };
+  }
+  const block = (selector, reason) => {
+    skipped.push({ selector, line: lineOf(selector), reason, blocking: true });
+    return { pairs, skipped };
+  };
+  if (config.themeCSS !== undefined)
+    return block("themeCSS", "themeCSS restyles the diagram with CSS the audit cannot model");
+  const pinned = config.theme;
+  if (pinned !== undefined && !SEQUENCE_THEMES.includes(String(pinned))) {
+    return block("theme", `the ${String(pinned)} theme is not modelled, only ${SEQUENCE_THEMES.join(", ")}`);
+  }
+  const features = sequenceFeatures(db);
+  const host = profile === "mkdocs-material";
+  const theme = (fallback) => pinned === undefined ? fallback : String(pinned);
+  let variables;
+  try {
+    variables = resolveVariables(mermaid, config, { light: theme("default"), dark: theme(host ? "default" : "dark") });
+  } catch (err) {
+    return block("themeVariables", `Mermaid could not resolve the theme: ${message(err)}`);
+  }
+  for (const t of THEMES) {
+    const page = (host ? MKDOCS_MATERIAL : GITHUB)[t].bg;
+    const vars = variables[t];
+    const color = (key) => {
+      const value = vars[key];
+      if (typeof value !== "string")
+        throw new Error(`${key} is not a resolved colour`);
+      return value;
+    };
+    const pair = (kind, fgKey, bg, suffix = "", at) => {
+      const selector = fgKey + suffix;
+      const line = at ?? lineOf(fgKey);
+      try {
+        const box = compositeOver("key" in bg ? color(bg.key) : bg.colour, page);
+        pairs.push({ ...scoreHostPair(kind, themeVariable(selector, line), t, color(fgKey), box), advisory: host });
+      } catch (err) {
+        skipped.push({ selector, line, reason: `${t} sequence pair unparseable: ${message(err)}`, blocking: true });
+      }
+    };
+    const onPage = { colour: page };
+    if (host) {
+      pair("border", "actorLineColor", onPage);
+      pair("border", "signalColor", onPage, " (arrowhead)");
+      if (features.activation)
+        pair("border", "activationBorderColor", { key: "activationBkgColor" });
+      continue;
+    }
+    pair("text", "actorTextColor", { key: "actorBkg" });
+    pair("border", "actorBorder", { key: "actorBkg" });
+    if (features.humanActor) {
+      pair("text", "actorTextColor", onPage, " (human actor label)");
+      pair("border", "actorBorder", onPage, " (human actor glyph)");
+    }
+    pair("border", "actorLineColor", onPage);
+    pair("text", "signalTextColor", onPage);
+    pair("border", "signalColor", onPage);
+    if (features.note)
+      pair("text", "noteTextColor", { key: "noteBkgColor" });
+    if (features.frame) {
+      pair("text", "labelTextColor", { key: "labelBoxBkgColor" });
+      pair("text", "loopTextColor", onPage);
+      pair("border", "labelBoxBorderColor", onPage, " (loop frame)");
+    }
+    if (features.activation)
+      pair("border", "activationBorderColor", { key: "activationBkgColor" });
+    if (features.numbered)
+      pair("text", "sequenceNumberColor", { key: "signalColor" });
+    for (const [i, rect] of features.rects.entries()) {
+      const fill = { colour: rect };
+      const at = rectLines[i];
+      pair("text", "signalTextColor", fill, " (rect)", at);
+      pair("border", "signalColor", fill, " (rect)", at);
+      if (features.frame)
+        pair("text", "loopTextColor", fill, " (rect)", at);
+    }
+  }
+  return { pairs, skipped };
+};
+var scoreDiagram = (source, directives, profile, keyword) => keyword === "sequenceDiagram" ? scoreSequence(source, profile) : Promise.resolve(scoreForProfile(directives, profile, keyword));
 var detectProfile = (filePath) => {
   let dir = dirname(resolve(filePath));
   for (let i = 0;i < 20; i++) {
@@ -1272,7 +1406,7 @@ var contrastOf = (diagram, profile) => {
   }
   let result = byProfile.get(profile);
   if (!result) {
-    result = scoreForProfile(diagram.directives, profile, diagram.keyword);
+    result = scoreDiagram(diagram.source, diagram.directives, profile, diagram.keyword);
     byProfile.set(profile, result);
   }
   return result;
@@ -1384,11 +1518,11 @@ var contrastBorderBelowUiMinimum = {
   category: "contrast",
   summary: "a border below 3:1 against its fill",
   options: CONTRAST_OPTIONS,
-  check: (ctx) => {
+  check: async (ctx) => {
     const profile = profileOf(ctx);
     const found = [];
     for (const diagram of ctx.doc.diagrams) {
-      for (const p of contrastOf(diagram, profile).pairs) {
+      for (const p of (await contrastOf(diagram, profile)).pairs) {
         if (p.kind !== "border" || p.passes || p.advisory)
           continue;
         const line = fileLine(diagram, p.line);
@@ -1398,7 +1532,7 @@ var contrastBorderBelowUiMinimum = {
           endLine: line,
           rule: RULE.BORDER,
           message: `${p.directive.kind} ${p.selector}: border ${p.assessment.ratio.toFixed(2)}:1 < ${AA_NON_TEXT2} ` + `(${p.foreground} on ${p.background}${p.theme ? `, ${p.theme}` : ""})`,
-          remediation: "Darken the stroke or lighten the fill until the ratio reaches 3:1."
+          remediation: p.directive.kind === "themeVariables" ? "Set the theme variable to a colour that reaches 3:1 on its background in both themes, or remove it and let the theme set it." : "Darken the stroke or lighten the fill until the ratio reaches 3:1."
         });
       }
     }
@@ -1412,11 +1546,11 @@ var contrastDirectiveUnauditable = {
   category: "contrast",
   summary: "a style directive whose contrast cannot be audited",
   options: CONTRAST_OPTIONS,
-  check: (ctx) => {
+  check: async (ctx) => {
     const profile = profileOf(ctx);
     const found = [];
     for (const diagram of ctx.doc.diagrams) {
-      for (const s of contrastOf(diagram, profile).skipped) {
+      for (const s of (await contrastOf(diagram, profile)).skipped) {
         if (!s.blocking)
           continue;
         const line = fileLine(diagram, s.line);
@@ -1426,7 +1560,7 @@ var contrastDirectiveUnauditable = {
           endLine: line,
           rule: RULE.UNAUDITABLE,
           message: `${s.selector}: unaudited, ${s.reason}`,
-          remediation: "Declare the missing property or fix the colour so the pair can be scored."
+          remediation: "Declare the missing property, fix the colour, or remove the config the audit cannot model, so the pair can be scored."
         });
       }
     }
@@ -1443,11 +1577,11 @@ var contrastTextBelowAa = {
   category: "contrast",
   summary: "label text below 4.5:1 against its fill",
   options: CONTRAST_OPTIONS,
-  check: (ctx) => {
+  check: async (ctx) => {
     const profile = profileOf(ctx);
     const found = [];
     for (const diagram of ctx.doc.diagrams) {
-      for (const p of contrastOf(diagram, profile).pairs) {
+      for (const p of (await contrastOf(diagram, profile)).pairs) {
         if (p.kind !== "text" || p.passes)
           continue;
         const where = [p.theme, p.row].filter(Boolean).join("/");
@@ -1458,19 +1592,19 @@ var contrastTextBelowAa = {
           endLine: line,
           rule: RULE.TEXT,
           message: `${p.directive.kind} ${p.selector}: text ${p.assessment.ratio.toFixed(2)}:1 < ${AA_NORMAL2} ` + `(${p.foreground} on ${p.background}${where ? `, ${where}` : ""})`,
-          remediation: profile === "mkdocs-material" ? "The host theme forces the label text, so change the fill until the host text reads on it in both themes." : p.directive.kind === "linkStyle" ? "An edge label sits on Mermaid's own label box, light in one theme and grey in the other, and no one colour reads on both, so drop color: from the linkStyle and let the theme set the label text." : "Darken or lighten the fill, or change color:, until the ratio reaches 4.5:1 in every theme."
+          remediation: profile === "mkdocs-material" ? "The host theme forces the label text, so change the fill until the host text reads on it in both themes." : p.directive.kind === "themeVariables" ? "A sequence diagram colour is a theme variable, and text with no box of its own sits on the page, so set the variable to a colour that reads on its background in both themes, or remove it and let the theme set it." : p.directive.kind === "linkStyle" ? "An edge label sits on Mermaid's own label box, light in one theme and grey in the other, and no one colour reads on both, so drop color: from the linkStyle and let the theme set the label text." : "Darken or lighten the fill, or change color:, until the ratio reaches 4.5:1 in every theme."
         });
       }
     }
     return found;
   },
-  fix: (ctx) => {
+  fix: async (ctx) => {
     const profile = profileOf(ctx);
     if (profile === "mkdocs-material")
       return [];
     const edits = [];
     for (const diagram of ctx.doc.diagrams) {
-      const { pairs } = contrastOf(diagram, profile);
+      const { pairs } = await contrastOf(diagram, profile);
       const failing = new Set(pairs.filter((p) => p.kind === "text" && !p.passes).map((p) => p.directive));
       for (const directive of failing) {
         const span = directive.spans.color;

package/dist/types/parse/contrast.d.ts

@@ -5,10 +5,13 @@ export type PairKind = "text" | "border";
 export type ErRow = "odd" | "even";
 export declare const PROFILES: readonly ["auto", "github", "mkdocs-material"];
 export declare const edgeLabelBackground: (theme: Theme) => string;
+export type ContrastSource = StyleDirective | (Omit<StyleDirective, "kind"> & {
+    kind: "themeVariables";
+});
 export interface ContrastPair {
     kind: PairKind;
     selector: string;
-    directive: StyleDirective;
+    directive: ContrastSource;
     foreground: string;
     background: string;
     line: number;
@@ -32,4 +35,25 @@ export declare const scoreGithub: (directives: StyleDirective[]) => ContrastResu
 export declare const scoreMkdocs: (directives: StyleDirective[]) => ContrastResult;
 export declare const scoreEr: (directives: StyleDirective[]) => ContrastResult;
 export declare const scoreForProfile: (directives: StyleDirective[], profile: Profile, keyword: string | null) => ContrastResult;
+interface SequenceDb {
+    getActors: () => Map<string, {
+        type: string;
+    }>;
+    getMessages: () => Array<{
+        type: number;
+        message: unknown;
+    }>;
+}
+export interface SequenceFeatures {
+    humanActor: boolean;
+    note: boolean;
+    frame: boolean;
+    activation: boolean;
+    numbered: boolean;
+    rects: string[];
+}
+export declare const sequenceFeatures: (db: SequenceDb) => SequenceFeatures;
+export declare const scoreSequence: (source: string, profile: Profile) => Promise<ContrastResult>;
+export declare const scoreDiagram: (source: string, directives: StyleDirective[], profile: Profile, keyword: string | null) => Promise<ContrastResult>;
 export declare const detectProfile: (filePath: string) => Profile;
+export {};

package/dist/types/parse/stats.d.ts

@@ -1,3 +1,16 @@
+export interface MermaidCore {
+    parse: (text: string) => Promise<{
+        config: Record<string, unknown>;
+    }>;
+    initialize: (config: Record<string, unknown>) => void;
+    mermaidAPI: {
+        getSiteConfig: () => Record<string, unknown>;
+        getDiagramFromText: (text: string) => Promise<{
+            db: unknown;
+        }>;
+    };
+}
+export declare const getMermaidCore: () => Promise<MermaidCore>;
 export interface DiagramStats {
     nodes: number;
     edges: number;

package/dist/types/plugins/runtime.d.ts

@@ -3,4 +3,4 @@ export interface RuntimeInfo {
     features: Record<string, unknown>;
 }
 export declare const canImportTypeScript: (runtime?: RuntimeInfo) => boolean;
-export declare const TYPESCRIPT_HELP = "TypeScript cannot be imported by this runtime. Run with Bun (bunx --bun @jpeakai/mermaidjs-lint), use Node 22.18 or newer, or write a .js or .mjs file";
+export declare const TYPESCRIPT_HELP = "TypeScript cannot be imported by this runtime. Run with Bun (bunx --bun @jpeakai/mermaidjs-lint), use Node 22.18 or newer (23.6 or newer on Node 23), or write a .js or .mjs file";

package/dist/types/rules/shared.d.ts

@@ -14,5 +14,5 @@ export declare const finding: (ctx: RuleContext, diagram: Diagram, rule: RuleId,
 export declare const boundaryHint: (boundaries: string[]) => string;
 export declare const splitTarget: (c: ThresholdConfig) => string;
 export declare const profileOf: (ctx: RuleContext) => Profile;
-export declare const contrastOf: (diagram: Diagram, profile: Profile) => ContrastResult;
+export declare const contrastOf: (diagram: Diagram, profile: Profile) => Promise<ContrastResult>;
 export declare const fileLine: (diagram: Diagram, line: number) => number;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jpeakai/mermaidjs-lint",
-  "version": "0.4.2",
+  "version": "0.5.0",
   "type": "module",
   "description": "Deterministic lint gates and verified fixers for Mermaid diagrams in markdown",
   "license": "MIT",
@@ -58,7 +58,7 @@
     "mdast-util-from-markdown": "^2.0.3",
     "mdast-util-frontmatter": "^2.0.1",
     "mdast-util-gfm": "^3.1.0",
-    "mermaid": "^11.14.0",
+    "mermaid": "11.17.2",
     "micromark-extension-frontmatter": "^2.0.0",
     "micromark-extension-gfm": "^3.0.0"
   },

package/src/parse/contrast.ts

@@ -16,6 +16,7 @@
 import { existsSync } from "node:fs";
 import { dirname, join, resolve } from "node:path";
 import { alphaOf, type ContrastAssessment, compositeOver, type StyleDirective, wcagAssess } from "./color.ts";
+import { getMermaidCore, type MermaidCore } from "./stats.ts";
 
 export type Profile = "github" | "mkdocs-material";
 export type Theme = "light" | "dark";
@@ -73,10 +74,14 @@ const MERMAID_ER = {
 const AA_NORMAL = 4.5;
 const AA_NON_TEXT = 3.0;
 
+// What a pair was scored from: a style directive, or, in a sequence diagram,
+// a theme variable, which has no directive and no value span to rewrite.
+export type ContrastSource = StyleDirective | (Omit<StyleDirective, "kind"> & { kind: "themeVariables" });
+
 export interface ContrastPair {
   kind: PairKind;
   selector: string;
-  directive: StyleDirective;
+  directive: ContrastSource;
   foreground: string;
   background: string;
   line: number; // line within the diagram text
@@ -105,7 +110,7 @@ export interface ContrastResult {
   skipped: SkippedDirective[];
 }
 
-const scorePair = (kind: PairKind, d: StyleDirective, fg: string, bg: string): ContrastPair => {
+const scorePair = (kind: PairKind, d: ContrastSource, fg: string, bg: string): ContrastPair => {
   const assessment = wcagAssess(fg, bg);
   return {
     kind,
@@ -196,7 +201,7 @@ export const scoreGithub = (directives: StyleDirective[]): ContrastResult => {
   return { pairs, skipped };
 };
 
-const scoreHostPair = (kind: PairKind, d: StyleDirective, theme: Theme, fgRaw: string, box: string): ContrastPair => {
+const scoreHostPair = (kind: PairKind, d: ContrastSource, theme: Theme, fgRaw: string, box: string): ContrastPair => {
   // The foreground may itself be translucent, so it composites onto the box.
   const fg = compositeOver(fgRaw, box);
   const assessment = wcagAssess(fg, box);
@@ -320,6 +325,228 @@ export const scoreForProfile = (
   return keyword === "erDiagram" ? scoreEr(directives) : scoreGithub(directives);
 };
 
+// ─── Sequence diagrams ───────────────────────────────────────────────────────
+//
+// A sequence diagram has no style directives. Its colours are theme variables:
+// some set in YAML frontmatter or an %%{init}%% directive, the rest derived by
+// Mermaid's own theme calculation. So the config is read with mermaid.parse,
+// which merges both the way the renderer does, and every variable is resolved
+// by Mermaid's theme engine, never by a copy of its palettes. The features a
+// diagram uses (human actors, notes, loops, activations, numbering, rect
+// backgrounds) are read from the parsed sequence DB. The variables changed
+// between Mermaid releases, so package.json pins the exact version.
+//
+// The SVG is transparent: message text, arrows, lifelines and loop text sit on
+// the host page, and themeVariables.background paints nothing behind them.
+//
+// github: the default theme in light and the dark theme in dark, as GitHub
+// draws them, unless the config pins a theme, which then applies to both.
+//
+// mkdocs-material: Material renders with Mermaid's default theme in both of its
+// schemes and appends its own themeCSS, which wins over Mermaid's styles. That
+// CSS sets every sequence label, box, actor, message line, note, loop frame,
+// rect and number from its own --md-mermaid-* variables, so no text pair is
+// the author's. Three surfaces escape it and keep the diagram's variables, as
+// measured in a browser on Material 9.7 with Mermaid 11.17: lifelines
+// (.actor-line beats Material's bare `line`), arrowheads (Material targets
+// #arrowhead, but Mermaid 11 names it <id>-arrowhead) and activation bars.
+// Each is a border, so under this profile, as for every other diagram, it is
+// scored but advisory.
+
+// The themes Mermaid resolves without per-actor colour arrays or a look of its own.
+const SEQUENCE_THEMES = ["base", "default", "dark", "forest", "neutral"];
+
+// The sequence DB's message types, from Mermaid's LINETYPE table.
+const LINE = { NOTE: 2, ACTIVE_START: 17, RECT_START: 22, AUTONUMBER: 26 } as const;
+// loop, alt, opt, par, critical, break and par over each open a frame.
+const FRAME_STARTS = new Set([10, 12, 15, 19, 27, 30, 32]);
+
+interface SequenceDb {
+  getActors: () => Map<string, { type: string }>;
+  getMessages: () => Array<{ type: number; message: unknown }>;
+}
+
+// What a sequence diagram draws that brings its own colour pairs.
+export interface SequenceFeatures {
+  humanActor: boolean;
+  note: boolean;
+  frame: boolean;
+  activation: boolean;
+  numbered: boolean;
+  rects: string[];
+}
+
+export const sequenceFeatures = (db: SequenceDb): SequenceFeatures => {
+  const messages = db.getMessages();
+  const has = (type: number): boolean => messages.some((m) => m.type === type);
+  return {
+    humanActor: [...db.getActors().values()].some((a) => a.type === "actor"),
+    note: has(LINE.NOTE),
+    frame: messages.some((m) => FRAME_STARTS.has(m.type)),
+    activation: has(LINE.ACTIVE_START),
+    numbered: messages.some(
+      (m) => m.type === LINE.AUTONUMBER && (m.message as { visible?: boolean } | null)?.visible !== false,
+    ),
+    rects: messages.filter((m) => m.type === LINE.RECT_START).map((m) => String(m.message)),
+  };
+};
+
+type Variables = Record<string, unknown>;
+
+// Mermaid's theme variables for a config in each theme, as its own engine
+// resolves them. The site config is restored inside the same synchronous
+// block, so a parse elsewhere never sees it changed. The site config is read
+// rather than getConfig(), which mixes in the last parsed diagram's directives.
+const resolveVariables = (
+  mermaid: MermaidCore,
+  config: Variables,
+  themes: Record<Theme, string>,
+): Record<Theme, Variables> => {
+  const prior = mermaid.mermaidAPI.getSiteConfig();
+  try {
+    const out = {} as Record<Theme, Variables>;
+    for (const t of THEMES) {
+      mermaid.initialize({ ...structuredClone(config), theme: themes[t] });
+      out[t] = { ...(mermaid.mermaidAPI.getSiteConfig().themeVariables as Variables) };
+    }
+    return out;
+  } finally {
+    mermaid.initialize(prior);
+  }
+};
+
+const themeVariable = (selector: string, line: number): ContrastSource => ({
+  kind: "themeVariables",
+  selector,
+  properties: {},
+  spans: {},
+  line,
+});
+
+export const scoreSequence = async (source: string, profile: Profile): Promise<ContrastResult> => {
+  const pairs: ContrastPair[] = [];
+  const skipped: SkippedDirective[] = [];
+  const lines = source.split("\n");
+  const keywordLine = lines.findIndex((l) => /^\s*sequenceDiagram\b/.test(l)) + 1;
+  // The line that sets a variable, or the keyword line when it is inherited.
+  const lineOf = (key: string): number => {
+    const found = lines.findLastIndex((l) => new RegExp(`\\b${key}["']?\\s*:`).test(l));
+    return found < 0 ? keywordLine : found + 1;
+  };
+  const rectLines = lines.flatMap((l, i) => (/^\s*rect\s/.test(l) ? [i + 1] : []));
+
+  const mermaid = await getMermaidCore();
+  let config: Variables;
+  let db: SequenceDb;
+  try {
+    config = (await mermaid.parse(source)).config;
+    db = (await mermaid.mermaidAPI.getDiagramFromText(source)).db as SequenceDb;
+  } catch {
+    // parse-diagram-unparseable reports it. As for complexity, a diagram the
+    // parser cannot read has no colours to trust.
+    return { pairs, skipped };
+  }
+
+  const block = (selector: string, reason: string): ContrastResult => {
+    skipped.push({ selector, line: lineOf(selector), reason, blocking: true });
+    return { pairs, skipped };
+  };
+  // Under mkdocs-material a diagram's themeCSS replaces Material's own, so
+  // neither profile can say what it draws.
+  if (config.themeCSS !== undefined)
+    return block("themeCSS", "themeCSS restyles the diagram with CSS the audit cannot model");
+  const pinned = config.theme;
+  if (pinned !== undefined && !SEQUENCE_THEMES.includes(String(pinned))) {
+    return block("theme", `the ${String(pinned)} theme is not modelled, only ${SEQUENCE_THEMES.join(", ")}`);
+  }
+
+  const features = sequenceFeatures(db);
+  const host = profile === "mkdocs-material";
+  const theme = (fallback: string): string => (pinned === undefined ? fallback : String(pinned));
+  let variables: Record<Theme, Variables>;
+  try {
+    variables = resolveVariables(mermaid, config, { light: theme("default"), dark: theme(host ? "default" : "dark") });
+  } catch (err) {
+    // A colour the theme derives others from, such as actorBorder, fails here.
+    return block("themeVariables", `Mermaid could not resolve the theme: ${message(err)}`);
+  }
+
+  for (const t of THEMES) {
+    const page = (host ? MKDOCS_MATERIAL : GITHUB)[t].bg;
+    const vars = variables[t];
+    const color = (key: string): string => {
+      const value = vars[key];
+      if (typeof value !== "string") throw new Error(`${key} is not a resolved colour`);
+      return value;
+    };
+    // fgKey drawn on a background: a variable, or a colour such as the page.
+    const pair = (
+      kind: PairKind,
+      fgKey: string,
+      bg: { key: string } | { colour: string },
+      suffix = "",
+      at?: number,
+    ) => {
+      const selector = fgKey + suffix;
+      const line = at ?? lineOf(fgKey);
+      try {
+        const box = compositeOver("key" in bg ? color(bg.key) : bg.colour, page);
+        pairs.push({ ...scoreHostPair(kind, themeVariable(selector, line), t, color(fgKey), box), advisory: host });
+      } catch (err) {
+        skipped.push({ selector, line, reason: `${t} sequence pair unparseable: ${message(err)}`, blocking: true });
+      }
+    };
+    const onPage = { colour: page };
+
+    if (host) {
+      pair("border", "actorLineColor", onPage);
+      pair("border", "signalColor", onPage, " (arrowhead)");
+      if (features.activation) pair("border", "activationBorderColor", { key: "activationBkgColor" });
+      continue;
+    }
+
+    pair("text", "actorTextColor", { key: "actorBkg" });
+    pair("border", "actorBorder", { key: "actorBkg" });
+    // A human actor's name and stick figure sit outside the box fill.
+    if (features.humanActor) {
+      pair("text", "actorTextColor", onPage, " (human actor label)");
+      pair("border", "actorBorder", onPage, " (human actor glyph)");
+    }
+    pair("border", "actorLineColor", onPage);
+    pair("text", "signalTextColor", onPage);
+    pair("border", "signalColor", onPage);
+    if (features.note) pair("text", "noteTextColor", { key: "noteBkgColor" });
+    if (features.frame) {
+      pair("text", "labelTextColor", { key: "labelBoxBkgColor" });
+      pair("text", "loopTextColor", onPage);
+      pair("border", "labelBoxBorderColor", onPage, " (loop frame)");
+    }
+    if (features.activation) pair("border", "activationBorderColor", { key: "activationBkgColor" });
+    if (features.numbered) pair("text", "sequenceNumberColor", { key: "signalColor" });
+    // Messages and frame text inside a rect sit on its colour, not the page.
+    for (const [i, rect] of features.rects.entries()) {
+      const fill = { colour: rect };
+      const at = rectLines[i];
+      pair("text", "signalTextColor", fill, " (rect)", at);
+      pair("border", "signalColor", fill, " (rect)", at);
+      if (features.frame) pair("text", "loopTextColor", fill, " (rect)", at);
+    }
+  }
+  return { pairs, skipped };
+};
+
+// Scores a diagram by its keyword: a sequence diagram by its theme variables,
+// any other by its style directives.
+export const scoreDiagram = (
+  source: string,
+  directives: StyleDirective[],
+  profile: Profile,
+  keyword: string | null,
+): Promise<ContrastResult> =>
+  keyword === "sequenceDiagram"
+    ? scoreSequence(source, profile)
+    : Promise.resolve(scoreForProfile(directives, profile, keyword));
+
 // An ancestor mkdocs.yml or mkdocs.yaml, searched up to 20 levels, means the
 // diagram is read through Material.
 export const detectProfile = (filePath: string): Profile => {

package/src/parse/stats.ts

@@ -32,6 +32,20 @@ const getMermaid = async (): Promise<typeof import("mermaid").default> => {
   return mermaidCore;
 };
 
+// The slice of mermaid core the contrast scorer reads: the config a diagram
+// declares, its parsed DB, and the theme engine. Typed here without mermaid's
+// own types, so the published declarations never need them.
+export interface MermaidCore {
+  parse: (text: string) => Promise<{ config: Record<string, unknown> }>;
+  initialize: (config: Record<string, unknown>) => void;
+  mermaidAPI: {
+    getSiteConfig: () => Record<string, unknown>;
+    getDiagramFromText: (text: string) => Promise<{ db: unknown }>;
+  };
+}
+
+export const getMermaidCore = async (): Promise<MermaidCore> => (await getMermaid()) as unknown as MermaidCore;
+
 export interface DiagramStats {
   nodes: number;
   edges: number;

package/src/plugins/runtime.ts

@@ -1,5 +1,6 @@
 // What the running JavaScript can import. Bun runs TypeScript directly, and Node
-// strips types from 22.18 (earlier with a flag, and not at all before 22.6). A
+// strips types from 22.18 and from 23.6 (earlier with a flag, and not at all
+// before 22.6). A
 // local rule written in TypeScript therefore works under `bunx --bun` or a recent
 // Node, and anywhere else it fails with a message that says how to fix it.
 
@@ -12,4 +13,4 @@ export const canImportTypeScript = (runtime: RuntimeInfo = process as unknown as
   typeof runtime.versions.bun === "string" || Boolean(runtime.features.typescript);
 
 export const TYPESCRIPT_HELP =
-  "TypeScript cannot be imported by this runtime. Run with Bun (bunx --bun @jpeakai/mermaidjs-lint), use Node 22.18 or newer, or write a .js or .mjs file";
+  "TypeScript cannot be imported by this runtime. Run with Bun (bunx --bun @jpeakai/mermaidjs-lint), use Node 22.18 or newer (23.6 or newer on Node 23), or write a .js or .mjs file";

package/src/rules/contrast-border-below-ui-minimum.ts

@@ -12,11 +12,11 @@ export const contrastBorderBelowUiMinimum: Rule = {
   category: "contrast",
   summary: "a border below 3:1 against its fill",
   options: CONTRAST_OPTIONS,
-  check: (ctx) => {
+  check: async (ctx) => {
     const profile = profileOf(ctx);
     const found: Finding[] = [];
     for (const diagram of ctx.doc.diagrams) {
-      for (const p of contrastOf(diagram, profile).pairs) {
+      for (const p of (await contrastOf(diagram, profile)).pairs) {
         if (p.kind !== "border" || p.passes || p.advisory) continue;
         const line = fileLine(diagram, p.line);
         found.push({
@@ -27,7 +27,10 @@ export const contrastBorderBelowUiMinimum: Rule = {
           message:
             `${p.directive.kind} ${p.selector}: border ${p.assessment.ratio.toFixed(2)}:1 < ${AA_NON_TEXT} ` +
             `(${p.foreground} on ${p.background}${p.theme ? `, ${p.theme}` : ""})`,
-          remediation: "Darken the stroke or lighten the fill until the ratio reaches 3:1.",
+          remediation:
+            p.directive.kind === "themeVariables"
+              ? "Set the theme variable to a colour that reaches 3:1 on its background in both themes, or remove it and let the theme set it."
+              : "Darken the stroke or lighten the fill until the ratio reaches 3:1.",
         });
       }
     }