openapi-typesafe 0.0.0 → 1.0.0-rc.0

package/src/cli/cli-errors.ts

@@ -0,0 +1,125 @@
+import {
+  ERROR_CODES,
+  type ErrorCode,
+  isOpenAPITypesafeError,
+  OpenAPITypesafeError,
+} from "../domain/errors.js";
+
+/**
+ * How the CLI reports a failure (ENGINEERING_PLAN 4.6, ADR-011): each error code maps to a process
+ * exit code and the line printed for it. The table is exhaustive, so a new error code does not
+ * compile until the CLI handles it.
+ */
+
+/** Process exit codes of the CLI, documented in docs/cli.md. */
+export const EXIT_CODES = {
+  SUCCESS: 0,
+  /** `--check` found output that differs from the generated types (as in the original CLI). */
+  OUTPUT_STALE: 1,
+  /** A flag, the Redocly config, the environment or a callback is wrong. */
+  USAGE: 2,
+  /** The OpenAPI document cannot be read, is invalid, or cannot be converted. */
+  SCHEMA: 3,
+  /** An output file cannot be read or written. */
+  OUTPUT: 4,
+  /** An unexpected failure: a bug in the generator (sysexits `EX_SOFTWARE`). */
+  INTERNAL: 70,
+} as const;
+
+export type ExitCode = (typeof EXIT_CODES)[keyof typeof EXIT_CODES];
+
+interface CliErrorReport {
+  readonly exitCode: ExitCode;
+  /** The printed text; the error's own message when absent. */
+  readonly message?: (error: OpenAPITypesafeError) => string;
+}
+
+/** Problems are printed one by one while linting, so the summary only counts them. */
+function schemaInvalidMessage(error: OpenAPITypesafeError): string {
+  const count = Array.isArray(error.details.problems) ? error.details.problems.length : 1;
+  return `The OpenAPI document has ${count} ${count === 1 ? "error" : "errors"} (see above)`;
+}
+
+/**
+ * Node's `fetch` fails with only "fetch failed"; the network reason (refused, DNS, TLS) is the
+ * cause of that error. The Node API keeps the original message, so only the CLI adds it.
+ */
+function loadFailedMessage(error: OpenAPITypesafeError): string {
+  const reason = error.cause instanceof Error ? error.cause.cause : undefined;
+  if (!(reason instanceof Error)) {
+    return error.message;
+  }
+  const source = typeof error.details.source === "string" ? ` (${error.details.source})` : "";
+  return `${error.message}: ${reason.message}${source}`;
+}
+
+/** The message js-yaml throws at its nesting limit (docs/security/threat-model.md T2). */
+const YAML_DEPTH_LIMIT_MESSAGE = /nesting exceeded maxDepth \((\d+)\)/;
+
+/** The parser's message says the limit, not how to stay under it. */
+function parseFailedMessage(error: OpenAPITypesafeError): string {
+  const limit = YAML_DEPTH_LIMIT_MESSAGE.exec(error.message)?.[1];
+  if (limit === undefined) {
+    return error.message;
+  }
+  return (
+    `${error.message}. The YAML parser reads at most ${limit} nested levels: ` +
+    "move nested schemas to `components` and reference them with `$ref`"
+  );
+}
+
+const CLI_ERROR_REPORTS: Readonly<Record<ErrorCode, CliErrorReport>> = {
+  SCHEMA_SOURCE_EMPTY: { exitCode: EXIT_CODES.SCHEMA },
+  SCHEMA_SOURCE_INVALID: { exitCode: EXIT_CODES.SCHEMA },
+  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 },
+  SCHEMA_INVALID: { exitCode: EXIT_CODES.SCHEMA, message: schemaInvalidMessage },
+  SCHEMA_REF_INVALID: { exitCode: EXIT_CODES.SCHEMA },
+  SCHEMA_REF_FORBIDDEN: { exitCode: EXIT_CODES.SCHEMA },
+  SCHEMA_OBJECT_INVALID: { exitCode: EXIT_CODES.SCHEMA },
+  SCHEMA_PROPERTY_INVALID: { exitCode: EXIT_CODES.SCHEMA },
+  SCHEMA_TOO_DEEP: { exitCode: EXIT_CODES.SCHEMA },
+  SCHEMA_KEY_UNSUPPORTED: { exitCode: EXIT_CODES.SCHEMA },
+  ENUM_NAME_EMPTY: { exitCode: EXIT_CODES.SCHEMA },
+  CALLBACK_RESULT_UNREADABLE: { exitCode: EXIT_CODES.USAGE },
+  OPTION_FIX_UNKNOWN: { exitCode: EXIT_CODES.USAGE },
+  TYPESCRIPT_NOT_FOUND: { exitCode: EXIT_CODES.USAGE },
+  CLI_FLAG_REMOVED: { exitCode: EXIT_CODES.USAGE },
+  CLI_GLOB_UNSUPPORTED: { exitCode: EXIT_CODES.USAGE },
+  CLI_CONFIG_NOT_FOUND: { exitCode: EXIT_CODES.USAGE },
+  CLI_CONFIG_OUTPUT_MISSING: { exitCode: EXIT_CODES.USAGE },
+  CLI_CHECK_OUTPUT_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 },
+};
+
+/** What the CLI prints and returns for a thrown value. */
+export interface CliFailure {
+  readonly exitCode: ExitCode;
+  readonly message: string;
+}
+
+/**
+ * Map a thrown value to the CLI's output. A typed error prints one line with its code; anything
+ * else is a bug and prints its stack, so it can be reported.
+ */
+export function describeCliFailure(error: unknown): CliFailure {
+  if (!isOpenAPITypesafeError(error)) {
+    const text = error instanceof Error ? (error.stack ?? error.message) : String(error);
+    return { exitCode: EXIT_CODES.INTERNAL, message: `Unexpected error: ${text}` };
+  }
+  const report = CLI_ERROR_REPORTS[error.code];
+  const message = report.message?.(error) ?? error.message;
+  return { exitCode: report.exitCode, message: `${message} (${error.code})` };
+}
+
+/** Errors of the CLI itself; its messages are the original CLI's messages. */
+export function cliError(
+  code: Extract<ErrorCode, `CLI_${string}` | `OUTPUT_${string}`>,
+  message: string,
+  cause?: unknown,
+): OpenAPITypesafeError {
+  return new OpenAPITypesafeError({ code: ERROR_CODES[code], message, cause });
+}

