@jpeakai/mermaidjs-lint 0.6.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.6.0",
+  version: "0.6.1",
   type: "module",
   description: "Deterministic lint gates and verified fixers for Mermaid diagrams in markdown",
   license: "MIT",
@@ -181,8 +181,9 @@ class RuleOptionError extends UsageError {
 
 class CanvasProfileError extends UsageError {
   file;
-  constructor(file) {
-    super(`${file}: a canvas applies under the github profile only, and this file is scored under mkdocs-material, whose page is Material's own; drop the canvas for it, or pass --profile github`, "canvas-profile");
+  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;
   }
 }
@@ -1609,8 +1610,9 @@ var settingsOf = (ctx) => {
     if (problem)
       throw new Error(`canvas.${side} ${problem}: ${JSON.stringify(setting[side])}`);
   }
-  if (profile === "mkdocs-material")
-    throw new CanvasProfileError(ctx.file);
+  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;
@@ -2048,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];
@@ -2058,21 +2063,33 @@ var optionsFor = (rule, configured, flags) => {
   if (typeof options.preset === "string")
     options.preset = canonicalPreset(options.preset) ?? options.preset;
   const canvas = flags.canvas;
-  if (canvas && THEMES.some((side) => canvas[side] !== undefined) && rule.options?.canvas === "canvas") {
-    const configured2 = typeof options.canvas === "object" && options.canvas !== null ? options.canvas : {};
-    const merged = { ...configured2 };
-    for (const side of THEMES) {
-      const value = canvas[side];
-      if (value !== undefined)
-        merged[side] = value;
+  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;
     }
-    options.canvas = 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));
 };
@@ -2244,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))
@@ -2839,7 +2856,8 @@ Examples of every rule, with fixes: https://jpeakai.github.io/jpai-mermaidjs-lin
 --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 with a usage error.
+  (#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.
@@ -3025,6 +3043,10 @@ var run = async (argv, cwd) => {
     throw new FlagError("files", "no matching files");
   if (values.fix)
     await refuseOutsideLinks(files, root, cwd);
+  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) {

package/dist/index.js

@@ -103,8 +103,9 @@ class RuleOptionError extends UsageError {
 
 class CanvasProfileError extends UsageError {
   file;
-  constructor(file) {
-    super(`${file}: a canvas applies under the github profile only, and this file is scored under mkdocs-material, whose page is Material's own; drop the canvas for it, or pass --profile github`, "canvas-profile");
+  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;
   }
 }
@@ -1531,8 +1532,9 @@ var settingsOf = (ctx) => {
     if (problem)
       throw new Error(`canvas.${side} ${problem}: ${JSON.stringify(setting[side])}`);
   }
-  if (profile === "mkdocs-material")
-    throw new CanvasProfileError(ctx.file);
+  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;
@@ -1970,7 +1972,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];
@@ -1980,21 +1985,33 @@ var optionsFor = (rule, configured, flags) => {
   if (typeof options.preset === "string")
     options.preset = canonicalPreset(options.preset) ?? options.preset;
   const canvas = flags.canvas;
-  if (canvas && THEMES.some((side) => canvas[side] !== undefined) && rule.options?.canvas === "canvas") {
-    const configured2 = typeof options.canvas === "object" && options.canvas !== null ? options.canvas : {};
-    const merged = { ...configured2 };
-    for (const side of THEMES) {
-      const value = canvas[side];
-      if (value !== undefined)
-        merged[side] = value;
+  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;
     }
-    options.canvas = 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));
 };
@@ -2006,7 +2023,7 @@ import { parseArgs } from "node:util";
 // package.json
 var package_default = {
   name: "@jpeakai/mermaidjs-lint",
-  version: "0.6.0",
+  version: "0.6.1",
   type: "module",
   description: "Deterministic lint gates and verified fixers for Mermaid diagrams in markdown",
   license: "MIT",
@@ -2243,7 +2260,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))
@@ -2839,7 +2856,8 @@ Examples of every rule, with fixes: https://jpeakai.github.io/jpai-mermaidjs-lin
 --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 with a usage error.
