vouchington-tooling 0.20.0 → 0.22.0

package/dist/api-contract-discovery/query-contract-literals.mjs

@@ -0,0 +1,54 @@
+import ts from '../contract-schema/typescript-api.mjs';
+export function requiredPropertyType(type, name, checker, fail) {
+    const property = type.getProperty(name);
+    if (!property || property.flags & ts.SymbolFlags.Optional)
+        return fail(`requires literal ${name}`);
+    const location = property.valueDeclaration ?? property.declarations?.[0];
+    if (!location)
+        return fail(`requires declared ${name}`);
+    return checker.getTypeOfSymbolAtLocation(property, location);
+}
+export function requiredStringLiteral(type, name, checker, fail) {
+    const value = requiredPropertyType(type, name, checker, fail);
+    return value.isStringLiteral() ? value.value : fail(`requires literal ${name}`);
+}
+export function requiredNumberLiteral(type, name, checker, fail) {
+    const value = requiredPropertyType(type, name, checker, fail);
+    return value.isNumberLiteral() ? value.value : fail(`requires literal ${name}`);
+}
+export function requiredBooleanLiteral(type, name, checker, fail) {
+    const value = requiredPropertyType(type, name, checker, fail);
+    if (value.flags & ts.TypeFlags.BooleanLiteral)
+        return checker.typeToString(value) === 'true';
+    return fail(`requires literal ${name}`);
+}
+export function optionalStringLiteral(type, name, checker, node, fail) {
+    const property = type.getProperty(name);
+    if (!property)
+        return undefined;
+    if (property.flags & ts.SymbolFlags.Optional)
+        return fail(`${name} must be literal when present`);
+    const location = property.valueDeclaration ?? property.declarations?.[0] ?? node;
+    const value = checker.getTypeOfSymbolAtLocation(property, location);
+    return value.isStringLiteral() ? value.value : fail(`requires literal ${name}`);
+}
+export function optionalNumberLiteral(type, name, checker, node, fail) {
+    const property = type.getProperty(name);
+    if (!property)
+        return undefined;
+    if (property.flags & ts.SymbolFlags.Optional)
+        return fail(`${name} must be literal when present`);
+    const location = property.valueDeclaration ?? property.declarations?.[0] ?? node;
+    const value = checker.getTypeOfSymbolAtLocation(property, location);
+    return value.isNumberLiteral() ? value.value : fail(`requires literal ${name}`);
+}
+export function stringTuple(type, name, checker, fail) {
+    const value = requiredPropertyType(type, name, checker, fail);
+    if (!checker.isTupleType(value))
+        return fail(`${name} must be a literal tuple`);
+    const values = checker.getTypeArguments(value);
+    if (values.length === 0 || values.some((item) => !item.isStringLiteral())) {
+        return fail(`${name} must contain string literals`);
+    }
+    return values.map((item) => item.value);
+}

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

@@ -0,0 +1,3 @@
+import ts from '../contract-schema/typescript-api.mts';
+import type { BackendQueryContractRegistry } from './query-contract-types.mts';
+export declare function discoverApiQueryContracts(program: ts.Program, sourceFiles: readonly ts.SourceFile[], knownResponseRoutes: ReadonlySet<string>): BackendQueryContractRegistry;

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

