zopia 0.3.0

package/src/conversions/openapi-contracts.ts

@@ -0,0 +1,333 @@
+import { ZopiaError } from '../errors';
+import type { OpenApiOperationIR } from './openapi-ir';
+import type { OpenApiDocument } from './openapi';
+import { decodeJsonPointerSegment, resolveOpenApiLocalRef } from './openapi-ref';
+
+/** Normalized non-body operation parameter consumed by endpoint rendering. */
+export interface OperationParameter {
+  /** Exact source parameter name. */
+  name: string;
+  /** Supported OpenAPI parameter location. */
+  in: 'path' | 'query' | 'header' | 'cookie';
+  /** Whether callers must provide the parameter. */
+  required: boolean;
+  /** Resolved JSON Schema for the parameter value, when present. */
+  schema?: unknown;
+  /** Reusable parameter component whose bare `$ref` declared this parameter (D-18); absent for inline or sibling-merged resolutions. */
+  reusable?: string;
+}
+
+/** Normalized request, parameter, and response contracts for one operation. */
+export interface OperationContracts {
+  /** Resolved non-body operation parameters. */
+  parameters: OperationParameter[];
+  /** Primary request body contract, when the operation accepts a body. */
+  requestBody?: {
+    /** Selected request media type. */
+    contentType: string;
+    /** Resolved request JSON Schema, when present. */
+    schema?: unknown;
+    /** Whether callers must provide a request body. */
+    required: boolean;
+    /** Reusable parameter component whose bare `$ref` declared a Swagger `in: body` parameter (D-18). */
+    reusable?: string;
+    /** Reusable parameter component names for each bare-`$ref` formData property (D-18). */
+    formDataReusable?: Record<string, string>;
+  };
+  /** Response contracts in source-document order. */
+  responses: Array<{
+    /** Original response status key. */
+    status: string;
+    /** Required OpenAPI response description. */
+    description: string;
+    /** Selected response media type, when the response has content. */
+    contentType?: string;
+    /** Resolved response JSON Schema, when present. */
+    schema?: unknown;
+    /** Reusable response component whose bare `$ref` declared this status (D-18); absent for inline or sibling-merged resolutions. */
+    reusable?: string;
+  }>;
+}
+
+function firstContent(content: unknown): { contentType?: string; schema?: unknown } {
+  if (content === undefined) return {};
+  if (!content || typeof content !== 'object' || Array.isArray(content)) throw new ZopiaError('ZOPIA_SPEC_INVALID', 'Invalid content: expected an object');
+  const entries = Object.entries(content as Record<string, any>);
+  if (entries.length === 0) return {};
+  const [contentType, media] = entries.find(([type]) => type.toLowerCase() === 'application/json') ?? entries[0];
+  if (!contentType || !media || typeof media !== 'object' || Array.isArray(media)) throw new ZopiaError('ZOPIA_SPEC_INVALID', `Invalid media type content: ${contentType}`);
+  return { contentType, schema: media.schema };
+}
+
+function primarySwaggerMediaType(value: unknown): string | undefined {
+  if (!Array.isArray(value)) return undefined;
+  const types = value.filter((item): item is string => typeof item === 'string' && item.length > 0);
+  return types.find((type) => type.toLowerCase() === 'application/json' || type.toLowerCase().endsWith('+json')) ?? types[0];
+}
+
+function assertSwaggerMediaTypes(value: unknown, field: 'consumes' | 'produces', at: string): void {
+  if (value !== undefined && (!Array.isArray(value) || !value.every((item) => typeof item === 'string' && item.length > 0))) throw new ZopiaError('ZOPIA_SPEC_INVALID', `Invalid Swagger ${field}: ${at}`);
+}
+
+const SWAGGER_SCHEMA_KEYS = new Set(['format', 'items', 'default', 'maximum', 'exclusiveMaximum', 'minimum', 'exclusiveMinimum', 'maxLength', 'minLength', 'pattern', 'maxItems', 'minItems', 'uniqueItems', 'enum', 'multipleOf']);
+const SWAGGER_PARAMETER_TYPES = new Set(['string', 'number', 'integer', 'boolean', 'array']);
+
+function isValidSwaggerItems(value: unknown, seen = new Set<object>()): boolean {
+  if (!value || typeof value !== 'object' || Array.isArray(value) || seen.has(value)) return false;
+  seen.add(value);
+  const type = (value as Record<string, unknown>).type;
+  return SWAGGER_PARAMETER_TYPES.has(type as string) && (type !== 'array' || isValidSwaggerItems((value as Record<string, unknown>).items, seen));
+}
+
+/**
+ * Test whether a response key is valid for the selected source dialect.
+ *
+ * @param status Response-object key to validate.
+ * @param swagger Whether the target dialect is Swagger 2.0.
+ * @returns Whether the key is `default`, an exact HTTP status, or an OpenAPI range.
+ */
+export function isValidResponseStatus(status: string, swagger: boolean): boolean {
+  return status === 'default' || /^[1-5]\d{2}$/.test(status) || !swagger && /^[1-5]XX$/.test(status);
+}
+
+function pathParameterNames(path: string): Set<string> {
+  return new Set([...path.matchAll(/\{([^{}]+)\}/g)].map((match) => match[1]));
+}
+
+/**
+ * Derive the effective schema of a Swagger 2.0 non-body/formData parameter.
+ *
+ * @param parameter Validated Swagger parameter object.
+ * @returns The parameter's top-level constraint keywords as a JSON Schema (`file` renders as `string`/`binary`).
+ */
+export function swaggerParameterSchema(parameter: Record<string, any>): Record<string, unknown> {
+  return {
+    type: parameter.type === 'file' ? 'string' : parameter.type,
+    ...(parameter.type === 'file' ? { format: 'binary' } : {}),
+    ...Object.fromEntries(Object.entries(parameter).filter(([key]) => SWAGGER_SCHEMA_KEYS.has(key))),
+  };
+}
+
+/** Reusable non-schema component kinds emitted as standalone modules in components mode (D-18). */
+export type ReusableComponentKind = 'parameter' | 'response';
+
+/** Namespace table for reusable parameter/response references per source dialect (D-18). */
+const REUSABLE_REF_ROOTS = {
+  parameter: { openapi: '#/components/parameters/', swagger: '#/parameters/' },
+  response: { openapi: '#/components/responses/', swagger: '#/responses/' },
+} as const;
+
+/**
+ * Detect a bare reusable parameter/response reference (`{ "$ref": <namespace>/<name> }` with no sibling keys).
+ *
+ * Sibling-merged references resolve inline and therefore never receive a component import (D-18).
+ *
+ * @param raw Raw source node (parameter or response object, before local-reference resolution).
+ * @param kind Reusable namespace to match.
+ * @param swagger Whether the source dialect is Swagger 2.0.
+ * @returns The decoded component name when `raw` is a bare namespace reference, otherwise `undefined`.
+ */
+export function bareReusableReferenceName(raw: unknown, kind: ReusableComponentKind, swagger: boolean): string | undefined {
+  if (!raw || typeof raw !== 'object' || Array.isArray(raw)) return undefined;
+  const entries = Object.entries(raw as Record<string, unknown>);
+  if (entries.length !== 1 || entries[0][0] !== '$ref' || typeof entries[0][1] !== 'string') return undefined;
+  const prefix = REUSABLE_REF_ROOTS[kind][swagger ? 'swagger' : 'openapi'];
+  if (!entries[0][1].startsWith(prefix)) return undefined;
+  const suffix = entries[0][1].slice(prefix.length);
+  return suffix.includes('/') || suffix === '' ? undefined : decodeJsonPointerSegment(suffix, entries[0][1]);
+}
+
+/**
+ * Read the reusable parameter/response declaration maps of a normalized document.
+ *
+ * @param document Validated Swagger/OpenAPI document.
+ * @returns Declaration maps keyed by component name (empty when the dialect container is absent).
+ */
+export function reusableDeclarations(document: OpenApiDocument): Record<ReusableComponentKind, Record<string, unknown>> {
+  const swagger = document.swagger === '2.0';
+  return {
+    parameter: (swagger ? document.parameters : document.components?.parameters) ?? {},
+    response: (swagger ? document.responses : document.components?.responses) ?? {},
+  };
+}
+
+function resolveReusableDeclaration(document: OpenApiDocument, value: unknown, kind: ReusableComponentKind, name: string): Record<string, unknown> {
+  let current = value;
+  const seen = new Set<string>();
+  while (current && typeof current === 'object' && !Array.isArray(current) && typeof (current as Record<string, unknown>).$ref === 'string') {
+    const ref = (current as Record<string, unknown>).$ref as string;
+    if (seen.has(ref)) throw new ZopiaError('ZOPIA_REF_NOT_FOUND', `Circular reusable ${kind} $ref: ${ref}`, { at: `#/components/${kind}s/${name}`, hint: 'break the reusable reference cycle' });
+    seen.add(ref);
+    const resolved = resolveOpenApiLocalRef(document, ref);
+    if (!resolved || typeof resolved !== 'object' || Array.isArray(resolved)) throw new ZopiaError('ZOPIA_SPEC_INVALID', `Invalid reusable ${kind}: ${name}`, { at: `#/components/${kind}s/${name}` });
+    current = { ...(resolved as Record<string, unknown>), ...Object.fromEntries(Object.entries(current as Record<string, unknown>).filter(([key]) => key !== '$ref')) };
+  }
+  if (!current || typeof current !== 'object' || Array.isArray(current)) throw new ZopiaError('ZOPIA_SPEC_INVALID', `Invalid reusable ${kind}: ${name}`, { at: `#/components/${kind}s/${name}` });
+  return current as Record<string, unknown>;
+}
+
+/**
+ * Derive the JSON Schema rendered into a reusable parameter component module (D-18).
+ *
+ * @param document Validated Swagger/OpenAPI document (for reference chains).
+ * @param name Reusable parameter component name (used in diagnostics).
+ * @param declaration Raw declaration object; reference chains are resolved with sibling overrides.
+ * @returns The parameter's effective schema.
+ * @throws {@link ZopiaError} when the declaration has no derivable schema (`ZOPIA_SPEC_INVALID`).
+ */
+export function deriveReusableParameterSchema(document: OpenApiDocument, name: string, declaration: unknown): unknown {
+  const parameter = resolveReusableDeclaration(document, declaration, 'parameter', name);
+  const swagger = document.swagger === '2.0';
+  if (swagger) {
+    if (typeof parameter.name !== 'string' || !parameter.name || typeof parameter.in !== 'string' || !parameter.in) throw new ZopiaError('ZOPIA_SPEC_INVALID', `Invalid reusable parameter: ${name}`, { at: `#/parameters/${name}`, hint: 'declare name and in on the reusable parameter' });
+    if (parameter.in === 'body') {
+      if (parameter.schema === undefined) throw new ZopiaError('ZOPIA_SPEC_INVALID', `Invalid Swagger body parameter: ${name}`, { at: `#/parameters/${name}` });
+      return parameter.schema;
+    }
+    if (!SWAGGER_PARAMETER_TYPES.has(parameter.type as string) && parameter.type !== 'file') throw new ZopiaError('ZOPIA_SPEC_INVALID', `Invalid Swagger parameter type: ${name}`, { at: `#/parameters/${name}` });
+    return swaggerParameterSchema(parameter);
+  }
+  if (typeof parameter.name !== 'string' || !parameter.name || !['path', 'query', 'header', 'cookie'].includes(String(parameter.in))) throw new ZopiaError('ZOPIA_SPEC_INVALID', `Invalid reusable parameter: ${name}`, { at: `#/components/parameters/${name}`, hint: 'declare name and a supported in on the reusable parameter' });
+  if (parameter.schema !== undefined && parameter.content !== undefined) throw new ZopiaError('ZOPIA_SPEC_INVALID', `Parameter cannot define both schema and content: ${name}`, { at: `#/components/parameters/${name}` });
+  if (parameter.schema !== undefined) return parameter.schema;
+  if (parameter.content !== undefined) {
+    const media = firstContent(parameter.content);
+    if (media.schema === undefined) throw new ZopiaError('ZOPIA_SPEC_INVALID', `Parameter requires schema or content: ${name}`, { at: `#/components/parameters/${name}` });
+    return media.schema;
+  }
+  throw new ZopiaError('ZOPIA_SPEC_INVALID', `Parameter requires schema or content: ${name}`, { at: `#/components/parameters/${name}`, hint: 'add a schema or content field' });
+}
+
+/**
+ * Derive the JSON Schema rendered into a reusable response component module (D-18).
+ *
+ * @param document Validated Swagger/OpenAPI document (for reference chains).
+ * @param name Reusable response component name (used in diagnostics).
+ * @param declaration Raw declaration object; reference chains are resolved with sibling overrides.
+ * @returns The primary response schema, or `undefined` for schema-less responses (which render `z.void()`).
+ * @throws {@link ZopiaError} when the declaration is not an object (`ZOPIA_SPEC_INVALID`).
+ */
+export function deriveReusableResponseSchema(document: OpenApiDocument, name: string, declaration: unknown): unknown {
+  const response = resolveReusableDeclaration(document, declaration, 'response', name);
+  const swagger = document.swagger === '2.0';
+  if (swagger) return response.schema;
+  if (response.content !== undefined) return firstContent(response.content).schema;
+  return undefined;
+}
+
+function resolveRef(value: Record<string, any>, ir: OpenApiOperationIR, context: string): Record<string, any> {
+  let current: any = value; const seen = new Set<string>();
+  while ('$ref' in current) {
+    if (typeof current.$ref !== 'string' || !current.$ref) throw new ZopiaError('ZOPIA_REF_NOT_FOUND', `Invalid ${context} $ref`);
+    if (seen.has(current.$ref)) throw new ZopiaError('ZOPIA_REF_NOT_FOUND', `Circular ${context} $ref: ${current.$ref}`);
+    seen.add(current.$ref);
+    const resolved = resolveOpenApiLocalRef(ir.document, current.$ref);
+    if (!resolved || typeof resolved !== 'object' || Array.isArray(resolved)) throw new ZopiaError('ZOPIA_REF_NOT_FOUND', `Invalid resolved ${context} $ref: ${current.$ref}`);
+    const siblings = Object.fromEntries(Object.entries(current).filter(([key]) => key !== '$ref'));
+    current = Object.keys(siblings).length ? { ...(resolved as Record<string, any>), ...siblings } : resolved;
+  }
+  return current as Record<string, any>;
+}
+
+/**
+ * Extract request and response content without losing media-type metadata.
+ *
+ * @param ir Validated operation-level intermediate representation.
+ * @returns Resolved parameter, request-body, and response contracts.
+ * @throws {@link ZopiaError} when references or contract shapes are invalid.
+ */
+export function extractOperationContracts(ir: OpenApiOperationIR): OperationContracts {
+  const operation = ir.operation;
+  const swagger = ir.document.swagger === '2.0';
+  if (swagger) for (const field of ['consumes', 'produces'] as const) {
+    assertSwaggerMediaTypes(ir.document[field], field, '#');
+    assertSwaggerMediaTypes(operation[field], field, `${ir.method} ${ir.path}`);
+  }
+  const resolvedParameters = ir.parameters.map((raw) => resolveRef(raw, ir, 'parameter'));
+  const rawReusableParameters = ir.parameters.map((raw) => bareReusableReferenceName(raw, 'parameter', swagger));
+  if (!swagger) {
+    const legacyParameter = resolvedParameters.find((parameter) => parameter.in === 'body' || parameter.in === 'formData');
+    if (legacyParameter) throw new ZopiaError('ZOPIA_SPEC_INVALID', `OpenAPI 3 does not support ${legacyParameter.in} parameters: ${ir.method} ${ir.path}`);
+    const swaggerShaped = resolvedParameters.find((parameter) => ['type', ...SWAGGER_SCHEMA_KEYS].some((key) => Object.prototype.hasOwnProperty.call(parameter, key)));
+    if (swaggerShaped) throw new ZopiaError('ZOPIA_SPEC_INVALID', `OpenAPI 3 parameter must place schema keywords under schema: ${String(swaggerShaped.name)}`);
+  } else {
+    if (operation.requestBody !== undefined) throw new ZopiaError('ZOPIA_SPEC_INVALID', `Swagger 2.0 does not support requestBody: ${ir.method} ${ir.path}`);
+    const schemaShaped = resolvedParameters.find((parameter) => parameter.in !== 'body' && (parameter.schema !== undefined || parameter.content !== undefined));
+    if (schemaShaped) throw new ZopiaError('ZOPIA_SPEC_INVALID', `Swagger non-body parameter must use top-level type keywords: ${String(schemaShaped.name)}`);
+  }
+  const parameters = resolvedParameters.flatMap((parameter, parameterIndex) => {
+    if (parameter.in === 'body' || parameter.in === 'formData') return [];
+    if (!['path', 'query', 'header', 'cookie'].includes(parameter.in) || ir.document.swagger === '2.0' && parameter.in === 'cookie' || typeof parameter.name !== 'string' || !parameter.name) throw new ZopiaError('ZOPIA_SPEC_INVALID', `Invalid parameter: ${ir.method} ${ir.path}`);
+    if (parameter.required !== undefined && typeof parameter.required !== 'boolean') throw new ZopiaError('ZOPIA_SPEC_INVALID', `Invalid parameter.required: ${parameter.name}`);
+    if (parameter.in === 'path' && parameter.required !== true) throw new ZopiaError('ZOPIA_SPEC_INVALID', `Path parameter must be required: ${parameter.name}`);
+    if (parameter.content !== undefined && parameter.schema !== undefined) throw new ZopiaError('ZOPIA_SPEC_INVALID', `Parameter cannot define both schema and content: ${parameter.name}`);
+    if (parameter.content !== undefined && (!parameter.content || typeof parameter.content !== 'object' || Array.isArray(parameter.content) || Object.keys(parameter.content).length !== 1)) throw new ZopiaError('ZOPIA_SPEC_INVALID', `Parameter content must contain exactly one media type: ${parameter.name}`);
+    const parameterContent = parameter.schema === undefined && parameter.content !== undefined ? firstContent(parameter.content) : undefined;
+    if (ir.document.swagger === '2.0' && parameter.type !== undefined && (!SWAGGER_PARAMETER_TYPES.has(parameter.type) || (parameter.type === 'array' && !isValidSwaggerItems(parameter.items)))) throw new ZopiaError('ZOPIA_SPEC_INVALID', `Invalid Swagger parameter type: ${parameter.name}`);
+    const swaggerSchema = ir.document.swagger === '2.0' && parameter.type ? swaggerParameterSchema(parameter) : undefined;
+    const schema = parameter.schema ?? parameterContent?.schema ?? swaggerSchema;
+    if (schema === undefined) throw new ZopiaError('ZOPIA_SPEC_INVALID', `Parameter requires schema or content: ${parameter.name}`);
+    const reusable = rawReusableParameters[parameterIndex];
+    return [{ name: parameter.name, in: parameter.in, required: parameter.required === true || parameter.in === 'path', schema, ...(reusable === undefined ? {} : { reusable }) }];
+  });
+  const placeholders = pathParameterNames(ir.path);
+  const pathParameters = new Set(parameters.filter((parameter) => parameter.in === 'path').map((parameter) => parameter.name));
+  const missingPathParameter = [...placeholders].find((name) => !pathParameters.has(name));
+  if (missingPathParameter) throw new ZopiaError('ZOPIA_SPEC_INVALID', `Path template parameter is not defined: ${missingPathParameter}`);
+  const unrelatedPathParameter = [...pathParameters].find((name) => !placeholders.has(name));
+  if (unrelatedPathParameter) throw new ZopiaError('ZOPIA_SPEC_INVALID', `Path parameter is not present in the template: ${unrelatedPathParameter}`);
+  let body = operation.requestBody;
+  let bodyReusable: string | undefined;
+  let formDataReusable: Record<string, string> | undefined;
+  if (body === undefined && ir.document.swagger === '2.0') {
+    const bodyEntries = [...resolvedParameters.entries()].filter(([, parameter]) => parameter.in === 'body');
+    const bodyParameter = bodyEntries[0]?.[1];
+    const formEntries = [...resolvedParameters.entries()].filter(([, parameter]) => parameter.in === 'formData');
+    const formParameters = formEntries.map(([, parameter]) => parameter);
+    if (bodyEntries.length > 1) throw new ZopiaError('ZOPIA_SPEC_INVALID', `Swagger operation cannot define multiple body parameters: ${ir.method} ${ir.path}`);
+    if (bodyParameter && formParameters.length) throw new ZopiaError('ZOPIA_SPEC_INVALID', `Swagger operation cannot combine body and formData parameters: ${ir.method} ${ir.path}`);
+    if (bodyParameter) {
+      if (typeof bodyParameter !== 'object' || typeof bodyParameter.name !== 'string' || !bodyParameter.name || !bodyParameter.schema) throw new ZopiaError('ZOPIA_SPEC_INVALID', `Invalid Swagger body parameter: ${ir.method} ${ir.path}`);
+      if (bodyParameter.required !== undefined && typeof bodyParameter.required !== 'boolean') throw new ZopiaError('ZOPIA_SPEC_INVALID', `Invalid Swagger body parameter required: ${ir.method} ${ir.path}`);
+      const consumes = Array.isArray(operation.consumes) ? operation.consumes : Array.isArray(ir.document.consumes) ? ir.document.consumes : [];
+      body = { content: { [primarySwaggerMediaType(consumes) ?? 'application/json']: { schema: bodyParameter.schema } }, required: bodyParameter.required === true };
+      bodyReusable = rawReusableParameters[bodyEntries[0][0]];
+    } else if (formParameters.length) {
+      const properties: Record<string, any> = {}; const required: string[] = [];
+      for (const parameter of formParameters) { const validTypes = new Set([...SWAGGER_PARAMETER_TYPES, 'file']); if (typeof parameter.name !== 'string' || !parameter.name || !validTypes.has(parameter.type) || (parameter.type === 'array' && !isValidSwaggerItems(parameter.items))) throw new ZopiaError('ZOPIA_SPEC_INVALID', `Invalid Swagger formData parameter: ${ir.method} ${ir.path}`); if (parameter.required !== undefined && typeof parameter.required !== 'boolean') throw new ZopiaError('ZOPIA_SPEC_INVALID', `Invalid Swagger formData required: ${parameter.name}`); properties[parameter.name] = swaggerParameterSchema(parameter); if (parameter.required === true) required.push(parameter.name); }
+      const consumes = Array.isArray(operation.consumes) ? operation.consumes : Array.isArray(ir.document.consumes) ? ir.document.consumes : [];
+      const contentType = consumes.find((value: unknown) => value === 'multipart/form-data' || value === 'application/x-www-form-urlencoded') ?? (formParameters.some((parameter: any) => parameter.type === 'file') ? 'multipart/form-data' : 'application/x-www-form-urlencoded');
+      body = { content: { [contentType]: { schema: { type: 'object', properties, ...(required.length ? { required } : {}) } } }, required: required.length > 0 };
+      const reusables = Object.fromEntries(formEntries.flatMap(([index, parameter]) => {
+        const reusable = rawReusableParameters[index];
+        return reusable === undefined ? [] : [[String(parameter.name), reusable]];
+      }));
+      if (Object.keys(reusables).length) formDataReusable = reusables;
+    }
+  }
+  const requestBody = body === undefined ? undefined : (() => {
+    if (!body || typeof body !== 'object' || Array.isArray(body)) throw new ZopiaError('ZOPIA_SPEC_INVALID', `Invalid requestBody: ${ir.method} ${ir.path}`);
+    const bodyObject = resolveRef(body, ir, 'requestBody');
+    if (bodyObject.required !== undefined && typeof bodyObject.required !== 'boolean') throw new ZopiaError('ZOPIA_SPEC_INVALID', `Invalid requestBody.required: ${ir.method} ${ir.path}`);
+    if (bodyObject.content === undefined) throw new ZopiaError('ZOPIA_SPEC_INVALID', `Invalid requestBody.content: ${ir.method} ${ir.path}`);
+    const media = firstContent(bodyObject.content);
+    if (!media.contentType) throw new ZopiaError('ZOPIA_SPEC_INVALID', `Invalid requestBody.content: ${ir.method} ${ir.path}`);
+    return { ...media, contentType: media.contentType, required: bodyObject.required === true, ...(bodyReusable === undefined ? {} : { reusable: bodyReusable }), ...(formDataReusable === undefined ? {} : { formDataReusable }) };
+  })();
+  const responses = operation.responses;
+  if (!responses || typeof responses !== 'object' || Array.isArray(responses) || Object.keys(responses).length === 0) throw new ZopiaError('ZOPIA_SPEC_INVALID', `Invalid responses: ${ir.method} ${ir.path}`);
+  return { parameters, requestBody, responses: Object.entries(responses).map(([status, value]) => {
+    if (!isValidResponseStatus(status, ir.document.swagger === '2.0')) throw new ZopiaError('ZOPIA_SPEC_INVALID', `Invalid response status: ${status}`);
+    if (!value || typeof value !== 'object' || Array.isArray(value)) throw new ZopiaError('ZOPIA_SPEC_INVALID', `Invalid response ${status}: ${ir.method} ${ir.path}`);
+    const response = resolveRef(value as Record<string, any>, ir, 'response');
+    if (typeof response.description !== 'string' || response.description.trim() === '') throw new ZopiaError('ZOPIA_SPEC_INVALID', `Invalid response description: ${status}`);
+    if (swagger && (response.content !== undefined || response.produces !== undefined)) throw new ZopiaError('ZOPIA_SPEC_INVALID', `Swagger response must use schema and operation-level produces: ${status}`);
+    if (!swagger && response.schema !== undefined) throw new ZopiaError('ZOPIA_SPEC_INVALID', `OpenAPI 3 response must place schemas under content: ${status}`);
+    const media = firstContent(response.content);
+    const schema = media.schema === undefined && response.schema !== undefined ? { schema: response.schema } : {};
+    const swaggerProduces = swagger ? (Array.isArray(operation.produces) ? operation.produces : Array.isArray(ir.document.produces) ? ir.document.produces : []) : [];
+    const contentType = media.contentType ?? primarySwaggerMediaType(swaggerProduces);
+    const reusable = bareReusableReferenceName(value, 'response', swagger);
+    return { status, description: response.description, ...media, ...schema, ...(contentType ? { contentType } : {}), ...(reusable === undefined ? {} : { reusable }) };
+  }) };
+}

