openapi-typesafe 1.0.0-rc.4 → 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,6 +3,7 @@ import {
   type BaseResolver,
   bundle,
   type Document,
+  type LocationObject,
   lintDocument,
   type NormalizedProblem,
   type Config as RedoclyConfig,
@@ -14,12 +15,19 @@ 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";
@@ -160,6 +168,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);
@@ -171,6 +180,7 @@ 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,
     });
@@ -202,13 +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,
@@ -216,9 +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;
   }
@@ -228,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) {
@@ -253,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

@@ -13,6 +13,7 @@ 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 { isParsedSource, RemoteNodeLimit } from "./remote-node-limit.js";
 import { refForbiddenError } from "./schema-load-errors.js";
 
@@ -162,21 +163,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) {

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] : [];
+  });
+}

package/src/adapters/redocly-loader/remote-fetch.ts

@@ -115,6 +115,11 @@ export interface RedirectPolicy {
   readonly headers: readonly ConfiguredHeader[];
   /** `--remote-ref-hosts`; undefined allows every host. */
   readonly hosts: readonly string[] | undefined;
+  /**
+   * The URL of the root document, if it is remote. The developer chose it, so neither it nor its
+   * redirects are limited to the hosts (ADR-017): a spec URL that redirects to a CDN loads.
+   */
+  readonly rootUrl: string | undefined;
 }
 
 /**
@@ -130,12 +135,13 @@ export function fetchWithCheckedRedirects(
   policy: RedirectPolicy,
 ): RemoteFetch {
   return async (input, init = {}) => {
+    const hosts = input === policy.rootUrl ? undefined : policy.hosts;
     let url = new URL(input);
     for (let hop = 0; hop <= MAX_REDIRECTS; hop += 1) {
-      if (hop > 0 && policy.hosts !== undefined && !isHostAllowed(url, policy.hosts)) {
+      if (hop > 0 && hosts !== undefined && !isHostAllowed(url, hosts)) {
         throw refForbiddenError(url.href, {
           reason: "host-not-allowed",
-          allowedHosts: [...policy.hosts],
+          allowedHosts: [...hosts],
         });
       }
       const headers = await headersFor(url, policy.headers);
@@ -190,6 +196,8 @@ export interface RemoteFetchOptions {
   /** Time limit of one fetch and its body, unless the Redocly config has its own `customFetch`. */
   readonly timeoutMs: number;
   readonly access: RefAccess;
+  /** The root document's URL, whose redirects are not limited to the hosts. */
+  readonly rootUrl: string | undefined;
   readonly maxParallelFetches: number;
   readonly bodyLimits: RemoteBodyLimits;
 }
