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

package/src/application/transform/schema-comment.ts

@@ -1,4 +1,5 @@
 import type { IrComment, IrPropertySignature } from "../../domain/ir/nodes.js";
+import { OutputFix } from "../../domain/output-fixes.js";
 
 /** Schema fields that produce JSDoc lines (the original `AnnotatedSchemaObject`). */
 export interface AnnotatedSchema {
@@ -24,6 +25,27 @@ const COMMENT_END_RE = /\*\//g;
 const VALUE_TAGS = ["description", "default", "example"] as const;
 const TAGS_KEEPING_EMPTY_STRING: ReadonlySet<string> = new Set(["default", "example"]);
 const JSON_INDENT = 2;
+/** The member lists whose descriptions `anyof-oneof-descriptions` adds, with their headings. */
+const MEMBER_LISTS = [
+  ["anyOf", "Any of:"],
+  ["oneOf", "One of:"],
+] as const;
+/** The later lines of a member's description are indented under its bullet. */
+const BULLET_CONTINUATION = "\n  ";
+
+/** How a schema's JSDoc is written. */
+export interface SchemaCommentOptions {
+  /** `anyof-oneof-descriptions`: the descriptions of `anyOf` and `oneOf` members are listed. */
+  readonly hasMemberDescriptions: boolean;
+}
+
+/** The JSDoc the original writes. */
+export const ORIGINAL_SCHEMA_COMMENT: SchemaCommentOptions = { hasMemberDescriptions: false };
+
+/** How the fixes turned on write a schema's JSDoc. */
+export function schemaCommentOptionsOf(fixes: ReadonlySet<OutputFix>): SchemaCommentOptions {
+  return { hasMemberDescriptions: fixes.has(OutputFix.ANYOF_ONEOF_DESCRIPTIONS) };
+}
 
 function formatValue(value: unknown): string {
   const text = typeof value === "object" ? JSON.stringify(value, null, JSON_INDENT) : value;
@@ -81,17 +103,74 @@ function constantAndEnumLines(schema: AnnotatedSchema): string[] {
   return lines;
 }
 
+/** The own, non-blank `description` of each member; a member without one is left out. */
+function memberDescriptions(members: unknown): string[] {
+  if (!Array.isArray(members)) {
+    return [];
+  }
+  return members.flatMap((member: unknown) => {
+    const description = isSchemaObject(member) ? member.description : undefined;
+    return typeof description === "string" && description.trim() !== "" ? [description.trim()] : [];
+  });
+}
+
+/** Each member list with a described member, as a heading and one bullet per description. */
+function memberDescriptionLists(schema: SchemaRecord): string[] {
+  return MEMBER_LISTS.flatMap(([keyword, heading]) => {
+    const descriptions = memberDescriptions(schema[keyword]);
+    if (descriptions.length === 0) {
+      return [];
+    }
+    const bullets = descriptions.map(
+      (description) => `- ${description.replace(LINE_BREAK_RE, BULLET_CONTINUATION)}`,
+    );
+    return [[heading, ...bullets].join("\n")];
+  });
+}
+
+/**
+ * The schema with the descriptions of its `anyOf` and `oneOf` members after its own description
+ * (upstream #2142). A member's description holds only where that member applies, so each one is
+ * listed under its keyword rather than merged into one sentence. A `description` that is not a
+ * string is kept as it is.
+ */
+function withMemberDescriptions(schema: SchemaRecord): AnnotatedSchema {
+  const lists = memberDescriptionLists(schema);
+  const own = schema.description;
+  if (lists.length === 0 || (own !== undefined && typeof own !== "string")) {
+    // As the original, the keywords are read as they are, without validating them.
+    return schema as AnnotatedSchema;
+  }
+  const ownLines = typeof own === "string" && own.trim() !== "" ? [own.trim()] : [];
+  return { ...(schema as AnnotatedSchema), description: [...ownLines, ...lists].join("\n") };
+}
+
+/** A schema object read without knowing its keywords. */
+interface SchemaRecord {
+  readonly description?: unknown;
+  readonly [keyword: string]: unknown;
+}
+
+function isSchemaObject(value: unknown): value is SchemaRecord {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
 /**
  * The JSDoc comment the original writes for a schema (`addJSDocComment`): title, summary and
  * format, then `@deprecated`, `@description`, `@default`, `@example`, `@constant` and `@enum`
  * tags. One short line stays on the `/**` line; anything else is a block. Returns null when there
  * is nothing to say, or when the value is not a schema object.
  */
-export function schemaComment(schema: unknown): IrComment | null {
-  if (!schema || typeof schema !== "object" || Array.isArray(schema)) {
+export function schemaComment(
+  schema: unknown,
+  options: SchemaCommentOptions = ORIGINAL_SCHEMA_COMMENT,
+): IrComment | null {
+  if (!isSchemaObject(schema)) {
     return null;
   }
-  const annotated = schema as AnnotatedSchema;
+  const annotated = options.hasMemberDescriptions
+    ? withMemberDescriptions(schema)
+    : (schema as AnnotatedSchema);
   const lines = [
     ...plainLines(annotated),
     ...valueTagLines(annotated),
@@ -110,7 +189,8 @@ export function schemaComment(schema: unknown): IrComment | null {
 export function withSchemaComment(
   property: IrPropertySignature,
   schema: unknown,
+  options: SchemaCommentOptions = ORIGINAL_SCHEMA_COMMENT,
 ): IrPropertySignature {
-  const comment = schemaComment(schema);
+  const comment = schemaComment(schema, options);
   return comment === null ? property : { ...property, comments: [...property.comments, comment] };
 }

package/src/cli/api-settings.ts

@@ -0,0 +1,109 @@
+import { kebabCase } from "scule";
+import { WARNING_CODES, warningText } from "../domain/warnings.js";
+import { GENERATOR_FLAGS, hostList } from "./cli-arguments.js";
+import { cliError } from "./cli-errors.js";
+import { resolveLocationUrl } from "./cli-output.js";
+import type { RefLimitOptions } from "./ref-limits.js";
+
+/**
+ * The settings of one API in `redocly.yaml` (`apis.<name>.x-openapi-ts`). A setting has the name
+ * of its CLI flag, in kebab-case or camelCase (ADR-021, decision 1); a setting the CLI does not
+ * read gets a warning, as an unknown flag gets a notice.
+ */
+
+export type ApiSettings = Readonly<Record<string, unknown>>;
+
+/** The setting that names the output file. */
+export const OUTPUT_SETTING = "output";
+
+/** The setting that lists the API's output fixes. */
+export const FIX_SETTING = "fix";
+
+const LOCAL_REF_ROOT_SETTING = "localRefRoot";
+const REMOTE_REF_HOSTS_SETTING = "remoteRefHosts";
+
+/** `--content-never` is accepted and has no effect, as on the command line. */
+const IGNORED_SETTINGS = ["contentNever"] as const;
+
+const CAMEL_CASE_SETTINGS = [
+  OUTPUT_SETTING,
+  FIX_SETTING,
+  LOCAL_REF_ROOT_SETTING,
+  REMOTE_REF_HOSTS_SETTING,
+  ...GENERATOR_FLAGS,
+  ...IGNORED_SETTINGS,
+];
+
+const KNOWN_SETTINGS = new Set<string>([
+  ...CAMEL_CASE_SETTINGS,
+  ...CAMEL_CASE_SETTINGS.map((name) => kebabCase(name)),
+]);
+
+/** The warning for each setting of an API that no code reads. */
+export function unknownSettingWarnings(apiName: string, settings: ApiSettings): string[] {
+  return Object.keys(settings)
+    .filter((key) => !KNOWN_SETTINGS.has(key))
+    .map((key) =>
+      warningText(
+        `API ${apiName}: the setting \`${key}\` is not an openapi-typesafe option and is ignored`,
+        WARNING_CODES.CONFIG_SETTING_UNKNOWN,
+      ),
+    );
+}
+
+/** The value of a setting in camelCase, else in kebab-case; `undefined` when it is absent. */
+function settingValue(settings: ApiSettings, name: string): unknown {
+  return name in settings ? settings[name] : settings[kebabCase(name)];
+}
+
+function hasSetting(settings: ApiSettings, name: string): boolean {
+  return name in settings || kebabCase(name) in settings;
+}
+
+function invalidSetting(apiName: string, name: string, expected: string): Error {
+  return cliError(
+    "CLI_CONFIG_INVALID",
+    `API ${apiName}: \`${kebabCase(name)}\` in x-openapi-ts must be ${expected}`,
+  );
+}
+
+/** `local-ref-root: dir`, relative to the config file; empty means the config file's directory. */
+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, LOCAL_REF_ROOT_SETTING, "a directory path");
+  }
+  return { localRefRoot: resolveLocationUrl(value === "" ? "." : value, configRoot) };
+}
+
+/** `remote-ref-hosts: [a, b]` or `a,b`; an empty list or value allows no host. */
+function remoteRefHostsOf(apiName: string, settings: ApiSettings): RefLimitOptions {
+  if (!hasSetting(settings, REMOTE_REF_HOSTS_SETTING)) {
+    return {};
+  }
+  const value = settingValue(settings, REMOTE_REF_HOSTS_SETTING) ?? [];
+  const entries = [value].flat();
+  if (entries.some((entry) => typeof entry !== "string")) {
+    throw invalidSetting(apiName, REMOTE_REF_HOSTS_SETTING, "a host list");
+  }
+  return { remoteRefHosts: hostList(entries) ?? [] };
+}
+
+/**
+ * The `$ref` limits an API sets (threat model R1, R2). Each one replaces the CLI flag of the same
+ * name for this API, as its boolean settings and `fix` do; fails with `CLI_CONFIG_INVALID` for a
+ * value of another type.
+ */
+export function apiRefLimitOptions(
+  apiName: string,
+  settings: ApiSettings,
+  configRoot: URL,
+): RefLimitOptions {
+  return {
+    ...localRefRootOf(apiName, settings, configRoot),
+    ...remoteRefHostsOf(apiName, settings),
+  };
+}

package/src/cli/cli-arguments.ts

@@ -122,8 +122,11 @@ function lastString(value: unknown): string | undefined {
   return optionalString(Array.isArray(value) ? value.at(-1) : value);
 }
 
-/** `--remote-ref-hosts a.example,b.example`, repeatable; an empty value allows no host. */
-function hostList(value: unknown): string[] | undefined {
+/**
+ * `--remote-ref-hosts a.example,b.example`, repeatable; an empty value allows no host. The
+ * `remote-ref-hosts` setting of a `redocly.yaml` API is read the same way.
+ */
+export function hostList(value: unknown): string[] | undefined {
   if (value === undefined) {
     return undefined;
   }
@@ -165,13 +168,23 @@ const KNOWN_FLAGS = new Set<string>([
  * 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.
  */
-function unknownFlagsOf(parsed: parser.Arguments): string[] {
+function unknownFlagsOf(parsed: parser.Arguments, argv: readonly string[]): string[] {
   const names = Object.keys(parsed)
     .filter((key) => key !== "_" && key !== "--" && !KNOWN_FLAGS.has(key))
-    .map((key) => (key.length === 1 ? `-${key}` : `--${kebabCase(key)}`));
+    .map((key) => writtenFlagName(key, argv));
   return [...new Set(names)];
 }
 
+/** The flag as the user wrote it: yargs-parser reads `--no-x` as `x: false`. */
+function writtenFlagName(key: string, argv: readonly string[]): string {
+  if (key.length === 1) {
+    return `-${key}`;
+  }
+  const negated = `--no-${kebabCase(key)}`;
+  const isNegated = argv.some((arg) => arg === negated || arg.startsWith(`${negated}=`));
+  return isNegated ? negated : `--${kebabCase(key)}`;
+}
+
 /**
  * Parse the arguments after `node cli.js`. Fails with `CLI_FLAG_REMOVED` for an old flag and with
  * `OPTION_FIX_UNKNOWN` for an unknown `--fix` name.
@@ -193,6 +206,6 @@ export function parseCliArguments(argv: readonly string[]): CliArguments {
     generatorFlags: generatorFlagsOf(parsed),
     refLimits: refLimitsOf(parsed),
     fix: fixNamesOf(parsed.fix),
-    unknownFlags: unknownFlagsOf(parsed),
+    unknownFlags: unknownFlagsOf(parsed, argv),
   };
 }

package/src/cli/cli-dependencies.ts

@@ -33,6 +33,11 @@ export interface CliDependencies {
   readonly writeStdout: (text: string) => void;
   /** Read only when the schema comes from stdin: opening it early can keep the process alive. */
   readonly stdin: () => Readable;
+  /**
+   * Whether stdin is a terminal. Then nothing is piped in, and reading it would wait for typed
+   * input with no prompt, which looks like a hang (upstream #1905).
+   */
+  readonly isStdinTerminal: () => boolean;
   readonly files: FileReader & FileWriter;
   readonly redoclyConfigs: RedoclyConfigSource;
   readonly generate: GenerateTypes;

package/src/cli/cli-errors.ts

@@ -49,8 +49,8 @@ function loadFailedMessage(error: OpenAPITypesafeError): string {
   if (!(reason instanceof Error)) {
     return error.message;
   }
-  const source = typeof error.details.source === "string" ? ` (${error.details.source})` : "";
-  return `${error.message}: ${reason.message}${source}`;
+  // `loadFailedError`, the only source of this code, always sets the source.
+  return `${error.message}: ${reason.message} (${String(error.details.source)})`;
 }
 
 /** The message js-yaml throws at its nesting limit (docs/security/threat-model.md T2). */
@@ -88,8 +88,10 @@ const CLI_ERROR_REPORTS: Readonly<Record<ErrorCode, CliErrorReport>> = {
   CLI_FLAG_REMOVED: { 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 },
   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,5 +1,5 @@
 import path from "node:path";
-import { pathToFileURL } from "node:url";
+import { fileURLToPath, pathToFileURL } from "node:url";
 import { formatDuration } from "../adapters/terminal-logger/terminal-logger.js";
 import type { CliArguments } from "./cli-arguments.js";
 import type { CliDependencies } from "./cli-dependencies.js";
@@ -21,9 +21,23 @@ export interface OutputFile {
   readonly file: URL;
 }
 
-/** A file URL for a path that is absolute, or relative to `base` (a directory or file URL). */
-export function resolveFileUrl(filePath: string, base: URL): URL {
-  return path.isAbsolute(filePath) ? pathToFileURL(filePath) : new URL(filePath, base);
+/**
+ * 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 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.
+ */
+export function resolveLocationUrl(location: string, base: URL): URL {
+  if (URL_SCHEME.test(location)) {
+    return new URL(location);
+  }
+  const baseDirectory = fileURLToPath(new URL(".", base));
+  return pathToFileURL(path.resolve(baseDirectory, location));
 }
 
 function printDone(run: CliRun, output: OutputFile): void {

package/src/cli/help-text.ts

@@ -4,7 +4,7 @@ export const HELP_TEXT = [
   "  $ openapi-typesafe [input] [options]",
   "",
   "Options",
-  "  --help                     Display this",
+  "  --help                     Show this help",
   "  --version                  Display the version",
   "  --redocly [path], -c       Specify path to Redocly config (default: redocly.yaml)",
   "  --output, -o               Specify output file (if not specified in redocly.yaml)",
@@ -20,8 +20,8 @@ export const HELP_TEXT = [
   "  --additional-properties    Treat schema objects as if `additionalProperties: true` is set",
   "  --empty-objects-unknown    Generate `unknown` instead of" +
     " `Record<string, never>` for empty objects",
-  "  --default-non-nullable     Set to `false` to ignore default values" +
-    " when generating non-nullable types",
+  "  --default-non-nullable     A property with a `default` is required" +
+    " (default: true; =false makes it optional)",
   "  --properties-required-by-default",
   "                             Treat schema objects as if `required` is" +
     " set to all properties by default",
@@ -35,7 +35,7 @@ export const HELP_TEXT = [
     " undefined by schema",
   "  --alphabetize              Sort object keys alphabetically",
   "  --exclude-deprecated       Exclude deprecated types",
-  "  --root-types               Export schemas types at root level",
+  "  --root-types               Export `components` types as root-level aliases",
   "  --root-types-no-schema-prefix",
   '                             Do not add "Schema" prefix to types at' +
     " the root level (should only be used with --root-types)",

package/src/cli/main.ts

@@ -1,4 +1,5 @@
 import fs from "node:fs";
+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";
@@ -33,6 +34,8 @@ function terminalStyle(): TextStyle {
   };
 }
 
+const STDIN_DESCRIPTOR = 0;
+
 const generateTypes: GenerateTypes = async (source, options) =>
   `${COMMENT_HEADER}${astToString(await openapiTS(source, options))}`;
 
@@ -54,6 +57,9 @@ function processDependencies(): CliDependencies {
     console: terminalConsole(),
     writeStdout: (text) => process.stdout.write(text),
     stdin: () => process.stdin,
+    // `isatty` reads the descriptor without opening `process.stdin`, which would keep the
+    // process alive.
+    isStdinTerminal: () => isatty(STDIN_DESCRIPTOR),
     files: createNodeFileSystem(),
     redoclyConfigs: createRedoclyConfigSource(cwd),
     generate: generateTypes,

package/src/cli/redocly-apis.ts

@@ -2,9 +2,16 @@ 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,
+  apiRefLimitOptions,
+  FIX_SETTING,
+  OUTPUT_SETTING,
+  unknownSettingWarnings,
+} from "./api-settings.js";
 import { GENERATOR_FLAGS, type GeneratorFlags } from "./cli-arguments.js";
 import { cliError } from "./cli-errors.js";
-import { type CliRun, emitOutput, resolveFileUrl } from "./cli-output.js";
+import { type CliRun, emitOutput, resolveLocationUrl } from "./cli-output.js";
 import { MULTIPLE_SCHEMAS_DOCS_URL } from "./docs-links.js";
 import { fixNamesOf, fixOption } from "./fix-option.js";
 import { refLimitOptions } from "./ref-limits.js";
@@ -14,11 +21,6 @@ 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";
 
-/** The setting of an API that lists its output fixes. */
-const FIX_SETTING = "fix";
-
-type ApiSettings = Readonly<Record<string, unknown>>;
-
 interface RedoclyApi {
   readonly name: string;
   readonly root: string;
@@ -55,28 +57,36 @@ function apiFixNames(settings: ApiSettings): readonly OutputFixName[] | undefine
 
 /** 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 ? resolveFileUrl(redocly.configFile, cwd) : cwd;
+  return redocly.configFile ? resolveLocationUrl(redocly.configFile, cwd) : cwd;
 }
 
 async function generateApi(run: CliRun, redocly: RedoclyConfig, api: RedoclyApi): Promise<void> {
-  if (!api.settings?.output) {
+  if (!api.settings?.[OUTPUT_SETTING]) {
     throw cliError(
       "CLI_CONFIG_OUTPUT_MISSING",
       `API ${api.name} is missing an \`${REDOCLY_CONFIG_KEY}.output\` key. ` +
         `See ${MULTIPLE_SCHEMAS_DOCS_URL}`,
     );
   }
-  const output = String(api.settings.output);
+  for (const warning of unknownSettingWarnings(api.name, api.settings)) {
+    run.deps.logger.warn(warning);
+  }
+  const output = String(api.settings[OUTPUT_SETTING]);
   const configRoot = configRootOf(redocly, run.deps.cwd);
   const options: GeneratorOptions = {
     ...run.args.generatorFlags,
     ...apiFlags(api.settings),
     ...refLimitOptions(run.args, run.deps.cwd),
+    ...apiRefLimitOptions(api.name, api.settings, configRoot),
     ...fixOption(apiFixNames(api.settings) ?? run.args.fix),
     redocly,
   };
-  const contents = await run.deps.generate(new URL(api.root, configRoot), options);
-  emitOutput(run, { source: api.name, output, file: new URL(output, configRoot) }, contents);
+  const contents = await run.deps.generate(resolveLocationUrl(api.root, configRoot), options);
+  emitOutput(
+    run,
+    { source: api.name, output, file: resolveLocationUrl(output, configRoot) },
+    contents,
+  );
 }
 
 /**

package/src/cli/ref-limits.ts

@@ -1,6 +1,6 @@
 import type { GeneratorOptions } from "../types.js";
 import type { CliArguments } from "./cli-arguments.js";
-import { resolveFileUrl } from "./cli-output.js";
+import { resolveLocationUrl } from "./cli-output.js";
 
 /** The `$ref` limits of the CLI flags as generator options (threat model R1, R2, ADR-017). */
 
@@ -10,7 +10,7 @@ export type RefLimitOptions = Pick<GeneratorOptions, "localRefRoot" | "remoteRef
 export function refLimitOptions(args: CliArguments, cwd: URL): RefLimitOptions {
   const { localRefRoot, remoteRefHosts } = args.refLimits;
   return {
-    ...(localRefRoot === undefined ? {} : { localRefRoot: resolveFileUrl(localRefRoot, cwd) }),
+    ...(localRefRoot === undefined ? {} : { localRefRoot: resolveLocationUrl(localRefRoot, cwd) }),
     ...(remoteRefHosts === undefined ? {} : { remoteRefHosts }),
   };
 }

package/src/cli/run-cli.ts

@@ -1,9 +1,11 @@
 import type { Logger } from "../application/ports/logger.js";
 import type { RedoclyConfig } from "../application/ports/redocly-config-source.js";
+import { WARNING_CODES, warningText } from "../domain/warnings.js";
+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, resolveFileUrl } from "./cli-output.js";
+import { type CliRun, emitOutput, resolveLocationUrl } 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";
@@ -25,6 +27,22 @@ async function loadRedoclyConfig(run: CliRun): Promise<RedoclyConfig> {
   return configPath ? redoclyConfigs.load(configPath) : redoclyConfigs.createDefault();
 }
 
+/** The schema's URL, or stdin when no path or URL is given and something is piped in. */
+function schemaSource(run: CliRun): SchemaSource {
+  const { input } = run.args;
+  if (input) {
+    return resolveLocationUrl(input, run.deps.cwd);
+  }
+  if (run.deps.isStdinTerminal()) {
+    throw cliError(
+      "CLI_INPUT_MISSING",
+      "No schema given: pass a schema path or URL, pipe a schema into stdin, or define `apis` " +
+        "in redocly.yaml. See --help.",
+    );
+  }
+  return run.deps.stdin();
+}
+
 /** One schema from a path, a URL or stdin; without `--output`, the types go to stdout only. */
 async function generateSingleSchema(run: CliRun, redocly: RedoclyConfig): Promise<void> {
   const { input, output } = run.args;
@@ -42,7 +60,7 @@ async function generateSingleSchema(run: CliRun, redocly: RedoclyConfig): Promis
       "--check needs the generated file to compare with: add --output <file>.",
     );
   }
-  const source = input ? new URL(input, run.deps.cwd) : run.deps.stdin();
+  const source = schemaSource(run);
   const options = {
     ...run.args.generatorFlags,
     ...refLimitOptions(run.args, run.deps.cwd),
@@ -55,7 +73,7 @@ async function generateSingleSchema(run: CliRun, redocly: RedoclyConfig): Promis
     run.deps.writeStdout(contents);
     return;
   }
-  const file = resolveFileUrl(output, run.deps.cwd);
+  const file = resolveLocationUrl(output, run.deps.cwd);
   emitOutput(run, { source: input ?? "stdin", output, file }, contents);
 }
 
@@ -67,7 +85,10 @@ async function generate(run: CliRun): Promise<unknown[]> {
   }
   if (run.args.input) {
     run.deps.logger.warn(
-      "APIs are specified both in Redocly Config and CLI argument. Only using Redocly config.",
+      warningText(
+        "APIs are specified both in Redocly Config and CLI argument. Only using Redocly config.",
+        WARNING_CODES.CLI_INPUT_IGNORED,
+      ),
     );
   }
   return generateRedoclyApis(run, redocly);

package/src/domain/errors.ts

@@ -1,3 +1,5 @@
+import { redactUrlCredentials } from "./url-credentials.js";
+
 /**
  * Typed errors (ENGINEERING_PLAN 4.6, ADR-011). Every expected failure of the generator and the CLI
  * is an `OpenAPITypesafeError` with a stable machine-readable `code` and structured `details`. The
@@ -26,8 +28,10 @@ export const ERROR_CODES = {
   CLI_FLAG_REMOVED: "CLI_FLAG_REMOVED",
   CLI_GLOB_UNSUPPORTED: "CLI_GLOB_UNSUPPORTED",
   CLI_CONFIG_NOT_FOUND: "CLI_CONFIG_NOT_FOUND",
+  CLI_CONFIG_INVALID: "CLI_CONFIG_INVALID",
   CLI_CONFIG_OUTPUT_MISSING: "CLI_CONFIG_OUTPUT_MISSING",
   CLI_CHECK_OUTPUT_MISSING: "CLI_CHECK_OUTPUT_MISSING",
+  CLI_INPUT_MISSING: "CLI_INPUT_MISSING",
   OUTPUT_STALE: "OUTPUT_STALE",
   OUTPUT_READ_FAILED: "OUTPUT_READ_FAILED",
   OUTPUT_WRITE_FAILED: "OUTPUT_WRITE_FAILED",
@@ -46,13 +50,17 @@ export interface OpenAPITypesafeErrorInit {
   readonly cause?: unknown;
 }
 
-/** The base of every expected failure; check `code`, not the class or the message. */
+/**
+ * The base of every expected failure; check `code`, not the class or the message. The message
+ * never shows the user info of a URL (`url-credentials.ts`).
+ */
 export class OpenAPITypesafeError extends Error {
   readonly code: ErrorCode;
   readonly details: ErrorDetails;
 
   constructor(init: OpenAPITypesafeErrorInit) {
-    super(init.message, init.cause === undefined ? undefined : { cause: init.cause });
+    const message = redactUrlCredentials(init.message);
+    super(message, init.cause === undefined ? undefined : { cause: init.cause });
     this.name = "OpenAPITypesafeError";
     this.code = init.code;
     this.details = init.details ?? {};

package/src/domain/ir/constructors.ts

@@ -33,6 +33,9 @@ export function irKeyword(keyword: IrKeyword): IrKeywordType {
   return { kind: "keyword", keyword };
 }
 
+/** The encoding of a string literal that does not name one. */
+export const DEFAULT_STRING_ENCODING: IrStringEncoding = "json";
+
 export function irString(value: string, encoding: IrStringEncoding): IrStringLiteralType {
   return { kind: "stringLiteral", value, encoding };
 }
@@ -62,7 +65,12 @@ export function irTuple(elements: readonly IrTupleElement[]): IrTupleType {
 }
 
 export function irTupleElement(type: IrType, isRest = false): IrTupleElement {
-  return { type, isRest };
+  return { type, isRest, isOptional: false };
+}
+
+/** `T?`: an element the tuple may end before. */
+export function irOptionalTupleElement(type: IrType): IrTupleElement {
+  return { type, isRest: false, isOptional: true };
 }
 
 export function irUnion(types: readonly IrType[]): IrUnionType {