chaffjs 0.19.0 → 0.21.0

package/src/cli.ts

@@ -1,15 +1,11 @@
 import { mkdirSync, writeFileSync } from "node:fs";
 import { dirname, join } from "node:path";
-import { loadAdapter, packageFor } from "./adapter-load.ts";
+import { packageFor } from "./adapter-load.ts";
+import { checkSource, crossChecked, type SourceCheck } from "./check-source.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 type { PerFile } from "./render/suppressions.ts";
 import { runSuppressions } from "./commands/suppressions.ts";
 import { clock, describeChange, snapshotOf, watchPaths, type Snapshot } from "./watch.ts";
@@ -19,7 +15,7 @@ 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, withExperimental } from "./cli-args.ts";
+import { targetsOf, withExperimental, withIncludes } from "./cli-args.ts";
 import { rulesOf } from "./custom/load.ts";
 import { renderCompact } from "./render/compact.ts";
 import { renderExplain } from "./render/explain.ts";
@@ -33,7 +29,10 @@ import { renderSarif } from "./render/sarif.ts";
 import { VERSION, VERSION_LINES } from "./version.ts";
 import type { TreeContext } from "./commands/tree.ts";
 import { DOCUMENT_COMMANDS } from "./commands/document-commands.ts";
+import { asksForHelp } from "./command-help.ts";
+import { printCommandHelp } from "./commands/help.ts";
 import { runSkill } from "./commands/skill.ts";
+import { GRADE_EXIT, runGrade } from "./commands/grade.ts";
 import { fixPlanTargets, runFixPlan } from "./commands/fix-plan.ts";
 import { runConditions, runFeedback, settingsOf, type Checked } from "./commands/feedback.ts";
 import { homedir } from "node:os";
@@ -41,14 +40,16 @@ 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, 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";
+import { offOnlyAsExperimental } from "./experimental-alone.ts";
+import { DEFAULT_GENRE } from "./init-choice.ts";
+import { stoppingOnYamlFileError } from "./config/yaml-file.ts";
 
 /** Text for output that is not about one document. */
 const hostText = (config: Config): CliText => CLI_TEXT[hostLanguage(config.language, process.env)];
@@ -93,32 +94,18 @@ type Inspected = {
   readonly kept: readonly Finding[];
 };
 
-const inspect = async (path: string, config: Config, argv: readonly string[]): Promise<Inspected> => {
-  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 = rulesOf(language, config);
+const checkFile = async (path: string, config: Config, argv: readonly string[]): Promise<SourceCheck> => {
   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, 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,
-    raw.findings,
-    doc.sections.map((section) => section.span),
-  );
+  return checkSource(path, await readDocumentFile(path), config, { genre: flag(argv, "--genre"), experimental });
+};
+
+const present = (check: SourceCheck, argv: readonly string[]): Inspected => {
+  const { language, genre: resolved, rules, raw, applied } = check;
+  const { path, source } = check.doc;
+  const { genre, from, unread } = resolved;
+  if (unread !== undefined) console.error(`chaff: ${CLI_TEXT[uiLanguageOf(language)].unreadFrontMatterGenre(path, unread, GENRES)}`);
   const baseline = argv.includes("--show-baseline") ? undefined : readBaseline(join(process.cwd(), BASELINE_FILE));
-  const split = splitByBaseline(path, applied.kept, baseline);
+  const split = splitByBaseline(path, applied.kept, baseline, process.cwd());
   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);
@@ -135,6 +122,12 @@ const inspect = async (path: string, config: Config, argv: readonly string[]): P
   };
 };
 
