합치며 고친 것: 두 브랜치가 따로는 맞고 합치면 어긋나는 곳 둘. - 1105/12-04(실행 격리 브랜치)는 `vite.config.ts`가 `scripts/lib/run-isolation.ts`를 가져오게 해, 저장소를 임시 루트에 복사해 빌드하는 두 목록(`scripts/scale/measure-feature-shape-growth.ts`, `tests/unit/product-feature-selection-build.test.ts`)에 그 파일을 더했다. 1105/15-03(이 브랜치)은 두 목록을 `scripts/lib/vite-build-inputs.ts` 하나로 옮겼다. 두 파일의 충돌은 15-03 쪽으로 풀고, 옮긴 목록에 `scripts/lib/run-isolation.ts`를 더한다. 더하지 않으면 `tests/unit/vite-build-inputs.test.ts`가 그 파일 이름을 대며 실패하고, 임시 루트 빌드 두 곳이 "Could not resolve './scripts/lib/run-isolation.ts'"로 실패한다. - `scripts/lib/removal-fixture.ts`의 문서 테스트 목록에 03-01(HTTP 판정 브랜치)과 16-01(이 브랜치)이 각자 한 줄씩 더했다. 두 줄을 모두 둔다. 검증: desktop batch에서 확인. node scripts/run-vitest.ts run tests/unit/vite-build-inputs.test.ts tests/unit/feature-shape-growth.test.ts tests/unit/product-feature-selection-build.test.ts Refs: 1105/12-04, 1105/15-03, 1105/03-01, 1105/16-01
531 lines
19 KiB
TypeScript
531 lines
19 KiB
TypeScript
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<unknown>) {
|
|
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<unknown>)]),
|
|
),
|
|
).toEqual([expect.objectContaining({ validator: "output", reason: "" })]);
|
|
});
|
|
});
|
|
|
|
describe("validator invocation (07-06)", () => {
|
|
const returning = (result: unknown): RuntimeValidator<unknown> => ({
|
|
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" }] });
|
|
});
|
|
});
|