package/src/conversions/openapi-external-ref.ts

@@ -0,0 +1,233 @@
+import { readFile } from 'node:fs/promises';
+import { dirname, join, normalize } from 'node:path';
+import { ZopiaError } from '../errors';
+import { resolveOpenApiLocalRef } from './openapi-ref';
+import type { OpenApiDocument } from './openapi';
+import { parseYaml } from './yaml';
+
+/** One normalized external reference target: a file in the spec folder plus a JSON Pointer. */
+interface ExternalLocation {
+  /** Normalized filesystem key used for caching and cycle detection. */
+  fileKey: string;
+  /** Display name of the file (as written in the reference, without `./`). */
+  name: string;
+  /** Path used for reading. */
+  path: string;
+  /** Raw pointer text after `#` ('' = whole document) or undefined when the fragment is unsupported. */
+  pointer: string | undefined;
+}
+
+interface BundleContext {
+  /** Normalized key of the root input file; self-file references resolve into the root document. */
+  rootKey: string;
+  /** Root document (host of self-file references and pointer validation). */
+  root: OpenApiDocument;
+  /** Parsed-file cache; every external file is read and parsed exactly once. */
+  cache: Map<string, Promise<unknown>>;
+  /** Locations currently on the expansion stack (`fileKey|pointer`) for cycle detection. */
+  chain: string[];
+  /** Active expansion depth for the nesting guard. */
+  depth: number;
+  /** Folder of the root spec file; all supported external files live here. */
+  sourceDir: string;
+}
+
+/** Maximum external-reference expansion depth before failing deterministically (R-1006). */
+const EXTERNAL_REF_DEPTH_LIMIT = 512;
+
+/** Same-folder grammar: a plain file name (no separators, no `..`/`:`/NUL, no scheme/drive) with a spec extension. */
+const EXTERNAL_FILE_PATTERN = /^(?:\.\/)?([^/\\]+\.(?:json|ya?ml))#?(.*)$/i;
+
+const escapePointer = (value: string | number): string => String(value).replace(/~/g, '~0').replace(/\//g, '~1');
+const childPointer = (at: string, value: string | number): string => `${at}/${escapePointer(value)}`;
+
+/** Structural container keys whose children are nodes (kept in sync with the preflight reference walker). */
+const STRUCTURAL_CONTAINER_KEYS = new Set(['paths', 'schemas', 'definitions', '$defs', 'properties', 'patternProperties', 'dependentSchemas', 'responses', 'content', 'headers', 'links', 'encoding', 'callbacks', 'parameters', 'requestBodies', 'securitySchemes', 'securityDefinitions', 'pathItems']);
+
+/** Literal/demo positions that must not be interpreted as real references (kept in sync with the preflight walker). */
+const LITERAL_VALUE_KEYS = new Set(['example', 'default', 'enum', 'const']);
+
+type VisitMode = 'normal' | 'map' | 'example-map' | 'example-object';
+
+/** Parse and validate a non-local `$ref` against the same-folder grammar (D-17). */
+function classifyExternalRef(ref: string, refAt: string, sourceDir: string): ExternalLocation {
+  const match = EXTERNAL_FILE_PATTERN.exec(ref);
+  const name = match?.[1];
+  if (!match || !name || name === '.' || name === '..' || name.includes('\0') || name.includes(':')) {
+    throw new ZopiaError('ZOPIA_REF_EXTERNAL', `external reference is not supported outside the spec folder: ${ref}`, { at: refAt, hint: 'use a JSON/YAML file in the same folder as the spec' });
+  }
+  const path = join(sourceDir, name);
+  return { fileKey: normalize(path), name, path, pointer: match[2] ?? '' };
+}
+
+/** Read and parse a referenced file exactly once, mirroring the input pipeline's JSON/YAML selection. */
+async function loadExternalFile(ctx: BundleContext, location: ExternalLocation, refAt: string): Promise<unknown> {
+  const cached = ctx.cache.get(location.fileKey);
+  if (cached) return cached;
+  const task = (async (): Promise<unknown> => {
+    let text: string;
+    try { text = await readFile(location.path, 'utf8'); }
+    catch (error) {
+      throw new ZopiaError('ZOPIA_REF_EXTERNAL', `unable to read external reference target: ${location.name}`, { at: refAt, hint: `check that ${location.name} exists next to the spec and is readable`, cause: error });
+    }
+    if (/\.ya?ml$/i.test(location.name)) {
+      try { return parseYaml(text); }
+      catch (error) {
+        if (error instanceof ZopiaError && error.code === 'ZOPIA_SPEC_INVALID_YAML') {
+          throw new ZopiaError('ZOPIA_SPEC_INVALID_YAML', error.message.slice(`${error.code}: `.length), { at: location.path, hint: error.hint, cause: error });
+        }
+        throw error;
+      }
+    }
+    try { return JSON.parse(text) as unknown; }
+    catch (error) {
+      throw new ZopiaError('ZOPIA_SPEC_INVALID_JSON', `invalid JSON in external reference target ${location.name}: ${error instanceof Error ? error.message : String(error)}`, { at: location.path, hint: 'fix the JSON syntax', cause: error });
+    }
+  })();
+  ctx.cache.set(location.fileKey, task);
+  return task;
+}
+
+/** Resolve an optional pointer inside a parsed external file (or the root document). */
+function resolveTarget(document: unknown, name: string, pointer: string | undefined, refAt: string): unknown {
+  if (pointer !== '' && pointer !== undefined && !pointer.startsWith('/')) {
+    throw new ZopiaError('ZOPIA_REF_NOT_FOUND', `unsupported reference fragment: ${name}#${pointer}`, { at: refAt, hint: 'use a JSON Pointer after `#` (or omit it for the whole file)' });
+  }
+  if (!pointer) return document;
+  try { return resolveOpenApiLocalRef(document as OpenApiDocument, `#${pointer}`); }
+  catch (error) {
+    if (error instanceof ZopiaError && error.code === 'ZOPIA_REF_NOT_FOUND') {
+      throw new ZopiaError('ZOPIA_REF_NOT_FOUND', `unresolved external reference: ${name}#${pointer}`, { at: refAt, hint: `check that ${name} contains the pointer ${pointer}`, cause: error });
+    }
+    throw error;
+  }
+}
+
+/** Deep-clone plain document content so spliced subtrees never share identity with their source file. */
+function cloneSpecValue(value: unknown): unknown {
+  if (Array.isArray(value)) return value.map(cloneSpecValue);
+  if (value && typeof value === 'object') return Object.fromEntries(Object.entries(value as Record<string, unknown>).map(([key, entry]) => [key, cloneSpecValue(entry)]));
+  return value;
+}
+
+/** Walk data structures exactly like the preflight reference walker, expanding supported external refs. */
+async function bundleSubtree(ctx: BundleContext, value: unknown, at: string, ownerFile: string | undefined, mode: VisitMode = 'normal'): Promise<unknown> {
+  if (!value || typeof value !== 'object') return value;
+  if (Array.isArray(value)) {
+    const items: unknown[] = [];
+    for (const [index, item] of value.entries()) items.push(await bundleSubtree(ctx, item, childPointer(at, index), ownerFile, 'normal'));
+    return items;
+  }
+  const object = value as Record<string, unknown>;
+  if ((mode === 'normal' || mode === 'example-object') && Object.prototype.hasOwnProperty.call(object, '$ref') && typeof object.$ref === 'string' && object.$ref.length > 0) {
+    let ref = object.$ref;
+    if (ref.startsWith('#')) {
+      if (ownerFile === undefined) return object; // host-document reference: stays local
+      ref = `${ownerFile}${ref}`; // a local reference inside bundled content belongs to its owning file
+    }
+    return bundleReference(ctx, object, ref, childPointer(at, '$ref'), at, ownerFile);
+  }
+  const result: Record<string, unknown> = {};
+  for (const [key, child] of Object.entries(object)) {
+    result[key] = await bundleChild(ctx, key, child, at, ownerFile, mode);
+  }
+  return result;
+}
+
+/** Bundle one child value under the preflight walker's per-key mode rules (structural maps, literals, 2.0-vs-3.x examples). */
+function bundleChild(ctx: BundleContext, key: string, child: unknown, at: string, ownerFile: string | undefined, mode: VisitMode): Promise<unknown> | unknown {
+  if (mode === 'map') return bundleSubtree(ctx, child, childPointer(at, key), ownerFile, 'normal');
+  if (mode === 'example-map') return bundleSubtree(ctx, child, childPointer(at, key), ownerFile, 'example-object');
+  if (mode === 'example-object' && key === 'value') return child;
+  if (LITERAL_VALUE_KEYS.has(key) || key.startsWith('x-')) return child;
+  if (key === 'examples') {
+    return ctx.root.swagger !== '2.0' && !Array.isArray(child)
+      ? bundleSubtree(ctx, child, childPointer(at, key), ownerFile, 'example-map')
+      : child;
+  }
+  return bundleSubtree(ctx, child, childPointer(at, key), ownerFile, STRUCTURAL_CONTAINER_KEYS.has(key) ? 'map' : 'normal');
+}
+
+function checkDepthLimit(ctx: BundleContext, at: string): void {
+  if (ctx.depth > EXTERNAL_REF_DEPTH_LIMIT) throw new ZopiaError('ZOPIA_REF_NOT_FOUND', `external reference expansion exceeds ${EXTERNAL_REF_DEPTH_LIMIT} levels at ${at}`, { at, hint: 'reduce external reference nesting' });
+}
+
+/** Expand one validated external reference: load, resolve, clone, bundle, then re-attach sibling keys. */
+async function bundleReference(ctx: BundleContext, object: Record<string, unknown>, ref: string, refAt: string, at: string, ownerFile: string | undefined): Promise<unknown> {
+  const location = classifyExternalRef(ref, refAt, ctx.sourceDir);
+  const chainKey = `${location.fileKey}|${location.pointer ?? ''}`;
+  if (ctx.chain.includes(chainKey)) {
+    const display = [...ctx.chain, chainKey].map((entry) => entry.replace(ctx.sourceDir === '.' ? '' : `${ctx.sourceDir}/`, '').replace('|', '#'));
+    throw new ZopiaError('ZOPIA_REF_NOT_FOUND', `circular external reference: ${display.join(' → ')}`, { at: refAt, hint: 'break the external reference cycle' });
+  }
+  const isRoot = location.fileKey === ctx.rootKey;
+  const targetDocument = isRoot ? ctx.root : await loadExternalFile(ctx, location, refAt);
+  const clone = cloneSpecValue(resolveTarget(targetDocument, location.name, location.pointer, refAt));
+  ctx.chain.push(chainKey);
+  ctx.depth += 1;
+  checkDepthLimit(ctx, at);
+  let bundled: unknown;
+  try { bundled = await bundleSubtree(ctx, clone, at, isRoot ? undefined : location.name); }
+  finally {
+    ctx.depth -= 1;
+    ctx.chain.pop();
+  }
+  const siblingEntries = Object.entries(object).filter(([key]) => key !== '$ref');
+  if (siblingEntries.length === 0) return bundled;
+  if (!bundled || typeof bundled !== 'object' || Array.isArray(bundled)) {
+    throw new ZopiaError('ZOPIA_REF_NOT_FOUND', `external reference ${ref} with sibling keys must target an object`, { at: refAt, hint: 'remove the sibling keys or target a mapping' });
+  }
+  // Preflight parity: sibling keys are visited with the same per-key rules as any other node,
+  // so sibling-held external references resolve too (and sibling-held literals stay literal).
+  const siblings: Record<string, unknown> = {};
+  for (const [key, value] of siblingEntries) siblings[key] = await bundleChild(ctx, key, value, at, ownerFile, 'normal');
+  return { ...(bundled as Record<string, unknown>), ...siblings };
+}
+
+/**
+ * 🔗 Bundle same-folder external `$ref`s into a file-backed OpenAPI document (D-17).
+ *
+ * References of the form `other.yaml#/pointer` (including `other.json`,
+ * `other.yml`, and `./…` spellings) are resolved against the folder of the
+ * spec file path that produced `document`, read and parsed with the same
+ * JSON/YAML rules as the primary input, and spliced in place before
+ * normalization. Nested/cross-file references inside bundled content resolve
+ * against their owning file, while local references of the host document are
+ * untouched. Locations outside the spec folder (URLs, absolute paths, `../`,
+ * subdirectories, schemes/drives) fail with `ZOPIA_REF_EXTERNAL`; unreadable
+ * targets keep that code with the file as `cause`, unparsable targets surface
+ * `ZOPIA_SPEC_INVALID_JSON`/`ZOPIA_SPEC_INVALID_YAML` at the target path, and
+ * missing pointers or circular external chains fail with
+ * `ZOPIA_REF_NOT_FOUND`. Each referenced file is read exactly once (P-1),
+ * spliced content is deep-cloned so the returned document never shares object
+ * identity with another document, and traversal skips literal/example payload
+ * positions exactly like the preflight reference walker. Reverse conversion
+ * emits the bundled single-file document and does not re-split files (D-17).
+ *
+ * @param document Parsed OpenAPI document read from a spec file.
+ * @param sourceFile Path of the spec file the document was read from; its folder bounds resolution.
+ * @returns A new document with every supported external reference resolved inline.
+ * @throws {ZopiaError} `ZOPIA_REF_*` for unsupported/unreadable/circular targets; `ZOPIA_SPEC_INVALID_JSON`/`ZOPIA_SPEC_INVALID_YAML` for unparsable targets.
+ * @example
+ * ```ts
+ * import { readFile } from 'node:fs/promises';
+ * import { bundleExternalOpenApiRefs } from './src/conversions/openapi-external-ref';
+ *
+ * const document = JSON.parse(await readFile('spec/openapi.json', 'utf8')) as Record<string, unknown>;
+ * const bundled = await bundleExternalOpenApiRefs(document as never, 'spec/openapi.json');
+ * console.log(bundled);
+ * ```
+ * @see [docs/06-conversions.md → Engine ③](../../docs/06-conversions.md)
+ */
+export async function bundleExternalOpenApiRefs(document: OpenApiDocument, sourceFile: string): Promise<OpenApiDocument> {
+  if (!document || typeof document !== 'object' || Array.isArray(document)) throw new ZopiaError('ZOPIA_SPEC_INVALID', 'expected a Swagger/OpenAPI document object', { at: '#', hint: 'provide a Swagger/OpenAPI document object' });
+  const ctx: BundleContext = {
+    rootKey: normalize(sourceFile),
+    root: document,
+    cache: new Map(),
+    chain: [],
+    depth: 0,
+    sourceDir: dirname(sourceFile),
+  };
+  return (await bundleSubtree(ctx, document, '#', undefined)) as OpenApiDocument;
+}

package/src/conversions/openapi-ir.ts

@@ -0,0 +1,74 @@
+import { ZopiaError } from '../errors';
+import { collectOpenApiOperations, collectOpenApiWebhookOperations, type OpenApiOperation } from './openapi-to-api-docs';
+import { normalizeOpenApiDocument, type OpenApiDocument } from './openapi';
+
+/** Validated operation-level intermediate representation used by Engine ③. */
+export interface OpenApiOperationIR {
+  /** Original OpenAPI path template. */
+  path: string;
+  /** Uppercase HTTP method emitted to km-api. */
+  method: Uppercase<OpenApiOperation['method']>;
+  /** km-api path shape, preserving OpenAPI parameter braces. */
+  pathShape: string;
+  /** Explicit or deterministically derived operation identifier. */
+  operationId: string;
+  /** Optional operation summary. */
+  summary?: string;
+  /** Optional operation description. */
+  description?: string;
+  /** km-api tags, normalized with `#` prefixes. */
+  tags: string[];
+  /** Whether the source operation is deprecated. */
+  deprecated: boolean;
+  /** Effective operation or document security requirements. */
+  security?: unknown[];
+  /** Original operation object. */
+  operation: Record<string, any>;
+  /** Merged path-level and operation-level parameters. */
+  parameters: any[];
+  /** Complete normalized source document used for local reference resolution. */
+  document: OpenApiDocument;
+}
+
+function security(value: unknown, context: string): unknown[] | undefined {
+  if (value === undefined) return undefined;
+  if (!Array.isArray(value) || !value.every((item) => item && typeof item === 'object' && !Array.isArray(item) && Object.entries(item).every(([name, scopes]) => name.length > 0 && Array.isArray(scopes) && scopes.every((scope) => typeof scope === 'string')))) throw new ZopiaError('ZOPIA_SPEC_INVALID', `Invalid security requirements: ${context}`);
+  return value;
+}
+
+function tags(value: unknown): string[] {
+  if (value === undefined) return [];
+  if (!Array.isArray(value) || !value.every((tag) => typeof tag === 'string')) throw new ZopiaError('ZOPIA_SPEC_INVALID', 'Invalid operation tags: expected an array of strings');
+  return value.map((tag) => tag.startsWith('#') ? tag : `#${tag}`);
+}
+
+/**
+ * Build the validated operation-level IR used by endpoint rendering.
+ *
+ * @param input Valid Swagger/OpenAPI object or JSON text.
+ * @returns Canonically ordered validated operation records.
+ * @throws {@link ZopiaError} when source operation metadata is invalid.
+ */
+export function buildOpenApiOperationIR(input: OpenApiDocument | string): OpenApiOperationIR[] {
+  const { document } = normalizeOpenApiDocument(input);
+  return [...collectOpenApiOperations(document), ...collectOpenApiWebhookOperations(document)].map((entry) => {
+    const operation = entry.operation;
+    if (operation.summary !== undefined && typeof operation.summary !== 'string') throw new ZopiaError('ZOPIA_SPEC_INVALID', `Invalid summary: ${entry.method.toUpperCase()} ${entry.path}`);
+    if (operation.description !== undefined && typeof operation.description !== 'string') throw new ZopiaError('ZOPIA_SPEC_INVALID', `Invalid description: ${entry.method.toUpperCase()} ${entry.path}`);
+    if (operation.deprecated !== undefined && typeof operation.deprecated !== 'boolean') throw new ZopiaError('ZOPIA_SPEC_INVALID', `Invalid deprecated flag: ${entry.method.toUpperCase()} ${entry.path}`);
+    return {
+      path: entry.path,
+      method: entry.method.toUpperCase() as Uppercase<OpenApiOperation['method']>,
+      pathShape: entry.path,
+      operationId: entry.operationId,
+      summary: operation.summary,
+      description: operation.description,
+      tags: tags(operation.tags),
+      deprecated: operation.deprecated === true,
+      security: Object.prototype.hasOwnProperty.call(operation, 'security') ? security(operation.security, `${entry.method.toUpperCase()} ${entry.path}`) : security(document.security, 'document'),
+      operation,
+      parameters: entry.parameters,
+      document,
+    };
+  });
+}