vouchington-tooling 0.33.0 → 0.34.0

package/dist/api-contract-discovery/response-contract-handler-bindings.mjs

@@ -0,0 +1,126 @@
+import ts from '../contract-schema/typescript-api.mjs';
+import { executableProtocolPath } from './protocol-execution-path.mjs';
+import { potentiallyExecuted } from './protocol-executable-path.mjs';
+import { attributionSymbol, resolveSymbol } from './response-contract-symbols.mjs';
+import { findMutatedBindings, findMutatedProperties, } from './response-contract-property-mutations.mjs';
+import { handlerArgumentSymbols, isMutatedPropertyAccess, } from './response-contract-handler-calls.mjs';
+import { HTTP_METHODS, propertyName, routeTemplateFromExpression, unwrapTransparentExpression, visit, } from './response-contract-route-syntax.mjs';
+import { destructuredPropertyImplementationSymbol, propertyImplementationSymbol, } from './response-contract-object-symbols.mjs';
+export function collectHandlerBindings(sourceFiles, checker, ambiguousBindings) {
+    const bindingsBySymbol = new Map();
+    const attributionBindingsBySymbol = new Map();
+    const mutatedProperties = ambiguousBindings
+        ? findMutatedProperties(sourceFiles, checker)
+        : undefined;
+    const mutatedBindings = ambiguousBindings ? findMutatedBindings(sourceFiles, checker) : undefined;
+    for (const sourceFile of sourceFiles) {
+        visit(sourceFile, (node) => {
+            if (!ts.isCallExpression(node))
+                return;
+            const method = propertyName(node.expression)?.toUpperCase();
+            if (!method || !HTTP_METHODS.has(method))
+                return;
+            const routeTemplate = routeTemplateFromExpression(node.expression);
+            if (!routeTemplate)
+                return;
+            const binding = { method, routeTemplate };
+            for (const symbol of handlerArgumentSymbols(node, checker)) {
+                const resolved = resolveSymbol(symbol, checker);
+                const candidates = bindingsBySymbol.get(resolved) ?? [];
+                candidates.push(binding);
+                bindingsBySymbol.set(resolved, candidates);
+            }
+            if (ambiguousBindings) {
+                if (!potentiallyExecuted(node))
+                    return;
+                if (!isExportedRouteBuilder(node) && !executableProtocolPath(node, checker))
+                    return;
+                for (const symbol of handlerArgumentSymbols(node, checker, true, mutatedProperties)) {
+                    const propertySymbol = attributionSymbol(resolveSymbol(symbol, checker), checker);
+                    if (mutatedProperties?.has(propertySymbol))
+                        continue;
+                    const handlerSymbol = resolveHandlerSymbol(symbol, checker, mutatedProperties);
+                    const resolvedAttributionSymbol = attributionSymbol(handlerSymbol, checker);
+                    if (mutatedProperties?.has(resolvedAttributionSymbol))
+                        continue;
+                    if (mutatedBindings?.has(resolvedAttributionSymbol))
+                        continue;
+                    const attributionCandidates = attributionBindingsBySymbol.get(resolvedAttributionSymbol) ?? [];
+                    attributionCandidates.push(binding);
+                    attributionBindingsBySymbol.set(resolvedAttributionSymbol, attributionCandidates);
+                }
+            }
+        });
+    }
+    const bindings = new Map();
+    for (const [symbol, candidates] of bindingsBySymbol) {
+        const [first] = candidates;
+        const unambiguous = candidates.every((candidate) => candidate.method === first.method && candidate.routeTemplate === first.routeTemplate);
+        if (unambiguous) {
+            bindings.set(symbol, first);
+        }
+    }
+    if (ambiguousBindings) {
+        for (const [symbol, candidates] of attributionBindingsBySymbol) {
+            const [first] = candidates;
+            const unambiguous = candidates.every((candidate) => candidate.method === first.method && candidate.routeTemplate === first.routeTemplate);
+            if (!unambiguous) {
+                ambiguousBindings.set(symbol, [
+                    ...new Set(candidates.map(({ method, routeTemplate }) => `${method}:${routeTemplate}`)),
+                ].toSorted());
+            }
+        }
+    }
+    return bindings;
+}
+function isExportedRouteBuilder(node) {
+    let current = node.parent;
+    while (current) {
+        if (ts.isFunctionLike(current))
+            return (ts.isFunctionDeclaration(current) &&
+                !!(ts.getCombinedModifierFlags(current) &
+                    (ts.ModifierFlags.Export | ts.ModifierFlags.Default)));
+        current = current.parent;
+    }
+    return false;
+}
+function resolveHandlerSymbol(symbol, checker, mutatedProperties) {
+    const seen = new Set();
+    let current = resolveSymbol(symbol, checker);
+    while (!seen.has(current)) {
+        seen.add(current);
+        const declaration = current.valueDeclaration;
+        if (declaration && ts.isBindingElement(declaration)) {
+            const value = destructuredPropertyImplementationSymbol(declaration, checker);
+            if (!value)
+                return current;
+            current = resolveSymbol(value, checker);
+            continue;
+        }
+        if (declaration && ts.isShorthandPropertyAssignment(declaration)) {
+            const value = checker.getShorthandAssignmentValueSymbol(declaration);
+            if (!value)
+                return current;
+            current = resolveSymbol(value, checker);
+            continue;
+        }
+        if (!declaration || !ts.isVariableDeclaration(declaration) || !declaration.initializer)
+            return current;
+        if (!ts.isVariableDeclarationList(declaration.parent) ||
+            !(declaration.parent.flags & ts.NodeFlags.Const))
+            return current;
+        const initializer = unwrapTransparentExpression(declaration.initializer);
+        if (ts.isPropertyAccessExpression(initializer) &&
+            isMutatedPropertyAccess(initializer, checker, mutatedProperties))
+            return current;
+        const next = ts.isIdentifier(initializer)
+            ? checker.getSymbolAtLocation(initializer)
+            : ts.isPropertyAccessExpression(initializer)
+                ? propertyImplementationSymbol(initializer, checker)
+                : undefined;
+        if (!next)
+            return current;
+        current = resolveSymbol(next, checker);
+    }
+    return current;
+}

