openapi-typesafe 1.0.0-rc.1 → 1.0.0-rc.3

package/dist/index.mjs

@@ -4,11 +4,13 @@ export { COMMENT_HEADER } from './api/comment-header.mjs';
 export { scanDiscriminators } from './api/discriminator-scan.mjs';
 export { JS_ENUM_INVALID_CHARS_RE, JS_PROPERTY_INDEX_INVALID_CHARS_RE, JS_PROPERTY_INDEX_RE, QUESTION_TOKEN, SPECIAL_CHARACTER_MAP, addJSDocComment, enumCache, tsArrayLiteralExpression, tsDedupe, tsEnum, tsEnumMember, tsIsPrimitive, tsModifiers, tsPropertyIndex, tsReadonlyArray } from './api/legacy-ts-helpers.mjs';
 export { c, createDiscriminatorProperty, createRef, debug, error, formatTime, getEntries, resolveRef, walk, warn } from './api/legacy-utils.mjs';
-export { STRING_TO_AST_DEPRECATION_CODE, stringToAST } from './api/string-to-ast.mjs';
+export { stringToAST } from './api/string-to-ast.mjs';
 export { default as transformSchema } from './api/transform-schema.mjs';
 export { BOOLEAN, FALSE, NEVER, NULL, NUMBER, STRING, TRUE, UNDEFINED, UNKNOWN, oapiRef, tsIntersection, tsLiteral, tsNullable, tsOmit, tsRecord, tsUnion, tsWithRequired } from './api/type-helpers.mjs';
+export { DEPRECATION_CODES } from './domain/deprecations.mjs';
 export { ERROR_CODES, OpenAPITypesafeError, isOpenAPITypesafeError } from './domain/errors.mjs';
-export { ALL_OUTPUT_FIXES, OUTPUT_FIXES, OutputFix } from './domain/output-fixes.mjs';
+export { OUTPUT_FIXES } from './domain/output-fixes.mjs';
+export { WARNING_CODES } from './domain/warnings.mjs';
 export { default as transformComponentsObject } from './transform/components-object.mjs';
 export { default as transformHeaderObject } from './transform/header-object.mjs';
 export { default as transformMediaTypeObject } from './transform/media-type-object.mjs';

