Files
clean-architecture-frontend…/src/contracts/compatibility.ts
T
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

145 lines
4.1 KiB
TypeScript

export const COMPATIBILITY_TUPLE_FIELDS = Object.freeze([
"buildId",
"configSchemaVersion",
"apiContractVersion",
"assetManifestHash",
"releaseId",
] as const);
export type CompatibilityTupleField =
(typeof COMPATIBILITY_TUPLE_FIELDS)[number];
export type CompatibilityTuple = Readonly<
Record<CompatibilityTupleField, string>
>;
export type NumericVersion = Readonly<{
major: number;
minor: number;
patch: number;
}>;
export function parseNumericVersion(version: string): NumericVersion | null {
const match = /^(\d+)(?:\.(\d+))?(?:\.(\d+))?$/.exec(version);
if (!match) return null;
return {
major: Number(match[1]),
minor: Number(match[2] ?? 0),
patch: Number(match[3] ?? 0),
};
}
export function isVersionCompatible(
supported: string,
actual: string,
): boolean {
const expected = parseNumericVersion(supported);
const candidate = parseNumericVersion(actual);
if (!expected || !candidate) return false;
return (
expected.major === candidate.major &&
candidate.minor >= expected.minor
);
}
export function verifyCompatibilityTuple(input: Readonly<{
frontend: CompatibilityTuple;
runtime: CompatibilityTuple;
}>) {
const mismatches: CompatibilityTupleField[] = [];
if (input.frontend.buildId !== input.runtime.buildId) mismatches.push("buildId");
if (
!isVersionCompatible(
input.frontend.configSchemaVersion,
input.runtime.configSchemaVersion,
)
) {
mismatches.push("configSchemaVersion");
}
if (
!isVersionCompatible(
input.frontend.apiContractVersion,
input.runtime.apiContractVersion,
)
) {
mismatches.push("apiContractVersion");
}
if (input.frontend.assetManifestHash !== input.runtime.assetManifestHash) {
mismatches.push("assetManifestHash");
}
const releaseWarning: "releaseId" | null =
input.frontend.releaseId === input.runtime.releaseId
? null
: "releaseId";
return Object.freeze({
compatible: mismatches.length === 0,
mismatches: Object.freeze(mismatches),
warnings: Object.freeze(releaseWarning ? [releaseWarning] : []),
});
}
export type ObjectSchemaShape = Readonly<{
required?: readonly string[];
properties?: Readonly<Record<string, unknown>>;
additionalProperties?: unknown;
}>;
export type SchemaChangeClassification = "breaking" | "additive" | "none";
function canonicalJson(value: unknown): string {
return JSON.stringify(value, (_key, item: unknown) =>
item && typeof item === "object" && !Array.isArray(item)
? Object.fromEntries(
Object.entries(item).sort(([left], [right]) =>
left < right ? -1 : left > right ? 1 : 0,
),
)
: item,
);
}
/**
* Classifies an object schema change as seen by a reader built against
* `before` (07-02, 13-10). Fail-closed: the only "additive" change is a new
* property under a reader that tolerates unknown keys. Anything else that
* differs — removed or changed properties (type, enum, nullable, ...), a
* different required set, a new property under `additionalProperties: false`,
* or any other keyword — is "breaking".
*/
export function classifyObjectSchemaChange(
before: ObjectSchemaShape,
after: ObjectSchemaShape,
): SchemaChangeClassification {
const {
properties: beforeProperties = {},
required: beforeRequired = [],
...beforeRest
} = before;
const {
properties: afterProperties = {},
required: afterRequired = [],
...afterRest
} = after;
if (
canonicalJson(beforeRest) !== canonicalJson(afterRest) ||
canonicalJson([...beforeRequired].sort()) !==
canonicalJson([...afterRequired].sort())
) {
return "breaking";
}
for (const [key, schema] of Object.entries(beforeProperties)) {
if (
!Object.hasOwn(afterProperties, key) ||
canonicalJson(schema) !== canonicalJson(afterProperties[key])
) {
return "breaking";
}
}
const added = Object.keys(afterProperties).filter(
(key) => !Object.hasOwn(beforeProperties, key),
);
if (added.length === 0) return "none";
return before.additionalProperties === false ? "breaking" : "additive";
}