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

package/src/api/discriminator-patch.ts

@@ -0,0 +1,152 @@
+import type { Logger } from "../application/ports/logger.js";
+import { OutputFix } from "../domain/output-fixes.js";
+import { WARNING_CODES, warningText } from "../domain/warnings.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(
+    warningText(
+      "Discriminator mapping has an invalid schema " +
+        "(neither an object schema nor an allOf array): " +
+        `${mapped} (Discriminator: ${patch.discriminatorRef})`,
+      WARNING_CODES.DISCRIMINATOR_MAPPING_INVALID,
+    ),
+  );
+}

package/src/api/discriminator-scan.ts

@@ -1,4 +1,6 @@
 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,
@@ -7,7 +9,18 @@ import type {
   SchemaObject,
 } from "../types.js";
 import { defaultLogger } from "./default-ports.js";
-import { addEnumProperty, type EnumPatch } from "./discriminator-enum.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";
 
@@ -19,85 +32,6 @@ import { createRef } from "./legacy-utils.js";
 
 type DiscriminatorMapping = Record<string, { inferred?: string; defined?: string[] }>;
 
-/** How to scan; `fixesValueConflicts` is the `discriminator-values` fix (ADR-021, roadmap R12). */
-export interface DiscriminatorScanOptions {
-  readonly silent: boolean;
-  readonly logger: Logger;
-  readonly fixesValueConflicts: boolean;
-}
-
-/** What the two passes share: the document they patch and what they found so far. */
-interface ScanState extends DiscriminatorScanOptions {
-  readonly schema: OpenAPI3;
-  readonly objects: Record<string, DiscriminatorObject>;
-  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[];
-}
-
-/** 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 { silent, logger } = state;
-  const resolved = resolveDocumentRef<SchemaObject>(state.schema, patch.ref, { silent, logger });
-  const added = addEnumProperty(resolved, patch);
-  if (added === null) {
-    warnInvalidMapping(patch, state.logger);
-  }
-  return added;
-}
-
-/** One schema and discriminator property; two discriminators of one property share an enum. */
-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`.
- */
-function patchDiscriminatorEnum(state: ScanState, patch: EnumPatch): boolean {
-  if (!state.fixesValueConflicts) {
-    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;
-}
-
-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})`,
-  );
-}
-
 /** The schema name at the end of each `oneOf` `$ref` is the inferred discriminator value. */
 function inferredMapping(oneOf: (SchemaObject | ReferenceObject)[]): DiscriminatorMapping {
   const mapping: DiscriminatorMapping = {};
@@ -116,9 +50,9 @@ function inferredMapping(oneOf: (SchemaObject | ReferenceObject)[]): Discriminat
 /** Values defined in `discriminator.mapping` replace inferred ones for the same schema. */
 function addDefinedMapping(
   mapping: DiscriminatorMapping,
-  discriminator: DiscriminatorObject,
+  defined: Readonly<Record<string, string>>,
 ): void {
-  for (const [mappedValue, mappedRef] of Object.entries(discriminator.mapping ?? {})) {
+  for (const [mappedValue, mappedRef] of Object.entries(defined)) {
     if (!mappedRef) {
       continue;
     }
@@ -135,13 +69,13 @@ function patchMappedSchemas(
   discriminator: Omit<EnumPatch, "ref" | "values">,
 ): void {
   for (const [ref, { inferred, defined }] of Object.entries(mapping)) {
-    const isSkipped = !state.fixesValueConflicts && state.refsHandled.includes(ref);
+    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 (state.fixesValueConflicts && defined === undefined) {
+    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 })) {
@@ -162,12 +96,13 @@ function collectDiscriminator(
   }
   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);
+    addDefinedMapping(mapping, discriminator.mapping);
   }
   patchMappedSchemas(state, mapping, { discriminator, discriminatorRef });
 }
@@ -179,6 +114,41 @@ function valuesMappedTo(discriminator: DiscriminatorObject, ref: string): string
     .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
@@ -194,7 +164,12 @@ function inheritFromRef(state: ScanState, parentRef: string, ref: string): boole
   if (values.length > 0 && patchDiscriminatorEnum(state, patch)) {
     markHandled(state, ref);
   }
-  state.objects[ref] = { ...discriminator };
+  if (inheritsDiscriminator(state, parentRef, ref)) {
+    recordInherited(state, ref, discriminator, parentRef);
+    if (mergesValues(state)) {
+      inheritOtherOwners(state, parentRef, ref);
+    }
+  }
   return true;
 }
 
@@ -213,7 +188,8 @@ function inheritDiscriminators(
         return;
       }
     } else if (item.discriminator?.propertyName) {
-      state.objects[createRef(path)] = { ...item.discriminator };
+      // The inline item is typed at the schema's own location.
+      recordInherited(state, createRef(path), item.discriminator, createRef(path));
     }
   }
 }
