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

package/src/api/transform-schema.ts

@@ -1,14 +1,24 @@
 import type { ts } from "../adapters/type-ast-bridge/typescript-types.js";
 import { documentBody, documentClosing } from "../application/transform/document/document.js";
+import {
+  NAMES_THE_OUTPUT_MAY_NEED,
+  namesTheOutputNeeds,
+  withEnumsRenamed,
+} from "../application/transform/document/enum-names-given-back.js";
+import { operationKeysWritten } from "../application/transform/document/operation-keys-written.js";
 import { renameTakenAliases } from "../application/transform/document/root-type-aliases.js";
-import { RunFooter } from "../application/transform/footer/document-footer.js";
+import { RunFooter, type RunFooterNames } from "../application/transform/footer/document-footer.js";
+import { EnumNameClaims } from "../application/transform/footer/enum-name-claims.js";
 import { checkedEnumValues } from "../application/transform/footer/enum-values-check.js";
+import { OperationKeys } from "../application/transform/footer/operation-keys.js";
 import {
+  FIRST_SCHEMA_NAMES,
   SharedEnumNameRecorder,
   type SharedEnumNames,
 } from "../application/transform/footer/shared-enum-names.js";
 import type { IrDeclaration } from "../domain/ir/nodes.js";
 import type { DocumentObject } from "../domain/openapi/document-object.js";
+import { schemaDialectOf } from "../domain/openapi/schema-dialect.js";
 import { FIX } from "../domain/output-fixes.js";
 import type { GlobalContext, OpenAPI3 } from "../types.js";
 import { FirstSchemaNameRecorder } from "./discriminator-enum-names.js";
@@ -71,14 +81,46 @@ function enumNameRecorderOf(ctx: GlobalContext): EnumNameRecorder | null {
   return ctx.fix?.includes(FIX.DISCRIMINATOR_VALUES) ? new FirstSchemaNameRecorder() : null;
 }
 
