@jpeakai/mermaidjs-lint 0.2.0 → 0.4.0

package/dist/types/plugins/contract.d.ts

@@ -0,0 +1,24 @@
+import type { Awaitable, CheckContext, Edit, Finding, FixContext, OptionSpec } from "../rules/types.ts";
+export declare const API_VERSION = 1;
+export type PluginFinding = Pick<Finding, "line" | "message"> & Partial<Pick<Finding, "endLine" | "remediation">>;
+export type PluginEdit = Omit<Edit, "rule">;
+export interface PluginRule {
+    category: string;
+    summary: string;
+    options?: OptionSpec;
+    check: (ctx: CheckContext) => Awaitable<PluginFinding[]>;
+    fix?: (ctx: FixContext) => Awaitable<PluginEdit[]>;
+}
+export interface PluginMeta {
+    name: string;
+    namespace: string;
+    apiVersion: number;
+    categories?: Record<string, string>;
+}
+export interface Plugin {
+    meta: PluginMeta;
+    rules: Record<string, PluginRule>;
+}
+export declare const CATEGORY_WORD: RegExp;
+export declare const NAMESPACE: RegExp;
+export declare const RULE_KEY: RegExp;

package/dist/types/plugins/discover.d.ts

@@ -0,0 +1,20 @@
+import type { Config } from "../config.ts";
+import { PluginLoadError } from "../errors.ts";
+export type SourceKind = "local" | "package" | "config";
+export interface PluginSource {
+    kind: SourceKind;
+    spec: string;
+    path: string;
+}
+export interface UnresolvedSource {
+    kind: SourceKind;
+    error: PluginLoadError;
+}
+export interface Discovery {
+    sources: PluginSource[];
+    failures: UnresolvedSource[];
+}
+export declare const LOCAL_RULES: string;
+export declare const PACKAGE_PATTERN: RegExp;
+export declare const resolvePackage: (root: string, name: string) => Promise<string>;
+export declare const discoverSources: (root: string, config: Config, pluginsOff?: boolean) => Promise<Discovery>;

package/dist/types/plugins/index.d.ts

@@ -0,0 +1,19 @@
+import type { Config } from "../config.ts";
+import { PluginLoadError } from "../errors.ts";
+import { type LoadedSource } from "../rules/registry.ts";
+import type { Rule } from "../rules/types.ts";
+import { type SourceKind } from "./discover.ts";
+export type PluginMode = "off" | "strict" | "lenient" | "collect";
+export interface PluginFailure {
+    source: string;
+    kind: SourceKind;
+    error: PluginLoadError;
+}
+export interface PluginSet {
+    rules: Rule[];
+    categories: Map<string, string>;
+    sources: LoadedSource[];
+    skipped: string[];
+    failures: PluginFailure[];
+}
+export declare const loadPlugins: (root: string, config: Config, mode: PluginMode) => Promise<PluginSet>;

package/dist/types/plugins/load.d.ts

@@ -0,0 +1,14 @@
+import { PluginLoadError } from "../errors.ts";
+import type { Rule } from "../rules/types.ts";
+import { type Plugin, type PluginRule } from "./contract.ts";
+import type { PluginSource } from "./discover.ts";
+import { type RuntimeInfo } from "./runtime.ts";
+export { PluginLoadError };
+export declare const parsePlugin: (spec: string, raw: unknown, reserved: ReadonlySet<string>) => Plugin;
+export declare const loadPackage: (source: PluginSource, reserved: ReadonlySet<string>) => Promise<Plugin>;
+export interface LocalLoad {
+    plugin: Plugin | null;
+    failures: PluginLoadError[];
+}
+export declare const loadLocal: (sources: PluginSource[], runtime?: RuntimeInfo) => Promise<LocalLoad>;
+export declare const toRule: (namespace: string, key: string, rule: PluginRule) => Rule;

package/dist/types/plugins/runtime.d.ts

@@ -0,0 +1,6 @@
+export interface RuntimeInfo {
+    versions: Record<string, string | undefined>;
+    features: Record<string, unknown>;
+}
+export declare const canImportTypeScript: (runtime?: RuntimeInfo) => boolean;
+export declare const TYPESCRIPT_HELP = "TypeScript cannot be imported by this runtime. Run with Bun (bunx --bun @jpeakai/mermaidjs-lint), use Node 22.18 or newer, or write a .js or .mjs file";

package/dist/types/project.d.ts

