vouchington-tooling 0.29.0 → 0.31.0

package/dist/api-contract-discovery/protocol-platform-mutation-targets.mjs

@@ -0,0 +1,89 @@
+import { basename, dirname, resolve as resolvePath } from 'node:path';
+import ts from '../contract-schema/typescript-api.mjs';
+import { unwrapExpression } from './protocol-marker-analysis.mjs';
+const standardLibrary = dirname(resolvePath(ts.getDefaultLibFilePath({})));
+function isStandardDeclaration(declaration, libraries) {
+    const source = declaration.getSourceFile();
+    const file = resolvePath(source.fileName);
+    return libraries
+        ? libraries.has(source)
+        : source.isDeclarationFile &&
+            dirname(file) === standardLibrary &&
+            /^lib(?:\.[\w.-]+)?\.d\.ts$/.test(basename(file));
+}
+export function literalStrings(expression, checker) {
+    if (!expression)
+        return undefined;
+    const strings = new Set();
+    function visit(type) {
+        if (type.isUnion())
+            return type.types.every(visit);
+        if (type.flags & ts.TypeFlags.StringLiteral) {
+            strings.add(type.value);
+            return true;
+        }
+        if (type.flags &
+            (ts.TypeFlags.String | ts.TypeFlags.Any | ts.TypeFlags.Unknown | ts.TypeFlags.TypeParameter))
+            return false;
+        return true;
+    }
+    return visit(checker.getTypeAtLocation(expression)) ? [...strings] : undefined;
+}
+export function globalTarget(expression, checker, seen = new Set()) {
+    const value = unwrapExpression(expression);
+    if (!ts.isIdentifier(value))
+        return undefined;
+    const symbol = checker.getSymbolAtLocation(value);
+    if (!symbol || seen.has(symbol))
+        return undefined;
+    seen.add(symbol);
+    if (value.text === 'globalThis')
+        return symbol.declarations?.length ? undefined : value;
+    if (symbol.name === 'global' &&
+        symbol.declarations?.some((declaration) => {
+            const source = declaration.getSourceFile();
+            return (ts.isVariableDeclaration(declaration) &&
+                source.isDeclarationFile &&
+                resolvePath(source.fileName)
+                    .replaceAll('\\', '/')
+                    .endsWith('/node_modules/@types/node/globals.d.ts'));
+        }))
+        return value;
+    const declaration = symbol.valueDeclaration;
+    return declaration && ts.isVariableDeclaration(declaration) && declaration.initializer
+        ? globalTarget(declaration.initializer, checker, seen)
+        : undefined;
+}
+export function mutatorKind(call, checker, libraries) {
+    const callee = call.expression;
+    if (!ts.isPropertyAccessExpression(callee) || !ts.isIdentifier(callee.expression))
+        return undefined;
+    const owner = callee.expression.text;
+    const method = callee.name.text;
+    if (!((owner === 'Object' && ['defineProperty', 'assign'].includes(method)) ||
+        (owner === 'Reflect' && method === 'set')))
+        return undefined;
+    const ownerSymbol = checker.getSymbolAtLocation(callee.expression);
+    const methodSymbol = checker.getSymbolAtLocation(callee.name);
+    if (!ownerSymbol?.declarations?.length ||
+        !methodSymbol?.declarations?.length ||
+        !ownerSymbol.declarations.every((declaration) => isStandardDeclaration(declaration, libraries)) ||
+        !methodSymbol.declarations.every((declaration) => isStandardDeclaration(declaration, libraries)))
+        return undefined;
+    return method;
+}
+export function sourceKeys(source, checker) {
+    const keys = new Set();
+    function visit(type) {
+        if (type.flags & (ts.TypeFlags.Any | ts.TypeFlags.Unknown | ts.TypeFlags.TypeParameter))
+            return false;
+        if (type.isUnion())
+            return type.types.every(visit);
+        if (type.getStringIndexType())
+            return false;
+        for (const property of type.getProperties())
+            keys.add(property.name);
+        return true;
+    }
+    return visit(checker.getTypeAtLocation(unwrapExpression(source))) ? [...keys] : undefined;
+}

package/dist/api-contract-discovery/protocol-platform-writes.d.mts

