vouchington-tooling 0.0.10 → 0.0.12

package/README.md

@@ -64,4 +64,9 @@ import {
 import { createArtifactClassifier, runCleanup } from 'vouchington-tooling/gha-artifacts-cleanup'
 import { validateOptionalHttpOrigin } from 'vouchington-tooling/http-origin'
 import { boundPendingLine, splitCompleteLines } from 'vouchington-tooling/process-line-buffer'
+import {
+  generateSchemaSnapshot,
+  renderSchemaMarkdown,
+} from 'vouchington-tooling/pg-schema-snapshot'
+import { buildOpenApiDocument, writeOpenApi } from 'vouchington-tooling/openapi-document'
 ```

package/dist/index.d.mts

@@ -16,3 +16,7 @@ export { createArtifactClassifier, parseArtifactPatternsJson, planRunDeletions,
 export type { ArtifactClassification, ArtifactClassifier, ArtifactPatterns, CleanupRequest, DeletionSummary, } from './gha-artifacts-cleanup/index.mts';
 export { validateOptionalHttpOrigin } from './http-origin/index.mts';
 export { boundPendingLine, DEFAULT_MAX_PENDING_LINE_LENGTH, DEFAULT_TRUNCATED_LINE_MARKER, splitCompleteLines, } from './process-line-buffer/index.mts';
+export { buildSchemaSnapshot, detectRenamedIndexes, generateSchemaSnapshot, indexShapeKey, readSchemaCatalog, renderSchemaMarkdown, stableStringify, writeSchemaSnapshot, } from './pg-schema-snapshot/index.mts';
+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';

package/dist/index.mjs

@@ -9,3 +9,5 @@ export { decodeSelectedFiles, encodeSelectedFiles, formatMultilineOutput, SELECT
 export { createArtifactClassifier, parseArtifactPatternsJson, planRunDeletions, runCleanup, sweepCleanup, } from './gha-artifacts-cleanup/index.mjs';
 export { validateOptionalHttpOrigin } from './http-origin/index.mjs';
 export { boundPendingLine, DEFAULT_MAX_PENDING_LINE_LENGTH, DEFAULT_TRUNCATED_LINE_MARKER, splitCompleteLines, } from './process-line-buffer/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';

package/dist/openapi-document/build-openapi-document.d.mts

@@ -0,0 +1,11 @@
+import { type QueryOperationContract, type RegisteredRoute, type RequestContract, type ResponseContract } from './operation-types.mts';
+import type { OpenApiDocument } from './openapi-types.mts';
+export type BuildOpenApiDocumentInput = {
+    title: string;
+    version?: string;
+    responseContracts: Record<string, ResponseContract>;
+    requestContracts?: Record<string, RequestContract>;
+    queryContracts?: Readonly<Record<string, QueryOperationContract>>;
+    registeredRoutes?: readonly RegisteredRoute[];
+};
+export declare function buildOpenApiDocument(input: BuildOpenApiDocumentInput): OpenApiDocument;

package/dist/openapi-document/build-openapi-document.mjs

@@ -0,0 +1,122 @@
+import { queryParameters } from './build-openapi-query.mjs';
+import { buildOperationRequestBody } from './build-openapi-request.mjs';
+import { buildOperationResponse } from './build-openapi-response.mjs';
+import { createComponentRegistry } from './component-registry.mjs';
+import { responseStatusCodesForContract, routeShape, } from './operation-types.mjs';
+import { registerOpenApiErrorResponse } from './openapi-error-response.mjs';
+import { canonicalTemplatesByShape, catalogResponse, operationId, pathParameters, } from './openapi-route-helpers.mjs';
+export function buildOpenApiDocument(input) {
+    const registry = createComponentRegistry();
+    registerOpenApiErrorResponse(registry);
+    const requestContracts = input.requestContracts ?? {};
+    const queryContracts = input.queryContracts ?? {};
+    const registeredRoutes = input.registeredRoutes ?? [];
+    const contractGroups = groupContractsByRoute(input.responseContracts);
+    const contractGroupsByShape = uniqueShapeGroups(contractGroups);
+    const catalogByShape = new Map(registeredRoutes.map((route) => [`${route.method}:${routeShape(route.routeTemplate)}`, route]));
+    const operationKeys = new Set([...contractGroupsByShape.keys(), ...catalogByShape.keys()]);
+    const canonicalTemplates = canonicalTemplatesByShape([
+        ...[...contractGroups.values()].map((variants) => variants[0].routeTemplate),
+        ...registeredRoutes.map((route) => route.routeTemplate),
+    ]);
+    const paths = {};
+    const unavailableRoutes = [];
+    const unavailableRequestRoutes = [];
+    for (const shapeKey of [...operationKeys].toSorted()) {
+        const separator = shapeKey.indexOf(':');
+        const method = shapeKey.slice(0, separator);
+        const catalogRoute = catalogByShape.get(shapeKey);
+        const variants = contractGroupsByShape.get(shapeKey);
+        const routeTemplate = catalogRoute?.routeTemplate ?? variants[0].routeTemplate;
+        const groupKey = `${method}:${routeTemplate}`;
+        assertFixedNoContent(catalogRoute, variants, groupKey);
+        const rendered = renderOperation(catalogRoute, variants, registry);
+        if (rendered.unavailable)
+            unavailableRoutes.push(groupKey);
+        const { requestBody, unavailable: requestUnavailable } = buildOperationRequestBody(requestContracts[groupKey], registry);
+        if (requestUnavailable)
+            unavailableRequestRoutes.push(groupKey);
+        const canonicalTemplate = canonicalTemplates.get(routeShape(routeTemplate));
+        const parameters = [
+            ...pathParameters(canonicalTemplate),
+            ...queryParameters(queryContracts[groupKey]?.parameters),
+        ];
+        const operation = {
+            operationId: operationId(method, routeTemplate),
+            ...(parameters.length > 0 ? { parameters } : {}),
+            ...(requestBody ? { requestBody } : {}),
+            responses: { ...rendered.responses, default: { $ref: '#/components/responses/Error' } },
+            ...(rendered.unavailable
+                ? {
+                    'x-schema-unavailable': true,
+                    /* v8 ignore next -- catalog and conversion failures always include a reason */
+                    ...(rendered.unavailableReason
+                        ? { 'x-schema-unavailable-reason': rendered.unavailableReason }
+                        : {}),
+                }
+                : {}),
+        };
+        const path = canonicalTemplate.replace(/:(\w+)/g, '{$1}');
+        paths[path] ??= {};
+        paths[path][method.toLowerCase()] = operation;
+    }
+    return {
+        openapi: '3.1.0',
+        info: { title: input.title, version: input.version ?? '1.0.0' },
+        paths,
+        components: {
+            schemas: registry.schemas(),
+            responses: {
+                Error: {
+                    description: 'Error',
+                    content: {
+                        'application/json': {
+                            schema: { $ref: `#/components/schemas/${registry.refName('ErrorBody')}` },
+                        },
+                    },
+                },
+            },
+        },
+        'x-unavailable-routes': unavailableRoutes.toSorted(),
+        'x-unavailable-request-routes': unavailableRequestRoutes.toSorted(),
+    };
+}
+function groupContractsByRoute(contracts) {
+    const groups = new Map();
+    for (const contract of Object.values(contracts)) {
+        const groupKey = `${contract.method}:${contract.routeTemplate}`;
+        const variants = groups.get(groupKey) ?? [];
+        variants.push(contract);
+        groups.set(groupKey, variants);
+    }
+    return groups;
+}
+function uniqueShapeGroups(groups) {
+    const contractGroupsByShape = new Map();
+    for (const [, variants] of groups) {
+        const { method, routeTemplate } = variants[0];
+        const shapeKey = `${method}:${routeShape(routeTemplate)}`;
+        const existing = contractGroupsByShape.get(shapeKey);
+        if (existing)
+            throw new Error(`response contracts contain duplicate normalized route ${shapeKey}: ${existing[0].routeTemplate} and ${routeTemplate}`);
+        contractGroupsByShape.set(shapeKey, variants);
+    }
+    return contractGroupsByShape;
+}
+function assertFixedNoContent(catalogRoute, variants, groupKey) {
+    if (catalogRoute?.kind !== 'fixed-no-content' || !variants)
+        return;
+    if (variants.every((variant) => variant.bodyKind === 'none' &&
+        responseStatusCodesForContract(variant).every((status) => status === catalogRoute.fixedStatus)))
+        return;
+    throw new Error(`OpenAPI fixed-no-content metadata conflicts with extracted response variants for ${groupKey}`);
+}
+function renderOperation(catalogRoute, variants, registry) {
+    if (catalogRoute?.kind === 'sse' || catalogRoute?.kind === 'fixed-no-content')
+        return catalogResponse(catalogRoute.kind, catalogRoute.fixedStatus);
+    if (variants)
+        return buildOperationResponse(variants, registry);
+    if (catalogRoute?.kind === 'error-only')
+        return catalogResponse('error-only');
+    return catalogResponse('ordinary');
+}

