openapi-typesafe 0.0.0 → 1.0.0-rc.1

package/src/api/discriminator-enum.ts

@@ -0,0 +1,115 @@
+import type {
+  DiscriminatorObject,
+  ObjectSubtype,
+  ReferenceObject,
+  SchemaObject,
+} from "../types.js";
+
+/**
+ * The in-place patch of the discriminator pre-pass: a mapped schema gets a required enum property
+ * with its discriminator values, so that TypeScript can narrow the generated union.
+ */
+
+/** One mapped schema to patch: `ref` is the schema; `discriminatorRef` owns the discriminator. */
+export interface EnumPatch {
+  readonly ref: string;
+  readonly values: string[];
+  readonly discriminator: DiscriminatorObject;
+  readonly discriminatorRef: string;
+}
+
+function discriminatorEnum(values: string[], previous?: SchemaObject): SchemaObject {
+  return {
+    type: "string",
+    enum: values,
+    description: previous?.description
+      ? `${previous.description} (enum property replaced by openapi-typesafe)`
+      : "discriminator enum property added by openapi-typesafe",
+  };
+}
+
+/** An `allOf` schema gets one more item that holds the required enum property. */
+function patchAllOf(allOf: (SchemaObject | ReferenceObject)[], patch: EnumPatch): SchemaObject {
+  const added = discriminatorEnum(patch.values);
+  allOf.push({
+    type: "object",
+    required: [patch.discriminator.propertyName],
+    properties: { [patch.discriminator.propertyName]: added },
+  });
+  return added;
+}
+
+/** An object schema gets the enum property, which is always required, added or replaced. */
+function patchObjectSchema(schema: SchemaObject & ObjectSubtype, patch: EnumPatch): SchemaObject {
+  const name = patch.discriminator.propertyName;
+  if (!schema.properties) {
+    schema.properties = {};
+  }
+  if (!schema.required) {
+    schema.required = [name];
+  } else if (!schema.required.includes(name)) {
+    schema.required.push(name);
+  }
+  const added = discriminatorEnum(patch.values, schema.properties[name] as SchemaObject);
+  schema.properties[name] = added;
+  return added;
+}
+
+function isObjectSchema(schema: unknown): schema is SchemaObject & ObjectSubtype {
+  return (
+    typeof schema === "object" && schema !== null && "type" in schema && schema.type === "object"
+  );
+}
+
+/** The values a property schema allows, from `const` or `enum`; null when it lists none. */
+function listedValues(property: unknown): readonly unknown[] | null {
+  if (typeof property !== "object" || property === null) {
+    return null;
+  }
+  const { const: constant, enum: values } = property as SchemaObject;
+  if (constant !== undefined) {
+    return [constant];
+  }
+  return Array.isArray(values) ? values : null;
+}
+
+/** Whether one schema object requires the property and allows exactly the values. */
+function requiresValues(schema: unknown, name: string, values: readonly string[]): boolean {
+  if (typeof schema !== "object" || schema === null || "$ref" in schema) {
+    return false;
+  }
+  const { required, properties } = schema as SchemaObject & ObjectSubtype;
+  const listed = listedValues(properties?.[name]);
+  return (
+    Boolean(required?.includes(name)) &&
+    listed !== null &&
+    listed.length === values.length &&
+    values.every((value) => listed.includes(value))
+  );
+}
+
+/**
+ * Whether `schema`, or an inline `allOf` item of it, already requires the discriminator property
+ * with exactly the patch's values (the `discriminator-values` fix). Then a patch would
+ * only repeat it (#2124).
+ */
+export function declaresValues(schema: SchemaObject | undefined, patch: EnumPatch): boolean {
+  const name = patch.discriminator.propertyName;
+  return [schema, ...(schema?.allOf ?? [])].some((item) =>
+    requiresValues(item, name, patch.values),
+  );
+}
+
+/**
+ * Add or replace the enum property in `schema`, an `allOf` or object schema. Returns the added
+ * enum schema, or null for another kind of schema, which is left as it is.
+ */
+export function addEnumProperty(
+  schema: SchemaObject | undefined,
+  patch: EnumPatch,
+): SchemaObject | null {
+  if (schema?.allOf) {
+    return patchAllOf(schema.allOf, patch);
+  }
+  return isObjectSchema(schema) ? patchObjectSchema(schema, patch) : null;
+}

