vouchington-tooling 0.29.0 → 0.31.0

package/dist/api-contract-discovery/protocol-callback-values.mjs

@@ -0,0 +1,114 @@
+import ts from '../contract-schema/typescript-api.mjs';
+import { registeredHandler } from './protocol-callback-registration.mjs';
+import { runtimeParameters } from './registered-route-runtime-parameters.mjs';
+import { hasBindingWrite } from './registered-route-binding-writes.mjs';
+import { unwrapExpression } from './protocol-marker-analysis.mjs';
+export function isProtocolCallbackFunction(node) {
+    return ts.isFunctionLike(node) && 'body' in node;
+}
+/** Resolves stable named uses in outer statements and directly registered inline handlers. */
+export function protocolCallbackSourceCalls(fn) {
+    const declaration = fn.parent;
+    if (!ts.isFunctionDeclaration(fn) &&
+        (!ts.isVariableDeclaration(declaration) ||
+            !ts.isIdentifier(declaration.name) ||
+            !ts.isVariableDeclarationList(declaration.parent) ||
+            !(declaration.parent.flags & ts.NodeFlags.Const)))
+        return [];
+    const calls = [];
+    function visit(node) {
+        if (isProtocolCallbackFunction(node) &&
+            !(ts.isCallExpression(node.parent) &&
+                registeredHandler(node.parent) &&
+                node.parent.arguments.includes(node)))
+            return;
+        if (ts.isCallExpression(node))
+            calls.push(node);
+        ts.forEachChild(node, visit);
+    }
+    visit(fn.getSourceFile());
+    return calls;
+}
+function literalName(node) {
+    return ts.isIdentifier(node) || ts.isStringLiteral(node) ? node.text : undefined;
+}
+export function createProtocolCallbackValueResolver(checker) {
+    function symbol(node) {
+        const found = checker.getSymbolAtLocation(node);
+        return found?.flags && found.flags & ts.SymbolFlags.Alias
+            ? checker.getAliasedSymbol(found)
+            : found;
+    }
+    function property(value, name, seen) {
+        if (!value ||
+            !ts.isObjectLiteralExpression(value.node) ||
+            value.node.properties.some(ts.isSpreadAssignment))
+            return undefined;
+        const member = value.node.properties.find((item) => item.name && literalName(item.name) === name);
+        if (member && ts.isPropertyAssignment(member))
+            return resolve(member.initializer, value.env, seen);
+        if (member && ts.isShorthandPropertyAssignment(member)) {
+            const target = checker.getShorthandAssignmentValueSymbol(member);
+            return target ? declaration(target, value.env, seen) : undefined;
+        }
+        return member && isProtocolCallbackFunction(member)
+            ? { node: member, env: value.env }
+            : undefined;
+    }
+    function declaration(target, env, seen) {
+        const bound = env.get(target);
+        if (bound)
+            return resolve(bound.node, bound.env, seen);
+        const implemented = target.declarations?.find((item) => isProtocolCallbackFunction(item) && item.body);
+        if (implemented)
+            return { node: implemented, env };
+        const node = target.valueDeclaration;
+        if (!node || seen.has(node))
+            return undefined;
+        seen.add(node);
+        if (ts.isVariableDeclaration(node) &&
+            node.initializer &&
+            ts.isVariableDeclarationList(node.parent) &&
+            node.parent.flags & ts.NodeFlags.Const)
+            return resolve(node.initializer, env, seen);
+        if (ts.isBindingElement(node) && ts.isObjectBindingPattern(node.parent)) {
+            const owner = node.parent.parent;
+            const name = literalName(node.propertyName ?? node.name);
+            if (name &&
+                ts.isVariableDeclaration(owner) &&
+                owner.initializer &&
+                ts.isVariableDeclarationList(owner.parent) &&
+                owner.parent.flags & ts.NodeFlags.Const)
+                return property(resolve(owner.initializer, env, seen), name, seen);
+        }
+        return undefined;
+    }
+    function resolve(node, env, seen = new Set()) {
+        if (ts.isExpression(node))
+            node = unwrapExpression(node);
+        if (seen.has(node))
+            return undefined;
+        seen.add(node);
+        if (isProtocolCallbackFunction(node) ||
+            ts.isObjectLiteralExpression(node) ||
+            ts.isArrayLiteralExpression(node))
+            return { node, env };
+        if (ts.isIdentifier(node)) {
+            const target = symbol(node);
+            return target ? declaration(target, env, seen) : undefined;
+        }
+        if (ts.isPropertyAccessExpression(node)) {
+            const member = property(resolve(node.expression, env, seen), node.name.text, seen);
+            if (member)
+                return member;
+            const target = symbol(node.name);
+            return target ? declaration(target, env, seen) : undefined;
+        }
+        return undefined;
+    }
+    return { resolve, symbol, property };
+}
+export function protocolCallbackHasWrittenBindings(fn, checker) {
+    return ((ts.isFunctionDeclaration(fn) && hasBindingWrite(fn, checker)) ||
+        runtimeParameters(fn).some((parameter) => hasBindingWrite(parameter, checker)));
+}

