openapi-typesafe 0.0.0 → 1.0.0-rc.0

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

@@ -0,0 +1,200 @@
+import { irKeyword, irObject, irProperty } from "../../../domain/ir/constructors.js";
+import type { IrPropertyName, IrPropertySignature, IrType } from "../../../domain/ir/nodes.js";
+import { toPropertyName } from "../../../domain/ir/property-name.js";
+import { createRef } from "../../../domain/openapi/json-pointer.js";
+import {
+  PARAMETER_LOCATIONS,
+  type ParameterLocation,
+  type ParameterObject,
+  type ParameterOrReference,
+  QUERYSTRING_LOCATION,
+} from "../../../domain/openapi/parameter-object.js";
+import type { SchemaObject } from "../../../domain/openapi/schema-object.js";
+import { refType } from "../ref-type.js";
+import type { SchemaLocation } from "../schema/schema-context.js";
+import { withSchemaComment } from "../schema-comment.js";
+import type { TransformContext } from "../transform-context.js";
+import { parameterType } from "./parameter.js";
+
+const PATH_TEMPLATE_RE = /\{([^}]+)\}/g;
+
+/** A parameter as written in the document, and the object its `$ref` points to. */
+interface ParameterEntry {
+  readonly original: ParameterOrReference;
+  readonly resolved: ParameterObject | undefined;
+}
+
+/** An entry whose `$ref` resolved, so its location and name are known. */
+type ResolvedEntry = ParameterEntry & { readonly resolved: ParameterObject };
+
+function resolveParameter(
+  parameter: ParameterOrReference,
+  context: TransformContext,
+): ParameterObject | undefined {
+  return "$ref" in parameter
+    ? (context.refs.resolve(parameter.$ref) as ParameterObject | undefined)
+    : parameter;
+}
+
+/** Required string parameters for every `{name}` in a path template. */
+function pathTemplateParameters(path: string): ParameterObject[] {
+  return (path.match(PATH_TEMPLATE_RE) ?? []).map((match) => ({
+    name: match.slice(1, -1),
+    in: "path",
+    required: true,
+    schema: { type: "string" },
+  }));
+}
+
+/** `--generate-path-params`: add the path template parameters the list does not define. */
+function withPathTemplateParameters(
+  parameters: readonly ParameterOrReference[],
+  location: SchemaLocation,
+  context: TransformContext,
+): ParameterOrReference[] {
+  const result = [...parameters];
+  if (!context.options.generatePathParams || !location.path) {
+    return result;
+  }
+  for (const parameter of pathTemplateParameters(location.path)) {
+    const isDefined = result.some((candidate) => {
+      const resolved = resolveParameter(candidate, context);
+      return resolved?.in === "path" && resolved.name === parameter.name;
+    });
+    if (!isDefined) {
+      result.push(parameter);
+    }
+  }
+  return result;
+}
+
+function isDeprecatedParameter(parameter: ParameterObject | undefined): boolean {
+  const schema = parameter?.schema as SchemaObject | undefined;
+  return Boolean(parameter?.deprecated || schema?.deprecated);
+}
+
+/** Resolved parameters, sorted for `--alphabetize`, without deprecated ones if excluded. */
+function parameterEntries(
+  parameters: readonly ParameterOrReference[],
+  context: TransformContext,
+): ParameterEntry[] {
+  const entries = parameters.map((original) => ({
+    original,
+    resolved: resolveParameter(original, context),
+  }));
+  if (context.options.alphabetize) {
+    // Unlike map keys, the original sorts parameters with the default locale's `localeCompare`.
+    entries.sort((left, right) =>
+      (left.resolved?.name ?? "").localeCompare(right.resolved?.name ?? ""),
+    );
+  }
+  return context.options.excludeDeprecated
+    ? entries.filter(({ resolved }) => !isDeprecatedParameter(resolved))
+    : entries;
+}
+
+/** The original quotes a name that is not text (a missing name prints as `"undefined"`). */
+function parameterName(name: unknown): IrPropertyName {
+  return typeof name === "string" || typeof name === "number"
+    ? toPropertyName(name)
+    : { kind: "string", value: String(name) };
+}
+
+function referencedParameterType(ref: string, resolved: ParameterObject): IrType {
+  // A `$ref` that resolves to another `$ref` is not a parameter object yet: index it as a path.
+  const isParameter = !(resolved as { $ref?: unknown }).$ref;
+  const parameter = isParameter ? { in: resolved.in, name: resolved.name } : null;
+  return refType(ref, { parameter });
+}
+
+function entryType(
+  { original, resolved }: ResolvedEntry,
+  location: SchemaLocation,
+  context: TransformContext,
+): IrType {
+  const path = createRef([location.path, "parameters", resolved.in, resolved.name]);
+  return "$ref" in original
+    ? referencedParameterType(original.$ref, resolved)
+    : parameterType(resolved, { ...location, path }, context);
+}
+
+function parameterMember(
+  entry: ResolvedEntry,
+  location: SchemaLocation,
+  context: TransformContext,
+): IrPropertySignature {
+  const { resolved } = entry;
+  const property = irProperty(parameterName(resolved.name), entryType(entry, location, context), {
+    isOptional: resolved.in !== "path" && !resolved.required,
+    isReadonly: context.options.immutable,
+  });
+  return withSchemaComment(property, resolved);
+}
+
+/**
+ * The `query` member typed by an `in: querystring` parameter (OpenAPI 3.2, ADR-020): the parameter
+ * is the whole query string. Null when there is none, or when `in: query` parameters sit next to
+ * it, which 3.2 does not allow; those keep their types, and a warning names the parameter.
+ */
+function querystringMember(
+  entries: readonly ParameterEntry[],
+  location: SchemaLocation,
+  context: TransformContext,
+): IrPropertySignature | null {
+  const querystring = entries.find(
+    (entry): entry is ResolvedEntry => entry.resolved?.in === QUERYSTRING_LOCATION,
+  );
+  if (!querystring || entries.some((entry) => entry.resolved?.in === "query")) {
+    return null;
+  }
+  const property = irProperty(toPropertyName("query"), entryType(querystring, location, context), {
+    isOptional: !querystring.resolved.required,
+    isReadonly: context.options.immutable,
+  });
+  return withSchemaComment(property, querystring.resolved);
+}
+
+/** One location's parameters; optional when all of them are, and `never` when there are none. */
+function locationMember(
+  parameterIn: ParameterLocation,
+  entries: readonly ParameterEntry[],
+  location: SchemaLocation,
+  context: TransformContext,
+): IrPropertySignature {
+  const members = entries
+    .filter((entry): entry is ResolvedEntry => entry.resolved?.in === parameterIn)
+    .map((entry) => parameterMember(entry, location, context));
+  return irProperty(
+    toPropertyName(parameterIn),
+    members.length > 0 ? irObject(members) : irKeyword("never"),
+    {
+      isOptional: members.every((member) => member.isOptional),
+      isReadonly: context.options.immutable,
+    },
+  );
+}
+
+/**
+ * The `parameters` property of an operation or path item: one member per location, each an object
+ * of that location's parameters. `location.path` is the path template for
+ * `--generate-path-params`.
+ */
+export function parametersMember(
+  parameters: readonly ParameterOrReference[],
+  location: SchemaLocation,
+  context: TransformContext,
+): IrPropertySignature {
+  const entries = parameterEntries(
+    withPathTemplateParameters(parameters, location, context),
+    context,
+  );
+  const querystring = querystringMember(entries, location, context);
+  const members = PARAMETER_LOCATIONS.map((parameterIn) =>
+    parameterIn === "query" && querystring
+      ? querystring
+      : locationMember(parameterIn, entries, location, context),
+  );
+  return irProperty(toPropertyName("parameters"), irObject(members), {
+    isReadonly: context.options.immutable,
+  });
+}

