@speclynx/apidom-reference 5.2.2 → 5.2.5

package/src/bundle/strategies/openapi-3-1/visitor.cjs

@@ -67,6 +67,12 @@ const componentFieldElementByField = {
   [cf.pathItems.name]: _apidomNsOpenapi.ComponentsPathItemsElement
 };
 
+/**
+ * A bundled element awaiting placement into the entry document's Components
+ * Object field.
+ * @public
+ */
+
 /**
  * @public
  */
@@ -124,18 +130,50 @@ class OpenAPI3_1BundleVisitor {
    * generic object referenced once as a Parameter and once as a Response).
    */
   refractCache;
+
+  /**
+   * Index of `$id`-bearing schemas per document, shared across the entry document
+   * and every external document visitor of a single bundle run so it never
+   * outlives mutations of the documents (e.g. the final placement of components).
+   */
+  schema$idIndex;
+
+  /**
+   * Bundled fragments waiting to be placed into the entry document's
+   * Components Object, shared across the entry document and every external
+   * document visitor. Placement is deferred until the entry document traversal
+   * completes: the traversal walks live content, so placing a fragment mid-way
+   * would make it descend into the fragment and re-bundle its `$ref`s against
+   * the entry document's base URI instead of the fragment's own.
+   */
+  placements;
+
+  /**
+   * The base URI the traversed content will have once placed into the entry
+   * document, when placement changes it: content hoisted out of a non-schema
+   * document (a Response, Parameter, Path Item, ...) trades that document's
+   * base URI for the entry document's. Unset for the entry document itself and
+   * for embedded schema resources, whose `$id` carries their base along.
+   */
+  relocationBaseURI;
   constructor({
     reference,
     options,
     assignments = new Map(),
     reservedNames = new Map(),
-    refractCache = new WeakMap()
+    refractCache = new WeakMap(),
+    schema$idIndex = new WeakMap(),
+    placements = [],
+    relocationBaseURI
   }) {
     this.reference = reference;
     this.options = options;
     this.assignments = assignments;
     this.reservedNames = reservedNames;
     this.refractCache = refractCache;
+    this.schema$idIndex = schema$idIndex;
+    this.placements = placements;
+    this.relocationBaseURI = relocationBaseURI;
   }
   getRefracted(source, type) {
     return this.refractCache.get(source)?.get(type);
@@ -193,6 +231,22 @@ class OpenAPI3_1BundleVisitor {
     return ref.startsWith('#') ? ref : url.getHash(ref);
   }
 
+  /**
+   * The base URI the given Schema Object's `$ref` will be resolved against once
+   * the content is placed into the entry document, or `undefined` when the
+   * `$ref` as written resolves to `$refBaseURI` from there as well: the content
+   * isn't relocated, an absolute `$id` on the schema's ancestor chain pins its
+   * base, or the hoisted document sits next to the entry document.
+   */
+  relocatedSchemaBaseURI(path, $refBaseURI) {
+    if (this.relocationBaseURI === undefined) return undefined;
+    const relocatedBaseURI = (0, _util.resolveSchemaBaseURI)(this.relocationBaseURI, path);
+    if ((0, _util.resolveSchema$refField)(relocatedBaseURI, path.node) === $refBaseURI) {
+      return undefined;
+    }
+    return relocatedBaseURI;
+  }
+
   /**
    * Handles an error according to the `bundle.continueOnError` option.
    *
@@ -311,13 +365,16 @@ class OpenAPI3_1BundleVisitor {
 
   /**
    * Computes a collision-free component name within the target field. A name is
-   * taken if it's already placed in components or reserved by a component that
-   * is still being bundled (reserved before recursion).
+   * taken if it's already present in the entry document's components or reserved
+   * by a component that is still being bundled (reserved before recursion).
    */
   uniqueName(candidate, field) {
-    const fieldElement = this.ensureComponentsField(field);
+    const {
+      components
+    } = this.entryResult;
+    const fieldElement = (0, _apidomDatamodel.isObjectElement)(components) ? components.get(field) : undefined;
     const reserved = this.reservedNames.get(field) ?? new Set();
-    return (0, _util2.uniqueName)(candidate, name => fieldElement.hasKey(name) || reserved.has(name));
+    return (0, _util2.uniqueName)(candidate, name => (0, _apidomDatamodel.isObjectElement)(fieldElement) && fieldElement.hasKey(name) || reserved.has(name));
   }
 
   /**
@@ -341,6 +398,28 @@ class OpenAPI3_1BundleVisitor {
     // append (never prepend) so the result element stays ahead of annotations
     this.entryParseResult.content.push(annotation);
   }
+
+  /**
+   * The entry document traversal is rooted at its Parse Result (nested
+   * traversals are rooted at fragments), so leaving it marks the moment the
+   * whole entry document has been visited and the collected fragments can be
+   * placed into its Components Object without the traversal descending into them.
+   * Guarded on the node so that a traversal rooted at any other Parse Result
+   * never flushes the shared placements early.
+   */
+  ParseResultElement = {
+    leave: path => {
+      if (path.node !== this.entryParseResult) return;
+      for (const {
+        field,
+        name,
+        element
+      } of this.placements) {
+        this.ensureComponentsField(field).set(name, element);
+      }
+      this.placements.length = 0;
+    }
+  };
   async ReferenceElement(path) {
     const referencingElement = path.node;
     const $ref = (0, _apidomCore.toValue)(referencingElement.$ref);
@@ -428,14 +507,19 @@ class OpenAPI3_1BundleVisitor {
       if (!this.reservedNames.has(field)) this.reservedNames.set(field, new Set());
       this.reservedNames.get(field).add(componentName);
 
-      // own a copy of the fragment and bundle its own external references
+      // own a copy of the fragment and bundle its own external references; the
+      // fragment ends up in the entry document, so that is where its content
+      // resolves relative references from
       const hoistedElement = (0, _apidomDatamodel.cloneDeep)(referencedElement);
       const visitor = new OpenAPI3_1BundleVisitor({
         reference,
         options: this.options,
         assignments: this.assignments,
         reservedNames: this.reservedNames,
-        refractCache: this.refractCache
+        refractCache: this.refractCache,
+        schema$idIndex: this.schema$idIndex,
+        placements: this.placements,
+        relocationBaseURI: this.entryURI
       });
       const bundledElement = await (0, _apidomTraverse.traverseAsync)(hoistedElement, visitor, {
         mutable: true
@@ -446,8 +530,12 @@ class OpenAPI3_1BundleVisitor {
         bundledElement.meta.set('ref-origin', reference.uri);
       }
 
-      // place the bundled fragment into the entry document's components
-      this.ensureComponentsField(field).set(componentName, bundledElement);
+      // queue the bundled fragment for placement into the entry document's components
+      this.placements.push({
+        field,
+        name: componentName,
+        element: bundledElement
+      });
 
       // rewrite the referencing element to point at the hoisted fragment
       referencingElement.set('$ref', internalPointer);
@@ -536,14 +624,19 @@ class OpenAPI3_1BundleVisitor {
       if (!this.reservedNames.has(field)) this.reservedNames.set(field, new Set());
       this.reservedNames.get(field).add(componentName);
 
-      // own a copy of the fragment and bundle its own external references
+      // own a copy of the fragment and bundle its own external references; the
+      // Path Item ends up in the entry document, so that is where its content
+      // resolves relative references from
       const hoistedElement = (0, _apidomDatamodel.cloneDeep)(referencedElement);
       const visitor = new OpenAPI3_1BundleVisitor({
         reference,
         options: this.options,
         assignments: this.assignments,
         reservedNames: this.reservedNames,
-        refractCache: this.refractCache
+        refractCache: this.refractCache,
+        schema$idIndex: this.schema$idIndex,
+        placements: this.placements,
+        relocationBaseURI: this.entryURI
       });
       const bundledElement = await (0, _apidomTraverse.traverseAsync)(hoistedElement, visitor, {
         mutable: true
@@ -554,8 +647,12 @@ class OpenAPI3_1BundleVisitor {
       // internal `#/components/pathItems/...` pointer by the child traversal
       bundledElement.meta.set('ref-origin', reference.uri);
 
-      // place the bundled Path Item into the entry document's components
-      this.ensureComponentsField(field).set(componentName, bundledElement);
+      // queue the bundled Path Item for placement into the entry document's components
+      this.placements.push({
+        field,
+        name: componentName,
+        element: bundledElement
+      });
 
       // rewrite the referencing Path Item to point at the hoisted one, keeping
       // any sibling fields (e.g. summary, description) next to the $ref
@@ -590,7 +687,8 @@ class OpenAPI3_1BundleVisitor {
       // toReference) so an internal $ref needs no resolution and never trips the
       // resolve.maxDepth guard, matching how ReferenceElement returns early.
       const retrievalURI = this.reference.uri;
-      const $refBaseURI = (0, _util.resolveSchema$refField)(retrievalURI, referencingElement);
+      const schemaBaseURI = (0, _util.resolveSchemaBaseURI)(retrievalURI, path);
+      const $refBaseURI = (0, _util.resolveSchema$refField)(schemaBaseURI, referencingElement);
       const $refBaseURIStrippedHash = url.stripHash($refBaseURI);
       const file = new _File.default({
         uri: $refBaseURIStrippedHash
@@ -626,59 +724,95 @@ class OpenAPI3_1BundleVisitor {
       // as a canonical URI / URL against the current document's $id graph; if
       // that fails, fall back to fetching the external document and resolving
       // the fragment there as a $anchor or JSON Pointer.
+      //
+      // the fragment being traversed is searched before the whole document:
+      // content hoisted out of an external document (a Response, Parameter, Path
+      // Item, ...) is refracted with its own semantics, so the Schema Objects it
+      // contains are indexed, whereas the external document as a whole is parsed
+      // generically and refracted as a bare JSON Schema, which leaves those Schema
+      // Objects (under `content`, `schema`, ...) unrecognized and their `$id`s out
+      // of the index
+      const documentElement = this.reference.value.result;
+      const rootNode = path.getAncestorNodes().at(-1) ?? path.node;
+      const fragmentElement = (0, _apidomDatamodel.isParseResultElement)(rootNode) ? rootNode.result : rootNode;
+      const uriEvaluateOptions = {
+        baseURI: retrievalURI,
+        index: this.schema$idIndex
+      };
       let schemaReference = this.reference;
+      let resourceRoot;
+      let resourceBaseURI;
       try {
-        const referenceAsSchema = (0, _util.maybeRefractToSchemaElement)(schemaReference.value.result);
-        (0, _uri.evaluate)($refBaseURI, referenceAsSchema);
+        try {
+          (0, _uri.evaluate)($refBaseURI, (0, _util.maybeRefractToSchemaElement)(fragmentElement), uriEvaluateOptions);
+          // a $ref that resolves (by $id/$anchor/pointer) within the traversed
+          // content is internal even when its URI form (e.g. a URN or absolute
+          // $id) is not a bare fragment: the $id resource travels with the content
+          // wherever it is placed. Leave it untouched — it resolves against the
+          // in-content $id graph, and embedding the content into itself would be
+          // wrong.
+          return;
+        } catch (error) {
+          if (!(error instanceof _EvaluationJsonSchemaUriError.default) || fragmentElement === documentElement) {
+            throw error;
+          }
+          const documentAsSchema = (0, _util.maybeRefractToSchemaElement)(documentElement);
+          (0, _uri.evaluate)($refBaseURI, documentAsSchema, uriEvaluateOptions);
+          // the $id resource sits in the current document but outside the
+          // traversed fragment, so it stays behind once the fragment is placed
+          // into the entry document. The resource to embed is that $id-bearing
+          // schema, addressed by its canonical URI (the $ref without fragment).
+          resourceRoot = (0, _uri.evaluate)($refBaseURIStrippedHash, documentAsSchema, uriEvaluateOptions);
+          resourceBaseURI = $refBaseURIStrippedHash;
+        }
       } catch (error) {
         if (isURL && error instanceof _EvaluationJsonSchemaUriError.default) {
+          schemaReference = await this.toReference(url.unsanitize($refBaseURI));
+          const referenceAsSchema = (0, _util.maybeRefractToSchemaElement)(schemaReference.value.result);
           if ((0, _$anchor.isAnchor)((0, _$anchor.uriToAnchor)($refBaseURI))) {
-            schemaReference = await this.toReference(url.unsanitize($refBaseURI));
             const selector = (0, _$anchor.uriToAnchor)($refBaseURI);
-            const referenceAsSchema = (0, _util.maybeRefractToSchemaElement)(schemaReference.value.result);
             (0, _$anchor.evaluate)(selector, referenceAsSchema);
           } else {
-            schemaReference = await this.toReference(url.unsanitize($refBaseURI));
             const selector = _apidomJsonPointer.URIFragmentIdentifier.fromURIReference($refBaseURI);
-            const referenceAsSchema = (0, _util.maybeRefractToSchemaElement)(schemaReference.value.result);
             (0, _apidomJsonPointer.evaluate)(referenceAsSchema, selector);
           }
+
+          // the resource to embed is the WHOLE external document (its root
+          // schema), identified by its $id. A $ref into a fragment of the
+          // document embeds the entire document resource once; the fragment
+          // keeps resolving against the embedded $id.
+          resourceRoot = referenceAsSchema;
+          resourceBaseURI = (0, _util.resolveSchema$idField)(url.stripHash(schemaReference.uri), resourceRoot) ?? url.stripHash(schemaReference.uri);
         } else {
           throw error;
         }
       }
-
-      // a $ref that resolves (by $id/$anchor/pointer) within the current document
-      // is internal even when its URI form (e.g. a URN or absolute $id) is not a
-      // bare fragment. Leave it untouched — it resolves against the in-document
-      // $id graph, and embedding the current document into itself would be wrong.
-      if (url.stripHash(schemaReference.uri) === url.stripHash(this.reference.uri)) {
-        return;
-      }
-
-      // the resource to embed is the WHOLE external document (its root schema),
-      // identified by its $id. A $ref into a fragment of the document embeds the
-      // entire document resource once; the fragment keeps resolving against the
-      // embedded $id.
-      const resourceRoot = (0, _util.maybeRefractToSchemaElement)(schemaReference.value.result);
-      const resourceBaseURI = (0, _util.resolveSchema$idField)(url.stripHash(schemaReference.uri), resourceRoot) ?? url.stripHash(schemaReference.uri);
       const field = cf.schemas.name;
       const canonicalKey = `${field}\t${resourceBaseURI}`;
 
-      // resource already embedded (or being embedded) — leave the referencing
-      // $ref untouched and stop. This also terminates circular external schema
+      // a location-based $ref to a self-identifying resource is rebased onto the
+      // resource's $id (keeping its fragment) — once embedded, the resource is
+      // reachable only by its $id. A $ref already resolving to that $id is left
+      // as written. See rebaseSchema$ref for the spec trade-off.
+      //
+      // a $ref whose base URI changes on relocation into the entry document
+      // (inside a hoisted Response, Parameter, Path Item, ...) is instead
+      // rewritten to address the embedded resource from the base it will have
+      // there, otherwise it dangles once placed. See relocateSchema$ref.
+      const relocatedBaseURI = this.relocatedSchemaBaseURI(path, $refBaseURI);
+      const rebased$ref = relocatedBaseURI === undefined ? (0, _util2.rebaseSchema$ref)($refBaseURI, resourceBaseURI) : (0, _util2.relocateSchema$ref)($refBaseURI, resourceBaseURI, relocatedBaseURI, (0, _apidomDatamodel.isStringElement)(resourceRoot.$id));
+
+      // resource already embedded (or being embedded) — point the referencing
+      // $ref at it and stop. This also terminates circular external schema
       // references, since the assignment is reserved BEFORE recursion.
       if (this.assignments.has(canonicalKey)) {
+        if (rebased$ref !== undefined) referencingElement.set('$ref', rebased$ref);
         path.skip();
         return;
       }
 
-      // own a copy of the resource and ensure it carries a $id so the unchanged
-      // $ref still resolves against it once embedded
+      // own a copy of the resource
       const embeddedElement = (0, _apidomDatamodel.cloneDeep)(resourceRoot);
-      if (!(0, _apidomDatamodel.isStringElement)(embeddedElement.$id)) {
-        embeddedElement.set('$id', resourceBaseURI);
-      }
 
       // the embedded thing is the WHOLE resource (keyed by its $id), so its name
       // is derived from the resource URI, not the $ref fragment — passing a root
@@ -700,20 +834,36 @@ class OpenAPI3_1BundleVisitor {
         options: this.options,
         assignments: this.assignments,
         reservedNames: this.reservedNames,
-        refractCache: this.refractCache
+        refractCache: this.refractCache,
+        schema$idIndex: this.schema$idIndex,
+        placements: this.placements
       });
       const bundledElement = await (0, _apidomTraverse.traverseAsync)(embeddedElement, visitor, {
         mutable: true
       });
 
+      // a resource without its own $id is identified by its retrieval URI; write
+      // it relative to the entry document (the base of components.schemas) so the
+      // bundle carries no absolute filesystem path and stays relocatable. Assigned
+      // after the nested traversal so a reader deriving a schema's base from live
+      // $ids (see #540) never resolves the resource's own $refs against the entry
+      // document.
+      if (!(0, _apidomDatamodel.isStringElement)(bundledElement.$id)) {
+        bundledElement.set('$id', url.relative(this.entryURI, resourceBaseURI));
+      }
+
       // annotate the embedded resource with info about its origin
       bundledElement.meta.set('ref-origin', schemaReference.uri);
 
-      // place the embedded resource into the entry document's components
-      this.ensureComponentsField(field).set(componentName, bundledElement);
+      // queue the embedded resource for placement into the entry document's components
+      this.placements.push({
+        field,
+        name: componentName,
+        element: bundledElement
+      });
 
-      // the referencing $ref is left UNCHANGED — it resolves against the
-      // embedded resource's $id
+      // point the referencing $ref at the embedded resource's $id
+      if (rebased$ref !== undefined) referencingElement.set('$ref', rebased$ref);
       path.skip();
     } catch (error) {
       this.handleError(`Error while bundling Schema Object. Cannot resolve $ref "${$ref}": ${error.message}`, error, referencingElement, '$ref', $ref, path);