@@ -0,0 +1,18 @@
+import { type PluginFailure } from "./plugins/index.ts";
+import { type Registry } from "./rules/registry.ts";
+export declare const LOCAL_DIR = ".mermaidjs-lint";
+export declare const findProjectRoot: (cwd: string) => Promise<string>;
+export interface SetupOptions {
+    cwd: string;
+    configPath?: string;
+    noPlugins?: boolean;
+    lenient?: boolean;
+    collect?: boolean;
+}
+export interface Setup {
+    root: string;
+    registry: Registry;
+    skipped: string[];
+    failures: PluginFailure[];
+}
+export declare const setUp: ({ cwd, configPath, noPlugins, lenient, collect, }: SetupOptions) => Promise<Setup>;

package/dist/types/rules/complexity-node-count-acceptable-exceeded.d.ts

@@ -0,0 +1 @@
+export declare const complexityNodeCountAcceptableExceeded: import("./types.ts").Rule;

package/dist/types/rules/complexity-node-count-cognitive-limit.d.ts

@@ -0,0 +1 @@
+export declare const complexityNodeCountCognitiveLimit: import("./types.ts").Rule;

package/dist/types/rules/complexity-node-count-hard-limit.d.ts

@@ -0,0 +1 @@
+export declare const complexityNodeCountHardLimit: import("./types.ts").Rule;

package/dist/types/rules/complexity-subgraph-nesting-too-deep.d.ts

@@ -0,0 +1,2 @@
+export declare const MAX_NESTING = 3;
+export declare const complexitySubgraphNestingTooDeep: import("./types.ts").Rule;

package/dist/types/rules/complexity-visual-score-acceptable-exceeded.d.ts

@@ -0,0 +1 @@
+export declare const complexityVisualScoreAcceptableExceeded: import("./types.ts").Rule;

package/dist/types/rules/complexity-visual-score-critical.d.ts

@@ -0,0 +1 @@
+export declare const complexityVisualScoreCritical: import("./types.ts").Rule;

package/dist/types/rules/complexity.d.ts

@@ -0,0 +1,12 @@
+import { type ThresholdConfig } from "../parse/metrics.ts";
+import { type Measured } from "./shared.ts";
+import type { Rule, RuleId } from "./types.ts";
+export interface Hit {
+    message: string;
+    remediation: string;
+}
+export declare const complexityRule: (spec: {
+    id: RuleId;
+    summary: string;
+    hit: (m: Measured, c: ThresholdConfig) => Hit | null;
+}) => Rule;

package/dist/types/rules/contrast-border-below-ui-minimum.d.ts

@@ -0,0 +1,2 @@
+import { type Rule } from "./types.ts";
+export declare const contrastBorderBelowUiMinimum: Rule;

package/dist/types/rules/contrast-directive-unauditable.d.ts

@@ -0,0 +1,2 @@
+import { type Rule } from "./types.ts";
+export declare const contrastDirectiveUnauditable: Rule;

package/dist/types/rules/contrast-text-below-aa.d.ts

@@ -0,0 +1,2 @@
+import { type Rule } from "./types.ts";
+export declare const contrastTextBelowAa: Rule;

package/dist/types/rules/index.d.ts

@@ -0,0 +1,3 @@
+import type { Rule } from "./types.ts";
+export declare const RULES: Rule[];
+export declare const FIX_ORDER: Rule[];

package/dist/types/rules/parse-diagram-unparseable.d.ts

@@ -0,0 +1,2 @@
+import { type Rule } from "./types.ts";
+export declare const parseDiagramUnparseable: Rule;

package/dist/types/rules/parse-fence-unterminated.d.ts

@@ -0,0 +1,2 @@
+import { type Rule } from "./types.ts";
+export declare const parseFenceUnterminated: Rule;

package/dist/types/rules/registry.d.ts

@@ -0,0 +1,29 @@
+import type { Config } from "../config.ts";
+import { type Helpers, type Rule, type RuleId, type RuleOptions } from "./types.ts";
+export declare const BUILTIN_CATEGORIES: ReadonlyMap<string, string>;
+export declare const HELPERS: Helpers;
+export interface LoadedSource {
+    kind: "local" | "package" | "config";
+    spec: string;
+    namespace: string;
+    rules: RuleId[];
+}
+export interface Registry {
+    rules: Rule[];
+    fixOrder: Rule[];
+    enabled: ReadonlySet<RuleId>;
+    options: ReadonlyMap<RuleId, RuleOptions>;
+    categories: ReadonlyMap<string, string>;
+    sources: LoadedSource[];
+    ignoredSettings: string[];
+}
+export interface RegistryInput {
+    rules: Rule[];
+    fixOrder: Rule[];
+    categories: ReadonlyMap<string, string>;
+    sources?: LoadedSource[];
+    config?: Config;
+    ignoreUnknownPluginIds?: boolean;
+}
+export declare const buildRegistry: (input: RegistryInput) => Registry;
+export declare const BUILTIN: Registry;

