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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@speclynx/apidom-parser-adapter-yaml-1-2",
-  "version": "5.0.2",
+  "version": "5.1.0",
   "description": "Parser adapter for parsing YAML documents into base namespace.",
   "keywords": [
     "apidom",
@@ -58,9 +58,9 @@
   "license": "Apache-2.0",
   "dependencies": {
     "@babel/runtime-corejs3": "^8.0.0",
-    "@speclynx/apidom-core": "5.0.2",
-    "@speclynx/apidom-datamodel": "5.0.2",
-    "@speclynx/apidom-error": "5.0.2",
+    "@speclynx/apidom-core": "5.1.0",
+    "@speclynx/apidom-datamodel": "5.1.0",
+    "@speclynx/apidom-error": "5.1.0",
     "ramda": "~0.32.0",
     "ramda-adjunct": "^6.1.0",
     "unraw": "^3.0.0",
@@ -80,5 +80,5 @@
     "README.md",
     "CHANGELOG.md"
   ],
-  "gitHead": "01792b567baea3a47cb08d09e478178aa04afda9"
+  "gitHead": "2976a9fe41a9eb3a2de387695c41d21603f57c98"
 }

package/src/tree-sitter/syntactic-analysis/CstTransformer.cjs

@@ -103,8 +103,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 => {
@@ -147,7 +150,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;
       }
@@ -176,6 +182,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);
 
@@ -347,13 +382,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
@@ -399,21 +433,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 _YamlKeyValuePair.default({
       children: children.flat().filter(c => c !== null),
@@ -441,13 +461,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
@@ -493,21 +512,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 _YamlKeyValuePair.default({
       children: children.flat().filter(c => c !== null),

package/src/tree-sitter/syntactic-analysis/CstTransformer.mjs

@@ -95,8 +95,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 => {
@@ -139,7 +142,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;
       }
@@ -168,6 +174,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);
 
@@ -339,13 +374,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
@@ -391,21 +425,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 YamlKeyValuePair({
       children: children.flat().filter(c => c !== null),
@@ -433,13 +453,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
@@ -485,21 +504,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 YamlKeyValuePair({
       children: children.flat().filter(c => c !== null),

package/src/tree-sitter/syntactic-analysis/YamlAstTransformer.cjs

@@ -5,6 +5,7 @@ Object.defineProperty(exports, "__esModule", {
 });
 exports.transformYamlAstToApiDOM = exports.default = void 0;
 var _apidomDatamodel = require("@speclynx/apidom-datamodel");
+var _predicates = require("./ast/nodes/predicates.cjs");
 var _YamlStyle = require("./ast/nodes/YamlStyle.cjs");
 // Transform context passed through transformation
 
@@ -39,8 +40,11 @@ const detectIndent = node => {
   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
 
@@ -110,6 +114,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) => {
@@ -240,6 +245,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, _predicates.isDocument)(child)) break;
+    if ((0, _predicates.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)
@@ -261,6 +277,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

package/src/tree-sitter/syntactic-analysis/YamlAstTransformer.mjs

@@ -1,4 +1,5 @@
 import { ParseResultElement, AnnotationElement, CommentElement, MemberElement, ObjectElement, ArrayElement, isPrimitiveElement, Namespace, SourceMapElement } from '@speclynx/apidom-datamodel';
+import { isComment, isDocument } from "./ast/nodes/predicates.mjs";
 import { YamlStyle, YamlStyleGroup } from "./ast/nodes/YamlStyle.mjs"; // Transform context passed through transformation
 // Node with type property and flat position properties
 // Helper to add source map to element
@@ -30,8 +31,11 @@ const detectIndent = node => {
   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
 
@@ -101,6 +105,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) => {
@@ -231,6 +236,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 (isDocument(child)) break;
+    if (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)
@@ -252,6 +268,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