chaffjs 0.7.0 → 0.9.0

package/src/reasons.ts

@@ -0,0 +1,49 @@
+import type { Texts } from "./ui.ts";
+
+/** Why a rule did not run, in the document's language. Listed under the findings so "0 findings" is never a silent pass. */
+export type Reasons = {
+  readonly otherLanguage: (language: string) => string;
+  readonly noCapability: (capability: string) => string;
+  readonly noTags: string;
+  readonly semantic: string;
+  readonly experimental: string;
+  readonly turnedOff: string;
+  readonly noStructure: (language: string) => string;
+  readonly unreadStructure: (clauses: number, units: number) => string;
+  readonly noDetector: (name: string) => string;
+  readonly noLexicon: (language: string, list: string) => string;
+};
+
+const CAPABILITY_NAME: Texts<Readonly<Record<string, string>>> = {
+  ja: { pos: "品詞解析", lemma: "原形" },
+  en: { pos: "part-of-speech tagging", lemma: "lemmas" },
+};
+
+export const REASONS: Texts<Reasons> = {
+  ja: {
+    otherLanguage: (language) => `${language} 向けの rule ではないため`,
+    noCapability: (capability) => `この言語では${CAPABILITY_NAME.ja[capability] ?? capability}が使えないため`,
+    noTags: "アダプタが品詞を返さなかったため",
+    semantic: "意味を読む検査のため（npx chaff test で動きます）",
+    experimental: "まだ試験中のため",
+    turnedOff: "設定で止めているため",
+    noStructure: (language) => `${language} のパッケージは文書の構造を読めないため`,
+    unreadStructure: (clauses, units) =>
+      `条項の番号が本文に ${String(clauses)} 個あるのに、番号として読めたのは ${String(units)} 個のため（深い字下げや、行が本文につながった文書）`,
+    noDetector: (name) => `検出器 ${name} がないため`,
+    noLexicon: (language, list) => `${language} の語彙表 ${list} が無いため`,
+  },
+  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",
+    semantic: "it reads meaning; npx chaff test runs it",
+    experimental: "still experimental",
+    turnedOff: "turned off in the settings",
+    noStructure: (language) => `the ${language} package cannot read a document's structure`,
+    unreadStructure: (clauses, units) =>
+      `the text has ${String(clauses)} clause numbers but only ${String(units)} 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}`,
+  },
+};

package/src/render/explain.ts

@@ -1,39 +1,73 @@
 import { definedLevels, resolve } from "../levels.ts";
 import { localized } from "./text.ts";
+import { uiLanguageOf, type Texts } from "../ui.ts";
 import type { Level, RuleDefinition } from "../plugin.ts";
 