@@ -222,6 +198,10 @@ function inheritDiscriminators(
 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[]>>;
 }
 
 /**
@@ -229,12 +209,14 @@ export interface DiscriminatorScan {
  * Every enum patched so far came from a mapping, since schema-name values wait for this step.
  */
 function applyInferredPatches(state: ScanState): void {
-  const mapped = new Set(state.patchedEnums.keys());
+  // 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`. */
@@ -246,15 +228,21 @@ export function findDiscriminators(
     ...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);
-  return { objects: state.objects, refsHandled: state.refsHandled };
+  const { objects, refsHandled, enumParents, otherProperties } = state;
+  return { objects, refsHandled, enumParents, otherProperties };
 }
 
 /**
@@ -268,5 +256,5 @@ export function scanDiscriminators(
   logger: Logger = defaultLogger(options.silent ?? false),
 ): DiscriminatorScan {
   const silent = options.silent ?? false;
-  return findDiscriminators(schema, { silent, logger, fixesValueConflicts: false });
+  return findDiscriminators(schema, { silent, logger, fixes: new Set() });
 }

package/src/api/document-refs.ts

@@ -1,5 +1,6 @@
 import { parseRef } from "@redocly/openapi-core/lib/ref-utils.js";
 import type { Logger } from "../application/ports/logger.js";
+import { WARNING_CODES, warningText } from "../domain/warnings.js";
 import { defaultLogger } from "./default-ports.js";
 
 /** `$ref` resolution and the document walk that the generator's pre-pass uses. */
@@ -11,9 +12,13 @@ export interface ResolveRefOptions {
   logger?: Logger;
 }
 