@@ -0,0 +1,3 @@
+import ts from '../contract-schema/typescript-api.mts';
+/** Records global timer and Promise writes, including calls to standard property mutators. */
+export declare function writtenPlatformSymbols(files: readonly ts.SourceFile[], checker: ts.TypeChecker, libraries?: ReadonlySet<ts.SourceFile>): Set<ts.Symbol>;

package/dist/api-contract-discovery/protocol-platform-writes.mjs

@@ -0,0 +1,92 @@
+import ts from '../contract-schema/typescript-api.mjs';
+import { unwrapExpression } from './protocol-marker-analysis.mjs';
+import { globalTarget, literalStrings, mutatorKind, sourceKeys, } from './protocol-platform-mutation-targets.mjs';
+const platformNames = ['setTimeout', 'setInterval', 'Promise'];
+/** Records global timer and Promise writes, including calls to standard property mutators. */
+export function writtenPlatformSymbols(files, checker, libraries) {
+    const written = new Set();
+    function mark(target, keys) {
+        const root = globalTarget(target, checker);
+        if (!root)
+            return;
+        const members = keys
+            ? keys.map((key) => checker.getPropertyOfType(checker.getTypeAtLocation(root), key))
+            : platformNames.map((name) => checker.getPropertyOfType(checker.getTypeAtLocation(root), name));
+        for (const member of members)
+            if (member && platformNames.includes(member.name))
+                written.add(member);
+    }
+    function target(node) {
+        if (ts.isElementAccessExpression(node)) {
+            const keys = literalStrings(node.argumentExpression, checker);
+            mark(node.expression, keys);
+            return;
+        }
+        if (ts.isPropertyAccessExpression(node)) {
+            const symbol = checker.getSymbolAtLocation(node.name);
+            if (globalTarget(node.expression, checker) && symbol && platformNames.includes(symbol.name))
+                written.add(symbol);
+            return;
+        }
+        const symbol = checker.getSymbolAtLocation(node);
+        if (symbol && platformNames.includes(symbol.name))
+            written.add(symbol);
+        if (ts.isObjectLiteralExpression(node) ||
+            ts.isArrayLiteralExpression(node) ||
+            ts.isPropertyAssignment(node) ||
+            ts.isSpreadAssignment(node) ||
+            ts.isSpreadElement(node))
+            ts.forEachChild(node, target);
+    }
+    function visit(node) {
+        if (ts.isBinaryExpression(node) &&
+            node.operatorToken.kind >= ts.SyntaxKind.FirstAssignment &&
+            node.operatorToken.kind <= ts.SyntaxKind.LastAssignment)
+            target(node.left);
+        if (ts.isDeleteExpression(node))
+            target(node.expression);
+        if (ts.isCallExpression(node)) {
+            const kind = mutatorKind(node, checker, libraries);
+            if (kind && node.arguments[0] && ts.isSpreadElement(node.arguments[0]))
+                for (const file of files)
+                    for (const binding of checker.getSymbolsInScope(file, ts.SymbolFlags.Value | ts.SymbolFlags.Alias)) {
+                        const symbol = binding.flags & ts.SymbolFlags.Alias ? checker.getAliasedSymbol(binding) : binding;
+                        if (platformNames.includes(symbol.name))
+                            written.add(symbol);
+                    }
+            if (kind === 'defineProperty' || kind === 'set') {
+                const receiver = node.arguments[0];
+                if (receiver && !ts.isSpreadElement(receiver))
+                    mark(receiver, literalStrings(node.arguments[1] && !ts.isSpreadElement(node.arguments[1])
+                        ? node.arguments[1]
+                        : undefined, checker));
+            }
+            else if (kind === 'assign') {
+                const receiver = node.arguments[0];
+                if (receiver && !ts.isSpreadElement(receiver) && globalTarget(receiver, checker)) {
+                    for (const source of node.arguments.slice(1)) {
+                        if (ts.isSpreadElement(source)) {
+                            const values = unwrapExpression(source.expression);
+                            if (ts.isArrayLiteralExpression(values)) {
+                                for (const value of values.elements)
+                                    if (ts.isSpreadElement(value))
+                                        mark(receiver, undefined);
+                                    else
+                                        mark(receiver, sourceKeys(value, checker));
+                            }
+                            else
+                                mark(receiver, undefined);
+                        }
+                        else
+                            mark(receiver, sourceKeys(source, checker));
+                    }
+                }
+            }
+        }
+        ts.forEachChild(node, visit);
+    }
+    for (const file of files)
+        if (!file.isDeclarationFile)
+            visit(file);
+    return written;
+}

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