package/dist/api-contract-discovery/response-contract-handler-calls.d.mts

@@ -0,0 +1,3 @@
+import ts from '../contract-schema/typescript-api.mts';
+export declare function handlerArgumentSymbols(node: ts.CallExpression, checker: ts.TypeChecker, unwrapArguments?: boolean, mutatedProperties?: ReadonlySet<ts.Symbol>): ts.Symbol[];
+export declare function isMutatedPropertyAccess(expression: ts.Expression, checker: ts.TypeChecker, mutatedProperties: ReadonlySet<ts.Symbol> | undefined): boolean;

package/dist/api-contract-discovery/response-contract-handler-calls.mjs

@@ -0,0 +1,81 @@
+import ts from '../contract-schema/typescript-api.mjs';
+import { executableProtocolPath } from './protocol-execution-path.mjs';
+import { attributionSymbol, resolveSymbol } from './response-contract-symbols.mjs';
+import { propertyImplementationSymbol } from './response-contract-object-symbols.mjs';
+import { isInlineRouteHandler, unwrapTransparentExpression, } from './response-contract-route-syntax.mjs';
+export function handlerArgumentSymbols(node, checker, unwrapArguments = false, mutatedProperties) {
+    const symbols = [];
+    for (const originalArgument of node.arguments) {
+        const argument = unwrapArguments
+            ? unwrapTransparentExpression(originalArgument)
+            : originalArgument;
+        if (ts.isIdentifier(argument)) {
+            const symbol = checker.getSymbolAtLocation(argument);
+            if (symbol)
+                symbols.push(symbol);
+            continue;
+        }
+        if (unwrapArguments && ts.isPropertyAccessExpression(argument)) {
+            const mutatedSymbol = mutatedPropertyAccessSymbol(argument, checker, mutatedProperties);
+            if (mutatedSymbol) {
+                symbols.push(mutatedSymbol);
+                continue;
+            }
+            const symbol = propertyImplementationSymbol(argument, checker);
+            if (symbol)
+                symbols.push(symbol);
+            continue;
+        }
+        if (!isFunctionLike(argument))
+            continue;
+        visitHandlerCalls(argument, argument, checker, unwrapArguments, (child) => {
+            const callee = unwrapArguments
+                ? unwrapTransparentExpression(child.expression)
+                : child.expression;
+            const mutatedSymbol = mutatedPropertyAccessSymbol(callee, checker, mutatedProperties);
+            if (mutatedSymbol) {
+                symbols.push(mutatedSymbol);
+                return;
+            }
+            const symbol = handlerSymbol(callee, checker, unwrapArguments);
+            if (symbol)
+                symbols.push(symbol);
+        });
+    }
+    return symbols;
+}
+export function isMutatedPropertyAccess(expression, checker, mutatedProperties) {
+    return !!mutatedPropertyAccessSymbol(expression, checker, mutatedProperties);
+}
+function mutatedPropertyAccessSymbol(expression, checker, mutatedProperties) {
+    if (!mutatedProperties || !ts.isPropertyAccessExpression(expression))
+        return undefined;
+    const contextual = checker.getSymbolAtLocation(expression.name);
+    return contextual &&
+        mutatedProperties.has(attributionSymbol(resolveSymbol(contextual, checker), checker))
+        ? contextual
+        : undefined;
+}
+function handlerSymbol(expression, checker, resolvePropertyImplementation) {
+    if (resolvePropertyImplementation && ts.isPropertyAccessExpression(expression))
+        return propertyImplementationSymbol(expression, checker);
+    return checker.getSymbolAtLocation(expression);
+}
+function visitHandlerCalls(node, root, checker, attributeNestedCalls, onCall) {
+    if (node !== root && isInlineRouteHandler(node))
+        return;
+    const callee = ts.isCallExpression(node)
+        ? attributeNestedCalls
+            ? unwrapTransparentExpression(node.expression)
+            : node.expression
+        : undefined;
+    if (ts.isCallExpression(node) &&
+        !!callee &&
+        (ts.isIdentifier(callee) || (attributeNestedCalls && ts.isPropertyAccessExpression(callee))) &&
+        executableProtocolPath(node, checker, attributeNestedCalls ? root : undefined))
+        onCall(node);
+    ts.forEachChild(node, (child) => visitHandlerCalls(child, root, checker, attributeNestedCalls, onCall));
+}
+function isFunctionLike(node) {
+    return ts.isArrowFunction(node) || ts.isFunctionExpression(node);
+}

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

