chaffjs 0.18.0 → 0.20.0

package/src/detectors/unit-consistency.ts

@@ -0,0 +1,55 @@
+import type { Detector, Finding, ProseDocument, StructureNode } from "../plugin.ts";
+import { nameSpans } from "../compare/proper-nouns.ts";
+import { overlapsAny, spanIndex } from "../compare/spans.ts";
+import { factValues, type FactValue } from "../facts/fact-values.ts";
+import { labelledFacts } from "../facts/labelled-facts.ts";
+import { tableFacts } from "../facts/table-facts.ts";
+import { scopedFacts } from "../facts/fact-scope.ts";
+import { measuredValues, type Measured, type MeasureUnit } from "../facts/measures.ts";
+import { unitConflicts } from "../facts/unit-conflicts.ts";
+import { factWordsOf } from "./fact-consistency.ts";
+import { quoteAt } from "./structure-tree.ts";
+
+/** 量の種類ごとの語彙表。weight が基準の単位への倍率で、同じ単位を二度書けば倍率が二つ（GB の 10^9 と 2^30）。 */
+const DIMENSIONS = ["unit-length", "unit-mass", "unit-time", "unit-volume", "unit-data"] as const;
+
+const unitsOf = (doc: ProseDocument): MeasureUnit[] =>
+  DIMENSIONS.flatMap((dimension) => {
+    const factors = new Map<string, number[]>();
+    (doc.lexicons[dimension] ?? []).forEach((entry) => {
+      if (entry.weight !== undefined) factors.set(entry.pattern, [...(factors.get(entry.pattern) ?? []), entry.weight]);
+    });
+    return [...factors.entries()].map(([pattern, weights]) => ({ pattern, dimension, factors: weights }));
+  });
+
+/** fact-conflict と同じ値に、単位の付いた量を足す。量と重なる値（量の数だけを読んだもの）は量に置き換える。 */
+const valuesWith = (tree: StructureNode, doc: ProseDocument, measured: readonly Measured[]): FactValue[] => {
+  const taken = spanIndex(measured);
+  const others = factValues(tree, doc.source, nameSpans(doc)).filter((value) => !overlapsAny(taken, value));
+  return [...others, ...measured].toSorted((left, right) => left.start - right.start);
+};
+
+/** 同じ名前の量を、違う単位で書いて、換算すると合わない。 */
+export const unitMismatch: Detector = (doc): Finding[] => {
+  const tree = doc.structure;
+  if (tree === undefined) return [];
+  const measured = measuredValues(doc.source, unitsOf(doc));
+  if (measured.length === 0) return [];
+  const byStart = new Map(measured.map((value) => [value.start, value]));
+  const values = valuesWith(tree, doc, measured);
+  const facts = [...labelledFacts(doc.source, values, factWordsOf(doc)), ...tableFacts(doc.source, values)];
+  const scoped = scopedFacts(facts, tree, doc.source, []);
+  return unitConflicts(scoped, (fact) => byStart.get(fact.value.start)).map((conflict) => ({
+    rule: "unit-mismatch",
+    severity: "warning",
+    line: 0,
+    column: 0,
+    quote: quoteAt(doc.source, conflict.measured.start),
+    values: {
+      label: conflict.fact.label,
+      value: doc.source.slice(conflict.measured.start, conflict.measured.end),
+      other: doc.source.slice(conflict.other.start, conflict.other.end),
+      offset: conflict.measured.start,
+    },
+  }));
+};

package/src/detectors/unknown-word.ts

