@jpeakai/mermaidjs-lint 0.5.0 → 0.6.1

package/dist/bin.js

@@ -9,7 +9,7 @@ import { parseArgs } from "node:util";
 // package.json
 var package_default = {
   name: "@jpeakai/mermaidjs-lint",
-  version: "0.5.0",
+  version: "0.6.1",
   type: "module",
   description: "Deterministic lint gates and verified fixers for Mermaid diagrams in markdown",
   license: "MIT",
@@ -179,6 +179,15 @@ class RuleOptionError extends UsageError {
   }
 }
 
+class CanvasProfileError extends UsageError {
+  file;
+  constructor(file, cause = "flag") {
+    const hint = cause === "flag" ? "run --canvas-light and --canvas-dark over the GitHub-rendered paths only, or set the canvas in the config, which a Material file sets aside" : "remove the mkdocs-material profile setting for this run, or remove the canvas";
+    super(`${file}: a canvas applies under the github profile only, and this file is scored under mkdocs-material, whose page is Material's own; ${hint}`, "canvas-profile");
+    this.file = file;
+  }
+}
+
 class FixOutsideRootError extends UsageError {
   file;
   target;
@@ -1041,15 +1050,27 @@ var MKDOCS_MATERIAL = {
   light: { bg: "#ffffff", text: "#36464e" },
   dark: { bg: "#1e2129", text: "hsl(225 18% 86% / 0.82)" }
 };
-var GITHUB = { light: { bg: "#ffffff" }, dark: { bg: "#0d1117" } };
+var GITHUB_CANVAS = { light: "#ffffff", dark: "#0d1117" };
 var THEMES = ["light", "dark"];
+var canvasColourProblem = (value) => {
+  if (typeof value !== "string")
+    return "is not a colour string";
+  let alpha;
+  try {
+    alpha = alphaOf(value);
+  } catch {
+    return "is not a CSS colour";
+  }
+  return alpha < 1 ? "is translucent, and a page canvas must be opaque" : null;
+};
+var resolveCanvas = (setting) => ({ ...GITHUB_CANVAS, ...setting });
 var MERMAID_EDGE_LABEL = {
   light: { box: "rgba(232,232,232,0.8)", backing: "rgba(232,232,232,0.5)" },
   dark: { box: "#585858", backing: "rgba(88,88,88,0.5)" }
 };
-var edgeLabelBackground = (theme) => {
+var edgeLabelBackground = (theme, canvas = GITHUB_CANVAS) => {
   const { box, backing } = MERMAID_EDGE_LABEL[theme];
-  return compositeOver(box, compositeOver(box, compositeOver(backing, GITHUB[theme].bg)));
+  return compositeOver(box, compositeOver(box, compositeOver(backing, canvas[theme])));
 };
 var MERMAID_ER = {
   light: { odd: "#ffffff", even: "#f1f1ff", label: "#333333" },
@@ -1071,12 +1092,12 @@ var scorePair = (kind, d, fg, bg) => {
   };
 };
 var message = (err) => err instanceof Error ? err.message : String(err);
-var scoreEdgeLabel = (d, pairs, skipped) => {
+var scoreEdgeLabel = (d, canvas, pairs, skipped) => {
   const { color } = d.properties;
   if (!color)
     return;
   try {
-    pairs.push(...THEMES.map((t) => scoreHostPair("text", d, t, color, edgeLabelBackground(t))));
+    pairs.push(...THEMES.map((t) => scoreHostPair("text", d, t, color, edgeLabelBackground(t, canvas))));
   } catch (err) {
     skipped.push({
       selector: d.selector,
@@ -1086,12 +1107,12 @@ var scoreEdgeLabel = (d, pairs, skipped) => {
     });
   }
 };
-var scoreGithub = (directives) => {
+var scoreGithub = (directives, canvas = GITHUB_CANVAS) => {
   const pairs = [];
   const skipped = [];
   for (const d of directives) {
     if (d.kind === "linkStyle")
-      scoreEdgeLabel(d, pairs, skipped);
+      scoreEdgeLabel(d, canvas, pairs, skipped);
     if (d.kind !== "classDef" && d.kind !== "style")
       continue;
     const { fill, color, stroke } = d.properties;
@@ -1113,7 +1134,7 @@ var scoreGithub = (directives) => {
       note("fill is fully transparent, so there is no box to anchor contrast");
       continue;
     }
-    const boxes = alpha < 1 ? THEMES.map((t) => [compositeOver(fill, GITHUB[t].bg), t]) : [[fill, undefined]];
+    const boxes = alpha < 1 ? THEMES.map((t) => [compositeOver(fill, canvas[t]), t]) : [[fill, undefined]];
     if (!color) {
       note("no color: declared beside fill:, and the github profile requires one " + "(if the host forces label text, use the mkdocs-material profile)", true);
     }
@@ -1246,10 +1267,10 @@ var scoreEr = (directives) => {
   }
   return { pairs, skipped };
 };
-var scoreForProfile = (directives, profile, keyword) => {
+var scoreForProfile = (directives, profile, keyword, canvas = GITHUB_CANVAS) => {
   if (profile === "mkdocs-material")
     return scoreMkdocs(directives);
-  return keyword === "erDiagram" ? scoreEr(directives) : scoreGithub(directives);
+  return keyword === "erDiagram" ? scoreEr(directives) : scoreGithub(directives, canvas);
 };
 var SEQUENCE_THEMES = ["base", "default", "dark", "forest", "neutral"];
 var LINE = { NOTE: 2, ACTIVE_START: 17, RECT_START: 22, AUTONUMBER: 26 };
@@ -1286,7 +1307,7 @@ var themeVariable = (selector, line) => ({
   spans: {},
   line
 });
-var scoreSequence = async (source, profile) => {
+var scoreSequence = async (source, profile, canvas = GITHUB_CANVAS) => {
   const pairs = [];
   const skipped = [];
   const lines = source.split(`
@@ -1326,7 +1347,7 @@ var scoreSequence = async (source, profile) => {
     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 page = host ? MKDOCS_MATERIAL[t].bg : canvas[t];
     const vars = variables[t];
     const color = (key) => {
       const value = vars[key];
@@ -1383,7 +1404,7 @@ var scoreSequence = async (source, profile) => {
   }
   return { pairs, skipped };
 };
-var scoreDiagram = (source, directives, profile, keyword) => keyword === "sequenceDiagram" ? scoreSequence(source, profile) : Promise.resolve(scoreForProfile(directives, profile, keyword));
+var scoreDiagram = (source, directives, profile, keyword, canvas = GITHUB_CANVAS) => keyword === "sequenceDiagram" ? scoreSequence(source, profile, canvas) : Promise.resolve(scoreForProfile(directives, profile, keyword, canvas));
 var detectProfile = (filePath) => {
   let dir = dirname(resolve(filePath));
   for (let i = 0;i < 20; i++) {
@@ -1547,7 +1568,7 @@ var COMPLEXITY_OPTIONS = {
   subgraphWeight: "number",
   depthWeight: "number"
 };
-var CONTRAST_OPTIONS = { profile: "string" };
+var CONTRAST_OPTIONS = { profile: "string", canvas: "canvas" };
 var measure = async (diagram, config) => {
   const stats = await diagram.stats();
   if (parseFailed(diagram.source, stats))
@@ -1577,17 +1598,36 @@ var profileOf = (ctx) => {
   }
   return wanted === "auto" ? detectProfile(ctx.file) : wanted;
 };
-var scored = new WeakMap;
-var contrastOf = (diagram, profile) => {
-  let byProfile = scored.get(diagram);
-  if (!byProfile) {
-    byProfile = new Map;
-    scored.set(diagram, byProfile);
+var settingsOf = (ctx) => {
+  const profile = profileOf(ctx);
+  const setting = ctx.options.canvas;
+  if (setting === undefined)
+    return { profile, canvas: GITHUB_CANVAS };
+  for (const side of THEMES) {
+    if (!(side in setting))
+      continue;
+    const problem = canvasColourProblem(setting[side]);
+    if (problem)
+      throw new Error(`canvas.${side} ${problem}: ${JSON.stringify(setting[side])}`);
   }
-  let result = byProfile.get(profile);
+  if (profile === "mkdocs-material") {
+    throw new CanvasProfileError(ctx.file, ctx.options.profile === "mkdocs-material" ? "profile" : "flag");
+  }
+  return { profile, canvas: resolveCanvas(setting) };
+};
+var scored = new WeakMap;
+var contrastOf = (diagram, settings) => {
+  const { profile, canvas } = settings;
+  const key = `${profile}\x00${canvas.light}\x00${canvas.dark}`;
+  let bySettings = scored.get(diagram);
+  if (!bySettings) {
+    bySettings = new Map;
+    scored.set(diagram, bySettings);
+  }
+  let result = bySettings.get(key);
   if (!result) {
-    result = scoreDiagram(diagram.source, diagram.directives, profile, diagram.keyword);
-    byProfile.set(profile, result);
+    result = scoreDiagram(diagram.source, diagram.directives, profile, diagram.keyword, canvas);
+    bySettings.set(key, result);
   }
   return result;
 };
@@ -1700,10 +1740,10 @@ var contrastBorderBelowUiMinimum = {
   summary: "a border below 3:1 against its fill",
   options: CONTRAST_OPTIONS,
   check: async (ctx) => {
-    const profile = profileOf(ctx);
+    const settings = settingsOf(ctx);
     const found = [];
     for (const diagram of ctx.doc.diagrams) {
-      for (const p of (await contrastOf(diagram, profile)).pairs) {
+      for (const p of (await contrastOf(diagram, settings)).pairs) {
         if (p.kind !== "border" || p.passes || p.advisory)
           continue;
         const line = fileLine(diagram, p.line);
@@ -1728,10 +1768,10 @@ var contrastDirectiveUnauditable = {
   summary: "a style directive whose contrast cannot be audited",
   options: CONTRAST_OPTIONS,
   check: async (ctx) => {
-    const profile = profileOf(ctx);
+    const settings = settingsOf(ctx);
     const found = [];
     for (const diagram of ctx.doc.diagrams) {
-      for (const s of (await contrastOf(diagram, profile)).skipped) {
+      for (const s of (await contrastOf(diagram, settings)).skipped) {
         if (!s.blocking)
           continue;
         const line = fileLine(diagram, s.line);
@@ -1759,10 +1799,10 @@ var contrastTextBelowAa = {
   summary: "label text below 4.5:1 against its fill",
   options: CONTRAST_OPTIONS,
   check: async (ctx) => {
-    const profile = profileOf(ctx);
+    const settings = settingsOf(ctx);
     const found = [];
     for (const diagram of ctx.doc.diagrams) {
-      for (const p of (await contrastOf(diagram, profile)).pairs) {
+      for (const p of (await contrastOf(diagram, settings)).pairs) {
         if (p.kind !== "text" || p.passes)
           continue;
         const where = [p.theme, p.row].filter(Boolean).join("/");
@@ -1773,19 +1813,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 === "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."
+          remediation: settings.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: async (ctx) => {
-    const profile = profileOf(ctx);
-    if (profile === "mkdocs-material")
+    const settings = settingsOf(ctx);
+    if (settings.profile === "mkdocs-material")
       return [];
     const edits = [];
     for (const diagram of ctx.doc.diagrams) {
-      const { pairs } = await contrastOf(diagram, profile);
+      const { pairs } = await contrastOf(diagram, settings);
       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;
@@ -1905,8 +1945,27 @@ var typeOf = (value) => {
     return "boolean";
   if (Array.isArray(value) && value.every((v) => typeof v === "string"))
     return "string[]";
+  if (isCanvasShape(value))
+    return "canvas";
   return null;
 };
+var isCanvasShape = (value) => {
+  if (typeof value !== "object" || value === null || Array.isArray(value))
+    return false;
+  const keys = Object.keys(value);
+  return keys.length > 0 && keys.every((k) => THEMES.includes(k));
+};
+var describeType = (want) => want === "canvas" ? 'an object such as { "light": "#ffffff", "dark": "#0d1117" }' : `a ${want}`;
+var checkCanvas = (where, rule, name, value) => {
+  for (const side of THEMES) {
+    if (!(side in value))
+      continue;
+    const problem = canvasColourProblem(value[side]);
+    if (problem) {
+      throw new RuleOptionError(where, rule.id, name, `option "${name}.${side}" of "${rule.id}" ${problem}: ${JSON.stringify(value[side])}`);
+    }
+  }
+};
 var checkOptions = (where, rule, options) => {
   const accepted = Object.keys(rule.options ?? {});
   for (const [name, value] of Object.entries(options)) {
@@ -1916,8 +1975,13 @@ var checkOptions = (where, rule, options) => {
       throw new RuleOptionError(where, rule.id, name, `rule "${rule.id}" has no option "${name}"; ${list}`);
     }
     if (typeOf(value) !== want) {
-      throw new RuleOptionError(where, rule.id, name, `option "${name}" of "${rule.id}" must be a ${want}`);
+      throw new RuleOptionError(where, rule.id, name, `option "${name}" of "${rule.id}" must be ${describeType(want)}`);
     }
+    if (want === "canvas")
+      checkCanvas(where, rule, name, value);
+  }
+  if (options.profile === "mkdocs-material" && options.canvas !== undefined && rule.options?.canvas === "canvas") {
+    throw new RuleOptionError(where, rule.id, "canvas", `option "canvas" of "${rule.id}" applies under the github profile only, and this rule sets profile mkdocs-material, whose page is Material's own`);
   }
   if (typeof options.preset === "string" && canonicalPreset(options.preset) === null) {
     throw new RuleOptionError(where, rule.id, "preset", `option "preset" of "${rule.id}" is not a known preset`);
@@ -1961,8 +2025,24 @@ var buildRegistry = (input) => {
 var BUILTIN = buildRegistry({ rules: RULES, fixOrder: FIX_ORDER, categories: BUILTIN_CATEGORIES });
 
 // src/check.ts
+var canvasName = (side, prefix) => prefix ? `${prefix}canvas-${side}` : `canvas.${side}`;
 var checkRunFlags = (flags, prefix = "") => {
-  const { preset, profile } = flags;
+  const { preset, profile, canvas } = flags;
+  for (const side of THEMES) {
+    if (canvas?.[side] === undefined)
+      continue;
+    const problem = canvasColourProblem(canvas[side]);
+    if (problem) {
+      const name = canvasName(side, prefix);
+      throw new FlagError(name, `${name} ${problem}: "${canvas[side]}"; give an opaque CSS colour, such as #ffffff`);
+    }
+  }
+  const sides = THEMES.filter((side) => canvas?.[side] !== undefined);
+  const first = sides[0];
+  if (profile === "mkdocs-material" && first !== undefined) {
+    const name = canvasName(first, prefix);
+    throw new FlagError(name, `${name} applies under the github profile only; mkdocs-material scores Material's own page colours`);
+  }
   if (preset !== undefined && canonicalPreset(preset) === null) {
     throw new FlagError(`${prefix}preset`, `${prefix}preset must be one of ${PRESET_NAMES.join(", ")}, not "${preset}"`);
   }
@@ -1970,7 +2050,10 @@ var checkRunFlags = (flags, prefix = "") => {
     throw new FlagError(`${prefix}profile`, `${prefix}profile must be one of ${PROFILES.join(", ")}, not "${profile}"`);
   }
 };
-var optionsFor = (rule, configured, flags) => {
+var canvasOptions = (rule) => Object.entries(rule.options ?? {}).filter(([, type]) => type === "canvas").map(([name]) => name);
+var hasFlagCanvas = (flags) => THEMES.some((side) => flags.canvas?.[side] !== undefined);
+var setsAside = (rule, options, flags, file) => !hasFlagCanvas(flags) && rule.options?.profile !== undefined && (options.profile ?? "auto") === "auto" && canvasOptions(rule).some((name) => options[name] !== undefined) && detectProfile(file) === "mkdocs-material";
+var optionsFor = (rule, configured, flags, file) => {
   const options = { ...configured };
   for (const name of ["preset", "profile"]) {
     const value = flags[name];
@@ -1979,11 +2062,34 @@ var optionsFor = (rule, configured, flags) => {
   }
   if (typeof options.preset === "string")
     options.preset = canonicalPreset(options.preset) ?? options.preset;
+  const canvas = flags.canvas;
+  if (canvas && hasFlagCanvas(flags)) {
+    for (const name of canvasOptions(rule)) {
+      const current = options[name];
+      const merged = {
+        ...typeof current === "object" && current !== null ? current : {}
+      };
+      for (const side of THEMES) {
+        const value = canvas[side];
+        if (value !== undefined)
+          merged[side] = value;
+      }
+      options[name] = merged;
+    }
+  }
+  if (file !== undefined && setsAside(rule, options, flags, file)) {
+    for (const name of canvasOptions(rule))
+      delete options[name];
+  }
   return options;
 };
+var canvasSetAside = (file, flags = {}, registry = BUILTIN) => registry.rules.some((rule) => {
+  const options = optionsFor(rule, registry.options.get(rule.id), flags);
+  return setsAside(rule, options, flags, file);
+});
 var checkModel = async (doc, file, flags = {}, registry = BUILTIN) => {
   checkRunFlags(flags);
-  const perRule = registry.rules.map((rule) => rule.check({ doc, file, options: optionsFor(rule, registry.options.get(rule.id), flags), helpers: HELPERS }));
+  const perRule = registry.rules.map((rule) => rule.check({ doc, file, options: optionsFor(rule, registry.options.get(rule.id), flags, file), helpers: HELPERS }));
   const findings = (await Promise.all(perRule)).flat();
   return findings.sort((a, b) => a.line - b.line || a.rule.localeCompare(b.rule));
 };
@@ -2155,7 +2261,7 @@ var fixSourceReport = async (src, file, flags = {}, registry = BUILTIN) => {
     };
     let progressed = false;
     for (const rule of registry.fixOrder) {
-      const options = optionsFor(rule, registry.options.get(rule.id), flags);
+      const options = optionsFor(rule, registry.options.get(rule.id), flags, file);
       const proposed = await rule.fix?.({ doc, file, options, helpers: HELPERS }) ?? [];
       const sound = proposed.filter((e) => {
         if (wellFormed(e, current.length))
@@ -2425,7 +2531,7 @@ var importModule = async (source, runtime) => {
     throw new PluginImportError(source.spec, message2(err));
   }
 };
-var OPTION_TYPES = new Set(["number", "string", "boolean", "string[]"]);
+var OPTION_TYPES = new Set(["number", "string", "boolean", "string[]", "canvas"]);
 var RESERVED_OPTIONS = ["preset", "profile"];
 var checkRule = (spec, key, raw, own) => {
   const where = `rule "${key}"`;
@@ -2454,7 +2560,7 @@ var checkRule = (spec, key, raw, own) => {
   if (options !== undefined) {
     const valid = isRecord3(options) && Object.values(options).every((t) => OPTION_TYPES.has(t));
     if (!valid) {
-      throw new PluginContractError(spec, `${where} options must map names to number, string, boolean or string[]`);
+      throw new PluginContractError(spec, `${where} options must map names to number, string, boolean, string[] or canvas`);
     }
     for (const name of RESERVED_OPTIONS) {
       if (name in options && options[name] !== "string") {
@@ -2721,7 +2827,7 @@ var setUp = async ({
 
 // src/cli.ts
 var SYNOPSIS = `usage: mermaidjs-lint <path...> [--fix] [--json] [--preset NAME] [--profile NAME] [--config FILE]
-                     [--no-plugins | --lenient-plugins]
+                     [--canvas-light COLOUR] [--canvas-dark COLOUR] [--no-plugins | --lenient-plugins]
        mermaidjs-lint --list-rules
        mermaidjs-lint --validate-plugins [--json] [--config FILE]
        mermaidjs-lint --version | -h, --help`;
@@ -2747,6 +2853,11 @@ Examples of every rule, with fixes: https://jpeakai.github.io/jpai-mermaidjs-lin
   numeric threshold set in the config overrides both.
 --profile NAME sets how contrast is read: ${PROFILES.join(", ")}. It overrides a profile set in the config.
   auto reads mkdocs-material when any parent folder holds mkdocs.yml or mkdocs.yaml, else github.
+--canvas-light COLOUR and --canvas-dark COLOUR set the page a host draws in each theme, under the github
+  profile only. A translucent fill, an edge label box and a sequence diagram's page-backed text are scored
+  on it. Each is an opaque CSS colour such as #faf8f9, and a side not given keeps the config's, or GitHub's
+  (#ffffff light, #0d1117 dark). A file scored under mkdocs-material refuses a canvas flag with a usage
+  error, and sets a config canvas aside when auto picked the profile.
 --json prints one JSON object instead of text lines.
 --fix applies every fix it can prove safe, then reports what remains.
 A fixer that is unsure leaves the text alone and the finding stays.
@@ -2770,6 +2881,8 @@ var parse2 = (argv) => parseArgs({
     help: { type: "boolean", short: "h", default: false },
     preset: { type: "string", short: "p" },
     profile: { type: "string" },
+    "canvas-light": { type: "string" },
+    "canvas-dark": { type: "string" },
     config: { type: "string" },
     "no-plugins": { type: "boolean", default: false },
     "lenient-plugins": { type: "boolean", default: false },
@@ -2875,7 +2988,16 @@ var run = async (argv, cwd) => {
   }
   const listing = values["list-rules"];
   const validating = values["validate-plugins"];
-  checkRunFlags({ preset: values.preset, profile: values.profile }, "--");
+  const canvas = {
+    ...values["canvas-light"] !== undefined && { light: values["canvas-light"] },
+    ...values["canvas-dark"] !== undefined && { dark: values["canvas-dark"] }
+  };
+  const flags = {
+    preset: values.preset,
+    profile: values.profile,
+    ...Object.keys(canvas).length > 0 && { canvas }
+  };
+  checkRunFlags(flags, "--");
   if (values["no-plugins"] && values["lenient-plugins"]) {
     throw new FlagError("--lenient-plugins", "--no-plugins and --lenient-plugins contradict each other");
   }
@@ -2921,7 +3043,10 @@ var run = async (argv, cwd) => {
     throw new FlagError("files", "no matching files");
   if (values.fix)
     await refuseOutsideLinks(files, root, cwd);
-  const flags = { preset: values.preset, profile: values.profile };
+  const setAside = files.filter((file) => canvasSetAside(file, flags, registry));
+  if (setAside.length > 0) {
+    console.error(`mermaidjs-lint: config canvas set aside for ${plural(setAside.length, "file")} scored under mkdocs-material: ${setAside.map((f) => display(f, cwd)).join(", ")}`);
+  }
   const perFile = await Promise.all(files.map(async (file) => {
     let src = await readFile3(file, "utf8");
     if (values.fix) {