feat(reference): skip processing internal refererences in apidom resolve strategy

packages/apidom-reference/src/dereference/strategies/apidom/visitor.ts

@@ -88,10 +88,16 @@ const ApiDOMDereferenceVisitor = stampit({
       const refURI = toValue(refElement);
       const refNormalizedURI = refURI.includes('#') ? refURI : `#${refURI}`;
       const retrievalURI = this.toBaseURI(refNormalizedURI);
-      const isExternal = url.stripHash(this.reference.uri) !== retrievalURI;
+      const isInternalReference = url.stripHash(this.reference.uri) === retrievalURI;
+      const isExternalReference = !isInternalReference;
 
-      // ignore resolving external Ref Objects
-      if (!this.options.resolve.external && isExternal) {
+      // ignore resolving internal RefElements
+      if (!this.options.resolve.internal && isInternalReference) {
+        // skip traversing this ref element
+        return false;
+      }
+      // ignore resolving external RefElements
+      if (!this.options.resolve.external && isExternalReference) {
         // skip traversing this ref element
         return false;
       }
@@ -116,7 +122,7 @@ const ApiDOMDereferenceVisitor = stampit({
         throw new ApiDOMError('RefElement cannot reference another RefElement');
       }
 
-      if (isExternal) {
+      if (isExternalReference) {
         // dive deep into the fragment
         const visitor = ApiDOMDereferenceVisitor({ reference, options: this.options });
         referencedElement = await visitAsync(referencedElement, visitor);

packages/apidom-reference/src/options/index.ts

@@ -49,6 +49,11 @@ const defaultOptions: IReferenceOptions = {
      * These options are available in resolver strategy `canResolve` and `resolve` methods.
      */
     strategyOpts: {},
+    /**
+     * Determines whether internal references will be resolved.
+     * Internal references will simply be ignored.
+     */
+    internal: true,
     /**
      * Determines whether external references will be resolved.
      * If this option is disabled, then none of above resolvers will be called.

packages/apidom-reference/src/resolve/strategies/apidom/index.ts

@@ -10,6 +10,7 @@ import {
 import ReferenceSet from '../../../ReferenceSet';
 import Reference from '../../../Reference';
 import ApiDOMResolveVisitor from './visitor';
+import { merge as mergeOptions } from '../../../options/util';
 
 // @ts-ignore
 const visitAsync = visit[Symbol.for('nodejs.util.promisify.custom')];
@@ -30,7 +31,8 @@ const ApiDOMResolveStrategy: stampit.Stamp<IResolveStrategy> = stampit(ResolveSt
         ? cloneDeep(file.parseResult)
         : file.parseResult;
       const reference = Reference({ uri: file.uri, value: referenceValue });
-      const visitor = ApiDOMResolveVisitor({ reference, options });
+      const mergedOptions = mergeOptions(options, { resolve: { internal: false } });
+      const visitor = ApiDOMResolveVisitor({ reference, options: mergedOptions });
       const refSet = ReferenceSet();
       refSet.add(reference);
 

packages/apidom-reference/src/types.ts

@@ -92,6 +92,7 @@ export interface ReferenceResolveOptions {
   resolverOpts: Record<string, any>;
   strategies: Array<ResolveStrategy>;
   strategyOpts: Record<string, any>;
+  internal: boolean;
   external: boolean;
   maxDepth: number;
 }