+const inspect = async (path: string, config: Config, argv: readonly string[]): Promise<Inspected> => present(await checkFile(path, config, argv), argv);
+
+/** Every file of one run, with the rules that compare documents run over all of them. */
+const inspectRun = async (paths: readonly string[], config: Config, argv: readonly string[]): Promise<Inspected[]> =>
+  crossChecked(await Promise.all(paths.map((path) => checkFile(path, config, argv)))).map((check) => present(check, argv));
+
 /**
  * 指摘を PR の変更行に出すための出口。--sarif <path> を書いたときだけ作る。
  * 端末の出力は変えない。CI で上げるためのファイルが増えるだけ。
@@ -146,8 +139,9 @@ const writeSarif = (results: readonly Inspected[], argv: readonly string[], conf
   const located = results.flatMap((result) =>
     result.outcome.findings.map((finding) => ({ path: result.outcome.path, finding, language: result.language, rules: result.rules })),
   );
+  const notRun = results.flatMap((result) => result.checked.skipped.map((entry) => ({ path: result.outcome.path, rule: entry.rule, why: entry.why })));
   mkdirSync(dirname(path), { recursive: true });
-  writeFileSync(path, renderSarif(located, VERSION), "utf8");
+  writeFileSync(path, renderSarif(located, VERSION, notRun), "utf8");
   console.log(hostText(config).sarifWritten(path, located.length));
 };
 
@@ -162,10 +156,10 @@ const summaryLanguage = (results: readonly Inspected[], config: Config): UiLangu
 };
 
 const lint = async (targets: readonly string[], argv: readonly string[], config: Config): Promise<number> => {
-  const paths = collectTargets(targets);
+  const paths = collectTargets(targets, config.include);
   if (paths.length === 0) {
     // 0 件を成功にすると「CI は通っているが何も検証していない」状態が続く。§14。
-    console.error(hostText(config).noMarkdown(targets.join(", ")));
+    console.error(hostText(config).noMarkdown(targets.join(", "), config.include ?? []));
     return 1;
   }
   const language = config.language ?? "ja";
@@ -174,7 +168,7 @@ const lint = async (targets: readonly string[], argv: readonly string[], config:
     return 1;
   }
   warnRuleProblems(config, language);
-  const results = await Promise.all(paths.map((path) => inspect(path, config, argv)));
+  const results = await inspectRun(paths, config, argv);
   writeSarif(results, argv, config);
   results.filter((result) => result.outcome.findings.length > 0 || paths.length === 1).forEach((result) => console.log(result.text));
   renderSummary(
@@ -189,10 +183,10 @@ const lint = async (targets: readonly string[], argv: readonly string[], config:
  * 差分だけを出す。workflow spec §11。
  */
 const runWatch = async (targets: readonly string[], argv: readonly string[], config: Config): Promise<number> => {
-  const paths = collectTargets(targets);
+  const paths = collectTargets(targets, config.include);
   const text = hostText(config);
   if (paths.length === 0) {
-    console.error(text.noMarkdown(targets.join(", ")));
+    console.error(text.noMarkdown(targets.join(", "), config.include ?? []));
     return 1;
   }
   warnRuleProblems(config, config.language ?? "ja");
@@ -233,18 +227,19 @@ const explain = (config: Config, ruleId: string | undefined, genreFlag: string |
   }
   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, genre, settingSourcesOf(config, rule.id, language)));