@@ -0,0 +1,68 @@
+import ts from '../contract-schema/typescript-api.mjs';
+import { extractQueryParameterDescriptor } from './query-contract-extraction.mjs';
+import { contractError } from './response-contract-registration.mjs';
+import { collectHandlerBindings, enclosingRouteBinding, visit, } from './response-contract-route-analysis.mjs';
+export function discoverApiQueryContracts(program, sourceFiles, knownResponseRoutes) {
+    const checker = program.getTypeChecker();
+    const handlerBindings = collectHandlerBindings(sourceFiles, checker);
+    const contracts = new Map();
+    const knownOperations = new Set([...knownResponseRoutes].map((key) => key.split('#')[0]));
+    for (const sourceFile of sourceFiles) {
+        visit(sourceFile, (node) => {
+            if (!ts.isCallExpression(node) || !isApiQueryMarker(node.expression))
+                return;
+            const keyNode = node.arguments[0];
+            if (!keyNode || !ts.isStringLiteral(keyNode)) {
+                throw contractError(sourceFile, node, 'apiQuery requires a literal operation key');
+            }
+            const binding = enclosingRouteBinding(node, checker, handlerBindings);
+            if (!binding)
+                throw contractError(sourceFile, node, 'apiQuery must be inside an app.route handler');
+            const expectedKey = `${binding.method}:${binding.routeTemplate}`;
+            if (keyNode.text !== expectedKey) {
+                throw contractError(sourceFile, keyNode, `Query operation key "${keyNode.text}" does not match enclosing route ${expectedKey}`);
+            }
+            if (!knownOperations.has(expectedKey)) {
+                throw contractError(sourceFile, keyNode, `apiQuery references unknown response route ${expectedKey}`);
+            }
+            if (contracts.has(expectedKey)) {
+                throw contractError(sourceFile, keyNode, `Duplicate apiQuery marker for ${expectedKey}`);
+            }
+            if (node.arguments.length < 2) {
+                throw contractError(sourceFile, node, 'apiQuery requires at least one query contract carrier');
+            }
+            const parameters = Object.create(null);
+            for (const carrier of node.arguments.slice(1)) {
+                const carrierType = checker.getTypeAtLocation(carrier);
+                const queryContractSymbol = carrierType.getProperty('queryContract');
+                if (!queryContractSymbol || queryContractSymbol.flags & ts.SymbolFlags.Optional) {
+                    throw contractError(sourceFile, carrier, 'apiQuery carrier requires a queryContract property');
+                }
+                const queryContractType = checker.getTypeOfSymbolAtLocation(queryContractSymbol, carrier);
+                if (queryContractType.getStringIndexType()) {
+                    throw contractError(sourceFile, carrier, 'apiQuery queryContract keys must be literal names');
+                }
+                const properties = queryContractType.getProperties();
+                if (properties.length === 0) {
+                    throw contractError(sourceFile, carrier, 'apiQuery queryContract must define parameters');
+                }
+                for (const property of properties) {
+                    const name = property.getName();
+                    if (property.flags & ts.SymbolFlags.Optional) {
+                        throw contractError(sourceFile, carrier, `Query parameter "${name}" must not be optional`);
+                    }
+                    if (Object.hasOwn(parameters, name)) {
+                        throw contractError(sourceFile, carrier, `Duplicate query parameter contract: ${name}`);
+                    }
+                    const descriptorType = checker.getTypeOfSymbolAtLocation(property, carrier);
+                    parameters[name] = extractQueryParameterDescriptor(descriptorType, checker, sourceFile, carrier, name);
+                }
+            }
+            contracts.set(expectedKey, { ...binding, parameters });
+        });
+    }
+    return Object.fromEntries([...contracts.entries()].toSorted(([left], [right]) => left.localeCompare(right)));
+}
+function isApiQueryMarker(expression) {
+    return ts.isIdentifier(expression) && expression.text === 'apiQuery';
+}

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

@@ -0,0 +1,8 @@
+import type { OpenApiQueryContract, OpenApiQueryParameter } from '../openapi-document/index.mts';
+export type QueryParameterContract = OpenApiQueryParameter;
+export type BackendQueryContract = {
+    method: string;
+    routeTemplate: string;
+    parameters: OpenApiQueryContract;
+};
+export type BackendQueryContractRegistry = Readonly<Record<string, BackendQueryContract>>;

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

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

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

@@ -0,0 +1,10 @@
+import ts from '../contract-schema/typescript-api.mts';
+export type RegisteredRoute = {
+    method: string;
+    routeTemplate: string;
+    kind: 'ordinary' | 'sse' | 'error-only' | 'fixed-no-content';
+    fixedStatus?: number;
+    source: string;
+};
+export declare const routeShape: (routeTemplate: string) => string;
+export declare function discoverRegisteredRoutes(program: ts.Program, sourceFiles: readonly ts.SourceFile[]): RegisteredRoute[];

package/dist/api-contract-discovery/registered-route-catalog.mjs

