chaffjs 0.19.0 → 0.21.0

package/src/detectors/technical-docs.ts

@@ -0,0 +1,230 @@
+// Checks a README or a manual needs: code fences tagged with a language or not, shell commands written with and without
+// a prompt, a heading that names a command its section's code never shows, and a step of a numbered procedure written
+// as a statement among instructions. Pure. Shell languages and prompt marks come from the shell-fence-language and
+// shell-prompt lexicons.
+import { codeFences, codeSpans, type CodeFence } from "./code-fences.ts";
+import { quoteAt } from "./structure-tree.ts";
+import type { Detector, Finding, ProseDocument, Span, Token } from "../plugin.ts";
+
+const patternsOf = (doc: ProseDocument, id: string): string[] => (doc.lexicons[id] ?? []).map((entry) => entry.pattern);
+
+/** The members of the less used of two kinds: at most limit of them, and fewer than the other kind. */
+export const minorityOf = <T>(first: readonly T[], second: readonly T[], limit: number): readonly T[] => {
+  const [fewer, more] = first.length <= second.length ? [first, second] : [second, first];
+  return fewer.length > 0 && fewer.length < more.length && fewer.length <= limit ? fewer : [];
+};
+
+const finding = (doc: ProseDocument, rule: string, offset: number, values: Readonly<Record<string, string | number>> = {}): Finding => ({
+  rule,
+  severity: "info",
+  line: 0,
+  column: 0,
+  quote: quoteAt(doc.source, offset),
+  values: { ...values, offset },
+});
+
+/** Fences without a language, when they are the fewer kind: a document that mostly leaves the language out is not reported. */
+export const untaggedFewer = (fences: readonly CodeFence[], limit: number): readonly CodeFence[] => {
+  const untagged = fences.filter((fence) => fence.language === "");
+  const tagged = fences.filter((fence) => fence.language !== "");
+  return untagged.length > 0 && untagged.length < tagged.length && untagged.length <= limit ? untagged : [];
+};
+
+export const codeFenceLanguage: Detector = (doc, options): Finding[] => {
+  const fences = codeFences(doc.source);
+  const tagged = fences.filter((fence) => fence.language !== "").length;
+  return untaggedFewer(fences, options.limit).map((fence) =>
+    finding(doc, "code-fence-language-mix", fence.start, { tagged, untagged: fences.length - tagged }),
+  );
+};
+
+export type PromptStyle = "prompt" | "bare" | undefined;
+
+/**
+ * Whether a shell block writes its commands after a prompt ($ npm install) or bare (npm install). A block that mixes
+ * prompted and unprompted lines shows a command with its output, and is neither. Comment lines (#) are skipped.
+ */
+export const promptStyleOf = (fence: CodeFence, prompts: readonly string[]): PromptStyle => {
+  const lines = fence.lines.map((line) => line.trim()).filter((line) => line !== "" && !line.startsWith("#"));
+  if (lines.length === 0) return undefined;
+  const prompted = lines.filter((line) => prompts.some((prompt) => line.startsWith(`${prompt} `))).length;
+  if (prompted === lines.length) return "prompt";
+  return prompted === 0 ? "bare" : undefined;
+};
+
+export const shellPrompt: Detector = (doc, options): Finding[] => {
+  const languages = new Set(patternsOf(doc, "shell-fence-language").map((language) => language.toLowerCase()));
+  const prompts = patternsOf(doc, "shell-prompt");
+  const shells = codeFences(doc.source).filter((fence) => languages.has(fence.language));
+  const prompted = shells.filter((fence) => promptStyleOf(fence, prompts) === "prompt");
+  const bare = shells.filter((fence) => promptStyleOf(fence, prompts) === "bare");
+  const minority = minorityOf(prompted, bare, options.limit);
+  const style = minority === prompted ? "prompt" : "bare";
+  return minority.map((fence) => finding(doc, "shell-prompt-mix", fence.start, { majority: style === "prompt" ? bare.length : prompted.length }));
+};
+
+/**
+ * A code span that names a command or an option: a flag (--force, -f) or a command with its arguments (npm install). A
+ * single plain word (net, init) is as often a package, an endpoint or a type as a command, and is left out.
+ */
+const COMMAND_WORD = /^[a-z][a-z0-9_-]*$/u;
+const FLAG = /^--?[A-Za-z][\w-]*$/u;
+
+export const isCommandName = (text: string): boolean => {
+  const words = text.trim().split(/\s+/u);
+  const first = words[0] ?? "";
+  return words.length === 1 ? FLAG.test(first) : COMMAND_WORD.test(first);
+};
+
+/** The heading without its links' text: [`net`](/pkg/net/) names the page it links to, not a command shown below. */
+export const withoutLinks = (heading: string): string => {
+  const pieces: string[] = [];
+  const state = { at: 0 };
+  while (state.at < heading.length) {
+    const open = heading.indexOf("[", state.at);
+    const close = open === -1 ? -1 : heading.indexOf("]", open);
+    if (close === -1) break;
+    pieces.push(heading.slice(state.at, open), " ");
+    state.at = close + 1 + targetLength(heading, close + 1);
+  }
+  pieces.push(heading.slice(state.at));
+  return pieces.join("");
+};
+
+/** The length of a link's target right after its text: (url), [label] or [] (a reference link); 0 when there is none. */
+const targetLength = (heading: string, at: number): number => {
+  const pair: Readonly<Record<string, string>> = { "(": ")", "[": "]" };
+  const closer = pair[heading.charAt(at)];
+  const end = closer === undefined ? -1 : heading.indexOf(closer, at);
+  return end === -1 ? 0 : end - at + 1;
+};
+
+/** The commands and options a heading names: its code spans that read as one, and bare flags (--force). */
+export const commandsIn = (heading: string): string[] => {
+  const spans = codeSpans(withoutLinks(heading)).map((span) => span.text);
+  const flags = heading
+    .replace(/`[^`]*`/gu, " ")
+    .split(/\s+/u)
+    .filter((word) => FLAG.test(word) && word.startsWith("--"));
+  return [...new Set([...spans.filter(isCommandName), ...flags])];
+};
+
+const collapse = (text: string): string => text.replace(/\s+/gu, " ");
+const OPTION_CHAR = /[A-Za-z0-9_-]/u;
+
+/** Whether the code holds the command as a whole word: --force is not --force-with-lease, init is not initial. */
+export const showsCommand = (code: string, command: string): boolean => {
+  const text = collapse(code);
+  const wanted = collapse(command.trim());
+  const state = { at: text.indexOf(wanted) };
+  while (state.at !== -1) {
+    const before = text.charAt(state.at - 1);
+    const after = text.charAt(state.at + wanted.length);
+    if (!OPTION_CHAR.test(before) && !OPTION_CHAR.test(after)) return true;
+    state.at = text.indexOf(wanted, state.at + 1);
+  }
+  return false;
+};
+
+type Section = { readonly heading: string; readonly start: number; readonly body: Span };
+
+const sectionsOf = (doc: ProseDocument): Section[] => {
+  const headings = doc.markup?.headings ?? [];
+  return headings.map((heading, index) => {
+    const next = headings.slice(index + 1).find((later) => later.depth <= heading.depth);
+    return { heading: doc.source.slice(heading.start, heading.end), start: heading.start, body: { start: heading.end, end: next?.start ?? doc.source.length } };
+  });
+};
+
+/** The code a section shows: its fenced blocks and its inline code spans. Empty when it shows none. */
+const codeOf = (doc: ProseDocument, fences: readonly CodeFence[], body: Span): string => {
+  const inFences = fences.filter((fence) => fence.start >= body.start && fence.start < body.end);
+  const outside = inFences.reduceRight(
+    (text, fence) => `${text.slice(0, fence.start - body.start)}${text.slice(Math.min(fence.end, body.end) - body.start)}`,
+    doc.source.slice(body.start, body.end),
+  );
+  return [...inFences.flatMap((fence) => fence.lines), ...codeSpans(outside).map((span) => span.text)].join("\n");
+};
+
+export const headingCommand: Detector = (doc): Finding[] => {
+  const fences = codeFences(doc.source);
+  return sectionsOf(doc).flatMap((section) => {
+    const commands = commandsIn(section.heading);
+    if (commands.length === 0) return [];
+    const code = codeOf(doc, fences, section.body);
+    if (code.trim() === "") return [];
+    return commands.filter((command) => !showsCommand(code, command)).map((command) => finding(doc, "heading-command-missing", section.start, { command }));
+  });
+};
+
+const ORDERED_ITEM = /^\s*\d{1,3}[.)]\s/u;
+/** What opens a statement: an article or a pronoun (The installer asks, You click, It opens). */
+const SUBJECT_OPENER = new Set(["DET", "PRON"]);
+/** What a subject opens with when it is a name or a noun phrase (Docker builds, Each user gets). */
+const SUBJECT_HEAD = new Set(["DET", "PRON", "PROPN", "NOUN", "ADJ"]);
+/** What may stand between the opener and the verb: the rest of the subject. */
+const SUBJECT_PART = new Set(["DET", "PRON", "PROPN", "NOUN", "ADJ", "ADP"]);
+/** What opens an instruction. The tagger reads a sentence-initial imperative as a noun, an adjective or a name (Click, Open, Restart). */
+const INSTRUCTION_OPENER = new Set(["VERB", "NOUN", "ADJ", "PROPN"]);
+const PREDICATE = new Set(["VERB", "AUX"]);
+const SKIPPED = new Set(["PUNCT", "NUM", "SYM", "X", "SPACE"]);
+/** Steps shorter than this are labels (1. Setup), not instructions or statements. */
+const MIN_STEP_TOKENS = 3;
+/** A list needs this many steps to have a form to keep. */
+const MIN_STEPS = 3;
+
+/** A verb in a finite, inflected form (starts, built): it has a subject before it. A base form (Save) may be an imperative's object. */
+const isInflected = (token: Token): boolean =>
+  token.lemma !== undefined && token.lemma !== "" && token.surface.toLowerCase() !== token.lemma && token.features?.["VerbForm"] !== "Part";
+
+/**
+ * A step written as a statement: a subject, then its verb. The subject opens with an article or a pronoun (The installer
+ * asks, You click), or it is a name or a noun whose verb is inflected (Docker builds). A noun before a base-form verb is
+ * not enough: the tagger reads Click and Press there as nouns (Click Save).
+ */
+export const isStatement = (tokens: readonly Token[]): boolean => {
+  const words = tokens.filter((token) => !SKIPPED.has(token.pos));
+  const [head, ...rest] = words;
+  if (head === undefined || words.length < MIN_STEP_TOKENS || !SUBJECT_HEAD.has(head.pos)) return false;
+  const verbAt = rest.findIndex((token) => PREDICATE.has(token.pos));
+  const verb = rest[verbAt];
+  if (verb === undefined || !rest.slice(0, verbAt).every((token) => SUBJECT_PART.has(token.pos))) return false;
+  // Punctuation before the verb is no subject: a label (Guests: the users who …) or an opening phrase (On the left bar, select …).
+  const interrupted = tokens.some((token) => token.pos === "PUNCT" && token.span.start > head.span.start && token.span.start < verb.span.start);
+  return !interrupted && (SUBJECT_OPENER.has(head.pos) || isInflected(verb));
+};
+
+type Step = { readonly start: number; readonly kind: "statement" | "instruction" | "other" };
+
+/** A step that opens with its verb: an instruction (Run the installer). */
+export const isInstruction = (tokens: readonly Token[]): boolean => INSTRUCTION_OPENER.has(tokens.find((token) => !SKIPPED.has(token.pos))?.pos ?? "");
+
+const kindOf = (tokens: readonly Token[]): Step["kind"] => {
+  if (isStatement(tokens)) return "statement";
+  return isInstruction(tokens) ? "instruction" : "other";
+};
+
+/** The steps of each numbered list: each item's first sentence, read as a statement or not. */
+const stepLists = (doc: ProseDocument): Step[][] =>
+  doc.lists
+    .filter((list) => ORDERED_ITEM.test(doc.source.slice(list.span.start, list.span.end)))
+    .map((list) =>
+      list.itemSpans.flatMap((item): Step[] => {
+        const sentence = doc.sentences.find((candidate) => candidate.span.start >= item.start && candidate.span.start < item.end);
+        // Only the sentence on the item's own line: a note paragraph under it (**NOTE:** …) is not the step.
+        const onItemLine = sentence !== undefined && !doc.source.slice(item.start, sentence.span.start).includes("\n");
+        return sentence?.tokens === undefined || !onItemLine ? [] : [{ start: sentence.span.start, kind: kindOf(sentence.tokens) }];
+      }),
+    )
+    .filter((steps) => steps.length >= MIN_STEPS);
+
+export const stepStatement: Detector = (doc, options): Finding[] =>
+  stepLists(doc).flatMap((steps) => {
+    const statements = steps.filter((step) => step.kind === "statement");
+    const instructions = steps.filter((step) => step.kind === "instruction");
+    // A procedure is a list most of whose steps are instructions; a numbered list of terms and definitions is not one.
+    const isProcedure = instructions.length * 2 > steps.length;
+    return isProcedure && statements.length > 0 && statements.length < instructions.length && statements.length <= options.limit
+      ? statements.map((step) => finding(doc, "step-statement-mix", step.start, { count: instructions.length }))
+      : [];
+  });

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/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/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

@@ -11,13 +11,14 @@ import { speakerLabels } from "./speaker-labels.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";
@@ -324,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(
@@ -347,10 +348,10 @@ const documentOf = (path: string, source: string, adapter: LanguageAdapter, team
   const tagged = sentences.some((sentence) => sentence.tokens !== undefined);
   const structure = lazyTree(adapter.structure, () => ({
     path,
-    source,
+    source: text,
     language: adapter.id,
     // テキストの文書は、ページの飾りを覆って読む。フッターの「Section 9」を木の節にしない。
-    outline: markdown ? outlineOf(root, source, syntax, emailLayout.replyQuotes) : textOutline(source, emailLayout.replyQuotes),
+    outline: markdown ? outlineOf(root, source, syntax, emailLayout.replyQuotes) : textOutline(text, emailLayout.replyQuotes),
     markdown,
     profile,
   }));
@@ -375,6 +376,7 @@ const documentOf = (path: string, source: string, adapter: LanguageAdapter, team
     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/pack-read.ts

@@ -0,0 +1,128 @@
+import { existsSync, readFileSync, readdirSync, realpathSync, statSync } from "node:fs";
+import { basename, join } from "node:path";
+import { parse } from "yaml";
+import { API_VERSION } from "../api.ts";
+import { isInside } from "../custom/module-path.ts";
+
+// A rule pack: a plugin written in YAML alone. Its folder holds a manifest (chaff-plugin.yaml, or a chaff field in
+// package.json), rules/*.yaml, lexicons/<language>/<list>.yaml and styles/*.yaml. Read here into the shape a code
+// plugin's default export has, so plugin-parse.ts checks a pack exactly as it checks a code plugin. Nothing is run.
+
+export const PACK_MANIFEST = "chaff-plugin.yaml";
+
+const isRecord = (value: unknown): value is Record<string, unknown> => typeof value === "object" && value !== null && !Array.isArray(value);
+
+const printed = (value: unknown): string => JSON.stringify(value) ?? typeof value;
+
+const firstLine = (error: unknown): string => (error instanceof Error ? error.message : String(error)).split("\n")[0] ?? "";
+
+/** A YAML file, or why it cannot be read, naming it as the pack's own path (rules/no-tbd.yaml). */
+const readYaml = (dir: string, path: string): { readonly value: unknown } | { readonly message: string } => {
+  try {
+    // A link inside the pack that points out of it would read a file the pack does not hold.
+    if (!isInside(realpathSync(dir), realpathSync(join(dir, path)))) return { message: `${path}: it links to a file outside the pack` };
+    return { value: parse(readFileSync(join(dir, path), "utf8")) };
+  } catch (error) {
+    return { message: `${path}: ${firstLine(error)}` };
+  }
+};
+
+const yamlFilesIn = (dir: string, folder: string): string[] => {
+  const full = join(dir, folder);
+  if (!existsSync(full) || !statSync(full).isDirectory()) return [];
+  return readdirSync(full)
+    .filter((file) => file.endsWith(".yaml") || file.endsWith(".yml"))
+    .toSorted((left, right) => left.localeCompare(right, "en"))
+    .map((file) => `${folder}/${file}`);
+};
+
+const foldersIn = (dir: string, folder: string): string[] => {
+  const full = join(dir, folder);
+  if (!existsSync(full) || !statSync(full).isDirectory()) return [];
+  return readdirSync(full)
+    .filter((name) => statSync(join(full, name)).isDirectory())
+    .toSorted((left, right) => left.localeCompare(right, "en"));
+};
+
+const packageJsonOf = (dir: string): Record<string, unknown> | undefined => {
+  const read = existsSync(join(dir, "package.json")) ? readYaml(dir, "package.json") : undefined;
+  return read !== undefined && "value" in read && isRecord(read.value) ? read.value : undefined;
+};
+
+/** The name in the folder's package.json, if it has one. */
+export const packageNameOf = (dir: string): string | undefined => {
+  const name = packageJsonOf(dir)?.["name"];
+  return typeof name === "string" ? name : undefined;
+};
+
+/**
+ * The manifest of a pack folder: chaff-plugin.yaml, else package.json's chaff field. undefined when the folder is not
+ * a pack (a code plugin, loaded by importing it). A manifest that cannot be read is reported, not taken for "not a pack".
+ */
+export const packManifestOf = (dir: string): { readonly manifest: Record<string, unknown> } | { readonly message: string } | undefined => {
+  if (existsSync(join(dir, PACK_MANIFEST))) {
+    const read = readYaml(dir, PACK_MANIFEST);
+    if ("message" in read) return read;
+    // An empty manifest only marks the folder; anything else must be a map.
+    if (read.value === null || read.value === undefined) return { manifest: {} };
+    return isRecord(read.value) ? { manifest: read.value } : { message: `${PACK_MANIFEST}: write a map (apiVersion: 1), not ${printed(read.value)}` };
+  }
+  const chaff = packageJsonOf(dir)?.["chaff"];
+  if (chaff === undefined) return undefined;
+  return isRecord(chaff) ? { manifest: chaff } : { message: `package.json: chaff must be a map ({ "apiVersion": 1 }), not ${printed(chaff)}` };
+};
+
+type Read<T> = { readonly value: T } | { readonly message: string };
+
+/** Every file's value in the order of the files, or the first that cannot be read. */
+const readAll = (dir: string, paths: readonly string[]): Read<unknown[]> =>
+  paths.reduce<Read<unknown[]>>(
+    (done, path) => {
+      if ("message" in done) return done;
+      const read = readYaml(dir, path);
+      return "message" in read ? read : { value: [...done.value, read.value] };
+    },
+    { value: [] },
+  );
+
+/** rules/*.yaml: each file holds one rule, or a list of them. */
+const rulesOf = (dir: string): Read<unknown[]> => {
+  const read = readAll(dir, yamlFilesIn(dir, "rules"));
+  return "message" in read ? read : { value: read.value.flatMap((value) => (Array.isArray(value) ? value.map((rule: unknown) => rule) : [value])) };
+};
+
+/** lexicons/<language>/<list>.yaml, as a code plugin writes its lexicons: { list: { language: entries } }. */
+const lexiconsOf = (dir: string): Read<Record<string, Record<string, unknown>>> =>
+  foldersIn(dir, "lexicons").reduce<Read<Record<string, Record<string, unknown>>>>(
+    (done, language) => {
+      if ("message" in done) return done;
+      const paths = yamlFilesIn(dir, `lexicons/${language}`);
+      const read = readAll(dir, paths);
+      if ("message" in read) return read;
+      const merged = paths.reduce<Record<string, Record<string, unknown>>>((acc, path, index) => {
+        const list = basename(path).replace(/\.ya?ml$/u, "");
+        return { ...acc, [list]: { ...acc[list], [language]: read.value[index] } };
+      }, done.value);
+      return { value: merged };
+    },
+    { value: {} },
+  );
+
+/** The pack as a plugin's default export: its name and API version from the manifest, its rules, lexicons and styles from its folders. */
+export const readPack = (dir: string, manifest: Readonly<Record<string, unknown>>, expectedName: string | undefined): Read<Record<string, unknown>> => {
+  const rules = rulesOf(dir);
+  if ("message" in rules) return rules;
+  const lexicons = lexiconsOf(dir);
+  if ("message" in lexicons) return lexicons;
+  const styles = readAll(dir, yamlFilesIn(dir, "styles"));
+  if ("message" in styles) return styles;
+  return {
+    value: {
+      apiVersion: manifest["apiVersion"] ?? API_VERSION,
+      name: manifest["name"] ?? expectedName,
+      rules: rules.value,
+      lexicons: lexicons.value,
+      styles: styles.value,
+    },
+  };
+};