vouchington-tooling 0.32.0 → 0.34.0

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

@@ -1,7 +1,10 @@
 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';
-const HTTP_METHODS = new Set(['GET', 'POST', 'PUT', 'PATCH', 'DELETE']);
 export function requestedKeyForBinding(binding, requestedKeys) {
     if (!requestedKeys)
         return `${binding.method}:${binding.routeTemplate}`;
@@ -57,106 +60,6 @@ export function enclosingRouteBinding(node, checker, handlerBindings, proveCallb
     }
     return undefined;
 }
-export function collectHandlerBindings(sourceFiles, checker) {
-    const bindingsBySymbol = new Map();
-    for (const sourceFile of sourceFiles) {
-        visit(sourceFile, (node) => {
-            if (!ts.isCallExpression(node))
-                return;
-            const method = propertyName(node.expression)?.toUpperCase();
-            if (!method || !HTTP_METHODS.has(method))
-                return;
-            const routeTemplate = routeTemplateFromExpression(node.expression);
-            if (!routeTemplate)
-                return;
-            const binding = { method, routeTemplate };
-            for (const symbol of handlerArgumentSymbols(node, checker)) {
-                const resolved = resolveSymbol(symbol, checker);
-                const candidates = bindingsBySymbol.get(resolved) ?? [];
-                candidates.push(binding);
-                bindingsBySymbol.set(resolved, candidates);
-            }
-        });
-    }
-    const bindings = new Map();
-    for (const [symbol, candidates] of bindingsBySymbol) {
-        const [first] = candidates;
-        const unambiguous = candidates.every((candidate) => candidate.method === first.method && candidate.routeTemplate === first.routeTemplate);
-        // A symbol bound to more than one distinct route (a genuinely shared handler function) can't
-        // be attributed to either one — recording an arbitrary winner would misdocument whichever
-        // route lost.
-        if (unambiguous)
-            bindings.set(symbol, first);
-    }
-    return bindings;
-}
-/**
- * Symbols a route registration call directly implicates: identifiers passed by reference
- * (`app.route(...).post(handleThing)`), and — for an inline handler argument — every plain named
- * function it calls directly, e.g. `app.route(...).post(async ctx => { await handleThing(ctx) })`.
- * `enclosingRouteBinding`'s lexical walk can't see through the latter case on its own, since
- * `handleThing`'s body isn't lexically nested inside the route registration at all; recording its
- * symbol here lets the same `handlerBindings` lookup resolve it.
- */
-function handlerArgumentSymbols(node, checker) {
-    const symbols = [];
-    for (const argument of node.arguments) {
-        if (ts.isIdentifier(argument)) {
-            const symbol = checker.getSymbolAtLocation(argument);
-            if (symbol)
-                symbols.push(symbol);
-            continue;
-        }
-        if (isFunctionLike(argument)) {
-            visit(argument, (child) => {
-                if (!ts.isCallExpression(child) ||
-                    !ts.isIdentifier(child.expression) ||
-                    !executableProtocolPath(child, checker))
-                    return;
-                const symbol = checker.getSymbolAtLocation(child.expression);
-                if (symbol)
-                    symbols.push(symbol);
-            });
-        }
-    }
-    return symbols;
-}
-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;
-}
-function resolveSymbol(symbol, checker) {
-    return symbol.flags & ts.SymbolFlags.Alias ? checker.getAliasedSymbol(symbol) : symbol;
-}
-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;
-}
 function isFunctionLike(node) {
     return ts.isArrowFunction(node) || ts.isFunctionExpression(node);
 }
-export function visit(node, callback) {
-    callback(node);
-    node.forEachChild((child) => visit(child, callback));
-}

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

@@ -0,0 +1,7 @@
+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

@@ -0,0 +1,41 @@
+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-symbols.d.mts

@@ -0,0 +1,5 @@
+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

@@ -0,0 +1,82 @@
+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/basic-auth-doc-sync/index.d.mts

@@ -0,0 +1,3 @@
+export { findBasicAuthExemptPaths, findBasicAuthExemptMethodsByPath } from './source.mts';
+export { findRunbookExemptRoutes } from './runbook.mts';
+export type { ExemptRoute } from './runbook.mts';

package/dist/basic-auth-doc-sync/index.mjs

@@ -0,0 +1,2 @@
+export { findBasicAuthExemptPaths, findBasicAuthExemptMethodsByPath } from './source.mjs';
+export { findRunbookExemptRoutes } from './runbook.mjs';

package/dist/basic-auth-doc-sync/methods.d.mts