package/src/application/transform/document/path-item-conflicts.ts

@@ -0,0 +1,79 @@
+import type { IrMember, IrPropertySignature, IrType } from "../../../domain/ir/nodes.js";
+
+/**
+ * Whether TypeScript surely rejects a covered path item for the index signature that covers it
+ * (roadmap R10.2). The original output compiles when every covered type is assignable to the
+ * signature's type, and that output must stay the same, so a signature is only moved when this
+ * check proves the error. It compares object types property by property, as the checker does: a
+ * property the signature needs and the covered type may lack, or a value where the signature has
+ * the `?: never` of an empty slot (a missing method, an empty parameter location), proves it. Two
+ * object properties are compared the same way, inside. Any other pair of types (references,
+ * unions, keywords) decides nothing, and that output is left as it was.
+ */
+
+/**
+ * How a property is written. `never` is the `?: never` of an empty slot; a required `never`
+ * (assignable to every type) is `unknown` and decides nothing.
+ */
+type Presence = "absent" | "never" | "optional" | "required" | "unknown";
+
+function nameOf(member: IrPropertySignature): string {
+  return member.name.kind === "string" ? member.name.value : member.name.text;
+}
+
+function presenceOf(member: IrPropertySignature | undefined): Presence {
+  if (member === undefined) {
+    return "absent";
+  }
+  if (member.type.kind === "keyword" && member.type.keyword === "never") {
+    return member.isOptional ? "never" : "unknown";
+  }
+  return member.isOptional ? "optional" : "required";
+}
+
+function propertiesOf(type: IrType): ReadonlyMap<string, IrPropertySignature> | null {
+  if (type.kind !== "object") {
+    return null;
+  }
+  const properties = type.members.filter((member: IrMember): member is IrPropertySignature => {
+    return member.kind === "property";
+  });
+  return new Map(properties.map((property) => [nameOf(property), property]));
+}
+
+/**
+ * Whether the covered property's presence fails the signature's: a required value it may lack, or
+ * a value where the signature has `never` (an object is not `undefined`).
+ */
+function isPresenceRejected(covering: Presence, covered: Presence): boolean {
+  if (covered === "unknown") {
+    return false;
+  }
+  if (covering === "required") {
+    return covered !== "required";
+  }
+  return covering === "never" && (covered === "optional" || covered === "required");
+}
+
+function isPropertyRejected(
+  covering: IrPropertySignature,
+  covered: IrPropertySignature | undefined,
+): boolean {
+  if (isPresenceRejected(presenceOf(covering), presenceOf(covered))) {
+    return true;
+  }
+  // A `never` is not an object type, so a slot that is empty on either side decides nothing here.
+  return covered !== undefined && isCoveredPathItemRejected(covered.type, covering.type);
+}
+
+/** Whether the covered type is surely not assignable to the covering signature's type. */
+export function isCoveredPathItemRejected(covered: IrType, covering: IrType): boolean {
+  const coveredProperties = propertiesOf(covered);
+  const coveringProperties = propertiesOf(covering);
+  if (coveredProperties === null || coveringProperties === null) {
+    return false;
+  }
+  return [...coveringProperties].some(([name, property]) =>
+    isPropertyRejected(property, coveredProperties.get(name)),
+  );
+}