package/dist/api-contract-discovery/protocol-context-alias.d.mts

@@ -0,0 +1,3 @@
+import ts from '../contract-schema/typescript-api.mts';
+export declare function unsupportedContextAlias(node: ts.VariableDeclaration, context: ts.Symbol, checker: ts.TypeChecker): boolean;
+export declare function unsupportedContextAssignment(node: ts.Node, context: ts.Symbol, checker: ts.TypeChecker): boolean;

package/dist/api-contract-discovery/protocol-context-alias.mjs

@@ -0,0 +1,20 @@
+import ts from '../contract-schema/typescript-api.mjs';
+import { expressionReceiver } from './protocol-write-receiver.mjs';
+export function unsupportedContextAlias(node, context, checker) {
+    if (!node.initializer)
+        return false;
+    const receiver = expressionReceiver(node.initializer, checker);
+    return (receiver?.root === context &&
+        (receiver.path.length === 0 ||
+            (receiver.path.length === 1 && receiver.path[0] === 'response')) &&
+        (!ts.isIdentifier(node.name) ||
+            !ts.isVariableDeclarationList(node.parent) ||
+            !(node.parent.flags & ts.NodeFlags.Const)));
+}
+export function unsupportedContextAssignment(node, context, checker) {
+    if (!ts.isBinaryExpression(node) || node.operatorToken.kind !== ts.SyntaxKind.EqualsToken)
+        return false;
+    const receiver = expressionReceiver(node.right, checker);
+    return (receiver?.root === context &&
+        (receiver.path.length === 0 || (receiver.path.length === 1 && receiver.path[0] === 'response')));
+}

package/dist/api-contract-discovery/protocol-contract-extraction.d.mts

@@ -0,0 +1,9 @@
+import ts from '../contract-schema/typescript-api.mts';
+import { type ExtractedResponseContract } from '../contract-schema/index.mts';
+import type { DiscoverApiResponseContractsOptions } from './response-contract-lenient.mts';
+import type { BackendResponseContract } from './response-contract-types.mts';
+export declare function extractSseEvents(type: ts.Type, checker: ts.TypeChecker, source: string, options: DiscoverApiResponseContractsOptions | undefined): {
+    eventName: string;
+    contract: ExtractedResponseContract;
+}[];
+export declare function extractHttpVariants(type: ts.Type, checker: ts.TypeChecker, source: string, options: DiscoverApiResponseContractsOptions | undefined, selectRow: (index: number) => boolean): Omit<BackendResponseContract, 'method' | 'routeTemplate'>[];

package/dist/api-contract-discovery/protocol-contract-extraction.mjs

