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

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

@@ -109,12 +109,40 @@ 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. */
   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;
+  /** Where the final URL of each redirected document is recorded. */
+  readonly redirects: RedirectedUrls;
 }
 
 /**
@@ -130,18 +158,20 @@ 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);
       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);
@@ -190,8 +220,11 @@ 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;
+  readonly redirects: RedirectedUrls;
 }
 
 /**
@@ -216,6 +249,8 @@ export function resolveConfigWithAccess(
   const checked = fetchWithCheckedRedirects(base, {
     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/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") {

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 { 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;
@@ -84,19 +90,19 @@ 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 = redactUrlSecrets(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(` ⚠  ${redactUrlSecrets(message)}`));
+      this.#options.sink.warn(this.#palette.yellow(` ⚠  ${shownText(message)}`));
     }
   }
 
   error(message: string): void {
     if (!this.#options.silent) {
-      this.#options.sink.error(this.#palette.red(` ✘  ${redactUrlSecrets(message)}`));
+      this.#options.sink.error(this.#palette.red(` ✘  ${shownText(message)}`));
     }
   }
 }

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-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,8 @@
-import path from "node:path";
-import { fileURLToPath, 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,
@@ -14,11 +12,12 @@ 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";
 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";
 
@@ -55,32 +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));
-}
-
-/** 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,
@@ -126,7 +99,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 +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;
 }
 

package/src/api/openapi-ts.ts

@@ -1,7 +1,8 @@
 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";
+import type { GeneratorOptions, OpenAPITSOptions, SchemaSource } from "../types.js";
 import {
   DEFAULT_REMOTE_DOCUMENT_LIMITS,
   defaultDeprecationReporter,
@@ -52,10 +53,12 @@ export async function generateDeclarations(
 
 /**
  * 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,
@@ -75,6 +78,19 @@ export async function defaultGeneratorPorts(options: GeneratorOptions): Promise<
  *   - URL: URL to a YAML or JSON file (local or remote)
  *   - Readable: Readable stream of YAML or JSON
  */
+export default function openapiTS(
+  source: SchemaSource,
+  options?: OpenAPITSOptions,
+): Promise<IrDeclaration[]>;
+// The options without `irCallbacks` get their own signature: TypeScript does not pick a member of
+// `GeneratorOptions | undefined` (an optional parameter) by a key that the object leaves out, so
+// inline callbacks had implicit `any` parameters (TS7006). `irCallbacks: true` picks the member
+// here. This signature is last, so `Parameters<typeof openapiTS>` reads it.
+/** Convert an OpenAPI schema to IR declarations, with either form of the options. */
+export default function openapiTS(
+  source: SchemaSource,
+  options?: GeneratorOptions,
+): Promise<IrDeclaration[]>;
 export default async function openapiTS(
   source: SchemaSource,
   options: GeneratorOptions = {},

package/src/api/option-errors.ts

@@ -0,0 +1,22 @@
+import { ERROR_CODES, OpenAPITypesafeError } from "../domain/errors.js";
+
+/** The `OPTION_INVALID` errors of the Node API's options, checked before anything loads. */
+
+/** What a value is, for the error; a URL is named by its protocol only, as it may hold secrets. */
+export 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}`;
+}
+
+export 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 },
+  });
+}

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

@@ -0,0 +1,69 @@
+import path from "node:path";
+import { fileURLToPath, pathToFileURL } from "node:url";
+import type { RefAccess } from "../application/ports/schema-loader.js";
+import { hasUrlScheme } from "../domain/location-text.js";
+import type { GeneratorOptions } from "../types.js";
+import { kindOf, optionInvalid } from "./option-errors.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:";
+
+const LOCAL_ROOT_EXPECTED = "a directory path or a file: URL";
+const RELATIVE_ROOT_EXPECTED = "an absolute path or a file: URL when cwd is no 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. A
+ * relative path needs a local cwd: with an `http:` cwd it names no local directory.
+ */
+function localRootUrlOf(value: string, cwd: URL): URL | undefined {
+  if (hasUrlScheme(value)) {
+    return URL.parse(value, cwd.href) ?? undefined;
+  }
+  if (path.isAbsolute(value)) {
+    return pathToFileURL(value);
+  }
+  if (cwd.protocol !== FILE_PROTOCOL) {
+    throw optionInvalid(
+      "localRefRoot",
+      RELATIVE_ROOT_EXPECTED,
+      `a relative path, and cwd is ${kindOf(cwd)}`,
+    );
+  }
+  return pathToFileURL(path.resolve(fileURLToPath(cwd), value));
+}
+
+/** 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) }),
+  };
+}