@@ -216,6 +224,7 @@ export function resolveConfigWithAccess(
   const checked = fetchWithCheckedRedirects(base, {
     headers: resolve.http.headers,
     hosts: options.access.remoteHosts,
+    rootUrl: options.rootUrl,
   });
   // The limit is outside the redirects, so all hops of one document share one slot.
   const customFetch = fetchWithConcurrencyLimit(checked, options.maxParallelFetches);

package/src/adapters/redocly-loader/remote-node-limit.ts

@@ -13,12 +13,52 @@ import { refForbiddenError } from "./schema-load-errors.js";
 /** The extensions that Redocly 1.34's `BaseResolver.parseDocument` parses as YAML or JSON. */
 const PARSED_EXTENSIONS: ReadonlySet<string> = new Set([".json", ".yml", ".yaml"]);
 const PARSED_MIME_TYPE = /(json|yaml|openapi)/;
+/**
+ * The text formats that a `$ref` loads as text, as a `description` from a Markdown file. A URL
+ * keeps its document as text only when its extension or type names one of them: the last segment
+ * of an API's path often has a dot that is no file type (`/schemas/v1.0`, `/schemas/pet.v2`).
+ */
+const TEXT_EXTENSIONS: ReadonlySet<string> = new Set([".md", ".markdown", ".txt", ".html", ".htm"]);
+const TEXT_MIME_TYPE = /^text\/(markdown|x-markdown|html)\b/;
+const REMOTE_URL_RE = /^https?:\/\//;
+const PATH_SEPARATOR_RE = /[/\\]/;
+const EXTENSION_START = ".";
+
+/** The extension of the last segment of a path, with its dot; empty when it has none. */
+function extensionOf(path: string): string {
+  const name = path.split(PATH_SEPARATOR_RE).at(-1) ?? "";
+  const start = name.lastIndexOf(EXTENSION_START);
+  return start === -1 ? "" : name.slice(start);
+}
+
+/**
+ * The path of a document: the path of a URL, without its query and fragment, or the file path.
+ * Redocly took the extension of the whole URL, so `pet.yaml?token=…` had none it knew.
+ */
+function documentPath(absoluteRef: string): string {
+  return REMOTE_URL_RE.test(absoluteRef) && URL.canParse(absoluteRef)
+    ? new URL(absoluteRef).pathname
+    : absoluteRef;
+}
 
-/** Whether Redocly parses this source, or keeps its text: the same rule as its own resolver. */
+/**
+ * Whether a source is parsed as YAML or JSON, or kept as text (a Markdown `description`, say).
+ * It is parsed when it is the root, when its type or the extension of its path says JSON or YAML,
+ * and when it is a URL whose path and type name no text format: an API serves its documents at
+ * paths like `/schemas/pet` or `/schemas/v1.0`, often as `text/plain`, and Redocly kept those as
+ * text, which failed as a schema. A local file is kept as text unless its name says JSON or YAML,
+ * as Redocly keeps it.
+ */
 export function isParsedSource(source: Source, isRoot: boolean): boolean {
-  const { absoluteRef, mimeType } = source;
-  const extension = absoluteRef.slice(absoluteRef.lastIndexOf("."));
-  return isRoot || PARSED_EXTENSIONS.has(extension) || PARSED_MIME_TYPE.test(mimeType ?? "");
+  const { absoluteRef, mimeType = "" } = source;
+  const extension = extensionOf(documentPath(absoluteRef));
+  const isTextUrl = TEXT_EXTENSIONS.has(extension) || TEXT_MIME_TYPE.test(mimeType);
+  return (
+    isRoot ||
+    PARSED_EXTENSIONS.has(extension) ||
+    PARSED_MIME_TYPE.test(mimeType) ||
+    (REMOTE_URL_RE.test(absoluteRef) && !isTextUrl)
+  );
 }
 
 /** The parser's event for a node it starts to build. */

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

@@ -4,7 +4,7 @@ import { fileURLToPath } from "node:url";
 import {
   type BaseResolver,
   type Document,
-  makeDocumentFromString,
+  parseYaml,
   ResolveError,
   Source,
   YamlParseError,
@@ -74,12 +74,24 @@ function parseJsonText(text: string, absoluteRef: string): Document {
   }
 }
 
+/**
+ * How a parser message names document text that is no file. The document itself is named as a
+ * file in the working directory, so that its relative `$ref`s resolve there, but no such file
+ * exists, and a message that named it sent the user looking for it.
+ */
+const TEXT_ORIGIN_NAMES: Readonly<Record<TextOrigin, string>> = {
+  string: "the schema string",
+  stream: "the schema stream",
+};
+
 function parseYamlText(text: string, absoluteRef: string, origin: TextOrigin): Document {
+  const source = new Source(absoluteRef, text);
   let document: Document;
   try {
-    document = makeDocumentFromString(text, absoluteRef);
+    document = { source, parsed: parseYaml(text, { filename: TEXT_ORIGIN_NAMES[origin] }) };
   } catch (cause) {
-    throw parseFailedError("yaml", absoluteRef, cause);
+    // As Redocly's own parse: the error keeps the first line, not the parser's code excerpt.
+    throw parseFailedError("yaml", absoluteRef, new YamlParseError(cause as Error, source));
   }
   // Text that is only a YAML string scalar, such as "./openapi.yaml", was meant as a file path.
   if (typeof document.parsed === "string") {