import { describe, expect, it } from "vitest"; import { ContractContributionError, composeContractContributions, invokeValidator, type InstalledContractContribution, type RuntimeValidator, } from "../../src/contracts/external-contract-runtime.ts"; import { TEST_CONTRACT_CONTRIBUTION } 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"); }); 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"); }); }); // 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, ); }); }); 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" }] }); }); });