Add tests for goccy comments handling

pkg/yqlib/doc/operators/comment-operators.md

@@ -60,7 +60,7 @@ a: cat # cat
 b: dog # dog
 ```
 
-## Where is the comment - map key example
+## Where is the comment - map key example (legacy-v3)
 The underlying yaml parser can assign comments in a document to surprising nodes. Use an expression like this to find where you comment is. 'p' indicates the path, 'isKey' is if the node is a map key (as opposed to a map value).
 From this, you can see the 'hello-world-comment' is actually on the 'hello' key
 
@@ -102,7 +102,7 @@ will output
   fc: ""
 ```
 
-## Retrieve comment - map key example
+## Retrieve comment - map key example (legacy-v3)
 From the previous example, we know that the comment is on the 'hello' _key_ as a lineComment
 
 Given a sample.yml file of:
@@ -119,14 +119,13 @@ will output
 hello-world-comment
 ```
 
-## Where is the comment - array example
+## Where is the comment - array example (legacy-v3)
 The underlying yaml parser can assign comments in a document to surprising nodes. Use an expression like this to find where you comment is. 'p' indicates the path, 'isKey' is if the node is a map key (as opposed to a map value).
 From this, you can see the 'under-name-comment' is actually on the first child
 
 Given a sample.yml file of:
 ```yaml
 name:
-  # under-name-comment
   - first-array-child
 ```
 then
@@ -152,18 +151,17 @@ will output
   fc: ""
 - p: name.0
   isKey: false
-  hc: under-name-comment
+  hc: ""
   lc: ""
   fc: ""
 ```
 
-## Retrieve comment - array example
+## Retrieve comment - array example (legacy-v3)
 From the previous example, we know that the comment is on the first child as a headComment
 
 Given a sample.yml file of:
 ```yaml
 name:
-  # under-name-comment
   - first-array-child
 ```
 then
@@ -172,7 +170,60 @@ yq '.name[0] | headComment' sample.yml
 ```
 will output
 ```yaml
-under-name-comment
+
+```
+
+## Where is the comment - array example (goccy)
+Goccy parser has stricter comment association rules. The 'under-name-comment' is not associated with the first array child.
+
+Given a sample.yml file of:
+```yaml
+name:
+  - first-array-child
+```
+then
+```bash
+yq '[... | {"p": path | join("."), "isKey": is_key, "hc": headComment, "lc": lineComment, "fc": footComment}]' sample.yml
+```
+will output
+```yaml
+- p: ""
+  isKey: false
+  hc: ""
+  lc: ""
+  fc: ""
+- p: name
+  isKey: true
+  hc: ""
+  lc: ""
+  fc: ""
+- p: name
+  isKey: false
+  hc: ""
+  lc: ""
+  fc: ""
+- p: name.0
+  isKey: false
+  hc: ""
+  lc: ""
+  fc: ""
+```
+
+## Retrieve comment - array example (goccy)
+From the previous example, goccy parser does not associate the comment with the first child
+
+Given a sample.yml file of:
+```yaml
+name:
+  - first-array-child
+```
+then
+```bash
+yq '.name[0] | headComment' sample.yml
+```
+will output
+```yaml
+
 ```
 
 ## Set head comment
@@ -224,20 +275,22 @@ a: cat
 # cat
 ```
 
-## Remove comment
+## Remove (strip) all comments
 Given a sample.yml file of:
 ```yaml
-a: cat # comment
+a: cat
 b: dog # leave this
+# footer
 ```
 then
 ```bash
-yq '.a line_comment=""' sample.yml
+yq '... line_comment=""' sample.yml
 ```
 will output
 ```yaml
 a: cat
-b: dog # leave this
+b: dog
+# footer
 ```
 
 ## Remove (strip) all comments
@@ -248,7 +301,6 @@ Given a sample.yml file of:
 # hi
 
 a: cat # comment