package/src/cli/cli-output.ts

@@ -0,0 +1,53 @@
+import path from "node:path";
+import { 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";
+import { cliError } from "./cli-errors.js";
+
+/** Writing one generated file, or checking it with `--check`, and the line printed for it. */
+
+/** One CLI run: its dependencies, its arguments and when it started. */
+export interface CliRun {
+  readonly deps: CliDependencies;
+  readonly args: CliArguments;
+  readonly startedAt: number;
+}
+
+/** A generated file: `source` names the schema and `output` is the path as the user wrote it. */
+export interface OutputFile {
+  readonly source: string;
+  readonly output: string;
+  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);
+}
+
+function printDone(run: CliRun, output: OutputFile): void {
+  const { style, now } = run.deps;
+  const target = style.green(`${output.source} → ${style.bold(output.output)}`);
+  const duration = style.dim(`[${formatDuration(now() - run.startedAt)}]`);
+  run.deps.console.info(`🚀 ${target} ${duration}`);
+}
+
+/**
+ * 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.
+ */
+export function emitOutput(run: CliRun, output: OutputFile, contents: string): void {
+  if (run.args.isCheck) {
+    if (run.deps.files.readText(output.file) !== contents) {
+      // The original message, then the file: with several APIs it tells which one is stale.
+      throw cliError(
+        "OUTPUT_STALE",
+        `Generated types are not up-to-date! ${output.output} differs from its schema.`,
+      );
+    }
+    return;
+  }
+  run.deps.files.writeText(output.file, contents);
+  printDone(run, output);
+}

package/src/cli/docs-links.ts

@@ -0,0 +1,6 @@
+/**
+ * Links that CLI messages print. They point at the docs in this repository on GitHub, which work
+ * before the docs site is published and stay valid after.
+ */
+export const MULTIPLE_SCHEMAS_DOCS_URL =
+  "https://github.com/openapi-typesafe/openapi-typesafe/blob/main/docs/cli.md#multiple-schemas";

package/src/cli/fix-option.ts

