chaffjs 0.17.0 → 0.19.0

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。「受動か」のように品詞だけでは足りず、かつ言語ごとに
@@ -53,6 +62,10 @@ export type LexiconEntry = {
   readonly instead_of?: string | undefined;
   /** 語が、かかる語のどちら側に立つか。語順が言語で違うものを語彙表が言う（範囲の「で」は前、"in" は後ろ）。 */
   readonly position?: "before" | "after" | undefined;
+  /** How to rewrite this one phrase, in the lexicon's language. chaff fix-plan prints it next to the rule's own direction. */
+  readonly rewrite?: string | undefined;
+  /** 語の組の名前。同じ組の語どうしだけを比べる rule が使う（対応する OS を言う語と、対応する言語を言う語を分ける）。 */
+  readonly group?: string | undefined;
   /** pattern を adapter が語に分けたもの。品詞が読めるときだけ core が入れる。語彙表を書く側は書かない。 */
   readonly tokens?: readonly Token[] | undefined;
 };
@@ -72,7 +85,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";
@@ -175,8 +192,15 @@ export type StructurePatterns = {
   readonly continuesSentence?: (number: string, rest: string) => boolean;
   /** 数の書き方（「二十二」「3」）を数にする。相対の参照の「前二項」「前条第二項」が使う。 */
   readonly number?: (text: string) => number | undefined;
+  /** text の at のすぐ前に書いた文書の名前（「民法の」「…(平成二十年厚生労働省告示第五十九号)」「この規則の」）。名前が無ければ undefined。 */
+  readonly namedDocument?: DocumentNamer;
 };
 
+/** 位置のすぐ前に書いた文書の名前。self はこの文書を指す名前（「この規則」「本規約」）。 */
+export type NamedDocument = { readonly name: string; readonly self: boolean };
+
+export type DocumentNamer = (text: string, at: number) => NamedDocument | undefined;
+
 export type StructureKind = "doc" | "section" | "chapter" | "article" | "item" | "definition" | "reference" | "obligation" | "quantity" | "date";
 
 /** 番地の付いた木の節点。すべて元の文書の位置（UTF-16）と行を持つ。 */
