vouchington-tooling 0.35.0 → 0.36.0

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

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

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

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

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

@@ -1,65 +0,0 @@
-import ts from '../contract-schema/typescript-api.mjs';
-import { extractContractSchema, hashContractSchema } from '../contract-schema/index.mjs';
-import { isContextMethod, responseMarker, visit } from './response-contract-route-analysis.mjs';
-import { unwrapTransparentExpression } from './response-contract-route-syntax.mjs';
-export function responseBodyExpression(call, unwrapPipelineArguments = false) {
-    if (isContextMethod(call.expression, 'json'))
-        return call.arguments[0];
-    if (!isContextMethod(call.expression, 'pipeline'))
-        return undefined;
-    const originalBody = call.arguments[0];
-    const pipelineBody = originalBody &&
-        (unwrapPipelineArguments ? unwrapTransparentExpression(originalBody) : originalBody);
-    if (!pipelineBody ||
-        !ts.isCallExpression(pipelineBody) ||
-        !ts.isIdentifier(pipelineBody.expression) ||
-        pipelineBody.expression.text !== 'streamJsonObject') {
-        return undefined;
-    }
-    const body = pipelineBody.arguments[0];
-    return body && (unwrapPipelineArguments ? unwrapTransparentExpression(body) : body);
-}
-export function containsResponseMarker(node) {
-    let found = false;
-    visit(node, (child) => {
-        if (ts.isCallExpression(child) && responseMarker(child.expression))
-            found = true;
-    });
-    return found;
-}
-export function extractBodyContract(call, checker, sourceFile, location, options = {}) {
-    const body = call.arguments[1];
-    if (!body)
-        throw contractError(sourceFile, call, 'apiResponse requires a response body');
-    return extractContractSchema(checker.getTypeAtLocation(body), checker, location, options);
-}
-export function registerContract(contracts, key, contract) {
-    const existing = contracts.get(key);
-    if (!existing) {
-        contracts.set(key, contract);
-        return;
-    }
-    if (existing.hash !== contract.hash) {
-        throw new Error(`Backend response contract "${key}" resolves to multiple backend response schemas at ${existing.source} and ${contract.source}`);
-    }
-}
-export function noContentContract(source) {
-    const schema = { root: { type: 'null' }, definitions: {} };
-    return { source, schema, hash: hashContractSchema(schema) };
-}
-export function binaryContentContract(source) {
-    const schema = {
-        root: { type: 'string', format: 'binary' },
-        definitions: {},
-    };
-    return { source, schema, hash: hashContractSchema(schema) };
-}
-export function sourceLocation(sourceFile, _node) {
-    return normalizePath(sourceFile.fileName);
-}
-export function contractError(sourceFile, node, message) {
-    return new Error(`${sourceLocation(sourceFile, node)}: ${message}`);
-}
-function normalizePath(path) {
-    return path.replaceAll('\\', '/');
-}

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

@@ -1,7 +0,0 @@
-import ts from '../contract-schema/typescript-api.mts';
-import { type DiscoverApiResponseContractsOptions } from './response-contract-lenient.mts';
-import type { BackendResponseContract } from './response-contract-types.mts';
-export type { BackendResponseContract } from './response-contract-types.mts';
-export type { DiscoverApiResponseContractsOptions } from './response-contract-lenient.mts';
-export declare function discoverApiResponseContracts(program: ts.Program, sourceFiles: readonly ts.SourceFile[], requestedKeys?: ReadonlySet<string>, options?: DiscoverApiResponseContractsOptions): Record<string, BackendResponseContract>;
-export declare function enclosingResponseEmission(call: ts.CallExpression): ts.CallExpression | undefined;

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

