vouchington-tooling 0.20.0 → 0.22.0

package/dist/api-contract-discovery/request-contract-route-analysis.mjs

@@ -0,0 +1,68 @@
+import ts from '../contract-schema/typescript-api.mjs';
+import { isContextMethod } from './response-contract-route-analysis.mjs';
+/**
+ * Detects the request-contract markers in the version-one route convention.
+ * Kept out of `responseMarker` (which only recognizes `apiResponse`/`apiNoContent`) so the two
+ * AST walks never interfere — see `response-contract-route-analysis.mts` for the response side.
+ */
+export function requestMarker(expression) {
+    if (!ts.isIdentifier(expression))
+        return undefined;
+    if (expression.text === 'apiRequest' ||
+        expression.text === 'apiRequestContract' ||
+        expression.text === 'apiNoRequestBody')
+        return expression.text;
+    return undefined;
+}
+/**
+ * Detects `ctx.request.json(...)`: a two-level nested access (`ctx.request` then `.json`) that
+ * `isContextMethod`'s single-level match can't see through directly — mirrors
+ * `isContextResponseBufferCall`'s own two-level pattern on the response side.
+ */
+export function isContextRequestJsonCall(expression) {
+    if (!ts.isPropertyAccessExpression(expression) || expression.name.text !== 'json')
+        return false;
+    return isContextMethod(expression.expression, 'request');
+}
+/** Detects `ctx.request.buffer(...)`: a raw request body whose shape can't be statically extracted. */
+export function isContextRequestBufferCall(expression) {
+    if (!ts.isPropertyAccessExpression(expression) || expression.name.text !== 'buffer')
+        return false;
+    return isContextMethod(expression.expression, 'request');
+}
+/**
+ * Walks up from a `ctx.request.json(...)` call expression to find the enclosing `as T` cast that
+ * gives it a static type, unwrapping the wrapper shapes real call sites use in between:
+ * `(await ctx.request.json(...)) as T` and the `.catch()`-guarded
+ * `(await ctx.request.json(...).catch(() => ({}))) as T`.
+ * Returns `undefined` when no enclosing cast exists (e.g. the read feeds directly into another
+ * call, `parseFoo(await ctx.request.json())`) — the caller treats that as an honest untyped
+ * success, not a failure.
+ */
+export function enclosingRequestBodyCast(call) {
+    let current = call;
+    while (true) {
+        const parent = current.parent;
+        if (!parent)
+            return undefined;
+        if (ts.isParenthesizedExpression(parent) && parent.expression === current) {
+            current = parent;
+            continue;
+        }
+        if (ts.isAwaitExpression(parent) && parent.expression === current) {
+            current = parent;
+            continue;
+        }
+        if (ts.isPropertyAccessExpression(parent) &&
+            parent.name.text === 'catch' &&
+            parent.expression === current &&
+            ts.isCallExpression(parent.parent) &&
+            parent.parent.expression === parent) {
+            current = parent.parent;
+            continue;
+        }
+        if (ts.isAsExpression(parent) && parent.expression === current)
+            return parent;
+        return undefined;
+    }
+}

package/dist/api-contract-discovery/request-contract-types.d.mts

@@ -0,0 +1,12 @@
+import type { ExtractedResponseContract } from '../contract-schema/index.mts';
+/**
+ * A backend route's request-body contract. Mirrors `BackendResponseContract` minus the
+ * status/variant concepts responses have — a request has no status code and (unlike a response)
+ * no `#variant` escape hatch, so every route resolves to at most one `BackendRequestContract`.
+ */
+export type BackendRequestContract = ExtractedResponseContract & {
+    method: string;
+    routeTemplate: string;
+    /** Set when the route's request schema could not be extracted (lenient discovery mode), or the route reads a raw non-JSON buffer body. */
+    unavailableReason?: string;
+};

package/dist/api-contract-discovery/request-contract-types.mjs

@@ -0,0 +1 @@
+export {};

package/dist/api-contract-discovery/response-contract-ctx-analysis.d.mts

@@ -0,0 +1,7 @@
+import ts from '../contract-schema/typescript-api.mts';
+export declare function responseMarker(expression: ts.Expression): 'apiOpenApiRawResponse' | 'apiResponse' | 'apiNoContent' | undefined;
+export declare function isContextMethod(expression: ts.Expression, method: string): boolean;
+/** Detects the framework's explicit no-body signal independently of the response status. */
+export declare function isContextResponseEmptyCall(expression: ts.Expression): boolean;
+/** Detects `ctx.response.buffer(...)`: a raw pass-through body whose shape can't be statically extracted. */
+export declare function isContextResponseBufferCall(expression: ts.Expression): boolean;