@@ -0,0 +1,5 @@
+import type { RouteBinding } from './response-contract-route-analysis.mts';
+/** Whether requested protocol keys include a route binding, independent of its protocol variants. */
+export declare function protocolBindingRequested(binding: RouteBinding, requestedKeys?: ReadonlySet<string>): boolean;
+/** Maps one generated protocol key to its requested route spelling and exact variant suffix. */
+export declare function requestedProtocolKey(key: string, binding: RouteBinding, requestedKeys?: ReadonlySet<string>): string | undefined;

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

@@ -0,0 +1,45 @@
+import { routeShape } from './registered-route-catalog.mjs';
+/** Whether requested protocol keys include a route binding, independent of its protocol variants. */
+export function protocolBindingRequested(binding, requestedKeys) {
+    if (!requestedKeys)
+        return true;
+    return [...requestedKeys].some((key) => {
+        const requested = parseProtocolKey(key);
+        return requested && sameRoute(requested, binding);
+    });
+}
+/** Maps one generated protocol key to its requested route spelling and exact variant suffix. */
+export function requestedProtocolKey(key, binding, requestedKeys) {
+    if (!requestedKeys)
+        return key;
+    if (requestedKeys.size === 0)
+        return undefined;
+    const generated = parseProtocolKey(key);
+    if (!generated || !sameRoute(generated, binding))
+        return undefined;
+    const candidates = [];
+    for (const requestedKey of requestedKeys) {
+        const parsed = parseProtocolKey(requestedKey);
+        if (parsed?.suffix === generated.suffix && sameRoute(parsed, binding))
+            candidates.push({ key: requestedKey, parsed });
+    }
+    const exact = candidates.find((candidate) => candidate.parsed.base === generated.base);
+    return (exact ?? candidates.toSorted((left, right) => left.key.localeCompare(right.key))[0])?.key;
+}
+function parseProtocolKey(key) {
+    const suffixStart = key.indexOf('#');
+    const base = suffixStart < 0 ? key : key.slice(0, suffixStart);
+    const separator = base.indexOf(':');
+    if (separator <= 0)
+        return undefined;
+    return {
+        method: base.slice(0, separator),
+        routeTemplate: base.slice(separator + 1),
+        suffix: suffixStart < 0 ? '' : key.slice(suffixStart),
+        base,
+    };
+}
+function sameRoute(key, binding) {
+    return (key.method === binding.method &&
+        routeShape(key.routeTemplate) === routeShape(binding.routeTemplate));
+}

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

@@ -0,0 +1,7 @@
+import ts from '../contract-schema/typescript-api.mts';
+import { type HandlerBindings, type RouteBinding } from './response-contract-route-analysis.mts';
+export declare function sseCallerScope(functions: readonly ts.FunctionLikeDeclaration[], calls: readonly ts.CallExpression[], binding: RouteBinding, bindings: HandlerBindings, checker: ts.TypeChecker): {
+    paths: (ts.CallExpression | ts.NewExpression)[][];
+    contexts: Set<ts.Symbol>;
+    functions: ts.FunctionLikeDeclaration[];
+} | undefined;

package/dist/api-contract-discovery/protocol-sse-callers.mjs

