openapi-typesafe 0.0.0 → 1.0.0-rc.0

package/src/domain/openapi/alias-expansion.ts

@@ -0,0 +1,72 @@
+/**
+ * YAML aliases (`*name`) make the parsed document share objects. A "billion laughs" document,
+ * where each level refers to the previous one ten times, parses into a few hundred objects that
+ * every walk over the document (Redocly's resolver, the generator) visits as 10^9 nodes: the run
+ * took minutes and ended with "RangeError: Set maximum size exceeded" (pre-beta test plan 10.2).
+ * A document is refused when its aliases expand it far beyond what it stores.
+ */
+
+/** Expansion below this many nodes is allowed whatever the ratio: large real documents pass. */
+export const ALIAS_EXPANSION_MIN_NODES = 1_000_000;
+/** Real documents reuse anchors a few times; a bomb multiplies its size by orders of magnitude. */
+export const ALIAS_EXPANSION_MAX_RATIO = 100;
+
+export interface NodeCounts {
+  /** Nodes of the document as written: each object once, with its entries. */
+  readonly stored: number;
+  /** Nodes a walk visits when it follows every shared object again. */
+  readonly expanded: number;
+}
+
+function childrenOf(node: object): unknown[] {
+  return Array.isArray(node) ? node : Object.values(node);
+}
+
+function isContainer(value: unknown): value is object {
+  return typeof value === "object" && value !== null;
+}
+
+/** The expanded size of `node`, whose container children are all sized (or in a cycle). */
+function sizeOf(node: object, sizes: ReadonlyMap<object, number>): number {
+  return childrenOf(node).reduce<number>(
+    (total, child) => total + (isContainer(child) ? (sizes.get(child) ?? 1) : 1),
+    1,
+  );
+}
+
+/**
+ * Count stored and expanded nodes without recursion (documents can be thousands of levels deep)
+ * and without expanding: each shared object is sized once. A cycle counts its back edge once.
+ */
+export function countNodes(root: unknown): NodeCounts {
+  if (!isContainer(root)) {
+    return { stored: 1, expanded: 1 };
+  }
+  const sizes = new Map<object, number>();
+  const entered = new Set<object>();
+  const stack: object[] = [root];
+  while (stack.length > 0) {
+    const node = stack[stack.length - 1] as object;
+    const isFirstVisit = !entered.has(node);
+    entered.add(node);
+    const pending = isFirstVisit
+      ? childrenOf(node).filter((child) => isContainer(child) && !entered.has(child))
+      : [];
+    if (pending.length > 0) {
+      stack.push(...(pending as object[]));
+      continue;
+    }
+    stack.pop();
+    sizes.set(node, sizeOf(node, sizes));
+  }
+  let stored = 0;
+  for (const node of sizes.keys()) {
+    stored += 1 + childrenOf(node).filter((child) => !isContainer(child)).length;
+  }
+  return { stored, expanded: sizes.get(root) ?? 1 };
+}
+
+/** Whether the aliases of a parsed document expand it beyond the limits above. */
+export function isAliasExpansionExcessive({ stored, expanded }: NodeCounts): boolean {
+  return expanded > Math.max(ALIAS_EXPANSION_MIN_NODES, stored * ALIAS_EXPANSION_MAX_RATIO);
+}

package/src/domain/openapi/binary-content.ts

