@jpeakai/mermaidjs-lint 0.1.0 → 0.2.0

package/dist/index.js

@@ -183,17 +183,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,
@@ -202,11 +205,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":
@@ -692,6 +704,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") {
@@ -769,6 +786,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) {
@@ -881,6 +906,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" }
@@ -901,10 +934,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;
@@ -969,6 +1019,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;
@@ -1191,15 +1248,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 = {
@@ -1325,7 +1384,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)}`
@@ -1356,9 +1415,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
 });
@@ -1444,7 +1503,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."
         });
       }
     }
@@ -1481,18 +1540,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;
   }
@@ -1634,16 +1705,87 @@ var checkModel = async (doc, file, flags = {}, registry = BUILTIN) => {
   const findings = (await Promise.all(perRule)).flat();
   return findings.sort((a, b) => a.line - b.line || a.rule.localeCompare(b.rule));
 };
-var checkMarkdown = (src, file, flags = {}, registry = BUILTIN) => checkModel(buildDocModel(src, file.toLowerCase().endsWith(".mmd") ? "diagram" : "markdown"), file, flags, registry);
+var checkMarkdown = (src, file, flags = {}, registry = BUILTIN) => checkModel(buildDocModel(src, documentKind(file)), file, flags, registry);
 // src/cli.ts
 import { readFile as readFile3, writeFile } from "node:fs/promises";
 import { relative } from "node:path";
 import { parseArgs } from "node:util";
+// package.json
+var package_default = {
+  name: "@jpeakai/mermaidjs-lint",
+  version: "0.2.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"
+  },
+  exports: {
+    ".": {
+      bun: "./src/index.ts",
+      types: "./src/index.ts",
+      default: "./dist/index.js"
+    },
+    "./testing": {
+      bun: "./src/testing.ts",
+      types: "./src/testing.ts",
+      default: "./dist/testing.js"
+    }
+  },
+  engines: {
+    node: ">=20"
+  },
+  files: [
+    "src",
+    "dist",
+    "examples"
+  ],
+  dependencies: {
+    "@mermaid-js/parser": "^1.1.0",
+    "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",
+    "@types/mdast": "^4",
+    typescript: "^5"
+  }
+};
 
 // 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 collectFiles = (paths) => {
@@ -1755,7 +1897,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) => {
-  const kind = file.toLowerCase().endsWith(".mmd") ? "diagram" : "markdown";
+  const kind = documentKind(file);
   const applied = [];
   const refused = [];
   const refusedKeys = new Set;
@@ -1814,7 +1956,7 @@ var fixSource = async (src, file, flags = {}, registry = BUILTIN) => (await fixS
 
 // 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";
@@ -2283,6 +2425,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 +2442,47 @@ 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 };
 };
 
 // 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 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(`
 `)).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(", ")}.
+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.
+--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.
 --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.`;
+--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
+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 +2495,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
@@ -2405,6 +2558,10 @@ 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;
@@ -2421,6 +2578,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) {
@@ -2479,9 +2640,7 @@ 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;
+    return checkModel(buildDocModel(src, documentKind(file)), display(file, cwd), flags, registry);
   }));
   const all = perFile.flat();
   if (values.json) {
@@ -2493,10 +2652,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 +2666,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;
   }
 };
@@ -2523,6 +2681,7 @@ export {
   fixSource,
   findProjectRoot,
   extractStats,
+  documentKind,
   detectKeyword,
   collectFiles,
   checkModel,
@@ -2546,9 +2705,11 @@ export {
   MermaidLintError,
   FlagError,
   FIX_ORDER,
+  DIAGRAM_EXTS,
   ConfigShapeError,
   ConfigNotFoundError,
   ConfigFileError,
+  ConfigCodeError,
   CATEGORIES,
   BUILTIN_CATEGORIES,
   BUILTIN,