feat(reference): dereference dynamic schema refs

packages/apidom-reference/package.json

@@ -200,6 +200,11 @@
       "require": "./src/dereference/strategies/apidom/selectors/element-id.cjs",
       "types": "./types/dereference/strategies/apidom/selectors/element-id.d.ts"
     },
+    "./dereference/DynamicScopeStack": {
+      "import": "./src/dereference/DynamicScopeStack.mjs",
+      "require": "./src/dereference/DynamicScopeStack.cjs",
+      "types": "./types/dereference/DynamicScopeStack.d.ts"
+    },
     "./dereference/strategies/asyncapi-2": {
       "import": "./src/dereference/strategies/asyncapi-2/index.mjs",
       "require": "./src/dereference/strategies/asyncapi-2/index.cjs",
@@ -225,6 +230,11 @@
       "require": "./src/dereference/strategies/openapi-3-1/selectors/$anchor.cjs",
       "types": "./types/dereference/strategies/openapi-3-1/selectors/$anchor.d.ts"
     },
+    "./dereference/strategies/openapi-3-1/selectors/$dynamicAnchor": {
+      "import": "./src/dereference/strategies/openapi-3-1/selectors/$dynamicAnchor.mjs",
+      "require": "./src/dereference/strategies/openapi-3-1/selectors/$dynamicAnchor.cjs",
+      "types": "./types/dereference/strategies/openapi-3-1/selectors/$dynamicAnchor.d.ts"
+    },
     "./dereference/strategies/openapi-3-1/selectors/uri": {
       "import": "./src/dereference/strategies/openapi-3-1/selectors/uri.mjs",
       "require": "./src/dereference/strategies/openapi-3-1/selectors/uri.cjs",
@@ -240,6 +250,11 @@
       "require": "./src/dereference/strategies/openapi-3-2/selectors/$anchor.cjs",
       "types": "./types/dereference/strategies/openapi-3-2/selectors/$anchor.d.ts"
     },
