import { mkdir, readFile, writeFile } from "node:fs/promises"; import { z } from "zod"; import { classifyObjectSchemaChange, type ObjectSchemaShape, type SchemaChangeClassification, } from "../src/contracts/compatibility.ts"; import { runtimeConfigV2ArtifactSchema } from "../src/contracts/release-artifacts.ts"; import { compatibilityFixturesArtifactSchema } from "./contracts/release-artifacts.ts"; import { writeValidatedJsonArtifact } from "./lib/validated-json-artifact.ts"; // FE-GATE-014 (07-02, 13-10). The committed baseline stands in for the schema // the previous release's reader accepts; the current schema is exactly what // the build writes to dist/runtime-config.schema.json. const BASELINE_PATH = "config/compatibility/runtime-config.schema.baseline.json"; type CompatibilityFixtures = Readonly<{ cases: readonly Readonly<{ id: string; expected: SchemaChangeClassification; before: ObjectSchemaShape; after: ObjectSchemaShape; }>[]; }>; const current = z.toJSONSchema(runtimeConfigV2ArtifactSchema); if (process.argv.includes("--update-baseline")) { await writeFile(BASELINE_PATH, `${JSON.stringify(current, null, 2)}\n`); process.stdout.write(`Updated ${BASELINE_PATH}\n`); process.exit(0); } const fixtures = JSON.parse( await readFile("config/compatibility/fixtures.json", "utf8"), ) as CompatibilityFixtures; const results = fixtures.cases.map(({ id, expected, before, after }) => { const actual = classifyObjectSchemaChange(before, after); return { id, expected, actual, passed: actual === expected }; }); const baselineClassification = classifyObjectSchemaChange( JSON.parse(await readFile(BASELINE_PATH, "utf8")) as ObjectSchemaShape, current as ObjectSchemaShape, ); const baseline = { path: BASELINE_PATH, classification: baselineClassification, passed: baselineClassification !== "breaking", }; await mkdir("artifacts/release", { recursive: true }); await writeValidatedJsonArtifact({ path: "artifacts/release/compatibility.json", schema: compatibilityFixturesArtifactSchema, value: { schemaVersion: 2, generatedAt: new Date().toISOString(), rules: [ "a change is additive only when it adds a property under a reader that tolerates unknown keys", "type, enum, nullable, required-set and unmodelled changes are breaking (fail-closed)", "adding a field at a strict (REJECT_UNKNOWN) boundary is breaking: deploy the reader first", "config and API major versions must match", "incompatible persisted cache is discarded by default", "rollback uses a coherent compatibility tuple", ], results, baseline, }, }); if (results.some((result) => !result.passed)) { process.stderr.write("Compatibility fixture classification failed.\n"); process.exit(1); } if (!baseline.passed) { process.stderr.write( `Runtime config schema change is breaking for readers of ${BASELINE_PATH}.\n` + "Follow docs/contracts/compatibility.md (deploy readers first), then run\n" + "`corepack pnpm verify:compatibility --update-baseline` and commit the baseline.\n", ); process.exit(1); } process.stdout.write( `Compatibility fixtures: PASS; runtime config schema vs baseline: ${baseline.classification}\n`, );