openapi-typesafe 0.0.0 → 1.0.0-rc.1

package/src/application/transform/document/path-template-replace.ts

@@ -0,0 +1,90 @@
+import type { PathKeyPart, PathPlaceholder } from "./path-key-overlaps.js";
+
+/**
+ * The `--path-params-as-types` key as the original builds it: each `{name}` match, in URL order,
+ * replaces the first occurrence of its text in the key so far. A parameter named `number`,
+ * `string` or `boolean` can so hit the `${number}` an earlier parameter got: of
+ * `/a/{id}/b/{number}` the original makes `/a/$${number}/b/{number}`. That output compiles, so it
+ * stays the default (ADR-021); the `path-param-type-names` fix gives every match its own
+ * placeholder.
+ */
+
+/** One `{name}` of the URL and the placeholder of its parameter's type. */
+export interface PathParameterMatch {
+  readonly match: string;
+  readonly type: PathPlaceholder;
+}
+
+/**
+ * One UTF-16 code unit of the key so far (`indexOf` counts those): URL text, or a unit of the
+ * placeholder that the match at `owner` inserted.
+ */
+interface KeyUnit {
+  readonly unit: string;
+  readonly owner: number | null;
+}
+
+const URL_TEXT = null;
+
+/** `${type}`: the text of a template literal type placeholder. */
+export function placeholderText(type: PathPlaceholder): string {
+  return `\${${type}}`;
+}
+
+/** The key's units after each match replaced the first occurrence of its text. */
+function replacedUnits(url: string, matches: readonly PathParameterMatch[]): readonly KeyUnit[] {
+  const units: KeyUnit[] = url.split("").map((unit) => ({ unit, owner: URL_TEXT }));
+  matches.forEach(({ match, type }, owner) => {
+    const at = units
+      .map(({ unit }) => unit)
+      .join("")
+      .indexOf(match);
+    if (at >= 0) {
+      const inserted = placeholderText(type)
+        .split("")
+        .map((unit) => ({ unit, owner }));
+      units.splice(at, match.length, ...inserted);
+    }
+  });
+  return units;
+}
+
+/** The placeholders, by match, that no later match cut into. */
+function intactPlaceholders(
+  units: readonly KeyUnit[],
+  matches: readonly PathParameterMatch[],
+): ReadonlyMap<number, PathPlaceholder> {
+  const intact = new Map<number, PathPlaceholder>();
+  matches.forEach(({ type }, owner) => {
+    const left = units.filter((unit) => unit.owner === owner).length;
+    if (left === placeholderText(type).length) {
+      intact.set(owner, type);
+    }
+  });
+  return intact;
+}
+
+/**
+ * The key as parts. What is left of a placeholder that a later match cut into (the `$` of
+ * `$${number}`) is text, as TypeScript reads it.
+ */
+export function replacedTemplateParts(
+  url: string,
+  matches: readonly PathParameterMatch[],
+): PathKeyPart[] {
+  const units = replacedUnits(url, matches);
+  const intact = intactPlaceholders(units, matches);
+  const parts: PathKeyPart[] = [];
+  let text = "";
+  units.forEach(({ unit, owner }, index) => {
+    const type = owner === URL_TEXT ? undefined : intact.get(owner);
+    if (type === undefined) {
+      text += unit;
+    } else if (units[index - 1]?.owner !== owner) {
+      parts.push({ kind: "text", text }, { kind: "placeholder", type });
+      text = "";
+    }
+  });
+  parts.push({ kind: "text", text });
+  return parts;
+}

package/src/application/transform/document/paths-enum.ts