package/src/api/discriminator-other-owners.ts

@@ -0,0 +1,97 @@
+import type { DiscriminatorObject, ReferenceObject, SchemaObject } from "../types.js";
+import type { EnumPatch } from "./discriminator-enum.js";
+import { enumKey, patchDiscriminatorEnum, type ScanState } from "./discriminator-patch.js";
+import { resolveDocumentRef } from "./document-refs.js";
+
+/**
+ * The `discriminator-values` fix: a schema inherits one discriminator per property. A schema that
+ * owns a discriminator keeps its own (#2200), so the scan does not record the one it inherits for
+ * another property (`Content` owns `subtype` and `allOf`s `Element`, which owns `contentType`).
+ * Its members (`Video`) still get a value of that property, found here from the owners above.
+ */
+
+/** A discriminator and the schema that defines it. */
+interface OtherOwner {
+  readonly discriminator: DiscriminatorObject;
+  readonly ownerRef: string;
+}
+
+/** The `$ref`s of a schema's `allOf` items. */
+function allOfRefs(state: ScanState, ref: string): string[] {
+  const { silent, logger } = state;
+  const schema = resolveDocumentRef<SchemaObject>(state.schema, ref, { silent, logger });
+  const items = (schema?.allOf ?? []) as (SchemaObject | ReferenceObject)[];
+  return items.flatMap((item) =>
+    "$ref" in item && typeof item.$ref === "string" ? [item.$ref] : [],
+  );
+}
+
+/**
+ * The owners' discriminators that the schema at `parentRef` and its `allOf` parents define, the
+ * nearest one per property, except the property of `parentRef`'s own discriminator.
+ */
+function otherOwners(state: ScanState, parentRef: string): OtherOwner[] {
+  const own = state.objects[parentRef]?.propertyName;
+  const found = new Map<string, OtherOwner>();
+  const visited = new Set<string>();
+  const queue = [parentRef];
+  for (let ref = queue.shift(); ref !== undefined; ref = queue.shift()) {
+    if (visited.has(ref)) {
+      continue;
+    }
+    visited.add(ref);
+    const discriminator = state.owners.has(ref) ? state.objects[ref] : undefined;
+    const name = discriminator?.propertyName;
+    if (discriminator && name !== undefined && name !== own && !found.has(name)) {
+      found.set(name, { discriminator, ownerRef: ref });
+    }
+    queue.push(...allOfRefs(state, ref));
+  }
+  return [...found.values()];
+}
+
+/**
+ * The child redefines this property, so its `allOf` items omit it: a parent may have a value of
+ * its own, as `Content` has when `Element`'s mapping names it.
+ */
+function recordOtherProperty(state: ScanState, ref: string, propertyName: string): void {
+  const names = state.otherProperties[ref] ?? [];
+  if (!names.includes(propertyName)) {
+    names.push(propertyName);
+  }
+  state.otherProperties[ref] = names;
+}
+
+/**
+ * The child at `ref` of the schema at `parentRef` gets a value of each other property: a mapped
+ * one at once, else its schema name after both passes, where no mapping gives one. The schema's
+ * own discriminator property is still added, so these patches do not mark it handled.
+ */
+export function inheritOtherOwners(state: ScanState, parentRef: string, ref: string): void {
+  const childProperty = state.objects[ref]?.propertyName;
+  for (const { discriminator, ownerRef } of otherOwners(state, parentRef)) {
+    if (discriminator.propertyName === childProperty) {
+      continue;
+    }
+    recordOtherProperty(state, ref, discriminator.propertyName);
+    const mapped = Object.entries(discriminator.mapping ?? {})
+      .filter(([, target]) => target === ref)
+      .map(([value]) => value);
+    const name = ref.slice(ref.lastIndexOf("/") + 1);
+    const patch: EnumPatch = { ref, values: mapped, discriminator, discriminatorRef: ownerRef };
+    if (mapped.length > 0) {
+      patchDiscriminatorEnum(state, patch);
+    } else {
+      state.otherInferredPatches.push({ ...patch, values: [name] });
+    }
+  }
+}
+
+/** The deferred schema-name values of other properties; see `inheritOtherOwners`. */
+export function applyOtherInferredPatches(state: ScanState, mapped: ReadonlySet<string>): void {
+  for (const patch of state.otherInferredPatches) {
+    if (!mapped.has(enumKey(patch))) {
+      patchDiscriminatorEnum(state, patch);
+    }
+  }
+}

