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

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/CHANGELOG.md CHANGED
@@ -3,6 +3,10 @@
3
3
  All notable changes to this project will be documented in this file.
4
4
  See [Conventional Commits](https://conventionalcommits.org) for commit guidelines.
5
5
 
6
+ # [5.1.0](https://github.com/speclynx/apidom/compare/v5.0.2...v5.1.0) (2026-08-09)
7
+
8
+ **Note:** Version bump only for package @speclynx/apidom-parser-adapter-overlay-yaml-1
9
+
6
10
  ## [5.0.2](https://github.com/speclynx/apidom/compare/v5.0.1...v5.0.2) (2026-08-04)
7
11
 
8
12
  **Note:** Version bump only for package @speclynx/apidom-parser-adapter-overlay-yaml-1
@@ -1122,7 +1122,7 @@ function _defineProperty(e, r, t) { return (r = _toPropertyKey(r)) in e ? Object
1122
1122
  function _toPropertyKey(t) { var i = _toPrimitive(t, "string"); return "symbol" == typeof i ? i : i + ""; }
1123
1123
  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); }
1124
1124
  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"); }
1125
-
1125
+ ;
1126
1126
 
1127
1127
  var _CompositeEvaluationRealm_brand = /*#__PURE__*/new WeakSet();
1128
1128
  class CompositeEvaluationRealm extends _EvaluationRealm_mjs__WEBPACK_IMPORTED_MODULE_0__["default"] {
@@ -29794,7 +29794,7 @@ __webpack_require__.r(__webpack_exports__);
29794
29794
  * @public
29795
29795
  */
29796
29796
  const emptyElement = element => {
29797
- const meta = !element.isMetaEmpty ? element.meta.cloneDeep() : undefined;
29797
+ const meta = !element.isMetaEmpty ? (0,_speclynx_apidom_datamodel__WEBPACK_IMPORTED_MODULE_1__.cloneDeep)(element.meta) : undefined;
29798
29798
  const attributes = !element.isAttributesEmpty ? (0,_speclynx_apidom_datamodel__WEBPACK_IMPORTED_MODULE_1__.cloneDeep)(element.attributes) : undefined;
29799
29799
 
29800
29800
  // @ts-ignore
@@ -29810,7 +29810,7 @@ const getMergeFunction = (keyElement, options) => {
29810
29810
  };
29811
29811
  const getMetaMergeFunction = options => {
29812
29812
  if (typeof options.customMetaMerge !== 'function') {
29813
- return targetMeta => targetMeta.cloneDeep();
29813
+ return targetMeta => (0,_speclynx_apidom_datamodel__WEBPACK_IMPORTED_MODULE_1__.cloneDeep)(targetMeta);
29814
29814
  }
29815
29815
  return options.customMetaMerge;
29816
29816
  };
@@ -29885,9 +29885,9 @@ const deepmerge = (targetElement, sourceElement, options) => {
29885
29885
  if (!targetElement.isMetaEmpty && !sourceElement.isMetaEmpty) {
29886
29886
  mergedElement.meta = getMetaMergeFunction(mergedOptions)(targetElement.meta, sourceElement.meta);
29887
29887
  } else if (!targetElement.isMetaEmpty) {
29888
- mergedElement.meta = targetElement.meta.cloneDeep();
29888
+ mergedElement.meta = (0,_speclynx_apidom_datamodel__WEBPACK_IMPORTED_MODULE_1__.cloneDeep)(targetElement.meta);
29889
29889
  } else if (!sourceElement.isMetaEmpty) {
29890
- mergedElement.meta = sourceElement.meta.cloneDeep();
29890
+ mergedElement.meta = (0,_speclynx_apidom_datamodel__WEBPACK_IMPORTED_MODULE_1__.cloneDeep)(sourceElement.meta);
29891
29891
  }
29892
29892
  if (!targetElement.isAttributesEmpty && !sourceElement.isAttributesEmpty) {
29893
29893
  mergedElement.attributes = getAttributesMergeFunction(mergedOptions)(targetElement.attributes, sourceElement.attributes);
@@ -30865,19 +30865,21 @@ class ShallowCloneError extends _CloneError_mjs__WEBPACK_IMPORTED_MODULE_0__["de
30865
30865
  "use strict";
30866
30866
  __webpack_require__.r(__webpack_exports__);
30867
30867
  /* harmony export */ __webpack_require__.d(__webpack_exports__, {
30868
- /* harmony export */ CloneError: () => (/* reexport safe */ _errors_CloneError_mjs__WEBPACK_IMPORTED_MODULE_8__["default"]),
30869
- /* harmony export */ DeepCloneError: () => (/* reexport safe */ _errors_DeepCloneError_mjs__WEBPACK_IMPORTED_MODULE_6__["default"]),
30870
- /* harmony export */ ShallowCloneError: () => (/* reexport safe */ _errors_ShallowCloneError_mjs__WEBPACK_IMPORTED_MODULE_7__["default"])
30868
+ /* harmony export */ CloneError: () => (/* reexport safe */ _errors_CloneError_mjs__WEBPACK_IMPORTED_MODULE_9__["default"]),
30869
+ /* harmony export */ DeepCloneError: () => (/* reexport safe */ _errors_DeepCloneError_mjs__WEBPACK_IMPORTED_MODULE_7__["default"]),
30870
+ /* harmony export */ ShallowCloneError: () => (/* reexport safe */ _errors_ShallowCloneError_mjs__WEBPACK_IMPORTED_MODULE_8__["default"])
30871
30871
  /* harmony export */ });
30872
30872
  /* harmony import */ var ramda__WEBPACK_IMPORTED_MODULE_0__ = __webpack_require__(8138);
30873
30873
  /* harmony import */ var _ObjectSlice_mjs__WEBPACK_IMPORTED_MODULE_1__ = __webpack_require__(8504);
30874
30874
  /* harmony import */ var _KeyValuePair_mjs__WEBPACK_IMPORTED_MODULE_2__ = __webpack_require__(6663);
30875
- /* harmony import */ var _predicates_index_mjs__WEBPACK_IMPORTED_MODULE_3__ = __webpack_require__(8252);
30876
- /* harmony import */ var _predicates_index_mjs__WEBPACK_IMPORTED_MODULE_4__ = __webpack_require__(5162);
30877
- /* harmony import */ var _elements_SourceMap_mjs__WEBPACK_IMPORTED_MODULE_5__ = __webpack_require__(5810);
30878
- /* harmony import */ var _errors_DeepCloneError_mjs__WEBPACK_IMPORTED_MODULE_6__ = __webpack_require__(5018);
30879
- /* harmony import */ var _errors_ShallowCloneError_mjs__WEBPACK_IMPORTED_MODULE_7__ = __webpack_require__(3686);
30880
- /* harmony import */ var _errors_CloneError_mjs__WEBPACK_IMPORTED_MODULE_8__ = __webpack_require__(3772);
30875
+ /* harmony import */ var _Metadata_mjs__WEBPACK_IMPORTED_MODULE_3__ = __webpack_require__(1844);
30876
+ /* harmony import */ var _predicates_index_mjs__WEBPACK_IMPORTED_MODULE_4__ = __webpack_require__(8252);
30877
+ /* harmony import */ var _predicates_index_mjs__WEBPACK_IMPORTED_MODULE_5__ = __webpack_require__(5162);
30878
+ /* harmony import */ var _elements_SourceMap_mjs__WEBPACK_IMPORTED_MODULE_6__ = __webpack_require__(5810);
30879
+ /* harmony import */ var _errors_DeepCloneError_mjs__WEBPACK_IMPORTED_MODULE_7__ = __webpack_require__(5018);
30880
+ /* harmony import */ var _errors_ShallowCloneError_mjs__WEBPACK_IMPORTED_MODULE_8__ = __webpack_require__(3686);
30881
+ /* harmony import */ var _errors_CloneError_mjs__WEBPACK_IMPORTED_MODULE_9__ = __webpack_require__(3772);
30882
+
30881
30883
 
30882
30884
 
30883
30885
 
@@ -30911,7 +30913,7 @@ const cloneDeepElement = (element, options) => {
30911
30913
  } = element;
30912
30914
  if (Array.isArray(content)) {
30913
30915
  copy.content = content.map(el => cloneDeepElement(el, passThroughOptions));
30914
- } else if ((0,_predicates_index_mjs__WEBPACK_IMPORTED_MODULE_4__.isElement)(content)) {
30916
+ } else if ((0,_predicates_index_mjs__WEBPACK_IMPORTED_MODULE_5__.isElement)(content)) {
30915
30917
  copy.content = cloneDeepElement(content, passThroughOptions);
30916
30918
  } else if (content instanceof _KeyValuePair_mjs__WEBPACK_IMPORTED_MODULE_2__["default"]) {
30917
30919
  copy.content = cloneDeepKeyValuePair(content, passThroughOptions);
@@ -30959,7 +30961,7 @@ const cloneDeepObjectSlice = (slice, options) => {
30959
30961
  };
30960
30962
 
30961
30963
  /**
30962
- * Creates a deep clone of an ApiDOM Element, KeyValuePair, or ObjectSlice.
30964
+ * Creates a deep clone of an ApiDOM Element, KeyValuePair, ObjectSlice, or Metadata.
30963
30965
  * Handles cycles by memoizing visited objects.
30964
30966
  * @public
30965
30967
  */
@@ -30970,10 +30972,13 @@ const cloneDeep = (value, options = {}) => {
30970
30972
  if (value instanceof _ObjectSlice_mjs__WEBPACK_IMPORTED_MODULE_1__["default"]) {
30971
30973
  return cloneDeepObjectSlice(value, options);
30972
30974
  }
30973
- if ((0,_predicates_index_mjs__WEBPACK_IMPORTED_MODULE_4__.isElement)(value)) {
30975
+ if (value instanceof _Metadata_mjs__WEBPACK_IMPORTED_MODULE_3__["default"]) {
30976
+ return value.cloneDeep();
30977
+ }
30978
+ if ((0,_predicates_index_mjs__WEBPACK_IMPORTED_MODULE_5__.isElement)(value)) {
30974
30979
  return cloneDeepElement(value, options);
30975
30980
  }
30976
- throw new _errors_DeepCloneError_mjs__WEBPACK_IMPORTED_MODULE_6__["default"]("Value provided to cloneDeep function couldn't be cloned", {
30981
+ throw new _errors_DeepCloneError_mjs__WEBPACK_IMPORTED_MODULE_7__["default"]("Value provided to cloneDeep function couldn't be cloned", {
30977
30982
  value
30978
30983
  });
30979
30984
  };
@@ -31000,21 +31005,21 @@ const cloneShallowElement = element => {
31000
31005
  const copy = new Ctor();
31001
31006
  copy.element = element.element;
31002
31007
  if (!element.isMetaEmpty) {
31003
- copy.meta = element.meta.cloneDeep();
31008
+ copy.meta = cloneDeep(element.meta);
31004
31009
  }
31005
31010
  if (!element.isAttributesEmpty) {
31006
31011
  copy.attributes = cloneDeep(element.attributes);
31007
31012
  }
31008
- if ((0,_predicates_index_mjs__WEBPACK_IMPORTED_MODULE_3__.hasElementSourceMap)(element)) {
31009
- _elements_SourceMap_mjs__WEBPACK_IMPORTED_MODULE_5__["default"].transfer(element, copy);
31013
+ if ((0,_predicates_index_mjs__WEBPACK_IMPORTED_MODULE_4__.hasElementSourceMap)(element)) {
31014
+ _elements_SourceMap_mjs__WEBPACK_IMPORTED_MODULE_6__["default"].transfer(element, copy);
31010
31015
  }
31011
- if ((0,_predicates_index_mjs__WEBPACK_IMPORTED_MODULE_3__.hasElementStyle)(element)) {
31016
+ if ((0,_predicates_index_mjs__WEBPACK_IMPORTED_MODULE_4__.hasElementStyle)(element)) {
31012
31017
  copy.style = (0,ramda__WEBPACK_IMPORTED_MODULE_0__["default"])(element.style);
31013
31018
  }
31014
31019
  const {
31015
31020
  content
31016
31021
  } = element;
31017
- if ((0,_predicates_index_mjs__WEBPACK_IMPORTED_MODULE_4__.isElement)(content)) {
31022
+ if ((0,_predicates_index_mjs__WEBPACK_IMPORTED_MODULE_5__.isElement)(content)) {
31018
31023
  copy.content = cloneShallowElement(content);
31019
31024
  } else if (Array.isArray(content)) {
31020
31025
  copy.content = [...content];
@@ -31027,7 +31032,7 @@ const cloneShallowElement = element => {
31027
31032
  };
31028
31033
 
31029
31034
  /**
31030
- * Creates a shallow clone of an ApiDOM Element, KeyValuePair, or ObjectSlice.
31035
+ * Creates a shallow clone of an ApiDOM Element, KeyValuePair, ObjectSlice, or Metadata.
31031
31036
  * The element itself is cloned, but content references are shared.
31032
31037
  * Meta and attributes are deep cloned to preserve semantic information.
31033
31038
  * @public
@@ -31039,10 +31044,13 @@ const cloneShallow = value => {
31039
31044
  if (value instanceof _ObjectSlice_mjs__WEBPACK_IMPORTED_MODULE_1__["default"]) {
31040
31045
  return cloneShallowObjectSlice(value);
31041
31046
  }
31042
- if ((0,_predicates_index_mjs__WEBPACK_IMPORTED_MODULE_4__.isElement)(value)) {
31047
+ if (value instanceof _Metadata_mjs__WEBPACK_IMPORTED_MODULE_3__["default"]) {
31048
+ return value.cloneShallow();
31049
+ }
31050
+ if ((0,_predicates_index_mjs__WEBPACK_IMPORTED_MODULE_5__.isElement)(value)) {
31043
31051
  return cloneShallowElement(value);
31044
31052
  }
31045
- throw new _errors_ShallowCloneError_mjs__WEBPACK_IMPORTED_MODULE_7__["default"]("Value provided to cloneShallow function couldn't be cloned", {
31053
+ throw new _errors_ShallowCloneError_mjs__WEBPACK_IMPORTED_MODULE_8__["default"]("Value provided to cloneShallow function couldn't be cloned", {
31046
31054
  value
31047
31055
  });
31048
31056
  };
@@ -34292,7 +34300,7 @@ class SpecificationVisitor extends _Visitor_mjs__WEBPACK_IMPORTED_MODULE_6__["de
34292
34300
  if (visitor instanceof _FallbackVisitor_mjs__WEBPACK_IMPORTED_MODULE_7__["default"] && visitor?.constructor === _FallbackVisitor_mjs__WEBPACK_IMPORTED_MODULE_7__["default"]) {
34293
34301
  return this.consume ? element : (0,_speclynx_apidom_datamodel__WEBPACK_IMPORTED_MODULE_4__.cloneDeep)(element);
34294
34302
  }
34295
- (0,_speclynx_apidom_traverse__WEBPACK_IMPORTED_MODULE_5__.traverse)(element, visitor, options);
34303
+ ;(0,_speclynx_apidom_traverse__WEBPACK_IMPORTED_MODULE_5__.traverse)(element, visitor, options);
34296
34304
  return visitor.element;
34297
34305
  }
34298
34306
  }
@@ -34334,7 +34342,7 @@ class Visitor {
34334
34342
  if (!from.isMetaEmpty && !to.isMetaEmpty) {
34335
34343
  to.meta = to.meta.merge(from.meta);
34336
34344
  } else if (!from.isMetaEmpty) {
34337
- to.meta = from.meta.cloneDeep();
34345
+ to.meta = (0,_speclynx_apidom_datamodel__WEBPACK_IMPORTED_MODULE_1__.cloneDeep)(from.meta);
34338
34346
  }
34339
34347
  if (!from.isAttributesEmpty && !to.isAttributesEmpty) {
34340
34348
  to.attributes = (0,_speclynx_apidom_core__WEBPACK_IMPORTED_MODULE_0__["default"])(to.attributes, from.attributes);
@@ -34989,8 +34997,11 @@ const processChildren = (cursor, ctx, transformerMap) => {
34989
34997
  return results;
34990
34998
  };
34991
34999
 
34992
- // strip leading '# ' (or bare '#') from comment text, keeping only the content
34993
- const stripCommentHash = text => text.split('\n').map(line => line.replace(/^#\s?/, '')).join('\n');
35000
+ // strip leading '#' from each line of comment text; the text after '#' is kept
35001
+ // verbatim (including leading whitespace) so serializers can round-trip it exactly;
35002
+ // a bare '#' becomes a single space — the yaml library's encoding for an empty
35003
+ // comment, which its stringifier turns back into '#' (plain '' would be dropped)
35004
+ const stripCommentHash = text => text.split('\n').map(line => line === '#' ? ' ' : line.replace(/^#/, '')).join('\n');
34994
35005
 
34995
35006
  // find the first YamlNode in a TransformResult (which may be an array from block_node)
34996
35007
  const findYamlNode = result => {
@@ -35033,7 +35044,10 @@ const processKeyValuePairChildren = (cursor, ctx, transformerMap) => {
35033
35044
  if (seenValue) {
35034
35045
  commentsAfterValue.push(commentText);
35035
35046
  } else if (seenKey) {
35036
- commentsBetweenKeyValue.push(commentText);
35047
+ commentsBetweenKeyValue.push({
35048
+ text: commentText,
35049
+ startLine: info.startPosition.row
35050
+ });
35037
35051
  }
35038
35052
  continue;
35039
35053
  }
@@ -35062,6 +35076,35 @@ const processKeyValuePairChildren = (cursor, ctx, transformerMap) => {
35062
35076
  commentsAfterValue
35063
35077
  };
35064
35078
  };
35079
+
35080
+ // attach comments collected inside a pair: comments on the key's own line belong
35081
+ // after the key (`key: # comment`), the rest before the value node; comments
35082
+ // found after the value become the value's trailing comment
35083
+ const attachPairComments = ({
35084
+ key,
35085
+ value,
35086
+ commentsBetweenKeyValue,
35087
+ commentsAfterValue
35088
+ }) => {
35089
+ if (commentsBetweenKeyValue.length > 0) {
35090
+ const keyNode = findYamlNode(key);
35091
+ const valueNode = findYamlNode(value);
35092
+ const onKeyLine = commentsBetweenKeyValue.filter(comment => keyNode !== null && comment.startLine === keyNode.endLine);
35093
+ const onOwnLine = commentsBetweenKeyValue.filter(comment => !onKeyLine.includes(comment));
35094
+ if (onKeyLine.length > 0 && keyNode) {
35095
+ keyNode.comment = onKeyLine.map(comment => comment.text).join('\n');
35096
+ }
35097
+ if (onOwnLine.length > 0 && valueNode) {
35098
+ valueNode.commentBefore = onOwnLine.map(comment => comment.text).join('\n');
35099
+ }
35100
+ }
35101
+ if (commentsAfterValue.length > 0) {
35102
+ const valueNode = findYamlNode(value);
35103
+ if (valueNode) {
35104
+ valueNode.comment = commentsAfterValue.join('\n');
35105
+ }
35106
+ }
35107
+ };
35065
35108
  const transform = (cursor, ctx, transformerMap, siblings = {}) => {
35066
35109
  const info = getCursorInfo(cursor);
35067
35110
 
@@ -35233,13 +35276,12 @@ const createTransformers = transformerMap => ({
35233
35276
  },
35234
35277
  block_mapping_pair(cursor, ctx) {
35235
35278
  const info = getCursorInfo(cursor);
35279
+ const pairResult = processKeyValuePairChildren(cursor, ctx, transformerMap);
35236
35280
  const {
35237
35281
  key,
35238
35282
  value,
35239
- errors,
35240
- commentsBetweenKeyValue,
35241
- commentsAfterValue
35242
- } = processKeyValuePairChildren(cursor, ctx, transformerMap);
35283
+ errors
35284
+ } = pairResult;
35243
35285
  const children = [];
35244
35286
 
35245
35287
  // Handle empty key
@@ -35285,21 +35327,7 @@ const createTransformers = transformerMap => ({
35285
35327
  } else {
35286
35328
  children.push(value);
35287
35329
  }
35288
-
35289
- // attach comments found between key and value to the value node
35290
- if (commentsBetweenKeyValue.length > 0) {
35291
- const valueNode = findYamlNode(value);
35292
- if (valueNode) {
35293
- valueNode.commentBefore = commentsBetweenKeyValue.join('\n');
35294
- }
35295
- }
35296
- // attach comments found after value to the value node
35297
- if (commentsAfterValue.length > 0) {
35298
- const valueNode = findYamlNode(value);
35299
- if (valueNode) {
35300
- valueNode.comment = commentsAfterValue.join('\n');
35301
- }
35302
- }
35330
+ attachPairComments(pairResult);
35303
35331
  children.push(...errors);
35304
35332
  return new _ast_nodes_YamlKeyValuePair_mjs__WEBPACK_IMPORTED_MODULE_9__["default"]({
35305
35333
  children: children.flat().filter(c => c !== null),
@@ -35327,13 +35355,12 @@ const createTransformers = transformerMap => ({
35327
35355
  },
35328
35356
  flow_pair(cursor, ctx) {
35329
35357
  const info = getCursorInfo(cursor);
35358
+ const pairResult = processKeyValuePairChildren(cursor, ctx, transformerMap);
35330
35359
  const {
35331
35360
  key,
35332
35361
  value,
35333
- errors,
35334
- commentsBetweenKeyValue,
35335
- commentsAfterValue
35336
- } = processKeyValuePairChildren(cursor, ctx, transformerMap);
35362
+ errors
35363
+ } = pairResult;
35337
35364
  const children = [];
35338
35365
 
35339
35366
  // Handle empty key
@@ -35379,21 +35406,7 @@ const createTransformers = transformerMap => ({
35379
35406
  } else {
35380
35407
  children.push(value);
35381
35408
  }
35382
-
35383
- // attach comments found between key and value to the value node
35384
- if (commentsBetweenKeyValue.length > 0) {
35385
- const valueNode = findYamlNode(value);
35386
- if (valueNode) {
35387
- valueNode.commentBefore = commentsBetweenKeyValue.join('\n');
35388
- }
35389
- }
35390
- // attach comments found after value to the value node
35391
- if (commentsAfterValue.length > 0) {
35392
- const valueNode = findYamlNode(value);
35393
- if (valueNode) {
35394
- valueNode.comment = commentsAfterValue.join('\n');
35395
- }
35396
- }
35409
+ attachPairComments(pairResult);
35397
35410
  children.push(...errors);
35398
35411
  return new _ast_nodes_YamlKeyValuePair_mjs__WEBPACK_IMPORTED_MODULE_9__["default"]({
35399
35412
  children: children.flat().filter(c => c !== null),
@@ -35604,7 +35617,9 @@ __webpack_require__.r(__webpack_exports__);
35604
35617
  /* harmony import */ var _speclynx_apidom_datamodel__WEBPACK_IMPORTED_MODULE_6__ = __webpack_require__(94);
35605
35618
  /* harmony import */ var _speclynx_apidom_datamodel__WEBPACK_IMPORTED_MODULE_7__ = __webpack_require__(4823);
35606
35619
  /* harmony import */ var _speclynx_apidom_datamodel__WEBPACK_IMPORTED_MODULE_8__ = __webpack_require__(5810);
35607
- /* harmony import */ var _ast_nodes_YamlStyle_mjs__WEBPACK_IMPORTED_MODULE_9__ = __webpack_require__(1544);
35620
+ /* harmony import */ var _ast_nodes_predicates_mjs__WEBPACK_IMPORTED_MODULE_9__ = __webpack_require__(594);
35621
+ /* harmony import */ var _ast_nodes_YamlStyle_mjs__WEBPACK_IMPORTED_MODULE_10__ = __webpack_require__(1544);
35622
+
35608
35623
 
35609
35624
  // Transform context passed through transformation
35610
35625
  // Node with type property and flat position properties
@@ -35631,14 +35646,17 @@ const findFirst = (node, path) => {
35631
35646
  // detect indent from first nested block mapping (stream > document > mapping > keyValuePair > mapping)
35632
35647
  const detectIndent = node => {
35633
35648
  const nested = findFirst(node, ['document', 'mapping', 'keyValuePair', 'mapping']);
35634
- if (nested?.styleGroup === _ast_nodes_YamlStyle_mjs__WEBPACK_IMPORTED_MODULE_9__.YamlStyleGroup.Block && typeof nested.startCharacter === 'number' && nested.startCharacter > 0) {
35649
+ if (nested?.styleGroup === _ast_nodes_YamlStyle_mjs__WEBPACK_IMPORTED_MODULE_10__.YamlStyleGroup.Block && typeof nested.startCharacter === 'number' && nested.startCharacter > 0) {
35635
35650
  return nested.startCharacter;
35636
35651
  }
35637
35652
  return 2;
35638
35653
  };
35639
35654
 
35640
- // strip leading '#' from each line of comment text; yaml library adds '#' during stringification
35641
- const stripCommentHash = text => text.split('\n').map(line => line.replace(/^#/, '')).join('\n');
35655
+ // strip leading '#' from each line of comment text; yaml library adds '#' during
35656
+ // stringification; a bare '#' becomes a single space — the yaml library's encoding
35657
+ // for an empty comment, which its stringifier turns back into '#' (plain '' would
35658
+ // be dropped)
35659
+ const stripCommentHash = text => text.split('\n').map(line => line === '#' ? ' ' : line.replace(/^#/, '')).join('\n');
35642
35660
 
35643
35661
  // collect comment texts from raw AST children, indexed by position relative to non-comment siblings
35644
35662
 
@@ -35708,6 +35726,7 @@ const setYamlStyleProp = (element, key, value) => {
35708
35726
  yaml[key] = value;
35709
35727
  element.style.yaml = yaml;
35710
35728
  };
35729
+ const getYamlStyleProp = (element, key) => element.style?.yaml?.[key];
35711
35730
 
35712
35731
  // apply collected comments to transformed ApiDOM elements
35713
35732
  const applyComments = (elements, comments) => {
@@ -35838,6 +35857,17 @@ const transformChildren = (children, ctx) => {
35838
35857
  return results;
35839
35858
  };
35840
35859
 
35860
+ // stream comments that precede the first document, joined; null when there are none
35861
+ // (stream children are in source order, so everything before the document node qualifies)
35862
+ const collectPreDocumentComments = node => {
35863
+ const texts = [];
35864
+ for (const child of node.children) {
35865
+ if ((0,_ast_nodes_predicates_mjs__WEBPACK_IMPORTED_MODULE_9__.isDocument)(child)) break;
35866
+ if ((0,_ast_nodes_predicates_mjs__WEBPACK_IMPORTED_MODULE_9__.isComment)(child)) texts.push(stripCommentHash(child.content));
35867
+ }
35868
+ return texts.length > 0 ? texts.join('\n') : null;
35869
+ };
35870
+
35841
35871
  // Stream: Wraps transformed children in ParseResultElement
35842
35872
  const transformStream = (node, ctx) => {
35843
35873
  // detect indent from the stream structure (only needed for style preservation)
@@ -35859,6 +35889,16 @@ const transformStream = (node, ctx) => {
35859
35889
  if (elements.length > 0) {
35860
35890
  const resultElement = elements[0];
35861
35891
  resultElement.classes.push('result');
35892
+
35893
+ // stream comments before the first document belong above the result element;
35894
+ // capture them as commentBefore so style round-trips can re-emit them
35895
+ if (ctx.style) {
35896
+ const preDocumentComments = collectPreDocumentComments(node);
35897
+ if (preDocumentComments !== null) {
35898
+ const existing = getYamlStyleProp(resultElement, 'commentBefore');
35899
+ setYamlStyleProp(resultElement, 'commentBefore', typeof existing === 'string' ? `${preDocumentComments}\n${existing}` : preDocumentComments);
35900
+ }
35901
+ }
35862
35902
  }
35863
35903
 
35864
35904
  // Add collected annotations
@@ -35894,7 +35934,7 @@ const transformCollection = (element, node, ctx) => {
35894
35934
  const typedNode = node;
35895
35935
  const children = node.children || [];
35896
35936
  if (ctx.style) {
35897
- if (ctx.flowCollectionPadding === null && node.styleGroup === _ast_nodes_YamlStyle_mjs__WEBPACK_IMPORTED_MODULE_9__.YamlStyleGroup.Flow) {
35937
+ if (ctx.flowCollectionPadding === null && node.styleGroup === _ast_nodes_YamlStyle_mjs__WEBPACK_IMPORTED_MODULE_10__.YamlStyleGroup.Flow) {
35898
35938
  ctx.flowCollectionPadding = detectFlowPadding(typedNode);
35899
35939
  }
35900
35940
  const comments = collectComments(children, typedNode.startCharacter);
@@ -35960,7 +36000,7 @@ const transformScalar = (node, ctx) => {
35960
36000
  const element = ctx.namespace.toElement(node.content);
35961
36001
 
35962
36002
  // Translate style information about empty nodes
35963
- if (node.content === '' && node.style === _ast_nodes_YamlStyle_mjs__WEBPACK_IMPORTED_MODULE_9__.YamlStyle.Plain) {
36003
+ if (node.content === '' && node.style === _ast_nodes_YamlStyle_mjs__WEBPACK_IMPORTED_MODULE_10__.YamlStyle.Plain) {
35964
36004
  element.classes.push('yaml-e-node');
35965
36005
  element.classes.push('yaml-e-scalar');
35966
36006
  }
@@ -38176,7 +38216,7 @@ const forEach = (element, options) => {
38176
38216
  callback = options.callback ?? (() => {});
38177
38217
  predicate = options.predicate ?? (() => true);
38178
38218
  }
38179
- (0,_traversal_mjs__WEBPACK_IMPORTED_MODULE_0__.traverse)(element, {
38219
+ ;(0,_traversal_mjs__WEBPACK_IMPORTED_MODULE_0__.traverse)(element, {
38180
38220
  enter(path) {
38181
38221
  if (predicate(path)) {
38182
38222
  callback(path);