openapi-typesafe 1.0.0-rc.4 → 1.0.0-rc.6

package/src/adapters/redocly-loader/query-named-components.ts

@@ -0,0 +1,200 @@
+import {
+  appendPointer,
+  canonicalRef,
+  parseRefPointer,
+  ROOT_POINTER,
+} from "../../domain/openapi/json-pointer.js";
+import { type DocumentNames, queryDocumentNames } from "./query-document-names.js";
+import { findMappings, findRefHolders } from "./ref-holders.js";
+import type { LoadedDocument } from "./unsupported-keys.js";
+
+/**
+ * Redocly 1.x bundles an external `$ref` into a component named after the last segment of the
+ * document's URL, without its extension, when the pointer gives no free name (a `$ref` to a whole
+ * document, or two targets with the same pointer). The query stays in that name, and a query holds
+ * API keys and signatures, so `https://host/schemas/pet?token=…` became the component
+ * `pet?token=…` in the generated file and in messages (threat model T4b). This renames such a
+ * component after the URL without its query: `pet`, with a `-2` suffix when that name is taken.
+ * Each component is matched to its document by its node, since two URLs can give one name.
+ */
+
+type Components = Record<string, Record<string, unknown>>;
+
+/** The keys of each `components` group before bundling: the bundle edits the document in place. */
+export type ComponentKeys = ReadonlyMap<string, ReadonlySet<string>>;
+
+/** Old and new name of each renamed component, per `components` group. */
+type Renames = Map<string, Map<string, string>>;
+
+const COMPONENTS_KEY = "components";
+/** What Redocly puts between the base name and the rest of a component name. */
+const NAME_SUFFIX_STARTS = ["_", "-"];
+const FIRST_SERIAL = 2;
+/**
+ * The serial Redocly adds when a name is taken (`pet-2`). Two URLs that differ only in the query
+ * took one name; without the query they may not, so the serial is chosen again (`freeName`).
+ */
+const REDOCLY_SERIAL_RE = /-\d+$/;
+
+function isContainer(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+function componentsOf(document: unknown): Components {
+  const components = isContainer(document) ? document[COMPONENTS_KEY] : undefined;
+  if (!isContainer(components)) {
+    return {};
+  }
+  const groups: Components = {};
+  for (const [group, entries] of Object.entries(components)) {
+    if (isContainer(entries)) {
+      groups[group] = entries;
+    }
+  }
+  return groups;
+}
+
+/** The keys of every `components` group of a document. */
+export function componentKeysOf(document: unknown): ComponentKeys {
+  const keys = new Map<string, ReadonlySet<string>>();
+  for (const [group, entries] of Object.entries(componentsOf(document))) {
+    keys.set(group, new Set(Object.keys(entries)));
+  }
+  return keys;
+}
+
+/** The name a component of a document with a query gets; undefined for any other component. */
+function queryFreeName(key: string, names: DocumentNames | undefined): string | undefined {
+  if (names === undefined) {
+    return undefined;
+  }
+  const { named, clean } = names;
+  const hasBaseName =
+    key === named || NAME_SUFFIX_STARTS.some((start) => key.startsWith(`${named}${start}`));
+  return hasBaseName
+    ? `${clean}${key.slice(named.length).replace(REDOCLY_SERIAL_RE, "")}`
+    : undefined;
+}
+
+function freeName(name: string, taken: ReadonlySet<string>): string {
+  let free = name;
+  for (let serial = FIRST_SERIAL; taken.has(free); serial += 1) {
+    free = `${name}-${serial}`;
+  }
+  return free;
+}
+
+/** Rename the bundled components of one group in place, keeping their order. */
+function renameGroup(
+  entries: Record<string, unknown>,
+  keysBefore: ReadonlySet<string>,
+  documentNames: ReadonlyMap<object, DocumentNames>,
+): Map<string, string> {
+  const renames = new Map<string, string>();
+  const taken = new Set(Object.keys(entries));
+  for (const key of Object.keys(entries)) {
+    const node = entries[key];
+    const names = typeof node === "object" && node !== null ? documentNames.get(node) : undefined;
+    const name = keysBefore.has(key) ? undefined : queryFreeName(key, names);
+    if (name !== undefined) {
+      taken.delete(key);
+      const free = freeName(name, taken);
+      taken.add(free);
+      renames.set(key, free);
+    }
+  }
+  for (const [key, value] of Object.entries(entries)) {
+    delete entries[key];
+    entries[renames.get(key) ?? key] = value;
+  }
+  return renames;
+}
+
+/** Rewrites pointers and messages that name a renamed component. */
+export interface ComponentRenaming {
+  /** The pointer with a renamed component's new name; any other text as it is. */
+  readonly pointer: (pointer: string) => string;
+  /** The text with each renamed component's old name replaced by its new name. */
+  readonly text: (text: string) => string;
+  /**
+   * Whether the problem is Redocly's report of two components with one name that the new names
+   * tell apart: it renamed `new-api` to `new-api-2`, and the documents are now `pet` and `owner`.
+   */
+  readonly isResolvedCollision: (message: string) => boolean;
+}
+
+/** The warning Redocly 1.34 gives when it adds a serial to a component name. */
+const COLLISION_RE =
+  /^Two schemas are referenced with the same name but different content\. Renamed (.+) to (.+)\.$/;
+const SERIAL_RE = /^-\d+$/;
+
+function resolvesCollision(message: string, renames: Renames): boolean {
+  const [, first, second] = COLLISION_RE.exec(message) ?? [];
+  if (first === undefined || second === undefined) {
+    return false;
+  }
+  const renamed = new Map([...renames.values()].flatMap((group) => [...group]));
+  const [newFirst, newSecond] = [renamed.get(first) ?? first, renamed.get(second) ?? second];
+  return !(newSecond.startsWith(newFirst) && SERIAL_RE.test(newSecond.slice(newFirst.length)));
+}
+
+function renamedPointer(pointer: string, renames: Renames): string {
+  if (!pointer.startsWith(`${ROOT_POINTER}/`)) {
+    return pointer;
+  }
+  const [components, group = "", name = "", ...rest] = parseRefPointer(canonicalRef(pointer));
+  const renamed = components === COMPONENTS_KEY ? renames.get(group)?.get(name) : undefined;
+  return renamed === undefined
+    ? pointer
+    : appendPointer(ROOT_POINTER, [COMPONENTS_KEY, group, renamed, ...rest]);
+}
+
+function renamedText(text: string, renames: Renames): string {
+  const pairs = [...renames.values()].flatMap((group) => [...group]);
+  // The longest old name first, so a name that starts another one does not split it.
+  pairs.sort(([a], [b]) => b.length - a.length);
+  return pairs.reduce((shown, [old, renamed]) => shown.replaceAll(old, renamed), text);
+}
+
+function rewriteRefs(document: unknown, renaming: ComponentRenaming): void {
+  for (const { node } of findRefHolders(document)) {
+    node.$ref = renaming.pointer(node.$ref);
+  }
+  for (const mapping of findMappings(document)) {
+    for (const [name, value] of Object.entries(mapping)) {
+      if (typeof value === "string") {
+        mapping[name] = renaming.pointer(value);
+      }
+    }
+  }
+}
+
+/**
+ * Rename, in place, the components the bundle named after a URL with a query, and every local
+ * `$ref` and `mapping` value that names them. `documents` are the documents the load read.
+ */
+export function renameQueryNamedComponents(
+  bundled: unknown,
+  keysBefore: ComponentKeys,
+  documents: readonly LoadedDocument[],
+): ComponentRenaming {
+  const documentNames = queryDocumentNames(documents);
+  const renames: Renames = new Map();
+  if (documentNames.size > 0) {
+    for (const [group, entries] of Object.entries(componentsOf(bundled))) {
+      const groupRenames = renameGroup(entries, keysBefore.get(group) ?? new Set(), documentNames);
+      if (groupRenames.size > 0) {
+        renames.set(group, groupRenames);
+      }
+    }
+  }
+  const renaming: ComponentRenaming = {
+    pointer: (pointer) => renamedPointer(pointer, renames),
+    text: (text) => renamedText(text, renames),
+    isResolvedCollision: (message) => resolvesCollision(message, renames),
+  };
+  if (renames.size > 0) {
+    rewriteRefs(bundled, renaming);
+  }
+  return renaming;
+}

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

@@ -1,6 +1,12 @@
 import fs from "node:fs";
 import path from "node:path";
-import { createConfig, findConfig, IGNORE_FILE, loadConfig } from "@redocly/openapi-core";
+import {
+  createConfig,
+  findConfig,
+  getMergedConfig,
+  IGNORE_FILE,
+  loadConfig,
+} from "@redocly/openapi-core";
 import type {
   RedoclyConfig,
   RedoclyConfigSource,
@@ -70,6 +76,10 @@ class RedoclyConfigFiles implements RedoclyConfigSource {
       );
     return loadedConfig(create, undefined);
   }
+
+  forApi(config: RedoclyConfig, apiName: string): RedoclyConfig {
+    return getMergedConfig(config, apiName);
+  }
 }
 
 /** Find and load `redocly.yaml` relative to the directory `cwd`. */

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