@@ -0,0 +1,2 @@
+import type { BackendResponseContract } from './response-contract-types.mts';
+export declare function nextImplicitVariantKey(contracts: Map<string, BackendResponseContract>, key: string): string;

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

@@ -0,0 +1,6 @@
+export 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-implicit.d.mts

@@ -1,5 +1,6 @@
 import ts from '../contract-schema/typescript-api.mts';
+import type { ImplicitResponseCallLabel } from './response-contract-call-classification.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;
+export declare function discoverImplicitContract(call: ts.CallExpression, checker: ts.TypeChecker, sourceFile: ts.SourceFile, contracts: Map<string, BackendResponseContract>, handlerBindings: HandlerBindings, callLabel: ImplicitResponseCallLabel | undefined, requestedKeys: ReadonlySet<string> | undefined, options: DiscoverApiResponseContractsOptions | undefined): void;

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

@@ -1,15 +1,16 @@
 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 { containsResponseMarker, noContentContract, registerContract, responseBodyExpression, sourceLocation, } from './response-contract-registration.mjs';
+import { streamingTextMediaType } from './response-contract-media.mjs';
+import { nextImplicitVariantKey } from './response-contract-implicit-variants.mjs';
 import { markBufferedRouteUnavailable, registerRouteContract, } from './response-contract-lenient.mjs';
-import { enclosingRouteBinding, isContextMethod, isContextResponseBufferCall, isContextResponseEmptyCall, requestedKeyForBinding, responseMarker, } from './response-contract-route-analysis.mjs';
+import { enclosingRouteBinding, isContextMethod, requestedKeyForBinding, responseMarker, } from './response-contract-route-analysis.mjs';
 import { resolveEmissionStatus } from './response-contract-status.mjs';
 import { opaqueHttpResponse, unsupportedContextResponse, supportedResponseContext, } from './protocol-http-association.mjs';
 import { contextResponseMethod } from './protocol-http-context.mjs';
 import { taintRouteKeys, markRouteTaint, isSseSetter } from './protocol-http-implicit-taint.mjs';
