chaffjs 0.17.0 → 0.19.0

package/src/figure-references.ts

@@ -0,0 +1,173 @@
+import { escapeRegExp } from "./orthography.ts";
+import { lowerBound } from "./detectors/token-column.ts";
+import type { DocumentNamer, Span } from "./plugin.ts";
+
+/**
+ * 本文で番号を指した図・表・付録（図3、Table 2、Appendix B）と、それを行の頭に書いた所（キャプション、見出し）。
+ * 行の頭に一度も書いていない番号を指していれば、参照先が無い。その種類（図、表）を行の頭に一つも書いていない文書は見ない。
+ * 図が別の紙にある文書かもしれない。言語の知識（図や表の語、略した書き方、別の文書を指す語）は語彙表から受け取る。
+ */
+type LabelWord = {
+  readonly word: string;
+  /** 同じものを指す書き方をまとめる名前。「Fig.」は Figure。 */
+  readonly kind: string;
+};
+
+export type LabelWords = {
+  readonly labels: readonly LabelWord[];
+  /** 番号のすぐ後ろにあると、別の文書の図になる語（of、in）。 */
+  readonly elsewhere: readonly string[];
+  /** 番号のすぐ後ろにあると、図の数になる語（図3枚）。 */
+  readonly counters: readonly string[];
+};
+
+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 };
+
+/** 語の前の字が漢字・カタカナ・英数字なら、長い語の一部（地図3、一覧表2、法別表第二、SubFigure）。 */
+const INSIDE_WORD = "(?<![\\p{Script=Han}\\p{Script=Katakana}\\p{N}A-Za-z])";
+/** 番号。数字（3、3.2、第3）、「第」の後の漢数字（別表第一）、大文字一つかローマ数字（Appendix B、Annex II）。 */
+export const FIGURE_NUMBER = "[ \\t\\u00a0]?(?:第?(\\p{Nd}+(?:[.\\-－]\\p{Nd}+)*)|第([一二三四五六七八九十百]+)|([IVX]{2,5}|[A-ZＡ-Ｚ])(?![A-Za-z]))";
+
+const forms = (word: string): string[] => [...new Set([word, word.toUpperCase()])];
+
+const labelAlternation = (labels: readonly LabelWord[]): string =>
+  labels
+    .flatMap((label) => forms(label.word))
+    .toSorted((a, b) => b.length - a.length)
+    .map(escapeRegExp)
+    .join("|");
+
+const mentionPattern = (labels: readonly LabelWord[]): RegExp => new RegExp(`${INSIDE_WORD}(${labelAlternation(labels)})${FIGURE_NUMBER}`, "gu");
+
+/** 番号の付いた図か、番号の無い図（「…の別表に」）。番号が無ければ後ろが長い語の続きでない（表示、別表第一の「第」は番号）。 */
+const labelPattern = (labels: readonly LabelWord[]): RegExp =>
+  new RegExp(`${INSIDE_WORD}(${labelAlternation(labels)})(?:${FIGURE_NUMBER}|(?![\\p{Script=Han}\\p{Script=Katakana}A-Za-z]))`, "gu");
+
+const kindOf = (written: string, labels: readonly LabelWord[]): string => labels.find((label) => forms(label.word).includes(written))?.kind ?? written;
+
+/** 同じ図は同じ鍵。全角の数字と字は半角に揃える。 */
+const mentionsIn = (text: string, labels: readonly LabelWord[]): Mention[] =>
+  [...text.matchAll(mentionPattern(labels))].map((match) => {
+    const kind = kindOf(match[1] ?? "", labels);
+    const number = (match[2] ?? match[3] ?? match[4] ?? "").normalize("NFKC");
+    return { start: match.index, end: match.index + match[0].length, written: match[0].trim(), key: `${kind}\u0000${number}`, kind };
+  });
+
+type Scan = { readonly depth: number; readonly kept: string; readonly previous: string };
+
+/** 開きの括弧。「(」はリンクの行き先（[...](...)）のときだけ、つまり「]」のすぐ後ろだけ。 */
+const opens = (char: string, previous: string): boolean => char === "[" || char === "<" || (char === "(" && previous === "]");
+const CLOSERS = "])>";
+
+const step = (state: Scan, char: string): Scan => {
+  if (opens(char, state.previous)) return { depth: state.depth + 1, kept: state.kept, previous: char };
+  if (state.depth > 0 && CLOSERS.includes(char)) return { depth: state.depth - 1, kept: state.kept, previous: char };
+  return { depth: state.depth, kept: state.depth === 0 ? state.kept + char : state.kept, previous: char };
+};
+
+/** 括弧の外の字。リンクと画像の書き方（[...](...)）と HTML の札（<b>）の中身は、行の頭の飾りとして読み飛ばす。 */
+const outsideMarkup = (text: string): string => [...text].reduce(step, { depth: 0, kept: "", previous: "" }).kept;
+const LETTER = /\p{L}/u;
+
+const HEADING = /^[ \t]{0,3}#/u;
+
+/**
+ * 番号の後ろが題の区切りか。行の終わり、区切りの記号（: . — | 括弧）、または空白のあとの題の書き出し。
+ * 空白のあとがひらがなか英語の小文字なら、本文の文（図3の例では、Figure 3 shows）で、キャプションではない。
+ */
+const CAPTION_AFTER = /^(?:[ \t]*$|[:：.．—–\-|()（）【】\]*_]|[ \t\u3000]+[^\p{Script=Hiragana}\p{Ll}])/u;
+
+/**
+ * 行の頭に書いた番号。前にあるのが飾り（#、**、![、|、【、箇条書きの印）だけで、見出しの中か、後ろが題の区切りならキャプション。
+ * 行の頭から始まる本文の文（図３の例では、…）は、図の置き場所ではない。
+ */
+const isLabelled = (source: string, mention: Mention): boolean => {
+  const lineStart = source.lastIndexOf("\n", mention.start - 1) + 1;
+  const lineEnd = source.indexOf("\n", mention.end);
+  const before = source.slice(lineStart, mention.start);
+  if (LETTER.test(outsideMarkup(before))) return false;
+  return HEADING.test(before) || CAPTION_AFTER.test(source.slice(mention.end, lineEnd === -1 ? source.length : lineEnd));
+};
+
+const LATIN_WORD = /^[A-Za-z]/u;
+
+/** 番号のすぐ後ろの語。別の文書の図（Figure 5 of the report）か、図の数（図3枚）なら参照として見ない。 */
+const pointsHere = (text: string, mention: Mention, words: LabelWords): boolean => {
+  const after = text.slice(mention.end);
+  const trimmed = after.trimStart();
+  const elsewhere = words.elsewhere.some((word) => after !== trimmed && trimmed.startsWith(word) && !LATIN_WORD.test(trimmed.slice(word.length)));
+  return !elsewhere && !words.counters.some((word) => after.startsWith(word));
+};
+
+/** 行の頭に書いた番号（キャプションや見出し）。図の置き場所。 */
+const labelledIn = (source: string, labels: readonly LabelWord[]): Mention[] => mentionsIn(source, labels).filter((mention) => isLabelled(source, mention));
+
+/** 文書が行の頭に番号を書いている種類（図、Table）。番号で名指しできる種類。 */
+export const labelledKindsIn = (source: string, words: LabelWords): ReadonlySet<string> =>
+  new Set(labelledIn(source, words.labels).map((mention) => mention.kind));
+
+/** 文書の名前を読む言語の知識と、その名前が届く範囲（文）。 */
+export type Citations = { readonly namedDocument: DocumentNamer; readonly sentences: readonly Span[] };
+
+type NamedLabel = { readonly start: number; readonly kind: string; readonly self: boolean };
+
+/** 文書の名前のすぐ後ろに書いた図の語（「…(平成二十年厚生労働省告示第五十九号)別表第一」「…号)の別表」「この規則の別表第三」）。 */
+const namedLabelsIn = (prose: string, labels: readonly LabelWord[], namedDocument: DocumentNamer): NamedLabel[] =>
+  [...prose.matchAll(labelPattern(labels))].flatMap((match) => {
+    const named = namedDocument(prose, match.index);
+    return named === undefined ? [] : [{ start: match.index, kind: kindOf(match[1] ?? "", labels), self: named.self }];
+  });
+
+/** offset を含む文の頭。文の外（見出し）なら offset。文は文書の順に並んでいる。 */
+const sentenceStartAt = (sentences: readonly Span[], starts: readonly number[], offset: number): number => {
+  const sentence = sentences[lowerBound(starts, offset + 1) - 1];
+  return sentence !== undefined && offset < sentence.end ? sentence.start : offset;
+};
+
+/**
+ * 他の文書の図か。同じ文の中で、その番号の位置までに名前を添えて書いた同じ種類の図のうち、いちばん近いものが他の文書のもの。
+ * 「(…告示第五十九号)別表第一…及び別表第二」「…別表第一から別表第三まで」の後ろの番号も、その告示の別表。
+ * 「…手数料規則の別表第二により、この規則の別表第三による」の別表第三は、この文書のものと名指している。
+ * 文と名前の位置は二分探索で引く。参照先の無い番号が何万あっても、文書の長さの二乗にしない。
+ */
+const citedElsewhere = (named: readonly NamedLabel[], sentences: readonly Span[]): ((mention: Mention) => boolean) => {
+  const starts = sentences.map((sentence) => sentence.start);
+  const byKind = new Map(
+    [...new Set(named.map((label) => label.kind))].map((kind) => {
+      const labels = named.filter((label) => label.kind === kind);
+      return [kind, { labels, starts: labels.map((label) => label.start) }];
+    }),
+  );
+  return (mention) => {
+    const ofKind = byKind.get(mention.kind);
+    const nearest = ofKind?.labels[lowerBound(ofKind.starts, mention.start + 1) - 1];
+    return nearest !== undefined && !nearest.self && nearest.start >= sentenceStartAt(sentences, starts, mention.start);
+  };
+};
+
+/**
+ * 参照先の無い番号。source は行の頭を読み、prose（コードを覆った本文）は参照を読む。位置は同じ。
+ * 番号は、キャプションが 1 と書けば 1a や 1(b) の参照も 1 に当たる（番号の後ろの字は読まない）。
+ * リンクの字（[Figure 2](figures.md)）は、そのリンクが行き先を持つので参照として見ない。
+ */
+export const danglingFigures = (
+  source: string,
+  prose: string,
+  words: LabelWords,
+  links: readonly Span[] = [],
+  citations: Citations | undefined = undefined,
+): DanglingFigure[] => {
+  if (words.labels.length === 0) return [];
+  const labelled = labelledIn(source, words.labels);
+  const labelledKeys = new Set(labelled.map((mention) => mention.key));
+  const labelledKinds = new Set(labelled.map((mention) => mention.kind));
+  const dangling = mentionsIn(prose, words.labels)
+    .filter((mention) => labelledKinds.has(mention.kind) && !labelledKeys.has(mention.key))
+    .filter((mention) => pointsHere(prose, mention, words) && !links.some((link) => link.start <= mention.start && mention.end <= link.end));
+  // 他の文書の名前は、参照先の無い番号があるときだけ読む。図の語のたびに名前を後ろ向きに読む代金を、ふつうの文書に払わせない。
+  const named = dangling.length === 0 || citations === undefined ? [] : namedLabelsIn(prose, words.labels, citations.namedDocument);
+  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 }));
+};