@@ -0,0 +1,87 @@
+import ts from '../contract-schema/typescript-api.mjs';
+import { extractContractSchema } from '../contract-schema/index.mjs';
+import { propertyType, stringLiterals, typeVariants } from './protocol-marker-analysis.mjs';
+import { noContentContract } from './response-contract-registration.mjs';
+import { statusForbidsBody } from './protocol-body-status.mjs';
+export function extractSseEvents(type, checker, source, options) {
+    return typeVariants(type).flatMap((variant) => {
+        const names = stringLiterals(propertyType(variant, 'event', checker));
+        const contract = concretePayload(propertyType(variant, 'data', checker), checker, source, options);
+        return names.map((eventName) => ({ eventName, contract }));
+    });
+}
+export function extractHttpVariants(type, checker, source, options, selectRow) {
+    const carrier = propertyType(type, 'apiHttpResponseVariants', checker);
+    const variants = typeVariants(carrier).filter((variant) => !(variant.flags & ts.TypeFlags.Undefined));
+    if (variants.length === 0)
+        throw new Error('HTTP response requires concrete variants');
+    let row = 0;
+    const selections = variants.map((variant) => {
+        const rawMedia = rawPropertyType(variant, 'mediaType', checker);
+        const rawKind = rawPropertyType(variant, 'bodyKind', checker);
+        const count = rawKind?.isStringLiteral() && rawKind.value === 'none'
+            ? 1
+            : rawMedia?.isUnion()
+                ? rawMedia.types.length
+                : 1;
+        const selected = Array.from({ length: count }, () => selectRow(row++));
+        return selected;
+    });
+    return variants.flatMap((variant, index) => {
+        const selected = selections[index];
+        if (!selected.some(Boolean))
+            return [];
+        const status = propertyType(variant, 'status', checker);
+        if (!(status.flags & ts.TypeFlags.NumberLiteral))
+            throw new Error('HTTP response requires a literal status');
+        const value = status.value;
+        if (!Number.isInteger(value) || value < 100 || value > 599)
+            throw new Error('HTTP response status is invalid');
+        const kinds = stringLiterals(propertyType(variant, 'bodyKind', checker));
+        if (kinds.length !== 1)
+            throw new Error('HTTP response requires one concrete body kind per variant');
+        const statusCodes = [value];
+        if (kinds[0] === 'none')
+            return [
+                {
+                    ...noContentContract(source),
+                    statusCodes,
+                    statusKnowledge: 'explicit',
+                    bodyKind: 'none',
+                    mediaTypeKnowledge: 'none',
+                    ...(value === 400 ? { includeDefaultError: true } : {}),
+                },
+            ];
+        if (kinds[0] !== 'content')
+            throw new Error('HTTP response body kind is invalid');
+        if (statusForbidsBody(value))
+            throw new Error(`HTTP status ${value} forbids response content`);
+        const contract = concretePayload(propertyType(variant, 'body', checker), checker, source, options);
+        return stringLiterals(propertyType(variant, 'mediaType', checker)).flatMap((mediaType, index) => selected[index]
+            ? [
+                {
+                    ...contract,
+                    statusCodes,
+                    statusKnowledge: 'explicit',
+                    bodyKind: 'content',
+                    mediaType,
+                    mediaTypeKnowledge: 'known',
+                    ...(value === 400 ? { includeDefaultError: true } : {}),
+                },
+            ]
+            : []);
+    });
+}
+function concretePayload(type, checker, source, options) {
+    const contract = extractContractSchema(type, checker, source, options);
+    if (contract.schema.root.type === 'unknown')
+        throw new Error('Protocol payload must have a concrete root');
+    return contract;
+}
+function rawPropertyType(type, name, checker) {
+    const property = checker.getPropertyOfType(type, name);
+    const declaration = property?.valueDeclaration ?? property?.declarations?.[0];
+    return property && declaration
+        ? checker.getTypeOfSymbolAtLocation(property, declaration)
+        : undefined;
+}

package/dist/api-contract-discovery/protocol-contract-keys.d.mts

@@ -0,0 +1 @@
+export declare function nextProtocolKey(contracts: ReadonlyMap<string, unknown>, key: string): string;