@@ -0,0 +1,74 @@
+import type { SchemaObject } from "./schema-object.js";
+
+/**
+ * Which string schemas describe raw binary data, following "Working with Binary Data" of the
+ * OpenAPI specification (3.1): `format: binary` in 3.0, a `contentMediaType` without a
+ * `contentEncoding` in 3.1. `--binary-as-blob` types these as `Blob`.
+ * https://spec.openapis.org/oas/v3.1.1.html#working-with-binary-data
+ */
+
+/** The OpenAPI 3.0 format of unencoded octets (`byte` is base64 text). */
+const BINARY_FORMAT = "binary";
+
+/** The top-level media type whose contents are always text (RFC 2046). */
+const TEXT_TOP_LEVEL_TYPE = "text";
+
+/** The top-level media type of the text formats in `TEXT_APPLICATION_SUBTYPES`. */
+const APPLICATION_TOP_LEVEL_TYPE = "application";
+
+/**
+ * Text syntaxes, as a subtype (`application/json`) or a structured syntax suffix
+ * (`application/problem+json`, `image/svg+xml`; RFC 6839, RFC 9512).
+ */
+const TEXT_STRUCTURED_SYNTAXES: ReadonlySet<string> = new Set(["json", "xml", "yaml"]);
+
+/** Other text formats under `application/`, registered or in common use. */
+const TEXT_APPLICATION_SUBTYPES: ReadonlySet<string> = new Set([
+  "ecmascript",
+  "graphql",
+  "javascript",
+  "json-seq",
+  "jsonl",
+  "sql",
+  "x-ndjson",
+  "x-www-form-urlencoded",
+  "x-yaml",
+]);
+
+const PARAMETER_SEPARATOR = ";";
+const SUBTYPE_SEPARATOR = "/";
+const SUFFIX_SEPARATOR = "+";
+
+/**
+ * Whether a media type's contents are text, so a string schema with it holds the text itself.
+ * Parameters (`; charset=utf-8`) and case are ignored; a value without a subtype is not text.
+ */
+export function isTextualMediaType(mediaType: string): boolean {
+  const essence = (mediaType.split(PARAMETER_SEPARATOR)[0] ?? "").trim().toLowerCase();
+  const [topLevelType, subtype] = essence.split(SUBTYPE_SEPARATOR);
+  if (topLevelType === undefined || subtype === undefined) {
+    return false;
+  }
+  if (topLevelType === TEXT_TOP_LEVEL_TYPE) {
+    return true;
+  }
+  const suffix = subtype.slice(subtype.lastIndexOf(SUFFIX_SEPARATOR) + 1);
+  if (TEXT_STRUCTURED_SYNTAXES.has(subtype) || TEXT_STRUCTURED_SYNTAXES.has(suffix)) {
+    return true;
+  }
+  return topLevelType === APPLICATION_TOP_LEVEL_TYPE && TEXT_APPLICATION_SUBTYPES.has(subtype);
+}
+
+/**
+ * Whether a schema describes raw (unencoded) binary data. Any `contentEncoding` means the value
+ * is encoded text, so it wins over `format: binary`.
+ */
+export function isRawBinarySchema(schema: SchemaObject): boolean {
+  if (schema.contentEncoding !== undefined) {
+    return false;
+  }
+  if (schema.format === BINARY_FORMAT) {
+    return true;
+  }
+  return schema.contentMediaType !== undefined && !isTextualMediaType(schema.contentMediaType);
+}

package/src/domain/openapi/components-object.ts

@@ -0,0 +1,52 @@
+import { MEDIA_TYPES_COMPONENT_KIND } from "./media-type-object.js";
+
+/**
+ * The component maps the generator always writes, in output order (OpenAPI 3.1 §4.8.7); a kind the
+ * document lacks is `never`.
+ */
+export const COMPONENT_KINDS = Object.freeze([
+  "schemas",
+  "responses",
+  "parameters",
+  "requestBodies",
+  "headers",
+  "pathItems",
+] as const);
+
+/**
+ * OpenAPI 3.2 component maps, written after `COMPONENT_KINDS` and only when the document has them,
+ * so documents without them keep their output (ADR-020).
+ */
+export const DECLARED_COMPONENT_KINDS = Object.freeze([MEDIA_TYPES_COMPONENT_KIND] as const);
+
+export type ComponentKind =
+  | (typeof COMPONENT_KINDS)[number]
+  | (typeof DECLARED_COMPONENT_KINDS)[number];
+
+/** Components by kind and name; entries are read by each kind's transformer. */
+export type ComponentsObject = {
+  readonly [kind in ComponentKind]?: Readonly<Record<string, unknown>>;
+};
+
+/** `requestBodies` → `requestBody`; other kinds drop the final `s`. */
+export function singularizeComponentKind(kind: ComponentKind | `x-${string}`): string {
+  return kind === "requestBodies" ? "requestBody" : kind.slice(0, -1);
+}
+
+/**
+ * Whether a schema is an enum that `--enum` turns into a TypeScript enum. With `--root-types`
+ * such schemas get no root alias, because the enum is already exported under that name.
+ */
+export function isEnumSchema(schema: unknown): boolean {
+  if (typeof schema !== "object" || schema === null || Array.isArray(schema)) {
+    return false;
+  }
+  const record = schema as Record<string, unknown>;
+  return (
+    "enum" in record &&
+    Array.isArray(record.enum) &&
+    (!("type" in record) || record.type !== "object") &&
+    !("properties" in record) &&
+    !("additionalProperties" in record)
+  );
+}