package/dist/openapi-document/build-openapi-query.d.mts

@@ -0,0 +1,3 @@
+import type { OpenApiParameter } from './openapi-types.mts';
+import type { OpenApiQueryContract } from './query-types.mts';
+export declare function queryParameters(contract: OpenApiQueryContract | undefined): OpenApiParameter[];

package/dist/openapi-document/build-openapi-query.mjs

@@ -0,0 +1,53 @@
+export function queryParameters(contract) {
+    if (!contract)
+        return [];
+    return Object.entries(contract)
+        .toSorted(([left], [right]) => left.localeCompare(right))
+        .map(([name, descriptor]) => queryParameter(name, descriptor));
+}
+function queryParameter(name, descriptor) {
+    return {
+        name,
+        in: 'query',
+        required: false,
+        ...(descriptor.description ? { description: descriptor.description } : {}),
+        ...(descriptor.kind === 'csv-array'
+            ? { style: descriptor.style, explode: descriptor.explode }
+            : {}),
+        schema: querySchema(descriptor),
+    };
+}
+function querySchema(descriptor) {
+    switch (descriptor.kind) {
+        case 'string':
+            return { type: 'string', ...(descriptor.format ? { format: descriptor.format } : {}) };
+        case 'uuid-or-uri':
+            return {
+                anyOf: [
+                    { type: 'string', format: 'uuid' },
+                    { type: 'string', format: 'uri' },
+                ],
+            };
+        case 'boolean':
+            return { type: 'boolean' };
+        case 'nullable-boolean':
+            return { anyOf: [{ type: 'boolean' }, { type: 'string', const: 'null' }] };
+        case 'number':
+            return { type: 'number' };
+        case 'integer':
+            return {
+                type: 'integer',
+                minimum: descriptor.minimum,
+                maximum: descriptor.maximum,
+                ...(descriptor.default === undefined ? {} : { default: descriptor.default }),
+            };
+        case 'enum':
+            return {
+                type: 'string',
+                enum: [...descriptor.values],
+                ...(descriptor.default === undefined ? {} : { default: descriptor.default }),
+            };
+        case 'csv-array':
+            return { type: 'array', items: querySchema(descriptor.items) };
+    }
+}