package/dist/api-contract-discovery/protocol-contract-keys.mjs

@@ -0,0 +1,8 @@
+export function nextProtocolKey(contracts, key) {
+    if (!contracts.has(key))
+        return key;
+    let index = 2;
+    while (contracts.has(`${key}#protocol-${index}`))
+        index++;
+    return `${key}#protocol-${index}`;
+}

package/dist/api-contract-discovery/protocol-contract-registry.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 discoverProtocolContracts(sourceFiles: readonly ts.SourceFile[], checker: ts.TypeChecker, bindings: HandlerBindings, contracts: Map<string, BackendResponseContract>, options: DiscoverApiResponseContractsOptions | undefined, requestedKeys?: ReadonlySet<string>): Set<ts.CallExpression>;

package/dist/api-contract-discovery/protocol-contract-registry.mjs

@@ -0,0 +1,133 @@
+import ts from '../contract-schema/typescript-api.mjs';
+import { nextProtocolKey } from './protocol-contract-keys.mjs';
+import { extractContractSchema } from '../contract-schema/index.mjs';
+import { extractHttpVariants, extractSseEvents } from './protocol-contract-extraction.mjs';
+import { extractHttpBodyKinds } from './protocol-http-body-kinds.mjs';
+import { registerHttpProtocols } from './protocol-http-registration.mjs';
+import { protocolBindingRequested, requestedProtocolKey } from './protocol-requested-keys.mjs';
+import { protocolMarker } from './protocol-marker-analysis.mjs';
+import { registerRouteContract, } from './response-contract-lenient.mjs';
+import { contractError, sourceLocation } from './response-contract-registration.mjs';
+import { enclosingRouteBinding, visit, } from './response-contract-route-analysis.mjs';
+import { rejectRawSseWrites } from './protocol-sse-raw-writes.mjs';
+import { sseEmission } from './protocol-sse-emission.mjs';
+export function discoverProtocolContracts(sourceFiles, checker, bindings, contracts, options, requestedKeys) {
+    if (requestedKeys?.size === 0)
+        return new Set();
+    const calls = [];
+    for (const file of sourceFiles)
+        visit(file, (node) => {
+            if (ts.isCallExpression(node))
+                calls.push(node);
+        });
+    const pending = [];
+    const allocated = new Map();
+    const framedWrites = new Set();
+    const sseBindings = new Map();
+    for (const file of sourceFiles)
+        visit(file, (node) => {
+            if (!ts.isCallExpression(node))
+                return;
+            const marker = protocolMarker(node.expression, checker);
+            if (!marker)
+                return;
+            const binding = enclosingRouteBinding(node, checker, bindings, false);
+            if (!binding)
+                throw contractError(file, node, `${marker} must be inside an app.route handler`);
+            if (!protocolBindingRequested(binding, requestedKeys))
+                return;
+            const keyNode = node.arguments[0];
+            if (!keyNode || !ts.isStringLiteral(keyNode))
+                throw contractError(file, node, `${marker} requires a literal contract key`);
+            const prefix = `${binding.method}:${binding.routeTemplate}`;
+            if (keyNode.text !== prefix && !keyNode.text.startsWith(`${prefix}#`))
+                throw contractError(file, keyNode, `Contract key "${keyNode.text}" does not match enclosing route ${prefix}`);
+            const location = sourceLocation(file, node);
+            let errorKeys = [];
+            try {
+                if (marker === 'apiSseFrame') {
+                    const rowKey = reserveKey(allocated, keyNode.text);
+                    errorKeys = [rowKey];
+                    if (!requestedProtocolKey(rowKey, binding, requestedKeys)) {
+                        if (ts.isCallExpression(node.parent))
+                            framedWrites.add(node.parent);
+                        return;
+                    }
+                    const body = node.arguments[1];
+                    if (!body)
+                        throw new Error(`${marker} requires a protocol body`);
+                    const { write, receiver, status } = sseEmission(node, checker, calls, binding, bindings);
+                    const sseEvents = extractSseEvents(checker.getTypeAtLocation(body), checker, location, options);
+                    contracts.set(rowKey, {
+                        ...extractContractSchema(checker.getStringType(), checker, location, options),
+                        ...binding,
+                        bodyKind: 'content',
+                        mediaType: 'text/event-stream',
+                        mediaTypeKnowledge: 'known',
+                        ...status,
+                        sseEvents,
+                    });
+                    framedWrites.add(write);
+                    const routeWrites = sseBindings.get(prefix) ?? { receivers: [], keys: [] };
+                    routeWrites.receivers.push(receiver);
+                    routeWrites.keys.push(rowKey);
+                    sseBindings.set(prefix, routeWrites);
+                }
+                else {
+                    const declaration = node.parent;
+                    const symbol = ts.isVariableDeclaration(declaration) &&
+                        ts.isIdentifier(declaration.name) &&
+                        ts.isVariableDeclarationList(declaration.parent) &&
+                        !!(declaration.parent.flags & ts.NodeFlags.Const)
+                        ? checker.getSymbolAtLocation(declaration.name)
+                        : undefined;
+                    if (!symbol)
+                        throw new Error('apiOpenApiHttpResponse must bind a response variable');
+                    const keys = [];
+                    errorKeys = keys;
+                    const variants = extractHttpVariants(checker.getTypeAtLocation(node), checker, location, options, () => {
+                        const rowKey = reserveKey(allocated, keyNode.text);
+                        if (!requestedProtocolKey(rowKey, binding, requestedKeys))
+                            return false;
+                        keys.push(rowKey);
+                        return true;
+                    });
+                    pending.push({
+                        call: node,
+                        symbol,
+                        binding,
+                        variants,
+                        get declaredBodyKinds() {
+                            return extractHttpBodyKinds(checker.getTypeAtLocation(node), checker);
+                        },
+                        keys,
+                    });
+                }
+            }
+            catch (error) {
+                for (const key of errorKeys.length ? errorKeys : [reserveKey(allocated, keyNode.text)])
+                    unavailable(contracts, key, binding, location, error, options);
+            }
+        });
+    const covered = registerHttpProtocols(pending, contracts, checker, (response, error) => {
+        for (const key of response.keys)
+            unavailable(contracts, key, response.binding, response.variants[0].source, error, options);
+    });
+    rejectRawSseWrites(sourceFiles, checker, bindings, framedWrites, sseBindings, (node, binding, keys) => {
+        for (const key of keys) {
+            contracts.delete(key);
+            unavailable(contracts, key, binding, sourceLocation(node.getSourceFile(), node), new Error('SSE route writes an unmarked frame'), options);
+        }
+    });
+    return covered;
+}
+function unavailable(contracts, key, binding, location, error, options) {
+    registerRouteContract(contracts, nextProtocolKey(contracts, key), binding, location, { bodyKind: 'content', statusKnowledge: 'unknown', mediaTypeKnowledge: 'unknown' }, () => {
+        throw error;
+    }, options);
+}
+function reserveKey(allocated, key) {
+    const row = nextProtocolKey(allocated, key);
+    allocated.set(row, undefined);
+    return row;
+}