@@ -0,0 +1,29 @@
+import { type OutputFixName, outputFixNamesOf } from "../domain/output-fixes.js";
+import type { GeneratorOptions } from "../types.js";
+
+/**
+ * The `fix` option (ADR-021) as the CLI and `redocly.yaml` give it: `--fix a,b`, repeatable, or
+ * `fix: [a, b]` / `fix: a,b` in an API's settings. Unknown names fail with `OPTION_FIX_UNKNOWN`.
+ */
+
+const SEPARATOR = ",";
+
+/** The names of a flag value or a config value; `undefined` when the option is not set. */
+export function fixNamesOf(value: unknown): readonly OutputFixName[] | undefined {
+  if (value === undefined) {
+    return undefined;
+  }
+  const names = [value]
+    .flat()
+    .flatMap((entry) => String(entry).split(SEPARATOR))
+    .map((name) => name.trim())
+    .filter((name) => name !== "");
+  return outputFixNamesOf(names);
+}
+
+/** The generator option for the names; nothing when the option is not set. */
+export function fixOption(
+  names: readonly OutputFixName[] | undefined,
+): Pick<GeneratorOptions, "fix"> {
+  return names === undefined ? {} : { fix: names };
+}

package/src/cli/help-text.ts

@@ -0,0 +1,52 @@
+/** The text of `--help`, as in the original CLI; long lines are split only in this source. */
+export const HELP_TEXT = [
+  "Usage",
+  "  $ openapi-typesafe [input] [options]",
+  "",
+  "Options",
+  "  --help                     Display this",
+  "  --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)",
+  "  --enum                     Export true TS enums instead of unions",
+  "  --enum-values              Export enum values as arrays",
+  "  --conditional-enums        Only generate true TS enums when enum" +
+    " metadata is available (default: false)",
+  "  --dedupe-enums             Dedupe enum types when `--enum=true` is set",
+  "  --check                    Check that the generated types are" +
+    " up-to-date. (default: false)",
+  "  --export-type, -t          Export top-level `type` instead of `interface`",
+  "  --immutable                Generate readonly types",
+  "  --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",
+  "  --properties-required-by-default",
+  "                             Treat schema objects as if `required` is" +
+    " set to all properties by default",
+  "  --array-length             Generate tuples using array minItems / maxItems",
+  "  --binary-as-blob           Type raw binary strings (format: binary," +
+    " contentMediaType) as Blob",
+  "  --fix [names]              Turn on output fixes, comma-separated, or" +
+    ' "all" (see docs/cli.md#fix)',
+  "  --path-params-as-types     Convert paths to template literal types",
+  "  --generate-path-params     Generate path parameters for all paths where they are" +
+    " undefined by schema",
+  "  --alphabetize              Sort object keys alphabetically",
+  "  --exclude-deprecated       Exclude deprecated types",
+  "  --root-types               Export schemas types at root level",
+  "  --root-types-no-schema-prefix",
+  '                             Do not add "Schema" prefix to types at' +
+    " the root level (should only be used with --root-types)",
+  "  --root-types-keep-casing   Keep casing of root types (should only be" +
+    " used with --root-types)",
+  "  --make-paths-enum          Generate ApiPaths enum for all paths",
+  "  --read-write-markers       Generate $Read/$Write markers for" +
+    " readOnly/writeOnly properties",
+  "  --no-lint                  Skip the Redocly lint (bundling errors still fail)",
+  "  --local-ref-root [dir]     Load local $ref files only from this directory",
+  "  --remote-ref-hosts [hosts] Load remote $ref documents only from these" +
+    " comma-separated hosts (empty: none)",
+  "",
+].join("\n");

package/src/cli/main.ts

