chaffjs 0.20.0 → 0.21.0

package/src/fix-plan/mode.ts

@@ -1,13 +1,22 @@
+import { depthIncludes, type RewriteDepth } from "../rewrite-depth.ts";
+
 /**
- * Which of the three ways to rewrite (the guide's Light, Bold and Full) chaff recommends, from what it found alone.
+ * Which way to rewrite: the guide's Light, Bold and Full, and Register. Each is a rewrite depth (rewrite-depth.ts):
+ * Light and Bold keep the structure (light), Full reorganises it (structure), Register converts the style (register).
+ * chaff recommends a way from what it found; --depth or chaff.yaml's fix_plan.depth chooses the depth instead.
  * A request that says "from scratch" also means Full; chaff cannot read the request, so the plan says so in words.
  */
-export type FixMode = "none" | "light" | "bold" | "full";
+export type FixMode = "none" | "light" | "bold" | "full" | "register";
 
-/** Why the mode was chosen, so the plan can say it. */
-export type ModeReason = "nothing-found" | "composite" | "structure" | "genre" | "signals" | "spots";
+/** Why the mode was chosen, so the plan can say it. chosen: the depth was given; depth-limit: chaff would go deeper than the depth given. */
+export type ModeReason = "nothing-found" | "all-deeper" | "composite" | "structure" | "genre" | "signals" | "spots" | "chosen" | "depth-limit";
 
