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

package/src/cli/cli-dependencies.ts

@@ -1,5 +1,11 @@
 import type { Readable } from "node:stream";
-import type { FileReader, FileWriter } from "../application/ports/file-system.js";
+import type {
+  DirectoryCheck,
+  FileClaims,
+  FileIdentity,
+  FileReader,
+  FileWriter,
+} from "../application/ports/file-system.js";
 import type { Logger } from "../application/ports/logger.js";
 import type { RedoclyConfigSource } from "../application/ports/redocly-config-source.js";
 import type { GeneratorOptions, SchemaSource } from "../types.js";
@@ -19,8 +25,19 @@ export interface TextStyle {
   dim(text: string): string;
 }
 
-/** Generate the printed declarations, with the comment header, for one schema. */
-export type GenerateTypes = (source: SchemaSource, options: GeneratorOptions) => Promise<string>;
+/** The printed declarations of one schema, and the local files they were generated from. */
+export interface GeneratedTypes {
+  /** The declarations, with the comment header. */
+  readonly contents: string;
+  /** The schema, when it is a local file, and every local file its `$ref`s loaded. */
+  readonly localFiles: readonly URL[];
+}
+
+/** Generate the types of one schema. */
+export type GenerateTypes = (
+  source: SchemaSource,
+  options: GeneratorOptions,
+) => Promise<GeneratedTypes>;
 
 export interface CliDependencies {
   /** The working directory, as a directory URL (with a trailing slash). */
@@ -38,7 +55,7 @@ export interface CliDependencies {
    * input with no prompt, which looks like a hang (upstream #1905).
    */
   readonly isStdinTerminal: () => boolean;
-  readonly files: FileReader & FileWriter;
+  readonly files: FileReader & FileWriter & FileIdentity & DirectoryCheck & FileClaims;
   readonly redoclyConfigs: RedoclyConfigSource;
   readonly generate: GenerateTypes;
   /** A monotonic time in milliseconds, for the time printed after each output. */

package/src/cli/cli-errors.ts

@@ -68,9 +68,24 @@ function parseFailedMessage(error: OpenAPITypesafeError): string {
   );
 }
 
+/**
+ * Text piped into stdin that is only a YAML string (`echo api.yaml | openapi-typesafe`) gets the
+ * CLI's advice, not the Node API's (`openapiTS(pathToFileURL(path))`).
+ */
+function sourceInvalidMessage(error: OpenAPITypesafeError): string {
+  const { received, text } = error.details;
+  if (received !== "stream" || typeof text !== "string") {
+    return error.message;
+  }
+  return (
+    `stdin held only the YAML string "${text}", not an OpenAPI document. To read a file, pass ` +
+    "its path or URL as the first argument: openapi-typesafe ./openapi.yaml -o ./schema.ts"
+  );
+}
+
 const CLI_ERROR_REPORTS: Readonly<Record<ErrorCode, CliErrorReport>> = {
   SCHEMA_SOURCE_EMPTY: { exitCode: EXIT_CODES.SCHEMA },
-  SCHEMA_SOURCE_INVALID: { exitCode: EXIT_CODES.SCHEMA },
+  SCHEMA_SOURCE_INVALID: { exitCode: EXIT_CODES.SCHEMA, message: sourceInvalidMessage },
   SCHEMA_LOAD_FAILED: { exitCode: EXIT_CODES.SCHEMA, message: loadFailedMessage },
   SCHEMA_PARSE_FAILED: { exitCode: EXIT_CODES.SCHEMA, message: parseFailedMessage },
   SCHEMA_VERSION_UNSUPPORTED: { exitCode: EXIT_CODES.SCHEMA },
@@ -92,6 +107,10 @@ const CLI_ERROR_REPORTS: Readonly<Record<ErrorCode, CliErrorReport>> = {
   CLI_CONFIG_OUTPUT_MISSING: { exitCode: EXIT_CODES.USAGE },
   CLI_CHECK_OUTPUT_MISSING: { exitCode: EXIT_CODES.USAGE },
   CLI_INPUT_MISSING: { exitCode: EXIT_CODES.USAGE },
+  CLI_OUTPUT_IS_INPUT: { exitCode: EXIT_CODES.USAGE },
+  CLI_OUTPUT_DUPLICATE: { exitCode: EXIT_CODES.USAGE },
+  CLI_OUTPUT_INVALID: { exitCode: EXIT_CODES.USAGE },
+  CLI_LOCATION_INVALID: { exitCode: EXIT_CODES.USAGE },
   OUTPUT_STALE: { exitCode: EXIT_CODES.OUTPUT_STALE },
   OUTPUT_READ_FAILED: { exitCode: EXIT_CODES.OUTPUT },
   OUTPUT_WRITE_FAILED: { exitCode: EXIT_CODES.OUTPUT },

package/src/cli/cli-output.ts

@@ -1,8 +1,10 @@
 import path from "node:path";
 import { fileURLToPath, pathToFileURL } from "node:url";
 import { formatDuration } from "../adapters/terminal-logger/terminal-logger.js";
+import type { RedoclyConfig } from "../application/ports/redocly-config-source.js";
+import { redactUnparsedUrl } from "../domain/url-secrets.js";
 import type { CliArguments } from "./cli-arguments.js";
-import type { CliDependencies } from "./cli-dependencies.js";
+import type { CliDependencies, GeneratedTypes } from "./cli-dependencies.js";
 import { cliError } from "./cli-errors.js";
 
 /** Writing one generated file, or checking it with `--check`, and the line printed for it. */
@@ -14,10 +16,14 @@ export interface CliRun {
   readonly startedAt: number;
 }
 
-/** A generated file: `source` names the schema and `output` is the path as the user wrote it. */
-export interface OutputFile {
+/** An output as the user wrote it: `source` names the schema, `output` is the path or URL. */
+export interface NamedOutput {
   readonly source: string;
   readonly output: string;
+}
+
+/** A generated file: an output with the location of its local file. */
+export interface OutputFile extends NamedOutput {
   readonly file: URL;
 }
 
@@ -28,18 +34,180 @@ export interface OutputFile {
 const URL_SCHEME = /^[a-z][a-z\d+.-]+:/i;
 
 /**
- * The URL of a location the user wrote: a URL as it is, else a file path, absolute or relative to
- * the directory of `base` (a directory or file URL). A path is not parsed as a URL, so `#`, `?` and
- * `%` are part of the file name.
+ * The URL of a location the user wrote: a URL, else a file path, absolute or relative to the
+ * directory of `base` (a directory or file URL). A relative `file:` URL (`file:api.yaml`) resolves
+ * against `base` too, as in openapi-typescript. A path is not parsed as a URL, so `#`, `?` and `%`
+ * are part of the file name. A location with a scheme that does not parse as a URL
+ * (`http://[::1/x`) fails with `CLI_LOCATION_INVALID`.
  */
 export function resolveLocationUrl(location: string, base: URL): URL {
   if (URL_SCHEME.test(location)) {
-    return new URL(location);
+    const url = URL.parse(location, base.href);
+    if (url === null) {
+      const shown = redactUnparsedUrl(location);
+      throw cliError("CLI_LOCATION_INVALID", `The location ${shown} is not a valid URL`);
+    }
+    return url;
   }
   const baseDirectory = fileURLToPath(new URL(".", base));
   return pathToFileURL(path.resolve(baseDirectory, location));
 }
 
+const FILE_PROTOCOL = "file:";
+
+/** Segments that name a directory: the directory itself and its parent. */
+const DIRECTORY_SEGMENTS: ReadonlySet<string> = new Set([".", ".."]);
+
+/**
+ * Whether the location names a directory as written, before resolving drops the sign: a trailing
+ * `/` (or `\\` on Windows), or a last segment `.` or `..` (`-o gen/.`, `-o a/b/..`). For a URL
+ * the parsed path tells it too, since the URL parser drops `.`, `..` and their `%2E` forms.
+ */
+function namesDirectory(location: string, file: URL): boolean {
+  const lastSegment = location
+    .split(path.sep)
+    .flatMap((part) => part.split("/"))
+    .at(-1);
+  return (
+    lastSegment === "" || DIRECTORY_SEGMENTS.has(lastSegment ?? "") || file.pathname.endsWith("/")
+  );
+}
+
+function invalidOutput(output: string, reason: string): Error {
+  return cliError("CLI_OUTPUT_INVALID", `The output ${output} ${reason}`);
+}
+
+/** The URL of the output, if it is a local file that can be written; it may not exist yet. */
+function outputUrlOf(run: CliRun, output: string, base: URL): URL {
+  const file = parseLocationUrl(output, base);
+  if (file?.protocol !== FILE_PROTOCOL) {
+    throw invalidOutput(
+      output,
+      "is not a local file. Write the types to a file path or a file: URL.",
+    );
+  }
+  if (!isLocalFile(file)) {
+    throw invalidOutput(output, "names no file on this computer. Use a file path instead.");
+  }
+  if (namesDirectory(output, file) || run.deps.files.isDirectory(file)) {
+    throw invalidOutput(output, "is a directory. Name the file to write the types to in it.");
+  }
+  return file;
+}
+
+/** A `file:` URL with a host, or with an encoded slash, names no path on this platform. */
+function isLocalFile(file: URL): boolean {
+  try {
+    fileURLToPath(file);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * The output file of `source`, as the user wrote it in `output`, relative to `base`. Fails with
+ * `CLI_OUTPUT_INVALID` before anything is generated when it is not a local file (a URL of
+ * another scheme) or is a directory (a trailing separator, a last segment `.` or `..`, or a
+ * directory on disk). Without this check, `-o dir/` and `-o dir/.` wrote a file named `dir`.
+ */
+export function outputFileOf(run: CliRun, named: NamedOutput, base: URL): OutputFile {
+  return { ...named, file: outputUrlOf(run, named.output, base) };
+}
+
+/** A file the CLI reads or writes: `name` is how an error names it, `location` where it is. */
+export interface NamedFile {
+  readonly name: string;
+  readonly location: URL;
+}
+
+/** The `files` that are the local file `output`, also through a link or in another letter case. */
+function filesAtOutput(run: CliRun, output: OutputFile, files: readonly NamedFile[]): NamedFile[] {
+  return files.filter(
+    ({ location }) =>
+      location.protocol === FILE_PROTOCOL && run.deps.files.isSameFile(location, output.file),
+  );
+}
+
+/** A location as a path relative to the working directory, as error messages name files. */
+function displayPathOf(run: CliRun, location: URL): string {
+  return path.relative(fileURLToPath(run.deps.cwd), fileURLToPath(location)) || ".";
+}
+
+/** The Redocly config file the run read, if any: no output may replace it. */
+export function redoclyConfigFiles(run: CliRun, redocly: RedoclyConfig): NamedFile[] {
+  if (!redocly.configFile) {
+    return [];
+  }
+  const location = resolveLocationUrl(redocly.configFile, run.deps.cwd);
+  return [{ name: `Redocly config ${displayPathOf(run, location)}`, location }];
+}
+
+/** The local files that `owner` (a schema or an API) was generated from, `$ref`'d ones too. */
+export function filesReadBy(run: CliRun, types: GeneratedTypes, owner: string): NamedFile[] {
+  return types.localFiles.map((location) => ({
+    name: `schema ${displayPathOf(run, location)} that ${owner} reads`,
+    location,
+  }));
+}
+
+/**
+ * Fail with `CLI_OUTPUT_IS_INPUT` when `output` is one of the `schemas` (or the Redocly config).
+ * Writing it would replace that file with the types, which upstream did without a word. The CLI
+ * checks the files it knows before generating, so nothing is loaded or written, and the files
+ * that `$ref`s loaded after generating, before anything is written.
+ */
+export function ensureOutputIsNotSchema(
+  run: CliRun,
+  output: OutputFile,
+  schemas: readonly NamedFile[],
+): void {
+  const [schema] = filesAtOutput(run, output, schemas);
+  if (schema) {
+    throw cliError(
+      "CLI_OUTPUT_IS_INPUT",
+      `The output ${output.output} is the ${schema.name}: writing the types would ` +
+        "overwrite it. Choose another output file.",
+    );
+  }
+}
+
+/**
+ * Fail with `CLI_OUTPUT_DUPLICATE` when the output of an API is also one of `otherOutputs`.
+ * Whichever write came last would win, so every API with that output fails, before anything is
+ * generated.
+ */
+export function ensureOutputIsOwn(
+  run: CliRun,
+  output: OutputFile,
+  otherOutputs: readonly NamedFile[],
+): void {
+  const clashes = filesAtOutput(run, output, otherOutputs);
+  if (clashes.length > 0) {
+    throw duplicateOutputError(
+      output,
+      clashes.map(({ name }) => name),
+    );
+  }
+}
+
+/** `CLI_OUTPUT_DUPLICATE` for `output`, which is also the output of the `others` (named). */
+export function duplicateOutputError(output: NamedOutput, others: readonly string[]): Error {
+  return cliError(
+    "CLI_OUTPUT_DUPLICATE",
+    `The output ${output.output} of API ${output.source} is also the output of ` +
+      `${others.join(", ")}: they would overwrite each other. Give each API its own output file.`,
+  );
+}
+
+/** As `resolveLocationUrl`, but undefined for a URL that does not parse instead of a throw. */
+export function parseLocationUrl(location: string, base: URL): URL | undefined {
+  if (URL_SCHEME.test(location)) {
+    return URL.parse(location, base.href) ?? undefined;
+  }
+  return resolveLocationUrl(location, base);
+}
+
 function printDone(run: CliRun, output: OutputFile): void {
   const { style, now } = run.deps;
   const target = style.green(`${output.source} → ${style.bold(output.output)}`);
@@ -65,3 +233,14 @@ export function emitOutput(run: CliRun, output: OutputFile, contents: string): v
   run.deps.files.writeText(output.file, contents);
   printDone(run, output);
 }
+
+/** Write (or `--check`) the types, unless the output is one of the files the run read. */
+export function writeOutput(
+  run: CliRun,
+  output: OutputFile,
+  types: GeneratedTypes,
+  readFiles: readonly NamedFile[],
+): void {
+  ensureOutputIsNotSchema(run, output, readFiles);
+  emitOutput(run, output, types.contents);
+}

package/src/cli/main.ts

@@ -7,7 +7,7 @@ import { createRedoclyConfigSource } from "../adapters/redocly-loader/redocly-co
 import { astToString } from "../api/ast-to-string.js";
 import { COMMENT_HEADER } from "../api/comment-header.js";
 import { defaultLogger, monotonicNow, terminalSupportsColor } from "../api/default-ports.js";
-import openapiTS from "../api/openapi-ts.js";
+import { defaultGeneratorPorts, generateDocument } from "../api/openapi-ts.js";
 import type { CliConsole, CliDependencies, GenerateTypes, TextStyle } from "./cli-dependencies.js";
 import { runCli } from "./run-cli.js";
 
@@ -36,8 +36,11 @@ function terminalStyle(): TextStyle {
 
 const STDIN_DESCRIPTOR = 0;
 
-const generateTypes: GenerateTypes = async (source, options) =>
-  `${COMMENT_HEADER}${astToString(await openapiTS(source, options))}`;
+const generateTypes: GenerateTypes = async (source, options) => {
+  const ports = await defaultGeneratorPorts(options);
+  const { declarations, localFiles } = await generateDocument(source, options, ports);
+  return { contents: `${COMMENT_HEADER}${astToString(declarations)}`, localFiles };
+};
 
 function terminalConsole(): CliConsole {
   return {

package/src/cli/redocly-apis.ts

@@ -1,19 +1,29 @@
-import { kebabCase } from "scule";
 import type { RedoclyConfig } from "../application/ports/redocly-config-source.js";
-import type { OutputFixName } from "../domain/output-fixes.js";
 import type { GeneratorOptions } from "../types.js";
 import {
   type ApiSettings,
+  apiFixNames,
+  apiFlags,
+  apiOutputOf,
   apiRefLimitOptions,
-  FIX_SETTING,
   OUTPUT_SETTING,
   unknownSettingWarnings,
 } from "./api-settings.js";
-import { GENERATOR_FLAGS, type GeneratorFlags } from "./cli-arguments.js";
+import { type GeneratedApi, writeGeneratedApis } from "./api-writes.js";
 import { cliError } from "./cli-errors.js";
-import { type CliRun, emitOutput, resolveLocationUrl } from "./cli-output.js";
+import {
+  type CliRun,
+  ensureOutputIsNotSchema,
+  ensureOutputIsOwn,
+  filesReadBy,
+  type NamedFile,
+  outputFileOf,
+  parseLocationUrl,
+  redoclyConfigFiles,
+  resolveLocationUrl,
+} from "./cli-output.js";
 import { MULTIPLE_SCHEMAS_DOCS_URL } from "./docs-links.js";
-import { fixNamesOf, fixOption } from "./fix-option.js";
+import { fixOption } from "./fix-option.js";
 import { refLimitOptions } from "./ref-limits.js";
 
 /** The `apis` of a Redocly config: each API is generated into its `x-openapi-ts.output`. */
@@ -21,16 +31,17 @@ import { refLimitOptions } from "./ref-limits.js";
 /** The key of an API's openapi-typesafe settings in `redocly.yaml`. */
 const REDOCLY_CONFIG_KEY = "x-openapi-ts";
 
+/** An API of the config as written: `root` and the settings are not checked yet. */
 interface RedoclyApi {
   readonly name: string;
-  readonly root: string;
-  readonly settings: ApiSettings | undefined;
+  readonly root: unknown;
+  readonly settings: unknown;
 }
 
 function redoclyApisOf(redocly: RedoclyConfig): RedoclyApi[] {
   return Object.entries(redocly.apis ?? {}).map(([name, api]) => {
-    const settings = (api as Record<string, unknown>)[REDOCLY_CONFIG_KEY];
-    return { name, root: api.root, settings: settings as ApiSettings | undefined };
+    const fields = api as Readonly<Record<string, unknown>>;
+    return { name, root: fields.root, settings: fields[REDOCLY_CONFIG_KEY] };
   });
 }
 
@@ -38,64 +49,158 @@ export function hasRedoclyApis(redocly: RedoclyConfig): boolean {
   return Object.keys(redocly.apis ?? {}).length > 0;
 }
 
-/** The boolean flags an API sets, in camelCase or kebab-case; they win over the CLI's flags. */
-function apiFlags(settings: ApiSettings): GeneratorFlags {
-  const flags: Partial<Record<(typeof GENERATOR_FLAGS)[number], boolean>> = {};
-  for (const name of GENERATOR_FLAGS) {
-    const value = typeof settings[name] === "boolean" ? settings[name] : settings[kebabCase(name)];
-    if (typeof value === "boolean") {
-      flags[name] = value;
-    }
-  }
-  return flags;
+/** Paths in the config are relative to the config file; without a file, to the working dir. */
+function configRootOf(redocly: RedoclyConfig, cwd: URL): URL {
+  return redocly.configFile ? resolveLocationUrl(redocly.configFile, cwd) : cwd;
 }
 
-/** The API's `fix` names; they replace the CLI's `--fix`, as its boolean settings win (ADR-021). */
-function apiFixNames(settings: ApiSettings): readonly OutputFixName[] | undefined {
-  return fixNamesOf(settings[FIX_SETTING]);
+/** An API whose root and settings are usable, and the directory its paths are relative to. */
+interface ApiTarget {
+  readonly name: string;
+  readonly root: string;
+  readonly settings: ApiSettings;
+  readonly configRoot: URL;
 }
 
-/** Paths in the config are relative to the config file; without a file, to the working dir. */
-function configRootOf(redocly: RedoclyConfig, cwd: URL): URL {
-  return redocly.configFile ? resolveLocationUrl(redocly.configFile, cwd) : cwd;
+function isSettingsMap(value: unknown): value is ApiSettings {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
 }
 
-async function generateApi(run: CliRun, redocly: RedoclyConfig, api: RedoclyApi): Promise<void> {
-  if (!api.settings?.[OUTPUT_SETTING]) {
+/**
+ * The API with its settings. Fails with `CLI_CONFIG_OUTPUT_MISSING` when they name no output, and
+ * with `CLI_CONFIG_INVALID` when they are no map or `root` is no path or URL; only this API then
+ * fails, the others are still generated.
+ */
+function apiTarget(api: RedoclyApi, configRoot: URL): ApiTarget {
+  const { name, root, settings } = api;
+  if (settings !== undefined && !isSettingsMap(settings)) {
+    throw cliError("CLI_CONFIG_INVALID", `API ${name}: \`${REDOCLY_CONFIG_KEY}\` must be a map`);
+  }
+  if (!settings?.[OUTPUT_SETTING]) {
     throw cliError(
       "CLI_CONFIG_OUTPUT_MISSING",
-      `API ${api.name} is missing an \`${REDOCLY_CONFIG_KEY}.output\` key. ` +
+      `API ${name} is missing an \`${REDOCLY_CONFIG_KEY}.output\` key. ` +
         `See ${MULTIPLE_SCHEMAS_DOCS_URL}`,
     );
   }
-  for (const warning of unknownSettingWarnings(api.name, api.settings)) {
-    run.deps.logger.warn(warning);
+  if (typeof root !== "string" || root === "") {
+    throw cliError(
+      "CLI_CONFIG_INVALID",
+      `API ${name}: \`root\` in redocly.yaml must be the path or URL of its schema`,
+    );
   }
-  const output = String(api.settings[OUTPUT_SETTING]);
-  const configRoot = configRootOf(redocly, run.deps.cwd);
-  const options: GeneratorOptions = {
+  return { name, root, settings, configRoot };
+}
+
+/** The generator options of one API: its own settings win over the CLI's flags. */
+function apiOptions(run: CliRun, redocly: RedoclyConfig, target: ApiTarget): GeneratorOptions {
+  const { name, settings, configRoot } = target;
+  return {
     ...run.args.generatorFlags,
-    ...apiFlags(api.settings),
+    ...apiFlags(name, settings),
     ...refLimitOptions(run.args, run.deps.cwd),
-    ...apiRefLimitOptions(api.name, api.settings, configRoot),
-    ...fixOption(apiFixNames(api.settings) ?? run.args.fix),
+    ...apiRefLimitOptions(name, settings, configRoot),
+    ...fixOption(apiFixNames(name, settings) ?? run.args.fix),
     redocly,
   };
-  const contents = await run.deps.generate(resolveLocationUrl(api.root, configRoot), options);
-  emitOutput(
-    run,
-    { source: api.name, output, file: resolveLocationUrl(output, configRoot) },
-    contents,
-  );
+}
+
+/** The schemas and outputs of every API of the config, keyed by API name for the outputs. */
+interface ConfigFiles {
+  readonly schemas: readonly NamedFile[];
+  readonly outputs: ReadonlyMap<string, URL>;
+}
+
+/** The outputs of the other APIs, as `ensureOutputIsOwn` names them. */
+function otherOutputs(files: ConfigFiles, apiName: string): NamedFile[] {
+  return [...files.outputs]
+    .filter(([name]) => name !== apiName)
+    .map(([name, location]) => ({ name: `API ${name}`, location }));
+}
+
+/**
+ * Generate the types of one API. Its output must not be a file the run reads before any API is
+ * loaded (the root of any API, the Redocly config) nor another API's output.
+ */
+async function generateApi(
+  run: CliRun,
+  redocly: RedoclyConfig,
+  target: ApiTarget,
+  files: ConfigFiles,
+): Promise<GeneratedApi> {
+  for (const warning of unknownSettingWarnings(target.name, target.settings)) {
+    run.deps.logger.warn(warning);
+  }
+  const output = apiOutputOf(target.name, target.settings);
+  const outputFile = outputFileOf(run, { source: target.name, output }, target.configRoot);
+  ensureOutputIsNotSchema(run, outputFile, files.schemas);
+  ensureOutputIsOwn(run, outputFile, otherOutputs(files, target.name));
+  const source = resolveLocationUrl(target.root, target.configRoot);
+  const types = await run.deps.generate(source, apiOptions(run, redocly, target));
+  return { name: target.name, outputFile, types };
 }
 
 /**
- * Generate every API of the config, concurrently. Every API is generated or checked even when
- * another fails, so `--check` reports a stale output wherever it is; the failures are returned
- * in the order of the config.
+ * The schema and the output of every API, and the config file itself. A location that is no
+ * text or no valid URL is left out: it is no file that an output could be, and its own API fails
+ * on it, not every API.
+ */
+function configFilesOf(run: CliRun, redocly: RedoclyConfig, apis: readonly RedoclyApi[]) {
+  const configRoot = configRootOf(redocly, run.deps.cwd);
+  const roots = apis.flatMap(({ name, root }) => {
+    const location = typeof root === "string" ? parseLocationUrl(root, configRoot) : undefined;
+    return location ? [{ name: `schema ${root} of API ${name}`, location }] : [];
+  });
+  const outputs = new Map<string, URL>();
+  for (const api of apis) {
+    const output = isSettingsMap(api.settings) ? api.settings[OUTPUT_SETTING] : undefined;
+    const location = typeof output === "string" ? parseLocationUrl(output, configRoot) : undefined;
+    if (location) {
+      outputs.set(api.name, location);
+    }
+  }
+  const schemas = [...roots, ...redoclyConfigFiles(run, redocly)];
+  return { configRoot, files: { schemas, outputs } satisfies ConfigFiles };
+}
+
+/** What `task` gives for each item, run one after another: the next starts when one settles. */
+async function settledInTurn<T, R>(
+  items: readonly T[],
+  task: (item: T) => Promise<R>,
+): Promise<PromiseSettledResult<R>[]> {
+  const results: PromiseSettledResult<R>[] = [];
+  for (const item of items) {
+    try {
+      results.push({ status: "fulfilled", value: await task(item) });
+    } catch (reason) {
+      results.push({ status: "rejected", reason });
+    }
+  }
+  return results;
+}
+
+/**
+ * Generate every API of the config, one after another in the order of the config, then write
+ * them. One at a time, so a run takes the memory of its largest API, not the sum of all of them,
+ * and the work of one API cannot hold up the fetches of another until their timeout ends them.
+ * Nothing is written until every API is read and every output is claimed, so no output can
+ * replace a file that another API still reads; an output that is a file any API read (a `$ref`'d
+ * schema) fails with `CLI_OUTPUT_IS_INPUT`. Every API is generated or checked even when another
+ * fails, so `--check` reports a stale output wherever it is; the failures are returned in the
+ * order of the config.
  */
 export async function generateRedoclyApis(run: CliRun, redocly: RedoclyConfig): Promise<unknown[]> {
   const apis = redoclyApisOf(redocly);
-  const results = await Promise.allSettled(apis.map((api) => generateApi(run, redocly, api)));
-  return results.flatMap((result) => (result.status === "rejected" ? [result.reason] : []));
+  const { configRoot, files } = configFilesOf(run, redocly, apis);
+  const results = await settledInTurn(apis, (api) =>
+    generateApi(run, redocly, apiTarget(api, configRoot), files),
+  );
+  const generated = results.flatMap((result) =>
+    result.status === "fulfilled" ? [result.value] : [],
+  );
+  const readFiles = generated.flatMap(({ name, types }) => filesReadBy(run, types, `API ${name}`));
+  const writeFailures = writeGeneratedApis(run, generated, readFiles);
+  return results.flatMap((result) =>
+    result.status === "rejected" ? [result.reason] : (writeFailures.get(result.value.name) ?? []),
+  );
 }

package/src/cli/run-cli.ts

@@ -5,7 +5,16 @@ import type { SchemaSource } from "../types.js";
 import { ineffectiveFlagNotices, parseCliArguments } from "./cli-arguments.js";
 import type { CliDependencies } from "./cli-dependencies.js";
 import { cliError, describeCliFailure, EXIT_CODES, type ExitCode } from "./cli-errors.js";
-import { type CliRun, emitOutput, resolveLocationUrl } from "./cli-output.js";
+import {
+  type CliRun,
+  ensureOutputIsNotSchema,
+  filesReadBy,
+  type OutputFile,
+  outputFileOf,
+  redoclyConfigFiles,
+  resolveLocationUrl,
+  writeOutput,
+} from "./cli-output.js";
 import { MULTIPLE_SCHEMAS_DOCS_URL } from "./docs-links.js";
 import { fixOption } from "./fix-option.js";
 import { HELP_TEXT } from "./help-text.js";
@@ -43,7 +52,10 @@ function schemaSource(run: CliRun): SchemaSource {
   return run.deps.stdin();
 }
 
-/** One schema from a path, a URL or stdin; without `--output`, the types go to stdout only. */
+/**
+ * One schema from a path, a URL or stdin; without `--output`, the types go to stdout. Warnings and
+ * errors go to stderr either way, so they never mix with the types (upstream dropped warnings).
+ */
 async function generateSingleSchema(run: CliRun, redocly: RedoclyConfig): Promise<void> {
   const { input, output } = run.args;
   if (input?.includes("*")) {
@@ -61,20 +73,37 @@ async function generateSingleSchema(run: CliRun, redocly: RedoclyConfig): Promis
     );
   }
   const source = schemaSource(run);
+  const outputFile = output ? singleOutputFile(run, output, source, redocly) : undefined;
   const options = {
     ...run.args.generatorFlags,
     ...refLimitOptions(run.args, run.deps.cwd),
     ...fixOption(run.args.fix),
     redocly,
-    silent: !output,
   };
-  const contents = await run.deps.generate(source, options);
-  if (!output) {
-    run.deps.writeStdout(contents);
+  const types = await run.deps.generate(source, options);
+  if (!outputFile) {
+    run.deps.writeStdout(types.contents);
     return;
   }
-  const file = resolveLocationUrl(output, run.deps.cwd);
-  emitOutput(run, { source: input ?? "stdin", output, file }, contents);
+  writeOutput(run, outputFile, types, filesReadBy(run, types, outputFile.source));
+}
+
+/**
+ * The `--output` file; it must not be the schema file nor the Redocly config, which writing it
+ * would replace.
+ */
+function singleOutputFile(
+  run: CliRun,
+  output: string,
+  source: SchemaSource,
+  redocly: RedoclyConfig,
+): OutputFile {
+  const { input } = run.args;
+  const outputFile = outputFileOf(run, { source: input ?? "stdin", output }, run.deps.cwd);
+  const schemas =
+    input && source instanceof URL ? [{ name: `schema ${input}`, location: source }] : [];
+  ensureOutputIsNotSchema(run, outputFile, [...schemas, ...redoclyConfigFiles(run, redocly)]);
+  return outputFile;
 }
 
 async function generate(run: CliRun): Promise<unknown[]> {

package/src/domain/append-all.ts

@@ -0,0 +1,10 @@
+/**
+ * Append every item of `items` to `target`. `target.push(...items)` passes each item as an
+ * argument, and engines limit the arguments of a call (V8 throws a RangeError from about 125,000),
+ * so a list as long as a document allows (an `enum`, an `anyOf`, `examples`) must not be spread.
+ */
+export function appendAll<T>(target: T[], items: Iterable<T>): void {
+  for (const item of items) {
+    target.push(item);
+  }
+}