openapi-typesafe 1.0.0-rc.3 → 1.0.0-rc.5

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

@@ -1,20 +1,8 @@
 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 { FIX } from "../../../domain/output-fixes.js";
+import { appendPointer, ROOT_POINTER } from "../../../domain/openapi/json-pointer.js";
+import type { PathItemObject, PathsObject } from "../../../domain/openapi/path-item-object.js";
 import { documentEntries } from "../document-entries.js";
 import { refType } from "../ref-type.js";
 import type { TransformContext } from "../transform-context.js";
@@ -26,143 +14,88 @@ import {
   coveringTemplateKeys,
   type PathKey,
   type PathKeyPart,
-  type PathPlaceholder,
 } from "./path-key-overlaps.js";
 import {
-  type PathParameterMatch,
-  placeholderText,
-  replacedTemplateParts,
-} from "./path-template-replace.js";
+  booleanExpandedKeys,
+  pathTemplateParts,
+  plainUrlOf,
+  templateText,
+} from "./path-template-key.js";
 import { assignabilityProof } from "./type-assignability.js";
 
-/** `[^{}]` keeps the scan linear: `[^}]` retried from every `{` of a long run of them. */
-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);
+/** 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 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);
-    }
-  }
+/** The key of the parts: a plain URL, or a template with placeholders left. */
+export function pathKeyOf(parts: readonly PathKeyPart[]): PathKey {
+  const plainUrl = plainUrlOf(parts);
+  return plainUrl === null ? { kind: "template", parts } : literalKey(plainUrl);
 }
 
