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

package/src/cli/api-writes.ts

@@ -0,0 +1,117 @@
+import type { ClaimedFile } from "../application/ports/file-system.js";
+import type { GeneratedTypes } from "./cli-dependencies.js";
+import {
+  type CliRun,
+  duplicateOutputError,
+  emitOutput,
+  ensureOutputIsNotSchema,
+  type NamedFile,
+  type OutputFile,
+} from "./cli-output.js";
+
+/**
+ * Writing the generated APIs of a Redocly config. Before the first byte is written, every output
+ * is claimed: a missing one is created empty, so the file system gives it its own identity. Two
+ * APIs whose files then have one identity fail with `CLI_OUTPUT_DUPLICATE` and write nothing,
+ * also when their names looked different (ADR-043, decision 1).
+ */
+
+/** An API whose types are generated and not written yet. */
+export interface GeneratedApi {
+  readonly name: string;
+  readonly outputFile: OutputFile;
+  readonly types: GeneratedTypes;
+}
+
+/** An API whose output is claimed; `claim` is undefined with `--check`, which writes nothing. */
+interface ClaimedApi {
+  readonly api: GeneratedApi;
+  readonly claim: ClaimedFile | undefined;
+}
+
+/** The failures of the API an API name maps to; an API without failures was written. */
+type ApiFailures = Map<string, unknown[]>;
+
+/** The failure of a step, as a list: empty when it succeeded. */
+export function failuresOf(step: () => void): unknown[] {
+  try {
+    step();
+    return [];
+  } catch (failure) {
+    return [failure];
+  }
+}
+
+/** Claim the output of each API; an API whose claim fails gets that failure instead. */
+function claimOutputs(run: CliRun, apis: readonly GeneratedApi[], failures: ApiFailures) {
+  const claimed: ClaimedApi[] = [];
+  for (const api of apis) {
+    try {
+      const claim = run.args.isCheck ? undefined : run.deps.files.claimFile(api.outputFile.file);
+      claimed.push({ api, claim });
+    } catch (failure) {
+      failures.set(api.name, [failure]);
+    }
+  }
+  return claimed;
+}
+
+/** The APIs that share their claimed file with another, by API name, with the other names. */
+function sharedOutputs(claimed: readonly ClaimedApi[]): Map<string, string[]> {
+  const byIdentity = new Map<string, string[]>();
+  for (const { api, claim } of claimed) {
+    if (claim) {
+      byIdentity.set(claim.identity, [...(byIdentity.get(claim.identity) ?? []), api.name]);
+    }
+  }
+  const shared = new Map<string, string[]>();
+  for (const names of byIdentity.values()) {
+    for (const name of names.length > 1 ? names : []) {
+      shared.set(
+        name,
+        names.filter((other) => other !== name).map((other) => `API ${other}`),
+      );
+    }
+  }
+  return shared;
+}
+
+/** Write one claimed API; a failed write releases the claim, so no empty file is left. */
+function writeClaimed(run: CliRun, { api, claim }: ClaimedApi): unknown[] {
+  const failures = failuresOf(() => emitOutput(run, api.outputFile, api.types.contents));
+  return failures.length > 0 && claim
+    ? [...failures, ...failuresOf(() => claim.release())]
+    : failures;
+}
+
+/**
+ * Write (or `--check`) every API unless its output is a file the run read or the file of another
+ * API. Returns the failures by API name. Claims are released in reverse order, so a directory
+ * one claim created is empty by the time it is removed.
+ */
+export function writeGeneratedApis(
+  run: CliRun,
+  apis: readonly GeneratedApi[],
+  readFiles: readonly NamedFile[],
+): ApiFailures {
+  const failures: ApiFailures = new Map();
+  const ownOutputs = apis.filter((api) => {
+    const failure = failuresOf(() => ensureOutputIsNotSchema(run, api.outputFile, readFiles));
+    failures.set(api.name, failure);
+    return failure.length === 0;
+  });
+  const claimed = claimOutputs(run, ownOutputs, failures);
+  const shared = sharedOutputs(claimed);
+  for (const entry of [...claimed].reverse()) {
+    const { api, claim } = entry;
+    const others = shared.get(api.name);
+    if (others) {
+      const release = claim ? failuresOf(() => claim.release()) : [];
+      failures.set(api.name, [duplicateOutputError(api.outputFile, others), ...release]);
+    }
+  }
+  for (const entry of claimed.filter(({ api }) => !shared.has(api.name))) {
+    failures.set(entry.api.name, writeClaimed(run, entry));
+  }
+  return failures;
+}