+    "./dereference/strategies/openapi-3-2/selectors/$dynamicAnchor": {
+      "import": "./src/dereference/strategies/openapi-3-2/selectors/$dynamicAnchor.mjs",
+      "require": "./src/dereference/strategies/openapi-3-2/selectors/$dynamicAnchor.cjs",
+      "types": "./types/dereference/strategies/openapi-3-2/selectors/$dynamicAnchor.d.ts"
+    },
     "./dereference/strategies/openapi-3-2/selectors/uri": {
       "import": "./src/dereference/strategies/openapi-3-2/selectors/uri.mjs",
       "require": "./src/dereference/strategies/openapi-3-2/selectors/uri.cjs",

packages/apidom-reference/src/dereference/DynamicScopeStack.ts

@@ -0,0 +1,73 @@
+import { Element, find, isObjectElement, isStringElement, toValue } from '@swagger-api/apidom-core';
+
+/**
+ * @public
+ */
+export type DynamicScopeEntryType = 'root' | '$ref' | '$dynamicRef' | 'applicator';
+
+/**
+ * @public
+ */
+export interface DynamicScopeFrame {
+  readonly element: Element;
+  readonly documentURI: string;
+  readonly dynamicAnchors: Map<string, Element>;
+  readonly entryType: DynamicScopeEntryType;
+}
+
+const collectDynamicAnchors = (element: Element): Map<string, Element> => {
+  const anchors = new Map<string, Element>();
+
+  // @ts-ignore
+  find((e: Element) => {
+    const elementWithDynamicAnchor = e as Element & { $dynamicAnchor?: Element };
+    const dynamicAnchor =
+      elementWithDynamicAnchor.$dynamicAnchor ??
+      (isObjectElement(e) ? e.get('$dynamicAnchor') : undefined);
+
+    if (isStringElement(dynamicAnchor)) {
+      const anchor = toValue(dynamicAnchor);
+      if (typeof anchor === 'string' && !anchors.has(anchor)) {
+        anchors.set(anchor, e);
+      }
+    }
+    return false;
+  }, element);
+
+  return anchors;
+};
+
+/**
+ * @public
+ */
+export class DynamicScopeStack extends Array<DynamicScopeFrame> {
+  pushFrame(element: Element, documentURI: string, entryType: DynamicScopeEntryType): void {
+    this.push({
+      element,
+      documentURI,
+      entryType,
+      dynamicAnchors: collectDynamicAnchors(element),
+    });
+  }
+
+  popFrame(): DynamicScopeFrame | undefined {
+    return this.pop();
+  }
+
+  resolveDynamicRef(
+    anchorToken: string,
+  ): { referencedElement: Element; documentURI: string } | null {
+    for (let i = 0; i < this.length; i += 1) {
+      const frame = this[i];
+      const match = frame.dynamicAnchors.get(anchorToken);
+      if (typeof match !== 'undefined') {
+        return { referencedElement: match, documentURI: frame.documentURI };
+      }
+    }
+    return null;
+  }
+
+  clone(): DynamicScopeStack {
+    return new DynamicScopeStack(...this);
+  }
+}

packages/apidom-reference/src/dereference/strategies/openapi-3-1/selectors/$dynamicAnchor.ts

@@ -0,0 +1,60 @@
+import { trimCharsStart, isUndefined } from 'ramda-adjunct';
+import { Element, find, toValue } from '@swagger-api/apidom-core';
+import { isSchemaElement } from '@swagger-api/apidom-ns-openapi-3-1';
+
+import { getHash } from '../../../../util/url.ts';
+import EvaluationJsonSchema$dynamicAnchorError from '../../../../errors/EvaluationJsonSchema$dynamicAnchorError.ts';
+import InvalidJsonSchema$dynamicAnchorError from '../../../../errors/InvalidJsonSchema$dynamicAnchorError.ts';
+
+/**
+ * @public
+ */
+export const isDynamicAnchor = (uri: string) => {
+  /**
+   *  MUST start with a letter ([A-Za-z]) or underscore ("_"), followed by any number of letters,
+   *  digits ([0-9]), hyphens ("-"), underscores ("_"), and periods (".").
+   *
+   *  https://json-schema.org/draft/2020-12/json-schema-core.html#rfc.section.8.2.2
+   */
+  return /^[A-Za-z_][A-Za-z_0-9.-]*$/.test(uri);
+};
+
+/**
+ * @public
+ */
+export const uriToDynamicAnchor = (uri: string): string => {
+  const hash = getHash(uri);
+  return trimCharsStart('#', hash);
+};
+
+/**
+ * @public
+ */
+export const parse = (anchor: string): string => {
+  if (!isDynamicAnchor(anchor)) {
+    throw new InvalidJsonSchema$dynamicAnchorError(anchor);
+  }
+
+  return anchor;
+};
+
+/**
+ * Evaluates JSON Schema $dynamicAnchor against ApiDOM fragment.
+ * @public
+ */
+export const evaluate = <T extends Element>(anchor: string, element: T): Element | undefined => {
+  const token = parse(anchor);
+
+  // @ts-ignore
+  const result = find((e) => isSchemaElement(e) && toValue(e.$dynamicAnchor) === token, element);
+
+  if (isUndefined(result)) {
+    throw new EvaluationJsonSchema$dynamicAnchorError(`Evaluation failed on token: "${token}"`);
+  }
+
+  // @ts-ignore
+  return result;
+};
+
+export { EvaluationJsonSchema$dynamicAnchorError, InvalidJsonSchema$dynamicAnchorError };
+export { default as JsonSchema$dynamicAnchorError } from '../../../../errors/JsonSchema$dynamicAnchorError.ts';

packages/apidom-reference/src/dereference/strategies/openapi-3-1/util.ts

@@ -44,6 +44,27 @@ export const resolveSchema$idField = (retrievalURI: string, schemaElement: Schem
   );
 };
 
+export const resolveSchema$dynamicRefField = (
+  retrievalURI: string,
+  schemaElement: SchemaElement,
+) => {
+  if (typeof schemaElement.$dynamicRef === 'undefined') {
+    return undefined;
+  }
+
+  const hash = url.getHash(toValue(schemaElement.$dynamicRef));
+  const ancestorsSchemaIdentifiers = toValue(schemaElement.meta.get('ancestorsSchemaIdentifiers'));
+  const $dynamicRefBaseURI = reduce(
+    (acc: string, uri: string): string => {
+      return url.resolve(acc, url.sanitize(url.stripHash(uri)));
+    },
+    retrievalURI,
+    [...ancestorsSchemaIdentifiers, toValue(schemaElement.$dynamicRef)],
+  );
+
+  return `${$dynamicRefBaseURI}${hash === '#' ? '' : hash}`;
+};
+
 /**
  * Cached version of SchemaElement.refract.
  */