@@ -0,0 +1,127 @@
+import type { IrEnumDeclaration } from "../../../domain/ir/nodes.js";
+import type { OperationObject } from "../../../domain/openapi/operation-object.js";
+import {
+  ADDITIONAL_OPERATIONS_KEY,
+  HTTP_METHODS,
+  type PathItemMethod,
+  type PathsObject,
+  QUERY_METHOD,
+} from "../../../domain/openapi/path-item-object.js";
+import { EnumNaming, enumDeclaration } from "../footer/enum-naming.js";
+import { withNumberedRepeats } from "../numbered-names.js";
+import type { EnumMemberMetadata } from "../schema/schema-context.js";
+
+/** A path segment that is one parameter: `{user_id}` or `:user_id`. */
+const PARAMETER_SEGMENT_RE = /^(?:{(.+)}|:(.+))$/;
+/** Characters not allowed in an enum key, or a `{param}` / `:param` part (first match only). */
+const INVALID_KEY_PART_RE = /{.*}|:.*|[^a-zA-Z\d_]+/;
+const API_PATHS_NAME = "ApiPaths";
+const METHODS: ReadonlySet<string> = new Set<PathItemMethod>([...HTTP_METHODS, QUERY_METHOD]);
+
+/** The members of the `ApiPaths` enum (`--make-paths-enum`). */
+export interface ApiPathsEnum {
+  readonly values: readonly string[];
+  readonly metadata: readonly EnumMemberMetadata[];
+}
+
+/** `getUsersById` style key from the method and URL, when the operation has no ID. */
+function keyFromUrl(method: string, url: string): string {
+  return `${method}${url}`
+    .split("/")
+    .map((part) => {
+      const capitalized = part.charAt(0).toUpperCase() + part.slice(1);
+      return capitalized.replace(INVALID_KEY_PART_RE, "");
+    })
+    .join("");
+}
+
+/** `user_id` and `order-id` as `UserId` and `OrderId`. */
+function parameterWord(name: string): string {
+  return name
+    .split(/[^a-zA-Z\d]+/)
+    .map((word) => word.charAt(0).toUpperCase() + word.slice(1))
+    .join("");
+}
+
+/** The key with parameters named, `GetUserByUserId`, for keys that collide without them. */
+function keyWithParameters(method: string, url: string): string {
+  const parts = url.split("/").map((part) => {
+    const parameter = PARAMETER_SEGMENT_RE.exec(part);
+    const name = parameter?.[1] ?? parameter?.[2];
+    return name === undefined ? part : `By${parameterWord(name)}`;
+  });
+  return keyFromUrl(method, parts.join("/"));
+}
+
+interface PathOperation {
+  readonly url: string;
+  readonly method: string;
+  readonly operationId: string | undefined;
+}
+
+/**
+ * The operations of one path item in document order; `additionalOperations` (OpenAPI 3.2) adds
+ * its methods where the key stands.
+ */
+function pathItemEntries(pathItem: object): [string, unknown][] {
+  return Object.entries(pathItem).flatMap(([key, value]): [string, unknown][] => {
+    if (key === ADDITIONAL_OPERATIONS_KEY) {
+      return typeof value === "object" && value !== null ? Object.entries(value) : [];
+    }
+    return METHODS.has(key) ? [[key, value]] : [];
+  });
+}
+
+function pathOperations(paths: PathsObject): PathOperation[] {
+  return Object.entries(paths).flatMap(([url, pathItem]) =>
+    pathItemEntries(pathItem).map(([method, operation]) => {
+      const operationId = (operation as OperationObject).operationId || undefined;
+      return { url, method, operationId };
+    }),
+  );
+}
+
+function countOf(names: readonly string[]): Map<string, number> {
+  const counts = new Map<string, number>();
+  for (const name of names) {
+    counts.set(name, (counts.get(name) ?? 0) + 1);
+  }
+  return counts;
+}
+
+/**
+ * Names that are unique, so the enum compiles (upstream #2194). A URL key that collides names
+ * its parameters; a name that still collides gets 2, 3… after its first use.
+ */
+function uniqueNames(operations: readonly PathOperation[]): string[] {
+  const keys = operations.map((op) => op.operationId ?? keyFromUrl(op.method, op.url));
+  const counts = countOf(keys);
+  const named = operations.map((op, index) => {
+    const isCollidingUrlKey =
+      op.operationId === undefined && (counts.get(keys[index] as string) ?? 0) > 1;
+    return isCollidingUrlKey ? keyWithParameters(op.method, op.url) : (keys[index] as string);
+  });
+  return withNumberedRepeats(named, (name, count) => `${name}${count}`);
+}
+
+/**
+ * One enum member per operation: the URL as the value, the operation ID (or a key built from the
+ * method and URL) as the name. Paths are in document order; `--alphabetize` does not apply.
+ */
+export function apiPathsEnum(paths: PathsObject): ApiPathsEnum {
+  const operations = pathOperations(paths);
+  const names = uniqueNames(operations);
+  return {
+    values: operations.map((operation) => operation.url),
+    metadata: names.map((name) => ({ name, description: undefined })),
+  };
+}
+
+/**
+ * The `ApiPaths` enum declaration. Its own naming state is equivalent to the run's: the name is a
+ * valid identifier, and member names only reset the state, never read it.
+ */
+export function apiPathsEnumDeclaration(paths: PathsObject): IrEnumDeclaration {
+  const naming = new EnumNaming();
+  return enumDeclaration(naming.enumName(API_PATHS_NAME), apiPathsEnum(paths), naming);
+}

