@jpeakai/mermaidjs-lint 0.6.3 → 0.7.0

package/README.md

@@ -19,7 +19,6 @@ npx -y @jpeakai/mermaidjs-lint --fix docs/       # apply every fix proven safe,
 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.
 
 [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.

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.0",
   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.0",
   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.0",
   "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)),