@@ -1,124 +0,0 @@
-import ts from '../contract-schema/typescript-api.mjs';
-import { registerPlatformCompilerLibraries } from './protocol-platform-callbacks.mjs';
-import { protocolBindingRequested, requestedProtocolKey } from './protocol-requested-keys.mjs';
-import { discoverProtocolContracts } from './protocol-contract-registry.mjs';
-import { discoverImplicitContract } from './response-contract-implicit.mjs';
-import { ambiguousRoutesForCall } from './response-contract-attribution.mjs';
-import { sortAttributionFacts } from './response-contract-attribution-facts.mjs';
-import { implicitResponseCallLabel } from './response-contract-call-classification.mjs';
-import { collectHandlerBindings } from './response-contract-handler-bindings.mjs';
-import { registerRouteContract, } from './response-contract-lenient.mjs';
-import { binaryContentContract, contractError, extractBodyContract, noContentContract, sourceLocation, } from './response-contract-registration.mjs';
-import { enclosingRouteBinding, isContextMethod, responseMarker, visit, } from './response-contract-route-analysis.mjs';
-import { resolveEmissionStatus } from './response-contract-status.mjs';
-export function discoverApiResponseContracts(program, sourceFiles, requestedKeys, options) {
-    registerPlatformCompilerLibraries(program);
-    const checker = program.getTypeChecker();
-    const contracts = new Map();
-    const ambiguousBindings = options?.onAmbiguousAttribution
-        ? new Map()
-        : undefined;
-    const handlerBindings = collectHandlerBindings(sourceFiles, checker, ambiguousBindings);
-    const attributionFacts = [];
-    const protocolContracts = new Map();
-    const protocolEmissions = discoverProtocolContracts(sourceFiles, checker, handlerBindings, protocolContracts, options, requestedKeys);
-    for (const [key, contract] of protocolContracts) {
-        const requestedKey = requestedProtocolKey(key, contract, requestedKeys);
-        if (requestedKey)
-            contracts.set(requestedKey, contract);
-    }
-    for (const sourceFile of sourceFiles) {
-        visit(sourceFile, (node) => {
-            if (!ts.isCallExpression(node))
-                return;
-            const marker = responseMarker(node.expression);
-            if (!marker)
-                return;
-            const keyNode = node.arguments[0];
-            if (!keyNode || !ts.isStringLiteral(keyNode)) {
-                throw contractError(sourceFile, node, `${marker} requires a literal contract key`);
-            }
-            const binding = enclosingRouteBinding(node, checker, handlerBindings);
-            if (!binding)
-                throw contractError(sourceFile, node, `${marker} must be inside an app.route handler`);
-            const expectedPrefix = `${binding.method}:${binding.routeTemplate}`;
-            if (keyNode.text !== expectedPrefix && !keyNode.text.startsWith(`${expectedPrefix}#`)) {
-                throw contractError(sourceFile, keyNode, `Contract key "${keyNode.text}" does not match enclosing route ${expectedPrefix}`);
-            }
-            const location = sourceLocation(sourceFile, node);
-            const responseEmission = enclosingResponseEmission(node) ?? node;
-            const status = resolveEmissionStatus(responseEmission);
-            const rawMediaType = rawResponseMediaType(marker, node, sourceFile);
-            registerRouteContract(contracts, keyNode.text, binding, location, {
-                bodyKind: marker === 'apiNoContent' ? 'none' : 'content',
-                ...(marker === 'apiResponse'
-                    ? { mediaType: 'application/json', mediaTypeKnowledge: 'known' }
-                    : rawMediaType
-                        ? { mediaType: rawMediaType, mediaTypeKnowledge: 'known' }
-                        : { mediaTypeKnowledge: 'none' }),
-                ...status,
-            }, () => marker === 'apiNoContent'
-                ? noContentContract(location)
-                : marker === 'apiOpenApiRawResponse'
-                    ? binaryContentContract(location)
-                    : extractBodyContract(node, checker, sourceFile, location, options), options);
-        });
-    }
-    for (const sourceFile of sourceFiles) {
-        visit(sourceFile, (node) => {
-            if (!ts.isCallExpression(node))
-                return;
-            const callLabel = implicitResponseCallLabel(node);
-            if (options?.onAmbiguousAttribution) {
-                const attributionLabel = implicitResponseCallLabel(node, true, checker);
-                const routes = attributionLabel
-                    ? ambiguousBindings &&
-                        ambiguousRoutesForCall(node, checker, handlerBindings, ambiguousBindings)
-                    : undefined;
-                const requestedRoute = !requestedKeys ||
-                    routes?.some((route) => {
-                        const separator = route.indexOf(':');
-                        return (separator > 0 &&
-                            protocolBindingRequested({ method: route.slice(0, separator), routeTemplate: route.slice(separator + 1) }, requestedKeys));
-                    });
-                if (attributionLabel && routes && requestedRoute) {
-                    const position = sourceFile.getLineAndCharacterOfPosition(node.getStart(sourceFile));
-                    attributionFacts.push({
-                        sourceLocation: `${sourceLocation(sourceFile, node)}:${position.line + 1}:${position.character + 1}`,
-                        label: attributionLabel,
-                        routes: [...routes],
-                    });
-                }
-            }
-            if (responseMarker(node.expression) || protocolEmissions.has(node))
-                return;
-            discoverImplicitContract(node, checker, sourceFile, contracts, handlerBindings, callLabel, requestedKeys, options);
-        });
-    }
-    const result = Object.fromEntries([...contracts.entries()].toSorted(([left], [right]) => left.localeCompare(right)));
-    if (options?.onAmbiguousAttribution) {
-        for (const fact of sortAttributionFacts(attributionFacts))
-            options.onAmbiguousAttribution(fact);
-    }
-    return result;
-}
-function rawResponseMediaType(marker, node, sourceFile) {
-    if (marker !== 'apiOpenApiRawResponse')
-        return undefined;
-    const mediaType = node.arguments[1];
-    if (!mediaType || !ts.isStringLiteral(mediaType)) {
-        throw contractError(sourceFile, node, 'apiOpenApiRawResponse requires a literal media type');
-    }
-    return mediaType.text;
-}
-export function enclosingResponseEmission(call) {
-    let current = call.parent;
-    while (current && !ts.isStatement(current)) {
-        if (ts.isCallExpression(current) &&
-            (isContextMethod(current.expression, 'json') ||
-                isContextMethod(current.expression, 'pipeline')))
-            return current;
-        current = current.parent;
-    }
-    return undefined;
-}

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

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

