openapi-typesafe 0.0.0 → 1.0.0-rc.1

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

@@ -0,0 +1,269 @@
+import { irObject, irProperty } from "../../../domain/ir/constructors.js";
+import type {
+  IrMember,
+  IrObjectType,
+  IrPropertySignature,
+  IrType,
+} from "../../../domain/ir/nodes.js";
+import { toPropertyName } from "../../../domain/ir/property-name.js";
+import {
+  type Evaluated,
+  type Evaluation,
+  MISSING,
+  OPAQUE,
+  propertyKey,
+  unionType,
+} from "./evaluation.js";
+
+/**
+ * Rules of TypeScript about intersections, `Omit` and `Extract` that the `--enum-values` check
+ * needs (ADR-027). They read the types as written, before `FlattenedDeepRequired`.
+ */
+
+/** The part of the evaluator these rules use. */
+export interface TypeExpansion {
+  membersOf(value: Evaluated): readonly Evaluation[];
+}
+
+/** A unit value of a type: a literal, `null` or `undefined`. */
+type Unit = string;
+
+/**
+ * The parts an intersection is made of, nested intersections flattened: each object type, or
+ * `null` for a part that is not one.
+ */
+function objectParts(
+  types: TypeExpansion,
+  value: Evaluated,
+  parts: readonly IrType[],
+): (IrObjectType | null)[] {
+  return parts.flatMap((part) => {
+    const members = types.membersOf({ ...value, type: part });
+    const [only] = members;
+    if (members.length !== 1 || only?.kind !== "type") {
+      return [null];
+    }
+    if (only.type.kind === "intersection") {
+      return objectParts(types, only, only.type.types);
+    }
+    return [only.type.kind === "object" ? only.type : null];
+  });
+}
+
+function unitOf(type: IrType): Unit | null {
+  switch (type.kind) {
+    case "stringLiteral":
+      return `s:${type.value}`;
+    case "numberLiteral":
+      return `n:${type.value}`;
+    case "booleanLiteral":
+      return `b:${type.value}`;
+    case "keyword":
+      return type.keyword === "null" || type.keyword === "undefined" ? type.keyword : null;
+    default:
+      return null;
+  }
+}
+
+/** The unit values of a type made only of units, or `null` where it has other values. */
+function unitsOf(types: TypeExpansion, value: Evaluated, type: IrType): ReadonlySet<Unit> | null {
+  const units = types.membersOf({ ...value, type }).map((member) => {
+    return member.kind === "type" ? unitOf(member.type) : null;
+  });
+  return units.includes(null) ? null : new Set(units as Unit[]);
+}
+
+function propertiesNamed(objects: readonly IrObjectType[], key: string): IrPropertySignature[] {
+  return objects.flatMap((object) => {
+    const members: readonly IrMember[] = object.members;
+    return members.filter(
+      (member): member is IrPropertySignature =>
+        member.kind === "property" && propertyKey(member.name) === key,
+    );
+  });
+}
+
+/** Whether properties of the same name share no unit value, one of them required. */
+function isNeverProperty(
+  types: TypeExpansion,
+  value: Evaluated,
+  found: IrPropertySignature[],
+): boolean {
+  if (found.length < 2 || found.every((property) => property.isOptional)) {
+    return false;
+  }
+  const sets = found.map((property) => unitsOf(types, value, property.type));
+  if (sets.includes(null)) {
+    return false;
+  }
+  // At least two properties, so at least two sets.
+  const [first, ...rest] = sets as [ReadonlySet<Unit>, ...ReadonlySet<Unit>[]];
+  const shared = [...first].filter((unit) => rest.every((set) => set.has(unit)));
+  return shared.length === 0;
+}
+
+/** Whether an intersection has `null` or `undefined` next to an object: `null & { a: 1 }`. */
+function isNullishObject(types: TypeExpansion, value: Evaluated, parts: readonly IrType[]) {
+  const singles = parts.map((part) => {
+    const members = types.membersOf({ ...value, type: part });
+    const [only] = members;
+    return members.length === 1 && only?.kind === "type" ? only.type : null;
+  });
+  const isNullish = (type: IrType | null) =>
+    type?.kind === "keyword" && (type.keyword === "null" || type.keyword === "undefined");
+  return singles.some(isNullish) && singles.some((type) => type?.kind === "object");
+}
+
+/**
+ * Whether TypeScript reduces an intersection to `never`: `null` or `undefined` meets an object,
+ * or objects share a property with literal types that have no value in common, one of them
+ * requiring it (`{ a: "x" } & { a: "y" }`). Other properties are left alone, so the answer is
+ * sure where it is yes.
+ */
+export function isNeverIntersection(
+  types: TypeExpansion,
+  value: Evaluated,
+  parts: readonly IrType[],
+): boolean {
+  if (isNullishObject(types, value, parts)) {
+    return true;
+  }
+  const objects = objectParts(types, value, parts).filter((part) => part !== null);
+  if (objects.length < 2) {
+    return false;
+  }
+  const keys = new Set(
+    objects.flatMap((object) =>
+      object.members.flatMap((member) =>
+        member.kind === "property" ? [propertyKey(member.name)] : [],
+      ),
+    ),
+  );
+  const valueOfKeys = { ...value, deep: false };
+  return [...keys].some((key) =>
+    isNeverProperty(types, valueOfKeys, propertiesNamed(objects, key)),
+  );
+}
+
+/** Whether `key` reaches only an index signature of this object: it declares no such property. */
+function isSignatureOnly(types: TypeExpansion, value: Evaluated, key: string | null): boolean {
+  const members = types.membersOf(value);
+  const [only] = members;
+  if (
+    key === null ||
+    members.length !== 1 ||
+    only?.kind !== "type" ||
+    only.type.kind !== "object"
+  ) {
+    return false;
+  }
+  const { members: declared } = only.type;
+  const hasSignature = declared.some((member) => member.kind === "indexSignature");
+  return hasSignature && propertiesNamed([only.type], key).length === 0;
+}
+
+/**
+ * The parts of an intersection indexed by `index`, as TypeScript reads them: where one part
+ * declares the property, the index signatures of the others do not take part
+ * (`{ a: X } & { [key: string]: Y }` gives `X` for `a`).
+ */
+export function declaredFirst(
+  types: TypeExpansion,
+  value: Evaluated,
+  key: string | null,
+  parts: readonly { readonly type: IrType; readonly found: Evaluation }[],
+): Evaluation[] {
+  const bySignature = parts.map(({ type }) => isSignatureOnly(types, { ...value, type }, key));
+  const isDeclared = parts.some(({ found }, at) => found.kind === "type" && !bySignature[at]);
+  return parts.filter((_, at) => !(isDeclared && bySignature[at])).map(({ found }) => found);
+}
+
+/**
+ * Whether a member of `membersOf` has `key` as a property that `{ key: unknown }` accepts: written
+ * and, outside `FlattenedDeepRequired`, required. An index signature does not count, as in
+ * TypeScript. Such a member is expanded, parts included, so it is an object, an intersection of
+ * members, or a primitive or array type, which has no such property; a type the evaluator cannot
+ * read makes `membersOf` opaque instead.
+ */
+function hasKey(value: Evaluated, key: string): boolean {
+  const { type } = value;
+  if (type.kind === "intersection") {
+    return type.types.some((part) => hasKey({ ...value, type: part }, key));
+  }
+  if (type.kind !== "object") {
+    return false;
+  }
+  return propertiesNamed([type], key).some((property) => value.deep || !property.isOptional);
+}
+
+/**
+ * `Extract<T, { key: unknown }>`: the members of `T` that have `key`. When none has it the
+ * result is `never`; it is `missing` here, as the location then types nothing.
+ */
+export function extracted(types: TypeExpansion, value: Evaluated, key: string): Evaluation {
+  const members = types.membersOf(value);
+  if (members.some((member) => member.kind !== "type")) {
+    return OPAQUE;
+  }
+  const kept = (members as Evaluated[]).filter((member) => hasKey(member, key));
+  if (kept.length === 0) {
+    return MISSING;
+  }
+  return { ...value, type: unionType(kept.map((member) => member.type)) };
+}
+
+function omittedKeys(types: TypeExpansion, value: Evaluated, keys: IrType): Set<string> | null {
+  const members = types.membersOf({ ...value, type: keys });
+  const names = members.map((member) =>
+    member.kind === "type" && member.type.kind === "stringLiteral" ? member.type.value : null,
+  );
+  return names.includes(null) ? null : new Set(names as string[]);
+}
+
+/** Whether two members name the same property: merging them would need their intersection. */
+function hasSharedProperty(members: readonly IrMember[]): boolean {
+  const names = members.flatMap((member) =>
+    member.kind === "property" ? [propertyKey(member.name)] : [],
+  );
+  return new Set(names).size !== names.length;
+}
+
+/**
+ * `Omit<T, K>` for literal keys `K` over an object or an intersection of objects. A string index
+ * signature makes `keyof T` all strings, so only the index signatures are left.
+ */
+export function omitted(types: TypeExpansion, value: Evaluated, keys: IrType): Evaluation {
+  const names = omittedKeys(types, value, keys);
+  const objects = objectParts(types, value, [value.type]);
+  if (names === null || objects.length === 0 || objects.includes(null)) {
+    return OPAQUE;
+  }
+  const members = (objects as IrObjectType[]).flatMap((object) => object.members);
+  if (hasSharedProperty(members)) {
+    return OPAQUE;
+  }
+  const signatures = members.filter((member) => member.kind === "indexSignature");
+  const kept =
+    signatures.length > 0
+      ? signatures
+      : members.filter(
+          (member) => member.kind !== "property" || !names.has(propertyKey(member.name)),
+        );
+  return { ...value, type: { kind: "object", members: kept } };
+}
+
+/** The `--read-write-markers` types and their one member (`READ_WRITE_MARKER_TYPES`). */
+const READ_WRITE_MARKER_KEYS: ReadonlyMap<string, string> = new Map([
+  ["$Read", "$read"],
+  ["$Write", "$write"],
+]);
+
+/** `$Read<T>` is `{ readonly $read: T }`: an object, which holds no enum value. */
+export function markerObject(name: string, argument: Evaluated): Evaluated | null {
+  const key = READ_WRITE_MARKER_KEYS.get(name);
+  if (key === undefined) {
+    return null;
+  }
+  const member = irProperty(toPropertyName(key), argument.type, { isReadonly: true });
+  return { ...argument, type: irObject([member]) };
+}

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

