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

package/src/adapters/redocly-loader/query-document-names.ts

@@ -0,0 +1,79 @@
+import type { LoadedDocument } from "./unsupported-keys.js";
+
+/**
+ * Which loaded document with a query each node comes from, and the names Redocly and the loader
+ * give that document. Redocly names a component after the text behind the last `/` of the URL,
+ * query included, so `pet.json?ref=feature/new-api` and `owner.yaml?ref=feature/new-api` both give
+ * `new-api`: the name alone cannot tell the documents apart, the node can.
+ */
+
+const REMOTE_URL_RE = /^https?:\/\//;
+const PATH_SEPARATOR_RE = /[/\\]/;
+const EXTENSION_RE = /\.[^.]+$/;
+
+/** The base name Redocly gives a document and the one without the query. */
+export interface DocumentNames {
+  readonly named: string;
+  readonly clean: string;
+}
+
+/** 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;
+}
+
+/** The names of a remote document with a query whose Redocly name keeps it; else undefined. */
+function documentNamesOf(ref: string): DocumentNames | undefined {
+  const url = REMOTE_URL_RE.test(ref) && URL.canParse(ref) ? new URL(ref) : undefined;
+  if (url === undefined || url.search === "") {
+    return undefined;
+  }
+  const names = { named: redoclyBaseName(ref), clean: queryFreeBaseName(url) };
+  return names.named === names.clean ? undefined : names;
+}
+
+function isNode(value: unknown): value is object {
+  return typeof value === "object" && value !== null;
+}
+
+/** Every object and array of a parsed document, each once (a YAML alias can repeat one). */
+function nodesOf(parsed: unknown): object[] {
+  const visited = new Set<object>();
+  const pending = isNode(parsed) ? [parsed] : [];
+  for (let node = pending.pop(); node !== undefined; node = pending.pop()) {
+    if (!visited.has(node)) {
+      visited.add(node);
+      pending.push(...Object.values(node).filter(isNode));
+    }
+  }
+  return [...visited];
+}
+
+/**
+ * The names of the document each node of a loaded document with a query belongs to. The bundle
+ * keeps the nodes of the loaded documents as its components, so a component finds its document.
+ */
+export function queryDocumentNames(
+  documents: readonly LoadedDocument[],
+): ReadonlyMap<object, DocumentNames> {
+  const byNode = new Map<object, DocumentNames>();
+  for (const { source, parsed } of documents) {
+    const names = documentNamesOf(source);
+    if (names === undefined) {
+      continue;
+    }
+    for (const node of nodesOf(parsed)) {
+      byNode.set(node, names);
+    }
+  }
+  return byNode;
+}

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

