chaffjs 0.20.0 → 0.22.0

package/src/render/rules-json.ts

@@ -13,6 +13,7 @@ import { limitsFor, styleLevelSource } from "../config/style.ts";
 import { loadStyles } from "../style-load.ts";
 import type { OptionLayer } from "../rule-options.ts";
 import { CUSTOM_TYPES } from "../custom/parse.ts";
+import { DEFAULT_DEPTH, REWRITE_DEPTHS, depthMeaning } from "../rewrite-depth.ts";
 
 const TEXT: Texts<{
   readonly offBySetting: string;
@@ -39,7 +40,7 @@ const TEXT: Texts<{
       "決まりごとに、summary と level_meaning が合う rule を選ぶ。数の決まりは levels の数と比べ、合う段階を選ぶか数を直接書く。",
       "文書の種類が分かれば genre を決める。rules[].genres で、そのジャンルで動くか・止まるかを確かめる。",
       "表記の決まりは prefer、社内用語は jargon、必須の見出しは required_sections に書く。",
-      "既定と同じものは書かない。書いたら npx chaff explain <rule-id> と、決まりに沿った短い見本で確かめる。",
+      "既定と同じものは書かない。書いたら npx chaffjs explain <rule-id> と、決まりに沿った短い見本で確かめる。",
     ],
   },
   en: {
@@ -56,7 +57,7 @@ const TEXT: Texts<{
       "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.",
+      "Leave out anything at its default. Then check each rule with npx chaffjs explain <rule-id> and a short sample that follows the note.",
     ],
   },
 };
@@ -146,11 +147,20 @@ const guideOf = (rule: RuleDefinition): Record<string, unknown> => ({
   example: rule.guide?.examples ?? {},
   not_flagged: rule.guide?.notFlagged ?? {},
   level_meaning: rule.guide?.levelMeaning ?? {},
+  // The depth chaff fix-plan files the rule's direction under; a rule that does not say is light.
+  rewrite_depth: rule.guide?.rewriteDepth ?? DEFAULT_DEPTH,
   languages: rule.languages ?? READER_LANGUAGES,
   requires: rule.requires,
   genres: genresOf(rule),
 });
 