@@ -3,6 +3,7 @@ import {
   type BaseResolver,
   bundle,
   type Document,
+  type LocationObject,
   lintDocument,
   type NormalizedProblem,
   type Config as RedoclyConfig,
@@ -14,16 +15,27 @@ import type {
   SchemaLoadRequest,
 } from "../../application/ports/schema-loader.js";
 import { withStackOverflowReportedAsync } from "../../application/stack-overflow.js";
+import { redactUrlSecrets } from "../../domain/url-secrets.js";
 import { WARNING_CODES, warningText } from "../../domain/warnings.js";
 import type { OpenAPI3 } from "../../types.js";
 import { removeBundledMappingCopies, schemaKeysOf } from "./bundled-mapping-copies.js";
 import { repairBundledRefs } from "./bundled-ref-repair.js";
 import { loadedDocuments, localFilesRead } from "./loaded-documents.js";
 import { findMalformedRefs, malformedRefsError } from "./malformed-refs.js";
+import { pointMappingNamesAtSchemas } from "./mapping-schema-names.js";
+import {
+  type ComponentRenaming,
+  componentKeysOf,
+  renameQueryNamedComponents,
+} from "./query-named-components.js";
 import { RefAccessResolver } from "./ref-access.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 {
+  RedirectedUrls,
+  type RemoteDocumentLimits,
+  resolveConfigWithAccess,
+} from "./remote-fetch.js";
 import {
   loadFailedError,
   refCycleError,
@@ -160,6 +172,7 @@ class RedoclySchemaLoader implements SchemaLoader {
     const document = await parseSchema(request.source, { absoluteRef, resolver });
     logger.debug("Parsed schema", "redoc", now() - parseStartedAt);
     assertOpenAPI3(document.parsed);
+    pointMappingNamesAtSchemas(document.parsed);
     const bundled = await this.#lintAndBundle(document, resolver, request.shouldLint);
     const isRootAFile = request.source instanceof URL && request.source.protocol === "file:";
     const localFiles = await localFilesRead(document, resolver, isRootAFile);
@@ -168,16 +181,21 @@ class RedoclySchemaLoader implements SchemaLoader {
 
   #resolver(request: SchemaLoadRequest): RefAccessResolver {
     const { redoc, remoteRefTimeoutMs, remoteDocumentLimits } = this.#options;
+    // One record per load, as the resolver and its cache are.
+    const redirects = new RedirectedUrls();
     const config = resolveConfigWithAccess(redoc.resolve, {
       timeoutMs: remoteRefTimeoutMs,
       access: request.refAccess,
+      rootUrl: request.source instanceof URL ? request.source.href : undefined,
       maxParallelFetches: remoteDocumentLimits.maxParallelFetches,
       bodyLimits: remoteDocumentLimits,
+      redirects,
     });
     return new RefAccessResolver(config, {
       access: request.refAccess,
       maxRemoteDocuments: remoteDocumentLimits.maxDocuments,
       maxRemoteNodes: remoteDocumentLimits.maxNodes,
+      redirects,
     });
   }
 
@@ -202,13 +220,14 @@ class RedoclySchemaLoader implements SchemaLoader {
       config: this.#options.redoc.styleguide,
       externalRefResolver: resolver,
     });
-    this.#report(problems);
+    this.#report(problems, document.source.absoluteRef);
     this.#options.logger.debug("Linted schema", "lint", this.#options.now() - startedAt);
   }
 
   async #bundle(document: Document, resolver: BaseResolver): Promise<OpenAPI3> {
     const startedAt = this.#options.now();
     const schemaKeys = schemaKeysOf(document.parsed);
