chaffjs 0.18.0 → 0.20.0

package/src/commands/feedback.ts

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

package/src/commands/fix-plan.ts

@@ -0,0 +1,55 @@
+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 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"]);
+
+export const fixPlanTargets = (argv: readonly string[]): string[] =>
+  argv.slice(1).filter((arg, index, all) => !arg.startsWith("--") && !VALUED.has(all[index - 1] ?? ""));
+
+export type FixPlanContext = TreeContext & {
+  /** The file's findings as lint finds them, shelved ones included. */
+  readonly check: (path: string) => Promise<Omit<Checked, "conditions">>;
+};
+
+/**
+ * An instruction document for whoever rewrites the file: the findings grouped by rule, each rule's rewrite direction,
+ * 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> => {
+  const [path] = targets;
+  if (path === undefined || targets.length > 1) {
+    console.error(FIX_PLAN_TEXT[context.ui ?? "ja"].usage);
+    return 1;
+  }
+  if (!existsSync(path)) {
+    console.error(FIX_PLAN_TEXT[context.ui ?? "ja"].notFound(path));
+    return 1;
+  }
+  const checked = await context.check(path);
+  // The outline is read in the language lint chose, so the plan's findings and its outline describe one reading.
+  const prose = await readDocument(path, ["fix-plan", "--language", checked.language, ...argv.slice(1)], context, false);
+  if (prose === undefined) return 1;
+  const plan = buildFixPlan({
+    path,
+    language: checked.language,
+    genre: checked.genre,
+    experimental: context.config.experimental || argv.includes("--experimental"),
+    genreFlag: context.flag(argv, "--genre"),
+    findings: checked.findings,
+    rules: checked.rules,
+    skipped: checked.skipped,
+    outline: outlineOf(prose.doc),
+    structure: structureOf(prose.doc),
+    phrases: prose.doc.lexicons["ai-tell"] ?? [],
+  });
+  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/outline.ts

@@ -0,0 +1,50 @@
+import { uiLanguageOf } from "../ui.ts";
+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. */
+const VALUED: ReadonlySet<string> = new Set(["--language", "--genre"]);
+
+export const outlineTargets = (argv: readonly string[]): string[] =>
+  argv.slice(1).filter((arg, index, all) => !arg.startsWith("--") && !VALUED.has(all[index - 1] ?? ""));
+
+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), structure: structureOf(prose.doc) };
+};
+
+/** The files in the order given, or undefined once one cannot be read (its error is already printed). */
+const readAll = async (paths: readonly string[], argv: readonly string[], context: TreeContext): Promise<DocumentOutline[] | undefined> =>
+  paths.reduce<Promise<DocumentOutline[] | undefined>>(async (previous, path) => {
+    const earlier = await previous;
+    if (earlier === undefined) return undefined;
+    const next = await readOutline(path, argv, context);
+    return next === undefined ? undefined : [...earlier, next];
+  }, Promise.resolve([]));
+
+const renderFor = (argv: readonly string[], documents: readonly DocumentOutline[]): string => {
+  const text = OUTLINE_TEXT[uiLanguageOf(documents[0]?.language)];
+  if (argv.includes("--json")) return renderOutlineJson(documents);
+  return argv.includes("--compact") ? renderOutlineCompact(documents, text) : renderOutlineFriendly(documents, text);
+};
+
+/**
+ * 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) {
+    console.error(OUTLINE_TEXT[context.ui ?? "ja"].usage);
+    return 1;
+  }
+  const documents = await readAll(targets, argv, context);
+  if (documents === undefined) return 1;
+  console.log(renderFor(argv, documents));
+  return 0;
+};

package/src/commands/read-document.ts

@@ -0,0 +1,33 @@
+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 };
+
+/** 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 genre = resolveGenre(path, source, context.config, context.flag(argv, "--genre")).genre;
+  return documentFromSource(path, source, { language, genre }, context.config, pos);
+};

package/src/commands/suppressions.ts

@@ -0,0 +1,20 @@
+import { collectTargets } from "../files.ts";
+import { renderSuppressions, type PerFile } from "../render/suppressions.ts";
+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[],
+  inspectRun: (paths: readonly string[]) => Promise<readonly { readonly perFile: PerFile }[]>,
+  ui: UiLanguage,
+  include: readonly string[] = [],
+): Promise<number> => {
+  const inspected = await inspectRun(collectTargets(targets.length > 0 ? targets : ["."], include));
+  console.log(
+    renderSuppressions(
+      inspected.map((file) => file.perFile),
+      ui,
+    ),
+  );
+  return 0;
+};

package/src/commands/test.ts

@@ -91,7 +91,7 @@ const semanticDocument = async (path: string, config: Config, resolveGenre: Test
   const { genre } = resolveGenre(path, source, config);
   const rules = loadRules(language);
   await adapter.prepare?.(semanticNeeds(rules, config.rules, genre));
-  const doc = buildDocument(path, source, adapter, teamRules(config), profileFor(config, path, source, language, genre));
+  const doc = buildDocument(path, source, adapter, teamRules(config, language), profileFor(config, path, source, language, genre));
   return { doc, rules, language, genre };
 };
 
@@ -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/clock-time.ts

@@ -16,8 +16,11 @@ const COLON_TIME = new RegExp(
 /** 3 p.m., 11am. */
 const MERIDIEM_TIME = new RegExp(`(?<![0-9０-９:：])(${DIGIT}{1,2})\\s?([ap])\\.?m\\.?(?![a-z])`, "giu");
 
