chaffjs 0.19.0 → 0.21.0

package/src/grade-api.ts

@@ -0,0 +1,184 @@
+// `chaffjs/grade`: chaff's grader for an in-process eval harness (spec §29.6). One output at a time, with the same
+// result as one line of `chaff grade --out`: both go through gradeItem with the same settings and stamp. A separate entry
+// from `chaffjs/api`, so the plugin API's version and the result's shape are not bound to one number.
+import { statSync } from "node:fs";
+import { resolve } from "node:path";
+import { packageFor } from "./adapter-load.ts";
+import { CLI_TEXT } from "./cli-text.ts";
+import { EMPTY, loadConfig, type Config } from "./config/load.ts";
+import { withStyle } from "./config/style.ts";
+import { withExtensions } from "./extension/load.ts";
+import { GENRES } from "./genre.ts";
+import { gradeItem, type GradeSetup } from "./grade/grade-item.ts";
+import { readItem } from "./grade/item.ts";
+import type { GradeResult } from "./grade/result.ts";
+import { parseRubric, type Rubric } from "./grade/rubric.ts";
+import { gradeSetup } from "./grade/setup.ts";
+import { GRADE_TEXT } from "./grade/text.ts";
+import { compareVariantGroups, type VariantComparison } from "./grade/variants.ts";
+import { variantGroupsOf, type VariantInput } from "./grade/variants-input.ts";
+import { settingProblems } from "./setting-problems.ts";
+import { loadStyles } from "./style-load.ts";
+
+export type {
+  FailedCitation,
+  GradeCitations,
+  GradeContexts,
+  GradeFact,
+  GradeFacts,
+  GradeFinding,
+  GradeResult,
+  GradeScore,
+  NotRunEntry,
+  ScoreItem,
+  Stamp,
+  SupportedFact,
+} from "./grade/result.ts";
+export type { OutputSize } from "./grade/rates.ts";
+export { toScorer, type ChaffScore } from "./grade/scorer.ts";
+export type { Disagreement, VariantColumn, VariantComparison, VariantRates } from "./grade/variants.ts";
+export type { VariantInput } from "./grade/variants-input.ts";
+
+export type GradeOptions = {
+  /** The result's id. "output" when left out. */
+  readonly id?: string;
+  /** The document the output was made from: facts are checked against it, as `chaff compare` does. */
+  readonly reference?: string;
+  /** Each source's name and text. */
+  readonly sources?: Readonly<Record<string, string>>;
+  /** What the output quoted. `source` may be left out when there is one source. */
+  readonly citations?: readonly { readonly source?: string; readonly address: string; readonly quote: string }[];
+  /** The retrieved passages the output was meant to rest on: each fact of the output is looked for in them. */
+  readonly contexts?: readonly string[];
+  readonly language?: string;
+  readonly genre?: string;
+  /** The prompt, model or setting that produced the output, kept on the result for compareVariants(). */
+  readonly variant?: string;
+  /** Run the experimental rules too, as --experimental does. chaff.yaml's `experimental` when left out. */
+  readonly experimental?: boolean;
+  /** chaff.yaml's path, or settings already read. Without it chaff's defaults apply and no file is read. */
+  readonly config?: string | Config;
+};
+
+/** An input or a chaff.yaml grade() cannot use: the same cases end `chaff grade` with exit 2. */
+export class GradeInputError extends Error {
+  readonly problems: readonly string[];
+
+  constructor(problems: readonly string[]) {
+    super(problems.join("\n"));
+    this.name = "GradeInputError";
+    this.problems = problems;
+  }
+}
+
+const TEXT = GRADE_TEXT.en;
+
+/** Each chaff.yaml read, by its path and when it was last changed: one file is read and its code loaded once. */
+const readConfigs = new Map<string, Config>();
+
+const KEPT = 16;
+
+/** Adds to a cache, dropping the oldest entry past KEPT. */
+const remember = <T>(cache: Map<string, T>, key: string, value: T): T => {
+  cache.set(key, value);
+  const [oldest] = cache.keys();
+  if (cache.size > KEPT && oldest !== undefined) cache.delete(oldest);
+  return value;
+};
+
+/** chaff.yaml read as the command line reads it: its style applied and the code it names loaded. */
+const readConfig = async (path: string): Promise<Config> => {
+  const file = resolve(path);
+  const key = `${file}\n${String(statSync(file).mtimeMs)}`;
+  return readConfigs.get(key) ?? remember(readConfigs, key, await withExtensions(withStyle(loadConfig(file), loadStyles())));
+};
+
+/** A chaff.yaml that is missing or not YAML is an input grade() cannot use, as it is for the command line. */
+const readNamedConfig = async (path: string): Promise<Config> => {
+  try {
+    return await readConfig(path);
+  } catch (error) {
+    throw new GradeInputError([TEXT.unreadable(path, error instanceof Error ? error.message : String(error))]);
+  }
+};
+
+/** The settings to grade with, checked as the command line checks them, whether read here or given already read. */
+const configOf = async (given: string | Config | undefined): Promise<Config> => {
+  if (given === undefined) return EMPTY;
+  const config = typeof given === "string" ? await readNamedConfig(given) : given;
+  const problems = settingProblems("grade", undefined, config, CLI_TEXT.en);
+  if (problems.length > 0) throw new GradeInputError(problems);
+  return config;
+};
+
+const rubricOf = (config: Config): Rubric | undefined => {
+  const parsed = parseRubric(config.grade);
+  if ("problems" in parsed) throw new GradeInputError(parsed.problems.map((problem) => TEXT.rubricProblem(problem)));
+  return parsed.rubric;
+};
+
+/**
+ * Setups for each settings object, by what else decides them, so a harness grading many outputs loads the language
+ * packages and hashes the rules once. Keyed by the object itself: two chaff.yaml files that read alike may load other code.
+ */
+const setups = new WeakMap<Config, Map<string, Promise<GradeSetup>>>();
+
+const setupFor = (config: Config, experimental: boolean, languages: readonly string[]): Promise<GradeSetup> => {
+  const run = { experimental, genre: undefined };
+  const own = setups.get(config) ?? new Map<string, Promise<GradeSetup>>();
+  setups.set(config, own);
+  const key = `${String(experimental)}\n${languages.join(",")}`;
+  const known = own.get(key);
+  if (known !== undefined) return known;
+  const made = remember(own, key, gradeSetup(config, run, languages, rubricOf(config)));
+  // A language package that failed to load may be installed before the next call: do not keep the failure.
+  made.catch(() => own.delete(key));
+  return made;
+};
+
+/** The setup, or GradeInputError when a language package cannot be loaded, as `chaff grade` ends with 2 then. */
+const loadedSetup = async (config: Config, experimental: boolean, languages: readonly string[]): Promise<GradeSetup> => {
+  try {
+    return await setupFor(config, experimental, languages);
+  } catch (error) {
+    if (error instanceof GradeInputError) throw error;
+    throw new GradeInputError([TEXT.cannotLoad(error instanceof Error ? error.message : String(error))]);
+  }
+};
+
+/**
+ * Grades one output (spec §29.6): its findings and rates, its facts against `reference`, its `citations` against
+ * `sources`, and pass or fail by chaff.yaml's `grade:` or the default. Reads a file only when `config` is a path, and
+ * never writes one. Throws GradeInputError for an input or a chaff.yaml `chaff grade` would refuse with exit 2.
+ */
+export const grade = async (output: string, options: GradeOptions = {}): Promise<GradeResult> => {
+  const config = await configOf(options.config);
+  const raw = {
+    id: options.id ?? "output",
+    output,
+    reference: options.reference,
+    sources: options.sources,
+    citations: options.citations,
+    contexts: options.contexts,
+    language: options.language,
+    genre: options.genre,
+    variant: options.variant,
+  };
+  const read = readItem(raw, { isLanguage: (language) => packageFor(language) !== undefined, genres: GENRES });
+  if ("problem" in read) throw new GradeInputError([TEXT.problem(read.problem)]);
+  const languages = read.item.language === undefined ? [] : [read.item.language];
+  return gradeItem(read.item, await loadedSetup(config, options.experimental ?? config.experimental, languages));
+};
+
+/**
+ * Several variants' results side by side on the same inputs (spec §29.5), as `chaff grade` prints them for a file whose
+ * lines carry a variant: per variant the pass rate, each rule's rate, facts dropped and added, and failed quotations,
+ * over the ids every variant answered; and the ids where pass or fail differs. Takes results labelled by `variant`
+ * (grade() with `variant`, or `chaff grade --out`), or `{ [variant]: results }`. Throws GradeInputError for a result
+ * without an id or a variant, or an id given twice in one variant.
+ */
+export const compareVariants = (results: VariantInput): VariantComparison => {
+  const read = variantGroupsOf(results);
+  if ("problems" in read) throw new GradeInputError(read.problems);
+  return compareVariantGroups(read.groups);
+};