package/src/api/discriminator-patch.ts

@@ -0,0 +1,147 @@
+import type { Logger } from "../application/ports/logger.js";
+import { OutputFix } from "../domain/output-fixes.js";
+import type { DiscriminatorObject, OpenAPI3, SchemaObject } from "../types.js";
+import { addEnumProperty, declaresValues, type EnumPatch } from "./discriminator-enum.js";
+import {
+  type DiscriminatorOwner,
+  type EnumParent,
+  enumParentOf,
+} from "./discriminator-enum-parent.js";
+import { resolveDocumentRef } from "./document-refs.js";
+
+/**
+ * The state of the discriminator pre-pass and the in-place patch of a mapped schema: the enum
+ * property that the generated union narrows by. Two discriminators of one property may patch one
+ * schema; how they combine is the `discriminator-values` fix (ADR-021, roadmap R12).
+ */
+
+/** How to scan: the warnings, and the output fixes of the run (ADR-021). */
+export interface DiscriminatorScanOptions {
+  readonly silent: boolean;
+  readonly logger: Logger;
+  readonly fixes: ReadonlySet<OutputFix>;
+}
+
+/** What the two passes share: the document they patch and what they found so far. */
+export interface ScanState extends DiscriminatorScanOptions {
+  readonly schema: OpenAPI3;
+  readonly objects: Record<string, DiscriminatorObject>;
+  /** The schemas that define a discriminator themselves (pass 1), not by inheritance. */
+  readonly owners: Set<string>;
+  readonly refsHandled: string[];
+  /** With the fix: the enum added to each schema, by schema and property, so values merge. */
+  readonly patchedEnums: Map<string, SchemaObject>;
+  /** With the fix: schema-name values, applied after both passes where no mapping names one. */
+  readonly inferredPatches: EnumPatch[];
+  /** With the fix: schema-name values of other properties (`inheritOtherOwners`). */
+  readonly otherInferredPatches: EnumPatch[];
+  /** With the fix: the other properties each schema got a value of (`inheritOtherOwners`). */
+  readonly otherProperties: Record<string, string[]>;
+  /** With `discriminator-values`: the enum keys that a schema declares itself. */
+  readonly declaredKeys: Set<string>;
+  /** With `discriminator-values`: the owner's enum of each added enum, by that enum. */
+  readonly enumParents: Map<object, EnumParent>;
+}
+
+/** Whether `discriminator-values` is on: values of two discriminators merge into one enum. */
+export function mergesValues(state: ScanState): boolean {
+  return state.fixes.has(OutputFix.DISCRIMINATOR_VALUES);
+}
+
+function patchedSchema(state: ScanState, patch: EnumPatch): SchemaObject | undefined {
+  const { silent, logger } = state;
+  return resolveDocumentRef<SchemaObject>(state.schema, patch.ref, { silent, logger });
+}
+
+/**
+ * With `discriminator-values`: the schema at `patch.ref` requires the property with
+ * exactly these values already, so a patch would only repeat it (#2124).
+ */
+function isDeclared(state: ScanState, patch: EnumPatch): boolean {
+  return (
+    state.fixes.has(OutputFix.DISCRIMINATOR_VALUES) &&
+    declaresValues(patchedSchema(state, patch), patch)
+  );
+}
+
+/**
+ * With `discriminator-values`: the enum of the owner's property, for `key`: an enum the scan
+ * added, or a discriminator object that a schema inherited.
+ */
+export function recordEnumParent(state: ScanState, owner: DiscriminatorOwner, key: object): void {
+  if (!state.fixes.has(OutputFix.DISCRIMINATOR_VALUES)) {
+    return;
+  }
+  const { silent, logger } = state;
+  const parent = enumParentOf(owner, (ref) =>
+    resolveDocumentRef(state.schema, ref, { silent, logger }),
+  );
+  if (parent !== undefined) {
+    state.enumParents.set(key, parent);
+  }
+}
+
+/** The enum the schema at `patch.ref` gets, or null (with a warning) for another kind of schema. */
+function addDiscriminatorEnum(state: ScanState, patch: EnumPatch): SchemaObject | null {
+  const added = addEnumProperty(patchedSchema(state, patch), patch);
+  if (added === null) {
+    warnInvalidMapping(patch, state.logger);
+  } else {
+    recordEnumParent(state, patch, added);
+  }
+  return added;
+}
+
+/** One schema and discriminator property; two discriminators of one property share an enum. */
+export function enumKey(patch: EnumPatch): string {
+  return `${patch.ref}\n${patch.discriminator.propertyName}`;
+}
+
+/** With the fix, a second discriminator of the same property adds its values to the first enum. */
+function mergeIntoPatchedEnum(state: ScanState, key: string, values: readonly string[]): boolean {
+  const patched = state.patchedEnums.get(key);
+  if (patched === undefined) {
+    return false;
+  }
+  const merged = patched.enum as unknown[];
+  merged.push(...values.filter((value) => !merged.includes(value)));
+  return true;
+}
+
+/**
+ * Add or replace the discriminator enum in the schema at `patch.ref`. Returns false, with a
+ * warning, when that schema is neither an `allOf` nor an object schema. Without the fix every
+ * patch adds a property, so two discriminators with different values intersect to `never`.
+ */
+export function patchDiscriminatorEnum(state: ScanState, patch: EnumPatch): boolean {
+  if (isDeclared(state, patch)) {
+    state.declaredKeys.add(enumKey(patch));
+    return true;
+  }
+  if (!mergesValues(state)) {
+    return addDiscriminatorEnum(state, patch) !== null;
+  }
+  const key = enumKey(patch);
+  if (mergeIntoPatchedEnum(state, key, patch.values)) {
+    return true;
+  }
+  const added = addDiscriminatorEnum(state, patch);
+  if (added !== null) {
+    state.patchedEnums.set(key, added);
+  }
+  return added !== null;
+}
+
+export function markHandled(state: ScanState, ref: string): void {
+  if (!state.refsHandled.includes(ref)) {
+    state.refsHandled.push(ref);
+  }
+}
+
+function warnInvalidMapping(patch: EnumPatch, logger: Logger): void {
+  const mapped = `${patch.ref} => ${patch.values.join(", ")}`;
+  logger.warn(
+    "Discriminator mapping has an invalid schema (neither an object schema nor an allOf array): " +
+      `${mapped} (Discriminator: ${patch.discriminatorRef})`,
+  );
+}