package/src/domain/openapi/document-object.ts

@@ -0,0 +1,12 @@
+import type { ComponentsObject } from "./components-object.js";
+import type { PathsObject } from "./path-item-object.js";
+import type { Schema } from "./schema-object.js";
+
+/** The parts of an OpenAPI document that get a root type (OpenAPI 3.1 §4.8.1). */
+export interface DocumentObject {
+  readonly paths?: PathsObject;
+  readonly webhooks?: PathsObject;
+  readonly components?: ComponentsObject;
+  /** JSON Schema definitions at the document root: named subschemas. */
+  readonly $defs?: Readonly<Record<string, Schema>>;
+}

package/src/domain/openapi/header-object.ts

@@ -0,0 +1,9 @@
+import type { ContentMap } from "./media-type-object.js";
+import type { Schema } from "./schema-object.js";
+
+/** The parts of a Header Object the generator reads (OpenAPI 3.1 §4.8.21). */
+export interface HeaderObject {
+  readonly required?: boolean;
+  readonly schema?: Schema;
+  readonly content?: ContentMap;
+}

package/src/domain/openapi/json-pointer.ts

@@ -0,0 +1,46 @@
+/**
+ * The JSON Pointer of a `$ref` as path segments, with the semantics of Redocly's `parseRef`, which
+ * the original generator used: the part after the first `#/`, split at `/`, each segment unescaped
+ * (`~1` → `/`, `~0` → `~`, then percent-decoding), and empty segments dropped.
+ *
+ * Throws URIError for a malformed percent escape, as the original does.
+ */
+export function parseRefPointer(ref: string): string[] {
+  const [, pointer = ""] = ref.split("#/");
+  return pointer
+    .split("/")
+    .map(unescapePointerSegment)
+    .filter((segment) => segment.length > 0);
+}
+
+function unescapePointerSegment(segment: string): string {
+  return decodeURIComponent(segment.replaceAll("~1", "/").replaceAll("~0", "~"));
+}
+
+/**
+ * Escape one segment for a JSON Pointer in a `$ref` fragment: `~` → `~0`, `/` → `~1`, and `%` →
+ * `%25`, because reading a pointer back percent-decodes it. The original did not escape `%`, so a
+ * name like `50%` threw URIError and `a%2Fb` read back as `a/b` (upstream #2251, #2828).
+ */
+export function escapePointerSegment(segment: string): string {
+  return segment.replaceAll("~", "~0").replaceAll("/", "~1").replaceAll("%", "%25");
+}
+
+/**
+ * Join parts into a local `$ref` (the original `createRef`). Empty parts are skipped. A part that
+ * is itself a `$ref` contributes its segments; any other part is one segment.
+ */
+export function createRef(parts: readonly (string | number | null | undefined)[]): string {
+  let ref = "#";
+  for (const part of parts) {
+    if (part === undefined || part === null || part === "") {
+      continue;
+    }
+    const text = String(part);
+    const segments = parseRefPointer(text);
+    for (const segment of segments.length > 0 ? segments : [text]) {
+      ref += `/${escapePointerSegment(segment)}`;
+    }
+  }
+  return ref;
+}