package/dist/types/rules/shared.d.ts

@@ -0,0 +1,18 @@
+import type { Diagram } from "../model.ts";
+import { type ContrastResult, type Profile } from "../parse/contrast.ts";
+import { type ComplexityMetrics, type ThresholdConfig } from "../parse/metrics.ts";
+import type { DiagramStats } from "../parse/stats.ts";
+import type { Finding, OptionSpec, RuleContext, RuleId } from "./types.ts";
+export declare const COMPLEXITY_OPTIONS: OptionSpec;
+export declare const CONTRAST_OPTIONS: OptionSpec;
+export interface Measured {
+    stats: DiagramStats;
+    metrics: ComplexityMetrics;
+}
+export declare const measure: (diagram: Diagram, config: ThresholdConfig) => Promise<Measured | null>;
+export declare const finding: (ctx: RuleContext, diagram: Diagram, rule: RuleId, message: string, remediation?: string) => Finding;
+export declare const boundaryHint: (boundaries: string[]) => string;
+export declare const splitTarget: (c: ThresholdConfig) => string;
+export declare const profileOf: (ctx: RuleContext) => Profile;
+export declare const contrastOf: (diagram: Diagram, profile: Profile) => ContrastResult;
+export declare const fileLine: (diagram: Diagram, line: number) => number;

package/dist/types/rules/types.d.ts

@@ -0,0 +1,67 @@
+import type { DocModel } from "../model.ts";
+import type { compositeOver, wcagRatio } from "../parse/color.ts";
+import type { detectKeyword } from "../parse/stats.ts";
+export declare const RULE: {
+    readonly UNPARSEABLE: "parse-diagram-unparseable";
+    readonly FENCE_UNTERMINATED: "parse-fence-unterminated";
+    readonly NODES_HARD: "complexity-node-count-hard-limit";
+    readonly NODES_COGNITIVE: "complexity-node-count-cognitive-limit";
+    readonly NODES_ACCEPTABLE: "complexity-node-count-acceptable-exceeded";
+    readonly VCS_CRITICAL: "complexity-visual-score-critical";
+    readonly VCS_ACCEPTABLE: "complexity-visual-score-acceptable-exceeded";
+    readonly NESTING: "complexity-subgraph-nesting-too-deep";
+    readonly TEXT: "contrast-text-below-aa";
+    readonly BORDER: "contrast-border-below-ui-minimum";
+    readonly UNAUDITABLE: "contrast-directive-unauditable";
+};
+export type CoreRuleId = (typeof RULE)[keyof typeof RULE];
+export type Awaitable<T> = T | Promise<T>;
+export type PluginRuleId = `${string}/${string}`;
+export declare const isPluginRuleId: (id: string) => id is PluginRuleId;
+export type RuleId = CoreRuleId | PluginRuleId;
+export interface Finding {
+    file: string;
+    line: number;
+    endLine: number;
+    rule: RuleId;
+    message: string;
+    remediation?: string;
+}
+export type OptionType = "number" | "string" | "boolean" | "string[]";
+export type OptionSpec = Readonly<Record<string, OptionType>>;
+export type RuleOptions = Readonly<Record<string, unknown>>;
+export interface Helpers {
+    detectKeyword: typeof detectKeyword;
+    wcagRatio: typeof wcagRatio;
+    compositeOver: typeof compositeOver;
+}
+export interface RuleContext {
+    doc: DocModel;
+    file: string;
+    options: RuleOptions;
+    helpers: Helpers;
+}
+export type CheckContext = RuleContext;
+export type FixContext = RuleContext;
+export type Expectation = {
+    kind: "same-diagrams";
+} | {
+    kind: "same-tree";
+};
+export interface Edit {
+    rule: RuleId;
+    start: number;
+    end: number;
+    text: string;
+    expect: Expectation;
+}
+export declare const CATEGORIES: readonly ["parse", "complexity", "contrast"];
+export type Category = (typeof CATEGORIES)[number];
+export interface Rule {
+    id: RuleId;
+    category: string;
+    summary: string;
+    options?: OptionSpec;
+    check: (ctx: CheckContext) => Awaitable<Finding[]>;
+    fix?: (ctx: FixContext) => Awaitable<Edit[]>;
+}

