vouchington-tooling 0.29.0 → 0.31.0

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

@@ -0,0 +1,34 @@
+import ts from '../contract-schema/typescript-api.mjs';
+import { createProtocolCallbackValueResolver } from './protocol-callback-values.mjs';
+import { callbackArgumentBindings } from './protocol-callback-argument-bindings.mjs';
+import { registeredHandler } from './protocol-callback-registration.mjs';
+import { executableProtocolPath } from './protocol-execution-path.mjs';
+import { enclosingFunction } from './protocol-marker-analysis.mjs';
+/** Use the same actual invocation sites for context admission and caller emission coverage. */
+export function httpContextInvocations(fn, checker) {
+    const resolver = createProtocolCallbackValueResolver(checker);
+    const calls = [];
+    function visit(node) {
+        if (ts.isCallExpression(node) && executableProtocolPath(node, checker))
+            calls.push(node);
+        ts.forEachChild(node, visit);
+    }
+    visit(fn.getSourceFile());
+    const registered = calls.some((call) => registeredHandler(call) &&
+        call.arguments.some((argument) => resolver.resolve(argument, new Map())?.node === fn));
+    const callers = calls.filter((call) => {
+        if (resolver.resolve(call.expression, new Map())?.node === fn)
+            return true;
+        const owner = enclosingFunction(call);
+        if (!owner)
+            return false;
+        return calls.some((invocation) => {
+            const target = resolver.resolve(invocation.expression, new Map());
+            if (target?.node !== owner)
+                return false;
+            const env = callbackArgumentBindings(owner, invocation, new Map(), target.env, checker, resolver);
+            return !!env && resolver.resolve(call.expression, env)?.node === fn;
+        });
+    });
+    return { registered, callers };
+}

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

@@ -0,0 +1,9 @@
+import ts from '../contract-schema/typescript-api.mts';
+/** A helper parameter is a response context only when every executable caller passes one. */
+export declare function httpHandlerContext(fn: ts.FunctionLikeDeclaration, checker: ts.TypeChecker, active?: Set<ts.FunctionLikeDeclaration>): ts.Symbol | undefined;
+/** Literal bracket access is equivalent to property access for response methods. */
+export declare function contextResponseMethod(expression: ts.Expression, context: ts.Symbol, checker: ts.TypeChecker, allowMutable?: boolean): string | undefined;
+/** Follow only caller contexts already admitted by the actual-argument proof. */
+export declare function httpContextScopes(fn: ts.FunctionLikeDeclaration, checker: ts.TypeChecker): Map<ts.FunctionLikeDeclaration, ts.Symbol>;
+/** Indirect methods cannot prove the declared status or body, including borrowed this receivers. */
+export declare function indirectHttpResponseMethod(call: ts.CallExpression, context: ts.Symbol, checker: ts.TypeChecker): string | undefined;

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