@@ -0,0 +1 @@
+export declare function isCanonicalHttpMethod(method: string): boolean;

package/dist/basic-auth-doc-sync/methods.mjs

@@ -0,0 +1,4 @@
+const HTTP_METHOD_TOKEN_RE = /^[!#$%&'*+\-.^_`|~0-9A-Z]+$/;
+export function isCanonicalHttpMethod(method) {
+    return method === method.toUpperCase() && HTTP_METHOD_TOKEN_RE.test(method);
+}

package/dist/basic-auth-doc-sync/runbook.d.mts

@@ -0,0 +1,5 @@
+export type ExemptRoute = {
+    methods: string[];
+    path: string;
+};
+export declare function findRunbookExemptRoutes(markdown: string, heading: string): ExemptRoute[] | null;

package/dist/basic-auth-doc-sync/runbook.mjs

@@ -0,0 +1,59 @@
+import { parseGfmMarkdown } from '../markdown/ast.mjs';
+import { markdownNodeText } from '../markdown/text.mjs';
+import { parseMarkdownTables } from '../markdown/tables.mjs';
+import { isCanonicalHttpMethod } from './methods.mjs';
+const METHODS_CELL_RE = /^`[^`]+`(?:\s*,\s*`[^`]+`)*$/;
+function codeText(cell) {
+    const match = /^`([^`]+)`$/.exec(cell);
+    return match?.[1] ?? null;
+}
+function methodTexts(cell) {
+    if (!METHODS_CELL_RE.test(cell))
+        return null;
+    const methods = Array.from(cell.matchAll(/`([^`]+)`/g), (match) => match[1]).filter((value) => value !== undefined);
+    return methods.every(isCanonicalHttpMethod) ? methods : null;
+}
+function tableHeaderColumns(cells) {
+    const columns = new Map();
+    for (const [index, cell] of cells.entries()) {
+        const name = cell.toLowerCase();
+        if ((name === 'path' || name === 'methods') && columns.has(name))
+            return null;
+        columns.set(name, index);
+    }
+    return columns;
+}
+export function findRunbookExemptRoutes(markdown, heading) {
+    const children = parseGfmMarkdown(markdown).children;
+    const headingIndex = children.findIndex((node) => node.type === 'heading' &&
+        node.depth === 3 &&
+        markdownNodeText(node, { whitespace: 'collapse' }).toLowerCase() === heading.toLowerCase());
+    if (headingIndex === -1)
+        return null;
+    const endIndex = children.findIndex((node, index) => index > headingIndex && node.type === 'heading' && node.depth <= 3);
+    const startOffset = children[headingIndex].position.end.offset;
+    const endOffset = endIndex === -1 ? markdown.length : children[endIndex].position.start.offset;
+    const table = parseMarkdownTables(markdown.slice(startOffset, endOffset), {
+        preserveInlineCodeMarkers: true,
+    })[0];
+    if (!table || table.length < 2)
+        return null;
+    const routes = [];
+    const columns = tableHeaderColumns(table[0].cells);
+    if (!columns)
+        return null;
+    const pathColumn = columns.get('path') ?? -1;
+    const methodsColumn = columns.get('methods') ?? -1;
+    if (pathColumn === -1 || methodsColumn === -1)
+        return null;
+    for (const row of table.slice(1)) {
+        const path = codeText(row.cells[pathColumn] ?? '');
+        const methods = methodTexts(row.cells[methodsColumn] ?? '');
+        if (!path)
+            return null;
+        if (!methods || methods.length === 0)
+            return null;
+        routes.push({ methods, path });
+    }
+    return routes;
+}

package/dist/basic-auth-doc-sync/source.d.mts

@@ -0,0 +1,2 @@
+export declare function findBasicAuthExemptPaths(code: string, variableName: string): string[] | null;
+export declare function findBasicAuthExemptMethodsByPath(code: string, variableName: string): Map<string, string[]> | null;

package/dist/basic-auth-doc-sync/source.mjs