package/dist/openapi-document/build-openapi-request.d.mts

@@ -0,0 +1,7 @@
+import type { ComponentRegistry } from './component-registry.mts';
+import type { RequestContract } from './operation-types.mts';
+import type { OpenApiRequestBody } from './openapi-types.mts';
+export declare function buildOperationRequestBody(contract: RequestContract | undefined, registry: ComponentRegistry): {
+    requestBody: OpenApiRequestBody | undefined;
+    unavailable: boolean;
+};

package/dist/openapi-document/build-openapi-request.mjs

@@ -0,0 +1,29 @@
+import { nodeToOpenApi } from './contract-schema-to-openapi.mjs';
+export function buildOperationRequestBody(contract, registry) {
+    if (!contract)
+        return { requestBody: undefined, unavailable: false };
+    if (contract.unavailableReason) {
+        return { unavailable: true, requestBody: unavailableRequestBody(contract.unavailableReason) };
+    }
+    let schema;
+    try {
+        schema = nodeToOpenApi(contract.schema.root, {
+            definitions: contract.schema.definitions,
+            refName: registry.refName,
+        });
+    }
+    catch (error) {
+        /* v8 ignore next -- thrown values are Errors from nodeToOpenApi */
+        const reason = error instanceof Error ? error.message : String(error);
+        return { unavailable: true, requestBody: unavailableRequestBody(reason) };
+    }
+    registry.register(contract.source, contract.schema.definitions);
+    return { unavailable: false, requestBody: { content: { 'application/json': { schema } } } };
+}
+function unavailableRequestBody(reason) {
+    return {
+        content: { 'application/json': { schema: {} } },
+        'x-request-schema-unavailable': true,
+        'x-request-schema-unavailable-reason': reason,
+    };
+}

