@scalar/openapi-parser 0.29.14 → 0.29.16

package/dist/utils/openapi/utils/workThroughQueue.js

@@ -1,8 +1,8 @@
-import { dereference } from '../../../utils/dereference.js';
-import { filter } from '../../../utils/filter.js';
-import { load } from '../../../utils/load/load.js';
-import { upgrade } from '../../../utils/upgrade.js';
-import { validate } from '../../../utils/validate.js';
+import { dereference } from '../../dereference.js';
+import { filter } from '../../filter.js';
+import { load } from '../../load/load.js';
+import { upgrade } from '../../upgrade.js';
+import { validate } from '../../validate.js';
 /**
  * Takes a queue of tasks and works through them
  */

package/dist/utils/reference-context.d.ts

@@ -0,0 +1,7 @@
+/** Distinguishes reference-bearing objects from name maps and opaque instance data. */
+export type ReferenceContext = 'link' | 'linkMap' | 'discriminator' | 'object' | 'document' | 'components' | 'paths' | 'namedResponseMap' | 'schema' | 'response' | 'responseMap' | 'example' | 'objectMap' | 'schemaMap' | 'exampleMap' | 'callbackMap' | 'callback' | 'literal';
+/** A map's names are data, even when a name happens to be an OpenAPI keyword. */
+export declare const getChildReferenceContext: (context: ReferenceContext, key: string, value: unknown) => ReferenceContext;
+/** Only objects in reference positions may interpret their own $ref field as a URI. */
+export declare const canResolveReference: (context: ReferenceContext) => boolean;
+//# sourceMappingURL=reference-context.d.ts.map

package/dist/utils/reference-context.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"reference-context.d.ts","sourceRoot":"","sources":["../../src/utils/reference-context.ts"],"names":[],"mappings":"AAAA,uFAAuF;AACvF,MAAM,MAAM,gBAAgB,GACxB,MAAM,GACN,SAAS,GACT,eAAe,GACf,QAAQ,GACR,UAAU,GACV,YAAY,GACZ,OAAO,GACP,kBAAkB,GAClB,QAAQ,GACR,UAAU,GACV,aAAa,GACb,SAAS,GACT,WAAW,GACX,WAAW,GACX,YAAY,GACZ,aAAa,GACb,UAAU,GACV,SAAS,CAAA;AAkCb,iFAAiF;AACjF,eAAO,MAAM,wBAAwB,GAAI,SAAS,gBAAgB,EAAE,KAAK,MAAM,EAAE,OAAO,OAAO,KAAG,gBAwEjG,CAAA;AAED,uFAAuF;AACvF,eAAO,MAAM,mBAAmB,GAAI,SAAS,gBAAgB,KAAG,OAOxC,CAAA"}

package/dist/utils/reference-context.js

@@ -0,0 +1,111 @@
+const schemaMaps = new Set(['properties', 'patternProperties', '$defs', 'definitions', 'dependentSchemas']);
+const schemaArrays = new Set(['allOf', 'anyOf', 'oneOf', 'prefixItems']);
+const schemaValues = new Set([
+    'schema',
+    'items',
+    'additionalItems',
+    'contains',
+    'additionalProperties',
+    'unevaluatedProperties',
+    'unevaluatedItems',
+    'propertyNames',
+    'not',
+    'if',
+    'then',
+    'else',
+    'contentSchema',
+]);
+const objectMaps = new Set([
+    'additionalOperations',
+    'webhooks',
+    'content',
+    'mediaTypes',
+    'headers',
+    'encoding',
+    'variables',
+    'parameters',
+    'requestBodies',
+    'securitySchemes',
+    'pathItems',
+]);
+const literalValues = new Set(['example', 'default', 'enum', 'const', 'dependentRequired']);
+/** A map's names are data, even when a name happens to be an OpenAPI keyword. */
+export const getChildReferenceContext = (context, key, value) => {
+    if (context === 'literal') {
+        return 'literal';
+    }
+    if (context === 'callbackMap') {
+        return 'callback';
+    }
+    if (context === 'callback') {
+        return 'object';
+    }
+    if (context === 'responseMap' || context === 'paths') {
+        // These objects allow extensions, unlike maps of arbitrary component names.
+        return key.startsWith('x-') ? 'literal' : context === 'paths' ? 'object' : 'response';
+    }
+    if (context === 'namedResponseMap') {
+        return 'response';
+    }
+    if (context === 'schemaMap') {
+        return 'schema';
+    }
+    if (context === 'objectMap') {
+        return 'object';
+    }
+    if (context === 'linkMap') {
+        return 'link';
+    }
+    if (context === 'exampleMap') {
+        return 'example';
+    }
+    if (key.startsWith('x-') ||
+        key === 'scopes' ||
+        (context === 'discriminator' && key === 'mapping') ||
+        (context === 'link' && (key === 'requestBody' || key === 'parameters'))) {
+        return 'literal';
+    }
+    if (key === 'links') {
+        return 'linkMap';
+    }
+    if (key === 'discriminator') {
+        return 'discriminator';
+    }
+    if (literalValues.has(key) || (context === 'example' && (key === 'value' || key === 'dataValue'))) {
+        return 'literal';
+    }
+    if (key === 'examples') {
+        // OpenAPI 2 response examples map media types directly to instance data.
+        return context === 'schema' || context === 'response' || Array.isArray(value) ? 'literal' : 'exampleMap';
+    }
+    if (schemaMaps.has(key) || schemaArrays.has(key) || key === 'schemas') {
+        return 'schemaMap';
+    }
+    if (schemaValues.has(key)) {
+        return Array.isArray(value) ? 'schemaMap' : 'schema';
+    }
+    if (key === 'components') {
+        return 'components';
+    }
+    if (key === 'paths') {
+        return 'paths';
+    }
+    if (key === 'responses') {
+        return context === 'components' || context === 'document' ? 'namedResponseMap' : 'responseMap';
+    }
+    if (key === 'callbacks') {
+        return 'callbackMap';
+    }
+    if (objectMaps.has(key)) {
+        return 'objectMap';
+    }
+    return 'object';
+};
+/** Only objects in reference positions may interpret their own $ref field as a URI. */
+export const canResolveReference = (context) => context === 'document' ||
+    context === 'link' ||
+    context === 'object' ||
+    context === 'schema' ||
+    context === 'example' ||
+    context === 'callback' ||
+    context === 'response';

