@jpeakai/mermaidjs-lint 0.2.0 → 0.4.0

package/src/fix/engine.ts

@@ -4,12 +4,14 @@
 // computed from, so every accepted edit restarts the pass.
 
 import { optionsFor, type RunFlags } from "../check.ts";
+import { FixNotConvergingError } from "../errors.ts";
 import { buildDocModel, documentKind } from "../model.ts";
 import { BUILTIN, HELPERS, type Registry } from "../rules/registry.ts";
 import type { Edit } from "../rules/types.ts";
 import { verify } from "./verify.ts";
 
 const MAX_PASSES = 1_000;
+const RECENT_PASSES = 50;
 
 export interface FixReport {
   output: string;
@@ -51,6 +53,10 @@ export const fixSourceReport = async (
   const refusedKeys = new Set<string>();
   let current = src;
 
+  // The rule whose edit each pass kept, so a run that never converges can name
+  // the rules still proposing edits at the end.
+  const keptBy: string[] = [];
+
   for (let pass = 0; pass < MAX_PASSES; pass++) {
     const doc = buildDocModel(current, kind);
     const keyOf = (e: Edit): string => `${e.rule}\u0000${current.slice(e.start, e.end)}\u0000${e.text}`;
@@ -85,21 +91,27 @@ export const fixSourceReport = async (
       // the rest.
       if (edits.length > 1 && !overlaps(edits) && (await attempt(edits))) {
         progressed = true;
-        break;
-      }
-      for (const edit of edits) {
-        if (await attempt([edit])) {
-          progressed = true;
-          break;
+      } else {
+        for (const edit of edits) {
+          if (await attempt([edit])) {
+            progressed = true;
+            break;
+          }
+          refusedKeys.add(keyOf(edit));
+          refused.push(edit);
         }
-        refusedKeys.add(keyOf(edit));
-        refused.push(edit);
       }
-      if (progressed) break;
+      if (progressed) {
+        keptBy.push(rule.id);
+        break;
+      }
     }
     if (!progressed) return { output: current, applied, refused };
   }
-  throw new Error(`fix did not converge after ${MAX_PASSES} passes; a fixer keeps proposing edits`);
+  // The last passes show who was still editing: a fixer that never converges
+  // keeps one in every pass.
+  const lingering = [...new Set(keptBy.slice(-RECENT_PASSES))].sort();
+  throw new FixNotConvergingError(file, MAX_PASSES, lingering);
 };
 
 export const fixSource = async (

package/src/fix/verify.ts

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

package/src/index.ts

@@ -4,14 +4,16 @@ export { checkMarkdown, checkModel, type RunFlags } from "./check.ts";
 export { main } from "./cli.ts";
 export { type Config, loadConfig, type PluginLoading, parseConfig, type RuleSetting, type Severity } from "./config.ts";
 export * from "./errors.ts";
-export { collectFiles } from "./files.ts";
+export { type Collected, collectFiles } from "./files.ts";
 export { type FixReport, fixSource, fixSourceReport } from "./fix/engine.ts";
 export { buildDocModel, DIAGRAM_EXTS, type Diagram, type DocModel, documentKind } from "./model.ts";
 export type { ContrastAssessment, StyleDirective, ValueSpan } from "./parse/color.ts";
-export { PRESETS, thresholdsFrom } from "./parse/metrics.ts";
+export { PRESETS, type Preset, type ThresholdConfig, thresholdsFrom } from "./parse/metrics.ts";
 export { type DiagramStats, detectKeyword, extractStats } from "./parse/stats.ts";
 export type { Plugin, PluginEdit, PluginFinding, PluginMeta, PluginRule } from "./plugins/contract.ts";
-export { findProjectRoot, setUp } from "./project.ts";
+export type { SourceKind } from "./plugins/discover.ts";
+export type { PluginFailure } from "./plugins/index.ts";
+export { findProjectRoot, type Setup, type SetupOptions, setUp } from "./project.ts";
 export { FIX_ORDER, RULES } from "./rules/index.ts";
 export {
   BUILTIN,

package/src/parse/metrics.ts

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

package/src/parse/stats.ts

@@ -36,7 +36,14 @@ export interface DiagramStats {
   nodes: number;
   edges: number;
   subgraphs: number;
+  // How deep real containers nest: flowchart subgraphs, composite states,
+  // architecture groups and the like.
   max_subgraph_depth: number;
+  // How far a tree-shaped diagram (mindmap, treemap, treeView, ishikawa)
+  // reaches below its root. Those types draw no subgraphs, so their depth is
+  // kept apart from max_subgraph_depth and the nesting rule never reads it.
+  // It is 0 for every other type.
+  max_tree_depth: number;
   node_ids: string[];
   subgraph_names: string[];
   // The parser that read the diagram, or, on a failure, the one whose reason
@@ -137,6 +144,7 @@ export async function extractStats(content: string): Promise<MermaidStats> {
     edges: 0,
     subgraphs: 0,
     max_subgraph_depth: 0,
+    max_tree_depth: 0,
     node_ids: [],
     subgraph_names: [],
     parser_used: langium ? "langium" : "mermaid-core",
@@ -200,6 +208,7 @@ async function extractLangiumStats(content: string, keyword: string): Promise<Me
   const subgraphNames: string[] = [];
   let edges = 0;
   let maxDepth = 0;
+  let treeDepth = 0;
 
   switch (mapped) {
     case "architecture": {
@@ -246,7 +255,7 @@ async function extractLangiumStats(content: string, keyword: string): Promise<Me
       const stats = indentTreeStats(nodes.map((n, i) => ({ label: n.name ?? `node_${i}`, indent: n.indent ?? 0 })));
       nodeIds.push(...stats.labels);
       edges = stats.edges;
-      maxDepth = stats.depth;
+      treeDepth = stats.depth;
       break;
     }
     case "treemap": {
@@ -255,7 +264,7 @@ async function extractLangiumStats(content: string, keyword: string): Promise<Me
       const stats = indentTreeStats(rows.map((r, i) => ({ label: r.item?.name ?? `row_${i}`, indent: r.indent ?? 0 })));
       nodeIds.push(...stats.labels);
       edges = stats.edges;
-      maxDepth = stats.depth;
+      treeDepth = stats.depth;
       break;
     }
     case "wardley": {
@@ -277,6 +286,7 @@ async function extractLangiumStats(content: string, keyword: string): Promise<Me
     edges,
     subgraphs: subgraphNames.length,
     max_subgraph_depth: maxDepth,
+    max_tree_depth: treeDepth,
     node_ids: [...new Set(nodeIds.filter(Boolean))].sort(),
     subgraph_names: subgraphNames,
     parser_used: "langium",
@@ -340,6 +350,8 @@ interface Structure {
   edges: number;
   subgraphNames: string[];
   maxDepth: number;
+  // Set only by the tree-shaped types: see max_tree_depth.
+  treeDepth?: number;
 }
 type CoreAdapter = (db: AnyDb) => Structure;
 
@@ -362,13 +374,14 @@ async function extractCoreStats(content: string, keyword: string): Promise<Merma
   if (!adapter) {
     throw new Error(`no core adapter for diagram.type="${diagramType}" (keyword="${keyword}")`);
   }
-  const { nodeIds, edges, subgraphNames, maxDepth } = adapter(diagram.db);
+  const { nodeIds, edges, subgraphNames, maxDepth, treeDepth = 0 } = adapter(diagram.db);
 
   return {
     nodes: nodeIds.length,
     edges,
     subgraphs: subgraphNames.length,
     max_subgraph_depth: maxDepth,
+    max_tree_depth: treeDepth,
     node_ids: [...nodeIds].sort(),
     subgraph_names: subgraphNames,
     parser_used: "mermaid-core",
@@ -386,6 +399,9 @@ async function extractCoreStats(content: string, keyword: string): Promise<Merma
 const CORE_ADAPTERS: Record<string, CoreAdapter> = {
   "flowchart-v2": adaptFlowchart,
   flowchart: adaptFlowchart,
+  // `flowchart-elk` is a flowchart drawn with the ELK layout. Mermaid parses it
+  // with the flowchart grammar into the same DB, and only the layout differs.
+  "flowchart-elk": adaptFlowchart,
   graph: adaptFlowchart,
   classDiagram: adaptClass,
   "classDiagram-v2": adaptClass,
@@ -557,7 +573,13 @@ function adaptIshikawa(db: AnyDb): Structure {
     for (const c of node.children ?? []) walk(c, depth + 1);
   };
   walk(root, 0);
-  return { nodeIds: labels, edges: Math.max(0, labels.length - 1), subgraphNames: [], maxDepth };
+  return {
+    nodeIds: labels,
+    edges: Math.max(0, labels.length - 1),
+    subgraphNames: [],
+    maxDepth: 0,
+    treeDepth: maxDepth,
+  };
 }
 
 interface KanbanNode {
@@ -596,20 +618,29 @@ function adaptMindmap(db: AnyDb): Structure {
     for (const c of node.children ?? []) walk(c, depth + 1);
   };
   walk(root, 0);
-  return { nodeIds: labels, edges: Math.max(0, labels.length - 1), subgraphNames: [], maxDepth };
+  return {
+    nodeIds: labels,
+    edges: Math.max(0, labels.length - 1),
+    subgraphNames: [],
+    maxDepth: 0,
+    treeDepth: maxDepth,
+  };
 }
 
+type QuadrantText = { text?: string } | string | undefined;
 interface QuadrantData {
-  quadrants?: Array<{ text?: { text?: string } | string }>;
+  quadrants?: Array<{ text?: QuadrantText }>;
+  points?: Array<{ text?: QuadrantText }>;
 }
+// A node is every plotted point, plus every quadrant that carries a label. The
+// four quadrant boxes are always drawn, so an unlabelled one adds nothing to
+// read, while every point is a mark the reader must place.
 function adaptQuadrantChart(db: AnyDb): Structure {
   const data = callGetter<QuadrantData | null>(db, "getQuadrantData");
-  const quadrants = data?.quadrants ?? [];
-  const labels = quadrants.map((q) => {
-    const t = q.text;
-    return typeof t === "string" ? t : (t?.text ?? "");
-  });
-  return { nodeIds: labels, edges: 0, subgraphNames: [], maxDepth: 0 };
+  const textOf = (t: QuadrantText): string => (typeof t === "string" ? t : (t?.text ?? ""));
+  const quadrants = (data?.quadrants ?? []).map((q) => textOf(q.text)).filter((t) => t.trim() !== "");
+  const points = (data?.points ?? []).map((p, i) => textOf(p.text) || `point_${i}`);
+  return { nodeIds: [...quadrants, ...points], edges: 0, subgraphNames: [], maxDepth: 0 };
 }
 
 function adaptRequirement(db: AnyDb): Structure {
@@ -639,36 +670,56 @@ function adaptSankey(db: AnyDb): Structure {
 interface StateNode {
   id?: string;
   type?: string;
+  isGroup?: boolean;
+  parentId?: string;
 }
 interface StateEdge {
   id1?: string;
   id2?: string;
 }
+// A composite state (`state A { ... }`) is a group that holds other states,
+// so it counts as a subgraph too, and its nesting depth is read from each
+// state's parentId chain. It stays a node as well, because it is drawn as a
+// labelled state.
 function adaptState(db: AnyDb): Structure {
   // stateDiagram db exposes data on direct properties.
   const nodes = (db.nodes as StateNode[] | undefined) ?? [];
   const edges = (db.edges as StateEdge[] | undefined) ?? [];
+  const groups = nodes.filter((n) => n.isGroup === true);
+  const parentOf = new Map(nodes.map((n) => [n.id ?? "", n.parentId]));
+  let maxDepth = 0;
+  for (const g of groups) {
+    let depth = 1;
+    const seen = new Set<string>();
+    for (let cur = g.parentId; cur && !seen.has(cur); cur = parentOf.get(cur)) {
+      seen.add(cur);
+      depth++;
+    }
+    maxDepth = Math.max(maxDepth, depth);
+  }
   return {
     nodeIds: nodes.map((n) => n.id ?? ""),
     edges: edges.length,
-    subgraphNames: [],
-    maxDepth: 0,
+    subgraphNames: groups.map((g) => g.id ?? ""),
+    maxDepth,
   };
 }
 
 interface TimelineTask {
   task?: string;
   section?: string;
+  events?: string[];
 }
 interface TimelineSection {
   sectionName?: string;
   section?: string;
 }
 function adaptTimeline(db: AnyDb): Structure {
+  // Every period and every event under it is a box on the page.
   const tasks = callGetter<TimelineTask[]>(db, "getTasks") ?? [];
   const sections = callGetter<TimelineSection[]>(db, "getSections") ?? [];
   return {
-    nodeIds: tasks.map((t) => t.task ?? ""),
+    nodeIds: tasks.flatMap((t) => [t.task ?? "", ...(t.events ?? []).map((e) => `${t.task ?? ""}: ${e}`)]),
     edges: 0,
     subgraphNames: sections.map((s) => s.sectionName ?? s.section ?? ""),
     maxDepth: sections.length > 0 ? 1 : 0,
@@ -714,11 +765,16 @@ function adaptVenn(db: AnyDb): Structure {
 
 interface XYChartData {
   xAxis?: { categories?: string[] };
+  plots?: Array<{ data?: unknown[] }>;
 }
+// A node is an x position: a category, or, on a numeric x-axis, a point of the
+// longest series.
 function adaptXychart(db: AnyDb): Structure {
   const data = callGetter<XYChartData | null>(db, "getXYChartData");
   const categories = data?.xAxis?.categories ?? [];
-  return { nodeIds: categories, edges: 0, subgraphNames: [], maxDepth: 0 };
+  if (categories.length > 0) return { nodeIds: categories, edges: 0, subgraphNames: [], maxDepth: 0 };
+  const longest = Math.max(0, ...(data?.plots ?? []).map((p) => p.data?.length ?? 0));
+  return { nodeIds: Array.from({ length: longest }, (_, i) => `x_${i}`), edges: 0, subgraphNames: [], maxDepth: 0 };
 }
 
 function subgraphNestingDepth(subGraphs: Array<{ id?: string; nodes?: string[] }>): number {

package/src/plugins/contract.ts

@@ -37,5 +37,7 @@ export interface Plugin {
 
 // A one-word category and a namespace or rule key, as they appear in an id.
 export const CATEGORY_WORD = /^[a-z]+$/;
-export const NAMESPACE = /^[a-z][a-z0-9-]*$/;
-export const RULE_KEY = /^[a-z][a-z0-9-]*$/;
+// Lower-case words joined by single hyphens: no leading, trailing or doubled
+// hyphen, so `house-` and `a-` are refused.
+export const NAMESPACE = /^[a-z][a-z0-9]*(-[a-z0-9]+)*$/;
+export const RULE_KEY = /^[a-z][a-z0-9]*(-[a-z0-9]+)*$/;

package/src/plugins/discover.ts

@@ -4,14 +4,16 @@
 // names a config lists. A directory of node_modules is never scanned, so only
 // what the project chose to depend on can run.
 //
-// A declared package that is not installed is a failure the caller decides
-// how to treat, not an exception, so a lenient run can skip it and a
-// validating run can report every one. A malformed package.json throws.
+// A declared package that is not installed, or whose package.json is not a
+// JSON object, is a failure the caller decides how to treat, not an exception,
+// so a lenient run can skip it and a validating run can report every one. A
+// malformed project package.json throws PackageJsonError, except in a run with
+// plugins off, which loads no package it names.
 
 import { readdir, readFile } from "node:fs/promises";
 import { dirname, extname, isAbsolute, join, resolve } from "node:path";
 import type { Config } from "../config.ts";
-import { PluginNotInstalledError } from "../errors.ts";
+import { PackageJsonError, PluginLoadError, PluginNotInstalledError, PluginSourceError } from "../errors.ts";
 
 export type SourceKind = "local" | "package" | "config";
 
@@ -23,10 +25,16 @@ export interface PluginSource {
   path: string;
 }
 
+export interface UnresolvedSource {
+  kind: SourceKind;
+  error: PluginLoadError;
+}
+
 export interface Discovery {
   sources: PluginSource[];
-  // Sources found but not resolvable, such as a declared package that is not installed.
-  failures: PluginNotInstalledError[];
+  // Sources found but not resolvable, such as a declared package that is not
+  // installed, each with the kind of source that named it.
+  failures: UnresolvedSource[];
 }
 
 export const LOCAL_RULES = join(".mermaidjs-lint", "rules");
@@ -49,7 +57,7 @@ const readJson = async (path: string): Promise<Record<string, unknown> | null> =
   } catch {
     // Reported below with the path.
   }
-  throw new Error(`${path} is not a JSON object`);
+  throw new PackageJsonError(path);
 };
 
 // Every extension a local rule may have. Whether the runtime can import a
@@ -101,15 +109,27 @@ const entryOf = (pkg: Record<string, unknown>): string => {
 export const resolvePackage = async (root: string, name: string): Promise<string> => {
   for (let dir = resolve(root); ; dir = dirname(dir)) {
     const folder = join(dir, "node_modules", name);
-    const pkg = await readJson(join(folder, "package.json"));
+    let pkg: Record<string, unknown> | null;
+    try {
+      pkg = await readJson(join(folder, "package.json"));
+    } catch (err) {
+      if (!(err instanceof PackageJsonError)) throw err;
+      throw new PluginSourceError(name, `its package.json at ${err.file} is not a JSON object`);
+    }
     if (pkg) return join(folder, entryOf(pkg));
     if (dirname(dir) === dir) break;
   }
   throw new PluginNotInstalledError(name, root);
 };
 
-const declaredPlugins = async (root: string): Promise<string[]> => {
-  const pkg = await readJson(join(root, "package.json"));
+const declaredPlugins = async (root: string, tolerateBadManifest: boolean): Promise<string[]> => {
+  let pkg: Record<string, unknown> | null;
+  try {
+    pkg = await readJson(join(root, "package.json"));
+  } catch (err) {
+    if (tolerateBadManifest && err instanceof PackageJsonError) return [];
+    throw err;
+  }
   if (!pkg) return [];
   const names = ["dependencies", "devDependencies", "optionalDependencies"].flatMap((field) => {
     const deps = pkg[field];
@@ -118,18 +138,21 @@ const declaredPlugins = async (root: string): Promise<string[]> => {
   return [...new Set(names)].filter((name) => PACKAGE_PATTERN.test(name)).sort();
 };
 
-export const discoverSources = async (root: string, config: Config): Promise<Discovery> => {
+// A run with plugins off loads nothing, so a malformed project package.json,
+// which could only name packages that run will not load, does not stop it.
+export const discoverSources = async (root: string, config: Config, pluginsOff = false): Promise<Discovery> => {
   const sources = await localSources(root);
-  const failures: PluginNotInstalledError[] = [];
+  const failures: UnresolvedSource[] = [];
   const add = async (kind: SourceKind, spec: string, resolveIt: () => Promise<string>): Promise<void> => {
     try {
       sources.push({ kind, spec, path: await resolveIt() });
     } catch (err) {
-      if (!(err instanceof PluginNotInstalledError)) throw err;
-      failures.push(err);
+      if (!(err instanceof PluginLoadError)) throw err;
+      failures.push({ kind, error: err });
     }
   };
-  for (const name of await declaredPlugins(root)) await add("package", name, () => resolvePackage(root, name));
+  for (const name of await declaredPlugins(root, pluginsOff))
+    await add("package", name, () => resolvePackage(root, name));
   for (const spec of config.plugins || []) {
     const path = spec.startsWith(".") || isAbsolute(spec);
     await add("config", spec, () => (path ? Promise.resolve(resolve(root, spec)) : resolvePackage(root, spec)));

package/src/plugins/index.ts

@@ -34,7 +34,7 @@ export interface PluginSet {
 }
 
 export const loadPlugins = async (root: string, config: Config, mode: PluginMode): Promise<PluginSet> => {
-  const { sources: found, failures: unresolved } = await discoverSources(root, config);
+  const { sources: found, failures: unresolved } = await discoverSources(root, config, mode === "off");
   const set: PluginSet = {
     rules: [],
     categories: new Map(BUILTIN_CATEGORIES),
@@ -42,14 +42,16 @@ export const loadPlugins = async (root: string, config: Config, mode: PluginMode
     skipped: [],
     failures: [],
   };
-  if (mode === "off") return { ...set, skipped: [...found.map((s) => s.spec), ...unresolved.map((e) => e.source)] };
+  if (mode === "off") {
+    return { ...set, skipped: [...found.map((s) => s.spec), ...unresolved.map((u) => u.error.source)] };
+  }
 
   // Strict stops at the first failure. The others record it and carry on.
   const settle = (error: PluginLoadError, kind: SourceKind): void => {
     if (mode === "strict") throw error;
     if (!set.failures.some((f) => f.source === error.source)) set.failures.push({ source: error.source, kind, error });
   };
-  for (const error of unresolved) settle(error, "package");
+  for (const { error, kind } of unresolved) settle(error, kind);
 
   const loaded: { plugin: Plugin; kind: SourceKind; spec: string }[] = [];
   const locals = found.filter((s) => s.kind === "local");

package/src/plugins/load.ts

@@ -49,6 +49,9 @@ const importModule = async (source: PluginSource, runtime?: RuntimeInfo): Promis
 
 const OPTION_TYPES = new Set<OptionType>(["number", "string", "boolean", "string[]"]);
 
+// Option names every rule shares with the built-ins. See checkRule.
+const RESERVED_OPTIONS = ["preset", "profile"] as const;
+
 // Checks one rule's declaration and returns it, so a bad rule fails at load
 // rather than the first time it runs.
 const checkRule = (spec: string, key: string, raw: unknown, own: ReadonlySet<string>): PluginRule => {
@@ -80,6 +83,18 @@ const checkRule = (spec: string, key: string, raw: unknown, own: ReadonlySet<str
     if (!valid) {
       throw new PluginContractError(spec, `${where} options must map names to number, string, boolean or string[]`);
     }
+    // preset and profile keep their built-in meaning for every rule: the
+    // config checks the value against the built-in names, and --preset and
+    // --profile overwrite it. A rule may declare one to follow the run's
+    // setting, as a string, but cannot give the name another meaning.
+    for (const name of RESERVED_OPTIONS) {
+      if (name in options && (options as Record<string, unknown>)[name] !== "string") {
+        throw new PluginContractError(
+          spec,
+          `${where} declares option "${name}" as ${String((options as Record<string, unknown>)[name])}, but "${name}" is reserved for the built-in ${name}, which is a string set by --${name}; declare it as "string" to follow the run's ${name}, or pick another name`,
+        );
+      }
+    }
   }
   return raw as unknown as PluginRule;
 };
@@ -148,7 +163,23 @@ export const loadLocal = async (sources: PluginSource[], runtime?: RuntimeInfo):
   const categories: Record<string, string> = {};
   const owner: Record<string, string> = {};
   const loaded: { key: string; source: PluginSource; raw: unknown }[] = [];
+  // A rule's key is its file's base name, so two files with one base name
+  // (house-x.js and house-x.mjs) would claim one rule. Neither is imported,
+  // and the failure names both, rather than one silently replacing the other.
+  const keyOf = (source: PluginSource): string => basename(source.path, extname(source.path));
+  const byKey = new Map<string, PluginSource[]>();
+  for (const source of sources) byKey.set(keyOf(source), [...(byKey.get(keyOf(source)) ?? []), source]);
+  for (const [key, group] of byKey) {
+    if (group.length < 2) continue;
+    fail(
+      new PluginContractError(
+        (group[0] as PluginSource).spec,
+        `rule "${key}" is defined by more than one file: ${group.map((s) => s.spec).join(", ")}; each rule comes from exactly one file, so rename or remove all but one`,
+      ),
+    );
+  }
   for (const source of sources) {
+    if ((byKey.get(keyOf(source))?.length ?? 0) > 1) continue;
     try {
       const mod = await importModule(source, runtime);
       if (mod.default === undefined) {
@@ -166,7 +197,7 @@ export const loadLocal = async (sources: PluginSource[], runtime?: RuntimeInfo):
         categories[word] = description;
         owner[word] = source.spec;
       }
-      loaded.push({ key: basename(source.path, extname(source.path)), source, raw: mod.default });
+      loaded.push({ key: keyOf(source), source, raw: mod.default });
     } catch (err) {
       fail(err);
     }

package/src/project.ts

@@ -43,6 +43,8 @@ export interface SetupOptions {
 }
 
 export interface Setup {
+  // The project root the config and plugins were found from.
+  root: string;
   registry: Registry;
   skipped: string[];
   // Plugins left out because they failed. Empty unless the run was lenient or collecting.
@@ -84,5 +86,5 @@ export const setUp = async ({
     // rather than failing the run. A built-in id never is.
     ignoreUnknownPluginIds: mode !== "strict",
   });
-  return { registry, skipped: plugins.skipped, failures: plugins.failures };
+  return { root, registry, skipped: plugins.skipped, failures: plugins.failures };
 };

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

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

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

@@ -20,7 +20,7 @@ export const parseFenceUnterminated: Rule = {
           d,
           RULE.FENCE_UNTERMINATED,
           `mermaid fence opened at line ${d.startLine} is never closed`,
-          "Add a closing fence after the last line of the diagram.",
+          "Add a closing fence directly after the last line of the diagram, with the opening line's prefix: `> ` in a quote, the item's indent in a list.",
         ),
       ),
   fix: (ctx) => {