package/dist/index.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"index.mjs","sources":[],"sourcesContent":[],"names":[],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;"}
+{"version":3,"file":"index.mjs","sources":[],"sourcesContent":[],"names":[],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;"}

package/dist/transform/path-item-object.cjs.map

@@ -1 +1 @@
-{"version":3,"file":"path-item-object.cjs","sources":["../../src/transform/path-item-object.ts"],"sourcesContent":["import { createTransformContext, schemaLocation } from \"../api/transform-context.js\";\nimport { pathItemType } from \"../application/transform/document/path-item.js\";\nimport type { IrType } from \"../domain/ir/nodes.js\";\nimport type { HttpMethod } from \"../domain/openapi/path-item-object.js\";\nimport type { PathItemObject, TransformNodeOptions } from \"../types.js\";\n\nexport type Method = HttpMethod;\n\n/**\n * Transform PathItem nodes (4.8.9)\n * @see https://spec.openapis.org/oas/v3.1.0#path-item-object\n *\n * Ported to IR (ENGINEERING_PLAN Phase 5, step 5). Same name and parameters as the original;\n * returns IR (task 6.2). For the public API and for users who call it from callbacks.\n */\nexport default function transformPathItemObject(\n  pathItem: PathItemObject,\n  options: TransformNodeOptions,\n): IrType {\n  const context = createTransformContext(options.ctx);\n  return pathItemType(pathItem, schemaLocation(options), context);\n}\n"],"names":["pathItem","createTransformContext","pathItemType","schemaLocation"],"mappings":";;;;;AAeA,SAAwB,uBAAA,CACtBA,YACA,OAAA,EACQ;AACR,EAAA,MAAM,OAAA,GAAUC,uCAAA,CAAuB,OAAA,CAAQ,GAAG,CAAA;AAClD,EAAA,OAAOC,qBAAA,CAAaF,UAAA,EAAUG,+BAAA,CAAe,OAAO,GAAG,OAAO,CAAA;AAChE;;"}
+{"version":3,"file":"path-item-object.cjs","sources":["../../src/transform/path-item-object.ts"],"sourcesContent":["import { createTransformContext, schemaLocation } from \"../api/transform-context.js\";\nimport { pathItemType } from \"../application/transform/document/path-item.js\";\nimport type { IrType } from \"../domain/ir/nodes.js\";\nimport type { PathItemMethod } from \"../domain/openapi/path-item-object.js\";\nimport type { PathItemObject, TransformNodeOptions } from \"../types.js\";\n\n/**\n * The operation methods of a path item: openapi-typescript's eight, plus the OpenAPI 3.2 `query`\n * (ADR-020), as `HttpMethod` of openapi-typesafe-helpers lists them.\n */\nexport type Method = PathItemMethod;\n\n/**\n * Transform PathItem nodes (4.8.9)\n * @see https://spec.openapis.org/oas/v3.1.0#path-item-object\n *\n * Ported to IR (ENGINEERING_PLAN Phase 5, step 5). Same name and parameters as the original;\n * returns IR (task 6.2). For the public API and for users who call it from callbacks.\n */\nexport default function transformPathItemObject(\n  pathItem: PathItemObject,\n  options: TransformNodeOptions,\n): IrType {\n  const context = createTransformContext(options.ctx);\n  return pathItemType(pathItem, schemaLocation(options), context);\n}\n"],"names":["pathItem","createTransformContext","pathItemType","schemaLocation"],"mappings":";;;;;AAmBA,SAAwB,uBAAA,CACtBA,YACA,OAAA,EACQ;AACR,EAAA,MAAM,OAAA,GAAUC,uCAAA,CAAuB,OAAA,CAAQ,GAAG,CAAA;AAClD,EAAA,OAAOC,qBAAA,CAAaF,UAAA,EAAUG,+BAAA,CAAe,OAAO,GAAG,OAAO,CAAA;AAChE;;"}

package/dist/transform/path-item-object.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"path-item-object.mjs","sources":["../../src/transform/path-item-object.ts"],"sourcesContent":["import { createTransformContext, schemaLocation } from \"../api/transform-context.js\";\nimport { pathItemType } from \"../application/transform/document/path-item.js\";\nimport type { IrType } from \"../domain/ir/nodes.js\";\nimport type { HttpMethod } from \"../domain/openapi/path-item-object.js\";\nimport type { PathItemObject, TransformNodeOptions } from \"../types.js\";\n\nexport type Method = HttpMethod;\n\n/**\n * Transform PathItem nodes (4.8.9)\n * @see https://spec.openapis.org/oas/v3.1.0#path-item-object\n *\n * Ported to IR (ENGINEERING_PLAN Phase 5, step 5). Same name and parameters as the original;\n * returns IR (task 6.2). For the public API and for users who call it from callbacks.\n */\nexport default function transformPathItemObject(\n  pathItem: PathItemObject,\n  options: TransformNodeOptions,\n): IrType {\n  const context = createTransformContext(options.ctx);\n  return pathItemType(pathItem, schemaLocation(options), context);\n}\n"],"names":[],"mappings":";;;AAeA,SAAwB,uBAAA,CACtB,UACA,OAAA,EACQ;AACR,EAAA,MAAM,OAAA,GAAU,sBAAA,CAAuB,OAAA,CAAQ,GAAG,CAAA;AAClD,EAAA,OAAO,YAAA,CAAa,QAAA,EAAU,cAAA,CAAe,OAAO,GAAG,OAAO,CAAA;AAChE;;"}
+{"version":3,"file":"path-item-object.mjs","sources":["../../src/transform/path-item-object.ts"],"sourcesContent":["import { createTransformContext, schemaLocation } from \"../api/transform-context.js\";\nimport { pathItemType } from \"../application/transform/document/path-item.js\";\nimport type { IrType } from \"../domain/ir/nodes.js\";\nimport type { PathItemMethod } from \"../domain/openapi/path-item-object.js\";\nimport type { PathItemObject, TransformNodeOptions } from \"../types.js\";\n\n/**\n * The operation methods of a path item: openapi-typescript's eight, plus the OpenAPI 3.2 `query`\n * (ADR-020), as `HttpMethod` of openapi-typesafe-helpers lists them.\n */\nexport type Method = PathItemMethod;\n\n/**\n * Transform PathItem nodes (4.8.9)\n * @see https://spec.openapis.org/oas/v3.1.0#path-item-object\n *\n * Ported to IR (ENGINEERING_PLAN Phase 5, step 5). Same name and parameters as the original;\n * returns IR (task 6.2). For the public API and for users who call it from callbacks.\n */\nexport default function transformPathItemObject(\n  pathItem: PathItemObject,\n  options: TransformNodeOptions,\n): IrType {\n  const context = createTransformContext(options.ctx);\n  return pathItemType(pathItem, schemaLocation(options), context);\n}\n"],"names":[],"mappings":";;;AAmBA,SAAwB,uBAAA,CACtB,UACA,OAAA,EACQ;AACR,EAAA,MAAM,OAAA,GAAU,sBAAA,CAAuB,OAAA,CAAQ,GAAG,CAAA;AAClD,EAAA,OAAO,YAAA,CAAa,QAAA,EAAU,cAAA,CAAe,OAAO,GAAG,OAAO,CAAA;AAChE;;"}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "openapi-typesafe",
-  "description": "Convert OpenAPI 3.0 & 3.1 schemas to TypeScript",
-  "version": "1.0.0-rc.1",
+  "description": "Convert OpenAPI 3.0, 3.1 & 3.2 schemas to TypeScript",
+  "version": "1.0.0-rc.3",
   "author": {
     "name": "Fedor Chishchin",
     "url": "https://github.com/fedorello"
@@ -81,15 +81,16 @@
     "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",
+    "dependency-cruiser": "18.7.2",
     "execa": "^10.2.1",
     "fast-check": "4.10.2",
     "strip-ansi": "7.2.0",
     "typescript": "^6.0.3",
+    "typescript-5.4": "npm:typescript@5.4.5",
+    "typescript-7.0": "npm:typescript@7.0.2",
     "vite-node": "6.0.0"
   },
   "engines": {

package/src/adapters/node-deprecations/node-deprecations.ts

@@ -0,0 +1,14 @@
+import { deprecate } from "node:util";
+import type { DeprecationReporter } from "../../application/ports/deprecation-reporter.js";
+
+/**
+ * Deprecations as Node.js `DeprecationWarning`s. `util.deprecate` warns once per process for each
+ * code, also across wrappers, and honours `--no-deprecation` and `--throw-deprecation`.
+ */
+export function createNodeDeprecationReporter(): DeprecationReporter {
+  return {
+    report(code, message) {
+      deprecate(() => undefined, message, code)();
+    },
+  };
+}

package/src/adapters/redocly-loader/configured-headers.ts

@@ -0,0 +1,65 @@
+import { type Config as RedoclyConfig, readFileFromUrl } from "@redocly/openapi-core";
+
+/**
+ * Which `resolve.http.headers` of the Redocly config go with a request (threat model T4a). The
+ * headers often carry credentials, so they are chosen again for every request and every redirect,
+ * from the parsed URL, and never sent over plain HTTP to another machine unless the pattern asks
+ * for it.
+ */
+
+/** One `resolve.http.headers` entry: a name, a value or an environment variable, a pattern. */
+export type ConfiguredHeader = RedoclyConfig["resolve"]["http"]["headers"][number];
+
+/** Redocly matches the protocol only when the pattern starts with one; the same test. */
+const EXPLICIT_HTTP_PATTERN = /^http:\/\//;
+
+/** Hosts that never leave the machine: plain HTTP to them cannot be read on the network. */
+const LOOPBACK_HOSTNAMES: ReadonlySet<string> = new Set(["localhost", "[::1]"]);
+// The URL parser has already turned every IPv4 form (`2130706433`, `0x7f.1`) into dotted decimal.
+const LOOPBACK_IPV4 = /^127\.\d{1,3}\.\d{1,3}\.\d{1,3}$/;
+
+function isLoopback(url: URL): boolean {
+  return LOOPBACK_HOSTNAMES.has(url.hostname) || LOOPBACK_IPV4.test(url.hostname);
+}
+
+/**
+ * A header goes over HTTPS, over HTTP to this machine (a local dev server), or over HTTP to
+ * another machine when its pattern names `http://` itself.
+ */
+function isProtocolAllowed(header: ConfiguredHeader, url: URL): boolean {
+  return (
+    url.protocol === "https:" ||
+    (url.protocol === "http:" && isLoopback(url)) ||
+    EXPLICIT_HTTP_PATTERN.test(header.matches)
+  );
+}
+
+/**
+ * The URL as a pattern sees it: protocol, host and path. User info, query and fragment are left
+ * out, so a `*` in the pattern cannot match across `?`, `#` or `@` into another host's URL.
+ */
+function matchedText(url: URL): string {
+  return `${url.protocol}//${url.host}${url.pathname}`;
+}
+
+/**
+ * The headers configured for this URL. The patterns are matched by Redocly's own matcher, which
+ * also reads `envVariable` values, so a pattern means here what it means in Redocly; its fetch
+ * only records the headers it would send and sends nothing.
+ */
+export async function headersFor(
+  url: URL,
+  configured: readonly ConfiguredHeader[],
+): Promise<Record<string, string>> {
+  const candidates = configured.filter((header) => isProtocolAllowed(header, url));
+  let selected: Record<string, string> = {};
+  if (candidates.length === 0) {
+    return selected;
+  }
+  const recordHeaders = async (_input: string, init: { headers: Record<string, string> }) => {
+    selected = init.headers;
+    return new Response("");
+  };
+  await readFileFromUrl(matchedText(url), { headers: [...candidates], customFetch: recordHeaders });
+  return selected;
+}

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

@@ -10,11 +10,14 @@ import {
 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 { WARNING_CODES, warningText } from "../../domain/warnings.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 { checkRefsResolve } from "./ref-resolution-check.js";
+import { REF_CYCLE_MESSAGE } from "./ref-resolution-steps.js";
+import { type RemoteDocumentLimits, resolveConfigWithAccess } from "./remote-fetch.js";
 import {
   loadFailedError,
   refCycleError,
@@ -39,6 +42,7 @@ export interface RedoclySchemaLoaderOptions {
   readonly now: () => number;
   /** Time limit of one remote fetch, unless the Redocly config brings its own `customFetch`. */
   readonly remoteRefTimeoutMs: number;
+  readonly remoteDocumentLimits: RemoteDocumentLimits;
 }
 
 const UNSUPPORTED_FORMAT_MESSAGE = "Unsupported schema format, expected `openapi: 3.x`";
@@ -103,9 +107,6 @@ function sourceFilePath(source: URL): string {
   }
 }
 
-/** 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.
@@ -176,12 +177,16 @@ class RedoclySchemaLoader implements SchemaLoader {
   }
 
   #resolver(request: SchemaLoadRequest): RefAccessResolver {
-    const { redoc, remoteRefTimeoutMs } = this.#options;
+    const { redoc, remoteRefTimeoutMs, remoteDocumentLimits } = this.#options;
     const config = resolveConfigWithAccess(redoc.resolve, {
       timeoutMs: remoteRefTimeoutMs,
       access: request.refAccess,
+      maxParallelFetches: remoteDocumentLimits.maxParallelFetches,
+    });
+    return new RefAccessResolver(config, {
+      access: request.refAccess,
+      maxRemoteDocuments: remoteDocumentLimits.maxDocuments,
     });
-    return new RefAccessResolver(config, request.refAccess);
   }
 
   async #lintAndBundle(
@@ -190,6 +195,8 @@ class RedoclySchemaLoader implements SchemaLoader {
     shouldLint: boolean,
   ): Promise<OpenAPI3> {
     const rethrow = (error: unknown) => rethrowDocumentError(error, document, resolver);
+    // Redocly leaves unhandled rejections behind when a `$ref` fails in two documents (ADR-031).
+    await checkRefsResolve(document, resolver, this.#options.redoc.styleguide).catch(rethrow);
     if (shouldLint) {
       await this.#lint(document, resolver).catch(rethrow);
     }
@@ -242,7 +249,7 @@ class RedoclySchemaLoader implements SchemaLoader {
         errorMessages.push(message);
         this.#options.logger.error(message);
       } else {
-        this.#options.logger.warn(message);
+        this.#options.logger.warn(lintWarningText(problem));
       }
     }
     if (errorMessages.length > 0) {
@@ -251,6 +258,14 @@ class RedoclySchemaLoader implements SchemaLoader {
   }
 }
 
+/** A lint warning names its rule, which `redocly.yaml` can turn off, and ends with its code. */
+function lintWarningText(problem: NormalizedProblem): string {
+  return warningText(
+    `${problemMessage(problem)}, rule ${problem.ruleId}`,
+    WARNING_CODES.LINT_PROBLEM,
+  );
+}
+
 function problemMessage(problem: NormalizedProblem): string {
   const location = problem.location?.[0]?.pointer;
   return location ? `${problem.message} at ${location}` : problem.message;

package/src/adapters/redocly-loader/ref-access.ts

@@ -10,6 +10,7 @@ import {
 } from "@redocly/openapi-core";
 import type { RefAccess } from "../../application/ports/schema-loader.js";
 import { ERROR_CODES, type OpenAPITypesafeError } from "../../domain/errors.js";
+import { redactUrlCredentials } from "../../domain/url-credentials.js";
 import { aliasExpansionFailure } from "./alias-limit.js";
 import { isHostAllowed } from "./allowed-hosts.js";
 import { refForbiddenError } from "./schema-load-errors.js";
@@ -79,20 +80,45 @@ export async function refusalOf(
   });
 }
 
+/**
+ * A remote document may refer only to other URLs (threat model T3). Redocly resolves a `$ref`
+ * against a URL base with `new URL()`, so `C:/x` becomes `c:/x` and `file:///x` stays as it is;
+ * Redocly then reads either from disk, and on Windows a drive letter is an absolute path.
+ */
+function localFromRemoteRefusal(
+  base: string,
+  absoluteRef: string,
+): OpenAPITypesafeError | undefined {
+  if (!isRemoteRef(base) || isRemoteRef(absoluteRef)) {
+    return undefined;
+  }
+  const shownBase = redactUrlCredentials(base);
+  return refForbiddenError(absoluteRef, { reason: "local-ref-from-remote", base: shownBase });
+}
+
+/** The limits one resolver checks; each load gets its own resolver. */
+export interface RefAccessLimits {
+  readonly access: RefAccess;
+  /** Remote documents one load may fetch, the root included (threat model T2). */
+  readonly maxRemoteDocuments: number;
+}
+
 /**
  * A Redocly resolver that checks each document before it loads it. Redocly turns a failed load
  * into an unresolved-`$ref` problem, so the refusals are also kept for the loader to report as
  * the typed error.
  */
 export class RefAccessResolver extends BaseResolver {
-  readonly #access: RefAccess;
+  readonly #limits: RefAccessLimits;
   readonly #refusals: OpenAPITypesafeError[] = [];
   /** The root document's ref: it is chosen by the developer, so it is not limited. */
   #rootRef: string | undefined;
+  /** Remote documents asked for so far; Redocly caches each one, so each is counted once. */
+  #remoteDocumentCount = 0;
 
-  constructor(config: ResolveConfig, access: RefAccess) {
+  constructor(config: ResolveConfig, limits: RefAccessLimits) {
     super(config);
-    this.#access = access;
+    this.#limits = limits;
   }
 
   /** The first document that was refused, if any. */
@@ -108,6 +134,12 @@ export class RefAccessResolver extends BaseResolver {
     if (isRoot) {
       this.#rootRef = this.resolveExternalRef(base, ref);
     }
+    const refusal =
+      base === null ? undefined : localFromRemoteRefusal(base, this.resolveExternalRef(base, ref));
+    if (refusal !== undefined) {
+      this.#refusals.push(refusal);
+      return Promise.reject(refusal);
+    }
     return super.resolveDocument(base, ref, isRoot);
   }
 
@@ -122,8 +154,7 @@ export class RefAccessResolver extends BaseResolver {
   }
 
   override async loadExternalRef(absoluteRef: string): Promise<Source> {
-    const refusal =
-      absoluteRef === this.#rootRef ? undefined : await refusalOf(absoluteRef, this.#access);
+    const refusal = this.#countRefusal(absoluteRef) ?? (await this.#accessRefusal(absoluteRef));
     if (refusal !== undefined) {
       this.#refusals.push(refusal);
       throw refusal;
@@ -139,6 +170,30 @@ export class RefAccessResolver extends BaseResolver {
       throw error;
     }
   }
+
+  #accessRefusal(absoluteRef: string): Promise<OpenAPITypesafeError | undefined> {
+    return absoluteRef === this.#rootRef
+      ? Promise.resolve(undefined)
+      : refusalOf(absoluteRef, this.#limits.access);
+  }
+
+  /**
+   * A document that changes all its URLs can fan out without end: 150 `$ref`s per document, three
+   * levels deep, made 16,212 requests and exhausted the local ports (audit B2, F4).
+   */
+  #countRefusal(absoluteRef: string): OpenAPITypesafeError | undefined {
+    if (!isRemoteRef(absoluteRef)) {
+      return undefined;
+    }
+    this.#remoteDocumentCount += 1;
+    const { maxRemoteDocuments } = this.#limits;
+    return this.#remoteDocumentCount > maxRemoteDocuments
+      ? refForbiddenError(absoluteRef, {
+          reason: "too-many-remote-documents",
+          maxDocuments: maxRemoteDocuments,
+        })
+      : undefined;
+  }
 }
 
 function isRefusal(value: unknown): value is OpenAPITypesafeError {

package/src/adapters/redocly-loader/ref-resolution-check.ts

@@ -0,0 +1,257 @@
+import {
+  type BaseResolver,
+  type Document,
+  detectSpec,
+  getTypes,
+  isRef,
+  normalizeTypes,
+  type Config as RedoclyConfig,
+} from "@redocly/openapi-core";
+import {
+  ANCHOR_REF,
+  escapePointer,
+  hasRef,
+  isExternalValue,
+  isNamedType,
+  joinPointer,
+  nextTick,
+  parseRef,
+  propertyType,
+  REF_CYCLE_MESSAGE,
+  type Ref,
+  type RefStack,
+  type ResolvedRef,
+  UNKNOWN_TYPE,
+  type WalkType,
+} from "./ref-resolution-steps.js";
+
+/**
+ * Redocly 1.34 resolves `$ref`s with `Promise.all` over the lookups it has started and stops at
+ * the first one that fails. Lookups it starts after that (the walk of a document that was still
+ * loading) are never awaited: when one of them fails too, its rejection is unhandled, and Node.js
+ * ends the process on an unhandled rejection (ADR-031). Redocly 2.x has the same loop.
+ *
+ * This is a port of Redocly's `resolveDocument` (`lib/resolve.js`, 1.34.22, MIT) that waits for
+ * every lookup and then throws the first failure. The loader runs it before Redocly lints or
+ * bundles, so Redocly only resolves documents in which no lookup fails. It walks the same nodes
+ * with the same types and throws the same errors: the "Self-referencing circular pointer" Error,
+ * the URIError of a malformed percent escape, and the TypeError of a key such as `valueOf`.
+ */
+
+/** One walk of the documents a root reaches, with every `$ref` lookup it starts. */
+class RefResolutionWalk {
+  readonly #resolver: BaseResolver;
+  /** Redocly's `SpecExtension` type: its values are walked like values of no known type. */
+  readonly specExtension: WalkType;
+  /** Walked nodes per type name; a node walked again with the same type starts the same lookups. */
+  readonly #seenNodes = new Map<string, WeakSet<object>>();
+  readonly #lookups: Promise<void>[] = [];
+
+  constructor(resolver: BaseResolver, specExtension: WalkType) {
+    this.#resolver = resolver;
+    this.specExtension = specExtension;
+  }
+
+  isWalkedLikeUnknown(type: WalkType): boolean {
+    return type === UNKNOWN_TYPE || type === this.specExtension;
+  }
+
+  /** Wait for every lookup, including those started while waiting; return the first failure. */
+  async settle(): Promise<PromiseRejectedResult | undefined> {
+    let settled: PromiseSettledResult<void>[];
+    do {
+      settled = await Promise.allSettled(this.#lookups);
+    } while (settled.length !== this.#lookups.length);
+    return settled.find((result) => result.status === "rejected");
+  }
+
+  walkFrom(node: unknown, document: Document, pointer: string, type: WalkType): void {
+    new DocumentWalk(this, document).walk(node, type, document.source.absoluteRef + pointer);
+  }
+
+  /** Whether the node was walked with this type before; marks it walked. */
+  isSeen(type: WalkType, node: object): boolean {
+    let seen = this.#seenNodes.get(type.name);
+    if (seen === undefined) {
+      seen = new WeakSet();
+      this.#seenNodes.set(type.name, seen);
+    }
+    if (seen.has(node)) {
+      return true;
+    }
+    seen.add(node);
+    return false;
+  }
+
+  track(lookup: Promise<ResolvedRef>, type: WalkType): void {
+    this.#lookups.push(
+      lookup.then((resolved) => {
+        if (resolved.resolved && resolved.document !== undefined) {
+          this.walkFrom(resolved.node, resolved.document, resolved.nodePointer ?? "#/", type);
+        }
+      }),
+    );
+  }
+
+  async loadDocument(base: Document, uri: string): Promise<Document | undefined> {
+    try {
+      return (await this.#resolver.resolveDocument(base.source.absoluteRef, uri)) as Document;
+    } catch {
+      // Redocly records the failed lookup as an unresolved `$ref`; the lint reports it.
+      return undefined;
+    }
+  }
+}
+
+/** The walk of one document from one node, with the anchors it collects (as in Redocly). */
+class DocumentWalk {
+  readonly #walk: RefResolutionWalk;
+  readonly #document: Document;
+  readonly #anchors = new Map<string, unknown>();
+
+  constructor(walk: RefResolutionWalk, document: Document) {
+    this.#walk = walk;
+    this.#document = document;
+  }
+
+  walk(node: unknown, type: WalkType, absoluteRef: string): void {
+    if (typeof node !== "object" || node === null || this.#walk.isSeen(type, node)) {
+      return;
+    }
+    const anchor = (node as { $anchor?: unknown }).$anchor;
+    if (Object.hasOwn(node, "$anchor") && anchor) {
+      this.#anchors.set(`#${String(anchor)}`, node);
+    }
+    if (Array.isArray(node)) {
+      this.#walkItems(node, type, absoluteRef);
+      return;
+    }
+    for (const name of Object.keys(node)) {
+      const value = (node as Record<string, unknown>)[name];
+      const [propType, walked] = propertyType(type, name, value, this.#walk.specExtension);
+      if (isNamedType(propType) && typeof walked === "object") {
+        this.walk(walked, propType, joinPointer(absoluteRef, escapePointer(name)));
+      }
+    }
+    if (isRef(node)) {
+      this.#walk.track(this.#follow(this.#document, node, { prev: null, node }), type);
+    }
+    if (isExternalValue(node)) {
+      const ref = { $ref: node.externalValue };
+      this.#walk.track(this.#follow(this.#document, ref, { prev: null, node }), type);
+    }
+  }
+
+  #walkItems(items: readonly unknown[], type: WalkType, absoluteRef: string): void {
+    const itemsType = type.items;
+    if (itemsType === undefined && !this.#walk.isWalkedLikeUnknown(type)) {
+      return;
+    }
+    items.forEach((item, index) => {
+      const pointer = joinPointer(absoluteRef, index);
+      const itemType = typeof itemsType === "function" ? itemsType(item, pointer) : itemsType;
+      if (itemType === undefined && !this.#walk.isWalkedLikeUnknown(type)) {
+        return;
+      }
+      this.walk(item, isNamedType(itemType) ? itemType : UNKNOWN_TYPE, pointer);
+    });
+  }
+
+  async #follow(document: Document, ref: Ref, refStack: RefStack): Promise<ResolvedRef> {
+    if (hasRef(refStack.prev, ref)) {
+      throw new Error(REF_CYCLE_MESSAGE);
+    }
+    if (ANCHOR_REF.test(ref.$ref)) {
+      await nextTick();
+      return { resolved: true, node: this.#anchors.get(ref.$ref), document, nodePointer: ref.$ref };
+    }
+    const { uri, pointer } = parseRef(ref.$ref);
+    const targetDocument = uri === null ? document : await this.#walk.loadDocument(document, uri);
+    if (targetDocument === undefined) {
+      return { resolved: false };
+    }
+    const found = await this.#followSegments(targetDocument, pointer, refStack);
+    if (found.document !== undefined && isRef(found.node)) {
+      return this.#follow(found.document, found.node, pushRef(refStack, found.node));
+    }
+    return found;
+  }
+
+  /** Follow the pointer segments; a `$ref` met on the way is resolved first. */
+  async #followSegments(
+    targetDocument: Document,
+    segments: readonly string[],
+    refStack: RefStack,
+  ): Promise<ResolvedRef> {
+    let document = targetDocument;
+    let nodePointer = "#/";
+    let target: unknown = targetDocument.parsed;
+    for (const segment of segments) {
+      if (typeof target !== "object") {
+        return { resolved: true, node: undefined, document, nodePointer };
+      }
+      // A `null` target throws a TypeError here, as it does in Redocly.
+      const step = (target as Record<string, unknown>)[segment];
+      if (step !== undefined) {
+        target = step;
+      } else if (isRef(target)) {
+        const resolved = await this.#follow(document, target, pushRef(refStack, target));
+        document = resolved.document ?? document;
+        if (typeof resolved.node !== "object") {
+          return {
+            resolved: true,
+            node: undefined,
+            document,
+            nodePointer: resolved.nodePointer ?? nodePointer,
+          };
+        }
+        target = (resolved.node as Record<string, unknown>)[segment];
+        nodePointer = resolved.nodePointer ?? nodePointer;
+      } else {
+        return { resolved: true, node: undefined, document, nodePointer };
+      }
+      nodePointer = joinPointer(nodePointer, escapePointer(segment));
+    }
+    return { resolved: true, node: target, document, nodePointer };
+  }
+}
+
+function pushRef(head: RefStack, node: unknown): RefStack {
+  return { prev: head, node };
+}
+
+/**
+ * Resolve every `$ref` the document reaches, as Redocly's lint and bundle do, and throw the first
+ * failure only after all lookups have finished. Documents are loaded through the given resolver,
+ * whose cache Redocly then reuses.
+ */
+export async function checkRefsResolve(
+  document: Document,
+  resolver: BaseResolver,
+  styleguide: RedoclyConfig["styleguide"],
+): Promise<void> {
+  const specVersion = detectSpec(document.parsed);
+  const types = normalizeTypes(
+    styleguide.extendTypes(getTypes(specVersion), specVersion),
+    styleguide,
+  );
+  const rootType = types.Root;
+  const specExtension = types.SpecExtension;
+  if (rootType === undefined || specExtension === undefined) {
+    // Redocly gives every spec version both types; a missing one is a Redocly change to port.
+    throw new Error(`Redocly has no Root or SpecExtension type for ${specVersion}`);
+  }
+  const walk = new RefResolutionWalk(resolver, specExtension);
+  let rootFailure: PromiseRejectedResult | undefined;
+  try {
+    walk.walkFrom(document.parsed, document, "#/", rootType);
+  } catch (error) {
+    // The walk of the root can fail after it started lookups; they are awaited all the same.
+    rootFailure = { status: "rejected", reason: error };
+  }
+  const lookupFailure = await walk.settle();
+  const failure = rootFailure ?? lookupFailure;
+  if (failure !== undefined) {
+    throw failure.reason;
+  }
+}