package/src/application/transform/document/paths.ts

@@ -0,0 +1,273 @@
+import { irIntersection, irObject, irProperty, irRaw } from "../../../domain/ir/constructors.js";
+import type { IrMember, IrType } from "../../../domain/ir/nodes.js";
+import { toPropertyName } from "../../../domain/ir/property-name.js";
+import { escapeTemplateText } from "../../../domain/ir/raw-text-escapes.js";
+import { createRef } from "../../../domain/openapi/json-pointer.js";
+import type { OperationObject } from "../../../domain/openapi/operation-object.js";
+import type {
+  ParameterObject,
+  ParameterOrReference,
+} from "../../../domain/openapi/parameter-object.js";
+import {
+  type PathItemObject,
+  type PathsObject,
+  pathItemOperations,
+} from "../../../domain/openapi/path-item-object.js";
+import type { ReferenceSchema, SchemaObject } from "../../../domain/openapi/schema-object.js";
+import { OutputFix } from "../../../domain/output-fixes.js";
+import { documentEntries } from "../document-entries.js";
+import { refType } from "../ref-type.js";
+import type { TransformContext } from "../transform-context.js";
+import { type DeclaredTypeLookup, NO_DECLARED_TYPES } from "./declared-types.js";
+import { documentMember } from "./document-member.js";
+import { pathItemType } from "./path-item.js";
+import {
+  type CoverRejection,
+  coveringTemplateKeys,
+  type PathKey,
+  type PathKeyPart,
+  type PathPlaceholder,
+} from "./path-key-overlaps.js";
+import {
+  type PathParameterMatch,
+  placeholderText,
+  replacedTemplateParts,
+} from "./path-template-replace.js";
+import { assignabilityProof } from "./type-assignability.js";
+
+const PATH_PARAMETER_RE = /\{[^}]+\}/g;
+
+/** Placeholders by parameter schema type; anything else is a string placeholder. */
+const PLACEHOLDERS: ReadonlyMap<unknown, PathPlaceholder> = new Map([
+  ["number", "number"],
+  ["integer", "number"],
+  ["boolean", "boolean"],
+]);
+const STRING_PLACEHOLDER: PathPlaceholder = "string";
+
+function resolvedParameter(
+  parameter: ParameterOrReference,
+  context: TransformContext,
+): ParameterObject | undefined {
+  return "$ref" in parameter && parameter.$ref
+    ? (context.refs.resolve(parameter.$ref) as ParameterObject | undefined)
+    : (parameter as ParameterObject);
+}
+
+function addPathParameters(
+  parameters: readonly ParameterOrReference[],
+  byName: Map<string, ParameterObject>,
+  context: TransformContext,
+): void {
+  for (const parameter of parameters) {
+    const resolved = resolvedParameter(parameter, context);
+    if (resolved && resolved.in === "path") {
+      byName.set(resolved.name, resolved);
+    }
+  }
+}
+
+/** Path parameters of the path item and of its operations; later definitions win. */
+function pathParameters(
+  pathItem: PathItemObject,
+  context: TransformContext,
+): Map<string, ParameterObject> {
+  const byName = new Map<string, ParameterObject>();
+  addPathParameters(pathItem.parameters ?? [], byName, context);
+  for (const { operation: entry } of pathItemOperations(pathItem)) {
+    const operation = (entry as ReferenceSchema).$ref
+      ? (context.refs.resolve((entry as ReferenceSchema).$ref) as OperationObject | undefined)
+      : (entry as OperationObject);
+    addPathParameters(operation?.parameters ?? [], byName, context);
+  }
+  return byName;
+}
+
+/** Each `{name}` of the URL and its own placeholder, from the URL split at the matches. */
+function splitTemplateParts(url: string, matches: readonly PathParameterMatch[]): PathKeyPart[] {
+  return url.split(PATH_PARAMETER_RE).flatMap((text, index): PathKeyPart[] => {
+    const type = matches[index]?.type;
+    const textPart: PathKeyPart = { kind: "text", text };
+    return type === undefined ? [textPart] : [textPart, { kind: "placeholder", type }];
+  });
+}
+
+/**
+ * `--path-params-as-types`: the URL as template parts, each `{name}` replaced by a placeholder for
+ * its parameter's type, the way the original replaces them unless the `path-param-type-names` fix
+ * is on (see `replacedTemplateParts`). Null when the URL has no complete `{…}` placeholder.
+ */
+function pathTemplateParts(
+  url: string,
+  pathItem: PathItemObject,
+  context: TransformContext,
+): PathKeyPart[] | null {
+  const found = url.match(PATH_PARAMETER_RE);
+  if (!found) {
+    return null;
+  }
+  const parameters = pathParameters(pathItem, context);
+  const matches = found.map((match): PathParameterMatch => {
+    const schema = parameters.get(match.slice(1, -1))?.schema as SchemaObject | undefined;
+    return { match, type: PLACEHOLDERS.get(schema?.type) ?? STRING_PLACEHOLDER };
+  });
+  return context.options.fixes.has(OutputFix.PATH_PARAM_TYPE_NAMES)
+    ? splitTemplateParts(url, matches)
+    : replacedTemplateParts(url, matches);
+}
+
+/**
+ * The template literal type of the parts. The original escaped only backticks: a backslash or
+ * `${` in the URL could end the literal or open a placeholder, and add code to the generated file
+ * (intentional fix). So the text parts are escaped.
+ */
+function templateText(parts: readonly PathKeyPart[]): string {
+  const text = parts
+    .map((part) =>
+      part.kind === "text" ? escapeTemplateText(part.text) : placeholderText(part.type),
+    )
+    .join("");
+  return `\`${text}\``;
+}
+
+/** A path's member, its key and its path item type for the overlap check. */
+export interface PathMember {
+  readonly url: string;
+  readonly member: IrMember;
+  readonly key: PathKey;
+  readonly type: IrType;
+}
+
+function pathItemMember(
+  url: string,
+  pathItem: PathItemObject,
+  context: TransformContext,
+): PathMember {
+  const isReadonly = context.options.immutable;
+  const type = pathItemType(pathItem, { path: createRef(["paths", url]) }, context);
+  const parts =
+    context.options.pathParamsAsTypes && url.includes("{")
+      ? pathTemplateParts(url, pathItem, context)
+      : null;
+  if (parts === null) {
+    const member = irProperty(toPropertyName(url), type, { isReadonly });
+    return { url, member, key: literalKey(url), type };
+  }
+  const member: IrMember = {
+    kind: "indexSignature",
+    parameterName: "path",
+    parameterType: irRaw(templateText(parts)),
+    type,
+    isReadonly,
+    comments: [],
+  };
+  return { url, member, key: { kind: "template", parts }, type };
+}
+
+function literalKey(url: string): PathKey {
+  return { kind: "literal", url };
+}
+
+const PATHS_TYPE_NAME = "paths";
+
+/** The URL of `paths["/apps/{id}"]`, or null for any other type. */
+function pathsIndexOf(type: IrType): string | null {
+  if (type.kind !== "indexedAccess" || type.index.kind !== "stringLiteral") {
+    return null;
+  }
+  const { object } = type;
+  const isPaths =
+    object.kind === "reference" &&
+    object.name === PATHS_TYPE_NAME &&
+    object.typeArguments.length === 0;
+  return isPaths ? type.index.value : null;
+}
+
+/**
+ * The lookup, and `paths["/apps/{id}"]` as that path's item. The declarations cannot read it: a
+ * templated path is no property of `paths`, and TypeScript finds it through the signature.
+ */
+function withPathItems(
+  paths: readonly PathMember[],
+  lookup: DeclaredTypeLookup,
+): DeclaredTypeLookup {
+  const byUrl = new Map(paths.map((path) => [path.url, path.type]));
+  return (type) => {
+    const url = pathsIndexOf(type);
+    return (url === null ? undefined : byUrl.get(url)) ?? lookup(type);
+  };
+}
+
+/**
+ * The rejection of a covered path item: only one proven not assignable to the signature's type
+ * counts (ADR-028). A pair the proof cannot decide keeps the original output, which may well
+ * compile (`Record<string, never>` fits `{ [key: string]: unknown }`).
+ */
+function rejectionOf(paths: readonly PathMember[], lookup: DeclaredTypeLookup): CoverRejection {
+  const relate = assignabilityProof(withPathItems(paths, lookup));
+  return (coveringIndex, coveredIndex) => {
+    const coveringPath = paths[coveringIndex];
+    const coveredPath = paths[coveredIndex];
+    return (
+      coveringPath !== undefined &&
+      coveredPath !== undefined &&
+      relate(coveredPath.type, coveringPath.type) === "rejected"
+    );
+  };
+}
+
+/**
+ * The members as one object type. When an index signature covers another key, TypeScript checks
+ * the covered key's type against it. Where that check surely fails (TS2411, TS2413), each such
+ * signature gets an object of its own in an intersection: an intersection does not check its parts
+ * against each other, and every key has the type it had in the one object. Output that compiles
+ * keeps the one object. The lookup reads the types that path items reference; without it, a
+ * reference decides nothing.
+ */
+export function pathsObjectType(
+  paths: readonly PathMember[],
+  lookup: DeclaredTypeLookup = NO_DECLARED_TYPES,
+): IrType {
+  const keys = paths.map(({ key }) => key);
+  const covering = coveringTemplateKeys(keys, rejectionOf(paths, lookup));
+  if (covering.size === 0) {
+    return irObject(paths.map(({ member }) => member));
+  }
+  const rest = paths.filter((_, index) => !covering.has(index)).map(({ member }) => member);
+  const own = paths
+    .filter((_, index) => covering.has(index))
+    .map(({ member }) => irObject([member]));
+  return irIntersection([irObject(rest), ...own]);
+}
+
+/** The members of the `paths` interface (OpenAPI 3.1 §4.8.8): one per path, by URL. */
+export function pathMembers(paths: PathsObject, context: TransformContext): PathMember[] {
+  const members: PathMember[] = [];
+  for (const [url, pathItem] of documentEntries(paths, context.options)) {
+    if (!pathItem || typeof pathItem !== "object") {
+      continue;
+    }
+    if ("$ref" in pathItem) {
+      const options = { isReadonly: context.options.immutable };
+      const member = documentMember(url, refType(pathItem.$ref), pathItem, options);
+      members.push({ url, member, key: literalKey(url), type: member.type });
+      continue;
+    }
+    const startedAt = context.diagnostics.now();
+    const path = pathItemMember(url, pathItem, context);
+    members.push(path);
+    // The original reports only paths written as properties.
+    if (path.member.kind === "property") {
+      context.diagnostics.debug(`Transformed path "${url}"`, context.diagnostics.now() - startedAt);
+    }
+  }
+  return members;
+}
+
+/**
+ * The `paths` interface body, with only the path items' own types for the overlap check. The
+ * document transform checks the overlaps again once the referenced types are declared.
+ */
+export function pathsType(paths: PathsObject, context: TransformContext): IrType {
+  return pathsObjectType(pathMembers(paths, context));
+}