package/dist/api-contract-discovery/response-contract-ctx-analysis.mjs

@@ -0,0 +1,28 @@
+import ts from '../contract-schema/typescript-api.mjs';
+export function responseMarker(expression) {
+    if (!ts.isIdentifier(expression))
+        return undefined;
+    if (expression.text === 'apiOpenApiRawResponse' ||
+        expression.text === 'apiResponse' ||
+        expression.text === 'apiNoContent')
+        return expression.text;
+    return undefined;
+}
+export function isContextMethod(expression, method) {
+    return (ts.isPropertyAccessExpression(expression) &&
+        ts.isIdentifier(expression.expression) &&
+        expression.expression.text === 'ctx' &&
+        expression.name.text === method);
+}
+/** Detects the framework's explicit no-body signal independently of the response status. */
+export function isContextResponseEmptyCall(expression) {
+    if (!ts.isPropertyAccessExpression(expression) || expression.name.text !== 'empty')
+        return false;
+    return isContextMethod(expression.expression, 'response');
+}
+/** Detects `ctx.response.buffer(...)`: a raw pass-through body whose shape can't be statically extracted. */
+export function isContextResponseBufferCall(expression) {
+    if (!ts.isPropertyAccessExpression(expression) || expression.name.text !== 'buffer')
+        return false;
+    return isContextMethod(expression.expression, 'response');
+}

package/dist/api-contract-discovery/response-contract-error-branch.d.mts

@@ -0,0 +1,15 @@
+import ts from '../contract-schema/typescript-api.mts';
+/**
+ * Detects a hand-rolled early-return error guard: `ctx.setStatus(NNN >= 400)` followed by a
+ * response body call in the same block (e.g. `auth-me.mts`'s `ctx.setStatus(401); return
+ * ctx.json({error})` before its `ctx.json({user})` success body). Skipping these keeps the
+ * bare implicit key free for the route's actual success body instead of locking onto whichever
+ * error branch happens to appear first in document order.
+ *
+ * Deliberately narrow: only a *direct* sibling `ExpressionStatement` counts, not a nested one
+ * inside an earlier sibling's own subtree (e.g. inside an earlier, unrelated `if` guard's own
+ * block). Recursing into nested subtrees would flag a trailing success statement that follows
+ * two independent, self-contained early-return guards, even though neither guard's error status
+ * is in effect on the path that reaches the trailing statement.
+ */
+export declare function isInErrorBranch(call: ts.CallExpression): boolean;

package/dist/api-contract-discovery/response-contract-error-branch.mjs

@@ -0,0 +1,47 @@
+import ts from '../contract-schema/typescript-api.mjs';
+import { isContextMethod } from './response-contract-route-analysis.mjs';
+/**
+ * Detects a hand-rolled early-return error guard: `ctx.setStatus(NNN >= 400)` followed by a
+ * response body call in the same block (e.g. `auth-me.mts`'s `ctx.setStatus(401); return
+ * ctx.json({error})` before its `ctx.json({user})` success body). Skipping these keeps the
+ * bare implicit key free for the route's actual success body instead of locking onto whichever
+ * error branch happens to appear first in document order.
+ *
+ * Deliberately narrow: only a *direct* sibling `ExpressionStatement` counts, not a nested one
+ * inside an earlier sibling's own subtree (e.g. inside an earlier, unrelated `if` guard's own
+ * block). Recursing into nested subtrees would flag a trailing success statement that follows
+ * two independent, self-contained early-return guards, even though neither guard's error status
+ * is in effect on the path that reaches the trailing statement.
+ */
+export function isInErrorBranch(call) {
+    let statement = call;
+    while (!ts.isStatement(statement))
+        statement = statement.parent;
+    return precededByErrorStatus(statement);
+}
+/**
+ * Walks outward through enclosing blocks so a `ctx.setStatus(>=400)` set before the branch's own
+ * containing statement — not just a direct sibling in the same block — still marks the branch as
+ * an error path. Needed for a shared helper like `data-request.mts`'s `sendActiveRequestConflict`,
+ * which sets one error status up front, then branches into two differently-shaped `ctx.json`
+ * bodies nested one block deeper.
+ */
+function precededByErrorStatus(statement) {
+    const block = statement.parent;
+    if (!ts.isBlock(block))
+        return false;
+    const index = block.statements.indexOf(statement);
+    if (block.statements.slice(0, index).some(isBareErrorStatusStatement))
+        return true;
+    const enclosing = block.parent;
+    return ts.isStatement(enclosing) ? precededByErrorStatus(enclosing) : false;
+}
+function isBareErrorStatusStatement(statement) {
+    if (!ts.isExpressionStatement(statement))
+        return false;
+    const expression = statement.expression;
+    if (!ts.isCallExpression(expression) || !isContextMethod(expression.expression, 'setStatus'))
+        return false;
+    const statusArgument = expression.arguments[0];
+    return (!!statusArgument && ts.isNumericLiteral(statusArgument) && Number(statusArgument.text) >= 400);
+}