package/src/domain/openapi/media-type-object.ts

@@ -0,0 +1,26 @@
+import { parseRefPointer } from "./json-pointer.js";
+import type { ReferenceSchema, Schema } from "./schema-object.js";
+
+/** The parts of a Media Type Object the generator reads (OpenAPI 3.2 §4.8.14). */
+export interface MediaTypeObject {
+  /** The complete content. */
+  readonly schema?: Schema;
+  /** Each item of a sequential media type such as `application/jsonl` (OpenAPI 3.2). */
+  readonly itemSchema?: Schema;
+}
+
+/** A `content` map: media type name to a Media Type Object or a `$ref` to one. */
+export type ContentMap = Readonly<Record<string, MediaTypeObject | ReferenceSchema>>;
+
+const COMPONENTS_SEGMENT = "components";
+/** The OpenAPI 3.2 component map of reusable Media Type Objects. */
+export const MEDIA_TYPES_COMPONENT_KIND = "mediaTypes";
+
+/**
+ * Whether a `content` entry's `$ref` points into `components.mediaTypes` (OpenAPI 3.2). Other
+ * `$ref`s in `content` keep the output they had before 3.2 (ADR-020).
+ */
+export function isMediaTypeComponentRef(ref: string): boolean {
+  const [root, kind] = parseRefPointer(ref);
+  return ref.startsWith("#/") && root === COMPONENTS_SEGMENT && kind === MEDIA_TYPES_COMPONENT_KIND;
+}

package/src/domain/openapi/operation-object.ts

@@ -0,0 +1,13 @@
+import type { ParameterOrReference } from "./parameter-object.js";
+import type { RequestBodyObject } from "./request-body-object.js";
+import type { ResponsesObject } from "./response-object.js";
+import type { ReferenceSchema } from "./schema-object.js";
+
+/** The parts of an Operation Object the generator reads (OpenAPI 3.1 §4.8.10). */
+export interface OperationObject {
+  readonly operationId?: string;
+  readonly deprecated?: boolean;
+  readonly parameters?: readonly ParameterOrReference[];
+  readonly requestBody?: RequestBodyObject | ReferenceSchema;
+  readonly responses?: ResponsesObject;
+}

package/src/domain/openapi/parameter-object.ts

@@ -0,0 +1,30 @@
+import type { ContentMap } from "./media-type-object.js";
+import type { ReferenceSchema, Schema } from "./schema-object.js";
+
+export type ParameterLocation = "query" | "header" | "path" | "cookie";
+
+/** Every parameter location, in the order the generated `parameters` type lists them. */
+export const PARAMETER_LOCATIONS: readonly ParameterLocation[] = Object.freeze([
+  "query",
+  "header",
+  "path",
+  "cookie",
+]);
+
+/**
+ * The OpenAPI 3.2 location of a parameter that is the whole query string, described by `content`.
+ * Its type becomes the `query` member of `parameters` (ADR-020).
+ */
+export const QUERYSTRING_LOCATION = "querystring";
+
+/** The parts of a Parameter Object the generator reads (OpenAPI 3.2 §4.8.12). */
+export interface ParameterObject {
+  readonly name: string;
+  readonly in: ParameterLocation | typeof QUERYSTRING_LOCATION;
+  readonly required?: boolean;
+  readonly deprecated?: boolean;
+  readonly schema?: Schema;
+  readonly content?: ContentMap;
+}
+
+export type ParameterOrReference = ParameterObject | ReferenceSchema;

package/src/domain/openapi/path-item-object.ts