-/** 午後3時30分, 10時半, 9時. */
-const JAPANESE_TIME = new RegExp(`(午前|午後)?(${DIGIT}{1,2})時(?:(${DIGIT}{1,2})分|(半))?`, "gu");
+/**
+ * 午後3時30分, 10時半, 9時. 時間 is a length of time (8時間), not a time of day, and the hour is not the end of a longer
+ * number (1.2時間, 123時).
+ */
+const JAPANESE_TIME = new RegExp(`(午前|午後)?(?<![0-9０-９.．])(${DIGIT}{1,2})時(?!間)(?:(${DIGIT}{1,2})分|(半))?`, "gu");
 
 const LAST_HOUR = 24;
 const MINUTES_PER_HOUR = 60;

package/src/compare/distinct.ts

@@ -0,0 +1,20 @@
+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
+ * as dropped. A name counts as stated when its spelling is in the other document's text (otherNameText), as when
+ * names are counted.
+ */
+export const unstatedChanges = (changes: readonly Atom[], other: readonly Atom[], otherNameText: string): Atom[] => {
+  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/extract.ts

@@ -5,7 +5,8 @@ import type { Atom, Extraction, Unread } from "./atom.ts";
 import { clockTimes } from "./clock-time.ts";
 import { factTextOf, type FactText } from "./fact-text.ts";
 import { codeAtoms, headingAtoms, urlAtoms } from "./markup-atoms.ts";
-import { nameKey, properNouns, readsProperNouns } from "./proper-nouns.ts";
+import { properNouns, readsProperNouns } from "./proper-nouns.ts";
+import { factKey, seenTextOf, wholeSpanOf } from "./fact-key.ts";
 import { spanIndex } from "./spans.ts";
 import { atomsOf, bareNumbers, footnotes, numericDates, quotations, teamNames, type TextInput } from "./text-atoms.ts";
 import { treeFacts, type TreeFacts } from "./tree-atoms.ts";
@@ -39,16 +40,17 @@ const proseFacts = (input: ExtractInput, readers: Readers, tree: TreeFacts, time
   const { facts, text, lineOf } = readers;
   const marks = footnotes(facts.codeless);
   const dates = numericDates(facts.text, spanIndex([...tree.taken, ...times]));
-  const names = teamNames(facts.text, input.names);
+  const seen = seenTextOf(facts.text, facts.unseen);
+  const names = teamNames(seen.text, input.names).map((found) => wholeSpanOf(seen, found));
   const taken = [...tree.taken, ...times, ...marks, ...dates];
   return [
     ...atomsOf(dates, "date", text),
     ...atomsOf(marks, "footnote", text),
     ...atomsOf(names, "name", text),
     ...bareNumbers(text, spanIndex([...taken, ...facts.listMarkers])),
-    ...quotations(text),
+    ...quotations(text, facts.unseen),
     // "April" in a date and "Section" in a reference are read with them, not again as names.
-    ...properNouns({ doc: input.doc, taken: spanIndex([...taken, ...names, ...facts.blanked]), lineOf }),
+    ...properNouns({ doc: input.doc, taken: spanIndex([...taken, ...names, ...facts.blanked]), lineOf, unseen: facts.unseen }),
   ];
 };
 
@@ -74,5 +76,5 @@ export const extractFacts = (input: ExtractInput): Extraction => {
     ...(input.root === undefined ? [] : codeAtoms(input.root, lineOf)),
     ...headingAtoms(input.doc.markup, lineOf),
   ];
-  return { atoms, unread: unreadOf(input), nameText: nameKey(facts.text) };
+  return { atoms, unread: unreadOf(input), nameText: factKey(facts.text, { start: 0, end: source.length }, facts.unseen) };
 };