package/dist/api-contract-discovery/protocol-executable-path.d.mts

@@ -0,0 +1,3 @@
+import ts from '../contract-schema/typescript-api.mts';
+/** Excludes statically dead branches without claiming that dynamic branches always run. */
+export declare function potentiallyExecuted(node: ts.Node): boolean;

package/dist/api-contract-discovery/protocol-executable-path.mjs

@@ -0,0 +1,64 @@
+import ts from '../contract-schema/typescript-api.mjs';
+import { unwrapExpression } from './protocol-marker-analysis.mjs';
+/** Excludes statically dead branches without claiming that dynamic branches always run. */
+export function potentiallyExecuted(node) {
+    let current = node;
+    while (current.parent && !ts.isFunctionLike(current.parent)) {
+        const parent = current.parent;
+        if (ts.isBlock(parent)) {
+            const index = parent.statements.indexOf(current);
+            if (parent.statements.slice(0, index).some(terminates))
+                return false;
+        }
+        if (ts.isIfStatement(parent)) {
+            const condition = unwrapExpression(parent.expression).kind;
+            if (condition === ts.SyntaxKind.FalseKeyword && parent.thenStatement === current)
+                return false;
+            if (condition === ts.SyntaxKind.TrueKeyword && parent.elseStatement === current)
+                return false;
+        }
+        if ((ts.isWhileStatement(parent) || ts.isForStatement(parent)) &&
+            parent.statement === current) {
+            const condition = ts.isWhileStatement(parent) ? parent.expression : parent.condition;
+            if (condition && unwrapExpression(condition).kind === ts.SyntaxKind.FalseKeyword)
+                return false;
+        }
+        if (ts.isConditionalExpression(parent)) {
+            const condition = unwrapExpression(parent.condition).kind;
+            if (condition === ts.SyntaxKind.FalseKeyword && parent.whenTrue === current)
+                return false;
+            if (condition === ts.SyntaxKind.TrueKeyword && parent.whenFalse === current)
+                return false;
+        }
+        if (ts.isBinaryExpression(parent) && parent.right === current) {
+            const left = unwrapExpression(parent.left).kind;
+            if (left === ts.SyntaxKind.FalseKeyword &&
+                parent.operatorToken.kind === ts.SyntaxKind.AmpersandAmpersandToken)
+                return false;
+            if (left === ts.SyntaxKind.TrueKeyword &&
+                parent.operatorToken.kind === ts.SyntaxKind.BarBarToken)
+                return false;
+        }
+        current = parent;
+    }
+    return true;
+}
+function terminates(statement) {
+    if (ts.isReturnStatement(statement) ||
+        ts.isThrowStatement(statement) ||
+        ts.isBreakStatement(statement) ||
+        ts.isContinueStatement(statement))
+        return true;
+    if (ts.isBlock(statement))
+        return statement.statements.some(terminates);
+    if (!ts.isIfStatement(statement))
+        return false;
+    const condition = unwrapExpression(statement.expression).kind;
+    if (condition === ts.SyntaxKind.TrueKeyword)
+        return terminates(statement.thenStatement);
+    if (condition === ts.SyntaxKind.FalseKeyword)
+        return !!statement.elseStatement && terminates(statement.elseStatement);
+    return (!!statement.elseStatement &&
+        terminates(statement.thenStatement) &&
+        terminates(statement.elseStatement));
+}

