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 >; 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>; }>; export type SchemaChangeClassification = "breaking" | "additive" | "none"; export function classifyObjectSchemaChange( before: ObjectSchemaShape, after: ObjectSchemaShape, ): SchemaChangeClassification { const beforeRequired = new Set(before.required ?? []); const afterRequired = new Set(after.required ?? []); const removedProperties = Object.keys(before.properties ?? {}).filter( (key) => !(key in (after.properties ?? {})), ); const addedRequired = [...afterRequired].filter( (key) => !beforeRequired.has(key), ); if (removedProperties.length > 0 || addedRequired.length > 0) return "breaking"; const addedProperties = Object.keys(after.properties ?? {}).filter( (key) => !(key in (before.properties ?? {})), ); return addedProperties.length > 0 ? "additive" : "none"; }