chaffjs 0.20.0 → 0.22.0

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/list-marks.ts

@@ -0,0 +1,106 @@
+// The bullets a document writes its lists with (`-`, `*`, `+`, and `・` typed at a line's start), where each list sits, and
+// the `・` lines Markdown folds into the item above. Pure; reads the source's Markdown tree.
+import { spanOf, type MarkdownNode } from "./markdown-node.ts";
+import type { Span } from "./plugin.ts";
+
+/** One bulleted list as the reader meets it: where its first item starts, how deep it sits among lists, and its bullet. */
+export type ListMark = {
+  readonly start: number;
+  readonly depth: number;
+  readonly mark: string;
+  /** The list written right before it in the same parent, when there is one: Markdown splits a list where the bullet changes. */
+  readonly previous: string | undefined;
+};
+
+/** Bullets Markdown reads as a list. */
+const MARKDOWN_BULLETS = new Set(["-", "*", "+"]);
+
+/** A bullet a Japanese writer types at a line's start. Markdown does not read it as a list, so the lines run together. */
+const TYPED_BULLET = "・";
+
+/** Blocks whose lists are someone else's or are not prose: quotations, code and HTML. */
+const SKIPPED = new Set(["blockquote", "code", "html"]);
+
+const bulletOf = (source: string, list: MarkdownNode): { readonly start: number; readonly mark: string } | undefined => {
+  const first = list.children?.[0];
+  const span = first === undefined ? undefined : spanOf(first);
+  const mark = span === undefined ? undefined : source.charAt(span.start);
+  return span === undefined || mark === undefined || !MARKDOWN_BULLETS.has(mark) ? undefined : { start: span.start, mark };
+};
+
+/** Where each line of a span starts, with the line's text. */
+const linesIn = (source: string, span: Span): { readonly start: number; readonly text: string }[] => {
+  const lines = source.slice(span.start, span.end).split("\n");
+  const read: { start: number; text: string }[] = [];
+  lines.forEach((text) => {
+    const previous = read.at(-1);
+    read.push({ start: previous === undefined ? span.start : previous.start + previous.text.length + 1, text });
+  });
+  return read;
+};
+
+/** The start of each line after the first that begins with a typed bullet. */
+const typedLineStarts = (source: string, paragraph: Span): number[] =>
+  linesIn(source, paragraph).flatMap((line, at) => {
+    const indent = line.text.length - line.text.trimStart().length;
+    return at > 0 && line.text.trimStart().startsWith(TYPED_BULLET) ? [line.start + indent] : [];
+  });
+
+/** Lines of a paragraph that start with a typed bullet; two or more in a row are a list the writer typed. */
+const typedListStart = (source: string, paragraph: Span): number | undefined => {
+  const lines = linesIn(source, paragraph).filter((line) => line.text.trim() !== "");
+  const typed = lines.filter((line) => line.text.trimStart().startsWith(TYPED_BULLET));
+  const first = typed[0];
+  return typed.length >= 2 && first !== undefined ? first.start + first.text.length - first.text.trimStart().length : undefined;
+};
+
+type Frame = { readonly node: MarkdownNode; readonly depth: number; readonly inItem: boolean };
+
+export type ListReading = {
+  readonly lists: readonly ListMark[];
+  /** `・` lines inside a Markdown list item's paragraph: Markdown joins them to the item above. */
+  readonly foldedTyped: readonly number[];
+};
+
+const listsOf = (source: string, node: MarkdownNode, depth: number): ListMark[] => {
+  const children = node.children ?? [];
+  return children.flatMap((child, at) => {
+    if (child.type !== "list") return [];
+    const bullet = bulletOf(source, child);
+    const before = children[at - 1];
+    const previous = before?.type === "list" ? bulletOf(source, before)?.mark : undefined;
+    return bullet === undefined ? [] : [{ ...bullet, depth, previous }];
+  });
+};
+
+const typedOf = (source: string, node: MarkdownNode, depth: number, inItem: boolean): { lists: ListMark[]; folded: number[] } => {
+  const span = spanOf(node);
+  if (node.type !== "paragraph" || span === undefined) return { lists: [], folded: [] };
+  if (inItem) return { lists: [], folded: typedLineStarts(source, span) };
+  const start = typedListStart(source, span);
+  return { lists: start === undefined ? [] : [{ start, depth, mark: TYPED_BULLET, previous: undefined }], folded: [] };
+};
+
+/**
+ * Every bulleted list outside quotations and code, with its depth among lists (a list in a list item is one deeper), in source
+ * order. A paragraph with two or more lines that start with `・` counts as a list at the paragraph's depth; the same lines in a
+ * list item's paragraph are folded into that item.
+ */
+export const readLists = (source: string, root: MarkdownNode): ListReading => {
+  const lists: ListMark[] = [];
+  const folded: number[] = [];
+  const pending: Frame[] = [{ node: root, depth: 0, inItem: false }];
+  for (let frame = pending.pop(); frame !== undefined; frame = pending.pop()) {
+    const { node, depth, inItem } = frame;
+    if (SKIPPED.has(node.type)) continue;
+    lists.push(...listsOf(source, node, depth));
+    const typed = typedOf(source, node, depth, inItem);
+    lists.push(...typed.lists);
+    folded.push(...typed.folded);
+    const childDepth = node.type === "list" ? depth + 1 : depth;
+    const childInItem = node.type === "listItem" || (inItem && node.type !== "list");
+    (node.children ?? []).forEach((child) => pending.push({ node: child, depth: childDepth, inItem: childInItem }));
+  }
+  const byStart = (left: number, right: number): number => left - right;
+  return { lists: lists.toSorted((left, right) => byStart(left.start, right.start)), foldedTyped: folded.toSorted(byStart) };
+};

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",

