@avi770/testteam 2.0.0 → 3.2.0

package/dist/core/api-contract/api-contract-validator.js

@@ -0,0 +1,796 @@
+/**
+ * API Contract Validator (#11 — "The Border Guard") — implementation.
+ *
+ * This is a COMPOSITE RESULTS-PROCESSOR over the engine "api" squad (#39/#41/#42).
+ * It does NOT re-implement what those engines do at runtime (live HTTP fetch,
+ * pagination edge-case probing, GraphQL depth/introspection). Those remain the
+ * engine agents' jobs; this layer INGESTS their Finding[] output verbatim (see
+ * ValidateApiContractOptions.engineFindings → ApiContractReport.engineFindings) and
+ * adds the static/composite REST-contract capabilities that belong at this tier:
+ *
+ *   - Spec-hash diff gating (skip unchanged endpoints, near-zero steady cost)
+ *   - Breaking-change detection (RECURSIVE spec diff, block/warn classification)
+ *   - Consumer-driven contracts (Pact — structural verification of provider interactions)
+ *   - Runtime contract monitoring (sampled prod traffic schema + latency; unknown endpoints flagged)
+ *   - Error-response contract validation
+ *   - Mock generation from spec (msw handler strings)
+ *   - Migration guide authoring (one entry per breaking change)
+ *
+ * Engine agent roles (NOT re-implemented here — surfaced via engineFindings):
+ *   #39 ApiContractTester   — live HTTP schema conformance
+ *   #41 ApiPaginationTester — pagination edge-case probing
+ *   #42 GraphqlTester       — GraphQL introspection / depth / auth probing
+ *
+ * The composition is real (not just a comment): COMPOSED_ENGINE_AGENTS (./types) is
+ * asserted against the live AGENT_REGISTRY 'api' squad by the integration test, and the
+ * engine Finding[] are ingested into the report.
+ *
+ * Operating rules (spec §"Operating & safety rules"):
+ * - Read-only / non-destructive on the API. Never mutates endpoints.
+ * - Gates rather than fixes.
+ * - Diagnostic-first: distinguish spec bug from impl bug before blocking.
+ * - First-do-no-harm.
+ *
+ * Spec: blueprint/agents/11-api-contract-validator.md.
+ */
+import { createHash } from 'node:crypto';
+// ---------------------------------------------------------------------------
+// Spec-hash diff gating (#1 of the 10 improvements — "near-zero steady cost")
+// ---------------------------------------------------------------------------
+/**
+ * Produce a deterministic JSON string with sorted object keys at all nesting levels.
+ * This is required for a stable hash: JSON.stringify with a replacer-array only filters
+ * top-level keys, not nested ones, so nested objects would serialize as {} — making all
+ * operations produce the same hash regardless of their schema content.
+ */
+function stableStringify(value) {
+    if (value === null || typeof value !== 'object') {
+        return JSON.stringify(value);
+    }
+    if (Array.isArray(value)) {
+        return '[' + value.map(stableStringify).join(',') + ']';
+    }
+    const record = value;
+    const sortedKeys = Object.keys(record).sort();
+    return '{' + sortedKeys.map((k) => JSON.stringify(k) + ':' + stableStringify(record[k])).join(',') + '}';
+}
+/**
+ * Compute a deterministic SHA-256 fingerprint of one endpoint's spec fragment.
+ * Only the operation JSON is hashed — stable and independent of spec metadata.
+ * Uses stableStringify to guarantee key-order independence (JSON.stringify key order
+ * is insertion-order in V8, which is not guaranteed canonical across environments).
+ */
+export function hashEndpointSpec(path, method, operation) {
+    const canonical = stableStringify({ method: method.toUpperCase(), operation, path });
+    const specHash = createHash('sha256').update(canonical).digest('hex').slice(0, 16);
+    return { path, method: method.toUpperCase(), specHash };
+}
+/**
+ * Given the current spec and a registry of last-validated hashes, return the set of endpoints
+ * that MUST be re-validated (their hash changed or they are new) and the set that can be skipped.
+ * Unchanged endpoints (same spec hash) skip schema re-validation — this gates spec-diff cost,
+ * NOT a proof of implementation conformance (runtime-sample monitoring still applies).
+ */
+export function partitionByHash(spec, registry) {
+    const toValidate = [];
+    const skipped = [];
+    const paths = spec.paths ?? {};
+    for (const [path, pathItem] of Object.entries(paths)) {
+        if (!pathItem)
+            continue;
+        for (const [rawMethod, operation] of Object.entries(pathItem)) {
+            if (rawMethod.startsWith('x-') || rawMethod === 'parameters' || !operation)
+                continue;
+            const method = rawMethod.toUpperCase();
+            if (!['GET', 'POST', 'PUT', 'DELETE', 'PATCH', 'HEAD', 'OPTIONS'].includes(method))
+                continue;
+            const current = hashEndpointSpec(path, method, operation);
+            const registryKey = `${method} ${path}`;
+            const previousHash = registry[registryKey];
+            if (previousHash === current.specHash) {
+                skipped.push(registryKey);
+            }
+            else {
+                toValidate.push(current);
+            }
+        }
+    }
+    return { toValidate, skipped };
+}
+// ---------------------------------------------------------------------------
+// Schema validation (reuses the shape proven by engine agent #39)
+// ---------------------------------------------------------------------------
+/**
+ * Validate a response body against a JSON schema fragment (OpenAPI 3 subset).
+ * Pure and deterministic — no I/O. Engine agent #39 validates live HTTP; this layer validates
+ * engine-provided body snapshots and sampled traffic records.
+ *
+ * Never rounds up: every violation is reported individually with field-path precision.
+ */
+export function validateResponseSchema(body, schema, endpointLabel, statusCode) {
+    const violations = [];
+    collectSchemaViolations(body, schema, '$', violations);
+    return {
+        endpoint: endpointLabel,
+        statusCode,
+        violations,
+        conformant: violations.length === 0,
+    };
+}
+function collectSchemaViolations(value, schema, path, out) {
+    // Infer the type when omitted: a schema with `properties` is an object and one with
+    // `items` is an array (OpenAPI allows the implicit form). Without this, a typeless
+    // schema validated NOTHING and silently passed (fail-open, NEW-3).
+    const effectiveType = schema.type ??
+        (schema.properties !== undefined ? 'object' : schema.items !== undefined ? 'array' : undefined);
+    if (effectiveType === 'object') {
+        if (typeof value !== 'object' || value === null || Array.isArray(value)) {
+            out.push({ fieldPath: path, expected: 'object', actual: describeType(value) });
+            return;
+        }
+        const record = value;
+        // Required-field presence check
+        for (const field of schema.required ?? []) {
+            if (!(field in record)) {
+                out.push({
+                    fieldPath: `${path}.${field}`,
+                    expected: `required field present`,
+                    actual: 'missing',
+                });
+            }
+        }
+        // Recursive property type checks
+        for (const [field, fieldSchema] of Object.entries(schema.properties ?? {})) {
+            if (field in record) {
+                collectSchemaViolations(record[field], fieldSchema, `${path}.${field}`, out);
+            }
+        }
+        // Enum check at object level (unusual but spec-legal)
+        if (schema.enum !== undefined && !schema.enum.includes(value)) {
+            out.push({
+                fieldPath: path,
+                expected: `one of [${schema.enum.map((v) => JSON.stringify(v)).join(', ')}]`,
+                actual: JSON.stringify(value),
+            });
+        }
+    }
+    else if (effectiveType === 'array') {
+        if (!Array.isArray(value)) {
+            out.push({ fieldPath: path, expected: 'array', actual: describeType(value) });
+            return;
+        }
+        if (schema.items) {
+            for (let i = 0; i < value.length; i++) {
+                collectSchemaViolations(value[i], schema.items, `${path}[${i}]`, out);
+            }
+        }
+    }
+    else if (effectiveType !== undefined) {
+        const jsType = jsTypeForSchemaType(effectiveType);
+        const actual = describeType(value);
+        // Must-fix #6: null is NOT a valid value when the schema declares a specific type.
+        // Remove the `&& value !== null` guard — null bypasses the type check otherwise.
+        if (actual !== jsType) {
+            out.push({ fieldPath: path, expected: jsType, actual });
+        }
+        // Enum check on scalar
+        if (schema.enum !== undefined && !schema.enum.includes(value)) {
+            out.push({
+                fieldPath: path,
+                expected: `one of [${schema.enum.map((v) => JSON.stringify(v)).join(', ')}]`,
+                actual: JSON.stringify(value),
+            });
+        }
+    }
+}
+function jsTypeForSchemaType(schemaType) {
+    if (schemaType === 'integer')
+        return 'number';
+    return schemaType; // string, boolean, number, object, array
+}
+function describeType(v) {
+    if (v === null)
+        return 'null';
+    if (Array.isArray(v))
+        return 'array';
+    return typeof v;
+}
+// ---------------------------------------------------------------------------
+// Breaking-change detection (spec diff, improvement #3/#7 of the 10)
+// ---------------------------------------------------------------------------
+/**
+ * Diff two OpenAPI specs and classify each change as breaking or additive.
+ * Breaking changes on stable APIs carry decision === 'block'; unstable/experimental carry 'warn'.
+ *
+ * Show-the-math: every change is individually listed with its kind, path, and decision.
+ * Never gameable: block/warn is derived deterministically from the kind + stability pair.
+ */
+export function detectBreakingChanges(previousSpec, currentSpec) {
+    const changes = [];
+    const additivePaths = [];
+    const prevPaths = previousSpec.paths ?? {};
+    const currPaths = currentSpec.paths ?? {};
+    // Detect removed endpoints
+    for (const [path, prevItem] of Object.entries(prevPaths)) {
+        if (!currPaths[path]) {
+            const stability = inferStability(prevItem?.['get']);
+            changes.push(makeBreakingChange('endpoint-removed', path, '*', `Endpoint ${path} was removed`, stability));
+            continue;
+        }
+        const currItem = currPaths[path];
+        // Diff per method
+        for (const [rawMethod, prevOp] of Object.entries(prevItem ?? {})) {
+            if (rawMethod.startsWith('x-') || rawMethod === 'parameters' || !prevOp)
+                continue;
+            const method = rawMethod.toUpperCase();
+            const currOp = currItem[rawMethod];
+            const stability = inferStability(prevOp);
+            if (!currOp) {
+                changes.push(makeBreakingChange('endpoint-removed', path, method, `${method} ${path} was removed`, stability));
+                continue;
+            }
+            // Diff response schemas
+            const prevResponses = prevOp.responses ?? {};
+            const currResponses = currOp.responses ?? {};
+            // Status code removal
+            for (const statusCode of Object.keys(prevResponses)) {
+                if (!currResponses[statusCode]) {
+                    changes.push(makeBreakingChange('status-code-removed', path, method, `Status ${statusCode} removed from ${method} ${path}`, stability));
+                }
+            }
+            // Schema field diffs on the primary success response
+            const prevSchema = extractPrimarySchema(prevResponses);
+            const currSchema = extractPrimarySchema(currResponses);
+            if (prevSchema && currSchema) {
+                diffSchemas(path, method, prevSchema, currSchema, stability, changes, additivePaths);
+            }
+            // Must-fix #4: Diff requestBody required fields and parameters.
+            // Adding a new required request field breaks old callers that don't send it.
+            diffRequestBody(path, method, prevOp.requestBody, currOp.requestBody, stability, changes);
+            diffParameters(path, method, prevOp.parameters ?? [], currOp.parameters ?? [], stability, changes);
+        }
+    }
+    // Detect added endpoints (additive, non-breaking)
+    for (const path of Object.keys(currPaths)) {
+        if (!prevPaths[path]) {
+            additivePaths.push(path);
+        }
+    }
+    const shouldBlockRelease = changes.some((c) => c.decision === 'block');
+    return { changes, additivePaths, shouldBlockRelease };
+}
+function inferStability(op) {
+    return op?.['x-stability'] ?? 'stable';
+}
+function decisionForStability(stability) {
+    return stability === 'stable' ? 'block' : 'warn';
+}
+function makeBreakingChange(kind, path, method, description, stability) {
+    return { kind, path, method, description, stability, decision: decisionForStability(stability) };
+}
+function extractPrimarySchema(responses) {
+    // Scan ALL 2xx success codes (sorted for determinism), not just 200/201/202, so a
+    // 203/206/etc. success body is not invisible to breaking-change + mock generation (NEW-6).
+    const successCodes = Object.keys(responses)
+        .filter((c) => /^2\d\d$/.test(c))
+        .sort();
+    for (const code of successCodes) {
+        const schema = responses[code]?.content?.['application/json']?.schema;
+        if (schema)
+            return schema;
+    }
+    return null;
+}
+/** Max nesting depth for the recursive schema diff (defensive against circular schemas). */
+const MAX_SCHEMA_DIFF_DEPTH = 64;
+function diffSchemas(path, method, prev, curr, stability, breaking, additive, fieldPrefix = '', depth = 0) {
+    // Defensive: real OpenAPI schemas are shallow; bail on pathological depth so a
+    // $ref-resolved circular schema cannot overflow the stack.
+    if (depth > MAX_SCHEMA_DIFF_DEPTH)
+        return;
+    const at = fieldPrefix === '' ? 'root' : `"${fieldPrefix}"`;
+    if (prev.type !== curr.type && prev.type !== undefined && curr.type !== undefined) {
+        breaking.push(makeBreakingChange('field-type-changed', path, method, `${method} ${path}: ${at} type changed from ${prev.type} to ${curr.type}`, stability));
+    }
+    const prevProps = prev.properties ?? {};
+    const currProps = curr.properties ?? {};
+    const prevRequired = new Set(prev.required ?? []);
+    for (const field of Object.keys(prevProps)) {
+        const fieldLabel = fieldPrefix === '' ? field : `${fieldPrefix}.${field}`;
+        if (!currProps[field]) {
+            if (prevRequired.has(field)) {
+                breaking.push(makeBreakingChange('field-removed', path, method, `${method} ${path}: required field "${fieldLabel}" removed from response`, stability));
+            }
+            // Non-required fields removed: additive, not breaking.
+        }
+        else {
+            const pf = prevProps[field];
+            const cf = currProps[field];
+            if (pf && cf) {
+                if (pf.type && cf.type && pf.type !== cf.type) {
+                    breaking.push(makeBreakingChange('field-type-changed', path, method, `${method} ${path}: field "${fieldLabel}" type changed from ${pf.type} to ${cf.type}`, stability));
+                }
+                if (pf.enum && cf.enum) {
+                    for (const val of pf.enum) {
+                        if (!cf.enum.includes(val)) {
+                            breaking.push(makeBreakingChange('enum-value-removed', path, method, `${method} ${path}: enum value ${JSON.stringify(val)} removed from field "${fieldLabel}"`, stability));
+                        }
+                    }
+                }
+                // RECURSE into nested object properties (NEW-1): a nested required-field removal
+                // or nested type change is breaking and the top-level scan alone would miss it.
+                if ((pf.properties !== undefined || pf.type === 'object') &&
+                    (cf.properties !== undefined || cf.type === 'object')) {
+                    diffSchemas(path, method, pf, cf, stability, breaking, additive, fieldLabel, depth + 1);
+                }
+                // RECURSE into array item schemas.
+                if (pf.items !== undefined && cf.items !== undefined) {
+                    diffSchemas(path, method, pf.items, cf.items, stability, breaking, additive, `${fieldLabel}[]`, depth + 1);
+                }
+            }
+        }
+    }
+    for (const field of Object.keys(currProps)) {
+        if (!prevProps[field]) {
+            const fieldLabel = fieldPrefix === '' ? field : `${fieldPrefix}.${field}`;
+            additive.push(`${method} ${path}#${fieldLabel}`);
+        }
+    }
+}
+/**
+ * Must-fix #4: Diff requestBody required fields.
+ * A new required field in the current requestBody schema breaks old callers that
+ * do not send it. This was previously dead — it only looked at RESPONSE schemas.
+ */
+function diffRequestBody(path, method, prevBody, currBody, stability, breaking) {
+    // Extract the JSON schema from the requestBody content
+    const prevSchema = prevBody?.content?.['application/json']?.schema;
+    const currSchema = currBody?.content?.['application/json']?.schema;
+    if (!currSchema)
+        return; // Nothing to enforce on the current side
+    const prevRequired = new Set(prevSchema?.required ?? []);
+    const currRequired = new Set(currSchema?.required ?? []);
+    for (const field of currRequired) {
+        if (!prevRequired.has(field)) {
+            // New required field in the request body — old callers that omit it will fail
+            breaking.push(makeBreakingChange('required-added', path, method, `${method} ${path}: new required request body field "${field}" (old callers will fail)`, stability));
+        }
+    }
+}
+/**
+ * Must-fix #4: Diff path/query parameters for newly required parameters.
+ * Adding a required parameter where none existed (or it was optional) breaks old callers.
+ */
+function diffParameters(path, method, prevParams, currParams, stability, breaking) {
+    const prevByName = new Map(prevParams.map((p) => [p.name, p]));
+    for (const currParam of currParams) {
+        if (!currParam.required)
+            continue; // optional params added are non-breaking
+        const prevParam = prevByName.get(currParam.name);
+        if (!prevParam) {
+            // Entirely new required parameter
+            breaking.push(makeBreakingChange('required-added', path, method, `${method} ${path}: new required parameter "${currParam.name}" in ${currParam.in} (old callers will fail)`, stability));
+        }
+        else if (!prevParam.required) {
+            // Was optional, now required
+            breaking.push(makeBreakingChange('required-added', path, method, `${method} ${path}: parameter "${currParam.name}" in ${currParam.in} changed from optional to required (old callers will fail)`, stability));
+        }
+    }
+}
+// ---------------------------------------------------------------------------
+// Consumer-driven contracts (Pact — improvement #6)
+// ---------------------------------------------------------------------------
+/**
+ * Verify a provider against one consumer Pact contract by checking each interaction against
+ * the fixture responses returned by the provider fixture function.
+ *
+ * `providerFixture` is the adapter that the caller provides — it replays an interaction against
+ * the actual provider (staging) or a recorded fixture. Pure composition: this layer classifies;
+ * the caller owns I/O.
+ */
+export async function verifyPactContract(contract, providerFixture) {
+    const results = [];
+    for (const interaction of contract.interactions) {
+        let result;
+        try {
+            const actual = await providerFixture(interaction);
+            const statusMatches = actual.statusCode === interaction.response.status;
+            // If the interaction specifies a response body, validate it structurally
+            let bodyMatches = true;
+            let failureReason;
+            if (!statusMatches) {
+                bodyMatches = false;
+                failureReason = `expected status ${interaction.response.status}, got ${actual.statusCode}`;
+            }
+            else if (interaction.response.body !== undefined) {
+                const match = deepStructuralMatch(actual.body, interaction.response.body);
+                bodyMatches = match.matched;
+                failureReason = match.matched ? undefined : match.reason;
+            }
+            result = {
+                consumer: contract.consumer.name,
+                provider: contract.provider.name,
+                interaction: interaction.description,
+                passed: statusMatches && bodyMatches,
+                ...(failureReason !== undefined ? { failureReason } : {}),
+            };
+        }
+        catch (err) {
+            result = {
+                consumer: contract.consumer.name,
+                provider: contract.provider.name,
+                interaction: interaction.description,
+                passed: false,
+                failureReason: err instanceof Error ? err.message : String(err),
+            };
+        }
+        results.push(result);
+    }
+    return results;
+}
+/**
+ * Build a blast-radius map: which consumers have failing interactions, and how many total.
+ * Show-the-math: lists every consumer and every failing interaction by name.
+ */
+export function buildBlastRadiusMap(verifications) {
+    const byConsumer = new Map();
+    for (const v of verifications) {
+        if (!v.passed) {
+            const existing = byConsumer.get(v.consumer) ?? [];
+            existing.push(v.interaction);
+            byConsumer.set(v.consumer, existing);
+        }
+    }
+    const brokenConsumers = [...byConsumer.entries()].map(([consumer, failingInteractions]) => ({
+        consumer,
+        failingInteractions,
+    }));
+    return { brokenConsumers, totalAffectedConsumers: brokenConsumers.length };
+}
+/**
+ * Structural deep equality check: actual must contain at least all fields present in expected.
+ *
+ * Null semantics (must-fix #5):
+ *   expected === null  → actual MUST be null (fail-closed; provider omitting a null field fails)
+ *   expected === undefined → skip (field not specified by consumer; any actual value is fine)
+ */
+function deepStructuralMatch(actual, expected) {
+    if (expected === undefined) {
+        // Consumer didn't specify this field — any actual value accepted
+        return { matched: true };
+    }
+    if (expected === null) {
+        // Consumer explicitly expects null — provider must also return null
+        if (actual !== null) {
+            return { matched: false, reason: `expected null, got ${describeType(actual)}` };
+        }
+        return { matched: true };
+    }
+    if (typeof expected !== typeof actual) {
+        return { matched: false, reason: `type mismatch: expected ${typeof expected}, got ${typeof actual}` };
+    }
+    if (typeof expected === 'object' && !Array.isArray(expected)) {
+        const expObj = expected;
+        const actObj = actual;
+        for (const key of Object.keys(expObj)) {
+            if (!(key in actObj)) {
+                return { matched: false, reason: `missing field "${key}"` };
+            }
+            const nested = deepStructuralMatch(actObj[key], expObj[key]);
+            if (!nested.matched) {
+                return { matched: false, reason: `field "${key}": ${nested.reason}` };
+            }
+        }
+        return { matched: true };
+    }
+    if (Array.isArray(expected)) {
+        if (!Array.isArray(actual)) {
+            return { matched: false, reason: `expected array, got ${typeof actual}` };
+        }
+        for (let i = 0; i < expected.length; i++) {
+            const nested = deepStructuralMatch(actual[i], expected[i]);
+            if (!nested.matched) {
+                return { matched: false, reason: `index ${i}: ${nested.reason}` };
+            }
+        }
+        return { matched: true };
+    }
+    if (expected !== actual) {
+        return { matched: false, reason: `expected ${JSON.stringify(expected)}, got ${JSON.stringify(actual)}` };
+    }
+    return { matched: true };
+}
+// ---------------------------------------------------------------------------
+// Runtime contract monitoring (improvement #8 — sampled prod traffic)
+// ---------------------------------------------------------------------------
+/**
+ * Validate a set of sampled production traffic records against the spec.
+ * Frugal by design: callers control the sample size; we only classify what we receive.
+ * Latency / SLA contract: also checks response-time budget per endpoint.
+ */
+export function validateRuntimeSample(records, spec) {
+    const violations = [];
+    for (const record of records) {
+        const [method = '', ...pathParts] = record.endpoint.split(' ');
+        const path = pathParts.join(' ');
+        const pathItem = spec.paths?.[path];
+        const operation = pathItem?.[method.toLowerCase()];
+        // FAIL-CLOSED (NEW-2): an endpoint absent from the spec is an UNKNOWN/undocumented
+        // surface — flag it rather than silently passing it as conformant.
+        if (operation === undefined) {
+            violations.push({
+                record,
+                violations: [{
+                        fieldPath: '$',
+                        expected: 'a documented endpoint in the spec',
+                        actual: `unknown endpoint "${record.endpoint}"`,
+                    }],
+                latencyViolated: false,
+            });
+            continue;
+        }
+        const schemaForStatus = operation.responses?.[String(record.statusCode)]?.content?.['application/json']?.schema;
+        const schemaViolations = [];
+        if (schemaForStatus) {
+            collectSchemaViolations(record.responseBodyJson, schemaForStatus, '$', schemaViolations);
+        }
+        const budgetMs = operation['x-latency-budget-ms'];
+        const latencyViolated = budgetMs !== undefined && record.latencyMs > budgetMs;
+        if (schemaViolations.length > 0 || latencyViolated) {
+            violations.push({
+                record,
+                violations: schemaViolations,
+                latencyViolated,
+                ...(budgetMs !== undefined ? { budgetMs } : {}),
+            });
+        }
+    }
+    return {
+        sampledCount: records.length,
+        violationCount: violations.length,
+        violations,
+    };
+}
+// ---------------------------------------------------------------------------
+// Error-response contract validation (core capability)
+// ---------------------------------------------------------------------------
+/**
+ * Validate that an error response body contains all fields declared in the error contract spec.
+ * Error-contract conformance is a first-class contract, not an afterthought.
+ */
+export function validateErrorContract(endpoint, statusCode, responseBody, errorSpec) {
+    const missingFields = [];
+    if (typeof responseBody === 'object' && responseBody !== null && !Array.isArray(responseBody)) {
+        const record = responseBody;
+        for (const field of errorSpec.requiredFields) {
+            if (!(field in record)) {
+                missingFields.push(field);
+            }
+        }
+    }
+    else {
+        // Body is not an object at all — all required fields are "missing"
+        missingFields.push(...errorSpec.requiredFields);
+    }
+    return {
+        endpoint,
+        statusCode,
+        conformant: missingFields.length === 0,
+        missingFields,
+    };
+}
+// ---------------------------------------------------------------------------
+// Mock generation (improvement #10 — self-healing mocks via msw)
+// ---------------------------------------------------------------------------
+/**
+ * Generate msw (Mock Service Worker) handler code from an OpenAPI spec.
+ * The generated handlers are derived from the spec's example / schema defaults so they are
+ * always in sync — "self-healing mocks". Callers write the returned code to their test fixtures.
+ *
+ * Pure and deterministic: same spec → same handler code.
+ */
+export function generateMockHandlers(spec) {
+    const handlers = [];
+    const paths = spec.paths ?? {};
+    for (const [path, pathItem] of Object.entries(paths)) {
+        if (!pathItem)
+            continue;
+        for (const [rawMethod, operation] of Object.entries(pathItem)) {
+            if (rawMethod.startsWith('x-') || rawMethod === 'parameters' || !operation)
+                continue;
+            const method = rawMethod.toLowerCase();
+            const op = operation;
+            const schema = extractPrimarySchema(op.responses ?? {});
+            const exampleBody = schema ? schemaToExample(schema) : null;
+            const endpointLabel = `${rawMethod.toUpperCase()} ${path}`;
+            // Convert OpenAPI path params ("{id}") to msw URL pattern (":id")
+            const mswPath = path.replace(/\{(\w+)\}/g, ':$1');
+            const handlerCode = [
+                `http.${method}('${mswPath}', () => {`,
+                `  return HttpResponse.json(${JSON.stringify(exampleBody, null, 2)}, { status: 200 });`,
+                `}),`,
+            ].join('\n');
+            handlers.push({ endpoint: endpointLabel, handlerCode });
+        }
+    }
+    return handlers;
+}
+/** Derive a minimal example object from a JSON schema fragment. */
+function schemaToExample(schema) {
+    switch (schema.type) {
+        case 'object': {
+            const obj = {};
+            for (const [field, fieldSchema] of Object.entries(schema.properties ?? {})) {
+                obj[field] = schemaToExample(fieldSchema);
+            }
+            return obj;
+        }
+        case 'array':
+            return schema.items ? [schemaToExample(schema.items)] : [];
+        case 'string':
+            if (schema.enum && schema.enum.length > 0)
+                return schema.enum[0];
+            if (schema.format === 'date-time')
+                return '2024-01-01T00:00:00.000Z';
+            if (schema.format === 'uuid')
+                return '00000000-0000-0000-0000-000000000000';
+            return 'string';
+        case 'integer':
+        case 'number':
+            return 0;
+        case 'boolean':
+            return false;
+        default:
+            return null;
+    }
+}
+// ---------------------------------------------------------------------------
+// Migration guide authoring (improvement #9)
+// ---------------------------------------------------------------------------
+/**
+ * Auto-draft a migration guide for every breaking change in a diff.
+ * Handed to Documentation Sync (#10) — this layer author's the draft; humans refine it.
+ * Show-the-math: every change gets its own entry with before/after examples.
+ */
+export function draftMigrationGuide(diff, options) {
+    if (diff.changes.length === 0)
+        return null;
+    const now = options?.clock ? new Date(options.clock()).toISOString() : new Date().toISOString();
+    const entries = diff.changes.map((change) => {
+        const { recommendation, exampleBefore, exampleAfter } = migrationAdvice(change);
+        return { change, recommendation, exampleBefore, exampleAfter };
+    });
+    return {
+        title: `API Breaking-Change Migration Guide — ${diff.changes.length} change(s)`,
+        generatedAt: now,
+        entries,
+    };
+}
+function migrationAdvice(change) {
+    switch (change.kind) {
+        case 'field-removed':
+            return {
+                recommendation: `Add the removed field back or introduce a new versioned endpoint. Bump the major version if on a stable API.`,
+                exampleBefore: `// Response included "${change.path}" field`,
+                exampleAfter: `// Field removed — update consumers to not rely on it, or restore it under a new version`,
+            };
+        case 'field-type-changed':
+            return {
+                recommendation: `Restore the original type or introduce a new field with the new type, keeping the old field. Bump the major version if on a stable API.`,
+                exampleBefore: `// ${change.description.split(':')[1]?.trim() ?? change.description}`,
+                exampleAfter: `// Add new typed field alongside the original; deprecate the original`,
+            };
+        case 'enum-value-removed':
+            return {
+                recommendation: `Restore the removed enum value, or verify no consumer depends on it via the blast-radius map.`,
+                exampleBefore: `// Enum included the removed value`,
+                exampleAfter: `// Value removed — consumers relying on it will error`,
+            };
+        case 'endpoint-removed':
+            return {
+                recommendation: `Restore the endpoint or add a forwarding redirect to the replacement. Announce sunset in advance.`,
+                exampleBefore: `// Endpoint ${change.path} existed`,
+                exampleAfter: `// Endpoint removed — consumers will receive 404`,
+            };
+        case 'status-code-removed':
+            return {
+                recommendation: `Restore the removed status code to the spec, or document the new error handling path clearly.`,
+                exampleBefore: `// ${change.method} ${change.path} declared the removed status code`,
+                exampleAfter: `// Status code removed from spec — consumers handling it need updating`,
+            };
+        case 'required-added':
+            return {
+                recommendation: `Remove the new required field or give it a default so old callers are not broken. Version bump required.`,
+                exampleBefore: `// Request did not include the now-required field`,
+                exampleAfter: `// Old callers will fail validation — add a default or make the field optional`,
+            };
+        default: {
+            // exhaustive guard — change satisfies never at compile time after all cases are handled
+            const _exhaustive = change.kind;
+            return {
+                recommendation: `Review the change manually: ${_exhaustive}`,
+                exampleBefore: '',
+                exampleAfter: '',
+            };
+        }
+    }
+}
+/**
+ * Run the full API contract validation pipeline.
+ * Composes: spec-hash gating → schema validation → breaking-change detection →
+ * Pact consumer verification → blast-radius mapping → error contract → runtime sample →
+ * mock generation → migration guide.
+ *
+ * Never mutates the API. Never throws on validation failures — failures are reported as findings
+ * in the returned report. Only infrastructure errors (bad spec JSON, etc.) propagate.
+ */
+export async function validateApiContract(opts) {
+    // 1. Spec-hash diff gating: determine which endpoints need re-validation.
+    const { toValidate, skipped } = partitionByHash(opts.currentSpec, opts.hashRegistry);
+    const toValidateKeys = new Set(toValidate.map((h) => `${h.method} ${h.path}`));
+    // 2. Schema validation: only on endpoints whose hash changed.
+    const schemaResults = [];
+    for (const [endpointKey, snapshot] of Object.entries(opts.endpointSnapshots)) {
+        const [method = '', ...pathParts] = endpointKey.split(' ');
+        const path = pathParts.join(' ');
+        const pathItem = opts.currentSpec.paths?.[path];
+        const operation = pathItem?.[method.toLowerCase()];
+        // FAIL-CLOSED: a snapshot for an endpoint absent from the spec is a typo or an
+        // undocumented endpoint — flag it rather than silently skipping it.
+        if (operation === undefined) {
+            schemaResults.push({
+                endpoint: endpointKey,
+                statusCode: snapshot.statusCode,
+                violations: [{ fieldPath: '$', expected: 'a documented endpoint in the spec', actual: `unknown endpoint "${endpointKey}"` }],
+                conformant: false,
+            });
+            continue;
+        }
+        if (!toValidateKeys.has(endpointKey)) {
+            // spec-hash gate: spec unchanged → skip schema re-validation (not a conformance proof)
+            continue;
+        }
+        const schema = operation.responses?.[String(snapshot.statusCode)]?.content?.['application/json']?.schema;
+        if (schema) {
+            schemaResults.push(validateResponseSchema(snapshot.body, schema, endpointKey, snapshot.statusCode));
+        }
+    }
+    // 3. Breaking-change detection.
+    const breakingChanges = detectBreakingChanges(opts.previousSpec, opts.currentSpec);
+    // 4. Consumer-driven Pact verification + blast radius.
+    const consumerVerifications = [];
+    for (const contract of opts.pactContracts) {
+        const results = await verifyPactContract(contract, opts.providerFixture);
+        consumerVerifications.push(...results);
+    }
+    const blastRadius = buildBlastRadiusMap(consumerVerifications);
+    // 5. Error-contract validation.
+    const errorContractResults = [];
+    for (const [endpointKey, errorResp] of Object.entries(opts.errorResponses)) {
+        const errorSpec = opts.errorContracts.find((s) => s.statusCode === errorResp.statusCode);
+        if (errorSpec) {
+            errorContractResults.push(validateErrorContract(endpointKey, errorResp.statusCode, errorResp.body, errorSpec));
+        }
+    }
+    // 6. Runtime sample validation.
+    const runtimeSample = validateRuntimeSample(opts.runtimeSamples, opts.currentSpec);
+    // 7. Mock generation from current spec.
+    const mocks = generateMockHandlers(opts.currentSpec);
+    // 8. Migration guide (only when breaking changes exist).
+    const migrationGuide = draftMigrationGuide(breakingChanges, { clock: opts.clock });
+    const generatedAt = opts.clock ? new Date(opts.clock()).toISOString() : new Date().toISOString();
+    return {
+        skippedEndpoints: skipped,
+        schemaResults,
+        breakingChanges,
+        consumerVerifications,
+        blastRadius,
+        errorContractResults,
+        runtimeSample,
+        migrationGuide,
+        mocks,
+        engineFindings: opts.engineFindings ?? [],
+        generatedAt,
+    };
+}
+//# sourceMappingURL=api-contract-validator.js.map