feat(parser): expose leading comments via getLeadingComments()

Downstream SQL rewriters currently recover statement-leading comments
from the JavaCC special-token chain via getASTNode(), whose erasure
changed within 5.x and broke compiled downstream adapters.

Signed-off-by: 付典 <fudianchn@gmail.com>

Author: fudianchn

src/main/java/net/sf/jsqlparser/parser/ASTNodeAccessImpl.java

@@ -9,6 +9,9 @@
  */
 package net.sf.jsqlparser.parser;
 
+import java.util.ArrayList;
+import java.util.Collections;
+import java.util.List;
 import java.util.Set;
 import java.util.TreeSet;
 
@@ -26,6 +29,26 @@ public void setASTNode(Node node) {
         this.node = node;
     }
 
+    /**
+     * The comments preceding this node's first token, in source order, with the original token
+     * images (line comments keep their line terminator). Empty for nodes built programmatically,
+     * which carry no AST.
+     */
+    public List<String> getLeadingComments() {
+        Node node = getASTNode();
+        if (node == null) {
+            return new ArrayList<>();
+        }
+        List<String> comments = new ArrayList<>();
+        for (Token specialToken =
+                node.jjtGetFirstToken().specialToken; specialToken != null; specialToken =
+                        specialToken.specialToken) {
+            comments.add(specialToken.image);
+        }
+        Collections.reverse(comments);
+        return comments;
+    }
+
     public StringBuilder appendTo(StringBuilder builder) {
         // don't add spaces around the following punctuation
         final Set<String> punctuation = new TreeSet<>(Set.of(".", "[", "]"));

src/test/java/net/sf/jsqlparser/parser/LeadingCommentsTest.java

@@ -0,0 +1,71 @@
+/*-
+ * #%L
+ * JSQLParser library
+ * %%
+ * Copyright (C) 2004 - 2019 JSQLParser
+ * %%
+ * Dual licensed under GNU LGPL 2.1 or Apache License 2.0
+ * #L%
+ */
+package net.sf.jsqlparser.parser;
+
+import static org.junit.jupiter.api.Assertions.assertEquals;
+import static org.junit.jupiter.api.Assertions.assertFalse;
+import static org.junit.jupiter.api.Assertions.assertTrue;
+
+import java.util.List;
+import net.sf.jsqlparser.JSQLParserException;
+import net.sf.jsqlparser.statement.Statements;
+import net.sf.jsqlparser.statement.select.PlainSelect;
+import net.sf.jsqlparser.statement.select.Select;
+import org.junit.jupiter.api.Test;
+
+public class LeadingCommentsTest {
+
+    @Test
+    public void blockCommentsBeforeStatementInSourceOrder() throws JSQLParserException {
+        Select select = (Select) CCJSqlParserUtil
+                .parse("/* keep orderby */ /*+ FULL(t) */ SELECT * FROM mytable");
+        assertEquals(List.of("/* keep orderby */", "/*+ FULL(t) */"), select.getLeadingComments());
+    }
+
+    @Test
+    public void lineCommentBeforeStatement() throws JSQLParserException {
+        Select select = (Select) CCJSqlParserUtil.parse("-- paging hint\nSELECT 1");
+        List<String> comments = select.getLeadingComments();
+        assertEquals(1, comments.size());
+        assertTrue(comments.get(0).startsWith("-- paging hint"));
+    }
+
+    @Test
+    public void commentInsideStatementIsNotLeading() throws JSQLParserException {
+        Select select = (Select) CCJSqlParserUtil.parse("SELECT /* mid comment */ 1");
+        assertEquals(List.of(), select.getLeadingComments());
+    }
+
+    @Test
+    public void statementWithoutComments() throws JSQLParserException {
+        Select select = (Select) CCJSqlParserUtil.parse("SELECT * FROM mytable");
+        assertEquals(List.of(), select.getLeadingComments());
+    }
+
+    @Test
+    public void programmaticStatementHasNoLeadingComments() {
+        assertEquals(List.of(), new PlainSelect().getLeadingComments());
+    }
+
+    @Test
+    public void toStringDropsLeadingCommentsAsBefore() throws JSQLParserException {
+        Select select = (Select) CCJSqlParserUtil
+                .parse("/* keep orderby */ SELECT * FROM mytable");
+        assertFalse(select.toString().contains("/*"));
+    }
+
+    @Test
+    public void commentsSplitPerStatement() throws JSQLParserException {
+        Statements statements = CCJSqlParserUtil
+                .parseStatements("/* first */ SELECT 1; /* second */ SELECT 2");
+        assertEquals(List.of("/* first */"), ((Select) statements.get(0)).getLeadingComments());
+        assertEquals(List.of("/* second */"), ((Select) statements.get(1)).getLeadingComments());
+    }
+}