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

package/src/cli/api-settings.ts

@@ -1,12 +1,10 @@
 import { kebabCase } from "scule";
-import { isOpenAPITypesafeError, OpenAPITypesafeError } from "../domain/errors.js";
 import type { OutputFixName } from "../domain/output-fixes.js";
 import { WARNING_CODES, warningText } from "../domain/warnings.js";
 import { GENERATOR_FLAGS, type GeneratorFlags, hostList } from "./cli-arguments.js";
-import { cliError } from "./cli-errors.js";
-import { resolveLocationUrl } from "./cli-output.js";
+import { ApiFailure, cliError } from "./cli-errors.js";
 import { fixNamesOf } from "./fix-option.js";
-import type { RefLimitOptions } from "./ref-limits.js";
+import { localRootUrl, type RefLimitOptions } from "./ref-limits.js";
 
 /**
  * The settings of one API in `redocly.yaml` (`apis.<name>.x-openapi-ts`). A setting has the name
@@ -23,6 +21,7 @@ export const OUTPUT_SETTING = "output";
 export const FIX_SETTING = "fix";
 
 const LOCAL_REF_ROOT_SETTING = "localRefRoot";
+const LOCAL_ROOT_EXPECTED = "a directory path or a file: URL";
 const REMOTE_REF_HOSTS_SETTING = "remoteRefHosts";
 
 /** `--content-never` is accepted and has no effect, as on the command line. */
@@ -127,31 +126,24 @@ export function apiFixNames(
   try {
     return fixNamesOf(entries);
   } catch (error) {
-    throw isOpenAPITypesafeError(error) ? withApiName(apiName, error) : error;
+    throw new ApiFailure(apiName, error);
   }
 }
 