@@ -0,0 +1,81 @@
+import ts from '../contract-schema/typescript-api.mjs';
+import { handlerNodes } from './registered-route-handler-analysis.mjs';
+import { propertyName, routeTemplateFromExpression, visit, } from './response-contract-route-analysis.mjs';
+export const routeShape = (routeTemplate) => routeTemplate.replace(/:[^/]+/g, ':');
+export function discoverRegisteredRoutes(program, sourceFiles) {
+    const checker = program.getTypeChecker();
+    const routes = [];
+    const registrations = new Map();
+    sourceFiles.forEach((sourceFile) => {
+        visit(sourceFile, (node) => {
+            if (!ts.isCallExpression(node))
+                return;
+            const method = propertyName(node.expression)?.toUpperCase();
+            if (!method || !['GET', 'POST', 'PUT', 'PATCH', 'DELETE'].includes(method))
+                return;
+            const routeTemplate = routeTemplateFromExpression(node.expression);
+            if (!routeTemplate)
+                return;
+            const key = `${method}:${routeShape(routeTemplate)}`;
+            const source = `${sourceFile.fileName}:${sourceFile.getLineAndCharacterOfPosition(node.getStart()).line + 1}`;
+            const classification = classifyHandler(node, checker, method, routeTemplate);
+            const route = {
+                method,
+                routeTemplate,
+                ...classification,
+                source,
+            };
+            const existing = registrations.get(key);
+            if (existing)
+                throw new Error(`Duplicate registered API route ${key} at ${existing.source} and ${source}`);
+            registrations.set(key, route);
+            routes.push(route);
+        });
+    });
+    return routes.toSorted((left, right) => `${left.method}:${left.routeTemplate}`.localeCompare(`${right.method}:${right.routeTemplate}`));
+}
+function classifyHandler(call, checker, method, routeTemplate) {
+    const nodes = call.arguments.flatMap((argument) => handlerNodes(argument, checker));
+    if (nodes.length === 0)
+        throw new Error(`Cannot inspect registered route handler ${method}:${routeTemplate}`);
+    let sse = false;
+    let error405 = false;
+    let fixedStatus;
+    nodes.forEach((node) => {
+        visit(node, (child) => {
+            if (!ts.isCallExpression(child))
+                return;
+            if (ts.isIdentifier(child.expression) && child.expression.text === 'apiOpenApiNoContent') {
+                const [key, status] = child.arguments;
+                if (!key || !ts.isStringLiteral(key) || key.text !== `${method}:${routeTemplate}`)
+                    throw new Error(`apiOpenApiNoContent key must match registered route ${method}:${routeTemplate}`);
+                if (!status || !ts.isNumericLiteral(status))
+                    throw new Error('apiOpenApiNoContent status requires a numeric literal');
+                const value = Number(status.text);
+                if (fixedStatus !== undefined && fixedStatus !== value)
+                    throw new Error(`Conflicting apiOpenApiNoContent statuses for ${method}:${routeTemplate}`);
+                fixedStatus = value;
+            }
+            if (ts.isIdentifier(child.expression) && child.expression.text === 'startSSE')
+                sse = true;
+            if (ts.isPropertyAccessExpression(child.expression) &&
+                child.expression.name.text === 'setType' &&
+                child.arguments[0] &&
+                ts.isStringLiteral(child.arguments[0]) &&
+                child.arguments[0].text.toLowerCase() === 'text/event-stream')
+                sse = true;
+            if (ts.isPropertyAccessExpression(child.expression) &&
+                child.expression.name.text === 'throw' &&
+                child.arguments[0] &&
+                ts.isNumericLiteral(child.arguments[0]) &&
+                child.arguments[0].text === '405')
+                error405 = true;
+        });
+    });
+    if (fixedStatus !== undefined) {
+        if (sse)
+            throw new Error(`apiOpenApiNoContent conflicts with SSE response handling for ${method}:${routeTemplate}`);
+        return { kind: 'fixed-no-content', fixedStatus };
+    }
+    return { kind: sse ? 'sse' : error405 ? 'error-only' : 'ordinary' };
+}

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

