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

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,7 +1,7 @@
 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 type { TransformContext } from "../transform-context.js";
@@ -14,7 +14,7 @@ import { pathItemType } from "./path-item.js";
  */
 export function webhooksType(webhooks: PathsObject, context: TransformContext): IrType {
   const members = documentEntries(webhooks, context.options).map(([name, pathItem]) => {
-    const location = { path: createRef(["webhooks", name]) };
+    const location = { path: appendPointer(ROOT_POINTER, ["webhooks", name]) };
     const type = pathItemType(pathItem as PathItemObject, location, context);
     return irProperty(toPropertyName(name), type, { isReadonly: context.options.immutable });
   });

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

@@ -12,12 +12,14 @@ import type {
   EnumValuesRequest,
 } from "../schema/schema-context.js";
 import type { DocumentFooter } from "../transform-context.js";
+import { EnumNameClaims } from "./enum-name-claims.js";
 import {
   type DeclaredMembers,
   EnumNaming,
   enumDeclaration,
   withoutDeclaredMembers,
 } from "./enum-naming.js";
+import { OperationKeys } from "./operation-keys.js";
 import { FIRST_SCHEMA_NAMES, type SharedEnumNames } from "./shared-enum-names.js";
 
 /** Where footer declarations go, in order: the run's `ctx.injectFooter`, open to user code. */
@@ -62,6 +64,12 @@ function declarationKey(name: string, request: EnumDeclarationRequest): string {
   return JSON.stringify([name, request.values, request.metadata]);
 }
 
+/** The naming state a run's footer shares with the rest of the run. */
+export interface RunFooterNames {
+  readonly enums: EnumNameClaims;
+  readonly operations: OperationKeys;
+}
+
 /**
  * The footer of one run: enums (deduplicated with `--dedupe-enums`), `--enum-values` arrays, the
  * helper types they need, and the `operations` interface. Replaces the original's module-level
@@ -83,15 +91,18 @@ export class RunFooter implements DocumentFooter {
   private readonly sink: FooterSink;
   private readonly isDedupingEnums: boolean;
   private readonly sharedNames: SharedEnumNames;
+  private readonly names: RunFooterNames;
 
   constructor(
     sink: FooterSink,
     isDedupingEnums: boolean,
     sharedNames: SharedEnumNames = FIRST_SCHEMA_NAMES,
+    names: RunFooterNames = { enums: new EnumNameClaims(), operations: new OperationKeys() },
   ) {
     this.sink = sink;
     this.isDedupingEnums = isDedupingEnums;
     this.sharedNames = sharedNames;
+    this.names = names;
   }
 
   addEnum(request: EnumDeclarationRequest): string {
@@ -99,11 +110,13 @@ export class RunFooter implements DocumentFooter {
     const ownName = this.naming.enumName(request.name);
     const key = this.isDedupingEnums ? dedupeKey(request) : null;
     // Every schema of a shared enum goes to `sharedNames`, the later ones too.
-    const name = key === null ? ownName : this.sharedNames.nameOf(key, ownName, request);
+    const sharedName = key === null ? ownName : this.sharedNames.nameOf(key, ownName, request);
     const known = key === null ? undefined : this.enumNamesByKey.get(key);
     if (known !== undefined) {
       return known;
     }
+    // The owner is the schema location: its requests share one enum, with `--dedupe-enums` too.
+    const name = this.names.enums.nameFor(sharedName, request.name);
     // Only a repeated member fails to compile; two empty declarations merge, so they stay.
     const declared = request.values.length > 0 ? declarationKey(name, request) : null;
     if (declared !== null && this.declaredEnums.has(declared)) {
@@ -200,6 +213,10 @@ export class RunFooter implements DocumentFooter {
     this.sink.addOperation(build);
   }
 
+  operationKey(operationId: string): string {
+    return this.names.operations.keyFor(operationId);
+  }
+
   private require(helper: HelperType): void {
     if (!this.sink.hasTypeAlias(helper.name)) {
       this.sink.add({ kind: "rawDeclaration", name: helper.name, text: helper.text });

package/src/application/transform/footer/enum-name-claims.ts

@@ -0,0 +1,62 @@
+import { freeNumberedName } from "../numbered-names.js";
+
+/**
+ * The names of the `--enum` declarations of one run, unique across the enums and apart from the
+ * names the rest of the output may need.
+ *
+ * Every enum has an owner: the schema location it is named after, or with `--dedupe-enums` its
+ * members. Two owners whose names come out the same (`status` and `Status`) merged into one enum
+ * before, so each accepted the values of the other (upstream behavior). Now the first owner keeps
+ * the name and each later one gets the next free `Name_2`, `Name_3`, …; requests of one owner (a
+ * property and an inline `allOf` item of one schema) still share one enum.
+ *
+ * An enum also gives way to a name the output may need, which is only known at the end: a global
+ * type the output refers to (the `Blob` of `--binary-as-blob`, the `Record` of
+ * `Record<string, never>`), a helper type, or `ApiPaths`. Until then it takes the numbered name;
+ * `givenBack` lists the ones whose own name the output turned out not to need, so output that
+ * compiled before keeps its names (ADR-021).
+ */
+export class EnumNameClaims {
+  private readonly mayBeNeeded: ReadonlySet<string>;
+  /** The first owner of each name an enum asked for. */
+  private readonly owners = new Map<string, string>();
+  /** The name given to each owner, by name asked for and owner. */
+  private readonly given = new Map<string, string>();
+  /** Every name given, and every name the output may need. */
+  private readonly taken: Set<string>;
+  /** A numbered name given only because the output may need the name asked for: that name. */
+  private readonly standIns = new Map<string, string>();
+
+  /** `mayBeNeeded`: the names an enum avoids until the end of the run; empty outside a run. */
+  constructor(mayBeNeeded: ReadonlySet<string> = new Set()) {
+    this.mayBeNeeded = mayBeNeeded;
+    this.taken = new Set(mayBeNeeded);
+  }
+
+  /** The declaration name of the enum `owner` asks to name `name`; the same for every request. */
+  nameFor(name: string, owner: string): string {
+    const key = JSON.stringify([name, owner]);
+    const known = this.given.get(key);
+    if (known !== undefined) {
+      return known;
+    }
+    const isFirstOwner = (this.owners.get(name) ?? owner) === owner;
+    this.owners.set(name, this.owners.get(name) ?? owner);
+    const isFree = isFirstOwner && !this.taken.has(name);
+    const declared = isFree ? name : freeNumberedName(name, this.taken);
+    if (isFirstOwner && this.mayBeNeeded.has(name)) {
+      this.standIns.set(declared, name);
+    }
+    this.taken.add(declared);
+    this.given.set(key, declared);
+    return declared;
+  }
+
+  /**
+   * The numbered names to rename back to the name asked for, because `needed` (the names the
+   * finished output declares or refers to) does not hold that name.
+   */
+  givenBack(needed: ReadonlySet<string>): ReadonlyMap<string, string> {
+    return new Map([...this.standIns].filter(([, name]) => !needed.has(name)));
+  }
+}

package/src/application/transform/footer/operation-keys.ts

@@ -0,0 +1,28 @@
+/**
+ * The keys of the `operations` interface in one run. A repeated `operationId` (Redocly warns
+ * about it) gave the interface two members of one name, which did not compile (TS2300). Now the
+ * first operation with an ID keeps it, and each later one gets the lowest number from 2 whose key
+ * no operation of the document has: the second `listItems` is `listItems2`, the name
+ * `--make-paths-enum` gives it in `ApiPaths` too. Keys follow the order the operations are
+ * transformed in, which is the document order (or the `--alphabetize` order).
+ */
+export class OperationKeys {
+  private readonly written: ReadonlySet<string>;
+  private readonly taken = new Set<string>();
+
+  /** `written`: every operation key of the document; empty outside a document run. */
+  constructor(written: ReadonlySet<string> = new Set()) {
+    this.written = written;
+  }
+
+  /** The key of the next operation with this key, written or numbered. */
+  keyFor(key: string): string {
+    let unique = key;
+    for (let count = 2; this.taken.has(unique); count += 1) {
+      const candidate = `${key}${count}`;
+      unique = this.written.has(candidate) ? unique : candidate;
+    }
+    this.taken.add(unique);
+    return unique;
+  }
+}

package/src/application/transform/footer/type-evaluation.ts

@@ -22,7 +22,7 @@ import { extracted, markerObject, omitted } from "./type-rules.js";
 
 /** How many references one evaluation expands; a deeper one is opaque. */
 const MAX_EXPANSIONS = 200;
-const DEEP_PREFIX = "FlattenedDeepRequired<";
+const DEEP_HELPER = "FlattenedDeepRequired";
 /** How many members distributing an intersection may give; more is opaque. */
 const MAX_DISTRIBUTED = 64;
 
@@ -75,15 +75,15 @@ export class TypeEvaluator {
     if (this.expansions++ > MAX_EXPANSIONS) {
       return OPAQUE;
     }
-    if (name.startsWith(DEEP_PREFIX) && name.endsWith(">")) {
-      const root = this.declared.get(name.slice(DEEP_PREFIX.length, -1));
+    const [first, second] = args;
+    if (name === DEEP_HELPER && first?.kind === "reference" && first.typeArguments.length === 0) {
+      const root = this.declared.get(first.name);
       return root === undefined ? OPAQUE : this.expand({ kind: "type", type: root, deep: true });
     }
     const declared = args.length === 0 ? this.declared.get(name) : undefined;
     if (declared !== undefined) {
       return this.expand({ ...value, type: declared });
     }
-    const [first, second] = args;
     if (first === undefined) {
       return OPAQUE;
     }

package/src/application/transform/helper-types.ts

@@ -51,9 +51,10 @@ export const HELPER_TYPES = {
 /**
  * The `--read-write-markers` helper types, written before the root types. Task 7.6 replaces the
  * original text on purpose (ADR-014): primitives (also branded), readonly arrays, tuples,
- * intersected arrays and null-only properties keep their types (upstream #2615, #2620, #2632,
- * #2717, #2765). The declarations equal `Readable` / `Writable` of openapi-typesafe-helpers
- * (`test/api/read-write-marker-types.test.ts`); the text is what the TypeScript printer prints.
+ * intersected arrays, null-only and `any` properties keep their types (upstream #2615, #2620,
+ * #2632, #2717, #2765). The declarations equal the `Readable` / `Writable` that
+ * openapi-typesafe-fetch declares (`test/api/read-write-marker-types.test.ts`); the text is what
+ * the TypeScript printer prints.
  */
 export const READ_WRITE_MARKER_TYPES = lines(
   "export type $Read<T> = {",
@@ -65,8 +66,8 @@ export const READ_WRITE_MARKER_TYPES = lines(
   "type ReadWritePrimitive = string | number | boolean | bigint | symbol | null | undefined;",
   "type ReadWriteLeaf = ReadWritePrimitive | ((...args: never) => unknown);",
   "type ReadWriteMarkedKeys<T, Marker> = {",
-  "    [K in keyof T]-?: NonNullable<T[K]> extends never ? never : NonNullable<T[K]> " +
-    "extends Marker ? K : never;",
+  "    [K in keyof T]-?: 0 extends 1 & T[K] ? never : NonNullable<T[K]> extends never ? never : " +
+    "NonNullable<T[K]> extends Marker ? K : never;",
   "}[keyof T];",
   'type ReadWriteResolveArray<T extends readonly unknown[], Resolved extends "read" | ' +
     '"write"> = T[number][] extends T ? T extends unknown[] ? ReadWriteResolve<T[number], ' +

package/src/application/transform/numbered-names.ts

@@ -18,3 +18,18 @@ export function withNumberedRepeats(names: readonly string[], numbered: Numbered
     return unique;
   });
 }
+
+/** Separates a repeated declaration name from its number: `Status` → `Status_2`. */
+const DECLARATION_NUMBER_SEPARATOR = "_";
+
+/**
+ * The first of `Name_2`, `Name_3`, … that `taken` does not hold: the suffix `--root-types` uses for
+ * its own conflicts, and every other declaration that must give way to another name.
+ */
+export function freeNumberedName(name: string, taken: ReadonlySet<string>): string {
+  let count = 2;
+  while (taken.has(`${name}${DECLARATION_NUMBER_SEPARATOR}${count}`)) {
+    count += 1;
+  }
+  return `${name}${DECLARATION_NUMBER_SEPARATOR}${count}`;
+}

package/src/application/transform/ref-pointer/generated-location.ts

@@ -1,4 +1,4 @@
-import { createRef } from "../../../domain/openapi/json-pointer.js";
+import { appendPointer, ROOT_POINTER } from "../../../domain/openapi/json-pointer.js";
 import type { RefResolver } from "../schema/schema-context.js";
 import { isJsonObject } from "./generated-shape.js";
 import {
@@ -205,7 +205,7 @@ function walkTo(ref: string, refs: RefResolver, seen: readonly string[]): Locati
 export function generatedLocationOf(ref: string, refs: RefResolver): GeneratedLocation {
   const walk = walkTo(ref, refs, []);
   return {
-    path: walk === null ? ref : createRef(walk.path),
+    path: walk === null ? ref : appendPointer(ROOT_POINTER, walk.path),
     isFromAdditionalProperties: walk?.isFromAdditionalProperties ?? false,
   };
 }

package/src/application/transform/ref-pointer/pointer-type.ts

@@ -1,6 +1,6 @@
 import { irReference } from "../../../domain/ir/constructors.js";
 import type { IrType } from "../../../domain/ir/nodes.js";
-import { OutputFix } from "../../../domain/output-fixes.js";
+import { FIX } from "../../../domain/output-fixes.js";
 import { InvalidRefError, refType } from "../ref-type.js";
 import type { SchemaRequest } from "../schema/schema-rule.js";
 import { generatedLocationOf } from "./generated-location.js";
@@ -62,9 +62,7 @@ function correctedType(
 
 function isCorrected(pointer: RefPointer, request: SchemaRequest): boolean {
   const { options, refs } = request.context;
-  return (
-    options.fixes.has(OutputFix.REF_POINTERS) || originalIndexFails({ pointer, options, refs })
-  );
+  return options.fixes.has(FIX.REF_POINTERS) || originalIndexFails({ pointer, options, refs });
 }
 
 /** The type of a schema `$ref`. Throws InvalidRefError when the `$ref` has no pointer. */

package/src/application/transform/ref-type.ts

@@ -68,7 +68,8 @@ export function indexKeyword(type: IrType, segment: string, isLast: boolean): Ir
 }
 
 export function rootType(rootSegment: string, isDeep: boolean): IrType {
-  return irReference(isDeep ? `FlattenedDeepRequired<${rootSegment}>` : rootSegment);
+  const root = irReference(rootSegment);
+  return isDeep ? irReference("FlattenedDeepRequired", [root]) : root;
 }
 
 /**

package/src/application/transform/schema/access-flags.ts

@@ -1,5 +1,5 @@
 import type { Schema, SchemaObject } from "../../../domain/openapi/schema-object.js";
-import { OutputFix } from "../../../domain/output-fixes.js";
+import { FIX } from "../../../domain/output-fixes.js";
 import type { SchemaContext } from "./schema-context.js";
 
 /** Whether a property is `readOnly` or `writeOnly` (JSON Schema 2020-12 Validation §9.4). */
@@ -56,7 +56,7 @@ export function propertyAccessFlags(value: Schema, context: SchemaContext): Acce
   if (typeof value !== "object") {
     return NO_FLAGS;
   }
-  if (!context.options.fixes.has(OutputFix.READ_WRITE_REFS)) {
+  if (!context.options.fixes.has(FIX.READ_WRITE_REFS)) {
     return ownFlags(value as SchemaObject);
   }
   return appliedFlags(value, context, new Set());