chaffjs 0.28.0 → 0.30.0

package/src/structure/version-mismatch.ts

@@ -1,5 +1,6 @@
 // A version written in the lead-in to a code block ("Install version 2.3.0 from npm:") that the block itself does not
 // show (npm install tidyq@2.4.0). Pure: reads the source, the code blocks, and the prose with code covered.
+import { escapeRegExp } from "../orthography.ts";
 import type { Span } from "../plugin.ts";
 import type { StructureIssue } from "./issues.ts";
 
@@ -85,19 +86,72 @@ const leadInOf = (source: string, blockStart: number): Span | undefined => {
   return text === "" || NOT_PROSE.test(text) || !LETTER.test(words) ? undefined : { start, end: lines.length };
 };
 
+/** A pin with the version it pins, of any number of parts: redis 7.4 in redis:7.4-alpine and in library/redis:7.4. */
+const PIN_VERSION = /^([\w.-]+)(?:@|==|=|:)[v^~]?(\d+(?:\.\d+)*)/u;
+const HAS_LETTER = /[A-Za-z]/u;
+
+/** Each name the block pins, with the one version it pins it to; a name pinned to two versions is left out. */
+const pinnedVersions = (code: string): Map<string, string> => {
+  const byName = new Map<string, Set<string>>();
+  codeWords(code).forEach((word) => {
+    const match = PIN_VERSION.exec(word.slice(word.lastIndexOf("/") + 1));
+    if (match?.[1] === undefined || match[2] === undefined || !HAS_LETTER.test(match[1])) return;
+    const name = match[1].toLowerCase();
+    byName.set(name, new Set([...(byName.get(name) ?? []), match[2]]));
+  });
+  const single = new Map<string, string>();
+  byName.forEach((versions, name) => {
+    const [only] = versions;
+    if (versions.size === 1 && only !== undefined) single.set(name, only);
+  });
+  return single;
+};
+
+/** 7 and 7.4, or 7.4 and 7.4.1: one names the other's series, so they agree. */
+const sameSeries = (written: string, pinned: string): boolean => {
+  const [shorter, longer] = [written.split("."), pinned.split(".")].toSorted((left, right) => left.length - right.length);
+  return (shorter ?? []).every((part, index) => part === longer?.[index]);
+};
+
 /**
- * Each version in a code block's lead-in that differs from the one version the block shows. A block with no version, or
- * with two (an upgrade from one to the other), says nothing to compare; a version marked as a bound, or named after another
- * program, is not the one installed.
+ * Each version written right after the name of a program the block pins ("We run Redis 7.2" over redis:7.4) that is not of
+ * the pinned version's series. The name says whose version it is, so a version of two parts is read here, where a bare 7.2
+ * is too often a decimal; one part (port 6379, Node 20) is too often another number.
  */
