zopia 0.3.0

package/src/conversions/openapi-ref.ts

@@ -0,0 +1,38 @@
+import { ZopiaError } from '../errors';
+import type { OpenApiDocument } from './openapi';
+
+/**
+ * Decode one RFC 6901 JSON Pointer segment.
+ *
+ * @param segment Escaped JSON Pointer path segment.
+ * @param ref Complete reference used in error diagnostics.
+ * @returns Decoded property name.
+ * @throws {@link ZopiaError} when `segment` contains an invalid escape.
+ */
+export function decodeJsonPointerSegment(segment: string, ref = segment): string {
+  if (typeof segment !== 'string') throw new ZopiaError('ZOPIA_REF_NOT_FOUND', `invalid JSON Pointer segment: ${String(segment)}`, { at: String(ref), hint: 'use string JSON Pointer segments' });
+  let decoded: string;
+  try { decoded = decodeURIComponent(segment); }
+  catch (error) { throw new ZopiaError('ZOPIA_REF_NOT_FOUND', `Invalid percent encoding in OpenAPI reference: ${ref}`, { at: ref, hint: 'fix the local URI fragment encoding', cause: error }); }
+  if (/~(?![01])/.test(decoded)) throw new ZopiaError('ZOPIA_REF_NOT_FOUND', `Invalid JSON Pointer escape in OpenAPI reference: ${ref}`, { at: ref, hint: 'fix the local JSON Pointer escape' });
+  return decoded.replace(/~1/g, '/').replace(/~0/g, '~');
+}
+
+/**
+ * Resolve a local JSON Pointer reference in an OpenAPI document.
+ *
+ * @param document Swagger/OpenAPI document containing the target.
+ * @param ref Local reference beginning with `#`.
+ * @returns Referenced value, including explicit `null` values.
+ * @throws {@link ZopiaError} when the document, reference, or target is invalid.
+ */
+export function resolveOpenApiLocalRef(document: OpenApiDocument, ref: string): unknown {
+  if (!document || typeof document !== 'object' || Array.isArray(document)) throw new ZopiaError('ZOPIA_SPEC_INVALID', 'invalid OpenAPI document: expected an object', { at: '#', hint: 'pass a Swagger/OpenAPI document object' });
+  if (typeof ref !== 'string' || (!ref.startsWith('#/') && ref !== '#')) throw new ZopiaError('ZOPIA_REF_EXTERNAL', `Only local OpenAPI references are supported: ${String(ref)}`, { at: String(ref), hint: "use a local reference beginning with '#'" });
+  const value = ref === '#' ? document : ref.slice(2).split('/').map((part) => decodeJsonPointerSegment(part, ref)).reduce<any>((current, key) => {
+    if (current === null || (typeof current !== 'object' && typeof current !== 'function') || !Object.prototype.hasOwnProperty.call(current, key)) return undefined;
+    return current[key];
+  }, document);
+  if (value === undefined) throw new ZopiaError('ZOPIA_REF_NOT_FOUND', `Unresolved OpenAPI reference: ${ref}`, { at: ref, hint: 'check that the local JSON Pointer target exists' });
+  return value;
+}

package/src/conversions/openapi-to-api-docs-public.ts