@@ -0,0 +1,108 @@
+import ts from '../contract-schema/typescript-api.mjs';
+import { httpContextInvocations } from './protocol-http-context-callers.mjs';
+import { enclosingFunction } from './protocol-marker-analysis.mjs';
+import { expressionReceiver } from './protocol-write-receiver.mjs';
+import { hasBindingWrite } from './registered-route-binding-writes.mjs';
+import { runtimeParameters } from './registered-route-runtime-parameters.mjs';
+/** A helper parameter is a response context only when every executable caller passes one. */
+export function httpHandlerContext(fn, checker, active = new Set()) {
+    if (active.has(fn))
+        return undefined;
+    const parameter = runtimeParameters(fn)[0];
+    const context = parameter && ts.isIdentifier(parameter.name)
+        ? checker.getSymbolAtLocation(parameter.name)
+        : undefined;
+    if (!context || hasBindingWrite(parameter, checker))
+        return undefined;
+    const { registered, callers } = httpContextInvocations(fn, checker);
+    const next = new Set(active).add(fn);
+    const valid = (registered || callers.length > 0) &&
+        callers.every((call) => {
+            const argument = call.arguments[0];
+            const receiver = argument && expressionReceiver(argument, checker);
+            const declaration = receiver?.root.valueDeclaration;
+            const owner = declaration && ts.isParameter(declaration) ? enclosingFunction(declaration) : undefined;
+            return (!!owner &&
+                !!receiver &&
+                receiver.path.length === 0 &&
+                !receiver.mutableAlias &&
+                receiver.root === httpHandlerContext(owner, checker, next));
+        });
+    const result = valid ? context : undefined;
+    return result;
+}
+/** Literal bracket access is equivalent to property access for response methods. */
+export function contextResponseMethod(expression, context, checker, allowMutable = false) {
+    const access = methodAccess(expression);
+    if (!access)
+        return undefined;
+    const receiver = expressionReceiver(access.receiver, checker) ??
+        bracketResponseReceiver(access.receiver, checker);
+    if (receiver?.root !== context || (receiver.mutableAlias && !allowMutable))
+        return undefined;
+    if (receiver.path.length === 0)
+        return access.name;
+    if (receiver.path.length === 1 && receiver.path[0] === 'response')
+        return `response.${access.name}`;
+    return undefined;
+}
+function methodAccess(expression) {
+    if (ts.isPropertyAccessExpression(expression))
+        return { receiver: expression.expression, name: expression.name.text };
+    if (ts.isElementAccessExpression(expression) && ts.isStringLiteral(expression.argumentExpression))
+        return { receiver: expression.expression, name: expression.argumentExpression.text };
+    return undefined;
+}
+function bracketResponseReceiver(expression, checker) {
+    const access = methodAccess(expression);
+    if (!access || access.name !== 'response')
+        return undefined;
+    const receiver = expressionReceiver(access.receiver, checker);
+    return receiver && { ...receiver, path: [...receiver.path, 'response'] };
+}
+/** Follow only caller contexts already admitted by the actual-argument proof. */
+export function httpContextScopes(fn, checker) {
+    const scopes = new Map();
+    const pending = [fn];
+    const seen = new Set();
+    while (pending.length) {
+        const current = pending.pop();
+        if (seen.has(current))
+            continue;
+        seen.add(current);
+        const context = httpHandlerContext(current, checker);
+        if (!context)
+            continue;
+        scopes.set(current, context);
+        for (const call of httpContextInvocations(current, checker).callers) {
+            // Admission above proves every caller's parameter-owned context.
+            const receiver = expressionReceiver(call.arguments[0], checker);
+            pending.push(enclosingFunction(receiver.root.valueDeclaration));
+        }
+    }
+    return scopes;
+}
+/** Indirect methods cannot prove the declared status or body, including borrowed this receivers. */
+export function indirectHttpResponseMethod(call, context, checker) {
+    const outer = methodAccess(call.expression);
+    if (!outer || !['call', 'apply', 'bind'].includes(outer.name))
+        return undefined;
+    const direct = contextResponseMethod(outer.receiver, context, checker, true);
+    if (direct)
+        return direct;
+    const method = expressionReceiver(outer.receiver, checker);
+    if (method?.root === context)
+        return method.path[0] === 'response' ? method.path.slice(0, 2).join('.') : method.path[0];
+    const receiver = call.arguments[0] && expressionReceiver(call.arguments[0], checker);
+    if (receiver?.root !== context)
+        return undefined;
+    const target = methodAccess(outer.receiver);
+    const name = target?.name ?? method?.path.at(-1);
+    if (!name)
+        return undefined;
+    return receiver.path.length === 0
+        ? name
+        : receiver.path.length === 1 && receiver.path[0] === 'response'
+            ? `response.${name}`
+            : undefined;
+}

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

@@ -0,0 +1,3 @@
+import ts from '../contract-schema/typescript-api.mts';
+export { contextResponseMethod } from './protocol-http-context.mts';
+export declare function httpEmissionKind(call: ts.CallExpression, response: ts.Symbol, context: ts.Symbol, checker: ts.TypeChecker): 'content' | 'none' | 'status' | undefined;

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