+  (#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.
@@ -3025,6 +3043,10 @@ var run = async (argv, cwd) => {
     throw new FlagError("files", "no matching files");
   if (values.fix)
     await refuseOutsideLinks(files, root, cwd);
+  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) {
@@ -3082,6 +3104,7 @@ export {
   collectFiles,
   checkModel,
   checkMarkdown,
+  canvasSetAside,
   buildRegistry,
   buildDocModel,
   UsageError,

package/dist/testing.js

@@ -50,8 +50,9 @@ class RuleOptionError extends UsageError {
 
 class CanvasProfileError extends UsageError {
   file;
-  constructor(file) {
-    super(`${file}: a canvas applies under the github profile only, and this file is scored under mkdocs-material, whose page is Material's own; drop the canvas for it, or pass --profile github`, "canvas-profile");
+  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;
   }
 }
@@ -1429,8 +1430,9 @@ var settingsOf = (ctx) => {
     if (problem)
       throw new Error(`canvas.${side} ${problem}: ${JSON.stringify(setting[side])}`);
   }
-  if (profile === "mkdocs-material")
-    throw new CanvasProfileError(ctx.file);
+  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;
@@ -1867,7 +1869,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];
@@ -1877,21 +1882,29 @@ var optionsFor = (rule, configured, flags) => {
   if (typeof options.preset === "string")
     options.preset = canonicalPreset(options.preset) ?? options.preset;
   const canvas = flags.canvas;
-  if (canvas && THEMES.some((side) => canvas[side] !== undefined) && rule.options?.canvas === "canvas") {
-    const configured2 = typeof options.canvas === "object" && options.canvas !== null ? options.canvas : {};
-    const merged = { ...configured2 };
-    for (const side of THEMES) {
-      const value = canvas[side];
-      if (value !== undefined)
-        merged[side] = value;
+  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;
     }
-    options.canvas = merged;
+  }
+  if (file !== undefined && setsAside(rule, options, flags, file)) {
+    for (const name of canvasOptions(rule))
+      delete options[name];
   }
   return options;
 };
 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));
 };
@@ -2004,7 +2017,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))

package/dist/types/check.d.ts

@@ -8,6 +8,7 @@ export interface RunFlags {
     canvas?: CanvasSetting;
 }
 export declare const checkRunFlags: (flags: RunFlags, prefix?: string) => void;
-export declare const optionsFor: (rule: Rule, configured: RuleOptions | undefined, flags: RunFlags) => RuleOptions;
+export declare const optionsFor: (rule: Rule, configured: RuleOptions | undefined, flags: RunFlags, file?: string) => RuleOptions;
+export declare const canvasSetAside: (file: string, flags?: RunFlags, registry?: Registry) => boolean;
 export declare const checkModel: (doc: DocModel, file: string, flags?: RunFlags, registry?: Registry) => Promise<Finding[]>;
 export declare const checkMarkdown: (src: string, file: string, flags?: RunFlags, registry?: Registry) => Promise<Finding[]>;

package/dist/types/errors.d.ts

@@ -49,7 +49,7 @@ export declare class RuleOptionError extends UsageError {
 }
 export declare class CanvasProfileError extends UsageError {
     readonly file: string;
-    constructor(file: string);
+    constructor(file: string, cause?: "flag" | "profile");
 }
 export declare class FixOutsideRootError extends UsageError {
     readonly file: string;

package/dist/types/index.d.ts

@@ -1,4 +1,4 @@
-export { checkMarkdown, checkModel, type RunFlags } from "./check.ts";
+export { canvasSetAside, checkMarkdown, checkModel, type RunFlags } from "./check.ts";
 export { main } from "./cli.ts";
 export { type Config, loadConfig, type PluginLoading, parseConfig, type RuleSetting, type Severity } from "./config.ts";
 export * from "./errors.ts";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jpeakai/mermaidjs-lint",
-  "version": "0.6.0",
+  "version": "0.6.1",
   "type": "module",
   "description": "Deterministic lint gates and verified fixers for Mermaid diagrams in markdown",
   "license": "MIT",

package/src/check.ts

@@ -6,7 +6,14 @@
 
 import { FlagError } from "./errors.ts";
 import { buildDocModel, type DocModel, documentKind } from "./model.ts";
-import { type CanvasSetting, canvasColourProblem, PROFILES, THEMES, type Theme } from "./parse/contrast.ts";
+import {
+  type CanvasSetting,
+  canvasColourProblem,
+  detectProfile,
+  PROFILES,
+  THEMES,
+  type Theme,
+} from "./parse/contrast.ts";
 import { canonicalPreset, PRESET_NAMES } from "./parse/metrics.ts";
 import { BUILTIN, HELPERS, type Registry } from "./rules/registry.ts";
 import type { Finding, Rule, RuleOptions } from "./rules/types.ts";
@@ -57,10 +64,36 @@ export const checkRunFlags = (flags: RunFlags, prefix = ""): void => {
   }
 };
 
