chaffjs 0.19.0 → 0.21.0

package/src/render/rules-json.ts

@@ -7,11 +7,13 @@ 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 { offOnlyAsExperimental } from "../experimental-alone.ts";
 import { optionsJson } from "./options.ts";
 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;
@@ -38,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: {
@@ -55,14 +57,16 @@ 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.",
     ],
   },
 };
 
 type Limits = Readonly<Record<string, number>>;
 
-const now = (rule: RuleDefinition, config: Config, limits: Limits, genre: string, text: (typeof TEXT)["ja"], preset: PresetLevels): Record<string, unknown> => {
+/** language: the documents', for a rule that reads only some languages. */
+const now = (rule: RuleDefinition, config: Config, limits: Limits, genre: string, preset: PresetLevels, language: string): Record<string, unknown> => {
+  const text = TEXT[uiLanguageOf(language)];
   // 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];
@@ -72,14 +76,15 @@ const now = (rule: RuleDefinition, config: Config, limits: Limits, genre: string
   if (limit !== undefined) return { level: "normal", limit, set_as: "number" };
   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` };
+    const alone = offOnlyAsExperimental(rule, config, genre, preset, language);
+    return { level: "off", why_off: text.offExperimental, ...(alone ? { turn_on_with: `npx chaffjs enable ${rule.id}` } : {}) };
   }
   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, limitsFor(config, language), genre, TEXT[uiLanguageOf(language)], presetLevels(genre));
+  now(rule, config, limitsFor(config, language), genre, presetLevels(genre), language);
 
 /** 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> =>
@@ -142,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,
@@ -186,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,
@@ -199,7 +214,7 @@ export const rulesJson = (
         ...levelsOf(rule, genre),
         levels_you_can_set: definedLevels(rule),
         your_setting: yourSetting(rule, config, limits),
-        now: now(rule, config, limits, genre, text, preset),
+        now: now(rule, config, limits, genre, preset, language),
         ...(rule.options === undefined ? {} : { options: optionsJson(rule, optionLayers) }),
         ...(rule.custom === undefined
           ? {}
@@ -208,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",
     ],
   },
 };
@@ -48,7 +48,7 @@ const runsWhenOf = (rule: RuleDefinition): RunsWhen => {
 };
 
 /** 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);
+export 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)))}`;
 

package/src/render/sarif.ts

@@ -37,6 +37,16 @@ type SarifResult = {
   }[];
 };
 
+/** A rule that did not run on one file, and why, in that file's language. */
+export type NotRunOnFile = { readonly path: string; readonly rule: string; readonly why: string };
+
+type SarifNotification = {
+  readonly level: "note";
+  readonly message: { readonly text: string };
+  readonly associatedRule: { readonly id: string };
+  readonly locations: readonly { readonly physicalLocation: { readonly artifactLocation: { readonly uri: string } } }[];
+};
+
 /** `chaff/<rule>` と名前空間を切る。同じ PR に上がる他のツールの rule id と衝突させない。 */
 const ruleIdOf = (rule: string): string => `chaff/${rule}`;
 
@@ -85,7 +95,26 @@ const usedRules = (located: readonly Located[]): SarifRule[] => {
   });
 };
 
-export const renderSarif = (located: readonly Located[], version: string): string => {
+/**
+ * The rules that did not run, one notification per rule and reason, with the files it holds for. Without them an upload
+ * with no results reads as "checked and fine" for rules that never looked.
+ */
+const notRunNotifications = (notRun: readonly NotRunOnFile[]): SarifNotification[] => {
+  const groups = new Map<string, { readonly rule: string; readonly why: string; readonly paths: readonly string[] }>();
+  notRun.forEach((entry) => {
+    const key = JSON.stringify([entry.rule, entry.why]);
+    const group = groups.get(key) ?? { rule: entry.rule, why: entry.why, paths: [] };
+    groups.set(key, { ...group, paths: [...group.paths, entry.path] });
+  });
+  return [...groups.values()].map((group) => ({
+    level: "note",
+    message: { text: `${group.rule}: ${group.why}` },
+    associatedRule: { id: ruleIdOf(group.rule) },
+    locations: group.paths.map((uri) => ({ physicalLocation: { artifactLocation: { uri } } })),
+  }));
+};
+
+export const renderSarif = (located: readonly Located[], version: string, notRun: readonly NotRunOnFile[] = []): string => {
   return `${JSON.stringify(
     {
       $schema: SCHEMA,
@@ -93,6 +122,7 @@ export const renderSarif = (located: readonly Located[], version: string): strin
       runs: [
         {
           tool: { driver: { name: "chaff", version, informationUri: INFORMATION_URI, rules: usedRules(located) } },
+          invocations: [{ executionSuccessful: true, toolConfigurationNotifications: notRunNotifications(notRun) }],
           results: located.map(resultOf),
         },
       ],

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/resolve-genre.ts

@@ -6,7 +6,7 @@ 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 type ResolvedGenre = { readonly genre: string; readonly from: GenreSource; readonly unread?: string | undefined };
 
 export const resolveGenre = (path: string, text: string, config: Config, cliGenre?: string): ResolvedGenre => {
   // コマンドで指定したものが最優先。その実行だけの指定だから、設定より強い。

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,95 @@
+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-example"; readonly written: string };
+
+export type FieldKind = FieldProblem["kind"];
+
+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) }];
+
+/** 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"]),
+];
+
+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-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-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;
@@ -61,12 +62,14 @@ export const groupTextOf = (language: string, group: RuleGroup): GroupText => GR
 /**
  * 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.
+ * other: a rule that compares documents (requires: [documents]) is tried with this third file in the same run.
  */
 export type RuleExample = {
   readonly before: string;
   readonly after: string;
   readonly config?: Readonly<Record<string, unknown>>;
   readonly pad?: boolean;
+  readonly other?: string;
 };
 
 /** One finding of the rule itself on its example, as the command line reported it. */
@@ -109,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);
@@ -126,6 +131,7 @@ const exampleOf = (value: unknown): RuleExample | undefined => {
     after: value["after"],
     ...(isRecord(config) ? { config } : {}),
     ...(value["pad"] === true ? { pad: true } : {}),
+    ...(isText(value["other"]) ? { other: value["other"] } : {}),
   };
 };
 
@@ -157,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"]),
@@ -166,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));