@hey-api/json-schema-ref-parser 0.0.1

package/lib/bundle.ts

@@ -0,0 +1,299 @@
+import $Ref from "./ref.js";
+import type { ParserOptions } from "./options.js";
+import Pointer from "./pointer.js";
+import * as url from "./util/url.js";
+import type $Refs from "./refs.js";
+import type { $RefParser } from "./index";
+import type { JSONSchema } from "./types/index.js";
+
+export interface InventoryEntry {
+  $ref: any;
+  parent: any;
+  key: any;
+  pathFromRoot: any;
+  depth: any;
+  file: any;
+  hash: any;
+  value: any;
+  circular: any;
+  extended: any;
+  external: any;
+  indirections: any;
+}
+/**
+ * Bundles all external JSON references into the main JSON schema, thus resulting in a schema that
+ * only has *internal* references, not any *external* references.
+ * This method mutates the JSON schema object, adding new references and re-mapping existing ones.
+ *
+ * @param parser
+ * @param options
+ */
+function bundle(
+  parser: $RefParser,
+  options: ParserOptions,
+) {
+  // console.log('Bundling $ref pointers in %s', parser.$refs._root$Ref.path);
+
+  // Build an inventory of all $ref pointers in the JSON Schema
+  const inventory: InventoryEntry[] = [];
+  crawl<JSONSchema>(parser, "schema", parser.$refs._root$Ref.path + "#", "#", 0, inventory, parser.$refs, options);
+
+  // Remap all $ref pointers
+  remap(inventory);
+}
+
+/**
+ * Recursively crawls the given value, and inventories all JSON references.
+ *
+ * @param parent - The object containing the value to crawl. If the value is not an object or array, it will be ignored.
+ * @param key - The property key of `parent` to be crawled
+ * @param path - The full path of the property being crawled, possibly with a JSON Pointer in the hash
+ * @param pathFromRoot - The path of the property being crawled, from the schema root
+ * @param indirections
+ * @param inventory - An array of already-inventoried $ref pointers
+ * @param $refs
+ * @param options
+ */
+function crawl<S extends object = JSONSchema>(
+  parent: object | $RefParser,
+  key: string | null,
+  path: string,
+  pathFromRoot: string,
+  indirections: number,
+  inventory: InventoryEntry[],
+  $refs: $Refs<S>,
+  options: ParserOptions,
+) {
+  const obj = key === null ? parent : parent[key as keyof typeof parent];
+
+  if (obj && typeof obj === "object" && !ArrayBuffer.isView(obj)) {
+    if ($Ref.isAllowed$Ref(obj)) {
+      inventory$Ref(parent, key, path, pathFromRoot, indirections, inventory, $refs, options);
+    } else {
+      // Crawl the object in a specific order that's optimized for bundling.
+      // This is important because it determines how `pathFromRoot` gets built,
+      // which later determines which keys get dereferenced and which ones get remapped
+      const keys = Object.keys(obj).sort((a, b) => {
+        // Most people will expect references to be bundled into the the "definitions" property,
+        // so we always crawl that property first, if it exists.
+        if (a === "definitions") {
+          return -1;
+        } else if (b === "definitions") {
+          return 1;
+        } else {
+          // Otherwise, crawl the keys based on their length.
+          // This produces the shortest possible bundled references
+          return a.length - b.length;
+        }
+      }) as (keyof typeof obj)[];
+
+      for (const key of keys) {
+        const keyPath = Pointer.join(path, key);
+        const keyPathFromRoot = Pointer.join(pathFromRoot, key);
+        const value = obj[key];
+
+        if ($Ref.isAllowed$Ref(value)) {
+          inventory$Ref(obj, key, path, keyPathFromRoot, indirections, inventory, $refs, options);
+        } else {
+          crawl(obj, key, keyPath, keyPathFromRoot, indirections, inventory, $refs, options);
+        }
+      }
+    }
+  }
+}
+
+/**
+ * Inventories the given JSON Reference (i.e. records detailed information about it so we can
+ * optimize all $refs in the schema), and then crawls the resolved value.
+ *
+ * @param $refParent - The object that contains a JSON Reference as one of its keys
+ * @param $refKey - The key in `$refParent` that is a JSON Reference
+ * @param path - The full path of the JSON Reference at `$refKey`, possibly with a JSON Pointer in the hash
+ * @param indirections - unknown
+ * @param pathFromRoot - The path of the JSON Reference at `$refKey`, from the schema root
+ * @param inventory - An array of already-inventoried $ref pointers
+ * @param $refs
+ * @param options
+ */
+function inventory$Ref<S extends object = JSONSchema>(
+  $refParent: any,
+  $refKey: string | null,
+  path: string,
+  pathFromRoot: string,
+  indirections: number,
+  inventory: InventoryEntry[],
+  $refs: $Refs<S>,
+  options: ParserOptions,
+) {
+  const $ref = $refKey === null ? $refParent : $refParent[$refKey];
+  const $refPath = url.resolve(path, $ref.$ref);
+  const pointer = $refs._resolve($refPath, pathFromRoot, options);
+  if (pointer === null) {
+    return;
+  }
+  const parsed = Pointer.parse(pathFromRoot);
+  const depth = parsed.length;
+  const file = url.stripHash(pointer.path);
+  const hash = url.getHash(pointer.path);
+  const external = file !== $refs._root$Ref.path;
+  const extended = $Ref.isExtended$Ref($ref);
+  indirections += pointer.indirections;
+
+  const existingEntry = findInInventory(inventory, $refParent, $refKey);
+  if (existingEntry) {
+    // This $Ref has already been inventoried, so we don't need to process it again
+    if (depth < existingEntry.depth || indirections < existingEntry.indirections) {
+      removeFromInventory(inventory, existingEntry);
+    } else {
+      return;
+    }
+  }
+
+  inventory.push({
+    $ref, // The JSON Reference (e.g. {$ref: string})
+    parent: $refParent, // The object that contains this $ref pointer
+    key: $refKey, // The key in `parent` that is the $ref pointer
+    pathFromRoot, // The path to the $ref pointer, from the JSON Schema root
+    depth, // How far from the JSON Schema root is this $ref pointer?
+    file, // The file that the $ref pointer resolves to
+    hash, // The hash within `file` that the $ref pointer resolves to
+    value: pointer.value, // The resolved value of the $ref pointer
+    circular: pointer.circular, // Is this $ref pointer DIRECTLY circular? (i.e. it references itself)
+    extended, // Does this $ref extend its resolved value? (i.e. it has extra properties, in addition to "$ref")
+    external, // Does this $ref pointer point to a file other than the main JSON Schema file?
+    indirections, // The number of indirect references that were traversed to resolve the value
+  });
+
+  // Recursively crawl the resolved value
+  if (!existingEntry || external) {
+    crawl(pointer.value, null, pointer.path, pathFromRoot, indirections + 1, inventory, $refs, options);
+  }
+}
+
+/**
+ * Re-maps every $ref pointer, so that they're all relative to the root of the JSON Schema.
+ * Each referenced value is dereferenced EXACTLY ONCE.  All subsequent references to the same
+ * value are re-mapped to point to the first reference.
+ *
+ * @example: {
+ *    first: { $ref: somefile.json#/some/part },
+ *    second: { $ref: somefile.json#/another/part },
+ *    third: { $ref: somefile.json },
+ *    fourth: { $ref: somefile.json#/some/part/sub/part }
+ *  }
+ *
+ * In this example, there are four references to the same file, but since the third reference points
+ * to the ENTIRE file, that's the only one we need to dereference.  The other three can just be
+ * remapped to point inside the third one.
+ *
+ * On the other hand, if the third reference DIDN'T exist, then the first and second would both need
+ * to be dereferenced, since they point to different parts of the file. The fourth reference does NOT
+ * need to be dereferenced, because it can be remapped to point inside the first one.
+ *
+ * @param inventory
+ */
+function remap(inventory: InventoryEntry[]) {
+  // Group & sort all the $ref pointers, so they're in the order that we need to dereference/remap them
+  inventory.sort((a: InventoryEntry, b: InventoryEntry) => {
+    if (a.file !== b.file) {
+      // Group all the $refs that point to the same file
+      return a.file < b.file ? -1 : +1;
+    } else if (a.hash !== b.hash) {
+      // Group all the $refs that point to the same part of the file
+      return a.hash < b.hash ? -1 : +1;
+    } else if (a.circular !== b.circular) {
+      // If the $ref points to itself, then sort it higher than other $refs that point to this $ref
+      return a.circular ? -1 : +1;
+    } else if (a.extended !== b.extended) {
+      // If the $ref extends the resolved value, then sort it lower than other $refs that don't extend the value
+      return a.extended ? +1 : -1;
+    } else if (a.indirections !== b.indirections) {
+      // Sort direct references higher than indirect references
+      return a.indirections - b.indirections;
+    } else if (a.depth !== b.depth) {
+      // Sort $refs by how close they are to the JSON Schema root
+      return a.depth - b.depth;
+    } else {
+      // Determine how far each $ref is from the "definitions" property.
+      // Most people will expect references to be bundled into the the "definitions" property if possible.
+      const aDefinitionsIndex = a.pathFromRoot.lastIndexOf("/definitions");
+      const bDefinitionsIndex = b.pathFromRoot.lastIndexOf("/definitions");
+
+      if (aDefinitionsIndex !== bDefinitionsIndex) {
+        // Give higher priority to the $ref that's closer to the "definitions" property
+        return bDefinitionsIndex - aDefinitionsIndex;
+      } else {
+        // All else is equal, so use the shorter path, which will produce the shortest possible reference
+        return a.pathFromRoot.length - b.pathFromRoot.length;
+      }
+    }
+  });
+
+  let file, hash, pathFromRoot;
+  for (const entry of inventory) {
+    // console.log('Re-mapping $ref pointer "%s" at %s', entry.$ref.$ref, entry.pathFromRoot);
+
+    if (!entry.external) {
+      // This $ref already resolves to the main JSON Schema file
+      entry.$ref.$ref = entry.hash;
+    } else if (entry.file === file && entry.hash === hash) {
+      // This $ref points to the same value as the prevous $ref, so remap it to the same path
+      entry.$ref.$ref = pathFromRoot;
+    } else if (entry.file === file && entry.hash.indexOf(hash + "/") === 0) {
+      // This $ref points to a sub-value of the prevous $ref, so remap it beneath that path
+      entry.$ref.$ref = Pointer.join(pathFromRoot, Pointer.parse(entry.hash.replace(hash, "#")));
+    } else {
+      // We've moved to a new file or new hash
+      file = entry.file;
+      hash = entry.hash;
+      pathFromRoot = entry.pathFromRoot;
+
+      // This is the first $ref to point to this value, so dereference the value.
+      // Any other $refs that point to the same value will point to this $ref instead
+      entry.$ref = entry.parent[entry.key] = $Ref.dereference(entry.$ref, entry.value);
+
+      if (entry.circular) {
+        // This $ref points to itself
+        entry.$ref.$ref = entry.pathFromRoot;
+      }
+    }
+  }
+
+  // we want to ensure that any $refs that point to another $ref are remapped to point to the final value
+  // let hadChange = true;
+  // while (hadChange) {
+  //   hadChange = false;
+  //   for (const entry of inventory) {
+  //     if (entry.$ref && typeof entry.$ref === "object" && "$ref" in entry.$ref) {
+  //       const resolved = inventory.find((e: InventoryEntry) => e.pathFromRoot === entry.$ref.$ref);
+  //       if (resolved) {
+  //         const resolvedPointsToAnotherRef =
+  //           resolved.$ref && typeof resolved.$ref === "object" && "$ref" in resolved.$ref;
+  //         if (resolvedPointsToAnotherRef && entry.$ref.$ref !== resolved.$ref.$ref) {
+  //           // console.log('Re-mapping $ref pointer "%s" at %s', entry.$ref.$ref, entry.pathFromRoot);
+  //           entry.$ref.$ref = resolved.$ref.$ref;
+  //           hadChange = true;
+  //         }
+  //       }
+  //     }
+  //   }
+  // }
+}
+
+/**
+ * TODO
+ */
+function findInInventory(inventory: InventoryEntry[], $refParent: any, $refKey: any) {
+  for (const existingEntry of inventory) {
+    if (existingEntry && existingEntry.parent === $refParent && existingEntry.key === $refKey) {
+      return existingEntry;
+    }
+  }
+  return undefined;
+}
+
+function removeFromInventory(inventory: InventoryEntry[], entry: any) {
+  const index = inventory.indexOf(entry);
+  inventory.splice(index, 1);
+}
+export default bundle;