-export type ModeChoice = { readonly mode: FixMode; readonly reason: ModeReason };
+export type ModeChoice = {
+  readonly mode: FixMode;
+  readonly reason: ModeReason;
+  /** How deep the rewrite goes. None when there is nothing to fix. */
+  readonly depth: RewriteDepth | undefined;
+};
 
 export type ModeInput = {
   readonly genre: string;
@@ -17,10 +26,25 @@ export type ModeInput = {
   readonly signalRules: ReadonlySet<string>;
   /** The structure score (measures past 90% of human articles) and the count at which the outline itself is the problem. */
   readonly structure?: { readonly score: number; readonly limit: number };
+  /** The depth --depth or chaff.yaml chose. Without one, chaff recommends. */
+  readonly chosen?: RewriteDepth | undefined;
+  /** How many fired rules the chosen depth sets apart; they are not in firedRules. */
+  readonly setApart?: number;
 };
 
 export const COMPOSITE_RULE = "ai-generated-composite";
 
+const DEPTH_OF: Readonly<Record<FixMode, RewriteDepth | undefined>> = {
+  none: undefined,
+  light: "light",
+  bold: "light",
+  full: "structure",
+  register: "register",
+};
+
+/** The way that goes exactly as deep as a chosen depth, beyond light, where chaff's recommendation picks Light or Bold. */
+const MODE_AT: Readonly<Record<Exclude<RewriteDepth, "light">, FixMode>> = { structure: "full", register: "register" };
+
 /** Two document-wide signals mean the prose of the sections is the problem, not a spot or two. */
 const MIN_SIGNALS_FOR_BOLD = 2;
 
@@ -30,11 +54,33 @@ const isFreeFormGenre = (genre: string): boolean => genre.startsWith("blog/") ||
 /** An outline far from human articles is rewritten from the outline, in any genre and whether or not a rule fired. */
 const hasStructureToFix = (input: ModeInput): boolean => input.structure !== undefined && input.structure.score >= input.structure.limit;
 
-export const recommendMode = (input: ModeInput): ModeChoice => {
-  if (input.firedRules.has(COMPOSITE_RULE)) return { mode: "full", reason: "composite" };
-  if (hasStructureToFix(input)) return { mode: "full", reason: "structure" };
-  if (input.firedRules.size === 0) return { mode: "none", reason: "nothing-found" };
-  if (isFreeFormGenre(input.genre)) return { mode: "full", reason: "genre" };
+const choice = (mode: FixMode, reason: ModeReason): ModeChoice => ({ mode, reason, depth: DEPTH_OF[mode] });
+
+/** Two document-wide signals mean Bold, else Light: the deepest way that keeps the structure. */
+const lightOrBold = (input: ModeInput): ModeChoice => {
   const signals = [...input.firedRules].filter((rule) => input.signalRules.has(rule)).length;
-  return signals >= MIN_SIGNALS_FOR_BOLD ? { mode: "bold", reason: "signals" } : { mode: "light", reason: "spots" };
+  return signals >= MIN_SIGNALS_FOR_BOLD ? choice("bold", "signals") : choice("light", "spots");
+};
+
+/** What chaff recommends from its findings alone. */
+const recommended = (input: ModeInput): ModeChoice => {
+  if (input.firedRules.has(COMPOSITE_RULE)) return choice("full", "composite");
+  if (hasStructureToFix(input)) return choice("full", "structure");
+  if (input.firedRules.size === 0) return choice("none", (input.setApart ?? 0) > 0 ? "all-deeper" : "nothing-found");
+  if (isFreeFormGenre(input.genre)) return choice("full", "genre");
+  return lightOrBold(input);
+};
+
+/** A chosen depth sets how deep the rewrite goes. At light, chaff still picks Light or Bold, and says when it would go deeper. */
+const atChosenDepth = (input: ModeInput, chosen: RewriteDepth, ownChoice: ModeChoice): ModeChoice => {
+  if (chosen !== "light") return ownChoice.depth === chosen ? ownChoice : choice(MODE_AT[chosen], "chosen");
+  if (ownChoice.depth !== undefined && depthIncludes(chosen, ownChoice.depth)) return ownChoice;
+  const within = lightOrBold(input);
+  return { ...within, reason: "depth-limit" };
+};
+
+export const recommendMode = (input: ModeInput): ModeChoice => {
+  const ownChoice = recommended(input);
+  if (input.chosen === undefined || ownChoice.mode === "none") return ownChoice;
+  return atChosenDepth(input, input.chosen, ownChoice);
 };

package/src/fix-plan/plan.ts

@@ -7,6 +7,7 @@ import { splitWords } from "../detectors/word-list.ts";
 import { COMPOSITE_RULE, recommendMode, type ModeChoice } from "./mode.ts";
 import type { StructureScore } from "../structure-shape/score.ts";
 import { structureTargetsOf, type StructureTarget } from "./structure-targets.ts";
+import { DEFAULT_DEPTH, depthIncludes, type RewriteDepth } from "../rewrite-depth.ts";
 
 /** One flagged spot, where it is and what chaff said about it. */
 export type PlanSpot = { readonly line: number; readonly column: number; readonly quote: string; readonly message: string };
@@ -18,6 +19,8 @@ export type PhraseHint = { readonly phrase: string; readonly rewrite: string };
 export type RulePlan = {
   readonly rule: string;
   readonly name: string;
+  /** How deep the rule's direction reaches (rewrite.depth); light when the rule does not say. */
+  readonly depth: RewriteDepth;
   /** The rule's rewrite direction, or its how_to_fix when it has no rewrite block. */
   readonly direction: string;
   readonly keep: readonly string[];
@@ -31,6 +34,12 @@ export type RulePlan = {
 /** A rule that measures the whole document, with what it said. */
 type DocumentSignal = { readonly rule: string; readonly message: string };
 
+/** A rule that fired but reaches deeper than the chosen depth: named, not planned, so its silence is not read as fixed. */
+export type DeeperRule = { readonly rule: string; readonly name: string; readonly depth: RewriteDepth; readonly spots: number };
+
+/** The depth chosen for the plan, and where: --depth on the command line, or fix_plan.depth in chaff.yaml. */
+export type ChosenDepth = { readonly depth: RewriteDepth; readonly from: "flag" | "config" };
+
 export type FixPlan = {
   readonly path: string;
   /** Where the plan suggests saving the rewrite, so the check commands can be pasted as they are. */
@@ -39,6 +48,8 @@ export type FixPlan = {
   readonly genre: string;
   readonly experimental: boolean;
   readonly mode: ModeChoice;
+  /** None when chaff recommends the depth itself. */
+  readonly chosenDepth: ChosenDepth | undefined;
   readonly signals: readonly DocumentSignal[];
   readonly outline: { readonly unit: LengthUnit; readonly shape: Shape };
   /** The structure score, the count at which the plan rewrites from the outline, and how many measures were compared. */
@@ -46,6 +57,8 @@ export type FixPlan = {
   /** The structure measures past 90% of human articles, each with the human numbers to bring it back to. */
   readonly targets: readonly StructureTarget[];
   readonly rules: readonly RulePlan[];
+  /** The rules that fired but reach deeper than the chosen depth. Empty without a chosen depth. */
+  readonly deeper: readonly DeeperRule[];
   /** The rewrite and signal rules that did not run, and why: silence from them is not "checked and fine". */
   readonly notRun: readonly Skipped[];
   readonly checks: readonly string[];
@@ -66,6 +79,7 @@ export type PlanInput = {
   readonly structure: StructureScore;
   /** The ai-tell lexicon of the document's language, whose entries may carry their own hint. */
   readonly phrases: Lexicon;
+  readonly chosenDepth?: ChosenDepth | undefined;
 };
 
 const BOLD_DENSITY_RULE = "bold-density";
@@ -114,6 +128,7 @@ const rulePlanOf = (rule: RuleDefinition, findings: readonly Finding[], input: P
   return {
     rule: rule.id,
     name: localized(rule.name, input.language),
+    depth: depthOfRule(rule),
     direction: rewrite?.direction ?? localized(rule.how_to_fix, input.language),
     keep: rewrite?.keep ?? [],
     avoid: rewrite?.avoid ?? [],
@@ -123,6 +138,18 @@ const rulePlanOf = (rule: RuleDefinition, findings: readonly Finding[], input: P
   };
 };
 
+const depthOfRule = (rule: RuleDefinition): RewriteDepth => rule.guide?.rewriteDepth ?? DEFAULT_DEPTH;
+
+/** Every rule that fired, planned; then the ones a chosen depth leaves out, set apart. */
+const byDepth = (plans: readonly RulePlan[], chosen: ChosenDepth | undefined): Pick<FixPlan, "rules" | "deeper"> => {
+  if (chosen === undefined) return { rules: plans, deeper: [] };
+  const within = (plan: RulePlan): boolean => depthIncludes(chosen.depth, plan.depth);
+  return {
+    rules: plans.filter(within),
+    deeper: plans.filter((plan) => !within(plan)).map((plan) => ({ rule: plan.rule, name: plan.name, depth: plan.depth, spots: plan.spots.length })),
+  };
+};
+
 /** The rules in the order their first finding appears; the composite has no spot of its own and is a signal only. */
 const rulePlansOf = (input: PlanInput): RulePlan[] => {
   const order = [...new Set(input.findings.map((finding) => finding.rule))].filter((id) => id !== COMPOSITE_RULE);
@@ -159,12 +186,12 @@ const notRunOf = (input: PlanInput, signalRules: ReadonlySet<string>): Skipped[]
   return input.skipped.filter((skipped) => watched.has(skipped.rule));
 };
 
-/** The commands to run on the rewrite. A full rewrite cuts repeats and rebuilds headings, which compare is told. */
+/** The commands to run on the rewrite. A rewrite past light cuts repeats and rebuilds headings, which compare is told. */
 const checksOf = (input: PlanInput, choice: ModeChoice): string[] => {
   const original = shellPath(input.path);
   const rewritten = shellPath(rewrittenPathOf(input.path));
   const lintFlags = [...(input.experimental ? ["--experimental"] : []), ...(input.genreFlag === undefined ? [] : ["--genre", input.genreFlag])];
-  const compareFlags = choice.mode === "full" ? ["--distinct", "--allow-dropped heading", "--allow-added heading"] : [];
+  const compareFlags = choice.depth !== undefined && choice.depth !== "light" ? ["--distinct", "--allow-dropped heading", "--allow-added heading"] : [];
   return [
     ["npx chaffjs", rewritten, ...lintFlags].join(" "),
     ["npx chaffjs compare", original, rewritten, ...compareFlags].join(" "),
@@ -182,8 +209,12 @@ const documentLength = (outline: Outline): number => outline.entries.reduce((sum
 export const buildFixPlan = (input: PlanInput): FixPlan => {
   const signalRules = signalRulesOf(input.rules);
   const structure = { score: input.structure.score, limit: structureLimitOf(input.rules), compared: input.structure.compared };
-  const firedRules = new Set(input.findings.map((finding) => finding.rule));
-  const mode = recommendMode({ genre: input.genre, firedRules, signalRules, structure });
+  const planned = byDepth(rulePlansOf(input), input.chosenDepth);
+  // A rule the depth sets apart is not something this rewrite fixes, so it does not decide the way either.
+  const setApart = new Set(planned.deeper.map((rule) => rule.rule));
+  const firedRules = new Set(input.findings.map((finding) => finding.rule).filter((rule) => !setApart.has(rule)));
+  const chosen = input.chosenDepth?.depth;
+  const mode = recommendMode({ genre: input.genre, firedRules, signalRules, structure, chosen, setApart: setApart.size });
   return {
     path: input.path,
     rewrittenPath: rewrittenPathOf(input.path),
@@ -191,11 +222,12 @@ export const buildFixPlan = (input: PlanInput): FixPlan => {
     genre: input.genre,
     experimental: input.experimental,
     mode,
+    chosenDepth: input.chosenDepth,
     signals: signalsOf(input, signalRules),
     outline: { unit: input.outline.unit, shape: input.outline.shape },
     structure,
     targets: structureTargetsOf(input.structure, documentLength(input.outline)),
-    rules: rulePlansOf(input),
+    ...planned,
     notRun: notRunOf(input, signalRules),
     checks: checksOf(input, mode),
   };

package/src/fix-plan/render.ts

@@ -5,6 +5,7 @@ import { uiLanguageOf } from "../ui.ts";
 import type { FixPlan, PhraseHint, PlanSpot, RulePlan } from "./plan.ts";
 import { FIX_PLAN_TEXT, type FixPlanText } from "./text.ts";
 import { STRUCTURE_TARGET_TEXT } from "./structure-target-text.ts";
+import { DEFAULT_DEPTH, depthMeaning } from "../rewrite-depth.ts";
 
 /** A phrase quoted the way the document's language quotes: 「…」 in Japanese, "…" otherwise. */
 const quoted = (text: string, language: string): string => (language === "ja" ? `「${text}」` : `"${text}"`);
@@ -34,6 +35,7 @@ const rulePlanLines = (rule: RulePlan, text: FixPlanText, language: string): str
   "",
   `### \`${rule.rule}\` ${rule.name}`,
   "",
+  ...(rule.depth === DEFAULT_DEPTH ? [] : [`**${text.ruleDepth}**: ${rule.depth}`, ""]),
   `**${text.direction}**: ${rule.direction}`,
   ...labelled(text.keep, bullets(rule.keep)),
   ...labelled(text.avoid, bullets(rule.avoid)),
@@ -48,15 +50,36 @@ const rulePlanLines = (rule: RulePlan, text: FixPlanText, language: string): str
   ),
 ];
 
+const depthLines = (plan: FixPlan, text: FixPlanText): string[] => {
+  const { depth } = plan.mode;
+  if (depth === undefined) return [];
+  const setBy = plan.chosenDepth === undefined ? "" : text.depthSetBy[plan.chosenDepth.from];
+  return [text.depthLine(depth, depthMeaning(depth, uiLanguageOf(plan.language)), setBy), ""];
+};
+
 const modeLines = (plan: FixPlan, text: FixPlanText): string[] => [
   "",
   `## ${text.modeHeading}: ${text.modeName[plan.mode.mode]}`,
   "",
   text.modeReason[plan.mode.reason],
   "",
+  ...depthLines(plan, text),
   ...bullets(text.modeWays),
 ];
 
+/** The rules a chosen depth leaves out, named with their depth, so their findings are not taken for fixed. */
+const deeperLines = (plan: FixPlan, text: FixPlanText): string[] => {
+  if (plan.deeper.length === 0 || plan.chosenDepth === undefined) return [];
+  return [
+    "",
+    `## ${text.deeperHeading}`,
+    "",
+    text.deeperNote(plan.chosenDepth.depth),
+    "",
+    ...bullets(plan.deeper.map((rule) => `\`${rule.rule}\` ${rule.name}: ${text.deeperLine(rule.depth, rule.spots)}`)),
+  ];
+};
+
 const signalLines = (plan: FixPlan, text: FixPlanText): string[] => {
   const outline = text.outlineLine(shapeMeasures(plan.outline.shape, plan.outline.unit, OUTLINE_TEXT[uiLanguageOf(plan.language)]));
   const said = plan.signals.length === 0 ? [text.noSignals, ""] : [];
@@ -126,6 +149,7 @@ export const renderFixPlanMarkdown = (plan: FixPlan): string => {
     ...structureLines(plan),
     ...(plan.rules.length === 0 ? [] : ["", `## ${text.rulesHeading}`]),
     ...plan.rules.flatMap((rule) => rulePlanLines(rule, text, plan.language)),
+    ...deeperLines(plan, text),
     ...notRunLines(plan, text),
     ...checkLines(plan, text),
   ].join("\n");

package/src/fix-plan/text.ts

@@ -13,6 +13,14 @@ export type FixPlanText = {
   readonly modeName: Readonly<Record<FixMode, string>>;
   readonly modeReason: Readonly<Record<ModeReason, string>>;
   readonly modeWays: readonly string[];
+  /** The depth the plan goes to, with what it means, and where it was chosen when it was. */
+  readonly depthLine: (depth: string, meaning: string, setBy: string) => string;
+  readonly depthSetBy: Readonly<Record<"flag" | "config", string>>;
+  /** A rule's own depth, shown when it reaches past light. */
+  readonly ruleDepth: string;
+  readonly deeperHeading: string;
+  readonly deeperNote: (chosen: string) => string;
+  readonly deeperLine: (depth: string, spots: number) => string;
   readonly signalsHeading: string;
   readonly noSignals: string;
   readonly outlineLine: (measures: string) => string;
@@ -35,7 +43,7 @@ export type FixPlanText = {
 
 export const FIX_PLAN_TEXT: Texts<FixPlanText> = {
   ja: {
-    usage: "使い方: chaff fix-plan <file> [--experimental] [--genre <ジャンル>] [--json]",
+    usage: "使い方: chaff fix-plan <file> [--depth light|structure|register] [--experimental] [--genre <ジャンル>] [--json]",
     notFound: (path) => `${path} がありません。`,
     title: (path) => `直す計画: ${path}`,
     about: (language, genre) => `言語 ${language}、ジャンル ${genre}`,
@@ -49,9 +57,18 @@ export const FIX_PLAN_TEXT: Texts<FixPlanText> = {
       "書き直しは 2 回まで。指摘を消すためだけに書き直しを繰り返さない。",
     ],
     modeHeading: "勧める直し方",
-    modeName: { none: "直すところなし", light: "軽く直す（Light）", bold: "大胆に直す（Bold）", full: "全面書き直し（Full）" },
+    modeName: {
+      none: "直すところなし",
+      light: "軽く直す（Light）",
+      bold: "大胆に直す（Bold）",
+      full: "全面書き直し（Full）",
+      register: "文体を変える（Register）",
+    },
     modeReason: {
+      chosen: "書き直しの深さが決めてあるので、その深さで直します。",
+      "depth-limit": "chaff だけなら構成から書き直すことを勧めますが、決めてある深さが light なので、構成は残します。",
       "nothing-found": "chaff は何も見つけませんでした。",
+      "all-deeper": "指摘はどれも、決めた深さより深く直すルールのものです。この深さで直すところはありません（下の「決めた深さより深いルール」）。",
       composite: "ai-generated-composite が出ています。文の言い回しを直しても、生成文の骨組みが残ります。",
       structure: "構成の項目のいくつもが、人の記事の 9 割を超えています（下の「構成の目標」）。文を直しても、見出しの立て方と節の形が残ります。",
       genre: "ブログやエッセイは、構成から書き直すほうが書き手の望みに合います。",
@@ -59,10 +76,18 @@ export const FIX_PLAN_TEXT: Texts<FixPlanText> = {
       spots: "指摘は箇所ごとです。指摘された所だけを直します。",
     },
     modeWays: [
-      "軽く直す: 指摘された箇所だけ。",
-      "大胆に直す: 見出しの構成は残し、節ごとに文を書き直す。",
-      "全面書き直し: 事実と主張を控えてから、構成から書き直す。頼まれた内容が「全面的に」「一から」なら、これを選ぶ。",
+      "軽く直す（深さ light）: 指摘された箇所だけ。",
+      "大胆に直す（深さ light）: 見出しの構成は残し、節ごとに文を書き直す。",
+      "全面書き直し（深さ structure）: 事実と主張を控えてから、構成から書き直す。頼まれた内容が「全面的に」「一から」なら、これを選ぶ。",
+      "文体を変える（深さ register）: 全面書き直しに加えて、文体も変える（です・ます → である など）。chaff からは勧めません。--depth register で選びます。",
     ],
+    depthLine: (depth, meaning, setBy) => `書き直しの深さ: ${depth}（${meaning}）${setBy}。`,
+    depthSetBy: { flag: "。--depth で決めました", config: "。chaff.yaml の fix_plan.depth で決めました" },
+    ruleDepth: "深さ",
+    deeperHeading: "決めた深さより深いルール",
+    deeperNote: (chosen) =>
+      `次のルールも指摘を出しましたが、直す方向が深さ ${chosen} より深いので、この計画では直しません。直すときは、そのルールの深さを --depth に渡して計画を出し直してください。`,
+    deeperLine: (depth, spots) => `深さ ${depth}、${String(spots)} 箇所`,
     signalsHeading: "文書全体の目印",
     noSignals: "文書全体を測るルールは、何も言っていません。",
     outlineLine: (measures) => `構成: ${measures}`,
@@ -84,7 +109,7 @@ export const FIX_PLAN_TEXT: Texts<FixPlanText> = {
       "1 つめは書き直した文書の指摘、2 つめは事実が落ちていないか・足されていないか、3 つめは構成の変化です。数は chaff の出力から取り、形容詞で言わないでください。",
   },
   en: {
-    usage: "usage: chaff fix-plan <file> [--experimental] [--genre <genre>] [--json]",
+    usage: "usage: chaff fix-plan <file> [--depth light|structure|register] [--experimental] [--genre <genre>] [--json]",
     notFound: (path) => `${path} does not exist.`,
     title: (path) => `Fix plan: ${path}`,
     about: (language, genre) => `language ${language}, genre ${genre}`,
@@ -98,9 +123,13 @@ export const FIX_PLAN_TEXT: Texts<FixPlanText> = {
       "At most two passes. Do not rewrite again just to silence a finding.",
     ],
     modeHeading: "Recommended way",
-    modeName: { none: "Nothing to fix", light: "Light", bold: "Bold", full: "Full rewrite" },
+    modeName: { none: "Nothing to fix", light: "Light", bold: "Bold", full: "Full rewrite", register: "Register change" },
     modeReason: {
+      chosen: "A rewrite depth is set, so the plan goes to that depth.",
+      "depth-limit": "On its findings alone chaff would rewrite from the structure up, but the depth set is light, so the structure stays.",
       "nothing-found": "chaff found nothing.",
+      "all-deeper":
+        'Every finding comes from a rule that rewrites deeper than the depth set. There is nothing to fix at this depth (see "Rules deeper than the depth set" below).',
       composite: "ai-generated-composite fires. Fixing the wording would leave the skeleton of generated text.",
       structure:
         'Several structure measures lie past 90% of human articles (see "Structure targets" below). Fixing the sentences would leave the headings and the shape of the sections.',
@@ -109,10 +138,18 @@ export const FIX_PLAN_TEXT: Texts<FixPlanText> = {
       spots: "The findings are single spots. Rewrite only those.",
     },
     modeWays: [
-      "Light: only the flagged spots.",
-      "Bold: keep the outline, rewrite the prose of each section.",
-      'Full: take an inventory of the facts and claims, then rewrite from the structure up. If the request says "from scratch", choose this.',
+      "Light (depth light): only the flagged spots.",
+      "Bold (depth light): keep the outline, rewrite the prose of each section.",
+      'Full (depth structure): take an inventory of the facts and claims, then rewrite from the structure up. If the request says "from scratch", choose this.',
+      "Register (depth register): a full rewrite that also converts the style (polite to plain endings, and so on). chaff never recommends it; choose it with --depth register.",
     ],
+    depthLine: (depth, meaning, setBy) => `Rewrite depth: ${depth} (${meaning})${setBy}.`,
+    depthSetBy: { flag: ", set by --depth", config: ", set by fix_plan.depth in chaff.yaml" },
+    ruleDepth: "Depth",
+    deeperHeading: "Rules deeper than the depth set",
+    deeperNote: (chosen) =>
+      `These rules fired too, but their direction goes deeper than ${chosen}, so this plan does not fix them. To fix them, give the rule's depth to --depth and print the plan again.`,
+    deeperLine: (depth, spots) => `depth ${depth}, ${String(spots)} ${spots === 1 ? "spot" : "spots"}`,
     signalsHeading: "Document-level signals",
     noSignals: "None of the rules that measure the whole document said anything.",
     outlineLine: (measures) => `Outline: ${measures}`,

package/src/genre-load.ts

@@ -2,17 +2,20 @@ import { readFileSync } from "node:fs";
 import { dirname, join } from "node:path";
 import { fileURLToPath } from "node:url";
 import { parse } from "yaml";
-import { parseGenres, presetLevelsOf, presetProfileOf, type GenreData, type PresetLevels } from "./genre-parse.ts";
+import { parseGenres, presetLevelsOf, presetProfileOf, withRuleOffs, type GenreData, type PresetLevels } from "./genre-parse.ts";
+import { loadRuleOffs } from "./rule-offs.ts";
 
-const GENRES_FILE = join(dirname(fileURLToPath(import.meta.url)), "..", "genres.yaml");
+const PACKAGE = join(dirname(fileURLToPath(import.meta.url)), "..");
+const GENRES_FILE = join(PACKAGE, "genres.yaml");
+const RULES_DIR = join(PACKAGE, "rules");
 
 const loaded: { value: GenreData | undefined } = { value: undefined };
 
-/** The bundled genres.yaml. Read once. */
+/** The bundled genres.yaml, with the offs the rule files set (off_for). Read once. */
 export const loadGenres = (): GenreData => {
   if (loaded.value !== undefined) return loaded.value;
   try {
-    loaded.value = parseGenres(parse(readFileSync(GENRES_FILE, "utf8")));
+    loaded.value = withRuleOffs(parseGenres(parse(readFileSync(GENRES_FILE, "utf8"))), loadRuleOffs(RULES_DIR));
   } catch (error) {
     throw new Error(`cannot read ${GENRES_FILE}: ${error instanceof Error ? error.message : String(error)}`, { cause: error });
   }

package/src/genre-parse.ts

@@ -1,5 +1,6 @@
 import { isLevel } from "./levels.ts";
 import type { Level, Localized } from "./plugin.ts";
+import type { RuleOff } from "./rule-offs.ts";
 
 /** A preset's rules: the level each named rule runs at, under whatever chaff.yaml's rules say. */
 export type PresetLevels = Readonly<Record<string, Level>>;
@@ -139,6 +140,24 @@ export const parseGenres = (raw: unknown): GenreData => {
   return { groups, genres };
 };
 
+const withOffsFor = <T extends { readonly id: string; readonly rules: PresetLevels }>(entry: T, offs: readonly RuleOff[]): T => {
+  const mine = offs.filter((off) => off.target === entry.id);
+  const both = mine.find((off) => entry.rules[off.rule] !== undefined);
+  if (both !== undefined) throw new Error(`${both.rule}: its off_for and genres.yaml both set its level for ${entry.id}`);
+  return mine.length === 0 ? entry : { ...entry, rules: { ...entry.rules, ...Object.fromEntries(mine.map((off) => [off.rule, "off" as const])) } };
+};
+
+/**
+ * genres.yaml's data with each rule file's off_for merged in. An off for a group joins the group's rules and an off for
+ * a genre the genre's own, so a genre's own level still wins over its group's. An off naming no group or genre stops here.
+ */
+export const withRuleOffs = (data: GenreData, offs: readonly RuleOff[]): GenreData => {
+  const known = new Set([...data.groups, ...data.genres].map((entry) => entry.id));
+  const unknown = offs.find((off) => !known.has(off.target));
+  if (unknown !== undefined) throw new Error(`${unknown.rule}: off_for names ${unknown.target}, which is no group or genre`);
+  return { groups: data.groups.map((group) => withOffsFor(group, offs)), genres: data.genres.map((genre) => withOffsFor(genre, offs)) };
+};
+
 /** The levels a genre's preset sets: its group's, then its own on top. Empty for a genre chaff does not know. */
 export const presetLevelsOf = (data: GenreData, genre: string): PresetLevels => {
   const own = data.genres.find((entry) => entry.id === genre);

package/src/init.ts

@@ -30,9 +30,9 @@ const TEXT: Texts<{
 #
 # コマンドでも変更できます。理由がコメントとして自動で残ります。
 #
-#   npx chaff relax bold-density --why "図の説明で太字を多用するため"
-#   npx chaff explain bold-density        そのルールの意図を読む
-#   npx chaff rules --json                AI に設定を書かせるときに渡す
+#   npx chaffjs relax bold-density --why "図の説明で太字を多用するため"
+#   npx chaffjs explain bold-density        そのルールの意図を読む
+#   npx chaffjs rules --json                AI に設定を書かせるときに渡す
 
 # この場所に置く文書の種類（${summary}）。ほかの種類: npx chaffjs genres
 genre: ${genre}
@@ -50,9 +50,9 @@ rules:
     exists: "chaff.yaml は既にあります。変更していません。",
     createdHeading: "作成しました:",
     genreChosen: (genre) => `ジャンルは ${genre} にしました。違う場合は chaff.yaml の genre を直してください。`,
-    genreList: "  一覧: npx chaff genres",
+    genreList: "  一覧: npx chaffjs genres",
     next: "次:",
-    nextCheck: "  npx chaff .            この場所の Markdown を全部見る",
+    nextCheck: "  npx chaffjs .            この場所の Markdown を全部見る",
   },
   en: {
     config: (genre, summary) => `# chaff.yaml — this team's writing rules
@@ -69,9 +69,9 @@ rules:
 #
 # Commands change it too, and leave the reason as a comment.
 #
-#   npx chaff relax bold-density --why "figure captions use a lot of bold"
-#   npx chaff explain bold-density        read what the rule is for
-#   npx chaff rules --json                give this to an AI that writes the settings
+#   npx chaffjs relax bold-density --why "figure captions use a lot of bold"
+#   npx chaffjs explain bold-density        read what the rule is for
+#   npx chaffjs rules --json                give this to an AI that writes the settings
 
 # The kind of document kept here (${summary}). The others: npx chaffjs genres
 genre: ${genre}
@@ -89,9 +89,9 @@ rules:
     exists: "chaff.yaml already exists. Nothing was changed.",
     createdHeading: "Created:",
     genreChosen: (genre) => `The genre is ${genre}. If that is wrong, change genre in chaff.yaml.`,
-    genreList: "  List: npx chaff genres",
+    genreList: "  List: npx chaffjs genres",
     next: "Next:",
-    nextCheck: "  npx chaff .            check every Markdown file here",
+    nextCheck: "  npx chaffjs .            check every Markdown file here",
   },
 };
 

package/src/known-genres.ts

@@ -0,0 +1,19 @@
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import { parse } from "yaml";
+import { loadGenres } from "./genre-load.ts";
+import { parseGenres, type GenreData } from "./genre-parse.ts";
+
+const idsOf = (data: GenreData): string[] => [...data.groups.map((group) => group.id), ...data.genres.map((genre) => genre.id)];
+
+/** Every genre and genre group genres.yaml names: what a rule's use_for may list. */
+export const knownGenres = (): string[] => idsOf(loadGenres());
+
+/**
+ * The genres of the genres.yaml beside a rules folder (packages/chaff/rules → packages/chaff/genres.yaml), else chaff's
+ * own. The site reads the rules from the source tree after bundling, where chaff's own file is not where the module is.
+ */
+export const genresBeside = (rulesDir: string): string[] => {
+  const file = join(rulesDir, "..", "genres.yaml");
+  return existsSync(file) ? idsOf(parseGenres(parse(readFileSync(file, "utf8")))) : knownGenres();
+};

package/src/link-shape.ts

@@ -0,0 +1,62 @@
+// What a link's text and an image's alt text look like: a URL, a host, a file name. Pure functions only.
+
+/** Link text that reads as an address: it starts with a scheme or with `www.`. A bare `README.md` is a file, not a host. */
+const URL_TEXT = /^(?:https?:\/\/|www\.)[^\s]+$/iu;
+
+/** Marks around a link's text that are not part of the address it shows (`**https://…**`, `` `https://…` ``, `<…>`). */
+const LEADING = new Set(" \t\n*_`<「『\"“'");
+const TRAILING = new Set(" \t\n*_`>」』\"”'.。,，、");
+
+/** The text as the reader sees the address, without emphasis, code marks, quotes or closing punctuation. */
+export const shownAddress = (text: string): string => {
+  const chars = [...text];
+  const start = chars.findIndex((char) => !LEADING.has(char));
+  return start === -1 ? "" : chars.slice(start, chars.findLastIndex((char) => !TRAILING.has(char)) + 1).join("");
+};
+
+/** Whether a link's text is itself an address. */
+export const isUrlText = (text: string): boolean => URL_TEXT.test(shownAddress(text));
+
+const WWW = /^www\./iu;
+const WEB_SCHEME = /^https?:\/\//iu;
+
+/** The host an address names, lower case and without `www.`; undefined for a relative path, a fragment or a mail address. */
+export const hostOf = (address: string): string | undefined => {
+  const written = shownAddress(address);
+  const absolute = WWW.test(written) ? `https://${written}` : written;
+  if (!WEB_SCHEME.test(absolute)) return undefined;
+  try {
+    return new URL(absolute).hostname.toLowerCase().replace(WWW, "");
+  } catch {
+    return undefined;
+  }
+};
+
+/**
+ * The host a link's text shows, when it differs from the host the link goes to. Both must be absolute web addresses;
+ * a shortened display of the same host (`github.com/a` for `https://github.com/a/b/tree/main`) is the same host.
+ */
+export const mismatchedHost = (text: string, destination: string): { readonly shown: string; readonly target: string } | undefined => {
+  if (!isUrlText(text)) return undefined;
+  const shown = hostOf(text);
+  const target = hostOf(destination);
+  return shown === undefined || target === undefined || shown === target ? undefined : { shown, target };
+};
+
+/** The extensions of image files. An alt text that ends in one is the file's name. */
+const IMAGE_FILE = /\.(?:png|jpe?g|gif|svg|webp|bmp|tiff?|heic|heif|avif|ico)$/iu;
+
+/** After a camera's or a screenshot tool's name: separators, then the number it counts with (`IMG_1234`, `Screenshot 2026-…`). */
+const COUNTER = /^[\s_-]*\d/u;
+
+/**
+ * Whether an alt text is a file's name rather than a description: it ends in an image extension (`IMG_1234.png`), or it
+ * starts with a name a camera or a screenshot tool gives (`prefixes`, from the language's lexicon) followed by its number.
+ */
+export const isFileNameAlt = (alt: string, prefixes: readonly string[]): boolean => {
+  const written = alt.trim();
+  if (written === "") return false;
+  if (IMAGE_FILE.test(written)) return true;
+  const lowered = written.toLowerCase();
+  return prefixes.some((prefix) => lowered.startsWith(prefix.toLowerCase()) && COUNTER.test(written.slice(prefix.length)));
+};

package/src/reasons.ts

@@ -22,6 +22,12 @@ export type Reasons = {
   readonly oneDocument: string;
 };
 
+/** A plugin's word list is named <plugin>/<list> (@scope/foo/list too); a language package's has no slash. */
+const pluginListOf = (list: string): { readonly plugin: string; readonly name: string } | undefined => {
+  const slash = list.lastIndexOf("/");
+  return slash === -1 ? undefined : { plugin: list.slice(0, slash), name: list.slice(slash + 1) };
+};
+
 const CAPABILITY_NAME: Texts<Readonly<Record<string, string>>> = {
   ja: { pos: "品詞解析", lemma: "原形" },
   en: { pos: "part-of-speech tagging", lemma: "lemmas" },
@@ -33,7 +39,7 @@ export const REASONS: Texts<Reasons> = {
     noCapability: (capability) => `この言語では${CAPABILITY_NAME.ja[capability] ?? capability}が使えないため`,
     noTags: "アダプタが品詞を返さなかったため",
     unreadTags: "言語のパッケージがこの文書を読めなかったため（品詞の取れない段落があります）",
-    semantic: "意味を読む検査のため（npx chaff test で動きます）",
+    semantic: "意味を読む検査のため（npx chaffjs test で動きます）",
     experimental: "まだ試験中のため",
     turnedOff: "設定で止めているため",
     presetOff: (genre) => `ジャンル ${genre} では見ないため`,
@@ -41,7 +47,10 @@ export const REASONS: Texts<Reasons> = {
     unreadStructure: (clauses, units) =>
       `条項の番号が本文に ${String(clauses)} 個あるのに、番号として読めたのは ${String(units)} 個のため（深い字下げや、行が本文につながった文書）`,
     noDetector: (name) => `検出器 ${name} がないため`,
-    noLexicon: (language, list) => `${language} の語彙表 ${list} が無いため`,
+    noLexicon: (language, list) => {
+      const owner = pluginListOf(list);
+      return owner === undefined ? `${language} の語彙表 ${list} が無いため` : `プラグイン ${owner.plugin} に ${language} の語彙表 ${owner.name} が無いため`;
+    },
     noHeadings: "表題より下の見出しが無いため",
     patternTimeout: (budgetMs) => `正規表現が ${String(budgetMs)} ms で終わらなかったため（chaff.yaml の pattern を単純にしてください）`,
     notMarkdown: "Markdown の文書ではないため",
@@ -52,7 +61,7 @@ export const REASONS: Texts<Reasons> = {
     noCapability: (capability) => `${CAPABILITY_NAME.en[capability] ?? capability} is not available for this language`,
     noTags: "the language package returned no parts of speech",
     unreadTags: "the language package could not read this document (some paragraphs have no parts of speech)",
-    semantic: "it reads meaning; npx chaff test runs it",
+    semantic: "it reads meaning; npx chaffjs test runs it",
     experimental: "still experimental",
     turnedOff: "turned off in the settings",
     presetOff: (genre) => `the ${genre} genre does not check it`,
@@ -60,7 +69,10 @@ export const REASONS: Texts<Reasons> = {
     unreadStructure: (clauses, units) =>
       `the text has ${String(clauses)} clause numbers but only ${String(units)} ${formFor(units, "was read as a numbered line", "were read as numbered lines")} (deep indents, or lines run into the text)`,
     noDetector: (name) => `no detector named ${name}`,
-    noLexicon: (language, list) => `the ${language} package has no word list ${list}`,
+    noLexicon: (language, list) => {
+      const owner = pluginListOf(list);
+      return owner === undefined ? `the ${language} package has no word list ${list}` : `the plugin ${owner.plugin} has no ${language} word list ${owner.name}`;
+    },
     noHeadings: "the document has no headings below its title",
     patternTimeout: (budgetMs) => `the pattern did not finish within ${String(budgetMs)} ms (simplify the pattern in chaff.yaml)`,
     notMarkdown: "the document is not Markdown",