@@ -0,0 +1,92 @@
+/**
+ * The helper type aliases the generator adds to the footer, declared once each. The text is the
+ * original's source text as the TypeScript printer printed it, so printing it as written gives
+ * the original output (ENGINEERING_PLAN 6.2 and 6.6), except for the fixes noted below.
+ */
+export interface HelperType {
+  readonly name: string;
+  readonly text: string;
+}
+
+function lines(...parts: readonly string[]): string {
+  return parts.join("\n");
+}
+
+export const HELPER_TYPES = {
+  withRequired: {
+    name: "WithRequired",
+    text: lines("type WithRequired<T, K extends keyof T> = T & {", "    [P in K]-?: T[P];", "};"),
+  },
+  // `unevaluated-properties` (roadmap R11): the value types of every member of a union, so a
+  // `$ref` to a `oneOf` schema gives the values of each variant, not only of the shared keys.
+  propertyValues: {
+    name: "PropertyValues",
+    text: "type PropertyValues<T> = T extends unknown ? T[keyof T] : never;",
+  },
+  // Task 7.4 changes the original text on purpose: `readonly unknown[]` also flattens the arrays
+  // of `--immutable` (upstream #2714, #2749), and `NonNullable` looks through nullable parents
+  // (upstream #2737). The old text did not compile for those schemas.
+  flattenedDeepRequired: {
+    name: "FlattenedDeepRequired",
+    text: lines(
+      "type FlattenedDeepRequired<T> = {",
+      "    [K in keyof T]-?: FlattenedDeepRequired<T[K] extends readonly unknown[] | undefined | " +
+        "null ? Extract<T[K], readonly unknown[]>[number] : NonNullable<T[K]>>;",
+      "};",
+    ),
+  },
+  // `readonly unknown[]`: a readonly array value type stays as is (upstream #2749).
+  readonlyArray: {
+    name: "ReadonlyArray",
+    text: lines(
+      "type ReadonlyArray<T> = [",
+      "    Exclude<T, undefined>",
+      "] extends [",
+      "    readonly unknown[]",
+      "] ? Readonly<Exclude<T, undefined>> : Readonly<Exclude<T, undefined>[]>;",
+    ),
+  },
+} as const satisfies Readonly<Record<string, HelperType>>;
+
+/**
+ * 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.
+ */
+export const READ_WRITE_MARKER_TYPES = lines(
+  "export type $Read<T> = {",
+  "    readonly $read: T;",
+  "};",
+  "export type $Write<T> = {",
+  "    readonly $write: T;",
+  "};",
+  "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 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>[] : {",
+  "    [K in keyof T]: ReadWriteResolve<T[K], Resolved>;",
+  "};",
+  'type ReadWriteResolve<T, Resolved extends "read" | "write"> = Resolved extends "read" ? ' +
+    "Readable<T> : Writable<T>;",
+  "export type Readable<T> = T extends $Write<any> ? never : T extends $Read<infer U> ? " +
+    "Readable<U> : T extends ReadWriteLeaf ? T : T extends readonly unknown[] ? " +
+    'ReadWriteResolveArray<T, "read"> : T extends object ? {',
+  "    [K in keyof T as K extends ReadWriteMarkedKeys<T, $Write<any>> ? never : K]: " +
+    "Readable<T[K]>;",
+  "} : T;",
+  "export type Writable<T> = T extends $Read<any> ? never : T extends $Write<infer U> ? " +
+    "Writable<U> : T extends ReadWriteLeaf ? T : T extends readonly unknown[] ? " +
+    'ReadWriteResolveArray<T, "write"> : T extends object ? {',
+  "    [K in keyof T as K extends ReadWriteMarkedKeys<T, $Read<any>> ? never : K]: " +
+    "Writable<T[K]>;",
+  "} & {",
+  "    [K in ReadWriteMarkedKeys<T, $Read<any>>]?: never;",
+  "} : T;",
+);

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

