openapi-typesafe 0.0.0 → 1.0.0-rc.0

package/package.json

@@ -1,6 +1,117 @@
 {
   "name": "openapi-typesafe",
-  "version": "0.0.0",
-  "description": "Reserved for openapi-typesafe. Contains no code.",
-  "license": "MIT"
-}
+  "description": "Convert OpenAPI 3.0 & 3.1 schemas to TypeScript",
+  "version": "1.0.0-rc.0",
+  "author": {
+    "name": "Fedor Chishchin",
+    "url": "https://github.com/fedorello"
+  },
+  "contributors": [
+    {
+      "name": "Drew Powers",
+      "email": "drew@pow.rs"
+    }
+  ],
+  "license": "MIT",
+  "bin": {
+    "openapi-typesafe": "bin/cli.js"
+  },
+  "type": "module",
+  "main": "./dist/index.mjs",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": {
+        "types": "./dist/index.d.mts",
+        "default": "./dist/index.mjs"
+      },
+      "require": {
+        "types": "./dist/index.d.cts",
+        "default": "./dist/index.cjs"
+      },
+      "default": "./dist/index.mjs"
+    },
+    "./*.js": "./*.mjs",
+    "./*": "./*"
+  },
+  "files": [
+    "bin",
+    "dist",
+    "src"
+  ],
+  "homepage": "https://github.com/openapi-typesafe/openapi-typesafe#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/openapi-typesafe/openapi-typesafe.git",
+    "directory": "packages/openapi-typesafe"
+  },
+  "keywords": [
+    "swagger",
+    "typescript",
+    "ts",
+    "dts",
+    "openapi",
+    "codegen",
+    "generation",
+    "openapi 3",
+    "node"
+  ],
+  "bugs": {
+    "url": "https://github.com/openapi-typesafe/openapi-typesafe/issues"
+  },
+  "peerDependencies": {
+    "@typescript/typescript6": "^6.0.0",
+    "typescript": ">=5.0.0"
+  },
+  "peerDependenciesMeta": {
+    "@typescript/typescript6": {
+      "optional": true
+    },
+    "typescript": {
+      "optional": true
+    }
+  },
+  "dependencies": {
+    "@redocly/openapi-core": "^1.34.22",
+    "ansi-colors": "^4.1.3",
+    "change-case": "^5.4.4",
+    "parse-json": "^8.3.0",
+    "scule": "^1.3.0",
+    "supports-color": "^11.0.0",
+    "yargs-parser": "^22.0.0"
+  },
+  "devDependencies": {
+    "@types/js-yaml": "4.0.9",
+    "@types/yargs-parser": "21.0.3",
+    "@typescript/typescript6": "6.0.2",
+    "degit": "3.10.1",
+    "dependency-cruiser": "18.7.0",
+    "execa": "^10.2.1",
+    "fast-check": "4.10.2",
+    "strip-ansi": "7.2.0",
+    "typescript": "^6.0.3",
+    "vite-node": "6.0.0"
+  },
+  "engines": {
+    "node": ">=22.12.0"
+  },
+  "scripts": {
+    "build": "unbuild",
+    "dev": "tsc -p tsconfig.build.json --watch",
+    "download:schemas": "vite-node ./scripts/download-schemas.ts",
+    "format": "biome format . --write",
+    "lint": "pnpm run lint:js && pnpm run lint:ts && pnpm run lint:deps && pnpm run lint:sizes",
+    "lint:js": "biome check .",
+    "lint:ts": "tsc --noEmit && tsc -p tsconfig.strict.json",
+    "test": "pnpm run test:js && pnpm run test:examples && pnpm run test:exports",
+    "test:js": "vitest run",
+    "test:exports": "pnpm run build && ../../scripts/check-exports.sh",
+    "test:examples": "tsc -p tsconfig.examples.json --noEmit",
+    "update:examples": "pnpm run build && pnpm run download:schemas && vite-node ./scripts/update-examples.ts",
+    "prepublish": "pnpm run build",
+    "version": "pnpm run build",
+    "lint:deps": "depcruise src --config .dependency-cruiser.cjs",
+    "test:coverage": "vitest run --coverage",
+    "lint:sizes": "vite-node scripts/size-rules/check-sizes.ts src"
+  }
+}