@@ -0,0 +1,67 @@
+import fs from "node:fs";
+import { pathToFileURL } from "node:url";
+import colors from "ansi-colors";
+import { createNodeFileSystem } from "../adapters/node-file-system/node-file-system.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 openapiTS from "../api/openapi-ts.js";
+import type { CliConsole, CliDependencies, GenerateTypes, TextStyle } from "./cli-dependencies.js";
+import { runCli } from "./run-cli.js";
+
+/**
+ * The CLI's composition root (ENGINEERING_PLAN 4.5, ADR-012): the only CLI module that touches the
+ * process. `bin/cli.js` imports the built copy of this module.
+ */
+
+/** The same path from `src/cli/` and from the built `dist/cli/`. */
+const PACKAGE_JSON = new URL("../../package.json", import.meta.url);
+
+function readVersion(): string {
+  const packageJson: { version: string } = JSON.parse(fs.readFileSync(PACKAGE_JSON, "utf8"));
+  return packageJson.version;
+}
+
+function terminalStyle(): TextStyle {
+  const palette = colors.create();
+  palette.enabled = terminalSupportsColor();
+  return {
+    bold: (text) => palette.bold(text),
+    green: (text) => palette.green(text),
+    dim: (text) => palette.dim(text),
+  };
+}
+
+const generateTypes: GenerateTypes = async (source, options) =>
+  `${COMMENT_HEADER}${astToString(await openapiTS(source, options))}`;
+
+function terminalConsole(): CliConsole {
+  return {
+    // biome-ignore lint/suspicious/noConsole: the CLI's own output lines
+    info: (text) => console.info(text),
+    // biome-ignore lint/suspicious/noConsole: the CLI's own notices
+    notice: (text) => console.warn(text),
+  };
+}
+
+function processDependencies(): CliDependencies {
+  const cwd = process.cwd();
+  return {
+    cwd: pathToFileURL(`${cwd}/`),
+    version: readVersion(),
+    logger: defaultLogger(false),
+    console: terminalConsole(),
+    writeStdout: (text) => process.stdout.write(text),
+    stdin: () => process.stdin,
+    files: createNodeFileSystem(),
+    redoclyConfigs: createRedoclyConfigSource(cwd),
+    generate: generateTypes,
+    now: monotonicNow,
+    style: terminalStyle(),
+  };
+}
+
+runCli(process.argv.slice(2), processDependencies()).then((exitCode) => {
+  process.exitCode = exitCode;
+});

package/src/cli/redocly-apis.ts

@@ -0,0 +1,91 @@
+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 { GENERATOR_FLAGS, type GeneratorFlags } from "./cli-arguments.js";
+import { cliError } from "./cli-errors.js";
+import { type CliRun, emitOutput, resolveFileUrl } 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";
+
+/** The `apis` of a Redocly config: each API is generated into its `x-openapi-ts.output`. */
+
+/** 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;
+  readonly settings: ApiSettings | undefined;
+}
+
+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 };
+  });
+}
+
+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;
+}
+
+/** 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]);
+}
+
+/** 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;
+}
+
+async function generateApi(run: CliRun, redocly: RedoclyConfig, api: RedoclyApi): Promise<void> {
+  if (!api.settings?.output) {
+    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);
+  const configRoot = configRootOf(redocly, run.deps.cwd);
+  const options: GeneratorOptions = {
+    ...run.args.generatorFlags,
+    ...apiFlags(api.settings),
+    ...refLimitOptions(run.args, run.deps.cwd),
+    ...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);
+}
+
+/**
+ * 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.
+ */
+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] : []));
+}

package/src/cli/ref-limits.ts

@@ -0,0 +1,16 @@
+import type { GeneratorOptions } from "../types.js";
+import type { CliArguments } from "./cli-arguments.js";
+import { resolveFileUrl } from "./cli-output.js";
+
+/** The `$ref` limits of the CLI flags as generator options (threat model R1, R2, ADR-017). */
+
+export type RefLimitOptions = Pick<GeneratorOptions, "localRefRoot" | "remoteRefHosts">;
+
+/** `--local-ref-root` resolves against the working directory, like every other CLI path. */
+export function refLimitOptions(args: CliArguments, cwd: URL): RefLimitOptions {
+  const { localRefRoot, remoteRefHosts } = args.refLimits;
+  return {
+    ...(localRefRoot === undefined ? {} : { localRefRoot: resolveFileUrl(localRefRoot, cwd) }),
+    ...(remoteRefHosts === undefined ? {} : { remoteRefHosts }),
+  };
+}

package/src/cli/run-cli.ts