package/dist/openapi-document/build-openapi-response.d.mts

@@ -0,0 +1,9 @@
+import type { ComponentRegistry } from './component-registry.mts';
+import { type ResponseContract } from './operation-types.mts';
+import type { OpenApiResponseOrRef, OpenApiSchema } from './openapi-types.mts';
+export declare function buildOperationResponse(variants: ResponseContract[], registry: ComponentRegistry): {
+    responses: Record<number, OpenApiResponseOrRef>;
+    unavailable: boolean;
+    unavailableReason?: string;
+};
+export declare function mergeVariantSchemas(schemas: OpenApiSchema[]): OpenApiSchema;

package/dist/openapi-document/build-openapi-response.mjs

@@ -0,0 +1,111 @@
+import { STATUS_CODES } from 'node:http';
+import { nodeToOpenApi } from './contract-schema-to-openapi.mjs';
+import { responseStatusCodesForContract } from './operation-types.mjs';
+export function buildOperationResponse(variants, registry) {
+    const content = new Map();
+    const bodyless = new Map();
+    const operationFailures = [];
+    for (const contract of variants) {
+        const converted = convertContract(contract, registry);
+        if (converted.failureReason)
+            operationFailures.push(converted.failureReason);
+        if (contract.statusKnowledge === 'unknown' && !converted.failureReason)
+            operationFailures.push('response status is not statically known');
+        for (const status of responseStatusCodesForContract(contract)) {
+            if (bodyKindFor(contract) === 'none') {
+                const reasons = bodyless.get(status) ?? [];
+                if (converted.failureReason)
+                    reasons.push(converted.failureReason);
+                bodyless.set(status, reasons);
+                continue;
+            }
+            const mediaType = mediaTypeFor(contract);
+            if (!mediaType) {
+                operationFailures.push('response media type is not statically known');
+                continue;
+            }
+            const byMedia = content.get(status) ?? new Map();
+            const bucket = byMedia.get(mediaType) ?? { schemas: [], failureReasons: [] };
+            bucket.schemas.push(converted.schema ?? {});
+            if (converted.failureReason)
+                bucket.failureReasons.push(converted.failureReason);
+            byMedia.set(mediaType, bucket);
+            content.set(status, byMedia);
+        }
+    }
+    const responses = {};
+    const statuses = new Set([...bodyless.keys(), ...content.keys()]);
+    for (const status of [...statuses].toSorted((left, right) => left - right)) {
+        responses[status] = renderStatusResponse(status, content.get(status), bodyless, operationFailures);
+    }
+    const reasons = [...new Set(operationFailures)];
+    return {
+        responses,
+        unavailable: reasons.length > 0,
+        ...(reasons.length > 0 ? { unavailableReason: reasons.join('; ') } : {}),
+    };
+}
+function renderStatusResponse(status, byMedia, bodyless, operationFailures) {
+    const hasBodyless = bodyless.has(status);
+    const conflictReason = byMedia && hasBodyless
+        ? `status ${status} has both body and no-body variants`
+        : byMedia && (status === 204 || status === 205)
+            ? `status ${status} cannot carry a response body`
+            : undefined;
+    if (conflictReason)
+        operationFailures.push(conflictReason);
+    const bucketFailures = [
+        ...(bodyless.get(status) ?? []),
+        ...[...(byMedia?.values() ?? [])].flatMap((bucket) => bucket.failureReasons),
+        ...(conflictReason ? [conflictReason] : []),
+    ];
+    return {
+        description: STATUS_CODES[status] ?? 'Response',
+        ...(!conflictReason && byMedia
+            ? {
+                content: Object.fromEntries([...byMedia.entries()]
+                    .toSorted(([left], [right]) => left.localeCompare(right))
+                    .map(([mediaType, bucket]) => [
+                    mediaType,
+                    { schema: mergeVariantSchemas(bucket.schemas) },
+                ])),
+            }
+            : {}),
+        ...(bucketFailures.length > 0
+            ? {
+                'x-schema-unavailable': true,
+                'x-schema-unavailable-reason': [...new Set(bucketFailures)].join('; '),
+            }
+            : {}),
+    };
+}
+function convertContract(contract, registry) {
+    if (contract.unavailableReason)
+        return { failureReason: contract.unavailableReason };
+    let schema;
+    try {
+        schema = nodeToOpenApi(contract.schema.root, {
+            definitions: contract.schema.definitions,
+            refName: registry.refName,
+        });
+    }
+    catch (error) {
+        /* v8 ignore start */
+        return { failureReason: error instanceof Error ? error.message : String(error) };
+        /* v8 ignore stop */
+    }
+    registry.register(contract.source, contract.schema.definitions);
+    return { schema };
+}
+function mediaTypeFor(contract) {
+    if (contract.mediaTypeKnowledge === 'unknown')
+        return undefined;
+    return contract.mediaType ?? 'application/json';
+}
+function bodyKindFor(contract) {
+    return contract.bodyKind ?? (contract.schema.root.type === 'null' ? 'none' : 'content');
+}
+export function mergeVariantSchemas(schemas) {
+    const unique = [...new Map(schemas.map((schema) => [JSON.stringify(schema), schema])).values()];
+    return unique.length === 1 ? unique[0] : { anyOf: unique };
+}

