@scalar/json-magic 0.4.3 → 0.5.1

package/src/bundle/bundle.ts

@@ -1,11 +1,14 @@
+import { convertToLocalRef } from '@/helpers/convert-to-local-ref'
+import { getId, getSchemas } from '@/helpers/get-schemas'
+import { getValueByPath } from '@/helpers/get-value-by-path'
+import path from '@/polyfills/path'
 import type { UnknownObject } from '@/types'
 
-import { escapeJsonPointer } from '../utils/escape-json-pointer'
-import path from '@/polyfills/path'
-import { getSegmentsFromPath } from '../utils/get-segments-from-path'
-import { isObject } from '../utils/is-object'
-import { isYaml } from '../utils/is-yaml'
-import { isJsonObject } from '../utils/is-json-object'
+import { escapeJsonPointer } from '../helpers/escape-json-pointer'
+import { getSegmentsFromPath } from '../helpers/get-segments-from-path'
+import { isJsonObject } from '../helpers/is-json-object'
+import { isObject } from '../helpers/is-object'
+import { isYaml } from '../helpers/is-yaml'
 import { getHash, uniqueValueGeneratorFactory } from './value-generator'
 
 /**
@@ -89,24 +92,6 @@ async function resolveContents(value: string, plugins: LoaderPlugin[]): Promise<
   }
 }
 
-/**
- * Retrieves a nested value from an object using an array of property segments.
- * @param target - The target object to traverse
- * @param segments - Array of property names representing the path to the desired value
- * @returns The value at the specified path, or undefined if the path doesn't exist
- * @example
- * const obj = { foo: { bar: { baz: 42 } } };
- * getNestedValue(obj, ['foo', 'bar', 'baz']); // returns 42
- */
-export function getNestedValue(target: Record<string, any>, segments: string[]) {
-  return segments.reduce<any>((acc, key) => {
-    if (acc === undefined) {
-      return undefined
-    }
-    return acc[key]
-  }, target)
-}
-
 /**
  * Sets a value at a specified path in an object, creating intermediate objects/arrays as needed.
  * This function traverses the object structure and creates any missing intermediate objects
@@ -293,6 +278,7 @@ export function prefixInternalRefRecursive(input: unknown, prefix: string[]) {
  * @param referencePath - The JSON pointer path to the reference
  * @param externalRefsKey - The key used for external references (e.g. 'x-ext')
  * @param documentKey - The key identifying the external document
+ * @param bundleLocalRefs - Also bundles the local refs
  * @param processedNodes - Set of already processed nodes to prevent duplicates
  * @example
  * ```ts
@@ -317,15 +303,16 @@ export function prefixInternalRefRecursive(input: unknown, prefix: string[]) {
  * // Result: target will contain the User schema with resolved references
  * ```
  */
