openapi-typesafe 0.0.0 → 1.0.0-rc.0

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

@@ -0,0 +1,211 @@
+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 { documentEntries } from "../document-entries.js";
+import { refType } from "../ref-type.js";
+import type { TransformContext } from "../transform-context.js";
+import { documentMember } from "./document-member.js";
+import { pathItemType } from "./path-item.js";
+import { isCoveredPathItemRejected } from "./path-item-conflicts.js";
+import {
+  coveringTemplateKeys,
+  type PathKey,
+  type PathKeyPart,
+  type PathPlaceholder,
+} from "./path-key-overlaps.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";
+
+/** `${type}`: the text of a template literal type placeholder. */
+function placeholderText(type: PathPlaceholder): string {
+  return `\${${type}}`;
+}
+
+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;
+}
+
+/**
+ * `--path-params-as-types`: the URL as template parts, each `{name}` replaced by a placeholder for
+ * its parameter's type. Null when the URL has no complete `{…}` placeholder.
+ */
+function pathTemplateParts(
+  url: string,
+  pathItem: PathItemObject,
+  context: TransformContext,
+): PathKeyPart[] | null {
+  const matches = url.match(PATH_PARAMETER_RE);
+  if (!matches) {
+    return null;
+  }
+  const parameters = pathParameters(pathItem, context);
+  const placeholders = matches.map((match) => {
+    const schema = parameters.get(match.slice(1, -1))?.schema as SchemaObject | undefined;
+    return PLACEHOLDERS.get(schema?.type) ?? STRING_PLACEHOLDER;
+  });
+  return url.split(PATH_PARAMETER_RE).flatMap((text, index): PathKeyPart[] => {
+    const type = placeholders[index];
+    const textPart: PathKeyPart = { kind: "text", text };
+    return type === undefined ? [textPart] : [textPart, { kind: "placeholder", type }];
+  });
+}
+
+/**
+ * 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. */
+interface PathMember {
+  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 { member, key: literalKey(url), type };
+  }
+  const member: IrMember = {
+    kind: "indexSignature",
+    parameterName: "path",
+    parameterType: irRaw(templateText(parts)),
+    type,
+    isReadonly,
+    comments: [],
+  };
+  return { member, key: { kind: "template", parts }, type };
+}
+
+function literalKey(url: string): PathKey {
+  return { kind: "literal", url };
+}
+
+/**
+ * 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.
+ */
+function pathsObjectType(paths: readonly PathMember[]): IrType {
+  const covering = coveringTemplateKeys(
+    paths.map(({ key }) => key),
+    (coveringIndex, coveredIndex) => {
+      const coveringPath = paths[coveringIndex];
+      const coveredPath = paths[coveredIndex];
+      return (
+        coveringPath !== undefined &&
+        coveredPath !== undefined &&
+        isCoveredPathItemRejected(coveredPath.type, coveringPath.type)
+      );
+    },
+  );
+  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 `paths` interface body (OpenAPI 3.1 §4.8.8): one member per path, by URL. */
+export function pathsType(paths: PathsObject, context: TransformContext): IrType {
+  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({ 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 pathsObjectType(members);
+}

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");
+}

package/src/application/transform/document/root-type-aliases.ts

@@ -0,0 +1,106 @@
+import { irRaw } from "../../../domain/ir/constructors.js";
+import type { IrDeclaration, IrTypeAliasDeclaration } from "../../../domain/ir/nodes.js";
+import { escapeSingleQuotedText } from "../../../domain/ir/raw-text-escapes.js";
+import type { ComponentKind } from "../../../domain/openapi/components-object.js";
+
+/** The `--root-types` aliases: `export type Pet = components['schemas']['Pet'];`. */
+
+const REFERENCE_PREFIX = "components['";
+
+/** The alias of one component. */
+export function rootTypeAlias(
+  name: string,
+  kind: ComponentKind,
+  item: string,
+): IrTypeAliasDeclaration {
+  return {
+    kind: "typeAlias",
+    name,
+    isExported: true,
+    // The original writes the reference as text, with single quotes, and did not escape the
+    // name: a quote in it could add code to the generated file (intentional fix).
+    type: irRaw(`${REFERENCE_PREFIX}${kind}']['${escapeSingleQuotedText(item)}']`),
+    comments: [],
+  };
+}
+
+function isRootTypeAlias(declaration: IrDeclaration): declaration is IrTypeAliasDeclaration {
+  return (
+    declaration.kind === "typeAlias" &&
+    declaration.type.kind === "raw" &&
+    declaration.type.text.startsWith(REFERENCE_PREFIX)
+  );
+}
+
+/**
+ * The type names the footer declares that an alias must not take: enums, and helper types such as
+ * `WithRequired`. Value declarations (`--enum-values` arrays) live in another namespace.
+ */
+function footerTypeNames(declarations: readonly IrDeclaration[]): Set<string> {
+  return new Set(
+    declarations.flatMap((declaration) => {
+      if (declaration.kind === "enum") {
+        return [declaration.name];
+      }
+      return declaration.kind === "rawDeclaration" && declaration.name !== undefined
+        ? [declaration.name]
+        : [];
+    }),
+  );
+}
+
+function declaredNames(declarations: readonly IrDeclaration[]): Set<string> {
+  return new Set(
+    declarations.flatMap((declaration) =>
+      "name" in declaration && declaration.name !== undefined ? [declaration.name] : [],
+    ),
+  );
+}
+
+function freeName(name: string, taken: ReadonlySet<string>): string {
+  let candidate = `${name}_2`;
+  for (let counter = 3; taken.has(candidate); counter++) {
+    candidate = `${name}_${counter}`;
+  }
+  return candidate;
+}
+
+/**
+ * With the `root-type-numbering` fix (ADR-021, roadmap R13, backlog 30): the aliases that a later
+ * schema of one exported name took the name from, numbered `Name_2`, `Name_3`, … in document order
+ * with the next free number. The later schema keeps the name, so the fix only adds exports.
+ */
+export function numberDisplacedAliases(
+  displaced: readonly IrTypeAliasDeclaration[],
+  kept: readonly IrTypeAliasDeclaration[],
+): IrTypeAliasDeclaration[] {
+  const taken = new Set(kept.map((alias) => alias.name));
+  return displaced.map((alias) => {
+    const name = freeName(alias.name, taken);
+    taken.add(name);
+    return { ...alias, name };
+  });
+}
+
+/**
+ * Rename each root alias whose name an enum or a helper type of the footer also declares, to the
+ * next free `Name_2`, `Name_3`, … (the suffix `--root-types` uses for its own conflicts). The
+ * footer keeps its names, because the generated types refer to them. Before, both were declared
+ * under one name, which does not compile (enums: upstream #2099, #2341, #2206; helpers: a schema
+ * named `WithRequired`, roadmap R11). Other declarations are returned unchanged.
+ */
+export function renameAliasesTakenByFooter(
+  body: readonly IrDeclaration[],
+  footer: readonly IrDeclaration[],
+): IrDeclaration[] {
+  const footerNames = footerTypeNames(footer);
+  const taken = declaredNames([...body, ...footer]);
+  return body.map((declaration) => {
+    if (!isRootTypeAlias(declaration) || !footerNames.has(declaration.name)) {
+      return declaration;
+    }
+    const name = freeName(declaration.name, taken);
+    taken.add(name);
+    return { ...declaration, name };
+  });
+}

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

@@ -0,0 +1,22 @@
+import { irObject, irProperty } from "../../../domain/ir/constructors.js";
+import type { IrType } from "../../../domain/ir/nodes.js";
+import { toPropertyName } from "../../../domain/ir/property-name.js";
+import { createRef } from "../../../domain/openapi/json-pointer.js";
+import type { PathItemObject, PathsObject } from "../../../domain/openapi/path-item-object.js";
+import { documentEntries } from "../document-entries.js";
+import type { TransformContext } from "../transform-context.js";
+import { pathItemType } from "./path-item.js";
+
+/**
+ * The `webhooks` interface body (OpenAPI 3.1 §4.8.1): one path item per webhook name. Unlike
+ * `paths`, a `$ref` entry is read as a path item (so every method is `never`), as in the original,
+ * and members carry no JSDoc.
+ */
+export function webhooksType(webhooks: PathsObject, context: TransformContext): IrType {
+  const members = documentEntries(webhooks, context.options).map(([name, pathItem]) => {
+    const location = { path: createRef(["webhooks", name]) };
+    const type = pathItemType(pathItem as PathItemObject, location, context);
+    return irProperty(toPropertyName(name), type, { isReadonly: context.options.immutable });
+  });
+  return irObject(members);
+}

package/src/application/transform/document-entries.ts

@@ -0,0 +1,28 @@
+import { sortEntriesByKey } from "../../domain/ir/normalize.js";
+import type { SchemaOptions } from "./schema/schema-context.js";
+
+/** Whether a document object has `deprecated: true` (`--exclude-deprecated` drops it). */
+export function isDeprecated(value: unknown): boolean {
+  return Boolean(value && typeof value === "object" && "deprecated" in value && value.deprecated);
+}
+
+/** Whether a deprecated entry is still needed, so `--exclude-deprecated` keeps it. */
+export type DeprecatedEntryFilter = (value: unknown) => boolean;
+
+const KEEPS_NONE: DeprecatedEntryFilter = () => false;
+
+/**
+ * `Object.entries` of a document map (the original `getEntries`): sorted for `--alphabetize`,
+ * without deprecated entries for `--exclude-deprecated`, except those `isKept` names.
+ */
+export function documentEntries<T>(
+  record: Readonly<Record<string, T>>,
+  options: Pick<SchemaOptions, "alphabetize" | "excludeDeprecated">,
+  isKept: DeprecatedEntryFilter = KEEPS_NONE,
+): [string, T][] {
+  const entries = Object.entries(record);
+  const sorted = options.alphabetize ? sortEntriesByKey(entries) : entries;
+  return options.excludeDeprecated
+    ? sorted.filter(([, value]) => !isDeprecated(value) || isKept(value))
+    : sorted;
+}

package/src/application/transform/footer/document-footer.ts

@@ -0,0 +1,127 @@
+import { irReference } from "../../../domain/ir/constructors.js";
+import type { IrDeclaration, IrPropertySignature, IrType } from "../../../domain/ir/nodes.js";
+import { HELPER_TYPES, type HelperType } from "../helper-types.js";
+import type {
+  EnumDeclarationRequest,
+  EnumMemberMetadata,
+  EnumValuesRequest,
+} from "../schema/schema-context.js";
+import type { DocumentFooter } from "../transform-context.js";
+import { EnumNaming, enumDeclaration } from "./enum-naming.js";
+
+/** Where footer declarations go, in order: the run's `ctx.injectFooter`, open to user code. */
+export interface FooterSink {
+  /** Whether a type alias with this name is declared already (by the generator or a user). */
+  hasTypeAlias(name: string): boolean;
+  add(declaration: IrDeclaration): void;
+  /** Add a member to the `operations` interface, declared first if needed; see `DocumentFooter`. */
+  addOperation(build: () => IrPropertySignature): void;
+}
+
+/**
+ * The `--dedupe-enums` key of the original: the values in default sort order, each paired with
+ * the metadata at its sorted position (not the value's own metadata), as the original does.
+ */
+function dedupeKey(request: EnumDeclarationRequest): string {
+  return [...request.values]
+    .sort(compareAsStrings)
+    .map((value, index) => metadataKey(String(value), request.metadata[index]))
+    .join(",");
+}
+
+/** `Array.prototype.sort` without a comparator: compares the values as strings. */
+function compareAsStrings(left: string | number, right: string | number): number {
+  const leftText = String(left);
+  const rightText = String(right);
+  if (leftText === rightText) {
+    return 0;
+  }
+  return leftText < rightText ? -1 : 1;
+}
+
+function metadataKey(value: string, metadata: EnumMemberMetadata | undefined): string {
+  return `${metadata?.name ?? value}:${metadata?.description || ""}`;
+}
+
+/** The whole declaration: an equal key means the same enum, member for member. */
+function declarationKey(name: string, request: EnumDeclarationRequest): string {
+  return JSON.stringify([name, request.values, request.metadata]);
+}
+
+/**
+ * The footer of one run: enums (deduplicated with `--dedupe-enums`), `--enum-values` arrays, the
+ * helper types they need, and the `operations` interface. Replaces the original's module-level
+ * `enumCache`, so runs no longer share enums (research/legacy-bugs.md, item 3).
+ */
+export class RunFooter implements DocumentFooter {
+  private readonly naming = new EnumNaming();
+  private readonly enumNamesByKey = new Map<string, string>();
+  /** Declarations added already: the same one twice fails with "Duplicate identifier". */
+  private readonly declaredEnums = new Set<string>();
+  private readonly sink: FooterSink;
+  private readonly isDedupingEnums: boolean;
+
+  constructor(sink: FooterSink, isDedupingEnums: boolean) {
+    this.sink = sink;
+    this.isDedupingEnums = isDedupingEnums;
+  }
+
+  addEnum(request: EnumDeclarationRequest): string {
+    // The name is built before the cache lookup: it advances the naming state either way.
+    const name = this.naming.enumName(request.name);
+    const key = this.isDedupingEnums ? dedupeKey(request) : null;
+    const known = key === null ? undefined : this.enumNamesByKey.get(key);
+    if (known !== undefined) {
+      return known;
+    }
+    // Only a repeated member fails to compile; two empty declarations merge, so they stay.
+    const declared = request.values.length > 0 ? declarationKey(name, request) : null;
+    if (declared !== null && this.declaredEnums.has(declared)) {
+      return name;
+    }
+    if (declared !== null) {
+      this.declaredEnums.add(declared);
+    }
+    this.sink.add(enumDeclaration(name, request, this.naming));
+    if (key !== null) {
+      this.enumNamesByKey.set(key, name);
+    }
+    return name;
+  }
+
+  addEnumValues(request: EnumValuesRequest): void {
+    const name = this.naming.arrayName(request.name);
+    this.require(HELPER_TYPES.flattenedDeepRequired);
+    this.require(HELPER_TYPES.readonlyArray);
+    this.sink.add({
+      kind: "constArray",
+      name,
+      isExported: true,
+      type: readonlyArrayOf(request.type),
+      values: request.values,
+      comments: [],
+    });
+  }
+
+  requireWithRequired(): void {
+    this.require(HELPER_TYPES.withRequired);
+  }
+
+  requirePropertyValues(): void {
+    this.require(HELPER_TYPES.propertyValues);
+  }
+
+  addOperation(build: () => IrPropertySignature): void {
+    this.sink.addOperation(build);
+  }
+
+  private require(helper: HelperType): void {
+    if (!this.sink.hasTypeAlias(helper.name)) {
+      this.sink.add({ kind: "rawDeclaration", name: helper.name, text: helper.text });
+    }
+  }
+}
+
+function readonlyArrayOf(type: IrType): IrType {
+  return irReference(HELPER_TYPES.readonlyArray.name, [type]);
+}