@@ -0,0 +1,70 @@
+import type { OperationObject } from "./operation-object.js";
+import type { ParameterOrReference } from "./parameter-object.js";
+import type { ReferenceSchema } from "./schema-object.js";
+
+/** The methods every generated path item lists, with `?: never` when the document has none. */
+export type HttpMethod = "get" | "put" | "post" | "delete" | "options" | "head" | "patch" | "trace";
+
+/** The operation fields of a path item, in the order the generated types list them. */
+export const HTTP_METHODS: readonly HttpMethod[] = Object.freeze([
+  "get",
+  "put",
+  "post",
+  "delete",
+  "options",
+  "head",
+  "patch",
+  "trace",
+]);
+
+/**
+ * The OpenAPI 3.2 QUERY method. Its member is written only when the path item declares it, so
+ * documents without it keep their output (ADR-020).
+ */
+export const QUERY_METHOD = "query";
+
+/** Every operation field of a path item. */
+export type PathItemMethod = HttpMethod | typeof QUERY_METHOD;
+
+/** The OpenAPI 3.2 path item field for methods other than the fixed fields, by exact name. */
+export const ADDITIONAL_OPERATIONS_KEY = "additionalOperations";
+
+export type OperationEntry = OperationObject | ReferenceSchema;
+
+/** The parts of a Path Item Object the generator reads (OpenAPI 3.2 §4.8.9). */
+export type PathItemObject = {
+  readonly parameters?: readonly ParameterOrReference[];
+  readonly additionalOperations?: Readonly<Record<string, OperationEntry>>;
+} & { readonly [method in PathItemMethod]?: OperationEntry };
+
+/** Path items by URL template (OpenAPI 3.1 §4.8.8); webhooks use the same shape by name. */
+export type PathsObject = Readonly<Record<string, PathItemObject | ReferenceSchema>>;
+
+/** One operation of a path item and the method it is declared under. */
+export interface PathItemOperation {
+  /** A fixed field (`get`, `query`, …) or an `additionalOperations` name (`SUBSCRIBE`). */
+  readonly method: string;
+  readonly operation: OperationEntry;
+  /** JSON Pointer segments from the path item to the operation. */
+  readonly segments: readonly string[];
+}
+
+/**
+ * Every operation of a path item: the fixed methods in output order, then `query`, then
+ * `additionalOperations` in document order.
+ */
+export function pathItemOperations(pathItem: PathItemObject): PathItemOperation[] {
+  const methods: readonly PathItemMethod[] = [...HTTP_METHODS, QUERY_METHOD];
+  const fixed = methods.flatMap((method) => {
+    const operation = pathItem[method];
+    return operation ? [{ method, operation, segments: [method] }] : [];
+  });
+  const additional = Object.entries(pathItem.additionalOperations ?? {}).map(
+    ([method, operation]) => ({
+      method,
+      operation,
+      segments: [ADDITIONAL_OPERATIONS_KEY, method],
+    }),
+  );
+  return [...fixed, ...additional];
+}

package/src/domain/openapi/request-body-object.ts

@@ -0,0 +1,7 @@
+import type { ContentMap } from "./media-type-object.js";
+
+/** The parts of a Request Body Object the generator reads (OpenAPI 3.1 §4.8.13). */
+export interface RequestBodyObject {
+  readonly required?: boolean;
+  readonly content?: ContentMap;
+}

package/src/domain/openapi/response-object.ts

@@ -0,0 +1,14 @@
+import type { HeaderObject } from "./header-object.js";
+import type { ContentMap } from "./media-type-object.js";
+import type { ReferenceSchema } from "./schema-object.js";
+
+/** The parts of a Response Object the generator reads (OpenAPI 3.1 §4.8.17). */
+export interface ResponseObject {
+  /** Written into the JSDoc of the response's member. */
+  readonly description?: string;
+  readonly headers?: Readonly<Record<string, HeaderObject | ReferenceSchema>>;
+  readonly content?: ContentMap;
+}
+
+/** Responses by status code or `default` (OpenAPI 3.1 §4.8.16). */
+export type ResponsesObject = Readonly<Record<string, ResponseObject | ReferenceSchema>>;

package/src/domain/openapi/schema-object.ts

