chaffjs 0.16.0 → 0.18.0

package/src/opening-line.ts

@@ -0,0 +1,17 @@
+import { plainSource } from "./plain-source.ts";
+
+const FRONT_MATTER_FENCE = "---";
+/** An ATX heading; four spaces of indent make it a code line instead. */
+const HEADING = /^ {0,3}#{1,6}(?:\s|$)/u;
+
+/** The lines after a leading front matter block. */
+const bodyLines = (lines: readonly string[]): readonly string[] => {
+  const close = lines[0] === FRONT_MATTER_FENCE ? lines.indexOf(FRONT_MATTER_FENCE, 1) : -1;
+  return close === -1 ? lines : lines.slice(close + 1);
+};
+
+/** The line a document's body opens with (a letter's salutation), past front matter, blank lines and Markdown headings. */
+export const openingLine = (source: string): string | undefined =>
+  bodyLines(plainSource(source).split("\n"))
+    .find((line) => line.trim() !== "" && !HEADING.test(line))
+    ?.trim();

package/src/orthography.ts

@@ -2,6 +2,14 @@
 
 export const escapeRegExp = (text: string): string => text.replace(/[.*+?^${}()|[\]\\]/gu, "\\$&");
 
+/**
+ * 字に挟まれた ’ と、どこにあっても ʼ を ' にする（don’t → don't）。語彙表は ' で書くので、’ で書いた本文も同じ語に当てるため。
+ * 英語アダプタの解析器が同じ決めかたをする（chaff とアダプタは実行時の値を共有しないので、ここにも置く）。一字を一字に置き換えるので位置は変わらない。
+ */
+const APOSTROPHE = /(?<=[\p{L}\p{N}])’(?=\p{L})|ʼ/gu;
+
+export const straightApostrophes = (text: string): string => text.replace(APOSTROPHE, "'");
+
 /** text の中で word が現れる [始まり, 終わり) を、左から順に。大文字小文字を区別しないときは i で探す（位置は元の文字列のまま）。 */
 const spansOf = (text: string, word: string, ignoreCase: boolean): [number, number][] => {
   const pattern = new RegExp(escapeRegExp(word), ignoreCase ? "giu" : "gu");
@@ -55,7 +63,7 @@ const kindOf = (char: string | undefined, digitSide: "before-digit" | "after-dig
   return DIGIT.test(char) ? digitSide : undefined;
 };
 
-const isJapanese = (char: string | undefined): boolean => char !== undefined && JAPANESE.test(char);
+export const isJapanese = (char: string | undefined): boolean => char !== undefined && JAPANESE.test(char);
 
 /** japanese が日本語の字のとき、other の英字・数字の種類。 */
 const latinBeside = (japanese: string | undefined, other: string | undefined, digitSide: "before-digit" | "after-digit"): SpacingKind | undefined =>
@@ -132,7 +140,9 @@ const isOrdinalRun = (chars: readonly string[], index: number): boolean => {
 const MIN_CODE_GROUPS = 3;
 
 // 通達の「5－1－1」は全角の「－」でつなぐ。ハイフン「‐」やマイナス「−」も同じに読む。長音「ー」は仮名の一部なので入れない。
-const HYPHEN = /[-‐‑−－]/u;
+/** 正規表現の文字クラスに入れるハイフンの字。- は範囲の記号にならないよう \ を付ける。 */
+export const HYPHEN_CHARS = "\\-‐‑−－";
+const HYPHEN = new RegExp(`[${HYPHEN_CHARS}]`, "u");
 
 /** 数字をつなぐハイフンか。半角の - のほか、全角・和文のハイフンも。 */
 export const isHyphen = (char: string | undefined): boolean => char !== undefined && HYPHEN.test(char);
@@ -158,8 +168,7 @@ const isUncountedNumber = (chars: readonly string[], index: number): boolean =>
   return left === ORDINAL_PREFIX || (isJapanese(left) && isCode(chars, next));
 };
 
-const boundaryAt = (chars: readonly string[], index: number): Omit<Boundary, "offset"> | undefined => {
-  if (isUncountedNumber(chars, index)) return undefined;
+const candidateAt = (chars: readonly string[], index: number): Omit<Boundary, "offset"> | undefined => {
   const [left, right, after] = [chars[index], chars[index + 1], chars[index + 2]];
   const touching = latinBeside(left, right, "before-digit") ?? leftRunBeside(chars, index, right);
   if (touching !== undefined) return { kind: touching, spaced: false };
@@ -168,6 +177,12 @@ const boundaryAt = (chars: readonly string[], index: number): Omit<Boundary, "of
   return spaced === undefined ? undefined : { kind: spaced, spaced: true };
 };
 
+// isUncountedNumber は数字の並びを端まで読む。境目の候補でだけ聞けば、並びの字ごとではなく並びごとに一度で済む。
+const boundaryAt = (chars: readonly string[], index: number): Omit<Boundary, "offset"> | undefined => {
+  const candidate = candidateAt(chars, index);
+  return candidate === undefined || isUncountedNumber(chars, index) ? undefined : candidate;
+};
+
 /**
  * 文の中の境目を全部。offset は境目の位置（左の字の直後、UTF-16）。配列を作り直さずに一度なめる。
  * text は本文でないものを空白で覆った文、written は覆う前の同じ範囲。覆ってできた空白（リンクの「[」など）は
@@ -189,7 +204,7 @@ export const latinBoundaries = (text: string, written: string = text): Boundary[
  * 混ざっているとき、そろえるべき少数派。種類（英字・数字の前・数字の後ろ）ごとに数える。
  * 同数なら、文書が先に使った書き方をその文書の書き方とみなし、後から出た書き方を少数派にする。
  */
-export const minorityStyle = (boundaries: readonly Boundary[]): boolean | undefined => {
+export const minorityStyle = (boundaries: readonly { readonly spaced: boolean }[]): boolean | undefined => {
   const spaced = boundaries.filter((boundary) => boundary.spaced).length;
   const touching = boundaries.length - spaced;
   if (spaced === 0 || touching === 0) return undefined;

package/src/page-furniture.ts

@@ -1,5 +1,7 @@
 import type { Span } from "./plugin.ts";
 import { NO_OUTLINE, type Outline } from "./structure/build.ts";
+import { markdownFigures, textFigures } from "./text-figures.ts";
+import type { MarkdownNode } from "./markdown-node.ts";
 
 /** 改ページから、飾りの行を探しにいく行数。飾りと改ページのあいだには空行が数行入る。 */
 const REACH = 3;
@@ -41,5 +43,12 @@ export const pageFurniture = (source: string): Span[] => {
   });
 };
 
-/** テキストの文書の外形。見出しもコードも無く、ページの飾りだけを覆う。木を作る入口はどれもこれを使う。 */
-export const textOutline = (source: string): Outline => ({ ...NO_OUTLINE, opaque: pageFurniture(source) });
+/** テキストの文書の外形。見出しもコードも無く、ページの飾り・線で描いた図・メールの引用した返信だけを覆う。木を作る入口はどれもこれを使う。 */
+export const textOutline = (source: string, replyQuotes: readonly Span[] = []): Outline => ({
+  ...NO_OUTLINE,
+  opaque: [...pageFurniture(source), ...textFigures(source), ...replyQuotes],
+});
+
+/** 紙面の形で本文でないもの: テキストの文書のページの飾り（Markdown には改ページが無い）と、線で描いた図。 */
+export const layoutMasks = (root: MarkdownNode, source: string, markdown: boolean): Span[] =>
+  markdown ? markdownFigures(root, source) : [...pageFurniture(source), ...textFigures(source)];

package/src/paragraph-length.ts

@@ -0,0 +1,9 @@
+/**
+ * 段落が長すぎるか。文の数が上限を超え、しかも長さが「上限の数だけ普通の長さの文を並べた長さ」を超えるときだけ。
+ * 短い文をいくつ並べても、読み手が息をつけない壁にはならない。長さは adapter の単位（日本語は文字、英語は語）。
+ * fullSentence が無ければ、文の数だけで決める。
+ */
+export const isTooLongParagraph = (sentenceSizes: readonly number[], limit: number, fullSentence: number | undefined): boolean => {
+  const size = sentenceSizes.reduce((sum, sentence) => sum + sentence, 0);
+  return sentenceSizes.length > limit && (fullSentence === undefined || size > limit * fullSentence);
+};

package/src/plain-source.ts

@@ -1,5 +1,6 @@
 /**
  * The Markdown parser drops a leading BOM and reads a lone "\r" as a line break; the rest of chaff counts "\n" only.
  * Reading the file this way keeps every offset, line and column on the text the writer sees.
+ * Every leading BOM goes, so that running this twice (on reading, then in buildDocument) gives the same text as once.
  */
-export const plainSource = (raw: string): string => raw.replace(/^\uFEFF/u, "").replace(/\r\n?/gu, "\n");
+export const plainSource = (raw: string): string => raw.replace(/^\uFEFF+/u, "").replace(/\r\n?/gu, "\n");

package/src/plugin.ts

@@ -1,6 +1,8 @@
 // 言語アダプタと genre pack が依存してよい唯一の面。spec §6。
 // ここに実装を置かない。型だけを置く。
 
+import type { RuleGuide } from "./rule-guide.ts";
+
 export type Span = { readonly start: number; readonly end: number };
 
 /**
@@ -17,8 +19,15 @@ export type Sentence = {
    * tokens は全角どうしに挟まれた段落内の改行を除いた文字列から作るので、改行をまたぐ語の span は改行ごと覆い、surface より長い。
    */
   readonly wrapBreaks?: readonly Span[];
+  /**
+   * 文書と違う言語で書いた文（和文の中の英文、英文の中の和文）。adapter が入れる。無ければ文書の言語の文。
+   * 長さの rule はこの単位で数え、この言語の上限と比べる。
+   */
+  readonly embeddedLanguage?: EmbeddedLanguage;
 };
 
+export type EmbeddedLanguage = { readonly id: string; readonly lengthUnit: LengthUnit };
+
 /**
  * 品詞は Universal Dependencies の UPOS に統一する。アダプタ独自の体系を露出させない。
  * features は UD の FEATS。「受動か」のように品詞だけでは足りず、かつ言語ごとに
@@ -72,7 +81,11 @@ export type AdapterCapabilities = {
 };
 
 /** prepare に渡す要求。動く rule が要らないものの代金を払わせない。 */
-export type AdapterNeeds = { readonly pos: boolean };
+export type AdapterNeeds = {
+  readonly pos: boolean;
+  /** Token features that cost the adapter extra work (LongVowelEnding asks the dictionary about each katakana word). Only the running rules' are asked for. */
+  readonly features?: readonly string[];
+};
 
 export type LanguageAdapter = {
   readonly kind: "language";
@@ -204,6 +217,10 @@ export type Section = {
   /** 見出しの深さ。見出しより前の導入部は 0。 */
   readonly depth: number;
   readonly heading: string;
+  /** 見出しを文と同じ解析器で語に分けたもの。文が tokens を持つときだけ入る。 */
+  readonly headingTokens?: readonly Token[];
+  /** 見出しの頭の番号の札（「例 3：」「1.」「第2章」「Step 3:」）を除いた題。札が無ければ見出しのまま。 */
+  readonly unlabeledHeading?: string;
   readonly span: Span;
   readonly sentences: readonly Sentence[];
   /** この節に含まれる強調（Markdown の ** **）の数。 */
@@ -322,6 +339,34 @@ export type ProseDocument = {
   readonly profile?: DocumentProfile | undefined;
   /** 本文でないもの（コード・HTML・強調の印）を同じ長さの空白で覆った source。位置は source と同じ。 */
   readonly prose?: string | undefined;
+  /** メールの引用した返信（前置きの行と「> 」の行）。ほかの人の言葉なので、見出しにも木にも入れない。 */
+  readonly replyQuotes?: readonly Span[] | undefined;
+  /** 記法の手がかり（見出し・画像・リンク）。記法を読む rule だけが触れ、触れたときに作る。 */
+  readonly markup?: Markup | undefined;
+};
+
+/** 見出し 1 つ。text は属性（`{#id}`）を外した言葉。 */
+export type MarkupHeading = { readonly depth: number; readonly text: string; readonly start: number; readonly end: number };
+
+/** 画像 1 つ。alt は代替テキスト。HTML の `<img>` で alt 属性が無ければ undefined。 */
+export type MarkupImage = { readonly alt: string | undefined; readonly start: number; readonly end: number };
+
+/** リンクの行き先 1 つ（`[text](url)` と、参照の定義 `[label]: url`）。 */
+export type MarkupLink = { readonly destination: string; readonly start: number; readonly end: number };
+
+/**
+ * 文書の記法。Markdown でない文書（.txt）は markdown が false で、見出し・画像・リンクを持たず、texts が文書全体。
+ * 位置はすべて doc.source の上。
+ */
+export type Markup = {
+  readonly markdown: boolean;
+  readonly headings: readonly MarkupHeading[];
+  readonly images: readonly MarkupImage[];
+  readonly links: readonly MarkupLink[];
+  /** 書き手が付けたページ内の名前（見出しの `{#id}`、HTML の id と name）。 */
+  readonly ids: ReadonlySet<string>;
+  /** 読み手に字のまま見える範囲（リンクの外のテキスト）。 */
+  readonly texts: readonly Span[];
 };
 
 export type Severity = "error" | "warning" | "info";
@@ -346,6 +391,31 @@ export type DetectorOptions = {
   readonly lexicon?: Lexicon | undefined;
   /** 見る範囲。opening は冒頭 2 段落、closing は最後の節、whole は全体。 */
   readonly where?: string | undefined;
+  /** 普通の長さの文 1 つの長さ（adapter の単位）。段落の長さを文の数と一緒に見る rule だけが持つ。 */
+  readonly fullSentence?: number | undefined;
+  /** 文書と違う言語で書いた文の上限。その言語の段から解決済み。rule がその言語の段を持たなければ無い。 */
+  readonly embeddedLimits?: Readonly<Record<string, number>> | undefined;
+  /** The rule's options (RuleDefinition.options), each at the value the settings chose or its default. Only a rule with options has them. */
+  readonly settings?: Readonly<Record<string, OptionValue>> | undefined;
+  /** A custom rule's spec (RuleDefinition.custom). */
+  readonly custom?: CustomSpec | undefined;
+};
+
+/** The value of one rule option: a choice, a count, or a list of words. */
+export type OptionValue = string | number | readonly string[];
+
+/**
+ * One option a rule takes, beyond its level. The rule's YAML declares it; a team sets it under options in chaff.yaml.
+ * choice takes one of choices, count a whole number of 1 or more, words a list of words.
+ */
+export type RuleOption = {
+  readonly kind: "choice" | "count" | "words";
+  readonly choices: readonly string[];
+  readonly default: OptionValue;
+  /** What the option decides, in plain words. */
+  readonly about: Localized;
+  /** What each choice means, in plain words. Only a choice has them. */
+  readonly choiceNames: Readonly<Record<string, Localized>>;
 };
 
 export type Detector = (doc: ProseDocument, options: DetectorOptions) => Finding[];
@@ -356,6 +426,10 @@ export type Level = "strict" | "normal" | "relaxed" | "off";
 
 export type LevelTable = Readonly<Partial<Record<Exclude<Level, "off">, number>>>;
 
+export type LevelSets = "limit" | "severity";
+
+export type LanguageLevels = { readonly levels: LevelTable; readonly by_genre: Readonly<Record<string, LevelTable>> };
+
 export type RuleDefinition = {
   readonly id: string;
   readonly layer: "L1" | "L2" | "L3" | "L4";
@@ -366,11 +440,17 @@ export type RuleDefinition = {
   readonly message: Localized;
   /** 見つけ方ごとの message（Finding の variant で引く）。ほとんどの rule は持たない。 */
   readonly messages: Readonly<Record<string, Localized>>;
+  /** How a placeholder in name, why or how_to_fix reads where no finding fills it (explain, the rule reference). */
+  readonly placeholders?: Readonly<Record<string, Localized>>;
   /** 4 語と数値の対応。2 つ以上。未定義の段は normal に落ちる。spec §18.1。
    *  言語別の閾値を持つ rule（max-sentence-length）は、読み込み時に言語で平坦化済み。 */
   readonly levels: LevelTable;
+  /** What a level changes: the limit a detector counts to, or, for a rule with nothing to count, the severity of its findings. */
+  readonly level_sets: LevelSets;
   /** ジャンル別の上書き。"business" は business/* 全部に効き、"business/email" が勝つ。spec §9。 */
   readonly by_genre: Readonly<Record<string, LevelTable>>;
+  /** 読み込んだ言語以外の levels と by_genre。文書と違う言語で書いた文（和文の中の英文）の上限に使う。 */
+  readonly other_languages?: Readonly<Record<string, LanguageLevels>>;
   readonly how_to_find: string;
   readonly word_list: string | undefined;
   /** word_list のほかに detector が名前で引く語彙表。どれかが無い言語では rule を動かさない。 */
@@ -378,14 +458,40 @@ export type RuleDefinition = {
   /** L4 のみ。LLM に渡す決まり。言語別。 */
   readonly what_to_check: Localized | undefined;
   readonly where: string | undefined;
+  /** 普通の長さの文 1 つの長さ。言語で単位が違うので、levels と同じく読み込み時に言語で平坦化済み。 */
+  readonly full_sentence: number | undefined;
   /** adapter に要る capability。"pos" / "lemma"。満たさなければ動かさない。spec §16。 */
   readonly requires: readonly string[];
   /** 使えるなら用意してほしい capability（"pos"）。requires と違い、満たせなくても動かす（品詞が無ければ文字だけで見る）。 */
   readonly uses: readonly string[];
+  /** Token features the rule reads that the adapter computes only when asked (AdapterNeeds.features). */
+  readonly token_features?: readonly string[];
   /** 複合シグナル。ここに並べた rule のうち何本が出たかを見る。spec §20.2。 */
   readonly from: readonly string[];
   /** 動かす言語。未指定は全言語。「ですます調」のように言語に固有の rule が使う。 */
   readonly languages: readonly string[] | undefined;
   readonly use_for: readonly string[];
   readonly severity: Severity;
+  /** Options beyond the level (the direction and length for katakana-long-vowel). Most rules have none. */
+  readonly options?: Readonly<Record<string, RuleOption>>;
+  /** A rule a team defined under custom_rules in chaff.yaml: what it looks for. Built-in rules have none. */
+  readonly custom?: CustomSpec;
+  /** What the rule reference tells a reader who is not an engineer: its group, one line, a before and after. */
+  readonly guide?: RuleGuide;
+};
+
+/** One token's condition in a custom rule's run of tokens. Each part written must hold; pos lists the tags that match. */
+export type TokenCondition = {
+  readonly pos?: readonly string[] | undefined;
+  readonly base?: string | undefined;
+  readonly surface?: string | undefined;
 };
+
+/**
+ * What a team's rule looks for. words: spellings to avoid, each with the one to use (or none, to only point at it).
+ * pattern: a regular expression, checked before it runs. tokens: a run of tokens from the language adapter.
+ */
+export type CustomSpec =
+  | { readonly type: "words"; readonly words: readonly { readonly avoid: string; readonly use: string }[] }
+  | { readonly type: "pattern"; readonly pattern: string; readonly flags: string }
+  | { readonly type: "tokens"; readonly tokens: readonly TokenCondition[] };

package/src/profile/for-file.ts

@@ -4,6 +4,7 @@ import type { DocumentProfile } from "../plugin.ts";
 import { presetProfile } from "../genre-load.ts";
 import { loadProfiles } from "./load.ts";
 import { chooseProfile } from "./select.ts";
+import { plainSource } from "../plain-source.ts";
 
 type ProfileSettings = Pick<Config, "profile" | "byPath" | "baseDir">;
 
@@ -13,6 +14,7 @@ export const profileFor = (config: ProfileSettings, path: string, source: string
     byPath: applyByPath(config.byPath, config.baseDir, path).profile,
     config: config.profile,
     genre: genre === undefined ? undefined : presetProfile(genre),
-    source,
+    // 行頭で数える検出は、CR だけの改行では 1 行に見える。
+    source: plainSource(source),
     language,
   })?.profile;

package/src/quoted-span.ts

@@ -4,7 +4,7 @@ import type { Sentence, Span } from "./plugin.ts";
 type Marks = Readonly<Record<string, string>>;
 
 /** 鉤括弧。日本語の引用と題名。 */
-export const KAGI_MARKS: Marks = { "「": "」", "『": "』" };
+const KAGI_MARKS: Marks = { "「": "」", "『": "』" };
 
 /**
  * 引用符も含めた、人の言葉を引く印。英語の "…" は開きと閉じが同じ字なので、開いている間に来たら閉じと読む。
@@ -13,15 +13,21 @@ export const KAGI_MARKS: Marks = { "「": "」", "『": "』" };
 export const QUOTATION_MARKS: Marks = { ...KAGI_MARKS, "“": "”", '"': '"' };
 
 type Open = { readonly closer: string; readonly at: number };
-type Scan = { readonly open: readonly Open[]; readonly spans: readonly Span[] };
+/** 1 回の読みの中だけで足し引きする。字ごとに配列を作り直すと、括弧が何万もある文で二乗に遅くなる。 */
+type Scan = { readonly open: Open[]; readonly spans: Span[] };
 
 const step =
   (marks: Marks) =>
   (scan: Scan, char: string, at: number): Scan => {
     const last = scan.open.at(-1);
-    if (last !== undefined && last.closer === char) return { open: scan.open.slice(0, -1), spans: [...scan.spans, { start: last.at + 1, end: at }] };
+    if (last !== undefined && last.closer === char) {
+      scan.open.pop();
+      scan.spans.push({ start: last.at + 1, end: at });
+      return scan;
+    }
     const closer = marks[char];
-    return closer === undefined ? scan : { open: [...scan.open, { closer, at }], spans: scan.spans };
+    if (closer !== undefined) scan.open.push({ closer, at });
+    return scan;
   };
 
 /**

package/src/reasons.ts

@@ -14,6 +14,9 @@ export type Reasons = {
   readonly unreadStructure: (clauses: number, units: number) => string;
   readonly noDetector: (name: string) => string;
   readonly noLexicon: (language: string, list: string) => string;
+  readonly noHeadings: string;
+  readonly patternTimeout: (budgetMs: number) => string;
+  readonly notMarkdown: string;
 };
 
 const CAPABILITY_NAME: Texts<Readonly<Record<string, string>>> = {
@@ -35,6 +38,9 @@ export const REASONS: Texts<Reasons> = {
       `条項の番号が本文に ${String(clauses)} 個あるのに、番号として読めたのは ${String(units)} 個のため（深い字下げや、行が本文につながった文書）`,
     noDetector: (name) => `検出器 ${name} がないため`,
     noLexicon: (language, list) => `${language} の語彙表 ${list} が無いため`,
+    noHeadings: "表題より下の見出しが無いため",
+    patternTimeout: (budgetMs) => `正規表現が ${String(budgetMs)} ms で終わらなかったため（chaff.yaml の pattern を単純にしてください）`,
+    notMarkdown: "Markdown の文書ではないため",
   },
   en: {
     otherLanguage: (language) => `not a rule for ${language}`,
@@ -49,5 +55,8 @@ export const REASONS: Texts<Reasons> = {
       `the text has ${String(clauses)} clause numbers but only ${String(units)} ${formFor(units, "was read as a numbered line", "were read as numbered lines")} (deep indents, or lines run into the text)`,
     noDetector: (name) => `no detector named ${name}`,
     noLexicon: (language, list) => `the ${language} package has no word list ${list}`,
+    noHeadings: "the document has no headings below its title",
+    patternTimeout: (budgetMs) => `the pattern did not finish within ${String(budgetMs)} ms (simplify the pattern in chaff.yaml)`,
+    notMarkdown: "the document is not Markdown",
   },
 };

package/src/reference-lists.ts

@@ -0,0 +1,91 @@
+import type { Span } from "./plugin.ts";
+
+/**
+ * 文献一覧の範囲。見出しの語（参考文献、References）で見つけ、構造で範囲を決める。
+ * Markdown の見出しなら、次の同じ深さか浅い見出しまで。見出しの語だけの段落（HTML から写した文書）なら、すぐ後に続く箇条書きだけ。
+ * 箇条書きが続かなければ文献一覧とは言えないので、何も返さない。
+ */
+type Line = { readonly text: string; readonly start: number; readonly end: number };
+
+const ATX_HEADING = /^ {0,3}(#{1,6})(?:[ \t](.*))?$/u;
+// 文献の番号（- [1]、1.、[1]）で始まる行。
+const LIST_ITEM = /^ {0,3}(?:[-*+]|\d{1,4}[.)]|\[\d{1,4}\])[ \t]/u;
+const CONTINUATION = /^[ \t]+\S/u;
+// 見出しの前の節番号（7.、7.1、VII.）、周りの強調、後ろの閉じの # とコロン。
+const SECTION_NUMBER = /^(?:\d+(?:\.\d+)*\.?|[IVXLC]+\.)\s+/u;
+const EMPHASIS_MARKS = ["**", "__"] as const;
+const CLOSING = new Set([" ", "\t", "#", ":", "："]);
+
+const withoutClosing = (text: string): string => {
+  const characters = [...text];
+  return characters.slice(0, characters.findLastIndex((character) => !CLOSING.has(character)) + 1).join("");
+};
+
+const linesOf = (source: string): Line[] =>
+  source.split("\n").reduce<Line[]>((lines, text) => {
+    const start = (lines.at(-1)?.end ?? -1) + 1;
+    lines.push({ text, start, end: start + text.length });
+    return lines;
+  }, []);
+
+const withoutEmphasis = (text: string): string => {
+  const mark = EMPHASIS_MARKS.find((candidate) => text.length > candidate.length * 2 && text.startsWith(candidate) && text.endsWith(candidate));
+  return mark === undefined ? text : text.slice(mark.length, -mark.length);
+};
+
+const isBlank = (line: Line | undefined): boolean => line === undefined || line.text.trim() === "";
+
+const headingWord = (text: string): string => {
+  const plain = withoutEmphasis(withoutClosing(text).trim());
+  return withoutClosing(plain.replace(SECTION_NUMBER, "")).trim().toLowerCase();
+};
+
+const levelOf = (line: Line): number | undefined => ATX_HEADING.exec(line.text)?.[1]?.length;
+
+/** from 以降で最初に test を満たす行。無ければ lines.length。先頭から数え直すと、見出しの多い文書で行数の 2 乗になる。 */
+const firstFrom = (lines: readonly Line[], from: number, test: (line: Line) => boolean): number => {
+  for (let index = from; index < lines.length; index += 1) {
+    const line = lines[index];
+    if (line !== undefined && test(line)) return index;
+  }
+  return lines.length;
+};
+
+/** Markdown の見出しの節の終わり: 次の同じ深さか浅い見出しの手前。無ければ文書の終わり。 */
+const sectionEnd = (lines: readonly Line[], at: number, level: number): number =>
+  firstFrom(lines, at + 1, (line) => (levelOf(line) ?? Number.POSITIVE_INFINITY) <= level);
+
+const isOutsideList = (line: Line): boolean => !isBlank(line) && !LIST_ITEM.test(line.text) && !CONTINUATION.test(line.text);
+
+/** from の後の最初の中身の行から続く箇条書きの終わり（最後の中身の行の次）。最初の中身が項目でなければ from。 */
+const listEnd = (lines: readonly Line[], from: number): number => {
+  const first = firstFrom(lines, from, (line) => !isBlank(line));
+  if (!LIST_ITEM.test(lines[first]?.text ?? "")) return from;
+  const stop = firstFrom(lines, first + 1, isOutsideList);
+  return first + lines.slice(first, stop).findLastIndex((line) => !isBlank(line)) + 1;
+};
+
+const standsAlone = (lines: readonly Line[], at: number): boolean => (at === 0 || isBlank(lines[at - 1])) && isBlank(lines[at + 1]);
+
+/** 見出しの行 at から、文献一覧の終わりの行（含まない）。文献一覧の見出しでなければ undefined。 */
+const blockEnd = (lines: readonly Line[], at: number, headings: ReadonlySet<string>): number | undefined => {
+  const line = lines[at];
+  if (line === undefined) return undefined;
+  const level = levelOf(line);
+  if (level !== undefined) return headings.has(headingWord(ATX_HEADING.exec(line.text)?.[2] ?? "")) ? sectionEnd(lines, at, level) : undefined;
+  if (!headings.has(headingWord(line.text)) || !standsAlone(lines, at)) return undefined;
+  const end = listEnd(lines, at + 1);
+  return end === at + 1 ? undefined : end;
+};
+
+export const referenceListSpans = (source: string, headingWords: readonly string[]): Span[] => {
+  const headings = new Set(headingWords.map((word) => word.toLowerCase()));
+  const lines = linesOf(source);
+  const spans: Span[] = [];
+  lines.forEach((line, at) => {
+    if ((spans.at(-1)?.end ?? -1) >= line.start) return;
+    const end = blockEnd(lines, at, headings);
+    if (end !== undefined) spans.push({ start: line.start, end: lines[end - 1]?.end ?? line.end });
+  });
+  return spans;
+};

package/src/render/explain.ts

@@ -1,7 +1,10 @@
-import { definedLevels, resolve } from "../levels.ts";
-import { localized } from "./text.ts";
-import { uiLanguageOf, type Texts } from "../ui.ts";
+import { definedLevels, resolve, severityAt } from "../levels.ts";
+import { readableText } from "./text.ts";
+import { SEVERITY_NAME } from "./severity-name.ts";
+import { uiLanguageOf, type Texts, type UiLanguage } from "../ui.ts";
 import type { Level, RuleDefinition } from "../plugin.ts";
+import { optionLines } from "./options.ts";
+import type { OptionLayer } from "../rule-options.ts";
 
 const TEXT: Texts<{
   readonly off: string;
@@ -9,8 +12,12 @@ const TEXT: Texts<{
   readonly genreNote: (genre: string, others: string) => string;
   readonly experimental: string;
   readonly howToFix: string;
+  readonly example: string;
+  readonly definedIn: string;
   readonly values: (unit: string) => string;
+  readonly severities: string;
   readonly now: (level: string) => string;
+  readonly from: (source: string) => string;
   readonly change: (id: string) => string;
 }> = {
   ja: {
@@ -19,8 +26,12 @@ const TEXT: Texts<{
     genreNote: (genre, others) => `この数字は ${genre} のものです。ほかに ${others} で別の数字を持っています。`,
     experimental: "このルールはまだ試験中で、既定では動きません（--experimental で動きます）。",
     howToFix: "直しかた",
+    example: "例",
+    definedIn: "このルールはチームが chaff.yaml の custom_rules で決めたものです。",
     values: (unit) => `設定できる値（単位: ${unit}）:`,
+    severities: "設定できる値（数える上限は無く、指摘の重さが変わります）:",
     now: (level) => `いまは ${level} です。`,
+    from: (source) => `（${source} で決めています）`,
     change: (id) => `変える:  npx chaff relax ${id} --why "理由"`,
   },
   en: {
@@ -29,16 +40,24 @@ const TEXT: Texts<{
     genreNote: (genre, others) => `These numbers are for ${genre}. ${others} have numbers of their own.`,
     experimental: "This rule is still experimental and does not run by default (--experimental runs it).",
     howToFix: "How to fix",
+    example: "Example",
+    definedIn: "The team defined this rule under custom_rules in chaff.yaml.",
     values: (unit) => `Levels (unit: ${unit}):`,
+    severities: "Levels (there is no limit to count to; a level sets how a finding is marked):",
     now: (level) => `Now: ${level}.`,
+    from: (source) => ` (set by ${source})`,
     change: (id) => `Change it:  npx chaff relax ${id} --why "reason"`,
   },
 };
 
-const levelLine = (rule: RuleDefinition, level: Level, current: Level, genre: string | undefined, off: string): string => {
+/** What a level holds: the limit a detector counts to, or the severity a rule with nothing to count gives. */
+const valueAt = (rule: RuleDefinition, level: Exclude<Level, "off">, genre: string | undefined, ui: UiLanguage): string =>
+  rule.level_sets === "severity" ? SEVERITY_NAME[ui][severityAt(rule, level, genre)] : String(resolve(rule, level, genre).limit);
+
+const levelLine = (rule: RuleDefinition, level: Level, current: Level, genre: string | undefined, ui: UiLanguage): string => {
   const mark = level === current ? "→" : " ";
   const name = level.padEnd(9);
-  return level === "off" ? `  ${mark} ${name}${off}` : `  ${mark} ${name}${resolve(rule, level, genre).limit}`;
+  return level === "off" ? `  ${mark} ${name}${TEXT[ui].off}` : `  ${mark} ${name}${valueAt(rule, level, genre, ui)}`;
 };
 
 /** ジャンルで数字が変わる rule は、それを言わないと「設定したのに効かない」に見える。 */
@@ -48,23 +67,38 @@ const genreNote = (rule: RuleDefinition, genre: string | undefined, text: (typeo
   return ["", `  ${text.genreNote(genre ?? text.defaultGenre, others.join(" / "))}`];
 };
 
+/** A team's rule shows its example, before and after, and says where it was defined. */
+const exampleLines = (rule: RuleDefinition, language: string, text: (typeof TEXT)["ja"]): string[] => {
+  const examples = rule.guide?.examples ?? {};
+  const example = examples[language] ?? examples["en"] ?? Object.values(examples)[0];
+  if (rule.custom === undefined || example === undefined) return [];
+  return ["", `  ${text.example}:  ${example.before}`, `      →  ${example.after}`, "", `  ${text.definedIn}`];
+};
+
+/** Where the rule's settings come from: the option layers, strongest first, and the source of its level when a style set it. */
+export type ExplainSettings = { readonly optionLayers?: readonly OptionLayer[]; readonly levelFrom?: string | undefined };
+
 /** rule の意図と根拠を読む。指摘に納得できないときの入口。 */
-export const renderExplain = (rule: RuleDefinition, current: Level, language: string, unit: string, genre?: string): string => {
-  const text = TEXT[uiLanguageOf(language)];
+export const renderExplain = (rule: RuleDefinition, current: Level, language: string, unit: string, genre?: string, settings: ExplainSettings = {}): string => {
+  const { optionLayers = [], levelFrom } = settings;
+  const ui = uiLanguageOf(language);
+  const text = TEXT[ui];
   const experimental = rule.status === "experimental" ? [`  ${text.experimental}`] : [];
   return [
     "",
-    `  ${localized(rule.name, language)}   (${rule.id})`,
+    `  ${readableText(rule, rule.name, language)}   (${rule.id})`,
     "",
-    `  ${localized(rule.why, language)}`,
+    `  ${readableText(rule, rule.why, language)}`,
     "",
-    `  ${text.howToFix}: ${localized(rule.how_to_fix, language)}`,
+    `  ${text.howToFix}: ${readableText(rule, rule.how_to_fix, language)}`,
+    ...exampleLines(rule, language, text),
     "",
-    `  ${text.values(unit)}`,
-    ...definedLevels(rule).map((level) => levelLine(rule, level, current, genre, text.off)),
+    `  ${rule.level_sets === "severity" ? text.severities : text.values(unit)}`,
+    ...definedLevels(rule).map((level) => levelLine(rule, level, current, genre, ui)),
     ...genreNote(rule, genre, text),
+    ...optionLines(rule, optionLayers, language),
     "",
-    `  ${text.now(current)}`,
+    `  ${text.now(current)}${levelFrom === undefined ? "" : text.from(levelFrom)}`,
     ...experimental,
     "",
     `  ${text.change(rule.id)}`,