@@ -0,0 +1,76 @@
+import ts from '../contract-schema/typescript-api.mjs';
+import { unwrapExpression } from './protocol-marker-analysis.mjs';
+import { contextResponseMethod } from './protocol-http-context.mjs';
+export { contextResponseMethod } from './protocol-http-context.mjs';
+export function httpEmissionKind(call, response, context, checker) {
+    const methodName = contextResponseMethod(call.expression, context, checker);
+    if (methodName === 'setStatus' &&
+        call.arguments[0] &&
+        responseProperty(call.arguments[0], response, 'status', checker))
+        return 'status';
+    if (methodName === 'response.empty' && emptyBodyBranch(call, response, checker))
+        return 'none';
+    if (!(methodName === 'pipeline' || methodName === 'response.buffer'))
+        return undefined;
+    const body = call.arguments[0];
+    if (!body)
+        return undefined;
+    const expression = unwrapExpression(body);
+    if (responseProperty(expression, response, 'body', checker))
+        return 'content';
+    if (!ts.isCallExpression(expression) || expression.arguments.length > 1)
+        return undefined;
+    const method = expression.expression;
+    if (!ts.isPropertyAccessExpression(method))
+        return undefined;
+    if (expression.arguments.length === 0 &&
+        ['arrayBuffer', 'text'].includes(method.name.text) &&
+        ts.isIdentifier(method.expression) &&
+        checker.getSymbolAtLocation(method.expression) === response)
+        return 'content';
+    const symbol = checker.getSymbolAtLocation(method.expression);
+    return method.name.text === 'from' &&
+        isNodeReadable(symbol) &&
+        expression.arguments[0] &&
+        responseProperty(expression.arguments[0], response, 'body', checker)
+        ? 'content'
+        : undefined;
+}
+function responseProperty(expression, response, property, checker) {
+    const value = unwrapExpression(expression);
+    return (ts.isPropertyAccessExpression(value) &&
+        value.name.text === property &&
+        ts.isIdentifier(value.expression) &&
+        checker.getSymbolAtLocation(value.expression) === response);
+}
+function emptyBodyBranch(node, response, checker) {
+    let current = node;
+    while (current.parent && !ts.isFunctionLike(current.parent)) {
+        const parent = current.parent;
+        if (ts.isIfStatement(parent)) {
+            const condition = unwrapExpression(parent.expression);
+            if (parent.thenStatement === current &&
+                ts.isPrefixUnaryExpression(condition) &&
+                condition.operator === ts.SyntaxKind.ExclamationToken &&
+                responseProperty(condition.operand, response, 'body', checker))
+                return true;
+            if (parent.elseStatement === current &&
+                responseProperty(condition, response, 'body', checker))
+                return true;
+        }
+        current = parent;
+    }
+    return false;
+}
+function isNodeReadable(symbol) {
+    return !!symbol?.declarations?.some((declaration) => {
+        if (!ts.isImportSpecifier(declaration))
+            return false;
+        const imported = declaration.propertyName ?? declaration.name;
+        const statement = declaration.parent.parent.parent;
+        return (imported.text === 'Readable' &&
+            ts.isImportDeclaration(statement) &&
+            ts.isStringLiteral(statement.moduleSpecifier) &&
+            statement.moduleSpecifier.text === 'node:stream');
+    });
+}

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

@@ -0,0 +1,7 @@
+import type { RouteBinding } from './response-contract-route-analysis.mts';
+import type { BackendResponseContract } from './response-contract-types.mts';
+/** Only already-selected route rows are tainted; implicit-only routes use their requested key. */
+export declare function taintRouteKeys(contracts: Map<string, BackendResponseContract>, binding: RouteBinding, key: string | undefined): string[];
+export declare function markRouteTaint(contracts: Map<string, BackendResponseContract>, keys: readonly string[], binding: RouteBinding, source: string, mutable: boolean): void;
+/** A direct setter is already covered by a successfully extracted matching SSE contract. */
+export declare function isSseSetter(contracts: Map<string, BackendResponseContract>, binding: RouteBinding, method: string | undefined): boolean;

package/dist/api-contract-discovery/protocol-http-implicit-taint.mjs