package/dist/api-contract-discovery/response-contract-route-analysis.mjs

@@ -1,65 +0,0 @@
-import ts from '../contract-schema/typescript-api.mjs';
-import { functionSymbol, resolveSymbol } from './response-contract-symbols.mjs';
-import { executableProtocolPath } from './protocol-execution-path.mjs';
-import { HTTP_METHODS, propertyName, routeTemplateFromExpression, } from './response-contract-route-syntax.mjs';
-export { collectHandlerBindings } from './response-contract-handler-bindings.mjs';
-export { propertyName, routeTemplateFromExpression, visit, } from './response-contract-route-syntax.mjs';
-export { isContextMethod, isContextResponseBufferCall, isContextResponseEmptyCall, responseMarker, } from './response-contract-ctx-analysis.mjs';
-export function requestedKeyForBinding(binding, requestedKeys) {
-    if (!requestedKeys)
-        return `${binding.method}:${binding.routeTemplate}`;
-    const exact = `${binding.method}:${binding.routeTemplate}`;
-    if (requestedKeys.has(exact))
-        return exact;
-    const bindingShape = routeShape(binding.routeTemplate);
-    return [...requestedKeys]
-        .filter((key) => !key.includes('#'))
-        .find((key) => {
-        const separator = key.indexOf(':');
-        return (key.slice(0, separator) === binding.method &&
-            routeShape(key.slice(separator + 1)) === bindingShape);
-    });
-}
-function routeShape(routeTemplate) {
-    return routeTemplate.replace(/:[^/]+/g, ':');
-}
-export function enclosingRouteBinding(node, checker, handlerBindings, proveCallbacks = true) {
-    let current = node;
-    let insideHandlerFunction = false;
-    while (current) {
-        if (ts.isFunctionLike(current))
-            insideHandlerFunction = true;
-        if (insideHandlerFunction && ts.isCallExpression(current)) {
-            const method = propertyName(current.expression)?.toUpperCase();
-            const routeTemplate = routeTemplateFromExpression(current.expression);
-            if (method && HTTP_METHODS.has(method) && routeTemplate)
-                return !proveCallbacks || executableProtocolPath(node, checker)
-                    ? { method, routeTemplate }
-                    : undefined;
-        }
-        if (isFunctionLike(current) && ts.isCallExpression(current.parent)) {
-            const handlerCall = current.parent;
-            const method = propertyName(handlerCall.expression)?.toUpperCase();
-            if (method && HTTP_METHODS.has(method)) {
-                const routeTemplate = routeTemplateFromExpression(handlerCall.expression);
-                if (routeTemplate)
-                    return !proveCallbacks || executableProtocolPath(node, checker)
-                        ? { method, routeTemplate }
-                        : undefined;
-            }
-        }
-        const handlerSymbol = functionSymbol(current, checker);
-        if (handlerSymbol) {
-            const binding = handlerBindings.get(resolveSymbol(handlerSymbol, checker));
-            if (binding)
-                return !proveCallbacks || executableProtocolPath(node, checker, current)
-                    ? binding
-                    : undefined;
-        }
-        current = current.parent;
-    }
-    return undefined;
-}
-function isFunctionLike(node) {
-    return ts.isArrowFunction(node) || ts.isFunctionExpression(node);
-}

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

