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();