@@ -0,0 +1,54 @@
+import {
+  irArray,
+  irBoolean,
+  irKeyword,
+  irNumber,
+  irObject,
+  irProperty,
+  irRaw,
+  irRecord,
+  irString,
+  irTuple,
+  irTupleElement,
+} from "../../domain/ir/constructors.js";
+import type { IrType } from "../../domain/ir/nodes.js";
+import { toPropertyName } from "../../domain/ir/property-name.js";
+import { UNKNOWN_TYPE } from "./shared-types.js";
+
+function objectLiteralType(value: object): IrType {
+  const members = Object.entries(value).map(([key, entry]) =>
+    irProperty(toPropertyName(key), literalType(entry)),
+  );
+  return members.length > 0 ? irObject(members) : irRecord(irKeyword("string"), irKeyword("never"));
+}
+
+function arrayLiteralType(value: readonly unknown[]): IrType {
+  return value.length === 0
+    ? irArray(irKeyword("never"))
+    : irTuple(value.map((item) => irTupleElement(literalType(item))));
+}
+
+/**
+ * The literal type of a JSON value (the original `tsLiteral`): strings as JSON text, arrays as
+ * tuples (an empty one as `never[]`), objects as object types (an empty one as
+ * `Record<string, never>`), and anything else (`undefined`, functions) as `unknown`.
+ */
+export function literalType(value: unknown): IrType {
+  if (typeof value === "string") {
+    return irString(value, "json");
+  }
+  if (typeof value === "number") {
+    // YAML `.nan` and `.inf` have no literal type; the original prints them as `NaN`, `-Infinity`.
+    return Number.isFinite(value) ? irNumber(value) : irRaw(String(value));
+  }
+  if (typeof value === "boolean") {
+    return irBoolean(value);
+  }
+  if (value === null) {
+    return irKeyword("null");
+  }
+  if (Array.isArray(value)) {
+    return arrayLiteralType(value);
+  }
+  return typeof value === "object" ? objectLiteralType(value) : UNKNOWN_TYPE;
+}

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