@@ -0,0 +1,67 @@
+import ts from '../contract-schema/typescript-api.mjs';
+import { createProtocolCallbackValueResolver } from './protocol-callback-values.mjs';
+import { registeredHandler } from './protocol-callback-registration.mjs';
+import { executableProtocolPath } from './protocol-execution-path.mjs';
+import { enclosingFunction } from './protocol-marker-analysis.mjs';
+import { runtimeParameters } from './registered-route-runtime-parameters.mjs';
+import { expressionReceiver } from './protocol-write-receiver.mjs';
+import { enclosingRouteBinding, } from './response-contract-route-analysis.mjs';
+export function sseCallerScope(functions, calls, binding, bindings, checker) {
+    const resolver = createProtocolCallbackValueResolver(checker);
+    const matches = calls.flatMap((call) => {
+        const fn = resolver.resolve(call.expression, new Map())?.node;
+        if (!fn ||
+            !functions.includes(fn) ||
+            !executableProtocolPath(call, checker))
+            return [];
+        const route = enclosingRouteBinding(call, checker, bindings, false);
+        return route?.method === binding.method && route.routeTemplate === binding.routeTemplate
+            ? [{ call, fn: fn }]
+            : [];
+    });
+    if (!matches.length)
+        return undefined;
+    const contexts = new Set();
+    const callerFunctions = new Set();
+    const paths = matches.map(({ call }) => {
+        const anchors = [call];
+        let fn = enclosingFunction(call);
+        let outer = fn;
+        while (fn) {
+            callerFunctions.add(fn);
+            let value = fn;
+            while (ts.isPropertyAssignment(value.parent) || ts.isObjectLiteralExpression(value.parent))
+                value = value.parent;
+            if (ts.isCallExpression(value.parent) || ts.isNewExpression(value.parent))
+                anchors.push(value.parent);
+            outer = fn;
+            fn = enclosingFunction(fn);
+        }
+        const name = outer && runtimeParameters(outer)[0]?.name;
+        const context = name && ts.isIdentifier(name) ? checker.getSymbolAtLocation(name) : undefined;
+        if (!outer ||
+            (name && !context) ||
+            !calls.some((node) => registeredHandler(node) &&
+                node.arguments.some((argument) => resolver.resolve(argument, new Map())?.node === outer)))
+            throw new Error('SSE helper must bind a registered caller context');
+        if (context)
+            contexts.add(context);
+        return anchors;
+    });
+    if (contexts.size > 1)
+        throw new Error('SSE helper has ambiguous caller contexts');
+    const context = [...contexts][0];
+    for (const { call, fn } of matches)
+        runtimeParameters(fn).forEach((parameter, index) => {
+            const argument = call.arguments[index];
+            const receiver = argument && expressionReceiver(argument, checker);
+            if (context &&
+                receiver?.root === context &&
+                receiver.path.length === 0 &&
+                !receiver.mutableAlias &&
+                ts.isIdentifier(parameter.name)) {
+                contexts.add(checker.getSymbolAtLocation(parameter.name));
+            }
+        });
+    return { paths, contexts, functions: [...callerFunctions] };
+}

package/dist/api-contract-discovery/protocol-sse-emission.d.mts

@@ -0,0 +1,11 @@
+import ts from '../contract-schema/typescript-api.mts';
+import type { HandlerBindings, RouteBinding } from './response-contract-route-analysis.mts';
+export declare function sseEmission(call: ts.CallExpression, checker: ts.TypeChecker, calls: readonly ts.CallExpression[], binding: RouteBinding, bindings: HandlerBindings): {
+    write: ts.CallExpression;
+    receiver: import("./protocol-write-receiver.mts").WriteReceiver;
+    status: {
+        statusCodes?: readonly [number, ...number[]];
+        statusKnowledge: 'default' | 'explicit' | 'unknown';
+        unavailableReason?: string;
+    };
+};

package/dist/api-contract-discovery/protocol-sse-emission.mjs

