@jpeakai/mermaidjs-lint 0.3.0 → 0.4.0

package/README.md

@@ -5,8 +5,9 @@ Deterministic checks and verified fixes for Mermaid diagrams in markdown.
 
 **[Docs](https://jpeakai.github.io/jpai-mermaidjs-lint/)** | **[Rules](https://jpeakai.github.io/jpai-mermaidjs-lint/reference/rules/)** | **[Changelog](CHANGELOG.md)** | **[GitHub](https://github.com/jpeakai/jpai-mermaidjs-lint)** | **[npm](https://www.npmjs.com/package/@jpeakai/mermaidjs-lint)**
 
-This README and the docs site describe the `main` branch.
-A feature on `main` but not yet on npm is listed under `Unreleased` in the [changelog](CHANGELOG.md).
+The docs site describes the latest release on npm.
+This README, read on GitHub, describes the `main` branch.
+A change on `main` that is not yet released is listed under `Unreleased` in the [changelog](CHANGELOG.md).
 
 ## Usage
 
@@ -40,14 +41,14 @@ Three tenets are guarantees about every diagram the tool passes, and the fourth
 | Extensible | Local rules and plugin packages |
 
 The [concepts page](https://jpeakai.github.io/jpai-mermaidjs-lint/concepts/) states the limit of each tenet.
-`mermaidjs-lint --list-rules` prints every rule.
+`bunx @jpeakai/mermaidjs-lint --list-rules` prints every rule.
 The [rules page](https://jpeakai.github.io/jpai-mermaidjs-lint/reference/rules/) draws each one before and after `--fix`, and [RULES.md](RULES.md) holds the same examples as plain markdown.
 
 Every finding fails the run, and a rule you do not want is switched off in the config.
 Node, edge and subgraph counts come from mermaid's own parsers.
 Style directives are read line by line, so a style joined to other statements by a semicolon is not seen.
 Every fix is verified by parsing the document again, and a fix that fails the check is refused, so the finding stays for a human.
-The check holds the markdown outside the diagrams unchanged, and each diagram's type, node ids, subgraph names and counts.
+The check holds the markdown outside the diagrams unchanged, and each diagram's type, node ids, subgraph names and counts, and whether it parses.
 It does not compare edge endpoints, edge labels or node text, so review the diff a fix writes.
 
 ## Requirements and compatibility

package/dist/bin.js

@@ -9,7 +9,7 @@ import { parseArgs } from "node:util";
 // package.json
 var package_default = {
   name: "@jpeakai/mermaidjs-lint",
-  version: "0.3.0",
+  version: "0.4.0",
   type: "module",
   description: "Deterministic lint gates and verified fixers for Mermaid diagrams in markdown",
   license: "MIT",
@@ -281,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",
@@ -330,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 ?? [];
@@ -376,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": {
@@ -384,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": {
@@ -404,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",
@@ -454,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",
@@ -470,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,
@@ -593,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");
@@ -621,7 +632,13 @@ 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");
@@ -941,7 +958,7 @@ 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");
+    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;
   }
@@ -1356,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;
@@ -1694,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;
@@ -1917,26 +1934,40 @@ 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") {
     if (!sameTree(before.tree, after.tree, {}))
       return "refuse";
-    if (before.kind === "markdown" && after.kind === "markdown")
-      return "accept";
+    if (before.kind === "markdown" && after.kind === "markdown") {
+      return await breaksAParse(before, after) ? "refuse" : "accept";
+    }
   }
   return await sameDiagrams(before, after) ? "accept" : "refuse";
 };

package/dist/index.js

@@ -203,6 +203,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",
@@ -252,6 +253,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 ?? [];
@@ -298,7 +300,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": {
@@ -306,7 +308,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": {
@@ -326,6 +328,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",
@@ -376,12 +379,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",
@@ -392,6 +396,7 @@ async function extractCoreStats(content, keyword) {
 var CORE_ADAPTERS = {
   "flowchart-v2": adaptFlowchart,
   flowchart: adaptFlowchart,
+  "flowchart-elk": adaptFlowchart,
   graph: adaptFlowchart,
   classDiagram: adaptClass,
   "classDiagram-v2": adaptClass,
@@ -515,7 +520,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");
@@ -543,7 +554,13 @@ 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");
@@ -863,7 +880,7 @@ 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");
+    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;
   }
@@ -1278,7 +1295,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;
@@ -1616,7 +1633,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;
@@ -1754,7 +1771,7 @@ import { parseArgs } from "node:util";
 // package.json
 var package_default = {
   name: "@jpeakai/mermaidjs-lint",
-  version: "0.3.0",
+  version: "0.4.0",
   type: "module",
   description: "Deterministic lint gates and verified fixers for Mermaid diagrams in markdown",
   license: "MIT",
@@ -1916,26 +1933,40 @@ 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") {
     if (!sameTree(before.tree, after.tree, {}))
       return "refuse";
-    if (before.kind === "markdown" && after.kind === "markdown")
-      return "accept";
+    if (before.kind === "markdown" && after.kind === "markdown") {
+      return await breaksAParse(before, after) ? "refuse" : "accept";
+    }
   }
   return await sameDiagrams(before, after) ? "accept" : "refuse";
 };

package/dist/testing.js

@@ -203,6 +203,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",
@@ -252,6 +253,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 ?? [];
@@ -298,7 +300,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": {
@@ -306,7 +308,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": {
@@ -326,6 +328,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",
@@ -376,12 +379,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",
@@ -392,6 +396,7 @@ async function extractCoreStats(content, keyword) {
 var CORE_ADAPTERS = {
   "flowchart-v2": adaptFlowchart,
   flowchart: adaptFlowchart,
+  "flowchart-elk": adaptFlowchart,
   graph: adaptFlowchart,
   classDiagram: adaptClass,
   "classDiagram-v2": adaptClass,
@@ -515,7 +520,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");
@@ -543,7 +554,13 @@ 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");
@@ -1168,7 +1185,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;
@@ -1505,7 +1522,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;
@@ -1669,26 +1686,40 @@ 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") {
     if (!sameTree(before.tree, after.tree, {}))
       return "refuse";
-    if (before.kind === "markdown" && after.kind === "markdown")
-      return "accept";
+    if (before.kind === "markdown" && after.kind === "markdown") {
+      return await breaksAParse(before, after) ? "refuse" : "accept";
+    }
   }
   return await sameDiagrams(before, after) ? "accept" : "refuse";
 };

package/dist/types/parse/stats.d.ts

@@ -3,6 +3,7 @@ export interface DiagramStats {
     edges: number;
     subgraphs: number;
     max_subgraph_depth: number;
+    max_tree_depth: number;
     node_ids: string[];
     subgraph_names: string[];
     parser_used: "langium" | "mermaid-core";

package/package.json

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

package/src/errors.ts

@@ -138,7 +138,7 @@ export class FixOutsideRootError extends UsageError {
 
   constructor(file: string, target: string, root: string) {
     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`,
+      `${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;

package/src/fix/verify.ts

@@ -4,6 +4,7 @@
 
 import type { Node, Root } from "mdast";
 import type { DocModel } from "../model.ts";
+import { parseFailed } from "../parse/metrics.ts";
 import type { Edit } from "../rules/types.ts";
 
 type Plain = { [k: string]: unknown };
@@ -43,28 +44,50 @@ const sameDiagrams = async (before: DocModel, after: DocModel): Promise<boolean>
     const now = after.diagrams[i];
     if (!now || was.keyword !== now.keyword) return false;
     const [a, b] = await Promise.all([was.stats(), now.stats()]);
-    const shape = (s: typeof a): unknown => [
+    const shape = (s: typeof a, source: string): unknown => [
+      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))) return false;
+    if (!sameJson(shape(a, was.source), shape(b, now.source))) return false;
   }
   return true;
 };
 
+// Whether a diagram that parsed before the edit fails to parse after it. The
+// diagrams are matched by position, which same-tree's identical tree already
+// pins. Asked of same-tree edits as a belt to the tree comparison's braces: a
+// diagram's text sits in the tree, so an unchanged tree cannot break it today,
+// but no edit may ever trade a parseable diagram for an unparseable one.
+const breaksAParse = async (before: DocModel, after: DocModel): Promise<boolean> => {
+  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;
+};
+
 // A raw diagram file (.mmd, .mermaid) has no markdown around its diagram, so
 // its tree is an empty root and comparing trees would prove nothing. There,
 // same-tree also demands what same-diagrams does: the diagram is still there
-// and parses to the same structure.
+// and parses to the same structure. same-diagrams compares parse success too
+// (parseFailed, the test parse-diagram-unparseable applies), so an edit can
+// neither break a diagram that parsed nor claim to have kept the diagrams the
+// same while making an unparseable one parse.
 export const verify = async (edit: Edit, before: DocModel, after: DocModel): Promise<Verdict> => {
   if (edit.expect.kind === "same-tree") {
     if (!sameTree(before.tree, after.tree, {})) return "refuse";
-    if (before.kind === "markdown" && after.kind === "markdown") return "accept";
+    if (before.kind === "markdown" && after.kind === "markdown") {
+      return (await breaksAParse(before, after)) ? "refuse" : "accept";
+    }
   }
   return (await sameDiagrams(before, after)) ? "accept" : "refuse";
 };

package/src/parse/metrics.ts

@@ -152,11 +152,18 @@ const round4 = (x: number): number => Math.round(x * 10000) / 10000;
 // (nodes + edges*w_e + subgraphs*w_s) * (1 + depth*w_d). Edge density is
 // reported as 0 below two nodes rather than dividing by a fallback, which gave
 // nonsense when a parser returned edges but no nodes.
+//
+// The depth is subgraph nesting or, for a tree-shaped type (mindmap, treemap,
+// treeView, ishikawa), tree depth; a diagram has only one of the two. A deep
+// tree is as hard to follow as deep nesting, so its depth still weighs on the
+// score, and the score of those types is unchanged from when tree depth was
+// counted as nesting. Only complexity-subgraph-nesting-too-deep ignores it,
+// because its remedy (flatten subgraphs) cannot apply to a tree.
 export const calculateComplexity = (stats: DiagramStats, config: ThresholdConfig): ComplexityMetrics => {
   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;

package/src/parse/stats.ts

@@ -36,7 +36,14 @@ export interface DiagramStats {
   nodes: number;
   edges: number;
   subgraphs: number;
+  // How deep real containers nest: flowchart subgraphs, composite states,
+  // architecture groups and the like.
   max_subgraph_depth: number;
+  // How far a tree-shaped diagram (mindmap, treemap, treeView, ishikawa)
+  // reaches below its root. Those types draw no subgraphs, so their depth is
+  // kept apart from max_subgraph_depth and the nesting rule never reads it.
+  // It is 0 for every other type.
+  max_tree_depth: number;
   node_ids: string[];
   subgraph_names: string[];
   // The parser that read the diagram, or, on a failure, the one whose reason
@@ -137,6 +144,7 @@ export async function extractStats(content: string): Promise<MermaidStats> {
     edges: 0,
     subgraphs: 0,
     max_subgraph_depth: 0,
+    max_tree_depth: 0,
     node_ids: [],
     subgraph_names: [],
     parser_used: langium ? "langium" : "mermaid-core",
@@ -200,6 +208,7 @@ async function extractLangiumStats(content: string, keyword: string): Promise<Me
   const subgraphNames: string[] = [];
   let edges = 0;
   let maxDepth = 0;
+  let treeDepth = 0;
 
   switch (mapped) {
     case "architecture": {
@@ -246,7 +255,7 @@ async function extractLangiumStats(content: string, keyword: string): Promise<Me
       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": {
@@ -255,7 +264,7 @@ async function extractLangiumStats(content: string, keyword: string): Promise<Me
       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": {
@@ -277,6 +286,7 @@ async function extractLangiumStats(content: string, keyword: string): Promise<Me
     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",
@@ -340,6 +350,8 @@ interface Structure {
   edges: number;
   subgraphNames: string[];
   maxDepth: number;
+  // Set only by the tree-shaped types: see max_tree_depth.
+  treeDepth?: number;
 }
 type CoreAdapter = (db: AnyDb) => Structure;
 
@@ -362,13 +374,14 @@ async function extractCoreStats(content: string, keyword: string): Promise<Merma
   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",
@@ -386,6 +399,9 @@ async function extractCoreStats(content: string, keyword: string): Promise<Merma
 const CORE_ADAPTERS: Record<string, CoreAdapter> = {
   "flowchart-v2": adaptFlowchart,
   flowchart: adaptFlowchart,
+  // `flowchart-elk` is a flowchart drawn with the ELK layout. Mermaid parses it
+  // with the flowchart grammar into the same DB, and only the layout differs.
+  "flowchart-elk": adaptFlowchart,
   graph: adaptFlowchart,
   classDiagram: adaptClass,
   "classDiagram-v2": adaptClass,
@@ -557,7 +573,13 @@ function adaptIshikawa(db: AnyDb): Structure {
     for (const c of node.children ?? []) 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,
+  };
 }
 
 interface KanbanNode {
@@ -596,7 +618,13 @@ function adaptMindmap(db: AnyDb): Structure {
     for (const c of node.children ?? []) 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,
+  };
 }
 
 type QuadrantText = { text?: string } | string | undefined;

package/src/rules/complexity-subgraph-nesting-too-deep.ts

@@ -3,6 +3,11 @@ import { RULE } from "./types.ts";
 
 export const MAX_NESTING = 3;
 
+// Reads max_subgraph_depth only. A mindmap, treemap, treeView or ishikawa
+// diagram reports its depth as max_tree_depth instead, because it draws no
+// subgraphs and flattening them is no remedy for a deep tree. Its depth still
+// weighs on the visual complexity score (calculateComplexity in metrics.ts).
+
 export const complexitySubgraphNestingTooDeep = complexityRule({
   id: RULE.NESTING,
   summary: "subgraphs nested three or more levels deep",

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

@@ -20,7 +20,7 @@ export const parseFenceUnterminated: Rule = {
           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.",
+          "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) => {