package/dist/api-contract-discovery/protocol-execution-path.d.mts

@@ -0,0 +1,3 @@
+import ts from '../contract-schema/typescript-api.mts';
+/** Proves execution up to an optional handler whose registered binding is already established. */
+export declare function executableProtocolPath(node: ts.Node, checker: ts.TypeChecker, boundHandler?: ts.Node): boolean;

package/dist/api-contract-discovery/protocol-execution-path.mjs

@@ -0,0 +1,16 @@
+import ts from '../contract-schema/typescript-api.mjs';
+import { isSupportedProtocolCallback } from './protocol-callback-invocation.mjs';
+import { potentiallyExecuted } from './protocol-executable-path.mjs';
+import { enclosingFunction } from './protocol-marker-analysis.mjs';
+/** Proves execution up to an optional handler whose registered binding is already established. */
+export function executableProtocolPath(node, checker, boundHandler) {
+    if (!potentiallyExecuted(node))
+        return false;
+    let fn = enclosingFunction(node);
+    while (fn && fn !== boundHandler) {
+        if (!potentiallyExecuted(fn) || !isSupportedProtocolCallback(fn, checker))
+            return false;
+        fn = enclosingFunction(fn);
+    }
+    return true;
+}

package/dist/api-contract-discovery/protocol-http-association.d.mts