@@ -0,0 +1,61 @@
+import ts from '../contract-schema/typescript-api.mjs';
+import { runtimeParameters } from './registered-route-runtime-parameters.mjs';
+import { isSupportedProtocolCallback } from './protocol-callback-invocation.mjs';
+import { potentiallyExecuted } from './protocol-executable-path.mjs';
+import { enclosingFunction } from './protocol-marker-analysis.mjs';
+import { sseCallerScope } from './protocol-sse-callers.mjs';
+import { resolveSseStatus } from './protocol-sse-status.mjs';
+import { writeReceiver } from './protocol-write-receiver.mjs';
+export function sseEmission(call, checker, calls, binding, bindings) {
+    const write = call.parent;
+    if (!ts.isCallExpression(write) ||
+        !ts.isPropertyAccessExpression(write.expression) ||
+        write.expression.name.text !== 'write' ||
+        write.arguments[0] !== call)
+        throw new Error('apiSseFrame must be the frame written by its route');
+    const receiver = writeReceiver(write, checker);
+    if (!receiver)
+        throw new Error('SSE frame requires a bound stream receiver');
+    if (receiver.mutableAlias)
+        throw new Error('SSE frame uses a mutable stream alias');
+    let fn = enclosingFunction(call);
+    let context;
+    const callbacks = [];
+    const functions = [];
+    while (fn) {
+        functions.push(fn);
+        if (!potentiallyExecuted(fn) || !potentiallyExecuted(call))
+            throw new Error('SSE frame is not on an executable callback path');
+        if (fn.asteriskToken)
+            throw new Error('SSE frame is in a deferred generator');
+        if (!isSupportedProtocolCallback(fn, checker))
+            throw new Error('SSE frame is in an uninvoked callback');
+        if (ts.isFunctionDeclaration(fn)) {
+            const name = runtimeParameters(fn)[0]?.name;
+            if (name && ts.isIdentifier(name))
+                context = checker.getSymbolAtLocation(name);
+        }
+        else {
+            let value = fn;
+            while (ts.isPropertyAssignment(value.parent) || ts.isObjectLiteralExpression(value.parent))
+                value = value.parent;
+            if (ts.isCallExpression(value.parent) || ts.isNewExpression(value.parent))
+                callbacks.push(value.parent);
+            if ((ts.isCallExpression(value.parent) &&
+                ts.isPropertyAccessExpression(value.parent.expression) &&
+                ['get', 'post', 'put', 'patch', 'delete'].includes(value.parent.expression.name.text)) ||
+                (ts.isVariableDeclaration(fn.parent) && !enclosingFunction(fn))) {
+                const name = runtimeParameters(fn)[0]?.name;
+                if (name && ts.isIdentifier(name))
+                    context = checker.getSymbolAtLocation(name);
+            }
+        }
+        fn = enclosingFunction(fn);
+    }
+    const caller = sseCallerScope(functions, calls, binding, bindings, checker);
+    const anchors = [write, ...callbacks];
+    const paths = caller ? caller.paths.map((path) => [...anchors, ...path]) : [anchors];
+    const contexts = caller?.contexts ?? new Set(context ? [context] : []);
+    const status = resolveSseStatus(paths, [...new Set([...functions, ...(caller?.functions ?? [])])], contexts, checker);
+    return { write, receiver, status };
+}

package/dist/api-contract-discovery/protocol-sse-feasible-status.d.mts

@@ -0,0 +1,3 @@
+import ts from '../contract-schema/typescript-api.mts';
+/** Excludes a sibling branch or a statement that cannot precede this anchor. */
+export declare function statusCanPrecede(setter: ts.Node, anchor: ts.Node): boolean;

package/dist/api-contract-discovery/protocol-sse-feasible-status.mjs

@@ -0,0 +1,24 @@
+import ts from '../contract-schema/typescript-api.mjs';
+/** Excludes a sibling branch or a statement that cannot precede this anchor. */
+export function statusCanPrecede(setter, anchor) {
+    const ancestors = new Set();
+    for (let node = anchor; node; node = node.parent)
+        ancestors.add(node);
+    for (let node = setter; node.parent; node = node.parent) {
+        const parent = node.parent;
+        if (ts.isIfStatement(parent) && parent.elseStatement) {
+            const opposite = parent.thenStatement === node ? parent.elseStatement : parent.thenStatement;
+            if (ancestors.has(opposite))
+                return false;
+        }
+        if (ts.isBlock(parent) && ancestors.has(parent)) {
+            let statement = anchor;
+            while (statement.parent !== parent)
+                statement = statement.parent;
+            if (parent.statements.indexOf(node) >
+                parent.statements.indexOf(statement))
+                return false;
+        }
+    }
+    return true;
+}

package/dist/api-contract-discovery/protocol-sse-raw-writes.d.mts

