@speclynx/apidom-overlay 6.1.0 → 6.1.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@speclynx/apidom-overlay",
-  "version": "6.1.0",
+  "version": "6.1.2",
   "description": "Apply Overlay 1.x.y documents to API definitions.",
   "keywords": [
     "apidom",
@@ -53,13 +53,13 @@
   "author": "Vladimir Gorej",
   "license": "Apache-2.0",
   "dependencies": {
-    "@babel/runtime-corejs3": "^8.0.5",
-    "@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",
+    "@babel/runtime-corejs3": "^8.0.8",
+    "@speclynx/apidom-core": "6.1.2",
+    "@speclynx/apidom-datamodel": "6.1.2",
+    "@speclynx/apidom-error": "6.1.2",
+    "@speclynx/apidom-json-path": "6.1.2",
+    "@speclynx/apidom-ns-overlay-1": "6.1.2",
+    "@speclynx/apidom-reference": "6.1.2",
     "ramda": "~0.32.0",
     "type-fest": "^5.10.0"
   },
@@ -73,5 +73,5 @@
     "README.md",
     "CHANGELOG.md"
   ],
-  "gitHead": "575dbf59cb58a6c57248bf2c027a5cbc99442a63"
+  "gitHead": "e3ba735e1c56369bb263dd8246c711d405ed9606"
 }

package/src/diff/realms/apidom.cjs

@@ -4,7 +4,7 @@ var _interopRequireDefault = require("@babel/runtime-corejs3/helpers/interopRequ
 Object.defineProperty(exports, "__esModule", {
   value: true
 });
-exports.diff = void 0;
+exports.diff = exports.assertSupportedOverlayVersion = void 0;
 var _ramda = require("ramda");
 var _apidomDatamodel = require("@speclynx/apidom-datamodel");
 var _apidomCore = require("@speclynx/apidom-core");
@@ -22,6 +22,21 @@ const defaultDiffOptions = {
     version: '0.0.0'
   }
 };
