@speclynx/apidom-reference 5.1.1 → 5.2.2

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

@@ -1,13 +1,11 @@
 import { ParseResultElement, AnnotationElement, isArrayElement, isStringElement } from '@speclynx/apidom-datamodel';
 import { isArazzoSpecification1Element, isSourceDescriptionElement } 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 { 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 { arazzoDocumentURIs, resolveArazzo$selfField, validateSourceDescriptionAPI } 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.
@@ -38,14 +36,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 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 AnnotationElement(`Source description "${retrievalURI}" has already been parsed. Reusing existing parse result`);
+    annotation.classes.push('info');
+    parseResult.push(annotation);
+    parseResult.meta.set('parseResult', sharedParseResult);
+    validateSourceDescriptionAPI(parseResult, sourceDescription, sharedParseResult.api, retrievalURI);
+    return parseResult;
+  }
   try {
     const sourceDescriptionParseResult = await parse(retrievalURI, mergeOptions(ctx.options, {
       parse: {
@@ -57,7 +66,8 @@ async function parseSourceDescription(sourceDescription, ctx) {
           sourceDescriptions: true,
           [ARAZZO_RECURSION_KEY]: {
             sourceDescriptionsDepth: ctx.currentDepth + 1,
-            sourceDescriptionsVisitedUrls: ctx.visitedUrls
+            sourceDescriptionsAncestors: ctx.ancestors,
+            sourceDescriptionsParsed: ctx.parsed
           }
         }
       }
@@ -75,32 +85,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 = 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 parseResult;
-  }
-
-  // validate declared type matches actual parsed 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 parsed as 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 parsed as OpenAPI document`);
-      annotation.classes.push('warning');
-      parseResult.push(annotation);
-    }
+  for (const documentURI of arazzoDocumentURIs(retrievalURI, sourceDescriptionAPI)) {
+    ctx.parsed.set(documentURI, parseResult);
   }
+  validateSourceDescriptionAPI(parseResult, sourceDescription, sourceDescriptionAPI, retrievalURI);
   return parseResult;
 }
 
@@ -112,6 +104,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
@@ -177,10 +176,9 @@ export async function parseSourceDescriptions(parseResult, parseResultRetrievalU
   // 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 ?? []), ...arazzoDocumentURIs(file.uri, api)];
   if (currentDepth >= maxDepth) {
     const annotation = new AnnotationElement(`Maximum parse depth of ${maxDepth} has been exceeded by file "${file.uri}"`);
     annotation.classes.push('error');
@@ -189,10 +187,12 @@ export async function parseSourceDescriptions(parseResult, parseResultRetrievalU
     return [parseResult];
   }
   const ctx = {
-    baseURI: file.uri,
+    // base URI for resolving source description URLs honors Arazzo `$self` field
+    baseURI: resolveArazzo$selfField(file.uri, api),
     options,
     currentDepth,
-    visitedUrls
+    ancestors,
+    parsed
   };
 
   // determine which source descriptions to parse (array filters by name)
@@ -203,11 +203,12 @@ export async function parseSourceDescriptions(parseResult, parseResultRetrievalU
     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;

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/source-descriptions.d.ts

@@ -8,6 +8,13 @@ import type { ReferenceOptions } from '../../../options/index.ts';
  * regardless of success or failure. On failure, the ParseResultElement
  * contains annotations explaining what went wrong.
  *
+ * A document referenced from more than one place is dereferenced 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 dereferenced; 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 a parsed (optionally dereferenced) Arazzo specification
  * @param parseResultRetrievalURI - URI from which the parseResult was retrieved
  * @param options - Full ReferenceOptions. Pass `sourceDescriptions` as an array of names

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

@@ -1,5 +1,38 @@
-import { Element } from '@speclynx/apidom-datamodel';
+import { Element, ParseResultElement } from '@speclynx/apidom-datamodel';
+import { SourceDescriptionElement } from '@speclynx/apidom-ns-arazzo-1';
+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;
+/**
+ * URIs an Arazzo document is known by: its retrieval URI and, when the
+ * document carries a `$self` field resolving elsewhere, its identity.
+ */
+export declare const arazzoDocumentURIs: (retrievalURI: string, element: unknown) => string[];
+/**
+ * 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 declare const validateSourceDescriptionAPI: (parseResult: ParseResultElement, sourceDescription: SourceDescriptionElement, sourceDescriptionAPI: Element | undefined, retrievalURI: string) => void;
+/**
+ * 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>;
     /**

package/types/parse/parsers/arazzo-json-1/source-descriptions.d.ts

@@ -8,6 +8,13 @@ import type { ReferenceOptions } from '../../../options/index.ts';
  * 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