import { spawnSync } from "node:child_process"; import { existsSync, readFileSync } from "node:fs"; import path from "node:path"; /** * 1103/12-06. Local only, outside every gate: CI checks this repository out * alone. Tells whether the paired backend checkout next to this one has moved * past the commit `config/contracts/backend-contract-pin.json` pins, and * whether the contract document changed since. * * corepack pnpm check:backend-contract-drift [--backend ] * * Exit 0: no checkout to compare, the pinned commit itself, or a later commit * whose contract document is unchanged. Exit 1: the document changed after * the pin. Recheck the frontend contract 6.1 table, the copied answer table * and the pin in one change. Exit 2: the checkout cannot be compared. */ type Pin = Readonly<{ backend: Readonly<{ repository: string; commit: string; document: string }>; }>; const PIN_PATH = "config/contracts/backend-contract-pin.json"; function backendDirectory(pin: Pin): string { const flag = process.argv.indexOf("--backend"); const given = flag >= 0 ? process.argv[flag + 1] : undefined; return given ? path.resolve(given) : path.resolve("..", pin.backend.repository); } function git(directory: string, ...args: string[]) { return spawnSync("git", ["-C", directory, ...args], { encoding: "utf8" }); } function main(): void { const pin = JSON.parse(readFileSync(PIN_PATH, "utf8")) as Pin; const directory = backendDirectory(pin); const { commit, document } = pin.backend; if (!existsSync(path.join(directory, ".git"))) { console.log( `Backend contract drift: skipped, no ${pin.backend.repository} checkout at ${directory} (pass --backend )`, ); return; } const head = git(directory, "rev-parse", "HEAD"); if (head.status !== 0 || git(directory, "cat-file", "-e", `${commit}^{commit}`).status !== 0) { console.error( `Backend contract drift: cannot compare ${directory} with the pinned ${commit.slice(0, 12)}; fetch the backend history first`, ); process.exitCode = 2; return; } const headCommit = head.stdout.trim(); if (headCommit === commit) { console.log(`Backend contract drift: ${directory} is at the pinned ${commit.slice(0, 12)}`); return; } const changed = git(directory, "diff", "--unified=0", `${commit}..HEAD`, "--", document); const tableLines = changed.stdout .split("\n") .filter((line) => /^[+-]\|/u.test(line)); if (changed.stdout.trim() === "") { console.log( `Backend contract drift: HEAD ${headCommit.slice(0, 12)} is past the pin ${commit.slice(0, 12)}, ${document} unchanged`, ); return; } console.error( `Backend contract drift: ${document} changed between the pin ${commit.slice(0, 12)} and HEAD ${headCommit.slice(0, 12)}.`, ); console.error( `Recheck docs/architecture/backend-api-and-server-state-contract.md 6.1, config/contracts/backend-idempotency-answers.json and ${PIN_PATH} together.`, ); for (const line of tableLines) console.error(` ${line}`); if (tableLines.length === 0) { console.error(" (no table rows changed; read the prose changes with git diff)"); } process.exitCode = 1; } main();