vouchington-tooling 0.0.9 → 0.0.11

package/dist/gha-artifacts-cleanup/plan.mjs

@@ -0,0 +1,40 @@
+export function summarize(deleted) {
+    return {
+        deletedCount: deleted.length,
+        bytesFreed: deleted.reduce((total, artifact) => total + artifact.size_in_bytes, 0),
+    };
+}
+export function planRunDeletions(artifacts, classify) {
+    return artifacts.filter((artifact) => !artifact.expired && classify(artifact.name) === 'delete');
+}
+export function isSweepCandidate(artifact, cutoffIso, classify) {
+    return (!artifact.expired && artifact.created_at < cutoffIso && classify(artifact.name) === 'delete');
+}
+const MAX_CONSECUTIVE_EXPIRED_PAGES = 5;
+const MAX_PAGES = 150;
+export function shouldStopPaging(pageArtifacts, state) {
+    if (state.page >= MAX_PAGES)
+        return true;
+    if (pageArtifacts.length === 0)
+        return true;
+    return state.consecutiveExpiredPages >= MAX_CONSECUTIVE_EXPIRED_PAGES;
+}
+export function nextPagingState(pageArtifacts, state) {
+    const pageFullyExpired = pageArtifacts.every((artifact) => artifact.expired);
+    return {
+        page: state.page + 1,
+        consecutiveExpiredPages: pageFullyExpired ? state.consecutiveExpiredPages + 1 : 0,
+    };
+}
+export async function planSweepDeletions(candidates, getConclusion) {
+    const toDelete = [];
+    for (const artifact of candidates) {
+        const runId = artifact.workflow_run?.id;
+        if (runId == null)
+            continue;
+        const conclusion = await getConclusion(runId);
+        if (conclusion === 'success' || conclusion === 'cancelled')
+            toDelete.push(artifact);
+    }
+    return toDelete;
+}

package/dist/gha-selected-files/index.d.mts

@@ -0,0 +1,6 @@
+export declare function encodeSelectedFiles(files: readonly string[]): string;
+export declare const SELECTED_FILES_ENV_MAX_BYTES = 120000;
+export declare function selectedFilesExceedEnvBudget(files: readonly string[]): boolean;
+export declare function decodeSelectedFiles(raw: string | undefined | null): string[];
+export declare function formatMultilineOutput(key: string, value: string, createId?: () => string): string;
+export declare function writeSelectedFilesOutput(key: string, files: readonly string[], createId?: () => string): void;

package/dist/gha-selected-files/index.mjs

@@ -0,0 +1,38 @@
+import { randomUUID } from 'node:crypto';
+import { appendFileSync } from 'node:fs';
+export function encodeSelectedFiles(files) {
+    return files.join('\n');
+}
+// Linux MAX_ARG_STRLEN is 131072. GitHub Actions interpolates selected-file
+// lists into a step env block, so the encoded list plus the variable prefix
+// must fit in one exec argument.
+export const SELECTED_FILES_ENV_MAX_BYTES = 120_000;
+export function selectedFilesExceedEnvBudget(files) {
+    return Buffer.byteLength(encodeSelectedFiles(files), 'utf8') > SELECTED_FILES_ENV_MAX_BYTES;
+}
+export function decodeSelectedFiles(raw) {
+    if (!raw)
+        return [];
+    return raw.split('\n').filter((file) => file.trim().length > 0);
+}
+export function formatMultilineOutput(key, value, createId = randomUUID) {
+    const delimiter = collisionFreeDelimiter(key, value, createId);
+    const body = value === '' ? '' : `${value}\n`;
+    return `${key}<<${delimiter}\n${body}${delimiter}\n`;
+}
+export function writeSelectedFilesOutput(key, files, createId = randomUUID) {
+    const target = process.env.GITHUB_OUTPUT;
+    if (target) {
+        appendFileSync(target, formatMultilineOutput(key, encodeSelectedFiles(files), createId));
+    }
+    console.log(`[select] ${key} (${files.length} file${files.length === 1 ? '' : 's'})`);
+}
+function collisionFreeDelimiter(key, value, createId) {
+    const prefix = key.toUpperCase().replace(/[^A-Z0-9]/g, '_');
+    for (let attempt = 0; attempt < 10; attempt += 1) {
+        const candidate = `${prefix}_${createId().toUpperCase().replaceAll('-', '_')}`;
+        if (!value.includes(candidate))
+            return candidate;
+    }
+    throw new Error(`could not create a collision-free GitHub output delimiter for ${key} after 10 attempts`);
+}

