chaffjs 0.16.0 → 0.18.0

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 = [

package/src/render/options.ts

@@ -0,0 +1,58 @@
+import type { OptionValue, RuleDefinition } from "../plugin.ts";
+import { DEFAULT_SOURCE, settleOptions, type OptionLayer } from "../rule-options.ts";
+import { localized } from "./text.ts";
+import type { Texts } from "../ui.ts";
+import { uiLanguageOf } from "../ui.ts";
+
+const printed = (value: OptionValue): string => (Array.isArray(value) ? `[${value.join(", ")}]` : String(value));
+
+/** A rule's options for rules --json: what each decides, what it may be, its default, its value now and which setting gave it. */
+export const optionsJson = (rule: RuleDefinition, layers: readonly OptionLayer[]): Record<string, unknown> | undefined => {
+  if (rule.options === undefined) return undefined;
+  const settled = settleOptions(rule.id, rule.options, layers);
+  return Object.fromEntries(
+    Object.entries(rule.options).map(([name, option]) => [
+      name,
+      {
+        kind: option.kind,
+        about: option.about,
+        ...(option.kind === "choice" ? { choices: option.choiceNames } : {}),
+        default: option.default,
+        now: settled[name]?.value ?? option.default,
+        from: settled[name]?.from ?? DEFAULT_SOURCE,
+      },
+    ]),
+  );
+};
+
+const TEXT: Texts<{ readonly heading: string; readonly byDefault: string; readonly from: (source: string) => string; readonly howTo: (id: string) => string }> =
+  {
+    ja: {
+      heading: "オプション（chaff.yaml の options で決めます）:",
+      byDefault: "既定",
+      from: (source) => `${source} から`,
+      howTo: (id) => `決める:  chaff.yaml に options: { ${id}: { <名前>: <値> } } を書く`,
+    },
+    en: {
+      heading: "Options (set under options in chaff.yaml):",
+      byDefault: "default",
+      from: (source) => `from ${source}`,
+      howTo: (id) => `Set one:  write options: { ${id}: { <name>: <value> } } in chaff.yaml`,
+    },
+  };
+
+/** A rule's options for explain: each one's value now and where it came from, what it decides, and each choice's meaning. */
+export const optionLines = (rule: RuleDefinition, layers: readonly OptionLayer[], language: string): string[] => {
+  if (rule.options === undefined) return [];
+  const text = TEXT[uiLanguageOf(language)];
+  const settled = settleOptions(rule.id, rule.options, layers);
+  const lines = Object.entries(rule.options).flatMap(([name, option]) => {
+    const now = settled[name];
+    const source = now === undefined || now.from === DEFAULT_SOURCE ? text.byDefault : text.from(now.from);
+    const choices = Object.entries(option.choiceNames).map(
+      ([choice, meaning]) => `      ${choice === now?.value ? "→" : " "} ${choice.padEnd(11)}${localized(meaning, language)}`,
+    );
+    return [`    ${name}: ${printed(now?.value ?? option.default)}   (${source})`, `      ${localized(option.about, language)}`, ...choices];
+  });
+  return ["", `  ${text.heading}`, ...lines, "", `  ${text.howTo(rule.id)}`];
+};

package/src/render/rules-json.ts

@@ -1,58 +1,104 @@
-import { definedLevels, resolve } from "../levels.ts";
+import { definedLevels, resolve, severityAt } from "../levels.ts";
 import type { Config } from "../config/load.ts";
-import type { RuleDefinition } from "../plugin.ts";
+import type { Level, Localized, RuleDefinition } from "../plugin.ts";
+import { readableText } from "./text.ts";
 import { uiLanguageOf, type Texts } from "../ui.ts";
-import { presetLevels } from "../genre-load.ts";
-import type { PresetLevels } from "../genre-parse.ts";
+import { loadGenres, presetLevels } from "../genre-load.ts";
+import { presetLevelsOf, type PresetLevels } from "../genre-parse.ts";
+import { RULE_GROUPS, groupTextOf } from "../rule-guide.ts";
+import { standingIn } from "../rule-genres.ts";
+import { optionsJson } from "./options.ts";
+import { styleLevelSource } from "../config/style.ts";
+import { loadStyles } from "../style-load.ts";
+import type { OptionLayer } from "../rule-options.ts";
 
 const TEXT: Texts<{
   readonly offBySetting: string;
   readonly offByGenre: (genre: string) => string;
+  readonly offUnsuited: (genre: string) => string;
   readonly offExperimental: string;
   readonly valuesNote: string;
   readonly reason: string;
   readonly byFile: string;
+  readonly optionsByFile: string;
+  readonly fromStyleNote: readonly string[];
 }> = {
   ja: {
     offBySetting: "設定で止めている",
     offByGenre: (genre) => `ジャンル ${genre} では見ない`,
+    offUnsuited: (genre) => `ジャンル ${genre} の文書には向かない rule（use_for）`,
     offExperimental: "experimental な rule は既定で動かさない",
     valuesNote: "この 4 語のかわりに数字を直接書いてもよい。4 語のほうを勧める。",
     reason: "<理由>",
     byFile: "chaff.yaml の rules に <rule-id>: <level> を足す。既定のままのものは書かない。",
+    optionsByFile: "options を持つ rule は、chaff.yaml の options に <rule-id>: { <option>: <value> } を足す。",
+    fromStyleNote: [
+      "チームの書き方の決まり（例: です・ます、1 文 80 字まで）を一つずつ読む。",
+      "決まりごとに、summary と level_meaning が合う rule を選ぶ。数の決まりは levels の数と比べ、合う段階を選ぶか数を直接書く。",
+      "文書の種類が分かれば genre を決める。rules[].genres で、そのジャンルで動くか・止まるかを確かめる。",
+      "表記の決まりは prefer、社内用語は jargon、必須の見出しは required_sections に書く。",
+      "既定と同じものは書かない。書いたら npx chaff explain <rule-id> と、決まりに沿った短い見本で確かめる。",
+    ],
   },
   en: {
     offBySetting: "turned off in the settings",
     offByGenre: (genre) => `the ${genre} genre does not check it`,
+    offUnsuited: (genre) => `not a rule for ${genre} documents (use_for)`,
     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.",
+    optionsByFile: "For a rule with options, add <rule-id>: { <option>: <value> } under options in chaff.yaml.",
+    fromStyleNote: [
+      "Read the team's style note one requirement at a time (for example: polite endings, sentences of at most 80 characters).",
+      "For each requirement, pick the rule whose summary and level_meaning match. For a number, compare it with the rule's levels and pick a level, or write the number itself.",
+      "If the kind of document is known, set genre, and check rules[].genres for whether each rule runs or is off in it.",
+      "Put spellings under prefer, in-house words under jargon, and required headings under required_sections.",
+      "Leave out anything at its default. Then check each rule with npx chaff explain <rule-id> and a short sample that follows the note.",
+    ],
   },
 };
 
 const now = (rule: RuleDefinition, config: Config, genre: string, text: (typeof TEXT)["ja"], preset: PresetLevels): Record<string, unknown> => {
+  // A run leaves out a rule whose use_for does not cover the genre before it reads any level.
+  if (standingIn(rule, genre, {}).kind === "unsuited") return { level: "off", why_off: text.offUnsuited(genre) };
   const explicit = config.rules[rule.id] ?? preset[rule.id];
   if (explicit === "off" && config.rules[rule.id] === undefined) return { level: "off", why_off: text.offByGenre(genre) };
   if (explicit === "off") return { level: "off", why_off: text.offBySetting };
-  const limit = rule.layer === "L4" ? undefined : config.limits[rule.id];
+  const limit = rule.level_sets === "severity" ? 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 (explicit !== undefined) return { level: explicit, ...effectAt(rule, explicit, genre) };
   if (rule.status === "experimental" && !config.experimental) {
     return { level: "off", why_off: text.offExperimental, turn_on_with: `npx chaff lint --experimental` };
   }
-  return { level: "normal", limit: resolve(rule, "normal", genre).limit };
+  return { level: "normal", ...effectAt(rule, "normal", genre) };
 };
 
+/** The level a rule runs at now, and why it is off when it is: what `chaff rules` shows in its table. */
+export const nowFor = (rule: RuleDefinition, config: Config, language: string, genre: string): Record<string, unknown> =>
+  now(rule, config, genre, TEXT[uiLanguageOf(language)], presetLevels(genre));
+
+/** What a level does to a rule: the limit it counts to, or, with nothing to count, the severity of its findings. */
+const effectAt = (rule: RuleDefinition, level: Exclude<Level, "off">, genre: string): Record<string, unknown> =>
+  rule.level_sets === "severity" ? { severity: severityAt(rule, level, genre) } : { limit: resolve(rule, level, genre).limit };
+
 const yourSetting = (rule: RuleDefinition, config: Config): Record<string, unknown> | null => {
   const level = config.rules[rule.id];
   if (level === undefined) return null;
-  const limit = rule.layer === "L4" ? undefined : config.limits[rule.id];
-  return limit === undefined ? { level, from: config.path } : { level, limit, from: config.path };
+  const from = styleLevelSource(config, rule.id) ?? config.path;
+  const limit = rule.level_sets === "severity" ? undefined : config.limits[rule.id];
+  return limit === undefined ? { level, from } : { level, limit, from };
+};
+
+/** The house style chaff.yaml names: what it decides and the guideline it follows, so an AI can say where a setting came from. */
+const styleOf = (config: Config): Record<string, unknown> | null => {
+  const style = loadStyles().find((entry) => entry.id === config.applied?.style);
+  return style === undefined ? null : { id: style.id, name: style.name, summary: style.summary, source: style.source };
 };
 
 /** ジャンルで数字が変わる rule があるので、いま効いている表と既定の表の両方を出す。 */
 const levelsOf = (rule: RuleDefinition, genre: string): Record<string, unknown> => {
+  if (rule.level_sets === "severity") return { levels: severitiesOf(rule, genre) };
   const effective = Object.fromEntries(
     definedLevels(rule)
       .filter((level) => level !== "off")
@@ -62,33 +108,103 @@ const levelsOf = (rule: RuleDefinition, genre: string): Record<string, unknown>
   return overridden ? { levels: effective, levels_default: rule.levels, levels_from: "by_genre" } : { levels: rule.levels };
 };
 
+const severitiesOf = (rule: RuleDefinition, genre: string): Record<string, string> =>
+  Object.fromEntries(
+    definedLevels(rule)
+      .filter((level) => level !== "off")
+      .map((level) => [level, severityAt(rule, level, genre)]),
+  );
+
+/** 指摘が無いので、置き場所は rule の言葉で読ませる。言語はどれも出す。 */
+const readableInEvery = (rule: RuleDefinition, field: Localized): Localized =>
+  Object.fromEntries(Object.keys(field).map((language) => [language, readableText(rule, field, language)]));
+
+const READER_LANGUAGES = ["ja", "en"];
+
+/** How the rule stands in every genre with no chaff.yaml, so an AI can pick a genre before it picks levels. */
+const genresOf = (rule: RuleDefinition): Record<string, Record<string, string>> => {
+  const data = loadGenres();
+  return Object.fromEntries(
+    data.genres.map((genre) => {
+      const standing = standingIn(rule, genre.id, presetLevelsOf(data, genre.id));
+      return [genre.id, standing.kind === "on" ? { runs: "on", level: standing.level } : { runs: standing.kind }];
+    }),
+  );
+};
+
+/** The plain-language part of the rule file: what it finds, an example, what it leaves alone, what a level means. */
+const guideOf = (rule: RuleDefinition): Record<string, unknown> => ({
+  group: rule.guide?.group ?? null,
+  summary: rule.guide?.summary ?? {},
+  example: rule.guide?.examples ?? {},
+  not_flagged: rule.guide?.notFlagged ?? {},
+  level_meaning: rule.guide?.levelMeaning ?? {},
+  languages: rule.languages ?? READER_LANGUAGES,
+  requires: rule.requires,
+  genres: genresOf(rule),
+});
+
+const groupsOf = (): Record<string, unknown>[] =>
+  RULE_GROUPS.map((group) => ({
+    id: group,
+    name: Object.fromEntries(READER_LANGUAGES.map((language) => [language, groupTextOf(language, group).name])),
+    note: Object.fromEntries(READER_LANGUAGES.map((language) => [language, groupTextOf(language, group).note])),
+  }));
+
+/**
+ * What the local-rules release adds. Named now so an AI reading the JSON knows they are coming and does not invent them.
+ * Filled in when they ship: the style presets under style:, the custom_rules types, and each rule's options.
+ */
+const COMING = {
+  style_presets: { status: "coming", presets: [] },
+  custom_rule_types: { status: "coming", planned: ["words", "pattern", "tokens", "module"] },
+  rule_options: { status: "coming", note: "Each rule's options (with their types and allowed values) will be listed under options." },
+};
+
 /** AI に設定を書かせるときの入口。推測せずに書けるだけの情報を 1 つに入れる。spec §19.3。 */
-export const rulesJson = (rules: readonly RuleDefinition[], config: Config, language: string, genre: string): string => {
+export const rulesJson = (
+  rules: readonly RuleDefinition[],
+  config: Config,
+  language: string,
+  genre: string,
+  optionLayers: readonly OptionLayer[] = [],
+): string => {
   const text = TEXT[uiLanguageOf(language)];
   const preset = presetLevels(genre);
   return JSON.stringify(
     {
-      schema_version: 1,
+      // 2: rules gained group, summary, example, not_flagged, level_meaning, languages, requires and genres,
+      // and groups and the coming local-rules fields were added. Nothing from 1 was removed or renamed.
+      schema_version: 2,
       config_file: "chaff.yaml",
       detected: { genre, language },
+      ...(config.applied === undefined ? {} : { style: styleOf(config) }),
       values_you_can_use: ["strict", "normal", "relaxed", "off"],
       values_note: text.valuesNote,
+      groups: groupsOf(),
+      ...COMING,
       rules: rules.map((rule) => ({
         id: rule.id,
         layer: rule.layer,
         status: rule.status,
-        name: rule.name,
-        why: rule.why,
-        how_to_fix: rule.how_to_fix,
+        name: readableInEvery(rule, rule.name),
+        why: readableInEvery(rule, rule.why),
+        how_to_fix: readableInEvery(rule, rule.how_to_fix),
         use_for: rule.use_for,
+        level_sets: rule.level_sets,
         ...levelsOf(rule, genre),
         levels_you_can_set: definedLevels(rule),
         your_setting: yourSetting(rule, config),
         now: now(rule, config, genre, text, preset),
+        ...(rule.options === undefined ? {} : { options: optionsJson(rule, optionLayers) }),
+        ...(rule.custom === undefined ? {} : { defined_in: "chaff.yaml custom_rules", custom: rule.custom }),
+        ...guideOf(rule),
       })),
+      how_to_write_settings_from_a_style_note: text.fromStyleNote,
       how_to_change: {
         by_command: ["relax", "strict", "off"].map((command) => `npx chaff ${command} <rule-id> --why "${text.reason}"`),
         by_file: text.byFile,
+        options_by_file: text.optionsByFile,
       },
     },
     null,

package/src/render/rules-table.ts

@@ -0,0 +1,91 @@
+import type { Config } from "../config/load.ts";
+import type { RuleDefinition } from "../plugin.ts";
+import { groupTextOf, rulesByGroup } from "../rule-guide.ts";
+import { uiLanguageOf, type Texts } from "../ui.ts";
+import { nowFor } from "./rules-json.ts";
+
+// `chaff rules`: every rule, grouped the way the reference groups them, with the level it runs at now.
+// `chaff rules --json` carries the same and more, for an AI to read.
+
+type RunsWhen = "default" | "experimental" | "team" | "test";
+
+const TEXT: Texts<{
+  readonly heading: (genre: string, count: number) => string;
+  readonly runsWhen: Readonly<Record<RunsWhen, string>>;
+  readonly ungrouped: string;
+  readonly footer: readonly string[];
+}> = {
+  ja: {
+    heading: (genre, count) => `chaff のルール ${count} 本（ジャンル ${genre}）`,
+    runsWhen: { default: "既定", experimental: "試験中", team: "要設定", test: "AI" },
+    ungrouped: "（グループ未設定）",
+    footer: [
+      "既定: 何も書かなくても動く   試験中: --experimental か chaff.yaml で動く",
+      "要設定: chaff.yaml に語や見出しを書いたときだけ   AI: npx chaff test で動く",
+      "",
+      "詳しく:    npx chaff explain <rule>",
+      "AI に渡す: npx chaff rules --json",
+    ],
+  },
+  en: {
+    heading: (genre, count) => `chaff's ${count} rules (genre ${genre})`,
+    runsWhen: { default: "default", experimental: "experimental", team: "needs list", test: "AI" },
+    ungrouped: "(no group yet)",
+    footer: [
+      "default: runs with no settings   experimental: runs with --experimental or a level in chaff.yaml",
+      "needs list: runs only on words or headings listed in chaff.yaml   AI: runs with npx chaff test",
+      "",
+      "More on one rule:  npx chaff explain <rule>",
+      "For an AI:         npx chaff rules --json",
+    ],
+  },
+};
+
+const runsWhenOf = (rule: RuleDefinition): RunsWhen => {
+  if (rule.layer === "L4") return "test";
+  if (rule.guide?.group === "team") return "team";
+  return rule.status === "experimental" ? "experimental" : "default";
+};
+
+/** Columns line up in a terminal only if a wide (CJK) character counts as two. */
+const widthOf = (text: string): number => Array.from(text).reduce((sum, char) => sum + ((char.codePointAt(0) ?? 0) >= 0x2e80 ? 2 : 1), 0);
+
+const pad = (text: string, width: number): string => `${text}${" ".repeat(Math.max(0, width - widthOf(text)))}`;
+
+/** "normal (100)", "strict (error)", or "off". */
+const levelNow = (now: Record<string, unknown>): string => {
+  const level = typeof now["level"] === "string" ? now["level"] : "";
+  const detail = now["limit"] ?? now["severity"];
+  return level !== "off" && (typeof detail === "number" || typeof detail === "string") ? `${level} (${String(detail)})` : level;
+};
+
+type Row = { readonly id: string; readonly level: string; readonly runs: string; readonly summary: string };
+
+/** A rule for one language only does not run on the others' documents, whatever its level says. */
+const forLanguage = (rule: RuleDefinition, language: string): boolean => rule.languages === undefined || rule.languages.includes(language);
+
+const rowOf = (rule: RuleDefinition, config: Config, language: string, genre: string): Row => ({
+  id: rule.id,
+  level: forLanguage(rule, language) ? levelNow(nowFor(rule, config, language, genre)) : `off (${(rule.languages ?? []).join("/")})`,
+  runs: TEXT[uiLanguageOf(language)].runsWhen[runsWhenOf(rule)],
+  summary: rule.guide?.summary[uiLanguageOf(language)] ?? "",
+});
+
+const lineOf = (row: Row, widths: { id: number; level: number; runs: number }): string =>
+  `  ${pad(row.id, widths.id)}  ${pad(row.level, widths.level)}  ${pad(row.runs, widths.runs)}  ${row.summary}`.trimEnd();
+
+export const rulesTable = (rules: readonly RuleDefinition[], config: Config, language: string, genre: string): string => {
+  const text = TEXT[uiLanguageOf(language)];
+  const grouped = rulesByGroup(rules, (rule) => rule.guide?.group).map(({ group, rules: members }) => ({ name: groupTextOf(language, group).name, members }));
+  // A rule added without its plain-language fields still shows, so the table never hides a rule that runs.
+  const ungrouped = { name: text.ungrouped, members: rules.filter((rule) => rule.guide?.group === undefined) };
+  const groups = [...grouped, ungrouped].map(({ name, members }) => ({ name, rows: members.map((rule) => rowOf(rule, config, language, genre)) }));
+  const rows = groups.flatMap((group) => group.rows);
+  const widths = {
+    id: Math.max(...rows.map((row) => widthOf(row.id))),
+    level: Math.max(...rows.map((row) => widthOf(row.level))),
+    runs: Math.max(...rows.map((row) => widthOf(row.runs))),
+  };
+  const body = groups.filter((group) => group.rows.length > 0).flatMap((group) => ["", group.name, ...group.rows.map((row) => lineOf(row, widths))]);
+  return [text.heading(genre, rows.length), ...body, "", ...text.footer].join("\n");
+};

package/src/render/sarif.ts

@@ -1,4 +1,4 @@
-import { localized, messageOf } from "./text.ts";
+import { messageOf, readableText } from "./text.ts";
 import type { Finding, RuleDefinition, Severity } from "../plugin.ts";
 
 /**
@@ -48,10 +48,10 @@ const ruleFor = (located: Located): RuleDefinition | undefined => located.rules.
 const sarifRule = (rule: RuleDefinition, language: string): SarifRule => ({
   id: ruleIdOf(rule.id),
   name: rule.id,
-  shortDescription: { text: localized(rule.name, language) },
+  shortDescription: { text: readableText(rule, rule.name, language) },
   // なぜ直すのかと、どう直すのかを一緒に上げる。指摘だけでは書いた人が動けない。
-  fullDescription: { text: localized(rule.why, language) },
-  help: { text: localized(rule.how_to_fix, language) },
+  fullDescription: { text: readableText(rule, rule.why, language) },
+  help: { text: readableText(rule, rule.how_to_fix, language) },
   properties: { tags: [rule.layer, ...rule.use_for] },
 });
 

package/src/render/semantic.ts

@@ -3,7 +3,7 @@ import type { UserCheck } from "../checks.ts";
 import type { Narrowing } from "../look-at.ts";
 import type { Job as Plan, SemanticResult } from "../run-semantic.ts";
 import { uiLanguageOf, type Texts, type UiLanguage } from "../ui.ts";
-import { MARK, localized } from "./text.ts";
+import { MARK, fill, localized } from "./text.ts";
 import { counted, formFor } from "./plural.ts";
 
 const RULE = 60;
@@ -129,13 +129,13 @@ const block = (finding: Finding, named: Named, language: UiLanguage): string[] =
   const confidence = finding.values["confidence"];
   const reason = String(finding.values["reason"] ?? "");
   const sure = confidence === undefined ? "" : `            ${text.confidence(String(confidence))}`;
-  const fix = named.howToFix.length > 0 ? ["", ...indent(`→ ${named.howToFix}`, "     ")] : [];
+  const fix = named.howToFix.length > 0 ? ["", ...indent(`→ ${fill(named.howToFix, finding.values)}`, "     ")] : [];
   return [
     "",
     // "12 行目" and "line 12" take the same width on a terminal, so the rule ends in the same column in both.
     `─── ${text.line(finding.line)} ${"─".repeat(Math.max(0, RULE - String(finding.line).length - 8))}`,
     "",
-    `  ${MARK[finding.severity] ?? "·"}  ${named.name}${sure}`,
+    `  ${MARK[finding.severity] ?? "·"}  ${fill(named.name, finding.values)}${sure}`,
     "",
     ...indent(reason, "     "),
     ...fix,

package/src/render/severity-name.ts

@@ -0,0 +1,10 @@
+import type { Severity } from "../plugin.ts";
+import type { Texts } from "../ui.ts";
+
+/** A severity as the summary line names it (エラー / 注意 / 参考, error / warning / note). */
+export const SEVERITY_NAME: Texts<Readonly<Record<Severity, string>>> = {
+  ja: { error: "エラー", warning: "注意", info: "参考" },
+  en: { error: "error", warning: "warning", info: "note" },
+};
+
+export const withArticle = (word: string): string => (/^[aeiou]/u.test(word) ? `an ${word}` : `a ${word}`);

package/src/render/text.ts

@@ -6,23 +6,37 @@ export const localized = (field: Localized, language: string): string => field[l
 /** `{count}` is the value; `{count|word|words}` is the form that agrees with it (English only; Japanese has no plural). */
 const PLACEHOLDER = /\{(\w+)(?:\|([^|{}]*)\|([^|{}]*))?\}/gu;
 
-const fill = (template: string, values: Readonly<Record<string, string | number>>): string =>
+export const fill = (template: string, values: Readonly<Record<string, string | number>>): string =>
   template.replace(PLACEHOLDER, (whole, key: string, singular: string | undefined, plural: string | undefined) => {
     const value = values[key];
     if (value === undefined) return whole;
     return singular === undefined || plural === undefined ? String(value) : formFor(value, singular, plural);
   });
 
-/** A template as the rule reference shows it: each agreeing form as its plural ("{count} such words"). */
-export const templateForReading = (template: string): string =>
-  template.replace(PLACEHOLDER, (whole, _key: string, singular: string | undefined, plural: string | undefined) =>
-    singular === undefined || plural === undefined ? whole : plural,
+/** A template as the rule reference shows it: each agreeing form as its plural ("{count} such words"), each value as its reading when given. */
+export const templateForReading = (template: string, readings: Readonly<Record<string, string>> = {}): string =>
+  template.replace(PLACEHOLDER, (whole, key: string, singular: string | undefined, plural: string | undefined) =>
+    singular === undefined || plural === undefined ? (readings[key] ?? whole) : plural,
   );
 
+/** A rule's text for one finding, with the finding's values in it. */
+export const filledText = (field: Localized, finding: Finding, language: string): string => fill(localized(field, language), finding.values);
+
+/** A rule's text where no finding fills it (explain, rules --json, the rule reference): each value as the rule's words for it. */
+export const readableText = (rule: Pick<RuleDefinition, "placeholders">, field: Localized, language: string): string => {
+  // The same fallback as the text itself: an English-only rule read in Japanese still gets its English words.
+  const readings = Object.fromEntries(
+    Object.entries(rule.placeholders ?? {}).flatMap(([key, reading]) => {
+      const words = localized(reading, language);
+      return words === "" ? [] : [[key, words]];
+    }),
+  );
+  return templateForReading(localized(field, language), readings);
+};
+
 const templateOf = (rule: RuleDefinition, finding: Finding): Localized =>
   (finding.variant === undefined ? undefined : rule.messages[finding.variant]) ?? rule.message;
 
-export const messageOf = (rule: RuleDefinition, finding: Finding, language: string): string =>
-  fill(localized(templateOf(rule, finding), language), finding.values);
+export const messageOf = (rule: RuleDefinition, finding: Finding, language: string): string => filledText(templateOf(rule, finding), finding, language);
 
 export const MARK: Readonly<Record<string, string>> = { error: "✖", warning: "⚠", info: "·" };

package/src/resolve-genre.ts

@@ -3,17 +3,20 @@ import type { Config } from "./config/load.ts";
 import type { GenreSource } from "./cli-text.ts";
 import { frontMatterGenre, GENRES, guessGenre } from "./genre.ts";
 import { unknownFrontMatterGenre } from "./genre-check.ts";
+import { plainSource } from "./plain-source.ts";
 
 /** unread: a genre the front matter wrote that chaff does not know, when the front matter was looked at. */
 type ResolvedGenre = { readonly genre: string; readonly from: GenreSource; readonly unread?: string | undefined };
 
-export const resolveGenre = (path: string, source: string, config: Config, cliGenre?: string): ResolvedGenre => {
+export const resolveGenre = (path: string, text: string, config: Config, cliGenre?: string): ResolvedGenre => {
   // コマンドで指定したものが最優先。その実行だけの指定だから、設定より強い。
   if (cliGenre !== undefined) return { genre: cliGenre, from: "--genre" };
   // パスごとの上書きが次。「全体はこう、ここだけは違う」を書けるようにする。
   const override = applyByPath(config.byPath, config.baseDir, path);
   if (override.genre !== undefined) return { genre: override.genre, from: "by_path" };
   if (config.genre !== undefined) return { genre: config.genre, from: "config" };
+  // front matter と行頭の手がかりは、buildDocument と同じく BOM と CRLF / CR をそろえた本文で読む。
+  const source = plainSource(text);
   const guess = guessGenre(path, source, frontMatterGenre(source));
   const unread = unknownFrontMatterGenre(source, GENRES);
   return guess === undefined ? { genre: "blog/tech", from: "default", unread } : { genre: guess.genre, from: guess.from, unread };

package/src/rule-genres.ts

@@ -0,0 +1,25 @@
+import type { Level, RuleDefinition } from "./plugin.ts";
+
+/**
+ * How a rule stands in one genre, with no chaff.yaml: the same order of precedence as a run (use_for, then the genre's
+ * preset, then the rule's status).
+ *   unsuited:     the rule is not for this kind of document (use_for), and does not run
+ *   genre-off:    the genre's preset turns it off
+ *   experimental: it runs only with --experimental or a level in chaff.yaml
+ *   on:           it runs, at this level
+ */
+export type GenreStanding =
+  | { readonly kind: "unsuited" }
+  | { readonly kind: "genre-off" }
+  | { readonly kind: "experimental" }
+  | { readonly kind: "on"; readonly level: Exclude<Level, "off">; readonly byPreset: boolean };
+
+type RuleFacts = Pick<RuleDefinition, "id" | "status" | "use_for">;
+
+export const standingIn = (rule: RuleFacts, genre: string, preset: Readonly<Record<string, Level>>): GenreStanding => {
+  if (!rule.use_for.some((target) => genre.startsWith(target))) return { kind: "unsuited" };
+  const fromPreset = preset[rule.id];
+  if (fromPreset === "off") return { kind: "genre-off" };
+  if (fromPreset !== undefined) return { kind: "on", level: fromPreset, byPreset: true };
+  return rule.status === "experimental" ? { kind: "experimental" } : { kind: "on", level: "normal", byPreset: false };
+};