package/src/adapters/node-file-system/node-file-system.ts

@@ -0,0 +1,44 @@
+import fs from "node:fs";
+import { fileURLToPath } from "node:url";
+import type { FileReader, FileWriter } from "../../application/ports/file-system.js";
+import { ERROR_CODES, OpenAPITypesafeError } from "../../domain/errors.js";
+
+/** The file ports on Node's `fs`, with the failures as typed errors (ADR-011). */
+
+function causeMessage(cause: unknown): string {
+  return cause instanceof Error ? cause.message : String(cause);
+}
+
+class NodeFileSystem implements FileReader, FileWriter {
+  readText(file: URL): string {
+    try {
+      return fs.readFileSync(file, "utf8");
+    } catch (cause) {
+      throw new OpenAPITypesafeError({
+        code: ERROR_CODES.OUTPUT_READ_FAILED,
+        message: `Cannot read ${fileURLToPath(file)}: ${causeMessage(cause)}`,
+        details: { file: fileURLToPath(file) },
+        cause,
+      });
+    }
+  }
+
+  writeText(file: URL, contents: string): void {
+    try {
+      fs.mkdirSync(new URL(".", file), { recursive: true });
+      fs.writeFileSync(file, contents, "utf8");
+    } catch (cause) {
+      throw new OpenAPITypesafeError({
+        code: ERROR_CODES.OUTPUT_WRITE_FAILED,
+        message: `Cannot write ${fileURLToPath(file)}: ${causeMessage(cause)}`,
+        details: { file: fileURLToPath(file) },
+        cause,
+      });
+    }
+  }
+}
+
+/** File access for the CLI. */
+export function createNodeFileSystem(): FileReader & FileWriter {
+  return new NodeFileSystem();
+}

package/src/adapters/redocly-loader/alias-limit.ts

@@ -0,0 +1,20 @@
+import {
+  ALIAS_EXPANSION_MAX_RATIO,
+  countNodes,
+  isAliasExpansionExcessive,
+} from "../../domain/openapi/alias-expansion.js";
+
+/**
+ * The reason a parsed YAML document is refused, if its aliases expand it too far. The check runs
+ * right after parsing, before Redocly or the generator walk the document (pre-beta test plan 10.2).
+ */
+export function aliasExpansionFailure(parsed: unknown): Error | undefined {
+  const counts = countNodes(parsed);
+  if (!isAliasExpansionExcessive(counts)) {
+    return undefined;
+  }
+  return new Error(
+    `YAML aliases expand the document from ${counts.stored} to ${counts.expanded} nodes, ` +
+      `more than ${ALIAS_EXPANSION_MAX_RATIO} times its size`,
+  );
+}

package/src/adapters/redocly-loader/allowed-hosts.ts

