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

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

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

@@ -1,19 +1,22 @@
 import { irKeyword } 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 ParameterObject,
   QUERYSTRING_LOCATION,
 } from "../../../domain/openapi/parameter-object.js";
+import { FIX } from "../../../domain/output-fixes.js";
 import type { SchemaContext, SchemaLocation } from "../schema/schema-context.js";
 import { transformSchema } from "../schema/schema-transform.js";
 import { contentEntryType } from "./media-type.js";
 
 /**
- * An `in: querystring` parameter (OpenAPI 3.2): the whole query string, typed by the schema of its
- * one `content` media type (ADR-020). Without one it is `string`, the query string as text.
+ * A parameter typed by the schema of its one `content` media type. An `in: querystring` parameter
+ * (OpenAPI 3.2) is the whole query string (ADR-020); without a media type it is `string`, the
+ * query string as text. With the `parameter-content` fix, any other parameter with `content`
+ * (OpenAPI 3.0 and later, for a JSON value in a query parameter) is typed the same way.
  */
-function querystringType(
+function contentParameterType(
   parameter: ParameterObject,
   location: SchemaLocation,
   context: SchemaContext,
@@ -22,22 +25,31 @@ function querystringType(
   if (mediaType === undefined || entry === undefined) {
     return irKeyword("string");
   }
-  const path = createRef([location.path, "content", mediaType]);
+  const path = appendPointer(location.path, ["content", mediaType]);
   return contentEntryType(entry, { ...location, path }, context);
 }
 
+function isTypedByContent(parameter: ParameterObject, context: SchemaContext): boolean {
+  if (parameter.in === QUERYSTRING_LOCATION) {
+    return true;
+  }
+  const hasContent = parameter.schema === undefined && parameter.content !== undefined;
+  return hasContent && context.options.fixes.has(FIX.PARAMETER_CONTENT);
+}
+
 /**
  * A parameter's type (OpenAPI 3.2 §4.8.12). Without a schema it is `string`, not `unknown`:
- * query, path, header and cookie values all arrive as text. `content` is read only for
- * `in: querystring`; other parameters with `content` keep their pre-3.2 type.
+ * query, path, header and cookie values all arrive as text. `content` is read for
+ * `in: querystring`, and with the `parameter-content` fix for every parameter; without the fix
+ * other parameters with `content` keep the original's `string`.
  */
 export function parameterType(
   parameter: ParameterObject,
   location: SchemaLocation,
   context: SchemaContext,
 ): IrType {
-  if (parameter.in === QUERYSTRING_LOCATION) {
-    return querystringType(parameter, location, context);
+  if (isTypedByContent(parameter, context)) {
+    return contentParameterType(parameter, location, context);
   }
   return parameter.schema
     ? transformSchema(parameter.schema, location, context)

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

@@ -7,7 +7,7 @@ import {
 } 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 { appendPointer } from "../../../domain/openapi/json-pointer.js";
 import {
   PARAMETER_LOCATIONS,
   type ParameterLocation,
@@ -15,36 +15,23 @@ import {
   type ParameterOrReference,
   QUERYSTRING_LOCATION,
 } from "../../../domain/openapi/parameter-object.js";
-import type { SchemaObject } from "../../../domain/openapi/schema-object.js";
-import { OutputFix } from "../../../domain/output-fixes.js";
-import { refType } from "../ref-type.js";
+import { FIX } from "../../../domain/output-fixes.js";
 import type { SchemaLocation } from "../schema/schema-context.js";
 import { withSchemaComment } from "../schema-comment.js";
 import type { TransformContext } from "../transform-context.js";
 import { isExplodedQueryObject } from "./exploded-query.js";
 import { parameterType } from "./parameter.js";
+import {
+  type ParameterEntry,
+  parameterEntries,
+  type ResolvedEntry,
+  resolveParameter,
+} from "./parameter-entries.js";
+import { referencedParameterType } from "./referenced-parameter.js";
 
 /** `[^{}]` keeps the scan linear: `[^}]` retried from every `{` of a long run of them. */
 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) => ({
@@ -67,7 +54,7 @@ function withPathTemplateParameters(
   }
   for (const parameter of pathTemplateParameters(location.path)) {
     const isDefined = result.some((candidate) => {
-      const resolved = resolveParameter(candidate, context);
+      const resolved = resolveParameter(candidate, context.refs);
       return resolved?.in === "path" && resolved.name === parameter.name;
     });
     if (!isDefined) {
@@ -77,31 +64,6 @@ function withPathTemplateParameters(
   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"
@@ -109,21 +71,14 @@ function parameterName(name: unknown): IrPropertyName {
     : { 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]);
+  const path = appendPointer(location.path, ["parameters", resolved.in, resolved.name]);
   return "$ref" in original
-    ? referencedParameterType(original.$ref, resolved)
+    ? referencedParameterType(original.$ref, resolved, context)
     : parameterType(resolved, { ...location, path }, context);
 }
 
@@ -166,7 +121,7 @@ function querystringMember(
 /** With `exploded-query-objects`, whether the parameter's object keys are keys of `query`. */
 function isExplodedEntry(entry: ResolvedEntry, context: TransformContext): boolean {
   return (
-    context.options.fixes.has(OutputFix.EXPLODED_QUERY_OBJECTS) &&
+    context.options.fixes.has(FIX.EXPLODED_QUERY_OBJECTS) &&
     isExplodedQueryObject(entry.resolved, context.refs)
   );
 }

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

@@ -1,12 +1,8 @@
 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 { appendPointer, ROOT_POINTER } 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,
@@ -21,11 +17,17 @@ 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 { mergedParameters } from "./parameter-entries.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;
 
+/** The `operations` key an `operationId` asks for, before a repeated one gets a number. */
+export function operationKeyOf(operationId: string): string {
+  return operationId.replace(HASH_RE, "/");
+}
+
 /** Whether the method has an operation, not removed by `--exclude-deprecated`. */
 function isIncluded(
   operation: OperationEntry | undefined,
@@ -41,26 +43,6 @@ function isIncluded(
   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.
@@ -71,17 +53,17 @@ function operationType(
   location: SchemaLocation,
   context: TransformContext,
 ): IrType {
-  const merged = { ...operation, parameters: mergedParameters(pathItem, operation, context) };
+  const merged = { ...operation, parameters: mergedParameters(pathItem, operation, context.refs) };
   if (!operation.operationId) {
     return irObject(operationMembers(merged, location, context));
   }
-  const operationId = operation.operationId.replace(HASH_RE, "/");
+  const operationId = context.footer.operationKey(operationKeyOf(operation.operationId));
   context.footer.addOperation(() =>
     irProperty(toPropertyName(operationId), irObject(operationMembers(merged, location, context)), {
       isReadonly: context.options.immutable,
     }),
   );
-  return refType(createRef(["operations", operationId]));
+  return refType(appendPointer(ROOT_POINTER, ["operations", operationId]));
 }
 
 /** An included operation, the member name it gets and its location below the path item. */
@@ -116,7 +98,7 @@ function methodMember(
     const isReadonly = context.options.immutable;
     return irProperty(toPropertyName(method), irKeyword("never"), { isOptional: true, isReadonly });
   }
-  const path = createRef([location.path, method]);
+  const path = appendPointer(location.path, [method]);
   return operationMember({ name: method, operation, path }, pathItem, location, context);
 }
 
@@ -133,7 +115,7 @@ function additionalOperationsMember(
   const members = entries
     .filter(([, operation]) => isIncluded(operation, context))
     .map(([method, operation]) => {
-      const path = createRef([location.path, ADDITIONAL_OPERATIONS_KEY, method]);
+      const path = appendPointer(location.path, [ADDITIONAL_OPERATIONS_KEY, method]);
       return operationMember({ name: method, operation, path }, pathItem, location, context);
     });
   return members.length > 0
@@ -152,7 +134,7 @@ export function pathItemType(
   location: SchemaLocation,
   context: TransformContext,
 ): IrType {
-  const parametersLocation = { ...location, path: createRef([location.path, "parameters"]) };
+  const parametersLocation = { ...location, path: appendPointer(location.path, ["parameters"]) };
   const members: IrMember[] = [
     parametersMember(pathItem.parameters ?? [], parametersLocation, context),
     ...HTTP_METHODS.map((method) => methodMember(method, pathItem, location, context)),

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

@@ -15,7 +15,7 @@ import type { EnumMemberMetadata } from "../schema/schema-context.js";
 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";
+export 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`). */

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

@@ -2,7 +2,7 @@ import { irIntersection, irObject, irProperty, irRaw } from "../../../domain/ir/
 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 { appendPointer, ROOT_POINTER } from "../../../domain/openapi/json-pointer.js";
 import type { OperationObject } from "../../../domain/openapi/operation-object.js";
 import type {
   ParameterObject,
@@ -14,7 +14,7 @@ import {
   pathItemOperations,
 } from "../../../domain/openapi/path-item-object.js";
 import type { ReferenceSchema, SchemaObject } from "../../../domain/openapi/schema-object.js";
-import { OutputFix } from "../../../domain/output-fixes.js";
+import { FIX } from "../../../domain/output-fixes.js";
 import { documentEntries } from "../document-entries.js";
 import { refType } from "../ref-type.js";
 import type { TransformContext } from "../transform-context.js";
@@ -112,7 +112,7 @@ function pathTemplateParts(
     const schema = parameters.get(match.slice(1, -1))?.schema as SchemaObject | undefined;
     return { match, type: PLACEHOLDERS.get(schema?.type) ?? STRING_PLACEHOLDER };
   });
-  return context.options.fixes.has(OutputFix.PATH_PARAM_TYPE_NAMES)
+  return context.options.fixes.has(FIX.PATH_PARAM_TYPE_NAMES)
     ? splitTemplateParts(url, matches)
     : replacedTemplateParts(url, matches);
 }
@@ -145,7 +145,11 @@ function pathItemMember(
   context: TransformContext,
 ): 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)