package/lib/dereference.ts

@@ -0,0 +1,286 @@
+import $Ref from "./ref.js";
+import Pointer from "./pointer.js";
+import { ono } from "@jsdevtools/ono";
+import * as url from "./util/url.js";
+import type $Refs from "./refs.js";
+import type { DereferenceOptions, ParserOptions } from "./options.js";
+import type { JSONSchema } from "./types";
+import type { $RefParser } from "./index";
+import { TimeoutError } from "./util/errors";
+
+export default dereference;
+
+/**
+ * Crawls the JSON schema, finds all JSON references, and dereferences them.
+ * This method mutates the JSON schema object, replacing JSON references with their resolved value.
+ *
+ * @param parser
+ * @param options
+ */
+function dereference(
+  parser: $RefParser,
+  options: ParserOptions,
+) {
+  const start = Date.now();
+  // console.log('Dereferencing $ref pointers in %s', parser.$refs._root$Ref.path);
+  const dereferenced = crawl<JSONSchema>(
+    parser.schema,
+    parser.$refs._root$Ref.path!,
+    "#",
+    new Set(),
+    new Set(),
+    new Map(),
+    parser.$refs,
+    options,
+    start,
+  );
+  parser.$refs.circular = dereferenced.circular;
+  parser.schema = dereferenced.value;
+}
+
+/**
+ * Recursively crawls the given value, and dereferences any JSON references.
+ *
+ * @param obj - The value to crawl. If it's not an object or array, it will be ignored.
+ * @param path - The full path of `obj`, possibly with a JSON Pointer in the hash
+ * @param pathFromRoot - The path of `obj` from the schema root
+ * @param parents - An array of the parent objects that have already been dereferenced
+ * @param processedObjects - An array of all the objects that have already been processed
+ * @param dereferencedCache - An map of all the dereferenced objects
+ * @param $refs
+ * @param options
+ * @param startTime - The time when the dereferencing started
+ * @returns
+ */
+function crawl<S extends object = JSONSchema>(
+  obj: any,
+  path: string,
+  pathFromRoot: string,
+  parents: Set<any>,
+  processedObjects: Set<any>,
+  dereferencedCache: any,
+  $refs: $Refs<S>,
+  options: ParserOptions,
+  startTime: number,
+) {
+  let dereferenced;
+  const result = {
+    value: obj,
+    circular: false,
+  };
+
+  if (options && options.timeoutMs) {
+    if (Date.now() - startTime > options.timeoutMs) {
+      throw new TimeoutError(options.timeoutMs);
+    }
+  }
+  const derefOptions = (options.dereference || {}) as DereferenceOptions;
+  const isExcludedPath = derefOptions.excludedPathMatcher || (() => false);
+
+  if (derefOptions?.circular === "ignore" || !processedObjects.has(obj)) {
+    if (obj && typeof obj === "object" && !ArrayBuffer.isView(obj) && !isExcludedPath(pathFromRoot)) {
+      parents.add(obj);
+      processedObjects.add(obj);
+
+      if ($Ref.isAllowed$Ref(obj)) {
+        dereferenced = dereference$Ref(
+          obj,
+          path,
+          pathFromRoot,
+          parents,
+          processedObjects,
+          dereferencedCache,
+          $refs,
+          options,
+          startTime,
+        );
+        result.circular = dereferenced.circular;
+        result.value = dereferenced.value;
+      } else {
+        for (const key of Object.keys(obj)) {
+          const keyPath = Pointer.join(path, key);
+          const keyPathFromRoot = Pointer.join(pathFromRoot, key);
+
+          if (isExcludedPath(keyPathFromRoot)) {
+            continue;
+          }
+
+          const value = obj[key];
+          let circular = false;
+
+          if ($Ref.isAllowed$Ref(value)) {
+            dereferenced = dereference$Ref(
+              value,
+              keyPath,
+              keyPathFromRoot,
+              parents,
+              processedObjects,
+              dereferencedCache,
+              $refs,
+              options,
+              startTime,
+            );
+            circular = dereferenced.circular;
+            // Avoid pointless mutations; breaks frozen objects to no profit
+            if (obj[key] !== dereferenced.value) {
+              obj[key] = dereferenced.value;
+              derefOptions?.onDereference?.(value.$ref, obj[key], obj, key);
+            }
+          } else {
+            if (!parents.has(value)) {
+              dereferenced = crawl(
+                value,
+                keyPath,
+                keyPathFromRoot,
+                parents,
+                processedObjects,
+                dereferencedCache,
+                $refs,
+                options,
+                startTime,
+              );
+              circular = dereferenced.circular;
+              // Avoid pointless mutations; breaks frozen objects to no profit
+              if (obj[key] !== dereferenced.value) {
+                obj[key] = dereferenced.value;
+              }
+            } else {
+              circular = foundCircularReference(keyPath, $refs, options);
+            }
+          }
+
+          // Set the "isCircular" flag if this or any other property is circular
+          result.circular = result.circular || circular;
+        }
+      }
+
+      parents.delete(obj);
+    }
+  }
+
+  return result;
+}
+
+/**
+ * Dereferences the given JSON Reference, and then crawls the resulting value.
+ *
+ * @param $ref - The JSON Reference to resolve
+ * @param path - The full path of `$ref`, possibly with a JSON Pointer in the hash
+ * @param pathFromRoot - The path of `$ref` from the schema root
+ * @param parents - An array of the parent objects that have already been dereferenced
+ * @param processedObjects - An array of all the objects that have already been dereferenced
+ * @param dereferencedCache - An map of all the dereferenced objects
+ * @param $refs
+ * @param options
+ * @returns
+ */
+function dereference$Ref<S extends object = JSONSchema>(
+  $ref: any,
+  path: string,
+  pathFromRoot: string,
+  parents: Set<any>,
+  processedObjects: any,
+  dereferencedCache: any,
+  $refs: $Refs<S>,
+  options: ParserOptions,
+  startTime: number,
+) {
+  const $refPath = url.resolve(path, $ref.$ref);
+
+  const cache = dereferencedCache.get($refPath);
+  if (cache && !cache.circular) {
+    const refKeys = Object.keys($ref);
+    if (refKeys.length > 1) {
+      const extraKeys = {};
+      for (const key of refKeys) {
+        if (key !== "$ref" && !(key in cache.value)) {
+          // @ts-expect-error TS(7053): Element implicitly has an 'any' type because expre... Remove this comment to see the full error message
+          extraKeys[key] = $ref[key];
+        }
+      }
+      return {
+        circular: cache.circular,
+        value: Object.assign({}, cache.value, extraKeys),
+      };
+    }
+
+    return cache;
+  }
+
+  const pointer = $refs._resolve($refPath, path, options);
+
+  if (pointer === null) {
+    return {
+      circular: false,
+      value: null,
+    };
+  }
+
+  // Check for circular references
+  const directCircular = pointer.circular;
+  let circular = directCircular || parents.has(pointer.value);
+  if (circular) {
+    foundCircularReference(path, $refs, options);
+  }
+
+  // Dereference the JSON reference
+  let dereferencedValue = $Ref.dereference($ref, pointer.value);
+
+  // Crawl the dereferenced value (unless it's circular)
+  if (!circular) {
+    // Determine if the dereferenced value is circular
+    const dereferenced = crawl(
+      dereferencedValue,
+      pointer.path,
+      pathFromRoot,
+      parents,
+      processedObjects,
+      dereferencedCache,
+      $refs,
+      options,
+      startTime,
+    );
+    circular = dereferenced.circular;
+    dereferencedValue = dereferenced.value;
+  }
+
+  if (circular && !directCircular && options.dereference?.circular === "ignore") {
+    // The user has chosen to "ignore" circular references, so don't change the value
+    dereferencedValue = $ref;
+  }
+
+  if (directCircular) {
+    // The pointer is a DIRECT circular reference (i.e. it references itself).
+    // So replace the $ref path with the absolute path from the JSON Schema root
+    dereferencedValue.$ref = pathFromRoot;
+  }
+
+  const dereferencedObject = {
+    circular,
+    value: dereferencedValue,
+  };
+
+  // only cache if no extra properties than $ref
+  if (Object.keys($ref).length === 1) {
+    dereferencedCache.set($refPath, dereferencedObject);
+  }
+
+  return dereferencedObject;
+}
+
+/**
+ * Called when a circular reference is found.
+ * It sets the {@link $Refs#circular} flag, and throws an error if options.dereference.circular is false.
+ *
+ * @param keyPath - The JSON Reference path of the circular reference
+ * @param $refs
+ * @param options
+ * @returns - always returns true, to indicate that a circular reference was found
+ */
+function foundCircularReference(keyPath: any, $refs: any, options: any) {
+  $refs.circular = true;
+  if (!options.dereference.circular) {
+    throw ono.reference(`Circular $ref pointer found at ${keyPath}`);
+  }
+  return true;
+}