vouchington-tooling 0.32.0 → 0.34.0

package/dist/api-contract-discovery/registered-route-handler-analysis.mjs

@@ -1,11 +1,19 @@
 import ts from '../contract-schema/typescript-api.mjs';
 import { returnedExpressions, returnsOnEveryPath } from './registered-route-factory-returns.mjs';
 import { runtimeParameters } from './registered-route-runtime-parameters.mjs';
+import { potentiallyExecuted } from './protocol-executable-path.mjs';
 import { hasBindingWrite } from './registered-route-binding-writes.mjs';
-export function handlerNodes(argument, checker, parameterBindings = new Map(), active = new Set(), staticProof = false, proofs) {
+import { hasStableBinding, unwrapHandlerExpression } from './registered-route-handler-helpers.mjs';
+import { isConditionalPosition } from './request-validation-conditional.mjs';
+export function handlerNodes(argument, checker, parameterBindings = new Map(), active = new Set(), staticProof = false, proofs, 
+/** Ignore `let`, `var` and reassigned bindings; always on under `staticProof`. */
+stableBindings = staticProof, 
+/** Ignore returned values on statically dead paths, and mark runtime-branch ones conditional. */
+executableReturns = false) {
+    const again = (node, bindings = parameterBindings, seen = active, sink = proofs) => handlerNodes(node, checker, bindings, seen, staticProof, sink, stableBindings, executableReturns);
     const unwrapped = unwrapHandlerExpression(argument);
     if (unwrapped !== argument)
-        return handlerNodes(unwrapped, checker, parameterBindings, active, staticProof, proofs);
+        return again(unwrapped);
     let bound = argument;
     const boundIdentifiers = new Set();
     while (ts.isIdentifier(bound)) {
@@ -19,7 +27,7 @@ export function handlerNodes(argument, checker, parameterBindings = new Map(), a
         bound = nextArgument;
     }
     if (bound !== argument)
-        return handlerNodes(bound, checker, parameterBindings, active, staticProof, proofs);
+        return again(bound);
     if (active.has(argument))
         return [];
     const next = new Set(active).add(argument);
@@ -29,7 +37,7 @@ export function handlerNodes(argument, checker, parameterBindings = new Map(), a
     }
     if (ts.isCallExpression(argument)) {
         const resolvedProofs = [];
-        const groups = callableImplementations(argument.expression, checker, staticProof).map((implementation) => {
+        const groups = callableImplementations(argument.expression, checker, staticProof, stableBindings).map((implementation) => {
             if (staticProof &&
                 (implementation.asteriskToken ||
                     implementation.modifiers?.some((modifier) => modifier.kind === ts.SyntaxKind.AsyncKeyword) ||
@@ -42,11 +50,18 @@ export function handlerNodes(argument, checker, parameterBindings = new Map(), a
                 if (callArgument && symbol)
                     bindings.set(symbol, callArgument);
             });
-            const returned = returnedExpressions(implementation);
+            const returned = returnedExpressions(implementation).filter((value) => !executableReturns || !value || potentiallyExecuted(value));
             if (staticProof &&
                 (!returnsOnEveryPath(implementation.body) || returned.some((value) => !value)))
                 return [];
-            const results = returned.map((value) => value ? handlerNodes(value, checker, bindings, next, staticProof, resolvedProofs) : []);
+            const results = returned.map((value) => {
+                const selected = [];
+                const found = value ? again(value, bindings, next, selected) : [];
+                if (executableReturns && value && isConditionalPosition(value))
+                    selected.forEach((proof) => (proof.conditional = true));
+                resolvedProofs.push(...selected);
+                return found;
+            });
             return staticProof && results.some((result) => !result.some(ts.isFunctionLike))
                 ? []
                 : results.flat();
@@ -56,16 +71,16 @@ export function handlerNodes(argument, checker, parameterBindings = new Map(), a
         proofs?.push(...resolvedProofs);
         return groups.flat();
     }
-    return declarationImplementations(argument, checker, next, staticProof, parameterBindings, proofs);
+    return declarationImplementations(argument, checker, next, staticProof, parameterBindings, proofs, stableBindings, executableReturns);
 }
-function callableImplementations(node, checker, staticProof = false) {
+function callableImplementations(node, checker, staticProof = false, stableBindings = staticProof) {
     const symbol = checker.getSymbolAtLocation(node);
     if (!symbol)
         return [];
     const resolved = symbol.flags & ts.SymbolFlags.Alias ? checker.getAliasedSymbol(symbol) : symbol;
     const implementations = [];
     for (const declaration of resolved.declarations ?? []) {
-        if (staticProof && !hasStableBinding(declaration, checker))
+        if (stableBindings && !hasStableBinding(declaration, checker))
             continue;
         if (ts.isVariableDeclaration(declaration) && declaration.initializer) {
             const initializer = unwrapHandlerExpression(declaration.initializer);
@@ -80,13 +95,13 @@ function callableImplementations(node, checker, staticProof = false) {
     }
     return implementations;
 }
-function declarationImplementations(node, checker, active, staticProof, parameterBindings, proofs) {
+function declarationImplementations(node, checker, active, staticProof, parameterBindings, proofs, stableBindings = staticProof, executableReturns = false) {
     const symbol = checker.getSymbolAtLocation(node);
     if (!symbol)
         return [];
     const resolved = symbol.flags & ts.SymbolFlags.Alias ? checker.getAliasedSymbol(symbol) : symbol;
     return (resolved.declarations ?? []).flatMap((declaration) => {
-        if (staticProof && !hasStableBinding(declaration, checker))
+        if (stableBindings && !hasStableBinding(declaration, checker))
             return [];
         if (ts.isFunctionDeclaration(declaration) ||
             (!staticProof && ts.isMethodDeclaration(declaration))) {
@@ -97,22 +112,8 @@ function declarationImplementations(node, checker, active, staticProof, paramete
         if (ts.isVariableDeclaration(declaration) && declaration.initializer)
             return [
                 declaration,
-                ...handlerNodes(declaration.initializer, checker, parameterBindings, active, staticProof, proofs),
+                ...handlerNodes(declaration.initializer, checker, parameterBindings, active, staticProof, proofs, stableBindings, executableReturns),
             ];
         return [];
     });
 }
-function hasStableBinding(declaration, checker) {
-    if (ts.isVariableDeclaration(declaration))
-        return (ts.isVariableDeclarationList(declaration.parent) &&
-            !!(declaration.parent.flags & ts.NodeFlags.Const));
-    return !ts.isFunctionDeclaration(declaration) || !hasBindingWrite(declaration, checker);
-}
-function unwrapHandlerExpression(node) {
-    while (ts.isParenthesizedExpression(node) ||
-        ts.isAsExpression(node) ||
-        ts.isTypeAssertionExpression(node) ||
-        ts.isSatisfiesExpression(node))
-        node = node.expression;
-    return node;
-}

package/dist/api-contract-discovery/registered-route-handler-helpers.d.mts

@@ -0,0 +1,3 @@
+import ts from '../contract-schema/typescript-api.mts';
+export declare function hasStableBinding(declaration: ts.Declaration, checker: ts.TypeChecker): boolean;
+export declare function unwrapHandlerExpression(node: ts.Expression): ts.Expression;

package/dist/api-contract-discovery/registered-route-handler-helpers.mjs

@@ -0,0 +1,16 @@
+import ts from '../contract-schema/typescript-api.mjs';
+import { hasBindingWrite } from './registered-route-binding-writes.mjs';
+export function hasStableBinding(declaration, checker) {
+    if (ts.isVariableDeclaration(declaration))
+        return (ts.isVariableDeclarationList(declaration.parent) &&
+            !!(declaration.parent.flags & ts.NodeFlags.Const));
+    return !ts.isFunctionDeclaration(declaration) || !hasBindingWrite(declaration, checker);
+}
+export function unwrapHandlerExpression(node) {
+    while (ts.isParenthesizedExpression(node) ||
+        ts.isAsExpression(node) ||
+        ts.isTypeAssertionExpression(node) ||
+        ts.isSatisfiesExpression(node))
+        node = node.expression;
+    return node;
+}

package/dist/api-contract-discovery/request-validation-callbacks.d.mts

@@ -0,0 +1,9 @@
+import ts from '../contract-schema/typescript-api.mts';
+import type { ExecutedCallbackConfig } from './request-validation-types.mts';
+/** The listed inline callback properties of a configured executed-callback host call. */
+export declare function executedCallbackFunctions(call: ts.CallExpression, hosts: readonly ExecutedCallbackConfig[], checker: ts.TypeChecker): ts.FunctionLikeDeclaration[];
+/**
+ * True when some invocation of a callback runs it straight from a function the call enters, outside
+ * any condition. Invocations elsewhere, such as in nested helpers, are treated as conditional.
+ */
+export declare function invokedUnconditionally(callers: readonly ts.CallExpression[], runners: ReadonlySet<ts.Node>): boolean;

package/dist/api-contract-discovery/request-validation-callbacks.mjs

@@ -0,0 +1,27 @@
+import ts from '../contract-schema/typescript-api.mjs';
+import { enclosingFunction } from './protocol-marker-analysis.mjs';
+import { isConditionalPosition } from './request-validation-conditional.mjs';
+import { inlineFunction } from './request-validation-follow.mjs';
+import { propertyNameText } from './request-validation-keys.mjs';
+import { findConfig } from './request-validation-match.mjs';
+import { unwrapTransparentExpression } from './response-contract-route-syntax.mjs';
+/** The listed inline callback properties of a configured executed-callback host call. */
+export function executedCallbackFunctions(call, hosts, checker) {
+    const host = findConfig(call.expression, hosts, checker);
+    const argument = host && call.arguments[host.argument];
+    const object = argument && unwrapTransparentExpression(argument);
+    if (!host || !object || !ts.isObjectLiteralExpression(object))
+        return [];
+    return object.properties.flatMap((property) => {
+        const name = propertyNameText(property.name);
+        const callback = inlineFunction(ts.isPropertyAssignment(property) ? property.initializer : property);
+        return name !== undefined && host.properties.includes(name) && callback ? [callback] : [];
+    });
+}
+/**
+ * True when some invocation of a callback runs it straight from a function the call enters, outside
+ * any condition. Invocations elsewhere, such as in nested helpers, are treated as conditional.
+ */
+export function invokedUnconditionally(callers, runners) {
+    return callers.some((caller) => !isConditionalPosition(caller) && runners.has(enclosingFunction(caller)));
+}

package/dist/api-contract-discovery/request-validation-checker.d.mts

@@ -0,0 +1,7 @@
+import ts from '../contract-schema/typescript-api.mts';
+/**
+ * A checker whose symbol lookups are memoized for one analysis run. The walker resolves the same
+ * identifiers and aliases for every route that reaches a shared helper; the program is immutable,
+ * so the answers cannot change. The cache dies with the returned object.
+ */
+export declare function memoizeCheckerSymbols(checker: ts.TypeChecker): ts.TypeChecker;

package/dist/api-contract-discovery/request-validation-checker.mjs

@@ -0,0 +1,25 @@
+import ts from '../contract-schema/typescript-api.mjs';
+/** A cached lookup keyed by node or symbol; `undefined` results are cached too. */
+function memoize(lookup) {
+    const cache = new Map();
+    return (key) => {
+        if (cache.has(key))
+            return cache.get(key);
+        const value = lookup(key);
+        cache.set(key, value);
+        return value;
+    };
+}
+/**
+ * A checker whose symbol lookups are memoized for one analysis run. The walker resolves the same
+ * identifiers and aliases for every route that reaches a shared helper; the program is immutable,
+ * so the answers cannot change. The cache dies with the returned object.
+ */
+export function memoizeCheckerSymbols(checker) {
+    return {
+        ...checker,
+        getSymbolAtLocation: memoize((node) => checker.getSymbolAtLocation(node)),
+        getShorthandAssignmentValueSymbol: memoize((node) => checker.getShorthandAssignmentValueSymbol(node)),
+        getAliasedSymbol: memoize((symbol) => checker.getAliasedSymbol(symbol)),
+    };
+}

package/dist/api-contract-discovery/request-validation-conditional.d.mts

@@ -0,0 +1,6 @@
+import ts from '../contract-schema/typescript-api.mts';
+/**
+ * True when, within its own function, the node runs only under an `if` or ternary branch, the
+ * right side of `&&`, `||` or `??`, a `switch` case, a loop body, a `catch` or a `finally`. Early returns are not modeled.
+ */
+export declare function isConditionalPosition(node: ts.Node): boolean;

package/dist/api-contract-discovery/request-validation-conditional.mjs

@@ -0,0 +1,31 @@
+import ts from '../contract-schema/typescript-api.mjs';
+const SHORT_CIRCUIT = new Set([
+    ts.SyntaxKind.AmpersandAmpersandToken,
+    ts.SyntaxKind.BarBarToken,
+    ts.SyntaxKind.QuestionQuestionToken,
+]);
+/**
+ * True when, within its own function, the node runs only under an `if` or ternary branch, the
+ * right side of `&&`, `||` or `??`, a `switch` case, a loop body, a `catch` or a `finally`. Early returns are not modeled.
+ */
+export function isConditionalPosition(node) {
+    let child = node;
+    for (let parent = node.parent; parent && !ts.isFunctionLike(parent); parent = parent.parent) {
+        if (ts.isIfStatement(parent) && child !== parent.expression)
+            return true;
+        if (ts.isConditionalExpression(parent) && child !== parent.condition)
+            return true;
+        if (ts.isBinaryExpression(parent) &&
+            child === parent.right &&
+            SHORT_CIRCUIT.has(parent.operatorToken.kind))
+            return true;
+        if (ts.isCaseOrDefaultClause(parent) || ts.isCatchClause(parent))
+            return true;
+        if (ts.isIterationStatement(parent, false) && child === parent.statement)
+            return true;
+        if (ts.isTryStatement(parent) && child === parent.finallyBlock)
+            return true;
+        child = parent;
+    }
+    return false;
+}

package/dist/api-contract-discovery/request-validation-factory-calls.d.mts

@@ -0,0 +1,11 @@
+import ts from '../contract-schema/typescript-api.mts';
+import type { FactoryConfig } from './request-validation-types.mts';
+/**
+ * The configured factory call that built the handler a call invokes: the callee resolves to a
+ * `const` binding initialized by that factory call, as in `const handler = createHandler({...})`
+ * followed by `handler(ctx)`.
+ */
+export declare function calledFactory(call: ts.CallExpression, factories: readonly FactoryConfig[], checker: ts.TypeChecker): {
+    call: ts.CallExpression;
+    config: FactoryConfig;
+} | undefined;

package/dist/api-contract-discovery/request-validation-factory-calls.mjs

@@ -0,0 +1,23 @@
+import ts from '../contract-schema/typescript-api.mjs';
+import { calleeSymbol, findConfig } from './request-validation-match.mjs';
+import { unwrapTransparentExpression } from './response-contract-route-syntax.mjs';
+/**
+ * The configured factory call that built the handler a call invokes: the callee resolves to a
+ * `const` binding initialized by that factory call, as in `const handler = createHandler({...})`
+ * followed by `handler(ctx)`.
+ */
+export function calledFactory(call, factories, checker) {
+    for (const declaration of calleeSymbol(call.expression, checker)?.declarations ?? []) {
+        if (!ts.isVariableDeclaration(declaration) || !declaration.initializer)
+            continue;
+        if (!(ts.getCombinedNodeFlags(declaration) & ts.NodeFlags.Const))
+            continue;
+        const built = unwrapTransparentExpression(declaration.initializer);
+        if (!ts.isCallExpression(built))
+            continue;
+        const config = findConfig(built.expression, factories, checker);
+        if (config)
+            return { call: built, config };
+    }
+    return undefined;
+}

package/dist/api-contract-discovery/request-validation-facts.d.mts

@@ -0,0 +1,16 @@
+import ts from '../contract-schema/typescript-api.mts';
+import type { ExecutedCallbackConfig, FactoryConfig, RouteValidationFacts, ValidatorConfig } from './request-validation-types.mts';
+export type RequestValidationFactsInput = {
+    program: ts.Program;
+    sourceFiles: readonly ts.SourceFile[];
+    validators: readonly ValidatorConfig[];
+    factories?: readonly FactoryConfig[];
+    /** Configured calls that always run the listed inline callback properties. */
+    executedCallbacks?: readonly ExecutedCallbackConfig[];
+};
+/**
+ * Reports, per registered route, the configured validator and factory calls its handlers reach,
+ * the operation key and carriers each covers, and the raw request carriers the handlers read.
+ * Facts only: which routes must validate, and what counts as covered, stays with the caller.
+ */
+export declare function discoverRequestValidationFacts(input: RequestValidationFactsInput): Record<string, RouteValidationFacts>;

package/dist/api-contract-discovery/request-validation-facts.mjs

@@ -0,0 +1,64 @@
+import ts from '../contract-schema/typescript-api.mjs';
+import { memoizeCheckerSymbols } from './request-validation-checker.mjs';
+import { createProtocolCache } from './protocol-analysis-cache.mjs';
+import { discoverRegisteredRoutes } from './registered-route-catalog.mjs';
+import { handlerNodes } from './registered-route-handler-analysis.mjs';
+import { insideConfiguredImplementation } from './request-validation-match.mjs';
+import { sourceOf } from './request-validation-sites.mjs';
+import { createRouteWalker } from './request-validation-walker.mjs';
+import { HTTP_METHODS, propertyName, routeTemplateFromExpression, visit, } from './response-contract-route-syntax.mjs';
+/** Maps each route's `source:method:template` identity to its registration call. */
+function registrationCalls(sourceFiles) {
+    const calls = new Map();
+    for (const sourceFile of sourceFiles)
+        visit(sourceFile, (node) => {
+            if (!ts.isCallExpression(node))
+                return;
+            const method = propertyName(node.expression)?.toUpperCase();
+            const template = routeTemplateFromExpression(node.expression);
+            if (method && HTTP_METHODS.has(method) && template)
+                calls.set(`${sourceOf(node)}|${method}:${template}`, node);
+        });
+    return calls;
+}
+/**
+ * Reports, per registered route, the configured validator and factory calls its handlers reach,
+ * the operation key and carriers each covers, and the raw request carriers the handlers read.
+ * Facts only: which routes must validate, and what counts as covered, stays with the caller.
+ */
+export function discoverRequestValidationFacts(input) {
+    const { program, sourceFiles, validators, factories = [], executedCallbacks = [] } = input;
+    const checker = memoizeCheckerSymbols(program.getTypeChecker());
+    const registrations = registrationCalls(sourceFiles);
+    const sourceFileSet = new Set(sourceFiles);
+    const protocolCache = createProtocolCache();
+    const result = {};
+    for (const route of discoverRegisteredRoutes(program, sourceFiles)) {
+        // Same call-selection logic as route discovery, so every discovered route has a registration.
+        const registration = registrations.get(`${route.source}|${route.method}:${route.routeTemplate}`);
+        const walker = createRouteWalker({
+            checker,
+            sourceFiles: sourceFileSet,
+            protocolCache,
+            validators,
+            factories,
+            executedCallbacks,
+        });
+        for (const argument of registration.arguments.filter((item) => !ts.isStringLiteral(item))) {
+            const proofs = [];
+            const nodes = handlerNodes(argument, checker, new Map(), new Set(), false, proofs, true, true);
+            walker.scanRegistration(argument);
+            for (const declaration of nodes.filter(ts.isVariableDeclaration))
+                walker.scanRegistration(declaration);
+            for (const proof of proofs)
+                if (!insideConfiguredImplementation(proof.node, [...validators, ...factories, ...executedCallbacks], checker))
+                    walker.walkHandler(proof);
+        }
+        result[`${route.method}:${route.routeTemplate}`] = {
+            kind: route.kind,
+            source: route.source,
+            ...walker.facts,
+        };
+    }
+    return result;
+}

package/dist/api-contract-discovery/request-validation-follow.d.mts

@@ -0,0 +1,24 @@
+import ts from '../contract-schema/typescript-api.mts';
+import type { ProtocolCache } from './protocol-analysis-cache.mts';
+import type { KeyBindings } from './request-validation-keys.mts';
+import type { RootBindings } from './request-validation-origin.mts';
+type ExportRef = {
+    module: string;
+    exportName: string;
+};
+/** Everything needed to resolve keys, origins and followed helpers at one program point. */
+export type Scope = {
+    checker: ts.TypeChecker;
+    sourceFiles: ReadonlySet<ts.SourceFile>;
+    /** Configured validators, factories and callback hosts, whose bodies are never entered. */
+    configured: readonly ExportRef[];
+    roots: RootBindings;
+    keys: KeyBindings;
+    /** Memoized proofs shared across one facts run. */
+    cache?: ProtocolCache | undefined;
+};
+export type Followable = ts.FunctionDeclaration | ts.ArrowFunction | ts.FunctionExpression;
+/** Function declarations and const function expressions in `sourceFiles` that a call runs. */
+export declare function followedImplementations(call: ts.CallExpression, scope: Scope): Followable[];
+export declare const inlineFunction: (node: ts.Node | undefined) => ts.ArrowFunction | ts.FunctionExpression | ts.MethodDeclaration | undefined;
+export {};

package/dist/api-contract-discovery/request-validation-follow.mjs

@@ -0,0 +1,38 @@
+import ts from '../contract-schema/typescript-api.mjs';
+import { findConfig, calleeSymbol } from './request-validation-match.mjs';
+import { unwrapTransparentExpression } from './response-contract-route-syntax.mjs';
+function constFunction(declaration) {
+    const { initializer } = declaration;
+    return initializer && ts.getCombinedNodeFlags(declaration) & ts.NodeFlags.Const
+        ? unwrapTransparentExpression(initializer)
+        : undefined;
+}
+/** Function declarations and const function expressions in `sourceFiles` that a call runs. */
+export function followedImplementations(call, scope) {
+    if (findConfig(call.expression, scope.configured, scope.checker))
+        return [];
+    const declarations = calleeSymbol(call.expression, scope.checker)?.declarations ?? [];
+    return declarations.flatMap((declaration) => {
+        if (!scope.sourceFiles.has(declaration.getSourceFile()))
+            return [];
+        const implementation = ts.isVariableDeclaration(declaration)
+            ? constFunction(declaration)
+            : declaration;
+        return implementation &&
+            (ts.isFunctionDeclaration(implementation) ||
+                ts.isFunctionExpression(implementation) ||
+                ts.isArrowFunction(implementation)) &&
+            implementation.body &&
+            // Calling a generator only creates an iterator; its body does not run.
+            !implementation.asteriskToken
+            ? [implementation]
+            : [];
+    });
+}
+export const inlineFunction = (node) => {
+    const value = node && ts.isExpression(node) ? unwrapTransparentExpression(node) : node;
+    return value &&
+        (ts.isArrowFunction(value) || ts.isFunctionExpression(value) || ts.isMethodDeclaration(value))
+        ? value
+        : undefined;
+};

package/dist/api-contract-discovery/request-validation-handler-state.d.mts

@@ -0,0 +1,8 @@
+import ts from '../contract-schema/typescript-api.mts';
+import type { HandlerProof } from './registered-route-handler-analysis.mts';
+import { type Bound } from './request-validation-origin.mts';
+/** Static keys bound by the proof (each resolved against the earlier ones), and the handler's own context parameter as the root. */
+export declare function handlerBindings(proof: HandlerProof, checker: ts.TypeChecker): {
+    keys: Map<ts.Symbol, string>;
+    roots: Map<ts.Symbol, Bound>;
+};

package/dist/api-contract-discovery/request-validation-handler-state.mjs

@@ -0,0 +1,35 @@
+import ts from '../contract-schema/typescript-api.mjs';
+import { runtimeParameters } from './registered-route-runtime-parameters.mjs';
+import { resolveKey } from './request-validation-keys.mjs';
+import { memberKind } from './request-validation-origin.mjs';
+/** Binds a context parameter, or each destructured member of it, to the carrier it denotes. */
+function bindContext(name, kind, checker, roots) {
+    if (ts.isIdentifier(name)) {
+        roots.set(checker.getSymbolAtLocation(name), { kind, origins: [] });
+        return;
+    }
+    if (!ts.isObjectBindingPattern(name))
+        return;
+    for (const element of name.elements) {
+        const key = element.propertyName ?? element.name;
+        const member = !element.dotDotDotToken && (ts.isIdentifier(key) || ts.isStringLiteral(key))
+            ? memberKind(kind, key.text)
+            : undefined;
+        if (member)
+            bindContext(element.name, member, checker, roots);
+    }
+}
+/** Static keys bound by the proof (each resolved against the earlier ones), and the handler's own context parameter as the root. */
+export function handlerBindings(proof, checker) {
+    const keys = new Map();
+    for (const [symbol, expression] of proof.bindings) {
+        const key = resolveKey(expression, checker, keys);
+        if (key !== undefined)
+            keys.set(symbol, key);
+    }
+    const roots = new Map();
+    const context = runtimeParameters(proof.node)[0]?.name;
+    if (context)
+        bindContext(context, 'context', checker, roots);
+    return { keys, roots };
+}

package/dist/api-contract-discovery/request-validation-input.d.mts

@@ -0,0 +1,12 @@
+import ts from '../contract-schema/typescript-api.mts';
+import type { Scope } from './request-validation-follow.mts';
+import { type ValidatorSite } from './request-validation-types.mts';
+export type InputResolution = {
+    carriers: ValidatorSite['carriers'];
+    /** Why the input object is not fully resolved; the carriers listed may then be incomplete. */
+    unresolved?: string;
+    /** Expressions that construct the validated input, whose request reads are not raw reads. */
+    nodes: ts.Node[];
+};
+/** Resolves the object a validator receives as input, through const objects and spreads. */
+export declare function resolveInput(input: ts.Expression | undefined, scope: Scope): InputResolution;

package/dist/api-contract-discovery/request-validation-input.mjs

@@ -0,0 +1,43 @@
+import ts from '../contract-schema/typescript-api.mjs';
+import { propertyNameText, resolveObject } from './request-validation-keys.mjs';
+import { traceValue } from './request-validation-trace.mjs';
+import { CARRIERS } from './request-validation-types.mjs';
+/** Applies the object's properties in order, so later properties and spreads win. */
+function collect(object, scope, found, seen) {
+    found.nodes.push(object);
+    for (const property of object.properties) {
+        if (ts.isSpreadAssignment(property)) {
+            const spread = resolveObject(property.expression, scope.checker, scope.roots);
+            if (spread && !seen.has(spread))
+                collect(spread, scope, found, new Set(seen).add(spread));
+            else
+                found.unresolved ??= `spread \`${property.expression.getText()}\` is not statically resolvable`;
+        }
+        else if (property.name && ts.isComputedPropertyName(property.name)) {
+            found.unresolved ??= 'a computed property name is not statically resolvable';
+        }
+        else if (ts.isPropertyAssignment(property) || ts.isShorthandPropertyAssignment(property)) {
+            const carrier = CARRIERS.find((item) => item === propertyNameText(property.name));
+            if (carrier)
+                found.entries.set(carrier, ts.isPropertyAssignment(property) ? property.initializer : property.name);
+        }
+    }
+}
+/** Resolves the object a validator receives as input, through const objects and spreads. */
+export function resolveInput(input, scope) {
+    const found = { entries: new Map(), nodes: input ? [input] : [] };
+    const object = resolveObject(input, scope.checker, scope.roots);
+    if (object)
+        collect(object, scope, found, new Set([object]));
+    else if (input)
+        found.unresolved = `input \`${input.getText()}\` is not statically resolvable`;
+    const carriers = [...found.entries].map(([carrier, value]) => {
+        const { origins, unresolved } = traceValue(value, scope);
+        return {
+            carrier,
+            origins: CARRIERS.filter((candidate) => origins.has(candidate)),
+            ...(unresolved && { unresolved }),
+        };
+    });
+    return { carriers, ...(found.unresolved && { unresolved: found.unresolved }), nodes: found.nodes };
+}

package/dist/api-contract-discovery/request-validation-keys.d.mts

@@ -0,0 +1,25 @@
+import ts from '../contract-schema/typescript-api.mts';
+/** Static string values bound to helper or factory parameters. */
+export type KeyBindings = ReadonlyMap<ts.Symbol, string>;
+/** A property name written as an identifier or string literal; computed names are `undefined`. */
+export declare const propertyNameText: (name: ts.PropertyName | undefined) => string | undefined;
+/** The variable symbol an identifier reads, including a shorthand property's value. */
+export declare function identifierSymbol(identifier: ts.Identifier, checker: ts.TypeChecker): ts.Symbol | undefined;
+/** The const initializer an identifier names, unless a property of it is written before the use. */
+export declare function stableConstInitializer(identifier: ts.Identifier, checker: ts.TypeChecker): ts.Expression | undefined;
+/** Resolves string literals, templates, const identifiers and bound parameters, else `undefined`. */
+export declare function resolveKey(expression: ts.Expression | undefined, checker: ts.TypeChecker, bindings: KeyBindings, seen?: Set<ts.Node>): string | undefined;
+/** Call-site bindings of parameters; an `expression` is the argument the call passes. */
+export type ParamBindings = ReadonlyMap<ts.Symbol, {
+    expression?: ts.Expression | undefined;
+}>;
+/** The object literal an expression denotes, through const identifiers and bound parameters. */
+export declare function resolveObject(expression: ts.Expression | undefined, checker: ts.TypeChecker, params?: ParamBindings, seen?: Set<ts.Node>): ts.ObjectLiteralExpression | undefined;
+export declare const ABSENT: unique symbol;
+/** `undefined` means the property cannot be statically resolved. */
+type Found = ts.Expression | undefined | typeof ABSENT;
+/** The value expression a property ends with, applying properties and spreads in order. */
+export declare function findProperty(object: ts.ObjectLiteralExpression, name: string, checker: ts.TypeChecker, params: ParamBindings, seen: Set<ts.Node>): Found;
+/** Resolves a string property of an options object, including from spread const objects. */
+export declare function resolveOptionString(expression: ts.Expression | undefined, name: string, checker: ts.TypeChecker, bindings: KeyBindings, params?: ParamBindings): string | undefined;
+export {};