import { readFileSync } from "node:fs"; import { describe, expect, it } from "vitest"; import { z } from "zod"; import { classifyObjectSchemaChange, isVersionCompatible, parseNumericVersion, verifyCompatibilityTuple, } from "../../src/contracts/compatibility.ts"; import { runtimeConfigV2ArtifactSchema } from "../../src/contracts/release-artifacts.ts"; describe("contract compatibility", () => { it("uses numeric version parsing rather than lexical comparison", () => { expect(parseNumericVersion("1.10.0")).toEqual({ major: 1, minor: 10, patch: 0 }); expect(isVersionCompatible("1.9", "1.10")).toBe(true); expect(isVersionCompatible("1.9", "2.0")).toBe(false); expect(isVersionCompatible("next", "1.0")).toBe(false); }); it("rejects a runtime whose minor version is lower than the supported one", () => { expect(isVersionCompatible("2.1", "2.0")).toBe(false); expect(isVersionCompatible("2.1", "2.1")).toBe(true); }); it("distinguishes additive and breaking object changes", () => { const base = { required: ["id"], properties: { id: {} } }; expect( classifyObjectSchemaChange(base, { required: ["id"], properties: { id: {}, name: {} }, }), ).toBe("additive"); expect( classifyObjectSchemaChange(base, { required: ["id", "name"], properties: { id: {}, name: {} }, }), ).toBe("breaking"); }); it("classifies changes it cannot prove compatible as breaking", () => { const base = { required: ["id"], properties: { id: { type: "string" }, state: { type: "string", enum: ["A", "B"] }, note: { type: "string" }, }, }; const withProperty = (key: string, schema: unknown) => ({ ...base, properties: { ...base.properties, [key]: schema }, }); expect(classifyObjectSchemaChange(base, base)).toBe("none"); expect( classifyObjectSchemaChange(base, withProperty("id", { type: "number" })), ).toBe("breaking"); expect( classifyObjectSchemaChange( base, withProperty("state", { type: "string", enum: ["A"] }), ), ).toBe("breaking"); expect( classifyObjectSchemaChange( base, withProperty("note", { type: ["string", "null"] }), ), ).toBe("breaking"); expect(classifyObjectSchemaChange(base, { ...base, required: [] })).toBe( "breaking", ); expect( classifyObjectSchemaChange(base, { ...base, additionalProperties: false }), ).toBe("breaking"); }); it("treats a property added under a reader that rejects unknown keys as breaking", () => { const strict = { required: ["id"], properties: { id: {} }, additionalProperties: false, }; expect( classifyObjectSchemaChange(strict, { ...strict, properties: { id: {}, displayName: {} }, }), ).toBe("breaking"); }); it("classifies an optional runtime config key as breaking against the committed baseline", () => { const baseline = JSON.parse( readFileSync("config/compatibility/runtime-config.schema.baseline.json", "utf8"), ) as Record; const current = z.toJSONSchema(runtimeConfigV2ArtifactSchema) as Record< string, unknown > & { properties: Record }; expect(classifyObjectSchemaChange(baseline, current)).toBe("none"); expect( classifyObjectSchemaChange(baseline, { ...current, properties: { ...current.properties, NEW_OPTIONAL_KEY: { type: "string" } }, }), ).toBe("breaking"); }); it("treats release ID mismatch as a warning when the blocking tuple is coherent", () => { const frontend = { buildId: "build-a", configSchemaVersion: "1.0", apiContractVersion: "1.0", assetManifestHash: "hash-a", releaseId: "release-a", }; expect( verifyCompatibilityTuple({ frontend, runtime: { ...frontend, releaseId: "release-b" }, }), ).toEqual({ compatible: true, mismatches: [], warnings: ["releaseId"], }); }); it("blocks mixed build, config, API, or asset tuples", () => { const frontend = { buildId: "build-a", configSchemaVersion: "1.0", apiContractVersion: "1.0", assetManifestHash: "hash-a", releaseId: "release-a", }; expect( verifyCompatibilityTuple({ frontend, runtime: { ...frontend, buildId: "build-b", configSchemaVersion: "2.0", assetManifestHash: "hash-b", }, }), ).toMatchObject({ compatible: false, mismatches: ["buildId", "configSchemaVersion", "assetManifestHash"], }); }); });