@speclynx/apidom-overlay 6.0.1 → 6.1.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@speclynx/apidom-overlay",
-  "version": "6.0.1",
+  "version": "6.1.0",
   "description": "Apply Overlay 1.x.y documents to API definitions.",
   "keywords": [
     "apidom",
@@ -18,7 +18,8 @@
   "publishConfig": {
     "access": "public",
     "registry": "https://registry.npmjs.org",
-    "provenance": true
+    "provenance": true,
+    "timeout": 60000
   },
   "type": "module",
   "sideEffects": false,
@@ -53,12 +54,13 @@
   "license": "Apache-2.0",
   "dependencies": {
     "@babel/runtime-corejs3": "^8.0.5",
-    "@speclynx/apidom-core": "6.0.1",
-    "@speclynx/apidom-datamodel": "6.0.1",
-    "@speclynx/apidom-error": "6.0.1",
-    "@speclynx/apidom-json-path": "6.0.1",
-    "@speclynx/apidom-ns-overlay-1": "6.0.1",
-    "@speclynx/apidom-reference": "6.0.1",
+    "@speclynx/apidom-core": "6.1.0",
+    "@speclynx/apidom-datamodel": "6.1.0",
+    "@speclynx/apidom-error": "6.1.0",
+    "@speclynx/apidom-json-path": "6.1.0",
+    "@speclynx/apidom-ns-overlay-1": "6.1.0",
+    "@speclynx/apidom-reference": "6.1.0",
+    "ramda": "~0.32.0",
     "type-fest": "^5.10.0"
   },
   "files": [
@@ -71,5 +73,5 @@
     "README.md",
     "CHANGELOG.md"
   ],
-  "gitHead": "d2ea4f01cac54a0d5e1030386e3b0b60664c9619"
+  "gitHead": "575dbf59cb58a6c57248bf2c027a5cbc99442a63"
 }

package/src/apply/realms/apidom.cjs

@@ -82,6 +82,20 @@ const mergeValue = (targetElement, sourceElement, options = defaultApplyOptions)
   throw new _OverlayError.default(`Incompatible types in overlay merge: cannot merge ` + `${targetIsObject ? 'object' : targetIsArray ? 'array' : 'primitive'} with ` + `${sourceIsObject ? 'object' : sourceIsArray ? 'array' : 'primitive'}`);
 };
 
+/**
+ * Anchors, aliases and comments belong to the overlay document. Written in the
+ * target they'd clash with its anchor names (an overlay anchor taking a name
+ * the target's aliases refer to, an overlay alias referring to a target node)
+ * or carry notes meant for the overlay. How a value is written is kept.
+ */
+const stripOverlayOnlyStyle = element => {
+  const yamlStyle = element.style?.yaml;
+  if (yamlStyle !== undefined) {
+    ['anchor', 'alias', 'comment', 'commentBefore'].forEach(name => delete yamlStyle[name]);
+  }
+  element.children.forEach(stripOverlayOnlyStyle);
+};
+
 /**
  * Resolves a normalized path to its parent element and child key.
  */
