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

package/src/application/transform/schema/discriminator-property.ts

@@ -1,5 +1,5 @@
 import { irProperty } from "../../../domain/ir/constructors.js";
-import type { IrPropertySignature } from "../../../domain/ir/nodes.js";
+import type { IrPropertySignature, IrType } from "../../../domain/ir/nodes.js";
 import { toPropertyName } from "../../../domain/ir/property-name.js";
 import { parseRefPointer } from "../../../domain/openapi/json-pointer.js";
 import { literalType } from "../literal-type.js";
@@ -17,12 +17,17 @@ function discriminatorValue(discriminator: Discriminator, path: string): string
   return match ? match[0] : name;
 }
 
-/** The discriminator property, typed as its literal value (`createDiscriminatorProperty`). */
+/**
+ * The discriminator property, typed as its literal value (`createDiscriminatorProperty`), or as
+ * `valueType` gives it; `valueType` returns null to keep the literal.
+ */
 export function discriminatorProperty(
   discriminator: Discriminator,
   path: string,
   isReadonly: boolean,
+  valueType: (value: string | undefined) => IrType | null = () => null,
 ): IrPropertySignature {
   const value = discriminatorValue(discriminator, path);
-  return irProperty(toPropertyName(discriminator.propertyName), literalType(value), { isReadonly });
+  const type = valueType(value) ?? literalType(value);
+  return irProperty(toPropertyName(discriminator.propertyName), type, { isReadonly });
 }

package/src/application/transform/schema/enum-rule.ts

@@ -3,14 +3,21 @@ import {
   irKeyword,
   irObject,
   irReference,
+  irString,
 } from "../../../domain/ir/constructors.js";
 import type { IrType } from "../../../domain/ir/nodes.js";
 import { createRef, parseRefPointer } from "../../../domain/openapi/json-pointer.js";
 import type { SchemaObject } from "../../../domain/openapi/schema-object.js";
+import { OutputFix } from "../../../domain/output-fixes.js";
 import { literalType } from "../literal-type.js";
 import { refType } from "../ref-type.js";
 import { intersectionOf, unionOf } from "../type-combinators.js";
-import type { EnumMemberMetadata, SchemaOptions } from "./schema-context.js";
+import type {
+  DiscriminatorEnumParent,
+  EnumDeclarationRequest,
+  EnumMemberMetadata,
+  SchemaOptions,
+} from "./schema-context.js";
 import type { SchemaRequest, SchemaRule } from "./schema-rule.js";
 
 /** Removed from generated names, so `#/components/schemas/Status` gives `Status`. */
@@ -29,6 +36,9 @@ function nameFromPath(path: string | undefined): string {
     .replace(COMPONENT_SCHEMAS_PREFIX, "");
 }
 