@@ -0,0 +1,43 @@
+import type { Detector, Finding, ProseDocument } from "../plugin.ts";
+import { isKnownWord, suggestionFor, wordsToCheck, type CheckedWord, type Speller } from "../spelling.ts";
+import { quoteAt } from "./structure-tree.ts";
+
+/** これより短い語は見ない。短い語は一字違いの語が多すぎて言い直しが決まらず（tost は test か toast か）、略した語（impl）も多い。 */
+const MIN_LENGTH = 5;
+
+/** これより長い字の並びは語でなく、符号化したデータ（base64、ハッシュ）。一字違いの形を作ると長さの二乗で重くなる。 */
+const MAX_LENGTH = 30;
+
+const patternsOf = (doc: ProseDocument, name: string): string[] => (doc.lexicons[name] ?? []).map((entry) => entry.pattern.toLowerCase());
+
+/** 辞書と、語彙表 extra-word の語と、チームの names と、別の rule が言う誤り（known-misspelling）を足した語。 */
+const spellerOf = (doc: ProseDocument, dictionary: ReadonlySet<string>): Speller => ({
+  words: [dictionary, new Set([...patternsOf(doc, "extra-word"), ...(doc.names ?? []).map((name) => name.toLowerCase())])],
+  suffixes: (doc.lexicons["word-suffix"] ?? []).map((entry) => ({ suffix: entry.pattern, replacement: entry.instead_of ?? "" })),
+  prefixes: patternsOf(doc, "word-prefix"),
+});
+
+/** 文書で一度だけ使った語。二度以上使う語は、打ち間違いより、その文書の用語であることが多い。 */
+const usedOnce = (words: readonly CheckedWord[]): CheckedWord[] => {
+  const counts = new Map<string, number>();
+  words.forEach(({ word }) => counts.set(word, (counts.get(word) ?? 0) + 1));
+  return words.filter(({ word }) => counts.get(word) === 1);
+};
+
+/**
+ * 辞書に無い英語の語で、一字違いの辞書の語があるもの（recieve → receive）。辞書は adapter が持ち、無い言語では動かない。
+ * 大文字を含む語（固有名詞・略語）、コード・URL の中、二度以上使う語、言い直しの無い語は言わない。
+ */
+export const unknownWord: Detector = (doc): Finding[] => {
+  if (doc.dictionary === undefined) return [];
+  const speller = spellerOf(doc, doc.dictionary());
+  const known = new Set(patternsOf(doc, "known-misspelling"));
+  const words = wordsToCheck(doc.prose ?? doc.source, MIN_LENGTH, MAX_LENGTH);
+  const used = new Set(words.map(({ word }) => word).filter((word) => isKnownWord(word, speller)));
+  return usedOnce(words).flatMap(({ offset, word }) => {
+    if (known.has(word) || isKnownWord(word, speller)) return [];
+    const suggestion = suggestionFor(word, speller, used);
+    if (suggestion === undefined) return [];
+    return [{ rule: "", severity: "warning", line: 0, column: 0, quote: quoteAt(doc.source, offset), values: { word, suggestion, offset } }];
+  });
+};

package/src/detectors/url-run-on.ts

@@ -10,6 +10,12 @@ const BARE_URL = /https?:\/\/[!-~]+/gu;
  */
 const RUNS_ON = /[^\s\p{Cf}]/u;
 
+/** index から始まる一字（サロゲートの対は一字）。末尾より後ろは空。 */
+const characterAt = (text: string, index: number): string => {
+  const point = text.codePointAt(index);
+  return point === undefined ? "" : String.fromCodePoint(point);
+};
+
 export type RunOnUrl = { readonly url: Span; readonly next: string };
 
 /** 字のまま見える範囲（texts）の中の、すぐ後ろに空白を置かずに日本語や全角の記号が続く URL。 */
@@ -18,7 +24,7 @@ export const runOnUrls = (source: string, texts: readonly Span[]): RunOnUrl[] =>
     const written = source.slice(text.start, text.end);
     return [...written.matchAll(BARE_URL)].flatMap((match) => {
       const end = match.index + match[0].length;
-      const next = [...written.slice(end, end + 2)][0] ?? "";
+      const next = characterAt(written, end);
       return RUNS_ON.test(next) ? [{ url: { start: text.start + match.index, end: text.start + end }, next }] : [];
     });
   });