-const levelLine = (rule: RuleDefinition, level: Level, current: Level, genre: string | undefined): string => {
-  const mark = level === current ? "\u2192" : " ";
+const TEXT: Texts<{
+  readonly off: string;
+  readonly defaultGenre: string;
+  readonly genreNote: (genre: string, others: string) => string;
+  readonly experimental: string;
+  readonly howToFix: string;
+  readonly values: (unit: string) => string;
+  readonly now: (level: string) => string;
+  readonly change: (id: string) => string;
+}> = {
+  ja: {
+    off: "見ない",
+    defaultGenre: "既定",
+    genreNote: (genre, others) => `この数字は ${genre} のものです。ほかに ${others} で別の数字を持っています。`,
+    experimental: "このルールはまだ試験中で、既定では動きません（--experimental で動きます）。",
+    howToFix: "直しかた",
+    values: (unit) => `設定できる値（単位: ${unit}）:`,
+    now: (level) => `いまは ${level} です。`,
+    change: (id) => `変える:  npx chaff relax ${id} --why "理由"`,
+  },
+  en: {
+    off: "not checked",
+    defaultGenre: "the default genre",
+    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}):`,
+    now: (level) => `Now: ${level}.`,
+    change: (id) => `Change it:  npx chaff relax ${id} --why "reason"`,
+  },
+};
+
+const levelLine = (rule: RuleDefinition, level: Level, current: Level, genre: string | undefined, off: string): string => {
+  const mark = level === current ? "→" : " ";
   const name = level.padEnd(9);
-  return level === "off" ? `  ${mark} ${name}見ない` : `  ${mark} ${name}${resolve(rule, level, genre).limit}`;
+  return level === "off" ? `  ${mark} ${name}${off}` : `  ${mark} ${name}${resolve(rule, level, genre).limit}`;
 };
 
 /** ジャンルで数字が変わる rule は、それを言わないと「設定したのに効かない」に見える。 */
-const genreNote = (rule: RuleDefinition, genre: string | undefined): string[] => {
+const genreNote = (rule: RuleDefinition, genre: string | undefined, text: (typeof TEXT)["ja"]): string[] => {
   const others = Object.keys(rule.by_genre).filter((key) => key !== genre);
   if (others.length === 0) return [];
-  return ["", `  この数字は ${genre ?? "既定"} のものです。ほかに ${others.join(" / ")} で別の数字を持っています。`];
+  return ["", `  ${text.genreNote(genre ?? text.defaultGenre, others.join(" / "))}`];
 };
 
 /** rule の意図と根拠を読む。指摘に納得できないときの入口。 */
 export const renderExplain = (rule: RuleDefinition, current: Level, language: string, unit: string, genre?: string): string => {
-  const experimental = rule.status === "experimental" ? ["  このルールはまだ試験中で、既定では動きません（--experimental で動きます）。"] : [];
+  const text = TEXT[uiLanguageOf(language)];
+  const experimental = rule.status === "experimental" ? [`  ${text.experimental}`] : [];
   return [
     "",
     `  ${localized(rule.name, language)}   (${rule.id})`,
     "",
     `  ${localized(rule.why, language)}`,
     "",
-    `  直しかた: ${localized(rule.how_to_fix, language)}`,
+    `  ${text.howToFix}: ${localized(rule.how_to_fix, language)}`,
     "",
-    `  設定できる値（単位: ${unit}）:`,
-    ...definedLevels(rule).map((level) => levelLine(rule, level, current, genre)),
-    ...genreNote(rule, genre),
+    `  ${text.values(unit)}`,
+    ...definedLevels(rule).map((level) => levelLine(rule, level, current, genre, text.off)),
+    ...genreNote(rule, genre, text),
     "",
-    `  いまは ${current} です。`,
+    `  ${text.now(current)}`,
     ...experimental,
     "",
-    `  変える:  npx chaff relax ${rule.id} --why "理由"`,
+    `  ${text.change(rule.id)}`,
     "",
   ].join("\n");
 };

package/src/render/friendly.ts

@@ -2,8 +2,41 @@ import type { Finding, RuleDefinition } from "../plugin.ts";
 import type { RunResult } from "../run.ts";
 import { MARK, localized, messageOf } from "./text.ts";
 import { tally } from "./summary.ts";
+import { uiLanguageOf, type Texts } from "../ui.ts";
 
 const RULE = 60;
+
+const TEXT: Texts<{
+  readonly line: (n: number) => string;
+  readonly relax: string;
+  readonly machine: string;
+  readonly deterministic: string;
+  readonly untouched: string;
+  readonly forced: (n: number, ids: string) => string;
+  readonly notRun: (n: number) => string;
+  readonly because: (why: string) => string;
+}> = {
+  ja: {
+    line: (n) => `${n} 行目`,
+    relax: "このルールをゆるめる",
+    machine: "すべて機械による判定です",
+    deterministic: "              （同じ文章なら何度実行しても同じ結果になります）",
+    untouched: "文章は書き換えていません。直すのは書いた人です。",
+    forced: (n, ids) => `試験中の rule を ${n} 件、設定により有効にしています: ${ids}`,
+    notRun: (n) => `${n} 件の rule は動いていません:`,
+    because: (why) => `（${why}）`,
+  },
+  en: {
+    line: (n) => `line ${n}`,
+    relax: "Relax this rule",
+    machine: "All judged by machine",
+    deterministic: "              (the same text gives the same result every time)",
+    untouched: "The text was not changed. Fixing it is the writer's job.",
+    forced: (n, ids) => `${n} experimental rule${n === 1 ? "" : "s"} turned on in the settings: ${ids}`,
+    notRun: (n) => `${n} rule${n === 1 ? "" : "s"} did not run:`,
+    because: (why) => ` (${why})`,
+  },
+};
 const QUOTE_LIMIT = 120;
 
 const indent = (text: string, pad: string): string[] => text.split("\n").map((line) => `${pad}${line}`);
@@ -21,7 +54,8 @@ const quoteOf = (finding: Finding): string[] => {
  */
 const block = (finding: Finding, rule: RuleDefinition, language: string): string[] => [
   "",
-  `─── ${finding.line} 行目 ${"─".repeat(Math.max(0, RULE - String(finding.line).length - 8))}`,
+  // "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),
   "",
   `  ${MARK[finding.severity] ?? "·"}  ${localized(rule.name, language)}`,
@@ -31,7 +65,7 @@ const block = (finding: Finding, rule: RuleDefinition, language: string): string
   "",
   ...indent(`→ ${localized(rule.how_to_fix, language)}`, "     "),
   "",
-  `     このルールをゆるめる:  npx chaff relax ${finding.rule}`,
+  `     ${TEXT[uiLanguageOf(language)].relax}:  npx chaff relax ${finding.rule}`,
   "",
 ];
 
@@ -41,22 +75,20 @@ export const renderFriendly = (header: string, result: RunResult, rules: readonl
     const rule = byId.get(finding.rule);
     return rule === undefined ? [] : block(finding, rule, language);
   });
+  const text = TEXT[uiLanguageOf(language)];
   const notes = [
     "",
     "─".repeat(RULE),
     "",
-    `  ${tally(result.findings)}   すべて機械による判定です`,
-    "              （同じ文章なら何度実行しても同じ結果になります）",
+    `  ${tally(result.findings, uiLanguageOf(language))}   ${text.machine}`,
+    text.deterministic,
     "",
-    "  文章は書き換えていません。直すのは書いた人です。",
+    `  ${text.untouched}`,
   ];
-  const forced =
-    result.forcedExperimental.length > 0
-      ? ["", `  試験中の rule を ${result.forcedExperimental.length} 件、設定により有効にしています: ${result.forcedExperimental.join(", ")}`]
-      : [];
+  const forced = result.forcedExperimental.length > 0 ? ["", `  ${text.forced(result.forcedExperimental.length, result.forcedExperimental.join(", "))}`] : [];
   const skipped =
     result.skipped.length > 0
-      ? ["", `  ${result.skipped.length} 件の rule は動いていません:`, ...result.skipped.map((entry) => `      ${entry.rule}（${entry.why}）`)]
+      ? ["", `  ${text.notRun(result.skipped.length)}`, ...result.skipped.map((entry) => `      ${entry.rule}${text.because(entry.why)}`)]
       : [];
   return ["", header, ...blocks, ...notes, ...forced, ...skipped, ""].join("\n");
 };

package/src/render/rules-json.ts

@@ -1,15 +1,39 @@
 import { definedLevels, resolve } from "../levels.ts";
 import type { Config } from "../config/load.ts";
 import type { RuleDefinition } from "../plugin.ts";
+import { uiLanguageOf, type Texts } from "../ui.ts";
 
-const now = (rule: RuleDefinition, config: Config, genre: string): Record<string, unknown> => {
+const TEXT: Texts<{
+  readonly offBySetting: string;
+  readonly offExperimental: string;
+  readonly valuesNote: string;
+  readonly reason: string;
+  readonly byFile: string;
+}> = {
+  ja: {
+    offBySetting: "設定で止めている",
+    offExperimental: "experimental な rule は既定で動かさない",
+    valuesNote: "この 4 語のかわりに数字を直接書いてもよい。4 語のほうを勧める。",
+    reason: "<理由>",
+    byFile: "chaff.yaml の rules に <rule-id>: <level> を足す。既定のままのものは書かない。",
+  },
+  en: {
+    offBySetting: "turned off in the settings",
+    offExperimental: "experimental rules do not run by default",
+    valuesNote: "A number may be written instead of these four words. The words are recommended.",
+    reason: "<reason>",
+    byFile: "Add <rule-id>: <level> under rules in chaff.yaml. Leave out anything at its default.",
+  },
+};
+
+const now = (rule: RuleDefinition, config: Config, genre: string, text: (typeof TEXT)["ja"]): Record<string, unknown> => {
   const explicit = config.rules[rule.id];
-  if (explicit === "off") return { level: "off", why_off: "設定で止めている" };
+  if (explicit === "off") return { level: "off", why_off: text.offBySetting };
   const limit = rule.layer === "L4" ? undefined : config.limits[rule.id];
   if (limit !== undefined) return { level: "normal", limit, set_as: "number" };
   if (explicit !== undefined) return { level: explicit, limit: resolve(rule, explicit, genre).limit };
   if (rule.status === "experimental" && !config.experimental) {
-    return { level: "off", why_off: "experimental な rule は既定で動かさない", turn_on_with: `npx chaff lint --experimental` };
+    return { level: "off", why_off: text.offExperimental, turn_on_with: `npx chaff lint --experimental` };
   }
   return { level: "normal", limit: resolve(rule, "normal", genre).limit };
 };
@@ -33,14 +57,15 @@ const levelsOf = (rule: RuleDefinition, genre: string): Record<string, unknown>
 };
 
 /** AI に設定を書かせるときの入口。推測せずに書けるだけの情報を 1 つに入れる。spec §19.3。 */
-export const rulesJson = (rules: readonly RuleDefinition[], config: Config, language: string, genre: string): string =>
-  JSON.stringify(
+export const rulesJson = (rules: readonly RuleDefinition[], config: Config, language: string, genre: string): string => {
+  const text = TEXT[uiLanguageOf(language)];
+  return JSON.stringify(
     {
       schema_version: 1,
       config_file: "chaff.yaml",
       detected: { genre, language },
       values_you_can_use: ["strict", "normal", "relaxed", "off"],
-      values_note: "この 4 語のかわりに数字を直接書いてもよい。4 語のほうを勧める。",
+      values_note: text.valuesNote,
       rules: rules.map((rule) => ({
         id: rule.id,
         layer: rule.layer,
@@ -52,13 +77,14 @@ export const rulesJson = (rules: readonly RuleDefinition[], config: Config, lang
         ...levelsOf(rule, genre),
         levels_you_can_set: definedLevels(rule),
         your_setting: yourSetting(rule, config),
-        now: now(rule, config, genre),
+        now: now(rule, config, genre, text),
       })),
       how_to_change: {
-        by_command: ['npx chaff relax <rule-id> --why "<理由>"', 'npx chaff strict <rule-id> --why "<理由>"', 'npx chaff off <rule-id> --why "<理由>"'],
-        by_file: "chaff.yaml の rules に <rule-id>: <level> を足す。既定のままのものは書かない。",
+        by_command: ["relax", "strict", "off"].map((command) => `npx chaff ${command} <rule-id> --why "${text.reason}"`),
+        by_file: text.byFile,
       },
     },
     null,
     2,
   );
+};

package/src/render/summary.ts

@@ -1,22 +1,47 @@
 import type { Finding } from "../plugin.ts";
+import type { Texts, UiLanguage } from "../ui.ts";
 
 export type FileOutcome = { readonly path: string; readonly findings: readonly Finding[]; readonly notRun: number };
 
 const count = (findings: readonly Finding[], severity: string): number => findings.filter((finding) => finding.severity === severity).length;
 
-export const tally = (findings: readonly Finding[]): string => {
-  const parts = [
-    count(findings, "error") > 0 ? `エラー ${count(findings, "error")} 件` : undefined,
-    count(findings, "warning") > 0 ? `注意 ${count(findings, "warning")} 件` : undefined,
-    count(findings, "info") > 0 ? `参考 ${count(findings, "info")} 件` : undefined,
-  ].filter((part) => part !== undefined);
-  return parts.length === 0 ? "指摘はありません" : parts.join("、");
+type Severity = "error" | "warning" | "info";
+
+const TEXT: Texts<{
+  readonly counts: Readonly<Record<Severity, (n: number) => string>>;
+  readonly join: string;
+  readonly none: string;
+  readonly files: (seen: number, touched: number) => string;
+}> = {
+  ja: {
+    counts: { error: (n) => `エラー ${n} 件`, warning: (n) => `注意 ${n} 件`, info: (n) => `参考 ${n} 件` },
+    join: "、",
+    none: "指摘はありません",
+    files: (seen, touched) => `${seen} ファイルを見て、${touched} ファイルに指摘がありました`,
+  },
+  en: {
+    counts: {
+      error: (n) => `${n} error${n === 1 ? "" : "s"}`,
+      warning: (n) => `${n} warning${n === 1 ? "" : "s"}`,
+      info: (n) => `${n} note${n === 1 ? "" : "s"}`,
+    },
+    join: ", ",
+    none: "No findings",
+    files: (seen, touched) => `${seen} files checked, ${touched} with findings`,
+  },
+};
+
+const SEVERITIES: readonly Severity[] = ["error", "warning", "info"];
+
+export const tally = (findings: readonly Finding[], ui: UiLanguage): string => {
+  const parts = SEVERITIES.filter((severity) => count(findings, severity) > 0).map((severity) => TEXT[ui].counts[severity](count(findings, severity)));
+  return parts.length === 0 ? TEXT[ui].none : parts.join(TEXT[ui].join);
 };
 
 /** 複数ファイルを見たときの締め。1 ファイルのときは出さない。 */
-export const renderSummary = (outcomes: readonly FileOutcome[]): string[] => {
+export const renderSummary = (outcomes: readonly FileOutcome[], ui: UiLanguage): string[] => {
   if (outcomes.length < 2) return [];
   const all = outcomes.flatMap((outcome) => outcome.findings);
   const touched = outcomes.filter((outcome) => outcome.findings.length > 0).length;
-  return ["", "═".repeat(60), "", `  ${outcomes.length} ファイルを見て、${touched} ファイルに指摘がありました`, `  ${tally(all)}`, ""];
+  return ["", "═".repeat(60), "", `  ${TEXT[ui].files(outcomes.length, touched)}`, `  ${tally(all, ui)}`, ""];
 };

package/src/render/suppressions.ts

@@ -1,4 +1,37 @@
 import type { Suppressed, Suppression } from "../stet.ts";
+import type { Texts, UiLanguage } from "../ui.ts";
+
+const TEXT: Texts<{
+  readonly nudge: string;
+  readonly more: (n: number) => string;
+  readonly count: (n: number) => string;
+  readonly reasons: (list: string) => string;
+  readonly relaxAll: (rule: string) => string;
+  readonly none: string;
+  readonly total: (n: number) => string;
+  readonly reasonless: (n: number) => string;
+}> = {
+  ja: {
+    nudge: "  ← 設定の見直しを検討してください",
+    more: (n) => ` ほか ${n} ファイル`,
+    count: (n) => `${String(n).padStart(3)} 件`,
+    reasons: (list) => `理由: ${list}`,
+    relaxAll: (rule) => `ルールごとゆるめる: npx chaff relax ${rule} --why "..."`,
+    none: "\n  抑制されている指摘はありません。\n",
+    total: (n) => `抑制されている指摘: ${n} 件`,
+    reasonless: (n) => `理由が書かれていない抑制: ${n} 件`,
+  },
+  en: {
+    nudge: "  <- consider changing the setting instead",
+    more: (n) => ` and ${n} more file${n === 1 ? "" : "s"}`,
+    count: (n) => `${String(n).padStart(3)}`,
+    reasons: (list) => `reasons: ${list}`,
+    relaxAll: (rule) => `relax the whole rule: npx chaff relax ${rule} --why "..."`,
+    none: "\n  No findings are silenced.\n",
+    total: (n) => `Silenced findings: ${n}`,
+    reasonless: (n) => `Silenced without a reason: ${n}`,
+  },
+};
 
 export type PerFile = { readonly path: string; readonly suppressed: readonly Suppressed[]; readonly reasonless: readonly Suppression[] };
 
@@ -23,16 +56,17 @@ const groupByRule = (files: readonly PerFile[]): Group[] => {
     .sort((left, right) => right.count - left.count);
 };
 
-const groupLines = (group: Group): string[] => {
-  const nudge = group.count >= NUDGE_AT ? "  ← 設定の見直しを検討してください" : "";
+const groupLines = (group: Group, ui: UiLanguage): string[] => {
+  const text = TEXT[ui];
+  const nudge = group.count >= NUDGE_AT ? text.nudge : "";
   const shown = group.files.slice(0, 3).join(", ");
-  const rest = group.files.length > 3 ? ` ほか ${group.files.length - 3} ファイル` : "";
+  const rest = group.files.length > 3 ? text.more(group.files.length - 3) : "";
   return [
     "",
-    `  ${group.rule.padEnd(26)}${String(group.count).padStart(3)} 件${nudge}`,
+    `  ${group.rule.padEnd(26)}${text.count(group.count)}${nudge}`,
     `      ${shown}${rest}`,
     ...(group.count >= NUDGE_AT && group.reasons.length > 0
-      ? [`      理由: ${group.reasons.slice(0, 2).join(" / ")}`, `      ルールごとゆるめる: npx chaff relax ${group.rule} --why "..."`]
+      ? [`      ${text.reasons(group.reasons.slice(0, 2).join(" / "))}`, `      ${text.relaxAll(group.rule)}`]
       : []),
   ];
 };
@@ -42,16 +76,17 @@ const groupLines = (group: Group): string[] => {
  * 同じ rule を何度も黙らせているなら、それは (b) ではなく (c) のサイン。
  * workflow spec §7.3。
  */
-export const renderSuppressions = (files: readonly PerFile[]): string => {
+export const renderSuppressions = (files: readonly PerFile[], ui: UiLanguage = "ja"): string => {
+  const text = TEXT[ui];
   const groups = groupByRule(files);
   const total = groups.reduce((sum, group) => sum + group.count, 0);
-  if (total === 0) return "\n  抑制されている指摘はありません。\n";
+  if (total === 0) return text.none;
   const reasonless = files.flatMap((file) => file.reasonless.map(() => file.path));
   return [
     "",
-    `  抑制されている指摘: ${total} 件`,
-    ...groups.flatMap(groupLines),
-    ...(reasonless.length > 0 ? ["", `  理由が書かれていない抑制: ${reasonless.length} 件`, `      ${[...new Set(reasonless)].join(", ")}`] : []),
+    `  ${text.total(total)}`,
+    ...groups.flatMap((group) => groupLines(group, ui)),
+    ...(reasonless.length > 0 ? ["", `  ${text.reasonless(reasonless.length)}`, `      ${[...new Set(reasonless)].join(", ")}`] : []),
     "",
   ].join("\n");
 };

package/src/run.ts

@@ -2,6 +2,10 @@ import { DETECTORS } from "./detectors/index.ts";
 import { resolve } from "./levels.ts";
 import type { AdapterNeeds, Finding, Level, ProseDocument, RuleDefinition } from "./plugin.ts";
 import { lineStarts, placeOf } from "./position.ts";
+import { REASONS, type Reasons } from "./reasons.ts";
+import { unreadStructure, type Unread } from "./structure/unread.ts";
+import { isMarkdownPath } from "./structure/markdown-path.ts";
+import { uiLanguageOf } from "./ui.ts";
 
 export type Skipped = { readonly rule: string; readonly why: string };
 
@@ -22,7 +26,28 @@ const levelFor = (rule: RuleDefinition, settings: Settings, experimental: boolea
   return "normal";
 };
 
-const CAPABILITY_NAME: Readonly<Record<string, string>> = { pos: "品詞解析", lemma: "原形" };
+const reasonsFor = (doc: ProseDocument): Reasons => REASONS[uiLanguageOf(doc.language)];
+
+/**
+ * 構造の rule が動けない理由。木を作れない言語か、番号の行を読めなかった文書。
+ * 読めなかった文書で「参照先が無い」が 0 件なのは、確かめた結果ではないので、読めなかったと言う。
+ */
+const treeProblem = (doc: ProseDocument): string | undefined => {
+  if (doc.structure === undefined) return reasonsFor(doc).noStructure(doc.language);
+  const unread = unreadOf(doc);
+  return unread === undefined ? undefined : reasonsFor(doc).unreadStructure(unread.clauses, unread.units);
+};
+
+/** 木が読んだのと同じ本文。Markdown はコードを覆ったもの、.txt はそのまま（.txt の字下げはコードではない）。 */
+const textTheTreeRead = (doc: ProseDocument): string => (isMarkdownPath(doc.path) ? (doc.prose ?? doc.source) : doc.source);
+
+const unreadByDocument = new WeakMap<ProseDocument, Unread | undefined>();
+
+/** 文書ごとに一度だけ数える。構造の rule が三つあっても、本文を三度なめない。 */
+const unreadOf = (doc: ProseDocument): Unread | undefined => {
+  if (!unreadByDocument.has(doc)) unreadByDocument.set(doc, doc.structure === undefined ? undefined : unreadStructure(textTheTreeRead(doc), doc.structure));
+  return unreadByDocument.get(doc);
+};
 
 /** 知らない要求は満たされていないものとして扱う。黙って無視すると、要求なしで動いてしまう。 */
 const has = (capabilities: ProseDocument["capabilities"], need: string): boolean => {
@@ -42,13 +67,19 @@ const hasTokens = (doc: ProseDocument): boolean => doc.sentences.length === 0 ||
 
 /** 要求を満たさない rule は動かせない。満たさないまま動かすと「指摘 0 件」が保証に見える。 */
 const unmet = (rule: RuleDefinition, doc: ProseDocument): string | undefined => {
-  if (rule.languages !== undefined && !rule.languages.includes(doc.language)) return `${doc.language} 向けの rule ではないため`;
+  if (rule.languages !== undefined && !rule.languages.includes(doc.language)) return reasonsFor(doc).otherLanguage(doc.language);
   const missing = rule.requires.filter((need) => need !== "structure").find((need) => !has(doc.capabilities, need));
-  if (missing !== undefined) return `この言語では${CAPABILITY_NAME[missing] ?? missing}が使えないため`;
-  if (rule.requires.some((need) => need === "pos" || need === "lemma") && !hasTokens(doc)) return "アダプタが品詞を返さなかったため";
+  if (missing !== undefined) return reasonsFor(doc).noCapability(missing);
   return undefined;
 };
 
+/**
+ * 品詞は、動かす rule があるときだけ用意する（neededBy）。だから「品詞が無い」は、段階を見た後でしか言えない。
+ * 先に聞くと、止めている rule まで「アダプタが品詞を返さなかった」と、違う理由で出る。
+ */
+const untagged = (rule: RuleDefinition, doc: ProseDocument): string | undefined =>
+  rule.requires.some((need) => need === "pos" || need === "lemma") && !hasTokens(doc) ? reasonsFor(doc).noTags : undefined;
+
 const forGenre = (rules: readonly RuleDefinition[], genre: string): RuleDefinition[] =>
   rules.filter((rule) => rule.use_for.some((target) => genre.startsWith(target)));
 
@@ -114,24 +145,26 @@ export const runRules = (
     (acc, rule) => {
       // L4 は意味を読む検査。chaff test が扱う。ここで「検出器が無い」と言わせない。
       if (rule.layer === "L4") {
-        return { findings: acc.findings, skipped: [...acc.skipped, { rule: rule.id, why: "意味を読む検査のため（npx chaff test で動きます）" }] };
+        return { findings: acc.findings, skipped: [...acc.skipped, { rule: rule.id, why: reasonsFor(doc).semantic }] };
       }
       const blocked = unmet(rule, doc);
       if (blocked !== undefined) return { findings: acc.findings, skipped: [...acc.skipped, { rule: rule.id, why: blocked }] };
       const level = levelFor(rule, settings, experimental);
       if (level === "off") {
-        const why = rule.status === "experimental" && settings[rule.id] === undefined ? "まだ試験中のため" : "設定で止めているため";
+        const why = rule.status === "experimental" && settings[rule.id] === undefined ? reasonsFor(doc).experimental : reasonsFor(doc).turnedOff;
         return { findings: acc.findings, skipped: [...acc.skipped, { rule: rule.id, why }] };
       }
+      const noTags = untagged(rule, doc);
+      if (noTags !== undefined) return { findings: acc.findings, skipped: [...acc.skipped, { rule: rule.id, why: noTags }] };
       // 木は capability ではなく、adapter が structure を持つかで決まる。持たない言語で動かすと「参照先が無い」が 0 件に見える。
       // 段階を見た後で聞く。doc.structure は触れたときに木を作るので、止めている rule のために作らない。
-      if (rule.requires.includes("structure") && doc.structure === undefined) {
-        return { findings: acc.findings, skipped: [...acc.skipped, { rule: rule.id, why: `${doc.language} のパッケージは文書の構造を読めないため` }] };
-      }
+      const noTree = rule.requires.includes("structure") ? treeProblem(doc) : undefined;
+      if (noTree !== undefined) return { findings: acc.findings, skipped: [...acc.skipped, { rule: rule.id, why: noTree }] };
       // 複合シグナルは二段目で扱う。一段目では「検出器が無い」と言わせない。
       if (rule.from.length > 0) return acc;
       const detector = DETECTORS[rule.how_to_find];
-      if (detector === undefined) return { findings: acc.findings, skipped: [...acc.skipped, { rule: rule.id, why: `検出器 ${rule.how_to_find} がないため` }] };
+      if (detector === undefined)
+        return { findings: acc.findings, skipped: [...acc.skipped, { rule: rule.id, why: reasonsFor(doc).noDetector(rule.how_to_find) }] };
       const options = {
         limit: limitFor(rule, level, genre, limits),
         lexicon: rule.word_list === undefined ? undefined : doc.lexicons[rule.word_list],
@@ -139,7 +172,7 @@ export const runRules = (
       };
       // 語彙表を要求する rule で、その言語に語彙表が無ければ動かせない。黙って通さない。
       if (rule.word_list !== undefined && options.lexicon === undefined) {
-        return { findings: acc.findings, skipped: [...acc.skipped, { rule: rule.id, why: `${doc.language} の語彙表 ${rule.word_list} が無いため` }] };
+        return { findings: acc.findings, skipped: [...acc.skipped, { rule: rule.id, why: reasonsFor(doc).noLexicon(doc.language, rule.word_list) }] };
       }
       const found = detector(doc, options).map((finding) => place(starts, { ...finding, rule: rule.id, severity: rule.severity }));
       return { findings: [...acc.findings, ...found], skipped: acc.skipped };