Merge lane/G: contracts (07-02~07-07, 13-10, F-3, F-6, F-7)

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
donghyeon-ka
2026-09-27 13:08:05 +09:00
co-authored by Claude Opus 5.5
42 changed files with 1026 additions and 832 deletions
+16
View File
@@ -921,6 +921,22 @@ async function runGraphFixtureChecks(): Promise<GraphFixtureResult> {
target === "lucide-react",
),
},
// F-7 (13-08): zod must be configured jitless before any schema is built.
{
name: "direct zod import outside src/contracts/zod.ts is rejected",
passed: blockingViolations(importBoundaryGraph).some(
({ rule, source, target }) =>
rule === "zod-is-reached-through-contracts-zod" &&
source === "src/presentation/pages/direct-zod.ts" &&
target === "zod",
),
},
{
name: "zod through src/contracts/zod.ts is accepted",
passed: !blockingViolations(importBoundaryGraph).some(({ source }) =>
["src/contracts/zod.ts", "src/presentation/pages/wrapped-zod.ts"].includes(source),
),
},
{
name: "unselected realtime runtime composition is rejected",
passed: blockingViolations(importBoundaryGraph).some(
+55 -26
View File
@@ -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`,
);
+16 -7
View File
@@ -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
+7 -1
View File
@@ -5,6 +5,7 @@ import process from "node:process";
import {
DEPLOYMENT_TARGETS,
isDeploymentTarget,
PUBLIC_TARGETS,
type DeploymentTarget,
} from "../src/contracts/deployment-admission.ts";
import { runtimeConfigV2ArtifactSchema } from "../src/contracts/release-artifacts.ts";
@@ -64,7 +65,12 @@ export async function generateRuntimeConfig(
) {
draft["RELEASE_MANIFEST_URL"] = `${basePath}${manifestUrl.slice(1)}`;
}
const buildId = environment["VITE_BUILD_ID"] ?? "local-build";
// F-6. A public build without its own identity would ship the local
// placeholder; fail here instead of at admission.
if (PUBLIC_TARGETS.has(target) && !environment["VITE_BUILD_ID"]) {
throw new Error(`${profilePath}: a ${target} build requires VITE_BUILD_ID`);
}
const buildId = environment["VITE_BUILD_ID"] || "local-build";
const releaseId = environment["RELEASE_ID"] ?? "local-release";
draft["BUILD_ID"] = buildId;
draft["RELEASE_ID"] = releaseId;