package/src/files.ts

@@ -1,5 +1,10 @@
 import { globSync, statSync } from "node:fs";
+import { readFile } from "node:fs/promises";
 import { join, 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"];
 

package/src/finding-order.ts

@@ -0,0 +1,3 @@
+/** 指摘を文書の中の位置の順に並べる。同じ行では桁の順。rule ごとの並びを残さない。 */
+export const byPosition = (left: { readonly line: number; readonly column: number }, right: { readonly line: number; readonly column: number }): number =>
+  left.line - right.line || left.column - right.column;

package/src/fix-plan/mode.ts

@@ -0,0 +1,34 @@
+/**
+ * Which of the three ways to rewrite (the guide's Light, Bold and Full) chaff recommends, from what it found alone.
+ * 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";
+
+/** Why the mode was chosen, so the plan can say it. */
+export type ModeReason = "nothing-found" | "composite" | "genre" | "signals" | "spots";
+
+export type ModeChoice = { readonly mode: FixMode; readonly reason: ModeReason };
+
+export type ModeInput = {
+  readonly genre: string;
+  /** The rules with at least one finding. */
+  readonly firedRules: ReadonlySet<string>;
+  /** The rules that measure the whole document: ai-generated-composite's inputs and bold-density. */
+  readonly signalRules: ReadonlySet<string>;
+};
+
+export const COMPOSITE_RULE = "ai-generated-composite";
+
+/** 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" };
+  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" };
+};

package/src/fix-plan/plan.ts

@@ -0,0 +1,181 @@
+import type { Finding, LengthUnit, Lexicon, RuleDefinition } from "../plugin.ts";
+import type { RewritePair } from "../rule-guide.ts";
+import type { Skipped } from "../run.ts";
+import type { Outline, Shape } from "../outline/shape.ts";
+import { localized, messageOf } from "../render/text.ts";
+import { splitWords } from "../detectors/word-list.ts";
+import { COMPOSITE_RULE, recommendMode, type ModeChoice } from "./mode.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 };
+
+/** A phrase's own hint from the lexicon ("時間を溶かす" → "時間がかかった（何に、どれだけ）"). */
+export type PhraseHint = { readonly phrase: string; readonly rewrite: string };
+
+/** Everything a rewriter needs for one rule: its direction and the spots it flagged. */
+export type RulePlan = {
+  readonly rule: string;
+  readonly name: string;
+  /** The rule's rewrite direction, or its how_to_fix when it has no rewrite block. */
+  readonly direction: string;
+  readonly keep: readonly string[];
+  readonly avoid: readonly string[];
+  /** The first of the rule's pairs, to copy the shape from. */
+  readonly pair: RewritePair | undefined;
+  readonly hints: readonly PhraseHint[];
+  readonly spots: readonly PlanSpot[];
+};
+
+/** A rule that measures the whole document, with what it said. */
+type DocumentSignal = { readonly rule: string; readonly message: string };
+
+export type FixPlan = {
+  readonly path: string;
+  /** Where the plan suggests saving the rewrite, so the check commands can be pasted as they are. */
+  readonly rewrittenPath: string;
+  readonly language: string;
+  readonly genre: string;
+  readonly experimental: boolean;
+  readonly mode: ModeChoice;
+  readonly signals: readonly DocumentSignal[];
+  readonly outline: { readonly unit: LengthUnit; readonly shape: Shape };
+  readonly rules: readonly RulePlan[];
+  /** 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[];
+};
+
+export type PlanInput = {
+  readonly path: string;
+  readonly language: string;
+  readonly genre: string;
+  readonly experimental: boolean;
+  /** --genre as given on the command line, repeated in the check commands. */
+  readonly genreFlag: string | undefined;
+  readonly findings: readonly Finding[];
+  readonly rules: readonly RuleDefinition[];
+  readonly skipped: readonly Skipped[];
+  readonly outline: Outline;
+  /** The ai-tell lexicon of the document's language, whose entries may carry their own hint. */
+  readonly phrases: Lexicon;
+};
+
+const BOLD_DENSITY_RULE = "bold-density";
+const AI_TELL_RULE = "ai-tell";
+
+/** ai-generated-composite's inputs and bold-density: the rules the guide reads as document-level signals. */
+const signalRulesOf = (rules: readonly RuleDefinition[]): ReadonlySet<string> =>
+  new Set([...(rules.find((rule) => rule.id === COMPOSITE_RULE)?.from ?? []), BOLD_DENSITY_RULE]);
+
+/** article.md → article.rewritten.md, beside the original. */
+export const rewrittenPathOf = (path: string): string => {
+  const dot = path.lastIndexOf(".");
+  const slash = path.lastIndexOf("/");
+  return dot > slash + 1 ? `${path.slice(0, dot)}.rewritten${path.slice(dot)}` : `${path}.rewritten`;
+};
+
+const SHELL_SAFE = /^[\w./-]+$/u;
+
+/** A single quote inside single quotes: close, an escaped quote, reopen. */
+const QUOTE_IN_QUOTES = "'\\''";
+
+/** A path as a shell reads it: quoted unless every character is plain. */
+export const shellPath = (path: string): string => (SHELL_SAFE.test(path) ? path : `'${path.replaceAll("'", QUOTE_IN_QUOTES)}'`);
+
+/** The ai-tell phrases the finding names that carry a hint of their own. */
+export const phraseHintsOf = (finding: Finding, phrases: Lexicon, language: string): PhraseHint[] => {
+  const named = new Set(splitWords(String(finding.values["word"] ?? ""), language));
+  return phrases.flatMap((entry) =>
+    entry.rewrite !== undefined && named.has(entry.pattern.toLowerCase()) ? [{ phrase: entry.pattern, rewrite: entry.rewrite }] : [],
+  );
+};
+
+const spotOf = (finding: Finding, rule: RuleDefinition, language: string): PlanSpot => ({
+  line: finding.line,
+  column: finding.column,
+  quote: finding.quote,
+  message: messageOf(rule, finding, language),
+});
+
+const rulePlanOf = (rule: RuleDefinition, findings: readonly Finding[], input: PlanInput): RulePlan => {
+  const rewrite = rule.guide?.rewrite[input.language];
+  const hints = rule.id === AI_TELL_RULE ? findings.flatMap((finding) => phraseHintsOf(finding, input.phrases, input.language)) : [];
+  return {
+    rule: rule.id,
+    name: localized(rule.name, input.language),
+    direction: rewrite?.direction ?? localized(rule.how_to_fix, input.language),
+    keep: rewrite?.keep ?? [],
+    avoid: rewrite?.avoid ?? [],
+    pair: rewrite?.pairs[0],
+    hints,
+    spots: findings.map((finding) => spotOf(finding, rule, input.language)),
+  };
+};
+
+/** 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);
+  return order.flatMap((id) => {
+    const rule = input.rules.find((entry) => entry.id === id);
+    return rule === undefined
+      ? []
+      : [
+          rulePlanOf(
+            rule,
+            input.findings.filter((finding) => finding.rule === id),
+            input,
+          ),
+        ];
+  });
+};
+
+/** The composite first, then each signal rule once, with what its first finding said. */
+const signalsOf = (input: PlanInput, signalRules: ReadonlySet<string>): DocumentSignal[] =>
+  [COMPOSITE_RULE, ...signalRules].flatMap((id) => {
+    const finding = input.findings.find((entry) => entry.rule === id);
+    const rule = input.rules.find((entry) => entry.id === id);
+    return finding === undefined || rule === undefined ? [] : [{ rule: id, message: messageOf(rule, finding, input.language) }];
+  });
+
+const hasRewrite = (rule: RuleDefinition): boolean => Object.keys(rule.guide?.rewrite ?? {}).length > 0;
+
+/** A rule written for other languages is not one that failed to run on this document. */
+const checksLanguage = (rule: RuleDefinition, language: string): boolean => rule.languages === undefined || rule.languages.includes(language);
+
+const notRunOf = (input: PlanInput, signalRules: ReadonlySet<string>): Skipped[] => {
+  const forThisLanguage = input.rules.filter((rule) => checksLanguage(rule, input.language));
+  const watched = new Set(forThisLanguage.filter((rule) => hasRewrite(rule) || rule.id === COMPOSITE_RULE || signalRules.has(rule.id)).map((rule) => rule.id));
+  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. */
+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"] : [];
+  return [
+    ["npx chaffjs", rewritten, ...lintFlags].join(" "),
+    ["npx chaffjs compare", original, rewritten, ...compareFlags].join(" "),
+    ["npx chaffjs outline", original, rewritten].join(" "),
+  ];
+};
+
+/** The plan for one document: deterministic, from chaff's findings and the rule files alone. */
+export const buildFixPlan = (input: PlanInput): FixPlan => {
+  const signalRules = signalRulesOf(input.rules);
+  const mode = recommendMode({ genre: input.genre, firedRules: new Set(input.findings.map((finding) => finding.rule)), signalRules });
+  return {
+    path: input.path,
+    rewrittenPath: rewrittenPathOf(input.path),
+    language: input.language,
+    genre: input.genre,
+    experimental: input.experimental,
+    mode,
+    signals: signalsOf(input, signalRules),
+    outline: { unit: input.outline.unit, shape: input.outline.shape },
+    rules: rulePlansOf(input),
+    notRun: notRunOf(input, signalRules),
+    checks: checksOf(input, mode),
+  };
+};

package/src/fix-plan/render.ts

@@ -0,0 +1,128 @@
+import type { RewritePair } from "../rule-guide.ts";
+import { shapeMeasures } from "../outline/render.ts";
+import { OUTLINE_TEXT } from "../outline/text.ts";
+import { uiLanguageOf } from "../ui.ts";
+import type { FixPlan, PhraseHint, PlanSpot, RulePlan } from "./plan.ts";
+import { FIX_PLAN_TEXT, type FixPlanText } from "./text.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}"`);
+
+const bullets = (items: readonly string[]): string[] => items.map((item) => `- ${item}`);
+
+/** Each line of a passage as a Markdown quotation, so a list inside it stays a list and does not join the plan's own. */
+const blockquote = (passage: string): string[] =>
+  passage
+    .trimEnd()
+    .split("\n")
+    .map((line) => (line === "" ? ">" : `> ${line}`));
+
+const labelled = (label: string, lines: readonly string[]): string[] => (lines.length === 0 ? [] : ["", `**${label}**`, "", ...lines]);
+
+const pairLines = (pair: RewritePair | undefined, text: FixPlanText): string[] =>
+  pair === undefined ? [] : [`${text.before}:`, "", ...blockquote(pair.before), "", `${text.after}:`, "", ...blockquote(pair.after)];
+
+const hintLine = (hint: PhraseHint, language: string): string => `- ${quoted(hint.phrase, language)} → ${hint.rewrite}`;
+
+const spotLines = (spot: PlanSpot, text: FixPlanText, language: string): string[] => [
+  `- ${text.at(spot.line)}: ${quoted(spot.quote, language)}`,
+  `  ${spot.message}`,
+];
+
+const rulePlanLines = (rule: RulePlan, text: FixPlanText, language: string): string[] => [
+  "",
+  `### \`${rule.rule}\` ${rule.name}`,
+  "",
+  `**${text.direction}**: ${rule.direction}`,
+  ...labelled(text.keep, bullets(rule.keep)),
+  ...labelled(text.avoid, bullets(rule.avoid)),
+  ...labelled(text.example, pairLines(rule.pair, text)),
+  ...labelled(
+    text.phrases,
+    rule.hints.map((hint) => hintLine(hint, language)),
+  ),
+  ...labelled(
+    text.spots,
+    rule.spots.flatMap((spot) => spotLines(spot, text, language)),
+  ),
+];
+
+const modeLines = (plan: FixPlan, text: FixPlanText): string[] => [
+  "",
+  `## ${text.modeHeading}: ${text.modeName[plan.mode.mode]}`,
+  "",
+  text.modeReason[plan.mode.reason],
+  "",
+  ...bullets(text.modeWays),
+];
+
+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, ""] : [];
+  return ["", `## ${text.signalsHeading}`, "", ...said, ...bullets([...plan.signals.map((signal) => `\`${signal.rule}\`: ${signal.message}`), outline])];
+};
+
+const notRunLines = (plan: FixPlan, text: FixPlanText): string[] => {
+  const note = plan.experimental ? [] : [text.notExperimental];
+  const listed = plan.notRun;
+  if (note.length === 0 && listed.length === 0) return [];
+  return [
+    "",
+    `## ${text.notRunHeading}`,
+    "",
+    ...note,
+    ...(note.length > 0 && listed.length > 0 ? [""] : []),
+    ...bullets(listed.map((skipped) => `\`${skipped.rule}\`: ${skipped.why}`)),
+  ];
+};
+
+const checkLines = (plan: FixPlan, text: FixPlanText): string[] => [
+  "",
+  `## ${text.checksHeading}`,
+  "",
+  text.saveAs(plan.rewrittenPath),
+  "",
+  "```bash",
+  ...plan.checks,
+  "```",
+  "",
+  text.checksNote,
+];
+
+const textOf = (plan: FixPlan): FixPlanText => FIX_PLAN_TEXT[uiLanguageOf(plan.language)];
+
+/** The plan as Markdown, in the document's language: what an agent reads before rewriting. */
+export const renderFixPlanMarkdown = (plan: FixPlan): string => {
+  const text = textOf(plan);
+  return [
+    `# ${text.title(plan.path)}`,
+    "",
+    text.about(plan.language, plan.genre),
+    "",
+    text.intro,
+    "",
+    `## ${text.constraintsHeading}`,
+    "",
+    ...text.constraints.map((constraint, index) => `${String(index + 1)}. ${constraint}`),
+    ...modeLines(plan, text),
+    ...signalLines(plan, text),
+    ...(plan.rules.length === 0 ? [] : ["", `## ${text.rulesHeading}`]),
+    ...plan.rules.flatMap((rule) => rulePlanLines(rule, text, plan.language)),
+    ...notRunLines(plan, text),
+    ...checkLines(plan, text),
+  ].join("\n");
+};
+
+/** The same plan as JSON, with the constraints and the mode's reason in the document's language. */
+export const renderFixPlanJson = (plan: FixPlan): string => {
+  const text = textOf(plan);
+  return JSON.stringify(
+    {
+      ...plan,
+      constraints: text.constraints,
+      mode: { ...plan.mode, name: text.modeName[plan.mode.mode], why: text.modeReason[plan.mode.reason] },
+    },
+    null,
+    2,
+  );
+};