package/src/application/transform/document/path-item.ts

@@ -0,0 +1,168 @@
+import { irKeyword, irObject, irProperty } 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 type { OperationObject } from "../../../domain/openapi/operation-object.js";
+import type {
+  ParameterObject,
+  ParameterOrReference,
+} from "../../../domain/openapi/parameter-object.js";
+import {
+  ADDITIONAL_OPERATIONS_KEY,
+  HTTP_METHODS,
+  type OperationEntry,
+  type PathItemMethod,
+  type PathItemObject,
+  QUERY_METHOD,
+} from "../../../domain/openapi/path-item-object.js";
+import { documentEntries } from "../document-entries.js";
+import { refType } from "../ref-type.js";
+import type { SchemaLocation } from "../schema/schema-context.js";
+import type { TransformContext } from "../transform-context.js";
+import { documentMember } from "./document-member.js";
+import { operationMembers } from "./operation.js";
+import { parametersMember } from "./parameters.js";
+
+/** Redocly reads `#` in an operation ID as a pointer, so it is replaced (upstream issue #1542). */
+const HASH_RE = /#/g;
+
+/** Whether the method has an operation, not removed by `--exclude-deprecated`. */
+function isIncluded(
+  operation: OperationEntry | undefined,
+  context: TransformContext,
+): operation is OperationEntry {
+  if (!operation) {
+    return false;
+  }
+  const resolved =
+    "$ref" in operation
+      ? (context.refs.resolve(operation.$ref) as OperationObject | undefined)
+      : operation;
+  return !(context.options.excludeDeprecated && resolved?.deprecated);
+}
+
+/**
+ * Path item parameters followed by the operation's, keyed by location and name, so an operation
+ * parameter replaces the path item parameter it redefines (upstream issue #1798).
+ */
+function mergedParameters(
+  pathItem: PathItemObject,
+  operation: OperationObject,
+  context: TransformContext,
+): ParameterOrReference[] {
+  const byKey = new Map<string, ParameterOrReference>();
+  for (const parameter of [...(pathItem.parameters ?? []), ...(operation.parameters ?? [])]) {
+    const resolved =
+      "$ref" in parameter
+        ? (context.refs.resolve(parameter.$ref) as ParameterObject | undefined)
+        : parameter;
+    byKey.set(`${resolved?.in}-${resolved?.name}`, parameter);
+  }
+  return [...byKey.values()];
+}
+
+/**
+ * An operation with an `operationId` goes into the `operations` interface and is referenced from
+ * the path item; others are written inline.
+ */
+function operationType(
+  pathItem: PathItemObject,
+  operation: OperationObject,
+  location: SchemaLocation,
+  context: TransformContext,
+): IrType {
+  const merged = { ...operation, parameters: mergedParameters(pathItem, operation, context) };
+  if (!operation.operationId) {
+    return irObject(operationMembers(merged, location, context));
+  }
+  const operationId = operation.operationId.replace(HASH_RE, "/");
+  context.footer.addOperation(() =>
+    irProperty(toPropertyName(operationId), irObject(operationMembers(merged, location, context)), {
+      isReadonly: context.options.immutable,
+    }),
+  );
+  return refType(createRef(["operations", operationId]));
+}
+
+/** An included operation, the member name it gets and its location below the path item. */
+interface DeclaredOperation {
+  readonly name: string;
+  readonly operation: OperationEntry;
+  readonly path: string;
+}
+
+function operationMember(
+  { name, operation, path }: DeclaredOperation,
+  pathItem: PathItemObject,
+  location: SchemaLocation,
+  context: TransformContext,
+): IrPropertySignature {
+  const type =
+    "$ref" in operation
+      ? refType(operation.$ref)
+      : operationType(pathItem, operation, { ...location, path }, context);
+  return documentMember(name, type, operation, { isReadonly: context.options.immutable });
+}
+
+/** A method member: the operation, or `?: never` when there is none or it is excluded. */
+function methodMember(
+  method: PathItemMethod,
+  pathItem: PathItemObject,
+  location: SchemaLocation,
+  context: TransformContext,
+): IrPropertySignature {
+  const operation = pathItem[method];
+  if (!isIncluded(operation, context)) {
+    const isReadonly = context.options.immutable;
+    return irProperty(toPropertyName(method), irKeyword("never"), { isOptional: true, isReadonly });
+  }
+  const path = createRef([location.path, method]);
+  return operationMember({ name: method, operation, path }, pathItem, location, context);
+}
+
+/**
+ * `additionalOperations` (OpenAPI 3.2): the included operations keyed by their exact method name,
+ * or null when the path item has none left.
+ */
+function additionalOperationsMember(
+  pathItem: PathItemObject,
+  location: SchemaLocation,
+  context: TransformContext,
+): IrPropertySignature | null {
+  const entries = documentEntries(pathItem.additionalOperations ?? {}, context.options);
+  const members = entries
+    .filter(([, operation]) => isIncluded(operation, context))
+    .map(([method, operation]) => {
+      const path = createRef([location.path, ADDITIONAL_OPERATIONS_KEY, method]);
+      return operationMember({ name: method, operation, path }, pathItem, location, context);
+    });
+  return members.length > 0
+    ? irProperty(toPropertyName(ADDITIONAL_OPERATIONS_KEY), irObject(members), {
+        isReadonly: context.options.immutable,
+      })
+    : null;
+}
+
+/**
+ * A path item (OpenAPI 3.2 §4.8.9): its `parameters`, one member per HTTP method, then `query` and
+ * `additionalOperations` when the path item declares them (ADR-020).
+ */
+export function pathItemType(
+  pathItem: PathItemObject,
+  location: SchemaLocation,
+  context: TransformContext,
+): IrType {
+  const parametersLocation = { ...location, path: createRef([location.path, "parameters"]) };
+  const members: IrMember[] = [
+    parametersMember(pathItem.parameters ?? [], parametersLocation, context),
+    ...HTTP_METHODS.map((method) => methodMember(method, pathItem, location, context)),
+  ];
+  if (pathItem[QUERY_METHOD] !== undefined) {
+    members.push(methodMember(QUERY_METHOD, pathItem, location, context));
+  }
+  const additionalOperations = additionalOperationsMember(pathItem, location, context);
+  if (additionalOperations) {
+    members.push(additionalOperations);
+  }
+  return irObject(members);
+}