-/** The same error, with the API named first in its message. */
-function withApiName(apiName: string, error: OpenAPITypesafeError): OpenAPITypesafeError {
-  const { code, details, cause } = error;
-  return new OpenAPITypesafeError({
-    code,
-    message: `API ${apiName}: ${error.message}`,
-    details,
-    cause,
-  });
-}
-
-/** `local-ref-root: dir`, relative to the config file; empty means the config file's directory. */
+/**
+ * `local-ref-root: dir`, relative to the config file; empty means the config file's directory. A
+ * value that is no text or a URL of another protocol fails with `CLI_CONFIG_INVALID`.
+ */
 function localRefRootOf(apiName: string, settings: ApiSettings, configRoot: URL): RefLimitOptions {
   if (!hasSetting(settings, LOCAL_REF_ROOT_SETTING)) {
     return {};
   }
   const value = settingValue(settings, LOCAL_REF_ROOT_SETTING) ?? "";
-  if (typeof value !== "string") {
-    throw invalidSetting(apiName, settings, LOCAL_REF_ROOT_SETTING, "a directory path");
+  const localRoot = typeof value === "string" ? localRootUrl(value, configRoot) : undefined;
+  if (localRoot === undefined) {
+    throw invalidSetting(apiName, settings, LOCAL_REF_ROOT_SETTING, LOCAL_ROOT_EXPECTED);
   }
-  return { localRefRoot: resolveLocationUrl(value === "" ? "." : value, configRoot) };
+  return { localRefRoot: localRoot };
 }
 
 /** `remote-ref-hosts: [a, b]` or `a,b`; an empty list or value allows no host. */

package/src/cli/api-writes.ts

@@ -1,5 +1,6 @@
 import type { ClaimedFile } from "../application/ports/file-system.js";
 import type { GeneratedTypes } from "./cli-dependencies.js";
+import { ApiFailure } from "./cli-errors.js";
 import {
   type CliRun,
   duplicateOutputError,
@@ -84,10 +85,17 @@ function writeClaimed(run: CliRun, { api, claim }: ClaimedApi): unknown[] {
     : failures;
 }
 
+/** The failures with the name of their API, which the CLI prints before each message. */
+function namedFailures(failures: ApiFailures): ApiFailures {
+  return new Map(
+    [...failures].map(([name, list]) => [name, list.map((cause) => new ApiFailure(name, cause))]),
+  );
+}
+
 /**
  * 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.
+ * API. Returns the failures by API name, each an `ApiFailure`. 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,
@@ -113,5 +121,5 @@ export function writeGeneratedApis(
   for (const entry of claimed.filter(({ api }) => !shared.has(api.name))) {
     failures.set(entry.api.name, writeClaimed(run, entry));
   }
-  return failures;
+  return namedFailures(failures);
 }

package/src/cli/cli-arguments.ts

@@ -2,51 +2,28 @@ import { kebabCase } from "scule";
 import parser from "yargs-parser";
 import type { OutputFixName } from "../domain/output-fixes.js";
 import { cliError } from "./cli-errors.js";
+import {
+  ALIASES,
+  BOOLEAN_FLAGS,
+  GENERATOR_FLAGS,
+  type GeneratorFlag,
+  type GeneratorFlags,
+  KNOWN_FLAGS,
+  STRING_FLAGS,
+} from "./cli-flag-names.js";
+import { MULTIPLE_SCHEMAS_DOCS_URL } from "./docs-links.js";
 import { fixNamesOf } from "./fix-option.js";
+import {
+  rejectInvalidBooleans,
+  rejectNegatedValueFlags,
+  rejectRemovedFlags,
+  unknownFlagNames,
+  writtenFlags,
+} from "./written-flags.js";
 
-/** The CLI's arguments, parsed as the original CLI parsed them (yargs-parser). */
-
-/** Boolean flags that become generator options (camelCase; yargs also accepts kebab-case). */
-export const GENERATOR_FLAGS = [
-  "additionalProperties",
-  "alphabetize",
-  "arrayLength",
-  "binaryAsBlob",
-  "conditionalEnums",
-  "dedupeEnums",
-  "defaultNonNullable",
-  "emptyObjectsUnknown",
-  "enum",
-  "enumValues",
-  "excludeDeprecated",
-  "exportType",
-  "generatePathParams",
-  "immutable",
-  "lint",
-  "makePathsEnum",
-  "pathParamsAsTypes",
-  "propertiesRequiredByDefault",
-  "readWriteMarkers",
-  "rootTypes",
-  "rootTypesKeepCasing",
-  "rootTypesNoSchemaPrefix",
-] as const;
-
-export type GeneratorFlag = (typeof GENERATOR_FLAGS)[number];
+export { GENERATOR_FLAGS, type GeneratorFlag, type GeneratorFlags } from "./cli-flag-names.js";
 
-export type GeneratorFlags = Readonly<Partial<Record<GeneratorFlag, boolean>>>;
-
-// `contentNever` was a boolean flag of the original CLI that no code reads; it stays in the list
-// so that `--content-never <input>` keeps parsing as a flag and an input.
-const CAMEL_CASE_BOOLEAN_FLAGS = [...GENERATOR_FLAGS, "check", "contentNever", "help"];
-
-// yargs-parser matches the `boolean` list by the exact spelling of the flag: with camelCase names
-// only, `--root-types schema.yaml` took the path as the flag's value (upstream #2523). Both
-// spellings are listed.
-const BOOLEAN_FLAGS = [
-  ...CAMEL_CASE_BOOLEAN_FLAGS,
-  ...CAMEL_CASE_BOOLEAN_FLAGS.map((flag) => kebabCase(flag)),
-];
+/** The CLI's arguments, parsed as the original CLI parsed them (yargs-parser). */
 
 /** The `$ref` limits as the user wrote them; unset flags are absent. */
 export interface CliRefLimits {
@@ -70,36 +47,16 @@ export interface CliArguments {
   readonly unknownFlags: readonly string[];
 }
 
-/** Flags of older versions that were removed or renamed, with the message for each. */
-const REMOVED_FLAGS: readonly (readonly [string, string])[] = [
-  ["-ap", `The -ap alias has been deprecated. Use "--additional-properties" instead.`],
-  ["--immutable-types", `The --immutable-types flag has been renamed to "--immutable".`],
-  [
-    "--support-array-length",
-    `The --support-array-length flag has been renamed to "--array-length".`,
-  ],
-  ["-it", `The -it alias has been deprecated. Use "--immutable" instead.`],
-  ["--redoc", `The --redoc config flag has been renamed to "--redocly" (or -c as shorthand).`],
-];
-
 /** Flags that only work together with `--root-types`. */
-const ROOT_TYPES_FLAGS = ["--root-types-no-schema-prefix", "--root-types-keep-casing"] as const;
-
-function rejectRemovedFlags(argv: readonly string[]): void {
-  for (const [flag, message] of REMOVED_FLAGS) {
-    if (argv.includes(flag)) {
-      throw cliError("CLI_FLAG_REMOVED", message);
-    }
-  }
-}
+const ROOT_TYPES_FLAGS = ["rootTypesNoSchemaPrefix", "rootTypesKeepCasing"] as const;
 
 /** 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 +74,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);
 }
@@ -146,24 +106,6 @@ function refLimitsOf(parsed: parser.Arguments): CliRefLimits {
   };
 }
 
-/** String flags, in both spellings, so that a value such as `8080` is not read as a number. */
-const STRING_FLAGS = [
-  "output",
-  "redocly",
-  "fix",
-  ...["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,
-  ...STRING_FLAGS,
-  ...Object.values(ALIASES).flat(),
-  "version",
-]);
-
 /**
  * Flags that no code reads. The original CLI ignored them silently, so a typo such as
  * `--alphabetise` gave other output with no hint; they still do not fail the run.
@@ -186,20 +128,43 @@ 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
+ * The one schema argument. More than one fails with `CLI_INPUT_EXTRA`: the original CLI read the
+ * first and dropped the rest, so a glob the shell expanded (`g/*.yaml`) generated one schema.
+ */
+function inputOf(positionals: readonly (string | number)[]): string | undefined {
+  if (positionals.length > 1) {
+    throw cliError(
+      "CLI_INPUT_EXTRA",
+      `Only one schema argument is allowed, but ${positionals.length} were given: ` +
+        `${positionals.join(" ")}. A shell expands an unquoted *; to generate several ` +
+        `schemas, list them under \`apis\` in redocly.yaml. See ${MULTIPLE_SCHEMAS_DOCS_URL}`,
+    );
+  }
+  return optionalString(positionals[0]);
+}
+
+/**
+ * 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 or a `--no-` form
+ * of a flag that takes a value, with `CLI_INPUT_EXTRA` for a second schema argument, 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);
+  rejectNegatedValueFlags(flags);
   const parsed = parser([...argv], {
-    boolean: BOOLEAN_FLAGS,
+    boolean: [...BOOLEAN_FLAGS, ...unknownFlagNames(flags)],
     string: STRING_FLAGS,
     alias: ALIASES,
+    // A schema path is a file name: `1.10` is not the number 1.1.
+    configuration: { "parse-positional-numbers": false },
   });
   return {
-    input: optionalString(parsed._[0]),
-    output: optionalString(parsed.output),
-    redocly: optionalString(parsed.redocly),
+    input: inputOf(parsed._),
+    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,6 +1,7 @@
 import type { Readable } from "node:stream";
 import type {
   DirectoryCheck,
+  FileCheck,
   FileClaims,
   FileIdentity,
   FileReader,
@@ -33,10 +34,14 @@ export interface GeneratedTypes {
   readonly localFiles: readonly URL[];
 }
 
-/** Generate the types of one schema. */
+/**
+ * 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 {
@@ -55,7 +60,7 @@ export interface CliDependencies {
    * input with no prompt, which looks like a hang (upstream #1905).
    */
   readonly isStdinTerminal: () => boolean;
-  readonly files: FileReader & FileWriter & FileIdentity & DirectoryCheck & FileClaims;
+  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

@@ -99,14 +99,17 @@ 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_INPUT_EXTRA: { 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 },
@@ -127,6 +130,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}` };
@@ -136,6 +143,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-flag-names.ts

@@ -0,0 +1,99 @@
+import { kebabCase } from "scule";
+
+/** The names of the CLI's flags, in the spellings yargs-parser is told about. */
+
+/** Boolean flags that become generator options (camelCase; yargs also accepts kebab-case). */
+export const GENERATOR_FLAGS = [
+  "additionalProperties",
+  "alphabetize",
+  "arrayLength",
+  "binaryAsBlob",
+  "conditionalEnums",
+  "dedupeEnums",
+  "defaultNonNullable",
+  "emptyObjectsUnknown",
+  "enum",
+  "enumValues",
+  "excludeDeprecated",
+  "exportType",
+  "generatePathParams",
+  "immutable",
+  "lint",
+  "makePathsEnum",
+  "pathParamsAsTypes",
+  "propertiesRequiredByDefault",
+  "readWriteMarkers",
+  "rootTypes",
+  "rootTypesKeepCasing",
+  "rootTypesNoSchemaPrefix",
+] as const;
+
+export type GeneratorFlag = (typeof GENERATOR_FLAGS)[number];
+
+export type GeneratorFlags = Readonly<Partial<Record<GeneratorFlag, boolean>>>;
+
+// `contentNever` was a boolean flag of the original CLI that no code reads; it stays in the list
+// so that `--content-never <input>` keeps parsing as a flag and an input.
+const CAMEL_CASE_BOOLEAN_FLAGS = [...GENERATOR_FLAGS, "check", "contentNever", "help"];
+
+// yargs-parser matches the `boolean` list by the exact spelling of the flag: with camelCase names
+// only, `--root-types schema.yaml` took the path as the flag's value (upstream #2523). Both
+// spellings are listed.
+export const BOOLEAN_FLAGS = [
+  ...CAMEL_CASE_BOOLEAN_FLAGS,
+  ...CAMEL_CASE_BOOLEAN_FLAGS.map((flag) => kebabCase(flag)),
+];
+
+export const ALIASES = { redocly: ["c"], exportType: ["t"], output: ["o"] };
+
+const CAMEL_CASE_STRING_FLAGS = ["output", "redocly", "fix", "localRefRoot", "remoteRefHosts"];
+
+/** String flags, in both spellings, so that a value such as `8080` is not read as a number. */
+export const STRING_FLAGS = [
+  ...CAMEL_CASE_STRING_FLAGS,
+  ...CAMEL_CASE_STRING_FLAGS.map((flag) => kebabCase(flag)),
+];
+
+/** Every name yargs-parser can return for a flag this CLI reads. */
+export const KNOWN_FLAGS: ReadonlySet<string> = new Set<string>([
+  ...BOOLEAN_FLAGS,
+  ...STRING_FLAGS,
+  ...Object.values(ALIASES).flat(),
+  "version",
+]);
+
+export const LONG_PREFIX = "--";
+export const SHORT_PREFIX = "-";
+export const NEGATION_PREFIX = "--no-";
+
+/** The short aliases of `flags`, as written on the command line (`-t`). */
+function aliasesOf(flags: readonly string[]): string[] {
+  return Object.entries(ALIASES)
+    .filter(([flag]) => flags.includes(flag))
+    .flatMap(([, aliases]) => aliases.map((alias) => `${SHORT_PREFIX}${alias}`));
+}
+
+/** The boolean flags as written, `--` and `-` included; they take `=true` or `=false`. */
+export const BOOLEAN_FLAG_NAMES: ReadonlySet<string> = new Set([
+  ...BOOLEAN_FLAGS.map((flag) => `${LONG_PREFIX}${flag}`),
+  ...aliasesOf(CAMEL_CASE_BOOLEAN_FLAGS),
+]);
+
+/**
+ * The flags that take a value, as `canonicalFlagName` gives them: kebab-case, and the short
+ * aliases with `--`, since yargs-parser reads `--no-o` as the negation of `-o`.
+ */
+export const VALUE_FLAG_NAMES: ReadonlySet<string> = new Set([
+  ...CAMEL_CASE_STRING_FLAGS.map((flag) => `${LONG_PREFIX}${kebabCase(flag)}`),
+  ...aliasesOf(CAMEL_CASE_STRING_FLAGS).map((alias) => `${SHORT_PREFIX}${alias}`),
+]);
+
+/** The long flags this CLI reads, as `canonicalFlagName` gives them. */
+export const KNOWN_LONG_FLAG_NAMES: ReadonlySet<string> = new Set(
+  [...KNOWN_FLAGS]
+    .filter((flag) => flag.length > 1)
+    .map((flag) => `${LONG_PREFIX}${kebabCase(flag)}`),
+);
+
+/** The short flags this CLI reads, without the `-`. */
+export const KNOWN_SHORT_FLAGS: ReadonlySet<string> = new Set(Object.values(ALIASES).flat());

package/src/cli/cli-output.ts

@@ -2,7 +2,9 @@ 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 { 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, GeneratedTypes } from "./cli-dependencies.js";
 import { cliError } from "./cli-errors.js";
@@ -27,12 +29,6 @@ export interface OutputFile extends NamedOutput {
   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;
-
 /**
  * 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
@@ -41,7 +37,7 @@ const URL_SCHEME = /^[a-z][a-z\d+.-]+:/i;
  * (`http://[::1/x`) fails with `CLI_LOCATION_INVALID`.
  */
 export function resolveLocationUrl(location: string, base: URL): URL {
-  if (URL_SCHEME.test(location)) {
+  if (hasUrlScheme(location)) {
     const url = URL.parse(location, base.href);
     if (url === null) {
       const shown = redactUnparsedUrl(location);
@@ -191,37 +187,56 @@ export function ensureOutputIsOwn(
   }
 }
 
-/** `CLI_OUTPUT_DUPLICATE` for `output`, which is also the output of the `others` (named). */
+/**
+ * `CLI_OUTPUT_DUPLICATE` for `output`, which is also the output of the `others` (named). Only
+ * APIs share outputs, and the CLI names the API before the message (`ApiFailure`).
+ */
 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.`,
+    `The output ${output.output} 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)) {
+  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}`);
 }
 
+const CRLF = /\r\n/g;
+const LF = "\n";
+
+/**
+ * The text with LF line ends. Git with `core.autocrlf` checks a committed file out with CRLF on
+ * Windows, so `--check` compares lines, not line ends.
+ */
+function withLfLineEnds(text: string): string {
+  return text.replace(CRLF, LF);
+}
+
 /**
- * With `--check`, fail with `OUTPUT_STALE` when the file differs from `contents` and leave it
- * alone otherwise. Without it, write the file and print where it went.
+ * With `--check`, fail with `OUTPUT_STALE` when the file differs from `contents` (line ends
+ * aside) and leave it alone otherwise. Without it, write the file and print where it went.
  */
 export function emitOutput(run: CliRun, output: OutputFile, contents: string): void {
   if (run.args.isCheck) {
-    if (run.deps.files.readText(output.file) !== contents) {
+    if (withLfLineEnds(run.deps.files.readText(output.file)) !== withLfLineEnds(contents)) {
       // The original message, then the file: with several APIs it tells which one is stale.
       throw cliError(
         "OUTPUT_STALE",

package/src/cli/main.ts

@@ -3,11 +3,14 @@ import { isatty } from "node:tty";
 import { pathToFileURL } from "node:url";
 import colors from "ansi-colors";
 import { createNodeFileSystem } from "../adapters/node-file-system/node-file-system.js";
+import { createPipeSafeWriter } from "../adapters/pipe-safe-writer/pipe-safe-writer.js";
 import { createRedoclyConfigSource } from "../adapters/redocly-loader/redocly-config-source.js";
 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 { defaultGeneratorPorts, generateDocument } from "../api/openapi-ts.js";
+import { terminalSafeText } from "../domain/terminal-text.js";
+import { apiLogger } from "./api-logger.js";
 import type { CliConsole, CliDependencies, GenerateTypes, TextStyle } from "./cli-dependencies.js";
 import { runCli } from "./run-cli.js";
 
@@ -24,9 +27,10 @@ function readVersion(): string {
   return packageJson.version;
 }
 
+/** The style of the CLI's own lines, which go to stdout. */
 function terminalStyle(): TextStyle {
   const palette = colors.create();
-  palette.enabled = terminalSupportsColor();
+  palette.enabled = terminalSupportsColor("stdout");
   return {
     bold: (text) => palette.bold(text),
     green: (text) => palette.green(text),
@@ -36,8 +40,10 @@ function terminalStyle(): TextStyle {
 
 const STDIN_DESCRIPTOR = 0;
 
-const generateTypes: GenerateTypes = async (source, options) => {
-  const ports = await defaultGeneratorPorts(options);
+const generateTypes: GenerateTypes = async (source, options, apiName) => {
+  const terminalLogger = defaultLogger(options.silent ?? false);
+  const logger = apiName === undefined ? terminalLogger : apiLogger(terminalLogger, apiName);
+  const ports = await defaultGeneratorPorts(options, logger);
   const { declarations, localFiles } = await generateDocument(source, options, ports);
   return { contents: `${COMMENT_HEADER}${astToString(declarations)}`, localFiles };
 };
@@ -46,8 +52,9 @@ function terminalConsole(): CliConsole {
   return {
     // biome-ignore lint/suspicious/noConsole: the CLI's own output lines
     info: (text) => console.info(text),
+    // A notice names flags and API names as written, so it is shown as one plain line.
     // biome-ignore lint/suspicious/noConsole: the CLI's own notices
-    notice: (text) => console.warn(text),
+    notice: (text) => console.warn(terminalSafeText(text)),
   };
 }
 
@@ -58,7 +65,7 @@ function processDependencies(): CliDependencies {
     version: readVersion(),
     logger: defaultLogger(false),
     console: terminalConsole(),
-    writeStdout: (text) => process.stdout.write(text),
+    writeStdout: createPipeSafeWriter(process.stdout),
     stdin: () => process.stdin,
     // `isatty` reads the descriptor without opening `process.stdin`, which would keep the
     // process alive.