+  const alone = offOnlyAsExperimental(rule, config, genre ?? DEFAULT_GENRE, preset, language);
+  console.log(renderExplain(rule, current, language, genre, { ...settingSourcesOf(config, rule.id, language), offOnlyAsExperimental: alone }));
   return 0;
 };
 
 const runBaseline = async (targets: readonly string[], argv: readonly string[], config: Config): Promise<number> => {
-  const paths = collectTargets(targets.length > 0 ? targets : ["."]);
+  const paths = collectTargets(targets.length > 0 ? targets : ["."], config.include);
   if (paths.length === 0) {
-    console.error(hostText(config).noMarkdownHere);
+    console.error(hostText(config).noMarkdownHere(config.include ?? []));
     return 1;
   }
-  const results = await Promise.all(paths.map((path) => inspect(path, config, [...argv, "--show-baseline"])));
-  const entries = results.flatMap((result) => fingerprints(result.outcome.path, result.kept));
+  const results = await inspectRun(paths, config, [...argv, "--show-baseline"]);
+  const entries = results.flatMap((result) => fingerprints(result.outcome.path, result.kept, process.cwd()));
   const file = join(process.cwd(), BASELINE_FILE);
   writeBaseline(file, entries);
   console.log(hostText(config).baselineDone(paths.length, entries.length, BASELINE_FILE).join("\n"));
@@ -303,10 +298,17 @@ const HANDLERS: Readonly<Record<string, Handler>> = {
   "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)),
+  suppressions: (argv, config) =>
+    runSuppressions(
+      positional(argv),
+      (paths) => inspectRun(paths, config, [...argv, "--show-baseline"]),
+      hostLanguage(config.language, process.env),
+      config.include,
+    ),
   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")),
+  enable: (argv, config) => changeSetting(config, "normal", argv[1], flag(argv, "--why")),
   feedback: (argv, config) => {
     return runFeedback(positional(argv), argv, {
       cwd: process.cwd(),
@@ -321,13 +323,14 @@ const HANDLERS: Readonly<Record<string, Handler>> = {
       }),
     });
   },
+  grade: (argv, config) => runGrade(argv, { config, flag, ui: hostLanguage(config.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. */
 export const COMMANDS: readonly string[] = Object.keys(HANDLERS);
 
-export const main = async (argv: readonly string[]): Promise<number> => {
+const dispatch = async (argv: readonly string[]): Promise<number> => {
   const first = argv[0];
   if (first === undefined || first === "--help" || first === "-h") {
     console.log(hostText(readConfig()).usage);
@@ -337,13 +340,19 @@ export const main = async (argv: readonly string[]): Promise<number> => {
     console.log(VERSION_LINES.join("\n"));
     return 0;
   }
+  if ((first === "lint" || HANDLERS[first] !== undefined) && asksForHelp(argv)) return printCommandHelp(hostText(readConfig()), first);
   // 知らないジャンルではどの rule も当たらず、知らない文書の種類では種類の知識が外れる。どちらも素通りに見えるので、何かする前に止める。
-  const config = await withExtensions(readConfig());
+  const config = withIncludes(await withExtensions(readConfig()), argv);
   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;
+  // grade は設定の誤りを 2 で返す。CI の門で「出力が悪い」（1）と取り違えないため。
+  if (problems.length > 0) return first === "grade" ? GRADE_EXIT.unreadable : 1;
   const handler = HANDLERS[first];
   if (handler !== undefined) return handler(argv, config);
   const targets = targetsOf(first === "lint" ? argv.slice(1) : argv);
   return argv.includes("--watch") ? runWatch(targets, argv, config) : lint(targets, argv, config);
 };
+
+/** A chaff.yaml or checks.yaml that is not YAML stops the run with its path and position, not a stack trace. */
+export const main = (argv: readonly string[]): Promise<number> =>
+  stoppingOnYamlFileError(() => dispatch(argv), process.cwd(), hostLanguage(undefined, process.env));

package/src/command-help.ts

@@ -0,0 +1,26 @@
+// Pure: what `chaff <command> --help` prints, taken from the usage that `chaff --help` prints, so the two cannot drift.
+
+const ENTRY = /^ {2}chaff (\S+)/u;
+const CONTINUATION = /^ {3,}\S/u;
+const HELP_FLAGS: ReadonlySet<string> = new Set(["--help", "-h"]);
+
+/** Whether the arguments after the command ask for its help. */
+export const asksForHelp = (argv: readonly string[]): boolean => argv.slice(1).some((arg) => HELP_FLAGS.has(arg));
+
+const namesOf = (line: string): readonly string[] => ENTRY.exec(line)?.[1]?.split("|") ?? [];
+
+/** The usage's lines for one command: each line naming it ("  chaff relax|strict|off …"), with the lines indented under it. */
+export const commandUsage = (usage: string, command: string): string[] =>
+  usage.split("\n").reduce<{ owned: boolean; lines: string[] }>(
+    (state, line) => {
+      const owned = ENTRY.test(line) ? namesOf(line).includes(command) : state.owned && CONTINUATION.test(line);
+      return { owned, lines: owned ? [...state.lines, line] : state.lines };
+    },
+    { owned: false, lines: [] },
+  ).lines;
+
+/** `chaff <command> --help`: the command's lines of the usage and where the rest is, or the whole usage when it has none. */
+export const commandHelp = (usage: string, command: string, moreHelp: string): string => {
+  const lines = commandUsage(usage, command);
+  return lines.length === 0 ? usage : [...lines, "", moreHelp].join("\n");
+};

package/src/commands/compare.ts

@@ -6,7 +6,7 @@ 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 { readDocument, type ReadDocument } from "./read-document.ts";
 import type { TreeContext } from "./tree.ts";
 
 /** Options whose value is the next argument. That value is not a file. */
@@ -33,13 +33,17 @@ const parseAllowed = (argv: readonly string[]): ParsedAllowed => {
 
 export type DocumentFacts = Compared & { readonly language: string };
 
+/** A document's facts, read with the team's names. */
+export const factsOf = (path: string, prose: ReadDocument, names: readonly string[]): DocumentFacts => {
+  const root = isMarkdownPath(path) ? readMarkdown(prose.doc.source).root : undefined;
+  const extraction = extractFacts({ doc: prose.doc, root, structure: prose.structure, names });
+  return { path, extraction, language: prose.language };
+};
+
 /** 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 };
+  return prose === undefined ? undefined : factsOf(path, prose, context.config.names ?? []);
 };
 
 const renderFor = (argv: readonly string[]): typeof renderFriendly => {

package/src/commands/eval.ts

@@ -20,11 +20,11 @@ const TEXT: Texts<{
   readonly unknownRule: (id: string) => string;
 }> = {
   ja: {
-    mixed: (mixes) => `言語かジャンルが混ざっています: ${mixes}\n1 つに絞って測ってください（例: npx chaff eval examples/blog-ja/）。`,
+    mixed: (mixes) => `言語かジャンルが混ざっています: ${mixes}\n1 つに絞って測ってください（例: npx chaffjs eval examples/blog-ja/）。`,
     unknownRule: (id) => `${id} という rule はありません。`,
   },
   en: {
-    mixed: (mixes) => `Languages or genres are mixed: ${mixes}\nMeasure one at a time (for example npx chaff eval examples/blog-en/).`,
+    mixed: (mixes) => `Languages or genres are mixed: ${mixes}\nMeasure one at a time (for example npx chaffjs eval examples/blog-en/).`,
     unknownRule: (id) => `There is no rule named ${id}.`,
   },
 };
@@ -53,9 +53,9 @@ export type Context = {
  * 測った結果は文書の言語で出す（混ざっていれば測らないので、言語は 1 つ）。断りは ui の言語。
  */
 export const runEval = async (targets: readonly string[], argv: readonly string[], context: Context): Promise<number> => {
-  const paths = collectTargets(targets.length > 0 ? targets : ["."]);
+  const paths = collectTargets(targets.length > 0 ? targets : ["."], context.config.include);
   if (paths.length === 0) {
-    console.error(CLI_TEXT[context.ui].noMarkdown(targets.join(", ")));
+    console.error(CLI_TEXT[context.ui].noMarkdown(targets.join(", "), context.config.include ?? []));
     return 1;
   }
   const { config, resolveGenre, flag, ui } = context;

package/src/commands/fix-plan.ts

@@ -1,14 +1,20 @@
 import { existsSync } from "node:fs";
 import { outlineOf } from "../outline/shape.ts";
+import { structureOf } from "../structure-shape/of-document.ts";
 import { buildFixPlan } from "../fix-plan/plan.ts";
 import { renderFixPlanJson, renderFixPlanMarkdown } from "../fix-plan/render.ts";
 import { FIX_PLAN_TEXT } from "../fix-plan/text.ts";
+import { chosenDepthOf } from "../fix-plan/chosen-depth.ts";
 import type { Checked } from "./feedback.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"]);
+const VALUED: ReadonlySet<string> = new Set(["--language", "--genre", "--depth"]);
+
+/** --depth's value: undefined when not given, empty when given with nothing after it (which is then reported). */
+const depthFlag = (argv: readonly string[], context: FixPlanContext): string | undefined =>
+  argv.includes("--depth") ? (context.flag(argv, "--depth") ?? "") : undefined;
 
 export const fixPlanTargets = (argv: readonly string[]): string[] =>
   argv.slice(1).filter((arg, index, all) => !arg.startsWith("--") && !VALUED.has(all[index - 1] ?? ""));
@@ -20,9 +26,15 @@ export type FixPlanContext = TreeContext & {
 
 /**
  * An instruction document for whoever rewrites the file: the findings grouped by rule, each rule's rewrite direction,
- * the document-level signals, a recommended mode and the checks to run after. Deterministic; sends nothing anywhere.
+ * the document-level signals, the structure targets from human articles, a recommended mode and the checks to run after. Deterministic; sends nothing anywhere.
  */
 export const runFixPlan = async (targets: readonly string[], argv: readonly string[], context: FixPlanContext): Promise<number> => {
+  // Checked first: a file name written after --depth by mistake is reported as the depth it was read as.
+  const depth = chosenDepthOf(depthFlag(argv, context), context.config.fixPlan, context.ui ?? "ja");
+  if ("problem" in depth) {
+    console.error(`chaff: ${depth.problem}`);
+    return 1;
+  }
   const [path] = targets;
   if (path === undefined || targets.length > 1) {
     console.error(FIX_PLAN_TEXT[context.ui ?? "ja"].usage);
@@ -46,7 +58,9 @@ export const runFixPlan = async (targets: readonly string[], argv: readonly stri
     rules: checked.rules,
     skipped: checked.skipped,
     outline: outlineOf(prose.doc),
+    structure: structureOf(prose.doc),
     phrases: prose.doc.lexicons["ai-tell"] ?? [],
+    chosenDepth: depth.chosen,
   });
   console.log(argv.includes("--json") ? renderFixPlanJson(plan) : renderFixPlanMarkdown(plan));
   return 0;

package/src/commands/grade-baseline.ts

@@ -0,0 +1,44 @@
+import { readDocumentFile } from "../files.ts";
+import { stampCheck } from "../grade/baseline.ts";
+import { BASELINE_TEXT } from "../grade/baseline-text.ts";
+import type { GradeResult, Stamp } from "../grade/result.ts";
+import { parseResults } from "../grade/results-read.ts";
+import { GRADE_TEXT } from "../grade/text.ts";
+import type { UiLanguage } from "../ui.ts";
+
+// `chaff grade --baseline <earlier results>` before anything is graded: the earlier results read, and their stamp
+// checked against this run's. Either can stop the run with exit 2, so no time is spent grading what cannot be compared.
+
+/** No --baseline; a baseline to compare with; or a reason already said why the run stops. */
+export type BaselineChoice =
+  { readonly kind: "none" } | { readonly kind: "stop" } | { readonly kind: "compare"; readonly path: string; readonly before: readonly GradeResult[] };
+
+const STOP: BaselineChoice = { kind: "stop" };
+
+const readResults = async (path: string, ui: UiLanguage): Promise<readonly GradeResult[] | undefined> => {
+  try {
+    const parsed = parseResults(await readDocumentFile(path));
+    if ("results" in parsed) return parsed.results;
+    console.error(BASELINE_TEXT[ui].unreadable(path, parsed.badLines.join(", ")));
+  } catch (error) {
+    console.error(GRADE_TEXT[ui].unreadable(path, error instanceof Error ? error.message : String(error)));
+  }
+  return undefined;
+};
+
+/** The earlier results, if they can be compared with a run stamped `stamp`. --allow-stamp-mismatch compares anyway, saying so first. */
+export const chooseBaseline = async (path: string | undefined, stamp: Stamp, allowMismatch: boolean, ui: UiLanguage): Promise<BaselineChoice> => {
+  if (path === undefined) return { kind: "none" };
+  const before = await readResults(path, ui);
+  if (before === undefined) return STOP;
+  const checked = stampCheck(before, stamp);
+  if (checked.comparable) return { kind: "compare", path, before };
+  const text = BASELINE_TEXT[ui];
+  const differ = checked.differ.map((part) => text.differ[part]).join(", ");
+  if (!allowMismatch || checked.differ.includes("mixed")) {
+    console.error(text.notComparable(path, differ));
+    return STOP;
+  }
+  console.error(text.mismatchAllowed(path, differ));
+  return { kind: "compare", path, before };
+};

package/src/commands/grade.ts

@@ -0,0 +1,191 @@
+import { mkdirSync, writeFileSync } from "node:fs";
+import { dirname } from "node:path";
+import { packageFor } from "../adapter-load.ts";
+import type { Config } from "../config/load.ts";
+import { readDocumentFile } from "../files.ts";
+import { GENRES } from "../genre.ts";
+import { gradeItem, type GradeSetup } from "../grade/grade-item.ts";
+import { DEFAULT_VARIANT_FIELD, ITEM_FIELDS, parseItems, type GradeItem, type VariantField } from "../grade/item.ts";
+import { renderMarkdown } from "../grade/render-markdown.ts";
+import { renderVariants, renderVariantsCompact } from "../grade/render-variants.ts";
+import { variantsOfRun, type VariantComparison } from "../grade/variants.ts";
+import { VARIANT_TEXT } from "../grade/variants-text.ts";
+import { renderCompact, renderSummary } from "../grade/render.ts";
+import type { GradeResult } from "../grade/result.ts";
+import { gradeSetup } from "../grade/setup.ts";
+import { parseRubric, type Rubric } from "../grade/rubric.ts";
+import { rulesOf } from "../custom/load.ts";
+import { summaryOf } from "../grade/summary.ts";
+import { GRADE_TEXT, type GradeText } from "../grade/text.ts";
+import { sharedLanguage, type UiLanguage } from "../ui.ts";
+import { compareRuns, type Comparison } from "../grade/baseline.ts";
+import { BASELINE_TEXT } from "../grade/baseline-text.ts";
+import { renderComparison, renderComparisonCompact } from "../grade/render-baseline.ts";
+import { chooseBaseline } from "./grade-baseline.ts";
+
+/** Exit codes (spec §29.3). 2 keeps "the grader did not run" apart from "an output is bad" at a CI gate. */
+export const GRADE_EXIT = { passed: 0, failed: 1, unreadable: 2 } as const;
+
+const VALUED: ReadonlySet<string> = new Set(["--out", "--genre", "--baseline", "--format", "--variant-key"]);
+
+const FORMATS = ["text", "json", "markdown"] as const;
+
+type Format = (typeof FORMATS)[number];
+
+const isFormat = (value: string): value is Format => FORMATS.some((format) => format === value);
+
+/** --format, with --json as its short form. Undefined for a format chaff does not write. */
+const formatOf = (argv: readonly string[], context: GradeContext): Format | undefined => {
+  const written = context.flag(argv, "--format") ?? (argv.includes("--json") ? "json" : "text");
+  return isFormat(written) ? written : undefined;
+};
+
+/** The field naming each output's variant. Given on the command line, every line must have it; a field an item already uses cannot be one. */
+const variantFieldOf = (argv: readonly string[], context: GradeContext): VariantField | undefined => {
+  const key = context.flag(argv, "--variant-key");
+  if (key === undefined) return DEFAULT_VARIANT_FIELD;
+  return key === "" || ITEM_FIELDS.includes(key) ? undefined : { key, required: true };
+};
+
+const gradeTargets = (argv: readonly string[]): string[] =>
+  argv.slice(1).filter((arg, index, all) => !arg.startsWith("--") && !VALUED.has(all[index - 1] ?? ""));
+
+export type GradeContext = {
+  readonly config: Config;
+  readonly flag: (argv: readonly string[], name: string) => string | undefined;
+  readonly ui: UiLanguage;
+};
+
+const readItems = async (path: string, variantField: VariantField, text: GradeText): Promise<readonly GradeItem[] | undefined> => {
+  try {
+    const vocabulary = { isLanguage: (language: string) => packageFor(language) !== undefined, genres: GENRES };
+    const parsed = parseItems(await readDocumentFile(path), vocabulary, variantField);
+    if ("items" in parsed) return parsed.items;
+    parsed.problems.forEach((problem) => console.error(`${path}: ${text.problem(problem)}`));
+  } catch (error) {
+    console.error(text.unreadable(path, error instanceof Error ? error.message : String(error)));
+  }
+  return undefined;
+};
+
+/** The `grade:` rubric, or undefined after saying what is wrong with it. `rubric: undefined` is a run with no rubric. */
+const readRubric = (config: Config, text: GradeText): { readonly rubric: Rubric | undefined } | undefined => {
+  const parsed = parseRubric(config.grade);
+  if ("rubric" in parsed) return parsed;
+  parsed.problems.forEach((problem) => console.error(`chaff: ${text.rubricProblem(problem)}`));
+  return undefined;
+};
+
+/** A rule id under grade.rules that chaff does not know. Said once here; each result also lists it as not run. */
+const warnUnknownRules = (rubric: Rubric | undefined, config: Config, text: GradeText): void => {
+  const known = new Set(rulesOf(config.language ?? "en", config).map((rule) => rule.id));
+  Object.keys(rubric?.rules ?? {})
+    .filter((id) => !known.has(id))
+    .forEach((id) => console.error(`chaff: grade.rules.${id}: ${text.unknownRule}`));
+};
+
+const setupFor = async (
+  items: readonly GradeItem[],
+  rubric: Rubric | undefined,
+  argv: readonly string[],
+  context: GradeContext,
+  text: GradeText,
+): Promise<GradeSetup | undefined> => {
+  const languages = items.flatMap((item) => (item.language === undefined ? [] : [item.language]));
+  const run = { experimental: context.config.experimental || argv.includes("--experimental"), genre: context.flag(argv, "--genre") };
+  try {
+    return await gradeSetup(context.config, run, languages, rubric);
+  } catch (error) {
+    console.error(text.cannotLoad(error instanceof Error ? error.message : String(error)));
+    return undefined;
+  }
+};
+
+/** One output after another, in the file's order: the results file lines up with the input. */
+const gradeInOrder = (items: readonly GradeItem[], setup: GradeSetup): Promise<GradeResult[]> =>
+  items.reduce<Promise<GradeResult[]>>(async (previous, item) => [...(await previous), await gradeItem(item, setup)], Promise.resolve([]));
+
+const writeResults = (path: string | undefined, results: readonly GradeResult[], text: GradeText): void => {
+  if (path === undefined) return;
+  mkdirSync(dirname(path), { recursive: true });
+  writeFileSync(path, results.map((result) => `${JSON.stringify(result)}\n`).join(""), "utf8");
+  // 標準エラーに出す。--json の標準出力を JSON のままにする。
+  console.error(text.wrote(path, results.length));
+};
+
+/** The baseline compared with, when there is one: where it was read from and how this run moved against it. */
+type Compared = { readonly path: string; readonly comparison: Comparison } | undefined;
+
+/** What the summary is printed with: the format, the comparisons made, and the language of the outputs. */
+type Printing = { readonly format: Format; readonly compact: boolean; readonly ui: UiLanguage };
+
+const printJson = (results: readonly GradeResult[], variants: VariantComparison | undefined, compared: Compared): void => {
+  const summary = summaryOf(results);
+  const withVariants = variants === undefined ? summary : { ...summary, variants };
+  console.log(JSON.stringify(compared === undefined ? withVariants : { ...withVariants, baseline: compared.comparison }, null, 2));
+};
+
+const printText = (path: string, results: readonly GradeResult[], variants: VariantComparison | undefined, compared: Compared, printing: Printing): void => {
+  const summary = summaryOf(results);
+  const { compact, ui } = printing;
+  console.log(compact ? renderCompact(path, results, summary, GRADE_TEXT[ui]) : renderSummary(path, summary, GRADE_TEXT[ui]));
+  if (variants !== undefined) console.log(compact ? renderVariantsCompact(variants, VARIANT_TEXT[ui]) : `\n${renderVariants(variants, VARIANT_TEXT[ui])}`);
+  if (compared === undefined) return;
+  const baselineText = BASELINE_TEXT[ui];
+  console.log(compact ? renderComparisonCompact(compared.comparison, baselineText) : `\n${renderComparison(compared.path, compared.comparison, baselineText)}`);
+};
+
+const printSummary = (path: string, results: readonly GradeResult[], compared: Compared, printing: Printing): void => {
+  const variants = variantsOfRun(results);
+  if (printing.format === "json") printJson(results, variants, compared);
+  else if (printing.format === "markdown") {
+    const texts = { grade: GRADE_TEXT[printing.ui], variants: VARIANT_TEXT[printing.ui] };
+    console.log(renderMarkdown(path, summaryOf(results), { variants, baseline: compared?.comparison }, texts));
+  } else printText(path, results, variants, compared, printing);
+};
+
+type RunOptions = { readonly path: string; readonly format: Format; readonly variantField: VariantField };
+
+/** The file to grade and how to read and print it, or undefined after printing the usage. */
+const runOptionsOf = (argv: readonly string[], context: GradeContext): RunOptions | undefined => {
+  const [path, ...extra] = gradeTargets(argv);
+  const format = formatOf(argv, context);
+  const variantField = variantFieldOf(argv, context);
+  if (path !== undefined && extra.length === 0 && format !== undefined && variantField !== undefined) return { path, format, variantField };
+  console.error(GRADE_TEXT[context.ui].usage);
+  return undefined;
+};
+
+/** With a baseline, the exit code says whether this run regressed (spec §29.5); without one, whether every output passed. */
+const exitCodeOf = (results: readonly GradeResult[], compared: Compared): number => {
+  if (compared !== undefined) return compared.comparison.regressions.length === 0 ? GRADE_EXIT.passed : GRADE_EXIT.failed;
+  return results.every((result) => result.pass) ? GRADE_EXIT.passed : GRADE_EXIT.failed;
+};
+
+/**
+ * Grades a JSONL file of model outputs (spec §29.3): each output's findings and rates, facts against its reference and
+ * quotations against its sources, then pass or fail. Never calls a model and never rewrites an output.
+ */
+export const runGrade = async (argv: readonly string[], context: GradeContext): Promise<number> => {
+  const host = GRADE_TEXT[context.ui];
+  const options = runOptionsOf(argv, context);
+  if (options === undefined) return GRADE_EXIT.unreadable;
+  const { path } = options;
+  const rubric = readRubric(context.config, host);
+  const items = rubric === undefined ? undefined : await readItems(path, options.variantField, host);
+  const setup = items === undefined || rubric === undefined ? undefined : await setupFor(items, rubric.rubric, argv, context, host);
+  if (setup === undefined || items === undefined) return GRADE_EXIT.unreadable;
+  const baseline = await chooseBaseline(context.flag(argv, "--baseline"), setup.stamp, argv.includes("--allow-stamp-mismatch"), context.ui);
+  if (baseline.kind === "stop") return GRADE_EXIT.unreadable;
+  warnUnknownRules(setup.rubric, context.config, host);
+  const results = await gradeInOrder(items, setup);
+  writeResults(context.flag(argv, "--out"), results, host);
+  const rubricRules = new Set(Object.keys(setup.rubric?.rules ?? {}));
+  const compared = baseline.kind === "compare" ? { path: baseline.path, comparison: compareRuns(baseline.before, results, rubricRules) } : undefined;
+  const ui = sharedLanguage(
+    results.map((result) => result.language),
+    context.ui,
+  );
+  printSummary(path, results, compared, { format: options.format, compact: argv.includes("--compact"), ui });
+  return exitCodeOf(results, compared);
+};

package/src/commands/help.ts

@@ -0,0 +1,8 @@
+import { commandHelp } from "../command-help.ts";
+import type { CliText } from "../cli-text.ts";
+
+/** `chaff <command> --help` prints the command's usage and runs nothing: `init --help` must not write chaff.yaml. */
+export const printCommandHelp = (text: CliText, command: string): number => {
+  console.log(commandHelp(text.usage, command, text.moreHelp));
+  return 0;
+};

package/src/commands/outline.ts

@@ -3,6 +3,7 @@ import { outlineOf } from "../outline/shape.ts";
 import { renderOutlineCompact, renderOutlineFriendly, renderOutlineJson, type DocumentOutline } from "../outline/render.ts";
 import { OUTLINE_TEXT } from "../outline/text.ts";
 import { readDocument } from "./read-document.ts";
+import { structureOf } from "../structure-shape/of-document.ts";
 import type { TreeContext } from "./tree.ts";
 
 /** Options whose value is the next argument. That value is not a file. */
@@ -15,7 +16,7 @@ const MOST_FILES = 2;
 
 const readOutline = async (path: string, argv: readonly string[], context: TreeContext): Promise<DocumentOutline | undefined> => {
   const prose = await readDocument(path, argv, context, false);
-  return prose === undefined ? undefined : { path, language: prose.language, outline: outlineOf(prose.doc) };
+  return prose === undefined ? undefined : { path, language: prose.language, outline: outlineOf(prose.doc), structure: structureOf(prose.doc) };
 };
 
 /** The files in the order given, or undefined once one cannot be read (its error is already printed). */
@@ -34,8 +35,8 @@ const renderFor = (argv: readonly string[], documents: readonly DocumentOutline[
 };
 
 /**
- * A document's outline and shape (headings, average section length, text in lists, bold), or two documents' side by
- * side: a restructure measured by machine. Measures; never judges, so it always ends with 0 once the files are read.
+ * A document's outline and shape (headings, average section length, text in lists, bold) and its structure measures
+ * against human articles, or two documents' side by side: a restructure measured by machine. Measures; never judges, so it always ends with 0 once the files are read.
  */
 export const runOutline = async (targets: readonly string[], argv: readonly string[], context: TreeContext): Promise<number> => {
   if (targets.length === 0 || targets.length > MOST_FILES) {