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>
This commit is contained in:
co-authored by
Claude Opus 5.5
parent
4d17259037
commit
17d617ab7a
@@ -1,63 +1,67 @@
|
||||
{
|
||||
"schemaVersion": 1,
|
||||
"families": {
|
||||
"api": {
|
||||
"additive": {
|
||||
"before": { "required": ["id"], "properties": { "id": {} } },
|
||||
"after": {
|
||||
"required": ["id"],
|
||||
"properties": { "id": {}, "displayName": {} }
|
||||
}
|
||||
},
|
||||
"breaking": {
|
||||
"before": { "required": ["id"], "properties": { "id": {} } },
|
||||
"after": {
|
||||
"required": ["id", "name"],
|
||||
"properties": { "id": {}, "name": {} }
|
||||
}
|
||||
"schemaVersion": 2,
|
||||
"cases": [
|
||||
{
|
||||
"id": "tolerant-reader-optional-field",
|
||||
"expected": "additive",
|
||||
"before": { "required": ["id"], "properties": { "id": {} } },
|
||||
"after": {
|
||||
"required": ["id"],
|
||||
"properties": { "id": {}, "displayName": {} }
|
||||
}
|
||||
},
|
||||
"config": {
|
||||
"additive": {
|
||||
"before": { "required": ["APP_ENV"], "properties": { "APP_ENV": {} } },
|
||||
"after": {
|
||||
"required": ["APP_ENV"],
|
||||
"properties": { "APP_ENV": {}, "OPTIONAL_FLAG": {} }
|
||||
}
|
||||
{
|
||||
"id": "strict-reader-optional-field",
|
||||
"expected": "breaking",
|
||||
"before": {
|
||||
"required": ["APP_ENV"],
|
||||
"properties": { "APP_ENV": {} },
|
||||
"additionalProperties": false
|
||||
},
|
||||
"breaking": {
|
||||
"before": { "required": ["APP_ENV"], "properties": { "APP_ENV": {} } },
|
||||
"after": {
|
||||
"required": ["APP_ENV", "NEW_REQUIRED"],
|
||||
"properties": { "APP_ENV": {}, "NEW_REQUIRED": {} }
|
||||
}
|
||||
"after": {
|
||||
"required": ["APP_ENV"],
|
||||
"properties": { "APP_ENV": {}, "OPTIONAL_FLAG": {} },
|
||||
"additionalProperties": false
|
||||
}
|
||||
},
|
||||
"storage": {
|
||||
"additive": {
|
||||
"before": { "properties": { "theme": {} } },
|
||||
"after": { "properties": { "theme": {}, "contrast": {} } }
|
||||
},
|
||||
"breaking": {
|
||||
"before": { "properties": { "theme": {} } },
|
||||
"after": { "properties": {} }
|
||||
{
|
||||
"id": "required-field-added",
|
||||
"expected": "breaking",
|
||||
"before": { "required": ["buildId"], "properties": { "buildId": {} } },
|
||||
"after": {
|
||||
"required": ["buildId", "assetManifestHash"],
|
||||
"properties": { "buildId": {}, "assetManifestHash": {} }
|
||||
}
|
||||
},
|
||||
"release": {
|
||||
"additive": {
|
||||
"before": { "required": ["buildId"], "properties": { "buildId": {} } },
|
||||
"after": {
|
||||
"required": ["buildId"],
|
||||
"properties": { "buildId": {}, "builtAt": {} }
|
||||
}
|
||||
},
|
||||
"breaking": {
|
||||
"before": { "required": ["buildId"], "properties": { "buildId": {} } },
|
||||
"after": {
|
||||
"required": ["buildId", "assetManifestHash"],
|
||||
"properties": { "buildId": {}, "assetManifestHash": {} }
|
||||
}
|
||||
}
|
||||
{
|
||||
"id": "field-removed",
|
||||
"expected": "breaking",
|
||||
"before": { "properties": { "theme": {} } },
|
||||
"after": { "properties": {} }
|
||||
},
|
||||
{
|
||||
"id": "type-changed",
|
||||
"expected": "breaking",
|
||||
"before": { "properties": { "id": { "type": "string" } } },
|
||||
"after": { "properties": { "id": { "type": "number" } } }
|
||||
},
|
||||
{
|
||||
"id": "enum-narrowed",
|
||||
"expected": "breaking",
|
||||
"before": { "properties": { "state": { "enum": ["A", "B"] } } },
|
||||
"after": { "properties": { "state": { "enum": ["A"] } } }
|
||||
},
|
||||
{
|
||||
"id": "nullable-added",
|
||||
"expected": "breaking",
|
||||
"before": { "properties": { "note": { "type": "string" } } },
|
||||
"after": { "properties": { "note": { "type": ["string", "null"] } } }
|
||||
},
|
||||
{
|
||||
"id": "unchanged",
|
||||
"expected": "none",
|
||||
"before": { "required": ["id"], "properties": { "id": { "type": "string" } } },
|
||||
"after": { "properties": { "id": { "type": "string" } }, "required": ["id"] }
|
||||
}
|
||||
}
|
||||
]
|
||||
}
|
||||
|
||||
@@ -0,0 +1,140 @@
|
||||
{
|
||||
"$schema": "https://json-schema.org/draft/2020-12/schema",
|
||||
"type": "object",
|
||||
"properties": {
|
||||
"APP_ENV": {
|
||||
"type": "string",
|
||||
"enum": [
|
||||
"local",
|
||||
"development",
|
||||
"staging",
|
||||
"production"
|
||||
]
|
||||
},
|
||||
"API_BASE_URL": {
|
||||
"type": "string",
|
||||
"format": "uri"
|
||||
},
|
||||
"REQUEST_TIMEOUT_MS": {
|
||||
"default": 10000,
|
||||
"type": "integer",
|
||||
"minimum": 100,
|
||||
"maximum": 60000
|
||||
},
|
||||
"MAX_RETRY_ATTEMPTS": {
|
||||
"default": 2,
|
||||
"type": "integer",
|
||||
"minimum": 0,
|
||||
"maximum": 2
|
||||
},
|
||||
"TELEMETRY_ENABLED": {
|
||||
"type": "boolean"
|
||||
},
|
||||
"TELEMETRY_ENDPOINT": {
|
||||
"type": "string",
|
||||
"format": "uri"
|
||||
},
|
||||
"AUTH_MODE": {
|
||||
"type": "string",
|
||||
"enum": [
|
||||
"external",
|
||||
"demo"
|
||||
]
|
||||
},
|
||||
"RELEASE_MANIFEST_URL": {
|
||||
"default": "/release-manifest.json",
|
||||
"type": "string",
|
||||
"minLength": 1
|
||||
},
|
||||
"RELEASE_ID": {
|
||||
"type": "string",
|
||||
"minLength": 1
|
||||
},
|
||||
"BUILD_ID": {
|
||||
"type": "string",
|
||||
"minLength": 1
|
||||
},
|
||||
"CONFIG_SCHEMA_VERSION": {
|
||||
"type": "string",
|
||||
"const": "2.0"
|
||||
},
|
||||
"CAPABILITY_OVERRIDES": {
|
||||
"default": {
|
||||
"REALTIME": "DEFAULT",
|
||||
"WEB_WORKER": "DEFAULT",
|
||||
"SERVICE_WORKER": "DEFAULT",
|
||||
"OFFLINE_COMMANDS": "DEFAULT"
|
||||
},
|
||||
"type": "object",
|
||||
"properties": {
|
||||
"REALTIME": {
|
||||
"default": "DEFAULT",
|
||||
"type": "string",
|
||||
"enum": [
|
||||
"DEFAULT",
|
||||
"DISABLED"
|
||||
]
|
||||
},
|
||||
"WEB_WORKER": {
|
||||
"default": "DEFAULT",
|
||||
"type": "string",
|
||||
"enum": [
|
||||
"DEFAULT",
|
||||
"DISABLED"
|
||||
]
|
||||
},
|
||||
"SERVICE_WORKER": {
|
||||
"default": "DEFAULT",
|
||||
"type": "string",
|
||||
"enum": [
|
||||
"DEFAULT",
|
||||
"DISABLED"
|
||||
]
|
||||
},
|
||||
"OFFLINE_COMMANDS": {
|
||||
"default": "DEFAULT",
|
||||
"type": "string",
|
||||
"enum": [
|
||||
"DEFAULT",
|
||||
"DISABLED"
|
||||
]
|
||||
}
|
||||
},
|
||||
"required": [
|
||||
"REALTIME",
|
||||
"WEB_WORKER",
|
||||
"SERVICE_WORKER",
|
||||
"OFFLINE_COMMANDS"
|
||||
],
|
||||
"additionalProperties": false
|
||||
},
|
||||
"FEATURE_OVERRIDES": {
|
||||
"default": {},
|
||||
"type": "object",
|
||||
"propertyNames": {
|
||||
"type": "string",
|
||||
"pattern": "^[a-z][a-z0-9-]{0,63}$"
|
||||
},
|
||||
"additionalProperties": {
|
||||
"type": "string",
|
||||
"enum": [
|
||||
"DEFAULT",
|
||||
"DISABLED"
|
||||
]
|
||||
}
|
||||
}
|
||||
},
|
||||
"required": [
|
||||
"APP_ENV",
|
||||
"API_BASE_URL",
|
||||
"REQUEST_TIMEOUT_MS",
|
||||
"MAX_RETRY_ATTEMPTS",
|
||||
"TELEMETRY_ENABLED",
|
||||
"AUTH_MODE",
|
||||
"RELEASE_MANIFEST_URL",
|
||||
"CONFIG_SCHEMA_VERSION",
|
||||
"CAPABILITY_OVERRIDES",
|
||||
"FEATURE_OVERRIDES"
|
||||
],
|
||||
"additionalProperties": false
|
||||
}
|
||||
@@ -3,13 +3,66 @@
|
||||
The blocking tuple is `(buildId, configSchemaVersion, apiContractVersion,
|
||||
assetManifestHash, releaseId)`. Versions are parsed numerically.
|
||||
|
||||
1. additive changes preserve current required fields
|
||||
2. breaking changes require a major version bump
|
||||
1. a change is additive only when it adds an optional field that every
|
||||
reader of the previous version tolerates; see the boundary table below
|
||||
2. breaking changes require a major version bump or a reader-first deployment
|
||||
3. persisted cache is discarded unless an explicit tested migration exists
|
||||
4. an incompatible config or API contract blocks product mount
|
||||
5. rollback restores HTML, assets, runtime config, API compatibility, and
|
||||
release manifest as one coherent set
|
||||
|
||||
## Per-boundary rules
|
||||
|
||||
Whether "add a field" is safe depends on the reader, not on the writer. Old
|
||||
readers stay alive: several tabs, cached app shells and rollbacks are all
|
||||
supported. At a `REJECT_UNKNOWN` boundary an added field is breaking, so the
|
||||
reader that accepts it must ship before any writer sends it.
|
||||
|
||||
| Boundary | Reader policy | Adding a field or value | Code |
|
||||
|---|---|---|---|
|
||||
| Runtime config V2 (`/config.json`) | strict object; `CONFIG_SCHEMA_VERSION` is the literal `"2.0"` | breaking | `src/contracts/release-artifacts.ts:163-171` |
|
||||
| `CAPABILITY_OVERRIDES` | strict; unknown capability rejected | breaking | `src/contracts/release-artifacts.ts:50-63` |
|
||||
| `FEATURE_OVERRIDES` | record; unknown feature id ignored | additive | `src/contracts/release-artifacts.ts:65-80` |
|
||||
| Release manifest V2 | strict object | breaking | `src/contracts/release-artifacts.ts:200-208` |
|
||||
| HTTP V2 success/failure envelope | strict object (`meta` strips) | breaking | `src/adapters/http/schema-registry.ts:12-34` |
|
||||
| HTTP V3 response DTO (reference feature) | `.strip()` drops unknown fields | additive | `src/features/reference-feature/contracts/reference-schemas.ts:29-35` |
|
||||
| Realtime envelope | exact key set; unknown `eventType` is `MALFORMED_EVENT` | breaking | `src/adapters/realtime/event-codec.ts:126,149` |
|
||||
| Browser RPC transport error code | closed vocabulary; unknown code is a protocol violation | breaking | `src/adapters/browser-rpc/browser-rpc-runtime.ts:1473` |
|
||||
| Persisted client storage | versioned key; incompatible value discarded | use a new key version | `src/contracts/storage-keys.ts:138-140` |
|
||||
|
||||
`CAPABILITY_OVERRIDES` and `FEATURE_OVERRIDES` differ on purpose. Feature ids
|
||||
vary per build because each downstream project installs its own features, and
|
||||
one shared config document may cover several builds. The capability set is
|
||||
fixed by the platform version, so an unknown capability means the config was
|
||||
written for a newer platform; it is treated like any other strict config
|
||||
addition.
|
||||
|
||||
## Schema change classifier and FE-GATE-014
|
||||
|
||||
`classifyObjectSchemaChange` (`src/contracts/compatibility.ts:110`) answers
|
||||
for a reader built against `before`. It is fail-closed: only a new property
|
||||
under a reader without `additionalProperties: false` is `additive`. A removed
|
||||
or changed property (type, enum, nullable, format, ...), a different required
|
||||
set, or any other changed keyword is `breaking`. Nothing differs: `none`.
|
||||
|
||||
FE-GATE-014 (`config-compatibility`, `corepack pnpm verify:compatibility`)
|
||||
runs `scripts/check-compatibility.ts`. It does two things:
|
||||
|
||||
1. Classifies the hand-written cases in `config/compatibility/fixtures.json`
|
||||
and fails if any result differs from `expected`.
|
||||
2. Compares the committed baseline
|
||||
`config/compatibility/runtime-config.schema.baseline.json` with the current
|
||||
runtime config schema, which is the same `z.toJSONSchema` output the build
|
||||
writes to `dist/runtime-config.schema.json`
|
||||
(`scripts/generate-build-manifest.ts`). A `breaking` result fails the gate.
|
||||
|
||||
The baseline stands for the schema that readers of the previous release
|
||||
accept. When a breaking config change is intended, deploy the reader first (or
|
||||
bump the config major version), then run
|
||||
`corepack pnpm verify:compatibility --update-baseline` and commit the new
|
||||
baseline with the change. The result is recorded in
|
||||
`artifacts/release/compatibility.json`.
|
||||
|
||||
The current `apiContractVersion` check proves release/config coherence, not
|
||||
provider conformance by itself. The target multi-protocol contract set binds
|
||||
REST/OpenAPI artifacts, GraphQL schema and persisted-operation manifests,
|
||||
|
||||
@@ -1,53 +1,72 @@
|
||||
import { mkdir, readFile } from "node:fs/promises";
|
||||
import { mkdir, readFile, writeFile } from "node:fs/promises";
|
||||
|
||||
import { classifyObjectSchemaChange } from "../src/contracts/compatibility.ts";
|
||||
import { z } from "zod";
|
||||
|
||||
import {
|
||||
classifyObjectSchemaChange,
|
||||
type ObjectSchemaShape,
|
||||
type SchemaChangeClassification,
|
||||
} from "../src/contracts/compatibility.ts";
|
||||
import { runtimeConfigV2ArtifactSchema } from "../src/contracts/release-artifacts.ts";
|
||||
import { compatibilityFixturesArtifactSchema } from "./contracts/release-artifacts.ts";
|
||||
import { writeValidatedJsonArtifact } from "./lib/validated-json-artifact.ts";
|
||||
|
||||
type CompatibilitySchema = Readonly<{
|
||||
required?: readonly string[];
|
||||
properties?: Readonly<Record<string, unknown>>;
|
||||
}>;
|
||||
|
||||
type CompatibilityFixture = Readonly<{
|
||||
before: CompatibilitySchema;
|
||||
after: CompatibilitySchema;
|
||||
}>;
|
||||
// FE-GATE-014 (07-02, 13-10). The committed baseline stands in for the schema
|
||||
// the previous release's reader accepts; the current schema is exactly what
|
||||
// the build writes to dist/runtime-config.schema.json.
|
||||
const BASELINE_PATH = "config/compatibility/runtime-config.schema.baseline.json";
|
||||
|
||||
type CompatibilityFixtures = Readonly<{
|
||||
families: Readonly<
|
||||
Record<string, Readonly<Record<"additive" | "breaking", CompatibilityFixture>>>
|
||||
>;
|
||||
cases: readonly Readonly<{
|
||||
id: string;
|
||||
expected: SchemaChangeClassification;
|
||||
before: ObjectSchemaShape;
|
||||
after: ObjectSchemaShape;
|
||||
}>[];
|
||||
}>;
|
||||
|
||||
const current = z.toJSONSchema(runtimeConfigV2ArtifactSchema);
|
||||
if (process.argv.includes("--update-baseline")) {
|
||||
await writeFile(BASELINE_PATH, `${JSON.stringify(current, null, 2)}\n`);
|
||||
process.stdout.write(`Updated ${BASELINE_PATH}\n`);
|
||||
process.exit(0);
|
||||
}
|
||||
|
||||
const fixtures = JSON.parse(
|
||||
await readFile("config/compatibility/fixtures.json", "utf8"),
|
||||
) as CompatibilityFixtures;
|
||||
const results = [];
|
||||
const results = fixtures.cases.map(({ id, expected, before, after }) => {
|
||||
const actual = classifyObjectSchemaChange(before, after);
|
||||
return { id, expected, actual, passed: actual === expected };
|
||||
});
|
||||
|
||||
for (const [family, cases] of Object.entries(fixtures.families)) {
|
||||
for (const expected of ["additive", "breaking"] as const) {
|
||||
const fixture = cases[expected];
|
||||
const actual = classifyObjectSchemaChange(fixture.before, fixture.after);
|
||||
results.push({ family, expected, actual, passed: actual === expected });
|
||||
}
|
||||
}
|
||||
const baselineClassification = classifyObjectSchemaChange(
|
||||
JSON.parse(await readFile(BASELINE_PATH, "utf8")) as ObjectSchemaShape,
|
||||
current as ObjectSchemaShape,
|
||||
);
|
||||
const baseline = {
|
||||
path: BASELINE_PATH,
|
||||
classification: baselineClassification,
|
||||
passed: baselineClassification !== "breaking",
|
||||
};
|
||||
|
||||
await mkdir("artifacts/release", { recursive: true });
|
||||
await writeValidatedJsonArtifact({
|
||||
path: "artifacts/release/compatibility.json",
|
||||
schema: compatibilityFixturesArtifactSchema,
|
||||
value: {
|
||||
schemaVersion: 1,
|
||||
schemaVersion: 2,
|
||||
generatedAt: new Date().toISOString(),
|
||||
rules: [
|
||||
"additive changes preserve required fields",
|
||||
"breaking changes require version bump and migration, discard, fallback, or rollback",
|
||||
"a change is additive only when it adds a property under a reader that tolerates unknown keys",
|
||||
"type, enum, nullable, required-set and unmodelled changes are breaking (fail-closed)",
|
||||
"adding a field at a strict (REJECT_UNKNOWN) boundary is breaking: deploy the reader first",
|
||||
"config and API major versions must match",
|
||||
"incompatible persisted cache is discarded by default",
|
||||
"rollback uses a coherent compatibility tuple",
|
||||
],
|
||||
results,
|
||||
baseline,
|
||||
},
|
||||
});
|
||||
|
||||
@@ -55,4 +74,14 @@ if (results.some((result) => !result.passed)) {
|
||||
process.stderr.write("Compatibility fixture classification failed.\n");
|
||||
process.exit(1);
|
||||
}
|
||||
process.stdout.write("Compatibility fixtures: PASS\n");
|
||||
if (!baseline.passed) {
|
||||
process.stderr.write(
|
||||
`Runtime config schema change is breaking for readers of ${BASELINE_PATH}.\n` +
|
||||
"Follow docs/contracts/compatibility.md (deploy readers first), then run\n" +
|
||||
"`corepack pnpm verify:compatibility --update-baseline` and commit the baseline.\n",
|
||||
);
|
||||
process.exit(1);
|
||||
}
|
||||
process.stdout.write(
|
||||
`Compatibility fixtures: PASS; runtime config schema vs baseline: ${baseline.classification}\n`,
|
||||
);
|
||||
|
||||
@@ -1338,32 +1338,41 @@ export const supplyChainProviderFixturesArtifactSchema = z
|
||||
}
|
||||
});
|
||||
|
||||
const compatibilityClassificationSchema = z.enum(["additive", "breaking"]);
|
||||
const compatibilityClassificationSchema = z.enum(["additive", "breaking", "none"]);
|
||||
export const compatibilityFixturesArtifactSchema = z
|
||||
.object({
|
||||
schemaVersion: z.literal(1),
|
||||
schemaVersion: z.literal(2),
|
||||
generatedAt: timestamp,
|
||||
rules: z.array(nonEmptyString).length(5),
|
||||
rules: z.array(nonEmptyString).min(1),
|
||||
results: z.array(
|
||||
z
|
||||
.object({
|
||||
family: z.enum(["api", "config", "storage", "release"]),
|
||||
id: nonEmptyString,
|
||||
expected: compatibilityClassificationSchema,
|
||||
actual: compatibilityClassificationSchema,
|
||||
passed: z.boolean(),
|
||||
})
|
||||
.strict(),
|
||||
).length(8),
|
||||
).min(1),
|
||||
baseline: z
|
||||
.object({
|
||||
path: nonEmptyString,
|
||||
classification: compatibilityClassificationSchema,
|
||||
passed: z.boolean(),
|
||||
})
|
||||
.strict(),
|
||||
})
|
||||
.strict()
|
||||
.superRefine((artifact, context) => {
|
||||
const keys = artifact.results.map(({ family, expected }) => `${family}\0${expected}`);
|
||||
addUniqueStringIssues(keys, ["results"], context);
|
||||
addUniqueStringIssues(artifact.results.map(({ id }) => id), ["results"], context);
|
||||
artifact.results.forEach((result, index) => {
|
||||
if (result.passed !== (result.actual === result.expected)) {
|
||||
context.addIssue({ code: "custom", path: ["results", index, "passed"], message: "must agree with expected and actual" });
|
||||
}
|
||||
});
|
||||
if (artifact.baseline.passed !== (artifact.baseline.classification !== "breaking")) {
|
||||
context.addIssue({ code: "custom", path: ["baseline", "passed"], message: "must fail exactly when the baseline change is breaking" });
|
||||
}
|
||||
});
|
||||
|
||||
export const documentationReviewArtifactSchema = z
|
||||
|
||||
@@ -82,26 +82,63 @@ export function verifyCompatibilityTuple(input: Readonly<{
|
||||
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 beforeRequired = new Set(before.required ?? []);
|
||||
const afterRequired = new Set(after.required ?? []);
|
||||
const removedProperties = Object.keys(before.properties ?? {}).filter(
|
||||
(key) => !(key in (after.properties ?? {})),
|
||||
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),
|
||||
);
|
||||
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";
|
||||
if (added.length === 0) return "none";
|
||||
return before.additionalProperties === false ? "breaking" : "additive";
|
||||
}
|
||||
|
||||
@@ -1,4 +1,7 @@
|
||||
import { readFileSync } from "node:fs";
|
||||
|
||||
import { describe, expect, it } from "vitest";
|
||||
import { z } from "zod";
|
||||
|
||||
import {
|
||||
classifyObjectSchemaChange,
|
||||
@@ -6,6 +9,7 @@ import {
|
||||
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", () => {
|
||||
@@ -15,6 +19,11 @@ describe("contract compatibility", () => {
|
||||
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(
|
||||
@@ -31,6 +40,74 @@ describe("contract compatibility", () => {
|
||||
).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",
|
||||
|
||||
Reference in New Issue
Block a user