@@ -0,0 +1,2 @@
+import ts from '../contract-schema/typescript-api.mts';
+export declare function handlerNodes(argument: ts.Expression, checker: ts.TypeChecker, parameterBindings?: Map<ts.Symbol, ts.Expression>): ts.Node[];

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

@@ -0,0 +1,74 @@
+import ts from '../contract-schema/typescript-api.mjs';
+export function handlerNodes(argument, checker, parameterBindings = new Map()) {
+    if (ts.isIdentifier(argument)) {
+        const symbol = checker.getSymbolAtLocation(argument);
+        const boundArgument = symbol && parameterBindings.get(symbol);
+        if (boundArgument)
+            return handlerNodes(boundArgument, checker, parameterBindings);
+    }
+    if (ts.isArrowFunction(argument) || ts.isFunctionExpression(argument))
+        return [argument];
+    if (ts.isCallExpression(argument)) {
+        return callableImplementations(argument.expression, checker).flatMap((implementation) => {
+            const bindings = new Map(parameterBindings);
+            implementation.parameters.forEach((parameter, index) => {
+                const callArgument = argument.arguments[index];
+                const symbol = checker.getSymbolAtLocation(parameter.name);
+                if (callArgument && symbol)
+                    bindings.set(symbol, callArgument);
+            });
+            return returnedExpressions(implementation).flatMap((returnedExpression) => handlerNodes(returnedExpression, checker, bindings));
+        });
+    }
+    return declarationImplementations(argument, checker);
+}
+function callableImplementations(node, checker) {
+    const symbol = checker.getSymbolAtLocation(node);
+    if (!symbol)
+        return [];
+    const resolved = symbol.flags & ts.SymbolFlags.Alias ? checker.getAliasedSymbol(symbol) : symbol;
+    const implementations = [];
+    for (const declaration of resolved.declarations ?? []) {
+        if (ts.isVariableDeclaration(declaration) && declaration.initializer) {
+            const initializer = declaration.initializer;
+            if (ts.isArrowFunction(initializer) || ts.isFunctionExpression(initializer))
+                implementations.push(initializer);
+            continue;
+        }
+        if ((ts.isFunctionDeclaration(declaration) || ts.isMethodDeclaration(declaration)) &&
+            declaration.body)
+            implementations.push(declaration);
+    }
+    return implementations;
+}
+function returnedExpressions(declaration) {
+    const body = declaration.body;
+    if (!ts.isBlock(body))
+        return [body];
+    const returned = [];
+    const collect = (node) => {
+        if (node !== declaration && ts.isFunctionLike(node))
+            return;
+        if (ts.isReturnStatement(node)) {
+            if (node.expression)
+                returned.push(node.expression);
+            return;
+        }
+        node.forEachChild(collect);
+    };
+    body.forEachChild(collect);
+    return returned;
+}
+function declarationImplementations(node, checker) {
+    const symbol = checker.getSymbolAtLocation(node);
+    if (!symbol)
+        return [];
+    const resolved = symbol.flags & ts.SymbolFlags.Alias ? checker.getAliasedSymbol(symbol) : symbol;
+    return (resolved.declarations ?? []).flatMap((declaration) => {
+        if (ts.isFunctionDeclaration(declaration) || ts.isMethodDeclaration(declaration))
+            return declaration.body ? [declaration] : [];
+        if (ts.isVariableDeclaration(declaration) && declaration.initializer)
+            return [declaration, ...handlerNodes(declaration.initializer, checker)];
+        return [];
+    });
+}

package/dist/api-contract-discovery/request-contract-implicit.d.mts