package/src/detectors/vague-figure-pointer.ts

@@ -0,0 +1,58 @@
+import type { Detector, Finding, Lexicon, ProseDocument } from "../plugin.ts";
+import { FIGURE_NUMBER, labelledKindsIn } from "../figure-references.ts";
+import { escapeRegExp } from "../orthography.ts";
+import { labelWordsOf } from "./dangling-figure.ts";
+import { quoteAt } from "./structure-tree.ts";
+import { numbersClauses } from "../structure/numbered-clauses.ts";
+
+// A figure or a table pointed at by where it is (上記の図, the table below) in a document that numbers that kind and
+// could name it (図3, Table 2), and a clause (以下の箇条, the clause below) in a document that numbers its clauses.
+// JIS Z 8301:2019 10.6. The phrases and the kind each points at come from the lexicons.
+
+export type VaguePointer = { readonly offset: number; readonly written: string; readonly kind: string };
+
+/** A phrase inside a longer word (向上の図, 上の図表) is not one. */
+const EDGE = "[\\p{Script=Han}\\p{Script=Katakana}A-Za-z0-9０-９]";
+
+/** Matched in any case (The figure below). */
+const pointerPattern = (pattern: string): RegExp => new RegExp(`(?<!${EDGE})${escapeRegExp(pattern)}(?!${EDGE})`, "giu");
+
+/** A pointer followed by a number names the figure (上の図 １, the figure below 2, the table above IV): the numbers figure labels take. */
+const NUMBERED = new RegExp(`^${FIGURE_NUMBER}`, "u");
+/** Enough characters after a pointer to hold a figure's number (第十二, 3.2.1). */
+const NUMBER_LOOKAHEAD = 16;
+
+/** Pure: every pointer in the prose that points at a kind the document labels. */
+export const vaguePointers = (prose: string, pointers: Lexicon, labelledKinds: ReadonlySet<string>): VaguePointer[] =>
+  pointers
+    .flatMap((entry) => {
+      const kind = entry.instead_of;
+      if (kind === undefined || !labelledKinds.has(kind)) return [];
+      return [...prose.matchAll(pointerPattern(entry.pattern))]
+        .filter((match) => !NUMBERED.test(prose.slice(match.index + match[0].length, match.index + match[0].length + NUMBER_LOOKAHEAD)))
+        .map((match) => ({ offset: match.index, written: match[0], kind }));
+    })
+    .toSorted((left, right) => left.offset - right.offset);
+
+const kindsOf = (pointers: Lexicon): Set<string> => new Set(pointers.flatMap((entry) => entry.instead_of ?? []));
+
+/** The clause kinds to check. The tree is built only when a clause pointer is written, so other documents do not pay for it. */
+const clauseKindsIn = (doc: ProseDocument, prose: string, pointers: Lexicon): string[] => {
+  const kinds = kindsOf(pointers);
+  if (vaguePointers(prose, pointers, kinds).length === 0) return [];
+  return doc.structure !== undefined && numbersClauses(doc.structure) ? [...kinds] : [];
+};
+
+export const vagueFigurePointer: Detector = (doc): Finding[] => {
+  const prose = doc.prose ?? doc.source;
+  const clausePointers = doc.lexicons["vague-clause-pointer"] ?? [];
+  const kinds = new Set([...labelledKindsIn(doc.source, labelWordsOf(doc)), ...clauseKindsIn(doc, prose, clausePointers)]);
+  return vaguePointers(prose, [...(doc.lexicons["vague-figure-pointer"] ?? []), ...clausePointers], kinds).map((pointer) => ({
+    rule: "",
+    severity: "warning",
+    line: 0,
+    column: 0,
+    quote: quoteAt(doc.source, pointer.offset),
+    values: { matched: pointer.written, kind: pointer.kind, offset: pointer.offset },
+  }));
+};

package/src/detectors/vague-link-text.ts