package/src/heading-numbering.ts

@@ -0,0 +1,106 @@
+// 見出しの番号の付け方。純粋な関数だけを置く。どの語が番号を持つか（第1章、Chapter 1）と、番号を付けない前後の見出し
+// （目次、参考文献）は言語パッケージの語彙表が言う。
+
+/** 番号の無い見出しの書き方。ほかの書き方は "dot"（1.）や "label:章"（第1章）のように、番号を持つ語ごとに分ける。 */
+export const UNNUMBERED = "none";
+
+/** 番号を持つ語。before は語が番号の前（Chapter 1、ステップ1）、after は番号の後ろ（第1章、1章）。 */
+export type NumberLabel = { readonly word: string; readonly position: "before" | "after" };
+
+const ARABIC = "[0-9０-９]+";
+const KANJI = "[一二三四五六七八九十百]+";
+const ROMAN = "[IVXⅠ-Ⅻ]+";
+
+/** 番号の後ろに続く見出しの言葉の頭。字で始まる。「8.2.3 (2026-08-06)」の版や「3 reasons」の数量は番号と読まない。 */
+const WORDS_FOLLOW = "(?=\\s*[\\p{L}])";
+
+/**
+ * 字だけで決まる書き方。上から順に試す。ラテン文字一字とローマ数字（A. と II.）は同じ書き方とする。どちらも番号の後ろに言葉が続くときだけ。
+ * 区切りの記号の無い数（「1 Introduction」）は数量（「10 reasons」）と見分けられないので読まない。
+ */
+const SHAPES: ReadonlyArray<readonly [string, RegExp]> = [
+  ["paren", /^[(（][0-9０-９]+[)）]/u],
+  ["close-paren", /^[0-9０-９]+[)）]/u],
+  ["dot", new RegExp(`^${ARABIC}[a-z]?(?:[.．]${ARABIC})*[.．](?![0-9０-９])${WORDS_FOLLOW}`, "u")],
+  ["dotted", new RegExp(`^${ARABIC}(?:[.．]${ARABIC})+\\s${WORDS_FOLLOW}`, "u")],
+  ["circled", /^[①-⑳]/u],
+  ["kanji", /^[一二三四五六七八九十]+[、.．]/u],
+  ["letter", /^(?:[IVX]+|[A-Z])[.)]\s+(?=\p{L})/u],
+];
+
+const escaped = (word: string): string => word.replace(/[.*+?^${}()|[\]\\]/gu, "\\$&");
+
+/** 番号を持つ語は書いたとおりか、全部大文字で照らす（Chapter と CHAPTER。小文字の section は本文の語）。 */
+const casings = (word: string): string => [...new Set([word, word.toUpperCase()])].map(escaped).join("|");
+
+const labelPattern = (label: NumberLabel): RegExp =>
+  label.position === "before"
+    ? new RegExp(`^(?:${casings(label.word)})(?:\\s*(?:${ARABIC}|${KANJI}|${ROMAN})|\\s+[A-Z])(?![A-Za-z])`, "u")
+    : new RegExp(`^(?:第(?:${ARABIC}|${KANJI}|${ROMAN})|${ARABIC})${escaped(label.word)}`, "u");
+
+/** 見出しの頭の強調の印と空白。「**1. 概要**」も「1. 概要」と読む。 */
+const LEAD = /^[\s*_]+/u;
+
+/** 見出しの言葉から、番号の書き方を読む。番号を持つ語（第1章）を先に、字だけの形（1.）を後に見る。 */
+export const numberingStyleOf = (heading: string, labels: readonly NumberLabel[]): string => {
+  const text = heading.replace(LEAD, "");
+  const label = labels.find((candidate) => labelPattern(candidate).test(text));
+  if (label !== undefined) return `label:${label.word.toLowerCase()}`;
+  return SHAPES.find(([, shape]) => shape.test(text))?.[0] ?? UNNUMBERED;
+};
+
+/** 見出し 1 つ。depth は深さ（#の数）、style は番号の書き方、skipped は番号を付けない前後の見出し（目次・参考文献）。 */
+export type NumberedHeading = { readonly depth: number; readonly style: string; readonly skipped: boolean };
+
+/** 親（直前の浅い見出し）と深さが同じ見出しの組。番号は兄弟の見出しのあいだで揃える。位置は渡した並びの添え字。 */
+export const siblingGroups = (headings: readonly NumberedHeading[]): number[][] => {
+  const parents = headings.map((heading, at) => headings.slice(0, at).findLastIndex((before) => before.depth < heading.depth));
+  const groups = new Map<string, number[]>();
+  headings.forEach((heading, at) => {
+    const key = `${String(parents[at])}:${String(heading.depth)}`;
+    groups.set(key, [...(groups.get(key) ?? []), at]);
+  });
+  return [...groups.values()];
+};
+
+/** 指す見出しと、何に対して少ないか。kind は numbered（番号の有無）か style（番号の書き方）。majority は多いほうの書き方で、count はその数。 */
+export type NumberingMinority = {
+  readonly at: number;
+  readonly kind: "numbered" | "style";
+  readonly majority: string;
+  readonly count: number;
+  /** 多いほうの書き方の、最初の兄弟の位置。指摘が例に引く。 */
+  readonly example: number;
+};
+
+type Split = { readonly minority: readonly number[]; readonly majority: string; readonly count: number; readonly example: number };
+
+const minorityBy = (members: readonly number[], keyOf: (at: number) => string): Split | undefined => {
+  const counts = new Map<string, number>();
+  members.forEach((at) => counts.set(keyOf(at), (counts.get(keyOf(at)) ?? 0) + 1));
+  const [top, second] = [...counts].toSorted((left, right) => right[1] - left[1]);
+  if (top === undefined || second === undefined || top[1] === second[1]) return undefined;
+  const example = members.find((at) => keyOf(at) === top[0]) ?? -1;
+  return { minority: members.filter((at) => keyOf(at) !== top[0]), majority: top[0], count: top[1], example };
+};
+
+const minoritiesOf = (split: Split | undefined, kind: NumberingMinority["kind"]): NumberingMinority[] =>
+  split === undefined ? [] : split.minority.map((at) => ({ at, kind, majority: split.majority, count: split.count, example: split.example }));
+
+/**
+ * 兄弟の見出しのうち、少ないほうの書き方のもの。先に番号の有無を比べ（「1. 概要」「2. 手順」「まとめ」の「まとめ」）、
+ * 番号の付いた見出しのあいだで書き方を比べる（「1.」「2.」「3）」の「3）」）。同じ数なら言わない（二つだけの兄弟は必ず同じ数か一つの書き方）。前後の見出し（目次・参考文献）は数えない。
+ */
+export const numberingMinorities = (headings: readonly NumberedHeading[]): NumberingMinority[] =>
+  siblingGroups(headings).flatMap((group) => {
+    const members = group.filter((at) => headings[at]?.skipped !== true);
+    const styleOf = (at: number): string => headings[at]?.style ?? UNNUMBERED;
+    const numbered = members.filter((at) => styleOf(at) !== UNNUMBERED);
+    return [
+      ...minoritiesOf(
+        minorityBy(members, (at) => (styleOf(at) === UNNUMBERED ? UNNUMBERED : "numbered")),
+        "numbered",
+      ),
+      ...minoritiesOf(minorityBy(numbered, styleOf), "style"),
+    ];
+  });