@@ -0,0 +1,466 @@
+import { readFile } from 'node:fs/promises';
+import { ZopiaError } from '../errors';
+import { ZopiaWarningCollector, type ZopiaWarning } from '../warnings';
+import { generateApiDocsFiles } from './api-docs-generate';
+import type { ApiDocsMode } from './api-docs-layout';
+import { bundleExternalOpenApiRefs } from './openapi-external-ref';
+import { extractOperationContracts } from './openapi-contracts';
+import { buildOpenApiOperationIR } from './openapi-ir';
+import { collectOpenApiWebhookOperations } from './openapi-to-api-docs';
+import { resolveOpenApiLocalRef } from './openapi-ref';
+import { normalizeOpenApiDocument, type OpenApiDocument } from './openapi';
+import { parseYaml } from './yaml';
+import { jsonSchemaToZod, type JsonSchema } from './json-schema-to-zod';
+import { hashOpenApiDocument, ZOPIA_MANIFEST_FILE } from './manifest-writer';
+import { formatManifestStaleness, inspectZopiaManifestStaleness } from './manifest-staleness';
+import { join } from 'node:path';
+import { planPresetBuckets, ZOPIA_GENERATE_PRESETS, type ZopiaGeneratePreset, type ZopiaPresetTree } from './api-docs-presets';
+
+/** Options for generating an api-docs tree from Swagger or OpenAPI. */
+export interface ZopiaGenerateOptions {
+  /** Directory in which generated files are written. @default 'api_docs' */
+  outDir?: string;
+  /** Endpoint directory layout. @default 'directory' */
+  mode?: ApiDocsMode;
+  /** Emit one file per declared schema component. @default false */
+  insertComponents?: boolean;
+  /** Import emitted components from endpoint files. Requires `insertComponents`. @default false */
+  useComponentAsReference?: boolean;
+  /** Write the reverse-conversion manifest. @default true */
+  manifest?: boolean;
+  /** Write merge-safe per-endpoint `custom` companion modules and export them. @default false */
+  custom?: boolean;
+  /** Split generation into per-bucket sub-trees: `multi-tag` (per primary tag) or `multi-server` (per effective first server). @default undefined */
+  preset?: ZopiaGeneratePreset;
+}
+
+/** One file written by Engine ③, relative to its output directory. */
+export interface ZopiaGeneratedFile {
+  /** Portable path relative to `outDir`. */
+  path: string;
+  /** Generated artifact category. */
+  kind: 'endpoint' | 'component' | 'manifest';
+}
+
+/** Result returned by the Engine ③ public API. */
+export interface ZopiaGenerateResult {
+  /** Every file written, sorted by portable relative path. */
+  files: ZopiaGeneratedFile[];
+  /** Structured, non-fatal conversion diagnostics. */
+  warnings: ZopiaWarning[];
+  /** Manifest path relative to `outDir`, absent when `manifest` is false. */
+  manifestPath?: string;
+  /** Generated preset sub-trees, present only when a preset split actually happened. */
+  trees?: ZopiaPresetTree[];
+}
+
+interface ValidatedOptions {
+  outDir: string;
+  mode: ApiDocsMode;
+  insertComponents: boolean;
+  useComponentAsReference: boolean;
+  manifest: boolean;
+  custom: boolean;
+  preset?: ZopiaGeneratePreset;
+}
+
+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)}`;
+
+function validateOptions(options: ZopiaGenerateOptions | undefined): ValidatedOptions {
+  if (options !== undefined && (!options || typeof options !== 'object' || Array.isArray(options))) {
+    throw new ZopiaError('ZOPIA_CONFIG_INVALID', 'generate options must be an object', { hint: 'pass an options object or omit it' });
+  }
+  const value = options ?? {};
+  const known = new Set(['outDir', 'mode', 'insertComponents', 'useComponentAsReference', 'manifest', 'custom', 'preset']);
+  const unknown = Object.keys(value).find((key) => !known.has(key));
+  if (unknown) throw new ZopiaError('ZOPIA_CONFIG_INVALID', `unknown generate option: ${unknown}`, { at: unknown, hint: 'remove the unsupported option' });
+  if (value.outDir !== undefined && (typeof value.outDir !== 'string' || value.outDir.trim() === '' || value.outDir.includes('\0'))) {
+    throw new ZopiaError('ZOPIA_CONFIG_INVALID', 'outDir must be a non-empty path', { at: 'outDir', hint: 'provide a writable output directory' });
+  }
+  if (value.mode !== undefined && value.mode !== 'directory' && value.mode !== 'flat') {
+    throw new ZopiaError('ZOPIA_CONFIG_INVALID', `unsupported layout mode: ${String(value.mode)}`, { at: 'mode', hint: "use 'directory' or 'flat'" });
+  }
+  for (const key of ['insertComponents', 'useComponentAsReference', 'manifest', 'custom'] as const) {
+    if (value[key] !== undefined && typeof value[key] !== 'boolean') throw new ZopiaError('ZOPIA_CONFIG_INVALID', `${key} must be a boolean`, { at: key });
+  }
+  if (value.useComponentAsReference === true && value.insertComponents !== true) {
+    throw new ZopiaError('ZOPIA_CONFIG_INVALID', 'useComponentAsReference requires insertComponents', { at: 'useComponentAsReference', hint: 'enable `insertComponents` first' });
+  }
+  if (value.preset !== undefined && !ZOPIA_GENERATE_PRESETS.includes(value.preset)) {
+    throw new ZopiaError('ZOPIA_CONFIG_INVALID', `unsupported generate preset: ${String(value.preset)}`, { at: 'preset', hint: `use ${ZOPIA_GENERATE_PRESETS.join(' or ')}` });
+  }
+  return {
+    outDir: value.outDir ?? 'api_docs',
+    mode: value.mode ?? 'directory',
+    insertComponents: value.insertComponents ?? false,
+    useComponentAsReference: value.useComponentAsReference ?? false,
+    manifest: value.manifest ?? true,
+    custom: value.custom ?? false,
+    ...(value.preset === undefined ? {} : { preset: value.preset }),
+  };
+}
+
+const YAML_PATH_PATTERN = /\.ya?ml$/i;
+
+/** Detect inline YAML text: multi-line strings that are not JSON, or a single-line mapping entry. */
+function isInlineYamlText(text: string): boolean {
+  if (text.includes('\n')) return true;
+  const firstLine = text.trimStart();
+  return /^---(?:\s|$)/.test(firstLine) || /^[^:#{}[\],&*!|>%@`][^:]*:(?:\s|$)/.test(firstLine);
+}
+
+function asSpecDocument(parsed: unknown, at: string | undefined): OpenApiDocument {
+  if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) throw new ZopiaError('ZOPIA_SPEC_INVALID', 'expected a Swagger/OpenAPI document object', { at: at ?? '#', hint: 'provide a Swagger/OpenAPI document object' });
+  return parsed as OpenApiDocument;
+}
+
+function parseJsonSpec(text: string, source: string | undefined): OpenApiDocument {
+  let parsed: unknown;
+  try { parsed = JSON.parse(text) as unknown; }
+  catch (error) {
+    throw new ZopiaError('ZOPIA_SPEC_INVALID_JSON', `invalid JSON: ${error instanceof Error ? error.message : String(error)}`, { at: source, hint: 'fix the JSON syntax', cause: error });
+  }
+  return asSpecDocument(parsed, source);
+}
+
+function parseYamlSpec(text: string, source: string | undefined): OpenApiDocument {
+  try { return asSpecDocument(parseYaml(text), source); }
+  catch (error) {
+    if (source !== undefined && error instanceof ZopiaError && error.code === 'ZOPIA_SPEC_INVALID_YAML') {
+      const message = error.message.slice(`${error.code}: `.length);
+      throw new ZopiaError('ZOPIA_SPEC_INVALID_YAML', message, { at: source, hint: error.hint, cause: error });
+    }
+    throw error;
+  }
+}
+
+/** The parsed input document plus the spec file it was read from (when any). */
+export interface ReadOpenApiSourceInputResult {
+  /** Parsed Swagger/OpenAPI document. */
+  document: OpenApiDocument;
+  /** Input spec file path; external `$ref`s resolve against its folder (D-17). */
+  sourceFile?: string;
+}
+
+async function readInput(input: string | Record<string, unknown>): Promise<ReadOpenApiSourceInputResult> {
+  if (input && typeof input === 'object' && !Array.isArray(input)) return { document: input };
+  if (typeof input !== 'string' || input.trim() === '') {
+    throw new ZopiaError('ZOPIA_SPEC_INVALID', 'input must be a Swagger/OpenAPI object, JSON/YAML text, or a .json/.yaml/.yml file path', { at: '#', hint: 'pass a Swagger/OpenAPI document object, document text, or file path' });
+  }
+  const trimmed = input.trimStart();
+  if (trimmed.startsWith('{') || trimmed.startsWith('[')) return { document: parseJsonSpec(input, undefined) };
+  if (isInlineYamlText(input)) return { document: parseYamlSpec(input, undefined) };
+  const yamlPath = YAML_PATH_PATTERN.test(input);
+  let text: string;
+  try { text = await readFile(input, 'utf8'); }
+  catch (error) {
+    const code = yamlPath ? 'ZOPIA_SPEC_INVALID_YAML' : 'ZOPIA_SPEC_INVALID_JSON';
+    throw new ZopiaError(code, `unable to read ${yamlPath ? 'YAML' : 'JSON'} input: ${input}`, { at: input, hint: 'check that the spec file exists and is readable', cause: error });
+  }
+  if (yamlPath) return { document: parseYamlSpec(text, input), sourceFile: input };
+  if (/\.json$/i.test(input)) return { document: parseJsonSpec(text, input), sourceFile: input };
+  try { return { document: parseJsonSpec(text, input), sourceFile: input }; }
+  catch (error) {
+    if (error instanceof ZopiaError && error.code === 'ZOPIA_SPEC_INVALID_JSON') return { document: parseYamlSpec(text, input), sourceFile: input };
+    throw error;
+  }
+}
+
+function normalizePublic(document: OpenApiDocument): OpenApiDocument {
+  try { return normalizeOpenApiDocument(document).document; }
+  catch (error) {
+    if (error instanceof ZopiaError) throw error;
+    const message = error instanceof Error ? error.message : String(error);
+    if (message.includes('Unsupported OpenAPI document version')) {
+      throw new ZopiaError('ZOPIA_SPEC_UNSUPPORTED_VERSION', message, { at: '#', hint: 'supported: Swagger 2.0, OpenAPI 3.0, and OpenAPI 3.1' });
+    }
+    if (message.includes('paths must be an object')) throw new ZopiaError('ZOPIA_SPEC_MISSING_PATHS', message, { at: '#/paths' });
+    throw new ZopiaError('ZOPIA_SPEC_INVALID', message, { at: '#', hint: 'fix the invalid Swagger/OpenAPI document', cause: error });
+  }
+}
+
+function validateReferences(document: OpenApiDocument): void {
+  const stack = new Set<object>();
+  const structuralMaps = new Set(['paths', 'schemas', 'definitions', '$defs', 'properties', 'patternProperties', 'dependentSchemas', 'responses', 'content', 'headers', 'links', 'encoding', 'callbacks', 'parameters', 'requestBodies', 'securitySchemes', 'securityDefinitions', 'pathItems']);
+  type VisitMode = 'normal' | 'map' | 'example-map' | 'example-object';
+  const visit = (value: unknown, at: string, mode: VisitMode = 'normal'): void => {
+    if (!value || typeof value !== 'object') return;
+    if (stack.has(value as object)) throw new ZopiaError('ZOPIA_SPEC_INVALID', 'circular in-memory OpenAPI value', { at, hint: 'use JSON references instead of JavaScript object cycles' });
+    stack.add(value as object);
+    if (Array.isArray(value)) value.forEach((child, index) => visit(child, childPointer(at, index)));
+    else {
+      const object = value as Record<string, unknown>;
+      if ((mode === 'normal' || mode === 'example-object') && Object.prototype.hasOwnProperty.call(object, '$ref')) {
+        const refAt = childPointer(at, '$ref');
+        if (typeof object.$ref !== 'string' || object.$ref.length === 0) throw new ZopiaError('ZOPIA_REF_NOT_FOUND', 'reference must be a non-empty string', { at: refAt, hint: 'use a valid local JSON Pointer' });
+        if (!object.$ref.startsWith('#')) throw new ZopiaError('ZOPIA_REF_EXTERNAL', `external reference is not supported: ${object.$ref}`, { at: refAt, hint: 'multi-file references land in Phase 2' });
+        try { resolveOpenApiLocalRef(document, object.$ref); }
+        catch (error) { throw new ZopiaError('ZOPIA_REF_NOT_FOUND', `unresolved local reference: ${object.$ref}`, { at: refAt, hint: 'check the local JSON Pointer', cause: error }); }
+      }
+      for (const [key, child] of Object.entries(object)) {
+        const childAt = childPointer(at, key);
+        if (mode === 'map') visit(child, childAt);
+        else if (mode === 'example-map') visit(child, childAt, 'example-object');
+        else if (mode === 'example-object' && key === 'value') continue;
+        else if (['example', 'default', 'enum', 'const'].includes(key) || key.startsWith('x-')) continue;
+        else if (key === 'examples') {
+          if (document.swagger !== '2.0' && !Array.isArray(child)) visit(child, childAt, 'example-map');
+        } else visit(child, childAt, structuralMaps.has(key) ? 'map' : 'normal');
+      }
+    }
+    stack.delete(value as object);
+  };
+  visit(document, '#');
+}
+
+function primaryContent(content: unknown): [string, Record<string, any>] | undefined {
+  if (!content || typeof content !== 'object' || Array.isArray(content)) return undefined;
+  const entries = Object.entries(content as Record<string, Record<string, any>>);
+  return entries.find(([type]) => type.toLowerCase() === 'application/json') ?? entries[0];
+}
+
+function warningsForDocument(document: OpenApiDocument): ZopiaWarning[] {
+  const collector = new ZopiaWarningCollector();
+  const push = (warning: ZopiaWarning): void => { collector.add(warning); };
+  const schemaWithoutRefs = (value: unknown): unknown => {
+    if (typeof value === 'boolean') return value;
+    if (!value || typeof value !== 'object' || Array.isArray(value)) return value;
+    const object = value as Record<string, unknown>;
+    if (typeof object.$ref === 'string') {
+      const siblings = Object.fromEntries(Object.entries(object).filter(([key]) => key !== '$ref'));
+      return Object.keys(siblings).length ? schemaWithoutRefs(siblings) : true;
+    }
+    const literalKeys = new Set(['example', 'examples', 'default', 'enum', 'const']);
+    return Object.fromEntries(Object.entries(object).map(([key, child]) => {
+      if (literalKeys.has(key) || key.startsWith('x-')) return [key, child];
+      if (Array.isArray(child)) return [key, child.map((item) => item && typeof item === 'object' ? schemaWithoutRefs(item) : item)];
+      if (child && typeof child === 'object') return [key, schemaWithoutRefs(child)];
+      return [key, child];
+    }));
+  };
+  const resolveReusable = (value: any): any => {
+    let current = value;
+    const seen = new Set<string>();
+    while (current && typeof current === 'object' && typeof current.$ref === 'string' && !seen.has(current.$ref)) {
+      seen.add(current.$ref);
+      const resolved = resolveOpenApiLocalRef(document, current.$ref);
+      if (!resolved || typeof resolved !== 'object' || Array.isArray(resolved)) break;
+      current = { ...(resolved as Record<string, unknown>), ...Object.fromEntries(Object.entries(current).filter(([key]) => key !== '$ref')) };
+    }
+    return current;
+  };
+  const addSchemaWarnings = (schema: unknown, at: string): void => {
+    if (schema === undefined) return;
+    const result = jsonSchemaToZod(schemaWithoutRefs(schema) as JsonSchema);
+    collector.addRebased(result.warnings, at);
+  };
+  const addMultiContentWarning = (content: unknown, at: string): void => {
+    if (!content || typeof content !== 'object' || Array.isArray(content)) throw new ZopiaError('ZOPIA_SPEC_INVALID', `Invalid content at ${at}: expected an object`);
+    for (const [mediaType, media] of Object.entries(content)) if (!mediaType || !media || typeof media !== 'object' || Array.isArray(media)) throw new ZopiaError('ZOPIA_SPEC_INVALID', `Invalid media type content at ${at}/${escapePointer(mediaType)}`);
+    const mediaTypes = Object.keys(content);
+    if (mediaTypes.length > 1) push({ code: 'ZOPIA_WARN_MULTI_CONTENT', at, message: `using ${primaryContent(content)?.[0]} as the generated primary media type; all ${mediaTypes.length} entries remain in the manifest` });
+  };
+
+  if (Array.isArray(document.servers)) document.servers.forEach((server: any, index: number) => {
+    if (server && typeof server === 'object' && server.variables !== undefined) push({ code: 'ZOPIA_WARN_SERVER_VARIABLES', at: `#/servers/${index}/variables`, message: 'server variables are preserved in the manifest but are not represented in generated endpoint code' });
+  });
+
+  if (document.webhooks !== undefined && collectOpenApiWebhookOperations(document).length === 0) push({ code: 'ZOPIA_WARN_WEBHOOKS', at: '#/webhooks', message: 'webhooks declare no operations and are preserved verbatim in the manifest' });
+
+  if (document.swagger !== '2.0' && document.components !== undefined && (!document.components || typeof document.components !== 'object' || Array.isArray(document.components))) throw new ZopiaError('ZOPIA_SPEC_INVALID', 'Invalid OpenAPI components: expected an object');
+  const schemas = document.swagger === '2.0' ? document.definitions : document.components?.schemas;
+  if (schemas !== undefined && (!schemas || typeof schemas !== 'object' || Array.isArray(schemas))) throw new ZopiaError('ZOPIA_SPEC_INVALID', 'Invalid schema components: expected an object');
+  if (schemas && typeof schemas === 'object' && !Array.isArray(schemas)) for (const [name, schema] of Object.entries(schemas)) {
+    addSchemaWarnings(schema, `${document.swagger === '2.0' ? '#/definitions' : '#/components/schemas'}/${escapePointer(name)}`);
+  }
+
+  for (const [path, rawItem] of Object.entries(document.paths ?? {})) {
+    if (path.startsWith('x-') || !rawItem || typeof rawItem !== 'object') continue;
+    let item = rawItem as Record<string, any>;
+    const pathRefs = new Set<string>();
+    while (typeof item.$ref === 'string' && !pathRefs.has(item.$ref)) {
+      pathRefs.add(item.$ref);
+      const resolved = resolveOpenApiLocalRef(document, item.$ref);
+      if (!resolved || typeof resolved !== 'object' || Array.isArray(resolved)) break;
+      item = { ...(resolved as Record<string, any>), ...Object.fromEntries(Object.entries(item).filter(([key]) => key !== '$ref')) };
+    }
+    for (const method of ['get', 'post', 'put', 'delete', 'head', 'options', 'patch', 'trace']) {
+      const operation = item[method];
+      if (!operation || typeof operation !== 'object') continue;
+      const operationAt = `#/paths/${escapePointer(path)}/${method}`;
+      const parameters = [...(Array.isArray(item.parameters) ? item.parameters : []), ...(Array.isArray(operation.parameters) ? operation.parameters : [])];
+      parameters.forEach((rawParameter: any, index: number) => {
+        const parameter = resolveReusable(rawParameter);
+        if (!parameter || typeof parameter !== 'object') return;
+        const parameterAt = `${operationAt}/parameters/${index}`;
+        if (parameter.schema !== undefined) addSchemaWarnings(parameter.schema, `${parameterAt}/schema`);
+        else if (parameter.in === 'body') addSchemaWarnings(parameter.schema, `${parameterAt}/schema`);
+        else if (document.swagger === '2.0' && parameter.type !== undefined) {
+          const keys = ['type', 'format', 'items', 'default', 'maximum', 'exclusiveMaximum', 'minimum', 'exclusiveMinimum', 'maxLength', 'minLength', 'pattern', 'maxItems', 'minItems', 'uniqueItems', 'enum', 'multipleOf'];
+          addSchemaWarnings(Object.fromEntries(Object.entries(parameter).filter(([key]) => keys.includes(key))), parameterAt);
+        }
+      });
+      const requestBody = resolveReusable(operation.requestBody);
+      if (requestBody?.content) {
+        addMultiContentWarning(requestBody.content, `${operationAt}/requestBody/content`);
+        for (const [mediaType, media] of Object.entries(requestBody.content as Record<string, any>)) addSchemaWarnings(media?.schema, `${operationAt}/requestBody/content/${escapePointer(mediaType)}/schema`);
+      }
+      for (const [status, rawResponse] of Object.entries(operation.responses ?? {})) {
+        const response = resolveReusable(rawResponse);
+        if (!response || typeof response !== 'object') continue;
+        const responseAt = `${operationAt}/responses/${escapePointer(status)}`;
+        if (response.content) {
+          addMultiContentWarning(response.content, `${responseAt}/content`);
+          for (const [mediaType, media] of Object.entries(response.content as Record<string, any>)) addSchemaWarnings(media?.schema, `${responseAt}/content/${escapePointer(mediaType)}/schema`);
+        } else addSchemaWarnings(response.schema, `${responseAt}/schema`);
+      }
+      if (document.swagger === '2.0') {
+        const consumes = Array.isArray(operation.consumes) ? operation.consumes : document.consumes;
+        const produces = Array.isArray(operation.produces) ? operation.produces : document.produces;
+        if (Array.isArray(consumes) && consumes.length > 1) push({ code: 'ZOPIA_WARN_MULTI_CONTENT', at: `${operationAt}/consumes`, message: `using ${consumes.find((type: unknown) => typeof type === 'string' && (/[/+]json$/i.test(type) || type === 'application/json')) ?? consumes[0]} as the generated request media type; all entries remain in the manifest` });
+        if (Array.isArray(produces) && produces.length > 1) push({ code: 'ZOPIA_WARN_MULTI_CONTENT', at: `${operationAt}/produces`, message: `using ${produces.find((type: unknown) => typeof type === 'string' && (/[/+]json$/i.test(type) || type === 'application/json')) ?? produces[0]} as the generated response media type; all entries remain in the manifest` });
+      }
+    }
+  }
+
+  return collector.toArray();
+}
+
+function mapGenerationError(error: unknown): ZopiaError {
+  if (error instanceof ZopiaError && error.code !== 'ZOPIA_SCHEMA_INVALID' && error.code !== 'ZOPIA_MANIFEST_INVALID') return error;
+  const message = error instanceof ZopiaError ? error.message.slice(`${error.code}: `.length) : error instanceof Error ? error.message : String(error);
+  if (message.includes('path-item $ref') || message.includes('path item $ref')) return new ZopiaError('ZOPIA_SPEC_PATH_REF', message, { hint: 'path-item references must be valid local references', cause: error });
+  return new ZopiaError('ZOPIA_SPEC_INVALID', message, { hint: 'fix the invalid Swagger/OpenAPI document', cause: error });
+}
+
+/**
+ * Read a Swagger/OpenAPI document from an in-memory object, JSON/YAML text, or a
+ * `.json`/`.yaml`/`.yml` path — the same acceptance rules as {@link openApiToApiDocs}.
+ *
+ * @param input Swagger/OpenAPI object, JSON/YAML text, or readable JSON/YAML file path.
+ * @returns Parsed document plus the spec file path when the input named one.
+ * @throws {@link ZopiaError} `ZOPIA_SPEC_INVALID*` when the input cannot be read or parsed.
+ */
+export function readOpenApiSourceInput(input: string | Record<string, unknown>): Promise<ReadOpenApiSourceInputResult> {
+  return readInput(input);
+}
+
+/**
+ * Validate every local `$ref` inside a normalized document against the rule that
+ * references must resolve — the same scan engine ③ runs before planning.
+ *
+ * @param document Normalized Swagger/OpenAPI document to scan.
+ * @returns Nothing.
+ * @throws {@link ZopiaError} `ZOPIA_REF_NOT_FOUND`/`ZOPIA_REF_EXTERNAL`/`ZOPIA_SPEC_INVALID` located at the offending reference.
+ */
+export function validateOpenApiReferences(document: OpenApiDocument): void {
+  validateReferences(document);
+}
+
+/**
+ * Generate a reversible api-docs tree from Swagger 2.0 or OpenAPI 3.0/3.1.
+ *
+ * Accepts an in-memory document object, JSON text, YAML text, or a readable
+ * `.json`/`.yaml`/`.yml` file path (D-16). See R-641 for primary-media
+ * selection and R-408 for structured warning behavior.
+ *
+ * @param input Swagger/OpenAPI object, JSON/YAML text, or readable JSON/YAML file path.
+ * @param options Output directory, layout, component, reference, and manifest controls.
+ * @returns Sorted written-file metadata, structured warnings, and the optional manifest path.
+ * @throws {ZopiaError} `ZOPIA_CONFIG_INVALID` for invalid options and `ZOPIA_SPEC_*` or `ZOPIA_REF_*` for invalid input.
+ * @example
+ * ```ts
+ * import { openApiToApiDocs } from 'zopia';
+ *
+ * const result = await openApiToApiDocs({
+ *   openapi: '3.1.0',
+ *   info: { title: 'Example', version: '1.0.0' },
+ *   paths: {},
+ * }, { outDir: 'api_docs', mode: 'flat' });
+ * console.log(result.files);
+ * ```
+ * @see [docs/06-conversions.md → Engine ③](../../docs/06-conversions.md)
+ */
+export async function openApiToApiDocs(input: string | Record<string, unknown>, options?: ZopiaGenerateOptions): Promise<ZopiaGenerateResult> {
+  const config = validateOptions(options);
+  const inputDocument = await readInput(input);
+  const bundled = inputDocument.sourceFile ? await bundleExternalOpenApiRefs(inputDocument.document, inputDocument.sourceFile) : inputDocument.document;
+  const document = normalizePublic(bundled);
+  validateReferences(document);
+
+  if (config.preset !== undefined) {
+    const buckets = planPresetBuckets(document, config.preset);
+    if (buckets !== undefined) {
+      const presetWarnings: ZopiaWarning[] = [];
+      for (const bucket of buckets) presetWarnings.push(...bucket.warnings);
+      const trees: ZopiaPresetTree[] = [];
+      const presetFiles: ZopiaGeneratedFile[] = [];
+      for (const bucket of buckets) {
+        const generatedTree = await openApiToApiDocs(bucket.document, { ...options, preset: undefined, outDir: join(config.outDir, bucket.directory) });
+        trees.push({ name: bucket.name, directory: bucket.directory, ...(generatedTree.manifestPath === undefined ? {} : { manifestPath: `${bucket.directory}/${generatedTree.manifestPath}` }) });
+        for (const file of generatedTree.files) presetFiles.push({ ...file, path: `${bucket.directory}/${file.path}` });
+        // Descriptions stay verbatim; locations gain the bucket directory prefix so downstream tooling can navigate directly.
+        for (const warning of generatedTree.warnings) presetWarnings.push(warning.at === undefined ? warning : { ...warning, at: `${bucket.directory}/${warning.at}` });
+      }
+      presetFiles.sort((left, right) => left.path < right.path ? -1 : left.path > right.path ? 1 : 0);
+      const collector = new ZopiaWarningCollector(); collector.addAll(presetWarnings);
+      return { files: presetFiles, warnings: collector.toArray(), trees };
+    }
+  }
+
+  let hash: string;
+  try { hash = hashOpenApiDocument(document); }
+  catch (error) { throw mapGenerationError(error); }
+
+  let warnings: ZopiaWarning[];
+  try {
+    warnings = warningsForDocument(document);
+    const operations = buildOpenApiOperationIR(document);
+    for (const operation of operations) extractOperationContracts(operation);
+  } catch (error) { throw mapGenerationError(error); }
+
+  try {
+    const staleness = await inspectZopiaManifestStaleness(config.outDir, {
+      sourceSha256: hash,
+      mode: config.mode,
+      insertComponents: config.insertComponents,
+      useComponentAsReference: config.useComponentAsReference,
+      manifest: config.manifest,
+      custom: config.custom,
+    });
+    if (staleness.status === 'stale') warnings.push({
+      code: 'ZOPIA_WARN_STALE_TREE',
+      at: ZOPIA_MANIFEST_FILE,
+      message: formatManifestStaleness(staleness.reasons),
+    });
+  } catch (error) {
+    throw new ZopiaError('ZOPIA_FS_WRITE_FAILED', 'unable to inspect the existing output manifest', { at: config.outDir, cause: error });
+  }
+
+  let generated;
+  try {
+    generated = await generateApiDocsFiles(document, {
+      outputDir: config.outDir,
+      mode: config.mode,
+      insertComponents: config.insertComponents,
+      useComponentAsReference: config.useComponentAsReference,
+      manifest: config.manifest,
+      custom: config.custom,
+    });
+  } catch (error: any) {
+    if (['EACCES', 'EPERM', 'EROFS', 'ENOSPC', 'EEXIST', 'EISDIR', 'ENOTDIR'].includes(String(error?.code))) throw new ZopiaError('ZOPIA_FS_WRITE_FAILED', `unable to write api-docs tree: ${error.message}`, { at: config.outDir, cause: error });
+    throw mapGenerationError(error);
+  }
+
+  const componentSchemas = document.swagger === '2.0' ? document.definitions ?? {} : document.components?.schemas ?? {};
+  const componentFiles = new Set(config.insertComponents
+    ? ['components/index.ts', ...Object.keys(componentSchemas).map((name) => `components/${name}/index.ts`)]
+    : []);
+  const files: ZopiaGeneratedFile[] = generated.map(({ file }): ZopiaGeneratedFile => ({
+    path: file,
+    kind: file === ZOPIA_MANIFEST_FILE ? 'manifest' : componentFiles.has(file) ? 'component' : 'endpoint',
+  })).sort((left, right) => left.path < right.path ? -1 : left.path > right.path ? 1 : 0);
+  const warningCollector = new ZopiaWarningCollector(); warningCollector.addAll(warnings);
+  return { files, warnings: warningCollector.toArray(), ...(config.manifest ? { manifestPath: ZOPIA_MANIFEST_FILE } : {}) };
+}