@@ -0,0 +1,20 @@
+/** Builds the name for the `count`-th use of `name` (2, 3…). */
+export type NumberedName = (name: string, count: number) => string;
+
+/**
+ * Names made unique, in order: the first use of a name keeps it, each repeat gets the lowest
+ * number from 2 whose name is not written anywhere in the list.
+ */
+export function withNumberedRepeats(names: readonly string[], numbered: NumberedName): string[] {
+  const written = new Set(names);
+  const taken = new Set<string>();
+  return names.map((name) => {
+    let unique = name;
+    for (let count = 2; taken.has(unique); count += 1) {
+      const candidate = numbered(name, count);
+      unique = written.has(candidate) ? unique : candidate;
+    }
+    taken.add(unique);
+    return unique;
+  });
+}

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

@@ -0,0 +1,211 @@
+import { createRef } from "../../../domain/openapi/json-pointer.js";
+import type { RefResolver } from "../schema/schema-context.js";
+import { isJsonObject } from "./generated-shape.js";
+import {
+  leadingSegmentsOf,
+  type RefPointer,
+  refPointerOf,
+  startsInSchema,
+} from "./pointer-walk.js";
+
+/**
+ * Where the generator types the node a `$ref` points at: the location path it passes down, which
+ * also names the node's `--enum` declaration and `--enum-values` array. A target written inline
+ * (ADR-026) is typed there, so it shares the generator's enum instead of declaring a second one
+ * named after the pointer: two TypeScript enums with the same members are not assignable.
+ *
+ * The path follows the generator: `properties` is skipped; `allOf/N`, `items`, `prefixItems/N`,
+ * `patternProperties/P` and `additionalProperties` type their schema at the parent's location;
+ * the `schema` of a parameter, header or media type is typed at the container's; a positional
+ * parameter is named by `in` and `name`. A `$ref` crossed on the way continues at its target's
+ * location. A node under a schema keyword the generator does not type (`definitions/A`, `not`) is
+ * typed nowhere else, so it keeps its pointer as its location.
+ */
+
+export interface GeneratedLocation {
+  readonly path: string;
+  /** The node is an `additionalProperties` value, as `transformNested` is told. */
+  readonly isFromAdditionalProperties: boolean;
+}
+
+interface LocationWalk {
+  readonly path: readonly string[];
+  readonly node: unknown;
+  readonly isSchema: boolean;
+  readonly isFromAdditionalProperties: boolean;
+}
+
+/** One step: the segments it adds to the path, the node it moves to, the segments it reads. */
+interface Step {
+  readonly path: readonly string[];
+  readonly child: unknown;
+  readonly length: 1 | 2;
+  readonly isSchema: boolean;
+  readonly isFromAdditionalProperties?: boolean;
+}
+
+/** Keywords followed by a name or position whose schema is typed at the parent's location. */
+const PARENT_LOCATION_PAIRS: ReadonlySet<string> = new Set([
+  "allOf",
+  "prefixItems",
+  "patternProperties",
+]);
+/** Keywords whose schema is typed at the parent's location as a record value. */
+const RECORD_VALUE_KEYWORDS: ReadonlySet<string> = new Set([
+  "additionalProperties",
+  "unevaluatedProperties",
+]);
+/** Keywords followed by a name or position that both stay in the location. */
+const KEPT_PAIRS: ReadonlySet<string> = new Set(["anyOf", "oneOf", "$defs"]);
+/** The other schema keywords the generator types: at the parent's location. */
+const PARENT_LOCATION_KEYWORDS: ReadonlySet<string> = new Set(["items", ...RECORD_VALUE_KEYWORDS]);
+const INDEX_RE = /^\d+$/;
+
+function childOf(node: unknown, segment: string | undefined): unknown {
+  return (isJsonObject(node) || Array.isArray(node)) && segment !== undefined
+    ? (node as Readonly<Record<string, unknown>>)[segment]
+    : undefined;
+}
+
+function pairStep(value: unknown, next: string | undefined, path: readonly string[]): Step {
+  return { path, child: childOf(value, next), length: 2, isSchema: true };
+}
+
+/** The step through a schema keyword; null for a keyword the generator does not type. */
+function schemaStep(node: unknown, segment: string, next: string | undefined): Step | null {
+  const value = childOf(node, segment);
+  const named = next === undefined ? [] : [next];
+  if (segment === "properties") {
+    return pairStep(value, next, named);
+  }
+  if (PARENT_LOCATION_PAIRS.has(segment) || (segment === "items" && Array.isArray(value))) {
+    return pairStep(value, next, []);
+  }
+  if (KEPT_PAIRS.has(segment)) {
+    return pairStep(value, next, [segment, ...named]);
+  }
+  if (!PARENT_LOCATION_KEYWORDS.has(segment)) {
+    return null;
+  }
+  const isRecordValue = RECORD_VALUE_KEYWORDS.has(segment);
+  return {
+    path: [],
+    child: value,
+    length: 1,
+    isSchema: true,
+    isFromAdditionalProperties: isRecordValue,
+  };
+}
+
+/** A path item's own parameters sit under one more `parameters` segment (`pathItemType`). */
+function isPathItem(path: readonly string[]): boolean {
+  const [root, section] = path;
+  return (
+    (path.length === 2 && (root === "paths" || root === "webhooks")) ||
+    (path.length === 3 && root === "components" && section === "pathItems")
+  );
+}
+
+/** `parameters/N`: the parameter is named by `in` and `name` (a `$ref` one is crossed later). */
+function parameterStep(walk: LocationWalk, next: string): Step {
+  const entry = childOf(childOf(walk.node, "parameters"), next);
+  const where = isJsonObject(entry) ? [String(entry.in), String(entry.name)] : [];
+  const prefix = isPathItem(walk.path) ? ["parameters"] : [];
+  return { path: [...prefix, "parameters", ...where], child: entry, length: 2, isSchema: false };
+}
+
+function documentStep(walk: LocationWalk, segments: readonly string[], index: number): Step {
+  const segment = segments[index] as string;
+  const next = segments[index + 1];
+  const value = childOf(walk.node, segment);
+  if (segment === "schema") {
+    return { path: [], child: value, length: 1, isSchema: true };
+  }
+  if (segment === "parameters" && next !== undefined && INDEX_RE.test(next)) {
+    return parameterStep(walk, next);
+  }
+  // A header's `content` entries are typed at `headers/<name>/<media type>` (`headerType`).
+  if (segment === "content" && segments[index - 2] === "headers") {
+    const path = next === undefined ? [] : [next];
+    return { path, child: childOf(value, next), length: 2, isSchema: false };
+  }
+  return { path: [segment], child: value, length: 1, isSchema: false };
+}
+
+function stepAt(walk: LocationWalk, pointer: RefPointer, index: number): Step | null {
+  const { segments } = pointer;
+  const segment = segments[index] as string;
+  if (index < leadingSegmentsOf(pointer)) {
+    const child = childOf(walk.node, segment);
+    return { path: [segment], child, length: 1, isSchema: startsInSchema(pointer) };
+  }
+  return walk.isSchema
+    ? schemaStep(walk.node, segment, segments[index + 1])
+    : documentStep(walk, segments, index);
+}
+
+function refOf(node: unknown): string | null {
+  return isJsonObject(node) && typeof node.$ref === "string" ? node.$ref : null;
+}
+
+/**
+ * The walk at a crossed `$ref`'s target, through `$ref`s to `$ref`s; null where the target has
+ * no generated location. A cycle of `$ref`s has no node.
+ */
+function crossed(
+  walk: LocationWalk,
+  ref: string,
+  refs: RefResolver,
+  seen: readonly string[],
+): LocationWalk | null {
+  if (seen.includes(ref)) {
+    return { ...walk, node: undefined };
+  }
+  const target = walkTo(ref, refs, seen);
+  const inner = refOf(target?.node);
+  return target === null || inner === null ? target : crossed(target, inner, refs, [...seen, ref]);
+}
+
+function walkTo(ref: string, refs: RefResolver, seen: readonly string[]): LocationWalk | null {
+  const pointer = refPointerOf(ref);
+  if (pointer === null || seen.includes(ref)) {
+    return null;
+  }
+  const root = pointer.rootSegment;
+  let walk: LocationWalk = {
+    path: [root],
+    node: refs.resolve(`#/${root}`),
+    isSchema: false,
+    isFromAdditionalProperties: false,
+  };
+  for (let index = 0; index < pointer.segments.length; ) {
+    const step = stepAt(walk, pointer, index);
+    if (step === null) {
+      return null;
+    }
+    index += step.length;
+    walk = {
+      path: [...walk.path, ...step.path],
+      node: step.child,
+      isSchema: step.isSchema,
+      isFromAdditionalProperties: step.isFromAdditionalProperties === true,
+    };
+    const inner = refOf(walk.node);
+    const target = inner !== null && index < pointer.segments.length;
+    const next = target ? crossed(walk, inner, refs, [...seen, ref]) : walk;
+    if (next === null) {
+      return null;
+    }
+    walk = next;
+  }
+  return walk;
+}
+
+/** The location the generator types the node at `ref` with; see the module comment. */
+export function generatedLocationOf(ref: string, refs: RefResolver): GeneratedLocation {
+  const walk = walkTo(ref, refs, []);
+  return {
+    path: walk === null ? ref : createRef(walk.path),
+    isFromAdditionalProperties: walk?.isFromAdditionalProperties ?? false,
+  };
+}