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

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. */
@@ -30,14 +32,23 @@ export interface FooterSink {
 }
 
 /**
- * The `--dedupe-enums` key of the original: the values in default sort order, each paired with
- * the metadata at its sorted position (not the value's own metadata), as the original does.
+ * The `--dedupe-enums` key. Two enums share a declaration only when the original shares it and
+ * each value has the same name and description in both. The original key pairs the values in
+ * default sort order with the metadata at the sorted position, not with the value's own metadata,
+ * so `[desc, asc]` and `[asc, desc]`, both named `[Desc, Asc]`, shared one declaration, and one of
+ * them typed `asc` as `Desc = "desc"`. The original also joined `name:description` texts with
+ * `,`, and a member name stood in for its value, so enums with other values (`"1"` and `1`, `A`
+ * and `1` both named `Active`, `["a", "b"]` and `["a:,b"]`) shared one key. As JSON, an equal key
+ * means the same values and metadata; enums the original kept apart still are.
  */
 function dedupeKey(request: EnumDeclarationRequest): string {
-  return [...request.values]
-    .sort(compareAsStrings)
-    .map((value, index) => metadataKey(String(value), request.metadata[index]))
-    .join(",");
+  const sorted = [...request.values].sort(compareAsStrings);
+  const originalPairs = sorted.map((value, index) => memberKey(value, request.metadata[index]));
+  const ownPairs = request.values
+    .map((value, index) => ({ value, member: memberKey(value, request.metadata[index]) }))
+    .sort((left, right) => compareAsStrings(left.value, right.value))
+    .map(({ member }) => member);
+  return JSON.stringify([originalPairs, ownPairs]);
 }
 
 /** `Array.prototype.sort` without a comparator: compares the values as strings. */
@@ -50,8 +61,9 @@ function compareAsStrings(left: string | number, right: string | number): number
   return leftText < rightText ? -1 : 1;
 }
 
