@jpeakai/mermaidjs-lint 0.6.3 → 0.7.1

package/README.md

@@ -1,30 +1,37 @@
-# jpai-mermaidjs-lint
+# mermaidjs-lint
 
-Diagrams in documentation should be readable.
-Deterministic checks and verified fixes for Mermaid diagrams in markdown.
+Catch Mermaid diagrams in your markdown that fail to parse, turn unreadable in light or dark themes, or grow too big to follow.
 
-**[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)**
+**[Docs](https://jpeakai.github.io/jpai-mermaidjs-lint/)** | **[Rules](https://jpeakai.github.io/jpai-mermaidjs-lint/reference/rules/)** | **[Changelog](CHANGELOG.md)** | **[npm](https://www.npmjs.com/package/@jpeakai/mermaidjs-lint)**
 
-The docs site describes the latest release on npm.
-This README, read on GitHub, describes the `main` branch.
-A change on `main` that is not yet released is listed under `Unreleased` in the [changelog](CHANGELOG.md).
-
-## Usage
+## Lint your docs with one command
 
 ```sh
-bunx @jpeakai/mermaidjs-lint README.md docs/     # report findings, exit 1 if any
-npx -y @jpeakai/mermaidjs-lint --fix docs/       # apply every fix proven safe, report the rest
+npx -y @jpeakai/mermaidjs-lint docs/
+```
+
+```text
+docs/architecture.md:6 contrast-text-below-aa classDef warn: text 1.43:1 < 4.5 (#ffffff on #ffd400)
+docs/login.md:3-7 parse-diagram-unparseable sequenceDiagram did not parse (parser: mermaid-core) (its line numbers count within the diagram, not the file): Parse error on line 3: Expecting 'TXT', got 'NEWLINE'
+docs/pipeline.md:3-41 complexity-node-count-acceptable-exceeded 37 nodes > 35 acceptable threshold
+3 finding(s) in 3 file(s)
 ```
 
-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.
+The run exits 1 while any finding remains, so it works as a CI gate.
+
+## Fix unreadable label text and unclosed fences
+
+Add `--fix` to apply the fixes that pass verification:
+
+```diff
+-  classDef warn fill:#ffd400,color:#ffffff
++  classDef warn fill:#ffd400,color:#000000
+```
 
-[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.
+A fix is kept only if the markdown around the diagrams is unchanged and each diagram reparses with the same node ids, subgraphs and counts.
+Edge endpoints, edge labels and node text are not compared, so review the diff.
 
-## The four tenets
+## Four tenets define the tool
 
 Three tenets are guarantees about every diagram the tool passes, and the fourth is a commitment about the tool.
 
@@ -33,101 +40,28 @@ Three tenets are guarantees about every diagram the tool passes, and the fourth
 - **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.
 
-| 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 |
+## Go further in the docs site
 
-The [concepts page](https://jpeakai.github.io/jpai-mermaidjs-lint/concepts/) states the limit of each tenet.
-`bunx @jpeakai/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.
-
-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, and whether it parses.
-It does not compare edge endpoints, edge labels or node text, so review the diff a fix writes.
-
-## Requirements and compatibility
-
-- **Runtime:** Bun, or Node `>=20` as the `engines` field of `package.json` states.
-- **Mermaid:** the parse and contrast rules use the `mermaid` package at exactly `11.17.2`, and `@mermaid-js/parser`, both installed with this package. The pin holds sequence diagram colours, which change between mermaid releases.
-- **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.
-
-`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.
-
-## Configure and extend
-
-- [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.
+- [Get started](https://jpeakai.github.io/jpai-mermaidjs-lint/get-started/): run it, fix a diagram, and add the gate to your project.
+- [Gate diagrams in CI](https://jpeakai.github.io/jpai-mermaidjs-lint/guides/ci/) or [before each commit](https://jpeakai.github.io/jpai-mermaidjs-lint/guides/pre-commit/).
+- [Configure the rules](https://jpeakai.github.io/jpai-mermaidjs-lint/guides/configure/), or [write a local rule](https://jpeakai.github.io/jpai-mermaidjs-lint/guides/local-rule/).
 
 ## Use it from an AI agent
 
-[`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.
-The skill is the one file `SKILL.md`.
-Its `evals/` folder holds deliberately failing fixtures for this repository's own tests, so never copy it.
-For Claude Code, run these in your project:
+The agent skill in [`skills/mermaidjs-lint/SKILL.md`](skills/mermaidjs-lint/SKILL.md) runs the tool, applies the safe fixes, and fixes the rest by judgement.
+Copy it into a Claude Code project:
 
 ```sh
-mkdir -p .claude/skills/mermaidjs-lint
-curl -fsSL https://raw.githubusercontent.com/jpeakai/jpai-mermaidjs-lint/main/skills/mermaidjs-lint/SKILL.md \
-  -o .claude/skills/mermaidjs-lint/SKILL.md
-```
-
-Use `~/.claude/skills/mermaidjs-lint` instead to use it in every project.
-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 fixed the failing fixtures it lists, and which skill revision they used.
-
-## Library use
-
-```ts
-import { checkMarkdown, fixSource } from "@jpeakai/mermaidjs-lint";
-
-const findings = await checkMarkdown(src, "README.md");
-const fixed = await fixSource(src, "README.md");
+curl -fsSL --create-dirs -o .claude/skills/mermaidjs-lint/SKILL.md \
+  https://raw.githubusercontent.com/jpeakai/jpai-mermaidjs-lint/main/skills/mermaidjs-lint/SKILL.md
 ```
 
-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 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
+## Runs on Bun or Node
 
-[CONTRIBUTING.md](CONTRIBUTING.md) covers setup and how a change is accepted.
+It needs Bun, or Node `>=20`.
+The package installs mermaid `11.17.2` to parse diagrams, and your host may draw with another version.
 
-## Licence
+## Contribute
 
-MIT, as stated in [LICENSE](LICENSE).
+[CONTRIBUTING.md](CONTRIBUTING.md) covers setup.
+Licensed under [MIT](LICENSE).

package/dist/bin.js

@@ -9,7 +9,7 @@ import { parseArgs } from "node:util";
 // package.json
 var package_default = {
   name: "@jpeakai/mermaidjs-lint",
-  version: "0.6.3",
+  version: "0.7.1",
   type: "module",
   description: "Deterministic lint gates and verified fixers for Mermaid diagrams in markdown",
   license: "MIT",
@@ -1936,6 +1936,22 @@ var BUILTIN_CATEGORIES = new Map([
   ["contrast", "Whether labels and borders can be read against their fills"]
 ]);
 var HELPERS = { detectKeyword, wcagRatio, compositeOver };
+var selectionNames = (prefix) => prefix ? { enable: `${prefix}category`, disable: `${prefix}disable-category` } : { enable: "selection.enable", disable: "selection.disable" };
+var checkSelection = (selection, categories) => {
+  const names = selectionNames(selection.prefix ?? "");
+  const known = [...categories.keys()];
+  for (const side of ["enable", "disable"]) {
+    for (const word of selection[side] ?? []) {
+      if (!categories.has(word)) {
+        throw new FlagError(names[side], `${names[side]} names no loaded category "${word}"; the categories are ${known.join(", ")}`);
+      }
+    }
+  }
+  const both = (selection.enable ?? []).filter((word) => selection.disable?.includes(word));
+  if (both.length > 0) {
+    throw new FlagError(names.disable, `${names.enable} and ${names.disable} both name ${[...new Set(both)].join(", ")}; name each category once`);
+  }
+};
 var typeOf = (value) => {
   if (typeof value === "number" && Number.isFinite(value))
     return "number";
@@ -1992,6 +2008,8 @@ var checkOptions = (where, rule, options) => {
 };
 var buildRegistry = (input) => {
   const { rules, fixOrder, categories, sources = [], config, ignoreUnknownPluginIds = false } = input;
+  const selection = input.selection ?? {};
+  checkSelection(selection, categories);
   const off = new Set;
   const options = new Map;
   const ignored = [];
@@ -2006,12 +2024,21 @@ var buildRegistry = (input) => {
       throw new UnknownRuleError(where, id, rules.map((r) => r.id));
     }
     checkOptions(where, rule, setting.options);
+    options.set(rule.id, setting.options);
     if (setting.severity === "off")
       off.add(id);
-    else
-      options.set(rule.id, setting.options);
+  }
+  for (const rule of rules) {
+    if (selection.enable?.includes(rule.category))
+      off.delete(rule.id);
+    if (selection.disable?.includes(rule.category))
+      off.add(rule.id);
   }
   const active = rules.filter((r) => !off.has(r.id));
+  if (active.length === 0 && (selection.disable?.length ?? 0) > 0) {
+    const name = selectionNames(selection.prefix ?? "").disable;
+    throw new FlagError(name, `${name} leaves no rule to run; disable fewer categories`);
+  }
   return {
     rules: active,
     fixOrder: fixOrder.filter((r) => !off.has(r.id)),
@@ -2792,7 +2819,8 @@ var setUp = async ({
   configPath,
   noPlugins = false,
   lenient = false,
-  collect = false
+  collect = false,
+  selection
 }) => {
   const root = await findProjectRoot(cwd);
   let file;
@@ -2820,7 +2848,8 @@ var setUp = async ({
     categories: plugins.categories,
     sources: plugins.sources,
     config,
-    ignoreUnknownPluginIds: mode !== "strict"
+    ignoreUnknownPluginIds: mode !== "strict",
+    ...selection && { selection }
   });
   return { root, registry, skipped: plugins.skipped, failures: plugins.failures };
 };
@@ -2828,7 +2857,8 @@ var setUp = async ({
 // src/cli.ts
 var SYNOPSIS = `usage: mermaidjs-lint <path...> [--fix] [--json] [--preset NAME] [--profile NAME] [--config FILE]
                      [--canvas-light COLOUR] [--canvas-dark COLOUR] [--no-plugins | --lenient-plugins]
-       mermaidjs-lint --list-rules [--config FILE] [--no-plugins | --lenient-plugins]
+                     [--category NAME]... [--disable-category NAME]...
+       mermaidjs-lint --list-rules [--config FILE] [--no-plugins | --lenient-plugins] [category flags]
        mermaidjs-lint --validate-plugins [--json] [--config FILE]
        mermaidjs-lint --version | -h, --help`;
 var ruleRow = (r, width) => `${`${r.id}${r.fix ? "*" : ""}`.padEnd(width)}  ${r.summary}`;
@@ -2858,6 +2888,10 @@ Examples of every rule, with fixes: https://jpeakai.github.io/jpai-mermaidjs-lin
   on it. Each is an opaque CSS colour such as #faf8f9, and a side not given keeps the config's, or GitHub's
   (#ffffff light, #0d1117 dark). A file scored under mkdocs-material refuses a canvas flag with a usage
   error, and sets a config canvas aside when auto picked the profile.
+--disable-category NAME turns off every rule in that category for this run, after the config is applied.
+--category NAME turns on every rule in that category for this run, even one the config turns off.
+  Each may be repeated or take a comma-separated list, such as --disable-category parse,complexity.
+  A category that is not loaded, one named by both flags, or a run left with no rule is a usage error.
 --json prints one JSON object instead of text lines.
 --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.
@@ -2869,7 +2903,7 @@ Plugins load on their own from .mermaidjs-lint/rules, from dependencies named me
 --lenient-plugins skips a plugin that fails to load and says so, instead of stopping the run.
 --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, and takes no path or other flag.
+  It imports the plugins to list them. It takes the category flags, to preview a run, and no path or other flag.
 --version prints the version, to quote in a bug report.
 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.`;
@@ -2888,11 +2922,19 @@ var parse2 = (argv) => parseArgs({
     "lenient-plugins": { type: "boolean", default: false },
     "validate-plugins": { type: "boolean", default: false },
     "list-rules": { type: "boolean", default: false },
-    version: { type: "boolean", default: false }
+    version: { type: "boolean", default: false },
+    category: { type: "string", multiple: true },
+    "disable-category": { type: "string", multiple: true }
   },
   allowPositionals: true,
   strict: true
 });
+var categoryWords = (flag, values) => (values ?? []).flatMap((value) => value.split(",").map((word) => {
+  const trimmed = word.trim();
+  if (!trimmed)
+    throw new FlagError(flag, `${flag} needs a category name, not "${value}"`);
+  return trimmed;
+}));
 var plural = (n, word) => `${n} ${word}${n === 1 ? "" : "s"}`;
 var namesOf = (sources) => sources.map((s) => `${s.namespace} (${plural(s.rules.length, "rule")})`).join(", ");
 var loadedLine = (sources, skipped) => {
@@ -3004,6 +3046,11 @@ var run = async (argv, cwd) => {
   if (validating && (values["no-plugins"] || values.fix || listing)) {
     throw new FlagError("--validate-plugins", "--validate-plugins takes no --no-plugins, --fix or --list-rules");
   }
+  const enable = categoryWords("--category", values.category);
+  const disable = categoryWords("--disable-category", values["disable-category"]);
+  if (validating && enable.length + disable.length > 0) {
+    throw new FlagError("--validate-plugins", "--validate-plugins checks every plugin, so it takes no category flag");
+  }
   if (listing && !validating) {
     const ignored = [
       ...["fix", "json", "preset", "profile", "canvas-light", "canvas-dark"].filter((name) => values[name] !== undefined && values[name] !== false).map((name) => `--${name}`),
@@ -3023,7 +3070,8 @@ var run = async (argv, cwd) => {
     configPath: values.config,
     noPlugins: values["no-plugins"],
     lenient: values["lenient-plugins"],
-    collect: validating
+    collect: validating,
+    selection: { enable, disable, prefix: "--" }
   });
   if (validating) {
     const result = validate(registry, failures, Boolean(values.json));

package/dist/index.js

@@ -1858,6 +1858,22 @@ var BUILTIN_CATEGORIES = new Map([
   ["contrast", "Whether labels and borders can be read against their fills"]
 ]);
 var HELPERS = { detectKeyword, wcagRatio, compositeOver };
+var selectionNames = (prefix) => prefix ? { enable: `${prefix}category`, disable: `${prefix}disable-category` } : { enable: "selection.enable", disable: "selection.disable" };
+var checkSelection = (selection, categories) => {
+  const names = selectionNames(selection.prefix ?? "");
+  const known = [...categories.keys()];
+  for (const side of ["enable", "disable"]) {
+    for (const word of selection[side] ?? []) {
+      if (!categories.has(word)) {
+        throw new FlagError(names[side], `${names[side]} names no loaded category "${word}"; the categories are ${known.join(", ")}`);
+      }
+    }
+  }
+  const both = (selection.enable ?? []).filter((word) => selection.disable?.includes(word));
+  if (both.length > 0) {
+    throw new FlagError(names.disable, `${names.enable} and ${names.disable} both name ${[...new Set(both)].join(", ")}; name each category once`);
+  }
+};
 var typeOf = (value) => {
   if (typeof value === "number" && Number.isFinite(value))
     return "number";
@@ -1914,6 +1930,8 @@ var checkOptions = (where, rule, options) => {
 };
 var buildRegistry = (input) => {
   const { rules, fixOrder, categories, sources = [], config, ignoreUnknownPluginIds = false } = input;
+  const selection = input.selection ?? {};
+  checkSelection(selection, categories);
   const off = new Set;
   const options = new Map;
   const ignored = [];
@@ -1928,12 +1946,21 @@ var buildRegistry = (input) => {
       throw new UnknownRuleError(where, id, rules.map((r) => r.id));
     }
     checkOptions(where, rule, setting.options);
+    options.set(rule.id, setting.options);
     if (setting.severity === "off")
       off.add(id);
-    else
-      options.set(rule.id, setting.options);
+  }
+  for (const rule of rules) {
+    if (selection.enable?.includes(rule.category))
+      off.delete(rule.id);
+    if (selection.disable?.includes(rule.category))
+      off.add(rule.id);
   }
   const active = rules.filter((r) => !off.has(r.id));
+  if (active.length === 0 && (selection.disable?.length ?? 0) > 0) {
+    const name = selectionNames(selection.prefix ?? "").disable;
+    throw new FlagError(name, `${name} leaves no rule to run; disable fewer categories`);
+  }
   return {
     rules: active,
     fixOrder: fixOrder.filter((r) => !off.has(r.id)),
@@ -2023,7 +2050,7 @@ import { parseArgs } from "node:util";
 // package.json
 var package_default = {
   name: "@jpeakai/mermaidjs-lint",
-  version: "0.6.3",
+  version: "0.7.1",
   type: "module",
   description: "Deterministic lint gates and verified fixers for Mermaid diagrams in markdown",
   license: "MIT",
@@ -2792,7 +2819,8 @@ var setUp = async ({
   configPath,
   noPlugins = false,
   lenient = false,
-  collect = false
+  collect = false,
+  selection
 }) => {
   const root = await findProjectRoot(cwd);
   let file;
@@ -2820,7 +2848,8 @@ var setUp = async ({
     categories: plugins.categories,
     sources: plugins.sources,
     config,
-    ignoreUnknownPluginIds: mode !== "strict"
+    ignoreUnknownPluginIds: mode !== "strict",
+    ...selection && { selection }
   });
   return { root, registry, skipped: plugins.skipped, failures: plugins.failures };
 };
@@ -2828,7 +2857,8 @@ var setUp = async ({
 // src/cli.ts
 var SYNOPSIS = `usage: mermaidjs-lint <path...> [--fix] [--json] [--preset NAME] [--profile NAME] [--config FILE]
                      [--canvas-light COLOUR] [--canvas-dark COLOUR] [--no-plugins | --lenient-plugins]
-       mermaidjs-lint --list-rules [--config FILE] [--no-plugins | --lenient-plugins]
+                     [--category NAME]... [--disable-category NAME]...
+       mermaidjs-lint --list-rules [--config FILE] [--no-plugins | --lenient-plugins] [category flags]
        mermaidjs-lint --validate-plugins [--json] [--config FILE]
        mermaidjs-lint --version | -h, --help`;
 var ruleRow = (r, width) => `${`${r.id}${r.fix ? "*" : ""}`.padEnd(width)}  ${r.summary}`;
@@ -2858,6 +2888,10 @@ Examples of every rule, with fixes: https://jpeakai.github.io/jpai-mermaidjs-lin
   on it. Each is an opaque CSS colour such as #faf8f9, and a side not given keeps the config's, or GitHub's
   (#ffffff light, #0d1117 dark). A file scored under mkdocs-material refuses a canvas flag with a usage
   error, and sets a config canvas aside when auto picked the profile.
+--disable-category NAME turns off every rule in that category for this run, after the config is applied.
+--category NAME turns on every rule in that category for this run, even one the config turns off.
+  Each may be repeated or take a comma-separated list, such as --disable-category parse,complexity.
+  A category that is not loaded, one named by both flags, or a run left with no rule is a usage error.
 --json prints one JSON object instead of text lines.
 --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.
@@ -2869,7 +2903,7 @@ Plugins load on their own from .mermaidjs-lint/rules, from dependencies named me
 --lenient-plugins skips a plugin that fails to load and says so, instead of stopping the run.
 --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, and takes no path or other flag.
+  It imports the plugins to list them. It takes the category flags, to preview a run, and no path or other flag.
 --version prints the version, to quote in a bug report.
 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.`;
@@ -2888,11 +2922,19 @@ var parse2 = (argv) => parseArgs({
     "lenient-plugins": { type: "boolean", default: false },
     "validate-plugins": { type: "boolean", default: false },
     "list-rules": { type: "boolean", default: false },
-    version: { type: "boolean", default: false }
+    version: { type: "boolean", default: false },
+    category: { type: "string", multiple: true },
+    "disable-category": { type: "string", multiple: true }
   },
   allowPositionals: true,
   strict: true
 });
+var categoryWords = (flag, values) => (values ?? []).flatMap((value) => value.split(",").map((word) => {
+  const trimmed = word.trim();
+  if (!trimmed)
+    throw new FlagError(flag, `${flag} needs a category name, not "${value}"`);
+  return trimmed;
+}));
 var plural = (n, word) => `${n} ${word}${n === 1 ? "" : "s"}`;
 var namesOf = (sources) => sources.map((s) => `${s.namespace} (${plural(s.rules.length, "rule")})`).join(", ");
 var loadedLine = (sources, skipped) => {
@@ -3004,6 +3046,11 @@ var run = async (argv, cwd) => {
   if (validating && (values["no-plugins"] || values.fix || listing)) {
     throw new FlagError("--validate-plugins", "--validate-plugins takes no --no-plugins, --fix or --list-rules");
   }
+  const enable = categoryWords("--category", values.category);
+  const disable = categoryWords("--disable-category", values["disable-category"]);
+  if (validating && enable.length + disable.length > 0) {
+    throw new FlagError("--validate-plugins", "--validate-plugins checks every plugin, so it takes no category flag");
+  }
   if (listing && !validating) {
     const ignored = [
       ...["fix", "json", "preset", "profile", "canvas-light", "canvas-dark"].filter((name) => values[name] !== undefined && values[name] !== false).map((name) => `--${name}`),
@@ -3023,7 +3070,8 @@ var run = async (argv, cwd) => {
     configPath: values.config,
     noPlugins: values["no-plugins"],
     lenient: values["lenient-plugins"],
-    collect: validating
+    collect: validating,
+    selection: { enable, disable, prefix: "--" }
   });
   if (validating) {
     const result = validate(registry, failures, Boolean(values.json));

package/dist/testing.js

@@ -1755,6 +1755,22 @@ var BUILTIN_CATEGORIES = new Map([
   ["contrast", "Whether labels and borders can be read against their fills"]
 ]);
 var HELPERS = { detectKeyword, wcagRatio, compositeOver };
+var selectionNames = (prefix) => prefix ? { enable: `${prefix}category`, disable: `${prefix}disable-category` } : { enable: "selection.enable", disable: "selection.disable" };
+var checkSelection = (selection, categories) => {
+  const names = selectionNames(selection.prefix ?? "");
+  const known = [...categories.keys()];
+  for (const side of ["enable", "disable"]) {
+    for (const word of selection[side] ?? []) {
+      if (!categories.has(word)) {
+        throw new FlagError(names[side], `${names[side]} names no loaded category "${word}"; the categories are ${known.join(", ")}`);
+      }
+    }
+  }
+  const both = (selection.enable ?? []).filter((word) => selection.disable?.includes(word));
+  if (both.length > 0) {
+    throw new FlagError(names.disable, `${names.enable} and ${names.disable} both name ${[...new Set(both)].join(", ")}; name each category once`);
+  }
+};
 var typeOf = (value) => {
   if (typeof value === "number" && Number.isFinite(value))
     return "number";
@@ -1811,6 +1827,8 @@ var checkOptions = (where, rule, options) => {
 };
 var buildRegistry = (input) => {
   const { rules, fixOrder, categories, sources = [], config, ignoreUnknownPluginIds = false } = input;
+  const selection = input.selection ?? {};
+  checkSelection(selection, categories);
   const off = new Set;
   const options = new Map;
   const ignored = [];
@@ -1825,12 +1843,21 @@ var buildRegistry = (input) => {
       throw new UnknownRuleError(where, id, rules.map((r) => r.id));
     }
     checkOptions(where, rule, setting.options);
+    options.set(rule.id, setting.options);
     if (setting.severity === "off")
       off.add(id);
-    else
-      options.set(rule.id, setting.options);
+  }
+  for (const rule of rules) {
+    if (selection.enable?.includes(rule.category))
+      off.delete(rule.id);
+    if (selection.disable?.includes(rule.category))
+      off.add(rule.id);
   }
   const active = rules.filter((r) => !off.has(r.id));
+  if (active.length === 0 && (selection.disable?.length ?? 0) > 0) {
+    const name = selectionNames(selection.prefix ?? "").disable;
+    throw new FlagError(name, `${name} leaves no rule to run; disable fewer categories`);
+  }
   return {
     rules: active,
     fixOrder: fixOrder.filter((r) => !off.has(r.id)),

package/dist/types/index.d.ts

@@ -14,6 +14,6 @@ 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, BUILTIN_CATEGORIES, buildRegistry, type LoadedSource, type Registry, type RegistryInput, } from "./rules/registry.ts";
+export { BUILTIN, BUILTIN_CATEGORIES, buildRegistry, type CategorySelection, type LoadedSource, type Registry, type RegistryInput, } from "./rules/registry.ts";
 export type { Category, CheckContext, CoreRuleId, Edit, Expectation, Finding, FixContext, Helpers, OptionSpec, OptionType, PluginRuleId, Rule, RuleContext, RuleId, RuleOptions, } from "./rules/types.ts";
 export { CATEGORIES, RULE } from "./rules/types.ts";

package/dist/types/project.d.ts

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

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

@@ -24,6 +24,12 @@ export interface RegistryInput {
     sources?: LoadedSource[];
     config?: Config;
     ignoreUnknownPluginIds?: boolean;
+    selection?: CategorySelection;
+}
+export interface CategorySelection {
+    enable?: readonly string[];
+    disable?: readonly string[];
+    prefix?: string;
 }
 export declare const buildRegistry: (input: RegistryInput) => Registry;
 export declare const BUILTIN: Registry;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jpeakai/mermaidjs-lint",
-  "version": "0.6.3",
+  "version": "0.7.1",
   "type": "module",
   "description": "Deterministic lint gates and verified fixers for Mermaid diagrams in markdown",
   "license": "MIT",

package/src/cli.ts

@@ -22,7 +22,8 @@ import { CATEGORIES, type Finding, type Rule } from "./rules/types.ts";
 // buried, and first in --help.
 const SYNOPSIS = `usage: mermaidjs-lint <path...> [--fix] [--json] [--preset NAME] [--profile NAME] [--config FILE]
                      [--canvas-light COLOUR] [--canvas-dark COLOUR] [--no-plugins | --lenient-plugins]
-       mermaidjs-lint --list-rules [--config FILE] [--no-plugins | --lenient-plugins]
+                     [--category NAME]... [--disable-category NAME]...
+       mermaidjs-lint --list-rules [--config FILE] [--no-plugins | --lenient-plugins] [category flags]
        mermaidjs-lint --validate-plugins [--json] [--config FILE]
        mermaidjs-lint --version | -h, --help`;
 
@@ -57,6 +58,10 @@ Examples of every rule, with fixes: https://jpeakai.github.io/jpai-mermaidjs-lin
   on it. Each is an opaque CSS colour such as #faf8f9, and a side not given keeps the config's, or GitHub's
   (#ffffff light, #0d1117 dark). A file scored under mkdocs-material refuses a canvas flag with a usage
   error, and sets a config canvas aside when auto picked the profile.
+--disable-category NAME turns off every rule in that category for this run, after the config is applied.
+--category NAME turns on every rule in that category for this run, even one the config turns off.
+  Each may be repeated or take a comma-separated list, such as --disable-category parse,complexity.
+  A category that is not loaded, one named by both flags, or a run left with no rule is a usage error.
 --json prints one JSON object instead of text lines.
 --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.
@@ -68,7 +73,7 @@ Plugins load on their own from .mermaidjs-lint/rules, from dependencies named me
 --lenient-plugins skips a plugin that fails to load and says so, instead of stopping the run.
 --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, and takes no path or other flag.
+  It imports the plugins to list them. It takes the category flags, to preview a run, and no path or other flag.
 --version prints the version, to quote in a bug report.
 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.`;
@@ -88,6 +93,8 @@ interface Parsed {
     "validate-plugins"?: boolean;
     "list-rules"?: boolean;
     version?: boolean;
+    category?: string[];
+    "disable-category"?: string[];
   };
   positionals: string[];
 }
@@ -109,11 +116,25 @@ const parse = (argv: string[]): Parsed =>
       "validate-plugins": { type: "boolean", default: false },
       "list-rules": { type: "boolean", default: false },
       version: { type: "boolean", default: false },
+      category: { type: "string", multiple: true },
+      "disable-category": { type: "string", multiple: true },
     },
     allowPositionals: true,
     strict: true,
   });
 
+// A category flag may be repeated or take a comma-separated list. A category
+// word never holds a comma, so the split cannot change a name. An empty item,
+// as in "parse,", is refused rather than dropped.
+const categoryWords = (flag: string, values: string[] | undefined): string[] =>
+  (values ?? []).flatMap((value) =>
+    value.split(",").map((word) => {
+      const trimmed = word.trim();
+      if (!trimmed) throw new FlagError(flag, `${flag} needs a category name, not "${value}"`);
+      return trimmed;
+    }),
+  );
+
 const plural = (n: number, word: string): string => `${n} ${word}${n === 1 ? "" : "s"}`;
 
 const namesOf = (sources: LoadedSource[]): string =>
@@ -246,6 +267,13 @@ const run = async (argv: string[], cwd: string): Promise<number> => {
   if (validating && (values["no-plugins"] || values.fix || listing)) {
     throw new FlagError("--validate-plugins", "--validate-plugins takes no --no-plugins, --fix or --list-rules");
   }
+  const enable = categoryWords("--category", values.category);
+  const disable = categoryWords("--disable-category", values["disable-category"]);
+  // Validation loads every plugin whatever the category flags say, so it
+  // refuses them rather than ignore them.
+  if (validating && enable.length + disable.length > 0) {
+    throw new FlagError("--validate-plugins", "--validate-plugins checks every plugin, so it takes no category flag");
+  }
   // --list-rules prints the rules the config and the plugin flags leave
   // active. Any other flag or a path would be silently ignored, so it is refused.
   if (listing && !validating) {
@@ -273,6 +301,7 @@ const run = async (argv: string[], cwd: string): Promise<number> => {
     noPlugins: values["no-plugins"],
     lenient: values["lenient-plugins"],
     collect: validating,
+    selection: { enable, disable, prefix: "--" },
   });
 
   if (validating) {

package/src/index.ts

@@ -20,6 +20,7 @@ export {
   BUILTIN,
   BUILTIN_CATEGORIES,
   buildRegistry,
+  type CategorySelection,
   type LoadedSource,
   type Registry,
   type RegistryInput,

package/src/project.ts

@@ -9,7 +9,7 @@ import { CONFIG_FILES, findConfig, loadConfig, NO_CONFIG } from "./config.ts";
 import { ConfigCodeError, ConfigNotFoundError } from "./errors.ts";
 import { loadPlugins, type PluginFailure, type PluginMode } from "./plugins/index.ts";
 import { FIX_ORDER, RULES } from "./rules/index.ts";
-import { buildRegistry, type Registry } from "./rules/registry.ts";
+import { buildRegistry, type CategorySelection, type Registry } from "./rules/registry.ts";
 
 export const LOCAL_DIR = ".mermaidjs-lint";
 
@@ -40,6 +40,8 @@ export interface SetupOptions {
   lenient?: boolean;
   // Load every plugin and report every failure, without stopping at the first.
   collect?: boolean;
+  // Categories switched on or off for this run, over the config.
+  selection?: CategorySelection;
 }
 
 export interface Setup {
@@ -57,6 +59,7 @@ export const setUp = async ({
   noPlugins = false,
   lenient = false,
   collect = false,
+  selection,
 }: SetupOptions): Promise<Setup> => {
   const root = await findProjectRoot(cwd);
   let file: string | null;
@@ -85,6 +88,7 @@ export const setUp = async ({
     // by choice (off) or by failure (lenient, collect), so it is set aside
     // rather than failing the run. A built-in id never is.
     ignoreUnknownPluginIds: mode !== "strict",
+    ...(selection && { selection }),
   });
   return { root, registry, skipped: plugins.skipped, failures: plugins.failures };
 };

package/src/rules/registry.ts

@@ -1,11 +1,11 @@
 // The registry: the rules a run actually uses. It starts from the built-in
-// catalogue, adds whatever plugins loaded, then applies the config, so a rule
-// that is off loses its check and its fixer together. Every check and fix reads
+// catalogue, adds whatever plugins loaded, applies the config, then the run's
+// category choice, so a rule that is off loses its check and its fixer together. Every check and fix reads
 // the registry, which is what lets a plugin rule behave as a built-in. The CLI
 // help reads the built-in catalogue directly.
 
 import type { Config } from "../config.ts";
-import { RuleOptionError, UnknownRuleError } from "../errors.ts";
+import { FlagError, RuleOptionError, UnknownRuleError } from "../errors.ts";
 import { compositeOver, wcagRatio } from "../parse/color.ts";
 import { canvasColourProblem, PROFILES, THEMES, type Theme } from "../parse/contrast.ts";
 import { canonicalPreset } from "../parse/metrics.ts";
@@ -49,8 +49,49 @@ export interface RegistryInput {
   // A lenient or collect (validating) run drops a setting for an unloaded
   // plugin rule instead of failing. A built-in id always fails.
   ignoreUnknownPluginIds?: boolean;
+  // Categories switched on or off for this run, over the config.
+  selection?: CategorySelection;
 }
 
+// The run's category choice. `enable` turns a category's rules on even when
+// the config turns them off, and `disable` turns them off. `prefix` is "--"
+// when the command passes its flags, so a message names the flag the user typed.
+export interface CategorySelection {
+  enable?: readonly string[];
+  disable?: readonly string[];
+  prefix?: string;
+}
+
+const selectionNames = (prefix: string): { enable: string; disable: string } =>
+  prefix
+    ? { enable: `${prefix}category`, disable: `${prefix}disable-category` }
+    : { enable: "selection.enable", disable: "selection.disable" };
+
+// A category the run does not know, or one named both on and off, is a usage
+// error, because either would leave the run checking something other than
+// what was asked.
+const checkSelection = (selection: CategorySelection, categories: ReadonlyMap<string, string>): void => {
+  const names = selectionNames(selection.prefix ?? "");
+  const known = [...categories.keys()];
+  for (const side of ["enable", "disable"] as const) {
+    for (const word of selection[side] ?? []) {
+      if (!categories.has(word)) {
+        throw new FlagError(
+          names[side],
+          `${names[side]} names no loaded category "${word}"; the categories are ${known.join(", ")}`,
+        );
+      }
+    }
+  }
+  const both = (selection.enable ?? []).filter((word) => selection.disable?.includes(word));
+  if (both.length > 0) {
+    throw new FlagError(
+      names.disable,
+      `${names.enable} and ${names.disable} both name ${[...new Set(both)].join(", ")}; name each category once`,
+    );
+  }
+};
+
 const typeOf = (value: unknown): OptionType | null => {
   if (typeof value === "number" && Number.isFinite(value)) return "number";
   if (typeof value === "string") return "string";
@@ -123,6 +164,8 @@ const checkOptions = (where: string, rule: Rule, options: RuleOptions): void =>
 
 export const buildRegistry = (input: RegistryInput): Registry => {
   const { rules, fixOrder, categories, sources = [], config, ignoreUnknownPluginIds = false } = input;
+  const selection = input.selection ?? {};
+  checkSelection(selection, categories);
   const off = new Set<string>();
   const options = new Map<RuleId, RuleOptions>();
   const ignored: string[] = [];
@@ -144,10 +187,23 @@ export const buildRegistry = (input: RegistryInput): Registry => {
       );
     }
     checkOptions(where, rule, setting.options);
+    // A rule that is off keeps its options, so a category flag that turns it
+    // back on runs it as the config describes it.
+    options.set(rule.id, setting.options);
     if (setting.severity === "off") off.add(id);
-    else options.set(rule.id, setting.options);
+  }
+  // Every rule starts on, the config turns some off, and then the category
+  // flags have the last word for this run (MJL-0020).
+  for (const rule of rules) {
+    if (selection.enable?.includes(rule.category)) off.delete(rule.id);
+    if (selection.disable?.includes(rule.category)) off.add(rule.id);
   }
   const active = rules.filter((r) => !off.has(r.id));
+  // Category flags that leave nothing to run would pass every file unchecked.
+  if (active.length === 0 && (selection.disable?.length ?? 0) > 0) {
+    const name = selectionNames(selection.prefix ?? "").disable;
+    throw new FlagError(name, `${name} leaves no rule to run; disable fewer categories`);
+  }
   return {
     rules: active,
     fixOrder: fixOrder.filter((r) => !off.has(r.id)),