@jpeakai/mermaidjs-lint 0.1.1 → 0.3.0

package/dist/bin.js

@@ -3,9 +3,81 @@ import { createRequire } from "node:module";
 var __require = /* @__PURE__ */ createRequire(import.meta.url);
 
 // src/cli.ts
-import { readFile as readFile3, writeFile } from "node:fs/promises";
-import { relative } from "node:path";
+import { lstat, readFile as readFile3, realpath, writeFile } from "node:fs/promises";
+import { isAbsolute as isAbsolute2, relative, resolve as resolve5 } from "node:path";
 import { parseArgs } from "node:util";
+// package.json
+var package_default = {
+  name: "@jpeakai/mermaidjs-lint",
+  version: "0.3.0",
+  type: "module",
+  description: "Deterministic lint gates and verified fixers for Mermaid diagrams in markdown",
+  license: "MIT",
+  keywords: [
+    "mermaid",
+    "mermaidjs",
+    "lint",
+    "diagram",
+    "markdown",
+    "documentation"
+  ],
+  repository: {
+    type: "git",
+    url: "git+https://github.com/jpeakai/jpai-mermaidjs-lint.git"
+  },
+  homepage: "https://jpeakai.github.io/jpai-mermaidjs-lint/",
+  bugs: "https://github.com/jpeakai/jpai-mermaidjs-lint/issues",
+  packageManager: "bun@1.3.12",
+  publishConfig: {
+    access: "public"
+  },
+  scripts: {
+    prepublishOnly: "make check",
+    prepack: "make build"
+  },
+  bin: {
+    "mermaidjs-lint": "dist/bin.js"
+  },
+  types: "./dist/types/index.d.ts",
+  exports: {
+    ".": {
+      types: "./dist/types/index.d.ts",
+      bun: "./src/index.ts",
+      default: "./dist/index.js"
+    },
+    "./testing": {
+      types: "./dist/types/testing.d.ts",
+      bun: "./src/testing.ts",
+      default: "./dist/testing.js"
+    }
+  },
+  engines: {
+    node: ">=20"
+  },
+  files: [
+    "src",
+    "dist",
+    "examples"
+  ],
+  dependencies: {
+    "@mermaid-js/parser": "^1.1.0",
+    "@types/mdast": "^4",
+    "colorjs.io": "^0.6.1",
+    "happy-dom": "^20.9.0",
+    "mdast-util-from-markdown": "^2.0.3",
+    "mdast-util-frontmatter": "^2.0.1",
+    "mdast-util-gfm": "^3.1.0",
+    mermaid: "^11.14.0",
+    "micromark-extension-frontmatter": "^2.0.0",
+    "micromark-extension-gfm": "^3.0.0"
+  },
+  devDependencies: {
+    "@biomejs/biome": "^2",
+    "@jpeakai/prose-gates": "^0.2.0",
+    "@types/bun": "latest",
+    typescript: "^5"
+  }
+};
 
 // src/model.ts
 import { fromMarkdown } from "mdast-util-from-markdown";