+function isObject(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null;
+}
+
 /** Resolve a `$ref` in a document; warns and returns undefined when it cannot. */
 export function resolveDocumentRef<T>(
-  schema: any,
+  schema: unknown,
   $ref: string,
   options: ResolveRefOptions,
 ): T | undefined {
@@ -23,30 +28,29 @@ export function resolveDocumentRef<T>(
   if (!pointer.length) {
     return undefined;
   }
-  let node = schema;
+  let node: unknown = schema;
   for (const key of pointer) {
-    if (node && typeof node === "object" && node[key]) {
-      node = node[key];
-    } else {
-      logger.warn(`Could not resolve $ref "${$ref}"`);
+    const child = isObject(node) ? node[key] : undefined;
+    if (!child) {
+      logger.warn(warningText(`Could not resolve $ref "${$ref}"`, WARNING_CODES.REF_NOT_FOUND));
       return undefined;
     }
+    node = child;
   }
 
   // if this is also a $ref, keep tracing
-  if (node && typeof node === "object" && node.$ref) {
-    if (visited.includes(node.$ref)) {
-      logger.warn(`Could not resolve circular $ref "${$ref}"`);
+  const next = isObject(node) ? node.$ref : undefined;
+  if (typeof next === "string" && next) {
+    if (visited.includes(next)) {
+      logger.warn(
+        warningText(`Could not resolve circular $ref "${$ref}"`, WARNING_CODES.REF_CIRCULAR),
+      );
       return undefined;
     }
-    return resolveDocumentRef(schema, node.$ref, {
-      ...options,
-      logger,
-      visited: [...visited, node.$ref],
-    });
+    return resolveDocumentRef(schema, next, { ...options, logger, visited: [...visited, next] });
   }
 
-  return node;
+  return node as T;
 }
 
 /** Call `cb` for every object in a JSON-serializable (non-circular) value, depth first. */

package/src/api/document-run.ts

@@ -7,13 +7,18 @@ import type { RefAccess, SchemaLoader } from "../application/ports/schema-loader
 import { withStackOverflowReported } from "../application/stack-overflow.js";
 import {
   ineffectiveFixNotices,
-  OutputFix,
+  type OutputFix,
   outputFixNamesOf,
   resolveOutputFixes,
 } from "../domain/output-fixes.js";
-import type { GeneratorOptions, GlobalContext, OpenAPI3, SchemaSource } from "../types.js";
+import { WARNING_CODES, warningText } from "../domain/warnings.js";
+import type { GeneratorOptions, OpenAPI3, SchemaSource } from "../types.js";
+import { processCwd } from "./default-ports.js";
+import { warnDiscriminatorValueConflicts } from "./discriminator-conflict-warnings.js";
 import { findDiscriminators } from "./discriminator-scan.js";
 import { resolveDocumentRef } from "./document-refs.js";
+import { warnIdenticalPathTemplates } from "./path-template-warnings.js";
+import type { RunContext } from "./run-context.js";
 import { warnUnsupportedFeatures } from "./unsupported-feature-warnings.js";
 
 /** The ports of one generator run, wired by the Node API or the CLI (ENGINEERING_PLAN 4.5). */
@@ -29,12 +34,12 @@ export interface GeneratorPorts {
 /** A validated, bundled document and the context of one generator run. */
 export interface DocumentRun {
   readonly schema: OpenAPI3;
-  readonly ctx: GlobalContext;
+  readonly ctx: RunContext;
 }
 
 /** The context fields that are user flags, with the original defaults. */
 type ContextFlags = Omit<
-  GlobalContext,
+  RunContext,
   | "discriminators"
   | "injectFooter"
   | "redoc"
@@ -45,10 +50,17 @@ type ContextFlags = Omit<
   | "fix"
 >;
 
+/**
+ * The directory that relative `$ref`s of an inline source resolve against, as a URL that ends in
+ * a slash. A path is resolved and encoded (`#`, `%`, spaces); a URL without the slash gets one.
+ */
 function sourceCwd(options: GeneratorOptions): URL {
-  return options.cwd instanceof URL
-    ? options.cwd
-    : new URL(`file://${options.cwd ?? process.cwd()}/`);
+  const { cwd } = options;
+  if (cwd instanceof URL) {
+    return cwd.pathname.endsWith("/") ? cwd : new URL(`${cwd.pathname}/`, cwd);
+  }
+  const directory = path.resolve(cwd === undefined ? processCwd() : cwd.toString());
+  return pathToFileURL(path.join(directory, path.sep));
 }
 
 /** The `$ref` limits of the options; a relative local root resolves against the cwd. */
@@ -110,11 +122,20 @@ function contextFlags(options: GeneratorOptions): ContextFlags {
 function outputFixesOf(options: GeneratorOptions, logger: Logger): readonly OutputFix[] {
   const names = outputFixNamesOf(options.fix ?? []);
   for (const notice of ineffectiveFixNotices(names, (option) => options[option] === true)) {
-    logger.warn(notice);
+    logger.warn(warningText(notice, WARNING_CODES.FIX_NEEDS_OPTION));
   }
   return [...resolveOutputFixes(names)];
 }
 
+/** The warnings about the loaded document itself, before it is transformed. */
+function warnAboutDocument(schema: OpenAPI3, fix: readonly OutputFix[], logger: Logger): void {
+  withStackOverflowReported("transform", () => warnUnsupportedFeatures(schema, logger));
+  withStackOverflowReported("transform", () =>
+    warnDiscriminatorValueConflicts(schema, fix, logger),
+  );
+  warnIdenticalPathTemplates(schema, logger);
+}
+
 /**
  * Load the source through the ports, then build the run's context from the options. The fix names
  * are checked first, so a typo fails before the document is read.
@@ -137,8 +158,8 @@ export async function createDocumentRun(
     shouldLint: options.lint ?? true,
     refAccess: refAccessOf(options, cwd),
   });
-  withStackOverflowReported("transform", () => warnUnsupportedFeatures(schema, logger));
-  const ctx: GlobalContext = {
+  warnAboutDocument(schema, fix, logger);
+  const ctx: RunContext = {
     ...contextFlags(options),
     fix,
     // The scan walks every schema before the transform does, so on a larger stack, where loading
@@ -147,7 +168,7 @@ export async function createDocumentRun(
       findDiscriminators(schema, {
         silent,
         logger,
-        fixesValueConflicts: fix.includes(OutputFix.DISCRIMINATOR_VALUES),
+        fixes: new Set(fix),
       }),
     ),
     injectFooter: [],

package/src/api/enum-values-warnings.ts

@@ -0,0 +1,21 @@
+import { WARNING_CODES, warningText } from "../domain/warnings.js";
+
+const DOCS_BASE_URL = "https://github.com/openapi-typesafe/openapi-typesafe/blob/main/docs";
+const DOCS_URL = `${DOCS_BASE_URL}/advanced.md#enum-values-arrays`;
+
+/**
+ * The warning for an `--enum-values` array whose schema's location in the generated types admits
+ * none or only some of its values (ADR-027): the schema contradicts itself, for example an `allOf`
+ * of enums with different values or a discriminator value that the property enum does not list.
+ */
+export function excludedValuesWarning(name: string, excluded: readonly unknown[]): string {
+  const values = excluded.map((value) => JSON.stringify(value)).join(", ");
+  return warningText(
+    `${name}: the generated type at the location of this enum does not admit ${values}; ` +
+      "other keywords of the document exclude these values (an allOf of enums with other " +
+      "values, or a discriminator value the enum does not list). The array is typed by its own " +
+      "values. " +
+      `See ${DOCS_URL}`,
+    WARNING_CODES.ENUM_VALUES_EXCLUDED,
+  );
+}

package/src/api/footer-sink.ts

@@ -4,6 +4,7 @@ import type { FooterSink } from "../application/transform/footer/document-footer
 import type {
   IrDeclaration,
   IrInterfaceDeclaration,
+  IrMember,
   IrPropertySignature,
 } from "../domain/ir/nodes.js";
 import { declaresTypeAlias, type FooterEntry, isIrDeclaration } from "./footer-entry.js";
@@ -16,6 +17,12 @@ const OPERATIONS_NAME = "operations";
  */
 export class ContextFooterSink implements FooterSink {
   private readonly footer: FooterEntry[];
+  /**
+   * The IR `operations` entry this sink wrote last, with its members array that only this sink
+   * holds. Adding to it in place keeps a run linear: copying the members on every operation was
+   * quadratic (about 0.4 s on Microsoft Graph beta).
+   */
+  private owned: OwnedOperations | null = null;
 
   constructor(footer: FooterEntry[]) {
     this.footer = footer;
@@ -35,6 +42,11 @@ export class ContextFooterSink implements FooterSink {
    * the member in place, as in the original.
    */
   addOperation(build: () => IrPropertySignature): void {
+    const owned = this.currentOwnedOperations();
+    if (owned !== null) {
+      owned.members.push(build());
+      return;
+    }
     const existing = this.findOperations();
     if (existing !== null && !isIrDeclaration(existing.entry)) {
       const ts = loadTypeScript();
@@ -45,9 +57,23 @@ export class ContextFooterSink implements FooterSink {
       return;
     }
     const index = existing?.index ?? this.footer.push(emptyOperations()) - 1;
-    const member = build();
+    this.takeOwnership(index).members.push(build());
+  }
+
+  /** The owned entry, unless user code replaced or moved it in the footer since. */
+  private currentOwnedOperations(): OwnedOperations | null {
+    const owned = this.owned;
+    return owned !== null && this.footer[owned.index] === owned.entry ? owned : null;
+  }
+
+  /** Replace the IR entry at `index` with a copy whose members array only this sink holds. */
+  private takeOwnership(index: number): OwnedOperations {
     const operations = this.footer[index] as IrInterfaceDeclaration;
-    this.footer[index] = { ...operations, members: [...operations.members, member] };
+    const members: IrMember[] = [...operations.members];
+    const entry: IrInterfaceDeclaration = { ...operations, members };
+    this.footer[index] = entry;
+    this.owned = { entry, members, index };
+    return this.owned;
   }
 
   /** The first `operations` interface: the generator's (IR) or a user's (TypeScript). */
@@ -62,6 +88,12 @@ export class ContextFooterSink implements FooterSink {
   }
 }
 
+interface OwnedOperations {
+  readonly entry: IrInterfaceDeclaration;
+  readonly members: IrMember[];
+  readonly index: number;
+}
+
 function emptyOperations(): IrInterfaceDeclaration {
   return { kind: "interface", name: OPERATIONS_NAME, isExported: true, members: [], comments: [] };
 }