@jpeakai/mermaidjs-lint 0.4.2 → 0.6.0

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

@@ -1,4 +1,4 @@
-import { CONTRAST_OPTIONS, contrastOf, fileLine, profileOf } from "./shared.ts";
+import { CONTRAST_OPTIONS, contrastOf, fileLine, settingsOf } from "./shared.ts";
 import { type Finding, RULE, type Rule } from "./types.ts";
 
 const AA_NON_TEXT = 3;
@@ -12,11 +12,11 @@ export const contrastBorderBelowUiMinimum: Rule = {
   category: "contrast",
   summary: "a border below 3:1 against its fill",
   options: CONTRAST_OPTIONS,
-  check: (ctx) => {
-    const profile = profileOf(ctx);
+  check: async (ctx) => {
+    const settings = settingsOf(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, settings)).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.",
         });
       }
     }

package/src/rules/contrast-directive-unauditable.ts

@@ -1,8 +1,9 @@
-import { CONTRAST_OPTIONS, contrastOf, fileLine, profileOf } from "./shared.ts";
+import { CONTRAST_OPTIONS, contrastOf, fileLine, settingsOf } from "./shared.ts";
 import { type Finding, RULE, type Rule } from "./types.ts";
 
 // A directive the profile requires to be scoreable but cannot be: a github fill
