@speclynx/apidom-parser-adapter-openapi-yaml-2 5.0.2 → 5.1.0

package/CHANGELOG.md

@@ -3,6 +3,10 @@
 All notable changes to this project will be documented in this file.
 See [Conventional Commits](https://conventionalcommits.org) for commit guidelines.
 
+# [5.1.0](https://github.com/speclynx/apidom/compare/v5.0.2...v5.1.0) (2026-08-09)
+
+**Note:** Version bump only for package @speclynx/apidom-parser-adapter-openapi-yaml-2
+
 ## [5.0.2](https://github.com/speclynx/apidom/compare/v5.0.1...v5.0.2) (2026-08-04)
 
 **Note:** Version bump only for package @speclynx/apidom-parser-adapter-openapi-yaml-2

package/dist/apidom-parser-adapter-openapi-yaml-2.browser.js

@@ -1122,7 +1122,7 @@ function _defineProperty(e, r, t) { return (r = _toPropertyKey(r)) in e ? Object
 function _toPropertyKey(t) { var i = _toPrimitive(t, "string"); return "symbol" == typeof i ? i : i + ""; }
 function _toPrimitive(t, r) { if ("object" != typeof t || !t) return t; var e = t[Symbol.toPrimitive]; if (void 0 !== e) { var i = e.call(t, r || "default"); if ("object" != typeof i) return i; throw new TypeError("@@toPrimitive must return a primitive value."); } return ("string" === r ? String : Number)(t); }
 function _assertClassBrand(e, t, n) { if ("function" == typeof e ? e === t : e.has(t)) return arguments.length < 3 ? t : n; throw new TypeError("Private element is not present on this object"); }
-
+;
 
 var _CompositeEvaluationRealm_brand = /*#__PURE__*/new WeakSet();
 class CompositeEvaluationRealm extends _EvaluationRealm_mjs__WEBPACK_IMPORTED_MODULE_0__["default"] {
@@ -10067,7 +10067,7 @@ function _unsupportedIterableToArray(r, a) { if (r) { if ("string" == typeof r)
 function _iterableToArray(r) { if ("undefined" != typeof Symbol && null != r[Symbol.iterator] || null != r["@@iterator"]) return Array.from(r); }
 function _arrayWithoutHoles(r) { if (Array.isArray(r)) return _arrayLikeToArray(r); }
 function _arrayLikeToArray(r, a) { (null == a || a > r.length) && (a = r.length); for (var e = 0, n = Array(a); e < a; e++) n[e] = r[e]; return n; }
-
+;
 
 /**
  * Can be used as a way to compose multiple invokers together to form polymorphic functions,
@@ -30749,7 +30749,7 @@ __webpack_require__.r(__webpack_exports__);
  * @public
  */
 const emptyElement = element => {
-  const meta = !element.isMetaEmpty ? element.meta.cloneDeep() : undefined;
+  const meta = !element.isMetaEmpty ? (0,_speclynx_apidom_datamodel__WEBPACK_IMPORTED_MODULE_1__.cloneDeep)(element.meta) : undefined;
   const attributes = !element.isAttributesEmpty ? (0,_speclynx_apidom_datamodel__WEBPACK_IMPORTED_MODULE_1__.cloneDeep)(element.attributes) : undefined;
 
   // @ts-ignore
@@ -30765,7 +30765,7 @@ const getMergeFunction = (keyElement, options) => {
 };
 const getMetaMergeFunction = options => {
   if (typeof options.customMetaMerge !== 'function') {
-    return targetMeta => targetMeta.cloneDeep();
+    return targetMeta => (0,_speclynx_apidom_datamodel__WEBPACK_IMPORTED_MODULE_1__.cloneDeep)(targetMeta);
   }
   return options.customMetaMerge;
 };
@@ -30840,9 +30840,9 @@ const deepmerge = (targetElement, sourceElement, options) => {
   if (!targetElement.isMetaEmpty && !sourceElement.isMetaEmpty) {
     mergedElement.meta = getMetaMergeFunction(mergedOptions)(targetElement.meta, sourceElement.meta);
   } else if (!targetElement.isMetaEmpty) {
-    mergedElement.meta = targetElement.meta.cloneDeep();
+    mergedElement.meta = (0,_speclynx_apidom_datamodel__WEBPACK_IMPORTED_MODULE_1__.cloneDeep)(targetElement.meta);
   } else if (!sourceElement.isMetaEmpty) {
-    mergedElement.meta = sourceElement.meta.cloneDeep();
+    mergedElement.meta = (0,_speclynx_apidom_datamodel__WEBPACK_IMPORTED_MODULE_1__.cloneDeep)(sourceElement.meta);
   }
   if (!targetElement.isAttributesEmpty && !sourceElement.isAttributesEmpty) {
     mergedElement.attributes = getAttributesMergeFunction(mergedOptions)(targetElement.attributes, sourceElement.attributes);
@@ -31820,19 +31820,21 @@ class ShallowCloneError extends _CloneError_mjs__WEBPACK_IMPORTED_MODULE_0__["de
 "use strict";
 __webpack_require__.r(__webpack_exports__);
 /* harmony export */ __webpack_require__.d(__webpack_exports__, {
-/* harmony export */   CloneError: () => (/* reexport safe */ _errors_CloneError_mjs__WEBPACK_IMPORTED_MODULE_8__["default"]),
-/* harmony export */   DeepCloneError: () => (/* reexport safe */ _errors_DeepCloneError_mjs__WEBPACK_IMPORTED_MODULE_6__["default"]),
-/* harmony export */   ShallowCloneError: () => (/* reexport safe */ _errors_ShallowCloneError_mjs__WEBPACK_IMPORTED_MODULE_7__["default"])
+/* harmony export */   CloneError: () => (/* reexport safe */ _errors_CloneError_mjs__WEBPACK_IMPORTED_MODULE_9__["default"]),
+/* harmony export */   DeepCloneError: () => (/* reexport safe */ _errors_DeepCloneError_mjs__WEBPACK_IMPORTED_MODULE_7__["default"]),
+/* harmony export */   ShallowCloneError: () => (/* reexport safe */ _errors_ShallowCloneError_mjs__WEBPACK_IMPORTED_MODULE_8__["default"])
 /* harmony export */ });
 /* harmony import */ var ramda__WEBPACK_IMPORTED_MODULE_0__ = __webpack_require__(8138);
 /* harmony import */ var _ObjectSlice_mjs__WEBPACK_IMPORTED_MODULE_1__ = __webpack_require__(38504);
 /* harmony import */ var _KeyValuePair_mjs__WEBPACK_IMPORTED_MODULE_2__ = __webpack_require__(36663);
-/* harmony import */ var _predicates_index_mjs__WEBPACK_IMPORTED_MODULE_3__ = __webpack_require__(18252);
-/* harmony import */ var _predicates_index_mjs__WEBPACK_IMPORTED_MODULE_4__ = __webpack_require__(25162);
-/* harmony import */ var _elements_SourceMap_mjs__WEBPACK_IMPORTED_MODULE_5__ = __webpack_require__(25810);
-/* harmony import */ var _errors_DeepCloneError_mjs__WEBPACK_IMPORTED_MODULE_6__ = __webpack_require__(95018);
-/* harmony import */ var _errors_ShallowCloneError_mjs__WEBPACK_IMPORTED_MODULE_7__ = __webpack_require__(3686);
-/* harmony import */ var _errors_CloneError_mjs__WEBPACK_IMPORTED_MODULE_8__ = __webpack_require__(3772);
+/* harmony import */ var _Metadata_mjs__WEBPACK_IMPORTED_MODULE_3__ = __webpack_require__(51844);
+/* harmony import */ var _predicates_index_mjs__WEBPACK_IMPORTED_MODULE_4__ = __webpack_require__(18252);
+/* harmony import */ var _predicates_index_mjs__WEBPACK_IMPORTED_MODULE_5__ = __webpack_require__(25162);
+/* harmony import */ var _elements_SourceMap_mjs__WEBPACK_IMPORTED_MODULE_6__ = __webpack_require__(25810);
+/* harmony import */ var _errors_DeepCloneError_mjs__WEBPACK_IMPORTED_MODULE_7__ = __webpack_require__(95018);
+/* harmony import */ var _errors_ShallowCloneError_mjs__WEBPACK_IMPORTED_MODULE_8__ = __webpack_require__(3686);
+/* harmony import */ var _errors_CloneError_mjs__WEBPACK_IMPORTED_MODULE_9__ = __webpack_require__(3772);
+
 
 
 
@@ -31866,7 +31868,7 @@ const cloneDeepElement = (element, options) => {
   } = element;
   if (Array.isArray(content)) {
     copy.content = content.map(el => cloneDeepElement(el, passThroughOptions));
-  } else if ((0,_predicates_index_mjs__WEBPACK_IMPORTED_MODULE_4__.isElement)(content)) {
+  } else if ((0,_predicates_index_mjs__WEBPACK_IMPORTED_MODULE_5__.isElement)(content)) {
     copy.content = cloneDeepElement(content, passThroughOptions);
   } else if (content instanceof _KeyValuePair_mjs__WEBPACK_IMPORTED_MODULE_2__["default"]) {
     copy.content = cloneDeepKeyValuePair(content, passThroughOptions);
@@ -31914,7 +31916,7 @@ const cloneDeepObjectSlice = (slice, options) => {
 };
 
 /**
- * Creates a deep clone of an ApiDOM Element, KeyValuePair, or ObjectSlice.
+ * Creates a deep clone of an ApiDOM Element, KeyValuePair, ObjectSlice, or Metadata.
  * Handles cycles by memoizing visited objects.
  * @public
  */
@@ -31925,10 +31927,13 @@ const cloneDeep = (value, options = {}) => {
   if (value instanceof _ObjectSlice_mjs__WEBPACK_IMPORTED_MODULE_1__["default"]) {
     return cloneDeepObjectSlice(value, options);
   }
-  if ((0,_predicates_index_mjs__WEBPACK_IMPORTED_MODULE_4__.isElement)(value)) {
+  if (value instanceof _Metadata_mjs__WEBPACK_IMPORTED_MODULE_3__["default"]) {
+    return value.cloneDeep();
+  }
+  if ((0,_predicates_index_mjs__WEBPACK_IMPORTED_MODULE_5__.isElement)(value)) {
     return cloneDeepElement(value, options);
   }
-  throw new _errors_DeepCloneError_mjs__WEBPACK_IMPORTED_MODULE_6__["default"]("Value provided to cloneDeep function couldn't be cloned", {
+  throw new _errors_DeepCloneError_mjs__WEBPACK_IMPORTED_MODULE_7__["default"]("Value provided to cloneDeep function couldn't be cloned", {
     value
   });
 };
@@ -31955,21 +31960,21 @@ const cloneShallowElement = element => {
   const copy = new Ctor();
   copy.element = element.element;
   if (!element.isMetaEmpty) {
-    copy.meta = element.meta.cloneDeep();
+    copy.meta = cloneDeep(element.meta);
   }
   if (!element.isAttributesEmpty) {
     copy.attributes = cloneDeep(element.attributes);
   }
-  if ((0,_predicates_index_mjs__WEBPACK_IMPORTED_MODULE_3__.hasElementSourceMap)(element)) {
-    _elements_SourceMap_mjs__WEBPACK_IMPORTED_MODULE_5__["default"].transfer(element, copy);
+  if ((0,_predicates_index_mjs__WEBPACK_IMPORTED_MODULE_4__.hasElementSourceMap)(element)) {
+    _elements_SourceMap_mjs__WEBPACK_IMPORTED_MODULE_6__["default"].transfer(element, copy);
   }
-  if ((0,_predicates_index_mjs__WEBPACK_IMPORTED_MODULE_3__.hasElementStyle)(element)) {
+  if ((0,_predicates_index_mjs__WEBPACK_IMPORTED_MODULE_4__.hasElementStyle)(element)) {
     copy.style = (0,ramda__WEBPACK_IMPORTED_MODULE_0__["default"])(element.style);
   }
   const {
     content
   } = element;
-  if ((0,_predicates_index_mjs__WEBPACK_IMPORTED_MODULE_4__.isElement)(content)) {
+  if ((0,_predicates_index_mjs__WEBPACK_IMPORTED_MODULE_5__.isElement)(content)) {
     copy.content = cloneShallowElement(content);
   } else if (Array.isArray(content)) {
     copy.content = [...content];
@@ -31982,7 +31987,7 @@ const cloneShallowElement = element => {
 };
 
 /**
- * Creates a shallow clone of an ApiDOM Element, KeyValuePair, or ObjectSlice.
+ * Creates a shallow clone of an ApiDOM Element, KeyValuePair, ObjectSlice, or Metadata.
  * The element itself is cloned, but content references are shared.
  * Meta and attributes are deep cloned to preserve semantic information.
  * @public
@@ -31994,10 +31999,13 @@ const cloneShallow = value => {
   if (value instanceof _ObjectSlice_mjs__WEBPACK_IMPORTED_MODULE_1__["default"]) {
     return cloneShallowObjectSlice(value);
   }
-  if ((0,_predicates_index_mjs__WEBPACK_IMPORTED_MODULE_4__.isElement)(value)) {
+  if (value instanceof _Metadata_mjs__WEBPACK_IMPORTED_MODULE_3__["default"]) {
+    return value.cloneShallow();
+  }
+  if ((0,_predicates_index_mjs__WEBPACK_IMPORTED_MODULE_5__.isElement)(value)) {
     return cloneShallowElement(value);
   }
-  throw new _errors_ShallowCloneError_mjs__WEBPACK_IMPORTED_MODULE_7__["default"]("Value provided to cloneShallow function couldn't be cloned", {
+  throw new _errors_ShallowCloneError_mjs__WEBPACK_IMPORTED_MODULE_8__["default"]("Value provided to cloneShallow function couldn't be cloned", {
     value
   });
 };
@@ -35422,7 +35430,7 @@ class SpecificationVisitor extends _Visitor_mjs__WEBPACK_IMPORTED_MODULE_6__["de
     if (visitor instanceof _FallbackVisitor_mjs__WEBPACK_IMPORTED_MODULE_7__["default"] && visitor?.constructor === _FallbackVisitor_mjs__WEBPACK_IMPORTED_MODULE_7__["default"]) {
       return this.consume ? element : (0,_speclynx_apidom_datamodel__WEBPACK_IMPORTED_MODULE_4__.cloneDeep)(element);
     }
-    (0,_speclynx_apidom_traverse__WEBPACK_IMPORTED_MODULE_5__.traverse)(element, visitor, options);
+    ;(0,_speclynx_apidom_traverse__WEBPACK_IMPORTED_MODULE_5__.traverse)(element, visitor, options);
     return visitor.element;
   }
 }
@@ -35464,7 +35472,7 @@ class Visitor {
     if (!from.isMetaEmpty && !to.isMetaEmpty) {
       to.meta = to.meta.merge(from.meta);
     } else if (!from.isMetaEmpty) {
-      to.meta = from.meta.cloneDeep();
+      to.meta = (0,_speclynx_apidom_datamodel__WEBPACK_IMPORTED_MODULE_1__.cloneDeep)(from.meta);
     }
     if (!from.isAttributesEmpty && !to.isAttributesEmpty) {
       to.attributes = (0,_speclynx_apidom_core__WEBPACK_IMPORTED_MODULE_0__["default"])(to.attributes, from.attributes);
@@ -40067,7 +40075,7 @@ class SpecificationVisitor extends _Visitor_mjs__WEBPACK_IMPORTED_MODULE_6__["de
     if (visitor instanceof _FallbackVisitor_mjs__WEBPACK_IMPORTED_MODULE_7__["default"] && visitor?.constructor === _FallbackVisitor_mjs__WEBPACK_IMPORTED_MODULE_7__["default"]) {
       return this.consume ? element : (0,_speclynx_apidom_datamodel__WEBPACK_IMPORTED_MODULE_4__.cloneDeep)(element);
     }
-    (0,_speclynx_apidom_traverse__WEBPACK_IMPORTED_MODULE_5__.traverse)(element, visitor);
+    ;(0,_speclynx_apidom_traverse__WEBPACK_IMPORTED_MODULE_5__.traverse)(element, visitor);
     return visitor.element;
   }
 }
@@ -40109,7 +40117,7 @@ class Visitor {
     if (!from.isMetaEmpty && !to.isMetaEmpty) {
       to.meta = to.meta.merge(from.meta);
     } else if (!from.isMetaEmpty) {
-      to.meta = from.meta.cloneDeep();
+      to.meta = (0,_speclynx_apidom_datamodel__WEBPACK_IMPORTED_MODULE_1__.cloneDeep)(from.meta);
     }
     if (!from.isAttributesEmpty && !to.isAttributesEmpty) {
       to.attributes = (0,_speclynx_apidom_core__WEBPACK_IMPORTED_MODULE_0__["default"])(to.attributes, from.attributes);
@@ -40502,6 +40510,7 @@ class ConsumesVisitor extends _FallbackVisitor_mjs__WEBPACK_IMPORTED_MODULE_2__[
   ArrayElement(path) {
     const arrayElement = path.node;
     this.element = this.element.concat((0,_speclynx_apidom_datamodel__WEBPACK_IMPORTED_MODULE_0__.cloneDeep)(arrayElement));
+    this.copyMetaAndAttributes(arrayElement, this.element);
     path.stop();
   }
 }
@@ -40559,6 +40568,7 @@ class ProducesVisitor extends _FallbackVisitor_mjs__WEBPACK_IMPORTED_MODULE_2__[
   ArrayElement(path) {
     const arrayElement = path.node;
     this.element = this.element.concat((0,_speclynx_apidom_datamodel__WEBPACK_IMPORTED_MODULE_0__.cloneDeep)(arrayElement));
+    this.copyMetaAndAttributes(arrayElement, this.element);
     path.stop();
   }
 }
@@ -40592,6 +40602,7 @@ class SchemesVisitor extends _FallbackVisitor_mjs__WEBPACK_IMPORTED_MODULE_2__["
   ArrayElement(path) {
     const arrayElement = path.node;
     this.element = this.element.concat((0,_speclynx_apidom_datamodel__WEBPACK_IMPORTED_MODULE_0__.cloneDeep)(arrayElement));
+    this.copyMetaAndAttributes(arrayElement, this.element);
     path.stop();
   }
 }
@@ -41160,6 +41171,7 @@ class ConsumesVisitor extends _FallbackVisitor_mjs__WEBPACK_IMPORTED_MODULE_2__[
   ArrayElement(path) {
     const arrayElement = path.node;
     this.element = this.element.concat((0,_speclynx_apidom_datamodel__WEBPACK_IMPORTED_MODULE_0__.cloneDeep)(arrayElement));
+    this.copyMetaAndAttributes(arrayElement, this.element);
     path.stop();
   }
 }
@@ -41236,6 +41248,7 @@ class ProducesVisitor extends _FallbackVisitor_mjs__WEBPACK_IMPORTED_MODULE_2__[
   ArrayElement(path) {
     const arrayElement = path.node;
     this.element = this.element.concat((0,_speclynx_apidom_datamodel__WEBPACK_IMPORTED_MODULE_0__.cloneDeep)(arrayElement));
+    this.copyMetaAndAttributes(arrayElement, this.element);
     path.stop();
   }
 }
@@ -41269,6 +41282,7 @@ class SchemesVisitor extends _FallbackVisitor_mjs__WEBPACK_IMPORTED_MODULE_2__["
   ArrayElement(path) {
     const arrayElement = path.node;
     this.element = this.element.concat((0,_speclynx_apidom_datamodel__WEBPACK_IMPORTED_MODULE_0__.cloneDeep)(arrayElement));
+    this.copyMetaAndAttributes(arrayElement, this.element);
     path.stop();
   }
 }
@@ -41338,6 +41352,7 @@ class TagsVisitor extends _FallbackVisitor_mjs__WEBPACK_IMPORTED_MODULE_2__["def
   ArrayElement(path) {
     const arrayElement = path.node;
     this.element = this.element.concat((0,_speclynx_apidom_datamodel__WEBPACK_IMPORTED_MODULE_0__.cloneDeep)(arrayElement));
+    this.copyMetaAndAttributes(arrayElement, this.element);
     path.stop();
   }
 }
@@ -42494,8 +42509,11 @@ const processChildren = (cursor, ctx, transformerMap) => {
   return results;
 };
 
-// strip leading '# ' (or bare '#') from comment text, keeping only the content
-const stripCommentHash = text => text.split('\n').map(line => line.replace(/^#\s?/, '')).join('\n');
+// strip leading '#' from each line of comment text; the text after '#' is kept
+// verbatim (including leading whitespace) so serializers can round-trip it exactly;
+// a bare '#' becomes a single space — the yaml library's encoding for an empty
+// comment, which its stringifier turns back into '#' (plain '' would be dropped)
+const stripCommentHash = text => text.split('\n').map(line => line === '#' ? ' ' : line.replace(/^#/, '')).join('\n');
 
 // find the first YamlNode in a TransformResult (which may be an array from block_node)
 const findYamlNode = result => {
@@ -42538,7 +42556,10 @@ const processKeyValuePairChildren = (cursor, ctx, transformerMap) => {
         if (seenValue) {
           commentsAfterValue.push(commentText);
         } else if (seenKey) {
-          commentsBetweenKeyValue.push(commentText);
+          commentsBetweenKeyValue.push({
+            text: commentText,
+            startLine: info.startPosition.row
+          });
         }
         continue;
       }
@@ -42567,6 +42588,35 @@ const processKeyValuePairChildren = (cursor, ctx, transformerMap) => {
     commentsAfterValue
   };
 };
+
+// attach comments collected inside a pair: comments on the key's own line belong
+// after the key (`key: # comment`), the rest before the value node; comments
+// found after the value become the value's trailing comment
+const attachPairComments = ({
+  key,
+  value,
+  commentsBetweenKeyValue,
+  commentsAfterValue
+}) => {
+  if (commentsBetweenKeyValue.length > 0) {
+    const keyNode = findYamlNode(key);
+    const valueNode = findYamlNode(value);
+    const onKeyLine = commentsBetweenKeyValue.filter(comment => keyNode !== null && comment.startLine === keyNode.endLine);
+    const onOwnLine = commentsBetweenKeyValue.filter(comment => !onKeyLine.includes(comment));
+    if (onKeyLine.length > 0 && keyNode) {
+      keyNode.comment = onKeyLine.map(comment => comment.text).join('\n');
+    }
+    if (onOwnLine.length > 0 && valueNode) {
+      valueNode.commentBefore = onOwnLine.map(comment => comment.text).join('\n');
+    }
+  }
+  if (commentsAfterValue.length > 0) {
+    const valueNode = findYamlNode(value);
+    if (valueNode) {
+      valueNode.comment = commentsAfterValue.join('\n');
+    }
+  }
+};
 const transform = (cursor, ctx, transformerMap, siblings = {}) => {
   const info = getCursorInfo(cursor);
 
@@ -42738,13 +42788,12 @@ const createTransformers = transformerMap => ({
   },
   block_mapping_pair(cursor, ctx) {
     const info = getCursorInfo(cursor);
+    const pairResult = processKeyValuePairChildren(cursor, ctx, transformerMap);
     const {
       key,
       value,
-      errors,
-      commentsBetweenKeyValue,
-      commentsAfterValue
-    } = processKeyValuePairChildren(cursor, ctx, transformerMap);
+      errors
+    } = pairResult;
     const children = [];
 
     // Handle empty key
@@ -42790,21 +42839,7 @@ const createTransformers = transformerMap => ({
     } else {
       children.push(value);
     }
-
-    // attach comments found between key and value to the value node
-    if (commentsBetweenKeyValue.length > 0) {
-      const valueNode = findYamlNode(value);
-      if (valueNode) {
-        valueNode.commentBefore = commentsBetweenKeyValue.join('\n');
-      }
-    }
-    // attach comments found after value to the value node
-    if (commentsAfterValue.length > 0) {
-      const valueNode = findYamlNode(value);
-      if (valueNode) {
-        valueNode.comment = commentsAfterValue.join('\n');
-      }
-    }
+    attachPairComments(pairResult);
     children.push(...errors);
     return new _ast_nodes_YamlKeyValuePair_mjs__WEBPACK_IMPORTED_MODULE_9__["default"]({
       children: children.flat().filter(c => c !== null),
@@ -42832,13 +42867,12 @@ const createTransformers = transformerMap => ({
   },
   flow_pair(cursor, ctx) {
     const info = getCursorInfo(cursor);
+    const pairResult = processKeyValuePairChildren(cursor, ctx, transformerMap);
     const {
       key,
       value,
-      errors,
-      commentsBetweenKeyValue,
-      commentsAfterValue
-    } = processKeyValuePairChildren(cursor, ctx, transformerMap);
+      errors
+    } = pairResult;
     const children = [];
 
     // Handle empty key
@@ -42884,21 +42918,7 @@ const createTransformers = transformerMap => ({
     } else {
       children.push(value);
     }
-
-    // attach comments found between key and value to the value node
-    if (commentsBetweenKeyValue.length > 0) {
-      const valueNode = findYamlNode(value);
-      if (valueNode) {
-        valueNode.commentBefore = commentsBetweenKeyValue.join('\n');
-      }
-    }
-    // attach comments found after value to the value node
-    if (commentsAfterValue.length > 0) {
-      const valueNode = findYamlNode(value);
-      if (valueNode) {
-        valueNode.comment = commentsAfterValue.join('\n');
-      }
-    }
+    attachPairComments(pairResult);
     children.push(...errors);
     return new _ast_nodes_YamlKeyValuePair_mjs__WEBPACK_IMPORTED_MODULE_9__["default"]({
       children: children.flat().filter(c => c !== null),
@@ -43109,7 +43129,9 @@ __webpack_require__.r(__webpack_exports__);
 /* harmony import */ var _speclynx_apidom_datamodel__WEBPACK_IMPORTED_MODULE_6__ = __webpack_require__(40094);
 /* harmony import */ var _speclynx_apidom_datamodel__WEBPACK_IMPORTED_MODULE_7__ = __webpack_require__(4823);
 /* harmony import */ var _speclynx_apidom_datamodel__WEBPACK_IMPORTED_MODULE_8__ = __webpack_require__(25810);
-/* harmony import */ var _ast_nodes_YamlStyle_mjs__WEBPACK_IMPORTED_MODULE_9__ = __webpack_require__(21544);
+/* harmony import */ var _ast_nodes_predicates_mjs__WEBPACK_IMPORTED_MODULE_9__ = __webpack_require__(90594);
+/* harmony import */ var _ast_nodes_YamlStyle_mjs__WEBPACK_IMPORTED_MODULE_10__ = __webpack_require__(21544);
+
 
  // Transform context passed through transformation
 // Node with type property and flat position properties
@@ -43136,14 +43158,17 @@ const findFirst = (node, path) => {
 // detect indent from first nested block mapping (stream > document > mapping > keyValuePair > mapping)
 const detectIndent = node => {
   const nested = findFirst(node, ['document', 'mapping', 'keyValuePair', 'mapping']);
-  if (nested?.styleGroup === _ast_nodes_YamlStyle_mjs__WEBPACK_IMPORTED_MODULE_9__.YamlStyleGroup.Block && typeof nested.startCharacter === 'number' && nested.startCharacter > 0) {
+  if (nested?.styleGroup === _ast_nodes_YamlStyle_mjs__WEBPACK_IMPORTED_MODULE_10__.YamlStyleGroup.Block && typeof nested.startCharacter === 'number' && nested.startCharacter > 0) {
     return nested.startCharacter;
   }
   return 2;
 };
 
-// strip leading '#' from each line of comment text; yaml library adds '#' during stringification
-const stripCommentHash = text => text.split('\n').map(line => line.replace(/^#/, '')).join('\n');
+// strip leading '#' from each line of comment text; yaml library adds '#' during
+// stringification; a bare '#' becomes a single space — the yaml library's encoding
+// for an empty comment, which its stringifier turns back into '#' (plain '' would
+// be dropped)
+const stripCommentHash = text => text.split('\n').map(line => line === '#' ? ' ' : line.replace(/^#/, '')).join('\n');
 
 // collect comment texts from raw AST children, indexed by position relative to non-comment siblings
 
@@ -43213,6 +43238,7 @@ const setYamlStyleProp = (element, key, value) => {
   yaml[key] = value;
   element.style.yaml = yaml;
 };
+const getYamlStyleProp = (element, key) => element.style?.yaml?.[key];
 
 // apply collected comments to transformed ApiDOM elements
 const applyComments = (elements, comments) => {
@@ -43343,6 +43369,17 @@ const transformChildren = (children, ctx) => {
   return results;
 };
 
+// stream comments that precede the first document, joined; null when there are none
+// (stream children are in source order, so everything before the document node qualifies)
+const collectPreDocumentComments = node => {
+  const texts = [];
+  for (const child of node.children) {
+    if ((0,_ast_nodes_predicates_mjs__WEBPACK_IMPORTED_MODULE_9__.isDocument)(child)) break;
+    if ((0,_ast_nodes_predicates_mjs__WEBPACK_IMPORTED_MODULE_9__.isComment)(child)) texts.push(stripCommentHash(child.content));
+  }
+  return texts.length > 0 ? texts.join('\n') : null;
+};
+
 // Stream: Wraps transformed children in ParseResultElement
 const transformStream = (node, ctx) => {
   // detect indent from the stream structure (only needed for style preservation)
@@ -43364,6 +43401,16 @@ const transformStream = (node, ctx) => {
   if (elements.length > 0) {
     const resultElement = elements[0];
     resultElement.classes.push('result');
+
+    // stream comments before the first document belong above the result element;
+    // capture them as commentBefore so style round-trips can re-emit them
+    if (ctx.style) {
+      const preDocumentComments = collectPreDocumentComments(node);
+      if (preDocumentComments !== null) {
+        const existing = getYamlStyleProp(resultElement, 'commentBefore');
+        setYamlStyleProp(resultElement, 'commentBefore', typeof existing === 'string' ? `${preDocumentComments}\n${existing}` : preDocumentComments);
+      }
+    }
   }
 
   // Add collected annotations
@@ -43399,7 +43446,7 @@ const transformCollection = (element, node, ctx) => {
   const typedNode = node;
   const children = node.children || [];
   if (ctx.style) {
-    if (ctx.flowCollectionPadding === null && node.styleGroup === _ast_nodes_YamlStyle_mjs__WEBPACK_IMPORTED_MODULE_9__.YamlStyleGroup.Flow) {
+    if (ctx.flowCollectionPadding === null && node.styleGroup === _ast_nodes_YamlStyle_mjs__WEBPACK_IMPORTED_MODULE_10__.YamlStyleGroup.Flow) {
       ctx.flowCollectionPadding = detectFlowPadding(typedNode);
     }
     const comments = collectComments(children, typedNode.startCharacter);
@@ -43465,7 +43512,7 @@ const transformScalar = (node, ctx) => {
   const element = ctx.namespace.toElement(node.content);
 
   // Translate style information about empty nodes
-  if (node.content === '' && node.style === _ast_nodes_YamlStyle_mjs__WEBPACK_IMPORTED_MODULE_9__.YamlStyle.Plain) {
+  if (node.content === '' && node.style === _ast_nodes_YamlStyle_mjs__WEBPACK_IMPORTED_MODULE_10__.YamlStyle.Plain) {
     element.classes.push('yaml-e-node');
     element.classes.push('yaml-e-scalar');
   }
@@ -45681,7 +45728,7 @@ const forEach = (element, options) => {
     callback = options.callback ?? (() => {});
     predicate = options.predicate ?? (() => true);
   }
-  (0,_traversal_mjs__WEBPACK_IMPORTED_MODULE_0__.traverse)(element, {
+  ;(0,_traversal_mjs__WEBPACK_IMPORTED_MODULE_0__.traverse)(element, {
     enter(path) {
       if (predicate(path)) {
         callback(path);