openapi-typesafe 0.0.0 → 1.0.0-rc.1

package/src/application/transform/ref-pointer/generated-shape.ts

@@ -0,0 +1,275 @@
+import { isRawBinarySchema } from "../../../domain/openapi/binary-content.js";
+import type { RefResolver, SchemaOptions } from "../schema/schema-context.js";
+
+/**
+ * What the generated type of a schema has under a key, read from the schema itself. It answers the
+ * question TypeScript answers when it checks `T["key"]`, for the schema shapes where the answer is
+ * sure; for every other shape it says `opaque`, so a caller never assumes an error that is not.
+ */
+
+export type GeneratedMember =
+  | { readonly kind: "property"; readonly node: unknown; readonly isOptional: boolean }
+  /** An index signature; `node` is undefined when its value type is `unknown`. */
+  | { readonly kind: "index"; readonly node: unknown }
+  | { readonly kind: "missing" }
+  | { readonly kind: "opaque" };
+
+type JsonObject = Readonly<Record<string, unknown>>;
+
+const OPAQUE_KEYS = ["not", "enum", "const", "$ref"] as const;
+/** How deep `allOf`/`anyOf`/`oneOf` members are read; deeper shapes count as opaque. */
+const MAX_DEPTH = 8;
+const INDEX_RE = /^\d+$/;
+const MISSING: GeneratedMember = { kind: "missing" };
+const OPAQUE: GeneratedMember = { kind: "opaque" };
+
+export function isJsonObject(value: unknown): value is JsonObject {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+/** The schema a node stands for: a `$ref` is followed to its target. */
+export function followRefs(node: unknown, refs: RefResolver): unknown {
+  return isJsonObject(node) && typeof node.$ref === "string" ? refs.resolve(node.$ref) : node;
+}
+
+/** `nullable: true` or a `type` list with `null`: the generated type includes `null`. */
+export function isNullableSchema(node: unknown): boolean {
+  if (!isJsonObject(node)) {
+    return false;
+  }
+  return node.nullable === true || (Array.isArray(node.type) && node.type.includes("null"));
+}
+
+function typeNames(node: JsonObject): readonly unknown[] {
+  return Array.isArray(node.type) ? node.type : [node.type];
+}
+
+/**
+ * Whether the generated type is an object. One `type` name decides alone: `type: string` with
+ * `properties` or `items` is `string`, as `coreType` matches the `type` before the keywords.
+ */
+export function isObjectShape(node: JsonObject): boolean {
+  if (typeof node.type === "string") {
+    return node.type === "object";
+  }
+  return (
+    typeNames(node).includes("object") ||
+    "properties" in node ||
+    "additionalProperties" in node ||
+    "patternProperties" in node
+  );
+}
+
+/** Whether the generated type is an array; one `type` name decides alone (`isObjectShape`). */
+export function isArrayShape(node: JsonObject): boolean {
+  if (typeof node.type === "string") {
+    return node.type === "array";
+  }
+  return typeNames(node).includes("array") || "items" in node;
+}
+
+/** Whether `objectType` writes a type for the schema; the same test as there. */
+function hasObjectKeywords(node: JsonObject): boolean {
+  const hasProperties = isJsonObject(node.properties) && Object.keys(node.properties).length > 0;
+  return (
+    hasProperties || Boolean(node.additionalProperties || node.patternProperties || node.$defs)
+  );
+}
+
+/**
+ * A key of an object schema without object keywords. With a `type` it is `Record<string, never>`:
+ * every key is `never`, and so is every key after it (or `unknown` with `--empty-objects-unknown`,
+ * which has no key). Without a `type` it is `unknown`.
+ */
+function emptyObjectMember(node: JsonObject, options: SchemaOptions): GeneratedMember {
+  return node.type !== undefined && !options.emptyObjectsUnknown ? OPAQUE : MISSING;
+}
+
+/** Whether a key the object has no property for is still a member: `toString`, `length`, `0`. */
+function isBuiltInMember(key: string, prototype: object): boolean {
+  return key in prototype;
+}
+
+function indexMember(node: JsonObject, options: SchemaOptions): GeneratedMember | null {
+  const { additionalProperties: values, patternProperties: patterns } = node;
+  if (isJsonObject(patterns) && Object.keys(patterns).length > 0) {
+    return OPAQUE;
+  }
+  if (isJsonObject(values) && Object.keys(values).length > 0) {
+    return { kind: "index", node: values };
+  }
+  const isImplicit = values === true || (isJsonObject(values) && Object.keys(values).length === 0);
+  return isImplicit || (!values && options.additionalProperties)
+    ? { kind: "index", node: undefined }
+    : null;
+}
+
+function isOptionalProperty(node: JsonObject, key: string, options: SchemaOptions): boolean {
+  const required = Array.isArray(node.required) ? node.required : undefined;
+  const property = (node.properties as JsonObject)[key];
+  const hasDefault = isJsonObject(property) && property.default !== undefined;
+  const isRequired =
+    required?.includes(key) === true ||
+    (required === undefined && options.propertiesRequiredByDefault) ||
+    (hasDefault && options.defaultNonNullable);
+  return !isRequired;
+}
+
+function objectMember(node: JsonObject, key: string, options: SchemaOptions): GeneratedMember {
+  const properties = isJsonObject(node.properties) ? node.properties : {};
+  if (Object.hasOwn(properties, key)) {
+    const property = properties[key];
+    const isExcluded = options.excludeDeprecated && isJsonObject(property) && property.deprecated;
+    return isExcluded || isJsonObject(node.discriminator)
+      ? OPAQUE
+      : { kind: "property", node: property, isOptional: isOptionalProperty(node, key, options) };
+  }
+  // `unevaluatedProperties` adds an index signature with its fix, so it counts as opaque too.
+  const isUnknownShape =
+    isJsonObject(node.discriminator) || node.unevaluatedProperties !== undefined;
+  if (isBuiltInMember(key, {}) || key === "$defs" || isUnknownShape) {
+    return OPAQUE;
+  }
+  return hasObjectKeywords(node)
+    ? (indexMember(node, options) ?? MISSING)
+    : emptyObjectMember(node, options);
+}
+
+/** Whether a value is there: `present`, `absent` (may be `undefined` or `null`) or `unknown`. */
+export type Presence = "present" | "absent" | "unknown";
+
+/** The presence of a value of `schema` itself: `absent` when its type includes `null`. */
+export function schemaPresence(schema: unknown, refs: RefResolver): Presence {
+  return isNullableSchema(followRefs(schema, refs)) ? "absent" : "present";
+}
+
+/** The presence of property `key` of `schema`: optional or nullable is `absent`. */
+export function propertyPresence(
+  schema: unknown,
+  key: string,
+  options: SchemaOptions,
+  refs: RefResolver,
+): Presence {
+  const node = followRefs(schema, refs);
+  const properties = isJsonObject(node) && isJsonObject(node.properties) ? node.properties : {};
+  if (!isJsonObject(node) || !Object.hasOwn(properties, key)) {
+    return "unknown";
+  }
+  return isOptionalProperty(node, key, options) ? "absent" : schemaPresence(properties[key], refs);
+}
+
+function membersOf(node: JsonObject, keyword: string): readonly unknown[] {
+  const members = node[keyword];
+  return Array.isArray(members) ? members : [];
+}
+
+function withoutComposition(node: JsonObject): JsonObject {
+  const { allOf: _allOf, anyOf: _anyOf, oneOf: _oneOf, ...own } = node;
+  return own;
+}
+
+/** Own keywords without an object type of their own (`properties: {}`) add no part. */
+function hasOwnObjectType(own: JsonObject): boolean {
+  return isObjectShape(own) && (hasObjectKeywords(own) || isJsonObject(own.discriminator));
+}
+
+/**
+ * `allOf` with own keywords is an intersection (`intersectionMember`).
+ * `anyOf` or `oneOf` alone is a union: a key is missing if one member misses it. A mix of both
+ * is written in more than one way (`anyof-properties`), so it counts as opaque.
+ */
+function composedMember(node: JsonObject, key: string, input: MemberInput): GeneratedMember {
+  const variants = [...membersOf(node, "anyOf"), ...membersOf(node, "oneOf")];
+  const own = withoutComposition(node);
+  const hasOwn = hasOwnObjectType(own);
+  if (variants.length > 0) {
+    const isAlone = membersOf(node, "allOf").length === 0 && !hasOwn;
+    const members = variants.map((variant) => memberAt(variant, key, input));
+    return isAlone && members.some((member) => member.kind === "missing") ? MISSING : OPAQUE;
+  }
+  const parts = [...membersOf(node, "allOf"), ...(hasOwn ? [own] : [])];
+  return intersectionMember(parts.map((part) => memberAt(part, key, input)));
+}
+
+function isUnknownIndex(member: GeneratedMember): boolean {
+  return member.kind === "index" && member.node === undefined;
+}
+
+/**
+ * A key of an intersection: missing if every part misses it; the part's member if only one part
+ * has it (`A & B` where `B` has no such key and no index signature); else opaque. A part's
+ * `[key: string]: unknown` adds nothing (`unknown & T` is `T`), and only such parts give `unknown`.
+ */
+function intersectionMember(members: readonly GeneratedMember[]): GeneratedMember {
+  const found = members.filter((member) => member.kind !== "missing");
+  const typed = found.filter((member) => !isUnknownIndex(member));
+  const [only] = typed;
+  if (only === undefined) {
+    return found[0] ?? MISSING;
+  }
+  return typed.length === 1 && only.kind !== "opaque" ? only : OPAQUE;
+}
+
+interface MemberInput {
+  readonly options: SchemaOptions;
+  readonly refs: RefResolver;
+  readonly depth: number;
+}
+
+function memberAt(schema: unknown, key: string, input: MemberInput): GeneratedMember {
+  const node = followRefs(schema, input.refs);
+  if (!isJsonObject(node) || OPAQUE_KEYS.some((name) => name in node) || input.depth > MAX_DEPTH) {
+    return OPAQUE;
+  }
+  if (isNullableSchema(node)) {
+    // Every key of `T | null` is an error, unless `T` is unknown (then the type is `unknown`).
+    return isObjectShape(node) || isArrayShape(node) ? MISSING : OPAQUE;
+  }
+  if (input.options.readWriteMarkers) {
+    return OPAQUE;
+  }
+  if ("allOf" in node || "anyOf" in node || "oneOf" in node) {
+    return composedMember(node, key, { ...input, depth: input.depth + 1 });
+  }
+  if (isObjectShape(node)) {
+    return objectMember(node, key, input.options);
+  }
+  if (isArrayShape(node)) {
+    return INDEX_RE.test(key) || isBuiltInMember(key, []) ? OPAQUE : MISSING;
+  }
+  // `--binary-as-blob` types raw binary strings as `Blob`, which has members of its own.
+  return input.options.binaryAsBlob && isRawBinarySchema(node as never)
+    ? OPAQUE
+    : primitiveMember(node, key);
+}
+
+/** The JavaScript value whose members a primitive `type` has: `"".length`, `(0).toFixed`. */
+const PRIMITIVE_PROTOTYPES: Readonly<Record<string, object>> = {
+  string: String.prototype,
+  number: Number.prototype,
+  integer: Number.prototype,
+  boolean: Boolean.prototype,
+};
+
+/**
+ * A key of a schema with one primitive `type`: missing unless the primitive has it. Object and
+ * array keywords next to that `type` do not change the type (`isObjectShape`). Without a `type`
+ * and object keywords the schema is `unknown` (`objectType` writes nothing), which has no keys.
+ */
+function primitiveMember(node: JsonObject, key: string): GeneratedMember {
+  if (node.type === undefined) {
+    return hasObjectKeywords(node) ? OPAQUE : MISSING;
+  }
+  const prototype = typeof node.type === "string" ? PRIMITIVE_PROTOTYPES[node.type] : undefined;
+  return prototype !== undefined && !isBuiltInMember(key, prototype) ? MISSING : OPAQUE;
+}
+
+/** The member `key` of the type generated for `schema` (a `$ref` is followed first). */
+export function generatedMember(
+  schema: unknown,
+  key: string,
+  options: SchemaOptions,
+  refs: RefResolver,
+): GeneratedMember {
+  return memberAt(schema, key, { options, refs, depth: 0 });
+}

package/src/application/transform/ref-pointer/inline-cycles.ts

@@ -0,0 +1,56 @@
+import type { RefResolver, SchemaOptions } from "../schema/schema-context.js";
+import { isJsonObject } from "./generated-shape.js";
+import { pointerNode, refPointerOf } from "./pointer-walk.js";
+import { typedWalk } from "./typed-walk.js";
+
+/**
+ * A `$ref` whose pointer crosses a segment with no type (`definitions/A`) is typed by writing its
+ * target inline. If the target, directly or through other such `$ref`s, points back at itself,
+ * writing it inline never ends; such a `$ref` keeps the original type.
+ */
+
+interface CycleInput {
+  readonly options: SchemaOptions;
+  readonly refs: RefResolver;
+}
+
+function refsIn(node: unknown, found: string[] = []): string[] {
+  if (Array.isArray(node)) {
+    for (const item of node) {
+      refsIn(item, found);
+    }
+  } else if (isJsonObject(node)) {
+    if (typeof node.$ref === "string") {
+      found.push(node.$ref);
+    }
+    for (const value of Object.values(node)) {
+      refsIn(value, found);
+    }
+  }
+  return found;
+}
+
+function isWrittenInline(ref: string, input: CycleInput): boolean {
+  const pointer = refPointerOf(ref);
+  return pointer !== null && typedWalk({ pointer, ...input }).kind === "untyped";
+}
+
+/** Depth-first search with the usual colors: a `$ref` met again while it is open is a cycle. */
+function reachesOpenRef(ref: string, open: Map<string, boolean>, input: CycleInput): boolean {
+  if (open.has(ref)) {
+    return open.get(ref) === true;
+  }
+  open.set(ref, true);
+  const pointer = refPointerOf(ref);
+  const target = pointer === null ? undefined : pointerNode(pointer, input.refs);
+  const isCycle = refsIn(target).some(
+    (inner) => isWrittenInline(inner, input) && reachesOpenRef(inner, open, input),
+  );
+  open.set(ref, false);
+  return isCycle;
+}
+
+/** Whether writing the target of `ref` inline would write it again inside itself. */
+export function hasInlineCycle(ref: string, options: SchemaOptions, refs: RefResolver): boolean {
+  return reachesOpenRef(ref, new Map(), { options, refs });
+}

package/src/application/transform/ref-pointer/original-index.ts

@@ -0,0 +1,95 @@
+import type { RefResolver, SchemaOptions } from "../schema/schema-context.js";
+import { followRefs, generatedMember, isJsonObject } from "./generated-shape.js";
+import {
+  isOptionalHeader,
+  isOptionalRequestBody,
+  isParameterList,
+  isTypedAsSchema,
+  leadingNode,
+  leadingSegmentsOf,
+  type RefPointer,
+  startsInSchema,
+} from "./pointer-walk.js";
+
+/**
+ * Whether the type the original wrote for a `$ref` (`refType`: every segment indexed by name,
+ * `properties` skipped) surely fails to compile. It walks the document as TypeScript walks the
+ * generated types and answers true only where TypeScript reports an error for sure; where the
+ * answer depends on a shape it does not model, it answers false, so that output stays as it was.
+ */
+
+type Step = "fails" | "compiles" | "continue";
+
+interface OriginalWalk {
+  readonly node: unknown;
+  readonly isSchema: boolean;
+}
+
+interface WalkInput {
+  readonly pointer: RefPointer;
+  readonly options: SchemaOptions;
+  readonly refs: RefResolver;
+}
+
+function schemaStep(walk: OriginalWalk, segment: string, isLast: boolean, input: WalkInput) {
+  if (segment === "properties") {
+    return { step: "continue" as Step, walk };
+  }
+  const member = generatedMember(walk.node, segment, input.options, input.refs);
+  if (member.kind === "missing") {
+    return { step: "fails" as Step, walk };
+  }
+  if (member.kind === "opaque") {
+    return { step: "compiles" as Step, walk };
+  }
+  const isAbsentValue = member.kind === "index" && member.node === undefined;
+  const isUnsafe = member.kind === "property" ? member.isOptional : isAbsentValue;
+  return {
+    step: (isUnsafe && !isLast ? "fails" : "continue") as Step,
+    walk: { ...walk, node: member.node },
+  };
+}
+
+function containerStep(walk: OriginalWalk, index: number, input: WalkInput) {
+  const segment = input.pointer.segments[index] as string;
+  const isLast = index === input.pointer.segments.length - 1;
+  const isOptional =
+    (segment === "requestBody" && isOptionalRequestBody(walk.node, input.refs)) ||
+    isOptionalHeader(input.pointer, index, walk.node);
+  if (isOptional && !isLast) {
+    return { step: "fails" as Step, walk };
+  }
+  const child = isJsonObject(walk.node) ? followRefs(walk.node[segment], input.refs) : undefined;
+  return {
+    step: (child === undefined ? "compiles" : "continue") as Step,
+    walk: { ...walk, node: child },
+  };
+}
+
+/** True when the original type of the `$ref` does not compile for sure. */
+export function originalIndexFails(input: WalkInput): boolean {
+  const { segments } = input.pointer;
+  let walk: OriginalWalk = {
+    node: leadingNode(input.pointer, input.refs),
+    isSchema: startsInSchema(input.pointer),
+  };
+  for (let index = leadingSegmentsOf(input.pointer); index < segments.length; index++) {
+    const segment = segments[index] as string;
+    const isLast = index === segments.length - 1;
+    if (!walk.isSchema && isParameterList(input.pointer, index)) {
+      return true;
+    }
+    if (!walk.isSchema && isTypedAsSchema(input.pointer, index) && isJsonObject(walk.node)) {
+      // The container's type is its schema's type: the segment indexes that type.
+      walk = { node: followRefs(walk.node.schema, input.refs), isSchema: true };
+    }
+    const result = walk.isSchema
+      ? schemaStep(walk, segment, isLast, input)
+      : containerStep(walk, index, input);
+    if (result.step !== "continue") {
+      return result.step === "fails";
+    }
+    walk = result.walk;
+  }
+  return false;
+}

package/src/application/transform/ref-pointer/pointer-type.ts

@@ -0,0 +1,92 @@
+import { irReference } from "../../../domain/ir/constructors.js";
+import type { IrType } from "../../../domain/ir/nodes.js";
+import { OutputFix } from "../../../domain/output-fixes.js";
+import { InvalidRefError, refType } from "../ref-type.js";
+import type { SchemaRequest } from "../schema/schema-rule.js";
+import { generatedLocationOf } from "./generated-location.js";
+import { isJsonObject } from "./generated-shape.js";
+import { hasInlineCycle } from "./inline-cycles.js";
+import { originalIndexFails } from "./original-index.js";
+import { leadingSegmentsOf, pointerNode, type RefPointer, refPointerOf } from "./pointer-walk.js";
+import { typedWalk } from "./typed-walk.js";
+
+/**
+ * The type of a schema `$ref` (ADR-026). The original indexed every segment of the pointer by
+ * name (`refType`), also schema keywords the generated types do not have (`["schema"]`,
+ * `["items"]`, `["allOf"]["0"]`), and did not look through optional or nullable values. Where that
+ * type does not compile, the `$ref` now gets the type of what it points at; where it compiles
+ * (through an index signature), it stays, and the `ref-pointers` fix gives the right type there.
+ */
+
+function pointerOf(ref: string): RefPointer {
+  const pointer = refPointerOf(ref);
+  if (pointer === null) {
+    throw new InvalidRefError(ref);
+  }
+  return pointer;
+}
+
+/** The target of a pointer that crosses a segment with no type: its `$ref`, or its own type. */
+function targetType(
+  ref: string,
+  pointer: RefPointer,
+  request: SchemaRequest,
+  seen: readonly string[],
+) {
+  const target = pointerNode(pointer, request.context.refs);
+  if (isJsonObject(target) && typeof target.$ref === "string") {
+    return seen.includes(target.$ref) ? null : schemaRefType(target.$ref, request, [...seen, ref]);
+  }
+  if (target === undefined || hasInlineCycle(ref, request.context.options, request.context.refs)) {
+    return null;
+  }
+  // Typed where the generator types the node, so it shares the node's enum (`--enum`).
+  const location = generatedLocationOf(ref, request.context.refs);
+  return request.transformNested(
+    target as never,
+    { path: location.path, schema: target },
+    location.isFromAdditionalProperties,
+  );
+}
+
+function correctedType(
+  ref: string,
+  pointer: RefPointer,
+  request: SchemaRequest,
+  seen: readonly string[],
+) {
+  const { options, refs } = request.context;
+  const result = typedWalk({ pointer, options, refs });
+  return result.kind === "typed" ? result.walk.type : targetType(ref, pointer, request, seen);
+}
+
+function isCorrected(pointer: RefPointer, request: SchemaRequest): boolean {
+  const { options, refs } = request.context;
+  return (
+    options.fixes.has(OutputFix.REF_POINTERS) || originalIndexFails({ pointer, options, refs })
+  );
+}
+
+/** The type of a schema `$ref`. Throws InvalidRefError when the `$ref` has no pointer. */
+export function schemaRefType(
+  ref: string,
+  request: SchemaRequest,
+  seen: readonly string[] = [],
+): IrType {
+  const pointer = pointerOf(ref);
+  if (pointer.segments.length <= leadingSegmentsOf(pointer) || !isCorrected(pointer, request)) {
+    return refType(ref);
+  }
+  return correctedType(ref, pointer, request, seen) ?? refType(ref);
+}
+
+/**
+ * The type of a `$ref` that `WithRequired` takes. A `$ref` to an optional or nullable value has
+ * no keys (`keyof (T | undefined)` is `never`), so it is wrapped in `NonNullable` (TS2344).
+ */
+export function requirableRefType(ref: string, type: IrType, request: SchemaRequest): IrType {
+  const { options, refs } = request.context;
+  const result = typedWalk({ pointer: pointerOf(ref), options, refs });
+  const isAbsent = result.kind === "typed" && result.walk.presence === "absent";
+  return isAbsent ? irReference("NonNullable", [type]) : type;
+}

package/src/application/transform/ref-pointer/pointer-walk.ts

@@ -0,0 +1,96 @@
+import { parseRefPointer } from "../../../domain/openapi/json-pointer.js";
+import type { RefResolver } from "../schema/schema-context.js";
+import { followRefs, isJsonObject } from "./generated-shape.js";
+
+/** The parts of a `$ref` pointer that both the original and the new types walk. */
+
+export interface RefPointer {
+  readonly rootSegment: string;
+  /** The segments after the root: `#/components/schemas/A` gives `["schemas", "A"]`. */
+  readonly segments: readonly string[];
+}
+
+/** Roots whose generated type is keyed by one segment: the path or webhook name. */
+const NAMED_ROOTS: ReadonlySet<string> = new Set(["paths", "webhooks"]);
+
+/**
+ * How many segments after the root index the generated root type directly: one for `paths` and
+ * `webhooks` (`paths["/a"]`, so the path item's own `parameters/0` is walked), two otherwise
+ * (`components["schemas"]["A"]`).
+ */
+export function leadingSegmentsOf(pointer: RefPointer): number {
+  return NAMED_ROOTS.has(pointer.rootSegment) ? 1 : 2;
+}
+
+export function refPointerOf(ref: string): RefPointer | null {
+  const [rootSegment, ...segments] = parseRefPointer(ref);
+  return rootSegment === undefined ? null : { rootSegment, segments };
+}
+
+/** The document node at the end of the leading segments, `$ref`s followed. */
+export function leadingNode(pointer: RefPointer, refs: RefResolver): unknown {
+  let node = refs.resolve(`#/${pointer.rootSegment}`);
+  for (const segment of pointer.segments.slice(0, leadingSegmentsOf(pointer))) {
+    node = isJsonObject(node) ? followRefs(node[segment], refs) : undefined;
+  }
+  return node;
+}
+
+/** The node at the whole pointer, without following a `$ref` at its end. */
+export function pointerNode(pointer: RefPointer, refs: RefResolver): unknown {
+  let node = refs.resolve(`#/${pointer.rootSegment}`);
+  pointer.segments.forEach((segment, index) => {
+    const child = isJsonObject(node) || Array.isArray(node) ? (node as never)[segment] : undefined;
+    node = index === pointer.segments.length - 1 ? child : followRefs(child, refs);
+  });
+  return node;
+}
+
+/** Whether the leading segments name a component schema, so the walk starts inside a schema. */
+export function startsInSchema(pointer: RefPointer): boolean {
+  return pointer.rootSegment === "components" && pointer.segments[0] === "schemas";
+}
+
+/**
+ * Whether the container at `index` is typed as its `schema`: a media type
+ * (`content/<media type>`), a header (`headers/<name>`) or a component parameter.
+ */
+export function isTypedAsSchema(pointer: RefPointer, index: number): boolean {
+  const owner = pointer.segments[index - 2];
+  const isComponentParameter =
+    pointer.rootSegment === "components" && index === 2 && owner === "parameters";
+  return owner === "content" || owner === "headers" || isComponentParameter;
+}
+
+/**
+ * Whether the segment at `index` is an operation's or path item's `parameters` list, indexed by
+ * position next. The generated type groups parameters by `in` (`query`, `path`), so it has no
+ * member `0`.
+ */
+export function isParameterList(pointer: RefPointer, index: number): boolean {
+  const next = pointer.segments[index + 1] ?? "";
+  return pointer.segments[index] === "parameters" && /^\d+$/.test(next);
+}
+
+/**
+ * Whether the segment at `index` names a response header that is an optional member: one the
+ * response lists without `required: true`. A `$ref` header counts as required, as the generated
+ * type has it; a component header (`components/headers/<name>`) is a member of its own.
+ */
+export function isOptionalHeader(pointer: RefPointer, index: number, headers: unknown): boolean {
+  const isComponentHeader = pointer.rootSegment === "components" && index === 1;
+  if (pointer.segments[index - 1] !== "headers" || isComponentHeader || !isJsonObject(headers)) {
+    return false;
+  }
+  const header = headers[pointer.segments[index] as string];
+  return isJsonObject(header) && header.$ref === undefined && header.required !== true;
+}
+
+/** A `requestBody` the operation does not mark `required` is an optional member. */
+export function isOptionalRequestBody(container: unknown, refs: RefResolver): boolean {
+  if (!isJsonObject(container) || container.requestBody === undefined) {
+    return false;
+  }
+  const body = followRefs(container.requestBody, refs);
+  return !(isJsonObject(body) && body.required === true);
+}