chaffjs 0.17.0 → 0.18.0

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 };
+};

package/src/rule-guide.ts

@@ -0,0 +1,135 @@
+import type { Localized } from "./plugin.ts";
+
+/** How the rule reference groups rules for a reader who is not an engineer, in the order it lists them. */
+export const RULE_GROUPS = ["readability", "wording", "slips", "consistency", "structure", "facts", "ai-tells", "team"] as const;
+
+export type RuleGroup = (typeof RULE_GROUPS)[number];
+
+/** A group's name and one line on what is in it, as the reference and chaff rules show them. */
+export type GroupText = { readonly name: string; readonly note: string };
+
+const GROUP_TEXT: Readonly<Record<"ja" | "en", Readonly<Record<RuleGroup, GroupText>>>> = {
+  ja: {
+    readability: { name: "読みやすさ", note: "長すぎる文、詰めすぎた段落、読み手がつまずく書き方。" },
+    wording: { name: "言葉づかい", note: "中身を言わずに強める言い方、決まり文句、誰がしたのかを書かない受け身。" },
+    slips: { name: "書き損じ", note: "書き換えの途中で残った語や空白。" },
+    consistency: {
+      name: "表記の揃え",
+      note: "どちらで書いても正しいものが、一つの文書の中で混ざっている所。chaff はどちらが正しいかを決めず、少ないほうを指します。",
+    },
+    structure: { name: "構造", note: "番号の抜け、無い条への参照、同じ語の二重定義、長い前置き。" },
+    facts: { name: "事実の食い違い", note: "日付と曜日、日付の順番、合計と内訳のように、暦や計算で確かめられる食い違い。" },
+    "ai-tells": {
+      name: "AIっぽさ",
+      note: "生成された文章にありがちな特徴。どれも、それだけで生成されたとは言いません。読み返す場所の目印です。",
+    },
+    team: {
+      name: "チームの表記",
+      note: "chaff.yaml にチームが書いた表記・社内用語・必須の見出しだけを見るルール。書かなければ何も言いません。",
+    },
+  },
+  en: {
+    readability: { name: "Readability", note: "Sentences that run too long, packed paragraphs, and other places a reader stumbles." },
+    wording: { name: "Wording", note: "Emphasis that says nothing, stock phrases, and passives that never say who acted." },
+    slips: { name: "Slips", note: "Words and spaces left over from an edit." },
+    consistency: {
+      name: "Consistency",
+      note: "Two ways of writing that are both right, mixed in one document. chaff does not pick a side; it points at whichever the document uses less.",
+    },
+    structure: {
+      name: "Structure",
+      note: "Skipped numbers, references to provisions that are not there, terms defined twice, long preambles.",
+    },
+    facts: {
+      name: "Facts that disagree",
+      note: "A date and its weekday, dates out of order, a total and its items: disagreements a calendar or a sum can settle.",
+    },
+    "ai-tells": {
+      name: "Signs of generated text",
+      note: "Traits common in generated text. None of them alone says the text was generated; they mark places to reread.",
+    },
+    team: {
+      name: "Your team's words",
+      note: "Rules that check only what your team lists in chaff.yaml: spellings, jargon, required headings. With nothing listed, they say nothing.",
+    },
+  },
+};
+
+/** In Japanese for "ja", in English for any other language. */
+export const groupTextOf = (language: string, group: RuleGroup): GroupText => GROUP_TEXT[language === "ja" ? "ja" : "en"][group];
+
+/**
+ * A short text the rule flags and the same text fixed, with the chaff.yaml it needs (jargon, prefer, a level).
+ * pad: the rule measures a whole document of some length (per 1000 words), so the example is tried after an ordinary passage.
+ */
+export type RuleExample = {
+  readonly before: string;
+  readonly after: string;
+  readonly config?: Readonly<Record<string, unknown>>;
+  readonly pad?: boolean;
+};
+
+/** One finding of the rule itself on its example, as the command line reported it. */
+export type ExampleFinding = { readonly line: number; readonly column: number; readonly message: string };
+
+/** What the command line said about a rule on its example, before and after the fix (scripts/rule-examples.ts). */
+export type ExampleOutcome = {
+  readonly rule: string;
+  readonly language: string;
+  readonly before: readonly ExampleFinding[];
+  readonly after: readonly ExampleFinding[];
+};
+
+/** The plain-language part of a rule file: what the reference tells a reader, apart from the texts chaff prints. */
+export type RuleGuide = {
+  readonly group: RuleGroup | undefined;
+  /** What the rule finds, in one line. */
+  readonly summary: Localized;
+  /** By language. A rule that runs in one language has an example in that language only. */
+  readonly examples: Readonly<Record<string, RuleExample>>;
+  /** What the rule leaves alone on purpose, so a reader does not take silence for a miss. */
+  readonly notFlagged: Localized;
+  /** What a level's number means, with {limit} for the number ("一文 {limit} 字まで"). None when every level is the same. */
+  readonly levelMeaning: Localized;
+};
+
+const isRecord = (value: unknown): value is Record<string, unknown> => typeof value === "object" && value !== null && !Array.isArray(value);
+
+const isText = (value: unknown): value is string => typeof value === "string" && value.trim() !== "";
+
+const localizedOf = (value: unknown): Localized =>
+  isRecord(value) ? Object.fromEntries(Object.entries(value).filter((entry): entry is [string, string] => isText(entry[1]))) : {};
+
+const exampleOf = (value: unknown): RuleExample | undefined => {
+  if (!isRecord(value) || !isText(value["before"]) || !isText(value["after"])) return undefined;
+  const config = value["config"];
+  return {
+    before: value["before"],
+    after: value["after"],
+    ...(isRecord(config) ? { config } : {}),
+    ...(value["pad"] === true ? { pad: true } : {}),
+  };
+};
+
+const examplesOf = (value: unknown): Readonly<Record<string, RuleExample>> =>
+  isRecord(value)
+    ? Object.fromEntries(
+        Object.entries(value).flatMap(([language, entry]) => {
+          const example = exampleOf(entry);
+          return example === undefined ? [] : [[language, example] as const];
+        }),
+      )
+    : {};
+
+/** A field that is missing or malformed reads as empty; the test on rule files names what a rule lacks. */
+export const ruleGuideOf = (raw: Readonly<Record<string, unknown>>): RuleGuide => ({
+  group: RULE_GROUPS.find((group) => group === raw["group"]),
+  summary: localizedOf(raw["summary"]),
+  examples: examplesOf(raw["example"]),
+  notFlagged: localizedOf(raw["not_flagged"]),
+  levelMeaning: localizedOf(raw["level_meaning"]),
+});
+
+/** The rules in each group, in the order the reference lists them. A rule with no group is in none, which the test on rule files reports. */
+export const rulesByGroup = <T>(rules: readonly T[], groupOf: (rule: T) => RuleGroup | undefined): { group: RuleGroup; rules: T[] }[] =>
+  RULE_GROUPS.map((group) => ({ group, rules: rules.filter((rule) => groupOf(rule) === group) }));