package/dist/types/testing.d.ts

@@ -0,0 +1,15 @@
+import { type RunFlags } from "./check.ts";
+import { type FixReport } from "./fix/engine.ts";
+import type { Plugin, PluginRule } from "./plugins/contract.ts";
+import type { Finding, RuleOptions } from "./rules/types.ts";
+export interface RunOptions {
+    options?: RuleOptions;
+    flags?: RunFlags;
+    file?: string;
+}
+export declare const localPlugin: (key: string, mod: {
+    default: PluginRule;
+    categories?: Record<string, string>;
+}) => Plugin;
+export declare const checkRule: (plugin: Plugin, key: string, src: string, run?: RunOptions) => Promise<Finding[]>;
+export declare const fixRule: (plugin: Plugin, key: string, src: string, run?: RunOptions) => Promise<FixReport>;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jpeakai/mermaidjs-lint",
-  "version": "0.2.0",
+  "version": "0.4.0",
   "type": "module",
   "description": "Deterministic lint gates and verified fixers for Mermaid diagrams in markdown",
   "license": "MIT",
@@ -29,15 +29,16 @@
   "bin": {
     "mermaidjs-lint": "dist/bin.js"
   },
+  "types": "./dist/types/index.d.ts",
   "exports": {
     ".": {
+      "types": "./dist/types/index.d.ts",
       "bun": "./src/index.ts",
-      "types": "./src/index.ts",
       "default": "./dist/index.js"
     },
     "./testing": {
+      "types": "./dist/types/testing.d.ts",
       "bun": "./src/testing.ts",
-      "types": "./src/testing.ts",
       "default": "./dist/testing.js"
     }
   },
@@ -51,6 +52,7 @@
   ],
   "dependencies": {
     "@mermaid-js/parser": "^1.1.0",
+    "@types/mdast": "^4",
     "colorjs.io": "^0.6.1",
     "happy-dom": "^20.9.0",
     "mdast-util-from-markdown": "^2.0.3",
@@ -64,7 +66,6 @@
     "@biomejs/biome": "^2",
     "@jpeakai/prose-gates": "^0.2.0",
     "@types/bun": "latest",
-    "@types/mdast": "^4",
     "typescript": "^5"
   }
 }

package/src/cli.ts

@@ -1,12 +1,12 @@
 // The command line: check files, optionally fix them first. The process glue
 // lives in bin.ts so tests can call main() directly.
 
-import { readFile, writeFile } from "node:fs/promises";
-import { relative } from "node:path";
+import { lstat, readFile, realpath, writeFile } from "node:fs/promises";
+import { isAbsolute, relative, resolve } 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 { FixOutsideRootError, FlagError, MermaidLintError, UsageError } from "./errors.ts";
 import { collectFiles, DIAGRAM_FILE_EXTS, SKIP_DIRS } from "./files.ts";
 import { fixSourceReport } from "./fix/engine.ts";
 import { buildDocModel, DIAGRAM_EXTS, documentKind } from "./model.ts";
@@ -16,7 +16,7 @@ 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, type Finding } from "./rules/types.ts";
+import { CATEGORIES, type Finding, type Rule } from "./rules/types.ts";
 
 // The invocation forms, printed alone after a usage error so the error is not
 // buried, and first in --help.
@@ -26,19 +26,25 @@ const SYNOPSIS = `usage: mermaidjs-lint <path...> [--fix] [--json] [--preset NAM
        mermaidjs-lint --validate-plugins [--json] [--config FILE]
        mermaidjs-lint --version | -h, --help`;
 
+// One rule as help and --list-rules print it: the id padded to a column, the
+// autofix marker inside it, then the summary, so every summary lines up.
+const ruleRow = (r: Rule, width: number): string => `${`${r.id}${r.fix ? "*" : ""}`.padEnd(width)}  ${r.summary}`;
+
+const idWidth = (rules: Rule[]): number => Math.max(0, ...rules.map((r) => r.id.length + 1));
+
 const 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(
-    "\n",
-  ),
+  [`  ${c}:`, ...RULES.filter((r) => r.category === c).map((r) => `    ${ruleRow(r, idWidth(RULES))}`)].join("\n"),
 ).join("\n")}
 
 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(", ")}.