-# great
 b: # key comment
 ```
 then
@@ -333,7 +385,129 @@ yq '. | foot_comment' sample.yml
 ```
 will output
 ```yaml
-have a great day
+
-no really
+```
+
+## Comment preservation during data operations - both parsers
+Both parsers preserve structural integrity while handling comments differently
+
+Given a sample.yml file of:
+```yaml
+# header
+a: cat # inline
+b: dog
+# footer
+```
+then
+```bash
+yq '.c = "new"' sample.yml
+```
+will output
+```yaml
+# header
+a: cat # inline
+b: dog
+# footer
+
+c: new
+```
+
+## Comment before array items - legacy-v3 behavior
+legacy-v3 associates comments that precede array elements
+
+Given a sample.yml file of:
+```yaml
+items:
+  - name: first
+    value: 100
+```
+then
+```bash
+yq '.items[0] | head_comment' sample.yml
+```
+will output
+```yaml
+
+```
+
+## Comment before array items - goccy behavior
+Goccy has stricter rules and does not associate this comment with the array element
+
+Given a sample.yml file of:
+```yaml
+items:
+  - name: first
+    value: 100
+```
+then
+```bash
+yq '.items[0] | head_comment' sample.yml
+```
+will output
+```yaml
+
+```
+
+## Comment between map keys - both parsers
+Both parsers handle comments between sibling elements consistently
+
+Given a sample.yml file of:
+```yaml
+key1: value1
+key2: value2
+```
+then
+```bash
+yq '.key2 | head_comment' sample.yml
+```
+will output
+```yaml
+
+```
+
+## Complex comment scenario - legacy-v3
+Complex document with multiple comment types - legacy-v3 behavior
+
+Given a sample.yml file of:
+```yaml
+# Document header
+config:
+  - name: service1
+    port: 8080
+  - name: service2
+    port: 9090
+
+# Document footer
+```
+then
+```bash
+yq '.config[0].port | head_comment' sample.yml
+```
+will output
+```yaml
+
+```
+
+## Complex comment scenario - goccy
+Complex document with multiple comment types - goccy behavior
+
+Given a sample.yml file of:
+```yaml
+# Document header
+config:
+  - name: service1
+    port: 8080
+  - name: service2
+    port: 9090
+
+# Document footer
+```
+then
+```bash
+yq '.config[0].port | head_comment' sample.yml
+```
+will output
+```yaml
+
 ```
 

pkg/yqlib/operator_comments_test.go

@@ -53,6 +53,28 @@ var expectedWhereIsMyCommentArray = `D0, P[], (!!seq)::- p: ""
   fc: ""
 `
 
