/** * 1105/07-01. The paired backend's `http-contract.md` tables the frontend * copies at the pinned commit (`config/contracts/backend-http-contract-excerpt.json`), * read the same way from the backend document and from the copy. * * - `tests/unit/backend-contract-pin.test.ts` (test:unit) holds the answer * table JSON to the copy. It needs no backend checkout. * - `scripts/check-backend-contract-drift.ts` (local, outside the gates) holds * the copy to the backend document at the pin and reports what changed at * the backend's HEAD. */ /** Section number (`"2"` for `## 2. ...`) → its tables, each the `|` lines in order. */ export type ExcerptSections = Readonly>; export type ContractAnswerRow = Readonly<{ section: string; code: string; status: number; }>; export type NotCopiedRow = Readonly<{ section: string; code: string; reason: string; }>; const SECTION_HEADING = /^## (\d+)\.\s/u; const ANY_SECTION_HEADING = /^## /u; const CODE_HEADERS = new Set(["error.code", "코드"]); const STATUS_HEADER = "status"; const CODE_CELL = /^`([A-Z][A-Z0-9_]*)`/u; const STATUS_CELL = /^\d{3}$/u; const SEPARATOR_ROW = /^\|(?:\s*:?-+:?\s*\|)+\s*$/u; /** * The tables of the `## N.` sections named: every run of lines that start * with `|`, kept as written. A `###` heading stays inside its section. */ export function readExcerptSections( markdown: string, sections: readonly string[], ): ExcerptSections { const tables: Record = {}; let section: string | undefined; let table: string[] | undefined; for (const line of markdown.split(/\r?\n/u)) { if (ANY_SECTION_HEADING.test(line)) { section = SECTION_HEADING.exec(line)?.[1]; table = undefined; continue; } if (section === undefined || !sections.includes(section) || !line.startsWith("|")) { table = undefined; continue; } if (table === undefined) { table = []; (tables[section] ??= []).push(table); } table.push(line); } return Object.freeze( Object.fromEntries( sections.map((name) => [ name, Object.freeze((tables[name] ?? []).map((rows) => Object.freeze([...rows]))), ]), ), ); } function cells(line: string): string[] { return line .replace(/^\|/u, "") .replace(/\|\s*$/u, "") .split("|") .map((cell) => cell.trim()); } /** * The rows that answer with one error code and one status: the code column * is headed `error.code` or `코드`, the status column `status`. A row without * a code (§2's replay) or without one three-digit status is not an answer. */ export function excerptAnswerRows(sections: ExcerptSections): readonly ContractAnswerRow[] { const rows: ContractAnswerRow[] = []; for (const [section, tables] of Object.entries(sections)) { for (const table of tables) { const [header = "", ...body] = table; const headings = cells(header).map((cell) => cell.replaceAll("`", "")); const codeColumn = headings.findIndex((cell) => CODE_HEADERS.has(cell)); const statusColumn = headings.indexOf(STATUS_HEADER); if (codeColumn < 0 || statusColumn < 0) continue; for (const line of body) { if (SEPARATOR_ROW.test(line)) continue; const row = cells(line); const code = CODE_CELL.exec(row[codeColumn] ?? "")?.[1]; const status = row[statusColumn] ?? ""; if (code !== undefined && STATUS_CELL.test(status)) { rows.push(Object.freeze({ section, code, status: Number(status) })); } } } } return Object.freeze(rows); } /** * What the copied answer table gets wrong against the excerpt: an answer the * named section does not have, an excerpt row neither copied nor listed as * not copied, and a not-copied entry the excerpt does not have. An answer * covers an excerpt row of any section with the same code and status (§4 * repeats §2's `IDEMPOTENCY_KEY_INVALID`). */ export function answerTableProblems( answers: readonly ContractAnswerRow[], notCopied: readonly NotCopiedRow[], excerpt: readonly ContractAnswerRow[], ): readonly string[] { const problems: string[] = []; for (const answer of answers) { const inSection = excerpt.some( (row) => row.section === answer.section && row.code === answer.code && row.status === answer.status, ); if (!inSection) { problems.push( `answer ${answer.status} ${answer.code} is not a row of the pinned document's §${answer.section}`, ); } } for (const row of excerpt) { const copied = answers.some( (answer) => answer.code === row.code && answer.status === row.status, ); const skipped = notCopied.some( (entry) => entry.section === row.section && entry.code === row.code, ); if (copied && skipped) { problems.push( `§${row.section} ${row.status} ${row.code} is both copied and listed in notCopied`, ); } else if (!copied && !skipped) { problems.push( `§${row.section} ${row.status} ${row.code} is neither in the answer table nor in the pin's notCopied`, ); } } for (const entry of notCopied) { if (!excerpt.some((row) => row.section === entry.section && row.code === entry.code)) { problems.push( `notCopied ${entry.code} is not a row of the pinned document's §${entry.section}`, ); } } return Object.freeze(problems); } /** * The lines one excerpt has and the other does not, per section: `-` only * in `expected`, `+` only in `actual`. Empty when they are the same. */ export function excerptDifferences( expected: ExcerptSections, actual: ExcerptSections, ): readonly string[] { const differences: string[] = []; const names = [...new Set([...Object.keys(expected), ...Object.keys(actual)])].sort(); for (const name of names) { const before = (expected[name] ?? []).flat(); const after = (actual[name] ?? []).flat(); const sameTables = JSON.stringify(expected[name] ?? []) === JSON.stringify(actual[name] ?? []); if (sameTables) continue; const removed = before.filter((line) => !after.includes(line)); const added = after.filter((line) => !before.includes(line)); for (const line of removed) differences.push(`§${name} -${line}`); for (const line of added) differences.push(`§${name} +${line}`); if (removed.length === 0 && added.length === 0) { differences.push(`§${name} the same rows, split into tables or ordered differently`); } } return Object.freeze(differences); }