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

package/CHANGELOG.md

@@ -3,6 +3,12 @@
 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)
+
+### Bug Fixes
+
+- **yaml:** make YAML style round-trips byte-perfect (comments, raw numbers) ([#441](https://github.com/speclynx/apidom/issues/441)) ([43dc5b6](https://github.com/speclynx/apidom/commit/43dc5b6a19bfe6268f0ecaedf8f099b1990a363d))
+
 ## [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-yaml-1-2

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

@@ -274,8 +274,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 => {
@@ -318,7 +321,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;
       }
@@ -347,6 +353,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);
 
@@ -518,13 +553,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
@@ -570,21 +604,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_ts__WEBPACK_IMPORTED_MODULE_9__["default"]({
       children: children.flat().filter(c => c !== null),
@@ -612,13 +632,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
@@ -664,21 +683,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_ts__WEBPACK_IMPORTED_MODULE_9__["default"]({
       children: children.flat().filter(c => c !== null),
@@ -889,7 +894,9 @@ __webpack_require__.r(__webpack_exports__);
 /* harmony import */ var _speclynx_apidom_datamodel__WEBPACK_IMPORTED_MODULE_6__ = __webpack_require__(94);
 /* 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__(5810);
-/* harmony import */ var _ast_nodes_YamlStyle_ts__WEBPACK_IMPORTED_MODULE_9__ = __webpack_require__(9276);
+/* harmony import */ var _ast_nodes_predicates_ts__WEBPACK_IMPORTED_MODULE_9__ = __webpack_require__(1228);
+/* harmony import */ var _ast_nodes_YamlStyle_ts__WEBPACK_IMPORTED_MODULE_10__ = __webpack_require__(9276);
+
 
 
 
@@ -920,14 +927,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_ts__WEBPACK_IMPORTED_MODULE_9__.YamlStyleGroup.Block && typeof nested.startCharacter === 'number' && nested.startCharacter > 0) {
+  if (nested?.styleGroup === _ast_nodes_YamlStyle_ts__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
 
@@ -997,6 +1007,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) => {
@@ -1127,6 +1138,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_ts__WEBPACK_IMPORTED_MODULE_9__.isDocument)(child)) break;
+    if ((0,_ast_nodes_predicates_ts__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)
@@ -1148,6 +1170,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
@@ -1183,7 +1215,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_ts__WEBPACK_IMPORTED_MODULE_9__.YamlStyleGroup.Flow) {
+    if (ctx.flowCollectionPadding === null && node.styleGroup === _ast_nodes_YamlStyle_ts__WEBPACK_IMPORTED_MODULE_10__.YamlStyleGroup.Flow) {
       ctx.flowCollectionPadding = detectFlowPadding(typedNode);
     }
     const comments = collectComments(children, typedNode.startCharacter);
@@ -1249,7 +1281,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_ts__WEBPACK_IMPORTED_MODULE_9__.YamlStyle.Plain) {
+  if (node.content === '' && node.style === _ast_nodes_YamlStyle_ts__WEBPACK_IMPORTED_MODULE_10__.YamlStyle.Plain) {
     element.classes.push('yaml-e-node');
     element.classes.push('yaml-e-scalar');
   }
@@ -21972,11 +22004,13 @@ __webpack_require__.r(__webpack_exports__);
 /* harmony import */ var ramda__WEBPACK_IMPORTED_MODULE_0__ = __webpack_require__(8138);
 /* harmony import */ var _ObjectSlice_mjs__WEBPACK_IMPORTED_MODULE_1__ = __webpack_require__(8504);
 /* harmony import */ var _KeyValuePair_mjs__WEBPACK_IMPORTED_MODULE_2__ = __webpack_require__(6663);
-/* harmony import */ var _predicates_index_mjs__WEBPACK_IMPORTED_MODULE_3__ = __webpack_require__(8252);
-/* harmony import */ var _predicates_index_mjs__WEBPACK_IMPORTED_MODULE_4__ = __webpack_require__(5162);
-/* harmony import */ var _elements_SourceMap_mjs__WEBPACK_IMPORTED_MODULE_5__ = __webpack_require__(5810);
-/* harmony import */ var _errors_DeepCloneError_mjs__WEBPACK_IMPORTED_MODULE_6__ = __webpack_require__(5018);
-/* harmony import */ var _errors_ShallowCloneError_mjs__WEBPACK_IMPORTED_MODULE_7__ = __webpack_require__(3686);
+/* harmony import */ var _Metadata_mjs__WEBPACK_IMPORTED_MODULE_3__ = __webpack_require__(1844);
+/* harmony import */ var _predicates_index_mjs__WEBPACK_IMPORTED_MODULE_4__ = __webpack_require__(8252);
+/* harmony import */ var _predicates_index_mjs__WEBPACK_IMPORTED_MODULE_5__ = __webpack_require__(5162);
+/* harmony import */ var _elements_SourceMap_mjs__WEBPACK_IMPORTED_MODULE_6__ = __webpack_require__(5810);
+/* harmony import */ var _errors_DeepCloneError_mjs__WEBPACK_IMPORTED_MODULE_7__ = __webpack_require__(5018);
+/* harmony import */ var _errors_ShallowCloneError_mjs__WEBPACK_IMPORTED_MODULE_8__ = __webpack_require__(3686);
+
 
 
 
@@ -22010,7 +22044,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);
@@ -22058,7 +22092,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
  */
@@ -22069,10 +22103,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
   });
 };
@@ -22099,21 +22136,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];
@@ -22126,7 +22163,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
@@ -22138,10 +22175,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
   });
 };