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>
145 lines
4.1 KiB
TypeScript
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";
|
|
}
|