@@ -0,0 +1,17 @@
+import ts from '../contract-schema/typescript-api.mts';
+import { type DiscoverApiRequestContractsOptions } from './request-contract-lenient.mts';
+import { type HandlerBindings } from './response-contract-route-analysis.mts';
+import type { BackendRequestContract } from './request-contract-types.mts';
+/**
+ * Phase 2 (implicit harvest) dispatch for one call expression. Requests have no `#variant` escape
+ * hatch, so precedence is stricter than the response side's: an explicit `apiRequest`/
+ * `apiNoRequestBody` marker registered in Phase 1 (`markerKeys`) always wins outright — a harvest
+ * never even attempts to register over one. A second implicit body-read for a route an earlier
+ * implicit call already covered attempts registration but swallows any failure (extraction error
+ * or hash mismatch), keeping the first-registered contract untouched — mirrors
+ * `response-contract-implicit.mts`'s secondary-variant handling, minus the variant key (requests
+ * get at most one contract per route). A `ctx.request.buffer(...)` read always overrides,
+ * regardless of visit order or what's already registered, mirroring the response side's own
+ * buffer-detection override.
+ */
+export declare function discoverImplicitRequestContract(call: ts.CallExpression, checker: ts.TypeChecker, sourceFile: ts.SourceFile, contracts: Map<string, BackendRequestContract>, markerKeys: ReadonlySet<string>, handlerBindings: HandlerBindings, requestedKeys: ReadonlySet<string> | undefined, options: DiscoverApiRequestContractsOptions | undefined): void;

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

@@ -0,0 +1,73 @@
+import ts from '../contract-schema/typescript-api.mjs';
+import { extractContractSchema } from '../contract-schema/index.mjs';
+import { markBufferedRequestRouteUnavailable, registerRequestContract, registerRequestRouteContract, } from './request-contract-lenient.mjs';
+import { enclosingRequestBodyCast, isContextRequestBufferCall, isContextRequestJsonCall, } from './request-contract-route-analysis.mjs';
+import { sourceLocation } from './response-contract-registration.mjs';
+import { enclosingRouteBinding, requestedKeyForBinding, } from './response-contract-route-analysis.mjs';
+/**
+ * Resolves the effective static type of a body-read call, or `undefined` when `call` isn't a
+ * body-read pattern this harvester recognizes at all (most call expressions in a route file
+ * aren't). `parseJsonBody<T>(ctx)`'s own call-expression type is `Promise<T>` (or `Promise<unknown>`
+ * with no type argument) — `extractContractSchema` auto-unwraps the `Promise` either way, so no
+ * special-casing is needed. `ctx.request.json(...)` has no such generic in practice; its effective
+ * type comes from the enclosing `as T` cast, when one exists (`enclosingRequestBodyCast`) — absent
+ * one, the call's own type is `Promise<unknown>`, which resolves to an honest `{type:'unknown'}`
+ * rather than a failure (see `enclosingRequestBodyCast`'s docstring).
+ */
+function resolveRequestBodyType(call, checker) {
+    if (ts.isIdentifier(call.expression) && call.expression.text === 'parseJsonBody') {
+        return checker.getTypeAtLocation(call);
+    }
+    if (!isContextRequestJsonCall(call.expression))
+        return undefined;
+    const cast = enclosingRequestBodyCast(call);
+    return checker.getTypeAtLocation(cast ?? call);
+}
+/**
+ * Phase 2 (implicit harvest) dispatch for one call expression. Requests have no `#variant` escape
+ * hatch, so precedence is stricter than the response side's: an explicit `apiRequest`/
+ * `apiNoRequestBody` marker registered in Phase 1 (`markerKeys`) always wins outright — a harvest
+ * never even attempts to register over one. A second implicit body-read for a route an earlier
+ * implicit call already covered attempts registration but swallows any failure (extraction error
+ * or hash mismatch), keeping the first-registered contract untouched — mirrors
+ * `response-contract-implicit.mts`'s secondary-variant handling, minus the variant key (requests
+ * get at most one contract per route). A `ctx.request.buffer(...)` read always overrides,
+ * regardless of visit order or what's already registered, mirroring the response side's own
+ * buffer-detection override.
+ */
+export function discoverImplicitRequestContract(call, checker, sourceFile, contracts, markerKeys, handlerBindings, requestedKeys, options) {
+    const binding = enclosingRouteBinding(call, checker, handlerBindings);
+    if (!binding)
+        return;
+    const key = requestedKeyForBinding(binding, requestedKeys);
+    if (!key)
+        return;
+    if (isContextRequestBufferCall(call.expression)) {
+        markBufferedRequestRouteUnavailable(contracts, key, binding, sourceLocation(sourceFile, call));
+        return;
+    }
+    if (markerKeys.has(key))
+        return; // An explicit Phase 1 marker always wins; never harvest over it.
+    const bodyType = resolveRequestBodyType(call, checker);
+    if (!bodyType)
+        return;
+    const location = sourceLocation(sourceFile, call);
+    const extract = () => extractContractSchema(bodyType, checker, location, options);
+    if (!contracts.has(key)) {
+        registerRequestRouteContract(contracts, key, binding, location, extract, options);
+        return;
+    }
+    // A second body-read call for a route an earlier implicit harvest already covered — attempt
+    // registration but silently drop it on a hash-mismatch collision, keeping the
+    // first-registered contract. Anything else (a type-checker crash, an AST invariant
+    // violation) is unexpected and worth surfacing rather than swallowing.
+    try {
+        const extracted = extract();
+        registerRequestContract(contracts, key, { ...extracted, ...binding });
+    }
+    catch (error) {
+        if (error instanceof Error && !error.message.includes('resolves to multiple')) {
+            console.warn(`Second body-read extraction for "${key}" failed:`, error);
+        }
+    }
+}

