chaffjs 0.19.0 → 0.20.0

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/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) {

package/src/commands/read-document.ts

@@ -2,23 +2,32 @@ import { loadAdapter } from "../adapter-load.ts";
 import { buildDocument, teamRules } from "../document.ts";
 import { profileFor } from "../profile/for-file.ts";
 import { resolveGenre } from "../resolve-genre.ts";
+import type { Config } from "../config/load.ts";
 import type { ProseDocument, StructurePatterns } from "../plugin.ts";
 import { readSource, treeLanguage, type TreeContext } from "./tree.ts";
 
 /** One document as lint reads it, and its language package's structure reader. */
 export type ReadDocument = { readonly doc: ProseDocument; readonly language: string; readonly structure: StructurePatterns | undefined };
 
-/**
- * Reads one file as lint does: its language, genre, document profile and the team's rules. `pos` loads the
- * part-of-speech tagger, which costs time, so only a command that reads names asks for it.
- */
+/** One text as lint reads it. `pos` loads the part-of-speech tagger, which costs time, so only a command that reads names asks for it. */
+export const documentFromSource = async (
+  path: string,
+  source: string,
+  choice: { readonly language: string; readonly genre: string },
+  config: Config,
+  pos: boolean,
+): Promise<ReadDocument> => {
+  const adapter = await loadAdapter(choice.language);
+  await adapter.prepare?.({ pos });
+  const doc = buildDocument(path, source, adapter, teamRules(config), profileFor(config, path, source, choice.language, choice.genre));
+  return { doc, language: choice.language, structure: adapter.structure };
+};
+
+/** Reads one file as lint does: its language, genre, document profile and the team's rules. */
 export const readDocument = async (path: string, argv: readonly string[], context: TreeContext, pos: boolean): Promise<ReadDocument | 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 });
   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));
-  return { doc, language, structure: adapter.structure };
+  return documentFromSource(path, source, { language, genre }, context.config, pos);
 };

package/src/commands/suppressions.ts