package/src/application/transform/document/request-body.ts

@@ -0,0 +1,50 @@
+import { irKeyword, irObject, irProperty } from "../../../domain/ir/constructors.js";
+import type { IrMember, IrType } from "../../../domain/ir/nodes.js";
+import { toPropertyName } from "../../../domain/ir/property-name.js";
+import { createRef } from "../../../domain/openapi/json-pointer.js";
+import type { RequestBodyObject } from "../../../domain/openapi/request-body-object.js";
+import { documentEntries } from "../document-entries.js";
+import type { SchemaContext, SchemaLocation } from "../schema/schema-context.js";
+import { documentMember } from "./document-member.js";
+import { contentEntryType, itemContentMember } from "./media-type.js";
+
+/** Stands in for the media types of a body that defines none: `"*\/*"?: never`. */
+const ANY_MEDIA_TYPE = "*/*";
+
+function contentMembers(
+  requestBody: RequestBodyObject,
+  location: SchemaLocation,
+  context: SchemaContext,
+): IrMember[] {
+  const entries = documentEntries(requestBody.content ?? {}, context.options);
+  return entries.map(([contentType, entry]) => {
+    const path = createRef([location.path, "content", contentType]);
+    const type = contentEntryType(entry, { ...location, path }, context);
+    return documentMember(contentType, type, entry, { isReadonly: context.options.immutable });
+  });
+}
+
+/**
+ * A request body (OpenAPI 3.2 §4.8.13): `{ content: { [mediaType]: T } }`, and `itemContent` when a
+ * media type has an `itemSchema`.
+ */
+export function requestBodyType(
+  requestBody: RequestBodyObject,
+  location: SchemaLocation,
+  context: SchemaContext,
+): IrType {
+  const members = contentMembers(requestBody, location, context);
+  // The placeholder is never readonly, even with --immutable, as in the original.
+  const placeholder = irProperty(toPropertyName(ANY_MEDIA_TYPE), irKeyword("never"), {
+    isOptional: true,
+  });
+  const content = irObject(members.length > 0 ? members : [placeholder]);
+  const isReadonly = context.options.immutable;
+  const itemContent = itemContentMember(requestBody.content ?? {}, location, context, {
+    isReadonly,
+  });
+  return irObject([
+    irProperty(toPropertyName("content"), content, { isReadonly }),
+    ...(itemContent ? [itemContent] : []),
+  ]);
+}