package/src/render/explain.ts

@@ -5,6 +5,7 @@ import { uiLanguageOf, type Texts } from "../ui.ts";
 import type { Level, RuleDefinition } from "../plugin.ts";
 import { optionLines } from "./options.ts";
 import type { OptionLayer } from "../rule-options.ts";
+import { depthMeaning } from "../rewrite-depth.ts";
 
 const TEXT: Texts<{
   readonly off: string;
@@ -13,6 +14,7 @@ const TEXT: Texts<{
   readonly experimental: string;
   readonly alone: (id: string) => string;
   readonly howToFix: string;
+  readonly depth: (depth: string, meaning: string) => string;
   readonly example: string;
   readonly definedIn: (plugin: string | undefined) => string;
   readonly values: string;
@@ -30,6 +32,8 @@ const TEXT: Texts<{
     experimental: "このルールはまだ試験中で、既定では動きません（--experimental で動きます）。",
     alone: (id) => `このルールだけを動かす:  npx chaffjs enable ${id}（chaff.yaml の rules に ${id}: normal と書くのと同じです）`,
     howToFix: "直しかた",
+    depth: (depth, meaning) =>
+      `書き直しの深さ: ${depth}（${meaning}）。chaff fix-plan --depth でこれより浅い深さを選ぶと、計画はこのルールを直さず、名前だけを挙げます。`,
     example: "例",
     definedIn: (plugin) =>
       plugin === undefined ? "このルールはチームが chaff.yaml の custom_rules で決めたものです。" : `このルールはプラグイン ${plugin} のものです。`,
@@ -39,7 +43,7 @@ const TEXT: Texts<{
     now: (level) => `いまは ${level} です。`,
     nowNumber: (limit) => `いまは段階ではなく数です: ${limit}。`,
     from: (source) => `（${source} で決めています）`,
-    change: (id) => `変える:  npx chaff relax ${id} --why "理由"`,
+    change: (id) => `変える:  npx chaffjs relax ${id} --why "理由"`,
   },
   en: {
     off: "not checked",
@@ -48,6 +52,7 @@ const TEXT: Texts<{
     experimental: "This rule is still experimental and does not run by default (--experimental runs it).",
     alone: (id) => `Turn on this rule alone:  npx chaffjs enable ${id}  (the same as rules: { ${id}: normal } in chaff.yaml)`,
     howToFix: "How to fix",
+    depth: (depth, meaning) => `Rewrite depth: ${depth} (${meaning}). With a shallower chaff fix-plan --depth, the plan names this rule without fixing it.`,
     example: "Example",
     definedIn: (plugin) =>
       plugin === undefined ? "The team defined this rule under custom_rules in chaff.yaml." : `This rule comes from the plugin ${plugin}.`,
@@ -57,7 +62,7 @@ const TEXT: Texts<{
     now: (level) => `Now: ${level}.`,
     nowNumber: (limit) => `Now: ${limit}, set as a number rather than a level.`,
     from: (source) => ` (set by ${source})`,
-    change: (id) => `Change it:  npx chaff relax ${id} --why "reason"`,
+    change: (id) => `Change it:  npx chaffjs relax ${id} --why "reason"`,
   },
 };
 
@@ -98,6 +103,12 @@ const exampleLines = (rule: RuleDefinition, language: string, text: (typeof TEXT
   return ["", `  ${text.example}:  ${example.before}`, `      →  ${example.after}`, "", `  ${text.definedIn(rule.plugin)}`];
 };
 
+/** How deep the rule's rewrite direction reaches, for a rule that has one: what chaff fix-plan --depth compares. */
+const depthLines = (rule: RuleDefinition, language: string, text: (typeof TEXT)["ja"]): string[] => {
+  const depth = rule.guide?.rewriteDepth;
+  return depth === undefined ? [] : ["", `  ${text.depth(depth, depthMeaning(depth, uiLanguageOf(language)))}`];
+};
+
 /** Where the rule's settings come from: the option layers, strongest first, and the source of its level when a style set it. */
 /** limit: a number chaff.yaml or its style set for the rule (rules: { id: 80 }, a style's limits), which a level does not show. */
 export type ExplainSettings = {
@@ -124,6 +135,7 @@ export const renderExplain = (rule: RuleDefinition, current: Level, language: st
     `  ${readableText(rule, rule.why, language)}`,
     "",
     `  ${text.howToFix}: ${readableText(rule, rule.how_to_fix, language)}`,
+    ...depthLines(rule, language, text),
     ...exampleLines(rule, language, text),
     "",
     `  ${rule.level_sets === "severity" ? text.severities : text.values}`,

package/src/render/friendly.ts

@@ -90,7 +90,7 @@ const block = (finding: Finding, rule: RuleDefinition, language: string, quoted:
   "",
   ...indent(`→ ${filledText(rule.how_to_fix, finding, language)}`, "     "),
   "",
-  `     ${TEXT[uiLanguageOf(language)].relax}:  npx chaff relax ${finding.rule}`,
+  `     ${TEXT[uiLanguageOf(language)].relax}:  npx chaffjs relax ${finding.rule}`,
   "",
 ];