@jpeakai/prose-gates 0.1.1 → 0.2.0

package/src/fix/verify.ts

@@ -5,6 +5,7 @@
 
 import type { Node, Parent, Root } from "mdast";
 import { visitParents as visit } from "unist-util-visit-parents";
+import { parse as parseYaml } from "yaml";
 import { parse } from "../model.ts";
 import type { Edit } from "../rules/types.ts";
 
@@ -105,6 +106,26 @@ const fragmentShapeOk = (nodes: Node[], listItems: number): boolean => {
   return items.length === listItems && items.every((i) => i.children[0]?.type === "paragraph");
 };
 
+const INVALID = Symbol("invalid frontmatter");
+
+// What the leading YAML block means: its data as the yaml package reads it, so a
+// rewrite that only changes how the data is written compares equal. Absent
+// frontmatter is `undefined`, and a block that does not parse is INVALID.
+const frontmatterData = (tree: Root): unknown => {
+  const first = tree.children[0];
+  if (first?.type !== "yaml") return undefined;
+  try {
+    return parseYaml(first.value);
+  } catch {
+    return INVALID;
+  }
+};
+
+// The tree with its leading frontmatter node taken off, so everything else can
+// be compared on its own.
+const withoutFrontmatter = (tree: Root): Root =>
+  tree.children[0]?.type === "yaml" ? { ...tree, children: tree.children.slice(1) } : tree;
+
 export type Verdict = "accept" | "refuse";
 
 export const verify = (edit: Edit, before: { src: string; tree: Root }, afterTree: Root): Verdict => {
@@ -122,6 +143,14 @@ export const verify = (edit: Edit, before: { src: string; tree: Root }, afterTre
   if (expect.kind === "same-tree") {
     return sameJson(normalise(before.tree), normalise(afterTree)) ? "accept" : "refuse";
   }
+  if (expect.kind === "same-frontmatter-data") {
+    const was = frontmatterData(before.tree);
+    const now = frontmatterData(afterTree);
+    if (was === INVALID || now === INVALID || !sameJson(was, now)) return "refuse";
+    return sameJson(normalise(withoutFrontmatter(before.tree)), normalise(withoutFrontmatter(afterTree)))
+      ? "accept"
+      : "refuse";
+  }
   if (expect.kind === "same-shape") {
     return sameJson(normalise(before.tree, { blankText: true }), normalise(afterTree, { blankText: true }))
       ? "accept"

package/src/index.ts

@@ -2,9 +2,45 @@
 
 export { checkMarkdown, checkModel, DEFAULT_MAX_WORDS } from "./check.ts";
 export { main } from "./cli.ts";
+export { type Config, loadConfig, type PluginLoading, parseConfig, type RuleSetting, type Severity } from "./config.ts";
+export * from "./errors.ts";
 export { type FixReport, fixMarkdown, fixMarkdownReport } from "./fix/engine.ts";
 export { FixInvariantError } from "./fix/verify.ts";
-export { buildDocModel, type DocModel } from "./model.ts";
+export {
+  buildDocModel,
+  type DocModel,
+  type FrontmatterEntry,
+  type FrontmatterScalar,
+  type FrontmatterView,
+  type ScalarStyle,
+} from "./model.ts";
+export type { Plugin, PluginEdit, PluginFinding, PluginMeta, PluginRule } from "./plugins/contract.ts";
+export { findProjectRoot, setUp } from "./project.ts";
 export { FIX_ORDER, RULES } from "./rules/index.ts";
-export type { Category, Edit, Finding, Rule, RuleId } from "./rules/types.ts";
+export {
+  BUILTIN,
+  BUILTIN_CATEGORIES,
+  buildRegistry,
+  type LoadedSource,
+  type Registry,
+  type RegistryInput,
+} from "./rules/registry.ts";
+export type {
+  Category,
+  CheckContext,
+  CoreRuleId,
+  Edit,
+  Expectation,
+  Finding,
+  FixContext,
+  OptionSpec,
+  OptionType,
+  PluginRuleId,
+  Rule,
+  RuleContext,
+  RuleId,
+  RuleOptions,
+  TextHelpers,
+} from "./rules/types.ts";
 export { CATEGORIES, RULE } from "./rules/types.ts";
+export { sentences, words } from "./text.ts";

package/src/interpunct.ts

@@ -0,0 +1,48 @@
+// The interpunct run: the one piece of data derived from a whole document
+// that more than one rule reads. list-interpunct-joined-run and list-stacked-interpunct-runs report a run, punctuation-interpunct-in-prose stays
+// quiet inside one, and sentence-one-per-line leaves a stacked one unreflowed, so it is
+// derived once per document and handed to every rule as data.
+
+import type { DocModel, ParagraphView } from "./model.ts";
+import { proseParagraphs } from "./query.ts";
+import { countOf, type Range } from "./text.ts";
+
+export const INTERPUNCT = "·";
+
+// The glyph on its own, for counting, and the glyph with the space a run
+// puts around it, for splitting. list-interpunct-joined-run and list-stacked-interpunct-runs both cut on the separator;
+// punctuation-interpunct-in-prose is stricter and needs space on both sides, so it keeps its own.
+export const GLYPH = /·/g;
+export const RUN_SEPARATOR = /[ \t]*·[ \t]*/;
+
+// A paragraph whose prose joins a run of items with 2+ interpunct separators.
+export interface InterpunctRun {
+  range: Range;
+  line: number;
+  separators: number;
+  lines: number; // source lines of the paragraph that carry a separator
+}
+
+export const interpunctRuns = (doc: DocModel): InterpunctRun[] => {
+  const runs: InterpunctRun[] = [];
+  for (const view of proseParagraphs(doc)) {
+    const separators = countOf(view.prose, GLYPH);
+    if (separators < 2) continue;
+    const lines = view.raw.split("\n").filter((line) => line.includes(INTERPUNCT)).length;
+    runs.push({ range: [view.startOffset, view.endOffset], line: view.line, separators, lines });
+  }
+  return runs;
+};
+
+// A run on one source line is a flat list, which list-interpunct-joined-run owns. A run spread
+// over two or more lines is a two-level structure, which list-stacked-interpunct-runs owns and
+// sentence-one-per-line leaves unreflowed. The two predicates partition every run.
+export const isFlat = (run: InterpunctRun): boolean => run.lines === 1;
+
+export const isStacked = (run: InterpunctRun): boolean => run.lines >= 2;
+
+// The paragraphs those runs were derived from. A run is keyed by the
+// paragraph it spans, so this is how a rule gets from the runs it was handed
+// back to the views its fixer needs.
+export const paragraphsOf = (doc: DocModel, runs: InterpunctRun[]): ParagraphView[] =>
+  doc.paragraphs.filter((view) => runs.some((run) => run.range[0] === view.startOffset));

package/src/model.ts

@@ -9,6 +9,8 @@ import { gfmFromMarkdown } from "mdast-util-gfm";
 import { frontmatter } from "micromark-extension-frontmatter";
 import { gfm } from "micromark-extension-gfm";
 import { visitParents } from "unist-util-visit-parents";
+import { type Document, isMap, isPair, isScalar, isSeq, LineCounter, parseDocument, type Scalar } from "yaml";
+import type { Range } from "./text.ts";
 
 // Fenced blocks in these languages hold markdown templates (a conventions or
 // skeleton file shown verbatim): their prose is audited as embedded markdown
@@ -16,8 +18,6 @@ import { visitParents } from "unist-util-visit-parents";
 // fence boundary.
 const MARKDOWN_FENCE_LANGS = new Set(["markdown", "md"]);
 
-export type Range = [number, number];
-
 // A text node that is a direct child of its paragraph. Only these carry
 // separators a fixer may split on: text inside a link, emphasis or code is
 // cargo and moves whole.
@@ -48,7 +48,6 @@ export interface ParagraphView {
 export interface TextView {
   value: string;
   line: number;
-  offset: number | undefined;
   start: number | undefined;
   end: number | undefined;
   block: Node | undefined; // nearest paragraph, heading or table cell
@@ -61,12 +60,58 @@ export interface FenceView {
   line: number; // line of the opening fence
 }
 
+// One top-level key of the frontmatter whose value is a string.
+export interface FrontmatterEntry {
+  key: string;
+  value: string; // the scalar as text, folded lines joined
+  line: number; // file line where the value starts
+  start: number; // source offsets of the value, quotes included
+  end: number;
+}
+
+// How a YAML string is written, which a fixer needs to rewrite it safely.
+export type ScalarStyle = "plain" | "double" | "single" | "literal" | "folded";
+
+// A string value anywhere in the frontmatter, found by walking the whole YAML
+// document in order. A value in a nested map or a list is here too, with the
+// path that leads to it.
+export interface FrontmatterScalar {
+  path: (string | number)[]; // keys and list indexes from the document root
+  key: string | null; // the nearest map key above it, at any depth
+  keyLine: number | null; // file line of that key
+  value: string; // the string as YAML reads it
+  line: number; // file line where the value starts
+  start: number; // absolute source offsets of the value, quotes included
+  end: number;
+  style: ScalarStyle;
+  indent: number; // leading spaces of the line the key, or the value, sits on
+  node: Scalar; // the yaml package node, for anything this view does not carry
+}
+
+export interface FrontmatterView {
+  format: "yaml";
+  // The top-level string entries, kept for the common flat case.
+  entries: FrontmatterEntry[];
+  // Every string scalar at any depth, in document order.
+  scalars: FrontmatterScalar[];
+  // The whole parsed document, from the yaml package, for full traversal.
+  document: Document.Parsed;
+  // Absolute offset in `src` where the YAML text starts, so a node range from
+  // `document` maps to the source as offset + range.
+  offset: number;
+  // The file line of an absolute source offset inside the block.
+  lineOf: (absoluteOffset: number) => number;
+}
+
 export interface DocModel {
   src: string;
   tree: Root;
   paragraphs: ParagraphView[];
   texts: TextView[]; // every prose text node, including headings and lists
   fences: FenceView[]; // embedded-markdown fences, audited recursively
+  // The leading YAML block as keys and values, read on first use so a document
+  // whose frontmatter is not valid YAML only fails the rules that ask for it.
+  readonly frontmatter: FrontmatterView | null;
 }
 
 export const parse = (src: string): Root =>
@@ -128,7 +173,6 @@ export const buildDocModel = (src: string): DocModel => {
       texts.push({
         value: t.value,
         line: t.position?.start.line ?? 0,
-        offset: start,
         start,
         end,
         block: ancestors.findLast((a) => a.type === "paragraph" || a.type === "heading" || a.type === "tableCell"),
@@ -152,14 +196,87 @@ export const buildDocModel = (src: string): DocModel => {
     const view = viewOf.get(p);
     if (view) view.prose = parts.join(" ").replace(/\s+/g, " ").trim();
   }
-  return { src, tree, paragraphs, texts, fences };
+  let frontmatter: FrontmatterView | null | undefined;
+  return {
+    src,
+    tree,
+    paragraphs,
+    texts,
+    fences,
+    get frontmatter() {
+      frontmatter ??= readFrontmatter(src, tree);
+      return frontmatter;
+    },
+  };
 };
 
-export const inRanges = (offset: number, ranges: Range[]): boolean =>
-  ranges.some(([a, b]) => offset >= a && offset < b);
+const STYLES: Record<string, ScalarStyle> = {
+  PLAIN: "plain",
+  QUOTE_DOUBLE: "double",
+  QUOTE_SINGLE: "single",
+  BLOCK_LITERAL: "literal",
+  BLOCK_FOLDED: "folded",
+};
+
+// A leading YAML block as a whole document, plus the string scalars found by
+// walking all of it. Only the first node of the tree can be frontmatter, and
+// TOML is not read. A value that is not a string is left out of `scalars`
+// rather than guessed at, and an alias is not followed. Invalid YAML throws with
+// the line, so a rule that needs the keys cannot run on a block it could not read.
+const readFrontmatter = (src: string, tree: Root): FrontmatterView | null => {
+  const node = tree.children[0];
+  const offset = node?.position?.start.offset;
+  if (node?.type !== "yaml" || offset == null || !node.position) return null;
+  const opening = node.position.start;
+  const contentStart = offset + src.slice(offset).indexOf("\n") + 1;
+  const lines = new LineCounter();
+  const doc = parseDocument(node.value, { lineCounter: lines });
+  const [problem] = doc.errors;
+  if (problem) {
+    const line = opening.line + (problem.linePos?.[0].line ?? 1);
+    throw new Error(`frontmatter YAML error at line ${line}: ${problem.message.split("\n")[0]}`);
+  }
+  const lineOf = (absolute: number): number => opening.line + lines.linePos(absolute - contentStart).line;
+  const indentOf = (relative: number): number => {
+    const lineStart = node.value.lastIndexOf("\n", relative - 1) + 1;
+    return /^ */.exec(node.value.slice(lineStart))?.[0].length ?? 0;
+  };
 
-export const sentences = (text: string): string[] =>
-  text
-    .split(/(?<=[.!?])\s+/)
-    .map((s) => s.trim())
-    .filter((s) => s.length > 0);
+  const scalars: FrontmatterScalar[] = [];
+  const walk = (value: unknown, path: (string | number)[], key: Scalar | null): void => {
+    if (isScalar(value)) {
+      if (typeof value.value !== "string" || !value.range) return;
+      const [from, to] = value.range;
+      const anchor = key?.range ? key.range[0] : from;
+      scalars.push({
+        path,
+        key: key && typeof key.value === "string" ? key.value : null,
+        keyLine: key?.range ? lineOf(contentStart + key.range[0]) : null,
+        value: value.value,
+        line: lineOf(contentStart + from),
+        start: contentStart + from,
+        end: contentStart + to,
+        style: STYLES[value.type ?? "PLAIN"] ?? "plain",
+        indent: indentOf(anchor),
+        node: value,
+      });
+    } else if (isMap(value)) {
+      for (const pair of value.items) {
+        if (!isPair(pair)) continue;
+        const k = isScalar(pair.key) ? pair.key : null;
+        const name = k ? String(k.value) : "";
+        walk(pair.value, [...path, name], k);
+      }
+    } else if (isSeq(value)) {
+      value.items.forEach((item, i) => {
+        walk(item, [...path, i], key);
+      });
+    }
+  };
+  walk(doc.contents, [], null);
+
+  const entries: FrontmatterEntry[] = scalars
+    .filter((s) => s.path.length === 1 && typeof s.path[0] === "string")
+    .map((s) => ({ key: s.path[0] as string, value: s.value, line: s.line, start: s.start, end: s.end }));
+  return { format: "yaml", entries, scalars, document: doc, offset: contentStart, lineOf };
+};

package/src/plugins/contract.ts

@@ -0,0 +1,41 @@
+// What a plugin is: an ES module whose default export is a Plugin, or, for a
+// local rule, one PluginRule per file. The context a plugin rule receives is
+// the one the built-ins read, so a plugin rule is a built-in with a namespace.
+
+import type { Awaitable, CheckContext, Edit, Finding, FixContext, OptionSpec } from "../rules/types.ts";
+
+// Bumped when the contract changes in a way a plugin must notice. A plugin
+// that targets another version fails to load with both numbers in the message.
+export const API_VERSION = 1;
+
+// What a plugin returns. The engine adds the rule id and the file to a finding,
+// and the rule id to an edit, so a plugin cannot report as another rule.
+export type PluginFinding = Pick<Finding, "line" | "message">;
+
+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;
+  // A new category the plugin adds, as the word and a one-line description.
+  categories?: Record<string, string>;
+}
+
+export interface Plugin {
+  meta: PluginMeta;
+  rules: Record<string, PluginRule>;
+}
+
+// A one-word category and a namespace or rule key, as they appear in an id.
+export const CATEGORY_WORD = /^[a-z]+$/;
+export const NAMESPACE = /^[a-z][a-z0-9-]*$/;
+export const RULE_KEY = /^[a-z][a-z0-9-]*$/;

package/src/plugins/discover.ts

@@ -0,0 +1,140 @@
+// Discovery: which plugin sources a project has. Three places, in this order:
+// local rule files in .prose-gates/rules, packages the project declares as
+// dependencies and whose name matches the plugin pattern, and the paths or
+// names a config lists. A directory of node_modules is never scanned, so only
+// what the project chose to depend on can run.
+//
+// A source that cannot be resolved is a failure the caller decides how to
+// treat, not an exception, so a lenient run can skip it and a validating run
+// can report every one.
+
+import { readdir, readFile } from "node:fs/promises";
+import { dirname, extname, isAbsolute, join, resolve } from "node:path";
+import type { Config } from "../config.ts";
+import { PluginNotInstalledError } from "../errors.ts";
+
+export type SourceKind = "local" | "package" | "config";
+
+export interface PluginSource {
+  kind: SourceKind;
+  // What the user would recognise: a package name or a path under the root.
+  spec: string;
+  // The file to import.
+  path: string;
+}
+
+export interface Discovery {
+  sources: PluginSource[];
+  // Sources found but not resolvable, such as a declared package that is not installed.
+  failures: PluginNotInstalledError[];
+}
+
+export const LOCAL_RULES = join(".prose-gates", "rules");
+
+// prose-gates-plugin-acme, @acme/prose-gates-plugin-acme or @acme/prose-gates-plugin.
+export const PACKAGE_PATTERN = /^(@[a-z0-9][a-z0-9._-]*\/)?prose-gates-plugin(-[a-z0-9-]+)?$/;
+
+const isRecord = (v: unknown): v is Record<string, unknown> => typeof v === "object" && v !== null && !Array.isArray(v);
+
+const readJson = async (path: string): Promise<Record<string, unknown> | null> => {
+  let text: string;
+  try {
+    text = await readFile(path, "utf8");
+  } catch {
+    return null;
+  }
+  try {
+    const value: unknown = JSON.parse(text);
+    if (isRecord(value)) return value;
+  } catch {
+    // Reported below with the path.
+  }
+  throw new Error(`${path} is not a JSON object`);
+};
+
+// Every extension a local rule may have. Whether the runtime can import a
+// TypeScript one is decided at load, so the reason is a named error.
+const LOCAL_EXTENSIONS = new Set([".js", ".mjs", ".ts", ".mts", ".cts"]);
+
+const localSources = async (root: string): Promise<PluginSource[]> => {
+  const dir = join(root, LOCAL_RULES);
+  let names: string[];
+  try {
+    names = (await readdir(dir)).sort();
+  } catch {
+    return [];
+  }
+  return names
+    .filter((name) => LOCAL_EXTENSIONS.has(extname(name)) && !name.endsWith(".d.ts") && !name.endsWith(".d.mts"))
+    .map((name) => ({ kind: "local", spec: join(LOCAL_RULES, name), path: join(dir, name) }));
+};
+
+// The file Node would import for a package, read from its package.json the
+// way a resolver does: the exports entry, then main, then index.js.
+const pick = (target: unknown): string | null => {
+  if (typeof target === "string") return target;
+  if (Array.isArray(target)) {
+    for (const item of target) {
+      const found = pick(item);
+      if (found) return found;
+    }
+    return null;
+  }
+  if (isRecord(target)) {
+    for (const condition of ["node", "import", "default"]) {
+      if (condition in target) {
+        const found = pick(target[condition]);
+        if (found) return found;
+      }
+    }
+  }
+  return null;
+};
+
+const entryOf = (pkg: Record<string, unknown>): string => {
+  const exported = pkg.exports;
+  const hasMap = isRecord(exported) && Object.keys(exported).some((k) => k.startsWith("."));
+  const main = isRecord(exported) && "." in exported ? exported["."] : hasMap ? null : exported;
+  return pick(main) ?? (typeof pkg.main === "string" ? pkg.main : "index.js");
+};
+
+export const resolvePackage = async (root: string, name: string): Promise<string> => {
+  for (let dir = resolve(root); ; dir = dirname(dir)) {
+    const folder = join(dir, "node_modules", name);
+    const pkg = await readJson(join(folder, "package.json"));
+    if (pkg) return join(folder, entryOf(pkg));
+    if (dirname(dir) === dir) break;
+  }
+  throw new PluginNotInstalledError(name, root);
+};
+
+const declaredPlugins = async (root: string): Promise<string[]> => {
+  const pkg = await readJson(join(root, "package.json"));
+  if (!pkg) return [];
+  const names = ["dependencies", "devDependencies", "optionalDependencies"].flatMap((field) => {
+    const deps = pkg[field];
+    return isRecord(deps) ? Object.keys(deps) : [];
+  });
+  return [...new Set(names)].filter((name) => PACKAGE_PATTERN.test(name)).sort();
+};
+
+export const discoverSources = async (root: string, config: Config): Promise<Discovery> => {
+  const sources = await localSources(root);
+  const failures: PluginNotInstalledError[] = [];
+  const add = async (kind: SourceKind, spec: string, resolveIt: () => Promise<string>): Promise<void> => {
+    try {
+      sources.push({ kind, spec, path: await resolveIt() });
+    } catch (err) {
+      if (!(err instanceof PluginNotInstalledError)) throw err;
+      failures.push(err);
+    }
+  };
+  for (const name of await declaredPlugins(root)) await add("package", name, () => resolvePackage(root, name));
+  for (const spec of config.plugins || []) {
+    const path = spec.startsWith(".") || isAbsolute(spec);
+    await add("config", spec, () => (path ? Promise.resolve(resolve(root, spec)) : resolvePackage(root, spec)));
+  }
+  // A package both declared and listed in the config loads once.
+  const seen = new Set<string>();
+  return { sources: sources.filter((s) => !seen.has(s.path) && seen.add(s.path)), failures };
+};

package/src/plugins/index.ts

@@ -0,0 +1,103 @@
+// Assembling plugins: discover the sources, load each one, and merge their
+// rules and categories into the set the registry is built from. Namespaces and
+// new category words are global, so two plugins cannot share either.
+//
+// How a failed source is treated is the mode. Strict throws the first failure,
+// which is the default. Lenient leaves the failed source out and returns it, so
+// the caller can say so. Collect does the same and is what validation uses, so
+// one run reports every failure. Off loads nothing.
+
+import type { Config } from "../config.ts";
+import { PluginConflictError, PluginLoadError } from "../errors.ts";
+import { BUILTIN_CATEGORIES, type LoadedSource } from "../rules/registry.ts";
+import type { Rule } from "../rules/types.ts";
+import type { Plugin } from "./contract.ts";
+import { discoverSources, LOCAL_RULES, type SourceKind } from "./discover.ts";
+import { loadLocal, loadPackage, toRule } from "./load.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[];
+  // Specs found but not loaded, because the run asked for built-ins only.
+  skipped: string[];
+  // Sources left out because they failed. Always empty in strict mode, which throws.
+  failures: PluginFailure[];
+}
+
+export const loadPlugins = async (root: string, config: Config, mode: PluginMode): Promise<PluginSet> => {
+  const { sources: found, failures: unresolved } = await discoverSources(root, config);
+  const set: PluginSet = {
+    rules: [],
+    categories: new Map(BUILTIN_CATEGORIES),
+    sources: [],
+    skipped: [],
+    failures: [],
+  };
+  if (mode === "off") return { ...set, skipped: [...found.map((s) => s.spec), ...unresolved.map((e) => e.source)] };
+
+  // Strict stops at the first failure. The others record it and carry on.
+  const settle = (error: PluginLoadError, kind: SourceKind): void => {
+    if (mode === "strict") throw error;
+    if (!set.failures.some((f) => f.source === error.source)) set.failures.push({ source: error.source, kind, error });
+  };
+  for (const error of unresolved) settle(error, "package");
+
+  const loaded: { plugin: Plugin; kind: SourceKind; spec: string }[] = [];
+  const locals = found.filter((s) => s.kind === "local");
+  if (locals.length > 0) {
+    const local = await loadLocal(locals);
+    for (const error of local.failures) settle(error, "local");
+    if (local.plugin) loaded.push({ plugin: local.plugin, kind: "local", spec: LOCAL_RULES });
+  }
+  for (const source of found.filter((s) => s.kind !== "local")) {
+    try {
+      loaded.push({ plugin: await loadPackage(source, new Set(["local"])), kind: source.kind, spec: source.spec });
+    } catch (err) {
+      if (!(err instanceof PluginLoadError)) throw err;
+      settle(err, source.kind);
+    }
+  }
+
+  // Namespaces and new categories are global. The first plugin to claim one
+  // keeps it, and a later claimant fails, naming both.
+  const namespaces = new Map<string, string>();
+  const declaredBy = new Map<string, string>();
+  const accepted: typeof loaded = [];
+  for (const entry of loaded) {
+    const { plugin, spec, kind } = entry;
+    const { namespace } = plugin.meta;
+    const words = Object.keys(plugin.meta.categories ?? {});
+    const taken = namespaces.get(namespace);
+    const clash = words.find((w) => declaredBy.has(w));
+    if (taken || clash) {
+      const other = (taken ?? declaredBy.get(clash as string)) as string;
+      const reason = taken
+        ? `namespace "${namespace}" is already used by ${other}`
+        : `category "${clash}" is already declared by ${other}`;
+      settle(new PluginConflictError(spec, other, reason), kind);
+      continue;
+    }
+    namespaces.set(namespace, spec);
+    for (const [word, description] of Object.entries(plugin.meta.categories ?? {})) {
+      declaredBy.set(word, spec);
+      set.categories.set(word, description);
+    }
+    accepted.push(entry);
+  }
+
+  for (const { plugin, kind, spec } of accepted) {
+    const rules = Object.entries(plugin.rules).map(([key, rule]) => toRule(plugin.meta.namespace, key, rule));
+    set.rules.push(...rules);
+    set.sources.push({ kind, spec, namespace: plugin.meta.namespace, rules: rules.map((r) => r.id) });
+  }
+  return set;
+};