package/dist/openapi-document/component-registry.d.mts

@@ -0,0 +1,9 @@
+import type { ContractSchemaNode } from './contract-schema-types.mts';
+import type { OpenApiSchema } from './openapi-types.mts';
+export type ComponentRegistry = {
+    refName: (rawName: string) => string;
+    register: (source: string, definitions: Record<string, ContractSchemaNode>) => void;
+    schemas: () => Record<string, OpenApiSchema>;
+};
+export declare function sanitizeComponentName(rawName: string): string;
+export declare function createComponentRegistry(): ComponentRegistry;

package/dist/openapi-document/component-registry.mjs

@@ -0,0 +1,49 @@
+import { createHash } from 'node:crypto';
+import { nodeToOpenApi } from './contract-schema-to-openapi.mjs';
+export function sanitizeComponentName(rawName) {
+    return rawName
+        .replace(/[<,]/g, '_')
+        .replace(/>/g, '')
+        .replace(/[^A-Za-z0-9._-]/g, '_');
+}
+export function createComponentRegistry() {
+    const sanitizedNames = new Map();
+    const entries = new Map();
+    function refName(rawName) {
+        const existing = sanitizedNames.get(rawName);
+        if (existing)
+            return existing;
+        const sanitized = sanitizeComponentName(rawName);
+        sanitizedNames.set(rawName, sanitized);
+        return sanitized;
+    }
+    function register(source, definitions) {
+        const rawNames = Object.keys(definitions).toSorted((left, right) => left.localeCompare(right));
+        const pending = new Map();
+        for (const rawName of rawNames) {
+            const sanitized = refName(rawName);
+            const schema = nodeToOpenApi(definitions[rawName], { definitions, refName });
+            const hash = createHash('sha256').update(JSON.stringify(schema)).digest('hex');
+            const existing = entries.get(sanitized) ?? pending.get(sanitized);
+            if (existing) {
+                if (existing.hash !== hash) {
+                    throw new Error([
+                        `OpenAPI component "${sanitized}" (raw name "${rawName}") maps to conflicting shapes.`,
+                        `Existing source: ${existing.source}`,
+                        `Conflicting source: ${source}`,
+                    ].join('\n'));
+                }
+                continue;
+            }
+            pending.set(sanitized, { hash, source, schema });
+        }
+        for (const [sanitized, entry] of pending)
+            entries.set(sanitized, entry);
+    }
+    function schemas() {
+        return Object.fromEntries([...entries.entries()]
+            .toSorted(([left], [right]) => left.localeCompare(right))
+            .map(([name, entry]) => [name, entry.schema]));
+    }
+    return { refName, register, schemas };
+}