@@ -0,0 +1,71 @@
+import ts from '../contract-schema/typescript-api.mjs';
+import { isCanonicalHttpMethod } from './methods.mjs';
+export function findBasicAuthExemptPaths(code, variableName) {
+    const declaration = findTopLevelConstInitializer(code, variableName);
+    if (!declaration)
+        return null;
+    return stringSetValues(declaration);
+}
+export function findBasicAuthExemptMethodsByPath(code, variableName) {
+    const declaration = findTopLevelConstInitializer(code, variableName);
+    if (!declaration || !isNewCollectionExpression(declaration, 'Map'))
+        return null;
+    const [entriesArg] = declaration.arguments ?? [];
+    if (!entriesArg || !ts.isArrayLiteralExpression(entriesArg))
+        return null;
+    const entries = new Map();
+    for (const entry of entriesArg.elements) {
+        if (!ts.isArrayLiteralExpression(entry) || entry.elements.length !== 2)
+            return null;
+        const path = stringLiteralValue(entry.elements[0]);
+        const methods = stringSetValues(entry.elements[1]);
+        if (!path || !methods || methods.length === 0)
+            return null;
+        if (!methods.every(isCanonicalHttpMethod))
+            return null;
+        entries.set(path, methods);
+    }
+    return entries.size > 0 ? entries : null;
+}
+function findTopLevelConstInitializer(code, name) {
+    const source = ts.createSourceFile('basic-auth.mts', code, ts.ScriptTarget.Latest, false, ts.ScriptKind.TS);
+    for (const statement of source.statements) {
+        if (!ts.isVariableStatement(statement))
+            continue;
+        if ((statement.declarationList.flags & ts.NodeFlags.Const) === 0)
+            continue;
+        for (const declaration of statement.declarationList.declarations) {
+            if (!ts.isIdentifier(declaration.name) || declaration.name.text !== name)
+                continue;
+            return declaration.initializer ?? null;
+        }
+    }
+    return null;
+}
+function stringSetValues(expression) {
+    if (!expression || !isNewCollectionExpression(expression, 'Set'))
+        return null;
+    const [valuesArg] = expression.arguments ?? [];
+    if (!valuesArg || !ts.isArrayLiteralExpression(valuesArg))
+        return null;
+    const values = [];
+    for (const element of valuesArg.elements) {
+        const value = stringLiteralValue(element);
+        if (!value)
+            return null;
+        values.push(value);
+    }
+    return values.length > 0 ? values : null;
+}
+function stringLiteralValue(expression) {
+    if (expression &&
+        (ts.isStringLiteral(expression) || ts.isNoSubstitutionTemplateLiteral(expression))) {
+        return expression.text;
+    }
+    return null;
+}
+function isNewCollectionExpression(expression, collectionName) {
+    return (ts.isNewExpression(expression) &&
+        ts.isIdentifier(expression.expression) &&
+        expression.expression.text === collectionName);
+}

package/dist/compiler-build/index.d.mts

@@ -1,2 +1,4 @@
 export { compilerHostProbesAreFresh, trackCompilerHost, type CompilerFilesystemHost, type CompilerHostProbeSnapshot, type CompilerHostTrackingOptions, } from './freshness.mts';
 export { settleBuild, type SettlementCallbacks, type SettlementConfirmation, } from './settlement.mts';
+export { createCompilerProgramCache } from './program.mts';
+export type { CompilerProgramCache, CompilerProgramCacheOptions, CompilerProgramGeneration, CompilerProgramSnapshot, } from './program-types.mts';

package/dist/compiler-build/index.mjs

@@ -1,2 +1,3 @@
 export { compilerHostProbesAreFresh, trackCompilerHost, } from './freshness.mjs';
 export { settleBuild, } from './settlement.mjs';
+export { createCompilerProgramCache } from './program.mjs';

package/dist/compiler-build/program-configuration.d.mts

@@ -0,0 +1,9 @@
+import type ts from '@typescript/typescript6';
+import type { CompilerProgramCacheOptions } from './program-types.mts';
+export interface CompilerProgramConfiguration {
+    parsed: ts.ParsedCommandLine;
+    roots: string[];
+    selectedSources: Set<string> | undefined;
+    signature: string;
+}
+export declare function readProgramConfiguration(api: typeof ts, input: CompilerProgramCacheOptions): CompilerProgramConfiguration;

package/dist/compiler-build/program-configuration.mjs