@@ -0,0 +1,114 @@
+import type { Logger } from "../application/ports/logger.js";
+import type { RedoclyConfig } from "../application/ports/redocly-config-source.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 { MULTIPLE_SCHEMAS_DOCS_URL } from "./docs-links.js";
+import { fixOption } from "./fix-option.js";
+import { HELP_TEXT } from "./help-text.js";
+import { generateRedoclyApis, hasRedoclyApis } from "./redocly-apis.js";
+import { refLimitOptions } from "./ref-limits.js";
+
+/**
+ * The CLI's use case: parse the arguments, then generate the APIs of the Redocly config, one
+ * schema file or URL, or stdin. It has no process access of its own; `main.ts` wires it (ADR-012).
+ */
+
+async function loadRedoclyConfig(run: CliRun): Promise<RedoclyConfig> {
+  const { redoclyConfigs } = run.deps;
+  const explicitPath = run.args.redocly;
+  const configPath = redoclyConfigs.find(explicitPath);
+  if (explicitPath && !configPath) {
+    throw cliError("CLI_CONFIG_NOT_FOUND", `Redocly config not found at: ${explicitPath}`);
+  }
+  return configPath ? redoclyConfigs.load(configPath) : redoclyConfigs.createDefault();
+}
+
+/** 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;
+  if (input?.includes("*")) {
+    throw cliError(
+      "CLI_GLOB_UNSUPPORTED",
+      "Globbing has been deprecated in favor of redocly.yaml’s `apis` keys. " +
+        `See ${MULTIPLE_SCHEMAS_DOCS_URL}`,
+    );
+  }
+  if (run.args.isCheck && !output) {
+    // Without a file there is nothing to compare: the original printed the types and passed.
+    throw cliError(
+      "CLI_CHECK_OUTPUT_MISSING",
+      "--check needs the generated file to compare with: add --output <file>.",
+    );
+  }
+  const source = input ? new URL(input, run.deps.cwd) : run.deps.stdin();
+  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);
+    return;
+  }
+  const file = resolveFileUrl(output, run.deps.cwd);
+  emitOutput(run, { source: input ?? "stdin", output, file }, contents);
+}
+
+async function generate(run: CliRun): Promise<unknown[]> {
+  const redocly = await loadRedoclyConfig(run);
+  if (!hasRedoclyApis(redocly)) {
+    await generateSingleSchema(run, redocly);
+    return [];
+  }
+  if (run.args.input) {
+    run.deps.logger.warn(
+      "APIs are specified both in Redocly Config and CLI argument. Only using Redocly config.",
+    );
+  }
+  return generateRedoclyApis(run, redocly);
+}
+
+/** Run the command; the failures it returns did not stop the other outputs. */
+async function runCommand(argv: readonly string[], deps: CliDependencies): Promise<unknown[]> {
+  const startedAt = deps.now();
+  for (const notice of ineffectiveFlagNotices(argv)) {
+    deps.console.notice(notice);
+  }
+  const args = parseCliArguments(argv);
+  for (const flag of args.unknownFlags) {
+    deps.console.notice(`Unknown flag ${flag} is ignored (see --help)`);
+  }
+  if (args.isHelp || args.isVersion) {
+    deps.console.info(args.isHelp ? HELP_TEXT : `v${deps.version}`);
+    return [];
+  }
+  if (args.output) {
+    deps.console.info(`✨ ${deps.style.bold(`openapi-typesafe ${deps.version}`)}`);
+  }
+  return generate({ deps, args, startedAt });
+}
+
+/** Print one line per failure; the exit code is the first failure's (ADR-011). */
+function reportFailures(failures: readonly unknown[], logger: Logger): ExitCode {
+  const reports = failures.map(describeCliFailure);
+  for (const report of reports) {
+    logger.error(report.message);
+  }
+  return reports[0]?.exitCode ?? EXIT_CODES.SUCCESS;
+}
+
+/** Run the CLI with the arguments after `node cli.js`, and return the process exit code. */
+export async function runCli(argv: readonly string[], deps: CliDependencies): Promise<ExitCode> {
+  let failures: unknown[];
+  try {
+    failures = await runCommand(argv, deps);
+  } catch (thrown) {
+    failures = [thrown];
+  }
+  return reportFailures(failures, deps.logger);
+}

package/src/domain/assert-never.ts

@@ -0,0 +1,8 @@
+/**
+ * Exhaustiveness guard for `switch` over a closed union: the call compiles only when every variant
+ * is handled. Reaching it at run time means a value outside the union, which is a bug, so it
+ * throws.
+ */
+export function assertNever(value: never): never {
+  throw new Error(`Unexpected variant: ${JSON.stringify(value)}`);
+}

package/src/domain/errors.ts

