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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hey-api/json-schema-ref-parser",
-  "version": "1.3.0",
+  "version": "1.3.1",
   "description": "Parse, Resolve, and Dereference JSON Schema $ref pointers",
   "keywords": [
     "$ref",

package/src/__tests__/__snapshots__/circular-ref-with-description.json

@@ -0,0 +1,11 @@
+{
+  "schemas": {
+    "Foo": {
+      "$ref": "#/schemas/Bar"
+    },
+    "Bar": {
+      "description": "ok",
+      "$ref": "#/schemas/Foo"
+    }
+  }
+}

package/src/__tests__/__snapshots__/main-with-external-siblings.json

@@ -0,0 +1,78 @@
+{
+  "openapi": "3.0.0",
+  "info": {
+    "title": "Test API",
+    "version": "1.0.0"
+  },
+  "paths": {
+    "/resolution": {
+      "get": {
+        "summary": "Get resolution step",
+        "responses": {
+          "200": {
+            "description": "Success",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ResolutionStep"
+                }
+              }
+            }
+          }
+        }
+      }
+    },
+    "/action": {
+      "get": {
+        "summary": "Get action info",
+        "responses": {
+          "200": {
+            "description": "Success",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ActionInfo"
+                }
+              }
+            }
+          }
+        }
+      }
+    }
+  },
+  "components": {
+    "schemas": {
+      "ActionInfo": {
+        "type": "object",
+        "properties": {
+          "ActionId": {
+            "type": "string"
+          }
+        }
+      },
+      "ResolutionStep": {
+        "type": "object",
+        "properties": {
+          "ResolutionType": {
+            "oneOf": [
+              {
+                "$ref": "#/components/schemas/ResolutionType"
+              }
+            ]
+          },
+          "ActionName": {
+            "type": "string"
+          }
+        }
+      },
+      "ResolutionType": {
+        "type": "string",
+        "enum": [
+          "ContactVendor",
+          "ResetToDefaults",
+          "RetryOperation"
+        ]
+      }
+    }
+  }
+}

package/src/__tests__/__snapshots__/multiple-refs.json

@@ -0,0 +1,48 @@
+{
+  "paths": {
+    "/test1/{pathId}": {
+      "get": {
+        "summary": "First endpoint using the same pathId schema",
+        "parameters": [
+          {
+            "$ref": "#/components/parameters/pathId"
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "Test 1 response"
+          }
+        }
+      }
+    },
+    "/test2/{pathId}": {
+      "get": {
+        "summary": "Second endpoint using the same pathId schema",
+        "parameters": [
+          {
+            "$ref": "#/components/parameters/pathId"
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "Test 2 response"
+          }
+        }
+      }
+    }
+  },
+  "components": {
+    "parameters": {
+      "pathId": {
+        "name": "pathId",
+        "in": "path",
+        "required": true,
+        "schema": {
+          "type": "string",
+          "format": "uuid",
+          "description": "Unique identifier for the path"
+        }
+      }
+    }
+  }
+}

package/src/__tests__/__snapshots__/redfish-like.json

@@ -0,0 +1,87 @@
+{
+  "openapi": "3.0.0",
+  "info": {
+    "title": "Redfish-like API",
+    "version": "1.0.0",
+    "description": "Test API simulating Redfish structure with versioned schemas"
+  },
+  "paths": {
+    "/redfish/v1/Systems": {
+      "get": {
+        "summary": "Get Systems",
+        "responses": {
+          "200": {
+            "description": "Success",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ResolutionStep_v1_0_1_ResolutionStep"
+                }
+              }
+            }
+          },
+          "default": {
+            "description": "Error"
+          }
+        }
+      }
+    },
+    "/redfish/v1/Actions": {
+      "post": {
+        "summary": "Submit Action",
+        "responses": {
+          "200": {
+            "description": "Success",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ResolutionStep_v1_0_1_ActionParameters"
+                }
+              }
+            }
+          }
+        }
+      }
+    }
+  },
+  "components": {
+    "schemas": {
+      "ResolutionStep_v1_0_1_ActionParameters": {
+        "type": "object",
+        "properties": {
+          "ActionId": {
+            "type": "string"
+          },
+          "ActionType": {
+            "$ref": "#/components/schemas/ResolutionStep_v1_0_1_ResolutionType"
+          }
+        }
+      },
+      "ResolutionStep_v1_0_1_ResolutionStep": {
+        "type": "object",
+        "properties": {
+          "ResolutionType": {
+            "oneOf": [
+              {
+                "$ref": "#/components/schemas/ResolutionStep_v1_0_1_ResolutionType"
+              }
+            ]
+          },
+          "ActionName": {
+            "type": "string",
+            "description": "Name of the action"
+          }
+        }
+      },
+      "ResolutionStep_v1_0_1_ResolutionType": {
+        "type": "string",
+        "enum": [
+          "ContactVendor",
+          "ResetToDefaults",
+          "RetryOperation"
+        ],
+        "description": "Types of resolution actions"
+      }
+    }
+  }
+}