@@ -189,17 +261,20 @@ function detectKeyword(content) {
 }
 async function extractStats(content) {
   const keyword = detectKeyword(content) ?? "unknown";
-  if (keyword in LANGIUM_TYPES) {
+  const langium = keyword in LANGIUM_TYPES;
+  let langiumError = null;
+  if (langium) {
     try {
       return await extractLangiumStats(content, keyword);
-    } catch {}
+    } catch (err) {
+      langiumError = parserReason(err);
+    }
   }
-  let error = null;
+  let coreError;
   try {
     return await extractCoreStats(content, keyword);
   } catch (err) {
-    error = (err instanceof Error ? err.message : String(err)).split(`
-`)[0] ?? null;
+    coreError = parserReason(err);
   }
   return {
     nodes: 0,
@@ -208,11 +283,20 @@ async function extractStats(content) {
     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
   };
 }
+var POINTER = /^-*\^$/;
+var parserReason = (err) => {
+  const message = err instanceof Error ? err.message : String(err);
+  const lines = message.split(`
+`);
+  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();
+};
 async function langiumParseAny(type, content) {
   switch (type) {
     case "architecture":
@@ -541,12 +625,10 @@ function adaptMindmap(db) {
 }
 function adaptQuadrantChart(db) {
   const data = callGetter(db, "getQuadrantData");
-  const quadrants = data?.quadrants ?? [];
-  const labels = quadrants.map((q) => {
-    const t = q.text;
-    return typeof t === "string" ? t : t?.text ?? "";
-  });
-  return { nodeIds: labels, edges: 0, subgraphNames: [], maxDepth: 0 };
+  const textOf = (t) => typeof t === "string" ? t : t?.text ?? "";
+  const quadrants = (data?.quadrants ?? []).map((q) => textOf(q.text)).filter((t) => t.trim() !== "");
+  const points = (data?.points ?? []).map((p, i) => textOf(p.text) || `point_${i}`);
+  return { nodeIds: [...quadrants, ...points], edges: 0, subgraphNames: [], maxDepth: 0 };
 }
 function adaptRequirement(db) {
   const requirements = db.requirements instanceof Map ? db.requirements : new Map;
@@ -572,18 +654,30 @@ function adaptSankey(db) {
 function adaptState(db) {
   const nodes = db.nodes ?? [];
   const edges = db.edges ?? [];
+  const groups = nodes.filter((n) => n.isGroup === true);
+  const parentOf = new Map(nodes.map((n) => [n.id ?? "", n.parentId]));
+  let maxDepth = 0;
+  for (const g of groups) {
+    let depth = 1;
+    const seen = new Set;
+    for (let cur = g.parentId;cur && !seen.has(cur); cur = parentOf.get(cur)) {
+      seen.add(cur);
+      depth++;
+    }
+    maxDepth = Math.max(maxDepth, depth);
+  }
   return {
     nodeIds: nodes.map((n) => n.id ?? ""),
     edges: edges.length,
-    subgraphNames: [],
-    maxDepth: 0
+    subgraphNames: groups.map((g) => g.id ?? ""),
+    maxDepth
   };
 }
 function adaptTimeline(db) {
   const tasks = callGetter(db, "getTasks") ?? [];
   const sections = callGetter(db, "getSections") ?? [];
   return {
-    nodeIds: tasks.map((t) => t.task ?? ""),
+    nodeIds: tasks.flatMap((t) => [t.task ?? "", ...(t.events ?? []).map((e) => `${t.task ?? ""}: ${e}`)]),
     edges: 0,
     subgraphNames: sections.map((s) => s.sectionName ?? s.section ?? ""),
     maxDepth: sections.length > 0 ? 1 : 0
@@ -613,7 +707,10 @@ function adaptVenn(db) {
 function adaptXychart(db) {
   const data = callGetter(db, "getXYChartData");
   const categories = data?.xAxis?.categories ?? [];
-  return { nodeIds: categories, edges: 0, subgraphNames: [], maxDepth: 0 };
+  if (categories.length > 0)
+    return { nodeIds: categories, edges: 0, subgraphNames: [], maxDepth: 0 };
+  const longest = Math.max(0, ...(data?.plots ?? []).map((p) => p.data?.length ?? 0));
+  return { nodeIds: Array.from({ length: longest }, (_, i) => `x_${i}`), edges: 0, subgraphNames: [], maxDepth: 0 };
 }
 function subgraphNestingDepth(subGraphs) {
   if (subGraphs.length === 0)
@@ -698,6 +795,11 @@ var collectMermaid = (node, out) => {
   for (const child of node.children ?? [])
     collectMermaid(child, out);
 };
+var DIAGRAM_EXTS = [".mmd", ".mermaid"];
+var documentKind = (file) => {
+  const lower = file.toLowerCase();
+  return DIAGRAM_EXTS.some((ext) => lower.endsWith(ext)) ? "diagram" : "markdown";
+};
 var buildDocModel = (src, kind = "markdown") => {
   const lineStarts = lineStartsOf(src);
   if (kind === "diagram") {
@@ -775,6 +877,14 @@ class ConfigNotFoundError extends UsageError {
   }
 }
 
+class ConfigCodeError extends UsageError {
+  file;
+  constructor(file) {
+    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;
+  }
+}
+
 class AmbiguousConfigError extends UsageError {
   files;
   constructor(root, files) {
@@ -827,6 +937,34 @@ class RuleOptionError extends UsageError {
   }
 }
 
+class FixOutsideRootError extends UsageError {
+  file;
+  target;
+  constructor(file, target, root) {
+    super(`${file} is a symbolic link to ${target}, outside the project root ${root}; --fix does not write through it. Fix the target in its own project, or name it directly`, "fix-outside-root");
+    this.file = file;
+    this.target = target;
+  }
+}
+
+class PackageJsonError extends MermaidLintError {
+  file;
+  constructor(file) {
+    super("package-json", `${file} is not a JSON object; fix or remove it`);
+    this.file = file;
+  }
+}
+
+class FixNotConvergingError extends MermaidLintError {
+  file;
+  rules;
+  constructor(file, passes, rules) {
+    super("fix-not-converging", `${file}: --fix did not converge after ${passes} passes; ${rules.join(", ")} kept proposing edits. A fixer must propose nothing once its edit is applied`);
+    this.file = file;
+    this.rules = rules;
+  }
+}
+
 class PluginLoadError extends MermaidLintError {
   source;
   constructor(source, reason, code = "plugin") {
@@ -887,6 +1025,14 @@ var MKDOCS_MATERIAL = {
 };
 var GITHUB = { light: { bg: "#ffffff" }, dark: { bg: "#0d1117" } };
 var THEMES = ["light", "dark"];
+var MERMAID_EDGE_LABEL = {
+  light: { box: "rgba(232,232,232,0.8)", backing: "rgba(232,232,232,0.5)" },
+  dark: { box: "#585858", backing: "rgba(88,88,88,0.5)" }
+};
+var edgeLabelBackground = (theme) => {
+  const { box, backing } = MERMAID_EDGE_LABEL[theme];
+  return compositeOver(box, compositeOver(box, compositeOver(backing, GITHUB[theme].bg)));
+};
 var MERMAID_ER = {
   light: { odd: "#ffffff", even: "#f1f1ff", label: "#333333" },
   dark: { odd: "#2c2d2d", even: "#060606", label: "#cccccc" }
@@ -907,10 +1053,27 @@ var scorePair = (kind, d, fg, bg) => {
   };
 };
 var message = (err) => err instanceof Error ? err.message : String(err);
+var scoreEdgeLabel = (d, pairs, skipped) => {
+  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
+    });
+  }
+};
 var scoreGithub = (directives) => {
   const pairs = [];
   const skipped = [];
   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;
@@ -975,6 +1138,13 @@ var scoreMkdocs = (directives) => {
   const pairs = [];
   const skipped = [];
   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;
@@ -1197,15 +1367,17 @@ var calculateComplexity = (stats, config) => {
   };
 };
 var parseFailed = (content, stats) => {
-  const lines = content.split(`
-`).filter((l) => {
-    const t = l.trim();
-    return t && !t.startsWith("%%") && t !== "---";
-  });
-  if (lines.length <= 1)
+  if (stats.error !== null)
+    return true;
+  if (stats.parser_used === "langium" || stats.nodes > 0)
     return false;
-  return stats.nodes === 0;
+  return sourceLines(content) > 1;
 };
+var sourceLines = (content) => content.split(`
+`).filter((l) => {
+  const t = l.trim();
+  return t && !t.startsWith("%%") && t !== "---";
+}).length;
 
 // src/rules/shared.ts
 var COMPLEXITY_OPTIONS = {
@@ -1331,7 +1503,7 @@ var complexityNodeCountCognitiveLimit = complexityRule({
 // src/rules/complexity-node-count-hard-limit.ts
 var 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 ? {
     message: `${stats.nodes} nodes > ${c.node_hard_limit} hard limit`,
     remediation: "Split immediately. This diagram is beyond any comprehensible size. " + `${boundaryHint(stats.subgraph_names).replace(/^along /, "Split along ")}. ${splitTarget(c)}`
@@ -1362,9 +1534,9 @@ var complexityVisualScoreAcceptableExceeded = complexityRule({
 // src/rules/complexity-visual-score-critical.ts
 var 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)}`
   } : null
 });
@@ -1450,7 +1622,7 @@ var contrastTextBelowAa = {
           endLine: line,
           rule: RULE.TEXT,
           message: `${p.directive.kind} ${p.selector}: text ${p.assessment.ratio.toFixed(2)}:1 < ${AA_NORMAL2} ` + `(${p.foreground} on ${p.background}${where ? `, ${where}` : ""})`,
-          remediation: profile === "mkdocs-material" ? "The host theme forces the label text, so change the fill until the host text reads on it in both themes." : "Darken or lighten the fill, or change color:, until the ratio reaches 4.5:1 in every theme."
+          remediation: profile === "mkdocs-material" ? "The host theme forces the label text, so change the fill until the host text reads on it in both themes." : p.directive.kind === "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."
         });
       }
     }
@@ -1487,18 +1659,30 @@ var contrastTextBelowAa = {
 };
 
 // src/rules/parse-diagram-unparseable.ts
+var EXTERNAL_TYPES = new Set(["zenuml"]);
+var messageOf = (stats) => {
+  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`;
+};
 var parseDiagramUnparseable = {
   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;
   }
@@ -1644,12 +1828,20 @@ var checkModel = async (doc, file, flags = {}, registry = BUILTIN) => {
 // src/files.ts
 import { readdirSync, statSync } from "node:fs";
 import { extname, join as join2, resolve as resolve2 } from "node:path";
-var DIAGRAM_FILE_EXTS = new Set([".mmd", ".md", ".markdown"]);
+var DIAGRAM_FILE_EXTS = new Set([...DIAGRAM_EXTS, ".md", ".markdown"]);
 var SKIP_DIRS = new Set(["node_modules", "vendor", "dist", "build", "tmp", "__pycache__"]);
 var skipDir = (name) => name.startsWith(".") || SKIP_DIRS.has(name);
+var linksToDir = (path) => {
+  try {
+    return statSync(path).isDirectory();
+  } catch {
+    return false;
+  }
+};
 var collectFiles = (paths) => {
   const files = [];
   const unreadable = [];
+  const symlinks = [];
   const seen = new Set;
   const walk = (dir) => {
     let entries;
@@ -1661,7 +1853,11 @@ var collectFiles = (paths) => {
     }
     for (const entry of entries.sort((a, b) => a.name.localeCompare(b.name))) {
       const abs = join2(dir, entry.name);
-      if (entry.isDirectory()) {
+      if (entry.isSymbolicLink()) {
+        if (!skipDir(entry.name) && (DIAGRAM_FILE_EXTS.has(extname(entry.name).toLowerCase()) || linksToDir(abs))) {
+          symlinks.push(abs);
+        }
+      } else if (entry.isDirectory()) {
         if (!skipDir(entry.name))
           walk(abs);
       } else if (entry.isFile() && DIAGRAM_FILE_EXTS.has(extname(entry.name).toLowerCase())) {
@@ -1686,7 +1882,7 @@ var collectFiles = (paths) => {
       unreadable.push(p);
     }
   }
-  return { files, unreadable };
+  return { files, unreadable, symlinks };
 };
 
 // src/fix/verify.ts
@@ -1737,13 +1933,17 @@ var sameDiagrams = async (before, after) => {
 };
 var verify = async (edit, before, after) => {
   if (edit.expect.kind === "same-tree") {
-    return sameTree(before.tree, after.tree, {}) ? "accept" : "refuse";
+    if (!sameTree(before.tree, after.tree, {}))
+      return "refuse";
+    if (before.kind === "markdown" && after.kind === "markdown")
+      return "accept";
   }
   return await sameDiagrams(before, after) ? "accept" : "refuse";
 };
 
 // src/fix/engine.ts
 var MAX_PASSES = 1000;
+var RECENT_PASSES = 50;
 var splice = (src, edits) => {
   let out = src;
   for (const e of [...edits].sort((a, b) => b.start - a.start))
@@ -1756,11 +1956,12 @@ var overlaps = (edits) => {
 };
 var wellFormed = (e, length) => Number.isInteger(e.start) && Number.isInteger(e.end) && e.start >= 0 && e.start <= e.end && e.end <= length && typeof e.text === "string";
 var fixSourceReport = async (src, file, flags = {}, registry = BUILTIN) => {
-  const kind = file.toLowerCase().endsWith(".mmd") ? "diagram" : "markdown";
+  const kind = documentKind(file);
   const applied = [];
   const refused = [];
   const refusedKeys = new Set;
   let current = src;
+  const keptBy = [];
   for (let pass = 0;pass < MAX_PASSES; pass++) {
     const doc = buildDocModel(current, kind);
     const keyOf = (e) => `${e.rule}\x00${current.slice(e.start, e.end)}\x00${e.text}`;
@@ -1793,28 +1994,31 @@ var fixSourceReport = async (src, file, flags = {}, registry = BUILTIN) => {
         continue;
       if (edits.length > 1 && !overlaps(edits) && await attempt(edits)) {
         progressed = true;
-        break;
-      }
-      for (const edit of edits) {
-        if (await attempt([edit])) {
-          progressed = true;
-          break;
+      } else {
+        for (const edit of edits) {
+          if (await attempt([edit])) {
+            progressed = true;
+            break;
+          }
+          refusedKeys.add(keyOf(edit));
+          refused.push(edit);
         }
-        refusedKeys.add(keyOf(edit));
-        refused.push(edit);
       }
-      if (progressed)
+      if (progressed) {
+        keptBy.push(rule.id);
         break;
+      }
     }
     if (!progressed)
       return { output: current, applied, refused };
   }
-  throw new Error(`fix did not converge after ${MAX_PASSES} passes; a fixer keeps proposing edits`);
+  const lingering = [...new Set(keptBy.slice(-RECENT_PASSES))].sort();
+  throw new FixNotConvergingError(file, MAX_PASSES, lingering);
 };
 
 // src/project.ts
 import { access as access2 } from "node:fs/promises";
-import { dirname as dirname3, join as join5, resolve as resolve4 } from "node:path";
+import { dirname as dirname3, extname as extname5, join as join5, resolve as resolve4 } from "node:path";
 
 // src/config.ts
 import { access, readFile } from "node:fs/promises";
@@ -1911,7 +2115,7 @@ var readJson = async (path) => {
     if (isRecord2(value))
       return value;
   } catch {}
-  throw new Error(`${path} is not a JSON object`);
+  throw new PackageJsonError(path);
 };
 var LOCAL_EXTENSIONS = new Set([".js", ".mjs", ".ts", ".mts", ".cts"]);
 var localSources = async (root) => {
@@ -1955,7 +2159,14 @@ var entryOf = (pkg) => {
 var resolvePackage = async (root, name) => {
   for (let dir = resolve3(root);; dir = dirname2(dir)) {
     const folder = join4(dir, "node_modules", name);
-    const pkg = await readJson(join4(folder, "package.json"));
+    let pkg;
+    try {
+      pkg = await readJson(join4(folder, "package.json"));
+    } catch (err) {
+      if (!(err instanceof PackageJsonError))
+        throw err;
+      throw new PluginSourceError(name, `its package.json at ${err.file} is not a JSON object`);
+    }
     if (pkg)
       return join4(folder, entryOf(pkg));
     if (dirname2(dir) === dir)
@@ -1963,8 +2174,15 @@ var resolvePackage = async (root, name) => {
   }
   throw new PluginNotInstalledError(name, root);
 };
-var declaredPlugins = async (root) => {
-  const pkg = await readJson(join4(root, "package.json"));
+var declaredPlugins = async (root, tolerateBadManifest) => {
+  let pkg;
+  try {
+    pkg = await readJson(join4(root, "package.json"));
+  } catch (err) {
+    if (tolerateBadManifest && err instanceof PackageJsonError)
+      return [];
+    throw err;
+  }
   if (!pkg)
     return [];
   const names = ["dependencies", "devDependencies", "optionalDependencies"].flatMap((field) => {
@@ -1973,19 +2191,19 @@ var declaredPlugins = async (root) => {
   });
   return [...new Set(names)].filter((name) => PACKAGE_PATTERN.test(name)).sort();
 };
-var discoverSources = async (root, config) => {
+var discoverSources = async (root, config, pluginsOff = false) => {
   const sources = await localSources(root);
   const failures = [];
   const add = async (kind, spec, resolveIt) => {
     try {
       sources.push({ kind, spec, path: await resolveIt() });
     } catch (err) {
-      if (!(err instanceof PluginNotInstalledError))
+      if (!(err instanceof PluginLoadError))
         throw err;
-      failures.push(err);
+      failures.push({ kind, error: err });
     }
   };
-  for (const name of await declaredPlugins(root))
+  for (const name of await declaredPlugins(root, pluginsOff))
     await add("package", name, () => resolvePackage(root, name));
   for (const spec of config.plugins || []) {
     const path = spec.startsWith(".") || isAbsolute(spec);
@@ -2002,8 +2220,8 @@ import { pathToFileURL as pathToFileURL2 } from "node:url";
 // src/plugins/contract.ts
 var API_VERSION = 1;
 var CATEGORY_WORD = /^[a-z]+$/;
-var NAMESPACE = /^[a-z][a-z0-9-]*$/;
-var RULE_KEY = /^[a-z][a-z0-9-]*$/;
+var NAMESPACE = /^[a-z][a-z0-9]*(-[a-z0-9]+)*$/;
+var RULE_KEY = /^[a-z][a-z0-9]*(-[a-z0-9]+)*$/;
 
 // src/plugins/runtime.ts
 var canImportTypeScript = (runtime = process) => typeof runtime.versions.bun === "string" || Boolean(runtime.features.typescript);
@@ -2030,6 +2248,7 @@ var importModule = async (source, runtime) => {
   }
 };
 var OPTION_TYPES = new Set(["number", "string", "boolean", "string[]"]);
+var RESERVED_OPTIONS = ["preset", "profile"];
 var checkRule = (spec, key, raw, own) => {
   const where = `rule "${key}"`;
   if (!isRecord3(raw))
@@ -2059,6 +2278,11 @@ var checkRule = (spec, key, raw, own) => {
     if (!valid) {
       throw new PluginContractError(spec, `${where} options must map names to number, string, boolean or string[]`);
     }
+    for (const name of RESERVED_OPTIONS) {
+      if (name in options && options[name] !== "string") {
+        throw new PluginContractError(spec, `${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`);
+      }
+    }
   }
   return raw;
 };
@@ -2110,7 +2334,18 @@ var loadLocal = async (sources, runtime) => {
   const categories = {};
   const owner = {};
   const loaded = [];
+  const keyOf = (source) => basename(source.path, extname4(source.path));
+  const byKey = new Map;
+  for (const source of sources)
+    byKey.set(keyOf(source), [...byKey.get(keyOf(source)) ?? [], source]);
+  for (const [key, group] of byKey) {
+    if (group.length < 2)
+      continue;
+    fail(new PluginContractError(group[0].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`));
+  }
   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) {
@@ -2124,7 +2359,7 @@ var loadLocal = async (sources, runtime) => {
         categories[word] = description;
         owner[word] = source.spec;
       }
-      loaded.push({ key: basename(source.path, extname4(source.path)), source, raw: mod.default });
+      loaded.push({ key: keyOf(source), source, raw: mod.default });
     } catch (err) {
       fail(err);
     }
@@ -2188,7 +2423,7 @@ var toRule = (namespace, key, rule) => {
 
 // src/plugins/index.ts
 var loadPlugins = async (root, config, mode) => {
-  const { sources: found, failures: unresolved } = await discoverSources(root, config);
+  const { sources: found, failures: unresolved } = await discoverSources(root, config, mode === "off");
   const set = {
     rules: [],
     categories: new Map(BUILTIN_CATEGORIES),
@@ -2196,16 +2431,17 @@ var loadPlugins = async (root, config, mode) => {
     skipped: [],
     failures: []
   };
-  if (mode === "off")
-    return { ...set, skipped: [...found.map((s) => s.spec), ...unresolved.map((e) => e.source)] };
+  if (mode === "off") {
+    return { ...set, skipped: [...found.map((s) => s.spec), ...unresolved.map((u) => u.error.source)] };
+  }
   const settle = (error, kind) => {
     if (mode === "strict")
       throw error;
     if (!set.failures.some((f) => f.source === error.source))
       set.failures.push({ source: error.source, kind, error });
   };
-  for (const error of unresolved)
-    settle(error, "package");
+  for (const { error, kind } of unresolved)
+    settle(error, kind);
   const loaded = [];
   const locals = found.filter((s) => s.kind === "local");
   if (locals.length > 0) {
@@ -2283,6 +2519,8 @@ var setUp = async ({
   } else {
     file = await findConfig(root);
   }
+  if (noPlugins && file !== null && extname5(file) === ".mjs")
+    throw new ConfigCodeError(file);
   const config = file ? await loadConfig(file) : NO_CONFIG;
   let mode = "strict";
   if (noPlugins || config.plugins === false)
@@ -2298,39 +2536,53 @@ var setUp = async ({
     categories: plugins.categories,
     sources: plugins.sources,
     config,
-    ignoreUnknownPluginIds: mode === "lenient" || mode === "collect"
+    ignoreUnknownPluginIds: mode !== "strict"
   });
-  return { registry, skipped: plugins.skipped, failures: plugins.failures };
+  return { root, registry, skipped: plugins.skipped, failures: plugins.failures };
 };
 
 // src/cli.ts
-var USAGE = `usage: mermaidjs-lint <path...> [--fix] [--json] [--preset NAME] [--profile NAME] [--config FILE]
+var SYNOPSIS = `usage: mermaidjs-lint <path...> [--fix] [--json] [--preset NAME] [--profile NAME] [--config FILE]
                      [--no-plugins | --lenient-plugins]
        mermaidjs-lint --list-rules
        mermaidjs-lint --validate-plugins [--json] [--config FILE]
+       mermaidjs-lint --version | -h, --help`;
+var ruleRow = (r, width) => `${`${r.id}${r.fix ? "*" : ""}`.padEnd(width)}  ${r.summary}`;
+var idWidth = (rules) => Math.max(0, ...rules.map((r) => r.id.length + 1));
+var USAGE = `${SYNOPSIS}
 
 Deterministic Mermaid diagram gates (* = autofixable):
-${CATEGORIES.map((c) => [`  ${c}:`, ...RULES.filter((r) => r.category === c).map((r) => `    ${r.id}${r.fix ? "*" : " "} ${r.summary}`)].join(`
+${CATEGORIES.map((c) => [`  ${c}:`, ...RULES.filter((r) => r.category === c).map((r) => `    ${ruleRow(r, idWidth(RULES))}`)].join(`
 `)).join(`
 `)}
 
-A path is a .mmd file, a markdown file whose mermaid fences are checked, or a
-directory, which is walked for both.
-Examples of every rule, with fixes: RULES.md
+A path is a file or a directory, and every path must exist. A file ending in
+${DIAGRAM_EXTS.join(" or ")} is read as one raw diagram, and any other file is read as markdown
+whose mermaid fences are checked. A directory is walked for ${[...DIAGRAM_FILE_EXTS].join(", ")} files,
+skipping dot-folders and ${[...SKIP_DIRS].join(", ")}. The walk does not follow a symbolic link,
+and names each one it skipped. A link named as a path is read, but --fix does not write
+through one whose target is outside the project root.
+Examples of every rule, with fixes: https://jpeakai.github.io/jpai-mermaidjs-lint/reference/rules/
 
---preset NAME sets the density for every complexity rule: ${PRESET_NAMES.join(", ")}
-  (aliases low, medium, high). Rule options and the config can set it per rule.
---profile NAME sets how contrast is read: ${PROFILES.join(", ")}.
-  auto reads mkdocs-material when an ancestor holds mkdocs.yml, else github.
+-p, --preset NAME sets the density for every complexity rule: ${PRESET_NAMES.join(", ")}
+  (aliases low, medium, high). It overrides a preset set in the config, and a
+  numeric threshold set in the config overrides both.
+--profile NAME sets how contrast is read: ${PROFILES.join(", ")}. It overrides a profile set in the config.
+  auto reads mkdocs-material when any parent folder holds mkdocs.yml or mkdocs.yaml, else github.
 --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.
 --config FILE reads that config instead of mermaidjs-lint.config.json or .mjs at the project root.
-Plugins load on their own from .mermaidjs-lint/rules and from dependencies named mermaidjs-lint-plugin-*.
---no-plugins runs the built-in rules only, for a baseline or a repo you do not trust.
+Plugins load on their own from .mermaidjs-lint/rules, from dependencies named mermaidjs-lint-plugin,
+  mermaidjs-lint-plugin-* or @scope/mermaidjs-lint-plugin(-*), and from the config's plugins list.
+--no-plugins runs the built-in rules only and loads no plugin. It reads a .json config as usual,
+  and stops with a usage error rather than import a .mjs config, which is code.
 --lenient-plugins skips a plugin that fails to load and says so, instead of stopping the run.
---validate-plugins loads and checks every plugin, reports every failure, and runs no check or fix.
+--validate-plugins imports and checks every plugin, reports every failure, and runs no check or fix.
 --list-rules prints every active rule by category, including plugin rules, and where each plugin came from.
-Exits 1 when findings remain or a plugin fails to load, 2 on usage error.`;
+  It imports the plugins to list them.
+--version prints the version, to quote in a bug report.
+Exits 0 when no findings remain, 1 when findings remain, a plugin fails to load or the run fails (a lenient run
+skips a broken plugin, so it alone does not exit 1), and 2 on a usage error.`;
 var parse2 = (argv) => parseArgs({
   args: argv,
   options: {
@@ -2343,7 +2595,8 @@ var parse2 = (argv) => parseArgs({
     "no-plugins": { type: "boolean", default: false },
     "lenient-plugins": { type: "boolean", default: false },
     "validate-plugins": { type: "boolean", default: false },
-    "list-rules": { type: "boolean", default: false }
+    "list-rules": { type: "boolean", default: false },
+    version: { type: "boolean", default: false }
   },
   allowPositionals: true,
   strict: true
@@ -2364,13 +2617,14 @@ var skippedLines = (failures, ignored) => [
 ];
 var listRules = (registry) => {
   const lines = [];
+  const width = idWidth(registry.rules);
   for (const [category, description] of registry.categories) {
     const rules = registry.rules.filter((r) => r.category === category);
     if (rules.length === 0)
       continue;
     lines.push(`${category}: ${description}`);
     for (const r of rules)
-      lines.push(`  ${r.id}${r.fix ? "*" : " "} ${r.summary}`);
+      lines.push(`  ${ruleRow(r, width)}`);
   }
   if (registry.sources.length > 0) {
     lines.push("", "plugins:");
@@ -2405,10 +2659,25 @@ var validate = (registry, failures, json) => {
   const line = sources.length === 0 ? "mermaidjs-lint: no plugins found" : `mermaidjs-lint: plugins valid: ${namesOf(registry.sources)}`;
   return { code, stdout: line, stderr: [] };
 };
+var reportLine = (f, file) => {
+  const where = f.endLine > f.line ? `${f.line}-${f.endLine}` : `${f.line}`;
+  return `${file}:${where} ${f.rule} ${f.message}`;
+};
 var display = (file, cwd) => {
   const rel = relative(cwd, file);
   return !rel || rel.startsWith("..") ? file : rel;
 };
+var refuseOutsideLinks = async (files, root, cwd) => {
+  const realRoot = await realpath(root);
+  for (const file of files) {
+    if (!(await lstat(file)).isSymbolicLink())
+      continue;
+    const target = await realpath(file);
+    const rel = relative(realRoot, target);
+    if (rel.startsWith("..") || isAbsolute2(rel))
+      throw new FixOutsideRootError(display(file, cwd), target, root);
+  }
+};
 var run = async (argv, cwd) => {
   let parsed;
   try {
@@ -2421,6 +2690,10 @@ var run = async (argv, cwd) => {
     console.log(USAGE);
     return 0;
   }
+  if (values.version) {
+    console.log(package_default.version);
+    return 0;
+  }
   const listing = values["list-rules"];
   const validating = values["validate-plugins"];
   if (values.preset !== undefined && canonicalPreset(values.preset) === null) {
@@ -2440,7 +2713,7 @@ var run = async (argv, cwd) => {
   }
   if (positionals.length === 0 && !listing && !validating)
     throw new FlagError("files", "no files given");
-  const { registry, skipped, failures } = await setUp({
+  const { root, registry, skipped, failures } = await setUp({
     cwd,
     configPath: values.config,
     noPlugins: values["no-plugins"],
@@ -2464,11 +2737,16 @@ var run = async (argv, cwd) => {
     console.log(listRules(registry));
     return 0;
   }
-  const { files, unreadable } = collectFiles(positionals.map((p) => p.startsWith("/") ? p : `${cwd}/${p}`));
+  const { files, unreadable, symlinks } = collectFiles(positionals.map((p) => resolve5(cwd, p)));
   if (unreadable.length > 0)
     throw new FlagError("files", `cannot read ${unreadable.join(", ")}`);
+  for (const link of symlinks) {
+    console.error(`mermaidjs-lint: skipped symbolic link ${display(link, cwd)}; name it as a path to check it`);
+  }
   if (files.length === 0)
     throw new FlagError("files", "no matching files");
+  if (values.fix)
+    await refuseOutsideLinks(files, root, cwd);
   const flags = { preset: values.preset, profile: values.profile };
   const perFile = await Promise.all(files.map(async (file) => {
     let src = await readFile3(file, "utf8");
@@ -2479,9 +2757,9 @@ var run = async (argv, cwd) => {
         src = fixed;
       }
     }
-    const kind = file.toLowerCase().endsWith(".mmd") ? "diagram" : "markdown";
-    const found = await checkModel(buildDocModel(src, kind), display(file, cwd), flags, registry);
-    return found;
+    const shown = display(file, cwd);
+    const found = await checkModel(buildDocModel(src, documentKind(file)), file, flags, registry);
+    return found.map((f) => ({ ...f, file: shown }));
   }));
   const all = perFile.flat();
   if (values.json) {
@@ -2493,10 +2771,8 @@ var run = async (argv, cwd) => {
     }));
     console.log(JSON.stringify({ findings: all, files: files.length, plugins: registry.sources, skippedPlugins }, null, 2));
   } else {
-    for (const f of all) {
-      const where = f.endLine > f.line ? `${f.line}-${f.endLine}` : `${f.line}`;
-      console.log(`${f.file}:${where} ${f.rule} ${f.message}`);
-    }
+    for (const f of all)
+      console.log(reportLine(f, f.file));
     console.log(`${all.length} finding(s) in ${files.length} file(s)`);
   }
   return all.length > 0 ? 1 : 0;
@@ -2509,7 +2785,8 @@ var main = async (argv = process.argv.slice(2), cwd = process.cwd()) => {
     if (!(err instanceof UsageError))
       throw err;
     console.error(describeError(err));
-    console.error(USAGE);
+    console.error(SYNOPSIS);
+    console.error("run mermaidjs-lint --help for more");
     return 2;
   }
 };