chaffjs 0.19.0 → 0.20.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/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/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. */

package/src/outline/structure-render.ts

@@ -0,0 +1,101 @@
+import type { LengthUnit } from "../plugin.ts";
+import type { FeatureValue } from "../structure-shape/features.ts";
+import type { Placement, StructureScore } from "../structure-shape/score.ts";
+import type { StructureText } from "./structure-text.ts";
+
+const BEYOND_MARK = "✗";
+const WITHIN_MARK = "·";
+const NOT_MEASURED = "—";
+
+const valueText = (feature: FeatureValue, unit: LengthUnit, text: StructureText): string =>
+  feature.value === undefined ? NOT_MEASURED : text.features[feature.id].value(feature.value, feature.detail, unit);
+
+const whereText = (placement: Placement, text: StructureText): string => {
+  if (placement.pastShare === undefined) return "";
+  const low = placement.direction === "low";
+  const where = text.past(placement.pastShare, low);
+  if (!placement.beyond || placement.median === undefined || placement.limit === undefined) return `  ${where}`;
+  return `  ${text.aside(where, text.human(String(placement.median), String(placement.limit), low))}`;
+};
+
+const placementLine = (placement: Placement, unit: LengthUnit, text: StructureText): string => {
+  const mark = placement.beyond ? BEYOND_MARK : WITHIN_MARK;
+  return `  ${mark} ${text.features[placement.feature.id].name}: ${valueText(placement.feature, unit, text)}${whereText(placement, text)}`;
+};
+
+const unmeasuredLine = (placements: readonly Placement[], text: StructureText): string[] => {
+  const reasons = placements.flatMap((placement) => {
+    const why = placement.feature.notMeasured;
+    return why === undefined ? [] : [text.aside(text.features[placement.feature.id].name, text.notMeasured[why])];
+  });
+  return reasons.length === 0 ? [] : [`  ${text.unmeasured(reasons.join(text.listSeparator))}`];
+};
+
+const headerOf = (score: StructureScore, language: string, text: StructureText): string =>
+  score.articles === undefined ? text.noBaseline(language) : text.score(score.score, score.compared, score.articles);
+
+/** A value no higher (or, for a low measure, no more uniform) than any step of the human articles. */
+const isUsual = (placement: Placement): boolean => placement.feature.value !== undefined && placement.pastShare === 0;
+
+const usualLine = (placements: readonly Placement[], unit: LengthUnit, text: StructureText): string[] => {
+  const usual = placements.filter(isUsual).map((placement) => `${text.features[placement.feature.id].name} ${valueText(placement.feature, unit, text)}`);
+  return usual.length === 0 ? [] : [`  ${WITHIN_MARK} ${text.usualAmong(usual.join(text.listSeparator))}`];
+};
+
+/**
+ * One document's structure block: the score, each value that stands out placed against human articles, the usual ones
+ * on one line, then what was not measured and why.
+ */
+export const structureLines = (score: StructureScore, language: string, unit: LengthUnit, text: StructureText): string[] => [
+  headerOf(score, language, text),
+  ...score.placements
+    .filter((placement) => placement.feature.value !== undefined && !isUsual(placement))
+    .map((placement) => placementLine(placement, unit, text)),
+  ...usualLine(score.placements, unit, text),
+  ...unmeasuredLine(score.placements, text),
+];
+
+const changeLine = (before: Placement, after: Placement | undefined, units: readonly [LengthUnit, LengthUnit], text: StructureText): string => {
+  const name = text.features[before.feature.id].name;
+  const afterValue = after === undefined ? NOT_MEASURED : valueText(after.feature, units[1], text);
+  return `  ${name}: ${valueText(before.feature, units[0], text)} → ${afterValue}`;
+};
+
+/** The score before and after, then each measure that either file measured. */
+export const structureChangeLines = (
+  before: StructureScore,
+  after: StructureScore,
+  units: readonly [LengthUnit, LengthUnit],
+  text: StructureText,
+): string[] => [
+  `  ${text.scoreChange}: ${String(before.score)} → ${String(after.score)}`,
+  ...before.placements.flatMap((placement, index) => {
+    const other = after.placements[index];
+    const measured = placement.feature.value !== undefined || other?.feature.value !== undefined;
+    return measured ? [changeLine(placement, other, units, text)] : [];
+  }),
+];
+
+/** For grep: the score and the measures past the human limit, on one line. */
+export const structureCompact = (path: string, score: StructureScore): string => {
+  const beyond = score.placements.filter((placement) => placement.beyond).map((placement) => `${placement.feature.id}=${String(placement.feature.value)}`);
+  return [`${path}: structure ${String(score.score)}/${String(score.compared)}`, ...beyond].join(" ");
+};
+
+/** The structure block as data: the score, and each measure with its value, where it sits, and why it was not measured. */
+export const structureJson = (score: StructureScore): Readonly<Record<string, unknown>> => ({
+  score: score.score,
+  compared: score.compared,
+  baselineArticles: score.articles ?? null,
+  features: score.placements.map((placement) => ({
+    id: placement.feature.id,
+    value: placement.feature.value ?? null,
+    ...(placement.feature.detail === undefined ? {} : { detail: placement.feature.detail }),
+    ...(placement.feature.notMeasured === undefined ? {} : { notMeasured: placement.feature.notMeasured }),
+    direction: placement.direction,
+    pastShare: placement.pastShare ?? null,
+    humanMedian: placement.median ?? null,
+    limit: placement.limit ?? null,
+    beyond: placement.beyond,
+  })),
+});