@@ -206,6 +230,8 @@ export type Section = {
   readonly heading: string;
   /** 見出しを文と同じ解析器で語に分けたもの。文が tokens を持つときだけ入る。 */
   readonly headingTokens?: readonly Token[];
+  /** 見出しの頭の番号の札（「例 3：」「1.」「第2章」「Step 3:」）を除いた題。札が無ければ見出しのまま。 */
+  readonly unlabeledHeading?: string;
   readonly span: Span;
   readonly sentences: readonly Sentence[];
   /** この節に含まれる強調（Markdown の ** **）の数。 */
@@ -216,8 +242,8 @@ export type Section = {
 
 export type Paragraph = { readonly span: Span; readonly sentences: readonly Sentence[] };
 
-/** 箇条書き 1 つ。項目は項目の文字数で持つ。長さのばらつきしか見ないため。 */
-export type BulletList = { readonly span: Span; readonly items: readonly number[] };
+/** 箇条書き 1 つ。items は項目の文字数（空白を除く）、itemSpans は同じ順の項目の範囲。 */
+export type BulletList = { readonly span: Span; readonly items: readonly number[]; readonly itemSpans: readonly Span[] };
 
 /**
  * detector に渡る唯一の入り口。core が I/O を済ませてから呼ぶ。
@@ -324,6 +350,36 @@ export type ProseDocument = {
   readonly profile?: DocumentProfile | undefined;
   /** 本文でないもの（コード・HTML・強調の印）を同じ長さの空白で覆った source。位置は source と同じ。 */
   readonly prose?: string | undefined;
+  /** 位置のすぐ前に書いた文書の名前を読む。言語パッケージが読めなければ無い。 */
+  readonly namedDocument?: DocumentNamer | 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";
@@ -350,6 +406,29 @@ export type DetectorOptions = {
   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[];
@@ -360,6 +439,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";
@@ -370,11 +453,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 を動かさない。 */
@@ -388,10 +477,38 @@ export type RuleDefinition = {
   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, or a plugin ships: what it looks for. Built-in rules have none. */
+  readonly custom?: CustomSpec;
+  /** The name of the plugin that ships the rule, which is also its id's prefix (foo in foo/rule-id). Only a plugin's rules have it. */
+  readonly plugin?: string;
+  /** 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.
+ * module: a detector the team wrote in JavaScript; module as written in chaff.yaml, file where it resolved to.
+ */
+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[] }
+  | { readonly type: "module"; readonly module: string; readonly file: string };

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

@@ -13,15 +13,21 @@ 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

@@ -6,6 +6,7 @@ export type Reasons = {
   readonly otherLanguage: (language: string) => string;
   readonly noCapability: (capability: string) => string;
   readonly noTags: string;
+  readonly unreadTags: string;
   readonly semantic: string;
   readonly experimental: string;
   readonly turnedOff: string;
@@ -14,6 +15,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>>> = {
@@ -26,6 +30,7 @@ export const REASONS: Texts<Reasons> = {
     otherLanguage: (language) => `${language} 向けの rule ではないため`,
     noCapability: (capability) => `この言語では${CAPABILITY_NAME.ja[capability] ?? capability}が使えないため`,
     noTags: "アダプタが品詞を返さなかったため",
+    unreadTags: "言語のパッケージがこの文書を読めなかったため（品詞の取れない段落があります）",
     semantic: "意味を読む検査のため（npx chaff test で動きます）",
     experimental: "まだ試験中のため",
     turnedOff: "設定で止めているため",
@@ -35,11 +40,15 @@ 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}`,
     noCapability: (capability) => `${CAPABILITY_NAME.en[capability] ?? capability} is not available for this language`,
     noTags: "the language package returned no parts of speech",
+    unreadTags: "the language package could not read this document (some paragraphs have no parts of speech)",
     semantic: "it reads meaning; npx chaff test runs it",
     experimental: "still experimental",
     turnedOff: "turned off in the settings",
@@ -49,5 +58,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/compact.ts

@@ -1,4 +1,4 @@
-import type { RuleDefinition } from "../plugin.ts";
+import type { Finding, RuleDefinition } from "../plugin.ts";
 import type { RunResult } from "../run.ts";
 import { messageOf } from "./text.ts";
 import { counted } from "./plural.ts";
@@ -12,14 +12,24 @@ const TALLY: Texts<{ readonly findings: (n: number) => string; readonly notRun:
   en: { findings: (n) => counted(n, "finding"), notRun: (n) => `${counted(n, "rule")} not run`, separator: ", " },
 };
 
+const POSITION_MIN_WIDTH = 8;
+const SEVERITY_WIDTH = 8;
+
+const positionOf = (finding: Finding): string => `${String(finding.line)}:${String(finding.column)}`;
+
+/** 「行:桁」の列の幅。一番長い位置の後ろにも空白を 1 つ残す。grep や awk が重さの語と区切れるように。 */
+export const positionWidthOf = (findings: readonly Finding[]): number =>
+  findings.reduce((width, finding) => Math.max(width, positionOf(finding).length + 1), POSITION_MIN_WIDTH);
+
 /** エンジニア向け。1 件 2 行。 */
 export const renderCompact = (header: string, result: RunResult, rules: readonly RuleDefinition[], language: string): string => {
   const byId = new Map(rules.map((rule) => [rule.id, rule]));
+  const width = positionWidthOf(result.findings);
   const lines = result.findings.flatMap((finding) => {
     const rule = byId.get(finding.rule);
     if (rule === undefined) return [];
-    const at = `${finding.line}:${finding.column}`.padEnd(8);
-    return [`  ${at}${finding.severity.padEnd(8)}${messageOf(rule, finding, language)}`, `          ${" ".repeat(8)}${finding.rule}`];
+    const message = `  ${positionOf(finding).padEnd(width)}${finding.severity.padEnd(SEVERITY_WIDTH)}${messageOf(rule, finding, language)}`;
+    return [message, `  ${" ".repeat(width + SEVERITY_WIDTH)}${finding.rule}`];
   });
   const text = TALLY[uiLanguageOf(language)];
   const tail = [text.findings(result.findings.length), result.skipped.length > 0 ? text.notRun(result.skipped.length) : undefined].filter(

package/src/render/explain.ts

@@ -1,7 +1,10 @@
-import { definedLevels, resolve } from "../levels.ts";
-import { localized } from "./text.ts";
+import { definedLevels, resolve, severityAt } from "../levels.ts";
+import { fill, localized, readableText } from "./text.ts";
+import { SEVERITY_NAME } from "./severity-name.ts";
 import { uiLanguageOf, type Texts } 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,14 @@ const TEXT: Texts<{
   readonly genreNote: (genre: string, others: string) => string;
   readonly experimental: string;
   readonly howToFix: string;
-  readonly values: (unit: string) => string;
+  readonly example: string;
+  readonly definedIn: (plugin: string | undefined) => string;
+  readonly values: string;
+  readonly times: string;
+  readonly severities: string;
   readonly now: (level: string) => string;
+  readonly nowNumber: (limit: string) => string;
+  readonly from: (source: string) => string;
   readonly change: (id: string) => string;
 }> = {
   ja: {
@@ -19,8 +28,15 @@ const TEXT: Texts<{
     genreNote: (genre, others) => `この数字は ${genre} のものです。ほかに ${others} で別の数字を持っています。`,
     experimental: "このルールはまだ試験中で、既定では動きません（--experimental で動きます）。",
     howToFix: "直しかた",
-    values: (unit) => `設定できる値（単位: ${unit}）:`,
+    example: "例",
+    definedIn: (plugin) =>
+      plugin === undefined ? "このルールはチームが chaff.yaml の custom_rules で決めたものです。" : `このルールはプラグイン ${plugin} のものです。`,
+    values: "設定できる値:",
+    times: "回",
+    severities: "設定できる値（数える上限は無く、指摘の重さが変わります）:",
     now: (level) => `いまは ${level} です。`,
+    nowNumber: (limit) => `いまは段階ではなく数です: ${limit}。`,
+    from: (source) => `（${source} で決めています）`,
     change: (id) => `変える:  npx chaff relax ${id} --why "理由"`,
   },
   en: {
@@ -29,16 +45,39 @@ 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",
-    values: (unit) => `Levels (unit: ${unit}):`,
+    example: "Example",
+    definedIn: (plugin) =>
+      plugin === undefined ? "The team defined this rule under custom_rules in chaff.yaml." : `This rule comes from the plugin ${plugin}.`,
+    values: "Levels:",
+    times: "times",
+    severities: "Levels (there is no limit to count to; a level sets how a finding is marked):",
     now: (level) => `Now: ${level}.`,
+    nowNumber: (limit) => `Now: ${limit}, set as a number rather than a 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 => {
+/**
+ * A limit in the rule's words for what it counts ("up to 8 emoji per 1000 words"), as the rule reference shows it.
+ * A rule that says nothing (a team's custom rule) counts matches, so its limit is a number of times.
+ */
+const limitText = (rule: RuleDefinition, limit: number, language: string): string => {
+  const meaning = localized(rule.guide?.levelMeaning ?? {}, language);
+  return meaning === "" ? `${String(limit)} ${TEXT[uiLanguageOf(language)].times}` : fill(meaning, { limit });
+};
+
+/** 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, language: string): string =>
+  rule.level_sets === "severity"
+    ? SEVERITY_NAME[uiLanguageOf(language)][severityAt(rule, level, genre)]
+    : limitText(rule, resolve(rule, level, genre).limit, language);
+
+/** current is undefined when a number, not a level, sets the limit: no level is marked. */
+const levelLine = (rule: RuleDefinition, level: Level, current: Level | undefined, genre: string | undefined, language: string): 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[uiLanguageOf(language)].off}` : `  ${mark} ${name}${valueAt(rule, level, genre, language)}`;
 };
 
 /** ジャンルで数字が変わる rule は、それを言わないと「設定したのに効かない」に見える。 */
@@ -48,23 +87,45 @@ 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(rule.plugin)}`];
+};
+
+/** Where the rule's settings come from: the option layers, strongest first, and the source of its level when a style set it. */
+/** limit: a number chaff.yaml or its style set for the rule (rules: { id: 80 }, a style's limits), which a level does not show. */
+export type ExplainSettings = {
+  readonly optionLayers?: readonly OptionLayer[];
+  readonly levelFrom?: string | undefined;
+  readonly limit?: number | undefined;
+};
+
 /** rule の意図と根拠を読む。指摘に納得できないときの入口。 */
-export const renderExplain = (rule: RuleDefinition, current: Level, language: string, unit: string, genre?: string): string => {
+export const renderExplain = (rule: RuleDefinition, current: Level, language: string, genre?: string, settings: ExplainSettings = {}): string => {
+  const { optionLayers = [], levelFrom } = settings;
+  // A rule with nothing to count has no number to set; chaff.yaml's number on it is reported as a problem and ignored.
+  const limit = rule.level_sets === "severity" ? undefined : settings.limit;
+  const marked = limit === undefined ? current : undefined;
   const text = TEXT[uiLanguageOf(language)];
   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}`,
+    ...definedLevels(rule).map((level) => levelLine(rule, level, marked, genre, language)),
     ...genreNote(rule, genre, text),
+    ...optionLines(rule, optionLayers, language),
     "",
-    `  ${text.now(current)}`,
+    `  ${limit === undefined ? text.now(current) : text.nowNumber(limitText(rule, limit, language))}${levelFrom === undefined ? "" : text.from(levelFrom)}`,
     ...experimental,
     "",
     `  ${text.change(rule.id)}`,

package/src/render/friendly.ts

@@ -1,6 +1,6 @@
 import type { Finding, RuleDefinition } from "../plugin.ts";
 import type { RunResult } from "../run.ts";
-import { MARK, localized, messageOf } from "./text.ts";
+import { MARK, filledText, messageOf } from "./text.ts";
 import { tally } from "./summary.ts";
 import { counted } from "./plural.ts";
 import { uiLanguageOf, type Texts } from "../ui.ts";
@@ -45,29 +45,39 @@ const QUOTE_LIMIT = 120;
 
 const indent = (text: string, pad: string): string[] => text.split("\n").map((line) => `${pad}${line}`);
 
-const quoteOf = (finding: Finding): string[] => {
-  const text = finding.quote.replace(/\s+/gu, " ").trim();
+const quoteOf = (quote: string): string[] => {
+  const text = quote.replace(/\s+/gu, " ").trim();
   if (text.length === 0) return [];
   return ["", ...indent(text.length > QUOTE_LIMIT ? `${text.slice(0, QUOTE_LIMIT)}…` : text, "    ")];
 };
 
+/** 一つの文から出た指摘は同じ文を引く。長い文に指摘が多いとき、指摘ごとに文を整え直さない。 */
+const quotesOf = (): ((quote: string) => readonly string[]) => {
+  const known = new Map<string, readonly string[]>();
+  return (quote) => {
+    const lines = known.get(quote) ?? quoteOf(quote);
+    known.set(quote, lines);
+    return lines;
+  };
+};
+
 /**
  * 1 件につき 4 つを出す。どれが欠けても、書いた人は動けない。
  *   引用 / 何が起きているか / なぜ問題か / どう直すか
  * rule の id は「ゆるめる」コマンドの中にだけ出す。最初に読むのは name。
  */
-const block = (finding: Finding, rule: RuleDefinition, language: string): string[] => [
+const block = (finding: Finding, rule: RuleDefinition, language: string, quoted: readonly string[]): string[] => [
   "",
   // "12 行目" and "line 12" take the same width on a terminal, so the rule ends in the same column in both.
   `─── ${TEXT[uiLanguageOf(language)].line(finding.line)} ${"─".repeat(Math.max(0, RULE - String(finding.line).length - 8))}`,
-  ...quoteOf(finding),
+  ...quoted,
   "",
-  `  ${MARK[finding.severity] ?? "·"}  ${localized(rule.name, language)}`,
+  `  ${MARK[finding.severity] ?? "·"}  ${filledText(rule.name, finding, language)}`,
   "",
   ...indent(messageOf(rule, finding, language), "     "),
-  ...indent(localized(rule.why, language), "     "),
+  ...indent(filledText(rule.why, finding, language), "     "),
   "",
-  ...indent(`→ ${localized(rule.how_to_fix, language)}`, "     "),
+  ...indent(`→ ${filledText(rule.how_to_fix, finding, language)}`, "     "),
   "",
   `     ${TEXT[uiLanguageOf(language)].relax}:  npx chaff relax ${finding.rule}`,
   "",
@@ -82,9 +92,10 @@ export const renderFriendly = (
   notes: readonly string[] = [],
 ): string => {
   const byId = new Map(rules.map((rule) => [rule.id, rule]));
+  const quoted = quotesOf();
   const blocks = result.findings.flatMap((finding) => {
     const rule = byId.get(finding.rule);
-    return rule === undefined ? [] : block(finding, rule, language);
+    return rule === undefined ? [] : block(finding, rule, language, quoted(finding.quote));
   });
   const text = TEXT[uiLanguageOf(language)];
   const closing = [