@@ -0,0 +1,7 @@
+import ts from '../contract-schema/typescript-api.mts';
+export declare function associateHttpResponse(call: ts.CallExpression, response: ts.Symbol, checker: ts.TypeChecker, siblings?: ReadonlySet<ts.Symbol>): Map<ts.CallExpression, 'content' | 'none' | 'status'>;
+/** Opaque callbacks may emit through an independently proven handler's context. */
+export declare function opaqueHttpResponse(call: ts.CallExpression, checker: ts.TypeChecker, context?: ts.Symbol): boolean;
+/** Mutable wrappers on supported callback paths cannot establish a complete contract. */
+export declare function unsupportedContextResponse(call: ts.CallExpression, checker: ts.TypeChecker): boolean;
+export declare function supportedResponseContext(call: ts.CallExpression, checker: ts.TypeChecker): ts.Symbol | undefined;

package/dist/api-contract-discovery/protocol-http-association.mjs

@@ -0,0 +1,97 @@
+import ts from '../contract-schema/typescript-api.mjs';
+import { httpHandlerContext, httpContextScopes, indirectHttpResponseMethod, } from './protocol-http-context.mjs';
+import { runtimeParameters } from './registered-route-runtime-parameters.mjs';
+import { httpEmissionKind, contextResponseMethod } from './protocol-http-emission.mjs';
+import { enclosingFunction } from './protocol-marker-analysis.mjs';
+import { executableProtocolPath } from './protocol-execution-path.mjs';
+import { unsupportedContextAlias } from './protocol-context-alias.mjs';
+import { expressionReceiver } from './protocol-write-receiver.mjs';
+import { visit } from './response-contract-route-analysis.mjs';
+import { isSupportedProtocolCallback } from './protocol-callback-invocation.mjs';
+import { opaqueProtocolCallbackPath } from './protocol-opaque-callback.mjs';
+const responseMethods = new Set([
+    'setStatus',
+    'pipeline',
+    'json',
+    'response.buffer',
+    'response.empty',
+]);
+export function associateHttpResponse(call, response, checker, siblings) {
+    const handler = enclosingFunction(call);
+    const handlerContext = handler && httpHandlerContext(handler, checker);
+    if (!handler || !handlerContext)
+        throw new Error('HTTP response must bind the handler context');
+    if (!executableProtocolPath(call, checker))
+        throw new Error('HTTP response must be inside a supported executable handler callback');
+    const emissions = new Map();
+    for (const [scope, context] of httpContextScopes(handler, checker))
+        visit(scope, (node) => {
+            if (ts.isCallExpression(node) &&
+                executableProtocolPath(node, checker) &&
+                responseMethods.has(indirectHttpResponseMethod(node, context, checker) ?? ''))
+                throw new Error('HTTP response has an unsupported indirect status or body emission');
+            if (ts.isCallExpression(node) && opaqueHttpResponse(node, checker, context))
+                throw new Error('HTTP response context escapes through an opaque callback');
+            if (ts.isBinaryExpression(node) &&
+                node.operatorToken.kind === ts.SyntaxKind.EqualsToken &&
+                executableProtocolPath(node, checker)) {
+                const receiver = expressionReceiver(node.right, checker);
+                if (receiver?.root === context &&
+                    (receiver.path.length === 0 ||
+                        (receiver.path.length === 1 && receiver.path[0] === 'response')))
+                    throw new Error('HTTP response context has an unsupported mutable alias');
+            }
+            if (ts.isVariableDeclaration(node) &&
+                enclosingFunction(node) === scope &&
+                unsupportedContextAlias(node, context, checker))
+                throw new Error('HTTP response context has an unsupported mutable or destructured alias');
+            if (!ts.isCallExpression(node) || !executableProtocolPath(node, checker))
+                return;
+            const kind = enclosingFunction(node) === handler
+                ? httpEmissionKind(node, response, context, checker)
+                : undefined;
+            if (kind)
+                emissions.set(node, kind);
+            else if (responseMethods.has(contextResponseMethod(node.expression, context, checker, true) ?? '') &&
+                (enclosingFunction(node) === scope ||
+                    !!contextResponseMethod(node.expression, context, checker)))
+                if (siblings &&
+                    [...siblings].some((symbol) => symbol !== response && !!httpEmissionKind(node, symbol, context, checker)))
+                    return;
+                else
+                    throw new Error('HTTP response has an unrelated status or body emission');
+        });
+    return emissions;
+}
+/** Opaque callbacks may emit through an independently proven handler's context. */
+export function opaqueHttpResponse(call, checker, context) {
+    if (context)
+        return (responseMethods.has(contextResponseMethod(call.expression, context, checker, true) ??
+            indirectHttpResponseMethod(call, context, checker) ??
+            '') && opaqueProtocolCallbackPath(call, checker));
+    return !!supportedResponseContext(call, checker) && opaqueProtocolCallbackPath(call, checker);
+}
+/** Mutable wrappers on supported callback paths cannot establish a complete contract. */
+export function unsupportedContextResponse(call, checker) {
+    if (!executableProtocolPath(call, checker))
+        return false;
+    const context = supportedResponseContext(call, checker);
+    return !!context && contextResponseMethod(call.expression, context, checker) === undefined;
+}
+export function supportedResponseContext(call, checker) {
+    let handler = enclosingFunction(call);
+    while (handler) {
+        const name = runtimeParameters(handler)[0]?.name;
+        const symbol = name && ts.isIdentifier(name) ? checker.getSymbolAtLocation(name) : undefined;
+        if (symbol &&
+            responseMethods.has(contextResponseMethod(call.expression, symbol, checker, true) ??
+                indirectHttpResponseMethod(call, symbol, checker) ??
+                '') &&
+            httpHandlerContext(handler, checker) === symbol &&
+            isSupportedProtocolCallback(handler, checker) &&
+            executableProtocolPath(handler, checker))
+            return symbol;
+        handler = enclosingFunction(handler);
+    }
+    return undefined;
+}

