@jpeakai/mermaidjs-lint 0.3.0 → 0.4.1

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.1",
   type: "module",
   description: "Deterministic lint gates and verified fixers for Mermaid diagrams in markdown",
   license: "MIT",
@@ -79,6 +79,184 @@ var package_default = {
   }
 };
 
+// src/errors.ts
+class MermaidLintError extends Error {
+  code;
+  constructor(code, message) {
+    super(message);
+    this.code = code;
+    this.name = new.target.name;
+  }
+}
+
+class UsageError extends MermaidLintError {
+  constructor(message, code = "usage") {
+    super(code, message);
+  }
+}
+
+class FlagError extends UsageError {
+  flag;
+  constructor(flag, message) {
+    super(message, "flag");
+    this.flag = flag;
+  }
+}
+
+class ConfigFileError extends UsageError {
+  file;
+  constructor(file, message) {
+    super(`${file}: ${message}`, "config-file");
+    this.file = file;
+  }
+}
+
+class ConfigNotFoundError extends UsageError {
+  path;
+  constructor(path) {
+    super(`--config ${path}: no such file`, "config-not-found");
+    this.path = path;
+  }
+}
+
+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) {
+    super(`more than one config file at ${root}: ${files.join(", ")}`, "config-ambiguous");
+    this.files = files;
+  }
+}
+
+class ConfigShapeError extends UsageError {
+  file;
+  key;
+  constructor(file, message, key = null) {
+    super(`${file}: ${message}`, "config-shape");
+    this.file = file;
+    this.key = key;
+  }
+}
+
+class RuleSettingError extends UsageError {
+  file;
+  rule;
+  constructor(file, rule, message) {
+    super(`${file}: rule "${rule}" ${message}`, "rule-setting");
+    this.file = file;
+    this.rule = rule;
+  }
+}
+
+class UnknownRuleError extends UsageError {
+  file;
+  rule;
+  known;
+  constructor(file, rule, known) {
+    super(`${file}: unknown rule "${rule}"; a retired or misspelt id cannot be switched off. Known rules: ${known.join(", ")}`, "unknown-rule");
+    this.file = file;
+    this.rule = rule;
+    this.known = known;
+  }
+}
+
+class RuleOptionError extends UsageError {
+  file;
+  rule;
+  option;
+  constructor(file, rule, option, message) {
+    super(`${file}: ${message}`, "rule-option");
+    this.file = file;
+    this.rule = rule;
+    this.option = option;
+  }
+}
+
+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") {
+    super(code, `plugin ${source}: ${reason}`);
+    this.source = source;
+  }
+}
+
+class PluginImportError extends PluginLoadError {
+  constructor(source, reason) {
+    super(source, `could not be imported: ${reason}`, "plugin-import");
+  }
+}
+
+class PluginContractError extends PluginLoadError {
+  constructor(source, reason) {
+    super(source, reason, "plugin-contract");
+  }
+}
+
+class PluginConflictError extends PluginLoadError {
+  other;
+  constructor(source, other, reason) {
+    super(source, reason, "plugin-conflict");
+    this.other = other;
+  }
+}
+
+class PluginNotInstalledError extends PluginLoadError {
+  root;
+  constructor(source, root) {
+    super(source, `is declared or listed but not installed; looked from ${root} upward. Install it, or remove it`, "plugin-not-installed");
+    this.root = root;
+  }
+}
+
+class PluginSourceError extends PluginLoadError {
+  constructor(source, reason) {
+    super(source, reason, "plugin-source");
+  }
+}
+
+class PluginFixerError extends MermaidLintError {
+  rule;
+  constructor(rule, reason) {
+    super("plugin-fixer", `plugin rule ${rule} ${reason}`);
+    this.rule = rule;
+  }
+}
+
 // src/model.ts
 import { fromMarkdown } from "mdast-util-from-markdown";
 import { frontmatterFromMarkdown } from "mdast-util-frontmatter";
@@ -281,6 +459,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 +509,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 +556,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 +564,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 +584,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 +635,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 +652,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 +776,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 +810,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");
@@ -837,184 +1032,6 @@ var buildDocModel = (src, kind = "markdown") => {
   return { src, kind, tree, diagrams };
 };
 