-/** With a naming fix, `--enum` and `--dedupe-enums`, the run's footer names shared enums. */
-function withSharedEnumNames(document: DocumentObject, ctx: RunContext): void {
-  const recorder = ctx.runFooter === undefined ? enumNameRecorderOf(ctx) : null;
-  if (recorder === null || !ctx.enum || !ctx.dedupeEnums) {
+/**
+ * The run's footer: with a naming fix, `--enum` and `--dedupe-enums` it names shared enums. A
+ * footer that a call before created on the context is kept.
+ */
+function withRunFooter(document: DocumentObject, ctx: RunContext, names: RunFooterNames): void {
+  if (ctx.runFooter !== undefined) {
     return;
   }
-  const names = sharedEnumNamesOf(document, ctx, recorder);
-  ctx.runFooter = new RunFooter(new ContextFooterSink(ctx.injectFooter), true, names);
+  const recorder = enumNameRecorderOf(ctx);
+  const shared =
+    recorder === null || !ctx.enum || !ctx.dedupeEnums
+      ? null
+      : sharedEnumNamesOf(document, ctx, recorder);
+  const sink = new ContextFooterSink(ctx.injectFooter);
+  ctx.runFooter =
+    shared === null
+      ? new RunFooter(sink, ctx.dedupeEnums, FIRST_SCHEMA_NAMES, names)
+      : new RunFooter(sink, true, shared, names);
+}
+
+/**
+ * The document with the enums renamed that gave way to a name the output turned out not to need
+ * (`EnumNameClaims`): they get that name back, as before.
+ */
+function withEnumNamesGivenBack(
+  parts: TransformedDocument,
+  names: RunFooterNames,
+): TransformedDocument {
+  const footer = parts.footer.filter(isIrDeclaration);
+  const renames = names.enums.givenBack(namesTheOutputNeeds({ ...parts, footer }));
+  if (renames.size === 0) {
+    return parts;
+  }
+  return {
+    body: withEnumsRenamed(parts.body, renames),
+    footer: parts.footer.map((entry) =>
+      isIrDeclaration(entry) ? (withEnumsRenamed([entry], renames)[0] ?? entry) : entry,
+    ),
+    closing: withEnumsRenamed(parts.closing, renames),
+  };
 }
 
 /**
@@ -105,14 +147,24 @@ function enumValuesChecked(
 /** @internal Root types, the footer, then the closing declarations (Phase 5, step 6). */
 export function transformDocument(schema: OpenAPI3, ctx: RunContext): TransformedDocument {
   const document = schema as DocumentObject;
-  withSharedEnumNames(document, ctx);
+  ctx.schemaDialect = schemaDialectOf(document.openapi);
+  const names: RunFooterNames = {
+    enums: new EnumNameClaims(NAMES_THE_OUTPUT_MAY_NEED),
+    operations: new OperationKeys(operationKeysWritten(document)),
+  };
+  withRunFooter(document, ctx, names);
   const context = createTransformContext(ctx);
   // documentBody registers the enums in the footer, so the footer is read after it.
   const rawBody = documentBody(document, context, () => ctx.injectFooter.filter(isIrDeclaration));
-  const footer = enumValuesChecked(rawBody, [...ctx.injectFooter], ctx);
-  const closing = documentClosing(document, context, footer.some(isOperations));
-  const body = renameTakenAliases(rawBody, footer.filter(isIrDeclaration), closing);
-  return { body, footer, closing };
+  const rawFooter = enumValuesChecked(rawBody, [...ctx.injectFooter], ctx);
+  const rawClosing = documentClosing(document, context, rawFooter.some(isOperations));
+  const parts = { body: rawBody, footer: rawFooter, closing: rawClosing };
+  const { body, footer, closing } = withEnumNamesGivenBack(parts, names);
+  return {
+    body: renameTakenAliases(body, footer.filter(isIrDeclaration), closing),
+    footer,
+    closing,
+  };
 }
 
 /**

package/src/application/ports/file-system.ts

@@ -10,3 +10,42 @@ export interface FileReader {
 export interface FileWriter {
   writeText(file: URL, contents: string): void;
 }
+
+/**
+ * Whether two `file:` locations name one file: also through a symbolic link, a hard link, or
+ * another letter case on a case-insensitive file system, and also when the file does not exist
+ * yet. The CLI asks before it writes, so that an output path never replaces a file the run reads
+ * (`CLI_OUTPUT_IS_INPUT`) nor another API's output (`CLI_OUTPUT_DUPLICATE`).
+ */
+export interface FileIdentity {
+  isSameFile(left: URL, right: URL): boolean;
+}
+
+/**
+ * Whether a `file:` location is an existing directory. An output there is no file the CLI can
+ * write, so it fails with `CLI_OUTPUT_INVALID` before anything is generated.
+ */
+export interface DirectoryCheck {
+  isDirectory(file: URL): boolean;
+}
+
+/**
+ * An output file that exists before its content is written: the claim created it, empty, when it
+ * was missing, so the file system has given it its own identity.
+ */
+export interface ClaimedFile {
+  /** The file system's identity of the file: equal for two paths that name one file. */
+  readonly identity: string;
+  /** Remove what the claim created (the file and its new directories); existing ones stay. */
+  release(): void;
+}
+
+/**
+ * Claim output files before writing to them. Names cannot prove that two missing files are two:
+ * the file system may ignore Unicode normalization, fold `ß` to `SS`, ignore letter case where
+ * nothing can be probed, or follow a link to a directory that does not exist yet. Once each file
+ * exists, its identity is the file system's own. Fails with `OUTPUT_WRITE_FAILED`.
+ */
+export interface FileClaims {
+  claimFile(file: URL): ClaimedFile;
+}

package/src/application/ports/schema-loader.ts

@@ -20,6 +20,16 @@ export interface SchemaLoadRequest {
   readonly refAccess: RefAccess;
 }
 
+/** A bundled document, and the local files read to build it. */
+export interface LoadedSchema {
+  readonly document: OpenAPI3;
+  /**
+   * The root, when it is a local file, and every local file a `$ref` loaded. The CLI keeps its
+   * output from replacing any of them (`CLI_OUTPUT_IS_INPUT`).
+   */
+  readonly localFiles: readonly URL[];
+}
+
 /**
  * Read, validate and bundle an OpenAPI 3 document into one document (ENGINEERING_PLAN 4.5).
  * Fails with a typed error (ADR-011): `SCHEMA_SOURCE_*`, `SCHEMA_LOAD_FAILED`,
@@ -28,5 +38,5 @@ export interface SchemaLoadRequest {
  * `SCHEMA_TOO_DEEP` or `SCHEMA_KEY_UNSUPPORTED`.
  */
 export interface SchemaLoader {
-  load(request: SchemaLoadRequest): Promise<OpenAPI3>;
+  load(request: SchemaLoadRequest): Promise<LoadedSchema>;
 }

package/src/application/print/text-writer.ts

@@ -22,7 +22,12 @@ export function isLineBreak(code: number): boolean {
  */
 export class TextWriter {
   readonly #options: PrintOptions;
-  #output = "";
+  /**
+   * The written parts, joined once at the end. A string built with `+=` is kept by V8 as a tree
+   * of its parts, several times the size of the text, for as long as the text is kept (until the
+   * CLI writes it); `join` gives one flat string.
+   */
+  #parts: string[] = [];
   #indent = 0;
   #isAtLineStart = true;
 
@@ -39,7 +44,9 @@ export class TextWriter {
   }
 
   get text(): string {
-    return this.#output;
+    const text = this.#parts.join("");
+    this.#parts = [text];
+    return text;
   }
 
   increaseIndent(): void {
@@ -61,7 +68,7 @@ export class TextWriter {
 
   /** Write text exactly as given. */
   rawWrite(text: string): void {
-    this.#output += text;
+    this.#parts.push(text);
     this.#updateLineStart(text);
   }
 

package/src/application/stack-overflow.ts

@@ -4,9 +4,11 @@ import { ERROR_CODES, OpenAPITypesafeError } from "../domain/errors.js";
  * Deeply nested schemas (ENGINEERING_PLAN 8.5). Loading, bundling, transforming and printing walk
  * schemas recursively, and Redocly follows each `$ref` inside the walk. On the default Node.js
  * stack, about 550 levels of inline schemas or a chain of about 900 `$ref`s (each schema refers to
- * the next) run out of call stack. Real documents stay far below: every YAML or JSON file goes
- * through the YAML parser, which stops at 100 levels, and the whole corpus passes. The overflow is
- * reported as a typed error instead of a `RangeError` with a stack trace.
+ * the next) run out of call stack. Redocly's walk also passes the keys of an object to one call as
+ * arguments, so a single object with more than about 100,000 keys runs out of it while loading.
+ * Real documents stay far below: every YAML or JSON file goes through the YAML parser, which stops
+ * at 100 levels, and the whole corpus passes. The overflow is reported as a typed error instead of
+ * a `RangeError` with a stack trace.
  */
 
 /** The step that ran out of call stack; named in the message and the details. */
@@ -20,13 +22,15 @@ export function isStackOverflowError(error: unknown): boolean {
   return error instanceof RangeError && STACK_OVERFLOW_MESSAGE.test(error.message);
 }
 
-/** The typed error for a document nested too deeply for the call stack. */
+/** The typed error for a document nested too deeply, or too wide, for the call stack. */
 export function schemaTooDeepError(step: DeepSchemaStep, cause: unknown): OpenAPITypesafeError {
+  const wide = step === "load" ? ", and so does an object with more than about 100,000 keys" : "";
   return new OpenAPITypesafeError({
     code: ERROR_CODES.SCHEMA_TOO_DEEP,
     message:
       `The schema is nested too deeply to ${step}: the call stack ran out. Both inline ` +
-      "schemas and chains of $ref (each schema referring to the next) count; shorten the deepest.",
+      `schemas and chains of $ref (each schema referring to the next) count${wide}; shorten ` +
+      "the deepest.",
     details: { step },
     cause,
   });

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

@@ -18,7 +18,7 @@ import {
   isEnumSchema,
   singularizeComponentKind,
 } from "../../../domain/openapi/components-object.js";
-import { createRef } from "../../../domain/openapi/json-pointer.js";
+import { appendPointer, ROOT_POINTER } from "../../../domain/openapi/json-pointer.js";
 import { FIX } from "../../../domain/output-fixes.js";
 import { type DeprecatedEntryFilter, documentEntries } from "../document-entries.js";
 import type { SchemaLocation } from "../schema/schema-context.js";
@@ -62,7 +62,7 @@ function componentMember(
   item: unknown,
   context: TransformContext,
 ): IrPropertySignature {
-  const location = { path: createRef(["components", kind, name]), schema: item };
+  const location = { path: appendPointer(ROOT_POINTER, ["components", kind, name]), schema: item };
   const type = COMPONENT_TRANSFORMS[kind](item as never, location, context);
   const custom = context.callbacks.transform(item, location);
   const property = irProperty(toPropertyName(name), custom?.type ?? type, {

package/src/application/transform/document/declared-type-names.ts

@@ -0,0 +1,36 @@
+import type { IrDeclaration } from "../../../domain/ir/nodes.js";
+
+/**
+ * The type names that declarations of the output take. Two declarations of one type name do not
+ * compile (TS2300, TS2567), or merge into one type without an error (two enums, two interfaces).
+ */
+
+/**
+ * A declaration at the start of a line of raw text: the helper types, the `--read-write-markers`
+ * types, `inject` text and footer nodes from user code. A `const` lives in the value namespace.
+ */
+const RAW_TYPE_DECLARATION_RE =
+  /^(?:export\s+)?(?:declare\s+)?(?:type|interface|enum|const\s+enum|class)\s+([A-Za-z_$][\w$]*)/gm;
+
+/** The type names that raw declaration text declares. */
+export function typeNamesInText(text: string): string[] {
+  return [...text.matchAll(RAW_TYPE_DECLARATION_RE)].map((match) => match[1] ?? "");
+}
+
+function typeNamesOf(declaration: IrDeclaration): readonly string[] {
+  switch (declaration.kind) {
+    case "rawDeclaration":
+      return declaration.name === undefined
+        ? typeNamesInText(declaration.text)
+        : [declaration.name];
+    case "constArray":
+      return [];
+    default:
+      return [declaration.name];
+  }
+}
+
+/** Every type name the declarations take; `--enum-values` arrays are values, so they take none. */
+export function typeNamesDeclaredBy(declarations: readonly IrDeclaration[]): Set<string> {
+  return new Set(declarations.flatMap(typeNamesOf));
+}

package/src/application/transform/document/defs-root.ts

@@ -1,7 +1,7 @@
 import { irObject, irProperty } from "../../../domain/ir/constructors.js";
 import type { IrObjectType } 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 { Schema } from "../../../domain/openapi/schema-object.js";
 import { transformSchema } from "../schema/schema-transform.js";
 import type { TransformContext } from "../transform-context.js";
@@ -17,7 +17,7 @@ export function defsRootType(
   context: TransformContext,
 ): IrObjectType {
   const members = Object.entries(defs).map(([name, schema]) => {
-    const location = { path: createRef(["$defs", name]), schema };
+    const location = { path: appendPointer(ROOT_POINTER, ["$defs", name]), schema };
     const type = transformSchema(schema, location, context);
     return irProperty(toPropertyName(name), type, { isReadonly: context.options.immutable });
   });

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

@@ -1,3 +1,4 @@
+import { appendAll } from "../../../domain/append-all.js";
 import { irKeyword, irObject, irRecord } from "../../../domain/ir/constructors.js";
 import type {
   IrDeclaration,
@@ -20,10 +21,10 @@ import { apiPathsEnumDeclaration } from "./paths-enum.js";
 import { webhooksType } from "./webhooks.js";
 
 /** The root types, in output order. */
-const ROOT_KEYS = Object.freeze(["paths", "webhooks", "components", "$defs"] as const);
+export const ROOT_KEYS = Object.freeze(["paths", "webhooks", "components", "$defs"] as const);
 type RootKey = (typeof ROOT_KEYS)[number];
 
-const OPERATIONS_NAME = "operations";
+export const OPERATIONS_NAME = "operations";
 /** The type of a root without members: `Record<string, never>`. */
 const EMPTY_ROOT_TYPE = irRecord(irKeyword("string"), irKeyword("never"));
 
@@ -191,7 +192,7 @@ export function documentBody(
   if (inject !== "") {
     declarations.push({ kind: "rawDeclaration", text: inject });
   }
-  declarations.push(...rootsDeclarations(document, context, footer));
+  appendAll(declarations, rootsDeclarations(document, context, footer));
   return declarations;
 }
 

package/src/application/transform/document/enum-names-given-back.ts

@@ -0,0 +1,91 @@
+import type { IrDeclaration } from "../../../domain/ir/nodes.js";
+import { HELPER_TYPES, READ_WRITE_MARKER_TYPES } from "../helper-types.js";
+import { typeNamesDeclaredBy, typeNamesInText } from "./declared-type-names.js";
+import { OPERATIONS_NAME, ROOT_KEYS } from "./document.js";
+import { GLOBAL_TYPE_NAMES, globalTypeReferences } from "./global-type-references.js";
+import { API_PATHS_NAME } from "./paths-enum.js";
+import { isRootTypeAlias } from "./root-type-aliases.js";
+
+/**
+ * The second step of naming `--enum` declarations (`EnumNameClaims`): once the output is known,
+ * an enum that gave way to a name the output turned out not to need gets that name back.
+ */
+
+/**
+ * The type names the output of a document may need, besides its enums: the global types it may
+ * refer to and the names the generator declares itself. An enum avoids them until the end.
+ */
+export const NAMES_THE_OUTPUT_MAY_NEED: ReadonlySet<string> = new Set([
+  ...GLOBAL_TYPE_NAMES,
+  ...Object.values(HELPER_TYPES).map(({ name }) => name),
+  ...typeNamesInText(READ_WRITE_MARKER_TYPES),
+  API_PATHS_NAME,
+  ...ROOT_KEYS,
+  OPERATIONS_NAME,
+]);
+
+/** The parts of a transformed document; the footer holds only IR declarations here. */
+export interface DocumentParts {
+  readonly body: readonly IrDeclaration[];
+  readonly footer: readonly IrDeclaration[];
+  readonly closing: readonly IrDeclaration[];
+}
+
+/**
+ * The type names the output needs besides its enums: the globals it refers to, and the names of
+ * its other declarations. Root aliases give way to enums (`renameTakenAliases`), so they count
+ * for nothing.
+ */
+export function namesTheOutputNeeds({ body, footer, closing }: DocumentParts): Set<string> {
+  const others = [
+    ...body.filter((declaration) => !isRootTypeAlias(declaration)),
+    ...footer.filter((declaration) => declaration.kind !== "enum"),
+    ...closing,
+  ];
+  return new Set([
+    ...globalTypeReferences([...body, ...footer, ...closing]),
+    ...typeNamesDeclaredBy(others),
+  ]);
+}
+
+/** `origin` holds the compiler node a raw type was printed from; it is not IR. */
+const SKIPPED_KEYS: ReadonlySet<string> = new Set(["origin"]);
+
+/** The enum references the generator writes: `Name`, `Name.member` and `typeof Name`. */
+const ENUM_REFERENCE_RE = /^(typeof )?([^.]+)(\..*)?$/s;
+
+function renamedReference(name: string, renames: ReadonlyMap<string, string>): string {
+  const match = ENUM_REFERENCE_RE.exec(name);
+  const renamed = match === null ? undefined : renames.get(match[2] ?? "");
+  return renamed === undefined ? name : `${match?.[1] ?? ""}${renamed}${match?.[3] ?? ""}`;
+}
+
+function isNode(value: unknown): value is Readonly<Record<string, unknown>> {
+  return typeof value === "object" && value !== null;
+}
+
+function renamedNode(value: unknown, renames: ReadonlyMap<string, string>): unknown {
+  if (Array.isArray(value)) {
+    return value.map((item) => renamedNode(item, renames));
+  }
+  if (!isNode(value)) {
+    return value;
+  }
+  const node = Object.fromEntries(
+    Object.entries(value).map(([key, child]) => [
+      key,
+      SKIPPED_KEYS.has(key) ? child : renamedNode(child, renames),
+    ]),
+  );
+  const isNamed =
+    (node.kind === "reference" || node.kind === "enum") && typeof node.name === "string";
+  return isNamed ? { ...node, name: renamedReference(node.name as string, renames) } : node;
+}
+
+/** The declarations with each enum in `renames` (old name to new) renamed, references too. */
+export function withEnumsRenamed<T extends IrDeclaration>(
+  declarations: readonly T[],
+  renames: ReadonlyMap<string, string>,
+): T[] {
+  return renames.size === 0 ? [...declarations] : (renamedNode(declarations, renames) as T[]);
+}

package/src/application/transform/document/global-type-references.ts

@@ -6,7 +6,7 @@ import type { IrDeclaration } from "../../../domain/ir/nodes.js";
  * (`Exclude<…>`, `Readonly<…>`). A module declaration of the same name shadows the global: every
  * use of it then fails to compile, or silently names the module's type (`Blob`).
  */
-const GLOBAL_TYPE_NAMES: ReadonlySet<string> = new Set([
+export const GLOBAL_TYPE_NAMES: ReadonlySet<string> = new Set([
   "Array",
   "Blob",
   "Exclude",

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

@@ -1,7 +1,7 @@
 import { irObject, irProperty } from "../../../domain/ir/constructors.js";
 import type { 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, createRef } from "../../../domain/openapi/json-pointer.js";
 import {
   type ContentMap,
   isMediaTypeComponentRef,
@@ -48,9 +48,10 @@ function itemSchemaAt(
     const resolved = isMediaTypeComponentRef(entry.$ref)
       ? (context.refs.resolve(entry.$ref) as MediaTypeObject | undefined)
       : undefined;
+    // `createRef` reads the `$ref` itself as a pointer; only the constant segment is appended.
     return { schema: resolved?.itemSchema, path: createRef([entry.$ref, "itemSchema"]) };
   }
-  return { schema: entry.itemSchema, path: createRef([path, "itemSchema"]) };
+  return { schema: entry.itemSchema, path: appendPointer(path, ["itemSchema"]) };
 }
 
 /**
@@ -64,7 +65,7 @@ export function itemContentMember(
   flags: { readonly isReadonly: boolean },
 ): IrPropertySignature | null {
   const members = documentEntries(content, context.options).flatMap(([mediaType, entry]) => {
-    const contentPath = createRef([location.path, "content", mediaType]);
+    const contentPath = appendPointer(location.path, ["content", mediaType]);
     const item = itemSchemaAt(entry, contentPath, context);
     if (item.schema === undefined) {
       return [];

package/src/application/transform/document/operation-keys-written.ts

@@ -0,0 +1,27 @@
+import { appendAll } from "../../../domain/append-all.js";
+import { operationKeyOf } from "./path-item.js";
+
+/**
+ * Every `operations` key that an `operationId` in the document asks for, so that a repeated ID
+ * never gets a number another operation has as its own ID (`OperationKeys`). Operations can sit
+ * in `paths`, `webhooks`, `components.pathItems` and callbacks, so the whole document is read. A
+ * Link Object's `operationId` is read too; an extra name only makes a number skip it.
+ */
+export function operationKeysWritten(document: object): Set<string> {
+  const keys = new Set<string>();
+  const seen = new WeakSet<object>();
+  const pending: unknown[] = [document];
+  while (pending.length > 0) {
+    const value = pending.pop();
+    if (typeof value !== "object" || value === null || seen.has(value)) {
+      continue;
+    }
+    seen.add(value);
+    const { operationId } = value as { operationId?: unknown };
+    if (typeof operationId === "string") {
+      keys.add(operationKeyOf(operationId));
+    }
+    appendAll(pending, Object.values(value));
+  }
+  return keys;
+}

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

@@ -1,7 +1,7 @@
 import { irKeyword, irProperty } from "../../../domain/ir/constructors.js";
 import type { IrPropertySignature } 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 { OperationObject } from "../../../domain/openapi/operation-object.js";
 import type { RequestBodyObject } from "../../../domain/openapi/request-body-object.js";
 import { refType } from "../ref-type.js";
@@ -31,7 +31,7 @@ function requestBodyMember(
     ? refType(body.$ref)
     : requestBodyType(
         body,
-        { ...location, path: createRef([location.path, "requestBody"]) },
+        { ...location, path: appendPointer(location.path, ["requestBody"]) },
         context,
       );
   const resolved = isReference

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

@@ -0,0 +1,70 @@
+import type { OperationObject } from "../../../domain/openapi/operation-object.js";
+import type {
+  ParameterObject,
+  ParameterOrReference,
+} from "../../../domain/openapi/parameter-object.js";
+import type { PathItemObject } from "../../../domain/openapi/path-item-object.js";
+import type { SchemaObject } from "../../../domain/openapi/schema-object.js";
+import type { RefResolver } from "../schema/schema-context.js";
+import type { TransformContext } from "../transform-context.js";
+
+/** A parameter as written in the document, and the object its `$ref` points to. */
+export interface ParameterEntry {
+  readonly original: ParameterOrReference;
+  readonly resolved: ParameterObject | undefined;
+}
+
+/** An entry whose `$ref` resolved, so its location and name are known. */
+export type ResolvedEntry = ParameterEntry & { readonly resolved: ParameterObject };
+
+/** The parameter object itself, or the one its `$ref` points to. */
+export function resolveParameter(
+  parameter: ParameterOrReference,
+  refs: RefResolver,
+): ParameterObject | undefined {
+  return "$ref" in parameter
+    ? (refs.resolve(parameter.$ref) as ParameterObject | undefined)
+    : parameter;
+}
+
+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. */
+export function parameterEntries(
+  parameters: readonly ParameterOrReference[],
+  context: TransformContext,
+): ParameterEntry[] {
+  const entries = parameters.map((original) => ({
+    original,
+    resolved: resolveParameter(original, context.refs),
+  }));
+  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;
+}
+
+/**
+ * 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).
+ */
+export function mergedParameters(
+  pathItem: PathItemObject,
+  operation: OperationObject,
+  refs: RefResolver,
+): ParameterOrReference[] {
+  const byKey = new Map<string, ParameterOrReference>();
+  for (const parameter of [...(pathItem.parameters ?? []), ...(operation.parameters ?? [])]) {
+    const resolved = resolveParameter(parameter, refs);
+    byKey.set(`${resolved?.in}-${resolved?.name}`, parameter);
+  }
+  return [...byKey.values()];
+}