vouchington-tooling 0.15.1 → 0.16.0

package/README.md

@@ -6,6 +6,9 @@ Libraries and the `vouchington` CLI.
 npm install vouchington-tooling
 # optional, only if you import vouchington-tooling/sql-ast
 npm install @libpg-query/parser
+# optional, only if you import vouchington-tooling/contract-schema
+# (classic compiler API; typescript@7's package root is version-only)
+npm install @typescript/typescript6
 # optional, only for vouchington-tooling/agent-blackboard and agent-blackboard CLI commands
 npm install agent-blackboard@^0.5.0
 ```
@@ -192,6 +195,15 @@ import {
   renderSchemaMarkdown,
 } from 'vouchington-tooling/pg-schema-snapshot'
 import { buildOpenApiDocument, writeOpenApi } from 'vouchington-tooling/openapi-document'
+import {
+  extractResponseContracts,
+  validateResponseContract,
+} from 'vouchington-tooling/contract-schema'
+import {
+  buildFixtureSchemaLock,
+  validateFixtureContracts,
+  writeGeneratedFiles,
+} from 'vouchington-tooling/api-fixtures'
 import { decide, deriveRetryAttempt } from 'vouchington-tooling/transient-retry'
 import { parseCsvRows, streamCsvRows } from 'vouchington-tooling/csv'
 import {

package/dist/api-fixtures/fixture-contract-validation.d.mts

@@ -0,0 +1,22 @@
+import type { ContractSchema } from '../openapi-document/contract-schema-types.mts';
+export type FixtureValidationCase = {
+    id: string;
+    method: string;
+    route: {
+        routeTemplate: string;
+    };
+    status: number;
+    body: unknown;
+    backendResponseContractKey: string;
+};
+export type FixtureValidationContract = {
+    method: string;
+    routeTemplate: string;
+    schema: ContractSchema;
+    statusCodes?: readonly number[];
+};
+export type ValidateFixtureContractsOptions = {
+    routeShape: (routeTemplate: string) => string;
+    statusCodesForContract: (contract: FixtureValidationContract) => number[];
+};
+export declare function validateFixtureContracts(fixtureCases: readonly FixtureValidationCase[], contracts: Record<string, FixtureValidationContract>, options: ValidateFixtureContractsOptions): void;

package/dist/api-fixtures/fixture-contract-validation.mjs

@@ -0,0 +1,36 @@
+import { validateResponseContract } from '../contract-schema/contract-schema-validator.mjs';
+export function validateFixtureContracts(fixtureCases, contracts, options) {
+    const usedKeys = new Set();
+    const errors = [];
+    for (const fixtureCase of fixtureCases) {
+        const key = fixtureCase.backendResponseContractKey;
+        const contract = contracts[key];
+        if (!contract) {
+            errors.push(`${fixtureCase.id}: response contract "${key}" was not found`);
+            continue;
+        }
+        usedKeys.add(key);
+        const fixtureOperation = `${fixtureCase.method}:${fixtureCase.route.routeTemplate}`;
+        const contractOperation = `${contract.method}:${contract.routeTemplate}`;
+        if (fixtureCase.method !== contract.method ||
+            options.routeShape(fixtureCase.route.routeTemplate) !==
+                options.routeShape(contract.routeTemplate)) {
+            errors.push(`${fixtureCase.id}: fixture operation ${fixtureOperation} does not match response contract "${key}" (${contractOperation})`);
+            continue;
+        }
+        const statuses = options.statusCodesForContract(contract);
+        if (!statuses.includes(fixtureCase.status)) {
+            errors.push(`${fixtureCase.id}: status ${fixtureCase.status} is not declared by response contract "${key}" (${contractOperation}); available statuses: ${statuses.join(', ') || 'none (status unknown)'}`);
+        }
+        for (const issue of validateResponseContract(contract.schema, fixtureCase.body)) {
+            errors.push(`${fixtureCase.id} ${issue.path}: ${issue.message}`);
+        }
+    }
+    for (const key of Object.keys(contracts)) {
+        if (!usedKeys.has(key))
+            errors.push(`Response contract "${key}" is not used by a fixture`);
+    }
+    if (errors.length > 0) {
+        throw new Error(['Fixture contract validation failed:', ...errors].join('\n'));
+    }
+}

package/dist/api-fixtures/index.d.mts

@@ -0,0 +1,3 @@
+export { validateFixtureContracts, type FixtureValidationCase, type FixtureValidationContract, type ValidateFixtureContractsOptions, } from './fixture-contract-validation.mts';
+export { buildFixtureSchemaLock, responseSchemaFor, type FixtureSchemaLock, type FixtureSchemaLockCase, type FixtureSchemaLockSource, } from './schema-lock.mts';
+export { writeGeneratedFiles } from './write-generated-files.mts';

package/dist/api-fixtures/index.mjs

@@ -0,0 +1,3 @@
+export { validateFixtureContracts, } from './fixture-contract-validation.mjs';
+export { buildFixtureSchemaLock, responseSchemaFor, } from './schema-lock.mjs';
+export { writeGeneratedFiles } from './write-generated-files.mjs';

package/dist/api-fixtures/schema-lock.d.mts

@@ -0,0 +1,35 @@
+export type FixtureSchemaLockSource = {
+    kind: 'generated';
+    generator: string;
+    caseRoot: string;
+};
+export type FixtureSchemaLock = {
+    version: 2;
+    source: FixtureSchemaLockSource;
+    schemas: Record<string, {
+        hash: string;
+        fixtureIds: string[];
+    }>;
+    backendResponseContracts: Record<string, {
+        hash: string;
+        fixtureIds: string[];
+    }>;
+};
+export type FixtureSchemaLockCase = {
+    id: string;
+    responseSchemaKey?: string;
+    body: unknown;
+    backendResponseContractKey: string;
+};
+export declare function responseSchemaFor(id: string, key: string | undefined, body: unknown, discriminatorKeys: ReadonlySet<string>): {
+    key: string;
+    hash: string;
+};
+export declare function buildFixtureSchemaLock({ cases, backendContracts, discriminatorKeys, source, }: {
+    cases: readonly FixtureSchemaLockCase[];
+    backendContracts: Record<string, {
+        hash: string;
+    }>;
+    discriminatorKeys: ReadonlySet<string>;
+    source: FixtureSchemaLockSource;
+}): FixtureSchemaLock;

package/dist/api-fixtures/schema-lock.mjs

@@ -0,0 +1,125 @@
+import { createHash } from 'node:crypto';
+export function responseSchemaFor(id, key, body, discriminatorKeys) {
+    return {
+        key: key ?? id,
+        hash: createHash('sha256')
+            .update(stableSchemaStringify(schemaShape(body, discriminatorKeys)))
+            .digest('hex'),
+    };
+}
+export function buildFixtureSchemaLock({ cases, backendContracts, discriminatorKeys, source, }) {
+    const schemas = new Map();
+    const casesById = new Map(cases.map((fixtureCase) => [fixtureCase.id, fixtureCase]));
+    const fixtureIdsByBackendContract = new Map();
+    for (const fixtureCase of cases) {
+        const backendFixtureIds = fixtureIdsByBackendContract.get(fixtureCase.backendResponseContractKey);
+        if (backendFixtureIds)
+            backendFixtureIds.push(fixtureCase.id);
+        else
+            fixtureIdsByBackendContract.set(fixtureCase.backendResponseContractKey, [fixtureCase.id]);
+        const schema = responseSchemaFor(fixtureCase.id, fixtureCase.responseSchemaKey, fixtureCase.body, discriminatorKeys);
+        const existing = schemas.get(schema.key);
+        if (existing) {
+            if (existing.hash !== schema.hash) {
+                const existingCase = casesById.get(existing.fixtureIds[0]);
+                throw new Error([
+                    `Fixture response schema key "${schema.key}" maps to multiple shapes.`,
+                    `Existing fixtures: ${existing.fixtureIds.join(', ')}`,
+                    `Mismatched fixture: ${fixtureCase.id}`,
+                    'Existing shape:',
+                    stableSchemaStringify(schemaShape(existingCase.body, discriminatorKeys)),
+                    'Mismatched shape:',
+                    stableSchemaStringify(schemaShape(fixtureCase.body, discriminatorKeys)),
+                ].join('\n'));
+            }
+            existing.fixtureIds.push(fixtureCase.id);
+            continue;
+        }
+        schemas.set(schema.key, { hash: schema.hash, fixtureIds: [fixtureCase.id] });
+    }
+    return {
+        version: 2,
+        source,
+        schemas: Object.fromEntries([...schemas.entries()].map(([key, schema]) => [
+            key,
+            { ...schema, fixtureIds: schema.fixtureIds.toSorted() },
+        ])),
+        backendResponseContracts: Object.fromEntries(Object.entries(backendContracts).map(([key, contract]) => [
+            key,
+            {
+                hash: contract.hash,
+                fixtureIds: (fixtureIdsByBackendContract.get(key) ?? []).toSorted(),
+            },
+        ])),
+    };
+}
+function schemaShape(value, discriminatorKeys, propertyKey) {
+    if (hasToJSON(value))
+        return schemaShape(value.toJSON(), discriminatorKeys, propertyKey);
+    if (value === null)
+        return { type: 'null' };
+    if (Array.isArray(value)) {
+        return {
+            type: 'array',
+            items: distinctSchemaShapes(value.map((item) => item === undefined ? { type: 'null' } : schemaShape(item, discriminatorKeys))),
+        };
+    }
+    if (value === undefined)
+        return { type: 'null' };
+    if (typeof value !== 'object') {
+        if (typeof value === 'string' && propertyKey && discriminatorKeys.has(propertyKey)) {
+            return { type: 'string', const: value };
+        }
+        if (typeof value === 'number')
+            return { type: Number.isInteger(value) ? 'integer' : 'number' };
+        return { type: typeof value };
+    }
+    const entries = Object.entries(value).filter(([, nested]) => nested !== undefined);
+    if (isIdKeyedMap(entries)) {
+        return {
+            type: 'id-map',
+            values: distinctSchemaShapes(entries.map(([, nested]) => schemaShape(nested, discriminatorKeys))),
+        };
+    }
+    return {
+        type: 'object',
+        properties: Object.fromEntries(entries
+            .toSorted(([left], [right]) => left.localeCompare(right))
+            .map(([key, nested]) => [key, schemaShape(nested, discriminatorKeys, key)])),
+    };
+}
+function stableSchemaStringify(value) {
+    return JSON.stringify(sortSchemaValue(value));
+}
+function distinctSchemaShapes(shapes) {
+    return Array.from(new Set(shapes.map(stableSchemaStringify)))
+        .toSorted()
+        .map((shape) => JSON.parse(shape));
+}
+function hasToJSON(value) {
+    if (value == null || typeof value !== 'object')
+        return false;
+    return typeof value.toJSON === 'function';
+}
+function isIdKeyedMap(entries) {
+    return (entries.length > 0 &&
+        entries.every(([key, nested]) => isFixtureIdKey(key) && isPlainObject(nested)));
+}
+function isFixtureIdKey(key) {
+    return (/^[0-9a-f]{8}-[0-9a-f]{4}-[1-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i.test(key) ||
+        /^[a-z][a-z0-9]*(?:-[a-z0-9]+)+$/i.test(key) ||
+        /^[a-z][a-z0-9-]*-\d+$/i.test(key) ||
+        /^[a-z]\d+$/i.test(key));
+}
+function isPlainObject(value) {
+    return value != null && typeof value === 'object' && !Array.isArray(value);
+}
+function sortSchemaValue(value) {
+    if (Array.isArray(value))
+        return value.map(sortSchemaValue);
+    if (value == null || typeof value !== 'object')
+        return value;
+    return Object.fromEntries(Object.entries(value)
+        .toSorted(([left], [right]) => left.localeCompare(right))
+        .map(([key, nested]) => [key, sortSchemaValue(nested)]));
+}

package/dist/api-fixtures/write-generated-files.d.mts

@@ -0,0 +1,6 @@
+export declare function writeGeneratedFiles({ files, check, obsoleteDirectory, staleError, }: {
+    files: ReadonlyMap<string, string>;
+    check?: boolean;
+    obsoleteDirectory?: string;
+    staleError: (paths: string[]) => Error;
+}): Promise<void>;

package/dist/api-fixtures/write-generated-files.mjs

@@ -0,0 +1,34 @@
+import { mkdir, readdir, readFile, unlink, writeFile } from 'node:fs/promises';
+import { dirname, join } from 'node:path';
+export async function writeGeneratedFiles({ files, check = false, obsoleteDirectory, staleError, }) {
+    const obsoletePaths = obsoleteDirectory ? await obsoleteJsonPaths(obsoleteDirectory, files) : [];
+    const stale = [];
+    for (const [path, content] of files) {
+        if (check) {
+            const actual = await readFile(path, 'utf8').catch((err) => err.code === 'ENOENT' ? null : Promise.reject(err));
+            if (actual !== content)
+                stale.push(path);
+            continue;
+        }
+        await mkdir(dirname(path), { recursive: true });
+        await writeFile(path, content);
+    }
+    if (check)
+        stale.push(...obsoletePaths);
+    else
+        await Promise.all(obsoletePaths.map((path) => unlink(path)));
+    if (stale.length > 0)
+        throw staleError(stale);
+}
+async function obsoleteJsonPaths(directory, files) {
+    const expected = new Set([...files.keys()].filter((path) => dirname(path) === directory));
+    const entries = await readdir(directory, { withFileTypes: true }).catch((err) => (err.code === 'ENOENT' ? [] : Promise.reject(err)));
+    const obsoletePaths = [];
+    for (const entry of entries) {
+        const path = join(directory, entry.name);
+        if (entry.isFile() && entry.name.endsWith('.json') && !expected.has(path)) {
+            obsoletePaths.push(path);
+        }
+    }
+    return obsoletePaths;
+}

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

@@ -0,0 +1,3 @@
+import ts from './typescript-api.mts';
+import type { ExtractContractSchemaOptions, ExtractedResponseContract } from './types.mts';
+export declare function extractResponseContracts(program: ts.Program, sourceFile: ts.SourceFile, registryName?: string, options?: ExtractContractSchemaOptions): Record<string, ExtractedResponseContract>;

package/dist/contract-schema/contract-schema-extractor.mjs

@@ -0,0 +1,25 @@
+import ts from './typescript-api.mjs';
+import { extractContractSchema } from './contract-schema-type-extractor.mjs';
+import { compareSymbols } from './contract-schema-type-utils.mjs';
+export function extractResponseContracts(program, sourceFile, registryName = 'ApiResponseContracts', options = {}) {
+    const checker = program.getTypeChecker();
+    const registry = findRegistryDeclaration(sourceFile, registryName);
+    const registryType = checker.getTypeAtLocation(registry);
+    const contracts = {};
+    for (const property of checker.getPropertiesOfType(registryType).toSorted(compareSymbols)) {
+        const declaration = property.valueDeclaration;
+        /* v8 ignore next */
+        if (!declaration)
+            throw new Error(`Contract "${property.name}" has no declaration`);
+        const propertyType = checker.getTypeOfSymbolAtLocation(property, declaration);
+        contracts[property.name] = extractContractSchema(propertyType, checker, sourceFile.fileName, options);
+    }
+    return contracts;
+}
+function findRegistryDeclaration(sourceFile, name) {
+    const declaration = sourceFile.statements.find((statement) => ts.isInterfaceDeclaration(statement) && statement.name.text === name);
+    if (!declaration || !ts.isInterfaceDeclaration(declaration)) {
+        throw new Error(`Response contract registry interface "${name}" was not found`);
+    }
+    return declaration;
+}

package/dist/contract-schema/contract-schema-object-tuple.d.mts

@@ -0,0 +1,7 @@
+import ts from './typescript-api.mts';
+import type { ContractSchemaNode } from '../openapi-document/contract-schema-types.mts';
+import type { ExtractionContext } from './contract-schema-type-extractor.mts';
+type SchemaForType = (type: ts.Type, context: ExtractionContext) => ContractSchemaNode;
+export declare function objectSchema(type: ts.Type, context: ExtractionContext, schemaForType: SchemaForType): ContractSchemaNode;
+export declare function tupleSchema(type: ts.TupleType, context: ExtractionContext, schemaForType: SchemaForType): ContractSchemaNode;
+export {};

package/dist/contract-schema/contract-schema-object-tuple.mjs

@@ -0,0 +1,49 @@
+import ts from './typescript-api.mjs';
+import { compareSymbols } from './contract-schema-type-utils.mjs';
+export function objectSchema(type, context, schemaForType) {
+    const properties = {};
+    for (const property of context.checker.getPropertiesOfType(type).toSorted(compareSymbols)) {
+        const declaration = property.valueDeclaration;
+        /* v8 ignore start */
+        const propertyType = declaration
+            ? context.checker.getTypeOfSymbolAtLocation(property, declaration)
+            : typeOfSyntheticProperty(property, context.checker);
+        if (!propertyType)
+            throw new Error(`Property "${property.name}" has no type`);
+        /* v8 ignore stop */
+        try {
+            properties[property.name] = {
+                required: !(property.flags & ts.SymbolFlags.Optional),
+                schema: schemaForType(propertyType, context),
+            };
+        }
+        catch (error) {
+            throw new Error(`Property "${property.name}": ${error.message}`, { cause: error });
+        }
+    }
+    const stringIndex = context.checker.getIndexInfoOfType(type, ts.IndexKind.String);
+    return {
+        type: 'object',
+        properties,
+        additionalProperties: stringIndex ? schemaForType(stringIndex.type, context) : false,
+    };
+}
+/* v8 ignore start -- checker internal used only for compiler-synthesized properties */
+function typeOfSyntheticProperty(property, checker) {
+    return checker.getTypeOfSymbol?.(property);
+}
+/* v8 ignore stop */
+export function tupleSchema(type, context, schemaForType) {
+    const items = context.checker.getTypeArguments(type);
+    const flags = type.target.elementFlags;
+    const restIndex = flags.findIndex((flag) => Boolean(flag & ts.ElementFlags.Variable));
+    const fixedItems = restIndex === -1 ? items : items.slice(0, restIndex);
+    return {
+        type: 'tuple',
+        items: fixedItems.map((item) => schemaForType(item, context)),
+        optionalItems: flags
+            .slice(0, fixedItems.length)
+            .filter((flag) => Boolean(flag & ts.ElementFlags.Optional)).length,
+        ...(restIndex === -1 ? {} : { rest: schemaForType(items[restIndex], context) }),
+    };
+}

package/dist/contract-schema/contract-schema-type-extractor.d.mts

@@ -0,0 +1,11 @@
+import ts from './typescript-api.mts';
+import type { ContractSchemaNode } from '../openapi-document/contract-schema-types.mts';
+import type { ExtractContractSchemaOptions, ExtractedResponseContract } from './types.mts';
+export type ExtractionContext = {
+    checker: ts.TypeChecker;
+    definitions: Map<string, ContractSchemaNode>;
+    definitionTypes: Map<string, ts.Type>;
+    activeTypes: Map<ts.Type, string>;
+    options: ExtractContractSchemaOptions;
+};
+export declare function extractContractSchema(type: ts.Type, checker: ts.TypeChecker, source: string, options?: ExtractContractSchemaOptions): ExtractedResponseContract;

package/dist/contract-schema/contract-schema-type-extractor.mjs

@@ -0,0 +1,170 @@
+import ts from './typescript-api.mjs';
+import { hashContractSchema } from '../openapi-document/contract-schema-canonical.mjs';
+import { objectSchema, tupleSchema } from './contract-schema-object-tuple.mjs';
+import { assertNotClass, distinctNodes, jsonPromiseType, jsonSerializedType, namedObjectDefinition, unsupportedType, } from './contract-schema-type-utils.mjs';
+export function extractContractSchema(type, checker, source, options = {}) {
+    const definitions = new Map();
+    const context = {
+        checker,
+        definitions,
+        definitionTypes: new Map(),
+        activeTypes: new Map(),
+        options,
+    };
+    let root;
+    try {
+        root = schemaForType(type, context);
+    }
+    catch (error) {
+        /* v8 ignore next -- schemaForType throws Error */
+        if (!(error instanceof Error))
+            throw error;
+        throw new Error(`${source}: ${error.message}`, { cause: error });
+    }
+    const schema = {
+        root,
+        definitions: Object.fromEntries([...definitions.entries()].toSorted(([a], [b]) => a.localeCompare(b))),
+    };
+    return { source, schema, hash: hashContractSchema(schema) };
+}
+function schemaForType(type, context) {
+    const { checker, options } = context;
+    if (type.flags & ts.TypeFlags.Any)
+        throw unsupportedType(type, checker, 'any is not allowed');
+    if (type.flags & ts.TypeFlags.Unknown)
+        return { type: 'unknown' };
+    const formatAlias = type.aliasSymbol ? options.formatAliases?.[type.aliasSymbol.name] : undefined;
+    if (formatAlias)
+        return { type: 'string', format: formatAlias };
+    if (type.flags & ts.TypeFlags.Never)
+        throw unsupportedType(type, checker, 'never is not supported');
+    if (type.flags & ts.TypeFlags.Null)
+        return { type: 'null' };
+    if (type.flags & ts.TypeFlags.BooleanLiteral) {
+        return {
+            type: 'literal',
+            value: type.intrinsicName === 'true',
+        };
+    }
+    if (type.flags & ts.TypeFlags.StringLiteral) {
+        return { type: 'literal', value: type.value };
+    }
+    if (type.flags & ts.TypeFlags.NumberLiteral) {
+        return { type: 'literal', value: type.value };
+    }
+    if (type.flags & ts.TypeFlags.StringLike)
+        return { type: 'string' };
+    if (type.flags & ts.TypeFlags.NumberLike)
+        return { type: 'number' };
+    if (type.flags & ts.TypeFlags.BooleanLike)
+        return { type: 'boolean' };
+    if (type.isUnion()) {
+        const variants = type.types.filter((variant) => !(variant.flags & ts.TypeFlags.Undefined));
+        /* v8 ignore next */
+        if (variants.length === 0)
+            throw unsupportedType(type, checker, 'undefined-only types are not supported');
+        if (variants.length === 1)
+            return schemaForType(variants[0], context);
+        if (variants.length === 2 &&
+            variants.every((variant) => variant.flags & ts.TypeFlags.BooleanLiteral)) {
+            return { type: 'boolean' };
+        }
+        const buildUnion = () => ({
+            type: 'union',
+            variants: distinctNodes(variants.map((variant) => schemaForType(variant, context))),
+        });
+        const definitionName = type.aliasSymbol ? namedObjectDefinition(type, checker) : undefined;
+        if (definitionName)
+            return schemaForNamedType(type, definitionName, context, buildUnion);
+        return buildUnion();
+    }
+    if (type.isIntersection()) {
+        return {
+            type: 'intersection',
+            variants: distinctNodes(type.types.map((variant) => schemaForType(variant, context))),
+        };
+    }
+    /* v8 ignore next */
+    if (!(type.flags & ts.TypeFlags.Object))
+        throw unsupportedType(type, checker, 'unsupported type');
+    const serializedType = jsonSerializedType(type, checker);
+    if (serializedType)
+        return schemaForType(serializedType, context);
+    const promisedType = jsonPromiseType(type, checker);
+    if (promisedType)
+        return schemaForType(promisedType, context);
+    if (checker.isTupleType(type))
+        return tupleSchema(type, context, schemaForType);
+    const constrainedArray = boundedArraySchema(type, context);
+    if (constrainedArray)
+        return constrainedArray;
+    if (checker.isArrayType(type) || checker.isArrayLikeType(type)) {
+        const typeArguments = checker.getTypeArguments(type);
+        /* v8 ignore next */
+        if (!typeArguments[0])
+            throw unsupportedType(type, checker, 'array element type is missing');
+        return { type: 'array', items: schemaForType(typeArguments[0], context) };
+    }
+    if (checker.getSignaturesOfType(type, ts.SignatureKind.Call).length > 0) {
+        throw unsupportedType(type, checker, 'callable types are not supported');
+    }
+    if (checker.getSignaturesOfType(type, ts.SignatureKind.Construct).length > 0) {
+        throw unsupportedType(type, checker, 'constructable types are not supported');
+    }
+    assertNotClass(type, checker);
+    const definitionName = namedObjectDefinition(type, checker);
+    if (definitionName) {
+        return schemaForNamedType(type, definitionName, context, () => objectSchema(type, context, schemaForType));
+    }
+    return objectSchema(type, context, schemaForType);
+}
+function boundedArraySchema(type, context) {
+    const alias = context.options.boundedArrayAlias;
+    if (!alias || type.aliasSymbol?.name !== alias)
+        return undefined;
+    const [itemType, minItemsType, maxItemsType, uniqueItemsType] = type.aliasTypeArguments ?? [];
+    if (!itemType || !minItemsType || !maxItemsType || !uniqueItemsType) {
+        throw unsupportedType(type, context.checker, `${alias} requires four type arguments`);
+    }
+    const minItems = numberLiteralValue(minItemsType, type, context.checker, alias);
+    const maxItems = numberLiteralValue(maxItemsType, type, context.checker, alias);
+    if (minItems < 0 || maxItems < minItems) {
+        throw unsupportedType(type, context.checker, `${alias} has invalid item bounds`);
+    }
+    if (!(uniqueItemsType.flags & ts.TypeFlags.BooleanLiteral)) {
+        throw unsupportedType(type, context.checker, `${alias} uniqueness must be literal`);
+    }
+    return {
+        type: 'array',
+        items: schemaForType(itemType, context),
+        minItems,
+        maxItems,
+        uniqueItems: uniqueItemsType.intrinsicName === 'true',
+    };
+}
+function numberLiteralValue(type, owner, checker, alias) {
+    if (!(type.flags & ts.TypeFlags.NumberLiteral)) {
+        throw unsupportedType(owner, checker, `${alias} bounds must be numeric literals`);
+    }
+    return type.value;
+}
+function schemaForNamedType(type, name, context, build) {
+    const existingType = context.definitionTypes.get(name);
+    /* v8 ignore start -- distinct checker types sharing a definition name */
+    if (existingType && existingType !== type) {
+        const flags = ts.TypeFormatFlags.NoTruncation;
+        const existingIdentity = context.checker.typeToString(existingType, undefined, flags);
+        const incomingIdentity = context.checker.typeToString(type, undefined, flags);
+        if (existingIdentity === incomingIdentity)
+            return { type: 'ref', name };
+        throw new Error(`Response contract schema definition name collision: "${name}"`);
+    }
+    /* v8 ignore stop */
+    if (context.definitions.has(name) || context.activeTypes.has(type))
+        return { type: 'ref', name };
+    context.definitionTypes.set(name, type);
+    context.activeTypes.set(type, name);
+    context.definitions.set(name, build());
+    context.activeTypes.delete(type);
+    return { type: 'ref', name };
+}

package/dist/contract-schema/contract-schema-type-utils.d.mts

@@ -0,0 +1,9 @@
+import ts from './typescript-api.mts';
+import type { ContractSchemaNode } from '../openapi-document/contract-schema-types.mts';
+export declare function namedObjectDefinition(type: ts.Type, checker: ts.TypeChecker): string | undefined;
+export declare function distinctNodes(nodes: ContractSchemaNode[]): ContractSchemaNode[];
+export declare function assertNotClass(type: ts.Type, checker: ts.TypeChecker): void;
+export declare function jsonPromiseType(type: ts.Type, checker: ts.TypeChecker): ts.Type | undefined;
+export declare function jsonSerializedType(type: ts.Type, checker: ts.TypeChecker): ts.Type | undefined;
+export declare function unsupportedType(type: ts.Type, checker: ts.TypeChecker, reason: string): Error;
+export declare function compareSymbols(left: ts.Symbol, right: ts.Symbol): number;

package/dist/contract-schema/contract-schema-type-utils.mjs

@@ -0,0 +1,107 @@
+import ts from './typescript-api.mjs';
+import { canonicalContractSchemaNode } from '../openapi-document/contract-schema-canonical.mjs';
+export function namedObjectDefinition(type, checker) {
+    const symbol = type.aliasSymbol ?? type.getSymbol();
+    if (!symbol || symbol.name === '__type' || symbol.name === '__object')
+        return undefined;
+    if (!type.aliasSymbol && !isDeclaredTypeSymbol(symbol))
+        return undefined;
+    const typeArguments = type.aliasTypeArguments ?? type.typeArguments;
+    if (!typeArguments?.length)
+        return symbol.name;
+    return `${symbol.name}<${typeArguments.map((argument) => typeIdentity(argument, checker)).join(',')}>`;
+}
+/**
+ * A plain (non-alias) symbol only identifies a genuine named type when it comes from an actual
+ * type-level declaration (interface/class/enum). The checker also attaches a destructuring
+ * variable's own symbol to the anonymous object type it synthesizes for a rest-binding pattern
+ * (`const { a, ...rest } = x`) — e.g. `rows.map(({ a, ...row }) => row)` names its per-call-site
+ * anonymous shape "row" purely from the local variable, not a real type. Treating that as a
+ * definition name falsely unifies (or falsely collides) unrelated shapes across call sites that
+ * happen to reuse the same rest-variable name.
+ */
+function isDeclaredTypeSymbol(symbol) {
+    return Boolean(symbol.declarations?.some((declaration) => ts.isInterfaceDeclaration(declaration) ||
+        ts.isClassDeclaration(declaration) ||
+        ts.isEnumDeclaration(declaration)));
+}
+/**
+ * Builds a name-suffix identity for one generic type argument. Recurses into the argument's own
+ * type arguments (e.g. `Array<Widget>`) so two different generics instantiated with the same outer
+ * shape but different nested element types don't collapse onto the same suffix. Anonymous element
+ * types (inline object literals, which have no symbol) fall back to a full structural stringify —
+ * without it, `Record<string, Array<{a}>>` and `Record<string, Array<{b}>>` would both identify as
+ * bare `Array` and sanitize to the same component name despite differing shapes.
+ *
+ * Literal type arguments (e.g. the `'topic'` in `PaginatedResult<'topic'>`) must keep their literal
+ * value rather than collapsing to the base primitive name — otherwise `PaginatedResult<'topic'>`
+ * and `PaginatedResult<'notification'>` both identify as `PaginatedResult<string>` and collide.
+ */
+function typeIdentity(type, checker) {
+    if (type.flags & ts.TypeFlags.StringLiteral)
+        return String(type.value);
+    if (type.flags & ts.TypeFlags.NumberLiteral)
+        return String(type.value);
+    if (type.flags & ts.TypeFlags.BooleanLiteral) {
+        return String(type.intrinsicName === 'true');
+    }
+    if (type.flags & ts.TypeFlags.StringLike)
+        return 'string';
+    if (type.flags & ts.TypeFlags.NumberLike)
+        return 'number';
+    if (type.flags & ts.TypeFlags.BooleanLike)
+        return 'boolean';
+    if (type.flags & ts.TypeFlags.Null)
+        return 'null';
+    const symbol = type.aliasSymbol ?? type.getSymbol();
+    if (symbol && symbol.name !== '__type' && symbol.name !== '__object') {
+        const typeArguments = type.aliasTypeArguments ?? type.typeArguments;
+        return typeArguments?.length
+            ? `${symbol.name}<${typeArguments.map((argument) => typeIdentity(argument, checker)).join(',')}>`
+            : symbol.name;
+    }
+    return checker.typeToString(type, undefined, ts.TypeFormatFlags.NoTruncation);
+}
+export function distinctNodes(nodes) {
+    const nodesByCanonicalSchema = new Map();
+    for (const node of nodes) {
+        const canonicalSchema = canonicalContractSchemaNode(node);
+        if (!nodesByCanonicalSchema.has(canonicalSchema)) {
+            nodesByCanonicalSchema.set(canonicalSchema, node);
+        }
+    }
+    return [...nodesByCanonicalSchema]
+        .toSorted(([left], [right]) => left.localeCompare(right))
+        .map(([, node]) => node);
+}
+export function assertNotClass(type, checker) {
+    const symbol = type.getSymbol();
+    if (symbol?.declarations?.some(ts.isClassDeclaration)) {
+        throw unsupportedType(type, checker, 'class instances are not supported');
+    }
+}
+export function jsonPromiseType(type, checker) {
+    const symbol = type.aliasSymbol ?? type.getSymbol();
+    if (symbol?.name !== 'Promise' && symbol?.name !== 'PromiseLike')
+        return undefined;
+    return checker.getTypeArguments(type)[0];
+}
+export function jsonSerializedType(type, checker) {
+    const toJSON = checker.getPropertyOfType(type, 'toJSON');
+    if (!toJSON)
+        return undefined;
+    const declaration = toJSON.valueDeclaration;
+    /* v8 ignore next */
+    if (!declaration)
+        return undefined;
+    const toJSONType = checker.getTypeOfSymbolAtLocation(toJSON, declaration);
+    const signature = checker.getSignaturesOfType(toJSONType, ts.SignatureKind.Call)[0];
+    /* v8 ignore next */
+    return signature ? checker.getReturnTypeOfSignature(signature) : undefined;
+}
+export function unsupportedType(type, checker, reason) {
+    return new Error(`Unsupported response contract type "${checker.typeToString(type)}": ${reason}`);
+}
+export function compareSymbols(left, right) {
+    return left.name.localeCompare(right.name);
+}

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

@@ -0,0 +1,3 @@
+import type { ContractSchema } from '../openapi-document/contract-schema-types.mts';
+import type { ContractValidationIssue } from './types.mts';
+export declare function validateResponseContract(schema: ContractSchema, value: unknown): ContractValidationIssue[];

package/dist/contract-schema/contract-schema-validator.mjs

@@ -0,0 +1,126 @@
+import { addIssue, addUnexpectedIssue, collectObjectShape, isObject, propertyPath, requireType, } from './validation-helpers.mjs';
+export function validateResponseContract(schema, value) {
+    const context = { definitions: schema.definitions, issues: [] };
+    validateNode(schema.root, value, '$', context, true);
+    return context.issues;
+}
+function validateNode(node, value, path, context, checkUnexpected) {
+    switch (node.type) {
+        case 'unknown':
+            return;
+        case 'null':
+            return requireType(value === null, 'null', value, path, context);
+        case 'boolean':
+            return requireType(typeof value === 'boolean', 'boolean', value, path, context);
+        case 'number':
+            return requireType(typeof value === 'number' && Number.isFinite(value), 'number', value, path, context);
+        case 'string':
+            return requireType(typeof value === 'string', 'string', value, path, context);
+        case 'literal':
+            return requireType(Object.is(value, node.value), JSON.stringify(node.value), value, path, context);
+        case 'array':
+            return validateArray(node.items, value, path, context);
+        case 'tuple':
+            return validateTuple(node, value, path, context);
+        case 'object':
+            return validateObject(node, value, path, context, checkUnexpected);
+        case 'union':
+            return validateUnion(node.variants, value, path, context);
+        case 'intersection':
+            return validateIntersection(node.variants, value, path, context);
+        case 'ref': {
+            const definition = context.definitions[node.name];
+            if (!definition)
+                throw new Error(`Unknown response contract schema reference "${node.name}"`);
+            return validateNode(definition, value, path, context, checkUnexpected);
+        }
+    }
+}
+function validateArray(itemSchema, value, path, context) {
+    if (!Array.isArray(value))
+        return requireType(false, 'array', value, path, context);
+    for (const item of value)
+        validateNode(itemSchema, item, `${path}[*]`, context, true);
+}
+function validateTuple(node, value, path, context) {
+    if (!Array.isArray(value))
+        return requireType(false, 'tuple', value, path, context);
+    const requiredLength = node.items.length - node.optionalItems;
+    if (value.length < requiredLength) {
+        addIssue(context, path, 'type', `Expected at least ${requiredLength} tuple items, received ${value.length}`);
+    }
+    if (!node.rest && value.length > node.items.length) {
+        addIssue(context, path, 'type', `Expected at most ${node.items.length} tuple items, received ${value.length}`);
+    }
+    node.items.forEach((item, index) => {
+        if (index < value.length)
+            validateNode(item, value[index], `${path}[${index}]`, context, true);
+    });
+    if (node.rest) {
+        for (const item of value.slice(node.items.length)) {
+            validateNode(node.rest, item, `${path}[*]`, context, true);
+        }
+    }
+}
+function validateObject(node, value, path, context, checkUnexpected) {
+    if (!isObject(value))
+        return requireType(false, 'object', value, path, context);
+    for (const [key, property] of Object.entries(node.properties)) {
+        if (!(key in value)) {
+            if (property.required) {
+                addIssue(context, propertyPath(path, key), 'missing-required', 'Required field is missing');
+            }
+            continue;
+        }
+        validateNode(property.schema, value[key], propertyPath(path, key), context, true);
+    }
+    if (!checkUnexpected)
+        return;
+    for (const [key, nested] of Object.entries(value)) {
+        if (key in node.properties)
+            continue;
+        if (node.additionalProperties === false) {
+            addUnexpectedIssue(context, propertyPath(path, key));
+            continue;
+        }
+        validateNode(node.additionalProperties, nested, `${path}{*}`, context, true);
+    }
+}
+function validateUnion(variants, value, path, context) {
+    const attempts = variants.map((variant) => validateIsolated(variant, value, path, context.definitions));
+    if (attempts.some((issues) => issues.length === 0))
+        return;
+    const closest = attempts.toSorted((left, right) => left.length - right.length)[0];
+    /* v8 ignore next -- unions always have at least one variant */
+    if (closest)
+        context.issues.push(...closest);
+}
+function validateIntersection(variants, value, path, context) {
+    for (const variant of variants)
+        validateNode(variant, value, path, context, false);
+    if (!isObject(value))
+        return;
+    const allowedProperties = new Set();
+    let additionalSchema;
+    const addAdditionalSchema = (schema) => {
+        additionalSchema ??= schema;
+    };
+    for (const variant of variants) {
+        collectObjectShape(variant, context.definitions, allowedProperties, addAdditionalSchema);
+    }
+    for (const [key, nested] of Object.entries(value)) {
+        if (allowedProperties.has(key))
+            continue;
+        if (additionalSchema) {
+            validateNode(additionalSchema, nested, `${path}{*}`, context, true);
+        }
+        else {
+            addUnexpectedIssue(context, propertyPath(path, key));
+        }
+    }
+}
+function validateIsolated(node, value, path, definitions) {
+    const isolated = { definitions, issues: [] };
+    validateNode(node, value, path, isolated, true);
+    return isolated.issues;
+}

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

@@ -0,0 +1,9 @@
+export { canonicalContractSchema, canonicalContractSchemaNode, hashContractSchema, } from '../openapi-document/contract-schema-canonical.mts';
+export type { ContractSchema, ContractSchemaNode, ContractSchemaProperty, } from '../openapi-document/contract-schema-types.mts';
+export { extractResponseContracts } from './contract-schema-extractor.mts';
+export { extractContractSchema } from './contract-schema-type-extractor.mts';
+export type { ExtractionContext } from './contract-schema-type-extractor.mts';
+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';

package/dist/contract-schema/index.mjs

@@ -0,0 +1,5 @@
+export { canonicalContractSchema, canonicalContractSchemaNode, hashContractSchema, } from '../openapi-document/contract-schema-canonical.mjs';
+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';

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

@@ -0,0 +1,15 @@
+import type { ContractSchema } from '../openapi-document/contract-schema-types.mts';
+export type ExtractedResponseContract = {
+    source: string;
+    schema: ContractSchema;
+    hash: string;
+};
+export type ContractValidationIssue = {
+    path: string;
+    kind: 'missing-required' | 'unexpected' | 'type';
+    message: string;
+};
+export type ExtractContractSchemaOptions = {
+    formatAliases?: Readonly<Record<string, 'uuid'>>;
+    boundedArrayAlias?: string;
+};

package/dist/contract-schema/types.mjs

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

package/dist/contract-schema/typescript-api.d.mts

@@ -0,0 +1,6 @@
+/**
+ * Classic TypeScript compiler API. typescript@7's package root is version-only;
+ * @typescript/typescript6 (or a typescript@5/@6 install aliased as "typescript")
+ * provides createProgram/type checker used by contract extraction.
+ */
+export { default } from '@typescript/typescript6';

package/dist/contract-schema/typescript-api.mjs

@@ -0,0 +1,6 @@
+/**
+ * Classic TypeScript compiler API. typescript@7's package root is version-only;
+ * @typescript/typescript6 (or a typescript@5/@6 install aliased as "typescript")
+ * provides createProgram/type checker used by contract extraction.
+ */
+export { default } from '@typescript/typescript6';

package/dist/contract-schema/validation-helpers.d.mts

@@ -0,0 +1,12 @@
+import type { ContractSchemaNode } from '../openapi-document/contract-schema-types.mts';
+import type { ContractValidationIssue } from './types.mts';
+export type ValidationContext = {
+    definitions: Record<string, ContractSchemaNode>;
+    issues: ContractValidationIssue[];
+};
+export declare function requireType(valid: boolean, expected: string, value: unknown, path: string, context: ValidationContext): void;
+export declare function addIssue(context: ValidationContext, path: string, kind: ContractValidationIssue['kind'], message: string): void;
+export declare function addUnexpectedIssue(context: ValidationContext, path: string): void;
+export declare function propertyPath(path: string, property: string): string;
+export declare function isObject(value: unknown): value is Record<string, unknown>;
+export declare function collectObjectShape(node: ContractSchemaNode, definitions: Record<string, ContractSchemaNode>, properties: Set<string>, addAdditional: (schema: ContractSchemaNode) => void): void;

package/dist/contract-schema/validation-helpers.mjs

@@ -0,0 +1,43 @@
+export function requireType(valid, expected, value, path, context) {
+    if (valid)
+        return;
+    addIssue(context, path, 'type', `Expected ${expected}, received ${describeValue(value)}`);
+}
+export function addIssue(context, path, kind, message) {
+    context.issues.push({ path, kind, message });
+}
+export function addUnexpectedIssue(context, path) {
+    addIssue(context, path, 'unexpected', 'Field is not declared by the contract');
+}
+export function propertyPath(path, property) {
+    if (/^[A-Za-z_$][\w$]*$/.test(property))
+        return `${path}.${property}`;
+    return `${path}[${JSON.stringify(property)}]`;
+}
+function describeValue(value) {
+    if (value === null)
+        return 'null';
+    if (Array.isArray(value))
+        return 'array';
+    return typeof value;
+}
+export function isObject(value) {
+    return value != null && typeof value === 'object' && !Array.isArray(value);
+}
+export function collectObjectShape(node, definitions, properties, addAdditional) {
+    if (node.type === 'ref') {
+        collectObjectShape(definitions[node.name], definitions, properties, addAdditional);
+        return;
+    }
+    if (node.type === 'intersection') {
+        for (const variant of node.variants) {
+            collectObjectShape(variant, definitions, properties, addAdditional);
+        }
+        return;
+    }
+    if (node.type !== 'object')
+        return;
+    Object.keys(node.properties).forEach((key) => properties.add(key));
+    if (node.additionalProperties !== false)
+        addAdditional(node.additionalProperties);
+}

package/dist/contract-schema/virtual-program.d.mts

@@ -0,0 +1,7 @@
+import ts from './typescript-api.mts';
+export interface VirtualProgramMatrix<Id extends string> {
+    readonly program: ts.Program;
+    sourceFile(id: Id): ts.SourceFile;
+}
+export declare function buildVirtualProgramMatrix<const Id extends string>(ownerExecution: ImportMeta, sources: Readonly<Record<Id, string>>): VirtualProgramMatrix<Id>;
+export declare function virtualProgramBuildCountForTest(): number;

package/dist/contract-schema/virtual-program.mjs

@@ -0,0 +1,88 @@
+import ts from './typescript-api.mjs';
+const virtualCompilerSourceFiles = new Map();
+const virtualProgramMatrixExecutions = new WeakSet();
+const virtualSourceIdPattern = /^[a-z0-9](?:[a-z0-9-]*[a-z0-9])?$/;
+let virtualProgramBuildCount = 0;
+export function buildVirtualProgramMatrix(ownerExecution, sources) {
+    const owner = normalizeOwnerFileUrl(ownerExecution.url);
+    const entries = Object.entries(sources);
+    if (entries.length === 0)
+        throw new Error('A virtual program matrix requires at least one source');
+    const sourcesByFileName = new Map();
+    const fileNameById = new Map();
+    for (const [id, sourceText] of entries) {
+        if (!virtualSourceIdPattern.test(id)) {
+            throw new Error(`Virtual source ID "${id}" must contain only lowercase letters, digits, and hyphens`);
+        }
+        const fileName = `/virtual/${id}.ts`;
+        sourcesByFileName.set(fileName, `${sourceText}\nexport {}\n`);
+        fileNameById.set(id, fileName);
+    }
+    const options = {
+        module: ts.ModuleKind.ESNext,
+        moduleResolution: ts.ModuleResolutionKind.Bundler,
+        skipLibCheck: true,
+        strict: true,
+        target: ts.ScriptTarget.ESNext,
+    };
+    const host = ts.createCompilerHost(options, true);
+    const originalGetSourceFile = host.getSourceFile.bind(host);
+    host.getSourceFile = (requested, languageVersion, onError, shouldCreateNewSourceFile) => {
+        const virtualSource = sourcesByFileName.get(requested);
+        if (virtualSource !== undefined) {
+            return ts.createSourceFile(requested, virtualSource, languageVersion, true, ts.ScriptKind.TS);
+        }
+        const cached = virtualCompilerSourceFiles.get(requested);
+        if (cached)
+            return cached;
+        const sourceFile = originalGetSourceFile(requested, languageVersion, onError, shouldCreateNewSourceFile);
+        /* v8 ignore next -- host lookup of a missing lib file */
+        if (sourceFile)
+            virtualCompilerSourceFiles.set(requested, sourceFile);
+        return sourceFile;
+    };
+    host.fileExists = (requested) => sourcesByFileName.has(requested) || ts.sys.fileExists(requested);
+    host.readFile = (requested) => sourcesByFileName.get(requested) ?? ts.sys.readFile(requested);
+    if (virtualProgramMatrixExecutions.has(ownerExecution)) {
+        throw new Error(`Virtual program matrix for "${owner}" was already built; each contract test file execution may build exactly one`);
+    }
+    const program = ts.createProgram([...sourcesByFileName.keys()], options, host);
+    virtualProgramMatrixExecutions.add(ownerExecution);
+    virtualProgramBuildCount += 1;
+    return {
+        program,
+        sourceFile(id) {
+            const fileName = fileNameById.get(id);
+            if (!fileName)
+                throw new Error(`Unknown virtual source ID "${id}"`);
+            const sourceFile = program.getSourceFile(fileName);
+            /* v8 ignore next -- createProgram always materializes matrix source files */
+            if (!sourceFile)
+                throw new Error(`Unable to load ${fileName}`);
+            const diagnostics = [
+                ...program.getSyntacticDiagnostics(sourceFile),
+                ...program.getSemanticDiagnostics(sourceFile),
+            ];
+            if (diagnostics.length > 0)
+                throw new Error(formatDiagnostics(diagnostics));
+            return sourceFile;
+        },
+    };
+}
+export function virtualProgramBuildCountForTest() {
+    return virtualProgramBuildCount;
+}
+function normalizeOwnerFileUrl(ownerFileUrl) {
+    const owner = new URL(ownerFileUrl);
+    if (owner.protocol !== 'file:') {
+        throw new Error(`Virtual program matrix owner must be a file URL, received "${ownerFileUrl}"`);
+    }
+    return owner.href;
+}
+function formatDiagnostics(diagnostics) {
+    return ts.formatDiagnosticsWithColorAndContext(diagnostics, {
+        getCanonicalFileName: (fileName) => fileName,
+        getCurrentDirectory: () => '/',
+        getNewLine: () => '\n',
+    });
+}

package/dist/index.d.mts

@@ -51,6 +51,10 @@ export { buildSchemaSnapshot, detectRenamedIndexes, generateSchemaSnapshot, inde
 export type { CatalogQuery, PartitionPolicy, SchemaCatalog, SchemaGrowthMaps, SchemaSnapshot, SchemaTableSnapshot, } from './pg-schema-snapshot/index.mts';
 export { buildOpenApiDocument, hashContractSchema, nodeToOpenApi, writeOpenApi, } from './openapi-document/index.mts';
 export type { BuildOpenApiDocumentInput, ContractSchema, OpenApiDocument, RequestContract, ResponseContract, } from './openapi-document/index.mts';
+export { buildVirtualProgramMatrix, extractContractSchema, extractResponseContracts, validateResponseContract, virtualProgramBuildCountForTest, } from './contract-schema/index.mts';
+export type { ContractValidationIssue, ExtractContractSchemaOptions, ExtractedResponseContract, VirtualProgramMatrix, } from './contract-schema/index.mts';
+export { buildFixtureSchemaLock, responseSchemaFor, validateFixtureContracts, writeGeneratedFiles, } from './api-fixtures/index.mts';
+export type { FixtureSchemaLock, FixtureSchemaLockCase, FixtureSchemaLockSource, FixtureValidationCase, FixtureValidationContract, ValidateFixtureContractsOptions, } from './api-fixtures/index.mts';
 export { decide, deriveRetryAttempt } from './transient-retry/index.mts';
 export type { DecisionResult, EvaluateRulesOptions, NoMatchReason, RetryContext, RetryDecision, RetryRule, RetryTarget, } from './transient-retry/index.mts';
 export { escapeSpreadsheetFormula, parseCsvRows, streamCsvRows, stripCsvBom } from './csv/index.mts';

package/dist/index.mjs

@@ -27,6 +27,8 @@ export { boundPendingLine, DEFAULT_MAX_PENDING_LINE_LENGTH, DEFAULT_TRUNCATED_LI
 export { isProcessGroupAlive, ProcessGroupDrainTimeoutError, runBrowserSession, waitForProcessGroupExit, } from './browser-session-runner/index.mjs';
 export { buildSchemaSnapshot, detectRenamedIndexes, generateSchemaSnapshot, indexShapeKey, readSchemaCatalog, renderSchemaMarkdown, stableStringify, writeSchemaSnapshot, } from './pg-schema-snapshot/index.mjs';
 export { buildOpenApiDocument, hashContractSchema, nodeToOpenApi, writeOpenApi, } from './openapi-document/index.mjs';
+export { buildVirtualProgramMatrix, extractContractSchema, extractResponseContracts, validateResponseContract, virtualProgramBuildCountForTest, } from './contract-schema/index.mjs';
+export { buildFixtureSchemaLock, responseSchemaFor, validateFixtureContracts, writeGeneratedFiles, } from './api-fixtures/index.mjs';
 export { decide, deriveRetryAttempt } from './transient-retry/index.mjs';
 export { escapeSpreadsheetFormula, parseCsvRows, streamCsvRows, stripCsvBom } from './csv/index.mjs';
 export { MissingResponseBodyError, readResponseBody, readResponseBodyAsBuffer, ResponseBodyTooLargeError, } from './http-body/index.mjs';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "vouchington-tooling",
-  "version": "0.15.1",
+  "version": "0.16.0",
   "description": "Vouchington CLI and extractable tooling libraries.",
   "homepage": "https://github.com/vouchington/vouchington-tooling/tree/main/packages/vouchington-tooling#readme",
   "bugs": {
@@ -168,6 +168,16 @@
       "import": "./dist/openapi-document/index.mjs",
       "default": "./dist/openapi-document/index.mjs"
     },
+    "./contract-schema": {
+      "types": "./dist/contract-schema/index.d.mts",
+      "import": "./dist/contract-schema/index.mjs",
+      "default": "./dist/contract-schema/index.mjs"
+    },
+    "./api-fixtures": {
+      "types": "./dist/api-fixtures/index.d.mts",
+      "import": "./dist/api-fixtures/index.mjs",
+      "default": "./dist/api-fixtures/index.mjs"
+    },
     "./transient-retry": {
       "types": "./dist/transient-retry/index.d.mts",
       "import": "./dist/transient-retry/index.mjs",
@@ -320,8 +330,17 @@
     "@types/picomatch": "^4.0.3",
     "agent-blackboard": "^0.5.0"
   },
+  "peerDependencies": {
+    "typescript": ">=5"
+  },
+  "peerDependenciesMeta": {
+    "typescript": {
+      "optional": true
+    }
+  },
   "optionalDependencies": {
-    "@libpg-query/parser": "^18.0.0"
+    "@libpg-query/parser": "^18.0.0",
+    "@typescript/typescript6": "^6.0.2"
   },
   "engines": {
     "node": ">=24.0.0"