package/dist/api-contract-discovery/response-contract-implicit-sources.test-helpers.d.mts

@@ -0,0 +1,145 @@
+export declare const responseContractImplicitSources: {
+    readonly 'called-helper': `
+    declare const app: any
+    async function handleCreate(ctx: any) {
+      ctx.setStatus(201)
+      return { id: 'one' as string }
+    }
+    app.route('/api/v1/items').post(async (ctx: any) => {
+      ctx.json(await handleCreate(ctx))
+    })
+  `;
+    readonly 'shared-helper': `
+    declare const app: any
+    function markCreated(ctx: any) { ctx.setStatus(201) }
+    app.route('/api/v1/items').post((ctx: any) => {
+      markCreated(ctx)
+      ctx.json({ id: 'one' as string })
+    })
+    app.route('/api/v1/widgets').post((ctx: any) => {
+      markCreated(ctx)
+      ctx.json({ id: 'one' as string })
+    })
+  `;
+    readonly empty: `
+    declare const app: any
+    app.route('/api/v1/items/:id').delete((ctx: any) => {
+      ctx.setStatus(200)
+      ctx.response.empty()
+    })
+  `;
+    readonly 'error-guard': `
+    declare const app: any
+    app.route('/api/v1/auth/me').get((ctx: any) => {
+      if (!ctx.user) {
+        ctx.setStatus(401)
+        return ctx.json({ error: 'not authenticated' as string })
+      }
+      ctx.json({ user: { id: 'one' as string } })
+    })
+  `;
+    readonly 'two-guards': `
+    declare const app: any
+    app.route('/api/v1/items/:id').get((ctx: any) => {
+      if (!ctx.user) {
+        ctx.setStatus(401)
+        return ctx.json({ error: 'not authenticated' as string })
+      }
+      if (!ctx.item) {
+        ctx.setStatus(404)
+        return ctx.json({ error: 'not found' as string })
+      }
+      ctx.json({ item: { id: 'one' as string } })
+    })
+  `;
+    readonly conflict: `
+    declare const app: any
+    const sendConflict = (ctx: any, existing: any) => {
+      ctx.setStatus(409)
+      if (!existing) {
+        ctx.json({ error: 'conflict' as string })
+        return
+      }
+      ctx.json({ error: 'conflict' as string, id: 'x' as string })
+    }
+    app.route('/api/v1/items').post((ctx: any) => {
+      const conflict: any = {}
+      if (conflict.existing !== undefined) {
+        sendConflict(ctx, conflict.existing)
+        return
+      }
+      ctx.setStatus(201)
+      ctx.json({ id: 'one' as string, status: 'pending' as string })
+    })
+  `;
+    readonly ternary: `
+    declare const app: any
+    declare const created: boolean
+    app.route('/api/v1/items').post((ctx: any) => {
+      ctx.setStatus(created ? 201 : 200)
+      ctx.json({ id: 'one' as string })
+    })
+  `;
+    readonly variants: `
+    declare const app: any
+    declare function apiResponse<K extends string, T>(key: K, body: T): T
+    app.route('/api/v1/items').post((ctx: any) => {
+      ctx.setStatus(422)
+      apiResponse('POST:/api/v1/items#validation', { error: 'invalid' as string })
+      ctx.setStatus(201)
+      apiResponse('POST:/api/v1/items', { id: 'one' as string })
+    })
+  `;
+    readonly branches: `
+    declare const app: any
+    app.route('/api/v1/webhooks/:id').post((ctx: any) => {
+      if (ctx.body.event === 'known') {
+        ctx.json({ received: true as boolean })
+        return
+      }
+      ctx.json({ ignored: true as boolean })
+    })
+  `;
+    readonly 'secondary-failure': `
+    declare const app: any
+    declare function riskyLookup(): any
+    app.route('/api/v1/jobs/:id').get((ctx: any) => {
+      if (ctx.query.mode === 'basic') {
+        ctx.json({ ready: true as boolean })
+        return
+      }
+      ctx.json({ value: riskyLookup() })
+    })
+  `;
+    readonly 'empty-then-buffer': `
+    declare const app: any
+    declare const body: any
+    declare const contentType: string
+    app.route('/api/v1/mcp').post((ctx: any) => {
+      if (body.byteLength === 0) {
+        ctx.response.empty()
+      } else {
+        ctx.response.buffer(body, contentType)
+      }
+    })
+  `;
+    readonly 'buffer-then-empty': `
+    declare const app: any
+    declare const body: any
+    declare const contentType: string
+    app.route('/api/v1/mcp').post((ctx: any) => {
+      if (body.byteLength > 0) {
+        ctx.response.buffer(body, contentType)
+      } else {
+        ctx.response.empty()
+      }
+    })
+  `;
+    readonly 'single-failure': `
+    declare const app: any
+    declare function riskyLookup(): any
+    app.route('/api/v1/jobs/:id').get((ctx: any) => {
+      ctx.json({ value: riskyLookup() })
+    })
+  `;
+};

