@hey-api/json-schema-ref-parser 1.3.0 → 1.4.0

package/src/bundle.ts

@@ -92,7 +92,7 @@ const getContainerTypeFromPath = (
 };
 
 /**
- * Inventories the given JSON Reference (i.e. records detailed information about it so we can
+ * 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.
  */
 const inventory$Ref = <S extends object = JSONSchema>({
@@ -157,11 +157,31 @@ const inventory$Ref = <S extends object = JSONSchema>({
       pointer = $refs._resolve($refPath, pathFromRoot, options);
     } catch (error) {
       if (error instanceof MissingPointerError) {
-        // Log warning but continue - common in complex schema ecosystems
-        console.warn(`Skipping unresolvable $ref: ${$refPath}`);
-        return;
+        // The ref couldn't be resolved in the target file. This commonly
+        // happens when a wrapper file redirects via $ref to a versioned
+        // file, and the bundler's crawl path retains the wrapper URL.
+        // Try resolving the hash fragment against other files in $refs
+        // that might contain the target schema.
+        const hash = url.getHash($refPath);
+        if (hash) {
+          const baseFile = url.stripHash($refPath);
+          for (const filePath of Object.keys($refs._$refs)) {
+            if (filePath === baseFile) continue;
+            try {
+              pointer = $refs._resolve(filePath + hash, pathFromRoot, options);
+              if (pointer) break;
+            } catch {
+              // try next file
+            }
+          }
+        }
+        if (!pointer) {
+          console.warn(`Skipping unresolvable $ref: ${$refPath}`);
+          return;
+        }
+      } else {
+        throw error;
       }
-      throw error; // Re-throw unexpected errors
     }
 
     if (pointer) {
@@ -193,10 +213,10 @@ const inventory$Ref = <S extends object = JSONSchema>({
   }
 
   const newEntry: InventoryEntry = {
-    $ref, // The JSON Reference (e.g. {$ref: string})
-    circular: pointer.circular, // Is this $ref pointer DIRECTLY circular? (i.e. it references itself)
+    $ref, // The JSON Reference (e.g., {$ref: string})
+    circular: pointer.circular, // Is this $ref pointer DIRECTLY circular? (i.e., it references itself)
     depth, // How far from the JSON Schema root is this $ref pointer?
-    extended, // Does this $ref extend its resolved value? (i.e. it has extra properties, in addition to "$ref")
+    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?
     file, // The file that the $ref pointer resolves to
     hash, // The hash within `file` that the $ref pointer resolves to
@@ -217,8 +237,19 @@ const inventory$Ref = <S extends object = JSONSchema>({
   inventory.push(newEntry);
   inventoryLookup.add(newEntry);
 
-  // Recursively crawl the resolved value
+  // Recursively crawl the resolved value.
+  // When the resolution followed a $ref chain to a different file,
+  // use the resolved file as the base path so that local $ref values
+  // (e.g., #/components/schemas/SiblingSchema) inside the resolved
+  // value resolve against the correct file.
   if (!existingEntry || external) {
+    let crawlPath = pointer.path;
+
+    const originalFile = url.stripHash($refPath);
+    if (file !== originalFile) {
+      crawlPath = file + url.getHash(pointer.path);
+    }
+
     crawl({
       $refs,
       indirections: indirections + 1,
@@ -227,7 +258,7 @@ const inventory$Ref = <S extends object = JSONSchema>({
       key: null,
       options,
       parent: pointer.value,
-      path: pointer.path,
+      path: crawlPath,
       pathFromRoot,
       resolvedRefs,
       visitedObjects,
@@ -414,8 +445,8 @@ function remap(parser: $RefParser, inventory: Array<InventoryEntry>) {
   const ensureContainer = (
     type: 'schemas' | 'parameters' | 'requestBodies' | 'responses' | 'headers',
   ) => {
-    const isOas3 = !!(root && typeof root === 'object' && typeof root.openapi === 'string');
-    const isOas2 = !!(root && typeof root === 'object' && typeof root.swagger === 'string');
+    const isOas3 = Boolean(root && typeof root === 'object' && typeof root.openapi === 'string');
+    const isOas2 = Boolean(root && typeof root === 'object' && typeof root.swagger === 'string');
 
     if (isOas3) {
       if (!root.components || typeof root.components !== 'object') {
@@ -539,7 +570,7 @@ function remap(parser: $RefParser, inventory: Array<InventoryEntry>) {
     }
 
     // Keep internal refs internal. However, if the $ref extends the resolved value
-    // (i.e. it has additional properties in addition to "$ref"), then we must
+    // (i.e., it has additional properties in addition to "$ref"), then we must
     // preserve the original $ref rather than rewriting it to the resolved hash.
     if (!entry.external) {
       if (!entry.extended && entry.$ref && typeof entry.$ref === 'object') {
@@ -586,7 +617,22 @@ function remap(parser: $RefParser, inventory: Array<InventoryEntry>) {
       } catch {
         // Ignore errors
       }
-      const proposed = `${proposedBase}_${lastToken(entry.hash)}`;
+
+      // Try without prefix first (cleaner names)
+      const schemaName = lastToken(entry.hash);
+      let proposed = schemaName;
+
+      // Check if this name would conflict with existing schemas from other files
+      if (!usedNamesByObj.has(container)) {
+        usedNamesByObj.set(container, new Set<string>(Object.keys(container || {})));
+      }
+      const used = usedNamesByObj.get(container)!;
+
+      // If the name is already used, add the file prefix
+      if (used.has(proposed)) {
+        proposed = `${proposedBase}_${schemaName}`;
+      }
+
       defName = uniqueName(container, proposed);
       namesForPrefix.set(targetKey, defName);
       // Store the resolved value under the container

package/src/dereference.ts

@@ -226,7 +226,7 @@ function dereference$Ref<S extends object = JSONSchema>(
   }
 
   if (directCircular) {
-    // The pointer is a DIRECT circular reference (i.e. it references itself).
+    // 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;
   }

package/src/index.ts

@@ -117,12 +117,12 @@ export class $RefParser {
 
     await resolveExternal(this, this.options);
     const errors = JSONParserErrorGroup.getParserErrors(this);
-    if (errors.length > 0) {
+    if (errors.length) {
       throw new JSONParserErrorGroup(this);
     }
     _bundle(this, this.options);
     const errors2 = JSONParserErrorGroup.getParserErrors(this);
-    if (errors2.length > 0) {
+    if (errors2.length) {
       throw new JSONParserErrorGroup(this);
     }
     return this.schema!;
@@ -148,14 +148,14 @@ export class $RefParser {
 
     await resolveExternal(this, this.options);
     const errors = JSONParserErrorGroup.getParserErrors(this);
-    if (errors.length > 0) {
+    if (errors.length) {
       throw new JSONParserErrorGroup(this);
     }
     _bundle(this, this.options);
     // Merged root is ready for bundling
 
     const errors2 = JSONParserErrorGroup.getParserErrors(this);
-    if (errors2.length > 0) {
+    if (errors2.length) {
       throw new JSONParserErrorGroup(this);
     }
     return this.schema!;
@@ -297,7 +297,7 @@ export class $RefParser {
 
   public mergeMany(): JSONSchema {
     const schemas = this.schemaMany || [];
-    if (schemas.length === 0) {
+    if (!schemas.length) {
       throw ono('mergeMany called with no schemas. Did you run parseMany?');
     }
 
@@ -335,7 +335,7 @@ export class $RefParser {
         }
       }
     }
-    if (Object.keys(infoAccumulator).length > 0) {
+    if (Object.keys(infoAccumulator).length) {
       merged.info = infoAccumulator;
     }
 
@@ -356,7 +356,7 @@ export class $RefParser {
         }
       }
     }
-    if (servers.length > 0) {
+    if (servers.length) {
       merged.servers = servers;
     }
 
@@ -527,24 +527,48 @@ export class $RefParser {
         }
       }
 
+      const HTTP_METHODS = new Set([
+        'delete',
+        'get',
+        'head',
+        'options',
+        'patch',
+        'post',
+        'put',
+        'trace',
+      ]);
+
       const srcPaths = (schema.paths || {}) as Record<string, any>;
       for (const [p, item] of Object.entries(srcPaths)) {
-        let targetPath = p;
         if (merged.paths[p]) {
-          const trimmed = p.startsWith('/') ? p.substring(1) : p;
-          targetPath = `/${prefix}/${trimmed}`;
+          const newMethods = Object.keys(item as object).filter((k) => HTTP_METHODS.has(k));
+          const hasMethodConflict = newMethods.some((m) => merged.paths[p][m] !== undefined);
+          const rewritten = cloneAndRewrite(
+            item,
+            refMap,
+            tagMap,
+            prefix,
+            url.stripHash(sourcePath),
+          );
+          if (hasMethodConflict) {
+            const trimmed = p.startsWith('/') ? p.substring(1) : p;
+            merged.paths[`/${prefix}/${trimmed}`] = rewritten;
+          } else {
+            Object.assign(merged.paths[p], rewritten);
+          }
+        } else {
+          merged.paths[p] = cloneAndRewrite(
+            item,
+            refMap,
+            tagMap,
+            prefix,
+            url.stripHash(sourcePath),
+          );
         }
-        merged.paths[targetPath] = cloneAndRewrite(
-          item,
-          refMap,
-          tagMap,
-          prefix,
-          url.stripHash(sourcePath),
-        );
       }
     }
 
-    if (tags.length > 0) {
+    if (tags.length) {
       merged.tags = tags;
     }
 
@@ -561,3 +585,17 @@ export class $RefParser {
 
 export { sendRequest } from './resolvers/url';
 export type { JSONSchema } from './types';
+export type { JSONParserErrorType } from './util/errors';
+export {
+  InvalidPointerError,
+  isHandledError,
+  JSONParserError,
+  JSONParserErrorGroup,
+  MissingPointerError,
+  normalizeError,
+  ParserError,
+  ResolverError,
+  TimeoutError,
+  UnmatchedParserError,
+  UnmatchedResolverError,
+} from './util/errors';

package/src/parsers/yaml.ts

@@ -1,5 +1,4 @@
-import yaml from 'js-yaml';
-import { JSON_SCHEMA } from 'js-yaml';
+import { parse } from 'yaml';
 
 import type { FileInfo, JSONSchema, Plugin } from '../types';
 import { ParserError } from '../util/errors';
@@ -16,8 +15,7 @@ export const yamlParser: Plugin = {
     }
 
     try {
-      const yamlSchema = yaml.load(data, { schema: JSON_SCHEMA }) as JSONSchema;
-      return yamlSchema;
+      return parse(data) as JSONSchema;
     } catch (error: any) {
       throw new ParserError(error?.message || 'Parser Error', file.url);
     }

package/src/pointer.ts

@@ -140,7 +140,7 @@ class Pointer<S extends object = JSONSchema> {
       }
     }
 
-    if (errors.length > 0) {
+    if (errors.length) {
       throw errors.length === 1
         ? errors[0]
         : new AggregateError(errors, 'Multiple missing pointer errors');
@@ -171,7 +171,7 @@ class Pointer<S extends object = JSONSchema> {
     const tokens = Pointer.parse(this.path);
     let token;
 
-    if (tokens.length === 0) {
+    if (!tokens.length) {
       // There are no tokens, replace the entire object with the new value
       this.value = value;
       return value;
@@ -205,7 +205,7 @@ class Pointer<S extends object = JSONSchema> {
   /**
    * Parses a JSON pointer (or a path containing a JSON pointer in the hash)
    * and returns an array of the pointer's tokens.
-   * (e.g. "schema.json#/definitions/person/name" => ["definitions", "person", "name"])
+   * (e.g., "schema.json#/definitions/person/name" => ["definitions", "person", "name"])
    *
    * The pointer is parsed according to RFC 6901
    * {@link https://tools.ietf.org/html/rfc6901#section-3}
@@ -244,8 +244,8 @@ class Pointer<S extends object = JSONSchema> {
   /**
    * Creates a JSON pointer path, by joining one or more tokens to a base path.
    *
-   * @param base - The base path (e.g. "schema.json#/definitions/person")
-   * @param tokens - The token(s) to append (e.g. ["name", "first"])
+   * @param base - The base path (e.g., "schema.json#/definitions/person")
+   * @param tokens - The token(s) to append (e.g., ["name", "first"])
    * @returns
    */
   static join(base: string, tokens: string | string[]) {

package/src/ref.ts

@@ -46,7 +46,7 @@ class $Ref<S extends object = JSONSchema> {
   $refs: $Refs<S>;
 
   /**
-   * Indicates the type of {@link $Ref#path} (e.g. "file", "http", etc.)
+   * Indicates the type of {@link $Ref#path} (e.g., "file", "http", etc.)
    */
   pathType: string | unknown;
 
@@ -152,7 +152,7 @@ class $Ref<S extends object = JSONSchema> {
       value !== null &&
       '$ref' in value &&
       typeof value.$ref === 'string' &&
-      value.$ref.length > 0
+      Boolean(value.$ref.length)
     );
   }
 

package/src/refs.ts

@@ -224,7 +224,7 @@ function getPaths<S extends object = JSONSchema>($refs: $RefsMap<S>, types: stri
 
   // Filter the paths by type
   types = Array.isArray(types[0]) ? types[0] : Array.prototype.slice.call(types);
-  if (types.length > 0 && types[0]) {
+  if (types.length && types[0]) {
     paths = paths.filter((key) => types.includes($refs[key]!.pathType as string));
   }