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

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

@@ -1,5 +1,19 @@
 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 {
+  hasKeptProperties,
+  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 +22,27 @@ import type { RefResolver, SchemaOptions } from "../schema/schema-context.js";
  */
 
 export type GeneratedMember =
-  | { readonly kind: "property"; readonly node: unknown; readonly isOptional: boolean }
-  /** An index signature; `node` is undefined when its value type is `unknown`. */
-  | { readonly kind: "index"; readonly node: unknown }
+  | {
+      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`. `isOtherType`: the
+   * type read is not the type of the node the key names (`indexMember`).
+   */
+  | {
+      readonly kind: "index";
+      readonly node: unknown;
+      readonly location: string | undefined;
+      readonly isOtherType: boolean;
+    }
   | { 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 +50,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 +100,71 @@ 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;
-  if (isJsonObject(patterns) && Object.keys(patterns).length > 0) {
-    return OPAQUE;
+/** `additionalProperties: true` or `{}` (also as a pattern's schema): a value of `unknown`. */
+function isUnknownValue(value: unknown): boolean {
+  return value === true || (isJsonObject(value) && Object.keys(value).length === 0);
+}
+
+/** The value schemas of an index signature none of whose values is `unknown`, located. */
+function typedIndexValues(owner: LocatedNode & { node: JsonObject }): LocatedNode[] {
+  const { additionalProperties: values, patternProperties: patterns } = owner.node;
+  const located: LocatedNode[] = [];
+  if (isJsonObject(values)) {
+    located.push({ node: values, location: childLocation(owner.location, "additionalProperties") });
   }
-  if (isJsonObject(values) && Object.keys(values).length > 0) {
-    return { kind: "index", node: values };
+  for (const [pattern, node] of isJsonObject(patterns) ? Object.entries(patterns) : []) {
+    located.push({ node, location: childLocation(owner.location, "patternProperties", pattern) });
   }
-  const isImplicit = values === true || (isJsonObject(values) && Object.keys(values).length === 0);
-  return isImplicit || (!values && options.additionalProperties)
-    ? { kind: "index", node: undefined }
-    : null;
+  return located;
 }
 
-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;
+/**
+ * The index signature of an object schema, or null without one. Its type is the union of its
+ * value schemas' types (`unknown` if one is `unknown`); a union of several counts as opaque. It
+ * also holds the kept property types (`withPropertyTypes`), and a key that names a property
+ * `--exclude-deprecated` left out reads it instead of that property: both are `isOtherType`.
+ */
+function indexMember(
+  owner: LocatedNode & { node: JsonObject },
+  isExcludedKey: boolean,
+  input: MemberInput,
+): GeneratedMember | null {
+  const { additionalProperties: values, patternProperties: patterns } = owner.node;
+  const patternValues = isJsonObject(patterns) ? Object.values(patterns) : [];
+  const isUnknown =
+    isUnknownValue(values) ||
+    patternValues.some(isUnknownValue) ||
+    (!values && input.options.additionalProperties);
+  if (isUnknown) {
+    return { kind: "index", node: undefined, location: undefined, isOtherType: isExcludedKey };
+  }
+  const typed = typedIndexValues(owner);
+  const [only] = typed;
+  if (only === undefined || typed.length > 1) {
+    return only === undefined ? null : OPAQUE;
+  }
+  const isOtherType = isExcludedKey || hasKeptProperties(owner.node, input.options, input.refs);
+  return { kind: "index", ...only, isOtherType };
 }
 
-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) };
+  const isExcludedKey =
+    Object.hasOwn(properties, key) && isExcludedProperty(properties[key], options, input.refs);
+  if (Object.hasOwn(properties, key) && !isExcludedKey) {
+    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 +173,23 @@ function objectMember(node: JsonObject, key: string, options: SchemaOptions): Ge
     return OPAQUE;
   }
   return hasObjectKeywords(node)
-    ? (indexMember(node, options) ?? MISSING)
+    ? (indexMember(owner, isExcludedKey, input) ?? 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 +205,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 +219,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 +249,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 +298,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);
+}

package/src/application/transform/ref-pointer/original-index.ts

@@ -1,11 +1,15 @@
 import type { RefResolver, SchemaOptions } from "../schema/schema-context.js";
-import { followRefs, generatedMember, isJsonObject } from "./generated-shape.js";
+import { generatedMember } from "./generated-shape.js";
+import { childLocation, followLocated, isJsonObject } from "./located-node.js";
 import {
+  type ContentForm,
+  headerParameterContentForm,
+  isExcludedOperation,
   isOptionalHeader,
   isOptionalRequestBody,
   isParameterList,
   isTypedAsSchema,
-  leadingNode,
+  leadingLocated,
   leadingSegmentsOf,
   type RefPointer,
   startsInSchema,
@@ -14,14 +18,18 @@ import {
 /**
  * Whether the type the original wrote for a `$ref` (`refType`: every segment indexed by name,
  * `properties` skipped) surely fails to compile. It walks the document as TypeScript walks the
- * generated types and answers true only where TypeScript reports an error for sure; where the
- * answer depends on a shape it does not model, it answers false, so that output stays as it was.
+ * generated types and answers true only where TypeScript reports an error for sure, or where the
+ * type compiles but is read through an index signature that is not the target's type alone
+ * (`isOtherType`); where the answer depends on a shape it does not model, it answers false, so
+ * that output stays as it was.
  */
 
 type Step = "fails" | "compiles" | "continue";
 
 interface OriginalWalk {
   readonly node: unknown;
+  /** The node's JSON Pointer (`LocatedNode`). */
+  readonly location: string | undefined;
   readonly isSchema: boolean;
 }
 
@@ -35,57 +43,135 @@ function schemaStep(walk: OriginalWalk, segment: string, isLast: boolean, input:
   if (segment === "properties") {
     return { step: "continue" as Step, walk };
   }
-  const member = generatedMember(walk.node, segment, input.options, input.refs);
-  if (member.kind === "missing") {
+  const member = generatedMember(walk, segment, input.options, input.refs);
+  // Such an index signature compiles, but its type is not the target's alone.
+  if (member.kind === "missing" || (member.kind === "index" && member.isOtherType)) {
     return { step: "fails" as Step, walk };
   }
   if (member.kind === "opaque") {
     return { step: "compiles" as Step, walk };
   }
   const isAbsentValue = member.kind === "index" && member.node === undefined;
-  const isUnsafe = member.kind === "property" ? member.isOptional : isAbsentValue;
+  const isUnsafe =
+    member.kind === "property" ? member.isOptional || member.isMarked : isAbsentValue;
   return {
     step: (isUnsafe && !isLast ? "fails" : "continue") as Step,
-    walk: { ...walk, node: member.node },
+    walk: { ...walk, node: member.node, location: member.location },
   };
 }
 
 function containerStep(walk: OriginalWalk, index: number, input: WalkInput) {
   const segment = input.pointer.segments[index] as string;
   const isLast = index === input.pointer.segments.length - 1;
+  if (isExcludedOperation(input.pointer, index, walk.node, input)) {
+    return { step: "fails" as Step, walk };
+  }
   const isOptional =
     (segment === "requestBody" && isOptionalRequestBody(walk.node, input.refs)) ||
     isOptionalHeader(input.pointer, index, walk.node);
   if (isOptional && !isLast) {
     return { step: "fails" as Step, walk };
   }
-  const child = isJsonObject(walk.node) ? followRefs(walk.node[segment], input.refs) : undefined;
+  const child = followLocated(
+    {
+      node: isJsonObject(walk.node) ? walk.node[segment] : undefined,
+      location: childLocation(walk.location, segment),
+    },
+    input.refs,
+  );
   return {
-    step: (child === undefined ? "compiles" : "continue") as Step,
-    walk: { ...walk, node: child },
+    step: (child.node === undefined ? "compiles" : "continue") as Step,
+    walk: { ...walk, ...child },
   };
 }
 
+/** The schema of the first media type of a `content` map, `$ref`s followed. */
+function firstMediaTypeSchema(walk: OriginalWalk, refs: RefResolver): OriginalWalk | null {
+  const content = isJsonObject(walk.node) ? walk.node.content : undefined;
+  if (!isJsonObject(content)) {
+    return null;
+  }
+  const [mediaType] = Object.keys(content);
+  if (mediaType === undefined) {
+    return null;
+  }
+  const location = childLocation(childLocation(walk.location, "content"), mediaType);
+  const entry = followLocated({ node: content[mediaType], location }, refs);
+  return ownSchema({ ...entry, isSchema: false }, refs);
+}
+
+/** The schema a header or parameter is typed by, `$ref`s followed. */
+function ownSchema(walk: OriginalWalk, refs: RefResolver): OriginalWalk {
+  const schema = isJsonObject(walk.node) ? walk.node.schema : undefined;
+  const location = childLocation(walk.location, "schema");
+  return { ...followLocated({ node: schema, location }, refs), isSchema: true };
+}
+
+/** The schema whose type a header or parameter is, when not its media type members. */
+function contentSchema(
+  walk: OriginalWalk,
+  form: Exclude<ContentForm, "media-type-members">,
+  refs: RefResolver,
+): OriginalWalk | null {
+  switch (form) {
+    case "first-media-type":
+      return firstMediaTypeSchema(walk, refs);
+    case "schema":
+      return ownSchema(walk, refs);
+    case "string":
+      return null;
+  }
+}
+
+/**
+ * The original indexes the `content` of a header or parameter by name. The media type members
+ * have no `content` unless a media type is named so, and `string` and `unknown` (no media type)
+ * have none; the schema of the first media type, or the `schema` next to `content`, is walked on.
+ */
+function contentStep(walk: OriginalWalk, form: ContentForm, isLast: boolean, input: WalkInput) {
+  const content = isJsonObject(walk.node) ? walk.node.content : undefined;
+  if (form === "media-type-members") {
+    const hasMember = isJsonObject(content) && Object.hasOwn(content, "content");
+    return { step: (hasMember ? "compiles" : "fails") as Step, walk };
+  }
+  const schema = contentSchema(walk, form, input.refs);
+  return schema === null
+    ? { step: "fails" as Step, walk }
+    : schemaStep(schema, "content", isLast, input);
+}
+
+/**
+ * A step outside a schema: a header's or parameter's `content`, a schema's container, or another.
+ */
+function documentStep(walk: OriginalWalk, index: number, input: WalkInput) {
+  const segment = input.pointer.segments[index] as string;
+  const isLast = index === input.pointer.segments.length - 1;
+  const form = headerParameterContentForm(input.pointer, index, walk.node, input.options);
+  if (form !== null) {
+    return contentStep(walk, form, isLast, input);
+  }
+  if (isTypedAsSchema(input.pointer, index) && isJsonObject(walk.node)) {
+    // The container's type is its schema's type: the segment indexes that type.
+    return schemaStep(ownSchema(walk, input.refs), segment, isLast, input);
+  }
+  return containerStep(walk, index, input);
+}
+
 /** True when the original type of the `$ref` does not compile for sure. */
 export function originalIndexFails(input: WalkInput): boolean {
   const { segments } = input.pointer;
   let walk: OriginalWalk = {
-    node: leadingNode(input.pointer, input.refs),
+    ...leadingLocated(input.pointer, input.refs),
     isSchema: startsInSchema(input.pointer),
   };
   for (let index = leadingSegmentsOf(input.pointer); index < segments.length; index++) {
-    const segment = segments[index] as string;
-    const isLast = index === segments.length - 1;
     if (!walk.isSchema && isParameterList(input.pointer, index)) {
       return true;
     }
-    if (!walk.isSchema && isTypedAsSchema(input.pointer, index) && isJsonObject(walk.node)) {
-      // The container's type is its schema's type: the segment indexes that type.
-      walk = { node: followRefs(walk.node.schema, input.refs), isSchema: true };
-    }
+    const isLast = index === segments.length - 1;
     const result = walk.isSchema
-      ? schemaStep(walk, segment, isLast, input)
-      : containerStep(walk, index, input);
+      ? schemaStep(walk, segments[index] as string, isLast, input)
+      : documentStep(walk, index, input);
     if (result.step !== "continue") {
       return result.step === "fails";
     }

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

@@ -4,8 +4,8 @@ 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";
-import { isJsonObject } from "./generated-shape.js";
 import { hasInlineCycle } from "./inline-cycles.js";
+import { isJsonObject } from "./located-node.js";
 import { originalIndexFails } from "./original-index.js";
 import { leadingSegmentsOf, pointerNode, type RefPointer, refPointerOf } from "./pointer-walk.js";
 import { typedWalk } from "./typed-walk.js";

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

@@ -1,6 +1,15 @@
-import { parseRefPointer } from "../../../domain/openapi/json-pointer.js";
-import type { RefResolver } from "../schema/schema-context.js";
-import { followRefs, isJsonObject } from "./generated-shape.js";
+import { placeOf } from "../../../domain/openapi/document-places.js";
+import { parseRefPointer, ROOT_POINTER } from "../../../domain/openapi/json-pointer.js";
+import { QUERYSTRING_LOCATION } from "../../../domain/openapi/parameter-object.js";
+import { FIX } from "../../../domain/output-fixes.js";
+import type { RefResolver, SchemaOptions } from "../schema/schema-context.js";
+import {
+  childLocation,
+  followLocated,
+  followRefs,
+  isJsonObject,
+  type LocatedNode,
+} from "./located-node.js";
 
 /** The parts of a `$ref` pointer that both the original and the new types walk. */
 
@@ -27,13 +36,18 @@ export function refPointerOf(ref: string): RefPointer | null {
   return rootSegment === undefined ? null : { rootSegment, segments };
 }
 
-/** The document node at the end of the leading segments, `$ref`s followed. */
-export function leadingNode(pointer: RefPointer, refs: RefResolver): unknown {
-  let node = refs.resolve(`#/${pointer.rootSegment}`);
+/** The document node at the end of the leading segments, `$ref`s followed, with its location. */
+export function leadingLocated(pointer: RefPointer, refs: RefResolver): LocatedNode {
+  let located: LocatedNode = {
+    node: refs.resolve(`#/${pointer.rootSegment}`),
+    location: childLocation(ROOT_POINTER, pointer.rootSegment),
+  };
   for (const segment of pointer.segments.slice(0, leadingSegmentsOf(pointer))) {
-    node = isJsonObject(node) ? followRefs(node[segment], refs) : undefined;
+    const { node, location } = located;
+    const child = isJsonObject(node) ? node[segment] : undefined;
+    located = followLocated({ node: child, location: childLocation(location, segment) }, refs);
   }
-  return node;
+  return located;
 }
 
 /** The node at the whole pointer, without following a `$ref` at its end. */
@@ -62,6 +76,47 @@ export function isTypedAsSchema(pointer: RefPointer, index: number): boolean {
   return owner === "content" || owner === "headers" || isComponentParameter;
 }
 
+/**
+ * How the generated type of a header or component parameter holds its `content` (header.ts,
+ * parameter.ts): one member per media type, the type of the first media type, `string` (a
+ * parameter without the `parameter-header-content` fix), or not at all (a `schema` wins).
+ */
+export type ContentForm = "media-type-members" | "first-media-type" | "string" | "schema";
+
+/**
+ * The form of the `content` at `index` when it belongs to a header or a component parameter; null
+ * for any other segment. An `in: querystring` parameter is typed by its `content` even next to a
+ * `schema`.
+ */
+export function headerParameterContentForm(
+  pointer: RefPointer,
+  index: number,
+  owner: unknown,
+  options: SchemaOptions,
+): ContentForm | null {
+  const isHeader = pointer.segments[index - 2] === "headers";
+  const isComponentParameter =
+    pointer.rootSegment === "components" && index === 2 && pointer.segments[0] === "parameters";
+  const isOwnContent = pointer.segments[index] === "content" && (isHeader || isComponentParameter);
+  if (!isOwnContent || !isJsonObject(owner)) {
+    return null;
+  }
+  const isFixed = options.fixes.has(FIX.PARAMETER_HEADER_CONTENT);
+  if (isHeader) {
+    if (owner.schema) {
+      return "schema";
+    }
+    return isFixed ? "first-media-type" : "media-type-members";
+  }
+  if (owner.in === QUERYSTRING_LOCATION) {
+    return "first-media-type";
+  }
+  if (owner.schema !== undefined) {
+    return "schema";
+  }
+  return isFixed ? "first-media-type" : "string";
+}
+
 /**
  * Whether the segment at `index` is an operation's or path item's `parameters` list, indexed by
  * position next. The generated type groups parameters by `in` (`query`, `path`), so it has no
@@ -86,6 +141,25 @@ export function isOptionalHeader(pointer: RefPointer, index: number, headers: un
   return isJsonObject(header) && header.$ref === undefined && header.required !== true;
 }
 
+/**
+ * Whether the segment at `index` names an operation that `--exclude-deprecated` leaves out: the
+ * path item types it `never`, which has no member to index (`isIncludedOperation`).
+ */
+export function isExcludedOperation(
+  pointer: RefPointer,
+  index: number,
+  pathItem: unknown,
+  input: { readonly options: SchemaOptions; readonly refs: RefResolver },
+): boolean {
+  const segments = [pointer.rootSegment, ...pointer.segments.slice(0, index + 1)];
+  if (!input.options.excludeDeprecated || placeOf(segments) !== "operation") {
+    return false;
+  }
+  const segment = pointer.segments[index] as string;
+  const operation = isJsonObject(pathItem) ? followRefs(pathItem[segment], input.refs) : undefined;
+  return isJsonObject(operation) && Boolean(operation.deprecated);
+}
+
 /** A `requestBody` the operation does not mark `required` is an optional member. */
 export function isOptionalRequestBody(container: unknown, refs: RefResolver): boolean {
   if (!isJsonObject(container) || container.requestBody === undefined) {