@jpeakai/mermaidjs-lint 0.2.0 → 0.4.0

package/dist/bin.js

@@ -3,13 +3,13 @@ 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.2.0",
+  version: "0.4.0",
   type: "module",
   description: "Deterministic lint gates and verified fixers for Mermaid diagrams in markdown",
   license: "MIT",
@@ -38,15 +38,16 @@ var package_default = {
   bin: {
     "mermaidjs-lint": "dist/bin.js"
   },
+  types: "./dist/types/index.d.ts",
   exports: {
     ".": {
+      types: "./dist/types/index.d.ts",
       bun: "./src/index.ts",
-      types: "./src/index.ts",
       default: "./dist/index.js"
     },
     "./testing": {
+      types: "./dist/types/testing.d.ts",
       bun: "./src/testing.ts",
-      types: "./src/testing.ts",
       default: "./dist/testing.js"
     }
   },
@@ -60,6 +61,7 @@ var package_default = {
   ],
   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",
@@ -73,7 +75,6 @@ var package_default = {
     "@biomejs/biome": "^2",
     "@jpeakai/prose-gates": "^0.2.0",
     "@types/bun": "latest",
-    "@types/mdast": "^4",
     typescript: "^5"
   }
 };
@@ -280,6 +281,7 @@ async function extractStats(content) {
     edges: 0,
     subgraphs: 0,
     max_subgraph_depth: 0,
+    max_tree_depth: 0,
     node_ids: [],
     subgraph_names: [],
     parser_used: langium ? "langium" : "mermaid-core",
@@ -329,6 +331,7 @@ async function extractLangiumStats(content, keyword) {
   const subgraphNames = [];
   let edges = 0;
   let maxDepth = 0;
+  let treeDepth = 0;
   switch (mapped) {
     case "architecture": {
       const services = ast.services ?? [];
@@ -375,7 +378,7 @@ async function extractLangiumStats(content, keyword) {
       const stats = indentTreeStats(nodes.map((n, i) => ({ label: n.name ?? `node_${i}`, indent: n.indent ?? 0 })));
       nodeIds.push(...stats.labels);
       edges = stats.edges;
-      maxDepth = stats.depth;
+      treeDepth = stats.depth;
       break;
     }
     case "treemap": {
@@ -383,7 +386,7 @@ async function extractLangiumStats(content, keyword) {
       const stats = indentTreeStats(rows.map((r, i) => ({ label: r.item?.name ?? `row_${i}`, indent: r.indent ?? 0 })));
       nodeIds.push(...stats.labels);
       edges = stats.edges;
-      maxDepth = stats.depth;
+      treeDepth = stats.depth;
       break;
     }
     case "wardley": {
@@ -403,6 +406,7 @@ async function extractLangiumStats(content, keyword) {
     edges,
     subgraphs: subgraphNames.length,
     max_subgraph_depth: maxDepth,
+    max_tree_depth: treeDepth,
     node_ids: [...new Set(nodeIds.filter(Boolean))].sort(),
     subgraph_names: subgraphNames,
     parser_used: "langium",
@@ -453,12 +457,13 @@ async function extractCoreStats(content, keyword) {
   if (!adapter) {
     throw new Error(`no core adapter for diagram.type="${diagramType}" (keyword="${keyword}")`);
   }
-  const { nodeIds, edges, subgraphNames, maxDepth } = adapter(diagram.db);
+  const { nodeIds, edges, subgraphNames, maxDepth, treeDepth = 0 } = adapter(diagram.db);
   return {
     nodes: nodeIds.length,
     edges,
     subgraphs: subgraphNames.length,
     max_subgraph_depth: maxDepth,
+    max_tree_depth: treeDepth,
     node_ids: [...nodeIds].sort(),
     subgraph_names: subgraphNames,
     parser_used: "mermaid-core",
@@ -469,6 +474,7 @@ async function extractCoreStats(content, keyword) {
 var CORE_ADAPTERS = {
   "flowchart-v2": adaptFlowchart,
   flowchart: adaptFlowchart,
+  "flowchart-elk": adaptFlowchart,
   graph: adaptFlowchart,
   classDiagram: adaptClass,
   "classDiagram-v2": adaptClass,
@@ -592,7 +598,13 @@ function adaptIshikawa(db) {
       walk(c, depth + 1);
   };
   walk(root, 0);
-  return { nodeIds: labels, edges: Math.max(0, labels.length - 1), subgraphNames: [], maxDepth };
+  return {
+    nodeIds: labels,
+    edges: Math.max(0, labels.length - 1),
+    subgraphNames: [],
+    maxDepth: 0,
+    treeDepth: maxDepth
+  };
 }
 function adaptKanban(db) {
   const data = callGetter(db, "getData");
@@ -620,16 +632,20 @@ function adaptMindmap(db) {
       walk(c, depth + 1);
   };
   walk(root, 0);
-  return { nodeIds: labels, edges: Math.max(0, labels.length - 1), subgraphNames: [], maxDepth };
+  return {
+    nodeIds: labels,
+    edges: Math.max(0, labels.length - 1),
+    subgraphNames: [],
+    maxDepth: 0,
+    treeDepth: maxDepth
+  };
 }
 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;
@@ -655,18 +671,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
@@ -696,7 +724,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)
@@ -923,6 +954,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 run on the target path itself`, "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") {
@@ -1314,7 +1373,7 @@ var calculateComplexity = (stats, config) => {
   const n = stats.nodes;
   const e = stats.edges;
   const s = stats.subgraphs;
-  const d = stats.max_subgraph_depth;
+  const d = Math.max(stats.max_subgraph_depth, stats.max_tree_depth);
   const base = n + e * config.edge_weight + s * config.subgraph_weight;
   const vcs = base * (1 + d * config.depth_weight);
   const maxEdges = n > 1 ? n * (n - 1) : 0;
@@ -1652,7 +1711,7 @@ var parseFenceUnterminated = {
   id: RULE.FENCE_UNTERMINATED,
   category: "parse",
   summary: "a mermaid fence that is never closed",
-  check: (ctx) => 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 after the last line of the diagram.")),
+  check: (ctx) => 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.")),
   fix: (ctx) => {
     const edits = [];
     const { src } = ctx.doc;
@@ -1789,9 +1848,17 @@ import { extname, join as join2, resolve as resolve2 } from "node:path";
 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;
@@ -1803,7 +1870,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())) {
@@ -1828,7 +1899,7 @@ var collectFiles = (paths) => {
       unreadable.push(p);
     }
   }
-  return { files, unreadable };
+  return { files, unreadable, symlinks };
 };
 
 // src/fix/verify.ts
@@ -1863,29 +1934,47 @@ var sameDiagrams = async (before, after) => {
     if (!now || was.keyword !== now.keyword)
       return false;
     const [a, b] = await Promise.all([was.stats(), now.stats()]);
-    const shape = (s) => [
+    const shape = (s, source) => [
+      parseFailed(source, s),
       s.diagram_type,
       s.nodes,
       s.edges,
       s.subgraphs,
       s.max_subgraph_depth,
+      s.max_tree_depth,
       s.node_ids,
       s.subgraph_names
     ];
-    if (!sameJson(shape(a), shape(b)))
+    if (!sameJson(shape(a, was.source), shape(b, now.source)))
       return false;
   }
   return true;
 };
+var breaksAParse = async (before, after) => {
+  for (const [i, was] of before.diagrams.entries()) {
+    const now = after.diagrams[i];
+    if (!now)
+      continue;
+    const [a, b] = await Promise.all([was.stats(), now.stats()]);
+    if (!parseFailed(was.source, a) && parseFailed(now.source, b))
+      return true;
+  }
+  return false;
+};
 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 await breaksAParse(before, after) ? "refuse" : "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))
@@ -1903,6 +1992,7 @@ var fixSourceReport = async (src, file, flags = {}, registry = BUILTIN) => {
   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}`;
@@ -1935,23 +2025,26 @@ 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
@@ -2053,7 +2146,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) => {
@@ -2097,7 +2190,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)
@@ -2105,8 +2205,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) => {
@@ -2115,19 +2222,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);
@@ -2144,8 +2251,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);
@@ -2172,6 +2279,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))
@@ -2201,6 +2309,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;
 };
@@ -2252,7 +2365,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) {
@@ -2266,7 +2390,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);
     }
@@ -2330,7 +2454,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),
@@ -2338,16 +2462,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) {
@@ -2444,7 +2569,7 @@ var setUp = async ({
     config,
     ignoreUnknownPluginIds: mode !== "strict"
   });
-  return { registry, skipped: plugins.skipped, failures: plugins.failures };
+  return { root, registry, skipped: plugins.skipped, failures: plugins.failures };
 };
 
 // src/cli.ts
@@ -2453,17 +2578,21 @@ var SYNOPSIS = `usage: mermaidjs-lint <path...> [--fix] [--json] [--preset NAME]
        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 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(", ")}.
+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/
 
 -p, --preset NAME sets the density for every complexity rule: ${PRESET_NAMES.join(", ")}
@@ -2474,14 +2603,16 @@ Examples of every rule, with fixes: https://jpeakai.github.io/jpai-mermaidjs-lin
 --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-*.
+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.
+  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 or a plugin fails to load (a lenient run
+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,
@@ -2517,13 +2648,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:");
@@ -2566,6 +2698,17 @@ 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 {
@@ -2601,7 +2744,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"],
@@ -2625,11 +2768,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");
@@ -2640,7 +2788,9 @@ var run = async (argv, cwd) => {
         src = fixed;
       }
     }
-    return checkModel(buildDocModel(src, documentKind(file)), display(file, cwd), flags, registry);
+    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) {