chaffjs 0.17.0 → 0.18.0

package/skills/chaff/SKILL.md

@@ -61,6 +61,7 @@ relaxing a rule.
   existing one is left as it is), and adds `.chaff-cache/` and `.env*` to `.gitignore`.
 - `npx chaffjs rules --json [--genre <genre>]` prints every rule with its levels, the setting in effect (`now`,
   the genre's preset included) and why a rule is off. Read it instead of guessing rule names or limits.
+  `npx chaffjs rules` shows the same as a table, grouped, with the level each rule runs at now.
 - A level is `strict` / `normal` / `relaxed` / `off`; when even `relaxed` is too tight, a positive number is the
   limit itself (`max-sentence-length: 260`).
 - `prefer:` maps spellings to the team's (`e-mail: email`); `preferred-term: normal` turns the rule on.
@@ -68,6 +69,75 @@ relaxing a rule.
 - `genre:` sets the kind of document; `by_path` sets one per folder; `--genre` overrides both for one run.
   `rules:` wins over the genre's preset.
 
+## Turn a team's style note into chaff.yaml
+
+When the person gives house rules ("polite endings, sentences of at most 80 characters"), do not guess rule
+names or numbers:
+
+1. Read `npx chaffjs rules --json`. Each rule has `summary` (what it finds), `level_meaning` (what a level's
+   number means), `levels`, `example`, `not_flagged`, and `genres` (whether it runs in each genre).
+2. Split the note into single requirements; map each to the rule whose `summary` and `level_meaning` fit. A
+   number between levels is written as the number itself (`max-sentence-length: 80`). Spellings go under
+   `prefer`, in-house words under `jargon`, required headings under `required_sections`.
+3. Say plainly what no rule covers. For example, `no-mixed-desumasu` flags a register mixed into a document, but
+   does not require a particular one; a document wholly in the other register is not reported.
+4. Write only what differs from the default, then check before committing: `npx chaffjs explain <rule-id>`, a
+   short sample that breaks each requirement (each must be reported), and `npx chaffjs rules` (the table shows the
+   level each rule now runs at).
+
+## Adding a team rule
+
+Pick the easiest way that can say the requirement:
+
+| Requirement | Use |
+| --- | --- |
+| An existing rule covers it | A level, a number, `prefer`, `jargon` or `required_sections` in `chaff.yaml` |
+| A fixed phrase or pattern, with the team's own message | `custom_rules` of type `words` or `pattern` (coming in the next release) |
+| Decided by part of speech or inflection | `custom_rules` of type `tokens` (coming in the next release) |
+| Counting or comparing that the above cannot express | a Node function, `type: module` (a later release) |
+
+Test a new team rule the same way: `explain`, then a sample it must report and a sample it must not, before
+committing `chaff.yaml`. The guide page "Adding a rule" covers each way and how to add a rule to chaff itself.
+
+## Making AI-sounding text sound human
+
+chaff marks the shapes common in generated text (group "Signs of generated text" in `npx chaffjs rules`: `ai-tell`,
+`contrast-framing`, `stock-transition`, `announcing-opener`, `colon-lead-in` (Japanese only), `assistant-residue`, and the signals
+`ai-generated-composite` reads). Most are experimental: run with `--experimental`. None of them says the text was
+generated. When asked to make a text sound less generated, pick one of two modes and say which.
+
+**Light** (only the flagged spots), when the content and structure are fine:
+
+1. `npx chaffjs <file> --experimental` (or with the genre's `--genre`); collect the AI-shape findings.
+2. Rewrite only those spots. Keep the meaning, numbers, conditions and technical constraints.
+3. Run chaff again. At most two rewrite passes.
+4. Show the rewritten text and a short list of what changed and why.
+
+**Bold** (section by section), when a light pass still leaves it reading as generated:
+
+1. Run chaff with `--experimental` and note the document-level signals: the `ai-generated-composite` inputs,
+   `bold-density`, `contrast-framing`, `stock-transition`, `sentence-rhythm`.
+2. Rewrite each section toward a human voice: less bold; one-line paragraphs and punchlines folded back into
+   paragraphs; no "X ではありません。Y です" / "It's not X. It's Y" frames; lists turned back into sentences where the
+   items connect; fewer em dashes; no announcing openers. Each paragraph carries one claim, joined to the last by a
+   connective, built around the writer's own experience or numbers where the original has them.
+3. Run chaff again and report the same signals before and after, from chaff's output.
+4. Run `npx chaffjs compare <old> <new>` (exit 1 on a dropped or added fact; `--json` to act on it). Restore every
+   dropped fact; for one that is not a fact (a number inside a metaphor, the heading of a section you cut), say why it
+   stays out. `--allow-dropped <kind>` excludes a kind you cut on purpose. Never leave an added fact.
+
+In both modes:
+
+- Never add facts, people, numbers or causes the original does not have.
+- Keep a domain term a word rule trips when it is right in context.
+- Prefer a direct statement over a negated contrast. Say who does what.
+- Never loop just to silence a warning; two passes at most, and list what is left with the reason.
+- Per genre: in a tech article, replace metaphors ("静かに壊れる", "silently fails") with what happens and keep steps
+  and commands as lists; in a business document, put the conclusion and who does what first and keep tables and
+  figures; in an essay, fold punchlines back in and replace big words ("真理", "new possibilities") with the scene.
+
+The guide page "Making AI-sounding text sound human" has a worked example with chaff's output before and after.
+
 ## Structured documents
 
 - `npx chaffjs tree <file>` shows a contract or specification as a tree of addresses (`3.2` for 第3条第2項 or

package/src/announced-count.ts

@@ -0,0 +1,148 @@
+import { escapeRegExp } from "./orthography.ts";
+import type { BulletList, Span } from "./plugin.ts";
+import { joined, linesAbove, type TextBlock } from "./text-above.ts";
+
+/**
+ * 箇条書きのすぐ前の文が予告した数（以下の3点、the following three steps）と、箇条書きのいちばん外側の項目の数。
+ * 予告と読むのは、文の最後の一文に数がちょうど一つあり、先を指す語がその前にあるか文がコロンで終わるときだけ。
+ * 言語の知識（先を指す語、漢数字や数の語、数える語、数を目安や順番にする語）は語彙表から受け取る。
+ */
+export type CountWords = {
+  /** 以下の、次の、following。 */
+  readonly anchors: readonly string[];
+  /** 数を字で書いたもの。一から順に並べる。 */
+  readonly numbers: readonly string[];
+  /** 数のすぐ後ろで並べるものを数える語。点、つ、steps。 */
+  readonly counters: readonly string[];
+  /** 数のすぐ前にあると予告でなくなる語（約、第、at least）。 */
+  readonly hedgesBefore: readonly string[];
+  /** 数か数える語のすぐ後ろにあると予告でなくなる語（以上、目、or more）。 */
+  readonly hedgesAfter: readonly string[];
+};
+
+export type CountMismatch = { readonly offset: number; readonly phrase: string; readonly announced: number; readonly listed: number };
+
+/** counted: 数える語が付いている（3点）。付いていない数（the following two:）は、先を指す語のすぐ後ろでだけ予告に読む。 */
+type Phrase = { readonly start: number; readonly numberEnd: number; readonly end: number; readonly announced: number; readonly counted: boolean };
+
+/** 予告の文の外側。見出し、表、引用、コードの囲みの行は、すぐ下の箇条書きを予告する文ではない。 */
+const NOT_A_LEAD = /^[ \t]*(?:#|\||>|```|~~~)/u;
+
+/** 箇条書きのすぐ前の塊。見出し・表・引用・コードの囲みなら undefined。 */
+const leadBefore = (source: string, listStart: number): TextBlock | undefined => {
+  const lines = linesAbove(source, listStart);
+  return lines.some((line) => NOT_A_LEAD.test(line.text)) ? undefined : joined(source, lines);
+};
+
+/** 文の終わり。英語の「.」は後ろが空白のときだけ（3.5 や e.g. の途中で切らない）。 */
+const SENTENCE_END = /[。！？!?]|\.(?=\s)/gu;
+
+/** 塊の最後の一文の始まり（塊の中の位置）。 */
+const lastSentenceStart = (text: string): number => {
+  const body = text.trimEnd();
+  const ends = [...body.matchAll(SENTENCE_END)].map((match) => match.index + match[0].length).filter((end) => end < body.length);
+  return ends.at(-1) ?? 0;
+};
+
+const alternation = (words: readonly string[]): string =>
+  words
+    .toSorted((a, b) => b.length - a.length)
+    .map(escapeRegExp)
+    .join("|");
+
+/**
+ * 数と、それが数えるもの。数の前が数字・英字・数の字なら数の途中（十三、23、eleven の中）。
+ * 英語は数と数える語の間に語を二つまで置ける（three key steps）。数える語が無くても、文がコロンで終わる直前の数（the following two:）は数に読む。
+ */
+const phrasePattern = (words: CountWords): RegExp => {
+  const numberChars = escapeRegExp([...new Set(words.numbers.join(""))].join(""));
+  const numbers = words.numbers.length === 0 ? "\\p{Nd}+" : `\\p{Nd}+|${alternation(words.numbers)}`;
+  const counted = `[ \\t\\u00a0]?(?:\\p{Ll}[\\p{Ll}-]*[ \\t]){0,2}(${alternation(words.counters)})(?![A-Za-z])`;
+  return new RegExp(`(?<![\\p{N}A-Za-z${numberChars}])(${numbers})(?:${counted}|(?=[ \\t]?[:：][ \\t]*$))`, "giu");
+};
+
+const valueOf = (written: string, numbers: readonly string[]): number => {
+  const digits = Number(written.normalize("NFKC"));
+  if (!Number.isNaN(digits)) return digits;
+  return numbers.findIndex((number) => number.toLowerCase() === written.toLowerCase()) + 1;
+};
+
+const LATIN_LETTER = /[A-Za-z]/u;
+const isLatin = (char: string | undefined): boolean => LATIN_LETTER.test(char ?? "");
+
+/** 英語の語は語の切れ目で照らす（over が moreover に当たらない）。日本語の語は字面どおり。 */
+const endsWithWord = (text: string, word: string): boolean => text.endsWith(word) && !(isLatin(word[0]) && isLatin(text.at(-word.length - 1)));
+
+const startsWithWord = (text: string, word: string): boolean => text.startsWith(word) && !(isLatin(word.at(-1)) && isLatin(text[word.length]));
+
+const isHedged = (sentence: string, phrase: Phrase, words: CountWords): boolean => {
+  const before = sentence.slice(0, phrase.start).trimEnd().toLowerCase();
+  const afters = [sentence.slice(phrase.numberEnd), sentence.slice(phrase.end)].map((text) => text.trimStart().toLowerCase());
+  return (
+    words.hedgesBefore.some((hedge) => endsWithWord(before, hedge.toLowerCase())) ||
+    words.hedgesAfter.some((hedge) => afters.some((after) => startsWithWord(after, hedge.toLowerCase())))
+  );
+};
+
+const COLON_END = /[:：][ \t]*$/u;
+
+/** 数える語の無い数は、先を指す語のすぐ後ろでだけ（the following two:）。「under $75:」の金額を数に読まない。 */
+const pointsAhead = (sentence: string, phrase: Phrase, anchors: readonly string[]): boolean => {
+  const before = sentence.slice(0, phrase.start).toLowerCase();
+  const lowered = anchors.map((anchor) => anchor.toLowerCase());
+  if (!phrase.counted) return lowered.some((anchor) => endsWithWord(before.trimEnd(), anchor));
+  return COLON_END.test(sentence.trimEnd()) || lowered.some((anchor) => before.includes(anchor));
+};
+
+/** 最後の一文の予告。数がちょうど一つで、目安や順番でなく、先を指しているときだけ。 */
+const announcedIn = (sentence: string, words: CountWords, pattern: RegExp): Phrase | undefined => {
+  const phrases = [...sentence.matchAll(pattern)].map((match) => ({
+    start: match.index,
+    numberEnd: match.index + (match[1] ?? "").length,
+    end: match.index + match[0].length,
+    announced: valueOf(match[1] ?? "", words.numbers),
+    counted: match[2] !== undefined,
+  }));
+  const only = phrases.length === 1 ? phrases[0] : undefined;
+  if (only === undefined || only.announced < 1 || isHedged(sentence, only, words)) return undefined;
+  return pointsAhead(sentence, only, words.anchors) ? only : undefined;
+};
+
+/** 位置から空白と改行を読み飛ばした先。 */
+const pastSpace = (source: string, at: number): number => {
+  const filled = /[^ \t\r\n]/gu;
+  filled.lastIndex = at;
+  return filled.exec(source)?.index ?? source.length;
+};
+
+/** 箇条書きの終わり（後ろの空白を読み飛ばした先）と始まり。空白だけを挟んで続く二つの箇条書きは、終わりと始まりが同じ位置になる。 */
+type Neighbours = { readonly ends: ReadonlySet<number>; readonly starts: ReadonlySet<number> };
+
+const neighboursOf = (source: string, lists: readonly BulletList[]): Neighbours => ({
+  ends: new Set(lists.map((list) => pastSpace(source, list.span.end))),
+  starts: new Set(lists.map((list) => list.span.start)),
+});
+
+/** 空白だけを挟んで前か後ろに別の箇条書きが続く。印が変わって二つに割れた一つの並びかもしれず、数を決められない。 */
+const hasNeighbour = (source: string, list: Span, neighbours: Neighbours): boolean =>
+  neighbours.ends.has(list.start) || neighbours.starts.has(pastSpace(source, list.end));
+
+type Context = { readonly source: string; readonly words: CountWords; readonly pattern: RegExp; readonly neighbours: Neighbours };
+
+const mismatchOf = ({ source, words, pattern, neighbours }: Context, list: BulletList): CountMismatch[] => {
+  if (hasNeighbour(source, list.span, neighbours)) return [];
+  const lead = leadBefore(source, list.span.start);
+  if (lead === undefined) return [];
+  const sentenceStart = lastSentenceStart(lead.text);
+  const sentence = lead.text.slice(sentenceStart);
+  const phrase = announcedIn(sentence, words, pattern);
+  if (phrase === undefined || phrase.announced === list.items.length) return [];
+  const offset = lead.start + sentenceStart + phrase.start;
+  return [{ offset, phrase: sentence.slice(phrase.start, phrase.end).trim(), announced: phrase.announced, listed: list.items.length }];
+};
+
+export const announcedCountMismatches = (source: string, lists: readonly BulletList[], words: CountWords): CountMismatch[] => {
+  if (words.counters.length === 0) return [];
+  const context = { source, words, pattern: phrasePattern(words), neighbours: neighboursOf(source, lists) };
+  return lists.flatMap((list) => mismatchOf(context, list));
+};

package/src/bare-url.ts

@@ -0,0 +1,35 @@
+import type { Span } from "./plugin.ts";
+
+/**
+ * `https://…` をそのまま書いた URL。GFM の autolink 拡張を入れていないので mdast では
+ * ただのテキストになり、本文として残る。残すと、見出しと URL の中の識別子が一致して
+ * 「見出しの繰り返し」と読まれる。表示される文字も本文ではない。
+ * 空白が来るまでを取るので、URL の直後に続けた日本語（「https://example.jp/をご覧ください」の「をご覧ください」）も入る。
+ */
+export const BARE_URL = /https?:\/\/[^\s)<>"'\]]+/gu;
+
+/** 文の終わりの句読点。URL の最後の字としてはまず書かれず、URL の後ろの文の字。 */
+const PUNCTUATION: ReadonlySet<string> = new Set([".", ",", ";", ":", "!", "?"]);
+
+/**
+ * そのまま書いた URL に続けた文の始まり: ひらがなと全角の句読点・括弧（「…/をご覧ください」「…/。」）。
+ * 漢字やカタカナは道の名前（/東京、/カタログ）にもなるので切らない。
+ */
+const SENTENCE_AFTER = /[\p{Script=Hiragana}\u3000-\u303f\uff01-\uff0f\uff1a-\uff20]/u;
+
+/** URL として読む長さ。続けた文の手前で切り、後ろの句読点を外す。正規表現の `[…]+$` は句読点の長い並びで後戻りが二乗になる。 */
+const urlLength = (written: string): number => {
+  const cut = SENTENCE_AFTER.exec(written)?.index ?? written.length;
+  let end = cut;
+  while (end > 0 && PUNCTUATION.has(written.charAt(end - 1))) end -= 1;
+  return end;
+};
+
+export type BareUrl = Span & { readonly url: string };
+
+/** text の中の、そのまま書いた URL。続けて書いた日本語と文末の句読点は外す。位置は text の先頭を 0 とする。 */
+export const bareUrls = (text: string): BareUrl[] =>
+  [...text.matchAll(BARE_URL)].map((match) => {
+    const url = match[0].slice(0, urlLength(match[0]));
+    return { start: match.index, end: match.index + url.length, url };
+  });

package/src/baseline.ts

@@ -13,6 +13,21 @@ export const fingerprint = (path: string, finding: Finding): string => {
   return createHash("sha256").update(body).digest("hex").slice(0, 16);
 };
 
+/**
+ * findings の fingerprint を順に。一つの文から出た指摘は同じ文を引くので、文と rule の組ごとに一度だけ計算する。
+ * 長い文に指摘が多いと、指摘ごとに文を読み直すのでは指摘数と文の長さの積になる。
+ */
+export const fingerprints = (path: string, findings: readonly Finding[]): string[] => {
+  const known = new Map<string, Map<string, string>>();
+  return findings.map((finding) => {
+    const byRule = known.get(finding.quote) ?? new Map<string, string>();
+    known.set(finding.quote, byRule);
+    const found = byRule.get(finding.rule) ?? fingerprint(path, finding);
+    byRule.set(finding.rule, found);
+    return found;
+  });
+};
+
 export type Baseline = { readonly version: 1; readonly created: string; readonly entries: readonly string[] };
 
 const isBaseline = (value: unknown): value is Baseline =>
@@ -40,7 +55,8 @@ export type Split = { readonly fresh: readonly Finding[]; readonly shelved: numb
 export const splitByBaseline = (path: string, findings: readonly Finding[], baseline: Baseline | undefined): Split => {
   if (baseline === undefined) return { fresh: findings, shelved: 0 };
   const known = new Set(baseline.entries);
-  const fresh = findings.filter((finding) => !known.has(fingerprint(path, finding)));
+  const prints = fingerprints(path, findings);
+  const fresh = findings.filter((_, index) => !known.has(prints[index] ?? ""));
   return { fresh, shelved: findings.length - fresh.length };
 };
 

package/src/body-section.ts

@@ -0,0 +1,7 @@
+import type { Section } from "./plugin.ts";
+
+/**
+ * 本題の始まり: 最初の中見出し（深さ 2 以上）の節。表題（深さ 1）の直後から数えると、表題しか無い文書で全文が前置きになる。
+ * 無ければ、本題の前を測る rule は動けない（rule の requires の headings）。
+ */
+export const bodySectionOf = (sections: readonly Section[]): Section | undefined => sections.find((section) => section.depth >= 2);

package/src/calendar-number.ts

@@ -8,9 +8,15 @@ import type { ProseDocument, Span, Token } from "./plugin.ts";
  * 単位は語彙表から渡す。chained は日付・時刻の単位を大きい順に（年月日時分秒）。大きい単位の後ろに小さい単位を続けて書けば
  * 一つの日付・時刻になる。「2008年 2年連続」のように同じ単位や大きい単位が続けば、別のものの始まり。
  * positional は数の後ろに置くだけで位置を言う単位（月、時）。year は 4 桁の数の後ろで暦の年を言う単位（年、年度）。
+ * era は元号（令和）。元号のすぐ後ろ（空白 1 つまで）の数は、単位が何でも暦の上の位置を言う（令和8年、桁が少なくても年数ではない）。
  * 「5日」「5分」「3年」のように、単位だけでは長さと見分けのつかないものは、位置を言う単位と続けて書いたときだけ日付・時刻と読む。
  */
-export type CalendarUnits = { readonly chained: readonly string[]; readonly positional: ReadonlySet<string>; readonly year: ReadonlySet<string> };
+export type CalendarUnits = {
+  readonly chained: readonly string[];
+  readonly positional: ReadonlySet<string>;
+  readonly year: ReadonlySet<string>;
+  readonly era: readonly string[];
+};
 
 /** 日付・時刻の数の並び。first は日付の頭の数、inner は前の単位に続く数（2026年9月の 9）。unit は数の後ろの単位（月）。 */
 export type CalendarRun = { readonly run: Span; readonly place: "first" | "inner"; readonly unit: string };
@@ -38,15 +44,22 @@ const pastSpace = (text: string, at: number): number => (text[at] === " " ? at +
 
 const isUnit = (surface: string, units: CalendarUnits): boolean => units.chained.includes(surface) || units.positional.has(surface) || units.year.has(surface);
 
-const isAnchor = (digits: string, surface: string, units: CalendarUnits): boolean =>
-  units.positional.has(surface) || (units.year.has(surface) && CALENDAR_YEAR.test(digits));
+/** 数 run のすぐ前（空白 1 つまで）が元号か。 */
+const followsEra = (text: string, run: Span, units: CalendarUnits): boolean => {
+  const before = text.slice(0, run.start);
+  const written = before.endsWith(" ") ? before.slice(0, -1) : before;
+  return units.era.some((era) => written.endsWith(era));
+};
+
+const isAnchor = (text: string, run: Span, surface: string, units: CalendarUnits): boolean =>
+  units.positional.has(surface) || (units.year.has(surface) && CALENDAR_YEAR.test(text.slice(run.start, run.end))) || followsEra(text, run, units);
 
 /** 数のすぐ後ろ（空白 1 つまで）の語が日付・時刻の単位なら、その組。語の切れ目が合わなければ組にしない。 */
 const partOf = (text: string, run: Span, tokens: readonly Token[], base: number, units: CalendarUnits): Part | undefined => {
   const unit = tokens.find((token) => token.span.start === base + pastSpace(text, run.end));
   if (unit === undefined || !isUnit(unit.surface, units)) return undefined;
   const rank = units.chained.indexOf(unit.surface);
-  return { run, unit: unit.surface, unitEnd: unit.span.end - base, rank, anchored: isAnchor(text.slice(run.start, run.end), unit.surface, units) };
+  return { run, unit: unit.surface, unitEnd: unit.span.end - base, rank, anchored: isAnchor(text, run, unit.surface, units) };
 };
 
 /** 前の組の単位のすぐ後ろ（空白 1 つまで）から始まり、単位が前より小さい組か。 */
@@ -81,4 +94,5 @@ export const calendarUnitsOf = (doc: ProseDocument): CalendarUnits => ({
   chained: patternList(doc, "date-time-unit"),
   positional: new Set(patternList(doc, "calendar-unit")),
   year: new Set(patternList(doc, "calendar-year-unit")),
+  era: patternList(doc, "calendar-era"),
 });

package/src/cli-args.ts

@@ -7,3 +7,9 @@ const VALUE_FLAGS: ReadonlySet<string> = new Set(["--sarif", "--genre", "--rule"
 /** The arguments that name what to check: everything that is neither an option nor an option's value. */
 export const targetsOf = (args: readonly string[]): string[] =>
   args.filter((arg, index) => !arg.startsWith("--") && !(index > 0 && VALUE_FLAGS.has(args[index - 1] ?? "")));
+
+/** The settings with --experimental applied: the command line turns experimental rules on as chaff.yaml can. */
+export const withExperimental = <T extends { readonly experimental: boolean }>(config: T, args: readonly string[]): T => ({
+  ...config,
+  experimental: config.experimental || args.includes("--experimental"),
+});

package/src/cli-text.ts

@@ -21,7 +21,9 @@ const USAGE_JA = `chaff — 文章の読みにくいところを見つけます
   chaff genres                   ジャンル（文書の種類）の一覧と、それぞれ何向けか
   chaff tree <file> [--format sexp|json]  文書を番地の付いた木にする（条・項・定義・参照）
   chaff cite <原文> <引用.json>           回答の引用（番地と引用文）が原文にあるかを確かめる
-  chaff rules --json             いまの設定を JSON で出す（AI に渡す用）
+  chaff compare <前> <後>                書き換えで事実（数・日付・URL・コード・名前・引用…）が落ちても足されてもいないかを確かめる
+  chaff rules                    ルールの一覧を、グループごとに表で出す（いまの段階つき）
+  chaff rules --json             いまの設定とルールの説明を JSON で出す（AI に渡す用）
   chaff baseline <dir>           いまある指摘を棚上げする（既存の repo に入れるとき）
   chaff suppressions <dir>       stet で黙らせている指摘を数える
   chaff relax|strict|off <rule> [--why "理由"]
@@ -55,7 +57,9 @@ const USAGE_EN = `chaff — finds what makes writing hard to read. It never rewr
   chaff genres                   list the genres (kinds of document) and what each is for
   chaff tree <file> [--format sexp|json]  the document as a tree of addresses (sections, clauses, definitions, references)
   chaff cite <source> <quotes.json>       check that quoted passages (address and text) are in the source
-  chaff rules --json             the current settings as JSON (to give to an AI)
+  chaff compare <before> <after>          check that a rewrite dropped no fact and added none (numbers, dates, URLs, code, names, quotations…)
+  chaff rules                    the rules as a table, by group, with the level each runs at now
+  chaff rules --json             the current settings and what each rule is, as JSON (to give to an AI)
   chaff baseline <dir>           shelve today's findings (when adding chaff to an existing repository)
   chaff suppressions <dir>       count the findings silenced with stet
   chaff relax|strict|off <rule> [--why "reason"]
@@ -137,7 +141,7 @@ export const CLI_TEXT: Texts<CliText> = {
     unknownProfile: (profile, where, known) =>
       `文書の種類 "${profile}" はありません（${where}）。使えるのは ${known.join("、")} と、種類を使わない none です。`,
     profileWhere: (where, files) => (where === "config" ? "chaff.yaml の profile" : `chaff.yaml の by_path、files: ${files.join(", ")}`),
-    unknownRule: (id) => `${id} というルールはありません。npx chaff rules --json で一覧が出ます。`,
+    unknownRule: (id) => `${id} というルールはありません。npx chaff rules で一覧が出ます。`,
     unknownRuleWithList: (id, list) => `${id} というルールはありません。\n一覧:\n${list}`,
     unnamed: "(名前なし)",
     sarifWritten: (path, count) => `\n  SARIF を書きました: ${path}（${count} 件）`,
@@ -191,7 +195,7 @@ export const CLI_TEXT: Texts<CliText> = {
     unknownProfile: (profile, where, known) =>
       `There is no document profile "${profile}" (${where}). The profiles are ${known.join(", ")}; none uses no profile.`,
     profileWhere: (where, files) => (where === "config" ? "profile in chaff.yaml" : `by_path in chaff.yaml, files: ${files.join(", ")}`),
-    unknownRule: (id) => `There is no rule named ${id}. npx chaff rules --json lists them.`,
+    unknownRule: (id) => `There is no rule named ${id}. npx chaff rules lists them.`,
     unknownRuleWithList: (id, list) => `There is no rule named ${id}.\nRules:\n${list}`,
     unnamed: "(no name)",
     sarifWritten: (path, count) => `\n  Wrote SARIF: ${path} (${counted(count, "finding")})`,

package/src/cli.ts

@@ -1,15 +1,13 @@
-import { readFile } from "node:fs/promises";
-import { existsSync, mkdirSync, writeFileSync } from "node:fs";
+import { mkdirSync, writeFileSync } from "node:fs";
 import { dirname, join } from "node:path";
 import { loadAdapter, packageFor } from "./adapter-load.ts";
-import { CONFIG_FILE, EMPTY, loadConfig, type Config } from "./config/load.ts";
+import { CONFIG_FILE, type Config } from "./config/load.ts";
 import { applyByPath } from "./config/by-path.ts";
 import { applyLevel } from "./config/write.ts";
 import { buildDocument, teamRules } from "./document.ts";
 import { guessLanguage } from "./detect.ts";
-import { plainSource } from "./plain-source.ts";
-import { collectTargets } from "./files.ts";
-import { BASELINE_FILE, fingerprint, readBaseline, splitByBaseline, writeBaseline } from "./baseline.ts";
+import { collectTargets, readDocumentFile } from "./files.ts";
+import { BASELINE_FILE, fingerprints, readBaseline, splitByBaseline, writeBaseline } from "./baseline.ts";
 import { applySuppressions } from "./stet.ts";
 import { renderSuppressions, type PerFile } from "./render/suppressions.ts";
 import { clock, describeChange, snapshotOf, watchPaths, type Snapshot } from "./watch.ts";
@@ -19,8 +17,8 @@ import { GENRES } from "./genre.ts";
 import { resolveGenre } from "./resolve-genre.ts";
 import { runInit } from "./init.ts";
 import { initGenre } from "./commands/init-ask.ts";
-import { targetsOf } from "./cli-args.ts";
-import { loadRules } from "./rule-load.ts";
+import { targetsOf, withExperimental } from "./cli-args.ts";
+import { rulesOf } from "./custom/load.ts";
 import { renderCompact } from "./render/compact.ts";
 import { renderExplain } from "./render/explain.ts";
 import { renderFriendly } from "./render/friendly.ts";
@@ -28,18 +26,21 @@ import { renderGenres } from "./render/genres.ts";
 import { loadGenres, presetLevels } from "./genre-load.ts";
 import { fileHeader } from "./file-header.ts";
 import { rulesJson } from "./render/rules-json.ts";
+import { rulesTable } from "./render/rules-table.ts";
 import { renderSarif } from "./render/sarif.ts";
 import { VERSION, VERSION_LINES } from "./version.ts";
 import { runTree, treeTargets, type TreeContext } from "./commands/tree.ts";
 import { citeTargets, runCite } from "./commands/cite.ts";
+import { compareTargets, runCompare } from "./commands/compare.ts";
 import { runSkill } from "./commands/skill.ts";
 import { runFeedback, settingsOf } from "./commands/feedback.ts";
 import { homedir } from "node:os";
-import { ruleProblems } from "./config/rule-problems.ts";
-import { nameProblems } from "./config/name-problems.ts";
+import { settingWarnings } from "./config/warnings.ts";
+import { readConfigIn } from "./config/read.ts";
+import { optionLayersOf, settingSourcesOf } from "./config/option-problems.ts";
 import { renderSummary, type FileOutcome } from "./render/summary.ts";
-import { neededBy, runRules } from "./run.ts";
-import type { Level, RuleDefinition } from "./plugin.ts";
+import { neededBy, runRulesWith } from "./run.ts";
+import type { Finding, Level, RuleDefinition } from "./plugin.ts";
 import { CLI_TEXT, type CliText, type GenreSource } from "./cli-text.ts";
 import { hostLanguage, sharedLanguage, uiLanguageOf, type UiLanguage } from "./ui.ts";
 import { profileFor } from "./profile/for-file.ts";
@@ -48,7 +49,7 @@ import { settingProblems } from "./setting-problems.ts";
 /** Text for output that is not about one document. */
 const hostText = (config: Config): CliText => CLI_TEXT[hostLanguage(config.language, process.env)];
 
-const readConfig = (): Config => (existsSync(join(process.cwd(), CONFIG_FILE)) ? loadConfig(join(process.cwd(), CONFIG_FILE)) : EMPTY);
+const readConfig = (): Config => readConfigIn(process.cwd());
 
 /** resolveGenre with this run's --genre, for the commands that take it as a dependency. */
 const genreFrom =
@@ -61,7 +62,7 @@ const findRule = (rules: readonly RuleDefinition[], id: string | undefined): Rul
 const changeSetting = (command: Level, ruleId: string | undefined, why: string | undefined): number => {
   const config = readConfig();
   const language = config.language ?? hostLanguage(undefined, process.env);
-  const rule = findRule(loadRules(language), ruleId);
+  const rule = findRule(rulesOf(language, config), ruleId);
   if (rule === undefined) {
     console.error(hostText(config).unknownRule(ruleId ?? hostText(config).unnamed));
     return 1;
@@ -84,20 +85,21 @@ type Inspected = {
   readonly genre: string;
   readonly outcome: FileOutcome;
   readonly perFile: PerFile;
-  readonly all: readonly string[];
+  /** stet で黙らせたものを除いた、baseline で棚上げする前の指摘。fingerprint は baseline を書くときだけ作る。 */
+  readonly kept: readonly Finding[];
 };
 
 const inspect = async (path: string, config: Config, argv: readonly string[]): Promise<Inspected> => {
-  const source = plainSource(await readFile(path, "utf8"));
+  const source = await readDocumentFile(path);
   const language = applyByPath(config.byPath, config.baseDir, path).language ?? config.language ?? guessLanguage(source).language;
   const adapter = await loadAdapter(language);
   const { genre, from, unread } = resolveGenre(path, source, config, flag(argv, "--genre"));
   if (unread !== undefined) console.error(`chaff: ${CLI_TEXT[uiLanguageOf(language)].unreadFrontMatterGenre(path, unread, GENRES)}`);
-  const rules = loadRules(language);
+  const rules = rulesOf(language, config);
   const experimental = config.experimental || argv.includes("--experimental");
   await adapter.prepare?.(neededBy(rules, config.rules, experimental, genre, language));
   const doc = buildDocument(path, source, adapter, teamRules(config), profileFor(config, path, source, language, genre));
-  const raw = runRules(doc, rules, config.rules, experimental, genre, config.limits);
+  const raw = runRulesWith(doc, rules, { settings: config.rules, experimental, genre, limits: config.limits, optionLayers: optionLayersOf(config) });
   // 応答は 3 つ。stet で黙らせたものは、ここで落とす。
   const applied = applySuppressions(
     source,
@@ -116,7 +118,7 @@ const inspect = async (path: string, config: Config, argv: readonly string[]): P
     genre,
     outcome: { path, findings: split.fresh, notRun: raw.skipped.length },
     perFile: { path, suppressed: applied.suppressed, reasonless: applied.unusedReasonless },
-    all: applied.kept.map((finding) => fingerprint(path, finding)),
+    kept: applied.kept,
   };
 };
 
@@ -137,10 +139,8 @@ const writeSarif = (results: readonly Inspected[], argv: readonly string[]): voi
 };
 
 /** 効いていない設定は、結果の前に一度だけ言う。標準エラーに出すので、JSON や SARIF の出力は汚さない。 */
-const warnRuleProblems = (config: Config, language: string): void => {
-  const ui = hostLanguage(config.language, process.env);
-  [...ruleProblems(config, loadRules(language), ui), ...nameProblems(config, ui)].forEach((problem) => console.error(`chaff: ${problem}`));
-};
+const warnRuleProblems = (config: Config, language: string): void =>
+  settingWarnings(config, rulesOf(language, config), hostLanguage(config.language, process.env)).forEach((problem) => console.error(`chaff: ${problem}`));
 
 /** Several files end with one summary: in their language when they share one, else the host's. */
 const summaryLanguage = (results: readonly Inspected[], config: Config): UiLanguage => {
@@ -214,7 +214,7 @@ const explain = (ruleId: string | undefined, genreFlag: string | undefined): num
   // The rule's limits differ by language (characters for Japanese, words for English): explain in the one being written.
   const language = config.language ?? hostLanguage(undefined, process.env);
   const text = CLI_TEXT[uiLanguageOf(language)];
-  const rules = loadRules(language);
+  const rules = rulesOf(language, config);
   const rule = findRule(rules, ruleId);
   if (rule === undefined) {
     const list = rules.map((entry) => `  ${entry.id}`).join("\n");
@@ -223,7 +223,7 @@ const explain = (ruleId: string | undefined, genreFlag: string | undefined): num
   }
   const preset = genre === undefined ? {} : presetLevels(genre);
   const current = config.rules[rule.id] ?? preset[rule.id] ?? (rule.status === "experimental" && !config.experimental ? "off" : "normal");
-  console.log(renderExplain(rule, current, language, text.unit(rule.id, language), genre));
+  console.log(renderExplain(rule, current, language, text.unit(rule.id, language), genre, settingSourcesOf(config, rule.id)));
   return 0;
 };
 
@@ -235,7 +235,7 @@ const runBaseline = async (targets: readonly string[], argv: readonly string[]):
     return 1;
   }
   const results = await Promise.all(paths.map((path) => inspect(path, config, [...argv, "--show-baseline"])));
-  const entries = results.flatMap((result) => result.all);
+  const entries = results.flatMap((result) => fingerprints(result.outcome.path, result.kept));
   const file = join(process.cwd(), BASELINE_FILE);
   writeBaseline(file, entries);
   console.log(hostText(config).baselineDone(paths.length, entries.length, BASELINE_FILE).join("\n"));
@@ -246,12 +246,8 @@ const runSuppressions = async (targets: readonly string[], argv: readonly string
   const paths = collectTargets(targets.length > 0 ? targets : ["."]);
   const config = readConfig();
   const results = await Promise.all(paths.map((path) => inspect(path, config, [...argv, "--show-baseline"])));
-  console.log(
-    renderSuppressions(
-      results.map((result) => result.perFile),
-      hostLanguage(config.language, process.env),
-    ),
-  );
+  const perFile = results.map((result) => result.perFile);
+  console.log(renderSuppressions(perFile, hostLanguage(config.language, process.env)));
   return 0;
 };
 
@@ -260,11 +256,14 @@ type Handler = (argv: readonly string[]) => number | Promise<number>;
 /** `--` で始まらない引数。対象のパス。 */
 const positional = (argv: readonly string[]): string[] => targetsOf(argv.slice(1));
 
-const showRules = (genreFlag: string | undefined): number => {
-  const config = readConfig();
+/** `rules --json` for an AI to read; `rules` alone, a table for a person. */
+const showRules = (argv: readonly string[]): number => {
+  const config = withExperimental(readConfig(), argv);
   const language = config.language ?? hostLanguage(undefined, process.env);
   warnRuleProblems(config, language);
-  console.log(rulesJson(loadRules(language), config, language, genreFlag ?? config.genre ?? "blog/tech"));
+  const genre = flag(argv, "--genre") ?? config.genre ?? "blog/tech";
+  const rules = rulesOf(language, config);
+  console.log(argv.includes("--json") ? rulesJson(rules, config, language, genre, optionLayersOf(config)) : rulesTable(rules, config, language, genre));
   return 0;
 };
 
@@ -294,11 +293,12 @@ const HANDLERS: Readonly<Record<string, Handler>> = {
     return "error" in chosen ? 1 : 0;
   },
   genres: showGenres,
-  rules: (argv) => showRules(flag(argv, "--genre")),
+  rules: showRules,
   explain: (argv) => explain(argv[1], flag(argv, "--genre")),
   eval: (argv) => runEval(positional(argv), argv, { ...measureContext(argv), flag }),
   tree: (argv) => runTree(treeTargets(argv), argv, treeContext()),
   cite: (argv) => runCite(citeTargets(argv), argv, treeContext()),
+  compare: (argv) => runCompare(compareTargets(argv), argv, treeContext()),
   test: (argv) => runTest(positional(argv), argv, { ...measureContext(argv), inspect }),
   baseline: (argv) => runBaseline(positional(argv), argv),
   suppressions: (argv) => runSuppressions(positional(argv), argv),
@@ -338,7 +338,7 @@ export const main = async (argv: readonly string[]): Promise<number> => {
   }
   // 知らないジャンルではどの rule も当たらず、知らない文書の種類では種類の知識が外れる。どちらも素通りに見えるので、何かする前に止める。
   const config = readConfig();
-  const problems = settingProblems(first, flag(argv, "--genre"), config, hostText(config));
+  const problems = settingProblems(first, flag(argv, "--genre"), config, hostText(config), hostLanguage(config.language, process.env));
   problems.forEach((problem) => console.error(problem));
   if (problems.length > 0) return 1;
   const handler = HANDLERS[first];