@@ -0,0 +1,9 @@
+import ts from '../contract-schema/typescript-api.mts';
+import { type HandlerBindings, type RouteBinding } from './response-contract-route-analysis.mts';
+import { type WriteReceiver } from './protocol-write-receiver.mts';
+export type SseRouteWrites = {
+    receivers: WriteReceiver[];
+    keys: string[];
+};
+/** Reports unmarked writes on executable or opaque escaping paths to a selected frame's stream. */
+export declare function rejectRawSseWrites(files: readonly ts.SourceFile[], checker: ts.TypeChecker, bindings: HandlerBindings, framedWrites: ReadonlySet<ts.CallExpression>, routes: ReadonlyMap<string, SseRouteWrites>, reject: (node: ts.CallExpression, binding: RouteBinding, keys: readonly string[]) => void): void;

package/dist/api-contract-discovery/protocol-sse-raw-writes.mjs

@@ -0,0 +1,70 @@
+import ts from '../contract-schema/typescript-api.mjs';
+import { potentiallyExecuted } from './protocol-executable-path.mjs';
+import { executableProtocolPath } from './protocol-execution-path.mjs';
+import { opaqueProtocolCallbackPath } from './protocol-opaque-callback.mjs';
+import { enclosingRouteBinding, visit, } from './response-contract-route-analysis.mjs';
+import { expressionReceiver, sameWriteReceiver, } from './protocol-write-receiver.mjs';
+import { sseWriteInvocation } from './protocol-sse-write-access.mjs';
+import { isSourceLevelMutation, mutationAffectsSelectedStream, sseWriteMutation, } from './protocol-sse-write-mutations.mjs';
+import { actualReceivers, helperBindings, routeKey } from './protocol-sse-write-helpers.mjs';
+/** Reports unmarked writes on executable or opaque escaping paths to a selected frame's stream. */
+export function rejectRawSseWrites(files, checker, bindings, framedWrites, routes, reject) {
+    const calls = [];
+    const mutations = [];
+    for (const file of files)
+        visit(file, (node) => {
+            if (ts.isCallExpression(node))
+                calls.push(node);
+            const mutation = sseWriteMutation(node);
+            if (mutation)
+                mutations.push(mutation);
+        });
+    for (const node of calls) {
+        if (framedWrites.has(node)) {
+            const binding = enclosingRouteBinding(node, checker, bindings, false);
+            const route = binding && routes.get(routeKey(binding));
+            const source = node.getSourceFile();
+            if (binding &&
+                route &&
+                mutationAffectsSelectedStream(mutations, route.receivers, checker, (mutationNode) => {
+                    if (mutationNode.getSourceFile() === source && isSourceLevelMutation(mutationNode))
+                        return true;
+                    const candidate = enclosingRouteBinding(mutationNode, checker, bindings, false);
+                    return !!candidate && routeKey(candidate) === routeKey(binding);
+                }, (expression) => {
+                    const receiver = expressionReceiver(expression, checker);
+                    return receiver && actualReceivers(receiver, binding, calls, checker, bindings);
+                }, (receiver) => actualReceivers(receiver, binding, calls, checker, bindings)))
+                reject(node, binding, route.keys);
+            continue;
+        }
+        const access = sseWriteInvocation(node, checker);
+        if (!access || !access.rawBytes || !potentiallyExecuted(node))
+            continue;
+        const proven = executableProtocolPath(node, checker) || opaqueProtocolCallbackPath(node, checker);
+        const helpers = helperBindings(node, calls, checker, bindings);
+        if (!proven && !helpers.length)
+            continue;
+        const binding = proven ? enclosingRouteBinding(node, checker, bindings, false) : undefined;
+        const candidates = binding ? [binding] : helpers;
+        for (const candidate of candidates) {
+            const route = routes.get(routeKey(candidate));
+            if (!route)
+                continue;
+            if (!access.receiver) {
+                reject(node, candidate, route.keys);
+                continue;
+            }
+            const receiver = expressionReceiver(access.receiver, checker);
+            if (!receiver) {
+                reject(node, candidate, route.keys);
+                continue;
+            }
+            const actual = actualReceivers(receiver, candidate, calls, checker, bindings);
+            const framed = route.receivers.flatMap((value) => actualReceivers(value, candidate, calls, checker, bindings));
+            if (actual.some((value) => value === undefined ||
+                framed.some((frame) => frame === undefined || sameWriteReceiver(frame, value))))
+                reject(node, candidate, route.keys);
+        }
+    }
+}