@@ -1,7 +0,0 @@
-import ts from '../contract-schema/typescript-api.mts';
-export declare const HTTP_METHODS: Set<string>;
-export declare function isInlineRouteHandler(node: ts.Node): boolean;
-export declare function routeTemplateFromExpression(expression: ts.Expression): string | undefined;
-export declare function propertyName(expression: ts.Expression): string | undefined;
-export declare function unwrapTransparentExpression(expression: ts.Expression): ts.Expression;
-export declare function visit(node: ts.Node, callback: (node: ts.Node) => void): void;

package/dist/api-contract-discovery/response-contract-route-syntax.mjs

@@ -1,41 +0,0 @@
-import ts from '../contract-schema/typescript-api.mjs';
-export const HTTP_METHODS = new Set(['GET', 'POST', 'PUT', 'PATCH', 'DELETE']);
-export function isInlineRouteHandler(node) {
-    if ((!ts.isArrowFunction(node) && !ts.isFunctionExpression(node)) ||
-        !ts.isCallExpression(node.parent))
-        return false;
-    const method = propertyName(node.parent.expression)?.toUpperCase();
-    return (!!method && HTTP_METHODS.has(method) && !!routeTemplateFromExpression(node.parent.expression));
-}
-export function routeTemplateFromExpression(expression) {
-    if (!ts.isPropertyAccessExpression(expression))
-        return undefined;
-    return findRouteCall(expression.expression);
-}
-function findRouteCall(expression) {
-    if (!ts.isCallExpression(expression))
-        return undefined;
-    if (!ts.isPropertyAccessExpression(expression.expression))
-        return undefined;
-    if (expression.expression.name.text === 'route') {
-        const route = expression.arguments[0];
-        return route && ts.isStringLiteral(route) ? route.text : undefined;
-    }
-    return findRouteCall(expression.expression.expression);
-}
-export function propertyName(expression) {
-    return ts.isPropertyAccessExpression(expression) ? expression.name.text : undefined;
-}
-export function unwrapTransparentExpression(expression) {
-    while (ts.isParenthesizedExpression(expression) ||
-        ts.isAsExpression(expression) ||
-        ts.isTypeAssertionExpression(expression) ||
-        ts.isSatisfiesExpression(expression) ||
-        ts.isNonNullExpression(expression))
-        expression = expression.expression;
-    return expression;
-}
-export function visit(node, callback) {
-    callback(node);
-    node.forEachChild((child) => visit(child, callback));
-}

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