+/** `#/components/schemas/Name`, and no deeper pointer. */
+const COMPONENT_SCHEMA_RE = /^#\/components\/schemas\/[^/]+$/;
+
 function hasEnumMetadata(schema: SchemaObject): boolean {
   return [
     schema["x-enum-varnames"],
@@ -38,26 +48,60 @@ function hasEnumMetadata(schema: SchemaObject): boolean {
   ].some(Array.isArray);
 }
 
+/**
+ * The values a TypeScript enum declares, with their positions in `enum`. With the
+ * `nullable-enums` fix a `null` value is left out (upstream #1872): an enum member cannot be
+ * `null`, so the type adds it as `| null` instead (`tsEnumType`).
+ */
+function tsEnumEntries(schema: SchemaObject, options: SchemaOptions): [unknown, number][] {
+  const entries = (schema.enum ?? []).map((value, index): [unknown, number] => [value, index]);
+  return options.fixes.has(OutputFix.NULLABLE_ENUMS)
+    ? entries.filter(([value]) => value !== null)
+    : entries;
+}
+
 /**
  * `--enum`: string and number enums become TypeScript enums. The original meant to allow `null`
- * too, but tested `typeof value` against `null`, so an enum containing null stays a union.
+ * too, but tested `typeof value` against `null`, so an enum containing null stays a union; the
+ * `nullable-enums` fix declares its other values.
  */
 function isTsEnum(schema: SchemaObject, options: SchemaOptions): boolean {
   if (!options.enum || !schema.enum) {
     return false;
   }
-  const isSupported = schema.enum.every((value) => ["string", "number"].includes(typeof value));
+  const entries = tsEnumEntries(schema, options);
+  // An empty `enum` stays an empty TypeScript enum, as the original made it; an enum of only
+  // `null` has no member left once the fix drops `null`, so it stays a union.
+  const isOnlyNull = entries.length === 0 && schema.enum.length > 0;
+  const isSupported =
+    !isOnlyNull && entries.every(([value]) => ["string", "number"].includes(typeof value));
   // `--conditional-enums` converts only enums that carry x-enum-* metadata.
   return isSupported && (!options.conditionalEnums || hasEnumMetadata(schema));
 }
 
-function enumMetadata(schema: SchemaObject): EnumMemberMetadata[] {
-  return (schema.enum ?? []).map((_, index) => ({
+function enumMetadata(
+  schema: SchemaObject,
+  entries: readonly [unknown, number][],
+): EnumMemberMetadata[] {
+  return entries.map(([, index]) => ({
     name: schema["x-enum-varnames"]?.[index] ?? schema["x-enumNames"]?.[index],
     description: schema["x-enum-descriptions"]?.[index] ?? schema["x-enumDescriptions"]?.[index],
   }));
 }
 
+/**
+ * Whether `null` is a valid value: it is in `enum` and the schema's type admits it (`type`
+ * absent or listing `"null"`, or OpenAPI 3.0 `nullable: true`). Both keywords must pass.
+ */
+function isNullAllowed(schema: SchemaObject): boolean {
+  const { type } = schema;
+  const isTypeNullable =
+    type === undefined ||
+    (Array.isArray(type) && type.includes("null")) ||
+    Boolean(schema.nullable);
+  return (schema.enum ?? []).includes(null) && isTypeNullable;
+}
+
 /**
  * `additionalProperties: true` on a string enum keeps other strings allowed but still offers the
  * listed values in editors: `"a" | "b" | (string & {})`.
@@ -69,14 +113,71 @@ function withOtherStrings(type: IrType, schema: SchemaObject): IrType {
   return unionOf([type, intersectionOf([irKeyword("string"), irObject([])])]);
 }
 
+/** The enum declaration of `schema` typed at `path`; its values are strings and numbers. */
+function enumRequest(
+  schema: SchemaObject,
+  path: string | undefined,
+  options: SchemaOptions,
+): EnumDeclarationRequest {
+  const entries = tsEnumEntries(schema, options);
+  return {
+    name: nameFromPath(path),
+    isComponentSchema: COMPONENT_SCHEMA_RE.test(path ?? ""),
+    values: entries.map(([value]) => value as string | number),
+    metadata: enumMetadata(schema, entries),
+  };
+}
+
+/** One member's type; a quoted member cannot follow a dot, `typeof E["+"]` is the same type. */
+function enumMemberType(enumName: string, member: string): IrType {
+  return member.startsWith('"')
+    ? irIndexedAccess(irReference(`typeof ${enumName}`), irString(JSON.parse(member), "escaped"))
+    : irReference(`${enumName}.${member}`);
+}
+
+/**
+ * The `discriminator-values` fix: a member's discriminator value is typed with members of
+ * the owner's enum (`PetType.Cat`), so the member is one of the owner's type (#1700). `key` is the
+ * enum the scan added or the inherited discriminator object. Null when the fix is off, or the
+ * owner's property is no TypeScript enum with every value.
+ */
+export function ownerEnumMembersType(
+  key: object,
+  values: readonly unknown[],
+  request: SchemaRequest,
+): IrType | null {
+  const { options, discriminators, footer } = request.context;
+  const parent: DiscriminatorEnumParent | undefined = options.fixes.has(
+    OutputFix.DISCRIMINATOR_VALUES,
+  )
+    ? discriminators.enumParentOf(key)
+    : undefined;
+  if (parent === undefined || !isTsEnum(parent.schema, options)) {
+    return null;
+  }
+  const reference = { ...enumRequest(parent.schema, parent.path, options), isOwnerReference: true };
+  const name = footer.addEnum(reference);
+  const members = footer.enumMembers(name);
+  const names = values.map((value) => members.get(value as string | number));
+  if (names.length === 0 || names.some((member) => member === undefined)) {
+    return null;
+  }
+  return unionOf(names.map((member) => enumMemberType(name, member as string)));
+}
+
 function tsEnumType(schema: SchemaObject, request: SchemaRequest): IrType {
-  // `isTsEnum` admits only strings and numbers, so there is no null member to split off.
-  const name = request.context.footer.addEnum({
-    name: nameFromPath(request.location.path),
-    values: (schema.enum ?? []) as (string | number)[],
-    metadata: enumMetadata(schema),
-  });
-  return withOtherStrings(irReference(name), schema);
+  const { options, footer } = request.context;
+  // `isTsEnum` admits only strings and numbers, and the fix leaves `null` out of the members.
+  const values = tsEnumEntries(schema, options).map(([value]) => value);
+  const type =
+    ownerEnumMembersType(schema, values, request) ??
+    withOtherStrings(
+      irReference(footer.addEnum(enumRequest(schema, request.location.path, options))),
+      schema,
+    );
+  return options.fixes.has(OutputFix.NULLABLE_ENUMS) && isNullAllowed(schema)
+    ? unionOf([type, irKeyword("null")])
+    : type;
 }
 
 function isUnionPosition(pointer: readonly string[], index: number): boolean {
@@ -84,13 +185,35 @@ function isUnionPosition(pointer: readonly string[], index: number): boolean {
   return UNION_KEYWORDS.has(pointer[index] as string) && next !== undefined && INDEX_RE.test(next);
 }
 
+const PARAMETERS = "parameters";
+
+/** Where the `parameters` of a path item sit in its pointer: `paths/<key>/…`, `components/…`. */
+function pathItemParametersIndex(pointer: readonly string[]): number | null {
+  if (pointer[0] === "paths" || pointer[0] === "webhooks") {
+    return 2;
+  }
+  return pointer[0] === "components" && pointer[1] === "pathItems" ? 3 : null;
+}
+
+/**
+ * The location of a path item parameter repeats `parameters` (`paths/~1a/parameters/parameters/
+ * path/id`), which keeps the generated names as they were. The generated type has the segment
+ * once: `paths["/a"]["parameters"]["path"]["id"]`.
+ */
+function withSingleParametersSegment(pointer: readonly string[]): readonly string[] {
+  const index = pathItemParametersIndex(pointer);
+  const isRepeated =
+    index !== null && pointer[index] === PARAMETERS && pointer[index + 1] === PARAMETERS;
+  return isRepeated ? [...pointer.slice(0, index), ...pointer.slice(index + 1)] : pointer;
+}
+
 /**
  * The pointer of `--enum-values` arrays without union positions (`anyOf/0`), so names stay
  * stable. Every property after the first union position is narrowed with `Extract`: a no-op where
  * all variants have it, and the needed narrowing where only some do.
  */
 function enumValuesPointer(path: string | undefined): { ref: string; extract: string[] } {
-  const pointer = parseRefPointer(path ?? "");
+  const pointer = withSingleParametersSegment(parseRefPointer(path ?? ""));
   const kept: string[] = [];
   let firstVariantStart: number | null = null;
   for (let index = 0; index < pointer.length; index++) {

package/src/application/transform/schema/inherited-discriminator.ts

@@ -0,0 +1,54 @@
+import type { IrMember } from "../../../domain/ir/nodes.js";
+import { unionAt, unionReaches } from "../../../domain/openapi/discriminated-union.js";
+import type { SchemaObject } from "../../../domain/openapi/schema-object.js";
+import { discriminatorProperty } from "./discriminator-property.js";
+import { ownerEnumMembersType } from "./enum-rule.js";
+import type { Discriminator } from "./schema-context.js";
+import type { SchemaRequest } from "./schema-rule.js";
+
+/**
+ * Whether the schema at `path` is a union that its own members inherit from (upstream #1665).
+ * Each member sets the discriminator value, so a value of the union's own would make every member
+ * `never`. The union's own keywords, which its members get, are typed at the same path.
+ */
+function isInheritedUnion(path: string, request: SchemaRequest): boolean {
+  const resolve = (ref: string) => request.context.refs.resolve(ref);
+  const union = unionAt(path, resolve);
+  return union !== undefined && unionReaches(union, path, resolve);
+}
+
+/** A discriminator a parent's mapping implies for the schema at `path`. */
+export interface InheritedDiscriminator {
+  readonly discriminator: Discriminator;
+  readonly path: string;
+}
+
+/**
+ * The discriminator a parent's mapping implies for this schema, if it adds a property. A schema
+ * with no path (a caller's own schema) is no component, so no mapping names it.
+ */
+export function inheritedDiscriminator(
+  schema: SchemaObject,
+  request: SchemaRequest,
+): InheritedDiscriminator | undefined {
+  const { path } = request.location;
+  if ((!schema.allOf && !schema.anyOf) || path === undefined) {
+    return undefined;
+  }
+  const { discriminators } = request.context;
+  // A schema does not get the discriminator it defines for its children, nor one added already.
+  const isAdded = !schema.discriminator && !discriminators.isHandled(path);
+  const discriminator = isAdded ? discriminators.objectAt(path) : undefined;
+  return discriminator && !isInheritedUnion(path, request) ? { discriminator, path } : undefined;
+}
+
+/** The property of an inherited discriminator, typed as the schema's value. */
+export function discriminatorMember(
+  { discriminator, path }: InheritedDiscriminator,
+  request: SchemaRequest,
+): IrMember {
+  // With `discriminator-values`, the value is a member of the owner's enum (#1700).
+  const valueType = (value: string | undefined) =>
+    ownerEnumMembersType(discriminator, [value], request);
+  return discriminatorProperty(discriminator, path, request.context.options.immutable, valueType);
+}

package/src/application/transform/schema/object-type.ts

@@ -10,11 +10,12 @@ import { toPropertyName } from "../../../domain/ir/property-name.js";
 import { createRef } from "../../../domain/openapi/json-pointer.js";
 import type { Schema, SchemaObject } from "../../../domain/openapi/schema-object.js";
 import { documentEntries } from "../document-entries.js";
-import { refType } from "../ref-type.js";
-import { withSchemaComment } from "../schema-comment.js";
+import { schemaRefType } from "../ref-pointer/pointer-type.js";
+import { schemaCommentOptionsOf, withSchemaComment } from "../schema-comment.js";
 import { UNKNOWN_TYPE } from "../shared-types.js";
 import { intersectionOf, unionOf } from "../type-combinators.js";
-import { discriminatorProperty } from "./discriminator-property.js";
+import { type AccessFlags, propertyAccessFlags } from "./access-flags.js";
+import { discriminatorMember, inheritedDiscriminator } from "./inherited-discriminator.js";
 import type { SchemaOptions } from "./schema-context.js";
 import type { SchemaRequest } from "./schema-rule.js";
 
@@ -42,11 +43,6 @@ function withReadWriteMarker(type: IrType, flags: AccessFlags, options: SchemaOp
   return irReference(flags.isReadOnly ? "$Read" : "$Write", [type]);
 }
 
-interface AccessFlags {
-  readonly isReadOnly: boolean;
-  readonly isWriteOnly: boolean;
-}
-
 /** Apply `transformProperty`, then the schema's JSDoc. */
 function finishProperty(
   property: IrPropertySignature,
@@ -58,7 +54,11 @@ function finishProperty(
   const transformed =
     request.context.callbacks.transformProperty(property, schema, location) ?? property;
   // The original adds the schema's comment after any comment the callback set.
-  return withSchemaComment(transformed, schema);
+  return withSchemaComment(
+    transformed,
+    schema,
+    schemaCommentOptionsOf(request.context.options.fixes),
+  );
 }
 
 /** What the property loop reads from a property schema, in the original order. */
@@ -68,16 +68,13 @@ interface PropertyFacts {
   readonly hasDefault: boolean;
 }
 
-function propertyFacts(value: Schema): PropertyFacts {
+function propertyFacts(value: Schema, request: SchemaRequest): PropertyFacts {
   if (typeof value !== "object") {
     return { ref: undefined, flags: { isReadOnly: false, isWriteOnly: false }, hasDefault: false };
   }
   // `in` throws for a null value, as in the original (which also reads `$ref` first).
   const ref = "$ref" in value && value.$ref ? value.$ref : undefined;
-  const flags = {
-    isReadOnly: Boolean("readOnly" in value && value.readOnly),
-    isWriteOnly: Boolean("writeOnly" in value && value.writeOnly),
-  };
+  const flags = propertyAccessFlags(value, request.context);
   return { ref, flags, hasDefault: "default" in value && value.default !== undefined };
 }
 
@@ -122,7 +119,7 @@ function propertyType(
 ): CustomResult {
   const path = createRef([request.location.path, key]);
   const type = facts.ref
-    ? refType(facts.ref)
+    ? schemaRefType(facts.ref, request)
     : request.transformNested(value, { ...request.location, path });
   const custom = request.context.callbacks.transform(value, request.location);
   return custom === null
@@ -139,7 +136,7 @@ function propertyMember(
   if ((typeof value !== "object" && typeof value !== "boolean") || Array.isArray(value)) {
     throw new InvalidPropertyError(request.location.path, key, value);
   }
-  const facts = propertyFacts(value);
+  const facts = propertyFacts(value, request);
   if (isExcluded(value, facts, request)) {
     return null;
   }
@@ -180,10 +177,7 @@ function defsMember(
   const { options } = request.context;
   const members = Object.entries(defs).map(([key, value]) => {
     const path = createRef([request.location.path, "$defs", key]);
-    const flags = {
-      isReadOnly: "readOnly" in value && !!value.readOnly,
-      isWriteOnly: "writeOnly" in value && !!value.writeOnly,
-    };
+    const flags = propertyAccessFlags(value, request.context);
     const type = withReadWriteMarker(
       request.transformNested(value, { ...request.location, path }),
       flags,
@@ -228,17 +222,41 @@ function indexValueTypes(schema: SchemaObject, request: SchemaRequest): IrType[]
   return types;
 }
 
-/** The discriminator property that a parent's mapping implies for this schema, if any. */
-function discriminatorMembers(schema: SchemaObject, request: SchemaRequest): IrMember[] {
-  if (!schema.allOf && !schema.anyOf) {
-    return [];
+/**
+ * Whether the schema declares property `key` and the type keeps it: `--exclude-deprecated` drops
+ * a deprecated one.
+ */
+export function isKeptProperty(schema: SchemaObject, key: string, request: SchemaRequest): boolean {
+  const properties = schema.properties ?? {};
+  if (!Object.hasOwn(properties, key)) {
+    return false;
   }
-  const path = request.location.path ?? "";
-  const { discriminators, options } = request.context;
-  // A schema does not get the discriminator it defines for its children, nor one added already.
-  const discriminator =
-    !schema.discriminator && !discriminators.isHandled(path) && discriminators.objectAt(path);
-  return discriminator ? [discriminatorProperty(discriminator, path, options.immutable)] : [];
+  const value = properties[key] as Schema;
+  const isExcludable = request.context.options.excludeDeprecated && typeof value === "object";
+  return !isExcludable || !isExcluded(value, propertyFacts(value, request), request);
+}
+
+/**
+ * The members for the discriminator and `properties`. A schema that declares the discriminator
+ * property itself keeps its own declaration, required as the discriminator needs: both in one
+ * object type do not compile (TS2300, the Apple SiriKit Cloud Media API). A declaration that
+ * `--exclude-deprecated` drops does not count, so the discriminator property stays.
+ */
+function discriminatorAndPropertyMembers(schema: SchemaObject, request: SchemaRequest): IrMember[] {
+  const inherited = inheritedDiscriminator(schema, request);
+  if (inherited === undefined) {
+    return propertyMembers(schema, request);
+  }
+  const name = inherited.discriminator.propertyName;
+  if (!isKeptProperty(schema, name, request)) {
+    return [discriminatorMember(inherited, request), ...propertyMembers(schema, request)];
+  }
+  // Without `required`, `--properties-required-by-default` requires every property already; a
+  // list of one would make the others optional.
+  const isAllRequired =
+    schema.required === undefined && request.context.options.propertiesRequiredByDefault;
+  const required = isAllRequired ? undefined : [...(schema.required ?? []), name];
+  return propertyMembers({ ...schema, required } as SchemaObject, request);
 }
 
 /**
@@ -247,11 +265,11 @@ function discriminatorMembers(schema: SchemaObject, request: SchemaRequest): IrM
  * has none of them.
  */
 export function objectType(schema: SchemaObject, request: SchemaRequest): IrType | null {
-  const members = discriminatorMembers(schema, request);
   if (!hasObjectKeywords(schema)) {
-    return members.length > 0 ? irObject(members) : null;
+    const inherited = inheritedDiscriminator(schema, request);
+    return inherited ? irObject([discriminatorMember(inherited, request)]) : null;
   }
-  members.push(...propertyMembers(schema, request));
+  const members = discriminatorAndPropertyMembers(schema, request);
   // As in the original, a null `$defs` throws here (Object.keys) instead of being skipped.
   if (
     "$defs" in schema &&

package/src/application/transform/schema/required-variants.ts

@@ -0,0 +1,88 @@
+import type { IrType } from "../../../domain/ir/nodes.js";
+import type { Schema, SchemaObject } from "../../../domain/openapi/schema-object.js";
+import { OutputFix } from "../../../domain/output-fixes.js";
+import { unionOf, withRequiredKeys } from "../type-combinators.js";
+import { isKeptProperty } from "./object-type.js";
+import type { SchemaRequest } from "./schema-rule.js";
+
+/**
+ * The `anyof-oneof-required` fix. `anyOf: [{ required: [a] }, { required: [b] }]` next to
+ * `properties` says which of the properties must be there. Each such variant has no type of its
+ * own (`unknown`), so the original gives `Props | unknown`, which is `unknown`. With the fix each
+ * variant is the parent with its keys required:
+ * `WithRequired<Props, "a"> | WithRequired<Props, "b">`.
+ */
+
+/** Keywords that do not change a value's type: a variant of these and `required` counts. */
+const ANNOTATION_KEYS: ReadonlySet<string> = new Set(["required", "description", "title"]);
+
+/** The `required` keys of a variant that has nothing else, or null for any other variant. */
+function requiredOnlyKeys(variant: Schema): readonly string[] | null {
+  if (typeof variant !== "object" || variant === null || "$ref" in variant) {
+    return null;
+  }
+  const { required } = variant as SchemaObject;
+  const isRequiredOnly = Object.keys(variant).every((key) => ANNOTATION_KEYS.has(key));
+  return isRequiredOnly && Array.isArray(required) && required.length > 0 ? required : null;
+}
+
+/** Whether the schema's type is an object: no `type`, `object`, or a list with `object`. */
+function isObjectTyped(schema: SchemaObject): boolean {
+  const { type } = schema;
+  return (
+    type === undefined || type === "object" || (Array.isArray(type) && type.includes("object"))
+  );
+}
+
+/** The variants' key lists, or null unless each requires only properties the type keeps. */
+function requiredKeyLists(
+  schema: SchemaObject,
+  variants: readonly Schema[],
+  request: SchemaRequest,
+): (readonly string[])[] | null {
+  const keyLists = variants.map(requiredOnlyKeys);
+  // A key of a property the type leaves out (`--exclude-deprecated`) is no key of `WithRequired`.
+  const isApplicable =
+    keyLists.length > 0 &&
+    keyLists.every((keys) => keys?.every((key) => isKeptProperty(schema, key, request)) === true);
+  return isApplicable ? (keyLists as (readonly string[])[]) : null;
+}
+
+/** Whether the fix gives `variants` of the schema their keys of its properties. */
+export function hasRequiredVariants(
+  schema: SchemaObject,
+  variants: readonly Schema[],
+  request: SchemaRequest,
+): boolean {
+  return (
+    request.context.options.fixes.has(OutputFix.ANYOF_ONEOF_REQUIRED) &&
+    isObjectTyped(schema) &&
+    requiredKeyLists(schema, variants, request) !== null
+  );
+}
+
+/**
+ * The union of the parent type with each variant's keys required, or null where the fix is off
+ * or the variants are not all required-only ones over the parent's own, kept properties. Only an
+ * object has the keys. For a `type` list, the `object` member has required them already
+ * (`multipleTypes`), so the list is the whole type.
+ */
+export function requiredVariantsType(
+  previous: IrType | null,
+  schema: SchemaObject,
+  variants: readonly Schema[],
+  request: SchemaRequest,
+): IrType | null {
+  if (!request.context.options.fixes.has(OutputFix.ANYOF_ONEOF_REQUIRED) || previous === null) {
+    return null;
+  }
+  const keyLists = isObjectTyped(schema) ? requiredKeyLists(schema, variants, request) : null;
+  if (keyLists === null) {
+    return null;
+  }
+  if (Array.isArray(schema.type)) {
+    return previous;
+  }
+  request.context.footer.requireWithRequired();
+  return unionOf(keyLists.map((keys) => withRequiredKeys(previous, keys)));
+}

package/src/application/transform/schema/schema-context.ts

@@ -1,4 +1,5 @@
 import type { IrPropertySignature, IrType } from "../../../domain/ir/nodes.js";
+import type { SchemaObject } from "../../../domain/openapi/schema-object.js";
 import type { OutputFix } from "../../../domain/output-fixes.js";
 
 /**
@@ -43,11 +44,27 @@ export interface Discriminator {
   readonly mapping?: Readonly<Record<string, string>> | undefined;
 }
 
+/** The enum of a discriminator owner's property, and the location it is typed at. */
+export interface DiscriminatorEnumParent {
+  readonly schema: SchemaObject;
+  readonly path: string;
+}
+
 export interface Discriminators {
   /** The discriminator that applies to the schema at this `$ref`, if any. */
   objectAt(ref: string): Discriminator | undefined;
   /** Whether the discriminator property of this `$ref` was already added. */
   isHandled(ref: string): boolean;
+  /**
+   * With `discriminator-values`: the properties of the discriminators the schema at `ref`
+   * inherits besides `objectAt`'s. It redefines them too, so its `allOf` items omit them.
+   */
+  otherPropertiesAt(ref: string): readonly string[];
+  /**
+   * With `discriminator-values`: the owner's enum that a member's value narrows, found by
+   * the enum schema the discriminator scan added or by the discriminator object of `objectAt`.
+   */
+  enumParentOf(schema: object): DiscriminatorEnumParent | undefined;
 }
 
 export interface RefResolver {
@@ -62,8 +79,15 @@ export interface EnumMemberMetadata {
 
 export interface EnumDeclarationRequest {
   readonly name: string;
+  /** Whether the schema is a component schema itself (`#/components/schemas/Name`). */
+  readonly isComponentSchema: boolean;
   readonly values: readonly (string | number)[];
   readonly metadata: readonly EnumMemberMetadata[];
+  /**
+   * The request only refers to the enum, for a discriminator member's value
+   * (`discriminator-values`); the schema at `name` declares it where it is typed itself.
+   */
+  readonly isOwnerReference?: boolean;
 }
 
 export interface EnumValuesRequest {
@@ -76,6 +100,8 @@ export interface EnumValuesRequest {
 export interface FooterDeclarations {
   /** Add (or reuse) an enum declaration and return the name it was declared with. */
   addEnum(request: EnumDeclarationRequest): string;
+  /** The member names of the enum declared with this name, by value; empty for another name. */
+  enumMembers(name: string): ReadonlyMap<string | number, string>;
   /** Add an exported, readonly array of enum values (`--enum-values`). */
   addEnumValues(request: EnumValuesRequest): void;
   /** Make sure the `WithRequired` helper type is declared. */

package/src/application/transform/schema/schema-transform.ts

@@ -3,7 +3,7 @@ import { irKeyword } from "../../../domain/ir/constructors.js";
 import type { IrType } from "../../../domain/ir/nodes.js";
 import type { Schema, SchemaObject } from "../../../domain/openapi/schema-object.js";
 import { literalType } from "../literal-type.js";
-import { refType } from "../ref-type.js";
+import { schemaRefType } from "../ref-pointer/pointer-type.js";
 import { UNKNOWN_TYPE } from "../shared-types.js";
 import { compositionType } from "./composition-type.js";
 import { enumRule } from "./enum-rule.js";
@@ -27,7 +27,7 @@ const SHAPE_RULES: readonly SchemaRule[] = [
   {
     name: "$ref",
     matches: (schema) => "$ref" in schema,
-    transform: (schema) => refType((schema as { $ref: string }).$ref),
+    transform: (schema, request) => schemaRefType((schema as { $ref: string }).$ref, request),
   },
   {
     name: "const",