package/dist/api-contract-discovery/protocol-sse-status.d.mts

@@ -0,0 +1,3 @@
+import ts from '../contract-schema/typescript-api.mts';
+import { resolveEmissionStatus } from './response-contract-status.mts';
+export declare function resolveSseStatus(paths: readonly (readonly (ts.CallExpression | ts.NewExpression)[])[], functions: readonly ts.FunctionLikeDeclaration[], contexts: ReadonlySet<ts.Symbol>, checker: ts.TypeChecker): ReturnType<typeof resolveEmissionStatus>;

package/dist/api-contract-discovery/protocol-sse-status.mjs

@@ -0,0 +1,84 @@
+import ts from '../contract-schema/typescript-api.mjs';
+import { executableProtocolPath } from './protocol-execution-path.mjs';
+import { unsupportedContextAlias, unsupportedContextAssignment } from './protocol-context-alias.mjs';
+import { contextResponseMethod } from './protocol-http-emission.mjs';
+import { enclosingFunction, unwrapExpression } from './protocol-marker-analysis.mjs';
+import { expressionReceiver } from './protocol-write-receiver.mjs';
+import { statusCanPrecede } from './protocol-sse-feasible-status.mjs';
+import { statusDominatesEmission, unconditionalStatusSetter } from './protocol-status-dominance.mjs';
+import { visit } from './response-contract-route-analysis.mjs';
+import { resolveEmissionStatus } from './response-contract-status.mjs';
+import { statusForbidsBody } from './protocol-body-status.mjs';
+export function resolveSseStatus(paths, functions, contexts, checker) {
+    const matches = (expression) => [...contexts].some((context) => contextResponseMethod(expression, context, checker) === 'setStatus');
+    const setters = new Set();
+    for (const fn of functions)
+        visit(fn, (node) => {
+            if (!executableProtocolPath(node, checker))
+                return;
+            if ([...contexts].some((context) => (ts.isVariableDeclaration(node) && unsupportedContextAlias(node, context, checker)) ||
+                unsupportedContextAssignment(node, context, checker)))
+                throw new Error('SSE context has an unsupported mutable or destructured alias');
+            if (ts.isCallExpression(node) && indirectSetter(node.expression, contexts, checker))
+                throw new Error('SSE context uses an unsupported indirect status setter');
+            if (ts.isCallExpression(node) && matches(node.expression))
+                setters.add(node);
+        });
+    const statuses = paths.map((path) => {
+        for (const setter of setters) {
+            const anchors = path.filter((anchor) => enclosingFunction(anchor) === enclosingFunction(setter));
+            if ((!anchors.length || anchors.some((anchor) => statusCanPrecede(setter, anchor))) &&
+                !anchors.some((anchor) => statusDominatesEmission(anchor, new Set([setter]))))
+                throw new Error('SSE status does not dominate its frame emission');
+        }
+        for (const anchor of path) {
+            const setter = nearestSetter(anchor, setters);
+            if (setter) {
+                const status = resolveEmissionStatus(setter, matches);
+                if (status.unavailableReason)
+                    throw new Error(status.unavailableReason);
+                return status;
+            }
+        }
+        return { statusKnowledge: 'default' };
+    });
+    if (statuses.every((status) => status.statusKnowledge === 'default'))
+        return { statusKnowledge: 'default' };
+    const codes = [...new Set(statuses.flatMap((status) => status.statusCodes ?? [200]))].toSorted((a, b) => a - b);
+    if (codes.some((code) => !Number.isInteger(code) || code < 100 || code > 599))
+        throw new Error('SSE status must be an integer from 100 through 599');
+    if (codes.some(statusForbidsBody))
+        throw new Error('SSE HTTP status forbids response content');
+    return { statusKnowledge: 'explicit', statusCodes: codes };
+}
+function indirectSetter(expression, contexts, checker) {
+    const access = unwrapExpression(expression);
+    const name = ts.isPropertyAccessExpression(access)
+        ? access.name.text
+        : ts.isElementAccessExpression(access) && ts.isStringLiteral(access.argumentExpression)
+            ? access.argumentExpression.text
+            : undefined;
+    if (!name || !['call', 'apply', 'bind'].includes(name))
+        return false;
+    const target = access.expression;
+    if ([...contexts].some((context) => contextResponseMethod(target, context, checker) === 'setStatus'))
+        return true;
+    const receiver = expressionReceiver(target, checker);
+    return !!receiver && contexts.has(receiver.root) && receiver.path[0] === 'setStatus';
+}
+function nearestSetter(anchor, setters) {
+    let current = anchor;
+    while (current.parent && !ts.isFunctionLike(current.parent)) {
+        const parent = current.parent;
+        if (ts.isBlock(parent)) {
+            const index = parent.statements.indexOf(current);
+            for (const statement of parent.statements.slice(0, index).toReversed()) {
+                const setter = unconditionalStatusSetter(statement, setters);
+                if (setter)
+                    return setter;
+            }
+        }
+        current = parent;
+    }
+    return undefined;
+}

