import { describe, expect, it } from "vitest"; import { ContractContributionError, composeContractContributions, invokeValidator, type InstalledContractContribution, type RuntimeValidator, } from "../../src/contracts/external-contract-runtime.ts"; import { listUnvalidatedPayloads, unvalidatedPayload, } from "../../src/contracts/unvalidated-payload.ts"; import { TEST_CONTRACT_CONTRIBUTION, TEST_EVENT_CONTRACT, } from "../helpers/external-contract-fixture.ts"; function contribution( contributionId: string, http: InstalledContractContribution["http"], ): InstalledContractContribution & Readonly<{ contributionId: string }> { return Object.freeze({ ...TEST_CONTRACT_CONTRIBUTION, contributionId, http: Object.freeze([...http]), }); } function captureContributionError(operation: () => unknown): ContractContributionError { try { operation(); } catch (error) { expect(error).toBeInstanceOf(ContractContributionError); return error as ContractContributionError; } throw new Error("Expected contract composition to fail."); } describe("external contract contribution composition", () => { it("allows one feature to install multiple uniquely identified contributions", () => { const operations = TEST_CONTRACT_CONTRIBUTION.http; const composed = composeContractContributions([ contribution("test-read-contracts", operations.slice(0, 2)), contribution("test-command-contracts", operations.slice(2)), ]); expect(composed.contributions).toHaveLength(2); expect(composed.httpByOperationId.size).toBe(3); }); it("rejects duplicate contribution identities even across different feature entries", () => { const first = contribution( "test-contracts", TEST_CONTRACT_CONTRIBUTION.http.slice(0, 1), ); const second = contribution( "test-contracts", TEST_CONTRACT_CONTRIBUTION.http.slice(1), ); const error = captureContributionError(() => composeContractContributions([first, second]), ); expect(error.reason).toContain("duplicate contributionId"); }); it("maps malformed source values to the closed composition error", () => { const malformed = { ...contribution("malformed-source", []), source: null, } as unknown as InstalledContractContribution; const error = captureContributionError(() => composeContractContributions([malformed]), ); expect(error.reason).toContain("source"); }); it("rejects method and body vocabulary outside the runtime protocol", () => { const installed = TEST_CONTRACT_CONTRIBUTION.http[0]!; const malformedOperation = { ...installed, contract: { ...installed.contract, method: "TRACE" }, } as unknown as InstalledContractContribution["http"][number]; const error = captureContributionError(() => composeContractContributions([ contribution("invalid-http-vocabulary", [malformedOperation]), ]), ); expect(error.reason).toContain("method"); }); }); // 07-06 (MX1, MX9, MX6). The write-API rules the composer teaches through its // error messages. TEST_CONTRACT_CONTRIBUTION composing in the first block is // the valid control. describe("write operation rules", () => { const [listRow, , createRow] = TEST_CONTRACT_CONTRIBUTION.http as readonly [ InstalledContractContribution["http"][number], InstalledContractContribution["http"][number], InstalledContractContribution["http"][number], ]; function reasonFor(row: object): string { return captureContributionError(() => composeContractContributions([ contribution("write-rule", [ row as InstalledContractContribution["http"][number], ]), ]), ).reason; } // The executor decides "write" by `commandEffect !== null`, not by method, // so this rule is the only thing keeping a GET from running as a command. it("rejects command descriptors on a read operation", () => { expect( reasonFor({ ...listRow, contract: { ...listRow.contract, commandEffect: createRow.contract.commandEffect }, }), ).toBe("test-feature/TEST_LIST_ENTITIES: read operations carry no command descriptors"); }); // 1103/07-01 (c). The KEYED recovery check sits in the write branch, so a // GET written as KEYED or NEVER used to compose and run as a read with no // retry. A read is SAFE or IDEMPOTENT (docs/manual/02-decision-tables.md 3절). it.each([ ["GET", "KEYED"], ["GET", "NEVER"], ["HEAD", "KEYED"], ["HEAD", "NEVER"], ] as const)("rejects a %s declared %s", (method, retrySemantics) => { expect( reasonFor({ ...listRow, contract: { ...listRow.contract, method, retrySemantics }, frontend: { ...listRow.frontend, retryBudget: 0 }, }), ).toBe( `test-feature/TEST_LIST_ENTITIES: ${method} is a read; its retrySemantics is SAFE or IDEMPOTENT, not ${retrySemantics}`, ); }); it.each(["SAFE", "IDEMPOTENT"] as const)("composes a GET declared %s", (retrySemantics) => { expect( composeContractContributions([ contribution("read-rule", [ { ...listRow, contract: { ...listRow.contract, retrySemantics }, } as InstalledContractContribution["http"][number], ]), ]).httpByOperationId.size, ).toBe(1); }); it("requires a recovery descriptor on a KEYED command", () => { expect( reasonFor({ ...createRow, contract: { ...createRow.contract, commandRecovery: null }, }), ).toBe("test-feature/TEST_CREATE_ENTITY: KEYED commands require a recovery descriptor"); }); it("rejects a retry budget on a NEVER-retry operation", () => { expect( reasonFor({ ...createRow, contract: { ...createRow.contract, retrySemantics: "NEVER" }, frontend: { ...createRow.frontend, retryBudget: 1 }, }), ).toBe("test-feature/TEST_CREATE_ENTITY: retry budget contradicts NEVER retry semantics"); }); // 1103/03-03. SAFE lets the executor resend after dispatch, which a write // copied from the scaffold's GET would then do with a lost answer. it.each(["POST", "PUT", "PATCH", "DELETE"])( "rejects SAFE retry semantics on a %s", (method) => { expect( reasonFor({ ...createRow, contract: { ...createRow.contract, method, retrySemantics: "SAFE", commandRecovery: null, }, frontend: { ...createRow.frontend, retryBudget: 2 }, }), ).toBe( `test-feature/TEST_CREATE_ENTITY: SAFE retry semantics is for GET and HEAD only; a ${method} declares IDEMPOTENT, KEYED or NEVER (docs/manual/02-decision-tables.md §3)`, ); }, ); it("keeps SAFE on a read and IDEMPOTENT on a write", () => { expect(() => composeContractContributions([ contribution("write-rule", [ listRow, { ...createRow, contract: { ...createRow.contract, method: "PUT", retrySemantics: "IDEMPOTENT", commandRecovery: null, }, } as InstalledContractContribution["http"][number], ]), ]), ).not.toThrow(); }); }); // 1103/03-01. A command names the backend codes its endpoint raises only // before it writes. Composition decides what such a list may hold. describe("declared pre-write refusals", () => { const [, , createRow] = TEST_CONTRACT_CONTRIBUTION.http as readonly [ InstalledContractContribution["http"][number], InstalledContractContribution["http"][number], InstalledContractContribution["http"][number], ]; function withRefusals( refusedBeforeWrite: unknown, responseEnvelope: unknown = "ENVELOPE_V1", ) { return contribution("refusal-rule", [ { ...createRow, contract: { ...createRow.contract, responseEnvelope, commandEffect: { ...createRow.contract.commandEffect!, refusedBeforeWrite, }, }, } as InstalledContractContribution["http"][number], ]); } function reasonFor(refusedBeforeWrite: unknown, responseEnvelope?: unknown) { return captureContributionError(() => composeContractContributions([ withRefusals(refusedBeforeWrite, responseEnvelope), ]), ).reason; } it("installs a frozen copy of the declared codes", () => { const declared = ["TEST_ENTITY_INVALID", "TEST_ENTITY_ALREADY_EXISTS"]; const composed = composeContractContributions([withRefusals(declared)]); declared.push("ADDED_AFTER_BOOT"); const installed = composed.httpByOperationId.get("TEST_CREATE_ENTITY")?.contract .commandEffect; expect(installed?.refusedBeforeWrite).toEqual([ "TEST_ENTITY_INVALID", "TEST_ENTITY_ALREADY_EXISTS", ]); expect(Object.isFrozen(installed?.refusedBeforeWrite)).toBe(true); // The classifiers are still the contribution's own. expect(installed?.classifyProblem).toBe(createRow.contract.commandEffect!.classifyProblem); expect(installed?.successEffect).toBe("APPLIED_CONFIRMED"); }); it.each([ "IDEMPOTENT_IN_FLIGHT", "IDEMPOTENT_REQUEST_MISMATCH", "IDEMPOTENCY_UNAVAILABLE", "IDEMPOTENCY_COMPLETION_UNKNOWN", "IDEMPOTENCY_KEY_INVALID", ])("refuses to declare the idempotency answer %s", (code) => { expect(reasonFor(["TEST_ENTITY_INVALID", code])).toBe( `test-feature/TEST_CREATE_ENTITY: refusedBeforeWrite cannot declare ${code}; the backend's idempotency answers are decided by its own table`, ); }); // 1105/03-01. Contract 6.1 reads these platform codes as possibly raised // after the write. Declared, a 400 or 409 that came after a write would read // as not applied and the next save would be a new request. it.each(["BAD_PARAMETER", "MAPPING_FAILED", "DB_UNIQUE_VIOLATION", "LOCK_ACQUISITION_TIMEOUT"])( "refuses to declare the platform code %s, which 6.1 reads as possibly after the write", (code) => { expect(reasonFor(["TEST_ENTITY_INVALID", code])).toBe( `test-feature/TEST_CREATE_ENTITY: refusedBeforeWrite cannot declare ${code}; contract 6.1 reads this platform code as possibly raised after the write`, ); }, ); it("refuses a list on an operation that does not read the Envelope", () => { expect(reasonFor(["TEST_ENTITY_INVALID"], "NONE")).toBe( "test-feature/TEST_CREATE_ENTITY: refusedBeforeWrite needs responseEnvelope ENVELOPE_V1; without it classifyProblem decides", ); }); it.each([ [ "a lowercase code", ["test_entity_invalid"], "test-feature/TEST_CREATE_ENTITY: refusedBeforeWrite code test_entity_invalid", ], [ "a repeated code", ["TEST_ENTITY_INVALID", "TEST_ENTITY_INVALID"], "test-feature/TEST_CREATE_ENTITY: refusedBeforeWrite repeats TEST_ENTITY_INVALID", ], // Refused while the row is copied, before its operation id is read. [ "a string instead of a list", "TEST_ENTITY_INVALID", "test-feature: refusedBeforeWrite must be a list of backend codes", ], ])("refuses %s", (_label, declared, reason) => { expect(reasonFor(declared)).toBe(reason); }); }); // 1103/16-01. A contribution is one backend's package, so its operations read // one wire frame. An operation added by hand without the `responseEnvelope` // line used to pass every gate and the MSW scenarios, and failed only on the // real backend. describe("one wire frame per contribution (1103/16-01)", () => { const [listRow, getRow, createRow] = TEST_CONTRACT_CONTRIBUTION.http as readonly [ InstalledContractContribution["http"][number], InstalledContractContribution["http"][number], InstalledContractContribution["http"][number], ]; function framed( row: InstalledContractContribution["http"][number], responseEnvelope: "NONE" | "ENVELOPE_V1" | undefined, ): InstalledContractContribution["http"][number] { const { responseEnvelope: _dropped, ...contract } = row.contract; return { ...row, contract: responseEnvelope === undefined ? contract : { ...contract, responseEnvelope }, } as InstalledContractContribution["http"][number]; } it("refuses an operation that forgot the Envelope its siblings read", () => { const error = captureContributionError(() => composeContractContributions([ contribution("mixed-frames", [ framed(listRow, "ENVELOPE_V1"), framed(getRow, undefined), framed(createRow, "ENVELOPE_V1"), ]), ]), ); expect(error.reason).toBe( "test-feature/TEST_GET_ENTITY: responseEnvelope NONE, but TEST_LIST_ENTITIES in the same contribution reads ENVELOPE_V1; a contribution is one backend's package, so declare the same responseEnvelope on every operation or split the contribution per backend", ); }); it("reads a missing value and NONE as the same frame", () => { const composed = composeContractContributions([ contribution("bare-frames", [ framed(listRow, "NONE"), framed(getRow, undefined), framed(createRow, undefined), ]), ]); expect(composed.httpByOperationId.size).toBe(3); }); it("lets one feature read two backends through two contributions", () => { const composed = composeContractContributions([ contribution("envelope-backend", [framed(listRow, "ENVELOPE_V1")]), contribution("bare-backend", [framed(getRow, "NONE"), framed(createRow, undefined)]), ]); expect(composed.contributions.map(({ http }) => http.length)).toEqual([1, 2]); }); /** * 1103/16-01 (rest). Assembly cannot tell a forgotten line from a bare * backend when every operation of a contribution forgot it: a read-only * contribution, or a write without `refusedBeforeWrite`. The line is * required by the descriptor type, so `check:types` fails on such a * descriptor (the directive below fails it when the type stops requiring * the line). A descriptor typed outside TypeScript still composes as NONE. */ it("requires the line on every descriptor at compile time", () => { const { responseEnvelope: _dropped, ...withoutLine } = listRow.contract; // @ts-expect-error 1103/16-01: responseEnvelope is required on a descriptor. const descriptor: InstalledContractContribution["http"][number] = { ...listRow, contract: withoutLine }; const composed = composeContractContributions([contribution("read-only", [descriptor])]); expect( composed.httpByOperationId.get("TEST_LIST_ENTITIES")?.contract.responseEnvelope ?? "NONE", ).toBe("NONE"); }); }); // The sample feature's own cases (its fixture composes, a second one does not) // live in tests/features so they leave with the sample. describe("template fixture provenance (07-04, §4.8)", () => { it("rejects a fixture copied into a product feature, which would leave the contract set silently", () => { const copied = Object.freeze({ ...contribution("order-http-v1", TEST_CONTRACT_CONTRIBUTION.http), featureId: "order", source: Object.freeze({ kind: "TEMPLATE_FIXTURE" as const, fixtureId: "REFERENCE_FEATURE_V1" as const, revision: 1 as const, }), }); const error = captureContributionError(() => composeContractContributions([copied]), ); expect(error.reason).toMatch( /^order: TEMPLATE_FIXTURE REFERENCE_FEATURE_V1 belongs to .+ only; pin an EXTERNAL_PACKAGE$/u, ); }); }); // 1101/07-03. Skipping runtime validation stays possible, but only a skip // made through `unvalidatedPayload` is named, so the composed result lists it. describe("validation skipped by name (1101/07-03)", () => { const [listRow] = TEST_CONTRACT_CONTRIBUTION.http as readonly [ InstalledContractContribution["http"][number], ]; const skipped = unvalidatedPayload("TestEntityListPayload", "typed by the package"); function withOutput(validator: RuntimeValidator) { return contribution("skip-test", [ { ...listRow, contract: { ...listRow.contract, outputValidator: validator } }, ]); } it("lists nothing when every validator checks its input", () => { expect( listUnvalidatedPayloads(composeContractContributions([TEST_CONTRACT_CONTRIBUTION])), ).toEqual([]); }); it("lists an operation whose output skips validation, with its reason", () => { expect( listUnvalidatedPayloads(composeContractContributions([withOutput(skipped)])), ).toEqual([ { featureId: "test-feature", contractId: "TEST_LIST_ENTITIES", validator: "output", schemaId: "TestEntityListPayload", reason: "typed by the package", }, ]); }); it("lists an event whose payload skips validation", () => { const composed = composeContractContributions([ Object.freeze({ ...contribution("skip-event", []), events: Object.freeze([ { ...TEST_EVENT_CONTRACT, payloadValidator: unvalidatedPayload("TestEntity", "trusted feed") }, ]), }), ]); expect(listUnvalidatedPayloads(composed)).toEqual([ expect.objectContaining({ contractId: "test.entity.changed", validator: "payload", reason: "trusted feed", }), ]); }); it("refuses to name a skip without a reason", () => { expect(() => unvalidatedPayload("TestEntity", " ")).toThrow( "TestEntity: an unvalidated payload needs a reason", ); }); // Composition (boot path) does not read the marker, so a hand-built one is // not refused there; the list still shows it instead of passing it as checked. it("lists a hand-built marker that is not NONE or has no reason", () => { const handBuilt = { ...skipped, validation: "PARTIAL", unvalidatedReason: undefined }; expect( listUnvalidatedPayloads( composeContractContributions([withOutput(handBuilt as unknown as RuntimeValidator)]), ), ).toEqual([expect.objectContaining({ validator: "output", reason: "" })]); }); }); describe("validator invocation (07-06)", () => { const returning = (result: unknown): RuntimeValidator => ({ schemaId: "Malformed", safeParse: () => result as never, }); it.each([ ["non-array issues", { success: false, issues: 5 }], ["object issues", { success: false, issues: {} }], ["non-boolean success", { success: "no", data: "unchecked" }], ["throwing issues getter", { success: false, get issues(): never { throw new Error("hostile"); }, }], ])("reports THROWN for a result with %s", (_label, result) => { expect(invokeValidator(returning(result), {})).toEqual({ outcome: "THROWN" }); }); it("keeps well-formed results", () => { expect(invokeValidator(returning({ success: true, data: 1 }), {})).toEqual({ outcome: "VALID", value: 1, }); expect( invokeValidator(returning({ success: false, issues: [{ path: [], code: "X" }] }), {}), ).toEqual({ outcome: "INVALID", issues: [{ path: [], code: "X" }] }); }); });