@@ -0,0 +1,26 @@
+import { markBufferedRouteUnavailable } from './response-contract-lenient.mjs';
+/** Only already-selected route rows are tainted; implicit-only routes use their requested key. */
+export function taintRouteKeys(contracts, binding, key) {
+    const keys = [...contracts]
+        .filter(([, row]) => row.method === binding.method && row.routeTemplate === binding.routeTemplate)
+        .map(([key]) => key);
+    return keys.length ? keys : key ? [key] : [];
+}
+export function markRouteTaint(contracts, keys, binding, source, mutable) {
+    for (const key of keys) {
+        if (contracts.get(key)?.unavailableReason)
+            continue;
+        markBufferedRouteUnavailable(contracts, key, binding, source);
+        if (mutable)
+            contracts.get(key).unavailableReason =
+                'route emits a response through a mutable context wrapper whose status or body is not statically determinable';
+    }
+}
+/** A direct setter is already covered by a successfully extracted matching SSE contract. */
+export function isSseSetter(contracts, binding, method) {
+    return (method === 'setStatus' &&
+        [...contracts.values()].some((row) => row.method === binding.method &&
+            row.routeTemplate === binding.routeTemplate &&
+            !row.unavailableReason &&
+            !!row.sseEvents?.length));
+}

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

@@ -0,0 +1,12 @@
+import ts from '../contract-schema/typescript-api.mts';
+import type { RouteBinding } from './response-contract-route-analysis.mts';
+import type { BackendResponseContract } from './response-contract-types.mts';
+export type PendingHttp = {
+    call: ts.CallExpression;
+    symbol: ts.Symbol;
+    keys: string[];
+    binding: RouteBinding;
+    variants: Omit<BackendResponseContract, 'method' | 'routeTemplate'>[];
+    declaredBodyKinds: ReadonlySet<'content' | 'none'>;
+};
+export declare function registerHttpProtocols(pending: readonly PendingHttp[], contracts: Map<string, BackendResponseContract>, checker: ts.TypeChecker, reject: (response: PendingHttp, error: unknown) => void): Set<ts.CallExpression>;

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

@@ -0,0 +1,53 @@
+import ts from '../contract-schema/typescript-api.mjs';
+import { associateHttpResponse } from './protocol-http-association.mjs';
+import { enclosingFunction } from './protocol-marker-analysis.mjs';
+import { statusDominatesEmission } from './protocol-status-dominance.mjs';
+export function registerHttpProtocols(pending, contracts, checker, reject) {
+    const covered = new Set();
+    const groups = new Map();
+    for (const response of pending) {
+        const handler = enclosingFunction(response.call);
+        const group = groups.get(handler) ?? [];
+        group.push(response);
+        groups.set(handler, group);
+    }
+    for (const group of groups.values()) {
+        if (!group.some((response) => response.keys.length))
+            continue;
+        try {
+            const siblings = new Set(group.map((response) => response.symbol));
+            const associations = new Map(group.map((response) => [
+                response,
+                associateHttpResponse(response.call, response.symbol, checker, siblings),
+            ]));
+            const allStatuses = new Set([...associations.values()].flatMap((emissions) => [...emissions].filter(([, kind]) => kind === 'status').map(([call]) => call)));
+            const proven = new Set();
+            for (const [response, emissions] of associations) {
+                proveHttpEmissions(response, emissions, allStatuses);
+                for (const call of emissions.keys())
+                    proven.add(call);
+            }
+            // Every sibling must prove its own emissions before any group contract is published.
+            for (const response of group)
+                response.variants.forEach((variant, index) => contracts.set(response.keys[index], { ...variant, ...response.binding }));
+            for (const call of proven)
+                covered.add(call);
+        }
+        catch (error) {
+            for (const response of group)
+                if (response.keys.length)
+                    reject(response, error);
+        }
+    }
+    return covered;
+}
+function proveHttpEmissions(response, emissions, allStatuses) {
+    const statuses = new Set([...emissions].filter(([, kind]) => kind === 'status').map(([call]) => call));
+    const kinds = new Set(emissions.values());
+    const declaredBodyKinds = response.declaredBodyKinds;
+    if (!kinds.has('status') ||
+        [...declaredBodyKinds].some((kind) => !kinds.has(kind)) ||
+        [...kinds].some((kind) => kind !== 'status' && !declaredBodyKinds.has(kind)) ||
+        [...emissions].some(([call, kind]) => kind !== 'status' && !statusDominatesEmission(call, statuses, allStatuses)))
+        throw new Error('HTTP response variants require dominating status and associated body emissions');
+}