+    const componentKeys = componentKeysOf(document.parsed);
     // The lint resolver: documents it already loaded are not fetched again.
     const bundled = await bundle({
       config: this.#options.redoc,
@@ -216,9 +235,12 @@ class RedoclySchemaLoader implements SchemaLoader {
       doc: document,
       externalRefResolver: resolver,
     });
-    this.#report(bundled.problems);
     removeBundledMappingCopies(bundled.bundle.parsed, schemaKeys);
     repairBundledRefs(bundled.bundle.parsed);
+    const documents = await loadedDocuments(document, resolver);
+    const renaming = renameQueryNamedComponents(bundled.bundle.parsed, componentKeys, documents);
+    // The problems name the components the bundle made, so they are shown by their new names.
+    this.#report(bundled.problems, document.source.absoluteRef, renaming);
     this.#options.logger.debug("Bundled schema", "bundle", this.#options.now() - startedAt);
     return bundled.bundle.parsed;
   }
@@ -226,24 +248,26 @@ class RedoclySchemaLoader implements SchemaLoader {
   /**
    * Report every problem; then throw if any of them is an error. A problem that the Redocly
    * config's `.redocly.lint-ignore.yaml` lists is left out, as `redocly lint` leaves it out
-   * (upstream #2189).
+   * (upstream #2189). A name collision that the renamed components no longer have is dropped.
    */
-  #report(problems: readonly NormalizedProblem[]): void {
+  #report(problems: readonly NormalizedProblem[], rootRef: string, renaming = UNRENAMED): void {
     const errorMessages: string[] = [];
-    for (const problem of problems) {
+    for (const problem of problems.filter(
+      (found) => !renaming.isResolvedCollision(found.message),
+    )) {
       if (problem.ignored === true) {
         this.#options.logger.debug(
-          `Ignored by the lint ignore file: ${problemMessage(problem)}`,
+          `Ignored by the lint ignore file: ${problemMessage(problem, renaming, rootRef)}`,
           "lint",
         );
         continue;
       }
-      const message = problemMessage(problem);
+      const message = problemMessage(problem, renaming, rootRef);
       if (problem.severity === "error") {
         errorMessages.push(message);
         this.#options.logger.error(message);
       } else {
-        this.#options.logger.warn(lintWarningText(problem));
+        this.#options.logger.warn(lintWarningText(message, problem.ruleId));
       }
     }
     if (errorMessages.length > 0) {
@@ -253,16 +277,38 @@ 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 lintWarningText(message: string, ruleId: string): string {
+  return warningText(`${message}, rule ${ruleId}`, WARNING_CODES.LINT_PROBLEM);
+}
+
+/** Problems found before the bundle named any component. */
+const UNRENAMED: ComponentRenaming = {
+  pointer: (pointer) => pointer,
+  text: (text) => text,
+  isResolvedCollision: () => false,
+};
+
+/** A problem location that names a JSON Pointer, not a line and column. */
+type PointerLocation = Extract<LocationObject, { pointer: string }>;
+
+/**
+ * Where a problem is: its pointer, and the document when it is not the root (URL secrets left
+ * out).
+ */
+function locationText(location: PointerLocation, renaming: ComponentRenaming, rootRef: string) {
+  const pointer = renaming.pointer(location.pointer);
+  const documentRef = location.source.absoluteRef;
+  return documentRef === rootRef ? pointer : `${pointer} in ${redactUrlSecrets(documentRef)}`;
 }
 
-function problemMessage(problem: NormalizedProblem): string {
-  const location = problem.location?.[0]?.pointer;
-  return location ? `${problem.message} at ${location}` : problem.message;
+function problemMessage(
+  problem: NormalizedProblem,
+  renaming: ComponentRenaming,
+  rootRef: string,
+): string {
+  const location = problem.location?.[0];
+  const message = renaming.text(problem.message);
+  return location?.pointer ? `${message} at ${locationText(location, renaming, rootRef)}` : message;
 }
 
 /** A schema loader with one Redocly config and logger, for one or more loads. */

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

@@ -5,7 +5,7 @@ import {
   BaseResolver,
   type Document,
   type Config as RedoclyConfig,
-  type Source,
+  Source,
   YamlParseError,
 } from "@redocly/openapi-core";
 import type { RefAccess } from "../../application/ports/schema-loader.js";
@@ -13,6 +13,8 @@ import { ERROR_CODES, type OpenAPITypesafeError } from "../../domain/errors.js";
 import { redactUrlSecrets } from "../../domain/url-secrets.js";
 import { aliasExpansionFailure } from "./alias-limit.js";
 import { isHostAllowed } from "./allowed-hosts.js";
+import { pointMappingNamesAtSchemas } from "./mapping-schema-names.js";
+import type { RedirectedUrls } from "./remote-fetch.js";
 import { isParsedSource, RemoteNodeLimit } from "./remote-node-limit.js";
 import { refForbiddenError } from "./schema-load-errors.js";
 
@@ -107,6 +109,8 @@ export interface RefAccessLimits {
   readonly maxRemoteDocuments: number;
   /** Nodes the remote documents of one load may parse into together (threat model T2). */
   readonly maxRemoteNodes: number;
+  /** The final URLs of redirected documents, which their relative `$ref`s resolve against. */
+  readonly redirects: RedirectedUrls;
 }
 
 /**
@@ -162,21 +166,33 @@ export class RefAccessResolver extends BaseResolver {
     return super.resolveDocument(base, ref, isRoot);
   }
 
-  /** Refuse a YAML alias bomb before Redocly walks it (pre-beta test plan 10.2). */
+  /**
+   * Refuse a YAML alias bomb before Redocly walks it (pre-beta test plan 10.2). A document a
+   * `$ref` loads has its own `components.schemas`, so its mapping names point at those schemas
+   * before Redocly resolves them, as the root's do (`pointMappingNamesAtSchemas`).
+   */
   override parseDocument(source: Source, isRoot = false): Document {
     const document = this.#parsed(source, isRoot);
     const failure = aliasExpansionFailure(document.parsed);
     if (failure !== undefined) {
       throw new YamlParseError(failure, source);
     }
+    pointMappingNamesAtSchemas(document.parsed);
     return document;
   }
 
-  /** A remote document is parsed within the node limit; any other one as Redocly parses it. */
+  /**
+   * A remote document is parsed within the node limit; a local one as Redocly parses it. Whether
+   * a remote one is parsed at all is decided here (`isParsedSource`), since Redocly read the
+   * extension of a URL with its query.
+   */
   #parsed(source: Source, isRoot: boolean): Document {
-    if (!isRemoteRef(source.absoluteRef) || !isParsedSource(source, isRoot)) {
+    if (!isRemoteRef(source.absoluteRef)) {
       return super.parseDocument(source, isRoot);
     }
+    if (!isParsedSource(source, isRoot)) {
+      return { source, parsed: source.body };
+    }
     try {
       return this.#nodeLimit.parse(source);
     } catch (error) {
@@ -194,7 +210,7 @@ export class RefAccessResolver extends BaseResolver {
       throw refusal;
     }
     try {
-      return await super.loadExternalRef(absoluteRef);
+      return this.#atFinalUrl(await super.loadExternalRef(absoluteRef));
     } catch (error) {
       // A refused redirect throws inside the fetch, and Redocly wraps it in a ResolveError.
       const cause = (error as { originalError?: unknown }).originalError;
@@ -205,6 +221,17 @@ export class RefAccessResolver extends BaseResolver {
     }
   }
 
+  /**
+   * A redirected document is named by the URL it came from, so its relative `$ref`s, its
+   * component names and its problems use that URL. Redocly still finds it by the requested one.
+   */
+  #atFinalUrl(source: Source): Source {
+    const finalUrl = this.#limits.redirects.finalUrlOf(source.absoluteRef);
+    return finalUrl === source.absoluteRef
+      ? source
+      : new Source(finalUrl, source.body, source.mimeType);
+  }
+
   #accessRefusal(absoluteRef: string): Promise<OpenAPITypesafeError | undefined> {
     return absoluteRef === this.#rootRef
       ? Promise.resolve(undefined)

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

@@ -6,38 +6,99 @@ export interface RefHolder {
   readonly pointer: string;
 }
 
+/**
+ * Keywords whose value is data, not OpenAPI: a `$ref` or a `discriminator` in an example, a
+ * default, a `const` or an `enum` value, or an extension is part of the data and stays as written.
+ */
+const DATA_KEYWORDS = new Set(["example", "examples", "default", "const", "enum"]);
+const EXTENSION_PREFIX = "x-";
+
+/**
+ * Keywords whose value maps names to objects: a property, a schema or a response may be named
+ * `default` or `example`, and is OpenAPI all the same.
+ */
+const NAME_MAPS = new Set([
+  "properties",
+  "patternProperties",
+  "dependentSchemas",
+  "$defs",
+  "definitions",
+  "schemas",
+  "responses",
+  "parameters",
+  "requestBodies",
+  "headers",
+  "securitySchemes",
+  "links",
+  "callbacks",
+  "pathItems",
+  "mediaTypes",
+  "content",
+  "encoding",
+  "paths",
+  "webhooks",
+]);
+
 interface PendingNode {
   readonly value: object;
   readonly pointer: string;
+  /** Whether the keys of `value` are names (of properties, schemas, responses), not keywords. */
+  readonly hasNameKeys: boolean;
 }
 
-function hasStringRef(value: object): value is { $ref: string } {
-  return !Array.isArray(value) && typeof (value as { $ref?: unknown }).$ref === "string";
+function isDataKey(key: string): boolean {
+  return DATA_KEYWORDS.has(key) || key.startsWith(EXTENSION_PREFIX);
 }
 
 /**
- * Every object with a string `$ref` in a parsed document, in no particular order. The walk uses
- * its own stack, so a deeply nested document does not run out of call stack, and a node shared by
- * YAML aliases (or a cycle of them) is visited once.
+ * Every object of a parsed document that is OpenAPI, not data (`DATA_KEYWORDS`), with its JSON
+ * Pointer, in no particular order. The walk uses its own stack, so a deeply nested document does
+ * not run out of call stack, and a node shared by YAML aliases (or a cycle of them) is visited
+ * once.
  */
-export function findRefHolders(document: unknown): RefHolder[] {
-  const found: RefHolder[] = [];
+function openApiNodes(document: unknown): PendingNode[] {
+  const found: PendingNode[] = [];
   const visited = new WeakSet<object>();
   const pending: PendingNode[] = [];
-  const enqueue = (value: unknown, pointer: string): void => {
+  const enqueue = (value: unknown, pointer: string, hasNameKeys: boolean): void => {
     if (typeof value === "object" && value !== null && !visited.has(value)) {
       visited.add(value);
-      pending.push({ value, pointer });
+      pending.push({ value, pointer, hasNameKeys });
     }
   };
-  enqueue(document, ROOT_POINTER);
+  enqueue(document, ROOT_POINTER, false);
   for (let next = pending.pop(); next !== undefined; next = pending.pop()) {
-    if (hasStringRef(next.value)) {
-      found.push({ node: next.value, pointer: next.pointer });
-    }
+    found.push(next);
+    // One push per child: spreading an array of millions of children overflows the stack.
     for (const [key, child] of Object.entries(next.value)) {
-      enqueue(child, childPointer(next.pointer, key));
+      if (next.hasNameKeys || !isDataKey(key)) {
+        enqueue(child, childPointer(next.pointer, key), !next.hasNameKeys && NAME_MAPS.has(key));
+      }
     }
   }
   return found;
 }
+
+function hasStringRef(value: object): value is { $ref: string } {
+  return !Array.isArray(value) && typeof (value as { $ref?: unknown }).$ref === "string";
+}
+
+/** Every object with a string `$ref` in a parsed document, outside data, in no particular order. */
+export function findRefHolders(document: unknown): RefHolder[] {
+  return openApiNodes(document).flatMap(({ value, pointer, hasNameKeys }) =>
+    !hasNameKeys && hasStringRef(value) ? [{ node: value, pointer }] : [],
+  );
+}
+
+function isMapping(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+/** Every `discriminator.mapping` object of a parsed document, outside data. */
+export function findMappings(document: unknown): Record<string, unknown>[] {
+  return openApiNodes(document).flatMap(({ value, hasNameKeys }) => {
+    const { discriminator } = value as { discriminator?: unknown };
+    const mapping = !hasNameKeys && isMapping(discriminator) ? discriminator.mapping : undefined;
+    return isMapping(mapping) ? [mapping] : [];
+  });
+}