chaffjs 0.18.0 → 0.19.0

package/src/cli-text.ts

@@ -22,6 +22,9 @@ const USAGE_JA = `chaff — 文章の読みにくいところを見つけます
   chaff tree <file> [--format sexp|json]  文書を番地の付いた木にする（条・項・定義・参照）
   chaff cite <原文> <引用.json>           回答の引用（番地と引用文）が原文にあるかを確かめる
   chaff compare <前> <後>                書き換えで事実（数・日付・URL・コード・名前・引用…）が落ちても足されてもいないかを確かめる
+  chaff facts <file>                     compare が照合する事実を、書き直す前の控えとして一覧にする
+  chaff outline <file> [<後>]            見出しの構成と形（見出しの数・節の平均の長さ・箇条書きの割合・太字）を測る。2 つなら前と後を並べる
+  chaff fix-plan <file> [--json]         指摘をルールごとにまとめ、直す方向と確かめのコマンドを、書き直す人や AI 向けの計画にする（何も送らない）
   chaff rules                    ルールの一覧を、グループごとに表で出す（いまの段階つき）
   chaff rules --json             いまの設定とルールの説明を JSON で出す（AI に渡す用）
   chaff baseline <dir>           いまある指摘を棚上げする（既存の repo に入れるとき）
@@ -58,6 +61,9 @@ const USAGE_EN = `chaff — finds what makes writing hard to read. It never rewr
   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 compare <before> <after>          check that a rewrite dropped no fact and added none (numbers, dates, URLs, code, names, quotations…)
+  chaff facts <file>                      list the facts compare checks, as an inventory to keep before a rewrite
+  chaff outline <file> [<after>]          measure the outline and its shape (headings, average section length, text in lists, bold); two files side by side
+  chaff fix-plan <file> [--json]          a plan for whoever rewrites the file, a person or an AI: findings by rule, how to rewrite each, the checks to run after (sends nothing)
   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)
@@ -104,7 +110,6 @@ export type CliText = {
   readonly watching: (files: number, findings: number) => string;
   readonly watchHint: string;
   readonly baselineDone: (files: number, entries: number, file: string) => readonly string[];
-  readonly unit: (ruleId: string, language: string) => string;
 };
 
 export const CLI_TEXT: Texts<CliText> = {
@@ -159,11 +164,6 @@ export const CLI_TEXT: Texts<CliText> = {
       `  ${file} を commit してください。`,
       "",
     ],
-    unit: (ruleId, language) => {
-      if (ruleId === "bold-density") return "1000 字あたりの箇所数";
-      if (ruleId !== "max-sentence-length") return "回";
-      return language === "ja" ? "文字" : "語";
-    },
   },
   en: {
     usage: USAGE_EN,
@@ -213,10 +213,5 @@ export const CLI_TEXT: Texts<CliText> = {
       `  Commit ${file}.`,
       "",
     ],
-    unit: (ruleId, language) => {
-      if (ruleId === "bold-density") return "places per 1000 characters";
-      if (ruleId !== "max-sentence-length") return "times";
-      return language === "ja" ? "characters" : "words";
-    },
   },
 };

package/src/cli.ts

@@ -3,13 +3,15 @@ import { dirname, join } from "node:path";
 import { loadAdapter, packageFor } from "./adapter-load.ts";
 import { CONFIG_FILE, type Config } from "./config/load.ts";
 import { applyByPath } from "./config/by-path.ts";
+import { limitsFor } from "./config/style.ts";
 import { applyLevel } from "./config/write.ts";
 import { buildDocument, teamRules } from "./document.ts";
 import { guessLanguage } from "./detect.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 type { PerFile } from "./render/suppressions.ts";
+import { runSuppressions } from "./commands/suppressions.ts";
 import { clock, describeChange, snapshotOf, watchPaths, type Snapshot } from "./watch.ts";
 import { runEval } from "./commands/eval.ts";
 import { runTest } from "./commands/test.ts";
@@ -29,11 +31,11 @@ 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 type { TreeContext } from "./commands/tree.ts";
+import { DOCUMENT_COMMANDS } from "./commands/document-commands.ts";
 import { runSkill } from "./commands/skill.ts";