package/dist/api-contract-discovery/protocol-marker-analysis.d.mts

@@ -0,0 +1,7 @@
+import ts from '../contract-schema/typescript-api.mts';
+export declare function protocolMarker(expression: ts.Expression, checker: ts.TypeChecker): 'apiSseFrame' | 'apiOpenApiHttpResponse' | undefined;
+export declare function propertyType(type: ts.Type, name: string, checker: ts.TypeChecker): ts.Type;
+export declare function typeVariants(type: ts.Type): readonly ts.Type[];
+export declare function stringLiterals(type: ts.Type): string[];
+export declare function unwrapExpression(expression: ts.Expression): ts.Expression;
+export declare function enclosingFunction(node: ts.Node): ts.FunctionLikeDeclaration | undefined;

package/dist/api-contract-discovery/protocol-marker-analysis.mjs

@@ -0,0 +1,50 @@
+import ts from '../contract-schema/typescript-api.mjs';
+export function protocolMarker(expression, checker) {
+    const symbol = checker.getSymbolAtLocation(expression);
+    const resolved = symbol && (symbol.flags & ts.SymbolFlags.Alias ? checker.getAliasedSymbol(symbol) : symbol);
+    const name = resolved?.name;
+    return name === 'apiSseFrame' || name === 'apiOpenApiHttpResponse' ? name : undefined;
+}
+export function propertyType(type, name, checker) {
+    const property = checker.getPropertyOfType(type, name);
+    const declaration = property?.valueDeclaration ?? property?.declarations?.[0];
+    if (!property || !declaration)
+        throw new Error(`Protocol contract requires ${name}`);
+    return checker.getTypeOfSymbolAtLocation(property, declaration);
+}
+export function typeVariants(type) {
+    if (type.flags & (ts.TypeFlags.Any | ts.TypeFlags.Unknown | ts.TypeFlags.Never))
+        throw new Error('Protocol contract requires concrete variants');
+    return type.isUnion() ? type.types : [type];
+}
+export function stringLiterals(type) {
+    return typeVariants(type).map((variant) => {
+        if (!(variant.flags & ts.TypeFlags.StringLiteral))
+            throw new Error('Protocol contract requires literal names and media types');
+        const value = variant.value;
+        if (!value || /[\r\n]/.test(value))
+            throw new Error('Protocol contract requires nonempty single-line names');
+        return value;
+    });
+}
+export function unwrapExpression(expression) {
+    if (ts.isParenthesizedExpression(expression) ||
+        ts.isAsExpression(expression) ||
+        ts.isTypeAssertionExpression(expression) ||
+        ts.isNonNullExpression(expression) ||
+        ts.isAwaitExpression(expression))
+        return unwrapExpression(expression.expression);
+    return expression;
+}
+export function enclosingFunction(node) {
+    let current = node.parent;
+    while (current) {
+        if (ts.isArrowFunction(current) ||
+            ts.isFunctionExpression(current) ||
+            ts.isFunctionDeclaration(current) ||
+            ts.isMethodDeclaration(current))
+            return current;
+        current = current.parent;
+    }
+    return undefined;
+}

package/dist/api-contract-discovery/protocol-opaque-callback.d.mts

@@ -0,0 +1,3 @@
+import ts from '../contract-schema/typescript-api.mts';
+/** Proves an executable lexical path containing at least one opaque callback escape. */
+export declare function opaqueProtocolCallbackPath(node: ts.Node, checker: ts.TypeChecker): boolean;

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