package/src/application/transform/document/response.ts

@@ -0,0 +1,109 @@
+import {
+  irKeyword,
+  irObject,
+  irProperty,
+  irStringIndexSignature,
+} from "../../../domain/ir/constructors.js";
+import type { IrMember, IrPropertySignature, IrType } from "../../../domain/ir/nodes.js";
+import { toPropertyName } from "../../../domain/ir/property-name.js";
+import { createRef } from "../../../domain/openapi/json-pointer.js";
+import {
+  isMediaTypeComponentRef,
+  type MediaTypeObject,
+} from "../../../domain/openapi/media-type-object.js";
+import type { ResponseObject } from "../../../domain/openapi/response-object.js";
+import { documentEntries } from "../document-entries.js";
+import { refType } from "../ref-type.js";
+import type { SchemaContext, SchemaLocation } from "../schema/schema-context.js";
+import { UNKNOWN_TYPE } from "../shared-types.js";
+import { documentMember } from "./document-member.js";
+import { headerType } from "./header.js";
+import { contentEntryType, itemContentMember, mediaTypeType } from "./media-type.js";
+
+type HeaderEntry = NonNullable<ResponseObject["headers"]>[string];
+
+function headerMember(
+  name: string,
+  header: HeaderEntry,
+  location: SchemaLocation,
+  context: SchemaContext,
+): IrPropertySignature {
+  // A referenced header counts as required: the reference does not say otherwise.
+  const isReference = "$ref" in header;
+  const type = isReference
+    ? refType(header.$ref)
+    : headerType(
+        header,
+        { ...location, path: createRef([location.path, "headers", name]) },
+        context,
+      );
+  return documentMember(name, type, header, {
+    isReadonly: context.options.immutable,
+    isOptional: !isReference && !header.required,
+  });
+}
+
+/** The listed headers, then `[name: string]: unknown`, because servers may send others. */
+function headersMember(
+  response: ResponseObject,
+  location: SchemaLocation,
+  context: SchemaContext,
+): IrPropertySignature {
+  const entries = documentEntries(response.headers ?? {}, context.options);
+  const members: IrMember[] = entries.map(([name, header]) =>
+    headerMember(name, header, location, context),
+  );
+  members.push(irStringIndexSignature("name", UNKNOWN_TYPE, context.options.immutable));
+  return irProperty(toPropertyName("headers"), irObject(members));
+}
+
+/**
+ * One media type of a response. The original reads a `$ref` entry as a media type without a
+ * schema, so it is `unknown`; a `$ref` to an OpenAPI 3.2 media type component is typed as it.
+ */
+function mediaTypeEntryType(
+  entry: NonNullable<ResponseObject["content"]>[string],
+  location: SchemaLocation,
+  context: SchemaContext,
+): IrType {
+  return "$ref" in entry && isMediaTypeComponentRef(entry.$ref)
+    ? contentEntryType(entry, location, context)
+    : mediaTypeType(entry as MediaTypeObject, location, context);
+}
+
+/** `content` with one member per media type, or `content?: never` when there are none. */
+function contentMember(
+  response: ResponseObject,
+  location: SchemaLocation,
+  context: SchemaContext,
+): IrPropertySignature {
+  const entries = documentEntries(response.content ?? {}, context.options);
+  const members = entries.map(([contentType, entry]) => {
+    const path = createRef([location.path, "content", contentType]);
+    const type = mediaTypeEntryType(entry, { ...location, path }, context);
+    return documentMember(contentType, type, entry, { isReadonly: context.options.immutable });
+  });
+  const name = toPropertyName("content");
+  return members.length > 0
+    ? irProperty(name, irObject(members))
+    : irProperty(name, irKeyword("never"), { isOptional: true });
+}
+
+/**
+ * A response (OpenAPI 3.2 §4.8.17): `{ headers: {…}; content: {…} }`, and `itemContent` when a
+ * media type has an `itemSchema`. No member is readonly, even with --immutable, as in the original.
+ */
+export function responseType(
+  response: ResponseObject,
+  location: SchemaLocation,
+  context: SchemaContext,
+): IrType {
+  const itemContent = itemContentMember(response.content ?? {}, location, context, {
+    isReadonly: false,
+  });
+  return irObject([
+    headersMember(response, location, context),
+    contentMember(response, location, context),
+    ...(itemContent ? [itemContent] : []),
+  ]);
+}