+
+// generated actions update primitive values and concatenate arrays, which Overlay 1.0.0 doesn't allow
+const supportedOverlayVersions = _apidomNsOverlay.mediaTypes.filterByFormat('generic').map(mediaType => mediaType.split('version=')[1]).filter(version => version !== '1.0.0');
+
+/**
+ * Throws {@link OverlayError} when the overlay version option is unsupported.
+ * Shared with the URI realm, which checks it before parsing any document.
+ */
+const assertSupportedOverlayVersion = overlay => {
+  const overlayVersion = overlay ?? defaultDiffOptions.overlay;
+  if (!supportedOverlayVersions.includes(overlayVersion)) {
+    throw new _OverlayError.default(`Unsupported overlay version "${overlayVersion}": diff supports ${supportedOverlayVersions.join(', ')}`);
+  }
+};
+exports.assertSupportedOverlayVersion = assertSupportedOverlayVersion;
 const createUpdateAction = (segments, value) => {
   const action = new _apidomNsOverlay.ActionElement();
   action.target = new _apidomDatamodel.StringElement(_apidomJsonPath.NormalizedPath.from(segments));
@@ -41,14 +56,19 @@ const createRemoveAction = segments => {
   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
+// elements are compared by their values, read with the core toValue
 const isEqual = (left, right) => (0, _ramda.equals)((0, _apidomCore.toValue)(left), (0, _apidomCore.toValue)(right));
+
+// a null (as an empty YAML node is) filled in with a scalar, or a scalar emptied to a null, is
+// updated in place like a value, keeping its position; any other change of type is structural
+const isStructuralChange = (left, right) => {
+  const kinds = [left.primitive(), right.primitive()];
+  const isCollection = kinds.some(kind => kind === 'object' || kind === 'array');
+  return kinds[0] !== kinds[1] && (isCollection || !kinds.includes('null'));
+};
 const diffElements = (left, right, segments, actions) => {
   if (isEqual(left, right)) return;
-  const leftKind = left.primitive();
-  const rightKind = right.primitive();
-  if (leftKind !== rightKind) {
+  if (isStructuralChange(left, right)) {
     if (segments.length === 0) {
       throw new _OverlayError.default('Cannot diff documents with incompatible root types');
     }
@@ -111,7 +131,7 @@ const diffArrays = (left, right, segments, actions) => {
     const leftItem = left.get(i);
     const rightItem = right.get(i);
     if (isEqual(leftItem, rightItem)) continue;
-    if (leftItem.primitive() !== rightItem.primitive()) {
+    if (isStructuralChange(leftItem, rightItem)) {
       // structural type change at index i — reconstruct tail:
       // remove from end down to i (reverse order preserves index stability),
       // then batch-append right[i..] as a single ArrayElement (Overlay concat semantics)
@@ -166,6 +186,7 @@ const diff = (leftElement, rightElement, options = {}) => {
   const infoTitle = options.info?.title ?? defaultDiffOptions.info.title;
   const infoVersion = options.info?.version ?? defaultDiffOptions.info.version;
   const infoDescription = options.info?.description;
+  assertSupportedOverlayVersion(overlayVersion);
   const actions = [];
   diffElements(leftElement, rightElement, [], actions);
   if (actions.length === 0 && options.onEmptyDiff === 'throw') {

package/src/diff/realms/apidom.mjs

@@ -2,7 +2,7 @@ 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 { ActionElement, Overlay1Element, InfoElement, OverlayElement, ActionsElement, mediaTypes } from '@speclynx/apidom-ns-overlay-1';
 import OverlayError from "../../errors/OverlayError.mjs";
 /**
  * @public
@@ -14,6 +14,20 @@ const defaultDiffOptions = {
     version: '0.0.0'
   }
 };
+
+// generated actions update primitive values and concatenate arrays, which Overlay 1.0.0 doesn't allow
+const supportedOverlayVersions = mediaTypes.filterByFormat('generic').map(mediaType => mediaType.split('version=')[1]).filter(version => version !== '1.0.0');
+
+/**
+ * Throws {@link OverlayError} when the overlay version option is unsupported.
+ * Shared with the URI realm, which checks it before parsing any document.
+ */
+export const assertSupportedOverlayVersion = overlay => {
+  const overlayVersion = overlay ?? defaultDiffOptions.overlay;
+  if (!supportedOverlayVersions.includes(overlayVersion)) {
+    throw new OverlayError(`Unsupported overlay version "${overlayVersion}": diff supports ${supportedOverlayVersions.join(', ')}`);
+  }
+};
 const createUpdateAction = (segments, value) => {
   const action = new ActionElement();
   action.target = new StringElement(NormalizedPath.from(segments));
@@ -33,14 +47,19 @@ const createRemoveAction = segments => {
   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
+// elements are compared by their values, read with the core toValue
 const isEqual = (left, right) => equals(toValue(left), toValue(right));
+
+// a null (as an empty YAML node is) filled in with a scalar, or a scalar emptied to a null, is
+// updated in place like a value, keeping its position; any other change of type is structural
+const isStructuralChange = (left, right) => {
+  const kinds = [left.primitive(), right.primitive()];
+  const isCollection = kinds.some(kind => kind === 'object' || kind === 'array');
+  return kinds[0] !== kinds[1] && (isCollection || !kinds.includes('null'));
+};
 const diffElements = (left, right, segments, actions) => {
   if (isEqual(left, right)) return;
-  const leftKind = left.primitive();
-  const rightKind = right.primitive();
-  if (leftKind !== rightKind) {
+  if (isStructuralChange(left, right)) {
     if (segments.length === 0) {
       throw new OverlayError('Cannot diff documents with incompatible root types');
     }
@@ -103,7 +122,7 @@ const diffArrays = (left, right, segments, actions) => {
     const leftItem = left.get(i);
     const rightItem = right.get(i);
     if (isEqual(leftItem, rightItem)) continue;
-    if (leftItem.primitive() !== rightItem.primitive()) {
+    if (isStructuralChange(leftItem, rightItem)) {
       // structural type change at index i — reconstruct tail:
       // remove from end down to i (reverse order preserves index stability),
       // then batch-append right[i..] as a single ArrayElement (Overlay concat semantics)
@@ -158,6 +177,7 @@ export const diff = (leftElement, rightElement, options = {}) => {
   const infoTitle = options.info?.title ?? defaultDiffOptions.info.title;
   const infoVersion = options.info?.version ?? defaultDiffOptions.info.version;
   const infoDescription = options.info?.description;
+  assertSupportedOverlayVersion(overlayVersion);
   const actions = [];
   diffElements(leftElement, rightElement, [], actions);
   if (actions.length === 0 && options.onEmptyDiff === 'throw') {

package/src/diff/realms/uri.cjs

@@ -49,6 +49,8 @@ const defaultOptions = exports.defaultOptions = {
  * @public
  */
 const diff = async (leftURI, rightURI, options = defaultOptions) => {
+  // fail on an unsupported version before fetching and parsing the documents
+  (0, _apidom.assertSupportedOverlayVersion)(options.overlay);
   const mergedRefOptions = (0, _apidomReference.mergeOptions)(defaultReferenceOptions, options.reference ?? {});
   const [leftParseResult, rightParseResult] = await Promise.all([(0, _apidomReference.parse)(leftURI, mergedRefOptions), (0, _apidomReference.parse)(rightURI, mergedRefOptions)]);
   const leftElement = leftParseResult.api;

package/src/diff/realms/uri.mjs

@@ -1,5 +1,5 @@
 import { parse, mergeOptions } from '@speclynx/apidom-reference';
-import { diff as diffApiDOM } from "./apidom.mjs";
+import { diff as diffApiDOM, assertSupportedOverlayVersion } from "./apidom.mjs";
 import OverlayError from "../../errors/OverlayError.mjs";
 /**
  * @public
@@ -41,6 +41,8 @@ export const defaultOptions = {
  * @public
  */
 const diff = async (leftURI, rightURI, options = defaultOptions) => {
+  // fail on an unsupported version before fetching and parsing the documents
+  assertSupportedOverlayVersion(options.overlay);
   const mergedRefOptions = mergeOptions(defaultReferenceOptions, options.reference ?? {});
   const [leftParseResult, rightParseResult] = await Promise.all([parse(leftURI, mergedRefOptions), parse(rightURI, mergedRefOptions)]);
   const leftElement = leftParseResult.api;

package/types/apidom-overlay.d.ts

@@ -155,6 +155,11 @@ export declare const diffApiDOM: (leftElement: Element_2, rightElement: Element_
  * @public
  */
 export declare interface DiffOptions {
+    /**
+     * Version written to the `overlay` field (default `'1.2.0'`). Must be `1.1.0` or later,
+     * otherwise {@link OverlayError} is thrown: generated actions update primitive values and
+     * concatenate arrays, which Overlay 1.0.0 doesn't allow.
+     */
     readonly overlay?: string;
     readonly info?: {
         title?: string;