@@ -0,0 +1,107 @@
+import ts from '../contract-schema/typescript-api.mjs';
+import { callbackOptionsEscape } from './protocol-callback-mutations.mjs';
+import { isSupportedProtocolCallback } from './protocol-callback-invocation.mjs';
+import { potentiallyExecuted } from './protocol-executable-path.mjs';
+import { enclosingFunction } from './protocol-marker-analysis.mjs';
+import { callbackArgumentBindings } from './protocol-callback-argument-bindings.mjs';
+import { createProtocolCallbackValueResolver, isProtocolCallbackFunction as functionNode, } from './protocol-callback-values.mjs';
+function implementedFunction(node) {
+    return functionNode(node) && !!node.body;
+}
+/** Proves an executable lexical path containing at least one opaque callback escape. */
+export function opaqueProtocolCallbackPath(node, checker) {
+    if (!potentiallyExecuted(node))
+        return false;
+    const functions = [];
+    for (let fn = enclosingFunction(node); fn; fn = enclosingFunction(fn))
+        functions.push(fn);
+    if (!functions.length ||
+        functions.some((fn) => !fn.body || fn.asteriskToken || !potentiallyExecuted(fn)))
+        return false;
+    let opaque = false;
+    for (const fn of functions) {
+        if (isSupportedProtocolCallback(fn, checker))
+            continue;
+        if (!escapesToOpaque(fn, checker))
+            return false;
+        opaque = true;
+    }
+    return opaque;
+}
+function escapesToOpaque(callback, checker) {
+    const resolver = createProtocolCallbackValueResolver(checker);
+    function opaque(call, env) {
+        const implementation = resolver.resolve(call.expression, env);
+        if (implementation && functionNode(implementation.node) && implementation.node.body)
+            return false;
+        const declaration = checker.getResolvedSignature(call)?.declaration;
+        return !declaration || !('body' in declaration && declaration.body);
+    }
+    function executableCallsite(call) {
+        const callbackAncestors = new Set();
+        for (let fn = enclosingFunction(callback); fn; fn = enclosingFunction(fn))
+            callbackAncestors.add(fn);
+        for (let fn = enclosingFunction(call); fn; fn = enclosingFunction(fn))
+            if (!fn.body ||
+                fn.asteriskToken ||
+                !potentiallyExecuted(fn) ||
+                (!callbackAncestors.has(fn) && !isSupportedProtocolCallback(fn, checker)))
+                return false;
+        return true;
+    }
+    function scanBody(fn, env, active) {
+        const chain = new Set([...active, fn]);
+        let escaped = false;
+        function visit(node) {
+            if (escaped || !potentiallyExecuted(node))
+                return;
+            if (ts.isFunctionLike(node))
+                return;
+            if (ts.isCallExpression(node) || ts.isNewExpression(node)) {
+                const forwards = callbackOptionsEscape(node, env, callback, resolver);
+                if (forwards && opaque(node, env)) {
+                    escaped = true;
+                    return;
+                }
+                const target = forwards ? resolver.resolve(node.expression, env) : undefined;
+                if (target &&
+                    implementedFunction(target.node) &&
+                    !target.node.asteriskToken &&
+                    !chain.has(target.node)) {
+                    const next = callbackArgumentBindings(target.node, node, env, target.env, checker, resolver);
+                    if (!next || scanBody(target.node, next, chain))
+                        escaped = true;
+                }
+            }
+            ts.forEachChild(node, visit);
+        }
+        visit(fn.body);
+        return escaped;
+    }
+    function sourceCalls(source) {
+        let escaped = false;
+        function visit(node) {
+            if (escaped || !potentiallyExecuted(node))
+                return;
+            if (ts.isCallExpression(node) || ts.isNewExpression(node)) {
+                if (!executableCallsite(node))
+                    return;
+                const forwards = callbackOptionsEscape(node, new Map(), callback, resolver);
+                if (forwards && opaque(node, new Map())) {
+                    escaped = true;
+                    return;
+                }
+                const target = forwards ? resolver.resolve(node.expression, new Map()) : undefined;
+                if (target && implementedFunction(target.node) && !target.node.asteriskToken) {
+                    const next = callbackArgumentBindings(target.node, node, new Map(), target.env, checker, resolver);
+                    if (!next || scanBody(target.node, next, new Set()))
+                        escaped = true;
+                }
+            }
+            ts.forEachChild(node, visit);
+        }
+        visit(source);
+        return escaped;
+    }
+    return sourceCalls(callback.getSourceFile());
+}

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

@@ -0,0 +1,5 @@
+import ts from '../contract-schema/typescript-api.mts';
+/** Records the actual caller compiler's library identities, including another installation. */
+export declare function registerPlatformCompilerLibraries(program: ts.Program): void;
+/** Recognizes only callback APIs supplied by the compiler's standard libraries or Node typings. */
+export declare function platformCallbackArgument(node: ts.CallExpression | ts.NewExpression, checker: ts.TypeChecker): ts.Expression | undefined;

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

