@scalar/openapi-parser 0.10.14 → 0.10.15

package/CHANGELOG.md

@@ -1,5 +1,12 @@
 # @scalar/openapi-parser
 
+## 0.10.15
+
+### Patch Changes
+
+- 4abe4f8: feat: add resolveInternalRefs to bundle documents
+- 4abe4f8: feat: external $ref’s (absolute and relative URLs)
+
 ## 0.10.14
 
 ### Patch Changes

package/README.md

@@ -239,11 +239,33 @@ import { fetchUrls } from '@scalar/openapi-parser/plugins/fetch-urls'
 const { filesystem } = await load(
   'https://cdn.jsdelivr.net/npm/@scalar/galaxy/dist/latest.yaml',
   {
+    // Optional: If you directly pass an OpenAPI (not an URL), let it know where the content came from
+    // That’s the only way we can resolve external references, if they are relative.
+    source: 'https://cdn.jsdelivr.net/npm/@scalar/galaxy/dist/latest.yaml'
     plugins: [fetchUrls()],
   },
 )
 ```
 
+#### Bundle external references
+
+By default, `dereference` tries to resolve both internal and external references. You can disable resolving internal references by setting `resolveInternalRefs` to `false`:
+
+```ts
+import { dereference, load } from '@scalar/openapi-parser'
+import { fetchUrls } from '@scalar/openapi-parser/plugins/fetch-urls'
+
+// Load a file and all referenced files
+const { filesystem } = await load('https://cdn.jsdelivr.net/npm/@scalar/galaxy/dist/latest.yaml', {
+  plugins: [fetchUrls()],
+})
+
+const result = await dereference(filesystem, {
+  // Skips internal references like `$ref: '#/components/schemas/foobar'`
+  resolveInternalRefs: false,
+})
+```
+
 #### Intercept HTTP requests
 
 If you’re using the package in a browser environment, you may run into CORS issues when fetching from URLs. You can intercept the requests, for example to use a proxy, though:

package/dist/lib/Validator/Validator.js

@@ -27,7 +27,7 @@ class Validator {
      */
     async validate(filesystem, options) {
         const entrypoint = filesystem.find((file) => file.isEntrypoint);
-        const specification = entrypoint?.specification;
+        const specification = entrypoint?.content;
         // TODO: How does this work with a filesystem?
         this.specification = specification;
         // TODO: defaulting info.version to keep parser compatible with the previous one

package/dist/plugins/fetch-urls/fetchUrls.d.ts

@@ -12,4 +12,5 @@ export declare const fetchUrls: (customConfiguration?: {
      */
     fetch?: (url: string) => Promise<Response>;
 }) => LoadPlugin;
+export declare function getAbsoluteUrl(value: string, source?: unknown): string;
 //# sourceMappingURL=fetchUrls.d.ts.map

package/dist/plugins/fetch-urls/fetchUrls.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"fetchUrls.d.ts","sourceRoot":"","sources":["../../../src/plugins/fetch-urls/fetchUrls.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,0BAA0B,CAAA;AAE1D,eAAO,MAAM,6BAA6B;;CAEzC,CAAA;AAED,eAAO,MAAM,SAAS,EAAE,CAAC,mBAAmB,CAAC,EAAE;IAC7C;;OAEG;IACH,KAAK,CAAC,EAAE,MAAM,GAAG,KAAK,CAAA;IACtB;;OAEG;IACH,KAAK,CAAC,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,OAAO,CAAC,QAAQ,CAAC,CAAA;CAC3C,KAAK,UA2CL,CAAA"}
+{"version":3,"file":"fetchUrls.d.ts","sourceRoot":"","sources":["../../../src/plugins/fetch-urls/fetchUrls.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,0BAA0B,CAAA;AAE1D,eAAO,MAAM,6BAA6B;;CAEzC,CAAA;AAED,eAAO,MAAM,SAAS,EAAE,CAAC,mBAAmB,CAAC,EAAE;IAC7C;;OAEG;IACH,KAAK,CAAC,EAAE,MAAM,GAAG,KAAK,CAAA;IACtB;;OAEG;IACH,KAAK,CAAC,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,OAAO,CAAC,QAAQ,CAAC,CAAA;CAC3C,KAAK,UAqDL,CAAA;AAED,wBAAgB,cAAc,CAAC,KAAK,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,OAAO,UAyE7D"}

package/dist/plugins/fetch-urls/fetchUrls.js

@@ -1,5 +1,5 @@
 const fetchUrlsDefaultConfiguration = {
-    limit: 20,
+    limit: 100,
 };
 const fetchUrls = (customConfiguration) => {
     // State
@@ -10,18 +10,24 @@ const fetchUrls = (customConfiguration) => {
         ...customConfiguration,
     };
     return {
+        // Make it run after readFiles
+        priority: 0,
         check(value) {
             // Not a string
             if (typeof value !== 'string') {
                 return false;
             }
-            // Not http/https
-            if (!value.startsWith('http://') && !value.startsWith('https://')) {
+            // Seems to be JSON
+            if (value.startsWith('{') || value.startsWith('[')) {
+                return false;
+            }
+            // Seems to be YAML
+            if (value.includes('\n')) {
                 return false;
             }
             return true;
         },
-        async get(value) {
+        async get(url) {
             // Limit ht enumber of requests
             if (configuration?.limit !== false && numberOfRequests >= configuration?.limit) {
                 console.warn(`[fetchUrls] Maximum number of requests reeached (${configuration?.limit}), skipping request`);
@@ -29,15 +35,81 @@ const fetchUrls = (customConfiguration) => {
             }
             try {
                 numberOfRequests++;
-                const response = await (configuration?.fetch ? configuration.fetch(value) : fetch(value));
+                const response = await (configuration?.fetch ? configuration.fetch(url) : fetch(url));
                 return await response.text();
             }
             catch (error) {
-                console.error('[fetchUrls]', error.message, `(${value})`);
+                console.error('[fetchUrls]', error.message, `(${url})`);
                 return undefined;
             }
         },
+        getUri(value, source) {
+            return getAbsoluteUrl(value, source);
+        },
     };
 };
+function getAbsoluteUrl(value, source) {
+    if (typeof source !== 'string') {
+        return value;
+    }
+    // Already an absolute URL
+    if (value.startsWith('http')) {
+        return value;
+    }
+    // Make it an absolute URL
+    if (source) {
+        // Skip if source or value is JSON/YAML content
+        if (source.startsWith('{') ||
+            source.startsWith('[') ||
+            source.includes('\n') ||
+            value.startsWith('{') ||
+            value.startsWith('[') ||
+            value.includes('\n')) {
+            return value;
+        }
+        try {
+            // If source is an HTTP URL, handle both absolute and relative paths
+            if (source.startsWith('http')) {
+                const sourceUrl = new URL(source);
+                // If value starts with /, treat it as relative to the host root
+                if (value.startsWith('/')) {
+                    // Simply combine the origin with the absolute path
+                    return `${sourceUrl.origin}${value}`;
+                }
+                // Otherwise treat it as relative to the source URL's directory
+                return new URL(value, sourceUrl.href).toString();
+            }
+            // Handle file system paths
+            if (source.startsWith('/') || !source.startsWith('http')) {
+                const sourceParts = source.split('/').filter(Boolean).slice(0, -1);
+                const valueParts = value.split('/').filter(Boolean);
+                const isAbsolute = source.startsWith('/');
+                // If value is absolute path, start fresh
+                if (value.startsWith('/')) {
+                    return value;
+                }
+                // Process each part of the path
+                const resultParts = [...sourceParts];
+                for (const part of valueParts) {
+                    if (part === '..') {
+                        resultParts.pop();
+                    }
+                    else if (part !== '.') {
+                        resultParts.push(part);
+                    }
+                }
+                // Preserve the leading slash for absolute paths, but avoid double slashes
+                return isAbsolute ? '/' + resultParts.join('/') : resultParts.join('/');
+            }
+            return new URL(value, source).toString();
+        }
+        catch (error) {
+            console.warn('[fetchUrls] Failed to resolve URL:', error.message, `(${value})`);
+            return value;
+        }
+    }
+    // Otherwise, return the value as is
+    return value;
+}
 
-export { fetchUrls, fetchUrlsDefaultConfiguration };
+export { fetchUrls, fetchUrlsDefaultConfiguration, getAbsoluteUrl };

package/dist/plugins/fetch-urls/index.d.ts

@@ -1,2 +1,2 @@
-export * from './fetchUrls.ts';
+export { fetchUrlsDefaultConfiguration, fetchUrls, getAbsoluteUrl, } from './fetchUrls.ts';
 //# sourceMappingURL=index.d.ts.map

package/dist/plugins/fetch-urls/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/plugins/fetch-urls/index.ts"],"names":[],"mappings":"AAAA,cAAc,gBAAgB,CAAA"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/plugins/fetch-urls/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,6BAA6B,EAC7B,SAAS,EACT,cAAc,GACf,MAAM,gBAAgB,CAAA"}

package/dist/plugins/fetch-urls/index.js

@@ -1 +1 @@
-export { fetchUrls, fetchUrlsDefaultConfiguration } from './fetchUrls.js';
+export { fetchUrls, fetchUrlsDefaultConfiguration, getAbsoluteUrl } from './fetchUrls.js';

package/dist/plugins/read-files/index.d.ts

@@ -1,2 +1,2 @@
-export * from './readFiles.ts';
+export { readFiles } from './readFiles.ts';
 //# sourceMappingURL=index.d.ts.map

package/dist/plugins/read-files/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/plugins/read-files/index.ts"],"names":[],"mappings":"AAAA,cAAc,gBAAgB,CAAA"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/plugins/read-files/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAA"}

package/dist/plugins/read-files/readFiles.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"readFiles.d.ts","sourceRoot":"","sources":["../../../src/plugins/read-files/readFiles.ts"],"names":[],"mappings":"AAMA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,0BAA0B,CAAA;AAE1D,eAAO,MAAM,SAAS,EAAE,MAAM,UAqD7B,CAAA"}
+{"version":3,"file":"readFiles.d.ts","sourceRoot":"","sources":["../../../src/plugins/read-files/readFiles.ts"],"names":[],"mappings":"AAMA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,0BAA0B,CAAA;AAE1D,eAAO,MAAM,SAAS,EAAE,MAAM,UAyE7B,CAAA"}

package/dist/plugins/read-files/readFiles.js

@@ -6,6 +6,8 @@ import { isYaml } from '../../utils/isYaml.js';
 
 const readFiles = () => {
     return {
+        // Make it run before fetchUrls
+        priority: 100,
         check(value) {
             // Not a string
             if (typeof value !== 'string') {
@@ -30,6 +32,9 @@ const readFiles = () => {
             return true;
         },
         async get(value) {
+            if (typeof value !== 'string') {
+                return false;
+            }
             if (!fs.existsSync(value)) {
                 throw new Error(ERRORS.FILE_DOES_NOT_EXIST.replace('%s', value));
             }
@@ -41,9 +46,19 @@ const readFiles = () => {
                 return false;
             }
         },
-        resolvePath(value, reference) {
-            const dir = dirname(value);
-            return join(dir, reference);
+        getUri(value, source) {
+            if (typeof value !== 'string') {
+                return undefined;
+            }
+            if (typeof source !== 'string') {
+                return value;
+            }
+            // Already absolute
+            if (value.startsWith('/')) {
+                return value;
+            }
+            const dir = dirname(source);
+            return join(dir, value);
         },
         getDir(value) {
             return dirname(value);

package/dist/types/index.d.ts

@@ -55,11 +55,30 @@ export type Filesystem = FilesystemEntry[];
  * Holds all information about a single file (doesn’t have to be a literal file, see Filesystem).
  */
 export type FilesystemEntry = {
-    dir: string;
+    /**
+     * The absolute path or URL to the file.
+     *
+     * @example https://example.com/path/to/file.yaml
+     * @example /Users/username/project/path/to/file.yaml
+     */
+    uri: string | null;
+    /**
+     * Whether this is the base document, everything else is just referenced by it.
+     */
     isEntrypoint: boolean;
-    references: string[];
-    filename: string;
-    specification: AnyObject;
+    /**
+     * A map of the references to other files.
+     *
+     * @example {
+     *   'file.yaml': 'https://example.com/folder/file.yaml',
+     *   '../file2.yaml': 'https://example.com/file2.yaml',
+     * }
+     */
+    references: Record<string, string>;
+    /**
+     * The actual content of the document
+     */
+    content: AnyObject;
 };
 /**
  * Options, that can apply to all commands

package/dist/types/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/types/index.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/types/index.ts"],"names":[],"mappings":"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"}

package/dist/utils/dereference.js

@@ -11,10 +11,10 @@ async function dereference(value, options) {
     const entrypoint = getEntrypoint(filesystem);
     const result = resolveReferences(filesystem, options);
     return {
-        specification: entrypoint.specification,
+        specification: entrypoint.content,
         errors: result.errors,
         schema: result.schema,
-        ...details(entrypoint.specification),
+        ...details(entrypoint.content),
     };
 }
 

package/dist/utils/filter.js

@@ -8,7 +8,7 @@ import { traverse } from './traverse.js';
 function filter(specification, callback) {
     const filesystem = makeFilesystem(specification);
     return {
-        specification: traverse(getEntrypoint(filesystem).specification, (schema) => {
+        specification: traverse(getEntrypoint(filesystem).content, (schema) => {
             return callback(schema) ? schema : undefined;
         }),
     };

package/dist/utils/isFilesystem.d.ts

@@ -1,5 +1,6 @@
+import type { Filesystem } from '../types/index.ts';
 /**
  * Check if the value is a filesystem
  */
-export declare function isFilesystem(value: any): boolean;
+export declare function isFilesystem(value: any): value is Filesystem;
 //# sourceMappingURL=isFilesystem.d.ts.map

package/dist/utils/isFilesystem.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"isFilesystem.d.ts","sourceRoot":"","sources":["../../src/utils/isFilesystem.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH,wBAAgB,YAAY,CAAC,KAAK,EAAE,GAAG,WAOtC"}
+{"version":3,"file":"isFilesystem.d.ts","sourceRoot":"","sources":["../../src/utils/isFilesystem.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,mBAAmB,CAAA;AAEnD;;GAEG;AACH,wBAAgB,YAAY,CAAC,KAAK,EAAE,GAAG,GAAG,KAAK,IAAI,UAAU,CAO5D"}

package/dist/utils/load/load.d.ts

@@ -1,14 +1,19 @@
 import type { AnyApiDefinitionFormat, Filesystem, LoadResult, ThrowOnErrorOption } from '../../types/index.ts';
 export type LoadPlugin = {
+    priority?: number;
     check: (value?: any) => boolean;
-    get: (value: any) => any;
+    get: (value: any, source?: string) => any;
+    /**
+     * @deprecated Use `getUri` instead
+     */
     resolvePath?: (value: any, reference: string) => string;
+    getUri?: (value: any, source?: string) => string;
     getDir?: (value: any) => string;
     getFilename?: (value: any) => string;
 };
 export type LoadOptions = {
     plugins?: LoadPlugin[];
-    filename?: string;
+    source?: string | undefined;
     filesystem?: Filesystem;
 } & ThrowOnErrorOption;
 /**
@@ -19,6 +24,10 @@ export type LoadOptions = {
  *
  * It builds a filesystem representation of all loaded content and collects any errors
  * encountered during the process.
+ *
+ * Known limitation:
+ * - TODO: Internal references inside external reference might not work
+ * - TODO: Protocol-relative URLs don’t work yet
  */
 export declare function load(value: AnyApiDefinitionFormat, options?: LoadOptions): Promise<LoadResult>;
 //# sourceMappingURL=load.d.ts.map

package/dist/utils/load/load.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"load.d.ts","sourceRoot":"","sources":["../../../src/utils/load/load.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EACV,sBAAsB,EAGtB,UAAU,EACV,UAAU,EACV,kBAAkB,EACnB,MAAM,sBAAsB,CAAA;AAM7B,MAAM,MAAM,UAAU,GAAG;IACvB,KAAK,EAAE,CAAC,KAAK,CAAC,EAAE,GAAG,KAAK,OAAO,CAAA;IAC/B,GAAG,EAAE,CAAC,KAAK,EAAE,GAAG,KAAK,GAAG,CAAA;IACxB,WAAW,CAAC,EAAE,CAAC,KAAK,EAAE,GAAG,EAAE,SAAS,EAAE,MAAM,KAAK,MAAM,CAAA;IACvD,MAAM,CAAC,EAAE,CAAC,KAAK,EAAE,GAAG,KAAK,MAAM,CAAA;IAC/B,WAAW,CAAC,EAAE,CAAC,KAAK,EAAE,GAAG,KAAK,MAAM,CAAA;CACrC,CAAA;AAED,MAAM,MAAM,WAAW,GAAG;IACxB,OAAO,CAAC,EAAE,UAAU,EAAE,CAAA;IACtB,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB,UAAU,CAAC,EAAE,UAAU,CAAA;CACxB,GAAG,kBAAkB,CAAA;AAEtB;;;;;;;;GAQG;AACH,wBAAsB,IAAI,CAAC,KAAK,EAAE,sBAAsB,EAAE,OAAO,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,UAAU,CAAC,CAyHpG"}
+{"version":3,"file":"load.d.ts","sourceRoot":"","sources":["../../../src/utils/load/load.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EACV,sBAAsB,EAGtB,UAAU,EACV,UAAU,EACV,kBAAkB,EACnB,MAAM,kBAAkB,CAAA;AAMzB,MAAM,MAAM,UAAU,GAAG;IACvB,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB,KAAK,EAAE,CAAC,KAAK,CAAC,EAAE,GAAG,KAAK,OAAO,CAAA;IAC/B,GAAG,EAAE,CAAC,KAAK,EAAE,GAAG,EAAE,MAAM,CAAC,EAAE,MAAM,KAAK,GAAG,CAAA;IACzC;;OAEG;IACH,WAAW,CAAC,EAAE,CAAC,KAAK,EAAE,GAAG,EAAE,SAAS,EAAE,MAAM,KAAK,MAAM,CAAA;IACvD,MAAM,CAAC,EAAE,CAAC,KAAK,EAAE,GAAG,EAAE,MAAM,CAAC,EAAE,MAAM,KAAK,MAAM,CAAA;IAChD,MAAM,CAAC,EAAE,CAAC,KAAK,EAAE,GAAG,KAAK,MAAM,CAAA;IAC/B,WAAW,CAAC,EAAE,CAAC,KAAK,EAAE,GAAG,KAAK,MAAM,CAAA;CACrC,CAAA;AAED,MAAM,MAAM,WAAW,GAAG;IACxB,OAAO,CAAC,EAAE,UAAU,EAAE,CAAA;IACtB,MAAM,CAAC,EAAE,MAAM,GAAG,SAAS,CAAA;IAC3B,UAAU,CAAC,EAAE,UAAU,CAAA;CACxB,GAAG,kBAAkB,CAAA;AAEtB;;;;;;;;;;;;GAYG;AACH,wBAAsB,IAAI,CAAC,KAAK,EAAE,sBAAsB,EAAE,OAAO,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,UAAU,CAAC,CAgKpG"}

package/dist/utils/load/load.js

@@ -1,7 +1,7 @@
 import { ERRORS } from '../../configuration/index.js';
 import { getEntrypoint } from '../getEntrypoint.js';
 import { getListOfReferences } from '../getListOfReferences.js';
-import { makeFilesystem } from '../makeFilesystem.js';
+import { makeFilesystemEntry } from '../makeFilesystem.js';
 import { normalize } from '../normalize.js';
 
 /**
@@ -12,25 +12,39 @@ import { normalize } from '../normalize.js';
  *
  * It builds a filesystem representation of all loaded content and collects any errors
  * encountered during the process.
+ *
+ * Known limitation:
+ * - TODO: Internal references inside external reference might not work
+ * - TODO: Protocol-relative URLs don’t work yet
  */
 async function load(value, options) {
     const errors = [];
-    // Don’t load a reference twice, check the filesystem before fetching something
-    if (options?.filesystem?.find((entry) => entry.filename === value)) {
+    const filesystem = [...(options?.filesystem ?? [])];
+    // Don't load a reference twice, check the filesystem before fetching something
+    if (filesystem.find((entry) => entry.uri === options?.source)) {
         return {
-            specification: getEntrypoint(options.filesystem)?.specification,
-            filesystem: options.filesystem,
+            specification: getEntrypoint(filesystem)?.content,
+            filesystem,
             errors,
         };
     }
-    // Check whether the value is an URL or file path
-    const plugin = options?.plugins?.find((thisPlugin) => thisPlugin.check(value));
     let content;
+    let uri;
+    // Check whether the value is an file or URL
+    const plugin = sortPlugins(options?.plugins)?.find((thisPlugin) => thisPlugin.check(value));
+    if (options?.source) {
+        uri = options.source;
+    }
+    // Seems to be a file or URL
     if (plugin) {
         try {
-            content = normalize(await plugin.get(value));
+            // Get the absolute URI/path
+            uri = plugin.getUri(value, options?.source);
+            // Fetch/read the content
+            content = normalize(await plugin.get(uri));
         }
         catch (_error) {
+            // Couldn’t fetch/read the content
             if (options?.throwOnError) {
                 throw new Error(ERRORS.EXTERNAL_REFERENCE_NOT_FOUND.replace('%s', value));
             }
@@ -40,15 +54,16 @@ async function load(value, options) {
             });
             return {
                 specification: null,
-                filesystem: [],
+                filesystem,
                 errors,
             };
         }
     }
     else {
+        // No plugin found, so it’s just the content, I guess.
         content = normalize(value);
     }
-    // No content
+    // Oops, no content
     if (content === undefined) {
         if (options?.throwOnError) {
             throw new Error('No content to load');
@@ -59,61 +74,85 @@ async function load(value, options) {
         });
         return {
             specification: null,
-            filesystem: [],
+            filesystem,
             errors,
         };
     }
-    let filesystem = makeFilesystem(content, {
-        filename: options?.filename ?? null,
+    const entryExistsAlready = options?.filesystem?.find((entry) => uri && entry.uri === uri);
+    if (entryExistsAlready) {
+        return {
+            specification: getEntrypoint(filesystem)?.content,
+            filesystem,
+            errors,
+        };
+    }
+    // Get all external references from the content
+    const listOfReferences = getListOfReferences(content);
+    const source = 
+    // A given URL/path
+    options?.source ??
+        // The reference that we come from
+        (typeof value === 'string'
+            ? value
+            : // Nothing
+                undefined);
+    // Map the references to their absolute URIs
+    const mapOfReferences = listOfReferences.reduce((acc, reference) => {
+        const plugin = sortPlugins(options?.plugins)?.find((p) => p.check(reference));
+        const absoluteUri = plugin?.getUri(reference, source);
+        return { ...acc, [reference]: absoluteUri };
+    }, {});
+    const entry = makeFilesystemEntry(content, {
+        isEntrypoint: false,
+        uri,
+        references: mapOfReferences,
     });
-    // Get references from file system entry, or from the content
-    const newEntry = options?.filename
-        ? filesystem.find((entry) => entry.filename === options?.filename)
-        : getEntrypoint(filesystem);
-    const listOfReferences = newEntry.references ?? getListOfReferences(content);
+    if (!filesystem.find((entry) => entry.uri === uri)) {
+        filesystem.push({
+            ...entry,
+            isEntrypoint: filesystem.length === 0,
+        });
+    }
     // No other references
     if (listOfReferences.length === 0) {
         return {
-            specification: getEntrypoint(filesystem)?.specification,
+            specification: entry.content,
             filesystem,
             errors,
         };
     }
     // Load other external references
     for (const reference of listOfReferences) {
+        // Work with the absolute URI
+        const absoluteUri = mapOfReferences[reference];
         // Find a matching plugin
-        const otherPlugin = options?.plugins?.find((thisPlugin) => thisPlugin.check(reference));
-        // Skip if no plugin is found (internal references don’t need a plugin for example)
+        const otherPlugin = sortPlugins(options?.plugins)?.find((thisPlugin) => thisPlugin.check(absoluteUri));
+        // Skip if no plugin is found (internal references don't need a plugin for example)
         if (!otherPlugin) {
             continue;
         }
-        const target = otherPlugin.check(reference) && otherPlugin.resolvePath ? otherPlugin.resolvePath(value, reference) : reference;
-        // Don’t load a reference twice, check the filesystem before fetching something
-        if (filesystem.find((entry) => entry.filename === reference)) {
+        // Don't load a reference twice, check the filesystem before fetching something
+        if (options?.filesystem?.find((entry) => entry.uri === absoluteUri)) {
             continue;
         }
-        const { filesystem: referencedFiles, errors: newErrors } = await load(target, {
+        const { filesystem: referencedFiles, errors: newErrors } = await load(absoluteUri, {
             ...options,
-            // Make the filename the exact same value as the $ref
-            // TODO: This leads to problems, if there are multiple references with the same file name but in different folders
-            filename: reference,
+            source: absoluteUri,
+            filesystem,
         });
         errors.push(...newErrors);
-        filesystem = [
-            ...filesystem,
-            ...referencedFiles.map((file) => {
-                return {
-                    ...file,
-                    isEntrypoint: false,
-                };
-            }),
-        ];
+        referencedFiles
+            .filter((file) => !filesystem.find((entry) => entry.uri === file.uri))
+            .forEach((file) => filesystem.push(file));
     }
     return {
-        specification: getEntrypoint(filesystem)?.specification,
+        specification: entry.content,
         filesystem,
         errors,
     };
 }
+function sortPlugins(plugins = []) {
+    return plugins?.sort((a, b) => (b.priority ?? 0) - (a.priority ?? 0));
+}
 
 export { load };

package/dist/utils/makeFilesystem.d.ts

@@ -1,3 +1,20 @@
 import type { AnyObject, Filesystem, FilesystemEntry } from '../types/index.ts';
-export declare function makeFilesystem(value: string | AnyObject | Filesystem, overwrites?: Partial<FilesystemEntry>): Filesystem;
+export declare function makeFilesystem(
+/**
+ * Pass whatever you have, it will be normalized and then used as the content.
+ */
+value: string | AnyObject | Filesystem | FilesystemEntry, 
+/**
+ * If you know better, you can overwrite the default values.
+ */
+overwrites?: Partial<FilesystemEntry> & (FilesystemEntry['references'] | {})): Filesystem;
+export declare function makeFilesystemEntry(
+/**
+ * Pass whatever you have, it will be normalized and then used as the content.
+ */
+value: string | AnyObject | Filesystem, 
+/**
+ * If you know better, you can overwrite the default values.
+ */
+overwrites?: Partial<FilesystemEntry> & (FilesystemEntry['references'] | {})): FilesystemEntry;
 //# sourceMappingURL=makeFilesystem.d.ts.map

package/dist/utils/makeFilesystem.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"makeFilesystem.d.ts","sourceRoot":"","sources":["../../src/utils/makeFilesystem.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,UAAU,EAAE,eAAe,EAAE,MAAM,mBAAmB,CAAA;AAK/E,wBAAgB,cAAc,CAC5B,KAAK,EAAE,MAAM,GAAG,SAAS,GAAG,UAAU,EACtC,UAAU,GAAE,OAAO,CAAC,eAAe,CAAM,GACxC,UAAU,CAoBZ"}
+{"version":3,"file":"makeFilesystem.d.ts","sourceRoot":"","sources":["../../src/utils/makeFilesystem.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,UAAU,EAAE,eAAe,EAAE,MAAM,mBAAmB,CAAA;AAI/E,wBAAgB,cAAc;AAC5B;;GAEG;AACH,KAAK,EAAE,MAAM,GAAG,SAAS,GAAG,UAAU,GAAG,eAAe;AACxD;;GAEG;AACH,UAAU,CAAC,EAAE,OAAO,CAAC,eAAe,CAAC,GAAG,CAAC,eAAe,CAAC,YAAY,CAAC,GAAG,EAAE,CAAC,GAC3E,UAAU,CA4BZ;AAED,wBAAgB,mBAAmB;AACjC;;GAEG;AACH,KAAK,EAAE,MAAM,GAAG,SAAS,GAAG,UAAU;AACtC;;GAEG;AACH,UAAU,CAAC,EAAE,OAAO,CAAC,eAAe,CAAC,GAAG,CAAC,eAAe,CAAC,YAAY,CAAC,GAAG,EAAE,CAAC,GAC3E,eAAe,CAmBjB"}