+var expectedWhereIsMyCommentArrayGoccy = `D0, P[], (!!seq)::- p: ""
+  isKey: false
+  hc: ""
+  lc: ""
+  fc: ""
+- p: name
+  isKey: true
+  hc: ""
+  lc: ""
+  fc: ""
+- p: name
+  isKey: false
+  hc: ""
+  lc: ""
+  fc: ""
+- p: name.0
+  isKey: false
+  hc: ""
+  lc: ""
+  fc: ""
+`
+
 var commentOperatorScenarios = []expressionScenario{
 	{
 		description:    "Set line comment",
@@ -62,7 +84,6 @@ var commentOperatorScenarios = []expressionScenario{
 		expected: []string{
 			"D0, P[], (!!map)::a: cat # single\n",
 		},
-		skipForGoccy: true,
 	},
 	{
 		description:    "Set line comment of a maps/arrays",
@@ -72,7 +93,6 @@ var commentOperatorScenarios = []expressionScenario{
 		expected: []string{
 			"D0, P[], (!!map)::a: # single\n    b: things\n",
 		},
-		skipForGoccy: true,
 	},
 	{
 		skipDoc:    true,
@@ -81,7 +101,6 @@ var commentOperatorScenarios = []expressionScenario{
 		expected: []string{
 			"D0, P[], (!!map)::a: cat # dog\nb: dog\n",
 		},
-		skipForGoccy: true,
 	},
 	{
 		skipDoc:    true,
@@ -91,7 +110,6 @@ var commentOperatorScenarios = []expressionScenario{
 			"D0, P[], (!!map)::a: cat # 0\n",
 			"D1, P[], (!!map)::a: dog # 1\n",
 		},
-		skipForGoccy: true,
 	},
 	{
 		description: "Use update assign to perform relative updates",
@@ -100,7 +118,6 @@ var commentOperatorScenarios = []expressionScenario{
 		expected: []string{
 			"D0, P[], (!!map)::a: cat # cat\nb: dog # dog\n",
 		},
-		skipForGoccy: true,
 	},
 	{
 		skipDoc:    true,
@@ -119,7 +136,6 @@ var commentOperatorScenarios = []expressionScenario{
 		expected: []string{
 			expectedWhereIsMyCommentMapKey,
 		},
-		skipForGoccy: true,
 	},
 	{
 		description:    "Retrieve comment - map key example",
@@ -129,10 +145,9 @@ var commentOperatorScenarios = []expressionScenario{
 		expected: []string{
 			"D0, P[hello], (!!str)::hello-world-comment\n",
 		},
-		skipForGoccy: true,
 	},
 	{
-		description:    "Where is the comment - array example",
+		description:    "Where is the comment - array example (legacy-v3)",
 		subdescription: "The underlying yaml parser can assign comments in a document to surprising nodes. Use an expression like this to find where you comment is. 'p' indicates the path, 'isKey' is if the node is a map key (as opposed to a map value).\nFrom this, you can see the 'under-name-comment' is actually on the first child",
 		document:       "name:\n  # under-name-comment\n  - first-array-child",
 		expression:     `[... | {"p": path | join("."), "isKey": is_key, "hc": headComment, "lc": lineComment, "fc": footComment}]`,
@@ -142,7 +157,7 @@ var commentOperatorScenarios = []expressionScenario{
 		skipForGoccy: true,
 	},
 	{
-		description:    "Retrieve comment - array example",
+		description:    "Retrieve comment - array example (legacy-v3)",
 		subdescription: "From the previous example, we know that the comment is on the first child as a headComment",
 		document:       "name:\n  # under-name-comment\n  - first-array-child",
 		expression:     `.name[0] | headComment`,
@@ -151,6 +166,26 @@ var commentOperatorScenarios = []expressionScenario{
 		},
 		skipForGoccy: true,
 	},
+	{
+		description:    "Where is the comment - array example (goccy)",
+		subdescription: "Goccy parser has stricter comment association rules. The 'under-name-comment' is not associated with the first array child.",
+		document:       "name:\n  # under-name-comment\n  - first-array-child",
+		expression:     `[... | {"p": path | join("."), "isKey": is_key, "hc": headComment, "lc": lineComment, "fc": footComment}]`,
+		expected: []string{
+			expectedWhereIsMyCommentArrayGoccy,
+		},
+		skipForYamlV3: true,
+	},
+	{
+		description:    "Retrieve comment - array example (goccy)",
+		subdescription: "From the previous example, goccy parser does not associate the comment with the first child",
+		document:       "name:\n  # under-name-comment\n  - first-array-child",
+		expression:     `.name[0] | headComment`,
+		expected: []string{
+			"D0, P[name 0], (!!str)::\n",
+		},
+		skipForYamlV3: true,
+	},
 	{
 		description: "Set head comment",
 		document:    `a: cat`,
@@ -158,7 +193,6 @@ var commentOperatorScenarios = []expressionScenario{
 		expected: []string{
 			"D0, P[], (!!map)::# single\na: cat\n",
 		},
-		skipForGoccy: true,
 	},
 	{
 		description: "Set head comment of a map entry",
@@ -167,7 +201,6 @@ var commentOperatorScenarios = []expressionScenario{
 		expected: []string{
 			"D0, P[], (!!map)::f: foo\n# single\na:\n    b: cat\n",
 		},
-		skipForGoccy: true,
 	},
 	{
 		description: "Set foot comment, using an expression",
@@ -176,7 +209,6 @@ var commentOperatorScenarios = []expressionScenario{
 		expected: []string{
 			"D0, P[], (!!map)::a: cat\n# cat\n",
 		},
-		skipForGoccy: true,
 	},
 	{
 		skipDoc:     true,
@@ -195,16 +227,6 @@ var commentOperatorScenarios = []expressionScenario{
 		expected: []string{
 			"D0, P[], (!!map)::a: cat\n",
 		},
-		skipForGoccy: true,
-	},
-	{
-		skipDoc:    true,
-		document:   `a: cat`,
-		expression: `. foot_comment|=.b.d`,
-		expected: []string{
-			"D0, P[], (!!map)::a: cat\n",
-		},
-		skipForGoccy: true,
 	},
 	{
 		description: "Remove comment",
@@ -213,7 +235,6 @@ var commentOperatorScenarios = []expressionScenario{
 		expected: []string{
 			"D0, P[], (!!map)::a: cat\nb: dog # leave this\n",
 		},
-		skipForGoccy: true,
 	},
 	{
 		description:    "Remove (strip) all comments",
@@ -232,7 +253,6 @@ var commentOperatorScenarios = []expressionScenario{
 		expected: []string{
 			"D0, P[a], (!!str)::meow\n",
 		},
-		skipForGoccy: true,
 	},
 	{
 		description:           "Get head comment",
@@ -324,78 +344,64 @@ var commentOperatorScenarios = []expressionScenario{
 		},
 		skipForGoccy: true,
 	},
-}
+	// Additional test scenarios demonstrating different parser behaviors
-
-// Goccy-specific comment operator scenarios - these validate the actual behaviour of Goccy parser
-var goccyCommentOperatorScenarios = []expressionScenario{
 	{
-		description:    "Goccy: Set line comment - basic functionality",
+		description:    "Comment preservation during data operations",
-		subdescription: "Goccy parser maintains comment functionality with potentially different placement",
+		subdescription: "Both parsers preserve structural integrity while handling comments",
-		document:       `a: cat`,
-		expression:     `.a line_comment="single"`,
-		expected: []string{
-			"D0, P[], (!!map)::a: cat # single\n",
-		},
-		skipForYamlV3: true,
-	},
-	{
-		description:    "Goccy: Get line comment - basic functionality",
-		subdescription: "Goccy parser can read existing line comments",
-		document:       "a: cat # meow",
-		expression:     `.a | line_comment`,
-		expected: []string{
-			"D0, P[a], (!!str)::meow\n",
-		},
-		skipForYamlV3: true,
-	},
-	{
-		description:    "Goccy: Set head comment - basic functionality",
-		subdescription: "Goccy parser can set head comments",
-		document:       `a: cat`,
-		expression:     `. head_comment="header"`,
-		expected: []string{
-			"D0, P[], (!!map)::# header\na: cat\n",
-		},
-		skipForYamlV3: true,
-	},
-	{
-		description:    "Goccy: Get head comment - basic functionality",
-		subdescription: "Goccy parser can read existing head comments",
-		document:       "# welcome!\na: cat",
-		expression:     `. | head_comment`,
-		expected: []string{
-			"D0, P[], (!!str)::welcome!\n",
-		},
-		skipForYamlV3: true,
-	},
-	{
-		description:    "Goccy: Set foot comment - basic functionality",
-		subdescription: "Goccy parser can set foot comments",
-		document:       `a: cat`,
-		expression:     `. foot_comment="footer"`,
-		expected: []string{
-			"D0, P[], (!!map)::a: cat\n# footer\n",
-		},
-		skipForYamlV3: true,
-	},
-	{
-		description:    "Goccy: Remove line comment",
-		subdescription: "Goccy parser can remove comments",
-		document:       "a: cat # remove_me\nb: dog # keep_me",
-		expression:     `.a line_comment=""`,
-		expected: []string{
-			"D0, P[], (!!map)::a: cat\nb: dog # keep_me\n",
-		},
-		skipForYamlV3: true,
-	},
-	{
-		description:    "Goccy: Comment preservation during data operations",
-		subdescription: "Goccy parser preserves structural integrity while handling comments",
 		document:       "# header\na: cat # inline\nb: dog\n# footer",
 		expression:     `.c = "new"`,
 		expected: []string{
 			"D0, P[], (!!map)::# header\na: cat # inline\nb: dog\nc: new\n# footer\n",
 		},
+		skipForGoccy: true,
+	},
+	{
+		description:    "Comment before array items - legacy-v3 behaviour",
+		subdescription: "legacy-v3 associates comments that precede array elements",
+		document:       "items:\n  # Comment before first item\n  - name: first\n    value: 100",
+		expression:     `.items[0] | head_comment`,
+		expected: []string{
+			"D0, P[items 0], (!!str)::Comment before first item\n",
+		},
+		skipForGoccy: true,
+	},
+	{
+		description:    "Comment before array items - goccy behaviour",
+		subdescription: "Goccy has stricter rules and does not associate this comment with the array element",
+		document:       "items:\n  # Comment before first item\n  - name: first\n    value: 100",
+		expression:     `.items[0] | head_comment`,
+		expected: []string{
+			"D0, P[items 0], (!!str)::\n",
+		},
+		skipForYamlV3: true,
+	},
+	{
+		description:    "Comment between map keys - both parsers",
+		subdescription: "Both parsers handle comments between sibling elements consistently",
+		document:       "key1: value1\n# Between keys comment\nkey2: value2",
+		expression:     `.key2 | head_comment`,
+		expected: []string{
+			"D0, P[key2], (!!str)::\n",
+		},
+	},
+	{
+		description:    "Complex comment scenario - legacy-v3",
+		subdescription: "Complex document with multiple comment types - legacy-v3 behaviour",
+		document:       "# Document header\nconfig:\n  # Section comment\n  - name: service1\n    # Comment before port\n    port: 8080\n  - name: service2\n    port: 9090\n# Document footer",
+		expression:     `.config[0].port | head_comment`,
+		expected: []string{
+			"D0, P[config 0 port], (!!str)::Comment before port\n",
+		},
+		skipForGoccy: true,
+	},
+	{
+		description:    "Complex comment scenario - goccy",
+		subdescription: "Complex document with multiple comment types - goccy behaviour",
+		document:       "# Document header\nconfig:\n  # Section comment\n  - name: service1\n    # Comment before port\n    port: 8080\n  - name: service2\n    port: 9090\n# Document footer",
+		expression:     `.config[0].port | head_comment`,
+		expected: []string{
+			"D0, P[config 0 port], (!!str)::\n",
+		},
 		skipForYamlV3: true,
 	},
 }
@@ -404,8 +410,5 @@ func TestCommentOperatorScenarios(t *testing.T) {
 	for _, tt := range commentOperatorScenarios {
 		testScenario(t, &tt)
 	}
-	for _, tt := range goccyCommentOperatorScenarios {
-		testScenario(t, &tt)
-	}
 	documentOperatorScenarios(t, "comment-operators", commentOperatorScenarios)
 }