chaffjs 0.30.0 → 0.32.0

package/src/structure/rent-multiple.ts

@@ -0,0 +1,207 @@
+import type { StructureIssue } from "./issues.ts";
+import { alternation, intervalOf, isMultiple, isPlainGap, nearestStated, occurrences, type Interval, type StatedAmount } from "./stated-multiple.ts";
+
+/**
+ * rent-multiple-mismatch: a deposit, key money or guarantee given both as a number of months of rent and as an amount that
+ * is not that many months of the listing's rent (敷金 2か月（98,000円） with 賃料 98,000円; "Deposit: Six months' rent
+ * ($145,000)" with Rent $21,500). The rent is the nearest one stated before the deposit (several listings on one page each
+ * state their own); a document whose deposits come before any rent uses the rent only when it states one. When the document
+ * also states a fee beside the rent (管理費, service charge), the multiple may be of the rent alone or of the rent and the
+ * fee, since listings do both and seldom say which. A months count without an amount, an amount without a months count, a
+ * range of months, and two different pairs in one statement are not compared. The words come from the lexicons. Pure.
+ */
+
+export type RentMultipleWords = {
+  /** Labels of the monthly rent (賃料, Rent). */
+  readonly rents: readonly string[];
+  /** Labels of a monthly fee paid with the rent (管理費, Service charge). */
+  readonly fees: readonly string[];
+  /** Labels of an amount stated in months of rent (敷金, 礼金, Security deposit). */
+  readonly multiples: readonly string[];
+  /** The word of a month after a count (か月, months). */
+  readonly months: readonly string[];
+  /** Words that may stand between a label or a months count and its amount (は, 分, of, equal to). */
+  readonly links: readonly string[];
+  /** Words that say an amount is not per month (per week, 年額, per sq ft); a rent line with one is not read. */
+  readonly periods: readonly string[];
+  /** Words that make the amount something other than the plain multiple (税込, tax included). */
+  readonly skips: readonly string[];
+  /** Marks and words that join the two ends of a range (〜, to). */
+  readonly connectors: readonly string[];
+  /** Numbers written as words (six, 一) and their values. */
+  readonly numberWords: readonly { readonly word: string; readonly value: number }[];
+};
+
+/** A rent or fee as stated. range is undefined when the label has amounts that are not one monthly amount (a change, per week). */
+type Stated = { readonly offset: number; readonly currency: string; readonly range: Interval | undefined; readonly written: string };
+
+type Months = { readonly start: number; readonly end: number; readonly count: number };
+
+const RANGE_START = /[0-9０-９A-Za-z一二三四五六七八九十]\s*$/u;
+const SENTENCE_END = /[。！？；;]|[.!?](?=\s|$)/u;
+const DIGITS = "[0-9０-９]+(?:[.．][0-9０-９]+)?";
+
+const lineBounds = (text: string, offset: number): { readonly start: number; readonly end: number } => {
+  const end = text.indexOf("\n", offset);
+  return { start: text.lastIndexOf("\n", offset - 1) + 1, end: end === -1 ? text.length : end };
+};
+
+const amountsBetween = (amounts: readonly StatedAmount[], start: number, end: number): StatedAmount[] =>
+  amounts.filter((amount) => amount.offset >= start && amount.end <= end);
+
+/** A label preceded by a months count (2 months' rent, First month's rent) names a multiple, not the rent. */
+const followsMonths = (before: string, words: RentMultipleWords): boolean => {
+  const trimmed = before.replace(/['’]s?\s*$/u, "").trimEnd();
+  return words.months.some((month) => trimmed.toLowerCase().endsWith(month.toLowerCase()));
+};
+
+/** The second end of a range that starts with this amount (85,000円〜90,000円), if one follows. */
+const rangeEnd = (text: string, first: StatedAmount, next: StatedAmount | undefined, words: RentMultipleWords): StatedAmount | undefined => {
+  if (next === undefined || next.currency !== first.currency || next.value < first.value) return undefined;
+  const joint = text.slice(first.end, next.offset).trim();
+  return words.connectors.some((connector) => connector.toLowerCase() === joint.toLowerCase()) ? next : undefined;
+};
+
+/** Where a label's own amount must be: before the next label of any kind on its line (賃料 98,000円 管理費 6,000円). */
+const labelledEnd = (text: string, from: number, lineEnd: number, words: RentMultipleWords): number => {
+  const [next] = occurrences(text.slice(from, lineEnd), [...words.rents, ...words.fees, ...words.multiples]);
+  return next === undefined ? lineEnd : from + next.start;
+};
+
+/**
+ * A rent or fee stated with one amount or one range of amounts. With a second amount (a change from one to another, two
+ * units) or a word of another period on the line (per week, 年額), it is stated but its monthly amount is not known.
+ */
+const statedAt = (
+  text: string,
+  label: { readonly start: number; readonly end: number },
+  amounts: readonly StatedAmount[],
+  words: RentMultipleWords,
+): Stated[] => {
+  const line = lineBounds(text, label.start);
+  const [first, second, ...rest] = amountsBetween(amounts, label.end, labelledEnd(text, label.end, line.end, words));
+  if (first === undefined || !isPlainGap(text.slice(label.end, first.offset), words.links)) return [];
+  if (followsMonths(text.slice(line.start, label.start), words)) return [];
+  const last = rangeEnd(text, first, second, words) ?? first;
+  const written = text.slice(first.offset, last.end);
+  const unclear = (second !== undefined && last !== second) || rest.length > 0 || occurrences(text.slice(line.start, line.end), words.periods).length > 0;
+  if (unclear) return [{ offset: label.start, currency: first.currency, range: undefined, written }];
+  const range = { low: intervalOf(first, text.slice(first.offset, first.end)).low, high: intervalOf(last, text.slice(last.offset, last.end)).high };
+  return [{ offset: label.start, currency: first.currency, range, written }];
+};
+
+/** Each label of the kind followed on its line by an amount (賃料 | 98,000円, Rent: $1,600 to $1,700), in document order. */
+const statedAmounts = (text: string, labels: readonly string[], amounts: readonly StatedAmount[], words: RentMultipleWords): Stated[] =>
+  occurrences(text, labels).flatMap((label) => statedAt(text, label, amounts, words));
+
+const numberWordValue = (word: string, words: RentMultipleWords): number | undefined =>
+  words.numberWords.find((entry) => entry.word.toLowerCase() === word.toLowerCase())?.value;
+
+const countOf = (written: string, words: RentMultipleWords): number => numberWordValue(written, words) ?? Number(written.normalize("NFKC"));
+
+/** The months counts in a piece of text (2か月, Six months), with the offset of the piece. */
+export const monthsIn = (piece: string, offset: number, words: RentMultipleWords): Months[] => {
+  const marker = alternation(words.months);
+  if (marker === undefined) return [];
+  const numberWords = alternation(words.numberWords.map((entry) => entry.word));
+  const count = numberWords === undefined ? DIGITS : `${DIGITS}|${numberWords}`;
+  const pattern = new RegExp(`(?<![0-9０-９.,，．])(${count})\\s?(?:${marker})`, "giu");
+  return [...piece.matchAll(pattern)].map((match) => ({
+    start: offset + match.index,
+    end: offset + match.index + match[0].length,
+    count: countOf(match[1] ?? "", words),
+  }));
+};
+
+/** Whether a months count is the upper end of a range (1〜2か月). */
+const endsRange = (text: string, months: Months, words: RentMultipleWords): boolean => {
+  const before = text.slice(Math.max(0, months.start - 12), months.start).trimEnd();
+  return words.connectors.some((connector) => before.endsWith(connector) && RANGE_START.test(before.slice(0, -connector.length)));
+};
+
+type Pair = { readonly months: Months; readonly amount: StatedAmount };
+
+const gapBetween = (text: string, months: Months, amount: StatedAmount): string =>
+  amount.offset >= months.end ? text.slice(months.end, amount.offset) : text.slice(amount.end, months.start);
+
+/** A months count and an amount standing together, either way round (1か月（98,000円）, $3,200 (2 months' rent)). */
+const pairsIn = (text: string, months: readonly Months[], amounts: readonly StatedAmount[], words: RentMultipleWords): Pair[] => {
+  const between = [...words.links, ...words.rents];
+  return months.flatMap((count) =>
+    amounts
+      .filter((amount) => (amount.offset >= count.end || amount.end <= count.start) && isPlainGap(gapBetween(text, count, amount), between))
+      .map((amount) => ({ months: count, amount })),
+  );
+};
+
+type Statement = { readonly label: number; readonly pair: Pair };
+
+/** Where the statement of one label ends: at the next label of its kind, the end of the sentence, or the end of the line. */
+const statementEnd = (text: string, from: number, nextLabel: number | undefined): number => {
+  const line = lineBounds(text, from);
+  const sentence = SENTENCE_END.exec(text.slice(from, line.end));
+  return Math.min(line.end, nextLabel ?? line.end, sentence === null ? line.end : from + sentence.index);
+};
+
+/** One label's months count and amount, when the statement holds exactly one such pair and no word that makes it another. */
+const statementAt = (
+  text: string,
+  label: { readonly start: number; readonly end: number },
+  next: number | undefined,
+  amounts: readonly StatedAmount[],
+  words: RentMultipleWords,
+): Statement[] => {
+  const end = statementEnd(text, label.end, next);
+  const piece = text.slice(label.end, end);
+  if (occurrences(piece, words.skips).length > 0) return [];
+  const months = monthsIn(piece, label.end, words);
+  if (months.some((count) => endsRange(text, count, words))) return [];
+  const pairs = pairsIn(text, months, amountsBetween(amounts, label.end, end), words);
+  const [pair] = pairs;
+  const single = pairs.every((other) => other.months.count === pair?.months.count && other.amount.value === pair.amount.value);
+  return pair === undefined || !single ? [] : [{ label: label.start, pair }];
+};
+
+/** Every label of a multiple with one months count and one amount (敷金 | 2か月（98,000円）). */
+const multipleStatements = (text: string, amounts: readonly StatedAmount[], words: RentMultipleWords): Statement[] => {
+  const labels = occurrences(text, words.multiples);
+  return labels.flatMap((label, index) => statementAt(text, label, labels[index + 1]?.start, amounts, words));
+};
+
+/** The fees of the listing a rent belongs to: those after it and before the next rent; for the first rent, else those before it. */
+export const feesFor = <T extends Stated>(rent: Stated, rents: readonly Stated[], fees: readonly T[]): T[] => {
+  const index = rents.indexOf(rent);
+  const next = rents[index + 1]?.offset ?? Number.POSITIVE_INFINITY;
+  const ofCurrency = fees.filter((fee) => fee.currency === rent.currency);
+  const after = ofCurrency.filter((fee) => fee.offset > rent.offset && fee.offset < next);
+  return after.length > 0 || index > 0 ? after : ofCurrency.filter((fee) => fee.offset < rent.offset);
+};
+
+const plus = (left: Interval, right: Interval): Interval => ({ low: left.low + right.low, high: left.high + right.high });
+
+/** The monthly amounts a multiple may be of: the rent alone, the rent with each fee, and the rent with every fee. */
+export const monthlyBases = (rent: Interval, fees: readonly Interval[]): Interval[] => {
+  const withEach = fees.map((fee) => plus(rent, fee));
+  const withAll = fees.length > 1 ? [fees.reduce(plus, rent)] : [];
+  return [rent, ...withEach, ...withAll];
+};
+
+const mismatchOf = (text: string, statement: Statement, rents: readonly Stated[], fees: readonly Stated[]): StructureIssue[] => {
+  const rent = nearestStated(rents, statement.label);
+  const { months, amount } = statement.pair;
+  if (rent?.range === undefined || rent.currency !== amount.currency) return [];
+  const feeRanges = feesFor(rent, rents, fees).map((fee) => fee.range);
+  if (!feeRanges.every((range) => range !== undefined)) return [];
+  const bases = monthlyBases(rent.range, feeRanges);
+  if (isMultiple(months.count, intervalOf(amount, text.slice(amount.offset, amount.end)), bases)) return [];
+  const values = { months: text.slice(months.start, months.end), amount: text.slice(amount.offset, amount.end), rent: rent.written };
+  return [{ offset: Math.min(months.start, amount.offset), values }];
+};
+
+/** Every multiple of rent whose amount is not that many months of the listing's rent (or of the rent and its fee). */
+export const rentMultipleMismatches = (text: string, amounts: readonly StatedAmount[], words: RentMultipleWords): StructureIssue[] => {
+  const rents = statedAmounts(text, words.rents, amounts, words);
+  if (rents.length === 0) return [];
+  const fees = statedAmounts(text, words.fees, amounts, words);
+  return multipleStatements(text, amounts, words).flatMap((statement) => mismatchOf(text, statement, rents, fees));
+};

package/src/structure/revision-direction.ts

@@ -0,0 +1,214 @@
+// A forecast said to be revised one way (上方修正, revised upward) whose revision table moves the other way: a table with a
+// column of the previous forecast and one of the revised forecast (or a row of each), and a word of revision in the same
+// section. Pure; the detector passes the text, the sections, the sentences and the words of its lexicons.
+import type { Span } from "../plugin.ts";
+import type { StructureIssue } from "./issues.ts";
+import { linesOf, type Line } from "./lines.ts";
+import { cellsOf, tablesOf, type Cell } from "../facts/table-facts.ts";
+import { withoutEdgeMarks } from "../facts/trim-marks.ts";
+import { escapeRegExp } from "../orthography.ts";
+
+export type RevisionWords = {
+  /** Words that say the forecast was revised upward (上方修正, revised upward) and downward (下方修正, lowered). */
+  readonly rises: readonly string[];
+  readonly falls: readonly string[];
+  /** Verbs that say so only with a word of forecast in their sentence ("raised the forecast", not "raised funds"). */
+  readonly risesWithObject: readonly string[];
+  readonly fallsWithObject: readonly string[];
+  /** Words of forecast (予想, forecast, guidance). */
+  readonly objects: readonly string[];
+  /** Labels of the previous forecast's column or row (前回発表予想, Previous forecast) and of the revised one's. */
+  readonly previous: readonly string[];
+  readonly revised: readonly string[];
+};
+
+export type RevisionText = {
+  readonly text: string;
+  /** Where each section starts (its heading). The text before the first is a section of its own. */
+  readonly sectionStarts: readonly number[];
+  /** The sentences and headings a word of revision is read in, for the rows it names. */
+  readonly units: readonly Span[];
+};
+
+type Table = { readonly header: Line; readonly rows: readonly Line[] };
+/** One item of a revision table: its label, and its previous and revised cells. */
+export type RevisionItem = { readonly label: string; readonly previous: Cell; readonly revised: Cell };
+type Hit = Span & { readonly sign: 1 | -1 };
+type Signed = { readonly word: string; readonly sign: 1 | -1; readonly needsObject: boolean };
+
+const LATIN = /^[A-Za-z]/u;
+const LETTER = /\p{L}/u;
+const NEGATIVE = /^[-−▲△]/u;
+const CURRENCY = /^[$€£¥]/u;
+const NUMBER = /^(?:\d{1,3}(?:,\d{3})+|\d+)(?:\.\d+)?/u;
+/** What may follow the number: a unit (百万円, million), never another number or a range ("5,200〜5,400"). */
+const UNIT = /^[^\d.,]*$/u;
+const RISE: 1 | -1 = 1;
+const FALL: 1 | -1 = -1;
+
+/** The text with a leading match of the pattern taken off, and what was taken ("" when none). */
+const takeLeading = (text: string, pattern: RegExp): readonly [string, string] => {
+  const taken = pattern.exec(text)?.[0] ?? "";
+  return [taken, text.slice(taken.length).trimStart()];
+};
+
+/** Where a word stands: a Latin word as a whole word, case aside; anything else as written. */
+export const spansOf = (text: string, word: string): Span[] => {
+  const pattern = LATIN.test(word) ? new RegExp(`\\b${escapeRegExp(word)}\\b`, "giu") : new RegExp(escapeRegExp(word), "gu");
+  return [...text.matchAll(pattern)].map((match) => ({ start: match.index, end: match.index + match[0].length }));
+};
+
+const mentions = (text: string, words: readonly string[]): boolean => words.some((word) => spansOf(text, word).length > 0);
+
+/** A cell's number with the unit written around it ("5,200", "△120", "$5,200 million"); undefined when it is anything else. */
+export const amountOf = (cell: string): { readonly value: number; readonly unit: string } | undefined => {
+  const [sign, unsigned] = takeLeading(withoutEdgeMarks(cell).normalize("NFKC"), NEGATIVE);
+  const [currency, priced] = takeLeading(unsigned, CURRENCY);
+  const [digits, rest] = takeLeading(priced, NUMBER);
+  if (digits === "" || !UNIT.test(rest)) return undefined;
+  const magnitude = Number(digits.replaceAll(",", ""));
+  return { value: sign === "" ? magnitude : -magnitude, unit: [currency, rest.trim()].join("|") };
+};
+
+/** Which way an item moved: 1 up, -1 down; undefined when a cell is not a number, the units differ, or nothing moved. */
+export const moveOf = (item: RevisionItem): 1 | -1 | undefined => {
+  const [previous, revised] = [amountOf(item.previous.text), amountOf(item.revised.text)];
+  if (previous === undefined || revised === undefined || previous.unit !== revised.unit || previous.value === revised.value) return undefined;
+  return revised.value > previous.value ? 1 : -1;
+};
+
+/** The one index whose label is of the group and not of the other ("前回予想" is previous, "今回予想" revised). */
+const onlyIndex = (labels: readonly string[], group: readonly string[], other: readonly string[]): number | undefined => {
+  const indices = labels.flatMap((label, index) => (mentions(label, group) && !mentions(label, other) ? [index] : []));
+  return indices.length === 1 ? indices[0] : undefined;
+};
+
+const labelOf = (cell: Cell | undefined): string => withoutEdgeMarks(cell?.text ?? "");
+
+/** Items in rows, the previous and revised forecasts in columns (| 項目 | 前回予想 | 今回予想 |). */
+const itemsByRow = (header: readonly Cell[], rows: readonly Cell[][], words: RevisionWords): RevisionItem[] | undefined => {
+  const labels = header.map((cell) => labelOf(cell));
+  const [previous, revised] = [onlyIndex(labels, words.previous, words.revised), onlyIndex(labels, words.revised, words.previous)];
+  if (previous === undefined || revised === undefined || previous === 0 || revised === 0) return undefined;
+  return rows.flatMap((row) => {
+    const [label, before, after] = [labelOf(row[0]), row[previous], row[revised]];
+    return LETTER.test(label) && before !== undefined && after !== undefined ? [{ label, previous: before, revised: after }] : [];
+  });
+};
+
+/** Items in columns, the previous and revised forecasts in rows (| | 売上高 | 営業利益 | with a row 前回発表予想（A）). */
+const itemsByColumn = (header: readonly Cell[], rows: readonly Cell[][], words: RevisionWords): RevisionItem[] | undefined => {
+  const labels = rows.map((row) => labelOf(row[0]));
+  const [previous, revised] = [onlyIndex(labels, words.previous, words.revised), onlyIndex(labels, words.revised, words.previous)];
+  if (previous === undefined || revised === undefined) return undefined;
+  return header.slice(1).flatMap((cell, index) => {
+    const [label, before, after] = [labelOf(cell), rows[previous]?.[index + 1], rows[revised]?.[index + 1]];
+    return LETTER.test(label) && before !== undefined && after !== undefined ? [{ label, previous: before, revised: after }] : [];
+  });
+};
+
+/** The items of a revision table, in the order written; undefined when the table is not one. */
+export const revisionItems = (table: Table, words: RevisionWords): RevisionItem[] | undefined => {
+  const header = cellsOf(table.header);
+  const rows = table.rows.map((row) => cellsOf(row));
+  return itemsByRow(header, rows, words) ?? itemsByColumn(header, rows, words);
+};
+
+const sectionOf = (offset: number, starts: readonly number[], length: number): Span => {
+  const start = starts.filter((at) => at <= offset).reduce((latest, at) => Math.max(latest, at), 0);
+  const end = starts.filter((at) => at > offset).reduce((earliest, at) => Math.min(earliest, at), length);
+  return { start, end };
+};
+
+const tableSpan = (table: Table): Span => {
+  const last = table.rows.at(-1) ?? table.header;
+  return { start: table.header.start, end: last.start + last.text.length };
+};
+
+const within = (outer: Span, inner: Span): boolean => inner.start >= outer.start && inner.end <= outer.end;
+
+const signedWords = (words: RevisionWords): Signed[] => [
+  ...words.rises.map((word) => ({ word, sign: RISE, needsObject: false })),
+  ...words.falls.map((word) => ({ word, sign: FALL, needsObject: false })),
+  ...words.risesWithObject.map((word) => ({ word, sign: RISE, needsObject: true })),
+  ...words.fallsWithObject.map((word) => ({ word, sign: FALL, needsObject: true })),
+];
+
+/** The words of revision in the section, outside its tables; a verb that needs a word of forecast, with one in its sentence. */
+const hitsIn = (input: RevisionText, section: Span, tables: readonly Span[], words: RevisionWords): Hit[] => {
+  const text = input.text.slice(section.start, section.end);
+  return signedWords(words).flatMap(({ word, sign, needsObject }) =>
+    spansOf(text, word)
+      .map((span) => ({ start: span.start + section.start, end: span.end + section.start, sign }))
+      .filter((hit) => !tables.some((table) => within(table, hit)))
+      .filter((hit) => !needsObject || mentions(unitTextOf(input, hit), words.objects)),
+  );
+};
+
+/** A word revises upward inside a phrase that revises downward ("下方修正" holds no "上方修正", but "revised downward" might). */
+const outermost = (hits: readonly Hit[]): Hit[] =>
+  hits.filter((hit) => !hits.some((other) => other !== hit && within(other, hit) && other.end - other.start > hit.end - hit.start));
+
+/** The text of the sentence or heading a word stands in, else of its line. */
+const unitTextOf = (input: RevisionText, hit: Span): string => {
+  const unit = input.units.find((span) => within(span, hit));
+  if (unit !== undefined) return input.text.slice(unit.start, unit.end);
+  const line = linesOf(input.text).find((candidate) => candidate.start <= hit.start && hit.start <= candidate.start + candidate.text.length);
+  return line?.text ?? input.text.slice(hit.start, hit.end);
+};
+
+const OPENING_BRACKET = /[（(]/u;
+
+/** A label as a sentence names it: as written, or without the brackets it ends with ("Operating profit (loss)", 「売上高（百万円）」). */
+export const namesItem = (sentence: string, label: string): boolean => {
+  const core = (label.split(OPENING_BRACKET)[0] ?? "").trim();
+  return [label, core].some((name) => LETTER.test(name) && spansOf(sentence, name).length > 0);
+};
+
+/** The items the sentences of the words name; with none named, the first item, the headline figure. */
+const checkedItems = (input: RevisionText, hits: readonly Hit[], items: readonly RevisionItem[]): RevisionItem[] => {
+  const units = hits.map((hit) => unitTextOf(input, hit));
+  const named = items.filter((item) => units.some((unit) => namesItem(unit, item.label)));
+  if (named.length > 0) return named;
+  return items.slice(0, 1);
+};
+
+const issueOf = (item: RevisionItem, hit: Hit, input: RevisionText): StructureIssue => {
+  const lead = item.revised.text.length - item.revised.text.trimStart().length;
+  return {
+    offset: item.revised.start + lead,
+    values: {
+      word: input.text.slice(hit.start, hit.end),
+      item: item.label,
+      previous: withoutEdgeMarks(item.previous.text),
+      revised: withoutEdgeMarks(item.revised.text),
+    },
+  };
+};
+
+/**
+ * One revision table's mismatches. The words of the section must agree on one direction; the items checked must agree on
+ * one move (named items that moved both ways are about different words), and that move must be the other way.
+ */
+const tableIssues = (input: RevisionText, table: Table, tables: readonly Span[], words: RevisionWords): StructureIssue[] => {
+  const items = revisionItems(table, words);
+  const section = sectionOf(table.header.start, input.sectionStarts, input.text.length);
+  const hits = outermost(hitsIn(input, section, tables, words));
+  const signs = new Set(hits.map((hit) => hit.sign));
+  const [hit] = hits;
+  if (items === undefined || hit === undefined || signs.size !== 1) return [];
+  const checked = checkedItems(input, hits, items).flatMap((item) => {
+    const move = moveOf(item);
+    return move === undefined ? [] : [{ item, move }];
+  });
+  const moves = new Set(checked.map(({ move }) => move));
+  if (moves.size !== 1 || moves.has(hit.sign)) return [];
+  return checked.map(({ item }) => issueOf(item, hit, input));
+};
+
+/** Each revision table whose items move against the word of revision written in its section. */
+export const revisionDirectionMismatches = (input: RevisionText, words: RevisionWords): StructureIssue[] => {
+  const tables = tablesOf(linesOf(input.text));
+  const spans = tables.map((table) => tableSpan(table));
+  return tables.flatMap((table) => tableIssues(input, table, spans, words));
+};

package/src/structure/running-balance.ts

@@ -0,0 +1,157 @@
+// running-balance-mismatch: a table with a running balance column (a repayment schedule, an account ledger, a stock card),
+// where each row's balance is the row above's less this row's principal (or payment), or plus what came in less what went out.
+// The columns are named by their heading words only. Pure.
+import type { StructureIssue } from "./issues.ts";
+import { holds, plain, valueIn, type ChangeTable, type TableCell } from "./change-rate-table.ts";
+
+export type BalanceRole = "date" | "sequence" | "balance" | "interest" | "principal" | "in" | "out" | "payment";
+export type BalanceWord = { readonly pattern: string; readonly role: BalanceRole };
+export type BalanceWords = { readonly columns: readonly BalanceWord[]; readonly totalLabels: readonly string[] };
+
+/** A date column first (「お支払日」, "Payment date" are not payments), then the balance ("Balance after payment", 「残元金」). */
+const ROLE_ORDER: readonly BalanceRole[] = ["date", "sequence", "balance", "interest", "principal", "in", "out", "payment"];
+
+/** How a row moves the balance: down by its principal or payment (a loan), or up by what came in and down by what went out. */
+export type BalanceColumns =
+  | { readonly kind: "loan"; readonly balance: number; readonly movement: number; readonly sequence?: number }
+  | { readonly kind: "ledger"; readonly balance: number; readonly in?: number; readonly out?: number; readonly sequence?: number };
+
+/** A heading that names both directions ("Deposit/Withdrawal", 「入出金」) says neither: its sign is in each row, unread. */
+const BOTH_WAYS = "both";
+
+const roleOf = (heading: string, words: readonly BalanceWord[]): BalanceRole | typeof BOTH_WAYS | undefined => {
+  const key = plain(heading).toLowerCase();
+  const named = ROLE_ORDER.filter((role) => words.some((word) => word.role === role && holds(key, word.pattern)));
+  if (named.includes("in") && named.includes("out")) return BOTH_WAYS;
+  return named[0];
+};
+
+/** The one column of a role: undefined when none or several carry it. */
+const onlyIndex = (indexes: readonly number[]): number | undefined => (indexes.length === 1 ? indexes[0] : undefined);
+
+const optional = (key: "in" | "out" | "sequence", index: number | undefined): Record<string, number> => (index === undefined ? {} : { [key]: index });
+
+/**
+ * The columns a table's headings name. A principal column is the movement; without one, a payment column is, but only when
+ * no interest column says part of the payment is not principal. A table with both loan and ledger columns is not read, and
+ * neither is one with no date or row-number column: its rows may be different accounts or items, not one balance over time.
+ */
+export const balanceColumnsOf = (headings: readonly string[], words: readonly BalanceWord[]): BalanceColumns | undefined => {
+  const roles = headings.map((heading) => roleOf(heading, words));
+  const all = (role: BalanceRole): number[] => roles.flatMap((found, index) => (found === role ? [index] : []));
+  const balance = onlyIndex(all("balance"));
+  const sequence = optional("sequence", onlyIndex(all("sequence")));
+  const overTime = all("date").length > 0 || all("sequence").length === 1;
+  if (balance === undefined || all("sequence").length > 1 || !overTime || roles.includes(BOTH_WAYS)) return undefined;
+  const loanColumns = all("principal").length + all("payment").length + all("interest").length;
+  const ledgerColumns = all("in").length + all("out").length;
+  if (ledgerColumns > 0) {
+    const [inColumn, outColumn] = [onlyIndex(all("in")), onlyIndex(all("out"))];
+    if (loanColumns > 0 || all("in").length > 1 || all("out").length > 1) return undefined;
+    return { kind: "ledger", balance, ...optional("in", inColumn), ...optional("out", outColumn), ...sequence };
+  }
+  const principal = all("principal").length > 0 ? onlyIndex(all("principal")) : undefined;
+  const payment = all("principal").length === 0 && all("interest").length === 0 ? onlyIndex(all("payment")) : undefined;
+  const movement = principal ?? payment;
+  return movement === undefined ? undefined : { kind: "loan", balance, movement, ...sequence };
+};
+
+type Amount = { readonly value: number; readonly step: number; readonly marks: string };
+
+/** A cell that says nothing came in or went out: blank, or a dash. */
+const NOTHING = /^[-−–—―ー－]?$/u;
+
+const amountIn = (cell: TableCell | undefined): Amount | undefined => (cell === undefined ? undefined : valueIn(cell.text));
+
+/** A ledger's in or out cell: blank or a dash is zero, written to no step. */
+const ledgerAmount = (cell: TableCell | undefined, marks: string): Amount | undefined => {
+  if (cell === undefined || NOTHING.test(plain(cell.text))) return { value: 0, step: 0, marks };
+  return amountIn(cell);
+};
+
+/** The signed change a row makes to the balance, and how far rounding may move it; undefined when the row cannot say. */
+type Change = { readonly value: number; readonly step: number };
+
+const loanChange = (row: readonly TableCell[], movement: number, marks: string): Change | undefined => {
+  const amount = amountIn(row[movement]);
+  return amount === undefined || amount.marks !== marks ? undefined : { value: -amount.value, step: amount.step };
+};
+
+/** In a ledger, a row whose in and out cells are both blank says nothing of a change (a brought-forward line). */
+const ledgerChange = (row: readonly TableCell[], columns: { in?: number; out?: number }, marks: string): Change | undefined => {
+  const cellOf = (index: number | undefined): TableCell | undefined => (index === undefined ? undefined : row[index]);
+  const [came, went] = [cellOf(columns.in), cellOf(columns.out)];
+  if ([came, went].every((cell) => cell === undefined || NOTHING.test(plain(cell.text)))) return undefined;
+  const [inAmount, outAmount] = [ledgerAmount(came, marks), ledgerAmount(went, marks)];
+  if (inAmount === undefined || outAmount === undefined || inAmount.marks !== marks || outAmount.marks !== marks) return undefined;
+  return { value: inAmount.value - outAmount.value, step: inAmount.step + outAmount.step };
+};
+
+const changeOf = (row: readonly TableCell[], columns: BalanceColumns, marks: string): Change | undefined =>
+  columns.kind === "loan" ? loanChange(row, columns.movement, marks) : ledgerChange(row, columns, marks);
+
+/** A row number written as a whole number (1, 2, 3) in the sequence column; anything else in it is not counted. */
+const WHOLE = /^\d+$/u;
+/** Room for the binary fractions of decimal amounts (22,630.95 − 460.01), as a share of the rounding allowed. */
+const EPSILON = 1e-6;
+
+const balanceOf = (row: readonly TableCell[], columns: BalanceColumns): Amount | undefined => amountIn(row[columns.balance]);
+
+const isTotalRow = (row: readonly TableCell[], labels: readonly string[]): boolean => {
+  const label = plain(row[0]?.text ?? "").toLowerCase();
+  return labels.some((word) => holds(label, word));
+};
+
+/** The rows are in order: the numbers of the sequence column rise, and a loan's balance is lower at the end than at the start. */
+const inOrder = (rows: readonly (readonly TableCell[])[], columns: BalanceColumns, labels: readonly string[]): boolean => {
+  const { sequence } = columns;
+  const texts = sequence === undefined ? [] : rows.map((row) => plain(row[sequence]?.text ?? ""));
+  const numbers = texts.filter((text) => WHOLE.test(text)).map(Number);
+  if (numbers.some((number, index) => index > 0 && number <= (numbers[index - 1] ?? 0))) return false;
+  const balances = rows.flatMap((row) => (isTotalRow(row, labels) ? [] : (balanceOf(row, columns) ?? [])));
+  const [first, last] = [balances[0], balances.at(-1)];
+  return columns.kind === "ledger" || first === undefined || last === undefined || last.value <= first.value;
+};
+
+/** The expected balance written the way the cell writes its own: the same decimals, thousands commas and marks (¥, 円, $). */
+const shownAmount = (value: number, written: Amount, text: string): string => {
+  const decimals = Math.max(0, Math.round(-Math.log10(written.step)));
+  const useGrouping = text.includes(",");
+  const number = Math.abs(value).toLocaleString("en-US", { minimumFractionDigits: decimals, maximumFractionDigits: decimals, useGrouping });
+  const [before = "", after = ""] = written.marks.split("|");
+  return `${value < 0 ? "-" : ""}${before}${number}${after}`;
+};
+
+type Walk = { readonly previous?: Amount; readonly issue?: StructureIssue };
+
+/** One row's step: its balance is what the next row starts from. A row that cannot be read starts the chain again. */
+const stepOf = (walk: Walk, row: readonly TableCell[], columns: BalanceColumns, labels: readonly string[]): Walk => {
+  const cell = row[columns.balance];
+  const balance = balanceOf(row, columns);
+  if (walk.issue !== undefined) return walk;
+  if (cell === undefined || balance === undefined || isTotalRow(row, labels)) return {};
+  const change = changeOf(row, columns, balance.marks);
+  const { previous } = walk;
+  if (previous === undefined || previous.marks !== balance.marks || change === undefined) return { previous: balance };
+  const expected = previous.value + change.value;
+  const tolerance = ((previous.step + change.step + balance.step) / 2) * (1 + EPSILON);
+  if (Math.abs(expected - balance.value) <= tolerance) return { previous: balance };
+  const offset = cell.start + (cell.text.length - cell.text.trimStart().length);
+  return { issue: { offset, values: { balance: plain(cell.text), computed: shownAmount(expected, balance, plain(cell.text)) } } };
+};
+
+/**
+ * Each table's first row whose balance is not the row above's moved by this row. Only the first: a wrong balance makes the
+ * next row's sum wrong too, so the walk stops there instead of reporting every row after one slip.
+ */
+export const runningBalanceMismatches = (tables: readonly ChangeTable[], words: BalanceWords): StructureIssue[] =>
+  tables.flatMap((table) => {
+    const columns = balanceColumnsOf(
+      table.header.map((cell) => cell.text),
+      words.columns,
+    );
+    const rows = table.rows.filter((row) => row.length === table.header.length);
+    if (columns === undefined || !inOrder(rows, columns, words.totalLabels)) return [];
+    const walk = rows.reduce<Walk>((state, row) => stepOf(state, row, columns, words.totalLabels), {});
+    return walk.issue === undefined ? [] : [walk.issue];
+  });