package/dist/api-contract-discovery/response-contract-implicit-sources.test-helpers.mjs

@@ -0,0 +1,145 @@
+export const responseContractImplicitSources = {
+    'called-helper': `
+    declare const app: any
+    async function handleCreate(ctx: any) {
+      ctx.setStatus(201)
+      return { id: 'one' as string }
+    }
+    app.route('/api/v1/items').post(async (ctx: any) => {
+      ctx.json(await handleCreate(ctx))
+    })
+  `,
+    'shared-helper': `
+    declare const app: any
+    function markCreated(ctx: any) { ctx.setStatus(201) }
+    app.route('/api/v1/items').post((ctx: any) => {
+      markCreated(ctx)
+      ctx.json({ id: 'one' as string })
+    })
+    app.route('/api/v1/widgets').post((ctx: any) => {
+      markCreated(ctx)
+      ctx.json({ id: 'one' as string })
+    })
+  `,
+    empty: `
+    declare const app: any
+    app.route('/api/v1/items/:id').delete((ctx: any) => {
+      ctx.setStatus(200)
+      ctx.response.empty()
+    })
+  `,
+    'error-guard': `
+    declare const app: any
+    app.route('/api/v1/auth/me').get((ctx: any) => {
+      if (!ctx.user) {
+        ctx.setStatus(401)
+        return ctx.json({ error: 'not authenticated' as string })
+      }
+      ctx.json({ user: { id: 'one' as string } })
+    })
+  `,
+    'two-guards': `
+    declare const app: any
+    app.route('/api/v1/items/:id').get((ctx: any) => {
+      if (!ctx.user) {
+        ctx.setStatus(401)
+        return ctx.json({ error: 'not authenticated' as string })
+      }
+      if (!ctx.item) {
+        ctx.setStatus(404)
+        return ctx.json({ error: 'not found' as string })
+      }
+      ctx.json({ item: { id: 'one' as string } })
+    })
+  `,
+    conflict: `
+    declare const app: any
+    const sendConflict = (ctx: any, existing: any) => {
+      ctx.setStatus(409)
+      if (!existing) {
+        ctx.json({ error: 'conflict' as string })
+        return
+      }
+      ctx.json({ error: 'conflict' as string, id: 'x' as string })
+    }
+    app.route('/api/v1/items').post((ctx: any) => {
+      const conflict: any = {}
+      if (conflict.existing !== undefined) {
+        sendConflict(ctx, conflict.existing)
+        return
+      }
+      ctx.setStatus(201)
+      ctx.json({ id: 'one' as string, status: 'pending' as string })
+    })
+  `,
+    ternary: `
+    declare const app: any
+    declare const created: boolean
+    app.route('/api/v1/items').post((ctx: any) => {
+      ctx.setStatus(created ? 201 : 200)
+      ctx.json({ id: 'one' as string })
+    })
+  `,
+    variants: `
+    declare const app: any
+    declare function apiResponse<K extends string, T>(key: K, body: T): T
+    app.route('/api/v1/items').post((ctx: any) => {
+      ctx.setStatus(422)
+      apiResponse('POST:/api/v1/items#validation', { error: 'invalid' as string })
+      ctx.setStatus(201)
+      apiResponse('POST:/api/v1/items', { id: 'one' as string })
+    })
+  `,
+    branches: `
+    declare const app: any
+    app.route('/api/v1/webhooks/:id').post((ctx: any) => {
+      if (ctx.body.event === 'known') {
+        ctx.json({ received: true as boolean })
+        return
+      }
+      ctx.json({ ignored: true as boolean })
+    })
+  `,
+    'secondary-failure': `
+    declare const app: any
+    declare function riskyLookup(): any
+    app.route('/api/v1/jobs/:id').get((ctx: any) => {
+      if (ctx.query.mode === 'basic') {
+        ctx.json({ ready: true as boolean })
+        return
+      }
+      ctx.json({ value: riskyLookup() })
+    })
+  `,
+    'empty-then-buffer': `
+    declare const app: any
+    declare const body: any
+    declare const contentType: string
+    app.route('/api/v1/mcp').post((ctx: any) => {
+      if (body.byteLength === 0) {
+        ctx.response.empty()
+      } else {
+        ctx.response.buffer(body, contentType)
+      }
+    })
+  `,
+    'buffer-then-empty': `
+    declare const app: any
+    declare const body: any
+    declare const contentType: string
+    app.route('/api/v1/mcp').post((ctx: any) => {
+      if (body.byteLength > 0) {
+        ctx.response.buffer(body, contentType)
+      } else {
+        ctx.response.empty()
+      }
+    })
+  `,
+    'single-failure': `
+    declare const app: any
+    declare function riskyLookup(): any
+    app.route('/api/v1/jobs/:id').get((ctx: any) => {
+      ctx.json({ value: riskyLookup() })
+    })
+  `,
+};

