@jpeakai/mermaidjs-lint 0.7.1 → 0.7.2

package/src/plugins/load.ts

@@ -52,19 +52,14 @@ const OPTION_TYPES = new Set<OptionType>(["number", "string", "boolean", "string
 // Option names every rule shares with the built-ins. See checkRule.
 const RESERVED_OPTIONS = ["preset", "profile"] as const;
 
-// Checks one rule's declaration and returns it, so a bad rule fails at load
-// rather than the first time it runs.
-const checkRule = (spec: string, key: string, raw: unknown, own: ReadonlySet<string>): PluginRule => {
+// A rule's category is one word, built in or declared by its plugin, and its
+// key starts with it.
+const checkRuleCategory = (spec: string, key: string, category: unknown, own: ReadonlySet<string>): void => {
   const where = `rule "${key}"`;
-  if (!isRecord(raw)) throw new PluginContractError(spec, `${where} must be an object`);
-  if (!RULE_KEY.test(key)) {
-    throw new PluginContractError(spec, `${where} is not a valid key; use lower-case words joined by hyphens`);
-  }
-  const { category, summary, options, check, fix } = raw;
   if (typeof category !== "string" || !CATEGORY_WORD.test(category)) {
     throw new PluginContractError(spec, `${where} needs a category of one lower-case word`);
   }
-  if (!BUILTIN_CATEGORIES.has(category) && !own.has(category)) {
+  if (!(BUILTIN_CATEGORIES.has(category) || own.has(category))) {
     throw new PluginContractError(
       spec,
       `${where} uses the category "${category}", which this plugin does not declare in meta.categories`,
@@ -73,32 +68,47 @@ const checkRule = (spec: string, key: string, raw: unknown, own: ReadonlySet<str
   if (!key.startsWith(`${category}-`)) {
     throw new PluginContractError(spec, `${where} must start with its category, as "${category}-short-name"`);
   }
-  if (typeof summary !== "string" || summary === "") throw new PluginContractError(spec, `${where} needs a summary`);
-  if (typeof check !== "function") throw new PluginContractError(spec, `${where} needs a check function`);
-  if (fix !== undefined && typeof fix !== "function") {
-    throw new PluginContractError(spec, `${where} fix must be a function`);
+};
+
+const checkRuleOptions = (spec: string, where: string, options: unknown): void => {
+  if (options === undefined) return;
+  const valid = isRecord(options) && Object.values(options).every((t) => OPTION_TYPES.has(t as OptionType));
+  if (!valid) {
+    throw new PluginContractError(
+      spec,
+      `${where} options must map names to number, string, boolean, string[] or canvas`,
+    );
   }
-  if (options !== undefined) {
-    const valid = isRecord(options) && Object.values(options).every((t) => OPTION_TYPES.has(t as OptionType));
-    if (!valid) {
+  // preset and profile keep their built-in meaning for every rule: the
+  // config checks the value against the built-in names, and --preset and
+  // --profile overwrite it. A rule may declare one to follow the run's
+  // setting, as a string, but cannot give the name another meaning.
+  for (const name of RESERVED_OPTIONS) {
+    if (name in options && options[name] !== "string") {
       throw new PluginContractError(
         spec,
-        `${where} options must map names to number, string, boolean, string[] or canvas`,
+        `${where} declares option "${name}" as ${String(options[name])}, but "${name}" is reserved for the built-in ${name}, which is a string set by --${name}; declare it as "string" to follow the run's ${name}, or pick another name`,
       );
     }
-    // preset and profile keep their built-in meaning for every rule: the
-    // config checks the value against the built-in names, and --preset and
-    // --profile overwrite it. A rule may declare one to follow the run's
-    // setting, as a string, but cannot give the name another meaning.
-    for (const name of RESERVED_OPTIONS) {
-      if (name in options && (options as Record<string, unknown>)[name] !== "string") {
-        throw new PluginContractError(
-          spec,
-          `${where} declares option "${name}" as ${String((options as Record<string, unknown>)[name])}, but "${name}" is reserved for the built-in ${name}, which is a string set by --${name}; declare it as "string" to follow the run's ${name}, or pick another name`,
-        );
-      }
-    }
   }
+};
+
+// Checks one rule's declaration and returns it, so a bad rule fails at load
+// rather than the first time it runs.
+const checkRule = (spec: string, key: string, raw: unknown, own: ReadonlySet<string>): PluginRule => {
+  const where = `rule "${key}"`;
+  if (!isRecord(raw)) throw new PluginContractError(spec, `${where} must be an object`);
+  if (!RULE_KEY.test(key)) {
+    throw new PluginContractError(spec, `${where} is not a valid key; use lower-case words joined by hyphens`);
+  }
+  const { category, summary, options, check, fix } = raw;
+  checkRuleCategory(spec, key, category, own);
+  if (typeof summary !== "string" || summary === "") throw new PluginContractError(spec, `${where} needs a summary`);
+  if (typeof check !== "function") throw new PluginContractError(spec, `${where} needs a check function`);
+  if (fix !== undefined && typeof fix !== "function") {
+    throw new PluginContractError(spec, `${where} fix must be a function`);
+  }
+  checkRuleOptions(spec, where, options);
   return raw as unknown as PluginRule;
 };
 
@@ -120,7 +130,7 @@ const checkCategories = (spec: string, raw: unknown): Record<string, string> =>
 // A plugin object is checked here, apart from how it was imported, so a test
 // can hold the same plugin to the same contract the loader does.
 export const parsePlugin = (spec: string, raw: unknown, reserved: ReadonlySet<string>): Plugin => {
-  if (!isRecord(raw) || !isRecord(raw.meta) || !isRecord(raw.rules)) {
+  if (!(isRecord(raw) && isRecord(raw.meta) && isRecord(raw.rules))) {
     throw new PluginContractError(spec, "the default export must be { meta, rules }");
   }
   const { name, namespace, apiVersion } = raw.meta;
@@ -157,50 +167,73 @@ export interface LocalLoad {
 // as one plugin under the fixed namespace `local`, and a file may export
 // `categories` to declare the word its rule uses. Each file fails on its own,
 // so one bad file does not hide the others, and the caller gets every failure.
+// A rule's key is its file's base name.
+const keyOf = (source: PluginSource): string => basename(source.path, extname(source.path));
+
+const groupByKey = (sources: PluginSource[]): Map<string, PluginSource[]> => {
+  const byKey = new Map<string, PluginSource[]>();
+  for (const source of sources) byKey.set(keyOf(source), [...(byKey.get(keyOf(source)) ?? []), source]);
+  return byKey;
+};
+
+const duplicateKeyError = (key: string, group: PluginSource[]): PluginContractError =>
+  new PluginContractError(
+    (group[0] as PluginSource).spec,
+    `rule "${key}" is defined by more than one file: ${group.map((s) => s.spec).join(", ")}; each rule comes from exactly one file, so rename or remove all but one`,
+  );
+
+// The categories the local files declare so far, and the file that first
+// declared each word.
+interface LocalCategories {
+  categories: Record<string, string>;
+  owner: Record<string, string>;
+}
+
+const mergeCategories = (seen: LocalCategories, spec: string, declared: Record<string, string>): void => {
+  for (const [word, description] of Object.entries(declared)) {
+    if (seen.categories[word] !== undefined && seen.categories[word] !== description) {
+      throw new PluginConflictError(
+        spec,
+        seen.owner[word] as string,
+        `declares category "${word}" with a different description than another local file`,
+      );
+    }
+    seen.categories[word] = description;
+    seen.owner[word] = spec;
+  }
+};
+
+// Imports one local file and returns its rule, unchecked until every file's
+// categories are known.
+const importLocal = async (source: PluginSource, seen: LocalCategories, runtime?: RuntimeInfo): Promise<unknown> => {
+  const mod = await importModule(source, runtime);
+  if (mod.default === undefined) {
+    throw new PluginContractError(source.spec, "has no default export; export one rule");
+  }
+  mergeCategories(seen, source.spec, checkCategories(source.spec, mod.categories));
+  return mod.default;
+};
+
 export const loadLocal = async (sources: PluginSource[], runtime?: RuntimeInfo): Promise<LocalLoad> => {
   const failures: PluginLoadError[] = [];
   const fail = (err: unknown): void => {
     if (!(err instanceof PluginLoadError)) throw err;
     failures.push(err);
   };
-  const categories: Record<string, string> = {};
-  const owner: Record<string, string> = {};
+  const seen: LocalCategories = { categories: {}, owner: {} };
+  const { categories } = seen;
   const loaded: { key: string; source: PluginSource; raw: unknown }[] = [];
   // A rule's key is its file's base name, so two files with one base name
   // (house-x.js and house-x.mjs) would claim one rule. Neither is imported,
   // and the failure names both, rather than one silently replacing the other.
-  const keyOf = (source: PluginSource): string => basename(source.path, extname(source.path));
-  const byKey = new Map<string, PluginSource[]>();
-  for (const source of sources) byKey.set(keyOf(source), [...(byKey.get(keyOf(source)) ?? []), source]);
+  const byKey = groupByKey(sources);
   for (const [key, group] of byKey) {
-    if (group.length < 2) continue;
-    fail(
-      new PluginContractError(
-        (group[0] as PluginSource).spec,
-        `rule "${key}" is defined by more than one file: ${group.map((s) => s.spec).join(", ")}; each rule comes from exactly one file, so rename or remove all but one`,
-      ),
-    );
+    if (group.length > 1) fail(duplicateKeyError(key, group));
   }
   for (const source of sources) {
     if ((byKey.get(keyOf(source))?.length ?? 0) > 1) continue;
     try {
-      const mod = await importModule(source, runtime);
-      if (mod.default === undefined) {
-        throw new PluginContractError(source.spec, "has no default export; export one rule");
-      }
-      const declared = checkCategories(source.spec, mod.categories);
-      for (const [word, description] of Object.entries(declared)) {
-        if (categories[word] !== undefined && categories[word] !== description) {
-          throw new PluginConflictError(
-            source.spec,
-            owner[word] as string,
-            `declares category "${word}" with a different description than another local file`,
-          );
-        }
-        categories[word] = description;
-        owner[word] = source.spec;
-      }
-      loaded.push({ key: keyOf(source), source, raw: mod.default });
+      loaded.push({ key: keyOf(source), source, raw: await importLocal(source, seen, runtime) });
     } catch (err) {
       fail(err);
     }
@@ -250,7 +283,7 @@ export const toRule = (namespace: string, key: string, rule: PluginRule): Rule =
     } catch (err) {
       return report(`threw: ${message(err)}`);
     }
-    if (!Array.isArray(found) || !found.every(validFinding)) {
+    if (!(Array.isArray(found) && found.every(validFinding))) {
       return report("returned something other than a list of { line, message } findings");
     }
     return found.map((f) => ({
@@ -273,7 +306,7 @@ export const toRule = (namespace: string, key: string, rule: PluginRule): Rule =
         if (!Array.isArray(edits))
           throw new PluginFixerError(id, "fixer returned something other than a list of edits");
         return edits.map((e: Edit) => {
-          if (!isRecord(e) || !isRecord(e.expect) || !EXPECTATIONS.has(e.expect.kind as string)) {
+          if (!(isRecord(e) && isRecord(e.expect) && EXPECTATIONS.has(e.expect.kind as string))) {
             throw new PluginFixerError(id, "fixer returned an edit with no valid expectation");
           }
           return { ...e, rule: id };

package/src/rules/complexity.ts

@@ -28,7 +28,7 @@ export const complexityRule = (spec: {
       const measured = await measure(diagram, config);
       if (!measured) continue;
       const hit = spec.hit(measured, config);
-      if (hit) found.push(finding(ctx, diagram, spec.id, hit.message, hit.remediation));
+      if (hit) found.push(finding(ctx, diagram, spec.id, hit));
     }
     return found;
   },

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

@@ -1,12 +1,44 @@
+import type { Diagram } from "../model.ts";
 import { compositeOver, wcagRatio } from "../parse/color.ts";
+import type { ContrastPair, ContrastSource, Profile } from "../parse/contrast.ts";
 import { CONTRAST_OPTIONS, contrastOf, fileLine, settingsOf } from "./shared.ts";
-import { type Edit, type Finding, RULE, type Rule } from "./types.ts";
+import { type Edit, type Finding, RULE, type Rule, type RuleContext } from "./types.ts";
 
 const AA_NORMAL = 4.5;
 const CANDIDATES = ["#000000", "#ffffff"] as const;
 
 const ratioOn = (fg: string, bg: string): number => wcagRatio(compositeOver(fg, bg), bg);
 
+// How to fix failing text, by who controls it and what the colour is.
+const remediationOf = (profile: Profile, kind: ContrastSource["kind"]): string => {
+  if (profile === "mkdocs-material") {
+    return "The host theme forces the label text, so change the fill until the host text reads on it in both themes.";
+  }
+  if (kind === "themeVariables") {
+    return "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.";
+  }
+  if (kind === "linkStyle") {
+    return "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.";
+  }
+  return "Darken or lighten the fill, or change color:, until the ratio reaches 4.5:1 in every theme.";
+};
+
+// The finding for one failing text pair.
+const textFinding = (ctx: RuleContext, diagram: Diagram, p: ContrastPair, profile: Profile): Finding => {
+  const where = [p.theme, p.row].filter(Boolean).join("/");
+  const line = fileLine(diagram, p.line);
+  return {
+    file: ctx.file,
+    line,
+    endLine: line,
+    rule: RULE.TEXT,
+    message:
+      `${p.directive.kind} ${p.selector}: text ${p.assessment.ratio.toFixed(2)}:1 < ${AA_NORMAL} ` +
+      `(${p.foreground} on ${p.background}${where ? `, ${where}` : ""})`,
+    remediation: remediationOf(profile, p.directive.kind),
+  };
+};
+
 // Label text must reach 4.5:1 against its fill, in every theme the fill is
 // scored in. The fix swaps a declared color: for black or white, whichever
 // reads better, and only when that clears 4.5:1 on every background the
@@ -25,26 +57,7 @@ export const contrastTextBelowAa: Rule = {
     const found: Finding[] = [];
     for (const diagram of ctx.doc.diagrams) {
       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);
-        found.push({
-          file: ctx.file,
-          line,
-          endLine: line,
-          rule: RULE.TEXT,
-          message:
-            `${p.directive.kind} ${p.selector}: text ${p.assessment.ratio.toFixed(2)}:1 < ${AA_NORMAL} ` +
-            `(${p.foreground} on ${p.background}${where ? `, ${where}` : ""})`,
-          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.",
-        });
+        if (p.kind === "text" && !p.passes) found.push(textFinding(ctx, diagram, p, settings.profile));
       }
     }
     return found;

package/src/rules/parse-diagram-unparseable.ts

@@ -38,7 +38,7 @@ export const parseDiagramUnparseable: Rule = {
       const remediation = EXTERNAL_TYPES.has(stats.diagram_type)
         ? `No fixer can help: mermaidjs-lint has no ${stats.diagram_type} parser. Redraw it as a type mermaid core includes, such as sequenceDiagram, or turn this rule off in the config.`
         : "Verify the diagram renders in mermaid.js and fix its syntax. Complexity rules are skipped for this diagram while it cannot be parsed.";
-      found.push(finding(ctx, diagram, RULE.UNPARSEABLE, messageOf(stats), remediation));
+      found.push(finding(ctx, diagram, RULE.UNPARSEABLE, { message: messageOf(stats), remediation }));
     }
     return found;
   },

package/src/rules/parse-fence-unterminated.ts

@@ -15,13 +15,11 @@ export const parseFenceUnterminated: Rule = {
     ctx.doc.diagrams
       .filter((d) => !d.terminated)
       .map((d) =>
-        finding(
-          ctx,
-          d,
-          RULE.FENCE_UNTERMINATED,
-          `mermaid fence opened at line ${d.startLine} is never closed`,
-          "Add a closing fence directly after the last line of the diagram, with the opening line's prefix: `> ` in a quote, the item's indent in a list.",
-        ),
+        finding(ctx, d, RULE.FENCE_UNTERMINATED, {
+          message: `mermaid fence opened at line ${d.startLine} is never closed`,
+          remediation:
+            "Add a closing fence directly after the last line of the diagram, with the opening line's prefix: `> ` in a quote, the item's indent in a list.",
+        }),
       ),
   fix: (ctx) => {
     const edits: Edit[] = [];

package/src/rules/registry.ts

@@ -127,19 +127,23 @@ const checkCanvas = (where: string, rule: Rule, name: string, value: Record<Them
   }
 };
 
-const checkOptions = (where: string, rule: Rule, options: RuleOptions): void => {
-  const accepted = Object.keys(rule.options ?? {});
-  for (const [name, value] of Object.entries(options)) {
-    const want = rule.options?.[name];
-    if (!want) {
-      const list = accepted.length > 0 ? `it accepts ${accepted.join(", ")}` : "it takes no 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 ${describeType(want)}`);
-    }
-    if (want === "canvas") checkCanvas(where, rule, name, value as Record<Theme, unknown>);
+// One option the rule must declare, holding a value of the declared type.
+const checkOption = (where: string, rule: Rule, name: string, value: unknown): void => {
+  const want = rule.options?.[name];
+  if (!want) {
+    const accepted = Object.keys(rule.options ?? {});
+    const list = accepted.length > 0 ? `it accepts ${accepted.join(", ")}` : "it takes no 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 ${describeType(want)}`);
+  }
+  if (want === "canvas") checkCanvas(where, rule, name, value as Record<Theme, unknown>);
+};
+
+// The options every rule shares with the built-ins, checked against each other
+// and the built-in names.
+const checkSharedOptions = (where: string, rule: Rule, options: RuleOptions): void => {
   // 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(
@@ -162,10 +166,20 @@ const checkOptions = (where: string, rule: Rule, options: RuleOptions): void =>
   }
 };
 
-export const buildRegistry = (input: RegistryInput): Registry => {
-  const { rules, fixOrder, categories, sources = [], config, ignoreUnknownPluginIds = false } = input;
-  const selection = input.selection ?? {};
-  checkSelection(selection, categories);
+const checkOptions = (where: string, rule: Rule, options: RuleOptions): void => {
+  for (const [name, value] of Object.entries(options)) checkOption(where, rule, name, value);
+  checkSharedOptions(where, rule, options);
+};
+
+// What the config makes of the rules: which are off, each rule's options, and
+// the settings dropped for a plugin that did not load.
+interface Configured {
+  off: Set<string>;
+  options: Map<RuleId, RuleOptions>;
+  ignored: string[];
+}
+
+const applyConfig = (rules: Rule[], config: Config | undefined, ignoreUnknownPluginIds: boolean): Configured => {
   const off = new Set<string>();
   const options = new Map<RuleId, RuleOptions>();
   const ignored: string[] = [];
@@ -192,6 +206,14 @@ export const buildRegistry = (input: RegistryInput): Registry => {
     options.set(rule.id, setting.options);
     if (setting.severity === "off") off.add(id);
   }
+  return { off, options, ignored };
+};
+
+export const buildRegistry = (input: RegistryInput): Registry => {
+  const { rules, fixOrder, categories, sources = [], config, ignoreUnknownPluginIds = false } = input;
+  const selection = input.selection ?? {};
+  checkSelection(selection, categories);
+  const { off, options, ignored } = applyConfig(rules, config, ignoreUnknownPluginIds);
   // Every rule starts on, the config turns some off, and then the category
   // flags have the last word for this run (MJL-0020).
   for (const rule of rules) {

package/src/rules/shared.ts

@@ -55,12 +55,17 @@ export const measure = async (diagram: Diagram, config: ThresholdConfig): Promis
   return { stats, metrics: calculateComplexity(stats, config) };
 };
 
+// A finding's text: what is wrong, and how to fix it when there is a way.
+export interface FindingText {
+  message: string;
+  remediation?: string | undefined;
+}
+
 export const finding = (
   ctx: RuleContext,
   diagram: Diagram,
   rule: RuleId,
-  message: string,
-  remediation?: string,
+  { message, remediation }: FindingText,
 ): Finding => ({
   file: ctx.file,
   line: diagram.startLine,
@@ -129,7 +134,7 @@ export const contrastOf = (diagram: Diagram, settings: ContrastSettings): Promis
   }
   let result = bySettings.get(key);
   if (!result) {
-    result = scoreDiagram(diagram.source, diagram.directives, profile, diagram.keyword, canvas);
+    result = scoreDiagram(diagram, profile, canvas);
     bySettings.set(key, result);
   }
   return result;