@@ -1,27 +0,0 @@
-import ts from '../contract-schema/typescript-api.mts';
-import type { BackendResponseContract } from './response-contract-types.mts';
-export declare function responseStatusCodesForContract(contract: BackendResponseContract): number[];
-/**
- * Maps `METHOD:/route` to the non-error static `ctx.setStatus(NNN)` literal(s) found for that
- * route binding: a plain literal contributes one status; `ctx.setStatus(cond ? A : B)` with both
- * branches numeric contributes both (the doc can't know which branch fires at request time, so
- * both are valid statuses for the operation). Statuses >= 400 are dropped per-branch: they mark
- * hand-rolled error branches (the shared `default` -> `components/responses/Error` already
- * documents error responses), and capturing them here would misattribute an error status to the
- * whole operation. A route absent from the map never sets a non-error status explicitly (callers
- * fall back to 200, or 204 when the response schema's root is `null`).
- */
-/**
- * Resolves the status documented for one specific `apiResponse`/`apiNoContent` marker call: the
- * nearest preceding sibling `ctx.setStatus(NNN)` literal, walking outward through enclosing
- * blocks (mirroring `response-contract-implicit.mts`'s `precededByErrorStatus` walk). Unlike
- * `collectRouteStatusCodes`, this has no `>=400` filter: an explicit `#variant` marker is a
- * deliberate author opt-in to document that exact status (e.g. 422 for a `#validation` variant),
- * and the route-wide map (keyed only on `method:routeTemplate`) can't tell two markers in the
- * same route apart when they're preceded by different statuses.
- */
-export declare function resolveEmissionStatus(call: ts.CallExpression | ts.NewExpression, matchesContext?: (expression: ts.Expression) => boolean): {
-    statusCodes?: readonly [number, ...number[]];
-    statusKnowledge: 'default' | 'explicit' | 'unknown';
-    unavailableReason?: string;
-};

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

