@jpeakai/mermaidjs-lint 0.1.0 → 0.2.0

package/src/errors.ts

@@ -51,6 +51,20 @@ export class ConfigNotFoundError extends UsageError {
   }
 }
 
+// --no-plugins runs no project code, and a .mjs config is code, so the run
+// stops before importing it. A .json config is data and is read as usual.
+export class ConfigCodeError extends UsageError {
+  readonly file: string;
+
+  constructor(file: string) {
+    super(
+      `${file}: a .mjs config is code, and --no-plugins runs no project code; pass --config with a .json config, or drop --no-plugins`,
+      "config-code",
+    );
+    this.file = file;
+  }
+}
+
 // Two config files at one root, so neither can be picked.
 export class AmbiguousConfigError extends UsageError {
   readonly files: string[];
@@ -178,9 +192,10 @@ export class PluginSourceError extends PluginLoadError {
 
 // --- plugins: a loaded plugin misbehaved while running --------------------
 
-// A fixer threw or returned something that is not a list of valid edits.
-// Unlike a check, this stops the run, because carrying on after a corrupt edit
-// is worse than stopping.
+// A fixer threw, returned a non-list, or returned an edit with no valid expect.
+// An edit with bad offsets is not this error: the engine refuses it and the
+// finding stays. Unlike a check, this stops the run, because carrying on after
+// a corrupt edit is worse than stopping.
 export class PluginFixerError extends MermaidLintError {
   readonly rule: string;
 

package/src/files.ts

@@ -5,8 +5,10 @@
 
 import { type Dirent, readdirSync, statSync } from "node:fs";
 import { extname, join, resolve } from "node:path";
+import { DIAGRAM_EXTS } from "./model.ts";
 
-export const DIAGRAM_FILE_EXTS = new Set([".mmd", ".md", ".markdown"]);
+// What a directory walk picks up: raw diagram files and markdown files.
+export const DIAGRAM_FILE_EXTS = new Set<string>([...DIAGRAM_EXTS, ".md", ".markdown"]);
 
 // Directories never worth walking. Vendored trees dwarf real content, and
 // dot-directories hold VCS and tool state, not diagrams. A denylist keeps the

package/src/fix/engine.ts

@@ -1,10 +1,10 @@
 // The fix engine: a fixpoint loop over splice edits. Each pass rebuilds the
-// model, asks the fixers for edits in priority order, and keeps the first edit
-// that survives verification. Offsets are only valid for the source they were
+// model, asks the fixers for edits in priority order, and keeps the first batch
+// or single edit that survives verification. Offsets are only valid for the source they were
 // computed from, so every accepted edit restarts the pass.
 
 import { optionsFor, type RunFlags } from "../check.ts";
-import { buildDocModel } from "../model.ts";
+import { buildDocModel, documentKind } from "../model.ts";
 import { BUILTIN, HELPERS, type Registry } from "../rules/registry.ts";
 import type { Edit } from "../rules/types.ts";
 import { verify } from "./verify.ts";
@@ -44,7 +44,7 @@ export const fixSourceReport = async (
   flags: RunFlags = {},
   registry: Registry = BUILTIN,
 ): Promise<FixReport> => {
-  const kind = file.toLowerCase().endsWith(".mmd") ? "diagram" : "markdown";
+  const kind = documentKind(file);
   const applied: Edit[] = [];
   const refused: Edit[] = [];
   // An edit refused once stays refused while its source slice is unchanged.

package/src/fix/verify.ts

@@ -1,5 +1,5 @@
-// Proof obligations for a fix. The engine applies one edit, re-parses, and
-// checks that the document changed exactly as the edit declared. An edit that
+// Proof obligations for a fix. The engine applies edits, re-parses, and checks
+// that the document still satisfies each edit's declared expectation. An edit that
 // cannot be proven is refused, the source is left alone, and the finding stays.
 
 import type { Node, Root } from "mdast";

package/src/index.ts

@@ -6,7 +6,7 @@ export { type Config, loadConfig, type PluginLoading, parseConfig, type RuleSett
 export * from "./errors.ts";
 export { collectFiles } from "./files.ts";
 export { type FixReport, fixSource, fixSourceReport } from "./fix/engine.ts";
-export { buildDocModel, type Diagram, type DocModel } from "./model.ts";
+export { buildDocModel, DIAGRAM_EXTS, type Diagram, type DocModel, documentKind } from "./model.ts";
 export type { ContrastAssessment, StyleDirective, ValueSpan } from "./parse/color.ts";
 export { PRESETS, thresholdsFrom } from "./parse/metrics.ts";
 export { type DiagramStats, detectKeyword, extractStats } from "./parse/stats.ts";

package/src/model.ts

@@ -107,6 +107,16 @@ const collectMermaid = (node: Node, out: Code[]): void => {
   for (const child of (node as Parent).children ?? []) collectMermaid(child, out);
 };
 
+// The extensions of a raw diagram file. Any other file is read as markdown.
+export const DIAGRAM_EXTS = [".mmd", ".mermaid"] as const;
+
+// How a file is read, from its name alone: a raw diagram, or markdown whose
+// mermaid fences are the diagrams.
+export const documentKind = (file: string): "markdown" | "diagram" => {
+  const lower = file.toLowerCase();
+  return DIAGRAM_EXTS.some((ext) => lower.endsWith(ext)) ? "diagram" : "markdown";
+};
+
 export const buildDocModel = (src: string, kind: "markdown" | "diagram" = "markdown"): DocModel => {
   const lineStarts = lineStartsOf(src);
   if (kind === "diagram") {

package/src/parse/color.ts

@@ -88,8 +88,8 @@ const STYLE_RE = /^[ \t]*style\s+(\S+)\s+(.+?)\s*;?\s*$/di;
 const LINKSTYLE_RE = /^[ \t]*linkStyle\s+(\S+)\s+(.+?)\s*;?\s*$/di;
 const INLINE_CLASS_RE = /([A-Za-z_][\w-]*)(?:\[[^\]]*\]|\([^)]*\)|\{[^}]*\}|>[^<]*)?:::([A-Za-z_][\w-]*)/g;
 
-// Mermaid allows `,` and `;` between properties, and a value never contains
-// either in well-formed source, so a plain split is safe.
+// Mermaid allows `,` and `;` between properties. A plain split assumes no
+// value holds an escaped `\,`, which holds for well-formed source.
 const parseProperties = (
   raw: string,
   rawStart: number,

package/src/parse/contrast.ts

@@ -1,8 +1,11 @@
 // Contrast scoring of a diagram's style directives, by the context the diagram
 // is read in. Two kinds of pair are scored: text (fill x color, at least 4.5)
-// and border (fill x stroke, at least 3, the UI-component rule). Only pairs
-// whose both sides are declared are scored, because an unset property falls
-// back to a theme default that cannot be resolved without rendering.
+// and border (fill x stroke, at least 3, the UI-component rule). Under github a
+// flowchart pair is scored only when both sides are declared, because an unset
+// property falls back to a theme default that cannot be resolved without
+// rendering. mkdocs-material scores the host text colour instead, and
+// erDiagram substitutes known theme text when no color is set. A linkStyle
+// color: is edge label text, scored on Mermaid's own label box under github.
 //
 // Profiles, by who controls the label text:
 //   github           the author does, so the declared pairs are scored as written
@@ -34,6 +37,30 @@ const GITHUB = { light: { bg: "#ffffff" }, dark: { bg: "#0d1117" } } as const;
 
 const THEMES: Theme[] = ["light", "dark"];
 
+// The box an edge label is drawn on, read off Mermaid 11's theme sources. A
+// linkStyle color: becomes an inline `color: ... !important` on the label's
+// div and span, and the text sits in a <p> inside them. Three layers paint the
+// box behind it: the div (.labelBkg, edgeLabelBackground faded to alpha 0.5),
+// the span and the p (both .edgeLabel, edgeLabelBackground as is). The theme's
+// edgeLabelBackground is rgba(232,232,232,0.8) in default (labelBackground)
+// and lighten(#181818, 25) = #585858 in dark, opaque. GitHub draws the default
+// theme in light mode and the dark theme in dark mode, the same assumption the
+// erDiagram rows make, so the stack is composited over the matching canvas:
+// #e8e8e8 in light and #585858 in dark. No one colour clears 4.5:1 on both, so
+// a fixed edge label colour always fails one theme. Under mkdocs-material the
+// host sets `.edgeLabel p { color: var(--md-mermaid-edge-color) }` on the p
+// itself, which beats the colour the p would inherit, so color: is ignored
+// there and nothing new is scored.
+const 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)" },
+} as const;
+
+export const edgeLabelBackground = (theme: Theme): string => {
+  const { box, backing } = MERMAID_EDGE_LABEL[theme];
+  return compositeOver(box, compositeOver(box, compositeOver(backing, GITHUB[theme].bg)));
+};
+
 // Mermaid's own erDiagram row surfaces under its default and dark themes. A
 // fill lands on the even attribute rows only, and a declared color lands on all
 // rows, so it has to read on the fill and on a theme surface that flips with
@@ -57,7 +84,8 @@ export interface ContrastPair {
   passes: boolean;
   theme?: Theme;
   row?: ErRow;
-  // Reported by the original auditor but never gating: a border on a faint fill
+  // Set on border pairs under mkdocs-material and erDiagram. The pair is still
+  // scored but never gates: a border on a faint fill
   // cannot clear 3:1 in both themes for a saturated hue. There is no warning
   // level, so an advisory pair is not a finding.
   advisory?: boolean;
@@ -93,10 +121,28 @@ const scorePair = (kind: PairKind, d: StyleDirective, fg: string, bg: string): C
 
 const message = (err: unknown): string => (err instanceof Error ? err.message : String(err));
 
+// A linkStyle color: is edge label text, scored on the label box in both themes.
+// A linkStyle without one styles only the line, which has no label pair.
+const scoreEdgeLabel = (d: StyleDirective, pairs: ContrastPair[], skipped: SkippedDirective[]): void => {
+  const { color } = d.properties;
+  if (!color) return;
+  try {
+    pairs.push(...THEMES.map((t) => scoreHostPair("text", d, t, color, edgeLabelBackground(t))));
+  } catch (err) {
+    skipped.push({
+      selector: d.selector,
+      line: d.line,
+      reason: `edge label text unparseable: ${message(err)}`,
+      blocking: true,
+    });
+  }
+};
+
 export const scoreGithub = (directives: StyleDirective[]): ContrastResult => {
   const pairs: ContrastPair[] = [];
   const skipped: SkippedDirective[] = [];
   for (const d of directives) {
+    if (d.kind === "linkStyle") scoreEdgeLabel(d, pairs, skipped);
     if (d.kind !== "classDef" && d.kind !== "style") continue;
     const { fill, color, stroke } = d.properties;
     const note = (reason: string, blocking?: boolean): void => {
@@ -172,6 +218,13 @@ export const scoreMkdocs = (directives: StyleDirective[]): ContrastResult => {
   const pairs: ContrastPair[] = [];
   const skipped: SkippedDirective[] = [];
   for (const d of directives) {
+    if (d.kind === "linkStyle" && d.properties.color) {
+      skipped.push({
+        selector: d.selector,
+        line: d.line,
+        reason: "color: ignored, because the host theme forces edge label text",
+      });
+    }
     if (d.kind !== "classDef" && d.kind !== "style") continue;
     const { fill, stroke, color } = d.properties;
     const note = (reason: string): void => {
@@ -267,7 +320,8 @@ export const scoreForProfile = (
   return keyword === "erDiagram" ? scoreEr(directives) : scoreGithub(directives);
 };
 
-// An ancestor mkdocs.yml means the diagram is read through Material.
+// An ancestor mkdocs.yml or mkdocs.yaml, searched up to 20 levels, means the
+// diagram is read through Material.
 export const detectProfile = (filePath: string): Profile => {
   let dir = dirname(resolve(filePath));
   for (let i = 0; i < 20; i++) {

package/src/parse/metrics.ts

@@ -167,14 +167,22 @@ export const calculateComplexity = (stats: DiagramStats, config: ThresholdConfig
   };
 };
 
-// A multi-line diagram that yielded no nodes is a silent parser failure, so its
-// metrics cannot be trusted. A diagram of only a keyword line has no structure
-// to extract and is fine.
+// Whether a diagram failed to parse, so its metrics cannot be trusted. A
+// parser's own error always counts: that is what catches `graph TD; A-->; B[[[`.
+// A Langium grammar that read the diagram without an error parsed it, even with
+// no nodes, as `pie` then `title Pets`, or `info` then `showInfo`, legitimately
+// have none. Mermaid core can read a multi-line diagram into an empty
+// structure without complaint, so there a multi-line diagram with no nodes is
+// taken as a silent failure. A one-line diagram may have none, as `info` does.
 export const parseFailed = (content: string, stats: DiagramStats): boolean => {
-  const lines = content.split("\n").filter((l) => {
+  if (stats.error !== null) return true;
+  if (stats.parser_used === "langium" || stats.nodes > 0) return false;
+  return sourceLines(content) > 1;
+};
+
+// The lines that carry diagram source: not blank, a comment or a frontmatter fence.
+export const sourceLines = (content: string): number =>
+  content.split("\n").filter((l) => {
     const t = l.trim();
     return t && !t.startsWith("%%") && t !== "---";
-  });
-  if (lines.length <= 1) return false;
-  return stats.nodes === 0;
-};
+  }).length;

package/src/parse/stats.ts

@@ -39,9 +39,12 @@ export interface DiagramStats {
   max_subgraph_depth: number;
   node_ids: string[];
   subgraph_names: string[];
-  parser_used: "langium" | "mermaid-core" | "custom";
+  // The parser that read the diagram, or, on a failure, the one whose reason
+  // `error` carries: langium for the types its grammars own, else mermaid-core.
+  parser_used: "langium" | "mermaid-core";
   diagram_type: string;
-  // The reason the last parser gave when no parser produced structure.
+  // The parser's reason, on one line, when no parser produced structure. Line
+  // numbers in it count from the diagram's own first line.
   error: string | null;
 }
 
@@ -72,7 +75,8 @@ export function detectKeyword(content: string): string | null {
   // A leading "---" opens a YAML frontmatter block that runs to the next "---".
   // Everything between is config, not diagram source: returning its first key
   // (typically "config:") would miss the Langium dispatch table and mis-report a
-  // valid frontmatter-prefixed diagram (e.g. architecture-beta) as ParserFailure.
+  // valid frontmatter-prefixed diagram (e.g. architecture-beta) as unparseable
+  // (parseFailed in metrics.ts, reported as parse-diagram-unparseable).
   let seenContent = false;
   let inFrontmatter = false;
 
@@ -103,11 +107,15 @@ export async function extractStats(content: string): Promise<MermaidStats> {
   const keyword = detectKeyword(content) ?? "unknown";
 
   // 1. Langium grammar (@mermaid-js/parser) — typed AST, no DOM needed.
-  if (keyword in LANGIUM_TYPES) {
+  // Its error is kept, because for these types it is the parser that owns the
+  // grammar, and mermaid core's attempt below is only a second chance.
+  const langium = keyword in LANGIUM_TYPES;
+  let langiumError: string | null = null;
+  if (langium) {
     try {
       return await extractLangiumStats(content, keyword);
-    } catch {
-      /* fall through to mermaid-core */
+    } catch (err) {
+      langiumError = parserReason(err);
     }
   }
 
@@ -115,15 +123,15 @@ export async function extractStats(content: string): Promise<MermaidStats> {
   // DOMPurify; the parsers populate each type's DB (vertices, edges,
   // blocks, sections, etc.). A per-type adapter in extractCoreStats reads
   // the canonical DB shape.
-  let error: string | null = null;
+  let coreError: string;
   try {
     return await extractCoreStats(content, keyword);
   } catch (err) {
-    error = (err instanceof Error ? err.message : String(err)).split("\n")[0] ?? null;
+    coreError = parserReason(err);
   }
 
-  // 3. Neither canonical parser produced stats. Return a tagged failure
-  // so assessParseQuality flags ParserFailure.
+  // 3. Neither canonical parser produced stats. Return a tagged failure so
+  // parseFailed (metrics.ts) flags it, reported as parse-diagram-unparseable.
   return {
     nodes: 0,
     edges: 0,
@@ -131,12 +139,31 @@ export async function extractStats(content: string): Promise<MermaidStats> {
     max_subgraph_depth: 0,
     node_ids: [],
     subgraph_names: [],
-    parser_used: "mermaid-core",
+    parser_used: langium ? "langium" : "mermaid-core",
     diagram_type: keyword,
-    error,
+    error: langiumError ?? coreError,
   };
 }
 
+// A pointer line under an echoed source line, as the JISON parsers print it.
+const POINTER = /^-*\^$/;
+
+// A parser's whole reason on one line, so a finding stays one line. The JISON
+// parsers echo the source line and point at the column; both are dropped, and
+// the line number and what the parser expected are kept. "No diagram type
+// detected" echoes the whole diagram after its first line, so only that line
+// is kept.
+export const parserReason = (err: unknown): string => {
+  const message = err instanceof Error ? err.message : String(err);
+  const lines = message.split("\n");
+  if (message.startsWith("No diagram type detected")) return (lines[0] ?? "").trim();
+  return lines
+    .filter((line, i) => !POINTER.test(line.trim()) && !POINTER.test((lines[i + 1] ?? "").trim()))
+    .join(" ")
+    .replace(/\s+/g, " ")
+    .trim();
+};
+
 // ── Langium extraction (@mermaid-js/parser) ─────────────────────────────────
 
 async function langiumParseAny(type: string, content: string): Promise<unknown> {
@@ -233,7 +260,6 @@ async function extractLangiumStats(content: string, keyword: string): Promise<Me
     }
     case "wardley": {
       // AST shape: ast.anchors[], ast.components[], ast.links[] — NOT ast.edges.
-      // The old code looked for `ast.edges` and returned 0.
       const components = (ast.components as Array<{ name?: string }> | undefined) ?? [];
       const anchors = (ast.anchors as Array<{ name?: string }> | undefined) ?? [];
       const links = (ast.links as Array<unknown> | undefined) ?? [];
@@ -278,9 +304,8 @@ function architectureDepth(groups: Array<{ id?: string; in?: string }>): number
 }
 
 // Compute tree structure from a flat, indent-ordered node list.
-// Used for treemap, treeView, mindmap, ishikawa, kanban — every diagram
-// type where parent-child is encoded via indentation rather than explicit
-// edges. `labels` preserves the node names for VCS bookkeeping; `edges` is
+// Used for treemap and treeView, where parent-child is encoded via
+// indentation rather than explicit edges. `labels` preserves the node names for VCS bookkeeping; `edges` is
 // the number of parent-child links (nodes - number_of_roots); `depth` is
 // the maximum number of indent-steps past the root level.
 export function indentTreeStats(items: Array<{ label: string; indent: number }>): {
@@ -302,9 +327,10 @@ export function indentTreeStats(items: Array<{ label: string; indent: number }>)
 // ── mermaid-core extraction via .db after parse ─────────────────────────────
 //
 // Every diagram type's canonical DB has a different shape. Some expose data
-// via getter methods (flowchart's getVertices/getEdges, kanban's getSections,
-// block's getBlocksFlat). Others expose it via direct properties (er.entities,
-// state.nodes, requirement.requirements). We dispatch on diagram.type and
+// via getter methods (kanban's getData, block's getBlocks, sankey's
+// getNodes/getLinks). Others expose it via direct properties (flowchart's
+// vertices/edges/subGraphs, er.entities, state.nodes,
+// requirement.requirements). We dispatch on diagram.type and
 // each adapter reads ONLY that type's canonical surface — no text parsing,
 // no regex. The parser did the work; we just read the result.
 

package/src/plugins/contract.ts

@@ -26,7 +26,7 @@ export interface PluginMeta {
   name: string;
   namespace: string;
   apiVersion: number;
-  // A new category the plugin adds, as the word and a one-line description.
+  // New categories the plugin adds, each word mapped to a one-line description.
   categories?: Record<string, string>;
 }
 

package/src/plugins/discover.ts

@@ -4,9 +4,9 @@
 // names a config lists. A directory of node_modules is never scanned, so only
 // what the project chose to depend on can run.
 //
-// A source that cannot be resolved is a failure the caller decides how to
-// treat, not an exception, so a lenient run can skip it and a validating run
-// can report every one.
+// A declared package that is not installed is a failure the caller decides
+// how to treat, not an exception, so a lenient run can skip it and a
+// validating run can report every one. A malformed package.json throws.
 
 import { readdir, readFile } from "node:fs/promises";
 import { dirname, extname, isAbsolute, join, resolve } from "node:path";
@@ -69,8 +69,8 @@ const localSources = async (root: string): Promise<PluginSource[]> => {
     .map((name) => ({ kind: "local", spec: join(LOCAL_RULES, name), path: join(dir, name) }));
 };
 
-// The file Node would import for a package, read from its package.json the
-// way a resolver does: the exports entry, then main, then index.js.
+// An approximation of Node resolution, read from a package's package.json:
+// exports "." by node, import, default priority, then main, then index.js.
 const pick = (target: unknown): string | null => {
   if (typeof target === "string") return target;
   if (Array.isArray(target)) {

package/src/plugins/load.ts

@@ -1,8 +1,8 @@
 // Loading: import a plugin module, check it has the shape the contract
 // promises, and turn its rules into ordinary Rules. Every failure is a named
 // PluginLoadError that says which source and why. These functions never skip
-// anything themselves: they return or throw, and the caller decides whether a
-// failed source stops the run (strict) or is reported and left out (lenient).
+// anything themselves: they return, throw, or (loadLocal) return failures. The
+// caller's mode (strict, lenient, collect) decides what a failure does.
 
 import { basename, extname } from "node:path";
 import { pathToFileURL } from "node:url";
@@ -201,7 +201,9 @@ const EXPECTATIONS = new Set(["same-diagrams", "same-tree"]);
 // be synchronous or return a promise, and the wrapper awaits it. Its check cannot
 // take the run down: a throw, a rejection or a malformed finding becomes a finding for that
 // rule, and the other rules carry on. Its fixer is held to the same proof as a
-// built-in, so a fixer that throws or returns nonsense stops the run loudly.
+// built-in. A fixer that throws, returns a non-list, or returns an edit with no
+// valid expect stops the run. An edit with bad offsets is refused by the engine
+// and the finding stays.
 export const toRule = (namespace: string, key: string, rule: PluginRule): Rule => {
   const id = `${namespace}/${key}` as RuleId;
   const check: Rule["check"] = async (ctx) => {

package/src/project.ts

@@ -4,9 +4,9 @@
 // before it touches a document.
 
 import { access } from "node:fs/promises";
-import { dirname, join, resolve } from "node:path";
+import { dirname, extname, join, resolve } from "node:path";
 import { CONFIG_FILES, findConfig, loadConfig, NO_CONFIG } from "./config.ts";
-import { ConfigNotFoundError } from "./errors.ts";
+import { ConfigCodeError, ConfigNotFoundError } from "./errors.ts";
 import { loadPlugins, type PluginFailure, type PluginMode } from "./plugins/index.ts";
 import { FIX_ORDER, RULES } from "./rules/index.ts";
 import { buildRegistry, type Registry } from "./rules/registry.ts";
@@ -33,7 +33,8 @@ export const findProjectRoot = async (cwd: string): Promise<string> => {
 export interface SetupOptions {
   cwd: string;
   configPath?: string;
-  // Built-ins only. Anything discovered is reported as skipped.
+  // Built-ins only, and no project code runs. Anything discovered is reported
+  // as skipped, and a .mjs config is refused with ConfigCodeError.
   noPlugins?: boolean;
   // Skip a plugin that fails to load and say so, instead of stopping the run.
   lenient?: boolean;
@@ -63,6 +64,9 @@ export const setUp = async ({
   } else {
     file = await findConfig(root);
   }
+  // A .mjs config is code, and --no-plugins promises that no project code
+  // runs, so the run stops before importing it rather than drop its settings.
+  if (noPlugins && file !== null && extname(file) === ".mjs") throw new ConfigCodeError(file);
   const config = file ? await loadConfig(file) : NO_CONFIG;
   let mode: PluginMode = "strict";
   if (noPlugins || config.plugins === false) mode = "off";
@@ -75,7 +79,10 @@ export const setUp = async ({
     categories: plugins.categories,
     sources: plugins.sources,
     config,
-    ignoreUnknownPluginIds: mode === "lenient" || mode === "collect",
+    // A plugin rule's setting names a rule that is not loaded in these modes,
+    // by choice (off) or by failure (lenient, collect), so it is set aside
+    // rather than failing the run. A built-in id never is.
+    ignoreUnknownPluginIds: mode !== "strict",
   });
   return { registry, skipped: plugins.skipped, failures: plugins.failures };
 };

package/src/rules/complexity-node-count-hard-limit.ts

@@ -4,7 +4,7 @@ import { RULE } from "./types.ts";
 
 export const complexityNodeCountHardLimit = complexityRule({
   id: RULE.NODES_HARD,
-  summary: "more nodes than any diagram can hold, above the hard limit",
+  summary: "more nodes than the preset's hard limit",
   hit: ({ stats }, c) =>
     stats.nodes > c.node_hard_limit
       ? {

package/src/rules/complexity-visual-score-critical.ts

@@ -4,11 +4,11 @@ import { RULE } from "./types.ts";
 
 export const complexityVisualScoreCritical = complexityRule({
   id: RULE.VCS_CRITICAL,
-  summary: "a visual complexity score above the critical threshold",
+  summary: "a visual complexity score above the preset's complex threshold",
   hit: ({ stats, metrics }, c) =>
     metrics.visual_complexity_score > c.vcs_complex
       ? {
-          message: `VCS ${metrics.visual_complexity_score.toFixed(1)} > ${c.vcs_complex} critical threshold`,
+          message: `VCS ${metrics.visual_complexity_score.toFixed(1)} > ${c.vcs_complex} complex threshold`,
           remediation:
             `Reduce diagram complexity. Split ${boundaryHint(stats.subgraph_names)}, remove redundant edges, ` +
             `or collapse leaf nodes into labelled groups. ${splitTarget(c)}`,

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

@@ -11,7 +11,9 @@ const ratioOn = (fg: string, bg: string): number => wcagRatio(compositeOver(fg,
 // 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
 // directive is scored against. Choosing a brand colour is a design decision, so
-// anything else stays reported.
+// 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
+// black and white each fail one theme, so edge label findings stay reported.
 export const contrastTextBelowAa: Rule = {
   id: RULE.TEXT,
   category: "contrast",
@@ -36,7 +38,9 @@ export const contrastTextBelowAa: Rule = {
           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."
-              : "Darken or lighten the fill, or change color:, until the ratio reaches 4.5:1 in every theme.",
+              : 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.",
         });
       }
     }

package/src/rules/index.ts

@@ -1,4 +1,5 @@
-// The rule catalogue, in id order. To add a rule: write one module exporting a
+// The rule catalogue, in category order (parse, complexity, contrast), most
+// severe first within a ladder. To add a rule: write one module exporting a
 // Rule with its category, register it here, and add its section and examples to
 // RULES.md, which tests/rules-doc.test.ts holds to the code.
 

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

@@ -1,29 +1,44 @@
 import { parseFailed } from "../parse/metrics.ts";
+import type { DiagramStats } from "../parse/stats.ts";
 import { finding } from "./shared.ts";
 import { RULE, type Rule } from "./types.ts";
 
-// A multi-line diagram whose parser yields no nodes is a silent parse failure.
-// It short-circuits the complexity rules, because thresholds are meaningless
-// against structure the parser never read.
+// Diagram types that mermaid draws through an external add-on. Mermaid core
+// does not register them, so no parser here can read them, valid or not.
+const EXTERNAL_TYPES = new Set(["zenuml"]);
+
+// What the finding says: the parser's own reason when it gave one, and
+// otherwise that it read the diagram as zero nodes without complaint.
+const messageOf = (stats: DiagramStats): string => {
+  const type = stats.diagram_type;
+  if (EXTERNAL_TYPES.has(type)) {
+    return `${type} is drawn by an external mermaid add-on that mermaidjs-lint does not include, so it cannot be parsed or checked`;
+  }
+  if (stats.error !== null) {
+    const lines = /\bline \d/.test(stats.error) ? " (its line numbers count within the diagram, not the file)" : "";
+    return `${type} did not parse (parser: ${stats.parser_used})${lines}: ${stats.error}`;
+  }
+  return `${type} parsed to 0 nodes from multi-line source with no error (parser: ${stats.parser_used}), a silent parse failure`;
+};
+
+// A diagram that mermaid's parser rejects, or that mermaid core reads as zero
+// nodes from more than one line, which is a silent parse failure. Rules never
+// read each other: the complexity rules skip the same diagrams themselves
+// through measure() in shared.ts, because thresholds are meaningless against
+// structure the parser never read.
 export const parseDiagramUnparseable: Rule = {
   id: RULE.UNPARSEABLE,
   category: "parse",
-  summary: "a multi-line diagram that mermaid's parser reads as zero nodes",
+  summary: "a diagram mermaid's parser rejects, or reads as zero nodes from several lines",
   check: async (ctx) => {
     const found = [];
     for (const diagram of ctx.doc.diagrams) {
       const stats = await diagram.stats();
       if (!parseFailed(diagram.source, stats)) continue;
-      const why = stats.error ? `: ${stats.error}` : "";
-      found.push(
-        finding(
-          ctx,
-          diagram,
-          RULE.UNPARSEABLE,
-          `${stats.diagram_type} yielded 0 nodes from multi-line source (parser: ${stats.parser_used})${why}`,
-          "Verify the diagram renders in mermaid.js and fix its syntax. Complexity rules are skipped for this diagram while it cannot be parsed.",
-        ),
-      );
+      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));
     }
     return found;
   },