package/dist/api-contract-discovery/request-contract-lenient.d.mts

@@ -0,0 +1,28 @@
+import type { ExtractedResponseContract, ExtractContractSchemaOptions } from '../contract-schema/index.mts';
+import type { RouteBinding } from './response-contract-route-analysis.mts';
+import type { RouteDiscoveryError } from './response-contract-lenient.mts';
+import type { BackendRequestContract } from './request-contract-types.mts';
+export type DiscoverApiRequestContractsOptions = ExtractContractSchemaOptions & {
+    onRouteError?: (error: RouteDiscoveryError) => void;
+};
+/**
+ * Marks `key` unavailable regardless of AST visit order or what else is already registered for
+ * this route (an explicit marker, or an earlier implicit harvest) — a raw buffered body's shape
+ * is never statically determinable, so it always wins. Mirrors the response side's
+ * `markBufferedRouteUnavailable` for `ctx.response.buffer(...)`.
+ */
+export declare function markBufferedRequestRouteUnavailable(contracts: Map<string, BackendRequestContract>, key: string, binding: RouteBinding, source: string): void;
+/**
+ * Inserts `contract` at `key`, throwing if `key` already resolves to a different schema. Requests
+ * have no `#variant` escape hatch, so — unlike the response side, where a genuine collision is
+ * always a real author bug worth surfacing — callers here must choose deliberately whether a
+ * mismatch should throw (an explicit marker collision) or be caught (an implicit harvest
+ * collision); see `request-contract-implicit.mts`.
+ */
+export declare function registerRequestContract(contracts: Map<string, BackendRequestContract>, key: string, contract: BackendRequestContract): void;
+/**
+ * Extracts a route's request contract and registers it. When `options.onRouteError` is set, an
+ * extraction failure is caught, reported, and replaced with an `unavailable` placeholder instead
+ * of aborting discovery for every other route — mirrors the response side's `registerRouteContract`.
+ */
+export declare function registerRequestRouteContract(contracts: Map<string, BackendRequestContract>, key: string, binding: RouteBinding, location: string, extract: () => ExtractedResponseContract, options: DiscoverApiRequestContractsOptions | undefined): void;

package/dist/api-contract-discovery/request-contract-lenient.mjs