package/dist/openapi-document/contract-schema-canonical.d.mts

@@ -0,0 +1,4 @@
+import type { ContractSchema, ContractSchemaNode } from './contract-schema-types.mts';
+export declare function canonicalContractSchema(schema: ContractSchema): string;
+export declare function hashContractSchema(schema: ContractSchema): string;
+export declare function canonicalContractSchemaNode(node: ContractSchemaNode): string;

package/dist/openapi-document/contract-schema-canonical.mjs

@@ -0,0 +1,23 @@
+import { createHash } from 'node:crypto';
+export function canonicalContractSchema(schema) {
+    return JSON.stringify(sortSchemaValue(schema));
+}
+export function hashContractSchema(schema) {
+    return createHash('sha256').update(canonicalContractSchema(schema)).digest('hex');
+}
+function sortSchemaValue(value, parentKey) {
+    if (Array.isArray(value)) {
+        const sorted = value.map((item) => sortSchemaValue(item));
+        return parentKey === 'variants'
+            ? sorted.toSorted((left, right) => JSON.stringify(left).localeCompare(JSON.stringify(right)))
+            : sorted;
+    }
+    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, key)]));
+}
+export function canonicalContractSchemaNode(node) {
+    return JSON.stringify(sortSchemaValue(node));
+}

package/dist/openapi-document/contract-schema-intersection-merge.d.mts

@@ -0,0 +1,13 @@
+import type { ContractSchemaNode } from './contract-schema-types.mts';
+import type { OpenApiConverterContext } from './contract-schema-to-openapi.mts';
+import type { OpenApiSchema } from './openapi-types.mts';
+/**
+ * Structurally merges an all-object intersection instead of emitting raw `allOf`: the
+ * extractor defaults `additionalProperties:false`, so `allOf` of two closed objects is
+ * unsatisfiable. Falls back to raw `allOf` only when a member isn't an object (directly or
+ * via `ref`), where that unsatisfiability concern doesn't apply. `nodeToOpenApi` is passed in
+ * (rather than imported) so this module doesn't form an import cycle with the dispatcher.
+ */
+export declare function intersectionToOpenApi(node: Extract<ContractSchemaNode, {
+    type: 'intersection';
+}>, ctx: OpenApiConverterContext, nodeToOpenApi: (node: ContractSchemaNode, ctx: OpenApiConverterContext) => OpenApiSchema): OpenApiSchema;

package/dist/openapi-document/contract-schema-intersection-merge.mjs