@@ -280,7 +294,9 @@ const applyAction = (actionElement, targetElement, options = defaultApplyOptions
     if (actionElement.update !== undefined) {
       const nodesValidation = (0, _validate.validateTargetNodes)(matches);
       if (!nodesValidation.valid) throw nodesValidation.error;
-      const result = applyUpdateAction(normalizedPaths, actionElement.update, workingElement, mutatingOptions);
+      const updateValue = (0, _apidomDatamodel.cloneDeep)(actionElement.update);
+      stripOverlayOnlyStyle(updateValue);
+      const result = applyUpdateAction(normalizedPaths, updateValue, workingElement, mutatingOptions);
       tracer?.action({
         target: targetExpression,
         type: 'update',

package/src/apply/realms/apidom.mjs

@@ -72,6 +72,20 @@ const mergeValue = (targetElement, sourceElement, options = defaultApplyOptions)
   throw new OverlayError(`Incompatible types in overlay merge: cannot merge ` + `${targetIsObject ? 'object' : targetIsArray ? 'array' : 'primitive'} with ` + `${sourceIsObject ? 'object' : sourceIsArray ? 'array' : 'primitive'}`);
 };
 
+/**
+ * Anchors, aliases and comments belong to the overlay document. Written in the
+ * target they'd clash with its anchor names (an overlay anchor taking a name
+ * the target's aliases refer to, an overlay alias referring to a target node)
+ * or carry notes meant for the overlay. How a value is written is kept.
+ */
+const stripOverlayOnlyStyle = element => {
+  const yamlStyle = element.style?.yaml;
+  if (yamlStyle !== undefined) {
+    ['anchor', 'alias', 'comment', 'commentBefore'].forEach(name => delete yamlStyle[name]);
+  }
+  element.children.forEach(stripOverlayOnlyStyle);
+};
+
 /**
  * Resolves a normalized path to its parent element and child key.
  */
@@ -267,7 +281,9 @@ export const applyAction = (actionElement, targetElement, options = defaultApply
     if (actionElement.update !== undefined) {
       const nodesValidation = validateTargetNodes(matches);
       if (!nodesValidation.valid) throw nodesValidation.error;
-      const result = applyUpdateAction(normalizedPaths, actionElement.update, workingElement, mutatingOptions);
+      const updateValue = cloneDeep(actionElement.update);
+      stripOverlayOnlyStyle(updateValue);
+      const result = applyUpdateAction(normalizedPaths, updateValue, workingElement, mutatingOptions);
       tracer?.action({
         target: targetExpression,
         type: 'update',

package/src/apply/realms/uri.cjs

@@ -17,12 +17,12 @@ const defaultReferenceOptions = {
       style: true,
       'overlay-json-1': {
         sourceMap: true,
-        style: false,
+        style: true,
         extends: true
       },
       'overlay-yaml-1': {
         sourceMap: true,
-        style: false,
+        style: true,
         extends: true
       }
     }
@@ -47,8 +47,10 @@ const defaultOptions = exports.defaultOptions = {
  * Applies an overlay document from a file/URL to its target document.
  *
  * Parses the overlay, resolves the target from `targetURI` or the overlay's
- * `extends` field, parses the target with style preservation for round-trip fidelity,
- * and applies all overlay actions.
+ * `extends` field, and applies all overlay actions. Both documents are parsed with
+ * style preservation for round-trip fidelity, so values added by the overlay are
+ * written as they're written in the overlay when both are in the same format.
+ * Anchors, aliases and comments in the overlay aren't written to the target.
  *
  * @param overlayURI - URI to the overlay document (file path or URL)
  * @param targetURI - URI to the target document; if omitted, uses the overlay's `extends` field

package/src/apply/realms/uri.mjs

@@ -10,12 +10,12 @@ const defaultReferenceOptions = {
       style: true,
       'overlay-json-1': {
         sourceMap: true,
-        style: false,
+        style: true,
         extends: true
       },
       'overlay-yaml-1': {
         sourceMap: true,
-        style: false,
+        style: true,
         extends: true
       }
     }
@@ -40,8 +40,10 @@ export const defaultOptions = {
  * Applies an overlay document from a file/URL to its target document.
  *
  * Parses the overlay, resolves the target from `targetURI` or the overlay's
- * `extends` field, parses the target with style preservation for round-trip fidelity,
- * and applies all overlay actions.
+ * `extends` field, and applies all overlay actions. Both documents are parsed with
+ * style preservation for round-trip fidelity, so values added by the overlay are
+ * written as they're written in the overlay when both are in the same format.
+ * Anchors, aliases and comments in the overlay aren't written to the target.
  *
  * @param overlayURI - URI to the overlay document (file path or URL)
  * @param targetURI - URI to the target document; if omitted, uses the overlay's `extends` field

package/src/diff/realms/apidom.cjs

@@ -5,7 +5,9 @@ Object.defineProperty(exports, "__esModule", {
   value: true
 });
 exports.diff = void 0;
+var _ramda = require("ramda");
 var _apidomDatamodel = require("@speclynx/apidom-datamodel");
+var _apidomCore = require("@speclynx/apidom-core");
 var _apidomJsonPath = require("@speclynx/apidom-json-path");
 var _apidomNsOverlay = require("@speclynx/apidom-ns-overlay-1");
 var _OverlayError = _interopRequireDefault(require("../../errors/OverlayError.cjs"));
@@ -38,8 +40,12 @@ const createRemoveAction = segments => {
   action.removeField = new _apidomDatamodel.BooleanElement(true);
   return action;
 };
+
+// elements are compared by their serialized values, which tell an empty YAML node (null) from an
+// empty string; Element#equals compares the elements' own values, where both are an empty string
+const isEqual = (left, right) => (0, _ramda.equals)((0, _apidomCore.toValue)(left), (0, _apidomCore.toValue)(right));
 const diffElements = (left, right, segments, actions) => {
-  if (left.equals(right)) return;
+  if (isEqual(left, right)) return;
   const leftKind = left.primitive();
   const rightKind = right.primitive();
   if (leftKind !== rightKind) {
@@ -104,7 +110,7 @@ const diffArrays = (left, right, segments, actions) => {
   for (let i = 0; i < minLen; i++) {
     const leftItem = left.get(i);
     const rightItem = right.get(i);
-    if (leftItem.equals(rightItem)) continue;
+    if (isEqual(leftItem, rightItem)) continue;
     if (leftItem.primitive() !== rightItem.primitive()) {
       // structural type change at index i — reconstruct tail:
       // remove from end down to i (reverse order preserves index stability),

package/src/diff/realms/apidom.mjs

@@ -1,4 +1,6 @@
+import { equals } from 'ramda';
 import { ObjectElement, ArrayElement, StringElement, BooleanElement, isObjectElement, isArrayElement, cloneDeep } from '@speclynx/apidom-datamodel';
+import { toValue } from '@speclynx/apidom-core';
 import { NormalizedPath } from '@speclynx/apidom-json-path';
 import { ActionElement, Overlay1Element, InfoElement, OverlayElement, ActionsElement } from '@speclynx/apidom-ns-overlay-1';
 import OverlayError from "../../errors/OverlayError.mjs";
@@ -30,8 +32,12 @@ const createRemoveAction = segments => {
   action.removeField = new BooleanElement(true);
   return action;
 };
+
+// elements are compared by their serialized values, which tell an empty YAML node (null) from an
+// empty string; Element#equals compares the elements' own values, where both are an empty string
+const isEqual = (left, right) => equals(toValue(left), toValue(right));
 const diffElements = (left, right, segments, actions) => {
-  if (left.equals(right)) return;
+  if (isEqual(left, right)) return;
   const leftKind = left.primitive();
   const rightKind = right.primitive();
   if (leftKind !== rightKind) {
@@ -96,7 +102,7 @@ const diffArrays = (left, right, segments, actions) => {
   for (let i = 0; i < minLen; i++) {
     const leftItem = left.get(i);
     const rightItem = right.get(i);
-    if (leftItem.equals(rightItem)) continue;
+    if (isEqual(leftItem, rightItem)) continue;
     if (leftItem.primitive() !== rightItem.primitive()) {
       // structural type change at index i — reconstruct tail:
       // remove from end down to i (reverse order preserves index stability),

package/types/apidom-overlay.d.ts

@@ -65,8 +65,10 @@ export declare interface ApplyOptions {
  * Applies an overlay document from a file/URL to its target document.
  *
  * Parses the overlay, resolves the target from `targetURI` or the overlay's
- * `extends` field, parses the target with style preservation for round-trip fidelity,
- * and applies all overlay actions.
+ * `extends` field, and applies all overlay actions. Both documents are parsed with
+ * style preservation for round-trip fidelity, so values added by the overlay are
+ * written as they're written in the overlay when both are in the same format.
+ * Anchors, aliases and comments in the overlay aren't written to the target.
  *
  * @param overlayURI - URI to the overlay document (file path or URL)
  * @param targetURI - URI to the target document; if omitted, uses the overlay's `extends` field