@@ -0,0 +1,59 @@
+import { hashContractSchema } from '../contract-schema/index.mjs';
+/** Placeholder contract for a route whose request body could not be extracted. */
+function unavailableRequestContract(source, reason) {
+    const schema = { root: { type: 'unknown' }, definitions: {} };
+    return { source, schema, hash: hashContractSchema(schema), unavailableReason: reason };
+}
+/**
+ * Marks `key` unavailable regardless of AST visit order or what else is already registered for
+ * this route (an explicit marker, or an earlier implicit harvest) — a raw buffered body's shape
+ * is never statically determinable, so it always wins. Mirrors the response side's
+ * `markBufferedRouteUnavailable` for `ctx.response.buffer(...)`.
+ */
+export function markBufferedRequestRouteUnavailable(contracts, key, binding, source) {
+    contracts.set(key, {
+        ...unavailableRequestContract(source, 'route reads a raw buffered request body (ctx.request.buffer) whose shape is not statically determinable'),
+        ...binding,
+    });
+}
+/**
+ * Inserts `contract` at `key`, throwing if `key` already resolves to a different schema. Requests
+ * have no `#variant` escape hatch, so — unlike the response side, where a genuine collision is
+ * always a real author bug worth surfacing — callers here must choose deliberately whether a
+ * mismatch should throw (an explicit marker collision) or be caught (an implicit harvest
+ * collision); see `request-contract-implicit.mts`.
+ */
+export function registerRequestContract(contracts, key, contract) {
+    const existing = contracts.get(key);
+    if (!existing) {
+        contracts.set(key, contract);
+        return;
+    }
+    if (existing.hash !== contract.hash) {
+        throw new Error(`Backend request contract "${key}" resolves to multiple backend request schemas at ${existing.source} and ${contract.source}`);
+    }
+}
+/**
+ * Extracts a route's request contract and registers it. When `options.onRouteError` is set, an
+ * extraction failure is caught, reported, and replaced with an `unavailable` placeholder instead
+ * of aborting discovery for every other route — mirrors the response side's `registerRouteContract`.
+ */
+export function registerRequestRouteContract(contracts, key, binding, location, extract, options) {
+    let extracted;
+    try {
+        extracted = extract();
+    }
+    catch (error) {
+        if (!options?.onRouteError)
+            throw error;
+        const reason = error instanceof Error ? error.message : String(error);
+        options.onRouteError({
+            method: binding.method,
+            routeTemplate: binding.routeTemplate,
+            source: location,
+            reason,
+        });
+        extracted = unavailableRequestContract(location, reason);
+    }
+    registerRequestContract(contracts, key, { ...extracted, ...binding });
+}

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

@@ -0,0 +1,14 @@
+import ts from '../contract-schema/typescript-api.mts';
+import { type DiscoverApiRequestContractsOptions } from './request-contract-lenient.mts';
+import type { BackendRequestContract } from './request-contract-types.mts';
+export type { BackendRequestContract } from './request-contract-types.mts';
+export type { DiscoverApiRequestContractsOptions } from './request-contract-lenient.mts';
+/**
+ * Two full passes over every route file, mirroring `discoverApiResponseContracts`: Phase 1
+ * (explicit request-contract markers) completes for every file before Phase 2
+ * (implicit harvest of `parseJsonBody`/`ctx.request.json(...) as T`/`ctx.request.buffer(...)`)
+ * begins, so a marker anywhere always wins over a harvest anywhere regardless of visit order.
+ * `markerKeys` records every key an explicit marker claimed (a body, or a deliberate
+ * `apiNoRequestBody` suppression) so Phase 2 knows to never harvest over it.
+ */
+export declare function discoverApiRequestContracts(program: ts.Program, sourceFiles: readonly ts.SourceFile[], requestedKeys?: ReadonlySet<string>, options?: DiscoverApiRequestContractsOptions): Record<string, BackendRequestContract>;

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

