@speclynx/apidom-reference 5.2.6 → 6.0.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@speclynx/apidom-reference",
-  "version": "5.2.6",
+  "version": "6.0.1",
   "description": "Advanced algorithms for semantic ApiDOM manipulations like dereferencing or resolution.",
   "keywords": [
     "apidom",
@@ -299,36 +299,35 @@
   "license": "Apache-2.0",
   "dependencies": {
     "@babel/runtime-corejs3": "^8.0.5",
-    "@speclynx/apidom-core": "5.2.6",
-    "@speclynx/apidom-datamodel": "5.2.6",
-    "@speclynx/apidom-error": "5.2.6",
-    "@speclynx/apidom-json-pointer": "5.2.6",
-    "@speclynx/apidom-ns-arazzo-1": "5.2.6",
-    "@speclynx/apidom-ns-asyncapi-2": "5.2.6",
-    "@speclynx/apidom-ns-json-schema-2020-12": "5.2.6",
-    "@speclynx/apidom-ns-openapi-2": "5.2.6",
-    "@speclynx/apidom-ns-openapi-3-0": "5.2.6",
-    "@speclynx/apidom-ns-openapi-3-1": "5.2.6",
-    "@speclynx/apidom-ns-overlay-1": "5.2.6",
-    "@speclynx/apidom-parser-adapter-arazzo-json-1": "5.2.6",
-    "@speclynx/apidom-parser-adapter-arazzo-yaml-1": "5.2.6",
-    "@speclynx/apidom-parser-adapter-asyncapi-json-2": "5.2.6",
-    "@speclynx/apidom-parser-adapter-asyncapi-yaml-2": "5.2.6",
-    "@speclynx/apidom-parser-adapter-json": "5.2.6",
-    "@speclynx/apidom-parser-adapter-openapi-json-2": "5.2.6",
-    "@speclynx/apidom-parser-adapter-openapi-json-3-0": "5.2.6",
-    "@speclynx/apidom-parser-adapter-openapi-json-3-1": "5.2.6",
-    "@speclynx/apidom-parser-adapter-openapi-yaml-2": "5.2.6",
-    "@speclynx/apidom-parser-adapter-openapi-yaml-3-0": "5.2.6",
-    "@speclynx/apidom-parser-adapter-openapi-yaml-3-1": "5.2.6",
-    "@speclynx/apidom-parser-adapter-overlay-json-1": "5.2.6",
-    "@speclynx/apidom-parser-adapter-overlay-yaml-1": "5.2.6",
-    "@speclynx/apidom-parser-adapter-yaml-1-2": "5.2.6",
-    "@speclynx/apidom-traverse": "5.2.6",
+    "@speclynx/apidom-core": "6.0.1",
+    "@speclynx/apidom-datamodel": "6.0.1",
+    "@speclynx/apidom-error": "6.0.1",
+    "@speclynx/apidom-json-pointer": "6.0.1",
+    "@speclynx/apidom-ns-arazzo-1": "6.0.1",
+    "@speclynx/apidom-ns-asyncapi-2": "6.0.1",
+    "@speclynx/apidom-ns-json-schema-2020-12": "6.0.1",
+    "@speclynx/apidom-ns-openapi-2": "6.0.1",
+    "@speclynx/apidom-ns-openapi-3-0": "6.0.1",
+    "@speclynx/apidom-ns-openapi-3-1": "6.0.1",
+    "@speclynx/apidom-ns-overlay-1": "6.0.1",
+    "@speclynx/apidom-parser-adapter-arazzo-json-1": "6.0.1",
+    "@speclynx/apidom-parser-adapter-arazzo-yaml-1": "6.0.1",
+    "@speclynx/apidom-parser-adapter-asyncapi-json-2": "6.0.1",
+    "@speclynx/apidom-parser-adapter-asyncapi-yaml-2": "6.0.1",
+    "@speclynx/apidom-parser-adapter-json": "6.0.1",
+    "@speclynx/apidom-parser-adapter-openapi-json-2": "6.0.1",
+    "@speclynx/apidom-parser-adapter-openapi-json-3-0": "6.0.1",
+    "@speclynx/apidom-parser-adapter-openapi-json-3-1": "6.0.1",
+    "@speclynx/apidom-parser-adapter-openapi-yaml-2": "6.0.1",
+    "@speclynx/apidom-parser-adapter-openapi-yaml-3-0": "6.0.1",
+    "@speclynx/apidom-parser-adapter-openapi-yaml-3-1": "6.0.1",
+    "@speclynx/apidom-parser-adapter-overlay-json-1": "6.0.1",
+    "@speclynx/apidom-parser-adapter-overlay-yaml-1": "6.0.1",
+    "@speclynx/apidom-parser-adapter-yaml-1-2": "6.0.1",
+    "@speclynx/apidom-traverse": "6.0.1",
     "@swaggerexpert/arazzo-runtime-expression": "^3.2.0",
     "axios": "^1.20.0",
     "picomatch": "^4.0.7",
-    "process": "^0.11.10",
     "ramda": "~0.32.0",
     "ramda-adjunct": "^6.1.0"
   },
@@ -346,5 +345,5 @@
     "README.md",
     "CHANGELOG.md"
   ],