-function metadataKey(value: string, metadata: EnumMemberMetadata | undefined): string {
-  return `${metadata?.name ?? value}:${metadata?.description || ""}`;
+/** One member: the value (JSON keeps `"1"` and `1` apart), its name and its description. */
+function memberKey(value: string | number, metadata: EnumMemberMetadata | undefined) {
+  return [value, metadata?.name ?? null, metadata?.description || null];
 }
 
 /** Separates a repeated `--enum-values` array name from its number, as root type aliases do. */
@@ -62,6 +74,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 +101,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 +120,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 +223,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> = {",
@@ -64,10 +65,10 @@ 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;",
-  "}[keyof T];",
+  "type ReadWriteMarkedKeys<T, Marker> = keyof {",
+  "    [K in keyof T as 0 extends 1 & T[K] ? never : NonNullable<T[K]> extends never ? never : " +
+    "NonNullable<T[K]> extends Marker ? K : never]: never;",
+  "};",
   'type ReadWriteResolveArray<T extends readonly unknown[], Resolved extends "read" | ' +
     '"write"> = T[number][] extends T ? T extends unknown[] ? ReadWriteResolve<T[number], ' +
     "Resolved>[] : readonly ReadWriteResolve<T[number], Resolved>[] : {",

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,6 +1,6 @@
-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 { isJsonObject } from "./located-node.js";
 import {
   leadingSegmentsOf,
   type RefPointer,
@@ -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/generated-shape.ts

@@ -1,5 +1,18 @@
 import { isRawBinarySchema } from "../../../domain/openapi/binary-content.js";
 import type { RefResolver, SchemaOptions } from "../schema/schema-context.js";
+import {
+  childLocation,
+  followLocated,
+  isJsonObject,
+  type JsonObject,
+  type LocatedNode,
+} from "./located-node.js";
+import {
+  isExcludedProperty,
+  isMarkedProperty,
+  isNullableSchema,
+  isOptionalProperty,
+} from "./property-shape.js";
 
 /**
  * What the generated type of a schema has under a key, read from the schema itself. It answers the
@@ -8,14 +21,19 @@ import type { RefResolver, SchemaOptions } from "../schema/schema-context.js";
  */
 
 export type GeneratedMember =
-  | { readonly kind: "property"; readonly node: unknown; readonly isOptional: boolean }
+  | {
+      readonly kind: "property";
+      readonly node: unknown;
+      readonly location: string | undefined;
+      readonly isOptional: boolean;
+      /** `$Read<T>` or `$Write<T>` (`isMarkedProperty`): no member but the marker's own. */
+      readonly isMarked: boolean;
+    }
   /** An index signature; `node` is undefined when its value type is `unknown`. */
-  | { readonly kind: "index"; readonly node: unknown }
+  | { readonly kind: "index"; readonly node: unknown; readonly location: string | undefined }
   | { readonly kind: "missing" }
   | { readonly kind: "opaque" };
 
-type JsonObject = Readonly<Record<string, unknown>>;
-
 const OPAQUE_KEYS = ["not", "enum", "const", "$ref"] as const;
 /** How deep `allOf`/`anyOf`/`oneOf` members are read; deeper shapes count as opaque. */
 const MAX_DEPTH = 8;
@@ -23,23 +41,6 @@ const INDEX_RE = /^\d+$/;
 const MISSING: GeneratedMember = { kind: "missing" };
 const OPAQUE: GeneratedMember = { kind: "opaque" };
 
-export function isJsonObject(value: unknown): value is JsonObject {
-  return typeof value === "object" && value !== null && !Array.isArray(value);
-}
-
-/** The schema a node stands for: a `$ref` is followed to its target. */
-export function followRefs(node: unknown, refs: RefResolver): unknown {
-  return isJsonObject(node) && typeof node.$ref === "string" ? refs.resolve(node.$ref) : node;
-}
-
-/** `nullable: true` or a `type` list with `null`: the generated type includes `null`. */
-export function isNullableSchema(node: unknown): boolean {
-  if (!isJsonObject(node)) {
-    return false;
-  }
-  return node.nullable === true || (Array.isArray(node.type) && node.type.includes("null"));
-}
-
 function typeNames(node: JsonObject): readonly unknown[] {
   return Array.isArray(node.type) ? node.type : [node.type];
 }
@@ -90,39 +91,37 @@ function isBuiltInMember(key: string, prototype: object): boolean {
   return key in prototype;
 }
 
-function indexMember(node: JsonObject, options: SchemaOptions): GeneratedMember | null {
-  const { additionalProperties: values, patternProperties: patterns } = node;
+function indexMember(owner: LocatedNode & { node: JsonObject }, options: SchemaOptions) {
+  const { additionalProperties: values, patternProperties: patterns } = owner.node;
   if (isJsonObject(patterns) && Object.keys(patterns).length > 0) {
     return OPAQUE;
   }
   if (isJsonObject(values) && Object.keys(values).length > 0) {
-    return { kind: "index", node: values };
+    const location = childLocation(owner.location, "additionalProperties");
+    return { kind: "index", node: values, location } satisfies GeneratedMember;
   }
   const isImplicit = values === true || (isJsonObject(values) && Object.keys(values).length === 0);
   return isImplicit || (!values && options.additionalProperties)
-    ? { kind: "index", node: undefined }
+    ? ({ kind: "index", node: undefined, location: undefined } satisfies GeneratedMember)
     : null;
 }
 
-function isOptionalProperty(node: JsonObject, key: string, options: SchemaOptions): boolean {
-  const required = Array.isArray(node.required) ? node.required : undefined;
-  const property = (node.properties as JsonObject)[key];
-  const hasDefault = isJsonObject(property) && property.default !== undefined;
-  const isRequired =
-    required?.includes(key) === true ||
-    (required === undefined && options.propertiesRequiredByDefault) ||
-    (hasDefault && options.defaultNonNullable);
-  return !isRequired;
-}
-
-function objectMember(node: JsonObject, key: string, options: SchemaOptions): GeneratedMember {
+function objectMember(
+  owner: LocatedNode & { node: JsonObject },
+  key: string,
+  input: MemberInput,
+): GeneratedMember {
+  const { options } = input;
+  const { node } = owner;
   const properties = isJsonObject(node.properties) ? node.properties : {};
-  if (Object.hasOwn(properties, key)) {
-    const property = properties[key];
-    const isExcluded = options.excludeDeprecated && isJsonObject(property) && property.deprecated;
-    return isExcluded || isJsonObject(node.discriminator)
-      ? OPAQUE
-      : { kind: "property", node: property, isOptional: isOptionalProperty(node, key, options) };
+  if (Object.hasOwn(properties, key) && !isExcludedProperty(properties[key], options, input.refs)) {
+    if (isJsonObject(node.discriminator)) {
+      return OPAQUE;
+    }
+    const location = childLocation(owner.location, "properties", key);
+    const isOptional = isOptionalProperty(owner, key, options);
+    const isMarked = isMarkedProperty(properties[key], options, input.refs);
+    return { kind: "property", node: properties[key], location, isOptional, isMarked };
   }
   // `unevaluatedProperties` adds an index signature with its fix, so it counts as opaque too.
   const isUnknownShape =
@@ -131,38 +130,23 @@ function objectMember(node: JsonObject, key: string, options: SchemaOptions): Ge
     return OPAQUE;
   }
   return hasObjectKeywords(node)
-    ? (indexMember(node, options) ?? MISSING)
+    ? (indexMember(owner, options) ?? MISSING)
     : emptyObjectMember(node, options);
 }
 
-/** Whether a value is there: `present`, `absent` (may be `undefined` or `null`) or `unknown`. */
-export type Presence = "present" | "absent" | "unknown";
-
-/** The presence of a value of `schema` itself: `absent` when its type includes `null`. */
-export function schemaPresence(schema: unknown, refs: RefResolver): Presence {
-  return isNullableSchema(followRefs(schema, refs)) ? "absent" : "present";
-}
-
-/** The presence of property `key` of `schema`: optional or nullable is `absent`. */
-export function propertyPresence(
-  schema: unknown,
-  key: string,
-  options: SchemaOptions,
-  refs: RefResolver,
-): Presence {
-  const node = followRefs(schema, refs);
-  const properties = isJsonObject(node) && isJsonObject(node.properties) ? node.properties : {};
-  if (!isJsonObject(node) || !Object.hasOwn(properties, key)) {
-    return "unknown";
-  }
-  return isOptionalProperty(node, key, options) ? "absent" : schemaPresence(properties[key], refs);
-}
-
 function membersOf(node: JsonObject, keyword: string): readonly unknown[] {
   const members = node[keyword];
   return Array.isArray(members) ? members : [];
 }
 
+/** The members of a composition keyword with their locations. */
+function locatedMembers(owner: LocatedNode & { node: JsonObject }, keyword: string): LocatedNode[] {
+  return membersOf(owner.node, keyword).map((node, index) => ({
+    node,
+    location: childLocation(owner.location, keyword, String(index)),
+  }));
+}
+
 function withoutComposition(node: JsonObject): JsonObject {
   const { allOf: _allOf, anyOf: _anyOf, oneOf: _oneOf, ...own } = node;
   return own;
@@ -178,8 +162,13 @@ function hasOwnObjectType(own: JsonObject): boolean {
  * `anyOf` or `oneOf` alone is a union: a key is missing if one member misses it. A mix of both
  * is written in more than one way (`anyof-properties`), so it counts as opaque.
  */
-function composedMember(node: JsonObject, key: string, input: MemberInput): GeneratedMember {
-  const variants = [...membersOf(node, "anyOf"), ...membersOf(node, "oneOf")];
+function composedMember(
+  owner: LocatedNode & { node: JsonObject },
+  key: string,
+  input: MemberInput,
+): GeneratedMember {
+  const { node } = owner;
+  const variants = [...locatedMembers(owner, "anyOf"), ...locatedMembers(owner, "oneOf")];
   const own = withoutComposition(node);
   const hasOwn = hasOwnObjectType(own);
   if (variants.length > 0) {
@@ -187,7 +176,8 @@ function composedMember(node: JsonObject, key: string, input: MemberInput): Gene
     const members = variants.map((variant) => memberAt(variant, key, input));
     return isAlone && members.some((member) => member.kind === "missing") ? MISSING : OPAQUE;
   }
-  const parts = [...membersOf(node, "allOf"), ...(hasOwn ? [own] : [])];
+  const ownPart = { node: own, location: owner.location };
+  const parts = [...locatedMembers(owner, "allOf"), ...(hasOwn ? [ownPart] : [])];
   return intersectionMember(parts.map((part) => memberAt(part, key, input)));
 }
 
@@ -216,23 +206,22 @@ interface MemberInput {
   readonly depth: number;
 }
 
-function memberAt(schema: unknown, key: string, input: MemberInput): GeneratedMember {
-  const node = followRefs(schema, input.refs);
+function memberAt(schema: LocatedNode, key: string, input: MemberInput): GeneratedMember {
+  const followed = followLocated(schema, input.refs);
+  const { node } = followed;
   if (!isJsonObject(node) || OPAQUE_KEYS.some((name) => name in node) || input.depth > MAX_DEPTH) {
     return OPAQUE;
   }
+  const owner = { ...followed, node };
   if (isNullableSchema(node)) {
     // Every key of `T | null` is an error, unless `T` is unknown (then the type is `unknown`).
     return isObjectShape(node) || isArrayShape(node) ? MISSING : OPAQUE;
   }
-  if (input.options.readWriteMarkers) {
-    return OPAQUE;
-  }
   if ("allOf" in node || "anyOf" in node || "oneOf" in node) {
-    return composedMember(node, key, { ...input, depth: input.depth + 1 });
+    return composedMember(owner, key, { ...input, depth: input.depth + 1 });
   }
   if (isObjectShape(node)) {
-    return objectMember(node, key, input.options);
+    return objectMember(owner, key, input);
   }
   if (isArrayShape(node)) {
     return INDEX_RE.test(key) || isBuiltInMember(key, []) ? OPAQUE : MISSING;
@@ -266,7 +255,7 @@ function primitiveMember(node: JsonObject, key: string): GeneratedMember {
 
 /** The member `key` of the type generated for `schema` (a `$ref` is followed first). */
 export function generatedMember(
-  schema: unknown,
+  schema: LocatedNode,
   key: string,
   options: SchemaOptions,
   refs: RefResolver,

package/src/application/transform/ref-pointer/inline-cycles.ts

@@ -1,5 +1,5 @@
 import type { RefResolver, SchemaOptions } from "../schema/schema-context.js";
-import { isJsonObject } from "./generated-shape.js";
+import { isJsonObject } from "./located-node.js";
 import { pointerNode, refPointerOf } from "./pointer-walk.js";
 import { typedWalk } from "./typed-walk.js";
 

package/src/application/transform/ref-pointer/located-node.ts

@@ -0,0 +1,38 @@
+import { appendPointer } from "../../../domain/openapi/json-pointer.js";
+import type { RefResolver } from "../schema/schema-context.js";
+
+/** Document nodes as the `$ref` pointer walks read them: with their place in the document. */
+
+export type JsonObject = Readonly<Record<string, unknown>>;
+
+/**
+ * A schema node and its JSON Pointer in the document. The generator writes the type of a schema
+ * reached by a `$ref` at the target, and the location decides whether a property with a `default`
+ * is required (`isInputLocation`). Undefined for a node that is not in the document.
+ */
+export interface LocatedNode {
+  readonly node: unknown;
+  readonly location: string | undefined;
+}
+
+export function isJsonObject(value: unknown): value is JsonObject {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+/** The schema a node stands for: a `$ref` is followed to its target. */
+export function followRefs(node: unknown, refs: RefResolver): unknown {
+  return isJsonObject(node) && typeof node.$ref === "string" ? refs.resolve(node.$ref) : node;
+}
+
+/** `followRefs` with the location: a `$ref` is followed to its target and the target's pointer. */
+export function followLocated(located: LocatedNode, refs: RefResolver): LocatedNode {
+  const { node } = located;
+  return isJsonObject(node) && typeof node.$ref === "string"
+    ? { node: refs.resolve(node.$ref), location: node.$ref }
+    : located;
+}
+
+/** The location of a child of a node at `location`, or undefined outside the document. */
+export function childLocation(location: string | undefined, ...segments: string[]) {
+  return location === undefined ? undefined : appendPointer(location, segments);
+}