chaffjs 0.18.0 → 0.19.0

package/src/document.ts

@@ -5,9 +5,11 @@ import { maskSpans } from "./mask.ts";
 import { spansWithin, unmaskedSoftBreaks } from "./soft-break.ts";
 import { segmentJoined } from "./joined-view.ts";
 import { documentLineParagraphs } from "./line-paragraphs.ts";
-import { subheadingPieces } from "./subheading-line.ts";
+import { closingRun, standaloneLines, subheadingPieces, type StandsAlone } from "./subheading-line.ts";
+import { isLinkLine } from "./link-line.ts";
 import { speakerLabels } from "./speaker-labels.ts";
-import { buildTree, type Outline } from "./structure/build.ts";
+import type { Outline } from "./structure/build.ts";
+import { lazyTree } from "./structure/lazy-tree.ts";
 import { isMarkdownPath } from "./structure/markdown-path.ts";
 import { layoutMasks, textOutline } from "./page-furniture.ts";
 import { tokenizedLexicons } from "./lexicon-tokens.ts";
@@ -98,7 +100,7 @@ const collectMasks = (root: Node, source: string, anchors: InPageAnchors, syntax
   return spans;
 };
 
-const emphasisSpans = (root: Node, source: string): Span[] => {
+export const emphasisSpans = (root: Node, source: string): Span[] => {
   const spans: Span[] = [];
   eachPreOrder(root, (node) => {
     if (EMPHASIS.has(node.type)) spans.push(...emphasisChrome(node, source));
@@ -171,9 +173,54 @@ const shift = (span: Span, by: number): Span => ({ start: by + span.start, end:
 
 const breaksWithin = (breaks: readonly Span[], paragraph: Span): Span[] => spansWithin(breaks, paragraph).map((span) => shift(span, -paragraph.start));
 
-/** 段落を、中の小見出しの行（「（経済再生）」）の後ろで切った片。片ごとに分割すれば、小見出しが次の文に入らない。 */
-const piecesOf = (prose: string, paragraphs: readonly Span[]): Span[] =>
-  paragraphs.flatMap((paragraph) => subheadingPieces(prose.slice(paragraph.start, paragraph.end)).map((piece) => shift(piece, paragraph.start)));
+/** 段落の中の行（段落の中の位置）が、一つのリンクだけの行か。 */
+const linkLineIn =
+  (source: string, links: readonly Span[], paragraph: Span): StandsAlone =>
+  (start, end) =>
+    isLinkLine(source, shift({ start, end }, paragraph.start), links);
+
+/**
+ * 段落を、中の小見出しの行（「（経済再生）」）とリンクだけの行の後ろで切った片。片ごとに分割すれば、
+ * 小見出しが次の文に入らず、1 行ずつ並べたリンクが一つの長い文にならない。
+ */
+const piecesOf = (prose: string, paragraphs: readonly Span[], source: string, links: readonly Span[]): Span[] =>
+  paragraphs.flatMap((paragraph) =>
+    subheadingPieces(prose.slice(paragraph.start, paragraph.end), linkLineIn(source, links, paragraph)).map((piece) => shift(piece, paragraph.start)),
+  );
+
+/**
+ * 段落の終わりまで続く、一つで立つリンクだけの行（文書の位置）。記事の一覧のように本文の後に 1 行ずつ並べたリンクは、
+ * 箇条書きの項目と同じに読む。段落の途中のリンクの行は、その段落の文の一つのまま。
+ */
+const linkItemsOf = (prose: string, paragraphs: readonly Span[], source: string, links: readonly Span[]): Span[] =>
+  paragraphs.flatMap((paragraph) => {
+    const isLink = linkLineIn(source, links, paragraph);
+    const text = prose.slice(paragraph.start, paragraph.end);
+    const linkLines = standaloneLines(text, isLink).filter((line) => isLink(line.start, line.end));
+    return closingRun(linkLines, text.length).map((line) => shift({ start: line.start, end: line.end }, paragraph.start));
+  });
+
+/**
+ * links: リンク。pieces: 文を分ける片。listSpans: 箇条書きの項目と同じに読む範囲（Markdown の項目と、1 行ずつ並べたリンクの行）。
+ * paragraphs: 段落として数える範囲。リンクの行を切り取る（「関連記事：」に続くリンクの行は、箇条書きと同じく段落の外）。
+ */
+type LineLayout = {
+  readonly links: readonly Span[];
+  readonly pieces: readonly Span[];
+  readonly listSpans: readonly Span[];
+  readonly paragraphs: readonly Span[];
+};
+
+const lineLayoutOf = (root: Node, source: string, prose: string, paragraphs: readonly Span[]): LineLayout => {
+  const links = [...spansOfType(root, "link"), ...spansOfType(root, "linkReference")];
+  const linkItems = linkItemsOf(prose, paragraphs, source, links);
+  return {
+    links,
+    pieces: piecesOf(prose, paragraphs, source, links),
+    listSpans: [...spansOfType(root, "listItem"), ...linkItems],
+    paragraphs: cutTextSpans(paragraphs, linkItems, source),
+  };
+};
 
 const sentencesOf = (prose: string, paragraphs: readonly Span[], adapter: LanguageAdapter, softBreaks: readonly Span[]): Sentence[] =>
   paragraphs.flatMap((paragraph) =>
@@ -216,11 +263,12 @@ const listsOf = (root: Node, source: string, anchors: InPageAnchors): BulletList
     if (node.type !== "list" || isNavigationList(node, anchors)) return;
     const span = spanOf(node);
     if (span === undefined) return;
-    const items = (node.children ?? []).flatMap((child) => {
+    const itemSpans = (node.children ?? []).flatMap((child) => {
       const item = spanOf(child);
-      return child.type === "listItem" && item !== undefined ? [source.slice(item.start, item.end).replace(/\s+/gu, "").length] : [];
+      return child.type === "listItem" && item !== undefined ? [item] : [];
     });
-    if (items.length > 0) found.push({ span, items });
+    const items = itemSpans.map((item) => source.slice(item.start, item.end).replace(/\s+/gu, "").length);
+    if (items.length > 0) found.push({ span, items, itemSpans });
   });
   return found;
 };
@@ -233,21 +281,28 @@ export type TeamRules = {
   readonly prefer?: Readonly<Record<string, string>>;
   /** チームの固有名詞。1 つの名前として読む rule が見る。 */
   readonly names?: readonly string[];
+  /** The word lists the plugins ship for the document's language, by name. */
+  readonly lexicons?: LanguageAdapter["lexicons"];
 };
 
 const EMPTY_TEAM: TeamRules = { jargon: [], requiredSections: [] };
 
-/** Config から取り出す。document は Config の形を知らない。 */
-export const teamRules = (config: {
-  readonly jargon: readonly string[];
-  readonly requiredSections: readonly string[];
-  readonly prefer?: Readonly<Record<string, string>>;
-  readonly names?: readonly string[];
-}): TeamRules => ({
+/** Config から取り出す。document は Config の形を知らない。language: the document's, for the plugins' word lists. */
+export const teamRules = (
+  config: {
+    readonly jargon: readonly string[];
+    readonly requiredSections: readonly string[];
+    readonly prefer?: Readonly<Record<string, string>>;
+    readonly names?: readonly string[];
+    readonly extensions?: { readonly lexicons: Readonly<Record<string, LanguageAdapter["lexicons"]>> };
+  },
+  language?: string,
+): TeamRules => ({
   jargon: config.jargon,
   prefer: config.prefer ?? {},
   requiredSections: config.requiredSections,
   names: config.names ?? [],
+  lexicons: language === undefined ? {} : (config.extensions?.lexicons[language] ?? {}),
 });
 
 /**
@@ -261,6 +316,7 @@ const proseOf = (source: string, masked: readonly Span[]): string => {
 
 const teamLexicons = (adapter: LanguageAdapter, team: TeamRules): LanguageAdapter["lexicons"] => ({
   ...adapter.lexicons,
+  ...team.lexicons,
   "internal-jargon": team.jargon.map((pattern) => ({ pattern })),
   // 使わない書き方を pattern に、使う書き方を instead_of に置く。語彙表の「同じことの別の書き方」と同じ向き。
   "preferred-term": Object.entries(team.prefer ?? {}).map(([pattern, use]) => ({ pattern, instead_of: use })),
@@ -283,15 +339,21 @@ const documentOf = (path: string, source: string, adapter: LanguageAdapter, team
     source,
   );
   const headings = headingsOf(root, source, maskSpans(source, syntax), emailLayout.replyQuotes);
-  const listItems = spansOfType(root, "listItem");
   // Markdown は段落を流し込んで表示するので、段落の中の改行は読み手に見えない。テキストの文書は行をそのまま見せる（法令は 1 行 1 号）。
   const softBreaks = markdown ? unmaskedSoftBreaks(source, prose) : [];
-  const sentences = sentencesOf(prose, piecesOf(prose, paragraphSpans), adapter, softBreaks);
+  const layout = lineLayoutOf(root, source, prose, paragraphSpans);
+  const sentences = sentencesOf(prose, layout.pieces, adapter, softBreaks);
   const lexicons = teamLexicons(adapter, team);
   const tagged = sentences.some((sentence) => sentence.tokens !== undefined);
-  const patterns = adapter.structure;
-  // null は「作ったが構造を読めない言語だった」、undefined は「まだ作っていない」。
-  const tree: { value: StructureNode | null | undefined } = { value: undefined };
+  const structure = lazyTree(adapter.structure, () => ({
+    path,
+    source,
+    language: adapter.id,
+    // テキストの文書は、ページの飾りを覆って読む。フッターの「Section 9」を木の節にしない。
+    outline: markdown ? outlineOf(root, source, syntax, emailLayout.replyQuotes) : textOutline(source, emailLayout.replyQuotes),
+    markdown,
+    profile,
+  }));
   return {
     path,
     source,
@@ -300,34 +362,19 @@ const documentOf = (path: string, source: string, adapter: LanguageAdapter, team
     capabilities: adapter.capabilities,
     sections: sectionsOf(headings, sentences, strongSpans(root, blocks), source.length, headingReadersOf(adapter, tagged, lexicons)),
     sentences,
-    listSpans: listItems,
-    paragraphs: paragraphsOf(prose, paragraphSpans, sentences, listItems),
+    listSpans: layout.listSpans,
+    paragraphs: paragraphsOf(prose, layout.paragraphs, sentences, layout.listSpans),
     lists: listsOf(root, source, anchors),
-    links: [...spansOfType(root, "link"), ...spansOfType(root, "linkReference")],
+    links: layout.links,
     lexicons: tagged ? tokenizedLexicons(lexicons, adapter) : lexicons,
     requiredSections: team.requiredSections,
     names: team.names ?? [],
-    // 構造の rule（参照先が無い・番号の抜け）が読む木。どの rule も読まなければ作らない。何万行の契約書で、他の rule の lint に代金を払わせない。
     get structure(): StructureNode | undefined {
-      tree.value ??=
-        patterns === undefined
-          ? null
-          : buildTree(
-              {
-                path,
-                source,
-                language: adapter.id,
-                // テキストの文書は、ページの飾りを覆って読む。フッターの「Section 9」を木の節にしない。
-                outline: markdown ? outlineOf(root, source, syntax, emailLayout.replyQuotes) : textOutline(source, emailLayout.replyQuotes),
-                markdown: isMarkdownPath(path),
-                profile,
-              },
-              patterns,
-            );
-      return tree.value ?? undefined;
+      return structure();
     },
     profile,
     prose,
+    namedDocument: adapter.structure?.namedDocument,
     replyQuotes: emailLayout.replyQuotes,
     get markup(): Markup {
       return documentMarkup(root, source, markdown, [...emailLayout.replyQuotes, ...syntax]);

package/src/extension/document-view.ts

@@ -0,0 +1,109 @@
+import type * as Api from "../api.ts";
+import type { BulletList, Lexicon, Markup, Paragraph, ProseDocument, Section, Sentence, Span, Token } from "../plugin.ts";
+
+// The document as the plugin API shows it (api.ts RuleDocument): copies of only the public fields, frozen. A copy, so
+// chaff's own shapes can change without breaking a plugin; frozen, so a plugin's rule cannot change what the next rule reads.
+
+const freezeAll = (value: unknown): void => {
+  if (typeof value !== "object" || value === null || Object.isFrozen(value)) return;
+  Object.values(value).forEach(freezeAll);
+  Object.freeze(value);
+};
+
+const deepFreeze = <T>(value: T): T => {
+  freezeAll(value);
+  return value;
+};
+
+const spanOf = (span: Span): Api.Span => ({ start: span.start, end: span.end });
+
+const tokenOf = (token: Token): Api.Token => ({
+  span: spanOf(token.span),
+  surface: token.surface,
+  pos: token.pos,
+  ...(token.lemma === undefined ? {} : { lemma: token.lemma }),
+  ...(token.reading === undefined ? {} : { reading: token.reading }),
+  ...(token.features === undefined ? {} : { features: { ...token.features } }),
+});
+
+/** Sentences are shared by the document, its paragraphs and its sections; each is copied once, so they stay one object. */
+type SentenceCopies = (sentence: Sentence) => Api.Sentence;
+
+const sentenceCopier = (): SentenceCopies => {
+  const copies = new Map<Sentence, Api.Sentence>();
+  return (sentence) => {
+    const known = copies.get(sentence);
+    if (known !== undefined) return known;
+    const copy = { span: spanOf(sentence.span), text: sentence.text, ...(sentence.tokens === undefined ? {} : { tokens: sentence.tokens.map(tokenOf) }) };
+    copies.set(sentence, copy);
+    return copy;
+  };
+};
+
+const paragraphOf = (paragraph: Paragraph, copy: SentenceCopies): Api.Paragraph => ({
+  span: spanOf(paragraph.span),
+  sentences: paragraph.sentences.map(copy),
+});
+
+const sectionOf = (section: Section, copy: SentenceCopies): Api.Section => ({
+  depth: section.depth,
+  heading: section.heading,
+  span: spanOf(section.span),
+  sentences: section.sentences.map(copy),
+});
+
+const listOf = (list: BulletList): Api.List => ({ span: spanOf(list.span), itemLengths: [...list.items] });
+
+const lexiconOf = (lexicon: Lexicon): Api.Lexicon =>
+  lexicon.map((entry) => ({ pattern: entry.pattern, ...(entry.instead_of === undefined ? {} : { instead_of: entry.instead_of }) }));
+
+const markupOf = (markup: Markup): Api.Markup => ({
+  markdown: markup.markdown,
+  headings: markup.headings.map((heading) => ({ depth: heading.depth, text: heading.text, span: { start: heading.start, end: heading.end } })),
+  images: markup.images.map((image) => ({ alt: image.alt, span: { start: image.start, end: image.end } })),
+  links: markup.links.map((link) => ({ destination: link.destination, span: { start: link.start, end: link.end } })),
+  ids: [...markup.ids].toSorted((left, right) => left.localeCompare(right, "en")),
+  texts: markup.texts.map(spanOf),
+});
+
+const EMPTY_MARKUP: Markup = { markdown: false, headings: [], images: [], links: [], ids: new Set(), texts: [] };
+
+const viewOf = (doc: ProseDocument): Api.RuleDocument => {
+  const copy = sentenceCopier();
+  const fields = deepFreeze({
+    path: doc.path,
+    source: doc.source,
+    language: doc.language,
+    lengthUnit: doc.lengthUnit,
+    sentences: doc.sentences.map(copy),
+    paragraphs: doc.paragraphs.map((paragraph) => paragraphOf(paragraph, copy)),
+    sections: doc.sections.map((section) => sectionOf(section, copy)),
+    lists: doc.lists.map(listOf),
+    listItems: doc.listSpans.map(spanOf),
+    links: doc.links.map(spanOf),
+    lexicons: Object.fromEntries(Object.entries(doc.lexicons).map(([name, lexicon]) => [name, lexiconOf(lexicon)])),
+  });
+  // The markup is read from the Markdown tree only when a rule asks for it, as chaff's own rules do.
+  const markup: { value: Api.Markup | undefined } = { value: undefined };
+  return Object.freeze({
+    ...fields,
+    get markup(): Api.Markup {
+      markup.value ??= deepFreeze(markupOf(doc.markup ?? EMPTY_MARKUP));
+      return markup.value;
+    },
+  });
+};
+
+/** A word list as a detector is given it (DetectorOptions.lexicon): public fields only, frozen. */
+export const frozenLexiconOf = (lexicon: Lexicon): Api.Lexicon => deepFreeze(lexiconOf(lexicon));
+
+const views = new WeakMap<ProseDocument, Api.RuleDocument>();
+
+/** The document as a plugin's detector sees it. Made once per document, however many plugin rules read it. */
+export const ruleDocumentOf = (doc: ProseDocument): Api.RuleDocument => {
+  const known = views.get(doc);
+  if (known !== undefined) return known;
+  const view = viewOf(doc);
+  views.set(doc, view);
+  return view;
+};

package/src/extension/failure-text.ts

@@ -0,0 +1,46 @@
+import type { Texts, UiLanguage } from "../ui.ts";
+import type { RuleFailure } from "./module-detector.ts";
+import type { ShapeProblem } from "./returned-findings.ts";
+
+// Why a plugin's rule is listed as not run on a document, in the reader's language. It names where the detector came
+// from, so the person who wrote it knows which file to open.
+
+type Text = {
+  readonly reason: (origin: string, what: string) => string;
+  readonly threw: (message: string) => string;
+  /** Each wrong return, with the finding's number and what was there. */
+  readonly shape: Readonly<Record<ShapeProblem["kind"], (index: string, written: string) => string>>;
+};
+
+const TEXT: Texts<Text> = {
+  ja: {
+    reason: (origin, what) => `${origin} の検出器が${what}ため`,
+    threw: (message) => `エラーを投げた（${message}）`,
+    shape: {
+      "not-a-list": (_index, written) => `指摘の並びでなく ${written} を返した`,
+      "not-a-finding": (index, written) => `${index} 番目の指摘に { start } の形でないもの（${written}）を返した`,
+      "bad-start": (index, written) => `${index} 番目の指摘の start に ${written} を返した（文書の中の位置を整数で返します）`,
+      "bad-end": (index, written) => `${index} 番目の指摘の end に ${written} を返した（start 以上、文書の長さ以下の整数で返します）`,
+      "bad-values": (index, written) => `${index} 番目の指摘の values に文字列と数でない値を入れた（${written}）`,
+    },
+  },
+  en: {
+    reason: (origin, what) => `the detector in ${origin} ${what}`,
+    threw: (message) => `threw an error (${message})`,
+    shape: {
+      "not-a-list": (_index, written) => `returned ${written}, not a list of findings`,
+      "not-a-finding": (index, written) => `returned ${written} as finding ${index}, not a { start } finding`,
+      "bad-start": (index, written) => `returned start ${written} in finding ${index} (an offset in the document, a whole number)`,
+      "bad-end": (index, written) => `returned end ${written} in finding ${index} (a whole number from start to the document's length)`,
+      "bad-values": (index, written) => `put a value that is not a string or a number in finding ${index}'s values (${written})`,
+    },
+  },
+};
+
+/** The reason a rule whose detector failed is listed as not run. */
+export const failureReason = (origin: string, failure: RuleFailure, ui: UiLanguage): string => {
+  const text = TEXT[ui];
+  if (failure.kind === "threw") return text.reason(origin, text.threw(failure.message));
+  const { kind, index, written } = failure.problem;
+  return text.reason(origin, text.shape[kind](String(index), written));
+};

package/src/extension/import-default.ts

@@ -0,0 +1,13 @@
+import { pathToFileURL } from "node:url";
+
+const firstLine = (error: unknown): string => (error instanceof Error ? error.message : String(error)).split("\n")[0] ?? "";
+
+/** A module's default export, or the first line of why it could not be imported (a syntax error, a missing import). Running it runs its code. */
+export const importDefault = async (file: string): Promise<{ readonly exported: unknown } | { readonly message: string }> => {
+  try {
+    const namespace: unknown = await import(pathToFileURL(file).href);
+    return { exported: typeof namespace === "object" && namespace !== null && "default" in namespace ? namespace.default : undefined };
+  } catch (error) {
+    return { message: firstLine(error) };
+  }
+};

package/src/extension/load.ts

@@ -0,0 +1,97 @@
+import { existsSync } from "node:fs";
+import type { Config } from "../config/load.ts";
+import type { Detector, Lexicon, RuleDefinition } from "../plugin.ts";
+import type { StyleDefinition } from "../style-parse.ts";
+import { customRulesOf } from "../custom/load.ts";
+import { withStyle } from "../config/style.ts";
+import { moduleDetector } from "./module-detector.ts";
+import { detectorExport, type ExportProblem } from "./rule-export.ts";
+import { importDefault } from "./import-default.ts";
+import { loadPlugins } from "./plugin-load.ts";
+import type { ParsedPlugin, PluginProblem } from "./plugin-parse.ts";
+import { staysInside } from "./real-path.ts";
+
+// The code chaff.yaml names, loaded once before anything runs: each type: module rule's file, and each plugin under
+// plugins:. Loading runs that code, which is why only chaff.yaml can name it. What cannot be loaded stops the run
+// (settingProblems), like a rule in custom_rules that cannot be read: a rule that silently does not run looks like a clean document.
+
+/** A rule whose file could not be loaded. file is the path as chaff.yaml writes it; detail: why, or what ExportProblem says. */
+export type LoadProblem = {
+  readonly kind: "missing-file" | "outside" | "import-failed" | ExportProblem["kind"];
+  readonly rule: string;
+  readonly file: string;
+  readonly detail: string;
+};
+
+/** What was loaded, and what could not be. */
+export type Extensions = {
+  /** The detector of each type: module rule and each plugin rule written in code, by the rule's id. */
+  readonly detectors: Readonly<Record<string, Detector>>;
+  /** The plugins' rules, with their ids under each plugin's name. */
+  readonly rules: readonly RuleDefinition[];
+  /** The plugins' word lists by language, then by name. */
+  readonly lexicons: Readonly<Record<string, Readonly<Record<string, Lexicon>>>>;
+  /** The plugins' house styles. */
+  readonly styles: readonly StyleDefinition[];
+  readonly problems: readonly LoadProblem[];
+  readonly pluginProblems: readonly PluginProblem[];
+};
+
+type Loaded = { readonly detector: Detector } | { readonly problem: LoadProblem };
+
+/** A type: module rule: its id, its file, and the path as chaff.yaml writes it, which every message names. */
+type ModuleRule = { readonly id: string; readonly file: string; readonly written: string };
+
+const loadRule = async ({ id, file, written }: ModuleRule, baseDir: string): Promise<Loaded> => {
+  const at = { rule: id, file: written };
+  if (!existsSync(file)) return { problem: { ...at, kind: "missing-file", detail: "" } };
+  if (!staysInside(written, file, baseDir)) return { problem: { ...at, kind: "outside", detail: "" } };
+  const imported = await importDefault(file);
+  if ("message" in imported) return { problem: { ...at, kind: "import-failed", detail: imported.message } };
+  const read = detectorExport(imported.exported);
+  return "problem" in read ? { problem: { ...at, ...read.problem } } : { detector: moduleDetector(read.detect, written) };
+};
+
+const moduleRulesOf = (rules: readonly RuleDefinition[]): ModuleRule[] =>
+  rules.flatMap((rule) => (rule.custom?.type === "module" ? [{ id: rule.id, file: rule.custom.file, written: rule.custom.module }] : []));
+
+/** Every type: module rule in chaff.yaml, loaded one by one in the order written, so the same chaff.yaml loads the same way. */
+const loadModuleRules = async (config: Config): Promise<readonly { readonly id: string; readonly loaded: Loaded }[]> =>
+  moduleRulesOf(customRulesOf(config).rules).reduce<Promise<{ id: string; loaded: Loaded }[]>>(
+    async (done, rule) => [...(await done), { id: rule.id, loaded: await loadRule(rule, config.baseDir) }],
+    Promise.resolve([]),
+  );
+
+/** A plugin's code rules, each run as one of chaff's; a failure names the plugin as chaff.yaml writes it. */
+const pluginDetectors = (plugin: ParsedPlugin): [string, Detector][] =>
+  Object.entries(plugin.detectors).map(([id, detect]) => [id, moduleDetector(detect, plugin.written)]);
+
+const lexiconsByLanguage = (plugins: readonly ParsedPlugin[]): Record<string, Record<string, Lexicon>> => {
+  const languages = [...new Set(plugins.flatMap((plugin) => Object.keys(plugin.lexicons)))];
+  return Object.fromEntries(
+    languages.map((language) => [language, plugins.reduce<Record<string, Lexicon>>((merged, plugin) => ({ ...merged, ...plugin.lexicons[language] }), {})]),
+  );
+};
+
+/** Everything chaff.yaml names in code, loaded. */
+const loadExtensions = async (config: Config): Promise<Extensions> => {
+  const modules = await loadModuleRules(config);
+  const { plugins, problems: pluginProblems } = await loadPlugins(config);
+  return {
+    detectors: Object.fromEntries([
+      ...modules.flatMap((entry): [string, Detector][] => ("detector" in entry.loaded ? [[entry.id, entry.loaded.detector]] : [])),
+      ...plugins.flatMap(pluginDetectors),
+    ]),
+    rules: plugins.flatMap((plugin) => plugin.rules),
+    lexicons: lexiconsByLanguage(plugins),
+    styles: plugins.flatMap((plugin) => plugin.styles),
+    problems: modules.flatMap((entry) => ("problem" in entry.loaded ? [entry.loaded.problem] : [])),
+    pluginProblems,
+  };
+};
+
+/** chaff.yaml with the code it names loaded, and the style it names applied when a plugin ships it. */
+export const withExtensions = async (config: Config): Promise<Config> => {
+  const extensions = await loadExtensions(config);
+  return withStyle({ ...config, extensions }, extensions.styles);
+};

package/src/extension/module-detector.ts

@@ -0,0 +1,61 @@
+import type * as Api from "../api.ts";
+import type { Detector, Finding, ProseDocument } from "../plugin.ts";
+import { frozenLexiconOf, ruleDocumentOf } from "./document-view.ts";
+import { returnedFindings, type ShapeProblem } from "./returned-findings.ts";
+
+// A detector a team or a plugin wrote, run as one of chaff's. It reads the document through the plugin API, and what it
+// returns is checked before chaff uses it. A throw or a wrong return is that rule's failure only: run.ts lists the rule
+// as not run with the reason, and every other rule still runs.
+
+/** A detector from a plugin. It is JavaScript nobody has type-checked against this chaff, so what it returns is unknown. */
+export type UntrustedDetector = (doc: Api.RuleDocument, options: Api.DetectorOptions) => unknown;
+
+export type RuleFailure = { readonly kind: "threw"; readonly message: string } | { readonly kind: "returned"; readonly problem: ShapeProblem };
+
+/** A plugin's rule that failed on a document. origin is where the detector came from: its file, or its package. */
+export class PluginRuleFailure extends Error {
+  readonly failure: RuleFailure;
+  readonly origin: string;
+  constructor(failure: RuleFailure, origin: string) {
+    super(`${origin}: ${failure.kind === "threw" ? failure.message : failure.problem.kind}`);
+    this.name = "PluginRuleFailure";
+    this.failure = failure;
+    this.origin = origin;
+  }
+}
+
+/** The first line of what was thrown. What a plugin throws is its own object, so printing it may throw too. */
+const messageOf = (error: unknown): string => {
+  try {
+    const text = error instanceof Error ? error.message : String(error);
+    return text.split("\n")[0] ?? text;
+  } catch {
+    return "an error that cannot be printed";
+  }
+};
+
+/**
+ * What the detector returned, as findings, or how it failed. Reading the return can run the plugin's code too (a getter,
+ * a Proxy), so it is checked inside the try. A Promise is a wrong return; its rejection must not end the run later.
+ */
+const findingsOf = (detect: UntrustedDetector, doc: ProseDocument, options: Api.DetectorOptions): { findings: Finding[] } | { failure: RuleFailure } => {
+  const view = ruleDocumentOf(doc);
+  try {
+    const returned: unknown = detect(view, options);
+    if (returned instanceof Promise) returned.catch(() => undefined);
+    const result = returnedFindings(returned, doc.source, doc.sentences);
+    return "problem" in result ? { failure: { kind: "returned", problem: result.problem } } : { findings: [...result.findings] };
+  } catch (error) {
+    return { failure: { kind: "threw", message: messageOf(error) } };
+  }
+};
+
+/** detect as one of chaff's detectors. Throws PluginRuleFailure when it throws or returns anything but findings. */
+export const moduleDetector =
+  (detect: UntrustedDetector, origin: string): Detector =>
+  (doc, options): Finding[] => {
+    const lexicon = options.lexicon === undefined ? undefined : frozenLexiconOf(options.lexicon);
+    const outcome = findingsOf(detect, doc, Object.freeze({ lexicon }));
+    if ("failure" in outcome) throw new PluginRuleFailure(outcome.failure, origin);
+    return outcome.findings;
+  };

package/src/extension/plugin-load.ts

@@ -0,0 +1,82 @@
+import { createRequire } from "node:module";
+import { join } from "node:path";
+import { CONFIG_FILE, type Config } from "../config/load.ts";
+import { modulePathOf } from "../custom/module-path.ts";
+import { loadGenres } from "../genre-load.ts";
+import { importDefault } from "./import-default.ts";
+import { staysInside } from "./real-path.ts";
+import { isPluginPath, pluginNameOfPackage } from "./plugin-name.ts";
+import { parsePlugin, type ParsedPlugin, type PluginOrigin, type PluginProblem } from "./plugin-parse.ts";
+
+// The plugins chaff.yaml lists under plugins:, found and loaded. A package is found from the folder chaff.yaml is in,
+// as Node finds it (node_modules); a path is the project's own plugin and, like a module rule, may not leave that
+// folder unless written as an absolute path. What cannot be found or read stops the run.
+
+export type LoadedPlugins = { readonly plugins: readonly ParsedPlugin[]; readonly problems: readonly PluginProblem[] };
+
+type Located = { readonly origin: PluginOrigin } | { readonly problem: PluginProblem };
+
+const problemOf = (kind: Exclude<PluginProblem["kind"], "rule">, plugin: string, detail = ""): { problem: PluginProblem } => ({
+  problem: { kind, plugin, detail },
+});
+
+/** The file Node would load for specifier from the folder chaff.yaml is in, or undefined when there is none. */
+const resolveFrom = (baseDir: string, specifier: string): string | undefined => {
+  try {
+    return createRequire(join(baseDir, CONFIG_FILE)).resolve(specifier);
+  } catch {
+    return undefined;
+  }
+};
+
+const locate = (written: string, baseDir: string): Located => {
+  if (isPluginPath(written)) {
+    const path = modulePathOf(written, baseDir);
+    if ("refusal" in path) return problemOf("outside", written);
+    const file = resolveFrom(baseDir, path.file);
+    if (file === undefined) return problemOf("not-found", written);
+    return staysInside(written, file, baseDir) ? { origin: { written, file, expectedName: undefined } } : problemOf("outside", written);
+  }
+  const expectedName = pluginNameOfPackage(written);
+  if (expectedName === undefined) return problemOf("bad-specifier", written);
+  const file = resolveFrom(baseDir, written);
+  return file === undefined ? problemOf("not-found", written) : { origin: { written, file, expectedName } };
+};
+
+const loadPlugin = async (written: string, baseDir: string, useFor: readonly string[]): Promise<LoadedPlugins> => {
+  const located = locate(written, baseDir);
+  if ("problem" in located) return { plugins: [], problems: [located.problem] };
+  const imported = await importDefault(located.origin.file);
+  if ("message" in imported) return { plugins: [], problems: [problemOf("import-failed", written, imported.message).problem] };
+  const read = parsePlugin(imported.exported, located.origin, useFor);
+  return { plugins: read.plugin === undefined ? [] : [read.plugin], problems: read.problems };
+};
+
+/** A second plugin with a name already taken is refused: its rules' ids would be the first one's. */
+const withoutDuplicates = (loaded: readonly { written: string; result: LoadedPlugins }[]): LoadedPlugins =>
+  loaded.reduce<{ plugins: ParsedPlugin[]; problems: PluginProblem[] }>(
+    (acc, { written, result }) => {
+      const taken = result.plugins.filter((plugin) => acc.plugins.some((seen) => seen.name === plugin.name));
+      return {
+        plugins: [...acc.plugins, ...result.plugins.filter((plugin) => !taken.includes(plugin))],
+        problems: [...acc.problems, ...result.problems, ...taken.map((plugin) => problemOf("duplicate-name", written, plugin.name).problem)],
+      };
+    },
+    { plugins: [], problems: [] },
+  );
+
+const isStringList = (value: unknown): value is readonly string[] =>
+  Array.isArray(value) && value.every((entry) => typeof entry === "string" && entry.trim() !== "");
+
+/** Every plugin chaff.yaml lists, loaded one by one in the order written. */
+export const loadPlugins = async (config: Pick<Config, "plugins" | "baseDir">): Promise<LoadedPlugins> => {
+  const written: unknown = config.plugins;
+  if (written === undefined || written === null) return { plugins: [], problems: [] };
+  if (!isStringList(written)) return { plugins: [], problems: [problemOf("not-a-list", "plugins", JSON.stringify(written) ?? "").problem] };
+  const useFor = loadGenres().groups.map((group) => group.id);
+  const loaded = await written.reduce<Promise<{ written: string; result: LoadedPlugins }[]>>(
+    async (done, entry) => [...(await done), { written: entry.trim(), result: await loadPlugin(entry.trim(), config.baseDir, useFor) }],
+    Promise.resolve([]),
+  );
+  return withoutDuplicates(loaded);
+};

package/src/extension/plugin-name.ts

@@ -0,0 +1,26 @@
+import { isAbsolute } from "node:path";
+
+// The names a plugin goes by. A package is chaff-plugin-<name> or @scope/chaff-plugin-<name>, and its rules are named
+// <name>/<rule> or @scope/<name>/<rule>, so they cannot take a built-in rule's id or another plugin's. Pure.
+
+/** A plugin's name, the prefix of its ids: foo, @scope/foo, or @scope for @scope/chaff-plugin. */
+const PLUGIN_NAME = /^(?:@[a-z0-9][a-z0-9._-]*(?:\/[a-z][a-z0-9-]*)?|[a-z][a-z0-9-]*)$/u;
+
+const PACKAGE = /^(?:(@[a-z0-9][a-z0-9._-]*)\/)?chaff-plugin(?:-([a-z][a-z0-9-]*))?$/u;
+
+/** A rule id as chaff.yaml, stet and baseline may write it: a built-in or team id, or a plugin's id with its prefix. */
+export const RULE_ID = /^(?:@[a-z0-9][a-z0-9._-]*\/)?(?:[a-z][a-z0-9-]*\/)?[a-z][a-z0-9-]*$/u;
+
+export const isPluginName = (name: string): boolean => PLUGIN_NAME.test(name);
+
+/** The name a plugin package must declare: chaff-plugin-foo → foo, @scope/chaff-plugin-foo → @scope/foo. undefined for a name that is not a plugin package's. */
+export const pluginNameOfPackage = (packageName: string): string | undefined => {
+  const match = PACKAGE.exec(packageName);
+  if (match === null) return undefined;
+  const [, scope, name] = match;
+  if (scope === undefined) return name;
+  return name === undefined ? scope : `${scope}/${name}`;
+};
+
+/** A path to a plugin of the project's own (./local-plugin), rather than a package's name. */
+export const isPluginPath = (written: string): boolean => written.startsWith(".") || isAbsolute(written);