chaffjs 0.17.0 → 0.19.0

package/src/cli.ts

@@ -1,17 +1,17 @@
-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 { limitsFor } from "./config/style.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 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";
@@ -19,8 +19,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,27 +28,32 @@ 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 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 { 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";
+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)];
 
-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 =
@@ -58,10 +63,9 @@ 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(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 +88,29 @@ type Inspected = {
   readonly genre: string;
   readonly outcome: FileOutcome;
   readonly perFile: PerFile;
-  readonly all: readonly string[];
+  readonly checked: Omit<Checked, "conditions">;
+  /** 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 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,
@@ -108,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,
@@ -115,8 +129,9 @@ 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 },
-    all: applied.kept.map((finding) => fingerprint(path, finding)),
+    perFile: { path, suppressed: applied.suppressed, reasonless: applied.unusedReasonless, notRun },
+    checked: { findings: split.fresh, rules, language, genre, skipped: raw.skipped },
+    kept: applied.kept,
   };
 };
 
@@ -124,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 言語が混ざるため。
@@ -133,14 +148,12 @@ 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 の出力は汚さない。 */
-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 => {
@@ -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,13 +219,12 @@ 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);
   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,90 +233,81 @@ 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, 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;
   }
   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"));
   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"])));
-  console.log(
-    renderSuppressions(
-      results.map((result) => result.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));
 
-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[], written: Config): number => {
+  const config = withExperimental(written, 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;
 };
 
-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,
-  rules: (argv) => showRules(flag(argv, "--genre")),
-  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()),
-  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();
+  genres: (_argv, config) => showGenres(config),
+  rules: showRules,
+  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 problems = settingProblems(first, flag(argv, "--genre"), config, hostText(config));
+  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

@@ -0,0 +1,73 @@
+import { readMarkdown } from "../markdown-read.ts";
+import { isMarkdownPath } from "../structure/markdown-path.ts";
+import { uiLanguageOf } from "../ui.ts";
+import { ATOM_KINDS, isAtomKind, type AtomKind } from "../compare/atom.ts";
+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 { 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"]);
+
+export const compareTargets = (argv: readonly string[]): string[] =>
+  argv.slice(1).filter((arg, index, all) => !arg.startsWith("--") && !VALUED.has(all[index - 1] ?? ""));
+
+/** Every value given to a repeatable option, split at commas: `--allow-dropped url,code --allow-dropped quote`. */
+const optionValues = (argv: readonly string[], name: string): string[] =>
+  argv.flatMap((arg, index) => (arg === name ? (argv[index + 1] ?? "").split(",") : [])).filter((value) => value !== "");
+
+type ParsedAllowed = { readonly allowed: Allowed } | { readonly unknown: string };
+
+/** The kinds allowed to be dropped and added, or the first word that is not a kind. */
+const parseAllowed = (argv: readonly string[]): ParsedAllowed => {
+  const dropped = optionValues(argv, "--allow-dropped");
+  const added = optionValues(argv, "--allow-added");
+  const unknown = [...dropped, ...added].find((kind) => !isAtomKind(kind));
+  if (unknown !== undefined) return { unknown };
+  const kinds = (values: readonly string[]): Set<AtomKind> => new Set(values.filter(isAtomKind));
+  return { allowed: { dropped: kinds(dropped), added: kinds(added) } };
+};
+
+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. */
+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 => {
+  if (argv.includes("--json")) return (outcome) => renderJson(outcome);
+  return argv.includes("--compact") ? renderCompact : 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"];
+  const [beforePath, afterPath] = targets;
+  if (beforePath === undefined || afterPath === undefined || targets.length !== 2) {
+    console.error(host.usage);
+    return 1;
+  }
+  const parsed = parseAllowed(argv);
+  if ("unknown" in parsed) {
+    console.error(host.unknownKind(parsed.unknown, ATOM_KINDS.join(", ")));
+    return 1;
+  }
+  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, 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

@@ -1,14 +1,15 @@
-import { plainSource } from "../plain-source.ts";
-import { readFile } from "node:fs/promises";
 import { loadAdapter } from "../adapter-load.ts";
 import { applyByPath } from "../config/by-path.ts";
 import { buildDocument, teamRules } from "../document.ts";
 import { guessLanguage } from "../detect.ts";
-import { collectTargets } from "../files.ts";
-import { loadRules } from "../rule-load.ts";
+import { collectTargets, readDocumentFile } from "../files.ts";
+import { rulesOf } from "../custom/load.ts";
 import { evaluate } from "../eval.ts";
 import { renderEval } from "../render/eval.ts";
-import { neededBy } from "../run.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";
@@ -28,6 +29,16 @@ const TEXT: Texts<{
   },
 };
 
+/**
+ * What the adapter must prepare. eval measures a rule whatever its level, so a rule named with --rule gets the tags and the
+ * token features it reads even when lint would not run it; without --rule, the tags are what lint would prepare.
+ */
+const evalNeeds = (rules: readonly RuleDefinition[], only: string | undefined, config: Config, genre: string, language: string): AdapterNeeds => {
+  const measured = rules.filter((rule) => only === undefined || rule.id === only);
+  const lint = neededBy(rules, config.rules, config.experimental, genre, language);
+  return { pos: lint.pos || (only !== undefined && measured.some(wantsTags)), features: tokenFeaturesOf(measured) };
+};
+
 export type Context = {
   readonly config: Config;
   readonly resolveGenre: (path: string, source: string, config: Config) => { genre: string; from: string };
@@ -51,12 +62,12 @@ export const runEval = async (targets: readonly string[], argv: readonly string[
   const only = flag(argv, "--rule");
   const docs = await Promise.all(
     paths.map(async (path) => {
-      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 } = resolveGenre(path, source, config);
-      await adapter.prepare?.(neededBy(loadRules(language), config.rules, config.experimental, genre, language));
-      return { doc: buildDocument(path, source, adapter, teamRules(config), profileFor(config, path, source, language, genre)), language, genre };
+      await adapter.prepare?.(evalNeeds(rulesOf(language, config), only, config, genre, language));
+      return { doc: buildDocument(path, source, adapter, teamRules(config, language), profileFor(config, path, source, language, genre)), language, genre };
     }),
   );
   const language = docs[0]?.language ?? "ja";
@@ -67,7 +78,7 @@ export const runEval = async (targets: readonly string[], argv: readonly string[
     console.error(TEXT[ui].mixed([...mixed].join(", ")));
     return 1;
   }
-  const rules = loadRules(language).filter((rule) => only === undefined || rule.id === only);
+  const rules = rulesOf(language, config).filter((rule) => only === undefined || rule.id === only);
   if (rules.length === 0) {
     console.error(TEXT[ui].unknownRule(only ?? CLI_TEXT[ui].unnamed));
     return 1;
@@ -79,7 +90,8 @@ export const runEval = async (targets: readonly string[], argv: readonly string[
         rules,
         genre,
         language,
-        config.limits,
+        limitsFor(config, language),
+        optionLayersOf(config),
       ),
       docs.length,
       paths.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;
+};