@@ -0,0 +1,74 @@
+/**
+ * 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
+ * `message` is English text for people; programs and the CLI decide by `code`. A bug (a broken
+ * invariant) is a plain `Error`, not one of these.
+ */
+
+/** Every error code. The set is closed: a new code must be handled by the CLI exit-code table. */
+export const ERROR_CODES = {
+  SCHEMA_SOURCE_EMPTY: "SCHEMA_SOURCE_EMPTY",
+  SCHEMA_SOURCE_INVALID: "SCHEMA_SOURCE_INVALID",
+  SCHEMA_LOAD_FAILED: "SCHEMA_LOAD_FAILED",
+  SCHEMA_PARSE_FAILED: "SCHEMA_PARSE_FAILED",
+  SCHEMA_VERSION_UNSUPPORTED: "SCHEMA_VERSION_UNSUPPORTED",
+  SCHEMA_INVALID: "SCHEMA_INVALID",
+  SCHEMA_REF_INVALID: "SCHEMA_REF_INVALID",
+  SCHEMA_REF_FORBIDDEN: "SCHEMA_REF_FORBIDDEN",
+  SCHEMA_OBJECT_INVALID: "SCHEMA_OBJECT_INVALID",
+  SCHEMA_PROPERTY_INVALID: "SCHEMA_PROPERTY_INVALID",
+  SCHEMA_TOO_DEEP: "SCHEMA_TOO_DEEP",
+  SCHEMA_KEY_UNSUPPORTED: "SCHEMA_KEY_UNSUPPORTED",
+  ENUM_NAME_EMPTY: "ENUM_NAME_EMPTY",
+  CALLBACK_RESULT_UNREADABLE: "CALLBACK_RESULT_UNREADABLE",
+  OPTION_FIX_UNKNOWN: "OPTION_FIX_UNKNOWN",
+  TYPESCRIPT_NOT_FOUND: "TYPESCRIPT_NOT_FOUND",
+  CLI_FLAG_REMOVED: "CLI_FLAG_REMOVED",
+  CLI_GLOB_UNSUPPORTED: "CLI_GLOB_UNSUPPORTED",
+  CLI_CONFIG_NOT_FOUND: "CLI_CONFIG_NOT_FOUND",
+  CLI_CONFIG_OUTPUT_MISSING: "CLI_CONFIG_OUTPUT_MISSING",
+  CLI_CHECK_OUTPUT_MISSING: "CLI_CHECK_OUTPUT_MISSING",
+  OUTPUT_STALE: "OUTPUT_STALE",
+  OUTPUT_READ_FAILED: "OUTPUT_READ_FAILED",
+  OUTPUT_WRITE_FAILED: "OUTPUT_WRITE_FAILED",
+} as const;
+
+export type ErrorCode = (typeof ERROR_CODES)[keyof typeof ERROR_CODES];
+
+/** Structured, JSON-serializable facts about a failure, for programs and logs. */
+export type ErrorDetails = Readonly<Record<string, unknown>>;
+
+export interface OpenAPITypesafeErrorInit {
+  readonly code: ErrorCode;
+  readonly message: string;
+  readonly details?: ErrorDetails;
+  /** The lower-level error this one reports, if any (kept as the standard `cause`). */
+  readonly cause?: unknown;
+}
+
+/** The base of every expected failure; check `code`, not the class or the message. */
+export class OpenAPITypesafeError extends Error {
+  readonly code: ErrorCode;
+  readonly details: ErrorDetails;
+
+  constructor(init: OpenAPITypesafeErrorInit) {
+    super(init.message, init.cause === undefined ? undefined : { cause: init.cause });
+    this.name = "OpenAPITypesafeError";
+    this.code = init.code;
+    this.details = init.details ?? {};
+  }
+}
+
+/** Whether a thrown value is one of our typed errors (also across bundled copies of the class). */
+export function isOpenAPITypesafeError(value: unknown): value is OpenAPITypesafeError {
+  if (value instanceof OpenAPITypesafeError) {
+    return true;
+  }
+  const code = (value as { code?: unknown } | null)?.code;
+  return (
+    value instanceof Error &&
+    typeof code === "string" &&
+    Object.hasOwn(ERROR_CODES, code) &&
+    typeof (value as { details?: unknown }).details === "object"
+  );
+}