feat(statement): add StmtFeature classification via Statement#getFeatures()

Signed-off-by: Andreas Reichel <andreas@manticore-projects.com>

Author: manticore-projects

README.md

@@ -62,7 +62,7 @@ EqualsTo equalsTo = (EqualsTo) select.getWhere();
 Column a = (Column) equalsTo.getLeftExpression();
 Column b = (Column) equalsTo.getRightExpression();
 Assertions.assertEquals("a", a.getColumnName());
-Assertions.assertEquals("b", b.getColumnName());
+        Assertions.assertEquals("b", b.getColumnName());
 ```
 
 The tree is traversable with the Visitor pattern, and the same object model works in reverse:
@@ -148,6 +148,40 @@ Beyond statement shapes, the grammar handles nested sub-selects, bind parameters
 array-literal ambiguity. The complete reference is on the
 [syntax page](https://jsqlparser.github.io/JSqlParser/syntax.html).
 
+## Statement classification
+
+Any parsed statement can say what it actually does — no second parse, no visitor to write:
+
+```java
+StatementFeatures features = CCJSqlParserUtil.parse(sqlStr).getFeatures();
+
+// safeguard a read-only client before anything reaches the database
+if (connection.isReadOnly() && features.mayModifyData()) {
+    throw new SQLException("rejected: " + features.getUnresolvedReferences());
+}
+
+// dispatch correctly
+if (features.returnsResultSet()) { statement.executeQuery(sqlStr);  }
+else                             { statement.executeUpdate(sqlStr); }
+```
+
+This is not `sqlStr.startsWith("SELECT")` with extra steps. `RETURNING` turns DML into a row
+source, a data-modifying CTE hides a `DELETE` inside a `SELECT`, and `INSERT INTO x SELECT ..`
+contains a query but returns nothing:
+
+| SQL | returns rows | modifies data |
+|---|---|---|
+| `SELECT * FROM t` | yes | no |
+| `INSERT INTO x SELECT * FROM t` | no | yes |
+| `DELETE FROM t RETURNING *` | yes | yes |
+| `WITH c AS (DELETE FROM t RETURNING *) SELECT * FROM c` | yes | yes |
+| `SELECT nextval('s')` | yes | *unproven* |
+
+Features are not mutually exclusive, and each is three-valued: proven, not excludable, or ruled
+out. `is()` answers "did the grammar prove it", `may()` answers "could it be ruled out" — so a
+guard uses `may()` and a dispatcher uses `is()`. Function volatility is not a syntactic property,
+so anything the caller has not declared pure stays unproven and is listed by name.
+
 ## Piped SQL
 
 Support is progressing for Piped SQL, which writes queries in the order they actually

src/main/java/net/sf/jsqlparser/statement/Statement.java

@@ -11,10 +11,26 @@
 
 import net.sf.jsqlparser.Model;
 
+import java.util.function.Predicate;
+
 public interface Statement extends Model {
     <T, S> T accept(StatementVisitor<T> statementVisitor, S context);
 
     default void accept(StatementVisitor<?> statementVisitor) {
         accept(statementVisitor, null);
     }
+
+    /**
+     * Static feature analysis of this statement tree. Not cached: the AST is mutable and publicly
+     * constructible, and a stale bitmask is worse than a recomputation (micro seconds against a
+     * millisecond-scale parse).
+     */
+    default StatementFeatures getFeatures() {
+        return StatementFeatureVisitor.analyse(this);
+    }
+
+    /** Same, with a caller-supplied allow-list of provably side-effect-free functions. */
+    default StatementFeatures getFeatures(Predicate<String> pureFunctions) {
+        return StatementFeatureVisitor.analyse(this, pureFunctions);
+    }
 }