@jpeakai/mermaidjs-lint 0.1.1 → 0.2.0

package/README.md

@@ -3,7 +3,10 @@
 Diagrams in documentation should be readable.
 Deterministic checks and verified fixes for Mermaid diagrams in markdown.
 
-**[Rules](RULES.md)** | **[GitHub](https://github.com/jpeakai/jpai-mermaidjs-lint)** | **[npm](https://www.npmjs.com/package/@jpeakai/mermaidjs-lint)**
+**[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).
 
 ## Usage
 
@@ -12,73 +15,72 @@ bunx @jpeakai/mermaidjs-lint README.md docs/     # report findings, exit 1 if an
 npx -y @jpeakai/mermaidjs-lint --fix docs/       # apply every fix proven safe, report the rest
 ```
 
-A path is a `.mmd` file, a markdown file whose mermaid fences are checked, or a directory.
-A directory is walked for both, and it skips `node_modules`, `dist`, `tmp` and dot-directories.
+Pass your own paths: every path you name must exist, or the run stops with a usage error and exit 2.
+A `.mmd` or `.mermaid` file is read as one diagram, and any other file you name is read as markdown.
+A directory is walked for `.mmd`, `.mermaid`, `.md` and `.markdown` files.
+The walk skips dot-folders and any folder named `node_modules`, `vendor`, `dist`, `build`, `tmp` or `__pycache__`, at any depth.
+Installed as a dev dependency, the command is `mermaidjs-lint`, and `--help` lists every flag.
 
-Installed as a dev dependency, the command is `mermaidjs-lint`, and `--json` gives machine-readable output with a remediation for each finding.
+[Get started](https://jpeakai.github.io/jpai-mermaidjs-lint/get-started/) walks through a first run, a fix, and adding the check to a project.
 
-`--preset NAME` sets the density for every complexity rule, as `low`, `medium` or `high`.
-`--profile NAME` sets how contrast is read, as `auto`, `github` or `mkdocs-material`.
-`--config FILE` reads a config other than the one at the project root.
-`--no-plugins` runs the built-in rules only, and `--lenient-plugins` skips a plugin that fails to load and says so.
-`--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.
-Exit codes are 0 for clean, 1 for findings, and 2 for a usage error.
+## The four tenets
 
-## The rules
+Three tenets are guarantees about every diagram the tool passes, and the fourth is a commitment about the tool.
 
-Eleven rules in three categories.
-[RULES.md](RULES.md) shows a failing example for each one, and the fix where there is one.
-There is no warning level, so every finding fails the run.
-A rule you do not want is switched off in the config.
+- **Readable in light and dark.** Declared fills, label colours and borders are scored as the host draws them, on nodes, erDiagram rows and edge labels, in both themes.
+- **Renders.** Every diagram parses with the mermaid parsers this package ships, and every mermaid fence is closed.
+- **Simple enough to follow.** Node count and visual complexity are scored against a density preset, so an oversized diagram is flagged to be split.
+- **Extensible.** A plugin adds rules of your own, which run through the same config, fix engine and verification as the built-ins.
 
-| Category | Rules | What it guards |
-|---|---|---|
-| Parse | parse-diagram-unparseable, parse-fence-unterminated | Whether mermaid can read the diagram, and whether its fence is whole |
-| Complexity | complexity-node-count-hard-limit, complexity-node-count-cognitive-limit, complexity-node-count-acceptable-exceeded, complexity-visual-score-critical, complexity-visual-score-acceptable-exceeded, complexity-subgraph-nesting-too-deep | How much a reader must hold in mind at once |
-| Contrast | contrast-text-below-aa, contrast-border-below-ui-minimum, contrast-directive-unauditable | Whether labels and borders can be read against their fills |
+| Tenet | Delivered by |
+|---|---|
+| Readable in light and dark | The contrast rules |
+| Renders | The parse rules |
+| Simple enough to follow | The complexity rules |
+| Extensible | Local rules and plugin packages |
 
-Structure comes from mermaid's own parsers, never from patterns over the text.
-Every fix is verified by parsing the document again.
-A fix that would change the markdown or the structure of a diagram is refused, so the finding stays for a human.
-The reasoning behind each choice is recorded in [`adrs/`](adrs/index.md).
+The [concepts page](https://jpeakai.github.io/jpai-mermaidjs-lint/concepts/) states the limit of each tenet.
+`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.
 
-## Density presets
+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.
+It does not compare edge endpoints, edge labels or node text, so review the diff a fix writes.
 
-Complexity rules measure the nodes and a visual complexity score, and compare them with a preset.
+## Requirements and compatibility
 
-| Preset | Acceptable nodes | Cognitive limit | Hard limit |
-|---|---|---|---|
-| low-density | 12 | 20 | 35 |
-| medium-density | 20 | 35 | 60 |
-| high-density | 35 | 50 | 100 |
+- **Runtime:** Bun, or Node `>=20` as the `engines` field of `package.json` states.
+- **Mermaid:** the parse rules use the `mermaid` package, at `^11.14.0`, and `@mermaid-js/parser`, both installed with this package.
+- **Your host's mermaid may differ.** GitHub and other hosts draw diagrams with their own mermaid version. A diagram type newer than the host's may parse here and still fail to draw there.
 
-The default is `high-density`, which follows the research that 50 nodes is where a diagram becomes hard to read.
-Each threshold is also a rule option, such as `nodeAcceptable` or `vcsCritical`.
+`npm ls mermaid` in your project prints the mermaid version a run uses.
+[Reference](https://jpeakai.github.io/jpai-mermaidjs-lint/reference/#requirements-and-compatibility) lists which parser reads each diagram type.
 
-## Plugins and local rules
+## Configure and extend
 
-A project adds its own rules without forking this package.
-Both sources load on their own, with no config, and every run prints a line saying what it loaded.
+- [Configure the rules](https://jpeakai.github.io/jpai-mermaidjs-lint/guides/configure/): switch a rule off, change the complexity preset, set options.
+- [Lint a MkDocs Material site](https://jpeakai.github.io/jpai-mermaidjs-lint/guides/mkdocs/): score diagrams the way the theme renders them.
+- [Write a local rule](https://jpeakai.github.io/jpai-mermaidjs-lint/guides/local-rule/) or [publish a plugin package](https://jpeakai.github.io/jpai-mermaidjs-lint/guides/plugin-package/): add rules of your own, which load with no config.
+- [Troubleshooting](https://jpeakai.github.io/jpai-mermaidjs-lint/guides/troubleshooting/): a README that fails after adding `mkdocs.yml`, skipping a diagram, and other common questions.
 
-- **Local rules.** A `.js`, `.mjs`, `.ts` or `.mts` file in `.mermaidjs-lint/rules/` exports one rule, and its id is `local/` followed by the file name.
-- **Plugin packages.** A dependency named `mermaidjs-lint-plugin-name` or `@scope/mermaidjs-lint-plugin-name` loads under the namespace its own `meta.namespace` declares.
-- **New categories.** A plugin declares a category of its own, and its rules use it.
-- **Same treatment.** A plugin rule is switched off, given options and listed exactly like a built-in, and its fixer is verified like a built-in fixer.
+## Use it from an AI agent
 
-A config at the project root switches rules off and sets options.
+[`skills/mermaidjs-lint/`](skills/mermaidjs-lint/SKILL.md) is an agent skill that runs the linter, applies the safe fixes, then fixes what remains by judgement.
+It is not in the npm package, so copy it from this repository.
+For Claude Code, run these in your project:
 
-```json
-{
-  "rules": {
-    "complexity-subgraph-nesting-too-deep": "off",
-    "complexity-node-count-acceptable-exceeded": ["error", { "preset": "medium" }],
-    "contrast-text-below-aa": ["error", { "profile": "mkdocs-material" }]
-  }
-}
+```sh
+git clone --depth 1 https://github.com/jpeakai/jpai-mermaidjs-lint.git mermaidjs-lint-src
+mkdir -p .claude/skills
+cp -R mermaidjs-lint-src/skills/mermaidjs-lint .claude/skills/
 ```
 
-[docs/plugins.md](docs/plugins.md) is the guide to writing a rule.
+Copy it to `~/.claude/skills/` instead to use it in every project, then delete the clone.
+Another agent can follow `SKILL.md` as plain instructions.
+[Agent evals](https://jpeakai.github.io/jpai-mermaidjs-lint/gallery/agent-evals/) shows how well agents fix the fixtures with it.
 
 ## Library use
 
@@ -89,13 +91,40 @@ const findings = await checkMarkdown(src, "README.md");
 const fixed = await fixSource(src, "README.md");
 ```
 
-A plugin author tests a rule with `@jpeakai/mermaidjs-lint/testing`, which runs the same loader checks and verified fixer as a real run.
+These calls run the built-in rules only, and read no config file and no plugin.
+The [Library API](https://jpeakai.github.io/jpai-mermaidjs-lint/reference/library-api/) page lists every export, and shows how to run with the config and plugins as the command does.
+
+## Versioning
+
+The package follows semantic versioning, and while it is at `0.x` a minor release may break the public surface.
+[Versioning](https://jpeakai.github.io/jpai-mermaidjs-lint/reference/#versioning) lists what that surface is.
+[CHANGELOG.md](CHANGELOG.md) lists what changed in each release, and what is on `main` but not yet released.
+
+## Security
+
+A plugin is code that runs on your machine, and plugins load on their own once a project depends on them.
+[SECURITY.md](SECURITY.md) covers the supported versions, the trust model and how to report a vulnerability privately.
+
+## Support
+
+Report a bug or ask a question in [GitHub issues](https://github.com/jpeakai/jpai-mermaidjs-lint/issues).
+A bug report needs:
+
+- The version, from `mermaidjs-lint --version`, or from `npm ls @jpeakai/mermaidjs-lint` on 0.1.1 and earlier.
+- The command you ran.
+- The diagram, or the smallest file that shows the problem.
+- The output of the same command with `--json`.
 
 ## Origin
 
-The checks port the logic of the `mermaidjs-diagrams` skill scripts, which measured complexity and contrast for Mermaid diagrams.
+The checks port an earlier set of diagram-checking scripts, which measured complexity and contrast for Mermaid diagrams.
 The package shape, the plugin mechanism and the fix verification follow [jpai-prose-gates](https://github.com/jpeakai/jpai-prose-gates).
+The reasoning behind each choice is recorded in [`adrs/`](adrs/index.md).
 
 ## Contributing
 
 [CONTRIBUTING.md](CONTRIBUTING.md) covers setup and how a change is accepted.
+
+## Licence
+
+MIT, as stated in [LICENSE](LICENSE).

package/dist/bin.js

@@ -6,6 +6,77 @@ var __require = /* @__PURE__ */ createRequire(import.meta.url);
 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/model.ts
 import { fromMarkdown } from "mdast-util-from-markdown";
@@ -189,17 +260,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,
@@ -208,11 +282,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":
@@ -698,6 +781,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") {
@@ -775,6 +863,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) {
@@ -887,6 +983,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" }
@@ -907,10 +1011,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;
@@ -975,6 +1096,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;
@@ -1197,15 +1325,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 = {
@@ -1331,7 +1461,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)}`
@@ -1362,9 +1492,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
 });
@@ -1450,7 +1580,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."
         });
       }
     }
@@ -1487,18 +1617,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;
   }
@@ -1644,7 +1786,7 @@ var checkModel = async (doc, file, flags = {}, registry = BUILTIN) => {
 // 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) => {
@@ -1756,7 +1898,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 fixSourceReport = async (src, file, flags = {}, registry = BUILTIN) => {
 
 // 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;
   }
 };