-  "gitHead": "c78f4a79e2b91b9ad099dff6dff5dc35236ae75b"
+  "gitHead": "d2ea4f01cac54a0d5e1030386e3b0b60664c9619"
 }

package/src/dereference/strategies/overlay-1/extends.cjs

@@ -45,8 +45,12 @@ async function dereferenceExtends(parseResult, parseResultRetrievalURI, options)
   if (!(0, _apidomDatamodel.isStringElement)(extendsElement)) {
     return;
   }
+
+  // Overlay 1.2.0: `$self` (itself resolved against the retrieval URI) is the base URI
+  const selfElement = api.get('$self');
+  const baseURI = (0, _apidomDatamodel.isStringElement)(selfElement) ? url.resolve(file.uri, (0, _apidomCore.toValue)(selfElement)) : file.uri;
   const extendsURI = (0, _apidomCore.toValue)(extendsElement);
-  const retrievalURI = url.sanitize(url.stripHash(url.resolve(file.uri, extendsURI)));
+  const retrievalURI = url.sanitize(url.stripHash(url.resolve(baseURI, extendsURI)));
   const extendsDereferenceResult = new _apidomDatamodel.ParseResultElement();
   extendsDereferenceResult.classes.push('extends');
   extendsDereferenceResult.setMetaProperty('retrievalURI', retrievalURI);

package/src/dereference/strategies/overlay-1/extends.mjs