package/src/cli/cli-arguments.ts

@@ -83,23 +83,95 @@ const REMOVED_FLAGS: readonly (readonly [string, string])[] = [
 ];
 
 /** Flags that only work together with `--root-types`. */
-const ROOT_TYPES_FLAGS = ["--root-types-no-schema-prefix", "--root-types-keep-casing"] as const;
+const ROOT_TYPES_FLAGS = ["rootTypesNoSchemaPrefix", "rootTypesKeepCasing"] as const;
 
-function rejectRemovedFlags(argv: readonly string[]): void {
+const OPTIONS_END = "--";
+const LONG_PREFIX = "--";
+const NEGATION_PREFIX = "--no-";
+const VALUE_SEPARATOR = "=";
+const BOOLEAN_VALUES: ReadonlySet<string> = new Set(["true", "false"]);
+
+/** A flag as written before `--`: its name (`--redoc`, `-o`) and the text after `=`, if any. */
+interface WrittenFlag {
+  readonly name: string;
+  readonly value: string | undefined;
+}
+
+function writtenFlags(argv: readonly string[]): WrittenFlag[] {
+  const end = argv.indexOf(OPTIONS_END);
+  return (end === -1 ? argv : argv.slice(0, end))
+    .filter((arg) => arg.startsWith("-") && arg !== "-")
+    .map((arg) => {
+      const at = arg.indexOf(VALUE_SEPARATOR);
+      return at === -1
+        ? { name: arg, value: undefined }
+        : { name: arg.slice(0, at), value: arg.slice(at + 1) };
+    });
+}
+
+/**
+ * A long flag as yargs-parser reads it: in kebab-case and without `--no-`, so `--immutableTypes`
+ * and `--no-immutable-types` are `--immutable-types`. A short flag stays as written.
+ */
+function canonicalFlagName(name: string): string {
+  if (!name.startsWith(LONG_PREFIX)) {
+    return name;
+  }
+  const bare = name.startsWith(NEGATION_PREFIX)
+    ? name.slice(NEGATION_PREFIX.length)
+    : name.slice(LONG_PREFIX.length);
+  return `${LONG_PREFIX}${kebabCase(bare)}`;
+}
+
+/** An old flag fails by its name in any spelling, also with a value (`--redoc=redocly.yaml`). */
+function rejectRemovedFlags(flags: readonly WrittenFlag[]): void {
+  const names = new Set(flags.map(({ name }) => canonicalFlagName(name)));
   for (const [flag, message] of REMOVED_FLAGS) {
-    if (argv.includes(flag)) {
+    if (names.has(flag)) {
       throw cliError("CLI_FLAG_REMOVED", message);
     }
   }
 }
 
+const ALIASES = { redocly: ["c"], exportType: ["t"], output: ["o"] };
+
+/** The short aliases of boolean flags (`-t`), which take a value the same way (`-t=true`). */
+const BOOLEAN_ALIASES = Object.entries(ALIASES)
+  .filter(([flag]) => CAMEL_CASE_BOOLEAN_FLAGS.includes(flag))
+  .flatMap(([, aliases]) => aliases.map((alias) => `-${alias}`));
+
+const BOOLEAN_FLAG_NAMES: ReadonlySet<string> = new Set([
+  ...BOOLEAN_FLAGS.map((flag) => `${LONG_PREFIX}${flag}`),
+  ...BOOLEAN_ALIASES,
+]);
+
+/**
+ * A boolean flag takes `=true` or `=false`, and its `--no-` form takes no value. yargs-parser read
+ * any other value as false (`--enum=1`, `--alphabetize=yes`), which turned the option off.
+ */
+function rejectInvalidBooleans(flags: readonly WrittenFlag[]): void {
+  for (const { name, value } of flags) {
+    const negated = name.startsWith(NEGATION_PREFIX)
+      ? `${LONG_PREFIX}${name.slice(NEGATION_PREFIX.length)}`
+      : undefined;
+    const isNegatedWithValue = negated !== undefined && BOOLEAN_FLAG_NAMES.has(negated);
+    const isInvalid = BOOLEAN_FLAG_NAMES.has(name) && !BOOLEAN_VALUES.has(value ?? "true");
+    if (value !== undefined && (isNegatedWithValue || isInvalid)) {
+      throw cliError(
+        "CLI_FLAG_INVALID",
+        `${name}=${value}: a boolean flag takes no value, or =true or =false.`,
+      );
+    }
+  }
+}
+
 /** Notices for flags that have no effect in this combination, printed before the run. */
-export function ineffectiveFlagNotices(argv: readonly string[]): string[] {
-  if (argv.includes("--root-types")) {
+export function ineffectiveFlagNotices(flags: GeneratorFlags): string[] {
+  if (flags.rootTypes === true) {
     return [];
   }
-  return ROOT_TYPES_FLAGS.filter((flag) => argv.includes(flag)).map(
-    (flag) => `${flag} has no effect without --root-types flag`,
+  return ROOT_TYPES_FLAGS.filter((flag) => flags[flag] === true).map(
+    (flag) => `--${kebabCase(flag)} has no effect without --root-types flag`,
   );
 }
 
@@ -117,7 +189,10 @@ function optionalString(value: unknown): string | undefined {
   return value === undefined ? undefined : String(value);
 }
 
-/** The last value of a flag that may be given more than once. */
+/**
+ * The last value of a flag that takes one value: given twice, the last one wins, as for the
+ * boolean flags (yargs-parser gives a list of every value).
+ */
 function lastString(value: unknown): string | undefined {
   return optionalString(Array.isArray(value) ? value.at(-1) : value);
 }
@@ -154,8 +229,6 @@ const STRING_FLAGS = [
   ...["localRefRoot", "remoteRefHosts"].flatMap((flag) => [flag, kebabCase(flag)]),
 ];
 
-const ALIASES = { redocly: ["c"], exportType: ["t"], output: ["o"] };
-
 /** Every name yargs-parser can return for a flag this CLI reads. */
 const KNOWN_FLAGS = new Set<string>([
   ...BOOLEAN_FLAGS,
@@ -186,11 +259,14 @@ function writtenFlagName(key: string, argv: readonly string[]): string {
 }
 
 /**
- * Parse the arguments after `node cli.js`. Fails with `CLI_FLAG_REMOVED` for an old flag and with
+ * Parse the arguments after `node cli.js`. Fails with `CLI_FLAG_REMOVED` for an old flag, with
+ * `CLI_FLAG_INVALID` for a boolean flag with another value than true or false, and with
  * `OPTION_FIX_UNKNOWN` for an unknown `--fix` name.
  */
 export function parseCliArguments(argv: readonly string[]): CliArguments {
-  rejectRemovedFlags(argv);
+  const flags = writtenFlags(argv);
+  rejectRemovedFlags(flags);
+  rejectInvalidBooleans(flags);
   const parsed = parser([...argv], {
     boolean: BOOLEAN_FLAGS,
     string: STRING_FLAGS,
@@ -198,8 +274,8 @@ export function parseCliArguments(argv: readonly string[]): CliArguments {
   });
   return {
     input: optionalString(parsed._[0]),
-    output: optionalString(parsed.output),
-    redocly: optionalString(parsed.redocly),
+    output: lastString(parsed.output),
+    redocly: lastString(parsed.redocly),
     isCheck: parsed.check === true,
     isHelp: "help" in parsed,
     isVersion: "version" in parsed,

package/src/cli/cli-dependencies.ts

@@ -1,5 +1,12 @@
 import type { Readable } from "node:stream";
-import type { FileReader, FileWriter } from "../application/ports/file-system.js";
+import type {
+  DirectoryCheck,
+  FileCheck,
+  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 +26,23 @@ 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. With `apiName`, an API of `redocly.yaml`, every line the
+ * generation logs names that API.
+ */
+export type GenerateTypes = (
+  source: SchemaSource,
+  options: GeneratorOptions,
+  apiName?: string,
+) => Promise<GeneratedTypes>;
 
 export interface CliDependencies {
   /** The working directory, as a directory URL (with a trailing slash). */
@@ -38,7 +60,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 & FileCheck & 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 },
@@ -84,14 +99,20 @@ const CLI_ERROR_REPORTS: Readonly<Record<ErrorCode, CliErrorReport>> = {
   ENUM_NAME_EMPTY: { exitCode: EXIT_CODES.SCHEMA },
   CALLBACK_RESULT_UNREADABLE: { exitCode: EXIT_CODES.USAGE },
   OPTION_FIX_UNKNOWN: { exitCode: EXIT_CODES.USAGE },
+  OPTION_INVALID: { exitCode: EXIT_CODES.USAGE },
   TYPESCRIPT_NOT_FOUND: { exitCode: EXIT_CODES.USAGE },
   CLI_FLAG_REMOVED: { exitCode: EXIT_CODES.USAGE },
+  CLI_FLAG_INVALID: { exitCode: EXIT_CODES.USAGE },
   CLI_GLOB_UNSUPPORTED: { exitCode: EXIT_CODES.USAGE },
   CLI_CONFIG_NOT_FOUND: { exitCode: EXIT_CODES.USAGE },
   CLI_CONFIG_INVALID: { exitCode: EXIT_CODES.USAGE },
   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 },
@@ -108,6 +129,10 @@ export interface CliFailure {
  * else is a bug and prints its stack, so it can be reported.
  */
 export function describeCliFailure(error: unknown): CliFailure {
+  if (error instanceof ApiFailure) {
+    const failure = describeCliFailure(error.cause);
+    return { ...failure, message: `API ${error.apiName}: ${failure.message}` };
+  }
   if (!isOpenAPITypesafeError(error)) {
     const text = error instanceof Error ? (error.stack ?? error.message) : String(error);
     return { exitCode: EXIT_CODES.INTERNAL, message: `Unexpected error: ${text}` };
@@ -117,6 +142,22 @@ export function describeCliFailure(error: unknown): CliFailure {
   return { exitCode: report.exitCode, message: `${message} (${error.code})` };
 }
 
+/**
+ * A failure of one API of a Redocly config. The CLI reports its cause with the API named first,
+ * as the config errors of an API are; the cause keeps its code and so its exit code.
+ */
+export class ApiFailure extends Error {
+  override readonly name = "ApiFailure";
+  override readonly cause: unknown;
+  readonly apiName: string;
+
+  constructor(apiName: string, cause: unknown) {
+    super(`API ${apiName} failed`, { cause });
+    this.apiName = apiName;
+    this.cause = cause;
+  }
+}
+
 /** Errors of the CLI itself; its messages are the original CLI's messages. */
 export function cliError(
   code: Extract<ErrorCode, `CLI_${string}` | `OUTPUT_${string}`>,

package/src/cli/cli-output.ts

@@ -1,8 +1,12 @@
 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 { hasUrlScheme } from "../domain/location-text.js";
+import { terminalSafeText } from "../domain/terminal-text.js";
+import { redactUnparsedUrl, redactUrlSecrets } 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,35 +18,200 @@ 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;
-  readonly file: URL;
 }
 
-/**
- * A scheme of two or more characters (`https:`, `file:`). One letter is a Windows drive (`C:`), so
- * `C:\\specs\\api.yaml` stays a path.
- */
-const URL_SCHEME = /^[a-z][a-z\d+.-]+:/i;
+/** A generated file: an output with the location of its local file. */
+export interface OutputFile extends NamedOutput {
+  readonly file: URL;
+}
 
 /**
- * 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);
+  if (hasUrlScheme(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 (hasUrlScheme(location)) {
+    return URL.parse(location, base.href) ?? undefined;
+  }
+  return resolveLocationUrl(location, base);
+}
+
+/**
+ * The line for a written file. It goes to the job log, so a source URL shows no secrets, and a
+ * line break or escape sequence in a name cannot start a forged line.
+ */
 function printDone(run: CliRun, output: OutputFile): void {
   const { style, now } = run.deps;
-  const target = style.green(`${output.source} → ${style.bold(output.output)}`);
+  const source = terminalSafeText(redactUrlSecrets(output.source));
+  const target = style.green(`${source} → ${style.bold(terminalSafeText(output.output))}`);
   const duration = style.dim(`[${formatDuration(now() - run.startedAt)}]`);
   run.deps.console.info(`🚀 ${target} ${duration}`);
 }
@@ -65,3 +234,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);
+}