@@ -0,0 +1,12 @@
+import type { Detector, Finding } from "../plugin.ts";
+import { findingAt, markupOf } from "./markup-finding.ts";
+import { bareLinkText, comparableLinkText, isVagueLinkText, linkTextOf } from "../link-text.ts";
+
+/** 言葉がそれだけでは行き先を言わないリンク（`[こちら](url)`、`[click here](url)`）。どの言葉かは語彙表 vague-link-text が言う。 */
+export const vagueLinkText: Detector = (doc, options): Finding[] => {
+  const vague = new Set((options.lexicon ?? []).map((entry) => comparableLinkText(entry.pattern)));
+  return (markupOf(doc)?.links ?? []).flatMap((link) => {
+    const text = linkTextOf(doc.source.slice(link.start, link.end));
+    return text !== undefined && isVagueLinkText(text, vague) ? [findingAt(doc, link, { text: bareLinkText(text) })] : [];
+  });
+};

package/src/detectors/word-list.ts

@@ -1,2 +1,7 @@
+const separatorOf = (language: string): string => (language === "ja" ? "、" : ", ");
+
 /** 語の並べ方は文書の言語に合わせる。日本語は「、」、ほかは ", "。英語の画面に「Risks、Costs」と出さない。 */
-export const joinWords = (words: readonly string[], language: string): string => words.join(language === "ja" ? "、" : ", ");
+export const joinWords = (words: readonly string[], language: string): string => words.join(separatorOf(language));
+
+/** joinWords で並べた語を、元の語に戻す。 */
+export const splitWords = (joined: string, language: string): string[] => (joined === "" ? [] : joined.split(separatorOf(language)));

package/src/document-reading.ts

@@ -0,0 +1,25 @@
+import { isMarkdownPath } from "./structure/markdown-path.ts";
+import { parse, readMarkdown } from "./markdown-read.ts";
+import type { MarkdownNode as Node } from "./markdown-node.ts";
+import type { Span } from "./plugin.ts";
+import { isYamlPath, outsideValues, valuesText, yamlValueSpans } from "./yaml-values.ts";
+
+/** A paragraph node per YAML value: a value is never read as Markdown (its indentation is not code) nor run into the next. */
+const valuesRoot = (values: readonly Span[]): Node => ({
+  type: "root",
+  children: values.map((span) => ({ type: "paragraph", position: { start: { offset: span.start }, end: { offset: span.end } }, children: [] })),
+});
+
+/**
+ * How a file is read: Markdown, a YAML file's string values, or plain text. text: what layout and structure read, which for YAML
+ * is the values alone, keys and comments blanked in place. extra: what is not prose beyond what the tree says (YAML's keys).
+ */
+export const readingOf = (path: string, source: string): { root: Node; syntax: readonly Span[]; text: string; extra: readonly Span[] } => {
+  if (isMarkdownPath(path)) return { ...readMarkdown(source), text: source, extra: [] };
+  const values = isYamlPath(path) ? yamlValueSpans(source) : undefined;
+  if (values === undefined) return { root: parse(source), syntax: [], text: source, extra: [] };
+  return { root: valuesRoot(values), syntax: [], text: valuesText(source, values), extra: outsideValues(values, source.length) };
+};
+
+/** The text a document's structure is read from: the file, or for a YAML file its values alone. */
+export const structureText = (path: string, source: string): string => readingOf(path, source).text;

package/src/document.ts

@@ -5,17 +5,20 @@ 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 { readingOf } from "./document-reading.ts";
 import { layoutMasks, textOutline } from "./page-furniture.ts";
 import { tokenizedLexicons } from "./lexicon-tokens.ts";
 import { plainSource } from "./plain-source.ts";
 import { inPageAnchors, isInPageNavigation, isNavigationList, type InPageAnchors } from "./in-page-nav.ts";
 import { eachPreOrder } from "./tree-walk.ts";
 import { alertReader } from "./template-syntax.ts";