package/src/api/discriminator-scan.ts

@@ -0,0 +1,260 @@
+import type { Logger } from "../application/ports/logger.js";
+import { isUnionMember, unionAt } from "../domain/openapi/discriminated-union.js";
+import { OutputFix } from "../domain/output-fixes.js";
+import type {
+  DiscriminatorObject,
+  GeneratorOptions,
+  OpenAPI3,
+  ReferenceObject,
+  SchemaObject,
+} from "../types.js";
+import { defaultLogger } from "./default-ports.js";
+import type { EnumPatch } from "./discriminator-enum.js";
+import type { EnumParent } from "./discriminator-enum-parent.js";
+import { applyOtherInferredPatches, inheritOtherOwners } from "./discriminator-other-owners.js";
+import {
+  type DiscriminatorScanOptions,
+  enumKey,
+  markHandled,
+  mergesValues,
+  patchDiscriminatorEnum,
+  recordEnumParent,
+  type ScanState,
+} from "./discriminator-patch.js";
+import { resolveDocumentRef, walkDocument } from "./document-refs.js";
+import { createRef } from "./legacy-utils.js";
+
+/**
+ * The inherited discriminator pre-pass. It finds every discriminator in the bundled document and
+ * patches the mapped schemas in place with a required enum property, so that TypeScript can narrow
+ * the generated union. The behavior and the warning text match the original `scanDiscriminators`.
+ */
+
+type DiscriminatorMapping = Record<string, { inferred?: string; defined?: string[] }>;
+
+/** The schema name at the end of each `oneOf` `$ref` is the inferred discriminator value. */
+function inferredMapping(oneOf: (SchemaObject | ReferenceObject)[]): DiscriminatorMapping {
+  const mapping: DiscriminatorMapping = {};
+  for (const item of oneOf) {
+    if (!("$ref" in item)) {
+      continue;
+    }
+    const value = item.$ref.split("/").pop();
+    if (value) {
+      mapping[item.$ref] = { ...mapping[item.$ref], inferred: value };
+    }
+  }
+  return mapping;
+}
+
+/** Values defined in `discriminator.mapping` replace inferred ones for the same schema. */
+function addDefinedMapping(
+  mapping: DiscriminatorMapping,
+  defined: Readonly<Record<string, string>>,
+): void {
+  for (const [mappedValue, mappedRef] of Object.entries(defined)) {
+    if (!mappedRef) {
+      continue;
+    }
+    if (!mapping[mappedRef]?.defined) {
+      mapping[mappedRef] = { defined: [] };
+    }
+    mapping[mappedRef].defined?.push(mappedValue);
+  }
+}
+
+function patchMappedSchemas(
+  state: ScanState,
+  mapping: DiscriminatorMapping,
+  discriminator: Omit<EnumPatch, "ref" | "values">,
+): void {
+  for (const [ref, { inferred, defined }] of Object.entries(mapping)) {
+    const isSkipped = !mergesValues(state) && state.refsHandled.includes(ref);
+    if (isSkipped || (!inferred && !defined)) {
+      continue;
+    }
+    // A defined value wins: the schema name may not be the value the API sends.
+    const values = defined ?? [inferred as string];
+    if (mergesValues(state) && defined === undefined) {
+      // A mapping found later, in this pass or the next, may name the schema.
+      state.inferredPatches.push({ ...discriminator, ref, values });
+    } else if (patchDiscriminatorEnum(state, { ...discriminator, ref, values })) {
+      markHandled(state, ref);
+    }
+  }
+}
+
+/** Pass 1: collect every discriminator; patch the schemas of a discriminator + `oneOf`. */
+function collectDiscriminator(
+  state: ScanState,
+  value: Record<string, unknown>,
+  path: (string | number)[],
+): void {
+  const discriminator = value.discriminator as DiscriminatorObject | undefined;
+  if (!discriminator?.propertyName) {
+    return;
+  }
+  const discriminatorRef = createRef(path);
+  state.objects[discriminatorRef] = discriminator;
+  state.owners.add(discriminatorRef);
+  if (!Array.isArray(value.oneOf)) {
+    return;
+  }
+  const mapping = inferredMapping(value.oneOf);
+  if (discriminator.mapping) {
+    addDefinedMapping(mapping, discriminator.mapping);
+  }
+  patchMappedSchemas(state, mapping, { discriminator, discriminatorRef });
+}
+
+/** The mapping keys of `discriminator` that point at `ref`. */
+function valuesMappedTo(discriminator: DiscriminatorObject, ref: string): string[] {
+  return Object.entries(discriminator.mapping ?? {})
+    .filter(([, mappedRef]) => mappedRef === ref)
+    .map(([mappedValue]) => mappedValue);
+}
+
+/**
+ * Whether the schema at `ref` takes the discriminator of its `allOf` parent at `parentRef`. With
+ * `allof-discriminated-union`, a schema that `allOf`s a discriminated union that does not contain
+ * it is that union, not one of its members, so it gets no value of its own (#1464, #1690). A
+ * schema that the union's mapping names is a member.
+ */
+function inheritsDiscriminator(state: ScanState, parentRef: string, ref: string): boolean {
+  if (!state.fixes.has(OutputFix.ALLOF_DISCRIMINATED_UNION)) {
+    return true;
+  }
+  const resolve = (target: string) => resolveDocumentRef(state.schema, target, state);
+  const union = unionAt(parentRef, resolve);
+  return union === undefined || isUnionMember(union, ref, resolve);
+}
+
+/**
+ * The schema at `ref` inherits `discriminator`. With `discriminator-values`, a schema that
+ * defines a discriminator keeps it: the inherited one replaced its mapping, so the members walked
+ * after this schema got their schema name instead of the mapped value (#2200). `ownerRef` is the
+ * schema that declares the discriminator property, whose enum `--enum` values use (#1700).
+ */
+function recordInherited(
+  state: ScanState,
+  ref: string,
+  discriminator: DiscriminatorObject,
+  ownerRef: string,
+): void {
+  if (state.fixes.has(OutputFix.DISCRIMINATOR_VALUES) && state.owners.has(ref)) {
+    return;
+  }
+  const inherited = { ...discriminator };
+  state.objects[ref] = inherited;
+  recordEnumParent(state, { discriminator, discriminatorRef: ownerRef }, inherited);
+}
+
+/**
+ * An `allOf` item that is a `$ref` to a discriminator owner: the schema at `ref` inherits the
+ * discriminator, and gets its enum when the parent's mapping names it. Returns false when the
+ * `$ref` owns no discriminator, which ends the scan of this `allOf` (as in the original).
+ */
+function inheritFromRef(state: ScanState, parentRef: string, ref: string): boolean {
+  const discriminator = state.objects[parentRef];
+  if (!discriminator) {
+    return false;
+  }
+  const values = valuesMappedTo(discriminator, ref);
+  const patch = { ref, values, discriminator, discriminatorRef: parentRef };
+  if (values.length > 0 && patchDiscriminatorEnum(state, patch)) {
+    markHandled(state, ref);
+  }
+  if (inheritsDiscriminator(state, parentRef, ref)) {
+    recordInherited(state, ref, discriminator, parentRef);
+    if (mergesValues(state)) {
+      inheritOtherOwners(state, parentRef, ref);
+    }
+  }
+  return true;
+}
+
+/** Pass 2: a schema whose `allOf` holds a discriminator, or a `$ref` to one, inherits it. */
+function inheritDiscriminators(
+  state: ScanState,
+  value: Record<string, unknown>,
+  path: (string | number)[],
+): void {
+  if (!Array.isArray(value.allOf)) {
+    return;
+  }
+  for (const item of value.allOf as (SchemaObject | ReferenceObject)[]) {
+    if ("$ref" in item) {
+      if (!inheritFromRef(state, item.$ref, createRef(path))) {
+        return;
+      }
+    } else if (item.discriminator?.propertyName) {
+      // The inline item is typed at the schema's own location.
+      recordInherited(state, createRef(path), item.discriminator, createRef(path));
+    }
+  }
+}
+
+/** The discriminators of a bundled document, after patching the mapped schemas in place. */
+export interface DiscriminatorScan {
+  objects: Record<string, DiscriminatorObject>;
+  refsHandled: string[];
+  /** With `discriminator-values`: the owner's enum of each enum the scan added. */
+  enumParents: ReadonlyMap<object, EnumParent>;
+  /** With `discriminator-values`: the properties of the other discriminators a schema inherits. */
+  otherProperties: Readonly<Record<string, readonly string[]>>;
+}
+
+/**
+ * With the fix: a schema-name value, only for a schema and property that no mapping gave a value.
+ * Every enum patched so far came from a mapping, since schema-name values wait for this step.
+ */
+function applyInferredPatches(state: ScanState): void {
+  // A value that a schema declares itself came from a mapping as well.
+  const mapped = new Set([...state.patchedEnums.keys(), ...state.declaredKeys]);
+  for (const patch of state.inferredPatches) {
+    if (!mapped.has(enumKey(patch)) && patchDiscriminatorEnum(state, patch)) {
+      markHandled(state, patch.ref);
+    }
+  }
+  applyOtherInferredPatches(state, mapped);
+}
+
+/** Find every discriminator in `schema`; warnings go to `logger` unless `silent`. */
+export function findDiscriminators(
+  schema: OpenAPI3,
+  options: DiscriminatorScanOptions,
+): DiscriminatorScan {
+  const state: ScanState = {
+    ...options,
+    schema,
+    objects: {},
+    owners: new Set(),
+    refsHandled: [],
+    patchedEnums: new Map(),
+    inferredPatches: [],
+    otherInferredPatches: [],
+    otherProperties: {},
+    declaredKeys: new Set(),
+    enumParents: new Map(),
+  };
+  walkDocument(schema, (value, path) => collectDiscriminator(state, value, path));
+  // A second pass, because an `allOf` may name a discriminator that is defined later.
+  walkDocument(schema, (value, path) => inheritDiscriminators(state, value, path));
+  applyInferredPatches(state);
+  const { objects, refsHandled, enumParents, otherProperties } = state;
+  return { objects, refsHandled, enumParents, otherProperties };
+}
+
+/**
+ * Return a key–value map of discriminator objects found in a schema. Warnings go to `logger`;
+ * without one, to the default terminal logger, as the original did.
+ * @deprecated Kept for 1.x; removed in 2.0 (ADR-004, decision 9).
+ */
+export function scanDiscriminators(
+  schema: OpenAPI3,
+  options: GeneratorOptions,
+  logger: Logger = defaultLogger(options.silent ?? false),
+): DiscriminatorScan {
+  const silent = options.silent ?? false;
+  return findDiscriminators(schema, { silent, logger, fixes: new Set() });
+}

