diff --git a/tests/unit/schema-metadata-policy.test.ts b/tests/unit/schema-metadata-policy.test.ts new file mode 100644 index 00000000..16923671 --- /dev/null +++ b/tests/unit/schema-metadata-policy.test.ts @@ -0,0 +1,98 @@ +import { describe, expect, it } from "vitest"; + +import type { RuntimeValidator } from "../../src/contracts/external-contract-runtime.ts"; +import { + COMPOSED_CONTRACT_CONTRIBUTIONS, + SCHEMA_REGISTRY, +} from "../../src/features/loaded-feature-runtimes.ts"; + +/** + * 1103/07-03. FE-REG-SCHEMA rows state each HTTP schema's direction and + * unknown-field policy, and `docs/contracts/compatibility.md` builds the + * "adding a response field is additive" rule on `STRIP_UNKNOWN`. Nothing at + * run time reads those two fields, so they are checked here against the + * validators the installed HTTP descriptors run. + * + * The probe is an object with one key no schema declares, and the same object + * as the only item of an array, so it reaches the first object level of an + * object or list payload. A validator that rejects it with + * `unrecognized_keys` rejects unknown fields; one that reaches the object + * without that issue tolerates them. A nested object below that level is not + * probed. + */ +const PROBE_KEY = "__unknownFieldProbe"; + +type ProbedPolicy = "REJECT_UNKNOWN" | "STRIP_UNKNOWN" | "UNREACHED"; + +function probeUnknownFieldPolicy(validator: RuntimeValidator): ProbedPolicy { + const probe = { [PROBE_KEY]: true }; + for (const [value, objectPath] of [ + [probe, []], + [[probe], [0]], + ] as const) { + const result = validator.safeParse(value); + if (result.success) return "STRIP_UNKNOWN"; + const atObject = (path: readonly (string | number)[]) => + JSON.stringify(path) === JSON.stringify(objectPath); + if ( + result.issues.some( + (issue) => issue.code === "unrecognized_keys" && atObject(issue.path), + ) + ) { + return "REJECT_UNKNOWN"; + } + // Every issue sits at or above the probed object (wrong type, wrong + // shape): the validator never looked inside it, so try the next probe. + const unreached = result.issues.every( + (issue) => + issue.path.length <= objectPath.length && + issue.path.every((segment, index) => segment === objectPath[index]), + ); + if (!unreached) return "STRIP_UNKNOWN"; + } + return "UNREACHED"; +} + +const slots = COMPOSED_CONTRACT_CONTRIBUTIONS.contributions.flatMap( + ({ http }) => + http.flatMap(({ contract }) => [ + { + operationId: contract.operationId, + direction: "REQUEST" as const, + validator: contract.inputValidator, + }, + { + operationId: contract.operationId, + direction: "RESPONSE" as const, + validator: contract.outputValidator, + }, + ]), +); + +// With no installed feature (after the sample is removed) there is nothing to +// probe, and both cases pass empty. +describe("FE-REG-SCHEMA policy of the installed HTTP schemas (1103/07-03)", () => { + it("declares the direction each schema is used in", () => { + const wrong = slots.flatMap(({ operationId, direction, validator }) => { + const declared = SCHEMA_REGISTRY[validator.schemaId]?.direction; + return declared === undefined || declared === direction + ? [] + : [`${operationId} ${validator.schemaId}: row ${declared}, used as ${direction}`]; + }); + + expect(wrong).toEqual([]); + }); + + it("declares the unknown-field policy its validator applies", () => { + const wrong = slots.flatMap(({ operationId, validator }) => { + const declared = SCHEMA_REGISTRY[validator.schemaId]?.unknownFieldPolicy; + if (declared === undefined) return []; + const probed = probeUnknownFieldPolicy(validator); + return probed === declared + ? [] + : [`${operationId} ${validator.schemaId}: row ${declared}, validator ${probed}`]; + }); + + expect(wrong).toEqual([]); + }); +});