package/dist/api-contract-discovery/protocol-http-body-kinds.d.mts

@@ -0,0 +1,3 @@
+import ts from '../contract-schema/typescript-api.mts';
+/** Checks complete wire body kinds without extracting unselected payload schemas. */
+export declare function extractHttpBodyKinds(type: ts.Type, checker: ts.TypeChecker): ReadonlySet<'content' | 'none'>;

package/dist/api-contract-discovery/protocol-http-body-kinds.mjs

@@ -0,0 +1,19 @@
+import ts from '../contract-schema/typescript-api.mjs';
+import { propertyType, stringLiterals, typeVariants } from './protocol-marker-analysis.mjs';
+/** Checks complete wire body kinds without extracting unselected payload schemas. */
+export function extractHttpBodyKinds(type, checker) {
+    const carrier = propertyType(type, 'apiHttpResponseVariants', checker);
+    const kinds = new Set();
+    for (const variant of typeVariants(carrier)) {
+        if (variant.flags & ts.TypeFlags.Undefined)
+            continue;
+        const names = stringLiterals(propertyType(variant, 'bodyKind', checker));
+        if (names.length !== 1)
+            throw new Error('HTTP response requires one concrete body kind per variant');
+        const kind = names[0];
+        if (kind !== 'content' && kind !== 'none')
+            throw new Error('HTTP response body kind is invalid');
+        kinds.add(kind);
+    }
+    return kinds;
+}

package/dist/api-contract-discovery/protocol-http-context-callers.d.mts

@@ -0,0 +1,6 @@
+import ts from '../contract-schema/typescript-api.mts';
+/** Use the same actual invocation sites for context admission and caller emission coverage. */
+export declare function httpContextInvocations(fn: ts.FunctionLikeDeclaration, checker: ts.TypeChecker): {
+    registered: boolean;
+    callers: ts.CallExpression[];
+};