@speclynx/apidom-reference 5.1.0 → 5.2.1

package/src/parse/parsers/arazzo-json-1/source-descriptions.cjs

@@ -16,6 +16,7 @@ var _File = _interopRequireDefault(require("../../../File.cjs"));
 var url = _interopRequireWildcard(require("../../../util/url.cjs"));
 var _util = require("../../../options/util.cjs");
 var _index = _interopRequireDefault(require("../../index.cjs"));
+var _util2 = require("../../../dereference/strategies/arazzo-1/util.cjs");
 // shared key for recursion state (works across JSON/YAML parsers)
 const ARAZZO_RECURSION_KEY = 'arazzo-1';
 /**
@@ -188,8 +189,12 @@ async function parseSourceDescriptions(parseResult, parseResultRetrievalURI, opt
   const currentDepth = sharedOpts.sourceDescriptionsDepth ?? 0;
   const visitedUrls = sharedOpts.sourceDescriptionsVisitedUrls ?? new Set();
 
-  // add current file to visited URLs to prevent cycles
+  // base URI for resolving source description URLs honors Arazzo `$self` field
+  const baseURI = (0, _util2.resolveArazzo$selfField)(file.uri, api);
+
+  // add current file to visited URLs to prevent cycles (by retrieval URI and by identity)
   visitedUrls.add(file.uri);
+  visitedUrls.add(baseURI);
   if (currentDepth >= maxDepth) {
     const annotation = new _apidomDatamodel.AnnotationElement(`Maximum parse depth of ${maxDepth} has been exceeded by file "${file.uri}"`);
     annotation.classes.push('error');
@@ -198,7 +203,7 @@ async function parseSourceDescriptions(parseResult, parseResultRetrievalURI, opt
     return [parseResult];
   }
   const ctx = {
-    baseURI: file.uri,
+    baseURI,
     options,
     currentDepth,
     visitedUrls

package/src/parse/parsers/arazzo-json-1/source-descriptions.mjs

@@ -7,7 +7,8 @@ import { toValue } from '@speclynx/apidom-core';
 import File from "../../../File.mjs";
 import * as url from "../../../util/url.mjs";
 import { merge as mergeOptions } from "../../../options/util.mjs";
-import parse from "../../index.mjs"; // shared key for recursion state (works across JSON/YAML parsers)
+import parse from "../../index.mjs";
+import { resolveArazzo$selfField } from "../../../dereference/strategies/arazzo-1/util.mjs"; // shared key for recursion state (works across JSON/YAML parsers)
 const ARAZZO_RECURSION_KEY = 'arazzo-1';
 /**
  * Parses a single source description element.
@@ -179,8 +180,12 @@ export async function parseSourceDescriptions(parseResult, parseResultRetrievalU
   const currentDepth = sharedOpts.sourceDescriptionsDepth ?? 0;
   const visitedUrls = sharedOpts.sourceDescriptionsVisitedUrls ?? new Set();
 
-  // add current file to visited URLs to prevent cycles
+  // base URI for resolving source description URLs honors Arazzo `$self` field
+  const baseURI = resolveArazzo$selfField(file.uri, api);
+
+  // add current file to visited URLs to prevent cycles (by retrieval URI and by identity)
   visitedUrls.add(file.uri);
+  visitedUrls.add(baseURI);
   if (currentDepth >= maxDepth) {
     const annotation = new AnnotationElement(`Maximum parse depth of ${maxDepth} has been exceeded by file "${file.uri}"`);
     annotation.classes.push('error');
@@ -189,7 +194,7 @@ export async function parseSourceDescriptions(parseResult, parseResultRetrievalU
     return [parseResult];
   }
   const ctx = {
-    baseURI: file.uri,
+    baseURI,
     options,
     currentDepth,
     visitedUrls

package/types/bundle/strategies/arazzo-1/visitor.d.ts

@@ -17,6 +17,12 @@ export interface Arazzo1BundleVisitorOptions {
  */
 declare class Arazzo1BundleVisitor {
     protected readonly reference: Reference;
+    /**
+     * Base URI of the current document for resolving relative references.
+     * Honors the Arazzo `$self` field when present, otherwise falls back
+     * to the retrieval URI (`this.reference.uri`).
+     */
+    protected readonly baseURI: string;
     protected readonly options: ReferenceOptions;
     /**
      * The entry parse result. Derived from the shared refSet's root reference.

package/types/dereference/strategies/arazzo-1/index.d.ts

@@ -28,6 +28,6 @@ declare class Arazzo1DereferenceStrategy extends DereferenceStrategy {
     dereference(file: File, options: ReferenceOptions): Promise<Element>;
 }
 export { Arazzo1DereferenceVisitor };
-export { resolveSchema$refField, resolveSchema$idField, maybeRefractToJSONSchemaElement, } from './util.ts';
+export { resolveSchema$refField, resolveSchema$idField, resolveArazzo$selfField, identifiedBy$self, maybeRefractToJSONSchemaElement, } from './util.ts';
 export { dereferenceSourceDescriptions } from './source-descriptions.ts';
 export default Arazzo1DereferenceStrategy;

package/types/dereference/strategies/arazzo-1/util.d.ts

@@ -1,5 +1,27 @@
 import { Element } from '@speclynx/apidom-datamodel';
+import type Reference from '../../../Reference.ts';
 export { resolveSchema$refField, resolveSchema$idField } from '../openapi-3-1/util.ts';
+/**
+ * Computes the base URI of an Arazzo document per Arazzo 1.1.0 rules.
+ *
+ * When the Arazzo Object carries a `$self` field, it establishes the document's
+ * canonical identity and the base URI for resolving relative references. `$self`
+ * may itself be relative, in which case it's resolved against the retrieval URI.
+ * Any fragment is stripped, as `$self` MUST NOT contain one. When `$self` is
+ * absent (or `element` is not an Arazzo document), the retrieval URI is the base URI.
+ *
+ * @public
+ */
+export declare const resolveArazzo$selfField: (retrievalURI: string, element: unknown) => string;
+/**
+ * Predicate matching a Reference by the identity (`$self`) of the Arazzo
+ * document it holds, rather than by its retrieval URI. Implements identity-based
+ * referencing from Arazzo 1.1.0: a URI matching a loaded document's `$self`
+ * refers to that document, regardless of where it was retrieved from.
+ *
+ * @public
+ */
+export declare const identifiedBy$self: (uri: string) => (reference: Reference) => boolean;
 /**
  * Cached version of JSONSchemaElement.refract.
  */

package/types/dereference/strategies/arazzo-1/visitor.d.ts

@@ -19,6 +19,12 @@ export interface Arazzo1DereferenceVisitorOptions {
 declare class Arazzo1DereferenceVisitor {
     protected readonly indirections: Element[];
     protected readonly reference: Reference;
+    /**
+     * Base URI of the current document for resolving relative references.
+     * Honors the Arazzo `$self` field when present, otherwise falls back
+     * to the retrieval URI (`this.reference.uri`).
+     */
+    protected readonly baseURI: string;
     protected readonly options: ReferenceOptions;
     protected readonly visited: WeakSet<Element>;
     /**