@@ -0,0 +1,62 @@
+/**
+ * Matching URLs against the `--remote-ref-hosts` list (threat model R2, ADR-017). Both sides are
+ * compared as the WHATWG URL parser writes hosts (lower case, Punycode, dotted IPv4, compressed
+ * IPv6 in brackets), so `bücher.example`, `::1` and `api.example.com.` match the hosts they name.
+ */
+
+const DEFAULT_PORTS: Readonly<Record<string, string>> = { "http:": "80", "https:": "443" };
+const FULLY_QUALIFIED_DOT = /\.$/;
+const PORT_SUFFIX = /:(\d+)$/;
+/** Characters that end a host in a URL: an entry with them would match a different host. */
+const NOT_A_HOST = /[/?#@\\]/;
+
+interface HostEntry {
+  readonly hostname: string;
+  /** Undefined when the entry allows any port. */
+  readonly port: string | undefined;
+}
+
+/** A bare IPv6 address has two colons or more and cannot carry a port; brackets add one. */
+function withBrackets(entry: string): string {
+  const isBareIPv6 = !entry.startsWith("[") && entry.split(":").length > 2;
+  return isBareIPv6 ? `[${entry}]` : entry;
+}
+
+function hostnameOf(url: URL): string {
+  return url.hostname.replace(FULLY_QUALIFIED_DOT, "");
+}
+
+function portOf(url: URL): string {
+  return url.port === "" ? (DEFAULT_PORTS[url.protocol] ?? "") : url.port;
+}
+
+/** The written port without leading zeros, as the URL parser writes it; undefined when none. */
+function writtenPort(entry: string): string | undefined {
+  const match = PORT_SUFFIX.exec(entry);
+  return match === null ? undefined : String(Number(match[1]));
+}
+
+/** The entry as the URL parser reads it, or undefined when it is not a bare host or host:port. */
+function parseHostEntry(entry: string): HostEntry | undefined {
+  const written = withBrackets(entry.trim());
+  const candidate = `http://${written}`;
+  if (written === "" || NOT_A_HOST.test(written) || !URL.canParse(candidate)) {
+    return undefined;
+  }
+  // The port is read from the text: the parser drops a default port (`:80`), which must still
+  // limit the entry to that port.
+  return { hostname: hostnameOf(new URL(candidate)), port: writtenPort(written) };
+}
+
+/** Whether the URL's host is listed, by host name alone (any port) or with its port. */
+export function isHostAllowed(url: URL, hosts: readonly string[]): boolean {
+  const hostname = hostnameOf(url);
+  if (hostname === "") {
+    return false;
+  }
+  const port = portOf(url);
+  return hosts.map(parseHostEntry).some((entry) => {
+    const isAnyPort = entry?.port === undefined;
+    return entry?.hostname === hostname && (isAnyPort || entry.port === port);
+  });
+}

package/src/adapters/redocly-loader/bundled-ref-repair.ts

@@ -0,0 +1,65 @@
+import { escapePointerSegment, parseRefPointer } from "../../domain/openapi/json-pointer.js";
+import { findRefHolders } from "./ref-holders.js";
+
+/**
+ * Redocly 1.x bundles an external `$ref` into a component named after the raw segment of the
+ * original pointer (`a~0b`, `50%`), and writes the new local `$ref` without escaping it. Read as a
+ * JSON Pointer, `#/components/schemas/a~0b` names the key `a~b`, which does not exist, and
+ * `#/components/schemas/50%` is malformed, so the generator failed on it. This rewrites every
+ * local `$ref` that does not resolve as a pointer but does resolve segment by segment as written.
+ */
+
+const LOCAL_REF_PREFIX = "#/";
+
+function isContainer(value: unknown): value is object {
+  return typeof value === "object" && value !== null;
+}
+
+function childAt(node: unknown, segment: string): unknown {
+  if (!isContainer(node) || !Object.hasOwn(node, segment)) {
+    return undefined;
+  }
+  return (node as Record<string, unknown>)[segment];
+}
+
+function resolves(document: unknown, segments: readonly string[]): boolean {
+  return segments.reduce<unknown>(childAt, document) !== undefined;
+}
+
+/** The pointer's segments, or null when the pointer has a malformed percent escape. */
+function decodedSegments(ref: string): string[] | null {
+  try {
+    return parseRefPointer(ref);
+  } catch (error) {
+    if (error instanceof URIError) {
+      return null;
+    }
+    throw error;
+  }
+}
+
+/** The repaired `$ref`, or null when the ref resolves already or cannot be repaired. */
+function repairedRef(document: unknown, ref: string): string | null {
+  const decoded = decodedSegments(ref);
+  if (decoded && resolves(document, decoded)) {
+    return null;
+  }
+  const raw = ref.slice(LOCAL_REF_PREFIX.length).split("/").filter(Boolean);
+  if (!resolves(document, raw)) {
+    return null;
+  }
+  return `${LOCAL_REF_PREFIX}${raw.map(escapePointerSegment).join("/")}`;
+}
+
+/** Repair the local `$ref`s of a bundled document in place, as Redocly's bundle edits it. */
+export function repairBundledRefs(document: unknown): void {
+  for (const { node } of findRefHolders(document)) {
+    if (!node.$ref.startsWith(LOCAL_REF_PREFIX)) {
+      continue;
+    }
+    const repaired = repairedRef(document, node.$ref);
+    if (repaired !== null) {
+      node.$ref = repaired;
+    }
+  }
+}

package/src/adapters/redocly-loader/malformed-refs.ts

@@ -0,0 +1,61 @@
+import { ERROR_CODES, OpenAPITypesafeError } from "../../domain/errors.js";
+import { parseRefPointer } from "../../domain/openapi/json-pointer.js";
+import { findRefHolders } from "./ref-holders.js";
+import type { LoadedDocument } from "./unsupported-keys.js";
+
+/**
+ * Redocly percent-decodes every JSON Pointer in a `$ref` and throws a bare `URIError` for a
+ * malformed escape such as `#/components/schemas/50%` (`%` must be written `%25`). The loader
+ * looks for these refs only after Redocly threw, and names them.
+ */
+
+/** Enough refs in the message to act on; `details.refs` has all of them. */
+const REFS_IN_MESSAGE = 5;
+
+/** A `$ref` whose pointer has a malformed percent escape, and where it is. */
+export interface MalformedRef {
+  readonly ref: string;
+  readonly pointer: string;
+  readonly source: string;
+}
+
+function isMalformed(ref: string): boolean {
+  try {
+    parseRefPointer(ref);
+    return false;
+  } catch (error) {
+    if (error instanceof URIError) {
+      return true;
+    }
+    throw error;
+  }
+}
+
+/** Every malformed `$ref` of the given documents. */
+export function findMalformedRefs(documents: readonly LoadedDocument[]): MalformedRef[] {
+  return documents.flatMap((document) =>
+    findRefHolders(document.parsed)
+      .filter(({ node }) => isMalformed(node.$ref))
+      .map(({ node, pointer }) => ({ ref: node.$ref, pointer, source: document.source })),
+  );
+}
+
+function describeRef(found: MalformedRef): string {
+  return `"${found.ref}" at ${found.pointer} in ${found.source}`;
+}
+
+/** The typed error for Redocly's `URIError`; `cause` is that error. */
+export function malformedRefsError(
+  refs: readonly MalformedRef[],
+  cause: unknown,
+): OpenAPITypesafeError {
+  const listed = refs.slice(0, REFS_IN_MESSAGE).map(describeRef);
+  const more = refs.length > REFS_IN_MESSAGE ? ` and ${refs.length - REFS_IN_MESSAGE} more` : "";
+  const where = listed.length === 0 ? "" : `: ${listed.join(", ")}${more}`;
+  return new OpenAPITypesafeError({
+    code: ERROR_CODES.SCHEMA_REF_INVALID,
+    message: `A $ref has a malformed percent escape; write "%" as "%25" in a JSON Pointer${where}.`,
+    details: { reason: "malformed", refs: refs.map((found) => ({ ...found })) },
+    cause,
+  });
+}

package/src/adapters/redocly-loader/redocly-config-source.ts

@@ -0,0 +1,43 @@
+import fs from "node:fs";
+import path from "node:path";
+import { createConfig, findConfig, loadConfig } from "@redocly/openapi-core";
+import type {
+  RedoclyConfig,
+  RedoclyConfigSource,
+} from "../../application/ports/redocly-config-source.js";
+
+/** The Redocly config port on `@redocly/openapi-core`, resolving paths from `cwd`. */
+class RedoclyConfigFiles implements RedoclyConfigSource {
+  readonly #cwd: string;
+
+  constructor(cwd: string) {
+    this.#cwd = cwd;
+  }
+
+  find(explicitPath: string | undefined): string | undefined {
+    if (!explicitPath) {
+      return findConfig(this.#cwd);
+    }
+    const resolved = path.resolve(this.#cwd, explicitPath);
+    if (!fs.existsSync(resolved)) {
+      return undefined;
+    }
+    return fs.statSync(resolved).isDirectory() ? findConfig(resolved) : resolved;
+  }
+
+  load(configPath: string): Promise<RedoclyConfig> {
+    return loadConfig({ configPath });
+  }
+
+  createDefault(): Promise<RedoclyConfig> {
+    return createConfig(
+      { rules: { "operation-operationId-unique": { severity: "warn" } } },
+      { extends: ["minimal"] },
+    );
+  }
+}
+
+/** Find and load `redocly.yaml` relative to the directory `cwd`. */
+export function createRedoclyConfigSource(cwd: string): RedoclyConfigSource {
+  return new RedoclyConfigFiles(cwd);
+}

package/src/adapters/redocly-loader/redocly-schema-loader.ts

@@ -0,0 +1,246 @@
+import { fileURLToPath } from "node:url";
+import {
+  type BaseResolver,
+  bundle,
+  type Document,
+  lintDocument,
+  type NormalizedProblem,
+  type Config as RedoclyConfig,
+} from "@redocly/openapi-core";
+import type { Logger } from "../../application/ports/logger.js";
+import type { SchemaLoader, SchemaLoadRequest } from "../../application/ports/schema-loader.js";
+import { withStackOverflowReportedAsync } from "../../application/stack-overflow.js";
+import type { OpenAPI3 } from "../../types.js";
+import { repairBundledRefs } from "./bundled-ref-repair.js";
+import { findMalformedRefs, malformedRefsError } from "./malformed-refs.js";
+import { RefAccessResolver } from "./ref-access.js";
+import { resolveConfigWithAccess } from "./remote-fetch.js";
+import {
+  loadFailedError,
+  refCycleError,
+  schemaInvalidError,
+  versionUnsupportedError,
+} from "./schema-load-errors.js";
+import { parseSchema } from "./schema-source.js";
+import {
+  findUnsupportedKeys,
+  type LoadedDocument,
+  unsupportedKeysError,
+} from "./unsupported-keys.js";
+
+/**
+ * The SchemaLoader port on Redocly 1.34 (ADR-005): parse any inherited source type, then lint and
+ * bundle with the given Redocly config. Problems go to the logger; errors fail the load.
+ */
+export interface RedoclySchemaLoaderOptions {
+  readonly redoc: RedoclyConfig;
+  readonly logger: Logger;
+  /** A monotonic time in milliseconds, for the debug durations. */
+  readonly now: () => number;
+  /** Time limit of one remote fetch, unless the Redocly config brings its own `customFetch`. */
+  readonly remoteRefTimeoutMs: number;
+}
+
+const UNSUPPORTED_FORMAT_MESSAGE = "Unsupported schema format, expected `openapi: 3.x`";
+
+/**
+ * Accept OpenAPI 3.x only; Swagger 2 and other formats get their own message. An empty file or a
+ * `null` root parses to nothing, so it is checked before any field is read.
+ */
+function assertOpenAPI3(document: unknown): void {
+  if (typeof document !== "object" || document === null) {
+    throw versionUnsupportedError(UNSUPPORTED_FORMAT_MESSAGE, {});
+  }
+  const parsed = document as Record<string, unknown>;
+  const openapiVersion = Number.parseFloat(parsed.openapi as string);
+  const isOpenAPI3 =
+    !parsed.swagger &&
+    Boolean(parsed.openapi) &&
+    !Number.isNaN(openapiVersion) &&
+    openapiVersion >= 3 &&
+    openapiVersion < 4;
+  if (isOpenAPI3) {
+    return;
+  }
+  if (parsed.swagger) {
+    throw versionUnsupportedError(
+      "Unsupported Swagger version: 2.x. Use OpenAPI 3.x instead.",
+      parsed,
+    );
+  }
+  if (parsed.openapi || openapiVersion < 3 || openapiVersion >= 4) {
+    throw versionUnsupportedError(`Unsupported OpenAPI version: ${parsed.openapi}`, parsed);
+  }
+  throw versionUnsupportedError(UNSUPPORTED_FORMAT_MESSAGE, parsed);
+}
+
+/** The base for relative `$ref`s: the source file or URL itself, else the working directory. */
+function sourceAbsoluteRef(source: unknown, cwd: URL): string {
+  if (source instanceof URL) {
+    return source.protocol === "file:" ? sourceFilePath(source) : source.href;
+  }
+  return fileURLToPath(cwd);
+}
+
+/**
+ * The path of a `file:` source. A URL that names no path on this platform (an encoded slash, a
+ * host on POSIX, no drive letter on Windows) cannot be read, so it fails as a read would.
+ */
+function sourceFilePath(source: URL): string {
+  try {
+    return fileURLToPath(source);
+  } catch (error) {
+    // Node.js reports these as TypeErrors (ERR_INVALID_FILE_URL_PATH, ERR_INVALID_FILE_URL_HOST).
+    if (!(error instanceof TypeError)) {
+      throw error;
+    }
+    throw loadFailedError(source.href, error);
+  }
+}
+
+/** Redocly throws a plain Error for a `$ref` chain that points back to itself. */
+const REF_CYCLE_MESSAGE = "Self-referencing circular pointer";
+
+/**
+ * The root document and every other document the resolver loaded, as far as they parsed. A root
+ * read from a file or URL is in the resolver cache too, and is listed once.
+ */
+async function loadedDocuments(root: Document, resolver: BaseResolver): Promise<LoadedDocument[]> {
+  const cached = await Promise.all(resolver.cache.values());
+  const bySource = new Map<string, unknown>([[root.source.absoluteRef, root.parsed]]);
+  for (const document of cached) {
+    if ("parsed" in document && !bySource.has(document.source.absoluteRef)) {
+      bySource.set(document.source.absoluteRef, document.parsed);
+    }
+  }
+  return [...bySource].map(([source, parsed]) => ({ source, parsed }));
+}
+
+/** Report the document problems Redocly throws as typed errors; anything else passes through. */
+async function rethrowDocumentError(
+  error: unknown,
+  root: Document,
+  resolver: BaseResolver,
+): Promise<never> {
+  if (error instanceof Error && error.message === REF_CYCLE_MESSAGE) {
+    throw refCycleError(error);
+  }
+  if (error instanceof URIError) {
+    throw malformedRefsError(findMalformedRefs(await loadedDocuments(root, resolver)), error);
+  }
+  if (error instanceof TypeError) {
+    const keys = findUnsupportedKeys(await loadedDocuments(root, resolver));
+    throw keys.length === 0 ? error : unsupportedKeysError(keys, error);
+  }
+  throw error;
+}
+
+class RedoclySchemaLoader implements SchemaLoader {
+  readonly #options: RedoclySchemaLoaderOptions;
+
+  constructor(options: RedoclySchemaLoaderOptions) {
+    this.#options = options;
+  }
+
+  async load(request: SchemaLoadRequest): Promise<OpenAPI3> {
+    const resolver = this.#resolver(request);
+    // Parsing is guarded too: `JSON.stringify` of a deep object source overflows the stack on
+    // Node.js 22 and 24, before linting starts.
+    const bundled = await withStackOverflowReportedAsync("load", () =>
+      this.#parseAndBundle(request, resolver),
+    ).catch((error: unknown) => {
+      throw resolver.firstRefusal ?? error;
+    });
+    // A refused `$ref` is an unresolved-`$ref` problem, which a Redocly config can turn off.
+    if (resolver.firstRefusal !== undefined) {
+      throw resolver.firstRefusal;
+    }
+    return bundled;
+  }
+
+  async #parseAndBundle(request: SchemaLoadRequest, resolver: BaseResolver): Promise<OpenAPI3> {
+    const { logger, now } = this.#options;
+    const configLoadedAt = now();
+    logger.debug("Loaded Redoc config", "redoc", now() - configLoadedAt);
+    const parseStartedAt = now();
+    const absoluteRef = sourceAbsoluteRef(request.source, request.cwd);
+    const document = await parseSchema(request.source, { absoluteRef, resolver });
+    logger.debug("Parsed schema", "redoc", now() - parseStartedAt);
+    assertOpenAPI3(document.parsed);
+    return this.#lintAndBundle(document, resolver, request.shouldLint);
+  }
+
+  #resolver(request: SchemaLoadRequest): RefAccessResolver {
+    const { redoc, remoteRefTimeoutMs } = this.#options;
+    const config = resolveConfigWithAccess(redoc.resolve, {
+      timeoutMs: remoteRefTimeoutMs,
+      access: request.refAccess,
+    });
+    return new RefAccessResolver(config, request.refAccess);
+  }
+
+  async #lintAndBundle(
+    document: Document,
+    resolver: BaseResolver,
+    shouldLint: boolean,
+  ): Promise<OpenAPI3> {
+    const rethrow = (error: unknown) => rethrowDocumentError(error, document, resolver);
+    if (shouldLint) {
+      await this.#lint(document, resolver).catch(rethrow);
+    }
+    return this.#bundle(document, resolver).catch(rethrow);
+  }
+
+  async #lint(document: Document, resolver: BaseResolver): Promise<void> {
+    const startedAt = this.#options.now();
+    const problems = await lintDocument({
+      document,
+      config: this.#options.redoc.styleguide,
+      externalRefResolver: resolver,
+    });
+    this.#report(problems);
+    this.#options.logger.debug("Linted schema", "lint", this.#options.now() - startedAt);
+  }
+
+  async #bundle(document: Document, resolver: BaseResolver): Promise<OpenAPI3> {
+    const startedAt = this.#options.now();
+    // The lint resolver: documents it already loaded are not fetched again.
+    const bundled = await bundle({
+      config: this.#options.redoc,
+      dereference: false,
+      doc: document,
+      externalRefResolver: resolver,
+    });
+    this.#report(bundled.problems);
+    repairBundledRefs(bundled.bundle.parsed);
+    this.#options.logger.debug("Bundled schema", "bundle", this.#options.now() - startedAt);
+    return bundled.bundle.parsed;
+  }
+
+  /** Report every problem; then throw if any of them is an error. */
+  #report(problems: readonly NormalizedProblem[]): void {
+    const errorMessages: string[] = [];
+    for (const problem of problems) {
+      const message = problemMessage(problem);
+      if (problem.severity === "error") {
+        errorMessages.push(message);
+        this.#options.logger.error(message);
+      } else {
+        this.#options.logger.warn(message);
+      }
+    }
+    if (errorMessages.length > 0) {
+      throw schemaInvalidError(errorMessages);
+    }
+  }
+}
+
+function problemMessage(problem: NormalizedProblem): string {
+  const location = problem.location?.[0]?.pointer;
+  return location ? `${problem.message} at ${location}` : problem.message;
+}
+
+/** A schema loader with one Redocly config and logger, for one or more loads. */
+export function createRedoclySchemaLoader(options: RedoclySchemaLoaderOptions): SchemaLoader {
+  return new RedoclySchemaLoader(options);
+}