@jpeakai/prose-gates 0.2.0 → 0.3.0

package/src/model.ts

@@ -10,6 +10,8 @@ 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 ConceptModel, NO_CONCEPTS } from "./concepts.ts";
+import { type LanguageView, languageOf } from "./language.ts";
 import type { Range } from "./text.ts";
 
 // Fenced blocks in these languages hold markdown templates (a conventions or
@@ -43,6 +45,8 @@ export interface ParagraphView {
   inBlockquote: boolean;
   inListItem: boolean;
   onlyChild: boolean; // the paragraph is its parent's only block
+  // Its sentences, words, tags and lemmas, read from `prose` on first use.
+  readonly language: LanguageView;
 }
 
 export interface TextView {
@@ -109,6 +113,8 @@ export interface DocModel {
   paragraphs: ParagraphView[];
   texts: TextView[]; // every prose text node, including headings and lists
   fences: FenceView[]; // embedded-markdown fences, audited recursively
+  // The project's concepts, which every paragraph's language view names.
+  concepts: ConceptModel;
   // 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;
@@ -123,86 +129,132 @@ export const parse = (src: string): Root =>
     mdastExtensions: [frontmatterFromMarkdown(["yaml", "toml"]), gfmFromMarkdown()],
   });
 
-export const buildDocModel = (src: string): DocModel => {
-  const tree = parse(src);
-  const paragraphs: ParagraphView[] = [];
-  const texts: TextView[] = [];
-  const fences: FenceView[] = [];
-  const viewOf = new Map<Paragraph, ParagraphView>();
-  const proseParts = new Map<Paragraph, string[]>();
+// The views a single walk of the tree fills in, in document order.
+interface WalkState {
+  src: string;
+  paragraphs: ParagraphView[];
+  texts: TextView[];
+  fences: FenceView[];
+  viewOf: Map<Paragraph, ParagraphView>;
+  proseParts: Map<Paragraph, string[]>;
+  concepts: ConceptModel;
+}
+
+// A markdown-tagged fence is kept as a template to audit; any other code is exempt.
+const visitCode = (state: WalkState, c: Code): void => {
+  if (c.lang != null && MARKDOWN_FENCE_LANGS.has(c.lang) && c.position) {
+    state.fences.push({ value: c.value, line: c.position.start.line });
+  }
+};
+
+// A paragraph opens a view that its descendants fill in as the walk reaches them.
+const visitParagraph = (state: WalkState, p: Paragraph, ancestors: Node[]): void => {
+  const pos = p.position;
+  if (!pos || pos.start.offset == null || pos.end.offset == null) return;
+  const parent = ancestors.at(-1) as Parent | undefined;
+  const view: ParagraphView = {
+    node: p,
+    raw: state.src.slice(pos.start.offset, pos.end.offset),
+    line: pos.start.line,
+    startOffset: pos.start.offset,
+    endOffset: pos.end.offset,
+    startColumn: pos.start.column,
+    prose: "",
+    codeRanges: [],
+    directTexts: [],
+    hasBreak: false,
+    inTable: ancestors.some((a) => a.type === "table" || a.type === "tableCell"),
+    inBlockquote: ancestors.some((a) => a.type === "blockquote"),
+    inListItem: ancestors.some((a) => a.type === "listItem"),
+    onlyChild: parent !== undefined && parent.children.length === 1,
+    // Tagging is the slowest step in a check, so it waits for the first read.
+    // By then the walk has joined the prose, which it is built from.
+    get language() {
+      language ??= languageOf(view.prose, state.concepts);
+      return language;
+    },
+  };
+  let language: LanguageView | undefined;
+  state.paragraphs.push(view);
+  state.viewOf.set(p, view);
+  state.proseParts.set(p, []);
+};
+
+// Every text node is prose; one directly under its paragraph is also a split point.
+const visitText = (state: WalkState, t: Text, ancestors: Node[], paragraph: Paragraph | undefined): void => {
+  const start = t.position?.start.offset;
+  const end = t.position?.end.offset;
+  state.texts.push({
+    value: t.value,
+    line: t.position?.start.line ?? 0,
+    start,
+    end,
+    block: ancestors.findLast((a) => a.type === "paragraph" || a.type === "heading" || a.type === "tableCell"),
+  });
+  if (!paragraph) return;
+  state.proseParts.get(paragraph)?.push(t.value);
+  const view = state.viewOf.get(paragraph);
+  if (view && ancestors.at(-1) === paragraph && start != null && end != null) {
+    view.directTexts.push({ value: t.value, start, end });
+  }
+};
+
+// Inline code reads as one CODE token in the prose, and its range is exempt.
+const visitInlineCode = (state: WalkState, c: InlineCode, paragraph: Paragraph, view: ParagraphView): void => {
+  state.proseParts.get(paragraph)?.push("CODE");
+  if (c.position?.start.offset != null && c.position.end.offset != null) {
+    view.codeRanges.push([c.position.start.offset, c.position.end.offset]);
+  }
+};
+
+// Route one node of the walk to the view it feeds.
+const visitNode = (state: WalkState, node: Node, ancestors: Node[]): void => {
+  if (node.type === "code") {
+    visitCode(state, node as Code);
+    return;
+  }
+  if (node.type === "paragraph") {
+    visitParagraph(state, node as Paragraph, ancestors);
+    return;
+  }
+  const paragraph = ancestors.findLast((a): a is Paragraph => a.type === "paragraph");
+  if (node.type === "text") {
+    visitText(state, node as Text, ancestors, paragraph);
+    return;
+  }
+  const view = paragraph ? state.viewOf.get(paragraph) : undefined;
+  if (!(paragraph && view)) return;
+  if (node.type === "inlineCode") visitInlineCode(state, node as InlineCode, paragraph, view);
+  else if (node.type === "break") view.hasBreak = true;
+};
 
+export const buildDocModel = (src: string, concepts: ConceptModel = NO_CONCEPTS): DocModel => {
+  const tree = parse(src);
+  const state: WalkState = {
+    src,
+    paragraphs: [],
+    texts: [],
+    fences: [],
+    viewOf: new Map(),
+    proseParts: new Map(),
+    concepts,
+  };
   visitParents(tree, (node: Node, ancestors: Node[]) => {
-    if (node.type === "code") {
-      const c = node as Code;
-      if (c.lang != null && MARKDOWN_FENCE_LANGS.has(c.lang) && c.position) {
-        fences.push({ value: c.value, line: c.position.start.line });
-      }
-      return;
-    }
-    const parent = ancestors.at(-1) as Parent | undefined;
-    if (node.type === "paragraph") {
-      const p = node as Paragraph;
-      const pos = p.position;
-      if (!pos || pos.start.offset == null || pos.end.offset == null) return;
-      const view: ParagraphView = {
-        node: p,
-        raw: src.slice(pos.start.offset, pos.end.offset),
-        line: pos.start.line,
-        startOffset: pos.start.offset,
-        endOffset: pos.end.offset,
-        startColumn: pos.start.column,
-        prose: "",
-        codeRanges: [],
-        directTexts: [],
-        hasBreak: false,
-        inTable: ancestors.some((a) => a.type === "table" || a.type === "tableCell"),
-        inBlockquote: ancestors.some((a) => a.type === "blockquote"),
-        inListItem: ancestors.some((a) => a.type === "listItem"),
-        onlyChild: parent !== undefined && parent.children.length === 1,
-      };
-      paragraphs.push(view);
-      viewOf.set(p, view);
-      proseParts.set(p, []);
-    }
-    const paragraph = ancestors.findLast((a): a is Paragraph => a.type === "paragraph");
-    const view = paragraph ? viewOf.get(paragraph) : undefined;
-    if (node.type === "text") {
-      const t = node as Text;
-      const start = t.position?.start.offset;
-      const end = t.position?.end.offset;
-      texts.push({
-        value: t.value,
-        line: t.position?.start.line ?? 0,
-        start,
-        end,
-        block: ancestors.findLast((a) => a.type === "paragraph" || a.type === "heading" || a.type === "tableCell"),
-      });
-      if (paragraph) proseParts.get(paragraph)?.push(t.value);
-      if (view && parent === paragraph && start != null && end != null) {
-        view.directTexts.push({ value: t.value, start, end });
-      }
-    } else if (node.type === "inlineCode" && view) {
-      const c = node as InlineCode;
-      proseParts.get(paragraph as Paragraph)?.push("CODE");
-      if (c.position?.start.offset != null && c.position.end.offset != null) {
-        view.codeRanges.push([c.position.start.offset, c.position.end.offset]);
-      }
-    } else if (node.type === "break" && view) {
-      view.hasBreak = true;
-    }
+    visitNode(state, node, ancestors);
   });
 
-  for (const [p, parts] of proseParts) {
-    const view = viewOf.get(p);
+  for (const [p, parts] of state.proseParts) {
+    const view = state.viewOf.get(p);
     if (view) view.prose = parts.join(" ").replace(/\s+/g, " ").trim();
   }
   let frontmatter: FrontmatterView | null | undefined;
   return {
     src,
     tree,
-    paragraphs,
-    texts,
-    fences,
+    paragraphs: state.paragraphs,
+    texts: state.texts,
+    fences: state.fences,
+    concepts,
     get frontmatter() {
       frontmatter ??= readFrontmatter(src, tree);
       return frontmatter;
@@ -218,6 +270,57 @@ const STYLES: Record<string, ScalarStyle> = {
   BLOCK_FOLDED: "folded",
 };
 
+// What the walk of a YAML document needs to place each scalar in the source,
+// and the list it fills in document order.
+interface ScalarWalk {
+  contentStart: number; // absolute offset where the YAML text starts
+  lineOf: (absoluteOffset: number) => number;
+  indentOf: (relativeOffset: number) => number;
+  scalars: FrontmatterScalar[];
+}
+
+// A string scalar with a range is recorded; anything else is left out.
+const visitScalar = (walk: ScalarWalk, value: Scalar, path: (string | number)[], key: Scalar | null): void => {
+  if (typeof value.value !== "string" || !value.range) return;
+  const { contentStart, lineOf } = walk;
+  const [from, to] = value.range;
+  const anchor = key?.range ? key.range[0] : from;
+  walk.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: walk.indentOf(anchor),
+    node: value,
+  });
+};
+
+// Descend into a YAML node in order: a map by key, a list by index, keeping the
+// nearest map key above each scalar.
+const walkYaml = (walk: ScalarWalk, value: unknown, path: (string | number)[], key: Scalar | null): void => {
+  if (isScalar(value)) {
+    visitScalar(walk, value, path, key);
+    return;
+  }
+  if (isMap(value)) {
+    for (const pair of value.items) {
+      if (!isPair(pair)) continue;
+      const k = isScalar(pair.key) ? pair.key : null;
+      walkYaml(walk, pair.value, [...path, k ? String(k.value) : ""], k);
+    }
+    return;
+  }
+  if (isSeq(value)) {
+    value.items.forEach((item, i) => {
+      walkYaml(walk, item, [...path, i], key);
+    });
+  }
+};
+
 // 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`
@@ -242,38 +345,9 @@ const readFrontmatter = (src: string, tree: Root): FrontmatterView | null => {
     return /^ */.exec(node.value.slice(lineStart))?.[0].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 walk: ScalarWalk = { contentStart, lineOf, indentOf, scalars: [] };
+  walkYaml(walk, doc.contents, [], null);
+  const { scalars } = walk;
 
   const entries: FrontmatterEntry[] = scalars
     .filter((s) => s.path.length === 1 && typeof s.path[0] === "string")

package/src/plugins/discover.ts

@@ -73,20 +73,26 @@ const localSources = async (root: string): Promise<PluginSource[]> => {
 // 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 (Array.isArray(target)) return pickFirst(target);
+  if (isRecord(target)) return pickCondition(target);
+  return null;
+};
+
+// A fallback array: the first entry that names a file.
+const pickFirst = (items: unknown[]): string | null => {
+  for (const item of items) {
+    const found = pick(item);
+    if (found) return found;
   }
-  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;
+};
+
+// A conditions object: the first condition Node would match that names a file.
+const pickCondition = (target: Record<string, unknown>): string | null => {
+  for (const condition of ["node", "import", "default"]) {
+    if (!(condition in target)) continue;
+    const found = pick(target[condition]);
+    if (found) return found;
   }
   return null;
 };

package/src/plugins/index.ts

@@ -12,7 +12,7 @@ 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 { discoverSources, LOCAL_RULES, type PluginSource, type SourceKind } from "./discover.ts";
 import { loadLocal, loadPackage, toRule } from "./load.ts";
 
 export type PluginMode = "off" | "strict" | "lenient" | "collect";
@@ -33,25 +33,25 @@ export interface PluginSet {
   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)] };
+type Settle = (error: PluginLoadError, kind: SourceKind) => void;
+
+interface LoadedPlugin {
+  plugin: Plugin;
+  kind: SourceKind;
+  spec: string;
+}
 
-  // Strict stops at the first failure. The others record it and carry on.
-  const settle = (error: PluginLoadError, kind: SourceKind): void => {
+// Strict stops at the first failure. The others record it and carry on.
+const settler =
+  (mode: PluginMode, failures: PluginFailure[]): Settle =>
+  (error, kind) => {
     if (mode === "strict") throw error;
-    if (!set.failures.some((f) => f.source === error.source)) set.failures.push({ source: error.source, kind, error });
+    if (!failures.some((f) => f.source === error.source)) failures.push({ source: error.source, kind, error });
   };
-  for (const error of unresolved) settle(error, "package");
 
-  const loaded: { plugin: Plugin; kind: SourceKind; spec: string }[] = [];
+// Local files load together as one plugin, then each package loads on its own.
+const importSources = async (found: PluginSource[], settle: Settle): Promise<LoadedPlugin[]> => {
+  const loaded: LoadedPlugin[] = [];
   const locals = found.filter((s) => s.kind === "local");
   if (locals.length > 0) {
     const local = await loadLocal(locals);
@@ -66,38 +66,71 @@ export const loadPlugins = async (root: string, config: Config, mode: PluginMode
       settle(err, source.kind);
     }
   }
+  return loaded;
+};
+
+interface Claims {
+  namespaces: Map<string, string>;
+  declaredBy: Map<string, string>;
+}
 
-  // 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 = [];
+// The earlier claimant and the reason, when a plugin reuses a namespace or a
+// category word another plugin already holds. Null when it claims nothing taken.
+const findClash = (plugin: Plugin, claims: Claims): { other: string; reason: string } | null => {
+  const { namespace } = plugin.meta;
+  const taken = claims.namespaces.get(namespace);
+  if (taken) return { other: taken, reason: `namespace "${namespace}" is already used by ${taken}` };
+  const clash = Object.keys(plugin.meta.categories ?? {}).find((w) => claims.declaredBy.has(w));
+  if (!clash) return null;
+  const other = claims.declaredBy.get(clash) as string;
+  return { other, reason: `category "${clash}" is already declared by ${other}` };
+};
+
+// Namespaces and new categories are global. The first plugin to claim one
+// keeps it, and a later claimant fails, naming both.
+const acceptPlugins = (loaded: LoadedPlugin[], set: PluginSet, settle: Settle): LoadedPlugin[] => {
+  const claims: Claims = { namespaces: new Map(), declaredBy: new Map() };
+  const accepted: LoadedPlugin[] = [];
   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);
+    const clash = findClash(plugin, claims);
+    if (clash) {
+      settle(new PluginConflictError(spec, clash.other, clash.reason), kind);
       continue;
     }
-    namespaces.set(namespace, spec);
+    claims.namespaces.set(plugin.meta.namespace, spec);
     for (const [word, description] of Object.entries(plugin.meta.categories ?? {})) {
-      declaredBy.set(word, spec);
+      claims.declaredBy.set(word, spec);
       set.categories.set(word, description);
     }
     accepted.push(entry);
   }
+  return accepted;
+};
 
+// Each accepted plugin's rules join the set, and the source records which ids it gave.
+const addRules = (set: PluginSet, accepted: LoadedPlugin[]): void => {
   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) });
   }