+skipping dot-folders and ${[...SKIP_DIRS].join(", ")}. The walk does not follow a symbolic link,
+and names each one it skipped. A link named as a path is read, but --fix does not write
+through one whose target is outside the project root.
 Examples of every rule, with fixes: https://jpeakai.github.io/jpai-mermaidjs-lint/reference/rules/
 
 -p, --preset NAME sets the density for every complexity rule: ${PRESET_NAMES.join(", ")}
@@ -49,14 +55,16 @@ Examples of every rule, with fixes: https://jpeakai.github.io/jpai-mermaidjs-lin
 --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-*.
+Plugins load on their own from .mermaidjs-lint/rules, from dependencies named mermaidjs-lint-plugin,
+  mermaidjs-lint-plugin-* or @scope/mermaidjs-lint-plugin(-*), and from the config's plugins list.
 --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.
+--validate-plugins imports 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.
+  It imports the plugins to list them.
 --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
+Exits 0 when no findings remain, 1 when findings remain, a plugin fails to load or the run fails (a lenient run
 skips a broken plugin, so it alone does not exit 1), and 2 on a usage error.`;
 
 interface Parsed {
@@ -122,11 +130,12 @@ export const skippedLines = (failures: PluginFailure[], ignored: string[]): stri
 // Every active rule under its category, then where each plugin came from.
 export const listRules = (registry: Registry): string => {
   const lines: string[] = [];
+  const width = idWidth(registry.rules);
   for (const [category, description] of registry.categories) {
     const rules = registry.rules.filter((r) => r.category === category);
     if (rules.length === 0) continue;
     lines.push(`${category}: ${description}`);
-    for (const r of rules) lines.push(`  ${r.id}${r.fix ? "*" : " "} ${r.summary}`);
+    for (const r of rules) lines.push(`  ${ruleRow(r, width)}`);
   }
   if (registry.sources.length > 0) {
     lines.push("", "plugins:");
@@ -180,6 +189,19 @@ const display = (file: string, cwd: string): string => {
   return !rel || rel.startsWith("..") ? file : rel;
 };
 
+// --fix writes through a symbolic link to its target, so a link whose target
+// sits outside the project root would let a run edit a file in another tree.
+// Every such link is refused before any file is written.
+const refuseOutsideLinks = async (files: string[], root: string, cwd: string): Promise<void> => {
+  const realRoot = await realpath(root);
+  for (const file of files) {
+    if (!(await lstat(file)).isSymbolicLink()) continue;
+    const target = await realpath(file);
+    const rel = relative(realRoot, target);
+    if (rel.startsWith("..") || isAbsolute(rel)) throw new FixOutsideRootError(display(file, cwd), target, root);
+  }
+};
+
 const run = async (argv: string[], cwd: string): Promise<number> => {
   let parsed: Parsed;
   try {
@@ -215,7 +237,7 @@ const run = async (argv: string[], cwd: string): Promise<number> => {
   }
   if (positionals.length === 0 && !listing && !validating) throw new FlagError("files", "no files given");
 
-  const { registry, skipped, failures } = await setUp({
+  const { root, registry, skipped, failures } = await setUp({
     cwd,
     configPath: values.config,
     noPlugins: values["no-plugins"],
@@ -238,10 +260,18 @@ const run = async (argv: string[], cwd: string): Promise<number> => {
     return 0;
   }
 
-  const { files, unreadable } = collectFiles(positionals.map((p) => (p.startsWith("/") ? p : `${cwd}/${p}`)));
+  const { files, unreadable, symlinks } = collectFiles(positionals.map((p) => resolve(cwd, p)));
   if (unreadable.length > 0) throw new FlagError("files", `cannot read ${unreadable.join(", ")}`);
+  for (const link of symlinks) {
+    console.error(`mermaidjs-lint: skipped symbolic link ${display(link, cwd)}; name it as a path to check it`);
+  }
   if (files.length === 0) throw new FlagError("files", "no matching files");
+  if (values.fix) await refuseOutsideLinks(files, root, cwd);
 
+  // Every rule, in check and in fix, sees the file as an absolute path, so a
+  // rule that reads the path sees one form, and the auto profile is found
+  // from the file's own folder whatever the process's working directory. The
+  // report shows the path relative to cwd.
   const flags: RunFlags = { preset: values.preset, profile: values.profile };
   const perFile = await Promise.all(
     files.map(async (file) => {
@@ -253,7 +283,9 @@ const run = async (argv: string[], cwd: string): Promise<number> => {
           src = fixed;
         }
       }
-      return checkModel(buildDocModel(src, documentKind(file)), display(file, cwd), flags, registry);
+      const shown = display(file, cwd);
+      const found = await checkModel(buildDocModel(src, documentKind(file)), file, flags, registry);
+      return found.map((f) => ({ ...f, file: shown }));
     }),
   );
   const all = perFile.flat();

package/src/errors.ts

@@ -130,6 +130,52 @@ export class RuleOptionError extends UsageError {
   }
 }
 
+// --fix would write through a symbolic link whose target sits outside the
+// project root, so the run stops before any file is written.
+export class FixOutsideRootError extends UsageError {
+  readonly file: string;
+  readonly target: string;
+
+  constructor(file: string, target: string, root: string) {
+    super(
+      `${file} is a symbolic link to ${target}, outside the project root ${root}; --fix does not write through it. Fix the target in its own project, or run on the target path itself`,
+      "fix-outside-root",
+    );
+    this.file = file;
+    this.target = target;
+  }
+}
+
+// --- runtime: the project or a fixer is in a state the run cannot use -------
+
+// A package.json the run reads, the project's own or an installed plugin's, is
+// not a JSON object. Exits 1, like any runtime failure.
+export class PackageJsonError extends MermaidLintError {
+  readonly file: string;
+
+  constructor(file: string) {
+    super("package-json", `${file} is not a JSON object; fix or remove it`);
+    this.file = file;
+  }
+}
+
+// A fixer, built-in or plugin, kept proposing edits that verified, so the fix
+// never reached a fixpoint. A fixer must be idempotent: once its edit is
+// applied, it proposes nothing for the same text. Nothing is written.
+export class FixNotConvergingError extends MermaidLintError {
+  readonly file: string;
+  readonly rules: string[];
+
+  constructor(file: string, passes: number, rules: string[]) {
+    super(
+      "fix-not-converging",
+      `${file}: --fix did not converge after ${passes} passes; ${rules.join(", ")} kept proposing edits. A fixer must propose nothing once its edit is applied`,
+    );
+    this.file = file;
+    this.rules = rules;
+  }
+}
+
 // --- plugins: a source could not be loaded --------------------------------
 
 // A source that failed to load. `source` is what the user would recognise, a

package/src/files.ts

@@ -17,15 +17,30 @@ export const SKIP_DIRS = new Set(["node_modules", "vendor", "dist", "build", "tm
 
 const skipDir = (name: string): boolean => name.startsWith(".") || SKIP_DIRS.has(name);
 
+// Whether a link resolves to a directory. A dangling link resolves to nothing.
+const linksToDir = (path: string): boolean => {
+  try {
+    return statSync(path).isDirectory();
+  } catch {
+    return false;
+  }
+};
+
 export interface Collected {
   files: string[];
   // Paths that could not be read, which the caller reports as usage errors.
   unreadable: string[];
+  // Symbolic links a directory walk passed over, to files or folders alike.
+  // A walk never follows a link, so it cannot leave the tree it was given or
+  // loop, and the caller says which it skipped so a gate never passes in
+  // silence over a file it did not read. A link named as a path is followed.
+  symlinks: string[];
 }
 
 export const collectFiles = (paths: string[]): Collected => {
   const files: string[] = [];
   const unreadable: string[] = [];
+  const symlinks: string[] = [];
   const seen = new Set<string>();
 
   const walk = (dir: string): void => {
@@ -38,7 +53,11 @@ export const collectFiles = (paths: string[]): Collected => {
     }
     for (const entry of entries.sort((a, b) => a.name.localeCompare(b.name))) {
       const abs = join(dir, entry.name);
-      if (entry.isDirectory()) {
+      if (entry.isSymbolicLink()) {
+        if (!skipDir(entry.name) && (DIAGRAM_FILE_EXTS.has(extname(entry.name).toLowerCase()) || linksToDir(abs))) {
+          symlinks.push(abs);
+        }
+      } else if (entry.isDirectory()) {
         if (!skipDir(entry.name)) walk(abs);
       } else if (entry.isFile() && DIAGRAM_FILE_EXTS.has(extname(entry.name).toLowerCase())) {
         if (!seen.has(abs)) {
@@ -64,5 +83,5 @@ export const collectFiles = (paths: string[]): Collected => {
       unreadable.push(p);
     }
   }
-  return { files, unreadable };
+  return { files, unreadable, symlinks };
 };