package/dist/api-contract-discovery/response-contract-implicit.d.mts

@@ -0,0 +1,5 @@
+import ts from '../contract-schema/typescript-api.mts';
+import { type DiscoverApiResponseContractsOptions } from './response-contract-lenient.mts';
+import { type HandlerBindings } from './response-contract-route-analysis.mts';
+import type { BackendResponseContract } from './response-contract-types.mts';
+export declare function discoverImplicitContract(call: ts.CallExpression, checker: ts.TypeChecker, sourceFile: ts.SourceFile, contracts: Map<string, BackendResponseContract>, handlerBindings: HandlerBindings, requestedKeys: ReadonlySet<string> | undefined, options: DiscoverApiResponseContractsOptions | undefined): void;

package/dist/api-contract-discovery/response-contract-implicit.mjs

@@ -0,0 +1,110 @@
+import ts from '../contract-schema/typescript-api.mjs';
+import { extractContractSchema } from '../contract-schema/index.mjs';
+import { containsResponseMarker, noContentContract, registerContract, responseBodyExpression, sourceLocation, } from './response-contract-registration.mjs';
+import { isInErrorBranch } from './response-contract-error-branch.mjs';
+import { isXmlResponseCall, streamingTextMediaType } from './response-contract-media.mjs';
+import { markBufferedRouteUnavailable, registerRouteContract, } from './response-contract-lenient.mjs';
+import { enclosingRouteBinding, isContextMethod, isContextResponseBufferCall, isContextResponseEmptyCall, requestedKeyForBinding, responseMarker, } from './response-contract-route-analysis.mjs';
+import { resolveEmissionStatus } from './response-contract-status.mjs';
+export function discoverImplicitContract(call, checker, sourceFile, contracts, handlerBindings, requestedKeys, options) {
+    const binding = enclosingRouteBinding(call, checker, handlerBindings);
+    if (!binding)
+        return;
+    const key = requestedKeyForBinding(binding, requestedKeys);
+    if (!key)
+        return;
+    const body = responseBodyExpression(call);
+    if (body) {
+        if (ts.isCallExpression(body) && responseMarker(body.expression))
+            return;
+        if (requestedKeys && contracts.has(key))
+            return;
+        if (isInErrorBranch(call))
+            return;
+        const location = sourceLocation(sourceFile, call);
+        const extract = () => extractContractSchema(checker.getTypeAtLocation(body), checker, location, options);
+        const status = resolveEmissionStatus(call);
+        const emission = {
+            bodyKind: 'content',
+            mediaType: 'application/json',
+            mediaTypeKnowledge: 'known',
+            ...status,
+        };
+        // Primary body (bare key, or requested key in subset mode) uses the lenient path, so a
+        // genuine single-variant route still reports a real `unavailableReason` on failure.
+        if (requestedKeys || !contracts.has(key)) {
+            registerRouteContract(contracts, key, binding, location, emission, extract, options);
+            return;
+        }
+        // Full-scope discovery: a route can emit more than one distinct unmarked success body across
+        // branches (e.g. a webhook's `{received}` vs `{ignored}`); register each under its own key —
+        // `groupContractsByRoute` merges by method/routeTemplate, not this key. This route already has
+        // a primary contract, so retain this one under a deterministic variant key. A failed secondary
+        // extraction is registered as unavailable so the operation never silently omits a real branch.
+        registerRouteContract(contracts, nextImplicitVariantKey(contracts, key), binding, location, emission, extract, options);
+        return;
+    }
+    if (isXmlResponseCall(call)) {
+        if (requestedKeys && contracts.has(key))
+            return;
+        const body = call.arguments[0];
+        if (!body)
+            return;
+        const location = sourceLocation(sourceFile, call);
+        registerRouteContract(contracts, contracts.has(key) ? nextImplicitVariantKey(contracts, key) : key, binding, location, {
+            bodyKind: 'content',
+            mediaType: 'application/xml',
+            mediaTypeKnowledge: 'known',
+            ...resolveEmissionStatus(call),
+        }, () => extractContractSchema(checker.getTypeAtLocation(body), checker, location, options), options);
+        return;
+    }
+    const streamedTextMediaType = isContextMethod(call.expression, 'pipeline')
+        ? streamingTextMediaType(call)
+        : undefined;
+    if (streamedTextMediaType) {
+        const location = sourceLocation(sourceFile, call);
+        registerRouteContract(contracts, contracts.has(key) ? nextImplicitVariantKey(contracts, key) : key, binding, location, {
+            bodyKind: 'content',
+            mediaType: streamedTextMediaType,
+            mediaTypeKnowledge: 'known',
+            ...resolveEmissionStatus(call),
+        }, () => extractContractSchema(checker.getStringType(), checker, location, options), options);
+        return;
+    }
+    // Empty and raw branches can coexist; AST order must not let empty hide an unmarked raw body,
+    // so every buffer or pipeline without an explicit response marker makes the route unavailable.
+    if (isContextResponseBufferCall(call.expression) ||
+        (isContextMethod(call.expression, 'pipeline') && !body && !containsResponseMarker(call))) {
+        markBufferedRouteUnavailable(contracts, key, binding, sourceLocation(sourceFile, call));
+        return;
+    }
+    if (requestedKeys && contracts.has(key))
+        return;
+    const emissionStatus = resolveEmissionStatus(call);
+    const isExplicitNoContentCall = (isContextMethod(call.expression, 'setStatus') &&
+        call.arguments[0] &&
+        ts.isNumericLiteral(call.arguments[0]) &&
+        (call.arguments[0].text === '204' || call.arguments[0].text === '205')) ||
+        isContextResponseEmptyCall(call.expression);
+    if (isExplicitNoContentCall) {
+        registerContract(contracts, contracts.has(key) ? nextImplicitVariantKey(contracts, key) : key, {
+            ...noContentContract(sourceLocation(sourceFile, call)),
+            ...binding,
+            bodyKind: 'none',
+            mediaTypeKnowledge: 'none',
+            ...(emissionStatus.statusCodes ? { statusCodes: emissionStatus.statusCodes } : {}),
+            statusKnowledge: emissionStatus.statusKnowledge,
+            ...(emissionStatus.unavailableReason
+                ? { unavailableReason: emissionStatus.unavailableReason }
+                : {}),
+        });
+    }
+}
+/** Picks the next deterministic registration key for another implicit response variant. */
+function nextImplicitVariantKey(contracts, key) {
+    let suffix = 2;
+    while (contracts.has(`${key}#implicit-${suffix}`))
+        suffix++;
+    return `${key}#implicit-${suffix}`;
+}