@@ -0,0 +1,72 @@
+import { basename, dirname, resolve as resolvePath } from 'node:path';
+import ts from '../contract-schema/typescript-api.mjs';
+import { unwrapExpression } from './protocol-marker-analysis.mjs';
+import { writtenPlatformSymbols } from './protocol-platform-writes.mjs';
+const standardLibrary = dirname(resolvePath(ts.getDefaultLibFilePath({})));
+const platformWrites = new WeakMap();
+const compilerLibraries = new WeakMap();
+/** Records the actual caller compiler's library identities, including another installation. */
+export function registerPlatformCompilerLibraries(program) {
+    const checker = program.getTypeChecker();
+    if (!compilerLibraries.has(checker)) {
+        const libraries = new Set(program.getSourceFiles().filter((file) => program.isSourceFileDefaultLibrary(file)));
+        compilerLibraries.set(checker, libraries);
+        platformWrites.set(checker, writtenPlatformSymbols(program.getSourceFiles(), checker, libraries));
+    }
+}
+function standardDeclaration(declaration, timer, checker) {
+    const source = declaration.getSourceFile();
+    if (!source.isDeclarationFile)
+        return false;
+    const file = resolvePath(source.fileName);
+    const libraries = compilerLibraries.get(checker);
+    if (libraries
+        ? libraries.has(source)
+        : dirname(file) === standardLibrary && /^lib(?:\.[\w.-]+)?\.d\.ts$/.test(basename(file)))
+        return true;
+    return (timer &&
+        /\/node_modules\/@types\/node\/(?:web-globals\/)?timers\.d\.ts$/.test(file.replaceAll('\\', '/')));
+}
+function platformSymbol(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 (symbol.flags & ts.SymbolFlags.Alias) {
+        const target = checker.getAliasedSymbol(symbol);
+        if (seen.has(target))
+            return undefined;
+        return target;
+    }
+    const declaration = symbol.valueDeclaration;
+    if (declaration &&
+        ts.isVariableDeclaration(declaration) &&
+        declaration.initializer &&
+        ts.isVariableDeclarationList(declaration.parent) &&
+        declaration.parent.flags & ts.NodeFlags.Const)
+        return platformSymbol(declaration.initializer, checker, seen);
+    return symbol;
+}
+/** Recognizes only callback APIs supplied by the compiler's standard libraries or Node typings. */
+export function platformCallbackArgument(node, checker) {
+    if (ts.isCallExpression(node) && node.questionDotToken)
+        return undefined;
+    const argument = node.arguments?.[0];
+    if (!argument || ts.isSpreadElement(argument))
+        return undefined;
+    const symbol = platformSymbol(node.expression, checker);
+    if (!symbol?.declarations?.length)
+        return undefined;
+    const timer = symbol.name === 'setInterval' || symbol.name === 'setTimeout';
+    if (!(timer ? ts.isCallExpression(node) : symbol.name === 'Promise' && ts.isNewExpression(node)))
+        return undefined;
+    const writes = platformWrites.get(checker) ?? writtenPlatformSymbols([node.getSourceFile()], checker);
+    if (writes.has(symbol))
+        return undefined;
+    return symbol.declarations.every((declaration) => standardDeclaration(declaration, timer, checker))
+        ? argument
+        : undefined;
+}

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

@@ -0,0 +1,5 @@
+import ts from '../contract-schema/typescript-api.mts';
+export declare function literalStrings(expression: ts.Expression | undefined, checker: ts.TypeChecker): readonly string[] | undefined;
+export declare function globalTarget(expression: ts.Expression, checker: ts.TypeChecker, seen?: Set<ts.Symbol>): ts.Expression | undefined;
+export declare function mutatorKind(call: ts.CallExpression, checker: ts.TypeChecker, libraries: ReadonlySet<ts.SourceFile> | undefined): 'defineProperty' | 'set' | 'assign' | undefined;
+export declare function sourceKeys(source: ts.Expression, checker: ts.TypeChecker): readonly string[] | undefined;