@scalar/openapi-parser 0.29.14 → 0.29.15

package/CHANGELOG.md

@@ -1,5 +1,13 @@
 # @scalar/openapi-parser
 
+## 0.29.15
+
+### Patch Changes
+
+- [#10643](https://github.com/scalar/scalar/pull/10643): Distinguish reference locations from schema name maps and literal data when validating, dereferencing, and collecting external references. Preserve `$ref` properties with object or boolean schemas, leave examples and default/enum/const values unchanged, and retain errors for malformed references.
+
+  Retain reference context across external files and fragments. Resolve custom operations while preserving OAuth scope names, discriminator mappings, Link payloads, and specification extension data.
+
 ## 0.29.14
 
 ## 0.29.13

package/dist/utils/get-list-of-references.d.ts

@@ -1,8 +1,4 @@
 import type { AnyObject } from '@scalar/types/utils';
-/**
- * Walks through the specification and returns all references as an array.
- *
- * Warning: Doesn't return internal references.
- */
-export declare function getListOfReferences(specification: AnyObject): string[];
+/** Collect external reference filenames without interpreting instance data as references. */
+export declare const getListOfReferences: (specification: AnyObject) => string[];
 //# sourceMappingURL=get-list-of-references.d.ts.map

package/dist/utils/get-list-of-references.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"get-list-of-references.d.ts","sourceRoot":"","sources":["../../src/utils/get-list-of-references.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,qBAAqB,CAAA;AAIpD;;;;GAIG;AACH,wBAAgB,mBAAmB,CAAC,aAAa,EAAE,SAAS,YAmB3D"}
+{"version":3,"file":"get-list-of-references.d.ts","sourceRoot":"","sources":["../../src/utils/get-list-of-references.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,qBAAqB,CAAA;AAIpD,6FAA6F;AAC7F,eAAO,MAAM,mBAAmB,GAAI,eAAe,SAAS,KAAG,MAAM,EAEpE,CAAA"}

package/dist/utils/get-list-of-references.js

@@ -1,22 +1,5 @@
-import { traverse } from './traverse.js';
-/**
- * Walks through the specification and returns all references as an array.
- *
- * Warning: Doesn't return internal references.
- */
-export function getListOfReferences(specification) {
-    const references = [];
-    // Make sure we're dealing with an object
-    if (!specification || typeof specification !== 'object') {
-        return references;
-    }
-    // Traverse the specification and collect all references
-    traverse(specification, (value) => {
-        if (value.$ref && typeof value.$ref === 'string' && !value.$ref.startsWith('#')) {
-            references.push(value.$ref.split('#')[0]);
-        }
-        return value;
-    });
-    // Remove duplicates
-    return [...new Set(references)];
-}
+import { getReferenceTargets } from './get-reference-targets.js';
+/** Collect external reference filenames without interpreting instance data as references. */
+export const getListOfReferences = (specification) => [
+    ...new Set(getReferenceTargets(specification).map(({ filename }) => filename)),
+];

package/dist/utils/get-reference-targets.d.ts

@@ -0,0 +1,14 @@
+import { type ReferenceContext } from './reference-context.js';
+/** A selected document fragment and the kind of object expected by its caller. */
+export type ReferenceTarget = {
+    fragment: string;
+    context: ReferenceContext;
+};
+/** External dependencies retain their fragment and context until the file is loaded. */
+type ExternalReferenceTarget = ReferenceTarget & {
+    filename: string;
+};
+/** Collect dependencies from selected fragments, following local aliases in the same context. */
+export declare const getReferenceTargets: (specification: unknown, targets?: ReferenceTarget[]) => ExternalReferenceTarget[];
+export {};
+//# sourceMappingURL=get-reference-targets.d.ts.map

package/dist/utils/get-reference-targets.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"get-reference-targets.d.ts","sourceRoot":"","sources":["../../src/utils/get-reference-targets.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,KAAK,gBAAgB,EAAiD,MAAM,qBAAqB,CAAA;AAE1G,kFAAkF;AAClF,MAAM,MAAM,eAAe,GAAG;IAAE,QAAQ,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,gBAAgB,CAAA;CAAE,CAAA;AAE7E,wFAAwF;AACxF,KAAK,uBAAuB,GAAG,eAAe,GAAG;IAAE,QAAQ,EAAE,MAAM,CAAA;CAAE,CAAA;AAErE,iGAAiG;AACjG,eAAO,MAAM,mBAAmB,GAC9B,eAAe,OAAO,EACtB,UAAS,eAAe,EAA4C,KACnE,uBAAuB,EA6CzB,CAAA"}

package/dist/utils/get-reference-targets.js

@@ -0,0 +1,45 @@
+import { isObjectLike } from '@scalar/helpers/object/is-object';
+import { getSegmentsFromPath } from './get-segments-from-path.js';
+import { canResolveReference, getChildReferenceContext } from './reference-context.js';
+/** Collect dependencies from selected fragments, following local aliases in the same context. */
+export const getReferenceTargets = (specification, targets = [{ fragment: '', context: 'document' }]) => {
+    const references = [];
+    const localTargets = [];
+    const visited = new WeakMap();
+    const visitTarget = ({ fragment, context }) => {
+        try {
+            const target = getSegmentsFromPath(fragment).reduce((value, key) => (isObjectLike(value) && Object.hasOwn(value, key) ? value[key] : undefined), specification);
+            visit(target, context);
+        }
+        catch {
+            // Reference resolution reports invalid pointers; dependency collection does not validate them.
+        }
+    };
+    const visit = (value, context) => {
+        if (context === 'literal' || !isObjectLike(value) || visited.get(value)?.has(context)) {
+            return;
+        }
+        const contexts = visited.get(value) ?? new Set();
+        contexts.add(context);
+        visited.set(value, contexts);
+        if (canResolveReference(context) && typeof value.$ref === 'string' && value.$ref) {
+            const [filename, fragment = ''] = value.$ref.split('#', 2);
+            if (filename) {
+                references.push({ filename, fragment, context });
+            }
+            else {
+                localTargets.push({ fragment, context });
+            }
+        }
+        for (const [key, child] of Object.entries(value)) {
+            visit(child, getChildReferenceContext(context, key, child));
+        }
+    };
+    for (const target of targets) {
+        visitTarget(target);
+    }
+    for (const target of localTargets) {
+        visitTarget(target);
+    }
+    return references;
+};

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

@@ -26,5 +26,5 @@ export type LoadOptions = {
  * It builds a filesystem representation of all loaded content and collects any errors
  * encountered during the process.
  */
-export declare function load(value: AnyApiDefinitionFormat, options?: LoadOptions): Promise<LoadResult>;
+export declare const 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,EAAE,sBAAsB,EAAe,UAAU,EAAE,UAAU,EAAE,kBAAkB,EAAE,MAAM,eAAe,CAAA;AAMpH,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;;;;;;;;;;;;;;GAcG;AACH,wBAAsB,IAAI,CAAC,KAAK,EAAE,sBAAsB,EAAE,OAAO,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,UAAU,CAAC,CAuHpG"}
+{"version":3,"file":"load.d.ts","sourceRoot":"","sources":["../../../src/utils/load/load.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,sBAAsB,EAAe,UAAU,EAAE,UAAU,EAAE,kBAAkB,EAAE,MAAM,eAAe,CAAA;AAMpH,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;;;;;;;;;;;;;;GAcG;AACH,eAAO,MAAM,IAAI,GAAI,OAAO,sBAAsB,EAAE,UAAU,WAAW,KAAG,OAAO,CAAC,UAAU,CAChE,CAAA"}

package/dist/utils/load/load.js

@@ -1,6 +1,6 @@
 import { ERRORS } from '../../configuration/index.js';
 import { getEntrypoint } from '../../utils/get-entrypoint.js';
-import { getListOfReferences } from '../../utils/get-list-of-references.js';
+import { getReferenceTargets } from '../../utils/get-reference-targets.js';
 import { makeFilesystem } from '../../utils/make-filesystem.js';
 import { normalize } from '../../utils/normalize.js';
 /**
@@ -18,7 +18,8 @@ import { normalize } from '../../utils/normalize.js';
  * It builds a filesystem representation of all loaded content and collects any errors
  * encountered during the process.
  */
-export async function load(value, options) {
+export const load = (value, options) => loadDocument(value, options);
+const loadDocument = async (value, options, targets, documents = new Map()) => {
     const errors = [];
     // Don't load a reference twice, check the filesystem before fetching something
     if (options?.filesystem?.find((entry) => entry.filename === value)) {
@@ -30,8 +31,10 @@ export async function load(value, options) {
     }
     // Check whether the value is an URL or file path
     const plugin = options?.plugins?.find((thisPlugin) => thisPlugin.check(value));
-    let content = normalize(value);
-    if (plugin) {
+    const documentKey = typeof value === 'string' ? value : options?.filename;
+    const cached = documentKey === undefined ? undefined : documents.get(documentKey);
+    let content = cached?.content ?? normalize(value);
+    if (plugin && !cached) {
         try {
             content = normalize(await plugin.get(value));
         }
@@ -65,14 +68,29 @@ export async function load(value, options) {
             errors,
         };
     }
-    let filesystem = makeFilesystem(content, {
+    const filesystem = makeFilesystem(content, {
         filename: options?.filename ?? null,
     });
     // 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);
+    // A file may be reached later through another fragment or another object type.
+    const visitedTargets = cached?.targets ?? new Set();
+    const pendingTargets = (targets ?? [{ fragment: '', context: 'document' }]).filter((target) => {
+        const key = JSON.stringify(target);
+        if (visitedTargets.has(key)) {
+            return false;
+        }
+        visitedTargets.add(key);
+        return true;
+    });
+    if (documentKey !== undefined) {
+        documents.set(documentKey, { content, targets: visitedTargets });
+    }
+    const referenceTargets = getReferenceTargets(newEntry.specification, pendingTargets);
+    const listOfReferences = [...new Set(referenceTargets.map(({ filename }) => filename))];
+    newEntry.references = listOfReferences;
     // No other references
     if (listOfReferences.length === 0) {
         return {
@@ -90,30 +108,28 @@ export async function load(value, options) {
             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)) {
-            continue;
-        }
-        const { filesystem: referencedFiles, errors: newErrors } = await load(target, {
+        const { filesystem: referencedFiles, errors: newErrors } = await loadDocument(target, {
             ...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,
-        });
+        }, referenceTargets
+            .filter(({ filename }) => filename === reference)
+            .map(({ fragment, context }) => ({ fragment, context })), documents);
         errors.push(...newErrors);
-        filesystem = [
-            ...filesystem,
-            ...referencedFiles.map((file) => {
-                return {
-                    ...file,
-                    isEntrypoint: false,
-                };
-            }),
-        ];
+        for (const file of referencedFiles) {
+            const existing = filesystem.find((entry) => entry.filename === file.filename);
+            if (existing) {
+                existing.references = [...new Set([...existing.references, ...file.references])];
+            }
+            else {
+                filesystem.push({ ...file, isEntrypoint: false });
+            }
+        }
     }
     return {
         specification: getEntrypoint(filesystem)?.specification,
         filesystem,
         errors,
     };
-}
+};