import { describe, expect, it } from "vitest"; import scopedOpenApi from "./contract/kwp-scoped-openapi.json" with { type: "json" }; import { buildKwpCapabilitySemanticContract, getKwpScopedOperation, KWP_SCOPED_OPERATIONS, KWP_SCOPED_OPERATION_INVENTORY, listKwpCapabilities, parseKwpOperationResponse, rejectKwpMutationOperation, validateKwpOperationInput, validateKwpOperationResponse, validateKwpScopedOpenApi, type KwpMutationOperationId, type KwpOperationInput, } from "./scoped-contract.js"; type JsonRecord = Record; describe("KWP scoped contract", () => { it("keeps the complete licensed inventory explicit and duplicate-free", () => { expect(KWP_SCOPED_OPERATION_INVENTORY).toEqual({ sourceOperationCount: 554, scopedOperationCount: 113, readOperationCount: 77, mutationOperationCount: 36, excludedOperationCount: 441, }); expect(new Set(KWP_SCOPED_OPERATIONS.map((operation) => operation.id))).toHaveLength(113); expect(new Set(KWP_SCOPED_OPERATIONS.map((operation) => `${operation.method} ${operation.path}`))).toHaveLength(113); expect(KWP_SCOPED_OPERATIONS.filter((operation) => operation.mode === "read")).toHaveLength(77); expect(KWP_SCOPED_OPERATIONS.filter((operation) => operation.mode === "mutation")).toHaveLength(36); }); it("keeps provider documentation markup out of the runtime contract", () => { expect(JSON.stringify(scopedOpenApi)).not.toContain('"description":'); }); it("compiles and fixture-validates every scoped request and response schema", () => { const document = scopedOpenApi as unknown as JsonRecord; for (const operation of KWP_SCOPED_OPERATIONS) { const contract = readOperationContract(document, operation.path, operation.method); const input = buildInputFixture(document, contract); const response = buildResponseFixture(document, contract); expect(() => validateKwpOperationInput(operation.id, input)).not.toThrow(); expect(() => validateKwpOperationResponse(operation.id, response)).not.toThrow(); } }); it("keeps all mutation contracts unavailable to runtime transport", () => { const mutations = KWP_SCOPED_OPERATIONS.filter((operation) => operation.mode === "mutation"); expect(mutations).toHaveLength(36); for (const operation of mutations) { expect(() => rejectKwpMutationOperation(operation.id as KwpMutationOperationId)).toThrowError("invalid_credentials"); } }); it("rejects caller-controlled mandant context", () => { expect(() => validateKwpOperationInput("projektSearch", { query: { mandant: "other-tenant" }, body: { value: "Projekt" }, }) ).toThrowError("invalid_credentials"); }); it("removes forbidden address data from generic adapter responses", () => { const parsed = parseKwpOperationResponse("adresseLoadAdressKomplett", { adrNrGes: "A-1", iban: "DE001234", bank: "Provider Bank", kreditLimit: 12_500, steuerNummer: "TAX-1", geburtstag: "1990-01-01T00:00:00.000Z", hinweis: "internal", bemerkung: "private", benutzerFeld1: "custom", ansprechpartner: [ { ansprechpartnerId: 1, nachname: "Kontakt", benutzerFeld2: "nested", }, ], }); expect(parsed).toEqual({ adrNrGes: "A-1", ansprechpartner: [ { ansprechpartnerId: 1, nachname: "Kontakt", }, ], }); }); it("isolates semantic drift by capability", () => { validateKwpScopedOpenApi(scopedOpenApi); const baseline = Object.fromEntries( listKwpCapabilities().map((capability) => [capability, buildKwpCapabilitySemanticContract(scopedOpenApi, capability).semanticFingerprint]) ); const drifted = structuredClone(scopedOpenApi) as unknown as JsonRecord; const paths = drifted.paths as JsonRecord; const addressPath = paths["/api/Adresse/LoadAdressDetails"] as JsonRecord; const addressGet = addressPath.get as JsonRecord; const parameters = addressGet.parameters as JsonRecord[]; const addressCode = parameters.find((parameter) => parameter.name === "adresskuerzel"); (addressCode!.schema as JsonRecord).maxLength = 190; const observed = Object.fromEntries( listKwpCapabilities().map((capability) => [capability, buildKwpCapabilitySemanticContract(drifted, capability).semanticFingerprint]) ); expect(observed.address).not.toBe(baseline.address); expect(observed.activity).toBe(baseline.activity); expect(observed.archive).toBe(baseline.archive); expect(observed.project).toBe(baseline.project); expect(observed.schedule).toBe(baseline.schedule); }); it("rejects unknown operation ids without exposing a free path", () => { expect(() => getKwpScopedOperation("freePath" as never)).toThrowError("invalid_credentials"); }); }); function readOperationContract(document: JsonRecord, path: string, method: string): JsonRecord { const paths = document.paths as JsonRecord; return (paths[path] as JsonRecord)[method.toLowerCase()] as JsonRecord; } function buildInputFixture(document: JsonRecord, operation: JsonRecord): KwpOperationInput { const input: { query?: JsonRecord; body?: unknown } = {}; const query: JsonRecord = {}; const parameters = Array.isArray(operation.parameters) ? operation.parameters : []; for (const parameterValue of parameters) { const parameter = parameterValue as JsonRecord; if (parameter.in !== "query" || parameter.name === "mandant" || parameter.required !== true) { continue; } query[String(parameter.name)] = buildSchemaFixture(document, parameter.schema); } if (Object.keys(query).length > 0) input.query = query; const requestBody = operation.requestBody as JsonRecord | undefined; const bodySchema = selectContentSchema(requestBody?.content); if (bodySchema) input.body = buildSchemaFixture(document, bodySchema); return input; } function buildResponseFixture(document: JsonRecord, operation: JsonRecord): unknown { const responses = operation.responses as JsonRecord; const success = (responses["200"] ?? responses["201"] ?? responses["202"] ?? responses["204"]) as JsonRecord; const schema = selectContentSchema(success?.content); return schema ? buildSchemaFixture(document, schema) : undefined; } function selectContentSchema(contentValue: unknown): unknown | null { const content = contentValue as JsonRecord | undefined; for (const type of ["application/json", "text/json", "text/plain"]) { const media = content?.[type] as JsonRecord | undefined; if (media?.schema) return media.schema; } return null; } function buildSchemaFixture(document: JsonRecord, schemaValue: unknown): unknown { const schema = schemaValue as JsonRecord; if (typeof schema.$ref === "string") { const name = schema.$ref.replace("#/components/schemas/", ""); const components = document.components as JsonRecord; const schemas = components.schemas as JsonRecord; return buildSchemaFixture(document, schemas[name]); } if (schema.nullable === true) return null; if (schema.example !== undefined) return structuredClone(schema.example); if (schema.default !== undefined) return structuredClone(schema.default); if (Array.isArray(schema.enum) && schema.enum.length > 0) return schema.enum[0]; if (schema.type === "object" || schema.properties) { const properties = (schema.properties ?? {}) as JsonRecord; const required = Array.isArray(schema.required) ? schema.required : []; return Object.fromEntries(required.map((name) => [String(name), buildSchemaFixture(document, properties[String(name)])])); } if (schema.type === "array") { const minimum = typeof schema.minItems === "number" ? schema.minItems : 0; return Array.from({ length: minimum }, () => buildSchemaFixture(document, schema.items)); } if (schema.type === "boolean") return false; if (schema.type === "integer" || schema.type === "number") { return typeof schema.minimum === "number" ? schema.minimum : 0; } if (schema.type === "string") { if (schema.format === "date-time") return "2026-07-24T00:00:00.000Z"; if (schema.format === "uuid") return "00000000-0000-4000-8000-000000000000"; if (schema.format === "uri") return "https://example.invalid/fixture"; return "fixture"; } return {}; }