package/dist/utils/resolve-references.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"resolve-references.d.ts","sourceRoot":"","sources":["../../src/utils/resolve-references.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,SAAS,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAA;AAGnE,OAAO,KAAK,EAAE,WAAW,EAAE,UAAU,EAAE,eAAe,EAAE,kBAAkB,EAAE,MAAM,eAAe,CAAA;AAgBjG,KAAK,uBAAuB,GAAG;IAC7B,KAAK,EAAE,OAAO,CAAA;IACd,MAAM,EAAE,WAAW,EAAE,CAAA;IACrB,MAAM,EAAE,aAAa,CAAA;CACtB,CAAA;AAED,MAAM,MAAM,wBAAwB,GAAG,kBAAkB,GAAG;IAC1D;;;;OAIG;IACH,aAAa,CAAC,EAAE,CAAC,IAAI,EAAE;QAAE,MAAM,EAAE,SAAS,CAAC;QAAC,GAAG,EAAE,MAAM,CAAC;QAAC,QAAQ,EAAE,SAAS,CAAA;KAAE,KAAK,IAAI,CAAA;CACxF,CAAA;AAED;;GAEG;AACH,wBAAgB,iBAAiB,CAE/B,KAAK,EAAE,SAAS,GAAG,UAAU,EAE7B,OAAO,CAAC,EAAE,wBAAwB,EAElC,IAAI,CAAC,EAAE,eAAe,EAEtB,MAAM,GAAE,WAAW,EAAO,GACzB,uBAAuB,CAuCzB"}
+{"version":3,"file":"resolve-references.d.ts","sourceRoot":"","sources":["../../src/utils/resolve-references.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,SAAS,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAA;AAGnE,OAAO,KAAK,EAAE,WAAW,EAAE,UAAU,EAAE,eAAe,EAAE,kBAAkB,EAAE,MAAM,eAAe,CAAA;AAiBjG,KAAK,uBAAuB,GAAG;IAC7B,KAAK,EAAE,OAAO,CAAA;IACd,MAAM,EAAE,WAAW,EAAE,CAAA;IACrB,MAAM,EAAE,aAAa,CAAA;CACtB,CAAA;AAED,MAAM,MAAM,wBAAwB,GAAG,kBAAkB,GAAG;IAC1D;;;;OAIG;IACH,aAAa,CAAC,EAAE,CAAC,IAAI,EAAE;QAAE,MAAM,EAAE,SAAS,CAAC;QAAC,GAAG,EAAE,MAAM,CAAC;QAAC,QAAQ,EAAE,SAAS,CAAA;KAAE,KAAK,IAAI,CAAA;CACxF,CAAA;AAED;;GAEG;AACH,wBAAgB,iBAAiB,CAE/B,KAAK,EAAE,SAAS,GAAG,UAAU,EAE7B,OAAO,CAAC,EAAE,wBAAwB,EAElC,IAAI,CAAC,EAAE,eAAe,EAEtB,MAAM,GAAE,WAAW,EAAO,GACzB,uBAAuB,CAuCzB"}

package/dist/utils/resolve-references.js

@@ -3,6 +3,7 @@ import { ERRORS } from '../configuration/index.js';
 import { getEntrypoint } from './get-entrypoint.js';
 import { getSegmentsFromPath } from './get-segments-from-path.js';
 import { makeFilesystem } from './make-filesystem.js';
+import { canResolveReference, getChildReferenceContext } from './reference-context.js';
 /**
  * Takes a specification and resolves all references.
  */
@@ -34,7 +35,7 @@ errors = []) {
         };
     }
     // Recursively resolve all references