package/src/fix-plan/text.ts

@@ -0,0 +1,133 @@
+import type { Texts } from "../ui.ts";
+import type { FixMode, ModeReason } from "./mode.ts";
+
+export type FixPlanText = {
+  readonly usage: string;
+  readonly notFound: (path: string) => string;
+  readonly title: (path: string) => string;
+  readonly about: (language: string, genre: string) => string;
+  readonly intro: string;
+  readonly constraintsHeading: string;
+  readonly constraints: readonly string[];
+  readonly modeHeading: string;
+  readonly modeName: Readonly<Record<FixMode, string>>;
+  readonly modeReason: Readonly<Record<ModeReason, string>>;
+  readonly modeWays: readonly string[];
+  readonly signalsHeading: string;
+  readonly noSignals: string;
+  readonly outlineLine: (measures: string) => string;
+  readonly rulesHeading: string;
+  readonly direction: string;
+  readonly keep: string;
+  readonly avoid: string;
+  readonly example: string;
+  readonly before: string;
+  readonly after: string;
+  readonly phrases: string;
+  readonly spots: string;
+  readonly at: (line: number) => string;
+  readonly notRunHeading: string;
+  readonly notExperimental: string;
+  readonly checksHeading: string;
+  readonly saveAs: (path: string) => string;
+  readonly checksNote: string;
+};
+
+export const FIX_PLAN_TEXT: Texts<FixPlanText> = {
+  ja: {
+    usage: "使い方: chaff fix-plan <file> [--experimental] [--genre <ジャンル>] [--json]",
+    notFound: (path) => `${path} がありません。`,
+    title: (path) => `直す計画: ${path}`,
+    about: (language, genre) => `言語 ${language}、ジャンル ${genre}`,
+    intro:
+      "chaff が機械で見つけた箇所と、それぞれの直す方向です。chaff は書き直しません。書き直すのは、この計画を読む人か AI です。直したら、最後の確かめのコマンドを実行してください。",
+    constraintsHeading: "守ること",
+    constraints: [
+      "事実、数、日付、条件、名前を変えない。",
+      "元の文書に無い事実、人、数、原因、例を足さない。",
+      "直すのに文書に無い具体（誰が、いつ、どれだけ）が要るときは、作らずに［ ］で空けて書き手に聞く。",
+      "書き直しは 2 回まで。指摘を消すためだけに書き直しを繰り返さない。",
+    ],
+    modeHeading: "勧める直し方",
+    modeName: { none: "直すところなし", light: "軽く直す（Light）", bold: "大胆に直す（Bold）", full: "全面書き直し（Full）" },
+    modeReason: {
+      "nothing-found": "chaff は何も見つけませんでした。",
+      composite: "ai-generated-composite が出ています。文の言い回しを直しても、生成文の骨組みが残ります。",
+      genre: "ブログやエッセイは、構成から書き直すほうが書き手の望みに合います。",
+      signals: "文書全体を測るルールが 2 つ以上出ています。見出しの構成は残し、節ごとに文を書き直します。",
+      spots: "指摘は箇所ごとです。指摘された所だけを直します。",
+    },
+    modeWays: [
+      "軽く直す: 指摘された箇所だけ。",
+      "大胆に直す: 見出しの構成は残し、節ごとに文を書き直す。",
+      "全面書き直し: 事実と主張を控えてから、構成から書き直す。頼まれた内容が「全面的に」「一から」なら、これを選ぶ。",
+    ],
+    signalsHeading: "文書全体の目印",
+    noSignals: "文書全体を測るルールは、何も言っていません。",
+    outlineLine: (measures) => `構成: ${measures}`,
+    rulesHeading: "ルールごとの直し方",
+    direction: "直す方向",
+    keep: "変えないもの",
+    avoid: "やりがちな間違い",
+    example: "例",
+    before: "前",
+    after: "後",
+    phrases: "言い回しごとの手がかり",
+    spots: "見つけた箇所",
+    at: (line) => `${String(line)} 行目`,
+    notRunHeading: "動かなかったルール",
+    notExperimental: "試験中のルールは動かしていません。AIっぽさのルールの多くは試験中です。--experimental を付けると見ます。",
+    checksHeading: "直したあとの確かめ",
+    saveAs: (path) => `書き直したものを ${path} に保存して、次を実行します。`,
+    checksNote:
+      "1 つめは書き直した文書の指摘、2 つめは事実が落ちていないか・足されていないか、3 つめは構成の変化です。数は chaff の出力から取り、形容詞で言わないでください。",
+  },
+  en: {
+    usage: "usage: chaff fix-plan <file> [--experimental] [--genre <genre>] [--json]",
+    notFound: (path) => `${path} does not exist.`,
+    title: (path) => `Fix plan: ${path}`,
+    about: (language, genre) => `language ${language}, genre ${genre}`,
+    intro:
+      "What chaff found by machine, and how to rewrite each kind of spot. chaff does not rewrite; whoever reads this plan does, a person or an AI. When done, run the checks at the end.",
+    constraintsHeading: "Constraints",
+    constraints: [
+      "Keep every fact, number, date, condition and name.",
+      "Add no fact, person, number, cause or example the original does not have.",
+      "Where a fix needs a specific the text does not give (who, when, how much), do not invent it: leave [ ] and ask the writer.",
+      "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" },
+    modeReason: {
+      "nothing-found": "chaff found nothing.",
+      composite: "ai-generated-composite fires. Fixing the wording would leave the skeleton of generated text.",
+      genre: "For a blog post or an essay, what the writer wants changed is usually the structure.",
+      signals: "Two or more rules that measure the whole document fire. Keep the outline and rewrite the prose section by section.",
+      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.',
+    ],
+    signalsHeading: "Document-level signals",
+    noSignals: "None of the rules that measure the whole document said anything.",
+    outlineLine: (measures) => `Outline: ${measures}`,
+    rulesHeading: "How to rewrite, rule by rule",
+    direction: "Direction",
+    keep: "Keep",
+    avoid: "Avoid",
+    example: "Example",
+    before: "before",
+    after: "after",
+    phrases: "Hints for the phrases found",
+    spots: "Spots",
+    at: (line) => `line ${String(line)}`,
+    notRunHeading: "Rules that did not run",
+    notExperimental: "The experimental rules did not run, and most rules for generated text are experimental. Add --experimental to run them.",
+    checksHeading: "Check after rewriting",
+    saveAs: (path) => `Save the rewrite as ${path} and run:`,
+    checksNote:
+      "The first lists the rewrite's findings, the second checks that no fact was dropped or added, the third shows how the outline moved. Take the numbers from chaff's output, not adjectives.",
+  },
+};