@@ -0,0 +1,28 @@
+import { dirname, resolve } from 'node:path';
+export function readProgramConfiguration(api, input) {
+    const configPath = resolve(input.configPath);
+    const directory = dirname(configPath);
+    const config = api.readConfigFile(configPath, (file) => api.sys.readFile(file));
+    const format = (diagnostics) => api.formatDiagnosticsWithColorAndContext(diagnostics, {
+        getCanonicalFileName: (file) => file,
+        getCurrentDirectory: () => directory,
+        getNewLine: () => '\n',
+    });
+    if (config.error)
+        throw new Error(format([config.error]));
+    const parsed = api.parseJsonConfigFileContent(config.config, api.sys, directory, undefined, configPath);
+    if (parsed.errors.length > 0)
+        throw new Error(format(parsed.errors));
+    const rootNames = typeof input.rootNames === 'function' ? input.rootNames(parsed) : input.rootNames;
+    const roots = (rootNames ?? parsed.fileNames).map((file) => resolve(directory, file));
+    const names = typeof input.sourceFilePaths === 'function' ? input.sourceFilePaths() : input.sourceFilePaths;
+    const selectedSources = names && new Set(names.map((file) => resolve(directory, file)));
+    const signature = JSON.stringify({
+        config: config.config,
+        options: parsed.options,
+        projectReferences: parsed.projectReferences?.map((reference) => reference.path),
+        roots,
+        sources: selectedSources && [...selectedSources].toSorted(),
+    });
+    return { parsed, roots, selectedSources, signature };
+}

package/dist/compiler-build/program-types.d.mts

@@ -0,0 +1,29 @@
+import type ts from '@typescript/typescript6';
+import type { CompilerHostTrackingOptions } from './freshness.mts';
+declare const generationBrand: unique symbol;
+/** Identity changes on each rebuild, including after clear(). */
+export type CompilerProgramGeneration = {
+    readonly [generationBrand]: true;
+};
+export interface CompilerProgramSnapshot {
+    readonly generation: CompilerProgramGeneration;
+    readonly program: ts.Program;
+    readonly sourceFiles: readonly ts.SourceFile[];
+}
+export interface CompilerProgramCache {
+    load(): CompilerProgramSnapshot;
+    clear(): void;
+    readonly buildCount: number;
+}
+export interface CompilerProgramCacheOptions {
+    /** Inject a compiler; otherwise load the optional peer when constructing this cache. */
+    ts?: typeof ts;
+    configPath: string;
+    /** Relative names resolve beside configPath; the callback selects parsed roots on each load. */
+    rootNames?: readonly string[] | ((configuration: ts.ParsedCommandLine) => readonly string[]);
+    /** Omit to return all sources; relative paths resolve beside configPath. */
+    sourceFilePaths?: readonly string[] | (() => readonly string[]);
+    maximumAttempts?: number;
+    tracking?: CompilerHostTrackingOptions;
+}
+export {};

package/dist/compiler-build/program-types.mjs

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

package/dist/compiler-build/program.d.mts

@@ -0,0 +1,7 @@
+import type { CompilerProgramCache, CompilerProgramCacheOptions } from './program-types.mts';
+/**
+ * Reuses a real Program while configuration, roots and recorded filesystem probes are unchanged.
+ * Rebuilds release the cache's old generation before allocating another Program. Callers retaining
+ * old snapshots still own those references; clear() cannot release caller data.
+ */
+export declare function createCompilerProgramCache(input: CompilerProgramCacheOptions): CompilerProgramCache;

package/dist/compiler-build/program.mjs

@@ -0,0 +1,78 @@
+import { createRequire } from 'node:module';
+import { resolve } from 'node:path';
+import { compilerHostProbesAreFresh, trackCompilerHost, } from './freshness.mjs';
+import { readProgramConfiguration } from './program-configuration.mjs';
+import { settleBuild } from './settlement.mjs';
+/**
+ * Reuses a real Program while configuration, roots and recorded filesystem probes are unchanged.
+ * Rebuilds release the cache's old generation before allocating another Program. Callers retaining
+ * old snapshots still own those references; clear() cannot release caller data.
+ */
+export function createCompilerProgramCache(input) {
+    const api = input.ts ?? createRequire(import.meta.url)('@typescript/typescript6');
+    const maximumAttempts = input.maximumAttempts ?? 3;
+    let cached;
+    let buildCount = 0;
+    const readConfiguration = () => {
+        try {
+            return readProgramConfiguration(api, input);
+        }
+        catch (error) {
+            cached = undefined;
+            throw error;
+        }
+    };
+    return {
+        get buildCount() {
+            return buildCount;
+        },
+        clear() {
+            cached = undefined;
+        },
+        load() {
+            const configuration = readConfiguration();
+            if (cached?.signature === configuration.signature &&
+                compilerHostProbesAreFresh(cached.probes()))
+                return cached;
+            cached = undefined;
+            const settled = settleBuild(configuration, maximumAttempts, {
+                buildAttempt(current) {
+                    const tracker = trackCompilerHost(api.createCompilerHost(current.parsed.options, true), {
+                        readFileReplay: 'when-filesystem-metadata-stable',
+                        ...input.tracking,
+                    });
+                    buildCount += 1;
+                    const program = api.createProgram({
+                        host: tracker.host,
+                        options: current.parsed.options,
+                        rootNames: current.roots,
+                        ...(current.parsed.projectReferences && {
+                            projectReferences: current.parsed.projectReferences,
+                        }),
+                    });
+                    // Compiler consumers may issue more host reads after construction; retain their probes.
+                    return { configuration: current, probes: () => tracker.snapshot(), program };
+                },
+                confirmAttempt(current, value) {
+                    const confirmed = readConfiguration();
+                    return {
+                        configuration: confirmed,
+                        settled: current.signature === confirmed.signature &&
+                            compilerHostProbesAreFresh(value.probes()),
+                    };
+                },
+            });
+            const selected = settled.configuration.selectedSources;
+            cached = {
+                generation: Object.freeze({}),
+                program: settled.program,
+                sourceFiles: settled.program
+                    .getSourceFiles()
+                    .filter((file) => !selected || selected.has(resolve(file.fileName))),
+                signature: settled.configuration.signature,
+                probes: settled.probes,
+            };
+            return cached;
+        },
+    };
+}