-    dereference(finalInput, filesystem, file ?? entrypoint, new WeakSet(), errors, options);
+    dereference(finalInput, filesystem, file ?? entrypoint, new WeakSet(), errors, options, 'document');
     // Remove duplicates (according to message) from errors
     const uniqueErrors = errors.filter((error, index, self) => index === self.findIndex((t) => t.message === error.message && t.code === error.code));
     // Return the resolved specification
@@ -51,15 +52,19 @@ function dereference(schema, filesystem, entrypoint,
 // references to resolved object
 resolvedSchemas, 
 // error output
-errors, options) {
-    if (schema === null || resolvedSchemas.has(schema)) {
+errors, options, context = 'object') {
+    if (context === 'literal' || schema === null || resolvedSchemas.has(schema)) {
         return;
     }
     resolvedSchemas.add(schema);
-    function resolveExternal(externalFile) {
-        dereference(externalFile.specification, filesystem, externalFile, resolvedSchemas, errors, options);
-        return externalFile;
-    }
+    // A fragment inherits the reference site's context, not its storage container's keys.
+    const resolveExternal = (externalFile, fragment) => {
+        const target = resolveUri(`#${fragment}`, options, externalFile, filesystem, resolveExternal, errors);
+        if (isObjectLike(target)) {
+            dereference(target, filesystem, externalFile, resolvedSchemas, errors, options, context);
+        }
+        return target;
+    };
     /**
      * Track seen $ref paths to detect self-referencing schemas.
      *
@@ -73,7 +78,7 @@ errors, options) {
      *   Person: { type: 'object', properties: { friend: { $ref: '#/components/schemas/Person' } } }
      */
     const processedRefs = new Set();
-    while (schema.$ref !== undefined) {
+    while (canResolveReference(context) && schema.$ref !== undefined) {
         const selfReferenceDetected = processedRefs.has(schema.$ref);
         if (selfReferenceDetected) {
             errors.push({
@@ -103,9 +108,9 @@ errors, options) {
         }
     }
     // Iterate over the whole object
-    for (const value of Object.values(schema)) {
+    for (const [key, value] of Object.entries(schema)) {
         if (typeof value === 'object' && value !== null) {
-            dereference(value, filesystem, entrypoint, resolvedSchemas, errors, options);
+            dereference(value, filesystem, entrypoint, resolvedSchemas, errors, options, getChildReferenceContext(context, key, value));
         }
     }
 }
@@ -153,13 +158,7 @@ resolve, errors) {
             });
             return undefined;
         }
-        // $ref: 'other-file.yaml'
-        if (path === undefined) {
-            return externalReference.specification;
-        }
-        // $ref: 'other-file.yaml#/foo/bar'
-        // resolve refs first before accessing properties directly
-        return resolveUri(`#${path}`, options, resolve(externalReference), filesystem, resolve, errors);
+        return resolve(externalReference, path ?? '');
     }
     // Try to find the URI
     try {

package/package.json

@@ -17,7 +17,7 @@
     "parser",
     "typescript"
   ],
-  "version": "0.29.14",
+  "version": "0.29.16",
   "engines": {
     "node": ">=22"
   },
@@ -49,18 +49,18 @@
   "sideEffects": false,
   "dependencies": {
     "@scalar/helpers": "0.16.4",
-    "@scalar/json-magic": "0.16.0",
+    "@scalar/json-magic": "0.17.0",
     "@scalar/openapi-types": "0.9.8",
-    "@scalar/openapi-upgrader": "0.4.5",
-    "@scalar/openapi-validator": "0.1.13",
-    "@scalar/types": "0.24.0",
-    "yaml": "^2.9.0"
+    "@scalar/openapi-upgrader": "0.4.6",
+    "@scalar/openapi-validator": "0.1.14",
+    "@scalar/types": "0.25.0",
+    "yaml": "^2.9.1"
   },
   "devDependencies": {
-    "@apidevtools/swagger-parser": "10.1.0",
-    "@types/node": "^24.1.0",
+    "@apidevtools/swagger-parser": "13.1.0",
+    "@types/node": "^24.19.2",
     "just-diff": "^6.0.2",
-    "vite": "8.1.5"
+    "vite": "8.3.4"
   },
   "scripts": {
     "build": "tsc -p tsconfig.build.json && tsc-alias -p tsconfig.build.json",