@@ -37,8 +37,12 @@ export async function dereferenceExtends(parseResult, parseResultRetrievalURI, o
   if (!isStringElement(extendsElement)) {
     return;
   }
+
+  // Overlay 1.2.0: `$self` (itself resolved against the retrieval URI) is the base URI
+  const selfElement = api.get('$self');
+  const baseURI = isStringElement(selfElement) ? url.resolve(file.uri, toValue(selfElement)) : file.uri;
   const extendsURI = toValue(extendsElement);
-  const retrievalURI = url.sanitize(url.stripHash(url.resolve(file.uri, extendsURI)));
+  const retrievalURI = url.sanitize(url.stripHash(url.resolve(baseURI, extendsURI)));
   const extendsDereferenceResult = new ParseResultElement();
   extendsDereferenceResult.classes.push('extends');
   extendsDereferenceResult.setMetaProperty('retrievalURI', retrievalURI);

package/src/dereference/strategies/overlay-1/index.cjs

@@ -4,6 +4,12 @@ var _interopRequireDefault = require("@babel/runtime-corejs3/helpers/interopRequ
 Object.defineProperty(exports, "__esModule", {
   value: true
 });
+Object.defineProperty(exports, "Overlay1DereferenceVisitor", {
+  enumerable: true,
+  get: function () {
+    return _visitor.default;
+  }
+});
 exports.default = void 0;
 Object.defineProperty(exports, "dereferenceExtends", {
   enumerable: true,
@@ -13,10 +19,12 @@ Object.defineProperty(exports, "dereferenceExtends", {
 });
 var _apidomDatamodel = require("@speclynx/apidom-datamodel");
 var _apidomNsOverlay = require("@speclynx/apidom-ns-overlay-1");
+var _apidomTraverse = require("@speclynx/apidom-traverse");
 var _DereferenceStrategy = _interopRequireDefault(require("../DereferenceStrategy.cjs"));
 var _Reference = _interopRequireDefault(require("../../../Reference.cjs"));
 var _ReferenceSet = _interopRequireDefault(require("../../../ReferenceSet.cjs"));
 var _extends = require("./extends.cjs");
+var _visitor = _interopRequireDefault(require("./visitor.cjs"));
 /**
  * @public
  */
@@ -68,6 +76,18 @@ class Overlay1DereferenceStrategy extends _DereferenceStrategy.default {
     }
     const dereferencedElement = reference.value;
 
+    /**
+     * Reusable Action References only occur within `actions`, so the root element is never
+     * replaced and traversing it keeps reported locations relative to the document.
+     */
+    const visitor = new _visitor.default({
+      reference,
+      options
+    });
+    await (0, _apidomTraverse.traverseAsync)(dereferencedElement.result, visitor, {
+      mutable: true
+    });
+
     /**
      * Dereference extends target if option is enabled.
      */

package/src/dereference/strategies/overlay-1/index.mjs

@@ -1,9 +1,11 @@
 import { cloneDeep } from '@speclynx/apidom-datamodel';
 import { isOverlay1Element, mediaTypes } from '@speclynx/apidom-ns-overlay-1';
+import { traverseAsync } from '@speclynx/apidom-traverse';
 import DereferenceStrategy from "../DereferenceStrategy.mjs";
 import Reference from "../../../Reference.mjs";
 import ReferenceSet from "../../../ReferenceSet.mjs";
 import { dereferenceExtends } from "./extends.mjs";
+import Overlay1DereferenceVisitor from "./visitor.mjs";
 /**
  * @public
  */
@@ -54,6 +56,18 @@ class Overlay1DereferenceStrategy extends DereferenceStrategy {
     }
     const dereferencedElement = reference.value;
 
+    /**
+     * Reusable Action References only occur within `actions`, so the root element is never
+     * replaced and traversing it keeps reported locations relative to the document.
+     */
+    const visitor = new Overlay1DereferenceVisitor({
+      reference,
+      options
+    });
+    await traverseAsync(dereferencedElement.result, visitor, {
+      mutable: true
+    });
+
     /**
      * Dereference extends target if option is enabled.
      */
@@ -84,4 +98,5 @@ class Overlay1DereferenceStrategy extends DereferenceStrategy {
   }
 }
 export { dereferenceExtends } from "./extends.mjs";
+export { Overlay1DereferenceVisitor };
 export default Overlay1DereferenceStrategy;

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

@@ -0,0 +1,148 @@
+"use strict";
+
+var _interopRequireDefault = require("@babel/runtime-corejs3/helpers/interopRequireDefault").default;
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.default = void 0;
+var _apidomDatamodel = require("@speclynx/apidom-datamodel");
+var _apidomCore = require("@speclynx/apidom-core");
+var _apidomError = require("@speclynx/apidom-error");
+var _apidomJsonPointer = require("@speclynx/apidom-json-pointer");
+var _apidomNsOverlay = require("@speclynx/apidom-ns-overlay-1");
+var _UnresolvableReferenceError = _interopRequireDefault(require("../../../errors/UnresolvableReferenceError.cjs"));
+/**
+ * @public
+ */
+
+/**
+ * @public
+ */
+class Overlay1DereferenceVisitor {
+  reference;
+  options;
+  constructor({
+    reference,
+    options
+  }) {
+    this.reference = reference;
+    this.options = options;
+  }
+  ReusableActionReferenceElement(path) {
+    const referencingElement = path.node;
+
+    // ignore if resolve.internal is false (Reusable Action References are internal references only)
+    if (!this.options.resolve.internal) {
+      path.skip();
+      return;
+    }
+    const $ref = (0, _apidomCore.toValue)(referencingElement.$ref);
+    const overlayElement = this.reference.value.result;
+    const actionElement = new _apidomNsOverlay.ActionElement();
+    try {
+      if (typeof $ref !== 'string') {
+        throw new _apidomError.ApiDOMStructuredError('Reusable Action Reference "$ref" field must be a string');
+      }
+
+      // only `target`, `description` and extensions may accompany `$ref`
+      const disallowedField = ['update', 'copy', 'remove'].find(field => referencingElement.hasKey(field));
+      if (disallowedField !== undefined) {
+        throw new _apidomError.ApiDOMStructuredError(`Reusable Action Reference "${$ref}" must not define "${disallowedField}"`, {
+          $ref
+        });
+      }
+
+      // same-document reference only; external references are not supported
+      if (!$ref.startsWith('#')) {
+        throw new _apidomError.ApiDOMStructuredError(`Reusable Action Reference "${$ref}" must be a same-document reference`, {
+          $ref
+        });
+      }
+
+      /**
+       * Only entries of `components.actions` are refracted as Reusable Actions,
+       * so the element type alone proves the pointer leads there.
+       */
+      let reusableAction;
+      try {
+        reusableAction = (0, _apidomJsonPointer.evaluate)(overlayElement, _apidomJsonPointer.URIFragmentIdentifier.from($ref));
+      } catch {
+        reusableAction = undefined;
+      }
+      if (!(0, _apidomNsOverlay.isReusableActionElement)(reusableAction)) {
+        throw new _apidomError.ApiDOMStructuredError(`Reusable Action Reference "${$ref}" cannot be resolved`, {
+          $ref
+        });
+      }
+      const {
+        fields
+      } = reusableAction;
+      if (fields !== undefined && !(0, _apidomNsOverlay.isActionElement)(fields)) {
+        throw new _apidomError.ApiDOMStructuredError(`Reusable Action "${$ref}" must define "fields" as an object`, {
+          $ref
+        });
+      }
+      if ((0, _apidomNsOverlay.isActionElement)(fields) && fields.hasKey('target')) {
+        throw new _apidomError.ApiDOMStructuredError(`Reusable Action "${$ref}" must not define "target" in its "fields"`, {
+          $ref
+        });
+      }
+
+      // the reference supplies `target` and its `description` takes precedence over the one in `fields`
+      const {
+        target,
+        description
+      } = referencingElement;
+      if (target !== undefined) {
+        actionElement.set('target', (0, _apidomDatamodel.cloneDeep)(target));
+      }
+      if ((0, _apidomNsOverlay.isActionElement)(fields)) {
+        fields.forEach((value, keyElement) => {
+          actionElement.set((0, _apidomCore.toValue)(keyElement), (0, _apidomDatamodel.cloneDeep)(value));
+        });
+      }
+      if (description !== undefined) {
+        actionElement.set('description', (0, _apidomDatamodel.cloneDeep)(description));
+      }
+    } catch (error) {
+      const {
+        continueOnError
+      } = this.options.dereference;
+      const unresolvedError = new _UnresolvableReferenceError.default(`Error while dereferencing Reusable Action Reference "${$ref}": ${error.message}`, {
+        cause: error,
+        type: referencingElement.element,
+        uri: this.reference.uri,
+        location: path.formatPath(),
+        codeFrame: (0, _apidomCore.toYAML)(referencingElement),
+        refFieldName: '$ref',
+        refFieldValue: $ref,
+        trace: []
+      });
+      if (continueOnError === false) throw unresolvedError;
+      if (typeof continueOnError === 'function') continueOnError(unresolvedError);
+      path.skip();
+      return;
+    }
+
+    // the action takes the place of the reference in `actions`, so it inherits its source position
+    if ((0, _apidomDatamodel.hasElementSourceMap)(referencingElement)) {
+      _apidomDatamodel.SourceMapElement.transfer(referencingElement, actionElement);
+    }
+
+    // annotate with info about original referencing element
+    actionElement.meta.set('ref-fields', {
+      $ref,
+      description: (0, _apidomCore.toValue)(referencingElement.description)
+    });
+    // annotate with info about origin
+    actionElement.meta.set('ref-origin', this.reference.uri);
+    actionElement.meta.set('ref-type', referencingElement.element);
+
+    /**
+     * Transclude referencing element with resolved Action Object.
+     */
+    path.replaceWith(actionElement);
+    path.skip();
+  }
+}
+var _default = exports.default = Overlay1DereferenceVisitor;

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

@@ -0,0 +1,140 @@
+import { SourceMapElement, cloneDeep, hasElementSourceMap } from '@speclynx/apidom-datamodel';
+import { toValue, toYAML } from '@speclynx/apidom-core';
+import { ApiDOMStructuredError } from '@speclynx/apidom-error';
+import { evaluate as jsonPointerEvaluate, URIFragmentIdentifier } from '@speclynx/apidom-json-pointer';
+import { ActionElement, isActionElement, isReusableActionElement } from '@speclynx/apidom-ns-overlay-1';
+import UnresolvableReferenceError from "../../../errors/UnresolvableReferenceError.mjs";
+/**
+ * @public
+ */
+/**
+ * @public
+ */
+class Overlay1DereferenceVisitor {
+  reference;
+  options;
+  constructor({
+    reference,
+    options
+  }) {
+    this.reference = reference;
+    this.options = options;
+  }
+  ReusableActionReferenceElement(path) {
+    const referencingElement = path.node;
+
+    // ignore if resolve.internal is false (Reusable Action References are internal references only)
+    if (!this.options.resolve.internal) {
+      path.skip();
+      return;
+    }
+    const $ref = toValue(referencingElement.$ref);
+    const overlayElement = this.reference.value.result;
+    const actionElement = new ActionElement();
+    try {
+      if (typeof $ref !== 'string') {
+        throw new ApiDOMStructuredError('Reusable Action Reference "$ref" field must be a string');
+      }
+
+      // only `target`, `description` and extensions may accompany `$ref`
+      const disallowedField = ['update', 'copy', 'remove'].find(field => referencingElement.hasKey(field));
+      if (disallowedField !== undefined) {
+        throw new ApiDOMStructuredError(`Reusable Action Reference "${$ref}" must not define "${disallowedField}"`, {
+          $ref
+        });
+      }
+
+      // same-document reference only; external references are not supported
+      if (!$ref.startsWith('#')) {
+        throw new ApiDOMStructuredError(`Reusable Action Reference "${$ref}" must be a same-document reference`, {
+          $ref
+        });
+      }
+
+      /**
+       * Only entries of `components.actions` are refracted as Reusable Actions,
+       * so the element type alone proves the pointer leads there.
+       */
+      let reusableAction;
+      try {
+        reusableAction = jsonPointerEvaluate(overlayElement, URIFragmentIdentifier.from($ref));
+      } catch {
+        reusableAction = undefined;
+      }
+      if (!isReusableActionElement(reusableAction)) {
+        throw new ApiDOMStructuredError(`Reusable Action Reference "${$ref}" cannot be resolved`, {
+          $ref
+        });
+      }
+      const {
+        fields
+      } = reusableAction;
+      if (fields !== undefined && !isActionElement(fields)) {
+        throw new ApiDOMStructuredError(`Reusable Action "${$ref}" must define "fields" as an object`, {
+          $ref
+        });
+      }
+      if (isActionElement(fields) && fields.hasKey('target')) {
+        throw new ApiDOMStructuredError(`Reusable Action "${$ref}" must not define "target" in its "fields"`, {
+          $ref
+        });
+      }
+
+      // the reference supplies `target` and its `description` takes precedence over the one in `fields`
+      const {
+        target,
+        description
+      } = referencingElement;
+      if (target !== undefined) {
+        actionElement.set('target', cloneDeep(target));
+      }
+      if (isActionElement(fields)) {
+        fields.forEach((value, keyElement) => {
+          actionElement.set(toValue(keyElement), cloneDeep(value));
+        });
+      }
+      if (description !== undefined) {
+        actionElement.set('description', cloneDeep(description));
+      }
+    } catch (error) {
+      const {
+        continueOnError
+      } = this.options.dereference;
+      const unresolvedError = new UnresolvableReferenceError(`Error while dereferencing Reusable Action Reference "${$ref}": ${error.message}`, {
+        cause: error,
+        type: referencingElement.element,
+        uri: this.reference.uri,
+        location: path.formatPath(),
+        codeFrame: toYAML(referencingElement),
+        refFieldName: '$ref',
+        refFieldValue: $ref,
+        trace: []
+      });
+      if (continueOnError === false) throw unresolvedError;
+      if (typeof continueOnError === 'function') continueOnError(unresolvedError);
+      path.skip();
+      return;
+    }
+
+    // the action takes the place of the reference in `actions`, so it inherits its source position
+    if (hasElementSourceMap(referencingElement)) {
+      SourceMapElement.transfer(referencingElement, actionElement);
+    }
+
+    // annotate with info about original referencing element
+    actionElement.meta.set('ref-fields', {
+      $ref,
+      description: toValue(referencingElement.description)
+    });
+    // annotate with info about origin
+    actionElement.meta.set('ref-origin', this.reference.uri);
+    actionElement.meta.set('ref-type', referencingElement.element);
+
+    /**
+     * Transclude referencing element with resolved Action Object.
+     */
+    path.replaceWith(actionElement);
+    path.skip();
+  }
+}
+export default Overlay1DereferenceVisitor;

package/src/parse/parsers/overlay-json-1/extends.cjs

@@ -40,8 +40,12 @@ async function parseExtends(parseResult, parseResultRetrievalURI, options) {
   if (!(0, _apidomDatamodel.isStringElement)(extendsElement)) {
     return;
   }
+
+  // Overlay 1.2.0: `$self` (itself resolved against the retrieval URI) is the base URI
+  const selfElement = api.get('$self');
+  const baseURI = (0, _apidomDatamodel.isStringElement)(selfElement) ? url.resolve(file.uri, (0, _apidomCore.toValue)(selfElement)) : file.uri;
   const extendsURI = (0, _apidomCore.toValue)(extendsElement);
-  const retrievalURI = url.sanitize(url.stripHash(url.resolve(file.uri, extendsURI)));
+  const retrievalURI = url.sanitize(url.stripHash(url.resolve(baseURI, extendsURI)));
   const extendsParseResult = new _apidomDatamodel.ParseResultElement();
   extendsParseResult.classes.push('extends');
   extendsParseResult.setMetaProperty('retrievalURI', retrievalURI);

package/src/parse/parsers/overlay-json-1/extends.mjs

@@ -32,8 +32,12 @@ export async function parseExtends(parseResult, parseResultRetrievalURI, options
   if (!isStringElement(extendsElement)) {
     return;
   }
+
+  // Overlay 1.2.0: `$self` (itself resolved against the retrieval URI) is the base URI
+  const selfElement = api.get('$self');
+  const baseURI = isStringElement(selfElement) ? url.resolve(file.uri, toValue(selfElement)) : file.uri;
   const extendsURI = toValue(extendsElement);
-  const retrievalURI = url.sanitize(url.stripHash(url.resolve(file.uri, extendsURI)));
+  const retrievalURI = url.sanitize(url.stripHash(url.resolve(baseURI, extendsURI)));
   const extendsParseResult = new ParseResultElement();
   extendsParseResult.classes.push('extends');
   extendsParseResult.setMetaProperty('retrievalURI', retrievalURI);

package/src/util/url.cjs

@@ -1,11 +1,9 @@
 "use strict";
 
-var _interopRequireDefault = require("@babel/runtime-corejs3/helpers/interopRequireDefault").default;
 Object.defineProperty(exports, "__esModule", {
   value: true
 });
 exports.unsanitize = exports.toFileSystemPath = exports.stripHash = exports.sanitize = exports.resolve = exports.relative = exports.isURI = exports.isHttpUrl = exports.isFileSystemPath = exports.hasProtocol = exports.getProtocol = exports.getHash = exports.getExtension = exports.getBasename = exports.fromFileSystemPath = exports.cwd = void 0;
-var _process = _interopRequireDefault(require("process"));
 var _ramda = require("ramda");
 var _ramdaAdjunct = require("ramda-adjunct");
 /**
@@ -18,7 +16,7 @@ var _ramdaAdjunct = require("ramda-adjunct");
  * @public
  */
 
-const isWindows = () => (0, _ramda.pathSatisfies)((0, _ramda.test)(/^win/), ['platform'], _process.default);
+const isWindows = () => (0, _ramda.pathSatisfies)((0, _ramda.test)(/^win/), ['platform'], globalThis.process);
 
 /**
  * Returns the protocol of the given URL, or `undefined` if it has no protocol.
@@ -244,11 +242,15 @@ const stripHash = uri => {
  */
 exports.stripHash = stripHash;
 const cwd = () => {
+  const {
+    process
+  } = globalThis;
+
   // @ts-ignore
-  if (_process.default.browser) {
+  if (typeof process?.cwd !== 'function' || process.browser) {
     return stripHash(globalThis.location.href);
   }
-  const path = _process.default.cwd();
+  const path = process.cwd();
   const lastChar = (0, _ramda.last)(path);
   if (['/', '\\'].includes(lastChar)) {
     return path;
@@ -264,13 +266,14 @@ exports.cwd = cwd;
 const resolve = (from, to) => {
   const resolvedUrl = new URL(to, new URL(from, 'resolve://'));
   if (resolvedUrl.protocol === 'resolve:') {
-    // `from` is a relative URL.
+    // `from` is a relative URL; a network-path reference (`//host/path`) keeps its authority
     const {
+      host,
       pathname,
       search,
       hash
     } = resolvedUrl;
-    return pathname + search + hash;
+    return (host ? `//${host}` : '') + pathname + search + hash;
   }
   return resolvedUrl.toString();
 };

package/src/util/url.mjs

@@ -1,4 +1,3 @@
-import process from 'process';
 import { pathSatisfies, propOr, pipe, test, last } from 'ramda';
 import { isUndefined, replaceAll, isNotUndefined, trimCharsEnd } from 'ramda-adjunct';
 
@@ -12,7 +11,7 @@ import { isUndefined, replaceAll, isNotUndefined, trimCharsEnd } from 'ramda-adj
  * @public
  */
 
-const isWindows = () => pathSatisfies(test(/^win/), ['platform'], process);
+const isWindows = () => pathSatisfies(test(/^win/), ['platform'], globalThis.process);
 
 /**
  * Returns the protocol of the given URL, or `undefined` if it has no protocol.
@@ -229,8 +228,12 @@ export const stripHash = uri => {
  * @public
  */
 export const cwd = () => {
+  const {
+    process
+  } = globalThis;
+
   // @ts-ignore
-  if (process.browser) {
+  if (typeof process?.cwd !== 'function' || process.browser) {
     return stripHash(globalThis.location.href);
   }
   const path = process.cwd();
@@ -248,13 +251,14 @@ export const cwd = () => {
 export const resolve = (from, to) => {
   const resolvedUrl = new URL(to, new URL(from, 'resolve://'));
   if (resolvedUrl.protocol === 'resolve:') {
-    // `from` is a relative URL.
+    // `from` is a relative URL; a network-path reference (`//host/path`) keeps its authority
     const {
+      host,
       pathname,
       search,
       hash
     } = resolvedUrl;
-    return pathname + search + hash;
+    return (host ? `//${host}` : '') + pathname + search + hash;
   }
   return resolvedUrl.toString();
 };

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

@@ -2,6 +2,7 @@ import { Element } from '@speclynx/apidom-datamodel';
 import DereferenceStrategy, { DereferenceStrategyOptions } from '../DereferenceStrategy.ts';
 import File from '../../../File.ts';
 import type { ReferenceOptions } from '../../../options/index.ts';
+import Overlay1DereferenceVisitor from './visitor.ts';
 export type { default as DereferenceStrategy, DereferenceStrategyOptions, } from '../DereferenceStrategy.ts';
 export type { default as File, FileOptions } from '../../../File.ts';
 export type { default as Reference, ReferenceOptions } from '../../../Reference.ts';
@@ -25,4 +26,6 @@ declare class Overlay1DereferenceStrategy extends DereferenceStrategy {
     dereference(file: File, options: ReferenceOptions): Promise<Element>;
 }
 export { dereferenceExtends } from './extends.ts';
+export { Overlay1DereferenceVisitor };
+export type { Overlay1DereferenceVisitorOptions } from './visitor.ts';
 export default Overlay1DereferenceStrategy;

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

@@ -0,0 +1,21 @@
+import { Element } from '@speclynx/apidom-datamodel';
+import type { Path } from '@speclynx/apidom-traverse';
+import Reference from '../../../Reference.ts';
+import type { ReferenceOptions } from '../../../options/index.ts';
+/**
+ * @public
+ */
+export interface Overlay1DereferenceVisitorOptions {
+    readonly reference: Reference;
+    readonly options: ReferenceOptions;
+}
+/**
+ * @public
+ */
+declare class Overlay1DereferenceVisitor {
+    protected readonly reference: Reference;
+    protected readonly options: ReferenceOptions;
+    constructor({ reference, options }: Overlay1DereferenceVisitorOptions);
+    ReusableActionReferenceElement(path: Path<Element>): void;
+}
+export default Overlay1DereferenceVisitor;