-// with no color:, or a colour that will not parse. Reporting it as an
+// with no color:, a colour that will not parse, or a sequence diagram config
+// the audit does not model, such as themeCSS or a theme outside the five. Reporting it as an
 // informational skip is how a gate exits clean on a diagram it never checked,
 // so it is a failure to audit.
 export const contrastDirectiveUnauditable: Rule = {
@@ -10,11 +11,11 @@ export const contrastDirectiveUnauditable: Rule = {
   category: "contrast",
   summary: "a style directive whose contrast cannot be audited",
   options: CONTRAST_OPTIONS,
-  check: (ctx) => {
-    const profile = profileOf(ctx);
+  check: async (ctx) => {
+    const settings = settingsOf(ctx);
     const found: Finding[] = [];
     for (const diagram of ctx.doc.diagrams) {
-      for (const s of contrastOf(diagram, profile).skipped) {
+      for (const s of (await contrastOf(diagram, settings)).skipped) {
         if (!s.blocking) continue;
         const line = fileLine(diagram, s.line);
         found.push({
@@ -23,7 +24,8 @@ export const contrastDirectiveUnauditable: Rule = {
           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.",
         });
       }
     }

package/src/rules/contrast-text-below-aa.ts

@@ -1,5 +1,5 @@
 import { compositeOver, wcagRatio } from "../parse/color.ts";
-import { CONTRAST_OPTIONS, contrastOf, fileLine, profileOf } from "./shared.ts";
+import { CONTRAST_OPTIONS, contrastOf, fileLine, settingsOf } from "./shared.ts";
 import { type Edit, type Finding, RULE, type Rule } from "./types.ts";
 
 const AA_NORMAL = 4.5;
@@ -12,18 +12,19 @@ const ratioOn = (fg: string, bg: string): number => wcagRatio(compositeOver(fg,
 // reads better, and only when that clears 4.5:1 on every background the
 // directive is scored against. Choosing a brand colour is a design decision, so
 // anything else stays reported. A linkStyle color: takes the same path, and it
-// never clears: its label box is #e8e8e8 in light and #585858 in dark, where
+// never clears on GitHub's canvas: its label box is #e8e8e8 in light and
+// #585858 in dark, where
 // black and white each fail one theme, so edge label findings stay reported.
 export const contrastTextBelowAa: Rule = {
   id: RULE.TEXT,
   category: "contrast",
   summary: "label text below 4.5:1 against its fill",
   options: CONTRAST_OPTIONS,
-  check: (ctx) => {
-    const profile = profileOf(ctx);
+  check: async (ctx) => {
+    const settings = settingsOf(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, settings)).pairs) {
         if (p.kind !== "text" || p.passes) continue;
         const where = [p.theme, p.row].filter(Boolean).join("/");
         const line = fileLine(diagram, p.line);
@@ -36,23 +37,25 @@ export const contrastTextBelowAa: Rule = {
             `${p.directive.kind} ${p.selector}: text ${p.assessment.ratio.toFixed(2)}:1 < ${AA_NORMAL} ` +
             `(${p.foreground} on ${p.background}${where ? `, ${where}` : ""})`,
           remediation:
-            profile === "mkdocs-material"
+            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 === "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.",
+              : 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) => {
-    const profile = profileOf(ctx);
+  fix: async (ctx) => {
+    const settings = settingsOf(ctx);
     // Under a host profile color: is ignored, so there is nothing to rewrite.
-    if (profile === "mkdocs-material") return [];
+    if (settings.profile === "mkdocs-material") return [];
     const edits: Edit[] = [];
     for (const diagram of ctx.doc.diagrams) {
-      const { pairs } = 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;

package/src/rules/registry.ts

@@ -7,7 +7,7 @@
 import type { Config } from "../config.ts";
 import { RuleOptionError, UnknownRuleError } from "../errors.ts";
 import { compositeOver, wcagRatio } from "../parse/color.ts";
-import { PROFILES } from "../parse/contrast.ts";
+import { canvasColourProblem, PROFILES, THEMES, type Theme } from "../parse/contrast.ts";
 import { canonicalPreset } from "../parse/metrics.ts";
 import { detectKeyword } from "../parse/stats.ts";
 import { FIX_ORDER, RULES } from "./index.ts";
@@ -56,9 +56,36 @@ const typeOf = (value: unknown): OptionType | null => {
   if (typeof value === "string") return "string";
   if (typeof value === "boolean") return "boolean";
   if (Array.isArray(value) && value.every((v) => typeof v === "string")) return "string[]";
+  if (isCanvasShape(value)) return "canvas";
   return null;
 };
 
+// An object naming light, dark or both, and nothing else. Its colours are
+// checked after the shape, so the message can say which side is wrong.
+const isCanvasShape = (value: unknown): value is Record<Theme, unknown> => {
+  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 as Theme));
+};
+
+const describeType = (want: OptionType): string =>
+  want === "canvas" ? 'an object such as { "light": "#ffffff", "dark": "#0d1117" }' : `a ${want}`;
+
+const checkCanvas = (where: string, rule: Rule, name: string, value: Record<Theme, unknown>): void => {
+  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])}`,
+      );
+    }
+  }
+};
+
 const checkOptions = (where: string, rule: Rule, options: RuleOptions): void => {
   const accepted = Object.keys(rule.options ?? {});
   for (const [name, value] of Object.entries(options)) {
@@ -68,8 +95,18 @@ const checkOptions = (where: string, rule: Rule, options: RuleOptions): void =>
       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 as Record<Theme, unknown>);
+  }
+  // Material draws its own page, so a canvas has nothing to set there.
+  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`);

package/src/rules/shared.ts

@@ -2,8 +2,21 @@
 // contrast pairs, derived once per diagram and shared, so two rules can never
 // disagree about what the same diagram holds.
 
+import { CanvasProfileError } from "../errors.ts";
 import type { Diagram } from "../model.ts";
-import { type ContrastResult, detectProfile, PROFILES, type Profile, scoreForProfile } from "../parse/contrast.ts";
+import {
+  type Canvas,
+  type CanvasSetting,
+  type ContrastResult,
+  canvasColourProblem,
+  detectProfile,
+  GITHUB_CANVAS,
+  PROFILES,
+  type Profile,
+  resolveCanvas,
+  scoreDiagram,
+  THEMES,
+} from "../parse/contrast.ts";
 import { type ComplexityMetrics, calculateComplexity, parseFailed, type ThresholdConfig } from "../parse/metrics.ts";
 import type { DiagramStats } from "../parse/stats.ts";
 import type { Finding, OptionSpec, RuleContext, RuleId } from "./types.ts";
@@ -26,7 +39,7 @@ export const COMPLEXITY_OPTIONS: OptionSpec = {
   depthWeight: "number",
 };
 
-export const CONTRAST_OPTIONS: OptionSpec = { profile: "string" };
+export const CONTRAST_OPTIONS: OptionSpec = { profile: "string", canvas: "canvas" };
 
 export interface Measured {
   stats: DiagramStats;
@@ -77,18 +90,45 @@ export const profileOf = (ctx: RuleContext): Profile => {
   return wanted === "auto" ? detectProfile(ctx.file) : (wanted as Profile);
 };
 
-const scored = new WeakMap<Diagram, Map<Profile, ContrastResult>>();
+// How a contrast rule scores a file: the profile, and the page canvas behind
+// anything page-backed.
+export interface ContrastSettings {
+  profile: Profile;
+  canvas: Canvas;
+}
+
+// The profile and canvas a contrast rule scores under. A canvas is GitHub's
+// unless the canvas option sets a side. Under mkdocs-material the page is
+// Material's own, so a canvas there is refused rather than ignored.
+export const settingsOf = (ctx: RuleContext): ContrastSettings => {
+  const profile = profileOf(ctx);
+  const setting = ctx.options.canvas as CanvasSetting | undefined;
+  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])}`);
+  }
+  if (profile === "mkdocs-material") throw new CanvasProfileError(ctx.file);
+  return { profile, canvas: resolveCanvas(setting) };
+};
+
+const scored = new WeakMap<Diagram, Map<string, Promise<ContrastResult>>>();
 
-export const contrastOf = (diagram: Diagram, profile: Profile): ContrastResult => {
-  let byProfile = scored.get(diagram);
-  if (!byProfile) {
-    byProfile = new Map();
-    scored.set(diagram, byProfile);
+// Scored once per diagram, profile and canvas. A sequence diagram is scored by
+// its theme variables, which Mermaid resolves asynchronously.
+export const contrastOf = (diagram: Diagram, settings: ContrastSettings): Promise<ContrastResult> => {
+  const { profile, canvas } = settings;
+  const key = `${profile}\u0000${canvas.light}\u0000${canvas.dark}`;
+  let bySettings = scored.get(diagram);
+  if (!bySettings) {
+    bySettings = new Map();
+    scored.set(diagram, bySettings);
   }
-  let result = byProfile.get(profile);
+  let result = bySettings.get(key);
   if (!result) {
-    result = scoreForProfile(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;
 };

package/src/rules/types.ts

@@ -44,7 +44,10 @@ export interface Finding {
   remediation?: string;
 }
 
-export type OptionType = "number" | "string" | "boolean" | "string[]";
+// "canvas" is an object { light?, dark? } of opaque CSS colours: the page a
+// diagram is drawn on. A rule that declares it receives --canvas-light and
+// --canvas-dark, as the contrast rules do.
+export type OptionType = "number" | "string" | "boolean" | "string[]" | "canvas";
 
 export type OptionSpec = Readonly<Record<string, OptionType>>;
 

package/src/testing.ts

@@ -14,7 +14,8 @@ import type { Finding, RuleOptions } from "./rules/types.ts";
 export interface RunOptions {
   // The rule's own options, as a config would give them.
   options?: RuleOptions;
-  // The run flags, as --preset and --profile would give them.
+  // The run flags, as --preset, --profile, --canvas-light and --canvas-dark
+  // would give them.
   flags?: RunFlags;
   // The file name, which decides markdown or a standalone diagram. Default test.md.
   file?: string;