@@ -0,0 +1,59 @@
+/**
+ * The parts of an OpenAPI / JSON Schema object that the schema transformer reads. Documents are
+ * validated by the loader, so fields are typed as the specification defines them; places where the
+ * original generator tolerates other input check the value at run time.
+ */
+
+export interface ReferenceSchema {
+  readonly $ref: string;
+}
+
+/** A schema: an object, a reference, or a boolean schema (`true` allows anything). */
+export type Schema = SchemaObject | ReferenceSchema | boolean;
+
+export type SchemaTypeName =
+  | "string"
+  | "number"
+  | "integer"
+  | "boolean"
+  | "null"
+  | "array"
+  | "object";
+
+export interface SchemaDiscriminator {
+  /** Optional since OpenAPI 3.2; a discriminator without it adds no property type. */
+  readonly propertyName?: string;
+  readonly mapping?: Readonly<Record<string, string>>;
+}
+
+export interface SchemaObject {
+  readonly type?: SchemaTypeName | readonly (SchemaTypeName | null)[];
+  readonly const?: unknown;
+  readonly enum?: readonly unknown[];
+  readonly nullable?: boolean;
+  readonly format?: string;
+  readonly contentMediaType?: string;
+  readonly contentEncoding?: string;
+  readonly properties?: Readonly<Record<string, Schema>>;
+  readonly required?: readonly string[];
+  readonly additionalProperties?: Schema | Readonly<Record<string, never>>;
+  readonly patternProperties?: Readonly<Record<string, Schema>>;
+  readonly unevaluatedProperties?: Schema | Readonly<Record<string, never>>;
+  readonly $defs?: Readonly<Record<string, SchemaObject>>;
+  readonly items?: Schema | readonly Schema[];
+  readonly prefixItems?: readonly Schema[];
+  readonly minItems?: number;
+  readonly maxItems?: number;
+  readonly allOf?: readonly Schema[];
+  readonly anyOf?: readonly Schema[];
+  readonly oneOf?: readonly Schema[];
+  readonly discriminator?: SchemaDiscriminator;
+  readonly readOnly?: boolean;
+  readonly writeOnly?: boolean;
+  readonly default?: unknown;
+  readonly deprecated?: boolean;
+  readonly "x-enum-varnames"?: readonly string[];
+  readonly "x-enumNames"?: readonly string[];
+  readonly "x-enum-descriptions"?: readonly string[];
+  readonly "x-enumDescriptions"?: readonly string[];
+}

package/src/domain/openapi/unsupported-features.ts