package/src/application/transform/document/responses.ts

@@ -0,0 +1,29 @@
+import { irKeyword, irObject } from "../../../domain/ir/constructors.js";
+import type { IrType } from "../../../domain/ir/nodes.js";
+import { createRef } from "../../../domain/openapi/json-pointer.js";
+import type { ResponsesObject } from "../../../domain/openapi/response-object.js";
+import { documentEntries } from "../document-entries.js";
+import { refType } from "../ref-type.js";
+import type { SchemaContext, SchemaLocation } from "../schema/schema-context.js";
+import { documentMember } from "./document-member.js";
+import { responseType } from "./response.js";
+
+/** Responses by status code (OpenAPI 3.1 §4.8.16), or `never` when there are none. */
+export function responsesType(
+  responses: ResponsesObject,
+  location: SchemaLocation,
+  context: SchemaContext,
+): IrType {
+  const members = documentEntries(responses, context.options).map(([code, response]) => {
+    const type =
+      "$ref" in response
+        ? refType(response.$ref)
+        : responseType(
+            response,
+            { ...location, path: createRef([location.path, "responses", code]) },
+            context,
+          );
+    return documentMember(code, type, response, { isReadonly: context.options.immutable });
+  });
+  return members.length > 0 ? irObject(members) : irKeyword("never");
+}