-/** 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);
+/** The member of one key of a path: a property for a plain URL, else an index signature. */
+function keyMember(url: string, parts: readonly PathKeyPart[], type: IrType, isReadonly: boolean) {
+  const key = pathKeyOf(parts);
+  if (key.kind === "literal") {
+    const member = irProperty(toPropertyName(key.url), type, { isReadonly });
+    return { url, member, key, type };
   }
-  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 }];
-  });
+  const member: IrMember = {
+    kind: "indexSignature",
+    parameterName: "path",
+    parameterType: irRaw(templateText(parts)),
+    type,
+    isReadonly,
+    comments: [],
+  };
+  return { url, member, key, 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.
+ * Whether a key of the path at `url` is written. A URL that `${boolean}` keys give is not when it
+ * is taken already: by a path of the document, which OpenAPI matches before a template (Paths
+ * Object), or by the keys of an earlier path. A property written twice does not compile (TS2300).
+ * `takenUrls` starts with the document's URLs and gets each expanded URL, in document order.
  */
-function pathTemplateParts(
-  url: string,
-  pathItem: PathItemObject,
-  context: TransformContext,
-): PathKeyPart[] | null {
-  const found = url.match(PATH_PARAMETER_RE);
-  if (!found) {
-    return null;
+export function isUntakenKey(url: string, key: PathKey, takenUrls: Set<string>): boolean {
+  const isExpandedUrl = key.kind === "literal" && key.url !== url;
+  if (!isExpandedUrl) {
+    return true;
   }
-  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(FIX.PATH_PARAM_TYPE_NAMES)
-    ? splitTemplateParts(url, matches)
-    : replacedTemplateParts(url, matches);
+  const isTaken = takenUrls.has(key.url);
+  takenUrls.add(key.url);
+  return !isTaken;
 }
 
-/**
- * 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}\``;
+function withoutTakenUrls(url: string, members: readonly PathMember[], takenUrls: Set<string>) {
+  return members.filter(({ key }) => isUntakenKey(url, key, takenUrls));
 }
 
-/** 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(
+/** The members of a path: one, or one per key of its `${boolean}` placeholders. */
+function pathItemMembers(
   url: string,
   pathItem: PathItemObject,
   context: TransformContext,
-): PathMember {
+): PathMember[] {
   const isReadonly = context.options.immutable;
-  const type = pathItemType(pathItem, { path: createRef(["paths", url]) }, context);
+  const type = pathItemType(
+    pathItem,
+    { path: appendPointer(ROOT_POINTER, ["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 };
+    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 };
+  return booleanExpandedKeys(parts).map((key) => keyMember(url, key, type, isReadonly));
 }
 
 function literalKey(url: string): PathKey {
@@ -244,6 +177,7 @@ export function pathsObjectType(
 /** 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[] = [];
+  const takenUrls = new Set(Object.keys(paths));
   for (const [url, pathItem] of documentEntries(paths, context.options)) {
     if (!pathItem || typeof pathItem !== "object") {
       continue;
@@ -255,10 +189,10 @@ export function pathMembers(paths: PathsObject, context: TransformContext): Path
       continue;
     }
     const startedAt = context.diagnostics.now();
-    const path = pathItemMember(url, pathItem, context);
-    members.push(path);
+    const pathMembersOfUrl = pathItemMembers(url, pathItem, context);
+    members.push(...withoutTakenUrls(url, pathMembersOfUrl, takenUrls));
     // The original reports only paths written as properties.
-    if (path.member.kind === "property") {
+    if (pathMembersOfUrl[0]?.key.kind === "literal" && pathMembersOfUrl[0].key.url === url) {
       context.diagnostics.debug(`Transformed path "${url}"`, context.diagnostics.now() - startedAt);
     }
   }

package/src/application/transform/document/referenced-parameter.ts

@@ -0,0 +1,146 @@
+import { irReference } from "../../../domain/ir/constructors.js";
+import type { IrType } from "../../../domain/ir/nodes.js";
+import {
+  appendPointer,
+  parseRefPointer,
+  ROOT_POINTER,
+} from "../../../domain/openapi/json-pointer.js";
+import type { OperationObject } from "../../../domain/openapi/operation-object.js";
+import {
+  type ParameterObject,
+  type ParameterOrReference,
+  QUERYSTRING_LOCATION,
+} from "../../../domain/openapi/parameter-object.js";
+import {
+  ADDITIONAL_OPERATIONS_KEY,
+  HTTP_METHODS,
+  type PathItemObject,
+  QUERY_METHOD,
+} from "../../../domain/openapi/path-item-object.js";
+import { indexBy, refType } from "../ref-type.js";
+import type { RefResolver } from "../schema/schema-context.js";
+import type { TransformContext } from "../transform-context.js";
+import { mergedParameters, type ParameterEntry, parameterEntries } from "./parameter-entries.js";
+
+/**
+ * The type of a parameter `$ref`. The original indexed the parameter's location and name
+ * (`refType`): `#/paths/~1a/get/parameters/0` gave
+ * `paths["/a"]["get"]["parameters"]["query"]["q"]`.
+ * Where the generated type differs, that does not compile, and only there it changes:
+ *
+ * - A location whose parameters are all optional is an optional member (`query?:`), so indexing it
+ *   fails (TS2339); it is wrapped in `NonNullable` before the name is indexed.
+ * - An OpenAPI 3.2 `in: querystring` parameter is the whole `query` member (ADR-020), not a member
+ *   `querystring`, so the pointer reads `["query"]`.
+ *
+ * A `$ref` to a component parameter, or into a list the generator types elsewhere (a `$ref` path
+ * item or operation, a callback), keeps the original type.
+ */
+
+const INDEX_RE = /^\d+$/;
+const OPERATION_KEYS: ReadonlySet<string> = new Set([...HTTP_METHODS, QUERY_METHOD]);
+
+/** A `parameters/N` pointer, split into its root and the segments of the list's owner. */
+interface ParameterListPointer {
+  readonly root: string;
+  readonly owner: readonly string[];
+}
+
+function listPointerOf(ref: string): ParameterListPointer | null {
+  if (!ref.startsWith(`${ROOT_POINTER}/`)) {
+    return null;
+  }
+  const [root, ...segments] = parseRefPointer(ref);
+  const [list, position] = segments.slice(-2);
+  const isList = list === "parameters" && position !== undefined && INDEX_RE.test(position);
+  return root !== undefined && isList ? { root, owner: segments.slice(0, -2) } : null;
+}
+
+function pointerTo(root: string, segments: readonly string[]): string {
+  return appendPointer(ROOT_POINTER, [root, ...segments]);
+}
+
+/** Whether the segments name a path item that `pathItemType` types in place. */
+function isPathItemAt(root: string, segments: readonly string[]): boolean {
+  const isNamedRoot = root === "paths" || root === "webhooks";
+  return (
+    (isNamedRoot && segments.length === 1) ||
+    (root === "components" && segments[0] === "pathItems" && segments.length === 2)
+  );
+}
+
+/** The segments of the path item that holds the operation at `owner`, or null. */
+function pathItemOfOperation(root: string, owner: readonly string[]): readonly string[] | null {
+  const method = owner.at(-1) ?? "";
+  if (OPERATION_KEYS.has(method) && isPathItemAt(root, owner.slice(0, -1))) {
+    return owner.slice(0, -1);
+  }
+  const isAdditional = owner.at(-2) === ADDITIONAL_OPERATIONS_KEY;
+  return isAdditional && isPathItemAt(root, owner.slice(0, -2)) ? owner.slice(0, -2) : null;
+}
+
+function documentNode<T>(refs: RefResolver, root: string, segments: readonly string[]): T | null {
+  const node = refs.resolve(pointerTo(root, segments));
+  const isTypedHere = typeof node === "object" && node !== null && !("$ref" in node);
+  return isTypedHere ? (node as T) : null;
+}
+
+/** The parameters the generator types at the list's owner; null where it types them elsewhere. */
+function typedParameters(
+  pointer: ParameterListPointer,
+  refs: RefResolver,
+): readonly ParameterOrReference[] | null {
+  const { root, owner } = pointer;
+  if (isPathItemAt(root, owner)) {
+    return documentNode<PathItemObject>(refs, root, owner)?.parameters ?? null;
+  }
+  const pathItemSegments = pathItemOfOperation(root, owner);
+  const pathItem = pathItemSegments && documentNode<PathItemObject>(refs, root, pathItemSegments);
+  const operation = pathItem && documentNode<OperationObject>(refs, root, owner);
+  return pathItem && operation ? mergedParameters(pathItem, operation, refs) : null;
+}
+
+/** A location member is optional when none of its parameters is required (`locationParts`). */
+function isLocationOptional(entries: readonly ParameterEntry[], location: string): boolean {
+  return entries
+    .filter((entry) => entry.resolved?.in === location)
+    .every((entry) => location !== "path" && !entry.resolved?.required);
+}
+
+/** The corrected type, or null where the original type compiles or no correction applies. */
+function correctedType(
+  listType: IrType,
+  entries: readonly ParameterEntry[],
+  parameter: ParameterObject,
+): IrType | null {
+  if (parameter.in === QUERYSTRING_LOCATION) {
+    // Next to `in: query` parameters it is not in the generated types (QUERYSTRING_NEXT_TO_QUERY).
+    const isTyped = !entries.some((entry) => entry.resolved?.in === "query");
+    return isTyped ? indexBy(listType, "query") : null;
+  }
+  if (!isLocationOptional(entries, parameter.in)) {
+    return null;
+  }
+  const location = irReference("NonNullable", [indexBy(listType, parameter.in)]);
+  return indexBy(location, parameter.name);
+}
+
+/** The type of a parameter `$ref` whose target resolved to `resolved`; see the module comment. */
+export function referencedParameterType(
+  ref: string,
+  resolved: ParameterObject,
+  context: TransformContext,
+): IrType {
+  // A `$ref` that resolves to another `$ref` is not a parameter object yet: index it as a path.
+  if ((resolved as { $ref?: unknown }).$ref) {
+    return refType(ref, { parameter: null });
+  }
+  const original = refType(ref, { parameter: { in: resolved.in, name: resolved.name } });
+  const pointer = listPointerOf(ref);
+  const parameters = pointer && typedParameters(pointer, context.refs);
+  if (pointer === null || parameters === null) {
+    return original;
+  }
+  const listType = refType(pointerTo(pointer.root, [...pointer.owner, "parameters"]));
+  return correctedType(listType, parameterEntries(parameters, context), resolved) ?? original;
+}

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

@@ -1,7 +1,7 @@
 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 { appendPointer } 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";
@@ -18,7 +18,7 @@ function contentMembers(
 ): IrMember[] {
   const entries = documentEntries(requestBody.content ?? {}, context.options);
   return entries.map(([contentType, entry]) => {
-    const path = createRef([location.path, "content", contentType]);
+    const path = appendPointer(location.path, ["content", contentType]);
     const type = contentEntryType(entry, { ...location, path }, context);
     return documentMember(contentType, type, entry, { isReadonly: context.options.immutable });
   });

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

@@ -6,7 +6,7 @@ import {
 } 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 { appendPointer } from "../../../domain/openapi/json-pointer.js";
 import {
   isMediaTypeComponentRef,
   type MediaTypeObject,
@@ -34,7 +34,7 @@ function headerMember(
     ? refType(header.$ref)
     : headerType(
         header,
-        { ...location, path: createRef([location.path, "headers", name]) },
+        { ...location, path: appendPointer(location.path, ["headers", name]) },
         context,
       );
   return documentMember(name, type, header, {
@@ -79,7 +79,7 @@ function contentMember(
 ): IrPropertySignature {
   const entries = documentEntries(response.content ?? {}, context.options);
   const members = entries.map(([contentType, entry]) => {
-    const path = createRef([location.path, "content", contentType]);
+    const path = appendPointer(location.path, ["content", contentType]);
     const type = mediaTypeEntryType(entry, { ...location, path }, context);
     return documentMember(contentType, type, entry, { isReadonly: context.options.immutable });
   });

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

@@ -1,6 +1,6 @@
 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 { appendPointer } 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";
@@ -20,7 +20,7 @@ export function responsesType(
         ? refType(response.$ref)
         : responseType(
             response,
-            { ...location, path: createRef([location.path, "responses", code]) },
+            { ...location, path: appendPointer(location.path, ["responses", code]) },
             context,
           );
     return documentMember(code, type, response, { isReadonly: context.options.immutable });

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

@@ -2,6 +2,8 @@ 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";
+import { freeNumberedName } from "../numbered-names.js";
+import { typeNamesDeclaredBy } from "./declared-type-names.js";
 import { globalTypeReferences } from "./global-type-references.js";
 
 /** The `--root-types` aliases: `export type Pet = components['schemas']['Pet'];`. */
@@ -25,7 +27,8 @@ export function rootTypeAlias(
   };
 }
 
-function isRootTypeAlias(declaration: IrDeclaration): declaration is IrTypeAliasDeclaration {
+/** Whether the declaration is a `--root-types` alias, which gives way to every other name. */
+export function isRootTypeAlias(declaration: IrDeclaration): declaration is IrTypeAliasDeclaration {
   return (
     declaration.kind === "typeAlias" &&
     declaration.type.kind === "raw" &&
@@ -33,23 +36,6 @@ function isRootTypeAlias(declaration: IrDeclaration): declaration is IrTypeAlias
   );
 }
 
-/**
- * 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) =>
@@ -58,21 +44,15 @@ function declaredNames(declarations: readonly IrDeclaration[]): Set<string> {
   );
 }
 
-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;
-}
-
 /**
- * Rename each root alias whose name an enum or a helper type of the footer also declares, or that
- * shadows a TypeScript global type the output refers to (`Record` in `Record<string, never>`), to
- * the next free `Name_2`, `Name_3`, … (the suffix `--root-types` uses for its own conflicts). The
- * footer and the globals keep their names, because the generated types refer to them. Before, the
- * output did not compile (enums: upstream #2099, #2341, #2206; helpers: a schema named
- * `WithRequired`, roadmap R11; globals: TS2315). Other declarations are returned unchanged.
+ * Rename each root alias whose name another declaration of the output also takes (an enum, a
+ * helper type, the `--make-paths-enum` enum `ApiPaths`, a root interface, `--read-write-markers`
+ * or `inject` types), or that shadows a TypeScript global type the output refers to (`Record` in
+ * `Record<string, never>`), to the next free `Name_2`, `Name_3`, … (the suffix `--root-types` uses
+ * for its own conflicts). The others and the globals keep their names, because the generated
+ * types refer to them. Before, the output did not compile (enums: upstream #2099, #2341, #2206;
+ * helpers: a schema named `WithRequired`, roadmap R11; globals: TS2315; `ApiPaths`: TS2567).
+ * Other declarations are returned unchanged.
  *
  * With the `root-type-numbering` fix (ADR-021, roadmap R13, backlog 30) the body also holds the
  * aliases a later schema of one exported name took the name from, after the other aliases and
@@ -85,11 +65,10 @@ export function renameTakenAliases<T extends IrDeclaration>(
   footer: readonly IrDeclaration[],
   closing: readonly IrDeclaration[] = [],
 ): T[] {
-  const reserved = footerTypeNames(footer);
-  for (const name of globalTypeReferences([...body, ...footer, ...closing])) {
-    reserved.add(name);
-  }
-  const taken = declaredNames([...body, ...footer, ...closing]);
+  const all = [...body, ...footer, ...closing];
+  const others = all.filter((declaration) => !isRootTypeAlias(declaration));
+  const reserved = new Set([...typeNamesDeclaredBy(others), ...globalTypeReferences(all)]);
+  const taken = new Set([...declaredNames(all), ...typeNamesDeclaredBy(all)]);
   const aliasNames = new Set<string>();
   return body.map((declaration) => {
     if (!isRootTypeAlias(declaration)) {
@@ -100,7 +79,7 @@ export function renameTakenAliases<T extends IrDeclaration>(
     if (!isRepeated && !reserved.has(declaration.name)) {
       return declaration;
     }
-    const name = freeName(declaration.name, taken);
+    const name = freeNumberedName(declaration.name, taken);
     taken.add(name);
     return { ...declaration, name };
   });

package/src/application/transform/document/type-resolution.ts

@@ -1,3 +1,4 @@
+import { appendAll } from "../../../domain/append-all.js";
 import type {
   IrIndexSignature,
   IrMember,
@@ -156,7 +157,7 @@ export class TypeResolution {
       if (objects === null) {
         return null;
       }
-      parts.push(...objects);
+      appendAll(parts, objects);
     }
     return parts;
   }

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

@@ -1,22 +1,35 @@
 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 { appendPointer, ROOT_POINTER } from "../../../domain/openapi/json-pointer.js";
 import type { PathItemObject, PathsObject } from "../../../domain/openapi/path-item-object.js";
 import { documentEntries } from "../document-entries.js";
+import { refType } from "../ref-type.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.
+ * The `webhooks` interface body (OpenAPI 3.1 §4.8.1): one path item per webhook name. A `$ref`
+ * entry (often to `components/pathItems`) is the type it points at, as in `paths`; the original
+ * read it as a path item, so every method was `never`. 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);
+    const type = webhookType(name, pathItem, context);
     return irProperty(toPropertyName(name), type, { isReadonly: context.options.immutable });
   });
   return irObject(members);
 }
+
+function webhookType(
+  name: string,
+  pathItem: PathsObject[string],
+  context: TransformContext,
+): IrType {
+  // A document may hold any value here; one that is no object is read as a path item, as before.
+  if (typeof pathItem === "object" && pathItem !== null && "$ref" in pathItem) {
+    return refType(pathItem.$ref);
+  }
+  const location = { path: appendPointer(ROOT_POINTER, ["webhooks", name]) };
+  return pathItemType(pathItem as PathItemObject, location, context);
+}