+};
+
+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)] };
+
+  const settle = settler(mode, set.failures);
+  for (const error of unresolved) settle(error, "package");
+  const loaded = await importSources(found, settle);
+  addRules(set, acceptPlugins(loaded, set, settle));
   return set;
 };

package/src/plugins/load.ts

@@ -49,15 +49,10 @@ const importModule = async (source: PluginSource, runtime?: RuntimeInfo): Promis
 
 const OPTION_TYPES = new Set<OptionType>(["number", "string", "boolean", "string[]"]);
 
-// Checks one rule's declaration and returns it, so a bad rule fails at load
-// rather than the first time it runs.
-const checkRule = (spec: string, key: string, raw: unknown, own: ReadonlySet<string>): PluginRule => {
+// A rule's category is one word, built in or declared by this plugin, and its
+// key starts with it.
+const checkRuleCategory = (spec: string, key: string, category: unknown, own: ReadonlySet<string>): void => {
   const where = `rule "${key}"`;
-  if (!isRecord(raw)) throw new PluginContractError(spec, `${where} must be an object`);
-  if (!RULE_KEY.test(key)) {
-    throw new PluginContractError(spec, `${where} is not a valid key; use lower-case words joined by hyphens`);
-  }
-  const { category, summary, options, check, fix } = raw;
   if (typeof category !== "string" || !CATEGORY_WORD.test(category)) {
     throw new PluginContractError(spec, `${where} needs a category of one lower-case word`);
   }
@@ -70,17 +65,34 @@ const checkRule = (spec: string, key: string, raw: unknown, own: ReadonlySet<str
   if (!key.startsWith(`${category}-`)) {
     throw new PluginContractError(spec, `${where} must start with its category, as "${category}-short-name"`);
   }
+};
+
+// A rule's summary, functions and option types, checked after its category.
+const checkRuleBody = (spec: string, key: string, raw: Record<string, unknown>): void => {
+  const where = `rule "${key}"`;
+  const { summary, options, check, fix } = raw;
   if (typeof summary !== "string" || summary === "") throw new PluginContractError(spec, `${where} needs a summary`);
   if (typeof check !== "function") throw new PluginContractError(spec, `${where} needs a check function`);
   if (fix !== undefined && typeof fix !== "function") {
     throw new PluginContractError(spec, `${where} fix must be a function`);
   }
-  if (options !== undefined) {
-    const valid = isRecord(options) && Object.values(options).every((t) => OPTION_TYPES.has(t as OptionType));
-    if (!valid) {
-      throw new PluginContractError(spec, `${where} options must map names to number, string, boolean or string[]`);
-    }
+  if (options === undefined) return;
+  const valid = isRecord(options) && Object.values(options).every((t) => OPTION_TYPES.has(t as OptionType));
+  if (!valid) {
+    throw new PluginContractError(spec, `${where} options must map names to number, string, boolean or string[]`);
   }
+};
+
+// Checks one rule's declaration and returns it, so a bad rule fails at load
+// rather than the first time it runs.
+const checkRule = (spec: string, key: string, raw: unknown, own: ReadonlySet<string>): PluginRule => {
+  const where = `rule "${key}"`;
+  if (!isRecord(raw)) throw new PluginContractError(spec, `${where} must be an object`);
+  if (!RULE_KEY.test(key)) {
+    throw new PluginContractError(spec, `${where} is not a valid key; use lower-case words joined by hyphens`);
+  }
+  checkRuleCategory(spec, key, raw.category, own);
+  checkRuleBody(spec, key, raw);
   return raw as unknown as PluginRule;
 };
 
@@ -135,6 +147,50 @@ export interface LocalLoad {
   failures: PluginLoadError[];
 }
 
+interface LocalCategories {
+  // Each word the local files declare, with its description.
+  categories: Record<string, string>;
+  // The file that first declared each word.
+  owner: Record<string, string>;
+}
+
+interface LocalFile {
+  key: string;
+  source: PluginSource;
+  raw: unknown;
+}
+
+// Local files may each declare the same word, but only with the same description.
+const mergeCategories = (source: PluginSource, declared: Record<string, string>, merged: LocalCategories): void => {
+  const { categories, owner } = merged;
+  for (const [word, description] of Object.entries(declared)) {
+    if (categories[word] !== undefined && categories[word] !== description) {
+      throw new PluginConflictError(
+        source.spec,
+        owner[word] as string,
+        `declares category "${word}" with a different description than another local file`,
+      );
+    }
+    categories[word] = description;
+    owner[word] = source.spec;
+  }
+};
+
+// Imports one local file and merges the categories it declares. Its rule is
+// checked later, once every file's categories are known.
+const importLocalFile = async (
+  source: PluginSource,
+  merged: LocalCategories,
+  runtime?: RuntimeInfo,
+): Promise<LocalFile> => {
+  const mod = await importModule(source, runtime);
+  if (mod.default === undefined) {
+    throw new PluginContractError(source.spec, "has no default export; export one rule");
+  }
+  mergeCategories(source, checkCategories(source.spec, mod.categories), merged);
+  return { key: basename(source.path, extname(source.path)), source, raw: mod.default };
+};
+
 // Local files: each default-exports one rule, keyed by its file name. They load
 // as one plugin under the fixed namespace `local`, and a file may export
 // `categories` to declare the word its rule uses. Each file fails on its own,
@@ -145,32 +201,16 @@ export const loadLocal = async (sources: PluginSource[], runtime?: RuntimeInfo):
     if (!(err instanceof PluginLoadError)) throw err;
     failures.push(err);
   };
-  const categories: Record<string, string> = {};
-  const owner: Record<string, string> = {};
-  const loaded: { key: string; source: PluginSource; raw: unknown }[] = [];
+  const merged: LocalCategories = { categories: {}, owner: {} };
+  const loaded: LocalFile[] = [];
   for (const source of sources) {
     try {
-      const mod = await importModule(source, runtime);
-      if (mod.default === undefined) {
-        throw new PluginContractError(source.spec, "has no default export; export one rule");
-      }
-      const declared = checkCategories(source.spec, mod.categories);
-      for (const [word, description] of Object.entries(declared)) {
-        if (categories[word] !== undefined && categories[word] !== description) {
-          throw new PluginConflictError(
-            source.spec,
-            owner[word] as string,
-            `declares category "${word}" with a different description than another local file`,
-          );
-        }
-        categories[word] = description;
-        owner[word] = source.spec;
-      }
-      loaded.push({ key: basename(source.path, extname(source.path)), source, raw: mod.default });
+      loaded.push(await importLocalFile(source, merged, runtime));
     } catch (err) {
       fail(err);
     }
   }
+  const { categories } = merged;
   const own = new Set(Object.keys(categories));
   const rules: Record<string, PluginRule> = {};
   for (const { key, source, raw } of loaded) {