@@ -4,7 +4,9 @@ import {
   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
@@ -13,6 +15,7 @@ import { findMappings, findRefHolders } from "./ref-holders.js";
  * 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>>;
@@ -24,12 +27,14 @@ export type ComponentKeys = ReadonlyMap<string, ReadonlySet<string>>;
 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;
+/**
+ * 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);
@@ -58,46 +63,17 @@ export function componentKeysOf(document: unknown): ComponentKeys {
   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);
-    }
+/** 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;
   }
-  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)}`;
+  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 {
@@ -112,12 +88,14 @@ function freeName(name: string, taken: ReadonlySet<string>): string {
 function renameGroup(
   entries: Record<string, unknown>,
   keysBefore: ReadonlySet<string>,
-  baseNames: ReadonlyMap<string, 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 name = keysBefore.has(key) ? undefined : queryFreeName(key, baseNames);
+    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);
@@ -138,6 +116,26 @@ export interface ComponentRenaming {
   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 {
@@ -173,18 +171,18 @@ function rewriteRefs(document: unknown, renaming: ComponentRenaming): void {
 
 /**
  * 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.
+ * `$ref` and `mapping` value that names them. `documents` are the documents the load read.
  */
 export function renameQueryNamedComponents(
   bundled: unknown,
   keysBefore: ComponentKeys,
-  documentRefs: Iterable<string>,
+  documents: readonly LoadedDocument[],
 ): ComponentRenaming {
-  const baseNames = queryBaseNames(documentRefs);
+  const documentNames = queryDocumentNames(documents);
   const renames: Renames = new Map();
-  if (baseNames.size > 0) {
+  if (documentNames.size > 0) {
     for (const [group, entries] of Object.entries(componentsOf(bundled))) {
-      const groupRenames = renameGroup(entries, keysBefore.get(group) ?? new Set(), baseNames);
+      const groupRenames = renameGroup(entries, keysBefore.get(group) ?? new Set(), documentNames);
       if (groupRenames.size > 0) {
         renames.set(group, groupRenames);
       }
@@ -193,6 +191,7 @@ export function renameQueryNamedComponents(
   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);

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

@@ -31,7 +31,11 @@ import {
 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,
@@ -177,17 +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,
     });
   }
 
@@ -229,8 +237,8 @@ class RedoclySchemaLoader implements SchemaLoader {
     });
     removeBundledMappingCopies(bundled.bundle.parsed, schemaKeys);
     repairBundledRefs(bundled.bundle.parsed);
-    const documentRefs = resolver.getFiles();
-    const renaming = renameQueryNamedComponents(bundled.bundle.parsed, componentKeys, documentRefs);
+    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);
@@ -240,11 +248,13 @@ 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[], 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, renaming, rootRef)}`,
@@ -272,7 +282,11 @@ function lintWarningText(message: string, ruleId: string): string {
 }
 
 /** Problems found before the bundle named any component. */
-const UNRENAMED: ComponentRenaming = { pointer: (pointer) => pointer, text: (text) => text };
+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 }>;

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";
@@ -14,6 +14,7 @@ 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";
 
@@ -108,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;
 }
 
 /**
@@ -207,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;
@@ -218,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/remote-fetch.ts

@@ -109,6 +109,27 @@ function fetchWithBodyLimit(fetchImpl: RemoteFetch, bodyLimit: RemoteBodyLimit):
   return async (input, init) => bufferedResponse(await fetchImpl(input, init), input, bodyLimit);
 }
 
+/**
+ * The URL each remote document was read from in the end, when redirects moved it. A relative
+ * `$ref` resolves against the URL the document was retrieved from (RFC 3986, section 5.1.3), so
+ * `/latest` that redirects to `/static/v1/root.yaml` loads `./pet.yaml` from `/static/v1/`.
+ * Redocly reads only the body of the response, so the fetch records the URL here.
+ */
+export class RedirectedUrls {
+  readonly #finalUrls = new Map<string, string>();
+
+  record(requested: string, final: string): void {
+    if (requested !== final) {
+      this.#finalUrls.set(requested, final);
+    }
+  }
+
+  /** The URL the document of `requested` came from; `requested` when it was not redirected. */
+  finalUrlOf(requested: string): string {
+    return this.#finalUrls.get(requested) ?? requested;
+  }
+}
+
 /** What every hop of a remote fetch is checked against. */
 export interface RedirectPolicy {
   /** `resolve.http.headers` of the Redocly config; chosen again for the URL of every hop. */
@@ -120,6 +141,8 @@ export interface RedirectPolicy {
    * redirects are limited to the hosts (ADR-017): a spec URL that redirects to a CDN loads.
    */
   readonly rootUrl: string | undefined;
+  /** Where the final URL of each redirected document is recorded. */
+  readonly redirects: RedirectedUrls;
 }
 
 /**
@@ -148,6 +171,7 @@ export function fetchWithCheckedRedirects(
       const response = await fetchImpl(url.href, { ...init, headers, redirect: "manual" });
       const location = response.headers.get("location");
       if (!REDIRECT_STATUSES.has(response.status) || location === null) {
+        policy.redirects.record(input, url.href);
         return response;
       }
       url = new URL(location, url);
@@ -200,6 +224,7 @@ export interface RemoteFetchOptions {
   readonly rootUrl: string | undefined;
   readonly maxParallelFetches: number;
   readonly bodyLimits: RemoteBodyLimits;
+  readonly redirects: RedirectedUrls;
 }
 
 /**
@@ -225,6 +250,7 @@ export function resolveConfigWithAccess(
     headers: resolve.http.headers,
     hosts: options.access.remoteHosts,
     rootUrl: options.rootUrl,
+    redirects: options.redirects,
   });
   // The limit is outside the redirects, so all hops of one document share one slot.
   const customFetch = fetchWithConcurrencyLimit(checked, options.maxParallelFetches);

package/src/api/cwd-option.ts

@@ -0,0 +1,76 @@
+import path from "node:path";
+import { fileURLToPath, pathToFileURL } from "node:url";
+import { hasUrlScheme } from "../domain/location-text.js";
+import type { GeneratorOptions } from "../types.js";
+import { processCwd } from "./default-ports.js";
+import { kindOf, optionInvalid } from "./option-errors.js";
+
+/**
+ * The `cwd` option: the directory that relative `$ref`s of an inline source resolve against
+ * (ADR-023). A string is read as `localRefRoot` is: a URL when it has a scheme, else a path.
+ */
+
+const FILE_PROTOCOL = "file:";
+
+/** A `file:` cwd is a local directory; an `http:` or `https:` one holds remote documents. */
+const CWD_PROTOCOLS: ReadonlySet<string> = new Set([FILE_PROTOCOL, "http:", "https:"]);
+
+const CWD_EXPECTED = "a directory path, or a file:, http: or https: URL";
+
+/** A path, resolved against the working directory, as a directory URL; `#` and `%` are encoded. */
+function pathDirectoryUrl(directory: string): URL {
+  return pathToFileURL(path.join(path.resolve(directory), path.sep));
+}
+
+/** The URL the value names, before its scheme is checked; undefined for another type. */
+function cwdUrlOf(value: unknown): URL | undefined {
+  if (value === undefined) {
+    return pathDirectoryUrl(processCwd());
+  }
+  if (typeof value === "string") {
+    if (!hasUrlScheme(value)) {
+      return pathDirectoryUrl(value);
+    }
+    return URL.parse(value, pathDirectoryUrl(processCwd()).href) ?? undefined;
+  }
+  if (Buffer.isBuffer(value)) {
+    return pathDirectoryUrl(value.toString());
+  }
+  return value instanceof URL ? value : undefined;
+}
+
+/** A `file:` URL with a host, or with an encoded slash, names no path on this platform. */
+function isLocalPath(url: URL): boolean {
+  try {
+    fileURLToPath(url);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/** What the cwd is instead of a directory, for the error. */
+function cwdKindOf(value: unknown, url: URL | undefined): string {
+  if (url?.protocol === FILE_PROTOCOL) {
+    return "a file: URL that names no local path";
+  }
+  return url === undefined && typeof value === "string"
+    ? "a string that is no valid URL"
+    : kindOf(url ?? value);
+}
+
+/**
+ * The cwd as a URL that ends in a slash. Fails with `OPTION_INVALID` for another type, a URL of
+ * another scheme or a `file:` URL that names no local path.
+ */
+export function sourceCwdOf(options: GeneratorOptions): URL {
+  const url = cwdUrlOf(options.cwd);
+  const isUsable =
+    url !== undefined &&
+    CWD_PROTOCOLS.has(url.protocol) &&
+    (url.protocol !== FILE_PROTOCOL || isLocalPath(url));
+  if (!isUsable) {
+    throw optionInvalid("cwd", CWD_EXPECTED, cwdKindOf(options.cwd, url));
+  }
+  return url.pathname.endsWith("/") ? url : new URL(`${url.pathname}/`, url);
+}

package/src/api/default-ports.ts

@@ -1,10 +1,11 @@
 import { performance } from "node:perf_hooks";
 import { createConfig, type Config as RedoclyConfig } from "@redocly/openapi-core";
-import supportsColor from "supports-color";
+import supportsColor, { type ColorInfo } from "supports-color";
 import { createNodeDeprecationReporter } from "../adapters/node-deprecations/node-deprecations.js";
 import type { RemoteDocumentLimits } from "../adapters/redocly-loader/remote-fetch.js";
 import {
   createTerminalLogger,
+  type TerminalLoggerOptions,
   type TerminalSink,
 } from "../adapters/terminal-logger/terminal-logger.js";
 import type { DeprecationReporter } from "../application/ports/deprecation-reporter.js";
@@ -15,10 +16,24 @@ import type { Logger } from "../application/ports/logger.js";
  * composition root are where the process environment is read.
  */
 
-/** Colors when the terminal supports them, as the original decided. */
-export function terminalSupportsColor(): boolean {
-  const stdout = supportsColor.stdout;
-  return Boolean(stdout) && stdout !== false && stdout.hasBasic !== false;
+/** The output streams of the process, which can each be a terminal or redirected. */
+export type TerminalStream = "stdout" | "stderr";
+
+/** The color support of each stream, as `supports-color` detects it. */
+export type StreamColorSupport = Readonly<Record<TerminalStream, ColorInfo>>;
+
+/**
+ * Whether `stream` shows colors. Each stream is asked for itself: with stdout on a terminal and
+ * stderr redirected to a log, the log gets no escape sequences.
+ */
+export function streamSupportsColor(stream: TerminalStream, support: StreamColorSupport): boolean {
+  const info = support[stream];
+  return info !== false && info.hasBasic;
+}
+
+/** Colors when the terminal of `stream` supports them, as the original decided. */
+export function terminalSupportsColor(stream: TerminalStream): boolean {
+  return streamSupportsColor(stream, supportsColor);
 }
 
 /**
@@ -34,14 +49,22 @@ const STDERR_SINK: TerminalSink = {
   error: (line) => console.error(line),
 };
 
-/** The terminal logger with `DEBUG` from the environment, writing to stderr. */
-export function defaultLogger(silent: boolean): Logger {
-  return createTerminalLogger({
+/** The options of the default logger: it writes to stderr, so the colors follow stderr. */
+export function defaultLoggerOptions(
+  silent: boolean,
+  support: StreamColorSupport,
+): TerminalLoggerOptions {
+  return {
     silent,
     debugFilter: process.env.DEBUG,
-    useColors: terminalSupportsColor(),
+    useColors: streamSupportsColor("stderr", support),
     sink: STDERR_SINK,
-  });
+  };
+}
+
+/** The terminal logger with `DEBUG` from the environment, writing to stderr. */
+export function defaultLogger(silent: boolean): Logger {
+  return createTerminalLogger(defaultLoggerOptions(silent, supportsColor));
 }
 
 /** Deprecations as Node.js `DeprecationWarning`s, each code once per process. */

package/src/api/document-run.ts

@@ -1,5 +1,3 @@
-import path from "node:path";
-import { pathToFileURL } from "node:url";
 import type { Config as RedoclyConfig } from "@redocly/openapi-core";
 import { sourceEmptyError } from "../adapters/redocly-loader/schema-load-errors.js";
 import type { DeprecationReporter } from "../application/ports/deprecation-reporter.js";
@@ -14,7 +12,7 @@ import {
 } from "../domain/output-fixes.js";
 import { WARNING_CODES, warningText } from "../domain/warnings.js";
 import type { GeneratorOptions, OpenAPI3, SchemaSource } from "../types.js";
-import { processCwd } from "./default-ports.js";
+import { sourceCwdOf } from "./cwd-option.js";
 import { warnDiscriminatorValueConflicts } from "./discriminator-conflict-warnings.js";
 import { findDiscriminators } from "./discriminator-scan.js";
 import { resolveDocumentRef } from "./document-refs.js";
@@ -56,19 +54,6 @@ type ContextFlags = Omit<
   | "fix"
 >;
 
-/**
- * The directory that relative `$ref`s of an inline source resolve against, as a URL that ends in
- * a slash. A path is resolved and encoded (`#`, `%`, spaces); a URL without the slash gets one.
- */
-function sourceCwd(options: GeneratorOptions): URL {
-  const { cwd } = options;
-  if (cwd instanceof URL) {
-    return cwd.pathname.endsWith("/") ? cwd : new URL(`${cwd.pathname}/`, cwd);
-  }
-  const directory = path.resolve(cwd === undefined ? processCwd() : cwd.toString());
-  return pathToFileURL(path.join(directory, path.sep));
-}
-
 function callbackOptions(options: GeneratorOptions) {
   return {
     irCallbacks: options.irCallbacks === true,
@@ -146,7 +131,7 @@ export async function createDocumentRun(
   const { logger } = ports;
   const fix = outputFixesOf(options, logger);
   const silent = options.silent ?? false;
-  const cwd = sourceCwd(options);
+  const cwd = sourceCwdOf(options);
   const { document: schema, localFiles } = await ports.loader.load({
     source,
     cwd,

package/src/api/legacy-utils.ts

@@ -15,7 +15,7 @@ import { type ResolveRefOptions, resolveDocumentRef, walkDocument } from "./docu
 
 // The exported `c` is the shared ansi-colors instance, switched off at import when the terminal has
 // no colors, as the original did. The generator's own logger uses a separate instance.
-if (!terminalSupportsColor()) {
+if (!terminalSupportsColor("stdout")) {
   colors.enabled = false;
 }