package/dist/api-contract-discovery/protocol-sse-write-access.d.mts

@@ -0,0 +1,9 @@
+import ts from '../contract-schema/typescript-api.mts';
+type WriteInvocation = {
+    receiver: ts.Expression | undefined;
+    method: string | undefined;
+    rawBytes: boolean;
+};
+/** Resolves direct and indirect SSE writes without losing their actual receiver. */
+export declare function sseWriteInvocation(call: ts.CallExpression, checker: ts.TypeChecker): WriteInvocation | undefined;
+export {};

package/dist/api-contract-discovery/protocol-sse-write-access.mjs

@@ -0,0 +1,42 @@
+import ts from '../contract-schema/typescript-api.mjs';
+import { hasRawBytes, indirectPayload, reflectApplyInvocation, writeAccess, } from './protocol-sse-write-resolution.mjs';
+/** Resolves direct and indirect SSE writes without losing their actual receiver. */
+export function sseWriteInvocation(call, checker) {
+    const reflected = reflectApplyInvocation(call, checker);
+    if (reflected)
+        return reflected;
+    const access = writeAccess(call.expression);
+    if (!access)
+        return undefined;
+    if (access.method === 'pipe')
+        return call.arguments[0]
+            ? { receiver: call.arguments[0], method: 'write', rawBytes: true }
+            : undefined;
+    if (access.method === 'bind') {
+        const target = writeAccess(access.receiver);
+        if (target?.method !== 'write' && target?.method !== 'end')
+            return undefined;
+        return { receiver: call.arguments[0], method: target.method, rawBytes: true };
+    }
+    if (access.method !== 'call' && access.method !== 'apply')
+        return { ...access, rawBytes: hasRawBytes(access.method, call.arguments, checker, false) };
+    const target = writeAccess(access.receiver);
+    const receiver = call.arguments[0];
+    if (!receiver)
+        return undefined;
+    const payload = indirectPayload(access.method, call, checker);
+    if (target?.method === 'pipe') {
+        const destination = payload?.[0];
+        return {
+            receiver: destination,
+            method: 'write',
+            rawBytes: payload === undefined || destination !== undefined,
+        };
+    }
+    const method = target?.method === 'write' || target?.method === 'end' ? target.method : undefined;
+    return {
+        receiver,
+        method,
+        rawBytes: payload === undefined || hasRawBytes(method, payload, checker, true),
+    };
+}

package/dist/api-contract-discovery/protocol-sse-write-helpers.d.mts

@@ -0,0 +1,6 @@
+import ts from '../contract-schema/typescript-api.mts';
+import { type HandlerBindings, type RouteBinding } from './response-contract-route-analysis.mts';
+import { type WriteReceiver } from './protocol-write-receiver.mts';
+export declare function routeKey(binding: RouteBinding): string;
+export declare function helperBindings(node: ts.Node, calls: readonly ts.CallExpression[], checker: ts.TypeChecker, bindings: HandlerBindings): RouteBinding[];
+export declare function actualReceivers(receiver: WriteReceiver, binding: RouteBinding, calls: readonly ts.CallExpression[], checker: ts.TypeChecker, bindings: HandlerBindings, active?: Set<ts.Symbol>): (WriteReceiver | undefined)[];