package/src/__tests__/bundle.test.ts

@@ -1,8 +1,38 @@
+import fs from 'node:fs';
 import path from 'node:path';
+import { fileURLToPath } from 'node:url';
 
 import { $RefParser } from '..';
 import { getSpecsPath } from './utils';
 
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+
+const getSnapshotsPath = () => path.join(__dirname, '__snapshots__');
+const getTempSnapshotsPath = () => path.join(__dirname, '.gen', 'snapshots');
+
+/**
+ * Helper function to compare a bundled schema with a snapshot file.
+ * Handles writing the schema to a temp file and comparing with the snapshot.
+ *
+ * @param schema - The bundled schema to compare
+ * @param snapshotName - The name of the snapshot file (e.g., 'circular-ref-with-description.json')
+ */
+const expectBundledSchemaToMatchSnapshot = async (schema: unknown, snapshotName: string) => {
+  const outputPath = path.join(getTempSnapshotsPath(), snapshotName);
+  const snapshotPath = path.join(getSnapshotsPath(), snapshotName);
+
+  // Ensure directory exists
+  fs.mkdirSync(path.dirname(outputPath), { recursive: true });
+
+  // Write the bundled result
+  const content = JSON.stringify(schema, null, 2);
+  fs.writeFileSync(outputPath, content);
+
+  // Compare with snapshot
+  await expect(content).toMatchFileSnapshot(snapshotPath);
+};
+
 describe('bundle', () => {
   it('handles circular reference with description', async () => {
     const refParser = new $RefParser();
@@ -12,17 +42,8 @@ describe('bundle', () => {
       'circular-ref-with-description.json',
     );
     const schema = await refParser.bundle({ pathOrUrlOrSchema });
-    expect(schema).toEqual({
-      schemas: {
-        Bar: {
-          $ref: '#/schemas/Foo',
-          description: 'ok',
-        },
-        Foo: {
-          $ref: '#/schemas/Bar',
-        },
-      },
-    });
+
+    await expectBundledSchemaToMatchSnapshot(schema, 'circular-ref-with-description.json');
   });
 
   it('bundles multiple references to the same file correctly', async () => {
@@ -32,28 +53,341 @@ describe('bundle', () => {
       'json-schema-ref-parser',
       'multiple-refs.json',
     );
-    const schema = (await refParser.bundle({ pathOrUrlOrSchema })) as any;
-
-    // Both parameters should now be $ref to the same internal definition
-    const firstParam = schema.paths['/test1/{pathId}'].get.parameters[0];
-    const secondParam = schema.paths['/test2/{pathId}'].get.parameters[0];
-
-    // The $ref should match the output structure in file_context_0
-    expect(firstParam.$ref).toBe('#/components/parameters/path-parameter_pathId');
-    expect(secondParam.$ref).toBe('#/components/parameters/path-parameter_pathId');
-
-    // The referenced parameter should exist and match the expected structure
-    expect(schema.components).toBeDefined();
-    expect(schema.components.parameters).toBeDefined();
-    expect(schema.components.parameters['path-parameter_pathId']).toEqual({
-      in: 'path',
-      name: 'pathId',
-      required: true,
-      schema: {
-        description: 'Unique identifier for the path',
-        format: 'uuid',
-        type: 'string',
-      },
+    const schema = await refParser.bundle({ pathOrUrlOrSchema });
+
+    await expectBundledSchemaToMatchSnapshot(schema, 'multiple-refs.json');
+  });
+
+  it('hoists sibling schemas from external files', async () => {
+    const refParser = new $RefParser();
+    const pathOrUrlOrSchema = path.join(
+      getSpecsPath(),
+      'json-schema-ref-parser',
+      'main-with-external-siblings.json',
+    );
+    const schema = await refParser.bundle({ pathOrUrlOrSchema });
+
+    await expectBundledSchemaToMatchSnapshot(schema, 'main-with-external-siblings.json');
+  });
+
+  it('hoists sibling schemas from YAML files with versioned names (Redfish-like)', async () => {
+    const refParser = new $RefParser();
+    const pathOrUrlOrSchema = path.join(
+      getSpecsPath(),
+      'json-schema-ref-parser',
+      'redfish-like.yaml',
+    );
+    const schema = await refParser.bundle({ pathOrUrlOrSchema });
+
+    await expectBundledSchemaToMatchSnapshot(schema, 'redfish-like.json');
+  });
+
+  describe('sibling schema resolution', () => {
+    const specsDir = path.join(getSpecsPath(), 'json-schema-ref-parser');
+
+    const findSchemaByValue = (
+      schemas: Record<string, any>,
+      predicate: (value: any) => boolean,
+    ): [string, any] | undefined => {
+      for (const [name, value] of Object.entries(schemas)) {
+        if (predicate(value)) {
+          return [name, value];
+        }
+      }
+      return undefined;
+    };
+
+    it('hoists sibling schemas through a bare $ref wrapper chain', async () => {
+      const refParser = new $RefParser();
+      const pathOrUrlOrSchema = path.join(specsDir, 'sibling-schema-root.json');
+      const schema = (await refParser.bundle({ pathOrUrlOrSchema })) as any;
+
+      expect(schema.components).toBeDefined();
+      expect(schema.components.schemas).toBeDefined();
+
+      const schemas = schema.components.schemas;
+
+      const mainSchema = findSchemaByValue(
+        schemas,
+        (v) => v.type === 'object' && v.properties?.name,
+      );
+      expect(mainSchema).toBeDefined();
+      const [mainName, mainValue] = mainSchema!;
+      expect(mainValue.type).toBe('object');
+      expect(mainValue.properties.name).toEqual({ type: 'string' });
+
+      const enumSchema = findSchemaByValue(
+        schemas,
+        (v) => Array.isArray(v.enum) && v.enum.includes('active'),
+      );
+      expect(enumSchema).toBeDefined();
+      const [enumName, enumValue] = enumSchema!;
+      expect(enumValue.type).toBe('string');
+      expect(enumValue.enum).toEqual(['active', 'inactive', 'pending']);
+
+      // The main schema's status property should reference the hoisted enum
+      expect(mainValue.properties.status.$ref).toBe(`#/components/schemas/${enumName}`);
+
+      // The root path's schema ref should point to the hoisted main schema
+      const rootRef = schema.paths['/test'].get.responses['200'].content['application/json'].schema;
+      expect(rootRef.$ref).toBe(`#/components/schemas/${mainName}`);
+    });
+
+    it('hoists sibling schemas through an extended $ref wrapper chain', async () => {
+      const refParser = new $RefParser();
+      const pathOrUrlOrSchema = path.join(specsDir, 'sibling-schema-extended-root.json');
+      const warnSpy = vi.spyOn(console, 'warn').mockImplementation(() => {});
+
+      try {
+        const schema = (await refParser.bundle({ pathOrUrlOrSchema })) as any;
+
+        expect(schema.components).toBeDefined();
+        expect(schema.components.schemas).toBeDefined();
+
+        const schemas = schema.components.schemas;
+
+        // The main schema should be hoisted (with the extra description merged in)
+        const mainSchema = findSchemaByValue(
+          schemas,
+          (v) =>
+            v.description === 'Wrapper that extends the versioned schema' ||
+            (v.type === 'object' && v.properties?.name),
+        );
+        expect(mainSchema).toBeDefined();
+
+        // The sibling enum must also be hoisted (this was the bug — it was lost before the fix)
+        const enumSchema = findSchemaByValue(
+          schemas,
+          (v) => Array.isArray(v.enum) && v.enum.includes('active'),
+        );
+        expect(enumSchema).toBeDefined();
+        const [, enumValue] = enumSchema!;
+        expect(enumValue.type).toBe('string');
+        expect(enumValue.enum).toEqual(['active', 'inactive', 'pending']);
+
+        // No "Skipping unresolvable $ref" warnings should have been emitted
+        const unresolvableWarnings = warnSpy.mock.calls.filter(
+          (args) => typeof args[0] === 'string' && args[0].includes('Skipping unresolvable $ref'),
+        );
+        expect(unresolvableWarnings).toHaveLength(0);
+      } finally {
+        warnSpy.mockRestore();
+      }
+    });
+
+    it('hoists sibling schemas from a direct reference (no wrapper)', async () => {
+      const refParser = new $RefParser();
+      const pathOrUrlOrSchema = path.join(specsDir, 'sibling-schema-direct-root.json');
+      const schema = (await refParser.bundle({ pathOrUrlOrSchema })) as any;
+
+      expect(schema.components).toBeDefined();
+      expect(schema.components.schemas).toBeDefined();
+
+      const schemas = schema.components.schemas;
+
+      const mainSchema = findSchemaByValue(
+        schemas,
+        (v) => v.type === 'object' && v.properties?.name,
+      );
+      expect(mainSchema).toBeDefined();
+
+      const enumSchema = findSchemaByValue(
+        schemas,
+        (v) => Array.isArray(v.enum) && v.enum.includes('active'),
+      );
+      expect(enumSchema).toBeDefined();
+      const [enumName, enumValue] = enumSchema!;
+      expect(enumValue.enum).toEqual(['active', 'inactive', 'pending']);
+
+      const [, mainValue] = mainSchema!;
+      expect(mainValue.properties.status.$ref).toBe(`#/components/schemas/${enumName}`);
+    });
+
+    it('hoists multiple sibling schemas through an extended wrapper', async () => {
+      const refParser = new $RefParser();
+      const pathOrUrlOrSchema = path.join(specsDir, 'sibling-schema-multi-root.json');
+      const warnSpy = vi.spyOn(console, 'warn').mockImplementation(() => {});
+
+      try {
+        const schema = (await refParser.bundle({ pathOrUrlOrSchema })) as any;
+
+        expect(schema.components).toBeDefined();
+        expect(schema.components.schemas).toBeDefined();
+
+        const schemas = schema.components.schemas;
+
+        const mainSchema = findSchemaByValue(
+          schemas,
+          (v) => v.type === 'object' && v.properties?.health,
+        );
+        expect(mainSchema).toBeDefined();
+
+        const statusEnum = findSchemaByValue(
+          schemas,
+          (v) => Array.isArray(v.enum) && v.enum.includes('enabled'),
+        );
+        expect(statusEnum).toBeDefined();
+        expect(statusEnum![1].enum).toEqual(['enabled', 'disabled', 'standby']);
+
+        const healthEnum = findSchemaByValue(
+          schemas,
+          (v) => Array.isArray(v.enum) && v.enum.includes('ok'),
+        );
+        expect(healthEnum).toBeDefined();
+        expect(healthEnum![1].enum).toEqual(['ok', 'warning', 'critical']);
+
+        const [, mainValue] = mainSchema!;
+        expect(mainValue.properties.status.$ref).toBe(`#/components/schemas/${statusEnum![0]}`);
+        expect(mainValue.properties.health.$ref).toBe(`#/components/schemas/${healthEnum![0]}`);
+
+        const unresolvableWarnings = warnSpy.mock.calls.filter(
+          (args) => typeof args[0] === 'string' && args[0].includes('Skipping unresolvable $ref'),
+        );
+        expect(unresolvableWarnings).toHaveLength(0);
+      } finally {
+        warnSpy.mockRestore();
+      }
+    });
+
+    it('handles multiple external files with same-named sibling schemas', async () => {
+      const refParser = new $RefParser();
+      const pathOrUrlOrSchema = path.join(specsDir, 'sibling-schema-collision-root.json');
+      const warnSpy = vi.spyOn(console, 'warn').mockImplementation(() => {});
+
+      try {
+        const schema = (await refParser.bundle({ pathOrUrlOrSchema })) as any;
+
+        expect(schema.components).toBeDefined();
+        expect(schema.components.schemas).toBeDefined();
+
+        const schemas = schema.components.schemas;
+        const schemaNames = Object.keys(schemas);
+
+        const mainSchemaKey = schemaNames.find((name) => name.includes('MainSchema'));
+        const otherSchemaKey = schemaNames.find((name) => name.includes('OtherSchema'));
+
+        expect(mainSchemaKey).toBeDefined();
+        expect(otherSchemaKey).toBeDefined();
+
+        const statusSchemas = schemaNames.filter((name) => name.includes('Status'));
+        expect(statusSchemas.length).toBeGreaterThanOrEqual(2);
+
+        const statusValues = statusSchemas.map((name) => schemas[name]);
+        const stringStatus = statusValues.find((v: any) => v.type === 'string');
+        const integerStatus = statusValues.find((v: any) => v.type === 'integer');
+
+        expect(stringStatus).toBeDefined();
+        expect(integerStatus).toBeDefined();
+        expect(stringStatus!.enum).toEqual(['active', 'inactive']);
+        expect(integerStatus!.enum).toEqual([0, 1, 2]);
+
+        const mainSchemaValue = schemas[mainSchemaKey!];
+        const mainStatusRef = mainSchemaValue.properties.status.$ref;
+        expect(mainStatusRef).toMatch(/^#\/components\/schemas\/.*Status/);
+
+        const referencedStatus = schemas[mainStatusRef.replace('#/components/schemas/', '')];
+        expect(referencedStatus).toBeDefined();
+        expect(referencedStatus.type).toBe('string');
+        expect(referencedStatus.enum).toEqual(['active', 'inactive']);
+
+        const otherSchemaValue = schemas[otherSchemaKey!];
+        const otherStatusRef = otherSchemaValue.properties.code.$ref;
+        expect(otherStatusRef).toMatch(/^#\/components\/schemas\/.*Status/);
+
+        const referencedOtherStatus = schemas[otherStatusRef.replace('#/components/schemas/', '')];
+        expect(referencedOtherStatus).toBeDefined();
+        expect(referencedOtherStatus.type).toBe('integer');
+        expect(referencedOtherStatus.enum).toEqual([0, 1, 2]);
+
+        const unresolvableWarnings = warnSpy.mock.calls.filter(
+          (args) => typeof args[0] === 'string' && args[0].includes('Skipping unresolvable $ref'),
+        );
+        expect(unresolvableWarnings).toHaveLength(0);
+      } finally {
+        warnSpy.mockRestore();
+      }
+    });
+  });
+
+  describe('mergeMany', () => {
+    it('merges paths with non-conflicting methods under the same path', async () => {
+      const refParser = new $RefParser();
+      const spec1 = {
+        info: { title: 'Spec 1', version: '1.0.0' },
+        paths: {
+          '/pet/{petId}': {
+            post: {
+              operationId: 'updatePetWithForm',
+              responses: { '405': { description: 'Invalid input' } },
+            },
+          },
+        },
+        swagger: '2.0',
+      };
+      const spec2 = {
+        info: { title: 'Spec 2', version: '1.0.0' },
+        paths: {
+          '/pet/{petId}': {
+            delete: {
+              operationId: 'deletePet',
+              responses: {
+                '400': { description: 'Invalid ID supplied' },
+                '404': { description: 'Pet not found' },
+              },
+            },
+          },
+        },
+        swagger: '2.0',
+      };
+
+      const merged = (await refParser.bundleMany({ pathOrUrlOrSchemas: [spec1, spec2] })) as any;
+
+      // Both methods should be under the same path (no prefix added)
+      expect(merged.paths['/pet/{petId}']).toBeDefined();
+      expect(merged.paths['/pet/{petId}'].post).toBeDefined();
+      expect(merged.paths['/pet/{petId}'].delete).toBeDefined();
+
+      // No prefixed path should be created
+      const pathKeys = Object.keys(merged.paths);
+      expect(pathKeys).toHaveLength(1);
+    });
+
+    it('adds prefix to path when HTTP methods conflict', async () => {
+      const refParser = new $RefParser();
+      const spec1 = {
+        info: { title: 'Spec 1', version: '1.0.0' },
+        paths: {
+          '/pet/{petId}': {
+            get: {
+              operationId: 'getPetById',
+              responses: { '200': { description: 'OK' } },
+            },
+          },
+        },
+        swagger: '2.0',
+      };
+      const spec2 = {
+        info: { title: 'Spec 2', version: '1.0.0' },
+        paths: {
+          '/pet/{petId}': {
+            get: {
+              operationId: 'getPet',
+              responses: { '200': { description: 'Success' } },
+            },
+          },
+        },
+        swagger: '2.0',
+      };
+
+      const merged = (await refParser.bundleMany({ pathOrUrlOrSchemas: [spec1, spec2] })) as any;
+
+      // The conflicting path should be prefixed
+      const pathKeys = Object.keys(merged.paths);
+      expect(pathKeys).toHaveLength(2);
+      expect(merged.paths['/pet/{petId}']).toBeDefined();
+      const prefixedKey = pathKeys.find((k) => k !== '/pet/{petId}');
+      expect(prefixedKey).toBeDefined();
+      expect(merged.paths[prefixedKey!].get).toBeDefined();
     });
   });
 });