+/** Each rewrite depth with what it means, shallowest first: the values of rules[].rewrite_depth and of fix_plan.depth. */
+const depthsOf = (): Record<string, unknown>[] =>
+  REWRITE_DEPTHS.map((depth) => ({
+    id: depth,
+    meaning: Object.fromEntries(READER_LANGUAGES.map((language) => [language, depthMeaning(depth, uiLanguageOf(language))])),
+  }));
+
 const groupsOf = (): Record<string, unknown>[] =>
   RULE_GROUPS.map((group) => ({
     id: group,
@@ -190,6 +200,7 @@ export const rulesJson = (
       values_you_can_use: ["strict", "normal", "relaxed", "off"],
       values_note: text.valuesNote,
       groups: groupsOf(),
+      rewrite_depths: depthsOf(),
       ...COMING,
       rules: rules.map((rule) => ({
         id: rule.id,
@@ -212,7 +223,7 @@ export const rulesJson = (
       })),
       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_command: ["relax", "strict", "off"].map((command) => `npx chaffjs ${command} <rule-id> --why "${text.reason}"`),
         by_file: text.byFile,
         options_by_file: text.optionsByFile,
       },

package/src/render/rules-table.ts

@@ -21,10 +21,10 @@ const TEXT: Texts<{
     ungrouped: "（グループ未設定）",
     footer: [
       "既定: 何も書かなくても動く   試験中: --experimental か chaff.yaml で動く",
-      "要設定: chaff.yaml に語や見出しを書いたときだけ   AI: npx chaff test で動く",
+      "要設定: chaff.yaml に語や見出しを書いたときだけ   AI: npx chaffjs test で動く",
       "",
-      "詳しく:    npx chaff explain <rule>",
-      "AI に渡す: npx chaff rules --json",
+      "詳しく:    npx chaffjs explain <rule>",
+      "AI に渡す: npx chaffjs rules --json",
     ],
   },
   en: {
@@ -33,10 +33,10 @@ const TEXT: Texts<{
     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",
+      "needs list: runs only on words or headings listed in chaff.yaml   AI: runs with npx chaffjs test",
       "",
-      "More on one rule:  npx chaff explain <rule>",
-      "For an AI:         npx chaff rules --json",
+      "More on one rule:  npx chaffjs explain <rule>",
+      "For an AI:         npx chaffjs rules --json",
     ],
   },
 };

package/src/render/semantic.ts

@@ -43,7 +43,7 @@ const TEXT: Texts<{
     confidence: (value) => `確からしさ ${value}`,
     disagree: ["     この指摘が違うと思ったら:"],
     silence: (rule) => `       この箇所だけ黙らせる    <!-- stet: ${rule} — 理由 -->`,
-    relax: (rule) => `       ルールごとゆるめる      npx chaff relax ${rule}`,
+    relax: (rule) => `       ルールごとゆるめる      npx chaffjs relax ${rule}`,
     notRunChecks: (count) => `  ${count} 件の検査は、見るところが無いため動いていません。`,
     byMachine: "機械で絞り込み済み",
     whole: "絞り込めず全文",
@@ -68,7 +68,7 @@ const TEXT: Texts<{
     confidence: (value) => `confidence ${value}`,
     disagree: ["     If you think this finding is wrong:"],
     silence: (rule) => `       Silence this spot only    <!-- stet: ${rule} — reason -->`,
-    relax: (rule) => `       Relax the whole rule      npx chaff relax ${rule}`,
+    relax: (rule) => `       Relax the whole rule      npx chaffjs relax ${rule}`,
     notRunChecks: (count) => `  ${counted(count, "check")} did not run: there was nothing for ${formFor(count, "it", "them")} to look at.`,
     byMachine: "narrowed by machine",
     whole: "not narrowed: the whole text",

package/src/render/suppressions.ts

@@ -20,7 +20,7 @@ const TEXT: Texts<{
     more: (n) => ` ほか ${n} ファイル`,
     count: (n) => `${String(n).padStart(3)} 件`,
     reasons: (list) => `理由: ${list}`,
-    relaxAll: (rule) => `ルールごとゆるめる: npx chaff relax ${rule} --why "..."`,
+    relaxAll: (rule) => `ルールごとゆるめる: npx chaffjs relax ${rule} --why "..."`,
     none: "\n  抑制されている指摘はありません。\n",
     total: (n) => `抑制されている指摘: ${n} 件`,
     reasonless: (n) => `理由が書かれていない抑制: ${n} 件`,
@@ -32,7 +32,7 @@ const TEXT: Texts<{
     more: (n) => ` and ${counted(n, "more file")}`,
     count: (n) => `${String(n).padStart(3)}`,
     reasons: (list) => `reasons: ${list}`,
-    relaxAll: (rule) => `relax the whole rule: npx chaff relax ${rule} --why "..."`,
+    relaxAll: (rule) => `relax the whole rule: npx chaffjs relax ${rule} --why "..."`,
     none: "\n  No findings are silenced.\n",
     total: (n) => `Silenced findings: ${n}`,
     reasonless: (n) => `Silenced without a reason: ${n}`,

package/src/rewrite-depth.ts

@@ -0,0 +1,60 @@
+import type { Texts, UiLanguage } from "./ui.ts";
+
+// How deep a rewrite goes, shallowest first. A rule's rewrite block says how deep its direction reaches, and
+// chaff fix-plan --depth (or fix_plan.depth in chaff.yaml) says how deep the rewrite may go. A depth includes the
+// shallower ones: a structure rewrite also fixes words and sentences. Pure.
+
+export const REWRITE_DEPTHS = ["light", "structure", "register"] as const;
+
+export type RewriteDepth = (typeof REWRITE_DEPTHS)[number];
+
+/** A rule without a depth of its own, or without a rewrite block, fixes words and sentences. */
+export const DEFAULT_DEPTH: RewriteDepth = "light";
+
+const isRewriteDepth = (value: unknown): value is RewriteDepth => REWRITE_DEPTHS.some((depth) => depth === value);
+
+const isRecord = (value: unknown): value is Record<string, unknown> => typeof value === "object" && value !== null && !Array.isArray(value);
+
+const rankOf = (depth: RewriteDepth): number => REWRITE_DEPTHS.indexOf(depth);
+
+/** Whether a rewrite that may go as deep as `allowed` covers a rule whose direction reaches `needed`. */
+export const depthIncludes = (allowed: RewriteDepth, needed: RewriteDepth): boolean => rankOf(needed) <= rankOf(allowed);
+
+/** A depth as written: none, one chaff knows, or a value to report as it was written. */
+export type DepthRead = { readonly depth: RewriteDepth | undefined } | { readonly unknown: string };
+
+/** rewrite.depth, chaff.yaml's fix_plan.depth or --depth as written. Nothing written is no depth; anything else must be a depth. */
+export const readDepth = (written: unknown): DepthRead => {
+  if (written === undefined || written === null) return { depth: undefined };
+  if (isRewriteDepth(written)) return { depth: written };
+  return { unknown: typeof written === "string" ? written : (JSON.stringify(written) ?? typeof written) };
+};
+
+/** rewrite.depth of a rule's rewrite block, which is otherwise keyed by language. */
+export const depthOfRewrite = (rewrite: unknown): DepthRead => (isRecord(rewrite) ? readDepth(rewrite["depth"]) : { depth: undefined });
+
+const MEANING: Texts<Readonly<Record<RewriteDepth, string>>> = {
+  ja: {
+    light: "語と文を直す。構成と文体は残す",
+    structure: "節・見出し・段落を組み替える",
+    register: "文体を変える（です・ます → である、比べる言い方を外す など）",
+  },
+  en: {
+    light: "words and sentences; the structure and the voice stay",
+    structure: "sections, headings and paragraphs are reorganised",
+    register: "the style is converted: polite to plain endings, comparatives removed and so on",
+  },
+};
+
+/** What a depth means, in a reader's words. */
+export const depthMeaning = (depth: RewriteDepth, ui: UiLanguage): string => MEANING[ui][depth];
+
+/** Every depth with its meaning, shallowest first: "light (…) / structure (…) / register (…)". */
+const depthChoices = (ui: UiLanguage): string =>
+  REWRITE_DEPTHS.map((depth) => (ui === "ja" ? `${depth}（${MEANING.ja[depth]}）` : `${depth} (${MEANING.en[depth]})`)).join(" / ");
+
+/** Why a written depth cannot be read, with every depth chaff knows. where: what was written ("rewrite.depth", "--depth"). */
+export const unknownDepthSentence = (where: string, written: string, ui: UiLanguage): string =>
+  ui === "ja"
+    ? `${where}: ${written} は書き直しの深さではありません。深さは ${depthChoices("ja")} のどれかで、深いほうは浅いほうを含みます。`
+    : `${where}: ${written} is not a rewrite depth. A depth is one of ${depthChoices("en")}; a deeper one includes the shallower.`;

package/src/rule-fields.ts

@@ -0,0 +1,123 @@
+import { RULE_GROUPS } from "./rule-guide.ts";
+import { depthOfRewrite, unknownDepthSentence } from "./rewrite-depth.ts";
+import type { Texts, UiLanguage } from "./ui.ts";
+
+// The fields a rule has whoever writes it: chaff's own rules/*.yaml, a team's custom_rules and a plugin's rules all
+// read these the same way, and all three refuse the same malformed values with the same sentence. Pure: the genres a
+// use_for entry may name come in.
+
+export type FieldProblem =
+  | { readonly kind: "bad-depth"; readonly written: string }
+  | { readonly kind: "bad-group"; readonly written: string }
+  | { readonly kind: "bad-use-for"; readonly written: string }
+  | { readonly kind: "bad-summary"; readonly written: string }
+  | { readonly kind: "bad-text"; readonly written: string }
+  | { readonly kind: "bad-example"; readonly written: string };
+
+export type FieldKind = FieldProblem["kind"];
+
+/** Every kind, for a caller that reports these among problems of its own. */
+export const FIELD_KINDS: ReadonlySet<string> = new Set<FieldKind>(["bad-depth", "bad-group", "bad-use-for", "bad-summary", "bad-example", "bad-text"]);
+
+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 printed = (value: unknown): string => (typeof value === "string" ? value : (JSON.stringify(value) ?? typeof value));
+
+/** A text in every language (one string) or by language ({ ja, en }), with no empty text. */
+const isTextByLanguage = (value: unknown): boolean =>
+  isText(value) || (isRecord(value) && Object.values(value).length > 0 && Object.values(value).every(isText));
+
+const groupProblems = (group: unknown): FieldProblem[] =>
+  group === undefined || RULE_GROUPS.some((known) => known === group) ? [] : [{ kind: "bad-group", written: printed(group) }];
+
+/** A use_for entry names a genre or the start of one (business covers business/report). */
+const namesGenre = (entry: unknown, genres: readonly string[]): boolean =>
+  isText(entry) && genres.some((genre) => genre === entry || genre.startsWith(`${entry}/`));
+
+const useForProblems = (useFor: unknown, genres: readonly string[]): FieldProblem[] => {
+  if (useFor === undefined) return [];
+  if (!Array.isArray(useFor) || useFor.length === 0) return [{ kind: "bad-use-for", written: printed(useFor) }];
+  return useFor.filter((entry: unknown) => !namesGenre(entry, genres)).map((entry: unknown) => ({ kind: "bad-use-for", written: printed(entry) }));
+};
+
+const summaryProblems = (summary: unknown): FieldProblem[] =>
+  summary === undefined || isTextByLanguage(summary) ? [] : [{ kind: "bad-summary", written: printed(summary) }];
+
+/** A language as a key of a text by language: ja, en, pt-br. */
+const LANGUAGE_KEY = /^[a-z]{2,3}(?:-[a-z0-9]+)*$/iu;
+
+/** The texts a reader sees. Each may be one string or one per language. */
+const TEXT_FIELDS = ["name", "why", "how_to_fix", "message", "summary"] as const;
+
+/**
+ * A text by language whose key is not a language, or whose value is not a text. In YAML, { en: Write a date, or a
+ * number of days } is two entries, the second keyed " or a number of days": without this, the text is cut silently.
+ */
+const textProblems = (raw: Readonly<Record<string, unknown>>): FieldProblem[] =>
+  TEXT_FIELDS.flatMap((field) => {
+    const value = raw[field];
+    if (!isRecord(value)) return [];
+    return Object.entries(value)
+      .filter(([key, text]) => !LANGUAGE_KEY.test(key) || typeof text !== "string")
+      .map(([key]) => ({ kind: "bad-text" as const, written: `${field}: ${JSON.stringify(key)}` }));
+  });
+
+/** One example: before and after, each a text in every language or by language. */
+const isExamplePair = (value: unknown): boolean => isRecord(value) && isTextByLanguage(value["before"]) && isTextByLanguage(value["after"]);
+
+/**
+ * example in either form: { before, after } (a team's rule writes it so), or by language, { ja: { before, after }, en: … }
+ * (chaff's rules write it so, with config, pad and other beside before and after).
+ */
+const exampleProblems = (example: unknown): FieldProblem[] => {
+  if (example === undefined) return [];
+  if (isRecord(example) && ("before" in example || "after" in example))
+    return isExamplePair(example) ? [] : [{ kind: "bad-example", written: printed(example) }];
+  if (!isRecord(example) || Object.keys(example).length === 0) return [{ kind: "bad-example", written: printed(example) }];
+  return Object.entries(example).flatMap(([language, pair]) => (isExamplePair(pair) ? [] : [{ kind: "bad-example" as const, written: language }]));
+};
+
+const depthProblems = (rewrite: unknown): FieldProblem[] => {
+  const read = depthOfRewrite(rewrite);
+  return "unknown" in read ? [{ kind: "bad-depth", written: read.unknown }] : [];
+};
+
+/** What is wrong with the shared fields of one rule as written, in the order the fields are listed here. */
+export const fieldProblems = (raw: Readonly<Record<string, unknown>>, genres: readonly string[]): FieldProblem[] => [
+  ...groupProblems(raw["group"]),
+  ...summaryProblems(raw["summary"]),
+  ...useForProblems(raw["use_for"], genres),
+  ...exampleProblems(raw["example"]),
+  ...depthProblems(raw["rewrite"]),
+  ...textProblems(raw),
+];
+
+const TEXT: Texts<Readonly<Record<FieldKind, (written: string) => string>>> = {
+  ja: {
+    "bad-depth": (written) => unknownDepthSentence("rewrite.depth", written, "ja"),
+    "bad-group": (written) => `group: ${written} は分類の名前ではありません（${RULE_GROUPS.join(" / ")}）。`,
+    "bad-use-for": (written) =>
+      `use_for: ${written} はジャンルではありません。ジャンルかその頭（business、business/report）を並べます。一覧は npx chaffjs genres。`,
+    "bad-summary": (written) => `summary: ${written} は読めません。一つの文字列か、言語ごとの文字列（{ ja: …, en: … }）で書きます。`,
+    "bad-text": (written) =>
+      `${written} は言語ではありません。{ } の中のカンマは項目の区切りになるので、カンマのある文は引用符で囲みます（en: "Write a date, or a number of days."）。`,
+    "bad-example": (written) =>
+      `example: ${written} の before と after が揃っていません。{ before, after } か、言語ごとに { ja: { before, after }, en: { before, after } } と書きます。`,
+  },
+  en: {
+    "bad-depth": (written) => unknownDepthSentence("rewrite.depth", written, "en"),
+    "bad-group": (written) => `group: ${written} is not a group (${RULE_GROUPS.join(" / ")}).`,
+    "bad-use-for": (written) =>
+      `use_for: ${written} is not a genre. List genres or their first part (business, business/report); npx chaffjs genres lists them.`,
+    "bad-summary": (written) => `summary: cannot read ${written}. Write one string, or one per language ({ ja: …, en: … }).`,
+    "bad-text": (written) =>
+      `${written} is not a language. Inside { }, a comma separates entries, so quote a text that has one (en: "Write a date, or a number of days.").`,
+    "bad-example": (written) =>
+      `example: ${written} lacks a before or an after. Write { before, after }, or one per language: { ja: { before, after }, en: { before, after } }.`,
+  },
+};
+
+/** What is wrong, with the value as written and what would be right. */
+export const fieldProblemSentence = (problem: FieldProblem, ui: UiLanguage): string => TEXT[ui][problem.kind](problem.written);

package/src/rule-guide.ts

@@ -1,4 +1,5 @@
 import type { Localized } from "./plugin.ts";
+import { depthOfRewrite, type RewriteDepth } from "./rewrite-depth.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;
@@ -111,6 +112,8 @@ export type RuleGuide = {
   readonly sources: readonly string[];
   /** By language, optional per rule. */
   readonly rewrite: Readonly<Record<string, RuleRewrite>>;
+  /** rewrite.depth: how deep the block's direction reaches. None when not written or not a depth; the loaders report the latter. */
+  readonly rewriteDepth?: RewriteDepth | undefined;
 };
 
 const isRecord = (value: unknown): value is Record<string, unknown> => typeof value === "object" && value !== null && !Array.isArray(value);
@@ -160,6 +163,11 @@ const rewritesOf = (value: unknown): Readonly<Record<string, RuleRewrite>> =>
     ? Object.fromEntries(Object.entries(value).flatMap(([language, entry]) => (isRecord(entry) ? [[language, rewriteOf(entry)] as const] : [])))
     : {};
 
+const rewriteDepthOf = (rewrite: unknown): RewriteDepth | undefined => {
+  const read = depthOfRewrite(rewrite);
+  return "depth" in read ? read.depth : undefined;
+};
+
 /** 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"]),
@@ -169,6 +177,7 @@ export const ruleGuideOf = (raw: Readonly<Record<string, unknown>>): RuleGuide =
   levelMeaning: localizedOf(raw["level_meaning"]),
   sources: textsOf(raw["sources"]),
   rewrite: rewritesOf(raw["rewrite"]),
+  rewriteDepth: rewriteDepthOf(raw["rewrite"]),
 });
 
 /** 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. */

package/src/rule-load.ts

@@ -6,6 +6,8 @@ import type { LanguageLevels, LevelSets, LevelTable, RuleDefinition, Severity }
 import { rankOfSeverity, severityAt } from "./levels.ts";
 import { optionsOf } from "./rule-options.ts";
 import { ruleGuideOf } from "./rule-guide.ts";
+import { fieldProblemSentence, fieldProblems } from "./rule-fields.ts";
+import { genresBeside } from "./known-genres.ts";
 
 const RULES_DIR = join(dirname(fileURLToPath(import.meta.url)), "..", "rules");
 
@@ -142,12 +144,14 @@ const checkedSeverity = (rule: RuleDefinition, file: string): RuleDefinition =>
   throw new Error(`${file}: severity ${rule.severity} が levels の normal（${severityAt(rule, "normal")}）と違います`);
 };
 
-const toRule = (raw: unknown, language: string, file: string): RuleDefinition => {
+const toRule = (raw: unknown, language: string, file: string, genres: readonly string[]): RuleDefinition => {
   if (!isRecord(raw)) throw new Error(`${file}: rule は object であること`);
   const levels = flattenLevels(raw["levels"], language);
   const missing = missingFields(raw, levels);
   if (missing.length > 0) throw new Error(`${file}: 必須フィールドがありません: ${missing.join(", ")}`);
   if (levels === undefined) throw new Error(`${file}: levels を解決できません`);
+  const [problem] = fieldProblems(raw, genres);
+  if (problem !== undefined) throw new Error(`${file}: ${fieldProblemSentence(problem, "ja")}`);
   return checkedSeverity(ruleOf(raw, levels, levelSetsOf(raw, language, file), language, file), file);
 };
 
@@ -193,8 +197,10 @@ const parseRule = (dir: string, file: string): unknown => {
   }
 };
 
-export const loadRules = (language: string, dir: string = RULES_DIR): RuleDefinition[] =>
-  readdirSync(dir)
+export const loadRules = (language: string, dir: string = RULES_DIR): RuleDefinition[] => {
+  const genres = genresBeside(dir);
+  return readdirSync(dir)
     .filter((file) => file.endsWith(".yaml"))
     .toSorted((left, right) => left.localeCompare(right, "en"))
-    .map((file) => toRule(parseRule(dir, file), language, file));
+    .map((file) => toRule(parseRule(dir, file), language, file, genres));
+};

package/src/rule-offs.ts

@@ -0,0 +1,50 @@
+import { readFileSync, readdirSync } from "node:fs";
+import { join } from "node:path";
+import { parse } from "yaml";
+
+/** One rule a group or genre turns off by default, from the rule file's off_for, with why. */
+export type RuleOff = { readonly rule: string; readonly target: string; readonly reason: string };
+
+const isRecord = (value: unknown): value is Record<string, unknown> => typeof value === "object" && value !== null && !Array.isArray(value);
+
+/** A rule file's off_for block: the "off_for:" line and the indented lines under it. */
+const OFF_FOR_BLOCK = /^off_for:\n(?:[ \t]+[^\n]*\n?)*/mu;
+/** Any top-level off_for line, of whatever form. Only the block form is read, the form `yarn rules:measure --apply` edits. */
+const OFF_FOR_LINE = /^off_for:.*$/gmu;
+
+/** The off_for map of one rule file (the group or genre, then why), checked; empty when the file has none. */
+export const ruleOffsOf = (rule: string, raw: unknown): RuleOff[] => {
+  if (raw === undefined || raw === null) return [];
+  if (!isRecord(raw)) throw new Error(`${rule}: off_for must map a group or genre to why it turns the rule off`);
+  return Object.entries(raw).map(([target, reason]) => {
+    if (typeof reason !== "string" || reason.trim() === "") throw new Error(`${rule}: off_for.${target} needs a reason`);
+    return { rule, target, reason };
+  });
+};
+
+/** The off_for block of one rule file's text, or undefined; a second block or another form stops here. */
+const offForBlock = (rule: string, text: string): string | undefined => {
+  const lines = [...text.matchAll(OFF_FOR_LINE)].map((match) => match[0]);
+  if (lines.length === 0) return undefined;
+  if (lines.length > 1 || lines[0] !== "off_for:")
+    throw new Error(`${rule}: write off_for once, as "off_for:" with one indented "<group or genre>: <why>" line under it per off`);
+  return OFF_FOR_BLOCK.exec(text)?.[0];
+};
+
+/** The offs of one rule file. The rule is named by the file, which is named by the rule's id. */
+const offsInFile = (dir: string, file: string): RuleOff[] => {
+  const rule = file.replace(/\.yaml$/u, "");
+  const block = offForBlock(rule, readFileSync(join(dir, file), "utf8").replaceAll("\r\n", "\n"));
+  const parsed: unknown = block === undefined ? undefined : parse(block);
+  return ruleOffsOf(rule, isRecord(parsed) ? parsed["off_for"] : undefined);
+};
+
+/**
+ * The offs of every rule file in `dir`. Only each file's off_for block is parsed, not the whole rule: genres are read
+ * at startup, before any rule is.
+ */
+export const loadRuleOffs = (dir: string): RuleOff[] =>
+  readdirSync(dir)
+    .filter((file) => file.endsWith(".yaml"))
+    .toSorted((left, right) => left.localeCompare(right, "en"))
+    .flatMap((file) => offsInFile(dir, file));

package/src/structure/build.ts

@@ -286,6 +286,26 @@ const numberedLine = (state: State, patterns: StructurePatterns, text: string, c
   unnumberedUnit(text, openUnits(state), state.profile?.unnumbered) ??
   universalNumber(patterns, text, context, state.plainText);
 
+/** A dotted number alone: what is left of 「### 29.3 `chaff grade`」 once its code is blanked and the line trimmed. */
+const NUMBER_ONLY = /^\d{1,3}(?:\.\d{1,3}){1,5}[.．]?$/u;
+
+/**
+ * A heading whose title is all inline code is numbered as written. Its rest is left empty: the code is not prose to read,
+ * and the blanked line has no place for it. A heading that is only a number as written (a changelog's 「## 46.3」) stays unnumbered.
+ */
+const codeTitledNumber = (
+  state: State,
+  patterns: StructurePatterns,
+  text: string,
+  heading: Heading | undefined,
+  context: NumberingContext,
+): NumberedLine | undefined => {
+  const written = heading?.text.trim() ?? "";
+  if (!NUMBER_ONLY.test(text) || written === text) return undefined;
+  const numbered = numberedLine(state, patterns, written, context);
+  return numbered === undefined ? undefined : { ...numbered, rest: "" };
+};
+
 /** 番号の後ろが見出しでなく本文か。前の行から見出しが付く前の、行そのもので決める。 */
 const carriesBody = (found: NumberedLine | undefined): boolean => found !== undefined && found.heading === "" && found.rest !== "";
 
@@ -302,7 +322,7 @@ const readLine = (state: State, patterns: StructurePatterns, line: Line, heading
   const text = heading === undefined ? line.text : headingLineText(line.text);
   const openNumbers = state.stack.flatMap((frame) => (frame.numbered === undefined ? [] : [frame.numbered]));
   const context = { open: openNumbers, isHeading: heading !== undefined };
-  const found = around.inTable ? undefined : numberedLine(state, patterns, text, context);
+  const found = around.inTable ? undefined : (numberedLine(state, patterns, text, context) ?? codeTitledNumber(state, patterns, text, heading, context));
   const numbered = withCaption(state, line, found);
   const caption = numbered === undefined && heading === undefined ? captionOf(state.profile, text) : undefined;
   if (caption !== undefined) state.captions.set(line.number, caption);

package/src/structure/cross-definitions.ts

@@ -0,0 +1,60 @@
+import { tallyVotes, type Vote } from "../cross-votes.ts";
+
+// One term defined in two files of one run, in different words. Pure: the definitions come in already read from each file.
+
+/** A definition as a file writes it: the term, what follows it up to the end of the sentence, and where it is. */
+export type WrittenDefinition = { readonly term: string; readonly body: string; readonly offset: number };
+
+export type FileDefinitions = { readonly path: string; readonly definitions: readonly WrittenDefinition[] };
+
+/** A file that defines a term unlike most files that define it, and one file of the usual wording. */
+export type DefinitionOutOfStep = {
+  readonly path: string;
+  readonly definition: WrittenDefinition;
+  readonly usual: Vote<WrittenDefinition>;
+  readonly files: number;
+};
+
+/** Marks that do not change what a definition says: the punctuation at its two ends. Spaces are evened out apart. */
+const LEADING: ReadonlySet<string> = new Set(["、", "，", ",", ":", "："]);
+const TRAILING: ReadonlySet<string> = new Set(["。", "．", "."]);
+const SPACE = /\s+/gu;
+
+const SPACE_CHAR = /\s/u;
+
+/** The text without spaces and the marks of a set at its start, or at its end. */
+const trimStartOf = (text: string, marks: ReadonlySet<string>): string => {
+  const first = text.split("").findIndex((char) => !marks.has(char) && !SPACE_CHAR.test(char));
+  return first === -1 ? "" : text.slice(first);
+};
+
+const trimEndOf = (text: string, marks: ReadonlySet<string>): string =>
+  text.slice(0, text.split("").findLastIndex((char) => !marks.has(char) && !SPACE_CHAR.test(char)) + 1);
+
+/** The wording compared: width, spaces and the punctuation at the ends evened out. */
+export const definitionKey = (body: string): string =>
+  trimEndOf(trimStartOf(body.normalize("NFKC"), LEADING), TRAILING)
+    .replace(SPACE, " ")
+    .trim();
+
+/** A file's vote for a term: its first definition of it (a second one in the same file is duplicate-definition's). */
+const voteOf = (file: FileDefinitions, term: string): Vote<WrittenDefinition>[] => {
+  const first = file.definitions.find((definition) => definition.term === term && definitionKey(definition.body) !== "");
+  return first === undefined ? [] : [{ path: file.path, value: first }];
+};
+
+const sameWording = (left: WrittenDefinition, right: WrittenDefinition): boolean => definitionKey(left.body) === definitionKey(right.body);
+
+/** The files that define a term in other words than most files of the run that define it. */
+export const definitionsOutOfStep = (files: readonly FileDefinitions[]): DefinitionOutOfStep[] => {
+  const terms = [...new Set(files.flatMap((file) => file.definitions.map((definition) => definition.term)))];
+  return terms.flatMap((term) => {
+    const tally = tallyVotes(
+      files.flatMap((file) => voteOf(file, term)),
+      sameWording,
+    );
+    const [usual] = tally?.usual ?? [];
+    if (tally === undefined || usual === undefined) return [];
+    return tally.odd.map((vote) => ({ path: vote.path, definition: vote.value, usual, files: tally.usual.length }));
+  });
+};