-// src/errors.ts
-class MermaidLintError extends Error {
-  code;
-  constructor(code, message) {
-    super(message);
-    this.code = code;
-    this.name = new.target.name;
-  }
-}
-
-class UsageError extends MermaidLintError {
-  constructor(message, code = "usage") {
-    super(code, message);
-  }
-}
-
-class FlagError extends UsageError {
-  flag;
-  constructor(flag, message) {
-    super(message, "flag");
-    this.flag = flag;
-  }
-}
-
-class ConfigFileError extends UsageError {
-  file;
-  constructor(file, message) {
-    super(`${file}: ${message}`, "config-file");
-    this.file = file;
-  }
-}
-
-class ConfigNotFoundError extends UsageError {
-  path;
-  constructor(path) {
-    super(`--config ${path}: no such file`, "config-not-found");
-    this.path = path;
-  }
-}
-
-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) {
-    super(`more than one config file at ${root}: ${files.join(", ")}`, "config-ambiguous");
-    this.files = files;
-  }
-}
-
-class ConfigShapeError extends UsageError {
-  file;
-  key;
-  constructor(file, message, key = null) {
-    super(`${file}: ${message}`, "config-shape");
-    this.file = file;
-    this.key = key;
-  }
-}
-
-class RuleSettingError extends UsageError {
-  file;
-  rule;
-  constructor(file, rule, message) {
-    super(`${file}: rule "${rule}" ${message}`, "rule-setting");
-    this.file = file;
-    this.rule = rule;
-  }
-}
-
-class UnknownRuleError extends UsageError {
-  file;
-  rule;
-  known;
-  constructor(file, rule, known) {
-    super(`${file}: unknown rule "${rule}"; a retired or misspelt id cannot be switched off. Known rules: ${known.join(", ")}`, "unknown-rule");
-    this.file = file;
-    this.rule = rule;
-    this.known = known;
-  }
-}
-
-class RuleOptionError extends UsageError {
-  file;
-  rule;
-  option;
-  constructor(file, rule, option, message) {
-    super(`${file}: ${message}`, "rule-option");
-    this.file = file;
-    this.rule = rule;
-    this.option = option;
-  }
-}
-
-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") {
-    super(code, `plugin ${source}: ${reason}`);
-    this.source = source;
-  }
-}
-
-class PluginImportError extends PluginLoadError {
-  constructor(source, reason) {
-    super(source, `could not be imported: ${reason}`, "plugin-import");
-  }
-}
-
-class PluginContractError extends PluginLoadError {
-  constructor(source, reason) {
-    super(source, reason, "plugin-contract");
-  }
-}
-
-class PluginConflictError extends PluginLoadError {
-  other;
-  constructor(source, other, reason) {
-    super(source, reason, "plugin-conflict");
-    this.other = other;
-  }
-}
-
-class PluginNotInstalledError extends PluginLoadError {
-  root;
-  constructor(source, root) {
-    super(source, `is declared or listed but not installed; looked from ${root} upward. Install it, or remove it`, "plugin-not-installed");
-    this.root = root;
-  }
-}
-
-class PluginSourceError extends PluginLoadError {
-  constructor(source, reason) {
-    super(source, reason, "plugin-source");
-  }
-}
-
-class PluginFixerError extends MermaidLintError {
-  rule;
-  constructor(rule, reason) {
-    super("plugin-fixer", `plugin rule ${rule} ${reason}`);
-    this.rule = rule;
-  }
-}
-
 // src/parse/contrast.ts
 import { existsSync } from "node:fs";
 import { dirname, join, resolve } from "node:path";
@@ -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;
@@ -1810,6 +1827,15 @@ var buildRegistry = (input) => {
 var BUILTIN = buildRegistry({ rules: RULES, fixOrder: FIX_ORDER, categories: BUILTIN_CATEGORIES });
 
 // src/check.ts
+var checkRunFlags = (flags, prefix = "") => {
+  const { preset, profile } = flags;
+  if (preset !== undefined && canonicalPreset(preset) === null) {
+    throw new FlagError(`${prefix}preset`, `${prefix}preset must be one of ${PRESET_NAMES.join(", ")}, not "${preset}"`);
+  }
+  if (profile !== undefined && !PROFILES.includes(profile)) {
+    throw new FlagError(`${prefix}profile`, `${prefix}profile must be one of ${PROFILES.join(", ")}, not "${profile}"`);
+  }
+};
 var optionsFor = (rule, configured, flags) => {
   const options = { ...configured };
   for (const name of ["preset", "profile"]) {
@@ -1820,6 +1846,7 @@ var optionsFor = (rule, configured, flags) => {
   return options;
 };
 var checkModel = async (doc, file, flags = {}, registry = BUILTIN) => {
+  checkRunFlags(flags);
   const perRule = registry.rules.map((rule) => rule.check({ doc, file, options: optionsFor(rule, registry.options.get(rule.id), flags), helpers: HELPERS }));
   const findings = (await Promise.all(perRule)).flat();
   return findings.sort((a, b) => a.line - b.line || a.rule.localeCompare(b.rule));
@@ -1917,26 +1944,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";
 };
@@ -1956,6 +1997,7 @@ 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) => {
+  checkRunFlags(flags);
   const kind = documentKind(file);
   const applied = [];
   const refused = [];
@@ -2569,6 +2611,7 @@ Examples of every rule, with fixes: https://jpeakai.github.io/jpai-mermaidjs-lin
   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.
+--json prints one JSON object instead of text lines.
 --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.
@@ -2696,12 +2739,7 @@ var run = async (argv, cwd) => {
   }
   const listing = values["list-rules"];
   const validating = values["validate-plugins"];
-  if (values.preset !== undefined && canonicalPreset(values.preset) === null) {
-    throw new FlagError("--preset", `--preset must be one of ${PRESET_NAMES.join(", ")}, not "${values.preset}"`);
-  }
-  if (values.profile !== undefined && !PROFILES.includes(values.profile)) {
-    throw new FlagError("--profile", `--profile must be one of ${PROFILES.join(", ")}, not "${values.profile}"`);
-  }
+  checkRunFlags({ preset: values.preset, profile: values.profile }, "--");
   if (values["no-plugins"] && values["lenient-plugins"]) {
     throw new FlagError("--lenient-plugins", "--no-plugins and --lenient-plugins contradict each other");
   }