chaffjs 0.19.0 → 0.21.0

package/src/facts/labelled-facts.ts

@@ -0,0 +1,131 @@
+import type { FactValue } from "./fact-values.ts";
+import { EDGE_MARKS, trimEndOf, withoutEdgeMarks } from "./trim-marks.ts";
+
+/**
+ * 名前の付いた値（「締切：10月5日」「参加費は3,000円です」"Fee: $300" "The deadline is May 3."）と、
+ * 属性の言い回しに続く値（"headquartered in Austin"、「東京に本社を置く」）。
+ * 名前は文の頭から区切り（：、は、is）までで、値は区切りのすぐ後ろから文の切れ目まで。値の後ろに語が続けば（「3,000円から」
+ * 「$300 per person」）、条件の付いた値なので読まない。読点のあとから始まる名前（「大人は、」「For adults, the fee」）も、
+ * 前に条件があるので読まない。言語の知識（区切り、値の終わり、落とす冠詞）は言語パッケージの語彙表から取る。
+ */
+export type AttributePhrase = { readonly pattern: string; readonly position: "before" | "after" };
+
+export type FactWords = {
+  /** 名前と値の区切り（：、は、is）。英字だけの区切りは、前が空白のときだけ。 */
+  readonly separators: readonly string[];
+  /** 値のすぐ後ろに来てよいもの（。、です、まで、.）。行の終わりと表の升の終わりはいつでもよい。 */
+  readonly valueEnds: readonly string[];
+  /** 名前の頭から落とす語（the, our）。 */
+  readonly determiners: readonly string[];
+  /** 名前にならない語（それ、it）。 */
+  readonly vague: readonly string[];
+  readonly attributes: readonly AttributePhrase[];
+};
+
+export type Fact = { readonly label: string; readonly key: string; readonly value: FactValue };
+
+const MAX_LABEL_LENGTH = 24;
+const MAX_LABEL_WORDS = 5;
+
+const MARKS_AFTER_VALUE = /^[*_]+/u;
+
+/** 文の切れ目。名前はこの後ろから始まる。表の升の区切りと、空白の前のピリオド（1. や文の終わり）も切れ目。 */
+const SENTENCE_BREAK = /[。！？!?|．]|\.(?=\s)/gu;
+const CLAUSE_COMMA = /[、，,]/u;
+const BLOCK_MARK = /^[ \t]*(?:#{1,6}[ \t]+|>[ \t]?)?/u;
+const ITEM_MARK = /^[-*+][ \t]+/u;
+const LETTER = /\p{L}/u;
+/** 名前に書かない記号。コードや属性（{style="…"}、"key"=）の中の値は、項目の値ではない。 */
+const CODE_MARK = /[{}<>=[\]"`]/u;
+const LATIN_WORD = /^[a-z ]+$/iu;
+
+const lineStartOf = (source: string, offset: number): number => source.lastIndexOf("\n", offset - 1) + 1;
+
+const lineEndOf = (source: string, offset: number): number => {
+  const end = source.indexOf("\n", offset);
+  return end === -1 ? source.length : end;
+};
+
+/** 区切りの前の名前の部分。英字の区切りは語の頭から（「this」の is は区切りではない）。 */
+const beforeSeparator = (head: string, separator: string): string | undefined => {
+  if (!head.toLowerCase().endsWith(separator.toLowerCase())) return undefined;
+  const rest = head.slice(0, head.length - separator.length);
+  if (LATIN_WORD.test(separator) && !/\s$/u.test(rest)) return undefined;
+  return rest;
+};
+
+/** 最後の文の切れ目より後ろ。 */
+const afterLastBreak = (text: string): string => {
+  const breaks = [...text.matchAll(SENTENCE_BREAK)];
+  const last = breaks.at(-1);
+  return last === undefined ? text : text.slice(last.index + last[0].length);
+};
+
+const wordsOf = (text: string): string[] => text.split(/\s+/u).filter((word) => word !== "");
+
+/** 名前を一つの書き方に。全角と半角、大文字と小文字、空白の数を揃え、頭の冠詞を落とす。 */
+const keyOf = (label: string, words: FactWords): string => {
+  const [first, ...rest] = wordsOf(label.normalize("NFKC").toLowerCase());
+  const determiners = new Set(words.determiners.map((word) => word.toLowerCase()));
+  return (first !== undefined && determiners.has(first) ? rest : [first ?? "", ...rest]).join(" ");
+};
+
+const containsSeparator = (label: string, words: FactWords): boolean =>
+  words.separators.some((separator) =>
+    LATIN_WORD.test(separator) ? wordsOf(label.toLowerCase()).includes(separator.toLowerCase()) : label.includes(separator),
+  );
+
+/** 名前として使える書き方か。短く、字を含み、区切りを含まず、指すだけの語（それ、it）でない。 */
+const isLabel = (label: string, key: string, words: FactWords): boolean =>
+  label.length > 0 &&
+  label.length <= MAX_LABEL_LENGTH &&
+  wordsOf(label).length <= MAX_LABEL_WORDS &&
+  LETTER.test(key) &&
+  !CODE_MARK.test(label) &&
+  !containsSeparator(label, words) &&
+  !words.vague.some((word) => word.toLowerCase() === key);
+
+/** 値の後ろが文の切れ目か。行の終わり、表の升の終わり、語彙表の終わりの語。 */
+const endsAfter = (source: string, value: FactValue, words: FactWords): boolean => {
+  const after = source.slice(value.end, lineEndOf(source, value.end)).replace(MARKS_AFTER_VALUE, "");
+  if (after.trim() === "" || after.trimStart().startsWith("|")) return true;
+  return words.valueEnds.some((end) => after.startsWith(end));
+};
+
+const labelledFact = (source: string, value: FactValue, words: FactWords): Fact | undefined => {
+  const head = trimEndOf(source.slice(lineStartOf(source, value.start), value.start), EDGE_MARKS);
+  for (const separator of words.separators) {
+    const before = beforeSeparator(head, separator);
+    if (before === undefined) continue;
+    const clause = afterLastBreak(before).replace(BLOCK_MARK, "").replace(ITEM_MARK, "");
+    if (CLAUSE_COMMA.test(clause)) return undefined;
+    const label = withoutEdgeMarks(clause);
+    const key = keyOf(label, words);
+    return isLabel(label, key, words) ? { label, key, value } : undefined;
+  }
+  return undefined;
+};
+
+/** 属性の言い回しのすぐ前か後ろの値。名前は言い回しそのもの。 */
+const attributeFact = (source: string, value: FactValue, words: FactWords): Fact | undefined => {
+  const head = trimEndOf(source.slice(lineStartOf(source, value.start), value.start), EDGE_MARKS).toLowerCase();
+  const tail = source
+    .slice(value.end, lineEndOf(source, value.end))
+    .replace(/^[ \t]+/u, "")
+    .toLowerCase();
+  const found = words.attributes.find((phrase) =>
+    phrase.position === "before" ? head.endsWith(phrase.pattern.toLowerCase()) : tail.startsWith(phrase.pattern.toLowerCase()),
+  );
+  if (found === undefined || (found.position === "before" && !endsAfter(source, value, words))) return undefined;
+  return { label: found.pattern, key: keyOf(found.pattern, words), value };
+};
+
+/** 文に書いた名前付きの値。値ごとに、属性の言い回しか、区切りの前の名前を探す。 */
+export const labelledFacts = (source: string, values: readonly FactValue[], words: FactWords): Fact[] =>
+  values.flatMap((value) => {
+    const attribute = attributeFact(source, value, words);
+    if (attribute !== undefined) return [attribute];
+    if (!endsAfter(source, value, words)) return [];
+    const fact = labelledFact(source, value, words);
+    return fact === undefined ? [] : [fact];
+  });

package/src/facts/measures.ts

@@ -0,0 +1,54 @@
+import type { FactValue } from "./fact-values.ts";
+
+/**
+ * 単位の付いた量（5 km、3000 m、1.5時間、2 GB）。単位は言語パッケージの語彙表から取り、量の種類（長さ、重さ…）と、基準の単位への
+ * 倍率を持つ。倍率が二つある単位（1 GB は 10^9 か 2^30 バイト）は、どちらで数えても合えば合う。
+ */
+export type MeasureUnit = { readonly pattern: string; readonly dimension: string; readonly factors: readonly number[] };
+
+export type Measured = FactValue & { readonly dimension: string; readonly factors: readonly number[]; readonly amount: number };
+
+/** 前に英字や数が続く数（v2、A4、1.2.3 の 2）は量ではない。日本語は数の前に空白を置かないので、仮名や漢字の後ろはよい。 */
+const NUMBER = /(?<![\p{Script=Latin}\p{N}.,])[0-9０-９]+(?:[,，][0-9０-９]{3})*(?:[.．][0-9０-９]+)?/gu;
+
+/**
+ * 数のすぐ後ろ（空白一つまで）の単位。長い単位から試す（「5分間」を 分 で切らない、min を m にしない）。
+ * 単位の後ろに語が続く（5 miners）ものは、名前付きの値の終わり（fact-value-end）で落ちるので、ここでは見ない。
+ */
+const unitAfter = (source: string, end: number, units: readonly MeasureUnit[]): { unit: MeasureUnit; end: number } | undefined => {
+  const gap = source.charAt(end) === " " ? 1 : 0;
+  const rest = source.slice(end + gap, end + gap + 16);
+  const unit = units.find((candidate) => rest.startsWith(candidate.pattern));
+  return unit === undefined ? undefined : { unit, end: end + gap + unit.pattern.length };
+};
+
+/** 文書の中の、単位の付いた量。 */
+export const measuredValues = (source: string, units: readonly MeasureUnit[]): Measured[] => {
+  const longestFirst = units.toSorted((left, right) => right.pattern.length - left.pattern.length);
+  return [...source.matchAll(NUMBER)].flatMap((match): Measured[] => {
+    const found = unitAfter(source, match.index + match[0].length, longestFirst);
+    if (found === undefined) return [];
+    const amount = Number(match[0].normalize("NFKC").replace(/,/gu, ""));
+    return [
+      {
+        start: match.index,
+        end: found.end,
+        kind: "quantity",
+        key: String(amount),
+        unit: found.unit.pattern,
+        dimension: found.unit.dimension,
+        factors: found.unit.factors,
+        amount,
+      },
+    ];
+  });
+};
+
+/** 二つの量が同じ量か。倍率のどの組み合わせかで、基準の単位に直した値の差が大きいほうの tolerance 以内なら同じ。 */
+export const sameMeasure = (left: Measured, right: Measured, tolerance: number): boolean =>
+  left.factors.some((a) =>
+    right.factors.some((b) => {
+      const [x, y] = [left.amount * a, right.amount * b];
+      return Math.abs(x - y) <= Math.max(Math.abs(x), Math.abs(y)) * tolerance;
+    }),
+  );

package/src/facts/table-facts.ts

@@ -0,0 +1,71 @@
+import type { Span } from "../plugin.ts";
+import { linesOf, type Line } from "../structure/lines.ts";
+import { TABLE_RULE } from "../structure/runs.ts";
+import { CELL_SEPARATOR } from "../structure/bare-numbers.ts";
+import type { FactValue } from "./fact-values.ts";
+import type { Fact } from "./labelled-facts.ts";
+import { withoutEdgeMarks } from "./trim-marks.ts";
+
+/**
+ * 表の升の値。名前は行の見出し（最初の列）で、列が三つ以上なら列の見出しも付ける（「大人 料金」）。
+ * 升に値だけを書いたときだけ読む。「3,000円（税込）」のように条件を書いた升は読まない。
+ * 行の見出しが値を含むか字を含まない表（日付の列から始まる日程表）は、行に名前が無いので読まない。
+ */
+type Cell = Span & { readonly text: string };
+
+const LETTER = /\p{L}/u;
+const TWO_COLUMNS = 2;
+
+const cellsOf = (line: Line): Cell[] => {
+  const bounds = [-1, ...[...line.text.matchAll(CELL_SEPARATOR)].map((match) => match.index), line.text.length];
+  const cells = bounds.slice(1).map((end, index) => {
+    const from = (bounds[index] ?? 0) + 1;
+    return { start: line.start + from, end: line.start + end, text: line.text.slice(from, end) };
+  });
+  const trimmed = line.text.trim();
+  return cells.slice(trimmed.startsWith("|") ? 1 : 0, trimmed.endsWith("|") ? cells.length - 1 : cells.length);
+};
+
+const plain = withoutEdgeMarks;
+
+/** 区切り行（|---|）の前の行が見出し、後ろに続く | の行が本体。 */
+const tablesOf = (lines: readonly Line[]): { header: Line; rows: Line[] }[] =>
+  lines.flatMap((line, index) => {
+    const header = lines[index - 1];
+    if (!TABLE_RULE.test(line.text) || header === undefined || !header.text.includes("|")) return [];
+    const after = lines.slice(index + 1);
+    const end = after.findIndex((row) => !row.text.includes("|"));
+    return [{ header, rows: end === -1 ? after : after.slice(0, end) }];
+  });
+
+const inside = (cell: Span, value: FactValue): boolean => value.start >= cell.start && value.end <= cell.end;
+
+/** 升の値。升の字（強調を除く）がちょうど一つの値のときだけ。 */
+const cellValue = (cell: Cell, values: readonly FactValue[], source: string): FactValue | undefined => {
+  const within = values.filter((value) => inside(cell, value));
+  const only = within.length === 1 ? within[0] : undefined;
+  return only !== undefined && source.slice(only.start, only.end) === plain(cell.text) ? only : undefined;
+};
+
+const keyOf = (label: string): string => label.normalize("NFKC").toLowerCase().replace(/\s+/gu, " ");
+
+const rowFacts = (row: Line, headings: readonly string[], values: readonly FactValue[], source: string): Fact[] => {
+  const [first, ...rest] = cellsOf(row);
+  if (first === undefined) return [];
+  const rowLabel = plain(first.text);
+  if (!LETTER.test(rowLabel) || values.some((value) => inside(first, value))) return [];
+  return rest.flatMap((cell, index) => {
+    const value = cellValue(cell, values, source);
+    const column = headings[index + 1] ?? "";
+    if (value === undefined || (headings.length > TWO_COLUMNS && column === "")) return [];
+    const label = headings.length > TWO_COLUMNS ? `${rowLabel} ${column}` : rowLabel;
+    return [{ label, key: keyOf(label), value }];
+  });
+};
+
+/** 文書の表すべての升の値。 */
+export const tableFacts = (source: string, values: readonly FactValue[]): Fact[] =>
+  tablesOf(linesOf(source)).flatMap((table) => {
+    const headings = cellsOf(table.header).map((cell) => plain(cell.text));
+    return table.rows.flatMap((row) => rowFacts(row, headings, values, source));
+  });

package/src/facts/trim-marks.ts

@@ -0,0 +1,18 @@
+/** 名前や値の端の、強調の印と空白。全角の空白も入れる。 */
+export const EDGE_MARKS: ReadonlySet<string> = new Set(["*", "_", " ", "\t", "　"]);
+
+/** 後ろの端から、chars の字を落とす。正規表現の [..]*$ は長い行で後戻りが重くなるので、端から数える。 */
+export const trimEndOf = (text: string, chars: ReadonlySet<string>): string => {
+  let end = text.length;
+  while (end > 0 && chars.has(text.charAt(end - 1))) end -= 1;
+  return text.slice(0, end);
+};
+
+const trimStartOf = (text: string, chars: ReadonlySet<string>): string => {
+  let start = 0;
+  while (start < text.length && chars.has(text.charAt(start))) start += 1;
+  return text.slice(start);
+};
+
+/** 両端から、強調の印と空白を落とす。 */
+export const withoutEdgeMarks = (text: string): string => trimStartOf(trimEndOf(text, EDGE_MARKS), EDGE_MARKS);

package/src/facts/unit-conflicts.ts

@@ -0,0 +1,45 @@
+import type { ScopedFact } from "./fact-scope.ts";
+import { sameMeasure, type Measured } from "./measures.ts";
+
+/**
+ * 同じ名前の量を、違う単位で書いて、換算すると合わない（「距離：5 km」と「距離：3000 m」）。比べるのは同じ範囲の、同じ種類の量で、
+ * 単位が違うものだけ。同じ単位どうしの食い違いは fact-conflict が見る。丸めた書き方（1 mile と 1.6 km）は、差が TOLERANCE 以内なら合う。
+ */
+export type UnitConflict = { readonly fact: ScopedFact; readonly measured: Measured; readonly other: Measured };
+
+const TOLERANCE = 0.02;
+
+const groupKey = (fact: ScopedFact): string => `${fact.scope}\u0000${fact.key}`;
+
+type Read = { readonly fact: ScopedFact; readonly measured: Measured };
+
+/**
+ * 一つの種類（長さなら長さ）の量のうち、前にある単位の違う量のどれとも換算して合わないもの。どれか一つと合えば、食い違いは同じ単位
+ * どうし（3 km と 5 km）の側にあり、fact-conflict が見る。
+ */
+const conflictsInDimension = (reads: readonly Read[]): UnitConflict[] =>
+  reads.flatMap(({ fact, measured }, index) => {
+    const others = reads.slice(0, index).filter((earlier) => earlier.measured.unit !== measured.unit);
+    const [first] = others;
+    if (first === undefined || others.some((earlier) => sameMeasure(earlier.measured, measured, TOLERANCE))) return [];
+    return [{ fact, measured, other: first.measured }];
+  });
+
+const conflictsIn = (reads: readonly Read[]): UnitConflict[] => {
+  if (reads.some(({ fact }) => fact.record)) return [];
+  const dimensions = [...new Set(reads.map(({ measured }) => measured.dimension))];
+  return dimensions.flatMap((dimension) => conflictsInDimension(reads.filter(({ measured }) => measured.dimension === dimension)));
+};
+
+/** 範囲と名前ごとに、最初の量と単位の違う量を換算して比べる。 */
+export const unitConflicts = (facts: readonly ScopedFact[], measuredOf: (fact: ScopedFact) => Measured | undefined): UnitConflict[] => {
+  const groups = new Map<string, Read[]>();
+  facts.forEach((fact) => {
+    const measured = measuredOf(fact);
+    if (measured === undefined) return;
+    const group = groups.get(groupKey(fact));
+    if (group === undefined) groups.set(groupKey(fact), [{ fact, measured }]);
+    else group.push({ fact, measured });
+  });
+  return [...groups.values()].flatMap(conflictsIn);
+};

package/src/figure-references.ts

@@ -23,7 +23,7 @@ export type LabelWords = {
 
 export type DanglingFigure = { readonly offset: number; readonly label: string };
 
-type Mention = { readonly start: number; readonly end: number; readonly written: string; readonly key: string; readonly kind: string };
+export type Mention = { readonly start: number; readonly end: number; readonly written: string; readonly key: string; readonly kind: string };
 
 /** 語の前の字が漢字・カタカナ・英数字なら、長い語の一部（地図3、一覧表2、法別表第二、SubFigure）。 */
 const INSIDE_WORD = "(?<![\\p{Script=Han}\\p{Script=Katakana}\\p{N}A-Za-z])";
@@ -171,3 +171,22 @@ export const danglingFigures = (
   const elsewhere = named.length === 0 || citations === undefined ? () => false : citedElsewhere(named, citations.sentences);
   return dangling.filter((mention) => !elsewhere(mention)).map((mention) => ({ offset: mention.start, label: mention.written }));
 };
+
+/**
+ * The document's captions (a number at the start of a line) and its references in the text (every other mention that
+ * points at this document, outside a link), each in document order. Only the kinds the document labels somewhere.
+ */
+export const figureMentions = (
+  source: string,
+  prose: string,
+  words: LabelWords,
+  links: readonly Span[] = [],
+): { readonly captions: readonly Mention[]; readonly references: readonly Mention[] } => {
+  if (words.labels.length === 0) return { captions: [], references: [] };
+  const captions = labelledIn(source, words.labels);
+  const kinds = new Set(captions.map((mention) => mention.kind));
+  const references = mentionsIn(prose, words.labels)
+    .filter((mention) => kinds.has(mention.kind) && !isLabelled(source, mention))
+    .filter((mention) => pointsHere(prose, mention, words) && !links.some((link) => link.start <= mention.start && mention.end <= link.end));
+  return { captions, references };
+};

package/src/files.ts

@@ -1,12 +1,13 @@
 import { globSync, statSync } from "node:fs";
 import { readFile } from "node:fs/promises";
-import { join, relative, sep } from "node:path";
+import { join, matchesGlob, relative, sep } from "node:path";
 import { plainSource } from "./plain-source.ts";
 
 /** 検査する文書を読む。言語・ジャンル・stet も文書モデルと同じ本文（BOM と CRLF / CR をそろえたもの）で読むため、ここでそろえる。 */
 export const readDocumentFile = async (path: string): Promise<string> => plainSource(await readFile(path, "utf8"));
 
-const MARKDOWN = [".md", ".markdown", ".mdx"];
+/** What a directory walk finds without include: Markdown. */
+export const MARKDOWN = [".md", ".markdown", ".mdx"];
 
 /** 走査から外す。ここを通すと node_modules の README を延々と検査することになる。 */
 const SKIP: ReadonlySet<string> = new Set(["node_modules", "dist", "build", "coverage", ".git", ".chaff-cache"]);
@@ -15,12 +16,17 @@ const isMarkdown = (path: string): boolean => MARKDOWN.some((ext) => path.toLowe
 
 const isSkipped = (path: string): boolean => path.split(sep).some((part) => SKIP.has(part));
 
-const expand = (target: string): string[] => {
-  const stat = statSync(target, { throwIfNoEntry: false });
-  if (stat === undefined) return globSync(target).filter(isMarkdown);
-  if (stat.isFile()) return [target];
-  return globSync(join(target, "**", "*.{md,markdown,mdx}"));
-};
+/** include: file-name globs (*.yaml) a walk takes besides Markdown. A glob with a slash is matched below each folder walked. */
+const isIncluded = (path: string, include: readonly string[]): boolean => include.some((pattern) => matchesGlob(path, join("**", pattern)));
+
+const expand =
+  (include: readonly string[]) =>
+  (target: string): string[] => {
+    const stat = statSync(target, { throwIfNoEntry: false });
+    if (stat === undefined) return globSync(target).filter((path) => isMarkdown(path) || isIncluded(path, include));
+    if (stat.isFile()) return [target];
+    return [join(target, "**", "*.{md,markdown,mdx}"), ...include.map((pattern) => join(target, "**", pattern))].flatMap((pattern) => globSync(pattern));
+  };
 
 /**
  * 与えられたファイル・ディレクトリ・glob を、検査する Markdown の一覧にする。
@@ -33,7 +39,7 @@ const expand = (target: string): string[] => {
  */
 const byPath = (left: string, right: string): number => left.localeCompare(right, "en");
 
-export const collectTargets = (targets: readonly string[]): string[] => {
-  const found = targets.flatMap(expand).filter((path) => !isSkipped(path));
+export const collectTargets = (targets: readonly string[], include: readonly string[] = []): string[] => {
+  const found = targets.flatMap(expand(include)).filter((path) => !isSkipped(path));
   return [...new Set(found)].toSorted((left, right) => byPath(relative(".", left), relative(".", right)));
 };

package/src/fix-plan/chosen-depth.ts

@@ -0,0 +1,28 @@
+import { readDepth, unknownDepthSentence } from "../rewrite-depth.ts";
+import type { UiLanguage } from "../ui.ts";
+import type { ChosenDepth } from "./plan.ts";
+
+// The depth a fix plan goes to: --depth, else chaff.yaml's fix_plan.depth, else none (chaff recommends one). Pure.
+
+export type DepthChoice = { readonly chosen: ChosenDepth | undefined } | { readonly problem: string };
+
+const isRecord = (value: unknown): value is Record<string, unknown> => typeof value === "object" && value !== null && !Array.isArray(value);
+
+const printed = (value: unknown): string => JSON.stringify(value) ?? String(value);
+
+/** fix_plan as chaff.yaml writes it: nothing, or a map whose depth is a depth. */
+const configured = (fixPlan: unknown, ui: UiLanguage): DepthChoice => {
+  if (fixPlan === undefined || fixPlan === null) return { chosen: undefined };
+  if (!isRecord(fixPlan)) return { problem: unknownDepthSentence("chaff.yaml fix_plan", printed(fixPlan), ui) };
+  const read = readDepth(fixPlan["depth"]);
+  if ("unknown" in read) return { problem: unknownDepthSentence("chaff.yaml fix_plan.depth", read.unknown, ui) };
+  return { chosen: read.depth === undefined ? undefined : { depth: read.depth, from: "config" } };
+};
+
+/** flag: --depth's value, or undefined when it is not given. An empty value is a value, and not a depth. */
+export const chosenDepthOf = (flag: string | undefined, fixPlan: unknown, ui: UiLanguage): DepthChoice => {
+  if (flag === undefined) return configured(fixPlan, ui);
+  const read = readDepth(flag);
+  if ("depth" in read && read.depth !== undefined) return { chosen: { depth: read.depth, from: "flag" } };
+  return { problem: unknownDepthSentence("--depth", flag, ui) };
+};

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" | "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;
@@ -15,20 +24,63 @@ export type ModeInput = {
   readonly firedRules: ReadonlySet<string>;
   /** The rules that measure the whole document: ai-generated-composite's inputs and bold-density. */
   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;
 
 /** A blog post or an essay is rewritten from its structure up: what the writer wants changed there is the structure. */
 const isFreeFormGenre = (genre: string): boolean => genre.startsWith("blog/") || genre === "literature/essay";
 
-export const recommendMode = (input: ModeInput): ModeChoice => {
-  if (input.firedRules.size === 0) return { mode: "none", reason: "nothing-found" };
-  if (input.firedRules.has(COMPOSITE_RULE)) return { mode: "full", reason: "composite" };
-  if (isFreeFormGenre(input.genre)) return { mode: "full", reason: "genre" };
+/** 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;
+
+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);
 };