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

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

@@ -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-run.ts

@@ -7,13 +7,15 @@ 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 { 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 { warnUnsupportedFeatures } from "./unsupported-feature-warnings.js";
 
 /** The ports of one generator run, wired by the Node API or the CLI (ENGINEERING_PLAN 4.5). */
@@ -45,10 +47,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 ? process.cwd() : cwd.toString());
+  return pathToFileURL(path.join(directory, path.sep));
 }
 
 /** The `$ref` limits of the options; a relative local root resolves against the cwd. */
@@ -115,6 +124,15 @@ function outputFixesOf(options: GeneratorOptions, logger: Logger): readonly Outp
   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,7 +155,7 @@ export async function createDocumentRun(
     shouldLint: options.lint ?? true,
     refAccess: refAccessOf(options, cwd),
   });
-  withStackOverflowReported("transform", () => warnUnsupportedFeatures(schema, logger));
+  warnAboutDocument(schema, fix, logger);
   const ctx: GlobalContext = {
     ...contextFlags(options),
     fix,
@@ -147,7 +165,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/path-template-warnings.ts

@@ -0,0 +1,27 @@
+import type { Logger } from "../application/ports/logger.js";
+import { findIdenticalPathTemplates } from "../domain/openapi/path-templates.js";
+import { WARNING_CODES, warningText } from "../domain/warnings.js";
+
+const DOCS_URL =
+  "https://github.com/openapi-typesafe/openapi-typesafe/blob/main/docs/cli.md#pathparamsastypes";
+const SPEC_RULE =
+  "OpenAPI does not allow this (Paths Object): templated paths with the same hierarchy but " +
+  "different templated names MUST NOT exist as they are identical";
+
+/** `"/a"`, `"/a" and "/b"`, `"/a", "/b" and "/c"`. */
+function quotedList(urls: readonly string[]): string {
+  const quoted = urls.map((url) => `"${url}"`);
+  const last = quoted.pop();
+  return quoted.length === 0 ? (last ?? "") : `${quoted.join(", ")} and ${last}`;
+}
+
+/**
+ * Warn once per group of paths that differ only in parameter names, which the spec forbids: a URL
+ * cannot tell them apart, and `--path-params-as-types` gives them the same key type.
+ */
+export function warnIdenticalPathTemplates(document: unknown, logger: Logger): void {
+  for (const urls of findIdenticalPathTemplates(document)) {
+    const message = `Paths ${quotedList(urls)} differ only in their parameter names. ${SPEC_RULE}`;
+    logger.warn(warningText(`${message}. See ${DOCS_URL}`, WARNING_CODES.PATH_TEMPLATES_IDENTICAL));
+  }
+}

package/src/api/transform-context.ts

@@ -1,6 +1,9 @@
 import * as changeCase from "change-case";
 import { RunFooter } from "../application/transform/footer/document-footer.js";
-import type { SchemaLocation } from "../application/transform/schema/schema-context.js";
+import type {
+  DiscriminatorEnumParent,
+  SchemaLocation,
+} from "../application/transform/schema/schema-context.js";
 import type {
   DocumentFooter,
   NameCasing,
@@ -73,6 +76,9 @@ export function createTransformContext(ctx: GlobalContext): TransformContext {
     discriminators: {
       objectAt: (ref) => ctx.discriminators.objects[ref],
       isHandled: (ref) => ctx.discriminators.refsHandled.includes(ref),
+      otherPropertiesAt: (ref) => ctx.discriminators.otherProperties?.[ref] ?? [],
+      enumParentOf: (schema) =>
+        ctx.discriminators.enumParents?.get(schema) as DiscriminatorEnumParent | undefined,
     },
     footer: runFooter(ctx),
     callbacks: schemaCallbacks(ctx),

package/src/api/transform-schema.ts

@@ -1,11 +1,21 @@
 import type { ts } from "../adapters/type-ast-bridge/typescript-types.js";
 import { documentBody, documentClosing } from "../application/transform/document/document.js";
-import { renameAliasesTakenByFooter } from "../application/transform/document/root-type-aliases.js";
+import { renameTakenAliases } from "../application/transform/document/root-type-aliases.js";
+import { RunFooter } from "../application/transform/footer/document-footer.js";
+import { checkedEnumValues } from "../application/transform/footer/enum-values-check.js";
+import {
+  SharedEnumNameRecorder,
+  type SharedEnumNames,
+} from "../application/transform/footer/shared-enum-names.js";
 import type { IrDeclaration } from "../domain/ir/nodes.js";
 import type { DocumentObject } from "../domain/openapi/document-object.js";
+import { OutputFix } from "../domain/output-fixes.js";
 import type { GlobalContext, OpenAPI3 } from "../types.js";
+import { FirstSchemaNameRecorder } from "./discriminator-enum-names.js";
 import { documentDeclarations, type TransformedDocument } from "./document-declarations.js";
+import { excludedValuesWarning } from "./enum-values-warnings.js";
 import { type FooterEntry, isIrDeclaration } from "./footer-entry.js";
+import { ContextFooterSink } from "./footer-sink.js";
 import { createTransformContext } from "./transform-context.js";
 
 const OPERATIONS_NAME = "operations";
@@ -18,15 +28,89 @@ function isOperations(entry: FooterEntry): boolean {
   return name === OPERATIONS_NAME;
 }
 
+/** Drops a message: the first pass must not repeat the run's warnings or debug lines. */
+const dropMessage = (): void => undefined;
+const DROPPED_MESSAGES = { debug: dropMessage, warn: dropMessage, error: dropMessage };
+
+/** A shared enum name recorder of a first pass, and the names it gives the second. */
+interface EnumNameRecorder extends SharedEnumNames {
+  chosenNames(): SharedEnumNames;
+}
+
+/**
+ * The names of shared enums, known only at the end: a first pass transforms the document into a
+ * scratch footer that `recorder` watches; its output is dropped. User callbacks run in both
+ * passes. The `dedupe-enum-names` fix (ADR-021, upstream #1683) names an enum by all of its
+ * schemas; `discriminator-values` keeps the first declaring schema's name
+ * (`FirstSchemaNameRecorder`).
+ */
+function sharedEnumNamesOf(
+  document: DocumentObject,
+  ctx: GlobalContext,
+  recorder: EnumNameRecorder,
+): SharedEnumNames {
+  const injectFooter: FooterEntry[] = [];
+  const scratch: GlobalContext = {
+    ...ctx,
+    injectFooter,
+    runFooter: new RunFooter(new ContextFooterSink(injectFooter), true, recorder),
+    logger: DROPPED_MESSAGES,
+    legacyCallbackWarnings: new Set(),
+  };
+  const scratchContext = createTransformContext(scratch);
+  documentBody(document, scratchContext, () => injectFooter.filter(isIrDeclaration));
+  return recorder.chosenNames();
+}
+
+/** The recorder of the run's fixes, or null where the first schema's name needs no first pass. */
+function enumNameRecorderOf(ctx: GlobalContext): EnumNameRecorder | null {
+  if (ctx.fix?.includes(OutputFix.DEDUPE_ENUM_NAMES)) {
+    return new SharedEnumNameRecorder();
+  }
+  return ctx.fix?.includes(OutputFix.DISCRIMINATOR_VALUES) ? new FirstSchemaNameRecorder() : null;
+}
+
+/** With a naming fix, `--enum` and `--dedupe-enums`, the run's footer names shared enums. */
+function withSharedEnumNames(document: DocumentObject, ctx: GlobalContext): void {
+  const recorder = ctx.runFooter === undefined ? enumNameRecorderOf(ctx) : null;
+  if (recorder === null || !ctx.enum || !ctx.dedupeEnums) {
+    return;
+  }
+  const names = sharedEnumNamesOf(document, ctx, recorder);
+  ctx.runFooter = new RunFooter(new ContextFooterSink(ctx.injectFooter), true, names);
+}
+
+/**
+ * With `--enum-values`, arrays whose location type does not hold their values are typed by their
+ * values (ADR-027); a location that excludes listed values is a contradiction of the document.
+ */
+function enumValuesChecked(
+  body: readonly IrDeclaration[],
+  footer: FooterEntry[],
+  ctx: GlobalContext,
+): FooterEntry[] {
+  if (!ctx.enumValues) {
+    return footer;
+  }
+  const checked = checkedEnumValues(footer, body, isIrDeclaration);
+  for (const retype of checked.retyped) {
+    if (retype.kind === "excluded") {
+      ctx.logger?.warn(excludedValuesWarning(retype.name, retype.excluded));
+    }
+  }
+  return checked.footer;
+}
+
 /** @internal Root types, the footer, then the closing declarations (Phase 5, step 6). */
 export function transformDocument(schema: OpenAPI3, ctx: GlobalContext): TransformedDocument {
   const document = schema as DocumentObject;
+  withSharedEnumNames(document, ctx);
   const context = createTransformContext(ctx);
   // documentBody registers the enums in the footer, so the footer is read after it.
-  const rawBody = documentBody(document, context);
-  const footer: FooterEntry[] = [...ctx.injectFooter];
-  const body = renameAliasesTakenByFooter(rawBody, footer.filter(isIrDeclaration));
+  const rawBody = documentBody(document, context, () => ctx.injectFooter.filter(isIrDeclaration));
+  const footer = enumValuesChecked(rawBody, [...ctx.injectFooter], ctx);
   const closing = documentClosing(document, context, footer.some(isOperations));
+  const body = renameTakenAliases(rawBody, footer.filter(isIrDeclaration), closing);
   return { body, footer, closing };
 }