package/dist/api-contract-discovery/response-contract-lenient.d.mts

@@ -0,0 +1,23 @@
+import type { ExtractedResponseContract, ExtractContractSchemaOptions } from '../contract-schema/index.mts';
+import type { RouteBinding } from './response-contract-route-analysis.mts';
+import type { BackendResponseContract } from './response-contract-types.mts';
+export type RouteDiscoveryError = {
+    method: string;
+    routeTemplate: string;
+    source: string;
+    reason: string;
+};
+export type DiscoverApiResponseContractsOptions = ExtractContractSchemaOptions & {
+    onRouteError?: (error: RouteDiscoveryError) => void;
+};
+/** Marks `key` unavailable regardless of AST visit order, for a route that can send a raw buffered body (e.g. a proxied MCP response) alongside a no-content branch. */
+export declare function markBufferedRouteUnavailable(contracts: Map<string, BackendResponseContract>, key: string, binding: RouteBinding, source: string): void;
+/**
+ * Extracts a route's response contract and registers it. When `options.onRouteError` is
+ * set, an extraction failure is caught, reported, and replaced with an `unavailable`
+ * placeholder instead of aborting discovery for every other route. With `options` absent
+ * (or `onRouteError` unset), behavior is unchanged: extraction failures throw.
+ */
+export declare function registerRouteContract(contracts: Map<string, BackendResponseContract>, key: string, binding: RouteBinding, location: string, emission: Pick<BackendResponseContract, 'bodyKind' | 'mediaType' | 'mediaTypeKnowledge' | 'statusCodes' | 'statusKnowledge'> & {
+    unavailableReason?: string;
+}, extract: () => ExtractedResponseContract, options: DiscoverApiResponseContractsOptions | undefined): void;

