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

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/cli-arguments.ts

@@ -165,13 +165,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 +203,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/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

@@ -4,7 +4,7 @@ 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 { 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";
@@ -55,7 +55,7 @@ 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> {
@@ -75,8 +75,12 @@ async function generateApi(run: CliRun, redocly: RedoclyConfig, api: RedoclyApi)
     ...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,10 @@
 import type { Logger } from "../application/ports/logger.js";
 import type { RedoclyConfig } from "../application/ports/redocly-config-source.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 +26,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 +59,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 +72,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);
 }
 

package/src/domain/errors.ts

@@ -26,8 +26,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",

package/src/domain/ir/constructors.ts

@@ -62,7 +62,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 {

package/src/domain/ir/nodes.ts

@@ -61,10 +61,11 @@ export interface IrArrayType {
   readonly element: IrType;
 }
 
-/** A tuple element; `isRest` prints `...T`. */
+/** A tuple element; `isRest` prints `...T`, `isOptional` prints `T?` (never both). */
 export interface IrTupleElement {
   readonly type: IrType;
   readonly isRest: boolean;
+  readonly isOptional: boolean;
 }
 
 export interface IrTupleType {

package/src/domain/openapi/admitted-values.ts

@@ -0,0 +1,113 @@
+import { parseRefPointer } from "./json-pointer.js";
+
+/**
+ * The values a schema admits when it admits only finitely many (`enum`, `const`, and `allOf` /
+ * `anyOf` / `oneOf` of those), read from the document. Null means "any value" as far as this
+ * reading goes: a schema of any other shape, or a `$ref` it cannot follow, is never assumed to
+ * exclude a value.
+ */
+
+export type AdmittedValue = string | number | boolean | null;
+/** A finite set of values, or null for every value. */
+export type AdmittedValues = ReadonlySet<AdmittedValue> | null;
+
+type JsonObject = Readonly<Record<string, unknown>>;
+
+/** How deep `$ref`s and compositions are followed; deeper schemas admit every value. */
+const MAX_DEPTH = 16;
+const LOCAL_REF_PREFIX = "#/";
+
+function isObject(value: unknown): value is JsonObject {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+/** The node at a local `$ref` (`#/...`) of the document, or undefined. */
+export function resolveLocalRef(document: unknown, ref: string): unknown {
+  if (!ref.startsWith(LOCAL_REF_PREFIX)) {
+    return undefined;
+  }
+  let node: unknown = document;
+  for (const segment of parseRefPointer(ref)) {
+    node = isObject(node) || Array.isArray(node) ? (node as JsonObject)[segment] : undefined;
+  }
+  return node;
+}
+
+function intersect(left: AdmittedValues, right: AdmittedValues): AdmittedValues {
+  if (left === null || right === null) {
+    return left ?? right;
+  }
+  return new Set([...left].filter((value) => right.has(value)));
+}
+
+function unite(sets: readonly AdmittedValues[]): AdmittedValues {
+  return sets.some((set) => set === null) ? null : new Set(sets.flatMap((set) => [...(set ?? [])]));
+}
+
+function isAdmittedValue(value: unknown): value is AdmittedValue {
+  return value === null || ["string", "number", "boolean"].includes(typeof value);
+}
+
+interface Walk {
+  readonly document: unknown;
+  readonly depth: number;
+  /** `$ref`s whose targets are left out: they add nothing to the generated type here. */
+  readonly skipped: ReadonlySet<string>;
+}
+
+function follow(node: unknown, walk: Walk): unknown {
+  if (!isObject(node) || typeof node.$ref !== "string") {
+    return node;
+  }
+  return walk.skipped.has(node.$ref) ? undefined : resolveLocalRef(walk.document, node.$ref);
+}
+
+function members(node: JsonObject, keyword: string): readonly unknown[] {
+  const list = node[keyword];
+  return Array.isArray(list) ? list : [];
+}
+
+/** `enum` and `const` of the schema itself, before its compositions. */
+function ownValues(node: JsonObject): AdmittedValues {
+  const listed = Array.isArray(node.enum) ? node.enum.filter(isAdmittedValue) : null;
+  const constant = "const" in node && isAdmittedValue(node.const) ? new Set([node.const]) : null;
+  return intersect(listed === null ? null : new Set(listed), constant);
+}
+
+function schemaValues(schema: unknown, walk: Walk): AdmittedValues {
+  const node = follow(schema, walk);
+  if (!isObject(node) || walk.depth > MAX_DEPTH) {
+    return null;
+  }
+  const next = { ...walk, depth: walk.depth + 1 };
+  const parts = members(node, "allOf").map((part) => schemaValues(part, next));
+  const variants = [...members(node, "anyOf"), ...members(node, "oneOf")];
+  const union = variants.length === 0 ? null : unite(variants.map((v) => schemaValues(v, next)));
+  return [...parts, union].reduce<AdmittedValues>(intersect, ownValues(node));
+}
+
+function propertyValues(schema: unknown, key: string, walk: Walk): AdmittedValues {
+  const node = follow(schema, walk);
+  if (!isObject(node) || walk.depth > MAX_DEPTH) {
+    return null;
+  }
+  const next = { ...walk, depth: walk.depth + 1 };
+  const properties = isObject(node.properties) ? node.properties : {};
+  const own = Object.hasOwn(properties, key) ? schemaValues(properties[key], next) : null;
+  const parts = members(node, "allOf").map((part) => propertyValues(part, key, next));
+  return parts.reduce<AdmittedValues>(intersect, own);
+}
+
+/**
+ * The values property `key` of an object schema admits: the intersection over the schema's own
+ * `properties` and its `allOf` parts (followed through `$ref`s, except `skipped` ones); null for
+ * every value.
+ */
+export function admittedPropertyValues(
+  schema: unknown,
+  key: string,
+  document: unknown,
+  skipped: ReadonlySet<string> = new Set(),
+): AdmittedValues {
+  return propertyValues(schema, key, { document, depth: 0, skipped });
+}

package/src/domain/openapi/discriminated-union.ts

@@ -0,0 +1,109 @@
+import { escapePointerSegment } from "./json-pointer.js";
+import type { Schema, SchemaObject } from "./schema-object.js";
+
+/**
+ * A discriminator owner is either a parent that its members `allOf` (an object with the
+ * discriminator property) or a union (`oneOf` / `anyOf` of the members). The generated type of a
+ * union is a TypeScript union, so it cannot be used like a parent: `Omit<Union, "kind">` keeps
+ * only the keys that every member has, and a member that intersects the union it belongs to
+ * refers to itself (TS2502, upstream #1665).
+ */
+
+/** Resolves a `$ref` of the document; `undefined` when it points nowhere. */
+export type ResolveSchemaRef = (ref: string) => unknown;
+
+const UNION_KEYWORDS = ["oneOf", "anyOf"] as const;
+const COMPOSITION_KEYWORDS = ["allOf", ...UNION_KEYWORDS] as const;
+
+function isSchemaObject(value: unknown): value is SchemaObject {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+function keywordItems(schema: SchemaObject, keywords: readonly string[]): readonly Schema[] {
+  const record = schema as Readonly<Record<string, unknown>>;
+  return keywords.flatMap((keyword) => {
+    const items = record[keyword];
+    return Array.isArray(items) ? (items as readonly Schema[]) : [];
+  });
+}
+
+/** The `oneOf` and `anyOf` members of a schema; empty when it is not a union. */
+export function unionMembers(schema: unknown): readonly Schema[] {
+  return isSchemaObject(schema) ? keywordItems(schema, UNION_KEYWORDS) : [];
+}
+
+/** The schema at `ref` when it is a union (has `oneOf` or `anyOf` members), else undefined. */
+export function unionAt(ref: string, resolve: ResolveSchemaRef): SchemaObject | undefined {
+  const schema = resolve(ref);
+  return isSchemaObject(schema) && unionMembers(schema).length > 0 ? schema : undefined;
+}
+
+/** What one search for a `$ref` has seen, so that a `$ref` cycle ends. */
+interface Search {
+  readonly target: string;
+  readonly resolve: ResolveSchemaRef;
+  readonly visited: Set<string>;
+}
+
+function reaches(schema: Schema, search: Search): boolean {
+  if (!isSchemaObject(schema)) {
+    return false;
+  }
+  const ref = (schema as { readonly $ref?: unknown }).$ref;
+  if (typeof ref === "string") {
+    if (ref === search.target) {
+      return true;
+    }
+    if (search.visited.has(ref)) {
+      return false;
+    }
+    search.visited.add(ref);
+    return reaches(search.resolve(ref) as Schema, search);
+  }
+  return keywordItems(schema, COMPOSITION_KEYWORDS).some((item) => reaches(item, search));
+}
+
+/**
+ * Whether the type of `union` contains the schema at `target` without an object in between: one
+ * of its members is a `$ref` to it, or `allOf` / `oneOf` / `anyOf` such a `$ref`, at any depth.
+ * Such a reference is resolved at once by TypeScript, unlike one in a property or an array.
+ */
+export function unionReaches(
+  union: SchemaObject,
+  target: string,
+  resolve: ResolveSchemaRef,
+): boolean {
+  const search = { target, resolve, visited: new Set<string>() };
+  return unionMembers(union).some((member) => reaches(member, search));
+}
+
+const COMPONENT_SCHEMAS = "#/components/schemas/";
+
+/** A mapping value as a `$ref`: a bare name is a component schema's name. */
+function mappingRef(target: unknown): string | undefined {
+  if (typeof target !== "string") {
+    return undefined;
+  }
+  return target.startsWith("#") ? target : `${COMPONENT_SCHEMAS}${escapePointerSegment(target)}`;
+}
+
+/** Whether the discriminator `mapping` of `union` names the schema at `target`. */
+export function unionMaps(union: SchemaObject, target: string): boolean {
+  const mapping = (union.discriminator as { readonly mapping?: unknown } | undefined)?.mapping;
+  if (!isSchemaObject(mapping)) {
+    return false;
+  }
+  return Object.values(mapping).some((value) => mappingRef(value) === target);
+}
+
+/**
+ * Whether the schema at `target` is a member of `union`: the union's type contains it, or the
+ * discriminator `mapping` names it, which gives it a value of the union as a member does.
+ */
+export function isUnionMember(
+  union: SchemaObject,
+  target: string,
+  resolve: ResolveSchemaRef,
+): boolean {
+  return unionMaps(union, target) || unionReaches(union, target, resolve);
+}