vouchington-tooling 0.15.1 → 0.16.1

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
 ```
@@ -144,6 +147,13 @@ Host-lock environment:
 | `HOST_LOCK_PROCESS_GROUP_DRAIN_SECONDS` | `30`                  | Time to wait for the command process group  |
 | `HOST_LOCK_ACTIVE`                      | unset                 | Set while a lock is held; nested locks fail |
 
+## Sourceable Bash libraries
+
+`scripts/worktree/git-worktrees.sh` is included in the published package. Source it to parse
+`git worktree list --porcelain` with `git_worktree_*` helpers. Its
+`git_worktree_canonical_path_hash <path>` helper resolves the physical path and prints a stable
+`d` plus the first 12 lowercase hexadecimal characters of its SHA-256 digest.
+
 ## Library
 
 ```ts
@@ -192,6 +202,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;