@@ -0,0 +1,61 @@
+import ts from '../contract-schema/typescript-api.mjs';
+import { extractContractSchema } from '../contract-schema/index.mjs';
+import { registerRequestRouteContract, } from './request-contract-lenient.mjs';
+import { discoverImplicitRequestContract } from './request-contract-implicit.mjs';
+import { requestMarker } from './request-contract-route-analysis.mjs';
+import { contractError, sourceLocation } from './response-contract-registration.mjs';
+import { collectHandlerBindings, enclosingRouteBinding, visit, } from './response-contract-route-analysis.mjs';
+/**
+ * Two full passes over every route file, mirroring `discoverApiResponseContracts`: Phase 1
+ * (explicit request-contract markers) completes for every file before Phase 2
+ * (implicit harvest of `parseJsonBody`/`ctx.request.json(...) as T`/`ctx.request.buffer(...)`)
+ * begins, so a marker anywhere always wins over a harvest anywhere regardless of visit order.
+ * `markerKeys` records every key an explicit marker claimed (a body, or a deliberate
+ * `apiNoRequestBody` suppression) so Phase 2 knows to never harvest over it.
+ */
+export function discoverApiRequestContracts(program, sourceFiles, requestedKeys, options) {
+    const checker = program.getTypeChecker();
+    const contracts = new Map();
+    const markerKeys = new Set();
+    const handlerBindings = collectHandlerBindings(sourceFiles, checker);
+    for (const sourceFile of sourceFiles) {
+        visit(sourceFile, (node) => {
+            if (!ts.isCallExpression(node))
+                return;
+            const marker = requestMarker(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 expectedKey = `${binding.method}:${binding.routeTemplate}`;
+            if (keyNode.text !== expectedKey) {
+                // Requests have no `#variant` escape hatch (unlike responses) — the key must match exactly.
+                throw contractError(sourceFile, keyNode, `Contract key "${keyNode.text}" does not match enclosing route ${expectedKey}`);
+            }
+            markerKeys.add(keyNode.text);
+            if (marker === 'apiNoRequestBody')
+                return; // Deliberate suppression: no contract, harvest skips this key.
+            const bodyNode = node.arguments[1];
+            const typeNode = node.typeArguments?.[1];
+            if (marker === 'apiRequest' && !bodyNode)
+                throw contractError(sourceFile, node, 'apiRequest requires a request body');
+            if (marker === 'apiRequestContract' && !typeNode)
+                throw contractError(sourceFile, node, 'apiRequestContract requires a request body type');
+            const location = sourceLocation(sourceFile, node);
+            registerRequestRouteContract(contracts, keyNode.text, binding, location, () => extractContractSchema(typeNode ? checker.getTypeFromTypeNode(typeNode) : checker.getTypeAtLocation(bodyNode), checker, location, options), options);
+        });
+    }
+    for (const sourceFile of sourceFiles) {
+        visit(sourceFile, (node) => {
+            if (!ts.isCallExpression(node) || requestMarker(node.expression))
+                return;
+            discoverImplicitRequestContract(node, checker, sourceFile, contracts, markerKeys, handlerBindings, requestedKeys, options);
+        });
+    }
+    return Object.fromEntries([...contracts.entries()].toSorted(([left], [right]) => left.localeCompare(right)));
+}

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

@@ -0,0 +1,25 @@
+import ts from '../contract-schema/typescript-api.mts';
+/**
+ * Detects the request-contract markers in the version-one route convention.
+ * Kept out of `responseMarker` (which only recognizes `apiResponse`/`apiNoContent`) so the two
+ * AST walks never interfere — see `response-contract-route-analysis.mts` for the response side.
+ */
+export declare function requestMarker(expression: ts.Expression): 'apiRequest' | 'apiRequestContract' | 'apiNoRequestBody' | undefined;
+/**
+ * Detects `ctx.request.json(...)`: a two-level nested access (`ctx.request` then `.json`) that
+ * `isContextMethod`'s single-level match can't see through directly — mirrors
+ * `isContextResponseBufferCall`'s own two-level pattern on the response side.
+ */
+export declare function isContextRequestJsonCall(expression: ts.Expression): boolean;
+/** Detects `ctx.request.buffer(...)`: a raw request body whose shape can't be statically extracted. */
+export declare function isContextRequestBufferCall(expression: ts.Expression): boolean;
+/**
+ * Walks up from a `ctx.request.json(...)` call expression to find the enclosing `as T` cast that
+ * gives it a static type, unwrapping the wrapper shapes real call sites use in between:
+ * `(await ctx.request.json(...)) as T` and the `.catch()`-guarded
+ * `(await ctx.request.json(...).catch(() => ({}))) as T`.
+ * Returns `undefined` when no enclosing cast exists (e.g. the read feeds directly into another
+ * call, `parseFoo(await ctx.request.json())`) — the caller treats that as an honest untyped
+ * success, not a failure.
+ */
+export declare function enclosingRequestBodyCast(call: ts.CallExpression): ts.AsExpression | undefined;