package/src/init.ts

@@ -30,9 +30,9 @@ const TEXT: Texts<{
 #
 # コマンドでも変更できます。理由がコメントとして自動で残ります。
 #
-#   npx chaff relax bold-density --why "図の説明で太字を多用するため"
-#   npx chaff explain bold-density        そのルールの意図を読む
-#   npx chaff rules --json                AI に設定を書かせるときに渡す
+#   npx chaffjs relax bold-density --why "図の説明で太字を多用するため"
+#   npx chaffjs explain bold-density        そのルールの意図を読む
+#   npx chaffjs rules --json                AI に設定を書かせるときに渡す
 
 # この場所に置く文書の種類（${summary}）。ほかの種類: npx chaffjs genres
 genre: ${genre}
@@ -50,9 +50,9 @@ rules:
     exists: "chaff.yaml は既にあります。変更していません。",
     createdHeading: "作成しました:",
     genreChosen: (genre) => `ジャンルは ${genre} にしました。違う場合は chaff.yaml の genre を直してください。`,
-    genreList: "  一覧: npx chaff genres",
+    genreList: "  一覧: npx chaffjs genres",
     next: "次:",
-    nextCheck: "  npx chaff .            この場所の Markdown を全部見る",
+    nextCheck: "  npx chaffjs .            この場所の Markdown を全部見る",
   },
   en: {
     config: (genre, summary) => `# chaff.yaml — this team's writing rules
@@ -69,9 +69,9 @@ rules:
 #
 # Commands change it too, and leave the reason as a comment.
 #
-#   npx chaff relax bold-density --why "figure captions use a lot of bold"
-#   npx chaff explain bold-density        read what the rule is for
-#   npx chaff rules --json                give this to an AI that writes the settings
+#   npx chaffjs relax bold-density --why "figure captions use a lot of bold"
+#   npx chaffjs explain bold-density        read what the rule is for
+#   npx chaffjs rules --json                give this to an AI that writes the settings
 
 # The kind of document kept here (${summary}). The others: npx chaffjs genres
 genre: ${genre}
@@ -89,9 +89,9 @@ rules:
     exists: "chaff.yaml already exists. Nothing was changed.",
     createdHeading: "Created:",
     genreChosen: (genre) => `The genre is ${genre}. If that is wrong, change genre in chaff.yaml.`,
-    genreList: "  List: npx chaff genres",
+    genreList: "  List: npx chaffjs genres",
     next: "Next:",
-    nextCheck: "  npx chaff .            check every Markdown file here",
+    nextCheck: "  npx chaffjs .            check every Markdown file here",
   },
 };
 

package/src/kana-spelling.ts

@@ -0,0 +1,49 @@
+// Keys that make two Japanese spellings of one word meet: the reading of the dictionary form (出来る and できる are both デキル),
+// the kanji a spelling keeps (引っ越し and 引越し both keep 引越), and a katakana word with its small kana and ー evened out
+// (ウィンドウ and ウインドウ). Pure: the tokens come in from the language adapter.
+
+const HIRAGANA_TO_KATAKANA = 0x60;
+const HIRAGANA = /[ぁ-ゖ]/gu;
+const KANA_ONLY = /^[ぁ-ゖァ-ヺー]+$/u;
+const KANJI = /[\p{Script=Han}々]/gu;
+
+/** Hiragana as katakana, the script the adapter reads in. */
+export const toKatakana = (text: string): string => text.replace(HIRAGANA, (char) => String.fromCodePoint((char.codePointAt(0) ?? 0) + HIRAGANA_TO_KATAKANA));
+
+export const isKanaOnly = (text: string): boolean => KANA_ONLY.test(text);
+
+/** The kanji of a spelling, in order: 引越 for both 引っ越し and 引越し, nothing for できる. */
+export const kanjiSkeleton = (text: string): string => [...text.matchAll(KANJI)].map((match) => match[0]).join("");
+
+/** The length, in UTF-16 units, of the start both strings share, compared character by character (𠮟 is one character, two units). */
+const sharedPrefixLength = (left: string, right: string): number => {
+  const [leftChars, rightChars] = [[...left], [...right]];
+  const differs = leftChars.findIndex((char, at) => rightChars[at] !== char);
+  const shared = differs === -1 ? leftChars.slice(0, rightChars.length) : leftChars.slice(0, differs);
+  return shared.join("").length;
+};
+
+/**
+ * The reading of the dictionary form, from the reading of the written form: 下さい (クダサイ) with lemma 下さる reads クダサル.
+ * The written form and the lemma differ only in their kana ending, so that ending is swapped in the reading. When the ending is
+ * not kana, or the reading does not end with it (来 read キ for 来る), there is no answer.
+ */
+export const lemmaReading = (surface: string, lemma: string, reading: string): string | undefined => {
+  const shared = sharedPrefixLength(surface, lemma);
+  const [writtenEnd, lemmaEnd] = [surface.slice(shared), lemma.slice(shared)];
+  if ((writtenEnd !== "" && !isKanaOnly(writtenEnd)) || (lemmaEnd !== "" && !isKanaOnly(lemmaEnd))) return undefined;
+  const spoken = toKatakana(writtenEnd);
+  if (!reading.endsWith(spoken)) return undefined;
+  return reading.slice(0, reading.length - spoken.length) + toKatakana(lemmaEnd);
+};
+
+const SMALL_TO_LARGE: Readonly<Record<string, string>> = { ァ: "ア", ィ: "イ", ゥ: "ウ", ェ: "エ", ォ: "オ", ヵ: "カ", ヶ: "ケ", ヮ: "ワ" };
+const VU: Readonly<Record<string, string>> = { ヴァ: "バ", ヴィ: "ビ", ヴェ: "ベ", ヴォ: "ボ", ヴ: "ブ" };
+
+/** A katakana word with ー dropped, small vowels made large, ヴ read as バ行 and エイ as エ: インターフェース and インタフェイス meet. */
+export const katakanaKey = (surface: string): string =>
+  surface
+    .replace(/ヴ[ァィェォ]?/gu, (match) => VU[match] ?? match)
+    .replace(/[ァィゥェォヵヶヮ]/gu, (char) => SMALL_TO_LARGE[char] ?? char)
+    .replace(/ー/gu, "")
+    .replace(/エイ/gu, "エ");

package/src/known-genres.ts

@@ -0,0 +1,19 @@
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import { parse } from "yaml";
+import { loadGenres } from "./genre-load.ts";
+import { parseGenres, type GenreData } from "./genre-parse.ts";
+
+const idsOf = (data: GenreData): string[] => [...data.groups.map((group) => group.id), ...data.genres.map((genre) => genre.id)];
+
+/** Every genre and genre group genres.yaml names: what a rule's use_for may list. */
+export const knownGenres = (): string[] => idsOf(loadGenres());
+
+/**
+ * The genres of the genres.yaml beside a rules folder (packages/chaff/rules → packages/chaff/genres.yaml), else chaff's
+ * own. The site reads the rules from the source tree after bundling, where chaff's own file is not where the module is.
+ */
+export const genresBeside = (rulesDir: string): string[] => {
+  const file = join(rulesDir, "..", "genres.yaml");
+  return existsSync(file) ? idsOf(parseGenres(parse(readFileSync(file, "utf8")))) : knownGenres();
+};

package/src/link-shape.ts

@@ -0,0 +1,62 @@
+// What a link's text and an image's alt text look like: a URL, a host, a file name. Pure functions only.
+
+/** Link text that reads as an address: it starts with a scheme or with `www.`. A bare `README.md` is a file, not a host. */
+const URL_TEXT = /^(?:https?:\/\/|www\.)[^\s]+$/iu;
+
+/** Marks around a link's text that are not part of the address it shows (`**https://…**`, `` `https://…` ``, `<…>`). */
+const LEADING = new Set(" \t\n*_`<「『\"“'");
+const TRAILING = new Set(" \t\n*_`>」』\"”'.。,，、");
+
+/** The text as the reader sees the address, without emphasis, code marks, quotes or closing punctuation. */
+export const shownAddress = (text: string): string => {
+  const chars = [...text];
+  const start = chars.findIndex((char) => !LEADING.has(char));
+  return start === -1 ? "" : chars.slice(start, chars.findLastIndex((char) => !TRAILING.has(char)) + 1).join("");
+};
+
+/** Whether a link's text is itself an address. */
+export const isUrlText = (text: string): boolean => URL_TEXT.test(shownAddress(text));
+
+const WWW = /^www\./iu;
+const WEB_SCHEME = /^https?:\/\//iu;
+
+/** The host an address names, lower case and without `www.`; undefined for a relative path, a fragment or a mail address. */
+export const hostOf = (address: string): string | undefined => {
+  const written = shownAddress(address);
+  const absolute = WWW.test(written) ? `https://${written}` : written;
+  if (!WEB_SCHEME.test(absolute)) return undefined;
+  try {
+    return new URL(absolute).hostname.toLowerCase().replace(WWW, "");
+  } catch {
+    return undefined;
+  }
+};
+
+/**
+ * The host a link's text shows, when it differs from the host the link goes to. Both must be absolute web addresses;
+ * a shortened display of the same host (`github.com/a` for `https://github.com/a/b/tree/main`) is the same host.
+ */
+export const mismatchedHost = (text: string, destination: string): { readonly shown: string; readonly target: string } | undefined => {
+  if (!isUrlText(text)) return undefined;
+  const shown = hostOf(text);
+  const target = hostOf(destination);
+  return shown === undefined || target === undefined || shown === target ? undefined : { shown, target };
+};
+
+/** The extensions of image files. An alt text that ends in one is the file's name. */
+const IMAGE_FILE = /\.(?:png|jpe?g|gif|svg|webp|bmp|tiff?|heic|heif|avif|ico)$/iu;
+
+/** After a camera's or a screenshot tool's name: separators, then the number it counts with (`IMG_1234`, `Screenshot 2026-…`). */
+const COUNTER = /^[\s_-]*\d/u;
+
+/**
+ * Whether an alt text is a file's name rather than a description: it ends in an image extension (`IMG_1234.png`), or it
+ * starts with a name a camera or a screenshot tool gives (`prefixes`, from the language's lexicon) followed by its number.
+ */
+export const isFileNameAlt = (alt: string, prefixes: readonly string[]): boolean => {
+  const written = alt.trim();
+  if (written === "") return false;
+  if (IMAGE_FILE.test(written)) return true;
+  const lowered = written.toLowerCase();
+  return prefixes.some((prefix) => lowered.startsWith(prefix.toLowerCase()) && COUNTER.test(written.slice(prefix.length)));
+};

package/src/link-text.ts

@@ -0,0 +1,46 @@
+// リンクの言葉（`[こちら](url)` の「こちら」）を読む。純粋な関数だけを置く。
+
+/** `[` から、対応する `]` の位置。入れ子の角括弧（`[a [b] c]`）を数える。閉じなければ undefined。 */
+const closingBracket = (written: string): number | undefined => {
+  let depth = 0;
+  for (const [at, char] of [...written].entries()) {
+    if (char === "[") depth += 1;
+    if (char === "]") depth -= 1;
+    if (depth === 0) return at;
+  }
+  return undefined;
+};
+
+/**
+ * インラインのリンク（`[言葉](行き先)`）の言葉。参照の定義（`[1]: url`）と自動リンク（`<https://…>`）は言葉を持たないので undefined。
+ * 位置は字（コードポイント）で数える。
+ */
+export const linkTextOf = (written: string): string | undefined => {
+  if (!written.startsWith("[")) return undefined;
+  const close = closingBracket(written);
+  const chars = [...written];
+  if (close === undefined || chars[close + 1] !== "(") return undefined;
+  return chars.slice(1, close).join("");
+};
+
+/** 言葉を包む強調の印と鉤括弧（前後とも）、終わりの句読点（後ろだけ）。「**こちら**」も「こちら。」も「こちら」と読む。 */
+const LEADING = new Set(" \t\n*_「『\"“'");
+const TRAILING = new Set([...LEADING, ..."」』”。．.、，,!！?？:："]);
+
+const trimmed = (chars: readonly string[]): string => {
+  const start = chars.findIndex((char) => !LEADING.has(char));
+  if (start === -1) return "";
+  return chars.slice(start, chars.findLastIndex((char) => !TRAILING.has(char)) + 1).join("");
+};
+
+/** Markdown の逃がし（`here\\.`）。字はそのまま見えるので、逃がしの印だけを外す。 */
+const ESCAPED = /\\(\p{P})/gu;
+
+/** 見せる形。逃がしの印と、強調と鉤括弧と終わりの句読点を外し、空白をまとめる。コードの印（`）は外さない。コードの言葉は語ではない。 */
+export const bareLinkText = (text: string): string => trimmed([...text.replace(ESCAPED, "$1")]).replace(/\s+/gu, " ");
+
+/** 比べる形。見せる形を小文字にしたもの。 */
+export const comparableLinkText = (text: string): string => bareLinkText(text).toLowerCase();
+
+/** リンクの言葉が、それだけでは行き先を言わない言葉（語彙表の語）そのものか。言葉の一部に含むだけ（「料金表はこちら」）なら違う。 */
+export const isVagueLinkText = (text: string, vague: ReadonlySet<string>): boolean => vague.has(comparableLinkText(text));

package/src/outline/render.ts

@@ -1,9 +1,11 @@
 import type { LengthUnit } from "../plugin.ts";
 import type { Outline, OutlineEntry, Shape } from "./shape.ts";
 import type { OutlineText } from "./text.ts";
+import type { StructureScore } from "../structure-shape/score.ts";
+import { structureChangeLines, structureCompact, structureJson, structureLines } from "./structure-render.ts";
 
-/** One file's outline as `chaff outline` shows it. */
-export type DocumentOutline = { readonly path: string; readonly language: string; readonly outline: Outline };
+/** One file's outline as `chaff outline` shows it, with its structure measures placed against human articles. */
+export type DocumentOutline = { readonly path: string; readonly language: string; readonly outline: Outline; readonly structure: StructureScore };
 
 type Measure = { readonly name: string; readonly value: (shape: Shape, unit: LengthUnit) => string };
 
@@ -37,6 +39,8 @@ const outlineBlock = (document: DocumentOutline, text: OutlineText): string[] =>
   shapeLine(document, text),
   "",
   ...document.outline.entries.map((entry) => entryLine(entry, document, text)),
+  "",
+  ...structureLines(document.structure, document.language, document.outline.unit, text.structure),
 ];
 
 /** Each measure before and after, so a restructure shows as numbers that moved. */