package/dist/http-origin/index.d.mts

@@ -0,0 +1 @@
+export declare function validateOptionalHttpOrigin(value: string, fieldName?: string): void;

package/dist/http-origin/index.mjs

@@ -0,0 +1,23 @@
+export function validateOptionalHttpOrigin(value, fieldName = 'origin') {
+    if (!value)
+        return;
+    let url;
+    try {
+        url = new URL(value);
+    }
+    catch {
+        throw invalidOriginError(fieldName);
+    }
+    if (!['http:', 'https:'].includes(url.protocol) ||
+        url.username !== '' ||
+        url.password !== '' ||
+        url.pathname !== '/' ||
+        url.search !== '' ||
+        url.hash !== '' ||
+        ![url.origin, `${url.origin}/`].includes(value)) {
+        throw invalidOriginError(fieldName);
+    }
+}
+function invalidOriginError(fieldName) {
+    return new Error(`${fieldName} must be empty or a pure HTTP(S) origin without credentials, path, query, or fragment`);
+}

package/dist/index.d.mts

@@ -9,5 +9,14 @@ export { createVitestBlobManifest, inspectVitestBlobBundle, parseVitestBlobManif
 export type { InspectedVitestBlobBundle, VitestBlobIdentity, VitestBlobManifest, } from './vitest-blob-manifest/index.mts';
 export { findWorkspaceLinkMismatches, formatReleaseAgeFailure, INSTALL_TERMINATION_FAILED, isReleaseAgeViolation, parseInstallOptions, parseReleaseAgeViolations, runInstallLifecycle, } from './pnpm-install/index.mts';
 export type { InstallOptions, Lifecycle } from './pnpm-install/index.mts';
-export { buildContextFromTrackedFiles, buildSharedContext, gitEnv, runNamedChecks, } from './shared-context/index.mts';
-export type { NamedCheck, SharedContext } from './shared-context/index.mts';
+export { buildContextFromTrackedFiles, buildSharedContext, clearFakeGitEnv, gitEnv, installFakeGit, runNamedChecks, setFakeGitTrackedFiles, } from './shared-context/index.mts';
+export type { FakeGitOptions, NamedCheck, SharedContext } from './shared-context/index.mts';
+export { decodeSelectedFiles, encodeSelectedFiles, formatMultilineOutput, SELECTED_FILES_ENV_MAX_BYTES, selectedFilesExceedEnvBudget, writeSelectedFilesOutput, } from './gha-selected-files/index.mts';
+export { createArtifactClassifier, parseArtifactPatternsJson, planRunDeletions, runCleanup, sweepCleanup, } from './gha-artifacts-cleanup/index.mts';
+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

@@ -4,4 +4,10 @@ export { dollarQuoteEnd, lineOf, maskSqlQuotedText, readDollarQuoteDelimiter, re
 export { auditCiJobRuntime, parseWorkflowNameMatch } from './gha-runtime-audit/index.mjs';
 export { createVitestBlobManifest, inspectVitestBlobBundle, parseVitestBlobManifest, serializeVitestBlobManifest, VITEST_BLOB_MANIFEST_FILENAME, VITEST_BLOB_MANIFEST_VERSION, vitestBlobBundlePaths, writeVitestBlobManifest, } from './vitest-blob-manifest/index.mjs';
 export { findWorkspaceLinkMismatches, formatReleaseAgeFailure, INSTALL_TERMINATION_FAILED, isReleaseAgeViolation, parseInstallOptions, parseReleaseAgeViolations, runInstallLifecycle, } from './pnpm-install/index.mjs';
-export { buildContextFromTrackedFiles, buildSharedContext, gitEnv, runNamedChecks, } from './shared-context/index.mjs';
+export { buildContextFromTrackedFiles, buildSharedContext, clearFakeGitEnv, gitEnv, installFakeGit, runNamedChecks, setFakeGitTrackedFiles, } from './shared-context/index.mjs';
+export { decodeSelectedFiles, encodeSelectedFiles, formatMultilineOutput, SELECTED_FILES_ENV_MAX_BYTES, selectedFilesExceedEnvBudget, writeSelectedFilesOutput, } from './gha-selected-files/index.mjs';
+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;