-const resolveAndCopyReferences = (
+export const resolveAndCopyReferences = (
   targetDocument: unknown,
   sourceDocument: unknown,
   referencePath: string,
   externalRefsKey: string,
   documentKey: string,
+  bundleLocalRefs = false,
   processedNodes = new Set(),
 ) => {
-  const referencedValue = getNestedValue(sourceDocument, getSegmentsFromPath(referencePath))
+  const referencedValue = getValueByPath(sourceDocument, getSegmentsFromPath(referencePath)).value
 
   if (processedNodes.has(referencedValue)) {
     return
@@ -350,8 +337,21 @@ const resolveAndCopyReferences = (
           targetDocument,
           sourceDocument,
           node['$ref'].substring(1),
+          externalRefsKey,
           documentKey,
+          bundleLocalRefs,
+          processedNodes,
+        )
+      }
+      // Bundle the local refs as well
+      else if (bundleLocalRefs) {
+        resolveAndCopyReferences(
+          targetDocument,
+          sourceDocument,
+          node['$ref'].substring(1),
           externalRefsKey,
+          documentKey,
+          bundleLocalRefs,
           processedNodes,
         )
       }
@@ -649,6 +649,9 @@ export async function bundle(input: UnknownObject | string, config: Config) {
   // We need this when we want to do a partial bundle of a document
   const documentRoot = config.root ?? rawSpecification
 
+  // Extract all $id and $anchor values from the document to identify local schemas
+  const schemas = getSchemas(documentRoot)
+
   // Determines if the bundling operation is partial.
   // Partial bundling occurs when:
   // - A root document is provided that is different from the raw specification being bundled, or
@@ -693,7 +696,7 @@ export async function bundle(input: UnknownObject | string, config: Config) {
     origin: string = defaultOrigin(),
     isChunkParent = false,
     depth = 0,
-    path: readonly string[] = [],
+    currentPath: readonly string[] = [],
     parent: UnknownObject = null,
   ) => {
     // If a maximum depth is set in the config, stop bundling when the current depth reaches or exceeds it
@@ -715,7 +718,7 @@ export async function bundle(input: UnknownObject | string, config: Config) {
 
     // Invoke the onBeforeNodeProcess hook for the current node before any further processing
     await config.hooks?.onBeforeNodeProcess?.(root as UnknownObject, {
-      path,
+      path: currentPath,
       resolutionCache: cache,
       parentNode: parent,
       rootNode: documentRoot as UnknownObject,
@@ -724,7 +727,7 @@ export async function bundle(input: UnknownObject | string, config: Config) {
     // Invoke onBeforeNodeProcess hooks from all registered lifecycle plugins
     for (const plugin of lifecyclePlugin) {
       await plugin.onBeforeNodeProcess?.(root as UnknownObject, {
-        path,
+        path: currentPath,
         resolutionCache: cache,
         parentNode: parent,
         rootNode: documentRoot as UnknownObject,
@@ -732,20 +735,33 @@ export async function bundle(input: UnknownObject | string, config: Config) {
       })
     }
 
+    const id = getId(root)
+
     if (typeof root === 'object' && '$ref' in root && typeof root['$ref'] === 'string') {
       const ref = root['$ref']
       const isChunk = '$global' in root && typeof root['$global'] === 'boolean' && root['$global']
 
-      if (isLocalRef(ref)) {
+      // Try to convert the reference to a local reference if possible
+      // This handles cases where the reference points to a local schema using $id or $anchor
+      // If it can be converted to a local reference, we do not need to bundle it
+      // and can skip further processing for this reference
+      // In case of partial bundling, we still need to ensure that all dependencies
+      // of the local reference are bundled to create a complete and self-contained partial bundle
+      // This is important to maintain the integrity of the partial bundle
+      const localRef = convertToLocalRef(ref, id ?? origin, schemas)
+
+      if (localRef !== undefined) {
         if (isPartialBundling) {
-          const segments = getSegmentsFromPath(ref.substring(1))
-          const parent = segments.length > 0 ? getNestedValue(documentRoot, segments.slice(0, -1)) : undefined
+          const segments = getSegmentsFromPath(`/${localRef}`)
+          const parent = segments.length > 0 ? getValueByPath(documentRoot, segments.slice(0, -1)).value : undefined
+
+          const targetValue = getValueByPath(documentRoot, segments)
 
           // When doing partial bundling, we need to recursively bundle all dependencies
           // referenced by this local reference to ensure the partial bundle is complete.
           // This includes not just the direct reference but also all its dependencies,
           // creating a complete and self-contained partial bundle.
-          await bundler(getNestedValue(documentRoot, segments), origin, isChunkParent, depth + 1, segments, parent)
+          await bundler(targetValue.value, targetValue.context, isChunkParent, depth + 1, segments, parent)
         }
         return
       }
@@ -754,7 +770,7 @@ export async function bundle(input: UnknownObject | string, config: Config) {
 
       // Combine the current origin with the new path to resolve relative references
       // correctly within the context of the external file being processed
-      const resolvedPath = resolveReferencePath(origin, prefix)
+      const resolvedPath = resolveReferencePath(id ?? origin, prefix)
 
       // Generate a unique compressed path for the external document
       // This is used as a key to store and reference the bundled external document
@@ -859,14 +875,14 @@ export async function bundle(input: UnknownObject | string, config: Config) {
           return
         }
 
-        await bundler(value, origin, isChunkParent, depth + 1, [...path, key], root as UnknownObject)
+        await bundler(value, id ?? origin, isChunkParent, depth + 1, [...currentPath, key], root as UnknownObject)
       }),
     )
 
     // Invoke the optional onAfterNodeProcess hook from the config, if provided.
     // This allows for custom post-processing logic after a node has been handled by the bundler.
     await config.hooks?.onAfterNodeProcess?.(root as UnknownObject, {
-      path,
+      path: currentPath,
       resolutionCache: cache,
       parentNode: parent,
       rootNode: documentRoot as UnknownObject,
@@ -877,7 +893,7 @@ export async function bundle(input: UnknownObject | string, config: Config) {
     // This enables plugins to perform additional post-processing or cleanup after the node is processed.
     for (const plugin of lifecyclePlugin) {
       await plugin.onAfterNodeProcess?.(root as UnknownObject, {
-        path,
+        path: currentPath,
         resolutionCache: cache,
         parentNode: parent,
         rootNode: documentRoot as UnknownObject,

package/src/bundle/index.ts

@@ -1,3 +1,3 @@
-// biome-ignore lint/performance/noBarrelFile: <explanation>
-export { bundle } from './bundle'
-export type { Plugin, LoaderPlugin, LifecyclePlugin, ResolveResult } from './bundle'
+export type { LifecyclePlugin, LoaderPlugin, Plugin, ResolveResult } from './bundle'
+// biome-ignore lint/performance/noBarrelFile: exporting bundle
+export { bundle, resolveAndCopyReferences } from './bundle'

package/src/bundle/plugins/fetch-urls/index.ts

@@ -1,7 +1,7 @@
-import { normalize } from '@/utils/normalize'
-import { createLimiter } from '@/bundle/create-limiter'
 import type { LoaderPlugin, ResolveResult } from '@/bundle'
 import { isRemoteUrl } from '@/bundle/bundle'
+import { createLimiter } from '@/bundle/create-limiter'
+import { normalize } from '@/helpers/normalize'
 
 type FetchConfig = Partial<{
   headers: { headers: HeadersInit; domains: string[] }[]

package/src/bundle/plugins/parse-json/index.ts

@@ -1,5 +1,5 @@
-import { isJsonObject } from '@/utils/is-json-object'
 import type { LoaderPlugin, ResolveResult } from '@/bundle'
+import { isJsonObject } from '@/helpers/is-json-object'
 
 /**
  * Creates a plugin that parses JSON strings into JavaScript objects.

package/src/bundle/plugins/parse-yaml/index.ts

@@ -1,7 +1,8 @@
-import type { LoaderPlugin, ResolveResult } from '@/bundle'
-import { isYaml } from '@/utils/is-yaml'
 import YAML from 'yaml'
 
+import type { LoaderPlugin, ResolveResult } from '@/bundle'
+import { isYaml } from '@/helpers/is-yaml'
+
 /**
  * Creates a plugin that parses YAML strings into JavaScript objects.
  * @returns A plugin object with validate and exec functions

package/src/bundle/plugins/read-files/index.ts

@@ -1,6 +1,6 @@
-import { normalize } from '@/utils/normalize'
 import type { LoaderPlugin, ResolveResult } from '@/bundle'
 import { isFilePath } from '@/bundle/bundle'
+import { normalize } from '@/helpers/normalize'
 
 /**
  * Reads and normalizes data from a local file

package/src/helpers/convert-to-local-ref.test.ts

@@ -0,0 +1,211 @@
+import { describe, expect, it } from 'vitest'
+
+import { convertToLocalRef } from './convert-to-local-ref'
+
+describe('convertToLocalRef', () => {
+  const schemas = new Map([
+    ['https://example.com/schema1.json', '/components/schemas/Schema1'],
+    ['https://example.com/schema2.json', '/components/schemas/Schema2'],
+    ['https://example.com/schema1.json#anchor1', '/components/schemas/Schema1/definitions/Anchor1'],
+    ['https://example.com/schema2.json#anchor2', '/components/schemas/Schema2/definitions/Anchor2'],
+    ['https://example.com/current.json#currentAnchor', '/components/schemas/Current/definitions/CurrentAnchor'],
+  ])
+
+  const currentContext = 'https://example.com/current.json'
+
+  describe('external references with baseUrl', () => {
+    it('should resolve external reference without path or anchor', () => {
+      const result = convertToLocalRef('https://example.com/schema1.json', currentContext, schemas)
+
+      expect(result).toBe('/components/schemas/Schema1')
+    })
+
+    it('should resolve external reference with JSON pointer path', () => {
+      const result = convertToLocalRef('https://example.com/schema1.json#/definitions/User', currentContext, schemas)
+
+      expect(result).toBe('/components/schemas/Schema1/definitions/User')
+    })
+
+    it('should resolve external reference with anchor', () => {
+      const result = convertToLocalRef('https://example.com/schema1.json#anchor1', currentContext, schemas)
+
+      expect(result).toBe('/components/schemas/Schema1/definitions/Anchor1')
+    })
+
+    it('should return undefined for external reference not in schemas', () => {
+      const result = convertToLocalRef('https://example.com/unknown.json', currentContext, schemas)
+
+      expect(result).toBeUndefined()
+    })
+
+    it('should return undefined for external reference with unknown anchor', () => {
+      const result = convertToLocalRef('https://example.com/schema1.json#unknownAnchor', currentContext, schemas)
+
+      expect(result).toBeUndefined()
+    })
+  })
+
+  describe('local references without baseUrl', () => {
+    it('should resolve local JSON pointer path', () => {
+      const result = convertToLocalRef('#/definitions/User', currentContext, schemas)
+
+      expect(result).toBe('definitions/User')
+    })
+
+    it('should resolve local JSON pointer path with multiple segments', () => {
+      const result = convertToLocalRef('#/components/schemas/User/properties/name', currentContext, schemas)
+
+      expect(result).toBe('components/schemas/User/properties/name')
+    })
+
+    it('should resolve local anchor reference', () => {
+      const result = convertToLocalRef('#currentAnchor', currentContext, schemas)
+
+      expect(result).toBe('/components/schemas/Current/definitions/CurrentAnchor')
+    })
+
+    it('should return undefined for local anchor not in schemas', () => {
+      const result = convertToLocalRef('#unknownAnchor', currentContext, schemas)
+
+      expect(result).toBeUndefined()
+    })
+  })
+
+  describe('edge cases', () => {
+    it('should return undefined for empty reference', () => {
+      const result = convertToLocalRef('', currentContext, schemas)
+
+      expect(result).toBeUndefined()
+    })
+
+    it('should return undefined for reference with only hash', () => {
+      const result = convertToLocalRef('#', currentContext, schemas)
+
+      expect(result).toBeUndefined()
+    })
+
+    it('should return undefined for reference with only baseUrl and hash', () => {
+      const result = convertToLocalRef('https://example.com/schema1.json#', currentContext, schemas)
+
+      expect(result).toBe('/components/schemas/Schema1')
+    })
+
+    it('should handle empty currentContext', () => {
+      const result = convertToLocalRef('#anchor', '', schemas)
+
+      expect(result).toBeUndefined()
+    })
+
+    it('should handle empty schemas map', () => {
+      const emptySchemas = new Map()
+      const result = convertToLocalRef('https://example.com/schema1.json', currentContext, emptySchemas)
+
+      expect(result).toBeUndefined()
+    })
+  })
+
+  describe('complex scenarios', () => {
+    it('should handle nested JSON pointer paths', () => {
+      const result = convertToLocalRef(
+        'https://example.com/schema1.json#/definitions/User/properties/address/properties/street',
+        currentContext,
+        schemas,
+      )
+
+      expect(result).toBe('/components/schemas/Schema1/definitions/User/properties/address/properties/street')
+    })
+
+    it('should handle anchor with special characters', () => {
+      const schemasWithSpecialChars = new Map([
+        ['https://example.com/schema1.json', '/components/schemas/Schema1'],
+        [
+          'https://example.com/schema1.json#anchor-with-dashes',
+          '/components/schemas/Schema1/definitions/AnchorWithDashes',
+        ],
+        [
+          'https://example.com/schema1.json#anchor_with_underscores',
+          '/components/schemas/Schema1/definitions/AnchorWithUnderscores',
+        ],
+      ])
+
+      const result1 = convertToLocalRef(
+        'https://example.com/schema1.json#anchor-with-dashes',
+        currentContext,
+        schemasWithSpecialChars,
+      )
+
+      const result2 = convertToLocalRef(
+        'https://example.com/schema1.json#anchor_with_underscores',
+        currentContext,
+        schemasWithSpecialChars,
+      )
+
+      expect(result1).toBe('/components/schemas/Schema1/definitions/AnchorWithDashes')
+      expect(result2).toBe('/components/schemas/Schema1/definitions/AnchorWithUnderscores')
+    })
+
+    it('should handle different schema contexts', () => {
+      const differentContext = 'https://example.com/different.json'
+      const schemasWithDifferentContext = new Map([
+        [
+          'https://example.com/different.json#differentAnchor',
+          '/components/schemas/Different/definitions/DifferentAnchor',
+        ],
+      ])
+
+      const result = convertToLocalRef('#differentAnchor', differentContext, schemasWithDifferentContext)
+
+      expect(result).toBe('/components/schemas/Different/definitions/DifferentAnchor')
+    })
+  })
+
+  describe('real-world examples', () => {
+    it('should handle OpenAPI component references', () => {
+      const openApiSchemas = new Map([
+        ['https://api.example.com/schemas/user.json', '/components/schemas/User'],
+        ['https://api.example.com/schemas/user.json#/properties/id', '/components/schemas/User/properties/id'],
+        ['https://api.example.com/schemas/user.json#userProfile', '/components/schemas/User/definitions/UserProfile'],
+      ])
+
+      const result1 = convertToLocalRef(
+        'https://api.example.com/schemas/user.json',
+        'https://api.example.com/openapi.json',
+        openApiSchemas,
+      )
+
+      const result2 = convertToLocalRef(
+        'https://api.example.com/schemas/user.json#/properties/name',
+        'https://api.example.com/openapi.json',
+        openApiSchemas,
+      )
+
+      const result3 = convertToLocalRef(
+        'https://api.example.com/schemas/user.json#userProfile',
+        'https://api.example.com/openapi.json',
+        openApiSchemas,
+      )
+
+      expect(result1).toBe('/components/schemas/User')
+      expect(result2).toBe('/components/schemas/User/properties/name')
+      expect(result3).toBe('/components/schemas/User/definitions/UserProfile')
+    })
+
+    it('should handle local component references in OpenAPI', () => {
+      const openApiSchemas = new Map([
+        ['https://api.example.com/openapi.json#userSchema', '/components/schemas/User'],
+        ['https://api.example.com/openapi.json#addressSchema', '/components/schemas/Address'],
+      ])
+
+      const result1 = convertToLocalRef('#userSchema', 'https://api.example.com/openapi.json', openApiSchemas)
+
+      const result2 = convertToLocalRef(
+        '#/components/schemas/User/properties/name',
+        'https://api.example.com/openapi.json',
+        openApiSchemas,
+      )
+
+      expect(result1).toBe('/components/schemas/User')
+      expect(result2).toBe('components/schemas/User/properties/name')
+    })
+  })
+})

package/src/helpers/convert-to-local-ref.ts

@@ -0,0 +1,43 @@
+/**
+ * Translates a JSON Reference ($ref) to a local object path within the root schema.
+ *
+ * @param ref - The JSON Reference string (e.g., "#/foo/bar", "other.json#/baz", "other.json#anchor")
+ * @param currentContext - The current base context (usually the $id of the current schema or parent)
+ * @param schemas - A map of schema identifiers ($id, $anchor) to their local object paths
+ * @returns The local object path as a string, or undefined if the reference cannot be resolved
+ */
+export const convertToLocalRef = (
+  ref: string,
+  currentContext: string,
+  schemas: Map<string, string>,
+): string | undefined => {
+  // Split the reference into base URL and path/anchor (e.g., "foo.json#/bar" => ["foo.json", "/bar"])
+  const [baseUrl, pathOrAnchor] = ref.split('#', 2)
+
+  if (baseUrl) {
+    if (!schemas.has(baseUrl)) {
+      return undefined
+    }
+
+    if (!pathOrAnchor) {
+      return schemas.get(baseUrl)
+    }
+
+    // If the pathOrAnchor is a JSON pointer, we need to append it to the baseUrl
+    if (pathOrAnchor.startsWith('/')) {
+      return `${schemas.get(baseUrl)}${pathOrAnchor}`
+    }
+
+    // If the pathOrAnchor is an anchor, we need to return the anchor
+    return schemas.get(`${baseUrl}#${pathOrAnchor}`)
+  }
+
+  if (pathOrAnchor) {
+    if (pathOrAnchor.startsWith('/')) {
+      return pathOrAnchor.slice(1)
+    }
+    return schemas.get(`${currentContext}#${pathOrAnchor}`)
+  }
+
+  return undefined
+}