package/src/api/document-declarations.ts

@@ -0,0 +1,41 @@
+import { loadTypeScript } from "../adapters/type-ast-bridge/load-typescript.js";
+import { printWithTypeScript } from "../adapters/type-ast-bridge/print-typescript.js";
+import type { ts } from "../adapters/type-ast-bridge/typescript-types.js";
+import type { IrDeclaration } from "../domain/ir/nodes.js";
+import { type FooterEntry, isIrDeclaration } from "./footer-entry.js";
+
+/** The document in three parts; the footer may hold TypeScript nodes from user code. */
+export interface TransformedDocument {
+  readonly body: readonly IrDeclaration[];
+  readonly footer: readonly FooterEntry[];
+  readonly closing: readonly IrDeclaration[];
+}
+
+/** The TypeScript printer ends the file with a line break; a raw declaration's text has none. */
+function withoutFinalLineBreak(text: string): string {
+  return text.endsWith("\n") ? text.slice(0, -1) : text;
+}
+
+/** A TypeScript node from user code, as the TypeScript printer prints it. */
+function printedNode(node: ts.Node): IrDeclaration {
+  return {
+    kind: "rawDeclaration",
+    text: withoutFinalLineBreak(printWithTypeScript(loadTypeScript(), [node])),
+  };
+}
+
+function entryDeclaration(entry: FooterEntry): IrDeclaration {
+  return isIrDeclaration(entry) ? entry : printedNode(entry);
+}
+
+/**
+ * The document as IR declarations in output order. Footer TypeScript nodes from user code become
+ * raw text through the bridge; raw text is printed as written (ADR-010, decision 4).
+ */
+export function documentDeclarations({
+  body,
+  footer,
+  closing,
+}: TransformedDocument): IrDeclaration[] {
+  return [...body, ...footer.map(entryDeclaration), ...closing];
+}