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

package/src/cli/redocly-apis.ts

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

package/src/cli/run-cli.ts

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

package/src/domain/append-all.ts

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

package/src/domain/cause-secrets.ts

@@ -0,0 +1,52 @@
+import { redactUrlSecrets } from "./url-secrets.js";
+
+/**
+ * The `cause` of a typed error is shown wherever the error is: `console.error(error)` and
+ * `util.inspect` print the whole chain, and error trackers send it. A lower-level error names the
+ * URL it failed on (fetch refuses `https://user:token@host/…` and quotes it), so the chain must
+ * hide the same secrets as the message (url-secrets.ts).
+ */
+
+/** A string with its URL secrets hidden; any other value as it is. */
+function redactedValue(value: unknown): unknown {
+  return typeof value === "string" ? redactUrlSecrets(value) : value;
+}
+
+/**
+ * A copy of `error` of the same class, its own properties (`message`, `stack`, `code`, `input`, a
+ * nested `cause`) with URL secrets hidden, or `error` itself when none of them holds one. Each
+ * property is read through its getter (V8 keeps `stack` behind one) and copied as a value.
+ */
+function redactedError(error: Error, seen: ReadonlySet<Error>): Error {
+  const inner = new Set([...seen, error]);
+  // A real error with the class of `error`, so `util.inspect` and `util.types.isNativeError`
+  // treat it as one.
+  const copy = Object.setPrototypeOf(new Error(), Object.getPrototypeOf(error)) as Error;
+  let isChanged = false;
+  for (const key of Reflect.ownKeys(error)) {
+    const value: unknown = Reflect.get(error, key);
+    const shown = key === "cause" ? redactedCauseIn(value, inner) : redactedValue(value);
+    isChanged ||= shown !== value;
+    const enumerable = Object.getOwnPropertyDescriptor(error, key)?.enumerable === true;
+    Object.defineProperty(copy, key, {
+      value: shown,
+      enumerable,
+      writable: true,
+      configurable: true,
+    });
+  }
+  return isChanged ? copy : error;
+}
+
+function redactedCauseIn(cause: unknown, seen: ReadonlySet<Error>): unknown {
+  if (!(cause instanceof Error)) {
+    return redactedValue(cause);
+  }
+  // A chain that loops back is cut where it does, so the copy is finite.
+  return seen.has(cause) ? undefined : redactedError(cause, seen);
+}
+
+/** The cause of a typed error with the URL secrets of its whole chain hidden. */
+export function redactCauseSecrets(cause: unknown): unknown {
+  return redactedCauseIn(cause, new Set());
+}

package/src/domain/errors.ts

@@ -1,4 +1,5 @@
-import { redactUrlCredentials } from "./url-credentials.js";
+import { redactCauseSecrets } from "./cause-secrets.js";
+import { redactUrlSecrets } from "./url-secrets.js";
 
 /**
  * Typed errors (ENGINEERING_PLAN 4.6, ADR-011). Every expected failure of the generator and the CLI
@@ -35,6 +36,10 @@ export const ERROR_CODES = {
   CLI_CONFIG_OUTPUT_MISSING: "CLI_CONFIG_OUTPUT_MISSING",
   CLI_CHECK_OUTPUT_MISSING: "CLI_CHECK_OUTPUT_MISSING",
   CLI_INPUT_MISSING: "CLI_INPUT_MISSING",
+  CLI_OUTPUT_IS_INPUT: "CLI_OUTPUT_IS_INPUT",
+  CLI_OUTPUT_DUPLICATE: "CLI_OUTPUT_DUPLICATE",
+  CLI_OUTPUT_INVALID: "CLI_OUTPUT_INVALID",
+  CLI_LOCATION_INVALID: "CLI_LOCATION_INVALID",
   OUTPUT_STALE: "OUTPUT_STALE",
   OUTPUT_READ_FAILED: "OUTPUT_READ_FAILED",
   OUTPUT_WRITE_FAILED: "OUTPUT_WRITE_FAILED",
@@ -52,21 +57,25 @@ 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`). */
+  /**
+   * The lower-level error this one reports, if any (kept as the standard `cause`; a copy with URL
+   * secrets hidden when its chain names one, see cause-secrets.ts).
+   */
   readonly cause?: unknown;
 }
 
 /**
  * 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`).
+ * and the `cause` chain never show the user info or the query of a URL (`url-secrets.ts`).
  */
 export class OpenAPITypesafeError extends Error {
   readonly code: ErrorCode;
   readonly details: ErrorDetails;
 
   constructor(init: OpenAPITypesafeErrorInit) {
-    const message = redactUrlCredentials(init.message);
-    super(message, init.cause === undefined ? undefined : { cause: init.cause });
+    const message = redactUrlSecrets(init.message);
+    const cause = redactCauseSecrets(init.cause);
+    super(message, cause === undefined ? undefined : { cause });
     this.name = "OpenAPITypesafeError";
     this.code = init.code;
     this.details = init.details ?? {};

package/src/domain/ir/identifier-text.ts

@@ -2,11 +2,12 @@ import { NEWER_IDENTIFIER_PART, NEWER_IDENTIFIER_START } from "./newer-identifie
 
 /**
  * Identifier rules of ECMAScript (Unicode `ID_Start` / `ID_Continue`, plus `$`, `_`, ZWNJ and
- * ZWJ), for names built from document text, without the characters that TypeScript's scanner
- * does not know yet. Node.js follows a newer Unicode version than TypeScript's identifier tables,
- * so a name such as `꟒Name` (Unicode 17) passed here and failed to parse with "Invalid
- * character" (ADR-019). Removing the newer characters also gives the same names on every
- * supported Node.js version.
+ * ZWJ), for names built from document text, without the characters that the scanner of the lowest
+ * supported TypeScript (5.4) does not know. Node.js follows a newer Unicode version than
+ * TypeScript's identifier tables, so a name such as `꟒Name` (Unicode 17) passed here and failed to
+ * parse with "Invalid character" (ADR-019); TypeScript 5.4 also rejects ZWJ and characters that
+ * TypeScript 6 accepts. Removing these also gives the same names on every supported Node.js
+ * version.
  */
 
 const IDENTIFIER_START_RE = new RegExp(