@speclynx/apidom-reference 5.1.1 → 5.2.2

package/src/dereference/strategies/arazzo-1/util.cjs

@@ -1,9 +1,10 @@
 "use strict";
 
+var _interopRequireWildcard = require("@babel/runtime-corejs3/helpers/interopRequireWildcard").default;
 Object.defineProperty(exports, "__esModule", {
   value: true
 });
-exports.refractToJSONSchemaElement = exports.maybeRefractToJSONSchemaElement = void 0;
+exports.resolveArazzo$selfField = exports.refractToJSONSchemaElement = exports.maybeRefractToJSONSchemaElement = exports.identifiedBy$self = exports.arazzoDocumentURIs = void 0;
 Object.defineProperty(exports, "resolveSchema$idField", {
   enumerable: true,
   get: function () {
@@ -16,12 +17,96 @@ Object.defineProperty(exports, "resolveSchema$refField", {
     return _util.resolveSchema$refField;
   }
 });
+exports.validateSourceDescriptionAPI = void 0;
 var _apidomDatamodel = require("@speclynx/apidom-datamodel");
+var _apidomCore = require("@speclynx/apidom-core");
 var _apidomNsArazzo = require("@speclynx/apidom-ns-arazzo-1");
+var _apidomNsOpenapi = require("@speclynx/apidom-ns-openapi-2");
+var _apidomNsOpenapi2 = require("@speclynx/apidom-ns-openapi-3-0");
+var _apidomNsOpenapi3 = require("@speclynx/apidom-ns-openapi-3-1");
+var url = _interopRequireWildcard(require("../../../util/url.cjs"));
 var _util = require("../openapi-3-1/util.cjs");
+/**
+ * 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
+ */
+const resolveArazzo$selfField = (retrievalURI, element) => {
+  if (!(0, _apidomNsArazzo.isArazzoSpecification1Element)(element)) {
+    return retrievalURI;
+  }
+  const $self = (0, _apidomCore.toValue)(element.$self);
+  if (typeof $self !== 'string' || $self === '') {
+    return retrievalURI;
+  }
+  return url.resolve(retrievalURI, url.sanitize(url.stripHash($self)));
+};
+
+/**
+ * URIs an Arazzo document is known by: its retrieval URI and, when the
+ * document carries a `$self` field resolving elsewhere, its identity.
+ */
+exports.resolveArazzo$selfField = resolveArazzo$selfField;
+const arazzoDocumentURIs = (retrievalURI, element) => {
+  const identity = resolveArazzo$selfField(retrievalURI, element);
+  return identity === retrievalURI ? [retrievalURI] : [retrievalURI, identity];
+};
+
+/**
+ * Annotates a source description result when the document is not an OpenAPI
+ * or Arazzo document, or does not match the type the source description declares.
+ */
+exports.arazzoDocumentURIs = arazzoDocumentURIs;
+const validateSourceDescriptionAPI = (parseResult, sourceDescription, sourceDescriptionAPI, retrievalURI) => {
+  // only allow OpenAPI and Arazzo as source descriptions
+  const isOpenApi = (0, _apidomNsOpenapi.isSwaggerElement)(sourceDescriptionAPI) || (0, _apidomNsOpenapi2.isOpenApi3_0Element)(sourceDescriptionAPI) || (0, _apidomNsOpenapi3.isOpenApi3_1Element)(sourceDescriptionAPI);
+  const isArazzo = (0, _apidomNsArazzo.isArazzoSpecification1Element)(sourceDescriptionAPI);
+  if (!isOpenApi && !isArazzo) {
+    const annotation = new _apidomDatamodel.AnnotationElement(`Source description "${retrievalURI}" is not an OpenAPI or Arazzo document`);
+    annotation.classes.push('warning');
+    parseResult.push(annotation);
+    return;
+  }
+
+  // validate declared type matches actual type
+  const declaredType = (0, _apidomCore.toValue)(sourceDescription.type);
+  if (typeof declaredType === 'string') {
+    if (declaredType === 'openapi' && !isOpenApi) {
+      const annotation = new _apidomDatamodel.AnnotationElement(`Source description "${retrievalURI}" declared as "openapi" but is an Arazzo document`);
+      annotation.classes.push('warning');
+      parseResult.push(annotation);
+    } else if (declaredType === 'arazzo' && !isArazzo) {
+      const annotation = new _apidomDatamodel.AnnotationElement(`Source description "${retrievalURI}" declared as "arazzo" but is an OpenAPI document`);
+      annotation.classes.push('warning');
+      parseResult.push(annotation);
+    }
+  }
+};
+
+/**
+ * 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
+ */
+exports.validateSourceDescriptionAPI = validateSourceDescriptionAPI;
+const identifiedBy$self = uri => reference => {
+  const result = reference.value?.result;
+  return (0, _apidomNsArazzo.isArazzoSpecification1Element)(result) && resolveArazzo$selfField(reference.uri, result) === uri;
+};
+
 /**
  * Cached version of JSONSchemaElement.refract.
  */
+exports.identifiedBy$self = identifiedBy$self;
 const refractToJSONSchemaElement = element => {
   if (refractToJSONSchemaElement.cache.has(element)) {
     return refractToJSONSchemaElement.cache.get(element);

package/src/dereference/strategies/arazzo-1/util.mjs

@@ -1,6 +1,85 @@
-import { isPrimitiveElement } from '@speclynx/apidom-datamodel';
-import { refractJSONSchema } from '@speclynx/apidom-ns-arazzo-1';
+import { AnnotationElement, isPrimitiveElement } from '@speclynx/apidom-datamodel';
+import { toValue } from '@speclynx/apidom-core';
+import { refractJSONSchema, isArazzoSpecification1Element } from '@speclynx/apidom-ns-arazzo-1';
+import { isSwaggerElement } from '@speclynx/apidom-ns-openapi-2';
+import { isOpenApi3_0Element } from '@speclynx/apidom-ns-openapi-3-0';
+import { isOpenApi3_1Element } from '@speclynx/apidom-ns-openapi-3-1';
+import * as url from "../../../util/url.mjs";
 export { resolveSchema$refField, resolveSchema$idField } from "../openapi-3-1/util.mjs";
+/**
+ * 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 const resolveArazzo$selfField = (retrievalURI, element) => {
+  if (!isArazzoSpecification1Element(element)) {
+    return retrievalURI;
+  }
+  const $self = toValue(element.$self);
+  if (typeof $self !== 'string' || $self === '') {
+    return retrievalURI;
+  }
+  return url.resolve(retrievalURI, url.sanitize(url.stripHash($self)));
+};
+
+/**
+ * URIs an Arazzo document is known by: its retrieval URI and, when the
+ * document carries a `$self` field resolving elsewhere, its identity.
+ */
+export const arazzoDocumentURIs = (retrievalURI, element) => {
+  const identity = resolveArazzo$selfField(retrievalURI, element);
+  return identity === retrievalURI ? [retrievalURI] : [retrievalURI, identity];
+};
+
+/**
+ * Annotates a source description result when the document is not an OpenAPI
+ * or Arazzo document, or does not match the type the source description declares.
+ */
+export const validateSourceDescriptionAPI = (parseResult, sourceDescription, sourceDescriptionAPI, retrievalURI) => {
+  // only allow OpenAPI and Arazzo as source descriptions
+  const isOpenApi = isSwaggerElement(sourceDescriptionAPI) || isOpenApi3_0Element(sourceDescriptionAPI) || isOpenApi3_1Element(sourceDescriptionAPI);
+  const isArazzo = isArazzoSpecification1Element(sourceDescriptionAPI);
+  if (!isOpenApi && !isArazzo) {
+    const annotation = new AnnotationElement(`Source description "${retrievalURI}" is not an OpenAPI or Arazzo document`);
+    annotation.classes.push('warning');
+    parseResult.push(annotation);
+    return;
+  }
+
+  // validate declared type matches actual type
+  const declaredType = toValue(sourceDescription.type);
+  if (typeof declaredType === 'string') {
+    if (declaredType === 'openapi' && !isOpenApi) {
+      const annotation = new AnnotationElement(`Source description "${retrievalURI}" declared as "openapi" but is an Arazzo document`);
+      annotation.classes.push('warning');
+      parseResult.push(annotation);
+    } else if (declaredType === 'arazzo' && !isArazzo) {
+      const annotation = new AnnotationElement(`Source description "${retrievalURI}" declared as "arazzo" but is an OpenAPI document`);
+      annotation.classes.push('warning');
+      parseResult.push(annotation);
+    }
+  }
+};
+
+/**
+ * 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 const identifiedBy$self = uri => reference => {
+  const result = reference.value?.result;
+  return isArazzoSpecification1Element(result) && resolveArazzo$selfField(reference.uri, result) === uri;
+};
+
 /**
  * Cached version of JSONSchemaElement.refract.
  */

package/src/dereference/strategies/arazzo-1/visitor.cjs

@@ -37,6 +37,13 @@ var _EvaluationJsonSchemaUriError = _interopRequireDefault(require("../../../err
 class Arazzo1DereferenceVisitor {
   indirections;
   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`).
+   */
+  baseURI;
   options;
   visited;
 
@@ -55,6 +62,7 @@ class Arazzo1DereferenceVisitor {
   }) {
     this.indirections = indirections;
     this.reference = reference;
+    this.baseURI = (0, _util2.resolveArazzo$selfField)(reference.uri, reference.value?.result);
     this.options = options;
     this.ancestors = new _util3.AncestorLineage(...ancestors);
     this.visited = visited;
@@ -66,7 +74,7 @@ class Arazzo1DereferenceVisitor {
     return [ancestorsLineage, directAncestors];
   }
   toBaseURI(uri) {
-    return url.resolve(this.reference.uri, url.sanitize(url.stripHash(uri)));
+    return url.resolve(this.baseURI, url.sanitize(url.stripHash(uri)));
   }
   async toReference(uri) {
     // detect maximum depth of resolution
@@ -85,6 +93,12 @@ class Arazzo1DereferenceVisitor {
     if (refSet.has(baseURI)) {
       return refSet.find((0, _ramda.propEq)(baseURI, 'uri'));
     }
+
+    // identity-based referencing: URI matches `$self` of an already processed Arazzo document
+    const referenceBy$self = refSet.find((0, _util2.identifiedBy$self)(baseURI));
+    if (referenceBy$self !== undefined) {
+      return referenceBy$self;
+    }
     const parseResult = await (0, _index.default)(url.unsanitize(baseURI), {
       ...this.options,
       parse: {
@@ -288,19 +302,19 @@ class Arazzo1DereferenceVisitor {
     }
     const indirectionsSize = this.indirections.length;
     try {
-      // compute baseURI using rules around $id and $ref keywords
+      // compute baseURI using rules around $self, $id and $ref keywords
       let reference = await this.toReference(url.unsanitize(this.reference.uri));
       let {
         uri: retrievalURI
       } = reference;
-      const $refBaseURI = (0, _util.resolveSchema$refField)(retrievalURI, referencingElement);
+      const $refBaseURI = (0, _util.resolveSchema$refField)(this.baseURI, referencingElement);
       const $refBaseURIStrippedHash = url.stripHash($refBaseURI);
       const file = new _File.default({
         uri: $refBaseURIStrippedHash
       });
       const isUnknownURI = (0, _ramda.none)(r => r.canRead(file), this.options.resolve.resolvers);
       const isURL = !isUnknownURI;
-      let isInternalReference = url.stripHash(this.reference.uri) === $refBaseURI;
+      let isInternalReference = this.baseURI === $refBaseURI;
       let isExternalReference = !isInternalReference;
 
       // determining reference, proper evaluation and selection mechanism
@@ -327,7 +341,7 @@ class Arazzo1DereferenceVisitor {
         } else {
           // we're assuming here that we're dealing with JSON Pointer here
           retrievalURI = this.toBaseURI($refBaseURI);
-          isInternalReference = url.stripHash(this.reference.uri) === retrievalURI;
+          isInternalReference = this.baseURI === retrievalURI;
           isExternalReference = !isInternalReference;
 
           // ignore resolving internal Schema Objects
@@ -354,7 +368,7 @@ class Arazzo1DereferenceVisitor {
         if (isURL && error instanceof _EvaluationJsonSchemaUriError.default) {
           if ((0, _$anchor.isAnchor)((0, _$anchor.uriToAnchor)($refBaseURI))) {
             // we're dealing with JSON Schema $anchor here
-            isInternalReference = url.stripHash(this.reference.uri) === retrievalURI;
+            isInternalReference = this.baseURI === retrievalURI;
             isExternalReference = !isInternalReference;
 
             // ignore resolving internal Schema Objects
@@ -375,7 +389,7 @@ class Arazzo1DereferenceVisitor {
           } else {
             // we're assuming here that we're dealing with JSON Pointer here
             retrievalURI = this.toBaseURI($refBaseURI);
-            isInternalReference = url.stripHash(this.reference.uri) === retrievalURI;
+            isInternalReference = this.baseURI === retrievalURI;
             isExternalReference = !isInternalReference;
 
             // ignore resolving internal Schema Objects

package/src/dereference/strategies/arazzo-1/visitor.mjs

@@ -9,7 +9,7 @@ import { parse as parseRuntimeExpression } from '@swaggerexpert/arazzo-runtime-e
 import { isAnchor, uriToAnchor, evaluate as $anchorEvaluate } from "./selectors/$anchor.mjs";
 import { evaluate as uriEvaluate } from "./selectors/uri.mjs";
 import { resolveSchema$refField } from "../openapi-3-1/util.mjs";
-import { maybeRefractToJSONSchemaElement } from "./util.mjs";
+import { maybeRefractToJSONSchemaElement, resolveArazzo$selfField, identifiedBy$self } from "./util.mjs";
 import UnresolvableReferenceError from "../../../errors/UnresolvableReferenceError.mjs";
 import MaximumDereferenceDepthError from "../../../errors/MaximumDereferenceDepthError.mjs";
 import MaximumResolveDepthError from "../../../errors/MaximumResolveDepthError.mjs";
@@ -28,6 +28,13 @@ import EvaluationJsonSchemaUriError from "../../../errors/EvaluationJsonSchemaUr
 class Arazzo1DereferenceVisitor {
   indirections;
   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`).
+   */
+  baseURI;
   options;
   visited;
 
@@ -46,6 +53,7 @@ class Arazzo1DereferenceVisitor {
   }) {
     this.indirections = indirections;
     this.reference = reference;
+    this.baseURI = resolveArazzo$selfField(reference.uri, reference.value?.result);
     this.options = options;
     this.ancestors = new AncestorLineage(...ancestors);
     this.visited = visited;
@@ -57,7 +65,7 @@ class Arazzo1DereferenceVisitor {
     return [ancestorsLineage, directAncestors];
   }
   toBaseURI(uri) {
-    return url.resolve(this.reference.uri, url.sanitize(url.stripHash(uri)));
+    return url.resolve(this.baseURI, url.sanitize(url.stripHash(uri)));
   }
   async toReference(uri) {
     // detect maximum depth of resolution
@@ -76,6 +84,12 @@ class Arazzo1DereferenceVisitor {
     if (refSet.has(baseURI)) {
       return refSet.find(propEq(baseURI, 'uri'));
     }
+
+    // identity-based referencing: URI matches `$self` of an already processed Arazzo document
+    const referenceBy$self = refSet.find(identifiedBy$self(baseURI));
+    if (referenceBy$self !== undefined) {
+      return referenceBy$self;
+    }
     const parseResult = await parse(url.unsanitize(baseURI), {
       ...this.options,
       parse: {
@@ -279,19 +293,19 @@ class Arazzo1DereferenceVisitor {
     }
     const indirectionsSize = this.indirections.length;
     try {
-      // compute baseURI using rules around $id and $ref keywords
+      // compute baseURI using rules around $self, $id and $ref keywords
       let reference = await this.toReference(url.unsanitize(this.reference.uri));
       let {
         uri: retrievalURI
       } = reference;
-      const $refBaseURI = resolveSchema$refField(retrievalURI, referencingElement);
+      const $refBaseURI = resolveSchema$refField(this.baseURI, referencingElement);
       const $refBaseURIStrippedHash = url.stripHash($refBaseURI);
       const file = new File({
         uri: $refBaseURIStrippedHash
       });
       const isUnknownURI = none(r => r.canRead(file), this.options.resolve.resolvers);
       const isURL = !isUnknownURI;
-      let isInternalReference = url.stripHash(this.reference.uri) === $refBaseURI;
+      let isInternalReference = this.baseURI === $refBaseURI;
       let isExternalReference = !isInternalReference;
 
       // determining reference, proper evaluation and selection mechanism
@@ -318,7 +332,7 @@ class Arazzo1DereferenceVisitor {
         } else {
           // we're assuming here that we're dealing with JSON Pointer here
           retrievalURI = this.toBaseURI($refBaseURI);
-          isInternalReference = url.stripHash(this.reference.uri) === retrievalURI;
+          isInternalReference = this.baseURI === retrievalURI;
           isExternalReference = !isInternalReference;
 
           // ignore resolving internal Schema Objects
@@ -345,7 +359,7 @@ class Arazzo1DereferenceVisitor {
         if (isURL && error instanceof EvaluationJsonSchemaUriError) {
           if (isAnchor(uriToAnchor($refBaseURI))) {
             // we're dealing with JSON Schema $anchor here
-            isInternalReference = url.stripHash(this.reference.uri) === retrievalURI;
+            isInternalReference = this.baseURI === retrievalURI;
             isExternalReference = !isInternalReference;
 
             // ignore resolving internal Schema Objects
@@ -366,7 +380,7 @@ class Arazzo1DereferenceVisitor {
           } else {
             // we're assuming here that we're dealing with JSON Pointer here
             retrievalURI = this.toBaseURI($refBaseURI);
-            isInternalReference = url.stripHash(this.reference.uri) === retrievalURI;
+            isInternalReference = this.baseURI === retrievalURI;
             isExternalReference = !isInternalReference;
 
             // ignore resolving internal Schema Objects

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

@@ -8,14 +8,12 @@ Object.defineProperty(exports, "__esModule", {
 exports.parseSourceDescriptions = parseSourceDescriptions;
 var _apidomDatamodel = require("@speclynx/apidom-datamodel");
 var _apidomNsArazzo = require("@speclynx/apidom-ns-arazzo-1");
-var _apidomNsOpenapi = require("@speclynx/apidom-ns-openapi-2");
-var _apidomNsOpenapi2 = require("@speclynx/apidom-ns-openapi-3-0");
-var _apidomNsOpenapi3 = require("@speclynx/apidom-ns-openapi-3-1");
 var _apidomCore = require("@speclynx/apidom-core");
 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';
 /**
@@ -47,14 +45,25 @@ async function parseSourceDescription(sourceDescription, ctx) {
   const retrievalURI = url.sanitize(url.stripHash(url.resolve(ctx.baseURI, sourceDescriptionURI)));
   parseResult.setMetaProperty('retrievalURI', retrievalURI);
 
-  // skip if already visited (cycle detection)
-  if (ctx.visitedUrls.has(retrievalURI)) {
+  // skip if the document is still being parsed higher up the chain (cycle detection)
+  if (ctx.ancestors.includes(retrievalURI)) {
     const annotation = new _apidomDatamodel.AnnotationElement(`Source description "${retrievalURI}" has already been visited. Skipping to prevent cycle`);
     annotation.classes.push('warning');
     parseResult.push(annotation);
     return parseResult;
   }
-  ctx.visitedUrls.add(retrievalURI);
+
+  // a document reached again through a different path is a shared dependency, not a cycle;
+  // point at the result where it was parsed instead of parsing it again
+  const sharedParseResult = ctx.parsed.get(retrievalURI);
+  if (sharedParseResult !== undefined) {
+    const annotation = new _apidomDatamodel.AnnotationElement(`Source description "${retrievalURI}" has already been parsed. Reusing existing parse result`);
+    annotation.classes.push('info');
+    parseResult.push(annotation);
+    parseResult.meta.set('parseResult', sharedParseResult);
+    (0, _util2.validateSourceDescriptionAPI)(parseResult, sourceDescription, sharedParseResult.api, retrievalURI);
+    return parseResult;
+  }
   try {
     const sourceDescriptionParseResult = await (0, _index.default)(retrievalURI, (0, _util.merge)(ctx.options, {
       parse: {
@@ -66,7 +75,8 @@ async function parseSourceDescription(sourceDescription, ctx) {
           sourceDescriptions: true,
           [ARAZZO_RECURSION_KEY]: {
             sourceDescriptionsDepth: ctx.currentDepth + 1,
-            sourceDescriptionsVisitedUrls: ctx.visitedUrls
+            sourceDescriptionsAncestors: ctx.ancestors,
+            sourceDescriptionsParsed: ctx.parsed
           }
         }
       }
@@ -84,32 +94,14 @@ async function parseSourceDescription(sourceDescription, ctx) {
     return parseResult;
   }
 
-  // only allow OpenAPI and Arazzo as source descriptions
+  // register parsed document for later references to it
   const {
     api: sourceDescriptionAPI
   } = parseResult;
-  const isOpenApi = (0, _apidomNsOpenapi.isSwaggerElement)(sourceDescriptionAPI) || (0, _apidomNsOpenapi2.isOpenApi3_0Element)(sourceDescriptionAPI) || (0, _apidomNsOpenapi3.isOpenApi3_1Element)(sourceDescriptionAPI);
-  const isArazzo = (0, _apidomNsArazzo.isArazzoSpecification1Element)(sourceDescriptionAPI);
-  if (!isOpenApi && !isArazzo) {
-    const annotation = new _apidomDatamodel.AnnotationElement(`Source description "${retrievalURI}" is not an OpenAPI or Arazzo document`);
-    annotation.classes.push('warning');
-    parseResult.push(annotation);
-    return parseResult;
-  }
-
-  // validate declared type matches actual parsed type
-  const declaredType = (0, _apidomCore.toValue)(sourceDescription.type);
-  if (typeof declaredType === 'string') {
-    if (declaredType === 'openapi' && !isOpenApi) {
-      const annotation = new _apidomDatamodel.AnnotationElement(`Source description "${retrievalURI}" declared as "openapi" but parsed as Arazzo document`);
-      annotation.classes.push('warning');
-      parseResult.push(annotation);
-    } else if (declaredType === 'arazzo' && !isArazzo) {
-      const annotation = new _apidomDatamodel.AnnotationElement(`Source description "${retrievalURI}" declared as "arazzo" but parsed as OpenAPI document`);
-      annotation.classes.push('warning');
-      parseResult.push(annotation);
-    }
+  for (const documentURI of (0, _util2.arazzoDocumentURIs)(retrievalURI, sourceDescriptionAPI)) {
+    ctx.parsed.set(documentURI, parseResult);
   }
+  (0, _util2.validateSourceDescriptionAPI)(parseResult, sourceDescription, sourceDescriptionAPI, retrievalURI);
   return parseResult;
 }
 
@@ -121,6 +113,13 @@ async function parseSourceDescription(sourceDescription, ctx) {
  * regardless of success or failure. On failure, the ParseResultElement
  * contains annotations explaining what went wrong.
  *
+ * A document referenced from more than one place is parsed only once.
+ * Every later source description referencing it gets its own result carrying
+ * an 'info' annotation and a 'parseResult' meta pointing at the result where
+ * the document was parsed; that result is also what gets attached to the
+ * SourceDescriptionElement's meta. A document referencing one of its ancestors
+ * forms a cycle and is skipped with a 'warning' annotation instead.
+ *
  * @param parseResult - ParseResult containing an Arazzo specification
  * @param parseResultRetrievalURI - URI from which the parseResult was retrieved
  * @param options - Full ReferenceOptions. Pass `sourceDescriptions` as an array of names
@@ -186,10 +185,9 @@ async function parseSourceDescriptions(parseResult, parseResultRetrievalURI, opt
   // recursion state comes from shared key (works across JSON/YAML)
   const sharedOpts = options?.parse?.parserOpts?.[ARAZZO_RECURSION_KEY] ?? {};
   const currentDepth = sharedOpts.sourceDescriptionsDepth ?? 0;
-  const visitedUrls = sharedOpts.sourceDescriptionsVisitedUrls ?? new Set();
-
-  // add current file to visited URLs to prevent cycles
-  visitedUrls.add(file.uri);
+  const parsed = sharedOpts.sourceDescriptionsParsed ?? new Map();
+  // current file is an ancestor of everything parsed below
+  const ancestors = [...(sharedOpts.sourceDescriptionsAncestors ?? []), ...(0, _util2.arazzoDocumentURIs)(file.uri, api)];
   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,10 +196,12 @@ async function parseSourceDescriptions(parseResult, parseResultRetrievalURI, opt
     return [parseResult];
   }
   const ctx = {
-    baseURI: file.uri,
+    // base URI for resolving source description URLs honors Arazzo `$self` field
+    baseURI: (0, _util2.resolveArazzo$selfField)(file.uri, api),
     options,
     currentDepth,
-    visitedUrls
+    ancestors,
+    parsed
   };
 
   // determine which source descriptions to parse (array filters by name)
@@ -212,11 +212,12 @@ async function parseSourceDescriptions(parseResult, parseResultRetrievalURI, opt
     return typeof name === 'string' && sourceDescriptionsOption.includes(name);
   }) : api.sourceDescriptions;
 
-  // process sequentially to ensure proper cycle detection with shared visitedUrls
+  // process sequentially to ensure proper cycle detection with shared state
   for (const sourceDescription of sourceDescriptions) {
     const sourceDescriptionParseResult = await parseSourceDescription(sourceDescription, ctx);
-    // always attach result (even on failure - contains annotations)
-    sourceDescription.meta.set('parseResult', sourceDescriptionParseResult);
+    // always attach result (even on failure - contains annotations);
+    // a shared document attaches the result where it was parsed
+    sourceDescription.meta.set('parseResult', sourceDescriptionParseResult.meta.get('parseResult') ?? sourceDescriptionParseResult);
     results.push(sourceDescriptionParseResult);
   }
   return results;