package/dist/contract-schema/index.d.mts

@@ -7,3 +7,7 @@ export { validateResponseContract } from './contract-schema-validator.mts';
 export type { ContractValidationIssue, ExtractContractSchemaOptions, ExtractedResponseContract, } from './types.mts';
 export { buildVirtualProgramMatrix, virtualProgramBuildCountForTest } from './virtual-program.mts';
 export type { VirtualProgramMatrix } from './virtual-program.mts';
+export { getExportedTypeFacts } from './type-query.mts';
+export type { ExportedTypeFactsRequest, TypeFacts, TypeFactsRequest, ExportedTypeSelector, TypeScriptApi, TypeScriptProgram, } from './type-query.mts';
+export { getCallRowTypeFacts } from './type-query-call.mts';
+export type { CallRowTypeFacts, CallRowTypeFactsRequest } from './type-query-call.mts';

package/dist/contract-schema/index.mjs

@@ -3,3 +3,5 @@ export { extractResponseContracts } from './contract-schema-extractor.mjs';
 export { extractContractSchema } from './contract-schema-type-extractor.mjs';
 export { validateResponseContract } from './contract-schema-validator.mjs';
 export { buildVirtualProgramMatrix, virtualProgramBuildCountForTest } from './virtual-program.mjs';
+export { getExportedTypeFacts } from './type-query.mjs';
+export { getCallRowTypeFacts } from './type-query-call.mjs';

package/dist/contract-schema/type-query-api.d.mts

@@ -0,0 +1,44 @@
+import type ts from './typescript-api.mts';
+type NodePredicate<Node extends ts.Node> = {
+    check(node: ts.Node): node is Node;
+}['check'];
+type ForEachChild = {
+    visit(node: ts.Node, callback: (child: ts.Node) => void): void;
+}['visit'];
+export interface TypeScriptApi {
+    readonly IndexKind: {
+        readonly Number: number;
+        readonly String: number;
+    };
+    readonly SymbolFlags: {
+        readonly Alias: number;
+        readonly Type: number;
+        readonly Value: number;
+    };
+    readonly SyntaxKind: {
+        readonly SourceFile: number;
+    };
+    readonly TypeFlags: {
+        readonly Any: number;
+        readonly Never: number;
+    };
+    readonly TypeFormatFlags: {
+        readonly NoTruncation: ts.TypeFormatFlags.NoTruncation;
+    };
+    readonly forEachChild: ForEachChild;
+    readonly isClassDeclaration: NodePredicate<ts.ClassDeclaration>;
+    readonly isCallExpression: NodePredicate<ts.CallExpression>;
+    readonly isFunctionDeclaration: NodePredicate<ts.FunctionDeclaration>;
+    readonly isInterfaceDeclaration: NodePredicate<ts.InterfaceDeclaration>;
+    readonly isIdentifier: NodePredicate<ts.Identifier>;
+    readonly isSourceFile: NodePredicate<ts.SourceFile>;
+    readonly isTypeReferenceNode: NodePredicate<ts.TypeReferenceNode>;
+    readonly isTypeAliasDeclaration: NodePredicate<ts.TypeAliasDeclaration>;
+}
+export interface TypeScriptProgram {
+    getSourceFile(fileName: string): unknown;
+    getTypeChecker(): unknown;
+}
+export declare function programForQuery(program: TypeScriptProgram): ts.Program;
+export declare function validateTypeScriptApi(typescript: TypeScriptApi, program: TypeScriptProgram, sourceFile: ts.SourceFile): void;
+export {};