Files
clean-architecture-frontend…/tests/unit/compatibility.test.ts
DongHyeonkaandClaude Opus 5.5 17d617ab7a fix(contracts): classify unknown schema changes as breaking and gate the runtime config schema against a baseline (07-02, 13-10)
The classifier called type, enum and nullable changes "none" and treated new
keys under strict readers as additive; FE-GATE-014 only checked hand-written
fixtures. It now fails closed and compares the committed baseline with the
schema the build emits. The doc lists per-boundary reader rules.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-09-26 00:04:25 +09:00

155 lines
4.6 KiB
TypeScript

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<string, unknown>;
const current = z.toJSONSchema(runtimeConfigV2ArtifactSchema) as Record<
string,
unknown
> & { properties: Record<string, unknown> };
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"],
});
});
});