@@ -0,0 +1,139 @@
+import { createRef, parseRefPointer } from "./json-pointer.js";
+import { QUERYSTRING_LOCATION } from "./parameter-object.js";
+import { type PathItemObject, pathItemOperations } from "./path-item-object.js";
+
+/**
+ * OpenAPI 3.2 uses that the generated types leave out, so each one gets a warning. The 3.2
+ * features are typed (ADR-020); what is left is an `in: querystring` parameter next to
+ * `in: query` parameters of the same operation, which 3.2 does not allow: the `query`
+ * parameters keep their types and the `querystring` parameter is not in the output.
+ */
+export const UnsupportedFeature = {
+  QUERYSTRING_NEXT_TO_QUERY: "querystring",
+} as const;
+export type UnsupportedFeature = (typeof UnsupportedFeature)[keyof typeof UnsupportedFeature];
+
+/** One place in the document that uses a feature the output leaves out. */
+export interface UnsupportedFeatureUse {
+  readonly feature: UnsupportedFeature;
+  /** A JSON Pointer to the object that has the feature's key, such as `#/paths/~1items`. */
+  readonly pointer: string;
+}
+
+const QUERY_LOCATION = "query";
+const LOCAL_REF_PREFIX = "#/";
+
+type JsonObject = Readonly<Record<string, unknown>>;
+
+function isObject(value: unknown): value is JsonObject {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+/** The value at a local `$ref` (`#/...`) of the document; null for other or broken `$ref`s. */
+function resolveLocal(document: JsonObject, value: unknown): unknown {
+  if (!isObject(value) || typeof value.$ref !== "string") {
+    return value;
+  }
+  if (!value.$ref.startsWith(LOCAL_REF_PREFIX)) {
+    return null;
+  }
+  let node: unknown = document;
+  for (const segment of parseRefPointer(value.$ref)) {
+    node = isObject(node) || Array.isArray(node) ? (node as JsonObject)[segment] : undefined;
+  }
+  return node ?? null;
+}
+
+/** A parameter where it is written, with the object its `$ref` points to. */
+interface LocatedParameter {
+  readonly pointer: string;
+  readonly parameter: JsonObject;
+}
+
+function locatedParameters(
+  document: JsonObject,
+  parameters: unknown,
+  segments: readonly string[],
+): LocatedParameter[] {
+  if (!Array.isArray(parameters)) {
+    return [];
+  }
+  return parameters.flatMap((entry, index) => {
+    const parameter = resolveLocal(document, entry);
+    const pointer = createRef([...segments, String(index)]);
+    return isObject(parameter) ? [{ pointer, parameter }] : [];
+  });
+}
+
+/** Path item parameters, then the operation's, which replace those of the same `in` and name. */
+function mergedParameters(
+  shared: readonly LocatedParameter[],
+  own: readonly LocatedParameter[],
+): LocatedParameter[] {
+  const byKey = new Map<string, LocatedParameter>();
+  for (const located of [...shared, ...own]) {
+    byKey.set(`${String(located.parameter.in)}-${String(located.parameter.name)}`, located);
+  }
+  return [...byKey.values()];
+}
+
+/** The `querystring` parameters of one operation that has `in: query` parameters as well. */
+function querystringPointers(parameters: readonly LocatedParameter[]): string[] {
+  const hasQuery = parameters.some(({ parameter }) => parameter.in === QUERY_LOCATION);
+  return hasQuery
+    ? parameters
+        .filter(({ parameter }) => parameter.in === QUERYSTRING_LOCATION)
+        .map(({ pointer }) => pointer)
+    : [];
+}
+
+/** Pointers of `querystring` parameters next to `query` ones in the operations of a path item. */
+function pathItemPointers(
+  document: JsonObject,
+  pathItem: JsonObject,
+  segments: readonly string[],
+): string[] {
+  const shared = locatedParameters(document, pathItem.parameters, [...segments, "parameters"]);
+  return pathItemOperations(pathItem as PathItemObject).flatMap((entry) => {
+    const operation = resolveLocal(document, entry.operation);
+    if (!isObject(operation)) {
+      return [];
+    }
+    const operationSegments = [...segments, ...entry.segments, "parameters"];
+    const own = locatedParameters(document, operation.parameters, operationSegments);
+    return querystringPointers(mergedParameters(shared, own));
+  });
+}
+
+function pathItemsPointers(
+  document: JsonObject,
+  pathItems: unknown,
+  root: readonly string[],
+): string[] {
+  if (!isObject(pathItems)) {
+    return [];
+  }
+  return Object.entries(pathItems).flatMap(([key, pathItem]) =>
+    isObject(pathItem) ? pathItemPointers(document, pathItem, [...root, key]) : [],
+  );
+}
+
+/**
+ * Every use of a feature in `UnsupportedFeature`, once per pointer, in document order: `paths`,
+ * then `webhooks`, then `components.pathItems`.
+ */
+export function findUnsupportedFeatures(document: unknown): UnsupportedFeatureUse[] {
+  if (!isObject(document)) {
+    return [];
+  }
+  const components = isObject(document.components) ? document.components : {};
+  const pointers = [
+    ...pathItemsPointers(document, document.paths, ["paths"]),
+    ...pathItemsPointers(document, document.webhooks, ["webhooks"]),
+    ...pathItemsPointers(document, components.pathItems, ["components", "pathItems"]),
+  ];
+  return [...new Set(pointers)].map((pointer) => ({
+    feature: UnsupportedFeature.QUERYSTRING_NEXT_TO_QUERY,
+    pointer,
+  }));
+}