-export function discoverImplicitContract(call, checker, sourceFile, contracts, handlerBindings, requestedKeys, options) {
+export function discoverImplicitContract(call, checker, sourceFile, contracts, handlerBindings, callLabel, requestedKeys, options) {
     const opaqueResponse = opaqueHttpResponse(call, checker);
     const binding = enclosingRouteBinding(call, checker, handlerBindings, !opaqueResponse);
     if (!binding)
@@ -63,12 +64,10 @@ export function discoverImplicitContract(call, checker, sourceFile, contracts, h
         registerRouteContract(contracts, nextImplicitVariantKey(contracts, key), binding, location, emission, extract, options);
         return;
     }
-    if (isXmlResponseCall(call)) {
+    if (callLabel === 'ctx.response.xml()') {
         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',
@@ -92,8 +91,8 @@ export function discoverImplicitContract(call, checker, sourceFile, contracts, h
         return;
     }
     // Empty branches must not hide any unmarked buffer or pipeline body.
-    if (isContextResponseBufferCall(call.expression) ||
-        (isContextMethod(call.expression, 'pipeline') && !body && !containsResponseMarker(call))) {
+    if (callLabel === 'ctx.response.buffer()' ||
+        (callLabel === 'ctx.pipeline()' && !body && !containsResponseMarker(call))) {
         markBufferedRouteUnavailable(contracts, key, binding, sourceLocation(sourceFile, call));
         return;
     }
@@ -104,7 +103,7 @@ export function discoverImplicitContract(call, checker, sourceFile, contracts, h
         call.arguments[0] &&
         ts.isNumericLiteral(call.arguments[0]) &&
         (call.arguments[0].text === '204' || call.arguments[0].text === '205')) ||
-        isContextResponseEmptyCall(call.expression);
+        callLabel === 'ctx.response.empty()';
     if (isExplicitNoContentCall) {
         registerContract(contracts, contracts.has(key) ? nextImplicitVariantKey(contracts, key) : key, {
             ...noContentContract(sourceLocation(sourceFile, call)),
@@ -119,10 +118,3 @@ export function discoverImplicitContract(call, checker, sourceFile, contracts, h
         });
     }
 }
-/** 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

@@ -7,8 +7,26 @@ export type RouteDiscoveryError = {
     source: string;
     reason: string;
 };
+/**
+ * A response emitter found in a named handler registered for multiple routes. `sourceLocation`
+ * is a normalized source path followed by one-based line and column; `routes` contains unique,
+ * lexically sorted `METHOD:path` keys. `label` identifies the implicit response form.
+ */
+export type AmbiguousAttributionFact = {
+    sourceLocation: string;
+    label: string;
+    routes: readonly string[];
+};
 export type DiscoverApiResponseContractsOptions = ExtractContractSchemaOptions & {
     onRouteError?: (error: RouteDiscoveryError) => void;
+    /**
+     * Opt in to response-attribution facts from the existing discovery pass. Facts are delivered
+     * after discovery succeeds, ordered by normalized source location; each callback receives its
+     * own copy of the sorted route list. Dynamic error payloads paired with a non-literal status are
+     * excluded from these facts; discovery output keeps its existing behavior. Consumers choose
+     * whether a fact needs a diagnostic or policy.
+     */
+    onAmbiguousAttribution?: (fact: AmbiguousAttributionFact) => 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;

package/dist/api-contract-discovery/response-contract-object-symbols.d.mts

@@ -0,0 +1,3 @@
+import ts from '../contract-schema/typescript-api.mts';
+export declare function propertyImplementationSymbol(access: ts.PropertyAccessExpression, checker: ts.TypeChecker): ts.Symbol | undefined;
+export declare function destructuredPropertyImplementationSymbol(declaration: ts.BindingElement, checker: ts.TypeChecker): ts.Symbol | undefined;

package/dist/api-contract-discovery/response-contract-object-symbols.mjs

@@ -0,0 +1,80 @@
+import ts from '../contract-schema/typescript-api.mjs';
+import { unwrapTransparentExpression } from './response-contract-route-syntax.mjs';
+export function propertyImplementationSymbol(access, checker) {
+    const contextual = checker.getSymbolAtLocation(access.name);
+    const receiver = unwrapTransparentExpression(access.expression);
+    if (!contextual || !ts.isIdentifier(receiver))
+        return undefined;
+    const receiverSymbol = checker.getSymbolAtLocation(receiver);
+    const declaration = receiverSymbol?.valueDeclaration;
+    if (!declaration || !ts.isVariableDeclaration(declaration))
+        return contextual;
+    if (!declaration.initializer ||
+        !ts.isVariableDeclarationList(declaration.parent) ||
+        !(declaration.parent.flags & ts.NodeFlags.Const))
+        return undefined;
+    return constObjectPropertySymbol(receiver, access.name.text, checker);
+}
+export function destructuredPropertyImplementationSymbol(declaration, checker) {
+    const pattern = declaration.parent;
+    if (!ts.isObjectBindingPattern(pattern) || !ts.isIdentifier(declaration.name))
+        return undefined;
+    const variable = pattern.parent;
+    if (!ts.isVariableDeclaration(variable) ||
+        !variable.initializer ||
+        !ts.isVariableDeclarationList(variable.parent) ||
+        !(variable.parent.flags & ts.NodeFlags.Const))
+        return undefined;
+    if (declaration.dotDotDotToken || declaration.initializer)
+        return undefined;
+    const property = declaration.propertyName ?? declaration.name;
+    if (!ts.isIdentifier(property) && !ts.isStringLiteral(property))
+        return undefined;
+    const initializer = unwrapTransparentExpression(variable.initializer);
+    return ts.isIdentifier(initializer)
+        ? constObjectPropertySymbol(initializer, property.text, checker)
+        : undefined;
+}
+function constObjectPropertySymbol(receiver, key, checker, seen = new Set()) {
+    const receiverSymbol = checker.getSymbolAtLocation(receiver);
+    if (!receiverSymbol || seen.has(receiverSymbol))
+        return undefined;
+    seen.add(receiverSymbol);
+    const declaration = receiverSymbol.valueDeclaration;
+    if (!declaration ||
+        !ts.isVariableDeclaration(declaration) ||
+        !declaration.initializer ||
+        !ts.isVariableDeclarationList(declaration.parent) ||
+        !(declaration.parent.flags & ts.NodeFlags.Const))
+        return undefined;
+    const initializer = unwrapTransparentExpression(declaration.initializer);
+    if (ts.isIdentifier(initializer))
+        return constObjectPropertySymbol(initializer, key, checker, seen);
+    if (!ts.isObjectLiteralExpression(initializer))
+        return undefined;
+    if (initializer.properties.some(ts.isSpreadAssignment))
+        return undefined;
+    const implementation = initializer.properties.findLast((property) => {
+        const name = property.name;
+        return objectLiteralPropertyName(name) === key;
+    });
+    if (implementation && ts.isPropertyAssignment(implementation)) {
+        const value = unwrapTransparentExpression(implementation.initializer);
+        if (ts.isIdentifier(value))
+            return checker.getSymbolAtLocation(value);
+    }
+    if (implementation &&
+        (ts.isGetAccessorDeclaration(implementation) || ts.isSetAccessorDeclaration(implementation)))
+        return undefined;
+    return implementation?.name && checker.getSymbolAtLocation(implementation.name);
+}
+function objectLiteralPropertyName(name) {
+    if (ts.isIdentifier(name) || ts.isStringLiteral(name) || ts.isNumericLiteral(name))
+        return name.text;
+    if (!ts.isComputedPropertyName(name))
+        return undefined;
+    const expression = unwrapTransparentExpression(name.expression);
+    return ts.isStringLiteral(expression) || ts.isNoSubstitutionTemplateLiteral(expression)
+        ? expression.text
+        : undefined;
+}

package/dist/api-contract-discovery/response-contract-property-mutations.d.mts

@@ -0,0 +1,5 @@
+import ts from '../contract-schema/typescript-api.mts';
+/** Direct syntactic property writes are excluded; indirect mutation is outside this proof. */
+export declare function findMutatedProperties(sourceFiles: readonly ts.SourceFile[], checker: ts.TypeChecker): Set<ts.Symbol>;
+/** Direct identifier and destructuring writes are excluded; indirect writes are unproven. */
+export declare function findMutatedBindings(sourceFiles: readonly ts.SourceFile[], checker: ts.TypeChecker): Set<ts.Symbol>;

package/dist/api-contract-discovery/response-contract-property-mutations.mjs

@@ -0,0 +1,84 @@
+import ts from '../contract-schema/typescript-api.mjs';
+import { attributionSymbol, resolveSymbol } from './response-contract-symbols.mjs';
+import { unwrapTransparentExpression, visit } from './response-contract-route-syntax.mjs';
+/** Direct syntactic property writes are excluded; indirect mutation is outside this proof. */
+export function findMutatedProperties(sourceFiles, checker) {
+    const mutated = new Set();
+    for (const sourceFile of sourceFiles) {
+        visit(sourceFile, (node) => {
+            let access;
+            if (ts.isBinaryExpression(node) &&
+                node.operatorToken.kind >= ts.SyntaxKind.FirstAssignment &&
+                node.operatorToken.kind <= ts.SyntaxKind.LastAssignment &&
+                ts.isPropertyAccessExpression(unwrapTransparentExpression(node.left)))
+                access = unwrapTransparentExpression(node.left);
+            else if ((ts.isPrefixUnaryExpression(node) || ts.isPostfixUnaryExpression(node)) &&
+                (node.operator === ts.SyntaxKind.PlusPlusToken ||
+                    node.operator === ts.SyntaxKind.MinusMinusToken) &&
+                ts.isPropertyAccessExpression(node.operand))
+                access = node.operand;
+            if (!access)
+                return;
+            const symbol = checker.getSymbolAtLocation(access.name);
+            if (symbol)
+                mutated.add(attributionSymbol(resolveSymbol(symbol, checker), checker));
+        });
+    }
+    return mutated;
+}
+/** Direct identifier and destructuring writes are excluded; indirect writes are unproven. */
+export function findMutatedBindings(sourceFiles, checker) {
+    const mutated = new Set();
+    for (const sourceFile of sourceFiles) {
+        visit(sourceFile, (node) => {
+            let identifiers = [];
+            if (ts.isBinaryExpression(node) &&
+                node.operatorToken.kind >= ts.SyntaxKind.FirstAssignment &&
+                node.operatorToken.kind <= ts.SyntaxKind.LastAssignment &&
+                isAssignmentTarget(node.left))
+                identifiers = assignmentTargetIdentifiers(node.left);
+            else if ((ts.isForInStatement(node) || ts.isForOfStatement(node)) &&
+                !ts.isVariableDeclarationList(node.initializer) &&
+                isAssignmentTarget(node.initializer))
+                identifiers = assignmentTargetIdentifiers(node.initializer);
+            else if ((ts.isPrefixUnaryExpression(node) || ts.isPostfixUnaryExpression(node)) &&
+                (node.operator === ts.SyntaxKind.PlusPlusToken ||
+                    node.operator === ts.SyntaxKind.MinusMinusToken) &&
+                ts.isIdentifier(node.operand))
+                identifiers = [node.operand];
+            for (const identifier of identifiers) {
+                const symbol = checker.getSymbolAtLocation(identifier);
+                if (symbol)
+                    mutated.add(attributionSymbol(resolveSymbol(symbol, checker), checker));
+            }
+        });
+    }
+    return mutated;
+}
+function isAssignmentTarget(expression) {
+    const target = unwrapTransparentExpression(expression);
+    return (ts.isIdentifier(target) ||
+        ts.isArrayLiteralExpression(target) ||
+        ts.isObjectLiteralExpression(target));
+}
+function assignmentTargetIdentifiers(expression) {
+    const target = unwrapTransparentExpression(expression);
+    if (ts.isIdentifier(target))
+        return [target];
+    if (ts.isArrayLiteralExpression(target))
+        return target.elements.flatMap((element) => ts.isOmittedExpression(element)
+            ? []
+            : assignmentTargetIdentifiers(ts.isSpreadElement(element) ? element.expression : element));
+    if (!ts.isObjectLiteralExpression(target))
+        return [];
+    const identifiers = [];
+    for (const property of target.properties) {
+        if (ts.isShorthandPropertyAssignment(property))
+            identifiers.push(property.name);
+        else if (ts.isPropertyAssignment(property))
+            identifiers.push(...assignmentTargetIdentifiers(property.initializer));
+        else if (ts.isSpreadAssignment(property))
+            identifiers.push(...assignmentTargetIdentifiers(property.expression));
+    }
+    return identifiers;
+}

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

@@ -1,7 +1,7 @@
 import ts from '../contract-schema/typescript-api.mts';
 import type { ExtractedResponseContract, ExtractContractSchemaOptions } from '../contract-schema/index.mts';
 import type { BackendResponseContract } from './response-contract-types.mts';
-export declare function responseBodyExpression(call: ts.CallExpression): ts.Expression | undefined;
+export declare function responseBodyExpression(call: ts.CallExpression, unwrapPipelineArguments?: boolean): ts.Expression | undefined;
 export declare function containsResponseMarker(node: ts.Node): boolean;
 export declare function extractBodyContract(call: ts.CallExpression, checker: ts.TypeChecker, sourceFile: ts.SourceFile, location: string, options?: ExtractContractSchemaOptions): ExtractedResponseContract;
 export declare function registerContract(contracts: Map<string, BackendResponseContract>, key: string, contract: BackendResponseContract): void;

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

@@ -1,19 +1,23 @@
 import ts from '../contract-schema/typescript-api.mjs';
 import { extractContractSchema, hashContractSchema } from '../contract-schema/index.mjs';
 import { isContextMethod, responseMarker, visit } from './response-contract-route-analysis.mjs';
-export function responseBodyExpression(call) {
+import { unwrapTransparentExpression } from './response-contract-route-syntax.mjs';
+export function responseBodyExpression(call, unwrapPipelineArguments = false) {
     if (isContextMethod(call.expression, 'json'))
         return call.arguments[0];
     if (!isContextMethod(call.expression, 'pipeline'))
         return undefined;
-    const pipelineBody = call.arguments[0];
+    const originalBody = call.arguments[0];
+    const pipelineBody = originalBody &&
+        (unwrapPipelineArguments ? unwrapTransparentExpression(originalBody) : originalBody);
     if (!pipelineBody ||
         !ts.isCallExpression(pipelineBody) ||
         !ts.isIdentifier(pipelineBody.expression) ||
         pipelineBody.expression.text !== 'streamJsonObject') {
         return undefined;
     }
-    return pipelineBody.arguments[0];
+    const body = pipelineBody.arguments[0];
+    return body && (unwrapPipelineArguments ? unwrapTransparentExpression(body) : body);
 }
 export function containsResponseMarker(node) {
     let found = false;

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

@@ -1,17 +1,25 @@
 import ts from '../contract-schema/typescript-api.mjs';
 import { registerPlatformCompilerLibraries } from './protocol-platform-callbacks.mjs';
-import { requestedProtocolKey } from './protocol-requested-keys.mjs';
+import { protocolBindingRequested, requestedProtocolKey } from './protocol-requested-keys.mjs';
 import { discoverProtocolContracts } from './protocol-contract-registry.mjs';
 import { discoverImplicitContract } from './response-contract-implicit.mjs';
+import { ambiguousRoutesForCall } from './response-contract-attribution.mjs';
+import { sortAttributionFacts } from './response-contract-attribution-facts.mjs';
+import { implicitResponseCallLabel } from './response-contract-call-classification.mjs';
+import { collectHandlerBindings } from './response-contract-handler-bindings.mjs';
 import { registerRouteContract, } from './response-contract-lenient.mjs';
 import { binaryContentContract, contractError, extractBodyContract, noContentContract, sourceLocation, } from './response-contract-registration.mjs';
-import { collectHandlerBindings, enclosingRouteBinding, isContextMethod, responseMarker, visit, } from './response-contract-route-analysis.mjs';
+import { enclosingRouteBinding, isContextMethod, responseMarker, visit, } from './response-contract-route-analysis.mjs';
 import { resolveEmissionStatus } from './response-contract-status.mjs';
 export function discoverApiResponseContracts(program, sourceFiles, requestedKeys, options) {
     registerPlatformCompilerLibraries(program);
     const checker = program.getTypeChecker();
     const contracts = new Map();
-    const handlerBindings = collectHandlerBindings(sourceFiles, checker);
+    const ambiguousBindings = options?.onAmbiguousAttribution
+        ? new Map()
+        : undefined;
+    const handlerBindings = collectHandlerBindings(sourceFiles, checker, ambiguousBindings);
+    const attributionFacts = [];
     const protocolContracts = new Map();
     const protocolEmissions = discoverProtocolContracts(sourceFiles, checker, handlerBindings, protocolContracts, options, requestedKeys);
     for (const [key, contract] of protocolContracts) {
@@ -58,14 +66,41 @@ export function discoverApiResponseContracts(program, sourceFiles, requestedKeys
     }
     for (const sourceFile of sourceFiles) {
         visit(sourceFile, (node) => {
-            if (!ts.isCallExpression(node) ||
-                responseMarker(node.expression) ||
-                protocolEmissions.has(node))
+            if (!ts.isCallExpression(node))
+                return;
+            const callLabel = implicitResponseCallLabel(node);
+            if (options?.onAmbiguousAttribution) {
+                const attributionLabel = implicitResponseCallLabel(node, true, checker);
+                const routes = attributionLabel
+                    ? ambiguousBindings &&
+                        ambiguousRoutesForCall(node, checker, handlerBindings, ambiguousBindings)
+                    : undefined;
+                const requestedRoute = !requestedKeys ||
+                    routes?.some((route) => {
+                        const separator = route.indexOf(':');
+                        return (separator > 0 &&
+                            protocolBindingRequested({ method: route.slice(0, separator), routeTemplate: route.slice(separator + 1) }, requestedKeys));
+                    });
+                if (attributionLabel && routes && requestedRoute) {
+                    const position = sourceFile.getLineAndCharacterOfPosition(node.getStart(sourceFile));
+                    attributionFacts.push({
+                        sourceLocation: `${sourceLocation(sourceFile, node)}:${position.line + 1}:${position.character + 1}`,
+                        label: attributionLabel,
+                        routes: [...routes],
+                    });
+                }
+            }
+            if (responseMarker(node.expression) || protocolEmissions.has(node))
                 return;
-            discoverImplicitContract(node, checker, sourceFile, contracts, handlerBindings, requestedKeys, options);
+            discoverImplicitContract(node, checker, sourceFile, contracts, handlerBindings, callLabel, requestedKeys, options);
         });
     }
-    return Object.fromEntries([...contracts.entries()].toSorted(([left], [right]) => left.localeCompare(right)));
+    const result = Object.fromEntries([...contracts.entries()].toSorted(([left], [right]) => left.localeCompare(right)));
+    if (options?.onAmbiguousAttribution) {
+        for (const fact of sortAttributionFacts(attributionFacts))
+            options.onAmbiguousAttribution(fact);
+    }
+    return result;
 }
 function rawResponseMediaType(marker, node, sourceFile) {
     if (marker !== 'apiOpenApiRawResponse')

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

@@ -1,13 +1,12 @@
 import ts from '../contract-schema/typescript-api.mts';
+export { collectHandlerBindings } from './response-contract-handler-bindings.mts';
+export { propertyName, routeTemplateFromExpression, visit, } from './response-contract-route-syntax.mts';
 export { isContextMethod, isContextResponseBufferCall, isContextResponseEmptyCall, responseMarker, } from './response-contract-ctx-analysis.mts';
 export type RouteBinding = {
     method: string;
     routeTemplate: string;
 };
 export type HandlerBindings = Map<ts.Symbol, RouteBinding>;
+export type AmbiguousHandlerBindings = Map<ts.Symbol, readonly string[]>;
 export declare function requestedKeyForBinding(binding: RouteBinding, requestedKeys?: ReadonlySet<string>): string | undefined;
 export declare function enclosingRouteBinding(node: ts.Node, checker: ts.TypeChecker, handlerBindings: HandlerBindings, proveCallbacks?: boolean): RouteBinding | undefined;
-export declare function collectHandlerBindings(sourceFiles: readonly ts.SourceFile[], checker: ts.TypeChecker): HandlerBindings;
-export declare function routeTemplateFromExpression(expression: ts.Expression): string | undefined;
-export declare function propertyName(expression: ts.Expression): string | undefined;
-export declare function visit(node: ts.Node, callback: (node: ts.Node) => void): void;