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

package/src/adapters/terminal-logger/terminal-logger.ts

@@ -1,13 +1,19 @@
 import colors from "ansi-colors";
 import type { DebugGroup, Logger } from "../../application/ports/logger.js";
-import { redactUrlCredentials } from "../../domain/url-credentials.js";
+import { terminalSafeText } from "../../domain/terminal-text.js";
+import { redactUrlSecrets } from "../../domain/url-secrets.js";
 
 /**
  * The Logger port on a terminal, with the original output format: ` ⚠  ` warnings, ` ✘  `
  * errors, and `openapi-ts:<group>` debug lines filtered by `DEBUG` (ENGINEERING_PLAN 4.5). No
- * line shows the user info of a URL.
+ * line shows the secrets of a URL, and each message prints as one line: a message quotes the
+ * document, whose control characters could forge CI commands (terminal-text.ts).
  */
 
+function shownText(message: string): string {
+  return terminalSafeText(redactUrlSecrets(message));
+}
+
 /** Where the lines go: `console` in production, a recording sink in tests. */
 export interface TerminalSink {
   debug(line: string): void;
@@ -16,7 +22,10 @@ export interface TerminalSink {
 }
 
 export interface TerminalLoggerOptions {
-  /** Drop warnings (errors and debug lines are still written). */
+  /**
+   * Drop warnings and error lines; debug lines, which `DEBUG` asks for, are still written. The
+   * error lines are the problems of a document that fails to load, which the thrown error lists.
+   */
   readonly silent: boolean;
   /** The value of `DEBUG`: `*`, `openapi-ts:*` or `openapi-ts:<group>` turn debug lines on. */
   readonly debugFilter: string | undefined;
@@ -81,18 +90,20 @@ class TerminalLogger implements Logger {
     // The original wrote no space without a duration (`openapi-ts:lintIgnored …`).
     const time =
       durationMs === undefined ? " " : this.#palette.green(` ${formatDuration(durationMs)} `);
-    const text = redactUrlCredentials(message);
+    const text = shownText(message);
     this.#options.sink.debug(`  ${this.#palette.bold(name)}${time}${text}`);
   }
 
   warn(message: string): void {
     if (!this.#options.silent) {
-      this.#options.sink.warn(this.#palette.yellow(` ⚠  ${redactUrlCredentials(message)}`));
+      this.#options.sink.warn(this.#palette.yellow(` ⚠  ${shownText(message)}`));
     }
   }
 
   error(message: string): void {
-    this.#options.sink.error(this.#palette.red(` ✘  ${redactUrlCredentials(message)}`));
+    if (!this.#options.silent) {
+      this.#options.sink.error(this.#palette.red(` ✘  ${shownText(message)}`));
+    }
   }
 }
 

package/src/api/default-ports.ts

@@ -3,7 +3,10 @@ import { createConfig, type Config as RedoclyConfig } from "@redocly/openapi-cor
 import supportsColor from "supports-color";
 import { createNodeDeprecationReporter } from "../adapters/node-deprecations/node-deprecations.js";
 import type { RemoteDocumentLimits } from "../adapters/redocly-loader/remote-fetch.js";
-import { createTerminalLogger } from "../adapters/terminal-logger/terminal-logger.js";
+import {
+  createTerminalLogger,
+  type TerminalSink,
+} from "../adapters/terminal-logger/terminal-logger.js";
 import type { DeprecationReporter } from "../application/ports/deprecation-reporter.js";
 import type { Logger } from "../application/ports/logger.js";
 
@@ -18,13 +21,26 @@ export function terminalSupportsColor(): boolean {
   return Boolean(stdout) && stdout !== false && stdout.hasBasic !== false;
 }
 
-/** The terminal logger with `DEBUG` from the environment, writing to the console. */
+/**
+ * Every line of the logger goes to stderr: the CLI writes the types to stdout, and `console.debug`
+ * writes there too, so debug lines would end up inside the generated file.
+ */
+const STDERR_SINK: TerminalSink = {
+  // biome-ignore lint/suspicious/noConsole: the terminal logger's own channel
+  debug: (line) => console.error(line),
+  // biome-ignore lint/suspicious/noConsole: the terminal logger's own channel
+  warn: (line) => console.warn(line),
+  // biome-ignore lint/suspicious/noConsole: the terminal logger's own channel
+  error: (line) => console.error(line),
+};
+
+/** The terminal logger with `DEBUG` from the environment, writing to stderr. */
 export function defaultLogger(silent: boolean): Logger {
   return createTerminalLogger({
     silent,
     debugFilter: process.env.DEBUG,
     useColors: terminalSupportsColor(),
-    sink: console,
+    sink: STDERR_SINK,
   });
 }
 
@@ -40,14 +56,27 @@ export function defaultDeprecationReporter(): DeprecationReporter {
  */
 export const REMOTE_REF_TIMEOUT_MS = 60_000;
 
+const MEBIBYTE = 1024 * 1024;
+
 /**
- * Bounds on the remote documents of one run (ADR-033). Large split documents have a few thousand
+ * Bounds on the remote documents of one schema (ADR-033). Large split documents have a few thousand
  * files, so 10,000 leaves room and still ends an endless fan-out. 16 parallel fetches keep a
  * multi-file document fast without exhausting local ports.
+ *
+ * The size limits count decoded bytes and parsed nodes (threat model T2, ADR-033 decision 6).
+ * The largest document of the 1,820-entry compatibility corpus is Microsoft Graph beta: 71 MiB,
+ * 2.65 million nodes (keys and values), 1.6 GB peak memory when loaded from a URL. A remote body
+ * took about 7 bytes of memory per byte of text and 110 per node in our measurements, so 128 MiB
+ * per document (1.8 times Graph beta), 256 MiB per schema (a split document may be twice as
+ * large) and 8 million nodes per schema (3 times Graph beta) let crafted documents finish within
+ * a heap of 2 GB; with the default heap of 4 GB they peak at about 1.2 to 2.3 GB.
  */
 export const DEFAULT_REMOTE_DOCUMENT_LIMITS: RemoteDocumentLimits = {
   maxDocuments: 10_000,
   maxParallelFetches: 16,
+  maxDocumentBytes: 128 * MEBIBYTE,
+  maxTotalBytes: 256 * MEBIBYTE,
+  maxNodes: 8_000_000,
 };
 
 /** The working directory of the process: the default `cwd` of an inline source. */

package/src/api/discriminator-enum-parent.ts

@@ -1,4 +1,4 @@
-import { createRef, parseRefPointer } from "../domain/openapi/json-pointer.js";
+import { appendPointer, parseRefPointer, ROOT_POINTER } from "../domain/openapi/json-pointer.js";
 import type { SchemaObject } from "../types.js";
 import type { EnumPatch } from "./discriminator-enum.js";
 
@@ -31,7 +31,7 @@ const ROOT_SEGMENTS = 3;
 function typedAt(ref: string): string {
   const segments = parseRefPointer(ref);
   const nested = segments.slice(ROOT_SEGMENTS).filter((segment) => segment !== PROPERTIES_KEYWORD);
-  return createRef([...segments.slice(0, ROOT_SEGMENTS), ...nested]);
+  return appendPointer(ROOT_POINTER, [...segments.slice(0, ROOT_SEGMENTS), ...nested]);
 }
 
 function isSchemaObject(value: unknown): value is SchemaObject {
@@ -41,7 +41,7 @@ function isSchemaObject(value: unknown): value is SchemaObject {
 /** The property `name` of a schema object typed at `ref`. */
 function ownProperty(item: SchemaObject, ref: string, name: string): DeclaredProperty | undefined {
   const property = ("properties" in item ? item.properties : undefined)?.[name];
-  return property === undefined ? undefined : { property, path: createRef([ref, name]) };
+  return property === undefined ? undefined : { property, path: appendPointer(ref, [name]) };
 }
 
 /** The property `name` of the schema at `ref`, its own or from an `allOf` item, depth first. */

package/src/api/discriminator-other-owners.ts

@@ -1,3 +1,5 @@
+import { appendAll } from "../domain/append-all.js";
+import { canonicalRef } from "../domain/openapi/json-pointer.js";
 import type { DiscriminatorObject, ReferenceObject, SchemaObject } from "../types.js";
 import type { EnumPatch } from "./discriminator-enum.js";
 import { enumKey, patchDiscriminatorEnum, type ScanState } from "./discriminator-patch.js";
@@ -22,7 +24,7 @@ function allOfRefs(state: ScanState, ref: string): string[] {
   const schema = resolveDocumentRef<SchemaObject>(state.schema, ref, { silent, logger });
   const items = (schema?.allOf ?? []) as (SchemaObject | ReferenceObject)[];
   return items.flatMap((item) =>
-    "$ref" in item && typeof item.$ref === "string" ? [item.$ref] : [],
+    "$ref" in item && typeof item.$ref === "string" ? [canonicalRef(item.$ref)] : [],
   );
 }
 
@@ -45,7 +47,7 @@ function otherOwners(state: ScanState, parentRef: string): OtherOwner[] {
     if (discriminator && name !== undefined && name !== own && !found.has(name)) {
       found.set(name, { discriminator, ownerRef: ref });
     }
-    queue.push(...allOfRefs(state, ref));
+    appendAll(queue, allOfRefs(state, ref));
   }
   return [...found.values()];
 }
@@ -75,7 +77,7 @@ export function inheritOtherOwners(state: ScanState, parentRef: string, ref: str
     }
     recordOtherProperty(state, ref, discriminator.propertyName);
     const mapped = Object.entries(discriminator.mapping ?? {})
-      .filter(([, target]) => target === ref)
+      .filter(([, target]) => canonicalRef(target) === ref)
       .map(([value]) => value);
     const name = ref.slice(ref.lastIndexOf("/") + 1);
     const patch: EnumPatch = { ref, values: mapped, discriminator, discriminatorRef: ownerRef };

package/src/api/discriminator-patch.ts

@@ -1,4 +1,5 @@
 import type { Logger } from "../application/ports/logger.js";
+import { appendAll } from "../domain/append-all.js";
 import { FIX, type OutputFix } from "../domain/output-fixes.js";
 import { WARNING_CODES, warningText } from "../domain/warnings.js";
 import type { DiscriminatorObject, OpenAPI3, SchemaObject } from "../types.js";
@@ -104,7 +105,10 @@ function mergeIntoPatchedEnum(state: ScanState, key: string, values: readonly st
     return false;
   }
   const merged = patched.enum as unknown[];
-  merged.push(...values.filter((value) => !merged.includes(value)));
+  appendAll(
+    merged,
+    values.filter((value) => !merged.includes(value)),
+  );
   return true;
 }
 

package/src/api/discriminator-scan.ts

@@ -1,5 +1,6 @@
 import type { Logger } from "../application/ports/logger.js";
 import { isUnionMember, unionAt } from "../domain/openapi/discriminated-union.js";
+import { appendPointer, canonicalRef, ROOT_POINTER } from "../domain/openapi/json-pointer.js";
 import { FIX } from "../domain/output-fixes.js";
 import type {
   DiscriminatorObject,
@@ -22,7 +23,6 @@ import {
   type ScanState,
 } from "./discriminator-patch.js";
 import { resolveDocumentRef, walkDocument } from "./document-refs.js";
-import { createRef } from "./legacy-utils.js";
 
 /**
  * The inherited discriminator pre-pass. It finds every discriminator in the bundled document and
@@ -39,9 +39,11 @@ function inferredMapping(oneOf: (SchemaObject | ReferenceObject)[]): Discriminat
     if (!("$ref" in item)) {
       continue;
     }
+    // The value is the name as the `$ref` writes it, as in the original.
     const value = item.$ref.split("/").pop();
+    const ref = canonicalRef(item.$ref);
     if (value) {
-      mapping[item.$ref] = { ...mapping[item.$ref], inferred: value };
+      mapping[ref] = { ...mapping[ref], inferred: value };
     }
   }
   return mapping;
@@ -52,10 +54,11 @@ function addDefinedMapping(
   mapping: DiscriminatorMapping,
   defined: Readonly<Record<string, string>>,
 ): void {
-  for (const [mappedValue, mappedRef] of Object.entries(defined)) {
-    if (!mappedRef) {
+  for (const [mappedValue, target] of Object.entries(defined)) {
+    if (!target) {
       continue;
     }
+    const mappedRef = canonicalRef(target);
     if (!mapping[mappedRef]?.defined) {
       mapping[mappedRef] = { defined: [] };
     }
@@ -94,7 +97,7 @@ function collectDiscriminator(
   if (!discriminator?.propertyName) {
     return;
   }
-  const discriminatorRef = createRef(path);
+  const discriminatorRef = appendPointer(ROOT_POINTER, path);
   state.objects[discriminatorRef] = discriminator;
   state.owners.add(discriminatorRef);
   if (!Array.isArray(value.oneOf)) {
@@ -110,7 +113,7 @@ function collectDiscriminator(
 /** The mapping keys of `discriminator` that point at `ref`. */
 function valuesMappedTo(discriminator: DiscriminatorObject, ref: string): string[] {
   return Object.entries(discriminator.mapping ?? {})
-    .filter(([, mappedRef]) => mappedRef === ref)
+    .filter(([, mappedRef]) => canonicalRef(mappedRef) === ref)
     .map(([mappedValue]) => mappedValue);
 }
 
@@ -184,12 +187,17 @@ function inheritDiscriminators(
   }
   for (const item of value.allOf as (SchemaObject | ReferenceObject)[]) {
     if ("$ref" in item) {
-      if (!inheritFromRef(state, item.$ref, createRef(path))) {
+      if (!inheritFromRef(state, canonicalRef(item.$ref), appendPointer(ROOT_POINTER, path))) {
         return;
       }
     } else if (item.discriminator?.propertyName) {
       // The inline item is typed at the schema's own location.
-      recordInherited(state, createRef(path), item.discriminator, createRef(path));
+      recordInherited(
+        state,
+        appendPointer(ROOT_POINTER, path),
+        item.discriminator,
+        appendPointer(ROOT_POINTER, path),
+      );
     }
   }
 }

package/src/api/document-refs.ts

@@ -16,6 +16,34 @@ function isObject(value: unknown): value is Record<string, unknown> {
   return typeof value === "object" && value !== null;
 }
 
+/**
+ * The child of a node under a pointer key. A pointer may pass through a `$ref`
+ * (`#/components/schemas/Wrap/properties/o/properties/v`, where `o` is a `$ref`): a key the node
+ * does not have is read from the node's target, as the generated types index it (ADR-026). A key
+ * the node has is read from it, so a pointer to a sibling of a `$ref` (OpenAPI 3.1) stays as
+ * written.
+ */
+function childOf(
+  schema: unknown,
+  node: unknown,
+  key: string,
+  options: ResolveRefOptions & { logger: Logger },
+): unknown {
+  if (!isObject(node)) {
+    return undefined;
+  }
+  const { visited = [] } = options;
+  const target = node.$ref;
+  if (node[key] || typeof target !== "string" || visited.includes(target)) {
+    return node[key];
+  }
+  const resolved = resolveDocumentRef(schema, target, {
+    ...options,
+    visited: [...visited, target],
+  });
+  return isObject(resolved) ? resolved[key] : undefined;
+}
+
 /** Resolve a `$ref` in a document; warns and returns undefined when it cannot. */
 export function resolveDocumentRef<T>(
   schema: unknown,
@@ -30,7 +58,7 @@ export function resolveDocumentRef<T>(
   }
   let node: unknown = schema;
   for (const key of pointer) {
-    const child = isObject(node) ? node[key] : undefined;
+    const child = childOf(schema, node, key, { ...options, logger });
     if (!child) {
       logger.warn(warningText(`Could not resolve $ref "${$ref}"`, WARNING_CODES.REF_NOT_FOUND));
       return undefined;

package/src/api/document-run.ts

@@ -1,10 +1,10 @@
 import path from "node:path";
-import { fileURLToPath, pathToFileURL } from "node:url";
+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";
 import type { Logger } from "../application/ports/logger.js";
-import type { RefAccess, SchemaLoader } from "../application/ports/schema-loader.js";
+import type { SchemaLoader } from "../application/ports/schema-loader.js";
 import { withStackOverflowReported } from "../application/stack-overflow.js";
 import {
   ineffectiveFixNotices,
@@ -19,6 +19,7 @@ import { warnDiscriminatorValueConflicts } from "./discriminator-conflict-warnin
 import { findDiscriminators } from "./discriminator-scan.js";
 import { resolveDocumentRef } from "./document-refs.js";
 import { warnIdenticalPathTemplates } from "./path-template-warnings.js";
+import { refAccessOf } from "./ref-limit-options.js";
 import type { RunContext } from "./run-context.js";
 import { warnUnsupportedFeatures } from "./unsupported-feature-warnings.js";
 
@@ -34,9 +35,10 @@ export interface GeneratorPorts {
   readonly now: () => number;
 }
 
-/** A validated, bundled document and the context of one generator run. */
+/** A validated, bundled document, the local files it was read from, and the run's context. */
 export interface DocumentRun {
   readonly schema: OpenAPI3;
+  readonly localFiles: readonly URL[];
   readonly ctx: RunContext;
 }
 
@@ -67,19 +69,6 @@ function sourceCwd(options: GeneratorOptions): URL {
   return pathToFileURL(path.join(directory, path.sep));
 }
 
-/** The `$ref` limits of the options; a relative local root resolves against the cwd. */
-function refAccessOf(options: GeneratorOptions, cwd: URL): RefAccess {
-  const { localRefRoot, remoteRefHosts } = options;
-  const localRoot =
-    typeof localRefRoot === "string"
-      ? pathToFileURL(path.resolve(fileURLToPath(cwd), localRefRoot))
-      : localRefRoot;
-  return {
-    ...(localRoot === undefined ? {} : { localRoot }),
-    ...(remoteRefHosts === undefined ? {} : { remoteHosts: remoteRefHosts }),
-  };
-}
-
 function callbackOptions(options: GeneratorOptions) {
   return {
     irCallbacks: options.irCallbacks === true,
@@ -125,7 +114,9 @@ function contextFlags(options: GeneratorOptions): ContextFlags {
  */
 function outputFixesOf(options: GeneratorOptions, logger: Logger): readonly OutputFix[] {
   const names = outputFixNamesOf(options.fix ?? []);
-  for (const notice of ineffectiveFixNotices(names, (option) => options[option] === true)) {
+  // The options with their defaults: `defaultNonNullable` is on unless set to false.
+  const flags = contextFlags(options);
+  for (const notice of ineffectiveFixNotices(names, (option) => flags[option])) {
     logger.warn(warningText(notice, WARNING_CODES.FIX_NEEDS_OPTION));
   }
   return [...resolveOutputFixes(names)];
@@ -156,7 +147,7 @@ export async function createDocumentRun(
   const fix = outputFixesOf(options, logger);
   const silent = options.silent ?? false;
   const cwd = sourceCwd(options);
-  const schema = await ports.loader.load({
+  const { document: schema, localFiles } = await ports.loader.load({
     source,
     cwd,
     shouldLint: options.lint ?? true,
@@ -181,5 +172,5 @@ export async function createDocumentRun(
     logger,
     deprecations: ports.deprecations,
   };
-  return { schema, ctx };
+  return { schema, localFiles, ctx };
 }

package/src/api/legacy-utils.ts

@@ -36,7 +36,11 @@ export function createDiscriminatorProperty(
   return discriminatorProperty(discriminator, path, readonly);
 }
 
-/** Create a $ref pointer (even from other $refs) */
+/**
+ * Create a $ref pointer (even from other $refs). A part that contains `#/` is read as a `$ref`
+ * and contributes its decoded segments, so it throws URIError for a malformed percent escape; any
+ * other part is one segment. To append raw document keys, escape each one instead.
+ */
 export function createRef(parts: (number | string | undefined | null)[]): string {
   return createDomainRef(parts);
 }

package/src/api/openapi-ts.ts

@@ -1,4 +1,5 @@
 import { createRedoclySchemaLoader } from "../adapters/redocly-loader/redocly-schema-loader.js";
+import type { Logger } from "../application/ports/logger.js";
 import { withStackOverflowReported } from "../application/stack-overflow.js";
 import type { IrDeclaration } from "../domain/ir/nodes.js";
 import type { GeneratorOptions, SchemaSource } from "../types.js";
@@ -18,29 +19,46 @@ import transformSchema from "./transform-schema.js";
  * `generateDeclarations` runs with any ports, which is how the CLI calls it.
  */
 
+/** The declarations of one document, and the local files it was read from. */
+export interface GeneratedDocument {
+  readonly declarations: IrDeclaration[];
+  readonly localFiles: readonly URL[];
+}
+
 /** Load, validate and bundle the source, then transform it into IR declarations. */
-export async function generateDeclarations(
+export async function generateDocument(
   source: SchemaSource,
   options: GeneratorOptions,
   ports: GeneratorPorts,
-): Promise<IrDeclaration[]> {
-  const { schema, ctx } = await createDocumentRun(source, options, ports);
+): Promise<GeneratedDocument> {
+  const { schema, localFiles, ctx } = await createDocumentRun(source, options, ports);
   const startedAt = ports.now();
-  const result = withStackOverflowReported("transform", () => transformSchema(schema, ctx));
+  const declarations = withStackOverflowReported("transform", () => transformSchema(schema, ctx));
   ports.logger.debug(
     "Completed AST transformation for entire document",
     "ts",
     ports.now() - startedAt,
   );
-  return result;
+  return { declarations, localFiles };
+}
+
+/** As `generateDocument`, the declarations only. */
+export async function generateDeclarations(
+  source: SchemaSource,
+  options: GeneratorOptions,
+  ports: GeneratorPorts,
+): Promise<IrDeclaration[]> {
+  return (await generateDocument(source, options, ports)).declarations;
 }
 
 /**
  * The default ports: the terminal logger, Node.js deprecation warnings, the given or default
- * Redocly config, Redocly loading.
+ * Redocly config, Redocly loading. A given `logger` takes every line, the loader's included.
  */
-export async function defaultGeneratorPorts(options: GeneratorOptions): Promise<GeneratorPorts> {
-  const logger = defaultLogger(options.silent ?? false);
+export async function defaultGeneratorPorts(
+  options: GeneratorOptions,
+  logger: Logger = defaultLogger(options.silent ?? false),
+): Promise<GeneratorPorts> {
   const redoc = options.redocly ?? (await defaultRedoclyConfig());
   const loader = createRedoclySchemaLoader({
     redoc,

package/src/api/ref-limit-options.ts

@@ -0,0 +1,76 @@
+import path from "node:path";
+import { fileURLToPath, pathToFileURL } from "node:url";
+import type { RefAccess } from "../application/ports/schema-loader.js";
+import { ERROR_CODES, OpenAPITypesafeError } from "../domain/errors.js";
+import { hasUrlScheme } from "../domain/location-text.js";
+import type { GeneratorOptions } from "../types.js";
+
+/**
+ * The `$ref` limits of the options (threat model R1, R2, ADR-017), checked before anything loads.
+ * A value of another type from JavaScript (`remoteRefHosts: "a.com"`, `localRefRoot: new
+ * URL("https://…")`) used to fail later as an error of the document.
+ */
+
+const FILE_PROTOCOL = "file:";
+
+/** What a value is, for the error; a URL is named by its protocol only, as it may hold secrets. */
+function kindOf(value: unknown): string {
+  if (value instanceof URL) {
+    return `a ${value.protocol} URL`;
+  }
+  if (Array.isArray(value)) {
+    return "a list";
+  }
+  return value === null ? "null" : `a ${typeof value}`;
+}
+
+function optionInvalid(option: string, expected: string, got: string): OpenAPITypesafeError {
+  return new OpenAPITypesafeError({
+    code: ERROR_CODES.OPTION_INVALID,
+    message: `The ${option} option must be ${expected}; got ${got}.`,
+    details: { option },
+  });
+}
+
+const LOCAL_ROOT_EXPECTED = "a directory path or a file: URL";
+
+/**
+ * A string as the CLI reads `--local-ref-root`: a URL when it has a scheme (`file:///specs/`),
+ * else a path that resolves against the cwd. Undefined when it does not parse as a URL.
+ */
+function localRootUrlOf(value: string, cwd: URL): URL | undefined {
+  if (!hasUrlScheme(value)) {
+    return pathToFileURL(path.resolve(fileURLToPath(cwd), value));
+  }
+  return URL.parse(value, cwd.href) ?? undefined;
+}
+
+/** The local root as a `file:` URL; the option is set, so it is not undefined. */
+function localRootOf(value: unknown, cwd: URL): URL {
+  const root = typeof value === "string" ? localRootUrlOf(value, cwd) : value;
+  if (root instanceof URL && root.protocol === FILE_PROTOCOL) {
+    return root;
+  }
+  const got = root === undefined ? "a string that is no valid URL" : kindOf(root);
+  throw optionInvalid("localRefRoot", LOCAL_ROOT_EXPECTED, got);
+}
+
+function remoteHostsOf(value: unknown): readonly string[] {
+  if (!Array.isArray(value)) {
+    throw optionInvalid("remoteRefHosts", "a list of hosts", kindOf(value));
+  }
+  const other = value.find((entry) => typeof entry !== "string");
+  if (other !== undefined) {
+    throw optionInvalid("remoteRefHosts", "a list of hosts", `a list with ${kindOf(other)}`);
+  }
+  return value;
+}
+
+/** The limits of the options; fails with `OPTION_INVALID` for a value of another type. */
+export function refAccessOf(options: GeneratorOptions, cwd: URL): RefAccess {
+  const { localRefRoot, remoteRefHosts } = options;
+  return {
+    ...(localRefRoot === undefined ? {} : { localRoot: localRootOf(localRefRoot, cwd) }),
+    ...(remoteRefHosts === undefined ? {} : { remoteHosts: remoteHostsOf(remoteRefHosts) }),
+  };
+}

package/src/api/run-context.ts

@@ -1,6 +1,7 @@
 import type { DeprecationReporter } from "../application/ports/deprecation-reporter.js";
 import type { Logger } from "../application/ports/logger.js";
 import type { DocumentFooter } from "../application/transform/transform-context.js";
+import type { SchemaDialect } from "../domain/openapi/schema-dialect.js";
 import type { GlobalContext, LegacyCallbackName, SchemaObject } from "../types.js";
 
 /**
@@ -26,6 +27,8 @@ export interface RunContext extends GlobalContext {
      */
     readonly otherProperties?: Readonly<Record<string, readonly string[]>>;
   };
+  /** The schema dialect of the run's document; without it, OpenAPI 3.0 (`schemaDialectOf`). */
+  schemaDialect?: SchemaDialect;
   /** Footer state of this run (enum registry and enum naming), created on first use. */
   runFooter?: DocumentFooter;
   /** The deprecated callback forms this run has warned about (once each). */