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

package/src/domain/ir/newer-identifier-ranges.ts

@@ -1,22 +1,52 @@
 // Generated by scripts/identifier-ranges.ts (Node.js 26.0.0, Unicode
-// 17.0, TypeScript 5.9.3). Do not edit.
+// 17.0, TypeScript 5.4.5). Do not edit.
 
 /** `ID_Start` code points that TypeScript's scanner does not accept, as regex class items. */
 export const NEWER_IDENTIFIER_START: readonly string[] = [
-  "\\u{88F}",
-  "\\u{C5C}",
-  "\\u{CDC}",
+  "\\u{870}-\\u{887}",
+  "\\u{889}-\\u{88F}",
+  "\\u{8B5}",
+  "\\u{8BE}-\\u{8C9}",
+  "\\u{C5C}-\\u{C5D}",
+  "\\u{CDC}-\\u{CDD}",
+  "\\u{D04}",
+  "\\u{170D}",
+  "\\u{171F}",
+  "\\u{1B4C}",
   "\\u{1C89}-\\u{1C8A}",
-  "\\u{A7CB}-\\u{A7CF}",
-  "\\u{A7D2}",
-  "\\u{A7D4}",
-  "\\u{A7DA}-\\u{A7DC}",
-  "\\u{A7F1}",
+  "\\u{2C2F}",
+  "\\u{2C5F}",
+  "\\u{31BB}-\\u{31BF}",
+  "\\u{4DB6}-\\u{4DBF}",
+  "\\u{9FF0}-\\u{9FFF}",
+  "\\u{A7C0}-\\u{A7C1}",
+  "\\u{A7C7}-\\u{A7DC}",
+  "\\u{A7F1}-\\u{A7F6}",
+  "\\u{AB68}-\\u{AB69}",
+  "\\u{10570}-\\u{1057A}",
+  "\\u{1057C}-\\u{1058A}",
+  "\\u{1058C}-\\u{10592}",
+  "\\u{10594}-\\u{10595}",
+  "\\u{10597}-\\u{105A1}",
+  "\\u{105A3}-\\u{105B1}",
+  "\\u{105B3}-\\u{105B9}",
+  "\\u{105BB}-\\u{105BC}",
   "\\u{105C0}-\\u{105F3}",
+  "\\u{10780}-\\u{10785}",
+  "\\u{10787}-\\u{107B0}",
+  "\\u{107B2}-\\u{107BA}",
   "\\u{10940}-\\u{10959}",
   "\\u{10D4A}-\\u{10D65}",
   "\\u{10D6F}-\\u{10D85}",
+  "\\u{10E80}-\\u{10EA9}",
+  "\\u{10EB0}-\\u{10EB1}",
   "\\u{10EC2}-\\u{10EC7}",
+  "\\u{10F70}-\\u{10F81}",
+  "\\u{10FB0}-\\u{10FC4}",
+  "\\u{11071}-\\u{11072}",
+  "\\u{11075}",
+  "\\u{11147}",
+  "\\u{1123F}-\\u{11240}",
   "\\u{11380}-\\u{11389}",
   "\\u{1138B}",
   "\\u{1138E}",
@@ -24,18 +54,47 @@ export const NEWER_IDENTIFIER_START: readonly string[] = [
   "\\u{113B7}",
   "\\u{113D1}",
   "\\u{113D3}",
+  "\\u{11460}-\\u{11461}",
+  "\\u{11740}-\\u{11746}",
+  "\\u{11900}-\\u{11906}",
+  "\\u{11909}",
+  "\\u{1190C}-\\u{11913}",
+  "\\u{11915}-\\u{11916}",
+  "\\u{11918}-\\u{1192F}",
+  "\\u{1193F}",
+  "\\u{11941}",
+  "\\u{11AB0}-\\u{11ABF}",
   "\\u{11BC0}-\\u{11BE0}",
   "\\u{11DB0}-\\u{11DDB}",
+  "\\u{11F02}",
+  "\\u{11F04}-\\u{11F10}",
+  "\\u{11F12}-\\u{11F33}",
+  "\\u{11FB0}",
+  "\\u{12F90}-\\u{12FF0}",
+  "\\u{1342F}",
+  "\\u{13441}-\\u{13446}",
   "\\u{13460}-\\u{143FA}",
   "\\u{16100}-\\u{1611D}",
+  "\\u{16A70}-\\u{16ABE}",
   "\\u{16D40}-\\u{16D6C}",
   "\\u{16EA0}-\\u{16EB8}",
   "\\u{16EBB}-\\u{16ED3}",
   "\\u{16FF2}-\\u{16FF6}",
   "\\u{187F8}-\\u{187FF}",
-  "\\u{18CFF}",
-  "\\u{18D09}-\\u{18D1E}",
+  "\\u{18AF3}-\\u{18CD5}",
+  "\\u{18CFF}-\\u{18D1E}",
   "\\u{18D80}-\\u{18DF2}",
+  "\\u{1AFF0}-\\u{1AFF3}",
+  "\\u{1AFF5}-\\u{1AFFB}",
+  "\\u{1AFFD}-\\u{1AFFE}",
+  "\\u{1B11F}-\\u{1B122}",
+  "\\u{1B132}",
+  "\\u{1B155}",
+  "\\u{1DF00}-\\u{1DF1E}",
+  "\\u{1DF25}-\\u{1DF2A}",
+  "\\u{1E030}-\\u{1E06D}",
+  "\\u{1E290}-\\u{1E2AD}",
+  "\\u{1E4D0}-\\u{1E4EB}",
   "\\u{1E5D0}-\\u{1E5ED}",
   "\\u{1E5F0}",
   "\\u{1E6C0}-\\u{1E6DE}",
@@ -44,32 +103,83 @@ export const NEWER_IDENTIFIER_START: readonly string[] = [
   "\\u{1E6E7}-\\u{1E6ED}",
   "\\u{1E6F0}-\\u{1E6F4}",
   "\\u{1E6FE}-\\u{1E6FF}",
-  "\\u{2B73A}-\\u{2B73F}",
+  "\\u{1E7E0}-\\u{1E7E6}",
+  "\\u{1E7E8}-\\u{1E7EB}",
+  "\\u{1E7ED}-\\u{1E7EE}",
+  "\\u{1E7F0}-\\u{1E7FE}",
+  "\\u{2A6D7}-\\u{2A6DF}",
+  "\\u{2B735}-\\u{2B73F}",
   "\\u{2CEA2}-\\u{2CEAD}",
-  "\\u{323B0}-\\u{33479}",
+  "\\u{2EBF0}-\\u{2EE5D}",
+  "\\u{30000}-\\u{3134A}",
+  "\\u{31350}-\\u{33479}",
 ];
 
 /** `ID_Continue` code points that TypeScript's scanner does not accept, as regex class items. */
 export const NEWER_IDENTIFIER_PART: readonly string[] = [
-  "\\u{88F}",
-  "\\u{897}",
-  "\\u{C5C}",
-  "\\u{CDC}",
-  "\\u{1ACF}-\\u{1ADD}",
+  "\\u{870}-\\u{887}",
+  "\\u{889}-\\u{88F}",
+  "\\u{897}-\\u{89F}",
+  "\\u{8B5}",
+  "\\u{8BE}-\\u{8D2}",
+  "\\u{B55}",
+  "\\u{C3C}",
+  "\\u{C5C}-\\u{C5D}",
+  "\\u{CDC}-\\u{CDD}",
+  "\\u{CF3}",
+  "\\u{D04}",
+  "\\u{D81}",
+  "\\u{ECE}",
+  "\\u{170D}",
+  "\\u{1715}",
+  "\\u{171F}",
+  "\\u{180F}",
+  "\\u{1ABF}-\\u{1ADD}",
   "\\u{1AE0}-\\u{1AEB}",
+  "\\u{1B4C}",
   "\\u{1C89}-\\u{1C8A}",
-  "\\u{A7CB}-\\u{A7CF}",
-  "\\u{A7D2}",
-  "\\u{A7D4}",
-  "\\u{A7DA}-\\u{A7DC}",
-  "\\u{A7F1}",
+  "\\u{1DFA}",
+  "\\u{200C}-\\u{200D}",
+  "\\u{2C2F}",
+  "\\u{2C5F}",
+  "\\u{30FB}",
+  "\\u{31BB}-\\u{31BF}",
+  "\\u{4DB6}-\\u{4DBF}",
+  "\\u{9FF0}-\\u{9FFF}",
+  "\\u{A7C0}-\\u{A7C1}",
+  "\\u{A7C7}-\\u{A7DC}",
+  "\\u{A7F1}-\\u{A7F6}",
+  "\\u{A82C}",
+  "\\u{AB68}-\\u{AB69}",
+  "\\u{FF65}",
+  "\\u{10570}-\\u{1057A}",
+  "\\u{1057C}-\\u{1058A}",
+  "\\u{1058C}-\\u{10592}",
+  "\\u{10594}-\\u{10595}",
+  "\\u{10597}-\\u{105A1}",
+  "\\u{105A3}-\\u{105B1}",
+  "\\u{105B3}-\\u{105B9}",
+  "\\u{105BB}-\\u{105BC}",
   "\\u{105C0}-\\u{105F3}",
+  "\\u{10780}-\\u{10785}",
+  "\\u{10787}-\\u{107B0}",
+  "\\u{107B2}-\\u{107BA}",
   "\\u{10940}-\\u{10959}",
   "\\u{10D40}-\\u{10D65}",
   "\\u{10D69}-\\u{10D6D}",
   "\\u{10D6F}-\\u{10D85}",
+  "\\u{10E80}-\\u{10EA9}",
+  "\\u{10EAB}-\\u{10EAC}",
+  "\\u{10EB0}-\\u{10EB1}",
   "\\u{10EC2}-\\u{10EC7}",
-  "\\u{10EFA}-\\u{10EFC}",
+  "\\u{10EFA}-\\u{10EFF}",
+  "\\u{10F70}-\\u{10F85}",
+  "\\u{10FB0}-\\u{10FC4}",
+  "\\u{11070}-\\u{11075}",
+  "\\u{110C2}",
+  "\\u{11147}",
+  "\\u{111CE}-\\u{111CF}",
+  "\\u{1123F}-\\u{11241}",
   "\\u{11380}-\\u{11389}",
   "\\u{1138B}",
   "\\u{1138E}",
@@ -80,30 +190,73 @@ export const NEWER_IDENTIFIER_PART: readonly string[] = [
   "\\u{113C7}-\\u{113CA}",
   "\\u{113CC}-\\u{113D3}",
   "\\u{113E1}-\\u{113E2}",
+  "\\u{11460}-\\u{11461}",
   "\\u{116D0}-\\u{116E3}",
+  "\\u{11740}-\\u{11746}",
+  "\\u{11900}-\\u{11906}",
+  "\\u{11909}",
+  "\\u{1190C}-\\u{11913}",
+  "\\u{11915}-\\u{11916}",
+  "\\u{11918}-\\u{11935}",
+  "\\u{11937}-\\u{11938}",
+  "\\u{1193B}-\\u{11943}",
+  "\\u{11950}-\\u{11959}",
+  "\\u{11AB0}-\\u{11ABF}",
   "\\u{11B60}-\\u{11B67}",
   "\\u{11BC0}-\\u{11BE0}",
   "\\u{11BF0}-\\u{11BF9}",
   "\\u{11DB0}-\\u{11DDB}",
   "\\u{11DE0}-\\u{11DE9}",
-  "\\u{11F5A}",
+  "\\u{11F00}-\\u{11F10}",
+  "\\u{11F12}-\\u{11F3A}",
+  "\\u{11F3E}-\\u{11F42}",
+  "\\u{11F50}-\\u{11F5A}",
+  "\\u{11FB0}",
+  "\\u{12F90}-\\u{12FF0}",
+  "\\u{1342F}",
+  "\\u{13440}-\\u{13455}",
   "\\u{13460}-\\u{143FA}",
   "\\u{16100}-\\u{16139}",
+  "\\u{16A70}-\\u{16ABE}",
+  "\\u{16AC0}-\\u{16AC9}",
   "\\u{16D40}-\\u{16D6C}",
   "\\u{16D70}-\\u{16D79}",
   "\\u{16EA0}-\\u{16EB8}",
   "\\u{16EBB}-\\u{16ED3}",
-  "\\u{16FF2}-\\u{16FF6}",
+  "\\u{16FE4}",
+  "\\u{16FF0}-\\u{16FF6}",
   "\\u{187F8}-\\u{187FF}",
-  "\\u{18CFF}",
-  "\\u{18D09}-\\u{18D1E}",
+  "\\u{18AF3}-\\u{18CD5}",
+  "\\u{18CFF}-\\u{18D1E}",
   "\\u{18D80}-\\u{18DF2}",
+  "\\u{1AFF0}-\\u{1AFF3}",
+  "\\u{1AFF5}-\\u{1AFFB}",
+  "\\u{1AFFD}-\\u{1AFFE}",
+  "\\u{1B11F}-\\u{1B122}",
+  "\\u{1B132}",
+  "\\u{1B155}",
   "\\u{1CCF0}-\\u{1CCF9}",
+  "\\u{1CF00}-\\u{1CF2D}",
+  "\\u{1CF30}-\\u{1CF46}",
+  "\\u{1DF00}-\\u{1DF1E}",
+  "\\u{1DF25}-\\u{1DF2A}",
+  "\\u{1E030}-\\u{1E06D}",
+  "\\u{1E08F}",
+  "\\u{1E290}-\\u{1E2AE}",
+  "\\u{1E4D0}-\\u{1E4F9}",
   "\\u{1E5D0}-\\u{1E5FA}",
   "\\u{1E6C0}-\\u{1E6DE}",
   "\\u{1E6E0}-\\u{1E6F5}",
   "\\u{1E6FE}-\\u{1E6FF}",
-  "\\u{2B73A}-\\u{2B73F}",
+  "\\u{1E7E0}-\\u{1E7E6}",
+  "\\u{1E7E8}-\\u{1E7EB}",
+  "\\u{1E7ED}-\\u{1E7EE}",
+  "\\u{1E7F0}-\\u{1E7FE}",
+  "\\u{1FBF0}-\\u{1FBF9}",
+  "\\u{2A6D7}-\\u{2A6DF}",
+  "\\u{2B735}-\\u{2B73F}",
   "\\u{2CEA2}-\\u{2CEAD}",
-  "\\u{323B0}-\\u{33479}",
+  "\\u{2EBF0}-\\u{2EE5D}",
+  "\\u{30000}-\\u{3134A}",
+  "\\u{31350}-\\u{33479}",
 ];

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

@@ -53,7 +53,10 @@ export function countNodes(root: unknown): NodeCounts {
       ? childrenOf(node).filter((child) => isContainer(child) && !entered.has(child))
       : [];
     if (pending.length > 0) {
-      stack.push(...(pending as object[]));
+      // One push per child: spreading an array of millions of children overflows the stack.
+      for (const child of pending as object[]) {
+        stack.push(child);
+      }
       continue;
     }
     stack.pop();

package/src/domain/openapi/discriminated-union.ts

@@ -1,4 +1,4 @@
-import { escapePointerSegment } from "./json-pointer.js";
+import { canonicalRef, escapePointerSegment } from "./json-pointer.js";
 import type { Schema, SchemaObject } from "./schema-object.js";
 
 /**
@@ -51,7 +51,7 @@ function reaches(schema: Schema, search: Search): boolean {
   }
   const ref = (schema as { readonly $ref?: unknown }).$ref;
   if (typeof ref === "string") {
-    if (ref === search.target) {
+    if (canonicalRef(ref) === canonicalRef(search.target)) {
       return true;
     }
     if (search.visited.has(ref)) {
@@ -84,7 +84,9 @@ function mappingRef(target: unknown): string | undefined {
   if (typeof target !== "string") {
     return undefined;
   }
-  return target.startsWith("#") ? target : `${COMPONENT_SCHEMAS}${escapePointerSegment(target)}`;
+  return target.startsWith("#")
+    ? canonicalRef(target)
+    : `${COMPONENT_SCHEMAS}${escapePointerSegment(target)}`;
 }
 
 /** Whether the discriminator `mapping` of `union` names the schema at `target`. */
@@ -93,7 +95,7 @@ export function unionMaps(union: SchemaObject, target: string): boolean {
   if (!isSchemaObject(mapping)) {
     return false;
   }
-  return Object.values(mapping).some((value) => mappingRef(value) === target);
+  return Object.values(mapping).some((value) => mappingRef(value) === canonicalRef(target));
 }
 
 /**

package/src/domain/openapi/discriminator-conflicts.ts

@@ -1,6 +1,13 @@
+import { appendAll } from "../append-all.js";
 import { admittedPropertyValues, resolveLocalRef } from "./admitted-values.js";
 import { isUnionMember, unionAt } from "./discriminated-union.js";
-import { createRef, escapePointerSegment, parseRefPointer } from "./json-pointer.js";
+import {
+  appendPointer,
+  canonicalRef,
+  escapePointerSegment,
+  parseRefPointer,
+  ROOT_POINTER,
+} from "./json-pointer.js";
 
 /**
  * Discriminator members whose discriminator value their own property does not allow. By the
@@ -45,8 +52,11 @@ function refsOf(list: unknown): string[] {
   );
 }
 
+/** A mapping value as a canonical `$ref`: Redocly writes it percent-decoded (`canonicalRef`). */
 function mappingTarget(target: string): string {
-  return target.startsWith("#") ? target : `${COMPONENT_SCHEMAS}${escapePointerSegment(target)}`;
+  return target.startsWith("#")
+    ? canonicalRef(target)
+    : `${COMPONENT_SCHEMAS}${escapePointerSegment(target)}`;
 }
 
 function ownerAt(node: JsonObject, pointer: () => string): Owner | null {
@@ -76,7 +86,7 @@ function pointerOf(visit: Visit): string {
   for (let current: Visit | null = visit; current?.key != null; current = current.parent) {
     segments.unshift(current.key);
   }
-  return createRef(segments);
+  return appendPointer(ROOT_POINTER, segments);
 }
 
 function childrenOf(visit: Visit): Visit[] {
@@ -101,7 +111,7 @@ function ownersIn(document: unknown): Owner[] {
     if (owner !== null) {
       found.push(owner);
     }
-    stack.push(...childrenOf(visit).reverse());
+    appendAll(stack, childrenOf(visit).reverse());
   }
   return found;
 }
@@ -200,8 +210,10 @@ function membersOf(owner: Owner, search: ConflictSearch): Member[] {
   const listed = owner.memberRefs.map((ref) => ({ ref, skipped: new Set([owner.pointer]) }));
   const members = new Map<string, Member>();
   for (const member of [...listed, ...inheritingMembers(owner, search)]) {
-    if (!members.has(member.ref)) {
-      members.set(member.ref, member);
+    // A member may be listed by a `$ref` and found by its pointer: both name it canonically.
+    const key = canonicalRef(member.ref);
+    if (!members.has(key)) {
+      members.set(key, member);
     }
   }
   return [...members.values()];
@@ -209,7 +221,9 @@ function membersOf(owner: Owner, search: ConflictSearch): Member[] {
 
 function memberValues(owner: Owner, member: string): { values: string[]; isImplicit: boolean } {
   const values = Object.entries(owner.mapping)
-    .filter(([, target]) => typeof target === "string" && mappingTarget(target) === member)
+    .filter(
+      ([, target]) => typeof target === "string" && mappingTarget(target) === canonicalRef(member),
+    )
     .map(([key]) => key);
   const name = parseRefPointer(member).pop() ?? "";
   return values.length > 0 ? { values, isImplicit: false } : { values: [name], isImplicit: true };

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

@@ -4,6 +4,8 @@ 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 {
+  /** The OpenAPI version: `3.0.x`, `3.1.x` or `3.2.x`. */
+  readonly openapi?: string;
   readonly paths?: PathsObject;
   readonly webhooks?: PathsObject;
   readonly components?: ComponentsObject;

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

@@ -18,19 +18,108 @@ function unescapePointerSegment(segment: string): string {
 }
 
 /**
- * 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).
+ * Escape one segment for a JSON Pointer in a `$ref` fragment: `~` → `~0` and `/` → `~1` (RFC 6901),
+ * then `%` → `%25` and `#` → `%23`, the two characters of a key that a URI fragment cannot hold as
+ * written (RFC 6901 §6, RFC 3986). Reading a pointer back percent-decodes it, so the original's
+ * unescaped `%` threw URIError for `50%` and read `a%2Fb` as `a/b` (upstream #2251, #2828), and
+ * reading starts at the first `#/`, so an unescaped key `a#` cut the pointer short.
  */
 export function escapePointerSegment(segment: string): string {
-  return segment.replaceAll("~", "~0").replaceAll("/", "~1").replaceAll("%", "%25");
+  return segment
+    .replaceAll("~", "~0")
+    .replaceAll("/", "~1")
+    .replaceAll("%", "%25")
+    .replaceAll("#", "%23");
+}
+
+/** The pointer of the document root. */
+export const ROOT_POINTER = "#";
+
+/** A raw pointer segment; a missing one (`undefined`, `null` or empty) is skipped. */
+export type PointerSegment = string | number | null | undefined;
+
+/**
+ * Extend the pointer `base` with raw segments: document keys, such as a path, a property name or a
+ * media type, and array indexes. Each segment is escaped and never read as a `$ref`, so a key like
+ * `#/%41` stays one segment and reads back unchanged with {@link parseRefPointer}. A missing
+ * segment, such as the absent `name` of a parameter, is skipped, as the original `createRef` did,
+ * and an empty one too, because `parseRefPointer` drops it.
+ */
+export function appendPointer(
+  base: string | undefined,
+  segments: readonly PointerSegment[],
+): string {
+  let pointer = pointerBase(base);
+  for (const segment of segments) {
+    if (segment !== undefined && segment !== null && segment !== "") {
+      pointer = childPointer(pointer, String(segment));
+    }
+  }
+  return pointer;
+}
+
+/**
+ * The pointer of the child `key` of the node at `pointer`, with `key` escaped. Unlike
+ * {@link appendPointer}, an empty key is a child too: a document walk names every key it visits.
+ */
+export function childPointer(pointer: string, key: string): string {
+  return `${pointer}/${escapePointerSegment(key)}`;
+}
+
+/**
+ * A local `$ref` or `mapping` value in the form {@link appendPointer} builds, so that pointers
+ * compare as text whatever escapes the document chose: `.../a#b` and `.../a%23b` are both
+ * `.../a%23b`. Redocly writes a bundled `mapping` value percent-decoded, which is no pointer for a
+ * key with `%` (`.../50%`), so such a text is read as written. Any other text, such as an
+ * external `$ref` or a bare schema name, is returned unchanged.
+ */
+export function canonicalRef(ref: string): string {
+  if (!ref.startsWith(`${ROOT_POINTER}/`)) {
+    return ref;
+  }
+  return appendPointer(ROOT_POINTER, refSegments(ref));
+}
+
+function refSegments(ref: string): string[] {
+  try {
+    return parseRefPointer(ref);
+  } catch (error) {
+    if (!(error instanceof URIError)) {
+      throw error;
+    }
+    return writtenSegments(ref);
+  }
+}
+
+/** The segments of a pointer that is not percent-encoded: only `~1` and `~0` are escapes. */
+function writtenSegments(ref: string): string[] {
+  return ref
+    .slice(ROOT_POINTER.length + 1)
+    .split("/")
+    .filter((segment) => segment.length > 0)
+    .map((segment) => segment.replaceAll("~1", "/").replaceAll("~0", "~"));
+}
+
+/**
+ * A pointer (`#` or `#/...`) is kept as written; a missing base is the root. Any other text is a
+ * `path` given to the exported transformers, such as `/items/{id}` or `other.yaml#/a`, which the
+ * original read as a `createRef` part, so it is read the same way here.
+ */
+function pointerBase(base: string | undefined): string {
+  if (base === undefined || base === "") {
+    return ROOT_POINTER;
+  }
+  return base === ROOT_POINTER || base.startsWith(`${ROOT_POINTER}/`) ? base : createRef([base]);
 }
 
 /**
- * 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.
+ * Join parts into a local `$ref` (the original `createRef`, exported for 1.x by ADR-034). Empty
+ * parts are skipped. A part that contains `#/` is parsed as a `$ref` and contributes its decoded
+ * segments, so it throws URIError for a malformed percent escape; any other part is one segment.
+ * Because of that parsing, the generator does not pass document keys here: it builds pointers
+ * with {@link appendPointer}, which never parses a segment.
  */
-export function createRef(parts: readonly (string | number | null | undefined)[]): string {
+export function createRef(parts: readonly PointerSegment[]): string {
   let ref = "#";
   for (const part of parts) {
     if (part === undefined || part === null || part === "") {

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

@@ -0,0 +1,22 @@
+/**
+ * The schema dialect of a document. OpenAPI 3.0 Schema Objects ignore every keyword next to a
+ * `$ref` (OpenAPI 3.0.3, Reference Object). OpenAPI 3.1 and 3.2 use JSON Schema 2020-12, where a
+ * `$ref` is one keyword among the others, and all of them apply (JSON Schema Core §8.2.3.1).
+ */
+export const SCHEMA_DIALECTS = {
+  OPENAPI_3_0: "openapi-3.0",
+  JSON_SCHEMA_2020_12: "json-schema-2020-12",
+} as const;
+
+export type SchemaDialect = (typeof SCHEMA_DIALECTS)[keyof typeof SCHEMA_DIALECTS];
+
+const OPENAPI_3_0_RE = /^3\.0(?:\.|$)/;
+
+/**
+ * The dialect of a document's `openapi` version. Without a version (a schema passed to a
+ * transformer on its own) it is OpenAPI 3.0, which keeps the output the original gives.
+ */
+export function schemaDialectOf(openapiVersion: unknown): SchemaDialect {
+  const isOpenApi30 = typeof openapiVersion !== "string" || OPENAPI_3_0_RE.test(openapiVersion);
+  return isOpenApi30 ? SCHEMA_DIALECTS.OPENAPI_3_0 : SCHEMA_DIALECTS.JSON_SCHEMA_2020_12;
+}

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

@@ -1,4 +1,4 @@
-import { createRef, parseRefPointer } from "./json-pointer.js";
+import { appendPointer, parseRefPointer, ROOT_POINTER } from "./json-pointer.js";
 import { QUERYSTRING_LOCATION } from "./parameter-object.js";
 import { type PathItemObject, pathItemOperations } from "./path-item-object.js";
 
@@ -60,7 +60,7 @@ function locatedParameters(
   }
   return parameters.flatMap((entry, index) => {
     const parameter = resolveLocal(document, entry);
-    const pointer = createRef([...segments, String(index)]);
+    const pointer = appendPointer(ROOT_POINTER, [...segments, index]);
     return isObject(parameter) ? [{ pointer, parameter }] : [];
   });
 }