+// Every option the rule declares with the canvas type, whatever its name.
+const canvasOptions = (rule: Rule): string[] =>
+  Object.entries(rule.options ?? {})
+    .filter(([, type]) => type === "canvas")
+    .map(([name]) => name);
+
+const hasFlagCanvas = (flags: RunFlags): boolean => THEMES.some((side) => flags.canvas?.[side] !== undefined);
+
+// A canvas from the config is set aside, rather than refused, for a file the
+// auto profile reads as mkdocs-material. The config covers the whole tree and
+// has no per-path setting, so refusing it would stop every run over a repo
+// that holds a Material site beside its GitHub-rendered markdown. A canvas
+// flag, or an explicit mkdocs-material profile, still refuses (MJL-0019).
+const setsAside = (rule: Rule, options: Record<string, unknown>, flags: RunFlags, file: string): boolean =>
+  !hasFlagCanvas(flags) &&
+  rule.options?.profile !== undefined &&
+  (options.profile ?? "auto") === "auto" &&
+  canvasOptions(rule).some((name) => options[name] !== undefined) &&
+  detectProfile(file) === "mkdocs-material";
+
 // The options a rule runs with: its configured options, then a flag for any
 // option the rule declares. A preset reaches the rule by its canonical name,
-// so a plugin rule never has to resolve an alias such as `high` or `H`.
-export const optionsFor = (rule: Rule, configured: RuleOptions | undefined, flags: RunFlags): RuleOptions => {
+// so a plugin rule never has to resolve an alias such as `high` or `H`. Given
+// the file, a config canvas the file sets aside is dropped.
+export const optionsFor = (
+  rule: Rule,
+  configured: RuleOptions | undefined,
+  flags: RunFlags,
+  file?: string,
+): RuleOptions => {
   const options: Record<string, unknown> = { ...configured };
   for (const name of ["preset", "profile"] as const) {
     const value = flags[name];
@@ -68,20 +101,36 @@ export const optionsFor = (rule: Rule, configured: RuleOptions | undefined, flag
   }
   if (typeof options.preset === "string") options.preset = canonicalPreset(options.preset) ?? options.preset;
   // A canvas flag sets one side over the configured canvas, so --canvas-dark
-  // alone keeps a configured light side.
+  // alone keeps a configured light side. It reaches every option of the
+  // canvas type, not only one named canvas.
   const canvas = flags.canvas;
-  if (canvas && THEMES.some((side) => canvas[side] !== undefined) && rule.options?.canvas === "canvas") {
-    const configured = typeof options.canvas === "object" && options.canvas !== null ? options.canvas : {};
-    const merged: Record<string, string> = { ...(configured as Record<string, string>) };
-    for (const side of THEMES) {
-      const value = canvas[side];
-      if (value !== undefined) merged[side] = value;
+  if (canvas && hasFlagCanvas(flags)) {
+    for (const name of canvasOptions(rule)) {
+      const current = options[name];
+      const merged: Record<string, string> = {
+        ...(typeof current === "object" && current !== null ? (current as Record<string, string>) : {}),
+      };
+      for (const side of THEMES) {
+        const value = canvas[side];
+        if (value !== undefined) merged[side] = value;
+      }
+      options[name] = merged;
     }
-    options.canvas = merged;
+  }
+  if (file !== undefined && setsAside(rule, options, flags, file)) {
+    for (const name of canvasOptions(rule)) delete options[name];
   }
   return options;
 };
 
+// Whether any rule sets its config canvas aside for this file, so the command
+// can say which files were scored without it.
+export const canvasSetAside = (file: string, flags: RunFlags = {}, registry: Registry = BUILTIN): boolean =>
+  registry.rules.some((rule) => {
+    const options = optionsFor(rule, registry.options.get(rule.id), flags);
+    return setsAside(rule, options as Record<string, unknown>, flags, file);
+  });
+
 export const checkModel = async (
   doc: DocModel,
   file: string,
@@ -90,7 +139,7 @@ export const checkModel = async (
 ): Promise<Finding[]> => {
   checkRunFlags(flags);
   const perRule = registry.rules.map((rule) =>
-    rule.check({ doc, file, options: optionsFor(rule, registry.options.get(rule.id), flags), helpers: HELPERS }),
+    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));

package/src/cli.ts

@@ -5,7 +5,7 @@ import { lstat, readFile, realpath, writeFile } from "node:fs/promises";
 import { isAbsolute, relative, resolve } from "node:path";
 import { parseArgs } from "node:util";
 import pkg from "../package.json" with { type: "json" };
-import { checkModel, checkRunFlags, type RunFlags } from "./check.ts";
+import { canvasSetAside, checkModel, checkRunFlags, type RunFlags } from "./check.ts";
 import { FixOutsideRootError, FlagError, MermaidLintError, UsageError } from "./errors.ts";
 import { collectFiles, DIAGRAM_FILE_EXTS, SKIP_DIRS } from "./files.ts";
 import { fixSourceReport } from "./fix/engine.ts";
@@ -55,7 +55,8 @@ Examples of every rule, with fixes: https://jpeakai.github.io/jpai-mermaidjs-lin
 --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 with a usage error.
+  (#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.
@@ -281,6 +282,16 @@ const run = async (argv: string[], cwd: string): Promise<number> => {
   if (files.length === 0) throw new FlagError("files", "no matching files");
   if (values.fix) await refuseOutsideLinks(files, root, cwd);
 
+  // A config canvas is set aside for a file the auto profile reads as
+  // mkdocs-material, and one line names every such file, so the run says what
+  // it scored without the canvas.
+  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(", ")}`,
+    );
+  }
+
   // Every rule, in check and in fix, sees the file as an absolute path, so a
   // rule that reads the path sees one form, and the auto profile is found
   // from the file's own folder whatever the process's working directory. The

package/src/errors.ts

@@ -132,13 +132,22 @@ export class RuleOptionError extends UsageError {
 
 // A canvas was set for a file scored under mkdocs-material, whose page is
 // Material's own, so the canvas would change nothing. Ignoring it would report
-// a pass the caller did not ask for, so the run stops instead.
+// a pass the caller did not ask for, so the run stops instead. A config canvas
+// on a file the auto profile reads as mkdocs-material is set aside, not
+// refused (MJL-0019), so this error comes from one of two explicit settings,
+// and its hint names the way out of each.
 export class CanvasProfileError extends UsageError {
   readonly file: string;
 
-  constructor(file: string) {
+  // "flag": a canvas flag met a file the auto profile reads as mkdocs-material.
+  // "profile": a canvas met an explicitly set mkdocs-material profile.
+  constructor(file: string, cause: "flag" | "profile" = "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; drop the canvas for it, or pass --profile github`,
+      `${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;

package/src/fix/engine.ts

@@ -73,7 +73,7 @@ export const fixSourceReport = async (
 
     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)) return true;

package/src/index.ts

@@ -1,6 +1,6 @@
 // Public API.
 
-export { checkMarkdown, checkModel, type RunFlags } from "./check.ts";
+export { canvasSetAside, checkMarkdown, checkModel, type RunFlags } from "./check.ts";
 export { main } from "./cli.ts";
 export { type Config, loadConfig, type PluginLoading, parseConfig, type RuleSetting, type Severity } from "./config.ts";
 export * from "./errors.ts";

package/src/rules/shared.ts

@@ -109,7 +109,9 @@ export const settingsOf = (ctx: RuleContext): ContrastSettings => {
     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);
+  if (profile === "mkdocs-material") {
+    throw new CanvasProfileError(ctx.file, ctx.options.profile === "mkdocs-material" ? "profile" : "flag");
+  }
   return { profile, canvas: resolveCanvas(setting) };
 };
 

package/src/rules/types.ts

@@ -45,8 +45,8 @@ export interface Finding {
 }
 
 // "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.
+// diagram is drawn on. Every option of this type, whatever its name, 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>>;