@@ -0,0 +1,96 @@
+import { hashContractSchema } from './contract-schema-canonical.mjs';
+/**
+ * Structurally merges an all-object intersection instead of emitting raw `allOf`: the
+ * extractor defaults `additionalProperties:false`, so `allOf` of two closed objects is
+ * unsatisfiable. Falls back to raw `allOf` only when a member isn't an object (directly or
+ * via `ref`), where that unsatisfiability concern doesn't apply. `nodeToOpenApi` is passed in
+ * (rather than imported) so this module doesn't form an import cycle with the dispatcher.
+ */
+export function intersectionToOpenApi(node, ctx, nodeToOpenApi) {
+    const resolved = node.variants.map((variant) => resolveObjectVariant(variant, ctx.definitions));
+    if (resolved.some((variant) => variant === undefined)) {
+        return { allOf: node.variants.map((variant) => nodeToOpenApi(variant, ctx)) };
+    }
+    const properties = {};
+    for (const variant of resolved) {
+        for (const [key, property] of Object.entries(variant.properties)) {
+            const existing = properties[key];
+            if (existing &&
+                hashSchemaNode(existing.schema, ctx) !== hashSchemaNode(property.schema, ctx)) {
+                // A member re-declaring a shared key with a strictly narrower type is a common, valid
+                // TypeScript intersection idiom (e.g. `Omit`-free overriding of an optional/nullable
+                // field to a guaranteed-present one) — TypeScript itself resolves the property to the
+                // narrower type, not a conflict. Prefer whichever side is the narrower one; only two
+                // genuinely incompatible schemas (neither a subset of the other) are a real conflict.
+                if (isNarrowerVariant(property.schema, existing.schema, ctx)) {
+                    properties[key] = {
+                        schema: property.schema,
+                        required: existing.required || property.required,
+                    };
+                    continue;
+                }
+                /* v8 ignore next 6 -- symmetric of the previous branch; covered by order-swapped fixtures */
+                if (isNarrowerVariant(existing.schema, property.schema, ctx)) {
+                    properties[key] = {
+                        schema: existing.schema,
+                        required: existing.required || property.required,
+                    };
+                    continue;
+                }
+                throw new Error(`Cannot merge intersection: property "${key}" has conflicting schemas across members`);
+            }
+            properties[key] = {
+                schema: property.schema,
+                required: existing?.required || property.required,
+            };
+        }
+    }
+    const sortedKeys = Object.keys(properties).toSorted();
+    const required = sortedKeys.filter((key) => properties[key].required);
+    return {
+        type: 'object',
+        properties: Object.fromEntries(sortedKeys.map((key) => [key, nodeToOpenApi(properties[key].schema, ctx)])),
+        ...(required.length > 0 ? { required } : {}),
+        additionalProperties: false,
+    };
+}
+// Bounds intersection-merge ref resolution so a cyclic or pathologically deep `definitions`
+// chain can't hang the converter; falls back to raw `allOf` if the object is still unresolved
+// past this many hops (comfortably above the extractor's actual definition-nesting depths).
+const MAX_REF_RESOLUTION_HOPS = 5;
+function resolveObjectVariant(node, definitions) {
+    const resolved = resolveRef(node, definitions);
+    return resolved.type === 'object' ? resolved : undefined;
+}
+/** Follows a `ref` chain (bounded by `MAX_REF_RESOLUTION_HOPS`) to its underlying node, whatever shape that turns out to be. Returns the node unchanged if it isn't a `ref`, or if the chain doesn't resolve within the hop budget. */
+function resolveRef(node, definitions) {
+    let current = node;
+    for (let hop = 0; hop < MAX_REF_RESOLUTION_HOPS && current.type === 'ref'; hop++) {
+        const next = definitions[current.name];
+        if (!next)
+            return current;
+        current = next;
+    }
+    return current;
+}
+function hashSchemaNode(node, ctx) {
+    return hashContractSchema({ root: node, definitions: ctx.definitions });
+}
+/**
+ * True when every value `narrow` accepts is also accepted by `wide` — i.e. `narrow`'s own variant
+ * set (a non-union schema is its own single-variant set) is a subset of `wide`'s. Covers the
+ * realistic case this converter needs to handle (an intersection member narrowing a shared
+ * optional/nullable property to a guaranteed-present one, e.g. `string | null` narrowed to
+ * `string`) without attempting full structural subtyping for arbitrary object shapes.
+ *
+ * Both sides are `ref`-resolved first: a shared property declared with its own named union alias
+ * (e.g. `post_type: PostType`) extracts as a `ref` to that alias, not an inline `union` node, so
+ * checking `.type === 'union'` on the raw node would miss it entirely.
+ */
+function isNarrowerVariant(narrow, wide, ctx) {
+    const resolvedNarrow = resolveRef(narrow, ctx.definitions);
+    const resolvedWide = resolveRef(wide, ctx.definitions);
+    const narrowVariants = resolvedNarrow.type === 'union' ? resolvedNarrow.variants : [resolvedNarrow];
+    const wideHashes = new Set((resolvedWide.type === 'union' ? resolvedWide.variants : [resolvedWide]).map((variant) => hashSchemaNode(variant, ctx)));
+    return narrowVariants.every((variant) => wideHashes.has(hashSchemaNode(variant, ctx)));
+}

package/dist/openapi-document/contract-schema-to-openapi.d.mts

@@ -0,0 +1,7 @@
+import type { ContractSchemaNode } from './contract-schema-types.mts';
+import type { OpenApiSchema } from './openapi-types.mts';
+export type OpenApiConverterContext = {
+    definitions: Record<string, ContractSchemaNode>;
+    refName: (name: string) => string;
+};
+export declare function nodeToOpenApi(node: ContractSchemaNode, ctx: OpenApiConverterContext): OpenApiSchema;