-import { runFeedback, settingsOf } from "./commands/feedback.ts";
+import { fixPlanTargets, runFixPlan } from "./commands/fix-plan.ts";
+import { runConditions, runFeedback, settingsOf, type Checked } from "./commands/feedback.ts";
 import { homedir } from "node:os";
 import { settingWarnings } from "./config/warnings.ts";
 import { readConfigIn } from "./config/read.ts";
@@ -44,7 +46,9 @@ 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";
+import { notRunAmong } from "./not-run.ts";
 import { settingProblems } from "./setting-problems.ts";
+import { withExtensions } from "./extension/load.ts";
 
 /** Text for output that is not about one document. */
 const hostText = (config: Config): CliText => CLI_TEXT[hostLanguage(config.language, process.env)];
@@ -59,8 +63,7 @@ const genreFrom =
 
 const findRule = (rules: readonly RuleDefinition[], id: string | undefined): RuleDefinition | undefined => rules.find((rule) => rule.id === id);
 
-const changeSetting = (command: Level, ruleId: string | undefined, why: string | undefined): number => {
-  const config = readConfig();
+const changeSetting = (config: Config, command: Level, ruleId: string | undefined, why: string | undefined): number => {
   const language = config.language ?? hostLanguage(undefined, process.env);
   const rule = findRule(rulesOf(language, config), ruleId);
   if (rule === undefined) {
@@ -85,6 +88,7 @@ type Inspected = {
   readonly genre: string;
   readonly outcome: FileOutcome;
   readonly perFile: PerFile;
+  readonly checked: Omit<Checked, "conditions">;
   /** stet で黙らせたものを除いた、baseline で棚上げする前の指摘。fingerprint は baseline を書くときだけ作る。 */
   readonly kept: readonly Finding[];
 };
@@ -98,8 +102,15 @@ const inspect = async (path: string, config: Config, argv: readonly string[]): P
   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 = runRulesWith(doc, rules, { settings: config.rules, experimental, genre, limits: config.limits, optionLayers: optionLayersOf(config) });
+  const doc = buildDocument(path, source, adapter, teamRules(config, language), profileFor(config, path, source, language, genre));
+  const raw = runRulesWith(doc, rules, {
+    settings: config.rules,
+    experimental,
+    genre,
+    limits: limitsFor(config, language),
+    optionLayers: optionLayersOf(config),
+    detectors: config.extensions?.detectors ?? {},
+  });
   // 応答は 3 つ。stet で黙らせたものは、ここで落とす。
   const applied = applySuppressions(
     source,
@@ -110,6 +121,7 @@ const inspect = async (path: string, config: Config, argv: readonly string[]): P
   const split = splitByBaseline(path, applied.kept, baseline);
   const result = { ...raw, findings: split.fresh };
   const { header, notes } = fileHeader(path, source, language, { genre, from, unread }, { shelved: split.shelved, hushed: applied.suppressed.length });
+  const notRun = notRunAmong(applied.named, raw.skipped);
   const text = argv.includes("--compact") ? renderCompact(header, result, rules, language) : renderFriendly(header, result, rules, language, notes);
   return {
     text,
@@ -117,7 +129,8 @@ const inspect = async (path: string, config: Config, argv: readonly string[]): P
     language,
     genre,
     outcome: { path, findings: split.fresh, notRun: raw.skipped.length },
-    perFile: { path, suppressed: applied.suppressed, reasonless: applied.unusedReasonless },
+    perFile: { path, suppressed: applied.suppressed, reasonless: applied.unusedReasonless, notRun },
+    checked: { findings: split.fresh, rules, language, genre, skipped: raw.skipped },
     kept: applied.kept,
   };
 };
@@ -126,7 +139,7 @@ const inspect = async (path: string, config: Config, argv: readonly string[]): P
  * 指摘を PR の変更行に出すための出口。--sarif <path> を書いたときだけ作る。
  * 端末の出力は変えない。CI で上げるためのファイルが増えるだけ。
  */
-const writeSarif = (results: readonly Inspected[], argv: readonly string[]): void => {
+const writeSarif = (results: readonly Inspected[], argv: readonly string[], config: Config): void => {
   const path = flag(argv, "--sarif");
   if (path === undefined) return;
   // 文言はファイルの言語で描く。by_path で 1 つの repo に 2 言語が混ざるため。
@@ -135,7 +148,7 @@ const writeSarif = (results: readonly Inspected[], argv: readonly string[]): voi
   );
   mkdirSync(dirname(path), { recursive: true });
   writeFileSync(path, renderSarif(located, VERSION), "utf8");
-  console.log(hostText(readConfig()).sarifWritten(path, located.length));
+  console.log(hostText(config).sarifWritten(path, located.length));
 };
 
 /** 効いていない設定は、結果の前に一度だけ言う。標準エラーに出すので、JSON や SARIF の出力は汚さない。 */
@@ -148,9 +161,8 @@ const summaryLanguage = (results: readonly Inspected[], config: Config): UiLangu
   return sharedLanguage(languages, hostLanguage(config.language, process.env));
 };
 
-const lint = async (targets: readonly string[], argv: readonly string[]): Promise<number> => {
+const lint = async (targets: readonly string[], argv: readonly string[], config: Config): Promise<number> => {
   const paths = collectTargets(targets);
-  const config = readConfig();
   if (paths.length === 0) {
     // 0 件を成功にすると「CI は通っているが何も検証していない」状態が続く。§14。
     console.error(hostText(config).noMarkdown(targets.join(", ")));
@@ -163,7 +175,7 @@ const lint = async (targets: readonly string[], argv: readonly string[]): Promis
   }
   warnRuleProblems(config, language);
   const results = await Promise.all(paths.map((path) => inspect(path, config, argv)));
-  writeSarif(results, argv);
+  writeSarif(results, argv, config);
   results.filter((result) => result.outcome.findings.length > 0 || paths.length === 1).forEach((result) => console.log(result.text));
   renderSummary(
     results.map((result) => result.outcome),
@@ -176,9 +188,8 @@ const lint = async (targets: readonly string[], argv: readonly string[]): Promis
  * 書いている最中は、全件を出し直されても何が変わったのか分からない。
  * 差分だけを出す。workflow spec §11。
  */
-const runWatch = async (targets: readonly string[], argv: readonly string[]): Promise<number> => {
+const runWatch = async (targets: readonly string[], argv: readonly string[], config: Config): Promise<number> => {
   const paths = collectTargets(targets);
-  const config = readConfig();
   const text = hostText(config);
   if (paths.length === 0) {
     console.error(text.noMarkdown(targets.join(", ")));
@@ -208,8 +219,7 @@ const runWatch = async (targets: readonly string[], argv: readonly string[]): Pr
 };
 
 /** genreFlag: --genre, which wins over chaff.yaml's genre here as it does in a run. */
-const explain = (ruleId: string | undefined, genreFlag: string | undefined): number => {
-  const config = readConfig();
+const explain = (config: Config, ruleId: string | undefined, genreFlag: string | undefined): number => {
   const genre = genreFlag ?? config.genre;
   // 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);
@@ -223,13 +233,12 @@ 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, settingSourcesOf(config, rule.id)));
+  console.log(renderExplain(rule, current, language, genre, settingSourcesOf(config, rule.id, language)));
   return 0;
 };
 
-const runBaseline = async (targets: readonly string[], argv: readonly string[]): Promise<number> => {
+const runBaseline = async (targets: readonly string[], argv: readonly string[], config: Config): Promise<number> => {
   const paths = collectTargets(targets.length > 0 ? targets : ["."]);
-  const config = readConfig();
   if (paths.length === 0) {
     console.error(hostText(config).noMarkdownHere);
     return 1;
@@ -242,23 +251,18 @@ const runBaseline = async (targets: readonly string[], argv: readonly string[]):
   return 0;
 };
 
-const runSuppressions = async (targets: readonly string[], argv: readonly string[]): Promise<number> => {
-  const paths = collectTargets(targets.length > 0 ? targets : ["."]);
-  const config = readConfig();
-  const results = await Promise.all(paths.map((path) => inspect(path, config, [...argv, "--show-baseline"])));
-  const perFile = results.map((result) => result.perFile);
-  console.log(renderSuppressions(perFile, hostLanguage(config.language, process.env)));
-  return 0;
-};
+/** A file's findings, shelved ones included: commands that look findings up are not asking what is new. */
+const inspectAll = (config: Config, argv: readonly string[]) => (path: string) => inspect(path, config, [...argv, "--show-baseline"]);
 
-type Handler = (argv: readonly string[]) => number | Promise<number>;
+/** A subcommand, given the command line and chaff.yaml as read once, with the code it names loaded. */
+type Handler = (argv: readonly string[], config: Config) => number | Promise<number>;
 
 /** `--` で始まらない引数。対象のパス。 */
 const positional = (argv: readonly string[]): string[] => targetsOf(argv.slice(1));
 
 /** `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 showRules = (argv: readonly string[], written: Config): number => {
+  const config = withExperimental(written, argv);
   const language = config.language ?? hostLanguage(undefined, process.env);
   warnRuleProblems(config, language);
   const genre = flag(argv, "--genre") ?? config.genre ?? "blog/tech";
@@ -267,46 +271,43 @@ const showRules = (argv: readonly string[]): number => {
   return 0;
 };
 
-const showGenres = (): number => {
-  console.log(renderGenres(loadGenres(), hostLanguage(readConfig().language, process.env)));
+const showGenres = (config: Config): number => {
+  console.log(renderGenres(loadGenres(), hostLanguage(config.language, process.env)));
   return 0;
 };
 
-const treeContext = (): TreeContext => {
-  const config = readConfig();
+const treeContext = (config: Config): TreeContext => {
   return { config, flag, ui: hostLanguage(config.language, process.env) };
 };
 
 /** What eval and test share: the settings, this run's genre, and the language for what is not about one document. */
-const measureContext = (argv: readonly string[]): { config: Config; resolveGenre: ReturnType<typeof genreFrom>; ui: UiLanguage } => {
-  const config = readConfig();
+const measureContext = (argv: readonly string[], config: Config): { config: Config; resolveGenre: ReturnType<typeof genreFrom>; ui: UiLanguage } => {
   return { config, resolveGenre: genreFrom(argv), ui: hostLanguage(config.language, process.env) };
 };
 
 /** 分岐を数珠つなぎにせず表にする。足すときに main を太らせない。 */
 const HANDLERS: Readonly<Record<string, Handler>> = {
-  init: async (argv) => {
-    const ui = hostLanguage(readConfig().language, process.env);
+  init: async (argv, config) => {
+    const ui = hostLanguage(config.language, process.env);
     const chosen = await initGenre(flag(argv, "--genre"), ui, process.cwd());
     if ("error" in chosen) console.error(chosen.error);
     else runInit(process.cwd(), chosen.genre, ui).forEach((line) => console.log(line));
     return "error" in chosen ? 1 : 0;
   },
-  genres: showGenres,
+  genres: (_argv, config) => showGenres(config),
   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),
-  relax: (argv) => changeSetting("relaxed", argv[1], flag(argv, "--why")),
-  strict: (argv) => changeSetting("strict", argv[1], flag(argv, "--why")),
-  off: (argv) => changeSetting("off", argv[1], flag(argv, "--why")),
-  feedback: (argv) => {
-    const config = readConfig();
+  explain: (argv, config) => explain(config, argv[1], flag(argv, "--genre")),
+  eval: (argv, config) => runEval(positional(argv), argv, { ...measureContext(argv, config), flag }),
+  ...Object.fromEntries(Object.entries(DOCUMENT_COMMANDS).map(([name, run]): [string, Handler] => [name, (argv, config) => run(argv, treeContext(config))])),
+  test: (argv, config) => runTest(positional(argv), argv, { ...measureContext(argv, config), inspect }),
+  "fix-plan": (argv, config) =>
+    runFixPlan(fixPlanTargets(argv), argv, { ...treeContext(config), check: async (path) => (await inspectAll(config, argv)(path)).checked }),
+  baseline: (argv, config) => runBaseline(positional(argv), argv, config),
+  suppressions: (argv, config) => runSuppressions(positional(argv), inspectAll(config, argv), hostLanguage(config.language, process.env)),
+  relax: (argv, config) => changeSetting(config, "relaxed", argv[1], flag(argv, "--why")),
+  strict: (argv, config) => changeSetting(config, "strict", argv[1], flag(argv, "--why")),
+  off: (argv, config) => changeSetting(config, "off", argv[1], flag(argv, "--why")),
+  feedback: (argv, config) => {
     return runFeedback(positional(argv), argv, {
       cwd: process.cwd(),
       ui: hostLanguage(config.language, process.env),
@@ -314,13 +315,13 @@ const HANDLERS: Readonly<Record<string, Handler>> = {
       runtime: `Node ${process.version} · ${process.platform} ${process.arch}`,
       flag,
       settingsOf: (ruleIds) => settingsOf(config, ruleIds),
-      check: async (path) => {
-        const inspected = await inspect(path, config, [...argv, "--show-baseline"]);
-        return { findings: inspected.outcome.findings, rules: inspected.rules, language: inspected.language, genre: inspected.genre };
-      },
+      check: async (path) => ({
+        ...(await inspectAll(config, argv)(path)).checked,
+        conditions: runConditions(argv, flag(argv, "--genre"), config.experimental),
+      }),
     });
   },
-  skill: (argv) => runSkill(argv, { cwd: process.cwd(), home: homedir(), ui: hostLanguage(readConfig().language, process.env) }),
+  skill: (argv, config) => runSkill(argv, { cwd: process.cwd(), home: homedir(), ui: hostLanguage(config.language, process.env) }),
 };
 
 /** Every subcommand. Anything else on the command line is a file to check. */
@@ -337,12 +338,12 @@ export const main = async (argv: readonly string[]): Promise<number> => {
     return 0;
   }
   // 知らないジャンルではどの rule も当たらず、知らない文書の種類では種類の知識が外れる。どちらも素通りに見えるので、何かする前に止める。
-  const config = readConfig();
+  const config = await withExtensions(readConfig());
   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];
-  if (handler !== undefined) return handler(argv);
+  if (handler !== undefined) return handler(argv, config);
   const targets = targetsOf(first === "lint" ? argv.slice(1) : argv);
-  return argv.includes("--watch") ? runWatch(targets, argv) : lint(targets, argv);
+  return argv.includes("--watch") ? runWatch(targets, argv, config) : lint(targets, argv, config);
 };

package/src/closing-paragraph.ts

@@ -0,0 +1,24 @@
+import type { Paragraph, Section, Sentence } from "./plugin.ts";
+
+/**
+ * 結びとして読む、最後の節の終わりの段落の数。決まり文句の後ろに一言や追記が続く結び（「いかがでしたか。」→ 感想 → 「よいお年を！」）は
+ * 人の書いた記事に多く、最後の段落だけでは取りこぼす。
+ */
+const CLOSING_PARAGRAPHS = 4;
+
+/** 文書の最初の段落は書き出しで、結びではない（冒頭の「簡単にまとめると、」）。段落が一つだけなら、それが結びでもある。 */
+const isOpening = (paragraphs: readonly Paragraph[], paragraph: Paragraph): boolean => paragraphs.length > 1 && paragraphs[0] === paragraph;
+
+/**
+ * 結びの文。最後の節の終わりの段落で、書き出しの段落でないもの。見出しの無い文書は本文全体が一つの節なので、節だけで切ると冒頭の
+ * 「まとめると」や、長い書き起こしの途中の問いかけまで結びになる。箇条書きは段落に数えない。
+ */
+export const closingSentences = (sections: readonly Pick<Section, "span">[], paragraphs: readonly Paragraph[]): readonly Sentence[] => {
+  const last = sections.at(-1);
+  if (last === undefined) return [];
+  return paragraphs
+    .filter((paragraph) => paragraph.span.start >= last.span.start && paragraph.span.start < last.span.end)
+    .slice(-CLOSING_PARAGRAPHS)
+    .filter((paragraph) => !isOpening(paragraphs, paragraph))
+    .flatMap((paragraph) => paragraph.sentences);
+};

package/src/commands/compare.ts

@@ -1,8 +1,4 @@
-import { loadAdapter } from "../adapter-load.ts";
-import { buildDocument, teamRules } from "../document.ts";
 import { readMarkdown } from "../markdown-read.ts";
-import { profileFor } from "../profile/for-file.ts";
-import { resolveGenre } from "../resolve-genre.ts";
 import { isMarkdownPath } from "../structure/markdown-path.ts";
 import { uiLanguageOf } from "../ui.ts";
 import { ATOM_KINDS, isAtomKind, type AtomKind } from "../compare/atom.ts";
@@ -10,7 +6,8 @@ import { extractFacts } from "../compare/extract.ts";
 import { outcomeOf, type Allowed, type Compared } from "../compare/outcome.ts";
 import { renderCompact, renderFriendly, renderJson } from "../compare/render.ts";
 import { COMPARE_TEXT } from "../compare/text.ts";
-import { readSource, treeLanguage, type TreeContext } from "./tree.ts";
+import { readDocument } from "./read-document.ts";
+import type { TreeContext } from "./tree.ts";
 
 /** Options whose value is the next argument. That value is not a file. */
 const VALUED: ReadonlySet<string> = new Set(["--language", "--genre", "--allow-dropped", "--allow-added"]);
@@ -34,20 +31,15 @@ const parseAllowed = (argv: readonly string[]): ParsedAllowed => {
   return { allowed: { dropped: kinds(dropped), added: kinds(added) } };
 };
 
-type Read = Compared & { readonly language: string };
+export type DocumentFacts = Compared & { readonly language: string };
 
 /** One document's facts, read as lint reads it: its language, the team's names, and the parts of speech. */
-const readFacts = async (path: string, argv: readonly string[], context: TreeContext): Promise<Read | undefined> => {
-  const source = await readSource(path, context);
-  if (source === undefined) return undefined;
-  const language = treeLanguage(path, source, argv, context);
-  const adapter = await loadAdapter(language);
-  await adapter.prepare?.({ pos: true });
-  const genre = resolveGenre(path, source, context.config, context.flag(argv, "--genre")).genre;
-  const doc = buildDocument(path, source, adapter, teamRules(context.config), profileFor(context.config, path, source, language, genre));
-  const root = isMarkdownPath(path) ? readMarkdown(doc.source).root : undefined;
-  const extraction = extractFacts({ doc, root, structure: adapter.structure, names: context.config.names ?? [] });
-  return { path, extraction, language };
+export const readFacts = async (path: string, argv: readonly string[], context: TreeContext): Promise<DocumentFacts | undefined> => {
+  const prose = await readDocument(path, argv, context, true);
+  if (prose === undefined) return undefined;
+  const root = isMarkdownPath(path) ? readMarkdown(prose.doc.source).root : undefined;
+  const extraction = extractFacts({ doc: prose.doc, root, structure: prose.structure, names: context.config.names ?? [] });
+  return { path, extraction, language: prose.language };
 };
 
 const renderFor = (argv: readonly string[]): typeof renderFriendly => {
@@ -58,6 +50,7 @@ const renderFor = (argv: readonly string[]): typeof renderFriendly => {
 /**
  * Whether a rewrite kept every fact: numbers, dates, URLs, code, names, quotations, headings, references and footnotes.
  * Compares; never rewrites. Ends with 1 when a fact was dropped or added, so a rewrite can be checked like a test.
+ * --distinct counts a fact as kept when the other document states it at least once.
  */
 export const runCompare = async (targets: readonly string[], argv: readonly string[], context: TreeContext): Promise<number> => {
   const host = COMPARE_TEXT[context.ui ?? "ja"];
@@ -74,7 +67,7 @@ export const runCompare = async (targets: readonly string[], argv: readonly stri
   const before = await readFacts(beforePath, argv, context);
   const after = before === undefined ? undefined : await readFacts(afterPath, argv, context);
   if (before === undefined || after === undefined) return 1;
-  const outcome = outcomeOf(before, after, parsed.allowed);
+  const outcome = outcomeOf(before, after, parsed.allowed, argv.includes("--distinct") ? "distinct" : "as-stated");
   console.log(renderFor(argv)(outcome, COMPARE_TEXT[uiLanguageOf(before.language)]));
   return outcome.ok ? 0 : 1;
 };

package/src/commands/document-commands.ts

@@ -0,0 +1,19 @@
+import { citeTargets, runCite } from "./cite.ts";
+import { compareTargets, runCompare } from "./compare.ts";
+import { factsTargets, runFacts } from "./facts.ts";
+import { outlineTargets, runOutline } from "./outline.ts";
+import { runTree, treeTargets, type TreeContext } from "./tree.ts";
+
+type DocumentCommand = (argv: readonly string[], context: TreeContext) => Promise<number>;
+
+/**
+ * The commands that read one or two documents and report on them without linting: the tree, quotations, facts and
+ * outline. Each is given the settings the command line read once.
+ */
+export const DOCUMENT_COMMANDS: Readonly<Record<string, DocumentCommand>> = {
+  tree: (argv, context) => runTree(treeTargets(argv), argv, context),
+  cite: (argv, context) => runCite(citeTargets(argv), argv, context),
+  compare: (argv, context) => runCompare(compareTargets(argv), argv, context),
+  facts: (argv, context) => runFacts(factsTargets(argv), argv, context),
+  outline: (argv, context) => runOutline(outlineTargets(argv), argv, context),
+};

package/src/commands/eval.ts

@@ -9,6 +9,7 @@ import { renderEval } from "../render/eval.ts";
 import { neededBy, tokenFeaturesOf, wantsTags } from "../run.ts";
 import type { AdapterNeeds, RuleDefinition } from "../plugin.ts";
 import { optionLayersOf } from "../config/option-problems.ts";
+import { limitsFor } from "../config/style.ts";
 import type { Config } from "../config/load.ts";
 import { profileFor } from "../profile/for-file.ts";
 import { CLI_TEXT } from "../cli-text.ts";
@@ -66,7 +67,7 @@ export const runEval = async (targets: readonly string[], argv: readonly string[
       const adapter = await loadAdapter(language);
       const { genre } = resolveGenre(path, source, config);
       await adapter.prepare?.(evalNeeds(rulesOf(language, config), only, config, genre, language));
-      return { doc: buildDocument(path, source, adapter, teamRules(config), profileFor(config, path, source, language, genre)), language, genre };
+      return { doc: buildDocument(path, source, adapter, teamRules(config, language), profileFor(config, path, source, language, genre)), language, genre };
     }),
   );
   const language = docs[0]?.language ?? "ja";
@@ -89,7 +90,7 @@ export const runEval = async (targets: readonly string[], argv: readonly string[
         rules,
         genre,
         language,
-        config.limits,
+        limitsFor(config, language),
         optionLayersOf(config),
       ),
       docs.length,

package/src/commands/facts.ts

@@ -0,0 +1,33 @@
+import { uiLanguageOf } from "../ui.ts";
+import { FACTS_TEXT } from "../compare/facts-text.ts";
+import { renderFactsCompact, renderFactsFriendly, renderFactsJson, type FactList } from "../compare/facts-render.ts";
+import { readFacts } from "./compare.ts";
+import type { TreeContext } from "./tree.ts";
+
+/** Options whose value is the next argument. That value is not a file. */
+const VALUED: ReadonlySet<string> = new Set(["--language", "--genre"]);
+
+export const factsTargets = (argv: readonly string[]): string[] =>
+  argv.slice(1).filter((arg, index, all) => !arg.startsWith("--") && !VALUED.has(all[index - 1] ?? ""));
+
+const renderFor = (argv: readonly string[], list: FactList): string => {
+  const text = FACTS_TEXT[uiLanguageOf(list.language)];
+  if (argv.includes("--json")) return renderFactsJson(list);
+  return argv.includes("--compact") ? renderFactsCompact(list, text) : renderFactsFriendly(list, text);
+};
+
+/**
+ * The facts `chaff compare` would check in one document, listed before a rewrite: the inventory a full rewrite
+ * starts from. Read by compare's own extractor, so the list is exactly what compare holds the rewrite to.
+ */
+export const runFacts = async (targets: readonly string[], argv: readonly string[], context: TreeContext): Promise<number> => {
+  const [path] = targets;
+  if (path === undefined || targets.length !== 1) {
+    console.error(FACTS_TEXT[context.ui ?? "ja"].usage);
+    return 1;
+  }
+  const documentFacts = await readFacts(path, argv, context);
+  if (documentFacts === undefined) return 1;
+  console.log(renderFor(argv, documentFacts));
+  return 0;
+};

package/src/commands/feedback.ts

@@ -7,6 +7,8 @@ import { messageOf } from "../render/text.ts";
 import type { Texts, UiLanguage } from "../ui.ts";
 import { excerptsAround } from "../feedback/excerpt.ts";
 import { feedbackDraft, type FeedbackDraft, type FeedbackKind, type ReportedFinding } from "../feedback/draft.ts";
+import { notRunAmong } from "../not-run.ts";
+import type { Skipped } from "../run.ts";
 
 export const FEEDBACK_FILE = ".chaff-feedback.md";
 const NEW_ISSUE = "https://github.com/isamu/lab/issues/new";
@@ -18,6 +20,10 @@ export type Checked = {
   readonly rules: readonly RuleDefinition[];
   readonly language: string;
   readonly genre: string;
+  /** The rules this check did not run, and why. */
+  readonly skipped: readonly Skipped[];
+  /** How the check was run, as the reader of a report would repeat it (runConditions). */
+  readonly conditions: readonly string[];
 };
 
 export type FeedbackContext = {
@@ -36,6 +42,8 @@ const TEXT: Texts<{
   readonly notFound: (path: string) => string;
   readonly badLine: (lines: number) => string;
   readonly noMatch: (list: string) => string;
+  readonly notRun: (rule: string, why: string) => string;
+  readonly runExperimental: string;
   readonly several: (list: string) => string;
   readonly none: string;
   readonly written: (file: string, lines: string) => string;
@@ -51,6 +59,8 @@ const TEXT: Texts<{
     notFound: (path) => `${path} がありません。`,
     badLine: (lines) => `--line には 1〜${String(lines)} の行番号を書いてください。`,
     noMatch: (list) => `その指摘が見つかりません。この文書の指摘:\n${list}`,
+    notRun: (rule, why) => `${rule} は今回動いていません（${why}）。`,
+    runExperimental: "試験中の rule です。--experimental を付けてかけ直してください。",
     several: (list) => `その rule の指摘がいくつもあります。--line で一つ選んでください:\n${list}`,
     none: "  （指摘はありません）",
     written: (file, lines) => `報告の下書きを ${file} に書きました。文書から載せたのは ${lines} だけです。送る前に読んで、要らない所は消してください。`,
@@ -66,6 +76,8 @@ const TEXT: Texts<{
     notFound: (path) => `${path} does not exist.`,
     badLine: (lines) => `--line must be a line number from 1 to ${String(lines)}.`,
     noMatch: (list) => `No such finding. The findings in this document:\n${list}`,
+    notRun: (rule, why) => `${rule} did not run in this check (${why}).`,
+    runExperimental: "It is experimental: run again with --experimental.",
     several: (list) => `That rule has several findings here. Pick one with --line:\n${list}`,
     none: "  (no findings)",
     written: (file, lines) =>
@@ -157,13 +169,32 @@ const sendInstructions = (title: string, lines: readonly number[], ui: UiLanguag
   ].join("\n");
 };
 
+/**
+ * Pure: how a check was run, in the words a reader would type to run it again: the flags that change what is found.
+ * Experimental rules switched on in chaff.yaml count too, said as chaff.yaml says it.
+ */
+export const runConditions = (argv: readonly string[], genreFlag: string | undefined, experimentalInConfig: boolean): string[] => {
+  const experimental = argv.includes("--experimental") ? ["--experimental"] : [];
+  const fromConfig = experimental.length === 0 && experimentalInConfig ? ["experimental: true (chaff.yaml)"] : [];
+  return [...experimental, ...fromConfig, ...(genreFlag === undefined ? [] : [`--genre ${genreFlag}`])];
+};
+
+/** No finding matched: say so with the findings there are, and first why the asked-for rule did not run, if it did not. */
+const noMatch = (request: Request, checked: Checked, ui: UiLanguage): string => {
+  const text = TEXT[ui];
+  const list = text.noMatch(describe(checked.findings, text.none));
+  const [notRun] = request.rule === undefined ? [] : notRunAmong([request.rule], checked.skipped);
+  if (notRun === undefined) return list;
+  return [text.notRun(notRun.rule, notRun.why), ...(notRun.needsExperimental ? [text.runExperimental] : []), list].join("\n");
+};
+
 /** Why the request cannot be drafted, or the findings to report. */
 const pick = (request: Request, checked: Checked, lineCount: number, ui: UiLanguage): { readonly error: string } | { readonly findings: Finding[] } => {
   const text = TEXT[ui];
   if (request.line !== undefined && (request.line < 1 || request.line > lineCount)) return { error: text.badLine(lineCount) };
   const picked = chosen(checked.findings, request.rule, request.line);
   if (request.kind === "missed") return { findings: picked };
-  if (picked.length === 0) return { error: text.noMatch(describe(checked.findings, text.none)) };
+  if (picked.length === 0) return { error: noMatch(request, checked, ui) };
   // One finding per report: a rule picked alone could otherwise pull excerpts from all over the document.
   if (picked.length > 1) return { error: text.several(describe(picked, text.none)) };
   return { findings: picked };
@@ -204,6 +235,7 @@ export const runFeedback = async (targets: readonly string[], argv: readonly str
       fileName: basename(request.path),
       language: checked.language,
       genre: checked.genre,
+      conditions: checked.conditions,
       findings,
       line: lines[0] ?? 0,
       excerpts: excerptsAround(source, lines),