package/dist/api-contract-discovery/response-contract-lenient.mjs

@@ -0,0 +1,52 @@
+import { hashContractSchema } from '../contract-schema/index.mjs';
+import { registerContract } from './response-contract-registration.mjs';
+/** Placeholder contract for a route whose response type could not be extracted. */
+function unavailableContract(source, reason) {
+    const schema = { root: { type: 'unknown' }, definitions: {} };
+    return { source, schema, hash: hashContractSchema(schema), unavailableReason: reason };
+}
+/** Marks `key` unavailable regardless of AST visit order, for a route that can send a raw buffered body (e.g. a proxied MCP response) alongside a no-content branch. */
+export function markBufferedRouteUnavailable(contracts, key, binding, source) {
+    contracts.set(key, {
+        ...unavailableContract(source, 'route can send a raw buffered response body (ctx.response.buffer) whose shape is not statically determinable'),
+        ...binding,
+        bodyKind: 'content',
+        statusKnowledge: 'unknown',
+        mediaTypeKnowledge: 'unknown',
+    });
+}
+/**
+ * Extracts a route's response contract and registers it. When `options.onRouteError` is
+ * set, an extraction failure is caught, reported, and replaced with an `unavailable`
+ * placeholder instead of aborting discovery for every other route. With `options` absent
+ * (or `onRouteError` unset), behavior is unchanged: extraction failures throw.
+ */
+export function registerRouteContract(contracts, key, binding, location, emission, extract, options) {
+    let extracted;
+    try {
+        if (emission.unavailableReason)
+            throw new Error(emission.unavailableReason);
+        extracted = extract();
+    }
+    catch (error) {
+        if (!options?.onRouteError)
+            throw error;
+        const reason = error instanceof Error ? error.message : String(error);
+        options.onRouteError({
+            method: binding.method,
+            routeTemplate: binding.routeTemplate,
+            source: location,
+            reason,
+        });
+        extracted = unavailableContract(location, reason);
+    }
+    registerContract(contracts, key, {
+        ...extracted,
+        ...binding,
+        ...(emission.bodyKind ? { bodyKind: emission.bodyKind } : {}),
+        ...(emission.mediaType ? { mediaType: emission.mediaType } : {}),
+        ...(emission.mediaTypeKnowledge ? { mediaTypeKnowledge: emission.mediaTypeKnowledge } : {}),
+        ...(emission.statusCodes ? { statusCodes: emission.statusCodes } : {}),
+        ...(emission.statusKnowledge ? { statusKnowledge: emission.statusKnowledge } : {}),
+    });
+}