@@ -1,82 +0,0 @@
-import ts from '../contract-schema/typescript-api.mjs';
-import { isContextMethod } from './response-contract-route-analysis.mjs';
-export function responseStatusCodesForContract(contract) {
-    if (contract.statusKnowledge === 'unknown')
-        return [];
-    if (contract.statusCodes)
-        return [...new Set(contract.statusCodes)].toSorted((a, b) => a - b);
-    const bodyKind = contract.bodyKind ?? (contract.schema.root.type === 'null' ? 'none' : 'content');
-    return [bodyKind === 'none' ? 204 : 200];
-}
-/**
- * Maps `METHOD:/route` to the non-error static `ctx.setStatus(NNN)` literal(s) found for that
- * route binding: a plain literal contributes one status; `ctx.setStatus(cond ? A : B)` with both
- * branches numeric contributes both (the doc can't know which branch fires at request time, so
- * both are valid statuses for the operation). Statuses >= 400 are dropped per-branch: they mark
- * hand-rolled error branches (the shared `default` -> `components/responses/Error` already
- * documents error responses), and capturing them here would misattribute an error status to the
- * whole operation. A route absent from the map never sets a non-error status explicitly (callers
- * fall back to 200, or 204 when the response schema's root is `null`).
- */
-/**
- * Resolves the status documented for one specific `apiResponse`/`apiNoContent` marker call: the
- * nearest preceding sibling `ctx.setStatus(NNN)` literal, walking outward through enclosing
- * blocks (mirroring `response-contract-implicit.mts`'s `precededByErrorStatus` walk). Unlike
- * `collectRouteStatusCodes`, this has no `>=400` filter: an explicit `#variant` marker is a
- * deliberate author opt-in to document that exact status (e.g. 422 for a `#validation` variant),
- * and the route-wide map (keyed only on `method:routeTemplate`) can't tell two markers in the
- * same route apart when they're preceded by different statuses.
- */
-export function resolveEmissionStatus(call, matchesContext = (expression) => isContextMethod(expression, 'setStatus')) {
-    if (ts.isCallExpression(call) && matchesContext(call.expression))
-        return statusArgument(call.arguments[0]);
-    let statement = call;
-    while (!ts.isStatement(statement))
-        statement = statement.parent;
-    return precedingStatus(statement, matchesContext);
-}
-function precedingStatus(statement, matchesContext) {
-    const block = statement.parent;
-    if (!ts.isBlock(block))
-        return { statusKnowledge: 'default' };
-    const index = block.statements.indexOf(statement);
-    for (let i = index - 1; i >= 0; i--) {
-        const status = statusStatement(block.statements[i], matchesContext);
-        if (status)
-            return status;
-    }
-    const enclosing = block.parent;
-    return ts.isStatement(enclosing)
-        ? precedingStatus(enclosing, matchesContext)
-        : { statusKnowledge: 'default' };
-}
-function statusStatement(statement, matchesContext) {
-    if (!ts.isExpressionStatement(statement))
-        return undefined;
-    const expression = statement.expression;
-    if (!ts.isCallExpression(expression) || !matchesContext(expression.expression))
-        return undefined;
-    return statusArgument(expression.arguments[0]);
-}
-/** A `ctx.setStatus` argument's possible numeric literal value(s): one for a bare literal, up to two (sorted ascending) for `cond ? A : B` when both branches are numeric literals. */
-function statusArgument(argument) {
-    if (!argument)
-        return {
-            statusKnowledge: 'unknown',
-            unavailableReason: 'ctx.setStatus has no statically known status',
-        };
-    if (ts.isNumericLiteral(argument))
-        return { statusCodes: [Number(argument.text)], statusKnowledge: 'explicit' };
-    if (ts.isConditionalExpression(argument) &&
-        ts.isNumericLiteral(argument.whenTrue) &&
-        ts.isNumericLiteral(argument.whenFalse)) {
-        const values = [
-            ...new Set([Number(argument.whenTrue.text), Number(argument.whenFalse.text)]),
-        ].toSorted((a, b) => a - b);
-        return { statusCodes: values, statusKnowledge: 'explicit' };
-    }
-    return {
-        statusKnowledge: 'unknown',
-        unavailableReason: 'nearest ctx.setStatus value is dynamic',
-    };
-}

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

@@ -1,5 +0,0 @@
-import ts from '../contract-schema/typescript-api.mts';
-export declare function functionSymbol(node: ts.Node, checker: ts.TypeChecker): ts.Symbol | undefined;
-export declare function attributionFunctionSymbol(node: ts.Node, checker: ts.TypeChecker): ts.Symbol | undefined;
-export declare function resolveSymbol(symbol: ts.Symbol, checker: ts.TypeChecker): ts.Symbol;
-export declare function attributionSymbol(symbol: ts.Symbol, checker: ts.TypeChecker): ts.Symbol;

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

