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

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

@@ -0,0 +1,201 @@
+import {
+  appendPointer,
+  canonicalRef,
+  parseRefPointer,
+  ROOT_POINTER,
+} from "../../domain/openapi/json-pointer.js";
+import { findMappings, findRefHolders } from "./ref-holders.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.
+ */
+
+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";
+const REMOTE_URL_RE = /^https?:\/\//;
+const PATH_SEPARATOR_RE = /[/\\]/;
+const EXTENSION_RE = /\.[^.]+$/;
+/** What Redocly puts between the base name and the rest of a component name. */
+const NAME_SUFFIX_STARTS = ["_", "-"];
+const FIRST_SERIAL = 2;
+
+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 base name Redocly 1.34 gives a document (`refBaseName`): the last segment, no extension. */
+function redoclyBaseName(ref: string): string {
+  return (ref.split(PATH_SEPARATOR_RE).at(-1) ?? "").replace(EXTENSION_RE, "");
+}
+
+/**
+ * The base name of the URL without its query and fragment. A URL with no last segment
+ * (`https://host/?key=…`) is named after its host, so the name is never empty.
+ */
+function queryFreeBaseName(url: URL): string {
+  const withoutQuery = new URL(url.pathname, url.origin).href;
+  return redoclyBaseName(withoutQuery) || url.hostname;
+}
+
+/** Each base name Redocly takes from a remote URL with a query, with the name to use instead. */
+function queryBaseNames(documentRefs: Iterable<string>): Map<string, string> {
+  const names = new Map<string, string>();
+  for (const ref of documentRefs) {
+    const url = REMOTE_URL_RE.test(ref) && URL.canParse(ref) ? new URL(ref) : undefined;
+    if (url === undefined || url.search === "") {
+      continue;
+    }
+    const named = redoclyBaseName(ref);
+    const clean = queryFreeBaseName(url);
+    if (named !== clean) {
+      names.set(named, clean);
+    }
+  }
+  return names;
+}
+
+/** The name `key` gets, or undefined when no query base name starts it. */
+function queryFreeName(key: string, baseNames: ReadonlyMap<string, string>): string | undefined {
+  // The longest base name first: `pet?a=1` must not match as `pet?a` when both were loaded.
+  const matches = [...baseNames.keys()].filter(
+    (named) =>
+      key === named || NAME_SUFFIX_STARTS.some((start) => key.startsWith(`${named}${start}`)),
+  );
+  const named = matches.sort((a, b) => b.length - a.length)[0];
+  return named === undefined ? undefined : `${baseNames.get(named)}${key.slice(named.length)}`;
+}
+
+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>,
+  baseNames: ReadonlyMap<string, string>,
+): Map<string, string> {
+  const renames = new Map<string, string>();
+  const taken = new Set(Object.keys(entries));
+  for (const key of Object.keys(entries)) {
+    const name = keysBefore.has(key) ? undefined : queryFreeName(key, baseNames);
+    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;
+}
+
+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. `documentRefs` are the refs of the loaded documents.
+ */
+export function renameQueryNamedComponents(
+  bundled: unknown,
+  keysBefore: ComponentKeys,
+  documentRefs: Iterable<string>,
+): ComponentRenaming {
+  const baseNames = queryBaseNames(documentRefs);
+  const renames: Renames = new Map();
+  if (baseNames.size > 0) {
+    for (const [group, entries] of Object.entries(componentsOf(bundled))) {
+      const groupRenames = renameGroup(entries, keysBefore.get(group) ?? new Set(), baseNames);
+      if (groupRenames.size > 0) {
+        renames.set(group, groupRenames);
+      }
+    }
+  }
+  const renaming: ComponentRenaming = {
+    pointer: (pointer) => renamedPointer(pointer, renames),
+    text: (text) => renamedText(text, renames),
+  };
+  if (renames.size > 0) {
+    rewriteRefs(bundled, renaming);
+  }
+  return renaming;
+}

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

@@ -3,17 +3,31 @@ import {
   type BaseResolver,
   bundle,
   type Document,
+  type LocationObject,
   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 type {
+  LoadedSchema,
+  SchemaLoader,
+  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";
@@ -25,11 +39,7 @@ import {
   versionUnsupportedError,
 } from "./schema-load-errors.js";
 import { parseSchema } from "./schema-source.js";
-import {
-  findUnsupportedKeys,
-  type LoadedDocument,
-  unsupportedKeysError,
-} from "./unsupported-keys.js";
+import { findUnsupportedKeys, unsupportedKeysError } from "./unsupported-keys.js";
 
 /**
  * The SchemaLoader port on Redocly 1.34 (ADR-005): parse any inherited source type, then lint and
@@ -107,21 +117,6 @@ function sourceFilePath(source: URL): string {
   }
 }
 
-/**
- * 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,
@@ -148,7 +143,7 @@ class RedoclySchemaLoader implements SchemaLoader {
     this.#options = options;
   }
 
-  async load(request: SchemaLoadRequest): Promise<OpenAPI3> {
+  async load(request: SchemaLoadRequest): Promise<LoadedSchema> {
     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.
@@ -164,7 +159,7 @@ class RedoclySchemaLoader implements SchemaLoader {
     return bundled;
   }
 
-  async #parseAndBundle(request: SchemaLoadRequest, resolver: BaseResolver): Promise<OpenAPI3> {
+  async #parseAndBundle(request: SchemaLoadRequest, resolver: BaseResolver): Promise<LoadedSchema> {
     const { logger, now } = this.#options;
     const configLoadedAt = now();
     logger.debug("Loaded Redoc config", "redoc", now() - configLoadedAt);
@@ -173,7 +168,11 @@ class RedoclySchemaLoader implements SchemaLoader {
     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);
+    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);
+    return { document: bundled, localFiles };
   }
 
   #resolver(request: SchemaLoadRequest): RefAccessResolver {
@@ -181,11 +180,14 @@ class RedoclySchemaLoader implements SchemaLoader {
     const config = resolveConfigWithAccess(redoc.resolve, {
       timeoutMs: remoteRefTimeoutMs,
       access: request.refAccess,
+      rootUrl: request.source instanceof URL ? request.source.href : undefined,
       maxParallelFetches: remoteDocumentLimits.maxParallelFetches,
+      bodyLimits: remoteDocumentLimits,
     });
     return new RefAccessResolver(config, {
       access: request.refAccess,
       maxRemoteDocuments: remoteDocumentLimits.maxDocuments,
+      maxRemoteNodes: remoteDocumentLimits.maxNodes,
     });
   }
 
@@ -210,12 +212,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,
@@ -223,8 +227,12 @@ class RedoclySchemaLoader implements SchemaLoader {
       doc: document,
       externalRefResolver: resolver,
     });
-    this.#report(bundled.problems);
+    removeBundledMappingCopies(bundled.bundle.parsed, schemaKeys);
     repairBundledRefs(bundled.bundle.parsed);
+    const documentRefs = resolver.getFiles();
+    const renaming = renameQueryNamedComponents(bundled.bundle.parsed, componentKeys, documentRefs);
+    // 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;
   }
@@ -234,22 +242,22 @@ class RedoclySchemaLoader implements SchemaLoader {
    * config's `.redocly.lint-ignore.yaml` lists is left out, as `redocly lint` leaves it out
    * (upstream #2189).
    */
-  #report(problems: readonly NormalizedProblem[]): void {
+  #report(problems: readonly NormalizedProblem[], rootRef: string, renaming = UNRENAMED): void {
     const errorMessages: string[] = [];
     for (const problem of problems) {
       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) {
@@ -259,16 +267,34 @@ 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 };
+
+/** 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

@@ -10,9 +10,11 @@ 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 { 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 { isParsedSource, RemoteNodeLimit } from "./remote-node-limit.js";
 import { refForbiddenError } from "./schema-load-errors.js";
 
 /**
@@ -92,15 +94,20 @@ function localFromRemoteRefusal(
   if (!isRemoteRef(base) || isRemoteRef(absoluteRef)) {
     return undefined;
   }
-  const shownBase = redactUrlCredentials(base);
+  const shownBase = redactUrlSecrets(base);
   return refForbiddenError(absoluteRef, { reason: "local-ref-from-remote", base: shownBase });
 }
 
+/** The scheme of an `http(s)` URL, in any case. */
+const REMOTE_SCHEME_RE = /^https?:(?=\/\/)/i;
+
 /** 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;
+  /** Nodes the remote documents of one load may parse into together (threat model T2). */
+  readonly maxRemoteNodes: number;
 }
 
 /**
@@ -110,6 +117,7 @@ export interface RefAccessLimits {
  */
 export class RefAccessResolver extends BaseResolver {
   readonly #limits: RefAccessLimits;
+  readonly #nodeLimit: RemoteNodeLimit;
   readonly #refusals: OpenAPITypesafeError[] = [];
   /** The root document's ref: it is chosen by the developer, so it is not limited. */
   #rootRef: string | undefined;
@@ -119,6 +127,7 @@ export class RefAccessResolver extends BaseResolver {
   constructor(config: ResolveConfig, limits: RefAccessLimits) {
     super(config);
     this.#limits = limits;
+    this.#nodeLimit = new RemoteNodeLimit(limits.maxRemoteNodes);
   }
 
   /** The first document that was refused, if any. */
@@ -126,6 +135,17 @@ export class RefAccessResolver extends BaseResolver {
     return this.#refusals[0];
   }
 
+  /**
+   * A scheme is the same in any case (RFC 3986, section 3.1), but Redocly takes only `http://` and
+   * `https://` as URLs: it read `HTTP://host/x.yaml` as a file path, and its "not found" message
+   * showed the user info and the query of the URL, which no longer looked like one. The scheme
+   * is written in lowercase first, so the `$ref` loads as the URL it is, within the same limits.
+   */
+  override resolveExternalRef(base: string | null, ref: string): string {
+    const normalized = ref.replace(REMOTE_SCHEME_RE, (scheme) => scheme.toLowerCase());
+    return super.resolveExternalRef(base, normalized);
+  }
+
   override resolveDocument(
     base: string | null,
     ref: string,
@@ -143,16 +163,43 @@ 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 = super.parseDocument(source, isRoot);
+    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; 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)) {
+      return super.parseDocument(source, isRoot);
+    }
+    if (!isParsedSource(source, isRoot)) {
+      return { source, parsed: source.body };
+    }
+    try {
+      return this.#nodeLimit.parse(source);
+    } catch (error) {
+      if (isRefusal(error)) {
+        this.#refusals.push(error);
+      }
+      throw new YamlParseError(error as Error, source);
+    }
+  }
+
   override async loadExternalRef(absoluteRef: string): Promise<Source> {
     const refusal = this.#countRefusal(absoluteRef) ?? (await this.#accessRefusal(absoluteRef));
     if (refusal !== undefined) {

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

@@ -1,4 +1,4 @@
-import { escapePointerSegment } from "../../domain/openapi/json-pointer.js";
+import { childPointer, ROOT_POINTER } from "../../domain/openapi/json-pointer.js";
 
 /** An object with a string `$ref`, and its JSON Pointer in the document. */
 export interface RefHolder {
@@ -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, "#");
+  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, `${next.pointer}/${escapePointerSegment(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] : [];
+  });
+}