@@ -46,6 +50,7 @@ const changeBlock = (before: DocumentOutline, after: DocumentOutline, text: Outl
   ...measuresOf(text).map(
     (measure) => `  ${measure.name}: ${measure.value(before.outline.shape, before.outline.unit)} → ${measure.value(after.outline.shape, after.outline.unit)}`,
   ),
+  ...structureChangeLines(before.structure, after.structure, [before.outline.unit, after.outline.unit], text.structure),
 ];
 
 /** For a person: each file's shape and outline, then, for two files, how each measure moved. */
@@ -67,6 +72,7 @@ export const renderOutlineCompact = (documents: readonly DocumentOutline[], text
   [
     ...documents.flatMap((document) => document.outline.entries.map((entry) => compactEntry(entry, document))),
     ...documents.map((document) => shapeLine(document, text)),
+    ...documents.map((document) => structureCompact(document.path, document.structure)),
   ].join("\n");
 
 const outlineJson = (document: DocumentOutline): Readonly<Record<string, unknown>> => ({
@@ -75,6 +81,7 @@ const outlineJson = (document: DocumentOutline): Readonly<Record<string, unknown
   unit: document.outline.unit,
   shape: document.outline.shape,
   outline: document.outline.entries,
+  structure: structureJson(document.structure),
 });
 
 /** For an AI: one file's outline and shape, or `before` and `after` for two. */