-import { opaqueSpans, parse, readMarkdown, spansOfType } from "./markdown-read.ts";
+import { opaqueSpans, readMarkdown, spansOfType } from "./markdown-read.ts";
 import { spanOf, type MarkdownNode as Node } from "./markdown-node.ts";
 import { emailParts, emailVocabulary } from "./email-parts.ts";
 import { cutTextSpans } from "./span-cut.ts";
@@ -98,7 +101,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 +174,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 +264,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 +282,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 +317,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 })),
@@ -268,13 +325,13 @@ const teamLexicons = (adapter: LanguageAdapter, team: TeamRules): LanguageAdapte
 
 const documentOf = (path: string, source: string, adapter: LanguageAdapter, team: TeamRules, profile: DocumentProfile | undefined): ProseDocument => {
   const markdown = isMarkdownPath(path);
-  const { root, syntax } = markdown ? readMarkdown(source) : { root: parse(source), syntax: [] };
+  const { root, syntax, text, extra } = readingOf(path, source);
   const anchors = inPageAnchors(root);
-  const emailLayout = emailParts(source, emailVocabulary(adapter.lexicons));
+  const emailLayout = emailParts(text, emailVocabulary(adapter.lexicons));
   // 強調の記号は「本文でないもの」だが、太字の数を数えるときの「覆われた場所」ではない。
   // 同じ集合にすると、太字が自分の記号のせいで覆われた場所にあることになり、1 つも数えられなくなる。
   // ページのヘッダーとフッター（テキストの文書）と、線で描いた図も本文ではない。
-  const blocks = [...collectMasks(root, source, anchors, syntax), ...layoutMasks(root, source, markdown), ...emailLayout.furniture];
+  const blocks = [...collectMasks(root, source, anchors, syntax), ...layoutMasks(root, text, markdown), ...emailLayout.furniture, ...extra];
   const prose = proseOf(source, [...blocks, ...emphasisSpans(root, source)]);
   // ページの案内は段落としても数えない。数えると、目次の行が「本題までの段落」に入る。メールのヘッダーや署名の行は段落から切り取る。
   const paragraphSpans = cutTextSpans(
@@ -283,15 +340,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: text,
+    language: adapter.id,
+    // テキストの文書は、ページの飾りを覆って読む。フッターの「Section 9」を木の節にしない。
+    outline: markdown ? outlineOf(root, source, syntax, emailLayout.replyQuotes) : textOutline(text, emailLayout.replyQuotes),
+    markdown,
+    profile,
+  }));
   return {
     path,
     source,
@@ -300,34 +363,20 @@ 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,
+    dictionary: adapter.dictionary,
     replyQuotes: emailLayout.replyQuotes,
     get markup(): Markup {
       return documentMarkup(root, source, markdown, [...emailLayout.replyQuotes, ...syntax]);

package/src/experimental-alone.ts

@@ -0,0 +1,21 @@
+import type { Level, RuleDefinition } from "./plugin.ts";
+import { standingIn } from "./rule-genres.ts";
+
+type Written = { readonly rules: Readonly<Record<string, Level>>; readonly experimental: boolean };
+
+/**
+ * Whether naming the rule in chaff.yaml (npx chaffjs enable <id>) is all it takes to run it: it is off only because it is
+ * experimental. Not when chaff.yaml already names it, the genre's preset decides it, the genre is not one it serves, or
+ * the language is not one it reads; enable would change nothing there, and saying so would mislead.
+ */
+export const offOnlyAsExperimental = (
+  rule: Pick<RuleDefinition, "id" | "status" | "use_for" | "languages">,
+  written: Written,
+  genre: string,
+  preset: Readonly<Record<string, Level>>,
+  language: string,
+): boolean =>
+  !written.experimental &&
+  written.rules[rule.id] === undefined &&
+  (rule.languages === undefined || rule.languages.includes(language)) &&
+  standingIn(rule, genre, preset).kind === "experimental";

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));
+};