@@ -5,10 +5,11 @@ import type { UiLanguage } from "../ui.ts";
 /** `chaff suppressions`: what the stets in these files (this folder by default) silence, and the stets whose rule did not run. */
 export const runSuppressions = async (
   targets: readonly string[],
-  inspect: (path: string) => Promise<{ readonly perFile: PerFile }>,
+  inspectRun: (paths: readonly string[]) => Promise<readonly { readonly perFile: PerFile }[]>,
   ui: UiLanguage,
+  include: readonly string[] = [],
 ): Promise<number> => {
-  const inspected = await Promise.all(collectTargets(targets.length > 0 ? targets : ["."]).map(inspect));
+  const inspected = await inspectRun(collectTargets(targets.length > 0 ? targets : ["."], include));
   console.log(
     renderSuppressions(
       inspected.map((file) => file.perFile),

package/src/commands/test.ts

@@ -155,9 +155,9 @@ const notRunNotice = (why: string, what: string, envFile: string | undefined, la
  * 見出しと指摘は文書の言語、締めは文書がそろっていればその言語、混ざっていれば ui の言語。
  */
 export const runTest = async (targets: readonly string[], argv: readonly string[], context: TestContext): 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, inspect } = context;

package/src/commands/tree.ts

@@ -1,10 +1,10 @@
 import { readDocumentFile } from "../files.ts";
 import { loadAdapter } from "../adapter-load.ts";
-import { applyByPath } from "../config/by-path.ts";
 import { profileFor } from "../profile/for-file.ts";
 import { resolveGenre } from "../resolve-genre.ts";
-import { guessLanguage } from "../detect.ts";
+import { documentLanguage } from "../check-source.ts";
 import { isMarkdownPath } from "../structure/markdown-path.ts";
+import { structureText } from "../document-reading.ts";
 import { buildStructure } from "../structure/of.ts";
 import { toSexp } from "../structure/sexp.ts";
 import { foldPostOrder } from "../tree-walk.ts";
@@ -63,13 +63,20 @@ export const readSource = async (path: string, context: TreeContext): Promise<st
  * その前に --language を置く。混在するリポジトリで、英語の契約書を日本語として読まないため。
  */
 export const treeLanguage = (path: string, source: string, argv: readonly string[], context: TreeContext): string =>
-  context.flag(argv, "--language") ??
-  applyByPath(context.config.byPath, context.config.baseDir, path).language ??
-  context.config.language ??
-  guessLanguage(source).language;
+  context.flag(argv, "--language") ?? documentLanguage(path, source, context.config);
 
 export type SourceTree = { readonly source: string; readonly tree: StructureNode };
 
+/** A text's tree of addresses, read as `chaff tree` reads a file; undefined when the language package cannot read structure. */
+export const treeFromSource = async (path: string, source: string, language: string, genre: string, config: Config): Promise<StructureNode | undefined> => {
+  const adapter = await loadAdapter(language);
+  if (adapter.structure === undefined) return undefined;
+  // 日本語は形態素で数量と日付を読む。解析器が無ければ単位の表で読むので、木は作れる。
+  await adapter.prepare?.({ pos: true });
+  const profile = profileFor(config, path, source, language, genre);
+  return buildStructure({ path, source, language, markdown: isMarkdownPath(path), profile, lexicons: adapter.lexicons }, adapter.structure);
+};
+
 /**
  * 1 ファイルを読んで木にする。読めない・言語パッケージが構造を読めないときは、黙らずに言って undefined を返す。
  * chaff tree と chaff cite が同じ木を見るように、ここを一つにしておく。
@@ -78,15 +85,15 @@ export const readTree = async (path: string, argv: readonly string[], context: T
   const source = await readSource(path, context);
   if (source === undefined) return undefined;
   const language = treeLanguage(path, source, argv, context);
-  const adapter = await loadAdapter(language);
-  if (adapter.structure === undefined) {
+  const genre = resolveGenre(path, source, context.config, context.flag(argv, "--genre")).genre;
+  // A YAML file's tree is read from its values alone, as a check reads it.
+  const text = structureText(path, source);
+  const tree = await treeFromSource(path, text, language, genre, context.config);
+  if (tree === undefined) {
     console.error(treeText(context).noStructure(path, language));
     return undefined;
   }
-  // 日本語は形態素で数量と日付を読む。解析器が無ければ単位の表で読むので、木は作れる。
-  await adapter.prepare?.({ pos: true });
-  const profile = profileFor(context.config, path, source, language, resolveGenre(path, source, context.config, context.flag(argv, "--genre")).genre);
-  return { source, tree: buildStructure({ path, source, language, markdown: isMarkdownPath(path), profile, lexicons: adapter.lexicons }, adapter.structure) };
+  return { source: text, tree };
 };
 
 /**

package/src/compare/distinct.ts

@@ -1,6 +1,13 @@
 import type { Atom } from "./atom.ts";
 import { identity } from "./match.ts";
 
+/**
+ * What makes two facts the same when only whether a fact is stated counts. A Markdown heading's key is only its level,
+ * so the level alone would let any heading at that level stand for a cut one; its wording is part of it here, as it is
+ * when facts are counted, where headings first pair by wording.
+ */
+const statedIdentity = (atom: Atom): string => (atom.kind === "heading" ? `${identity(atom)}\u0000${atom.text}` : identity(atom));
+
 /**
  * The changes left when facts are compared as sets (--distinct): a fact the other document states at least once is
  * kept, however many times either states it. A summary that repeated the body can be cut without its repeats reading
@@ -8,6 +15,6 @@ import { identity } from "./match.ts";
  * names are counted.
  */
 export const unstatedChanges = (changes: readonly Atom[], other: readonly Atom[], otherNameText: string): Atom[] => {
-  const stated = new Set(other.map(identity));
-  return changes.filter((atom) => !stated.has(identity(atom)) && !(atom.kind === "name" && otherNameText.includes(atom.key)));
+  const stated = new Set(other.map(statedIdentity));
+  return changes.filter((atom) => !stated.has(statedIdentity(atom)) && !(atom.kind === "name" && otherNameText.includes(atom.key)));
 };

package/src/compare/proper-nouns.ts

@@ -54,12 +54,16 @@ export const readsProperNouns = (doc: ProseDocument): boolean => doc.sentences.l
  */
 export const properNouns = (input: NounInput): Atom[] => {
   const { source } = input.doc;
-  const lowerCase = lowerCaseWords(source);
-  return input.doc.sentences.flatMap((sentence) =>
-    runsOf(sentence.tokens ?? [], source).flatMap((run): Atom[] => {
-      const text = source.slice(run.start, run.end);
-      if (overlapsAny(input.taken, run) || isCommonWord(run, text, lowerCase)) return [];
-      return [{ kind: "name", key: factKey(source, run, input.unseen), text, line: input.lineOf(run.start) }];
-    }),
+  return nameSpans(input.doc).flatMap((run): Atom[] => {
+    if (overlapsAny(input.taken, run)) return [];
+    return [{ kind: "name", key: factKey(source, run, input.unseen), text: source.slice(run.start, run.end), line: input.lineOf(run.start) }];
+  });
+};
+
+/** Where the tagger's proper nouns are written, each run of them one name, without the common words that began a sentence. */
+export const nameSpans = (doc: ProseDocument): Span[] => {
+  const lowerCase = lowerCaseWords(doc.source);
+  return doc.sentences.flatMap((sentence) =>
+    runsOf(sentence.tokens ?? [], doc.source).filter((run) => !isCommonWord(run, doc.source.slice(run.start, run.end), lowerCase)),
   );
 };

package/src/config/load.ts

@@ -1,6 +1,5 @@
-import { readFileSync } from "node:fs";
 import { dirname } from "node:path";
-import { parse } from "yaml";
+import { readYamlFile } from "./yaml-file.ts";
 import { isLevel } from "../levels.ts";
 import { defaultModel } from "../judge.ts";
 import { isBackend, type BackendName } from "../backends/types.ts";
@@ -36,6 +35,8 @@ export type Config = {
   readonly names: readonly string[];
   /** names に書かれていたが名前として読めなかった値。黙って捨てると、並べたつもりの名前が効いていないことに気づけない。 */
   readonly unreadableNames: readonly string[];
+  /** File-name globs (*.yaml) a directory walk checks besides Markdown. --include adds to them. */
+  readonly include?: readonly string[];
   /** パスごとの上書き。設定ファイルのある場所からの相対で照合する。 */
   readonly byPath: readonly PathRule[];
   readonly baseDir: string;
@@ -49,6 +50,8 @@ export type Config = {
   readonly applied?: AppliedStyle | undefined;
   /** custom_rules as written: the team's own rules. custom/parse.ts reads and checks them. */
   readonly customRules?: unknown;
+  /** grade as written: the rubric `chaff grade` reads (grade/rubric.ts). */
+  readonly grade?: unknown;
   /** plugins as written: package names and paths. extension/plugin-load.ts reads and checks them. */
   readonly plugins?: unknown;
   /** The code chaff.yaml names, once loaded (extension/load.ts). Reading chaff.yaml does not load it. */
@@ -163,7 +166,7 @@ const byPathOf = (raw: unknown): PathRule[] => (Array.isArray(raw) ? raw.map(toP
 
 /** 設定ファイルが無くても動く。あっても、既定から変えたものだけが書かれている。spec §18。 */
 export const loadConfig = (path: string): Config => {
-  const raw: unknown = parse(readFileSync(path, "utf8"));
+  const raw: unknown = readYamlFile(path);
   if (!isRecord(raw)) return { ...EMPTY, path };
   const declared: unknown = raw["ai_backend"];
   const backend: BackendName = isBackend(declared) ? declared : DEFAULT_BACKEND;
@@ -186,12 +189,14 @@ export const loadConfig = (path: string): Config => {
     requiredSections: wordsOf(raw["required_sections"]),
     names: names.names,
     unreadableNames: names.unreadable,
+    include: globsOf(raw["include"]),
     byPath: byPathOf(raw["by_path"]),
     baseDir: dirname(path),
     options: isRecord(options) ? options : {},
     unreadableOptions: options === undefined || options === null || isRecord(options) ? undefined : printed(options),
     style: raw["style"] === undefined || raw["style"] === null ? undefined : (str(raw["style"]) ?? printed(raw["style"])),
     customRules: raw["custom_rules"],
+    grade: raw["grade"],
     plugins: raw["plugins"],
   };
 };

package/src/config/yaml-file.ts

@@ -0,0 +1,65 @@
+import { readFileSync } from "node:fs";
+import { parse, YAMLParseError } from "yaml";
+import { relative } from "node:path";
+import type { Texts, UiLanguage } from "../ui.ts";
+
+/** Where a settings file stops being YAML: 1-based line and column, and the parser's own sentence without its position. */
+export type YamlSyntax = { readonly line: number; readonly column: number; readonly detail: string };
+
+/** The parser appends " at line 3, column 1:" and, on the lines below, a picture of the line; chaff says the position itself. */
+const POSITION_TAIL = / at line \d+, column \d+:?$/u;
+
+/** A YAML syntax error as a position and a sentence, or undefined for anything else (a missing file is not a syntax error). */
+export const yamlSyntaxOf = (error: unknown): YamlSyntax | undefined => {
+  if (!(error instanceof YAMLParseError)) return undefined;
+  const start = error.linePos?.[0];
+  return {
+    line: start?.line ?? 1,
+    column: start?.col ?? 1,
+    detail: (error.message.split("\n")[0] ?? "").replace(POSITION_TAIL, "").trim(),
+  };
+};
+
+/** A settings file the person wrote that is not YAML. The command line says where and stops; no stack trace. */
+export class YamlFileError extends Error {
+  readonly path: string;
+  readonly syntax: YamlSyntax;
+
+  constructor(path: string, syntax: YamlSyntax, cause: unknown) {
+    super(`${path}:${syntax.line}:${syntax.column}: ${syntax.detail}`, { cause });
+    this.name = "YamlFileError";
+    this.path = path;
+    this.syntax = syntax;
+  }
+}
+
+/** A settings file read as YAML. A syntax error becomes a YamlFileError naming the file; other failures pass through. */
+export const readYamlFile = (path: string): unknown => {
+  const text = readFileSync(path, "utf8");
+  try {
+    return parse(text);
+  } catch (error) {
+    const syntax = yamlSyntaxOf(error);
+    if (syntax === undefined) throw error;
+    throw new YamlFileError(path, syntax, error);
+  }
+};
+
+const TEXT: Texts<(path: string, syntax: YamlSyntax) => string> = {
+  ja: (path, { line, column, detail }) => `chaff: ${path} の ${line} 行目 ${column} 桁目が YAML として読めません: ${detail}`,
+  en: (path, { line, column, detail }) => `chaff: ${path}, line ${line}, column ${column}, is not valid YAML: ${detail}`,
+};
+
+/** The sentence the command line prints for a settings file that is not YAML. path: as the person would type it. */
+export const yamlFileProblem = (path: string, syntax: YamlSyntax, ui: UiLanguage): string => TEXT[ui](path, syntax);
+
+/** Runs a command, and turns a settings file that is not YAML into its sentence and exit code 1. cwd: what the path is printed relative to. */
+export const stoppingOnYamlFileError = async (run: () => Promise<number>, cwd: string, ui: UiLanguage): Promise<number> => {
+  try {
+    return await run();
+  } catch (error) {
+    if (!(error instanceof YamlFileError)) throw error;
+    console.error(yamlFileProblem(relative(cwd, error.path) || error.path, error.syntax, ui));
+    return 1;
+  }
+};

package/src/correction-edit.ts

@@ -0,0 +1,43 @@
+// 誤った形と正しい形の組から、書いた語のどこをどう直すかを決める。純粋な関数だけを置く。
+
+/** wrong の上の [start, end) を replacement にすると right になる。前後の同じ字は含めない。 */
+export type Edit = { readonly start: number; readonly end: number; readonly replacement: string };
+
+const commonPrefix = (left: string, right: string): number => {
+  const limit = Math.min(left.length, right.length);
+  const differs = [...Array(limit).keys()].find((at) => left[at] !== right[at]);
+  return differs ?? limit;
+};
+
+/** 二つの形の違う所。前の同じ字を先に除き、残りから後ろの同じ字を除く（「ですす」と「です」は、後ろの「す」を足した所）。 */
+export const editBetween = (wrong: string, right: string): Edit => {
+  const start = commonPrefix(wrong, right);
+  const tail = commonPrefix(Array.from(wrong.slice(start)).reverse().join(""), Array.from(right.slice(start)).reverse().join(""));
+  return { start, end: wrong.length - tail, replacement: right.slice(start, right.length - tail) };
+};
+
+/** 指す字と、そこに入る正しい形。指す字は、書いた字の頭から。 */
+export type Correction = { readonly matched: string; readonly suggestion: string };
+
+const capitalised = (word: string): string => `${word.charAt(0).toUpperCase()}${word.slice(1)}`;
+
+const isAllCapitals = (word: string): boolean => /\p{Lu}.*\p{Lu}/u.test(word) && !/\p{Ll}/u.test(word);
+
+/** 書いた語の大文字に合わせる（文頭の "Teh" には "The"、"TEH" には "THE"）。 */
+const casedLike = (written: string, suggestion: string): string => {
+  if (isAllCapitals(written)) return suggestion.toUpperCase();
+  return /^\p{Lu}/u.test(written) && /^\p{Ll}/u.test(suggestion) ? capitalised(suggestion) : suggestion;
+};
+
+/**
+ * 書いた字（written）に、語彙表の組の違い（edit）を当てる。boundaries は written の中の語の終わりの位置で、written.length を含む。
+ * 指すのは written の頭から、違う所を含む語の終わりまで。後ろに続く前後の語は言わない（「以外と簡単」は「以外」を「意外」に、
+ * 活用した「始めて会った」は「始めて」を「初めて」に）。written の頭が誤った形の違う所まで同じでなければ（活用で字が変わった）undefined。
+ */
+export const correctionIn = (written: string, wrong: string, edit: Edit, boundaries: readonly number[]): Correction | undefined => {
+  if (written.slice(0, edit.end).toLowerCase() !== wrong.slice(0, edit.end).toLowerCase()) return undefined;
+  const end = Math.min(written.length, ...boundaries.filter((at) => at >= edit.end));
+  const matched = written.slice(0, end);
+  const suggestion = `${matched.slice(0, edit.start)}${edit.replacement}${matched.slice(edit.end)}`;
+  return { matched, suggestion: casedLike(matched, suggestion) };
+};