@jpeakai/mermaidjs-lint 0.1.0 → 0.2.0

package/dist/testing.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") {
@@ -798,6 +815,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" }
@@ -818,10 +843,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;
@@ -886,6 +928,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;
@@ -1108,15 +1157,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 = {
@@ -1241,7 +1292,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)}`
@@ -1272,9 +1323,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
 });
@@ -1360,7 +1411,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."
         });
       }
     }
@@ -1397,18 +1448,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;
   }
@@ -1550,7 +1613,7 @@ 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/fix/verify.ts
 var OMIT = new Set(["position", "data"]);
@@ -1619,7 +1682,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;

package/examples/architecture_beta_iconify_logos.mmd

@@ -0,0 +1,27 @@
+architecture-beta
+    group ingress(logos:aws)[Ingress]
+        service dns(logos:aws-route53)[Route 53] in ingress
+        service cdn(logos:aws-cloudfront)[CloudFront] in ingress
+
+    group web(logos:aws-elb)[Web Tier]
+        service alb(logos:aws-elb)[Load Balancer] in web
+        service server(logos:aws-ec2)[Web Servers] in web
+
+    group app(logos:aws-ecs)[App Tier]
+        service worker(logos:aws-lambda)[Worker] in app
+        service api(logos:aws-ecs)[App Service] in app
+
+    group data(logos:aws-rds)[Data Tier]
+        service cache(logos:aws-elasticache)[Redis Cache] in data
+        service db(logos:aws-rds)[Primary DB] in data
+        service replica(logos:aws-rds)[Read Replica] in data
+
+    dns:R -[request]-> L:cdn
+    cdn:R -[route]-> L:alb
+    alb:R -[forward]-> L:server
+    server:R -[dispatch]-> L:worker
+    worker:R -[process]-> L:api
+    api:R -[read]-> L:cache
+    cache:R -[query]-> L:db
+    db:R -[replicate]-> L:replica
+%% expect: none

package/examples/flowchart_fontawesome_icons.mmd

@@ -0,0 +1,31 @@
+flowchart LR
+    subgraph Ingress
+        dns["fa:fa-globe Route 53"]
+        cdn["fa:fa-cloud CloudFront"]
+    end
+    subgraph web["Web Tier"]
+        alb["fa:fa-random Load Balancer"]
+        web1["fa:fa-desktop Web 1"]
+        web2["fa:fa-desktop Web 2"]
+    end
+    subgraph app["App Tier"]
+        api["fa:fa-cog App Service"]
+        worker["fa:fa-bolt Worker"]
+    end
+    subgraph data["Data Tier"]
+        cache["fa:fa-bolt Redis Cache"]
+        db[("fa:fa-database Primary DB")]
+        replica[("fa:fa-copy Read Replica")]
+    end
+
+    dns --> cdn
+    cdn --> alb
+    alb --> web1
+    alb --> web2
+    web1 --> api
+    web2 --> api
+    api --> cache
+    api --> db
+    worker --> db
+    db -- replication --> replica
+%% expect: none

package/examples/layout_cosebilkent_mindmap.mmd

@@ -0,0 +1,19 @@
+---
+config:
+  layout: cose-bilkent
+  look: classic
+  theme: default
+---
+mindmap
+  root((Platform))
+    Ingress
+      CDN
+      Load Balancer
+    Compute
+      API
+      Worker
+    Data
+      Cache
+      Primary DB
+      Object Store
+%% expect: none

package/examples/layout_dagre_classic.mmd

@@ -0,0 +1,22 @@
+---
+config:
+  layout: dagre
+  look: classic
+  theme: default
+---
+flowchart LR
+    user([User]) --> edge[CDN / Edge]
+    edge --> lb[Load Balancer]
+    lb --> api1[API Server 1]
+    lb --> api2[API Server 2]
+    api1 --> cache[(Cache)]
+    api2 --> cache
+    api1 --> db[(Primary DB)]
+    api2 --> db
+    api1 --> queue[[Job Queue]]
+    api2 --> queue
+    queue --> worker[Worker]
+    worker --> db
+    worker --> store[(Object Store)]
+    db -. replicate .-> replica[(Read Replica)]
+%% expect: none

package/examples/layout_dagre_handdrawn.mmd

@@ -0,0 +1,23 @@
+---
+config:
+  layout: dagre
+  look: handDrawn
+  handDrawnSeed: 1
+  theme: default
+---
+flowchart LR
+    user([User]) --> edge[CDN / Edge]
+    edge --> lb[Load Balancer]
+    lb --> api1[API Server 1]
+    lb --> api2[API Server 2]
+    api1 --> cache[(Cache)]
+    api2 --> cache
+    api1 --> db[(Primary DB)]
+    api2 --> db
+    api1 --> queue[[Job Queue]]
+    api2 --> queue
+    queue --> worker[Worker]
+    worker --> db
+    worker --> store[(Object Store)]
+    db -. replicate .-> replica[(Read Replica)]
+%% expect: none

package/examples/layout_dagre_neo.mmd

@@ -0,0 +1,26 @@
+---
+config:
+  layout: dagre
+  look: neo
+  theme: default
+  useGradient: true
+  gradientStart: "#ede9fe"
+  gradientStop: "#a78bfa"
+  dropShadow: true
+---
+flowchart LR
+    user([User]) --> edge[CDN / Edge]
+    edge --> lb[Load Balancer]
+    lb --> api1[API Server 1]
+    lb --> api2[API Server 2]
+    api1 --> cache[(Cache)]
+    api2 --> cache
+    api1 --> db[(Primary DB)]
+    api2 --> db
+    api1 --> queue[[Job Queue]]
+    api2 --> queue
+    queue --> worker[Worker]
+    worker --> db
+    worker --> store[(Object Store)]
+    db -. replicate .-> replica[(Read Replica)]
+%% expect: none

package/examples/layout_elk_default.mmd

@@ -0,0 +1,22 @@
+---
+config:
+  layout: elk
+  look: classic
+  theme: default
+---
+flowchart LR
+    user([User]) --> edge[CDN / Edge]
+    edge --> lb[Load Balancer]
+    lb --> api1[API Server 1]
+    lb --> api2[API Server 2]
+    api1 --> cache[(Cache)]
+    api2 --> cache
+    api1 --> db[(Primary DB)]
+    api2 --> db
+    api1 --> queue[[Job Queue]]
+    api2 --> queue
+    queue --> worker[Worker]
+    worker --> db
+    worker --> store[(Object Store)]
+    db -. replicate .-> replica[(Read Replica)]
+%% expect: none

package/examples/layout_elk_tuned.mmd

@@ -0,0 +1,25 @@
+---
+config:
+  layout: elk
+  look: classic
+  theme: default
+  elk:
+    mergeEdges: true
+    nodePlacementStrategy: LINEAR_SEGMENTS
+---
+flowchart LR
+    user([User]) --> edge[CDN / Edge]
+    edge --> lb[Load Balancer]
+    lb --> api1[API Server 1]
+    lb --> api2[API Server 2]
+    api1 --> cache[(Cache)]
+    api2 --> cache
+    api1 --> db[(Primary DB)]
+    api2 --> db
+    api1 --> queue[[Job Queue]]
+    api2 --> queue
+    queue --> worker[Worker]
+    worker --> db
+    worker --> store[(Object Store)]
+    db -. replicate .-> replica[(Read Replica)]
+%% expect: none

package/examples/layout_tidytree_mindmap.mmd

@@ -0,0 +1,19 @@
+---
+config:
+  layout: tidy-tree
+  look: classic
+  theme: default
+---
+mindmap
+  root((System))
+    Ingress
+      CDN
+      Load Balancer
+    Compute
+      API
+      Worker
+    Data
+      Cache
+      Primary DB
+      Object Store
+%% expect: none

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jpeakai/mermaidjs-lint",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "type": "module",
   "description": "Deterministic lint gates and verified fixers for Mermaid diagrams in markdown",
   "license": "MIT",
@@ -16,7 +16,7 @@
     "type": "git",
     "url": "git+https://github.com/jpeakai/jpai-mermaidjs-lint.git"
   },
-  "homepage": "https://github.com/jpeakai/jpai-mermaidjs-lint#readme",
+  "homepage": "https://jpeakai.github.io/jpai-mermaidjs-lint/",
   "bugs": "https://github.com/jpeakai/jpai-mermaidjs-lint/issues",
   "packageManager": "bun@1.3.12",
   "publishConfig": {

package/src/check.ts

@@ -4,7 +4,7 @@
 // them. A rule may be synchronous or return a promise, so a rule that waits on
 // a tool or a service overlaps with the others.
 
-import { buildDocModel, type DocModel } from "./model.ts";
+import { buildDocModel, type DocModel, documentKind } from "./model.ts";
 import { BUILTIN, HELPERS, type Registry } from "./rules/registry.ts";
 import type { Finding, Rule, RuleOptions } from "./rules/types.ts";
 
@@ -44,5 +44,4 @@ export const checkMarkdown = (
   file: string,
   flags: RunFlags = {},
   registry: Registry = BUILTIN,
-): Promise<Finding[]> =>
-  checkModel(buildDocModel(src, file.toLowerCase().endsWith(".mmd") ? "diagram" : "markdown"), file, flags, registry);
+): Promise<Finding[]> => checkModel(buildDocModel(src, documentKind(file)), file, flags, registry);

package/src/cli.ts

@@ -4,23 +4,29 @@
 import { readFile, writeFile } from "node:fs/promises";
 import { relative } from "node:path";
 import { parseArgs } from "node:util";
+import pkg from "../package.json" with { type: "json" };
 import { checkModel, type RunFlags } from "./check.ts";
 import { FlagError, MermaidLintError, UsageError } from "./errors.ts";
-import { collectFiles } from "./files.ts";
+import { collectFiles, DIAGRAM_FILE_EXTS, SKIP_DIRS } from "./files.ts";
 import { fixSourceReport } from "./fix/engine.ts";
-import { buildDocModel } from "./model.ts";
+import { buildDocModel, DIAGRAM_EXTS, documentKind } from "./model.ts";
 import { PROFILES } from "./parse/contrast.ts";
 import { canonicalPreset, PRESET_NAMES } from "./parse/metrics.ts";
 import type { PluginFailure } from "./plugins/index.ts";
 import { setUp } from "./project.ts";
 import { RULES } from "./rules/index.ts";
 import type { LoadedSource, Registry } from "./rules/registry.ts";
-import { CATEGORIES } from "./rules/types.ts";
+import { CATEGORIES, type Finding } from "./rules/types.ts";
 
-const USAGE = `usage: mermaidjs-lint <path...> [--fix] [--json] [--preset NAME] [--profile NAME] [--config FILE]
+// The invocation forms, printed alone after a usage error so the error is not
+// buried, and first in --help.
+const 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`;
+
+const USAGE = `${SYNOPSIS}
 
 Deterministic Mermaid diagram gates (* = autofixable):
 ${CATEGORIES.map((c) =>
@@ -29,23 +35,29 @@ ${CATEGORIES.map((c) =>
   ),
 ).join("\n")}
 
-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.`;
 
 interface Parsed {
   values: {
@@ -59,6 +71,7 @@ interface Parsed {
     "lenient-plugins"?: boolean;
     "validate-plugins"?: boolean;
     "list-rules"?: boolean;
+    version?: boolean;
   };
   positionals: string[];
 }
@@ -77,6 +90,7 @@ const parse = (argv: string[]): Parsed =>
       "lenient-plugins": { type: "boolean", default: false },
       "validate-plugins": { type: "boolean", default: false },
       "list-rules": { type: "boolean", default: false },
+      version: { type: "boolean", default: false },
     },
     allowPositionals: true,
     strict: true,
@@ -154,6 +168,13 @@ const validate = (
   return { code, stdout: line, stderr: [] };
 };
 
+// One finding as the text report prints it: file, line or line range, rule
+// and message. The site generator prints its examples with this too.
+export const reportLine = (f: Finding, file: string): string => {
+  const where = f.endLine > f.line ? `${f.line}-${f.endLine}` : `${f.line}`;
+  return `${file}:${where} ${f.rule} ${f.message}`;
+};
+
 const display = (file: string, cwd: string): string => {
   const rel = relative(cwd, file);
   return !rel || rel.startsWith("..") ? file : rel;
@@ -171,6 +192,10 @@ const run = async (argv: string[], cwd: string): Promise<number> => {
     console.log(USAGE);
     return 0;
   }
+  if (values.version) {
+    console.log(pkg.version);
+    return 0;
+  }
   const listing = values["list-rules"];
   const validating = values["validate-plugins"];
   if (values.preset !== undefined && canonicalPreset(values.preset) === null) {
@@ -228,9 +253,7 @@ const run = async (argv: string[], cwd: string): Promise<number> => {
           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();
@@ -246,10 +269,7 @@ const run = async (argv: string[], cwd: string): Promise<number> => {
       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;
@@ -261,15 +281,17 @@ export const describeError = (err: unknown): string =>
     ? `error[${err.code}]: ${err.message}`
     : `error: ${err instanceof Error ? err.message : String(err)}`;
 
-// A usage error prints its reason and the usage, and exits 2. Anything else is
-// a runtime failure and propagates to bin.ts, which exits 1.
+// A usage error prints its reason, the invocation forms and a pointer to
+// --help, and exits 2. Anything else is a runtime failure and propagates to
+// bin.ts, which exits 1.
 export const main = async (argv: string[] = process.argv.slice(2), cwd: string = process.cwd()): Promise<number> => {
   try {
     return await run(argv, cwd);
   } catch (err) {
     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;
   }
 };

package/src/config.ts

@@ -1,7 +1,8 @@
 // The config file: which rules are off, what options each takes, and how
 // strictly plugins load. It is optional, because everything auto-detected loads
 // without it. A mistake in it is a named usage error, so a stale or misspelt
-// rule id fails the run instead of silently doing nothing.
+// built-in rule id fails the run instead of silently doing nothing. A lenient
+// or collect (validating) run drops a setting for an unloaded plugin rule.
 
 import { access, readFile } from "node:fs/promises";
 import { extname, join } from "node:path";
@@ -76,7 +77,7 @@ export const parseConfig = (file: string, raw: unknown): Config => {
   };
 };
 
-// The first config file at the root, or null. Two at once is ambiguous, so it
+// The config file at the root, or null. Two at once is ambiguous, so it
 // is an error rather than a pick.
 export const findConfig = async (root: string): Promise<string | null> => {
   const found: string[] = [];