package/src/application/transform/document/path-key-overlaps.ts

@@ -0,0 +1,112 @@
+/**
+ * `--path-params-as-types` overlaps (roadmap R10.2, backlog 28). A path key with parameters is an
+ * index signature over a template literal type, such as `` `/apps/${string}` ``. `${string}` also
+ * matches `/`, so that signature covers `/apps/regions` and `` `/apps/${string}/restart` `` as
+ * well, and TypeScript requires the covered keys' types to be assignable to its type (TS2411,
+ * TS2413). These functions find the signatures that cover another key the checker rejects.
+ */
+
+/** A placeholder of a template literal type, by the type it stands for. */
+export type PathPlaceholder = "string" | "number" | "boolean";
+
+/** One part of a path key: text, or a placeholder. */
+export type PathKeyPart =
+  | { readonly kind: "text"; readonly text: string }
+  | { readonly kind: "placeholder"; readonly type: PathPlaceholder };
+
+/** A path key: a URL written as a property, or a template literal type of an index signature. */
+export type PathKey =
+  | { readonly kind: "literal"; readonly url: string }
+  | { readonly kind: "template"; readonly parts: readonly PathKeyPart[] };
+
+const BOOLEAN_TEXTS: readonly string[] = ["true", "false"];
+
+/** The text one placeholder stands for in a sample of a template key. */
+const SAMPLE_TEXTS: Readonly<Record<PathPlaceholder, string>> = {
+  string: "",
+  number: "0",
+  boolean: "true",
+};
+
+/** TypeScript's rule for `${number}`: a text that converts to a finite number. */
+function isNumberText(text: string): boolean {
+  return text !== "" && Number.isFinite(Number(text));
+}
+
+function isPlaceholderText(type: PathPlaceholder, text: string): boolean {
+  if (type === "number") {
+    return isNumberText(text);
+  }
+  return type === "boolean" ? BOOLEAN_TEXTS.includes(text) : true;
+}
+
+/** Whether `text` from `start` on is one of the strings the parts from `index` on describe. */
+function matchesFrom(
+  text: string,
+  start: number,
+  parts: readonly PathKeyPart[],
+  index: number,
+): boolean {
+  const part = parts[index];
+  if (part === undefined) {
+    return start === text.length;
+  }
+  if (part.kind === "text") {
+    return (
+      text.startsWith(part.text, start) &&
+      matchesFrom(text, start + part.text.length, parts, index + 1)
+    );
+  }
+  for (let end = start; end <= text.length; end += 1) {
+    if (
+      isPlaceholderText(part.type, text.slice(start, end)) &&
+      matchesFrom(text, end, parts, index + 1)
+    ) {
+      return true;
+    }
+  }
+  return false;
+}
+
+/**
+ * One string of the key. If a template key is covered, every string of it is, so a sample that is
+ * not covered proves the key is not; a sample that is covered may over-report, which only moves a
+ * signature that did not need it (the types stay the same, see `pathsObjectType`).
+ */
+function sampleOf(key: PathKey): string {
+  if (key.kind === "literal") {
+    return key.url;
+  }
+  return key.parts
+    .map((part) => (part.kind === "text" ? part.text : SAMPLE_TEXTS[part.type]))
+    .join("");
+}
+
+/** Whether TypeScript rejects the key at `covered` for the signature at `covering`. */
+export type CoverRejection = (covering: number, covered: number) => boolean;
+
+/** Without type information every covered key counts. */
+const EVERY_COVER_REJECTED: CoverRejection = () => true;
+
+/** The indexes of the template keys that cover another key of the list, where it is rejected. */
+export function coveringTemplateKeys(
+  keys: readonly PathKey[],
+  isRejected: CoverRejection = EVERY_COVER_REJECTED,
+): ReadonlySet<number> {
+  const covering = new Set<number>();
+  keys.forEach((key, index) => {
+    if (key.kind !== "template") {
+      return;
+    }
+    const isCovering = keys.some(
+      (other, otherIndex) =>
+        otherIndex !== index &&
+        matchesFrom(sampleOf(other), 0, key.parts, 0) &&
+        isRejected(index, otherIndex),
+    );
+    if (isCovering) {
+      covering.add(index);
+    }
+  });
+  return covering;
+}

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