@@ -1,82 +0,0 @@
-import ts from '../contract-schema/typescript-api.mjs';
-export function functionSymbol(node, checker) {
-    if (ts.isFunctionDeclaration(node) && node.name)
-        return checker.getSymbolAtLocation(node.name);
-    if ((ts.isArrowFunction(node) || ts.isFunctionExpression(node)) &&
-        ts.isVariableDeclaration(node.parent) &&
-        ts.isIdentifier(node.parent.name)) {
-        return checker.getSymbolAtLocation(node.parent.name);
-    }
-    return undefined;
-}
-export function attributionFunctionSymbol(node, checker) {
-    const existing = functionSymbol(node, checker);
-    if (existing)
-        return existing;
-    if (ts.isMethodDeclaration(node) && node.name)
-        return checker.getSymbolAtLocation(node.name);
-    if (ts.isArrowFunction(node) || ts.isFunctionExpression(node)) {
-        const owner = wrappedFunctionOwner(node);
-        if (owner &&
-            (ts.isVariableDeclaration(owner) ||
-                ts.isPropertyAssignment(owner) ||
-                ts.isPropertyDeclaration(owner))) {
-            return checker.getSymbolAtLocation(owner.name);
-        }
-    }
-    if (ts.isFunctionDeclaration(node) &&
-        !node.name &&
-        ts.getCombinedModifierFlags(node) & ts.ModifierFlags.Default)
-        return defaultExportSymbol(node.getSourceFile(), checker);
-    if ((ts.isArrowFunction(node) || ts.isFunctionExpression(node)) &&
-        isDefaultExportExpression(node))
-        return defaultExportSymbol(node.getSourceFile(), checker);
-    return undefined;
-}
-function wrappedFunctionOwner(node) {
-    let current = node;
-    let parent = current.parent;
-    while (ts.isParenthesizedExpression(parent) ||
-        ts.isAsExpression(parent) ||
-        ts.isTypeAssertionExpression(parent) ||
-        ts.isSatisfiesExpression(parent) ||
-        ts.isNonNullExpression(parent)) {
-        current = parent;
-        parent = current.parent;
-    }
-    if ((ts.isVariableDeclaration(parent) ||
-        ts.isPropertyAssignment(parent) ||
-        ts.isPropertyDeclaration(parent)) &&
-        parent.initializer === current)
-        return parent;
-    return undefined;
-}
-function isDefaultExportExpression(node) {
-    let current = node;
-    let parent = current.parent;
-    while ((ts.isParenthesizedExpression(parent) ||
-        ts.isAsExpression(parent) ||
-        ts.isTypeAssertionExpression(parent) ||
-        ts.isSatisfiesExpression(parent) ||
-        ts.isNonNullExpression(parent)) &&
-        parent.expression === current) {
-        current = parent;
-        parent = current.parent;
-    }
-    return ts.isExportAssignment(parent) && !parent.isExportEquals && parent.expression === current;
-}
-function defaultExportSymbol(sourceFile, checker) {
-    const moduleSymbol = checker.getSymbolAtLocation(sourceFile);
-    return (moduleSymbol &&
-        checker.getExportsOfModule(moduleSymbol).find((symbol) => symbol.getName() === 'default'));
-}
-export function resolveSymbol(symbol, checker) {
-    return symbol.flags & ts.SymbolFlags.Alias ? checker.getAliasedSymbol(symbol) : symbol;
-}
-export function attributionSymbol(symbol, checker) {
-    const resolved = resolveSymbol(symbol, checker);
-    const name = resolved.valueDeclaration?.name;
-    if (!name || !ts.isIdentifier(name))
-        return resolved;
-    return checker.getSymbolAtLocation(name) ?? resolved;
-}

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

@@ -1,23 +0,0 @@
-import type { ExtractedResponseContract } from '../contract-schema/index.mts';
-export type BackendResponseContract = ExtractedResponseContract & {
-    method: string;
-    routeTemplate: string;
-    /** Statuses owned by this response emission. Defaults to 200, or 204 for an unannotated empty emission. */
-    statusCodes?: readonly [number, ...number[]];
-    /** Distinguishes a known framework default from an explicitly set or genuinely unknown status. */
-    statusKnowledge?: 'default' | 'explicit' | 'unknown';
-    bodyKind?: 'content' | 'none';
-    /** Required for content emissions and absent for bodyless emissions. */
-    mediaType?: string;
-    /** Raw buffers and arbitrary streams have an unknown media type; bodyless emissions have none. */
-    mediaTypeKnowledge?: 'known' | 'none' | 'unknown';
-    /** Named SSE frames carried by the string stream body. */
-    sseEvents?: readonly {
-        eventName: string;
-        contract: ExtractedResponseContract;
-    }[];
-    /** A concrete error status can also be produced by the framework before dispatch. */
-    includeDefaultError?: boolean;
-    /** Set when the route's response schema could not be extracted (lenient discovery mode). */
-    unavailableReason?: string;
-};

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

@@ -1 +0,0 @@
-export {};