-export const versionMismatches = (source: string, prose: string, blocks: readonly CodeBlock[], words: VersionWords): StructureIssue[] =>
-  blocks.flatMap((block) => {
-    const shown = [...new Set(versionsIn(block.code).map((found) => found.version))];
-    const leadIn = leadInOf(source, block.start);
-    const [code] = shown;
-    if (shown.length !== 1 || code === undefined || leadIn === undefined) return [];
-    const names = pinnedNames(block.code);
-    return versionsIn(prose.slice(leadIn.start, leadIn.end), leadIn.start)
-      .filter((found) => found.version !== code && !isBound(prose, found, words.ranges) && isAboutBlock(prose, found, names, words.versionWords))
-      .map((found) => ({ offset: found.start, values: { written: found.version, code } }));
+const namedMismatches = (prose: string, leadIn: Span, code: string, ranges: readonly RangeWord[]): StructureIssue[] =>
+  [...pinnedVersions(code)].flatMap(([name, pinned]) => {
+    const pattern = new RegExp(`(?<![\\w.-])${escapeRegExp(name)}\\s+v?(\\d+(?:\\.\\d+){1,2})(?![\\w.]|\\.\\d)`, "giu");
+    return [...prose.slice(leadIn.start, leadIn.end).matchAll(pattern)].flatMap((match) => {
+      const written = match[1] ?? "";
+      const span = { start: leadIn.start + match.index, end: leadIn.start + match.index + match[0].length };
+      if (sameSeries(written, pinned) || isBound(prose, span, ranges)) return [];
+      return [{ offset: span.end - written.length, values: { written, code: pinned } }];
+    });
   });
+
+/**
+ * Each version in the lead-in that differs from the one version the block shows. A block with no version, or with two (an
+ * upgrade from one to the other), says nothing to compare; a version marked as a bound, or named after another program, is
+ * not the one installed.
+ */
+const shownMismatches = (prose: string, leadIn: Span, code: string, words: VersionWords): StructureIssue[] => {
+  const shown = [...new Set(versionsIn(code).map((found) => found.version))];
+  const [only] = shown;
+  if (shown.length !== 1 || only === undefined) return [];
+  const names = pinnedNames(code);
+  return versionsIn(prose.slice(leadIn.start, leadIn.end), leadIn.start)
+    .filter((found) => found.version !== only && !isBound(prose, found, words.ranges) && isAboutBlock(prose, found, names, words.versionWords))
+    .map((found) => ({ offset: found.start, values: { written: found.version, code: only } }));
+};
+
+/** Both readings of one block; a version both report is reported once, against the pin of the program it names. */
+const blockMismatches = (source: string, prose: string, block: CodeBlock, words: VersionWords): StructureIssue[] => {
+  const leadIn = leadInOf(source, block.start);
+  if (leadIn === undefined) return [];
+  const issues = [...namedMismatches(prose, leadIn, block.code, words.ranges), ...shownMismatches(prose, leadIn, block.code, words)];
+  return issues.filter((issue, index) => issues.findIndex((other) => other.offset === issue.offset) === index);
+};
+
+/** Each version in a code block's lead-in that differs from the version the block installs. */
+export const versionMismatches = (source: string, prose: string, blocks: readonly CodeBlock[], words: VersionWords): StructureIssue[] =>
+  blocks.flatMap((block) => blockMismatches(source, prose, block, words));

package/src/structure/version-order.ts

@@ -0,0 +1,94 @@
+import type { StructureIssue } from "./issues.ts";
+
+/**
+ * Versions listed in order, a changelog's headings or a list of releases, with one out of place. The direction (newest or
+ * oldest first) is taken from most of the steps, and a version that fits in no longest run along it is pointed out.
+ */
+export type VersionPoint = { readonly offset: number; readonly label: string };
+
+type Version = { readonly parts: readonly number[]; readonly prerelease: string };
+
+/** A version at the start of a heading or an item: 3.2.0, v3.2.0, [3.2.0], 3.2.0-beta.1. */
+const VERSION_START = /^\[?v?(\d{1,4})\.(\d{1,4})\.(\d{1,4})(?:-([0-9A-Za-z-]+(?:\.[0-9A-Za-z-]+)*))?\]?(?![\w.])/u;
+
+/** The version a heading or an item starts with, as written; undefined when it does not start with one. */
+export const leadingVersion = (text: string): string | undefined => VERSION_START.exec(text.trim())?.[0];
+
+const parse = (label: string): Version | undefined => {
+  const match = VERSION_START.exec(label);
+  if (match === null) return undefined;
+  return { parts: [match[1], match[2], match[3]].map(Number), prerelease: match[4] ?? "" };
+};
+
+/** A prerelease (3.0.0-beta.1) comes before its release (3.0.0). */
+const comparePrerelease = (left: string, right: string): number => {
+  if (left === right) return 0;
+  if (left === "") return 1;
+  return right === "" ? -1 : Math.sign(left.localeCompare(right, "en", { numeric: true }));
+};
+
+const compareVersions = (left: Version, right: Version): number => {
+  const differing = left.parts.findIndex((part, index) => part !== right.parts[index]);
+  return differing === -1 ? comparePrerelease(left.prerelease, right.prerelease) : Math.sign((left.parts[differing] ?? 0) - (right.parts[differing] ?? 0));
+};
+
+/** Whether every label is a version and no step goes against direction (equal versions do not break it). */
+export const versionsAlong = (labels: readonly (string | undefined)[], direction: number): boolean => {
+  const versions = labels.flatMap((label) => {
+    const version = label === undefined ? undefined : parse(label);
+    return version === undefined ? [] : [version];
+  });
+  if (versions.length !== labels.length) return false;
+  return versions.slice(1).every((version, index) => compareVersions(version, versions[index] ?? version) !== -direction);
+};
+
+/** The longest run along direction ending at each version (equal versions do not break it). */
+const longestEndingAt = (versions: readonly Version[], direction: number): number[] =>
+  versions.reduce<number[]>((lengths, version, index) => {
+    const along = versions.slice(0, index).map((earlier, at) => (compareVersions(version, earlier) === -direction ? 0 : (lengths[at] ?? 0)));
+    return [...lengths, 1 + Math.max(0, ...along)];
+  }, []);
+
+const majorityOf = (versions: readonly Version[]): number =>
+  Math.sign(versions.slice(1).reduce((sum, version, index) => sum + compareVersions(version, versions[index] ?? version), 0));
+
+/** The fewest versions an order is read from: with two, either one could be the one out of place. */
+const MIN_VERSIONS = 3;
+
+/**
+ * The versions that belong to no longest run along the majority direction. A run that holds no more than half of them is
+ * taken as sorted by something else, and nothing is said.
+ */
+export const versionOrderBreaks = (points: readonly VersionPoint[]): StructureIssue[] => {
+  const parsed = points.flatMap((point) => {
+    const version = parse(point.label);
+    return version === undefined ? [] : [{ point, version }];
+  });
+  const versions = parsed.map((entry) => entry.version);
+  const direction = majorityOf(versions);
+  if (versions.length < MIN_VERSIONS || direction === 0) return [];
+  const forward = longestEndingAt(versions, direction);
+  const backward = longestEndingAt(versions.toReversed(), -direction).toReversed();
+  const longest = Math.max(...forward);
+  if (longest * 2 <= versions.length) return [];
+  return parsed.flatMap((entry, index) =>
+    (forward[index] ?? 0) + (backward[index] ?? 0) - 1 === longest
+      ? []
+      : [{ offset: entry.point.offset, values: { version: entry.point.label, previous: parsed[index - 1]?.point.label ?? "" } }],
+  );
+};
+
+/** A version whose last part is zero (3.1.0) is no section number: the sections under 3.1 count from 3.1.1. */
+const endsInZero = (version: Version): boolean => version.parts.at(-1) === 0;
+
+/**
+ * Whether dotted labels (1.2.1, 1.2.2) are a version history rather than section numbers: all of them versions, and
+ * either one ends in zero or most steps go down (newest first). Section numbers only go up. version-order checks the
+ * histories and numbering-gap the rest, so a sequence is never reported by both.
+ */
+export const isVersionHistory = (labels: readonly string[]): boolean => {
+  const versions = labels.map(parse);
+  const parsed = versions.filter((version) => version !== undefined);
+  if (labels.length < 2 || parsed.length !== labels.length) return false;
+  return parsed.some(endsInZero) || majorityOf(parsed) < 0;
+};

package/src/surname-near.ts

@@ -0,0 +1,31 @@
+// 名が同じ人の名前の、姓だけの書き損じ（Whitford と Whitfield）。一字違い（isNearWord）より遠い違いを、英字の長い姓に限って見る。
+
+const LATIN_WORD = /^[a-z]+$/u;
+
+/** 二字違いまで見る姓の長さ。短い姓（Martin と Marten、Hansen と Hanson）は別の姓のことが多い。 */
+const MIN_SURNAME_LENGTH = 7;
+/** 頭からそろう字の数。頭が違えば別の姓（Robertson と Robinson）。 */
+const MIN_SURNAME_PREFIX = 4;
+/** 頭と終わりのそろった字のあいだに残る字の数。短いほうで二字まで、長いほうで三字まで（Whitford の or と Whitfield の iel）。 */
+const MAX_SURNAME_GAP = 2;
+
+const sharedPrefix = (left: string, right: string): number => {
+  const differ = [...left].findIndex((char, index) => char !== right.charAt(index));
+  return differ < 0 ? left.length : differ;
+};
+
+/**
+ * 二つの英字の姓が、頭が四字以上そろい、終わりの字もそろい、あいだの二字（長いほうは三字）までだけ違うか。どちらも七字以上で。
+ * 終わりだけの違い（Whitford と Whitfords）は語の形の違い。
+ */
+export const isNearSurname = (left: string, right: string): boolean => {
+  if (left === right || !LATIN_WORD.test(left) || !LATIN_WORD.test(right) || Math.min(left.length, right.length) < MIN_SURNAME_LENGTH) return false;
+  const prefix = sharedPrefix(left, right);
+  if (prefix < MIN_SURNAME_PREFIX) return false;
+  const [leftRest, rightRest] = [left.slice(prefix), right.slice(prefix)];
+  const suffix = sharedPrefix([...leftRest].toReversed().join(""), [...rightRest].toReversed().join(""));
+  if (suffix === 0) return false;
+  const gaps = [leftRest.length - suffix, rightRest.length - suffix].toSorted((first, second) => first - second);
+  const [shorter = 0, longer = 0] = gaps;
+  return shorter <= MAX_SURNAME_GAP && longer <= MAX_SURNAME_GAP + 1;
+};

package/src/table-cells.ts

@@ -0,0 +1,41 @@
+import type { ProseDocument, Segmentation, Span, TableCell, Token } from "./plugin.ts";
+import { proseAndTablesOf } from "./table-text.ts";
+import { tableBodyCells, type Cell } from "./facts/table-facts.ts";
+
+// 表の升の語。本文は表を覆うので、升の字は文の分割も品詞解析も通らない。升ごとに adapter に渡し、語の位置を source の上に戻す。
+
+const LETTER = /\p{L}/u;
+
+const shiftToken = (token: Token, by: number): Token => ({ ...token, span: { start: token.span.start + by, end: token.span.end + by } });
+
+/** 升一つの語。字の無い升（数だけ、空）は解析しない。adapter が語を返さなければ tokens は無い。 */
+export const cellWithTokens = (cell: Cell, segment: (text: string) => Segmentation): TableCell => {
+  if (!LETTER.test(cell.text)) return cell;
+  const sentences = segment(cell.text).sentences;
+  if (!sentences.some((sentence) => sentence.tokens !== undefined)) return cell;
+  return { ...cell, tokens: sentences.flatMap((sentence) => (sentence.tokens ?? []).map((token) => shiftToken(token, cell.start))) };
+};
+
+/** 文書の表（引用とコードの外）の本体の升と、その語。 */
+export const tableCellsOf = (doc: ProseDocument, segment: (text: string) => Segmentation): TableCell[] =>
+  tableBodyCells(proseAndTablesOf(doc)).map((cell) => cellWithTokens(cell, segment));
+
+/** prose に、升の字だけを書き戻したもの（表の見出しの行と区切りの | は覆ったまま）。位置は変えない。 */
+export const proseWithCells = (prose: string, cells: readonly (Span & { readonly text: string })[]): string => {
+  const pieces: string[] = [];
+  const end = cells
+    .toSorted((left, right) => left.start - right.start)
+    .reduce((from, cell) => {
+      if (cell.start < from || cell.end - cell.start !== cell.text.length) return from;
+      pieces.push(prose.slice(from, cell.start), cell.text);
+      return cell.end;
+    }, 0);
+  pieces.push(prose.slice(end));
+  return pieces.join("");
+};
+
+/** 表の升の語は、読む rule があるときに一度だけ作る。升ごとの解析を、表を読まない rule に払わせない。 */
+export const lazyCells = (make: () => readonly TableCell[]): (() => readonly TableCell[]) => {
+  const cells: { value?: readonly TableCell[] } = {};
+  return () => (cells.value ??= make());
+};

package/src/table-names.ts

@@ -0,0 +1,113 @@
+import { isNearWord, nameKey, type NameMention } from "./name-variants.ts";
+import type { TableCell, Token } from "./plugin.ts";
+import { withoutEdgeMarks } from "./facts/trim-marks.ts";
+
+// 表の升に書いた名前と、本文の名前の書き分け（本文は Sofia Mendes、担当者の表は Sofia Mendez）。表の升は品詞解析を通らないので、
+// 名前の形をした升だけを読み、本文で読めた名前と比べる。比べるのは姓と名のように二語以上の名前で、一語だけが違うときに限る。
+// 同じ語がほかにあることが、同じ人を指す手がかりになる。漢字・かなの名前は、本文と同じく読みが同じときに限る（佐々木 美穂 と
+// 佐々木 美保）。読みの違う一字違い（佐藤 太郎 と 佐藤 次郎）は別の人のことが多い。
+
+/** 表の升の名前。words は空白で分けた語。reading は升の語の読み（読めなければ無い）。 */
+export type CellName = { readonly surface: string; readonly offset: number; readonly words: readonly string[]; readonly reading?: string | undefined };
+
+/** 本文の名前の書き方と、その数。reading は最初の現れの読み。 */
+export type ProseName = { readonly surface: string; readonly words: readonly string[]; readonly count: number; readonly reading?: string | undefined };
+
+export type CellNameVariant = { readonly name: CellName; readonly usual: string; readonly kind: "spelling" | "reading" | "near" };
+
+/** 英字の名前の升: 大文字で始まる語が二つから四つ。小文字の語（Write the procedure）を含む升は名前でない。 */
+const LATIN_NAME = /^\p{Lu}[\p{L}'’.-]*(?: \p{Lu}[\p{L}'’.-]*){1,3}$/u;
+/** 漢字・カタカナの名前の升: 名前の字の語が、空白一つを挟んで二つか三つ（佐々木 美穂）。 */
+const CJK_NAME = /^[\p{Script=Han}\p{Script=Katakana}ー々]+(?:[ \u3000][\p{Script=Han}\p{Script=Katakana}ー々]+){1,2}$/u;
+const SPACE = /[ \u3000]/u;
+const LOWER = /\p{Ll}/u;
+
+/** 範囲の中の語の読みをつないだもの。記号と空白の語は読まない。読めない語があれば無い。 */
+export const readingWithin = (tokens: readonly Token[], start: number, end: number): string | undefined => {
+  const words = tokens.filter((token) => token.span.start >= start && token.span.end <= end && token.pos !== "PUNCT" && token.surface.trim() !== "");
+  const readings = words.map((token) => token.reading);
+  return words.length > 0 && readings.every((reading) => reading !== undefined && reading !== "") ? readings.join("") : undefined;
+};
+
+/** 名前の形をした升。升の字の前後の空白と強調の印は名前の外。 */
+export const cellNamesIn = (cells: readonly TableCell[]): CellName[] =>
+  cells.flatMap((cell) => {
+    const surface = withoutEdgeMarks(cell.text.trim());
+    if (!(LATIN_NAME.test(surface) && LOWER.test(surface)) && !CJK_NAME.test(surface)) return [];
+    const offset = cell.start + cell.text.indexOf(surface);
+    return [{ surface, offset, words: surface.split(SPACE), reading: readingWithin(cell.tokens ?? [], offset, offset + surface.length) }];
+  });
+
+/**
+ * 本文の名前の書き方ごとの数。空白一つで並んだ名前の現れ（佐々木 と 美穂）は、一つの名前（佐々木 美穂）としても数える。
+ * 日本語の解析器は姓と名のあいだの空白で名前を切る。
+ */
+export const proseNamesOf = (mentions: readonly NameMention[], source: string): ProseName[] => {
+  const sorted = mentions.toSorted((left, right) => left.offset - right.offset);
+  const joined = sorted.flatMap((mention, index): Written[] => {
+    const next = sorted[index + 1];
+    const end = mention.offset + mention.surface.length;
+    if (next === undefined || next.offset !== end + 1 || !SPACE.test(source.charAt(end))) return [];
+    const reading = mention.reading === undefined || next.reading === undefined ? undefined : `${mention.reading}${next.reading}`;
+    return [{ surface: `${mention.surface}${source.charAt(end)}${next.surface}`, reading }];
+  });
+  const forms = new Map<string, ProseName>();
+  [...sorted, ...joined].forEach(({ surface, reading }) => {
+    const form = forms.get(surface);
+    forms.set(surface, form === undefined ? { surface, words: surface.split(SPACE), count: 1, reading } : { ...form, count: form.count + 1 });
+  });
+  return [...forms.values()];
+};
+
+type Written = { readonly surface: string; readonly reading: string | undefined };
+
+const LATIN = /\p{Script=Latin}/u;
+/** 英字の語の中の記号（O'Connor、Anne-Marie）。一字違いは字だけで見る。 */
+const WORD_MARKS = /['’.-]/gu;
+
+/**
+ * 二つの英字の語が一字違いか（名前の見方と同じ isNearWord）。漢字・かなの語は見ない。升は読みが分からず、一字違いの名前
+ * （佐藤 太郎 と 佐藤 次郎）は別の人のことが多い。
+ */
+const isNearNameWord = (left: string, right: string): boolean =>
+  LATIN.test(left) && LATIN.test(right) && isNearWord(left.toLowerCase().replaceAll(WORD_MARKS, ""), right.toLowerCase().replaceAll(WORD_MARKS, ""));
+
+/**
+ * 升の名前が、本文の名前の書き分けか。記号・幅・大小だけの違いか、語の数が同じで一語だけが違い、残りの語が同じとき。違う一語は、
+ * 英字なら一字違い、漢字・かなら名前全体の読みが同じ（本文の名前の見方と同じ）。この二つは、本文の形が二度以上、升の形が文書の
+ * 中で一度だけのとき（別の人のこともある）。
+ */
+export const cellNameRelation = (name: CellName, uses: number, prose: ProseName): CellNameVariant["kind"] | undefined => {
+  if (name.surface === prose.surface || name.words.length !== prose.words.length) return undefined;
+  if (nameKey(name.surface) === nameKey(prose.surface)) return "spelling";
+  const differ = name.words.flatMap((word, index) => (word === prose.words[index] ? [] : [index]));
+  const [at] = differ;
+  if (differ.length !== 1 || at === undefined || uses !== 1 || prose.count < 2) return undefined;
+  if (isNearNameWord(name.words[at] ?? "", prose.words[at] ?? "")) return "near";
+  return name.reading !== undefined && name.reading === prose.reading ? "reading" : undefined;
+};
+
+/** 記号・幅・大小だけの違いを、読みの同じものと一字違いより先に取る。 */
+const KIND_ORDER: readonly CellNameVariant["kind"][] = ["spelling", "reading", "near"];
+
+/**
+ * 表の升の名前のうち、本文の名前の書き分けのもの。記号だけの違いを先に、その中で本文の形のうち一番多いものと比べる。
+ * 書き方ごとに最初の升を一つ。
+ */
+export const cellNameVariants = (names: readonly CellName[], prose: readonly ProseName[]): CellNameVariant[] => {
+  const uses = new Map(prose.map((form) => [form.surface, form.count]));
+  const firsts = new Map<string, CellName>();
+  names.forEach((name) => {
+    uses.set(name.surface, (uses.get(name.surface) ?? 0) + 1);
+    if (!firsts.has(name.surface)) firsts.set(name.surface, name);
+  });
+  return [...firsts.values()].flatMap((name) => {
+    const [usual] = prose
+      .flatMap((form) => {
+        const kind = cellNameRelation(name, uses.get(name.surface) ?? 0, form);
+        return kind === undefined ? [] : [{ form, kind }];
+      })
+      .toSorted((left, right) => KIND_ORDER.indexOf(left.kind) - KIND_ORDER.indexOf(right.kind) || right.form.count - left.form.count);
+    return usual === undefined ? [] : [{ name, usual: usual.form.surface, kind: usual.kind }];
+  });
+};

package/src/table-text.ts

@@ -0,0 +1,39 @@
+// The prose with its Markdown tables read back in. The prose masks tables, but a quote or an invoice keeps most of its
+// amounts in one, and a rule comparing how amounts are written has to see them.
+import type { ProseDocument, Span } from "./plugin.ts";
+import { maskSpans } from "./mask.ts";
+import { opaqueSpans, readMarkdown, spansOfType } from "./markdown-read.ts";
+import { TABLE_RULE } from "./structure/runs.ts";
+
+const within = (inner: Span, outer: Span): boolean => inner.start >= outer.start && inner.end <= outer.end;
+
+/**
+ * The prose, with each table span as the source writes it, except what stays hidden inside it (code in a cell). Offsets
+ * are kept. Pure.
+ */
+export const proseWithTables = (prose: string, source: string, tables: readonly Span[], hidden: readonly Span[]): string => {
+  if (tables.length === 0) return prose;
+  const shown = maskSpans(source, hidden);
+  const pieces: string[] = [];
+  const end = tables
+    .toSorted((left, right) => left.start - right.start)
+    .reduce((from, table) => {
+      if (table.start < from) return from;
+      pieces.push(prose.slice(from, table.start), shown.slice(table.start, table.end));
+      return table.end;
+    }, 0);
+  pieces.push(prose.slice(end));
+  return pieces.join("");
+};
+
+const hasTableRule = (source: string): boolean => source.split("\n").some((line) => TABLE_RULE.test(line) && line.includes("-"));
+
+/** The document's prose with its tables, outside code and quoted replies. A document that is not Markdown keeps its prose. */
+export const proseAndTablesOf = (doc: ProseDocument): string => {
+  const prose = doc.prose ?? doc.source;
+  if (doc.prose === undefined || doc.markup?.markdown !== true || !hasTableRule(doc.source)) return prose;
+  const { root } = readMarkdown(doc.source);
+  const quoted = [...spansOfType(root, "blockquote"), ...(doc.replyQuotes ?? [])];
+  const tables = spansOfType(root, "table").filter((table) => !quoted.some((quote) => within(table, quote)));
+  return proseWithTables(doc.prose, doc.source, tables, opaqueSpans(root));
+};

package/src/ui-labels.ts

@@ -0,0 +1,55 @@
+// The same label on the screen written two ways in one manual (**Start Restore** and **Start restore**, ［復元を開始］ and
+// ［復元開始］). Pure: reads the labels a manual marks as labels, bold or in ［］, and points at the form written less often.
+
+import { escapeRegExp } from "./orthography.ts";
+
+export type Label = { readonly surface: string; readonly offset: number };
+export type LabelVariant = { readonly label: Label; readonly usual: string };
+
+/** What a manual marks as a label on the screen: bold (** or __), or the full-width brackets Japanese manuals use. */
+const MARKED = /\*\*([^*\n]{1,40})\*\*|__([^_\n]{1,40})__|［([^］\n]{1,40})］/gu;
+const SPACES = /\s+/gu;
+const LETTER = /\p{L}/u;
+
+/** Each label marked in the source whose text is prose (not covered as code in prose) and holds a letter. */
+export const labelsIn = (source: string, prose: string): Label[] =>
+  [...source.matchAll(MARKED)].flatMap((match) => {
+    const surface = (match[1] ?? match[2] ?? match[3] ?? "").trim();
+    const inner = match.index + match[0].indexOf(surface);
+    const covered = prose.slice(inner, inner + surface.length) !== surface;
+    return covered || !LETTER.test(surface) ? [] : [{ surface, offset: inner }];
+  });
+
+/**
+ * Two forms of one label differ only in case, spaces, or a word a label is written with or without (the label-particle
+ * lexicon: 復元を開始 and 復元開始).
+ */
+const keyOf = (surface: string, particles: readonly string[]): string =>
+  particles.reduce((text, particle) => text.replace(joining(particle), ""), surface.replace(SPACES, "")).toLowerCase();
+
+/** A particle between two kanji or katakana (復元を開始), not one inside a word (その他). */
+const joining = (particle: string): RegExp =>
+  new RegExp(`(?<=[\\p{Script=Han}\\p{Script=Katakana}ー])${escapeRegExp(particle)}(?=[\\p{Script=Han}\\p{Script=Katakana}])`, "gu");
+
+/** Two forms that differ only in the case of their first letter (Note and note): emphasis at a sentence's start, not two labels. */
+const onlyFirstLetterDiffers = (forms: readonly string[]): boolean =>
+  new Set(forms.map((form) => `${form.charAt(0).toLowerCase()}${form.slice(1)}`)).size === 1;
+
+const groupBy = (labels: readonly Label[], keyFor: (label: Label) => string): Map<string, Label[]> =>
+  labels.reduce((groups, label) => groups.set(keyFor(label), [...(groups.get(keyFor(label)) ?? []), label]), new Map<string, Label[]>());
+
+/**
+ * Each label written in a form other than the one its key is written in most; on a tie, the later form. A label written
+ * one way only says nothing.
+ */
+export const labelVariants = (labels: readonly Label[], particles: readonly string[] = []): LabelVariant[] => {
+  const byKey = groupBy(labels, (label) => keyOf(label.surface, particles));
+  return [...byKey.values()].flatMap((group) => {
+    const counts = groupBy(group, (label) => label.surface);
+    if (counts.size < 2 || onlyFirstLetterDiffers([...counts.keys()])) return [];
+    const [first] = counts;
+    if (first === undefined) return [];
+    const usual = [...counts].reduce((best, entry) => (entry[1].length > best[1].length ? entry : best), first)[0];
+    return group.filter((label) => label.surface !== usual).map((label) => ({ label, usual }));
+  });
+};

package/src/undefined-call.ts

@@ -0,0 +1,65 @@
+// A function called in a code example that the page never defines, where the page documents one whose name it extends:
+// wrapText( on a page about wrap, wrapLines( after import { wrap }. Pure; reads the Markdown source. The global functions
+// of programming languages (parseInt, setTimeout) come from a lexicon, so a page about parse may call parseInt.
+import { codeFences } from "./detectors/code-fences.ts";
+
+/** A call to a name the page does not define, where it is written, and the documented name it is likely a slip of. */
+export type UndefinedCall = { readonly name: string; readonly offset: number; readonly documented: string };
+
+const CALL = /(?<![\w$.])([A-Za-z_$][\w$]*)[ \t]*\(/gu;
+const WORD = /[A-Za-z_$][\w$]*/gu;
+const LEADING_WORD = /^[A-Za-z_$][\w$]*/u;
+/** import { wrap, type Options, measure as m } from "wrapkit" (JavaScript) and from wrapkit import wrap, measure (Python). */
+const IMPORT_BRACES = /\bimport[ \t]*\{([^}]*)\}/gu;
+const FROM_IMPORT = /\bfrom[ \t]+[\w.]+[ \t]+import[ \t]+([\w, \t]+)/gu;
+const TYPE_MODIFIER = /^type[ \t]+/u;
+/** A name right after one of these is being declared, not called: function wrapText(, def wrap_text(. */
+const DECLARING = /\b(?:function\*?|def|fn|func|class|new)[ \t]+$/u;
+/** Where a line comment starts: a call after it is commented out. */
+const LINE_COMMENT = /\/\/|(?:^|[ \t])#/u;
+/** The shortest documented name a call is compared with: shorter ones (id, get) are prefixes of too many names. */
+const MIN_DOCUMENTED = 4;
+
+/** Each specifier's own name: `type Options` is Options, `measure as m` is measure. */
+const specifiers = (list: string): string[] =>
+  list.split(",").flatMap((specifier) => LEADING_WORD.exec(specifier.trim().replace(TYPE_MODIFIER, ""))?.[0] ?? []);
+
+const importedNames = (source: string): string[] =>
+  [...source.matchAll(IMPORT_BRACES), ...source.matchAll(FROM_IMPORT)].flatMap((match) => specifiers(match[1] ?? ""));
+
+/** Names the page documents: the first word of a heading (## wrap, ### `wrap()`) and the names it imports. */
+const documentedNames = (source: string, headings: readonly string[]): Set<string> => {
+  const fromHeadings = headings.flatMap((heading) => LEADING_WORD.exec(heading.replace(/[`*]/gu, "").trim())?.[0] ?? []);
+  return new Set([...fromHeadings, ...importedNames(source)].filter((name) => name.length >= MIN_DOCUMENTED));
+};
+
+const countWords = (source: string): Map<string, number> =>
+  [...source.matchAll(WORD)].reduce((counts, match) => counts.set(match[0], (counts.get(match[0]) ?? 0) + 1), new Map<string, number>());
+
+/** Whether the call at `at` in `code` is declared there or commented out. */
+const isDeclaredOrCommented = (code: string, at: number): boolean => {
+  const lineStart = code.lastIndexOf("\n", at - 1) + 1;
+  const before = code.slice(lineStart, at);
+  return DECLARING.test(before) || LINE_COMMENT.test(before);
+};
+
+/**
+ * Every call in a code block to a name written nowhere else on the page, when a documented name is its stem
+ * (wrap → wrapText). A name used twice (defined and called, or called twice) is the example's own. headings are the page's
+ * Markdown headings; globals the language functions every page may call.
+ */
+export const undefinedCalls = (source: string, headings: readonly string[], globals: readonly string[] = []): UndefinedCall[] => {
+  const documented = documentedNames(source, headings);
+  if (documented.size === 0) return [];
+  const counts = countWords(source);
+  const known = new Set([...documented, ...globals]);
+  return codeFences(source).flatMap((fence) => {
+    const code = source.slice(fence.start, fence.end);
+    return [...code.matchAll(CALL)].flatMap((match) => {
+      const name = match[1] ?? "";
+      const stem = [...documented].find((candidate) => name !== candidate && name.startsWith(candidate));
+      if (stem === undefined || known.has(name) || (counts.get(name) ?? 0) > 1 || isDeclaredOrCommented(code, match.index)) return [];
+      return [{ name, offset: fence.start + match.index, documented: stem }];
+    });
+  });
+};