feat(node): implement getChildWithDescendant

and deprecate `getChildContainingDescendant`

Author: ObserverOfTime

scripts/jextract.ps1

@@ -39,6 +39,7 @@ $env:package = 'io.github.treesitter.jtreesitter.internal'
     --include-function ts_node_child_by_field_id `
     --include-function ts_node_child_by_field_name `
     --include-function ts_node_child_containing_descendant `
+    --include-function ts_node_child_with_descendant `
     --include-function ts_node_child_count `
     --include-function ts_node_descendant_count `
     --include-function ts_node_descendant_for_byte_range `

scripts/jextract.sh

@@ -39,6 +39,7 @@ exec jextract \
     --include-function ts_node_child_by_field_id \
     --include-function ts_node_child_by_field_name \
     --include-function ts_node_child_containing_descendant \
+    --include-function ts_node_child_with_descendant \
     --include-function ts_node_child_count \
     --include-function ts_node_descendant_count \
     --include-function ts_node_descendant_for_byte_range \

src/main/java/io/github/treesitter/jtreesitter/Node.java

@@ -386,11 +386,27 @@ public Optional<Node> getNamedDescendant(Point start, Point end) {
         return optional(ts_node_named_descendant_for_point_range(arena, self, startPoint, endPoint));
     }
 
-    /** Get the child of the node that contains the given descendant, if any. */
+    /**
+     * Get the child of the node that contains the given descendant, if any.
+     *
+     * @apiNote This method will not return the descendant if it is a direct child of this node.
+     * @deprecated Use {@link #getChildWithDescendant} instead.
+     */
+    @Deprecated(forRemoval = true)
+    @SuppressWarnings("DeprecatedIsStillUsed")
     public Optional<Node> getChildContainingDescendant(Node descendant) {
         return optional(ts_node_child_containing_descendant(arena, self, descendant.self));
     }
 
+    /**
+     * Get the node that contains the given descendant, if any.
+     *
+     * @since 0.24.0
+     */
+    public Optional<Node> getChildWithDescendant(Node descendant) {
+        return optional(ts_node_child_with_descendant(arena, self, descendant.self));
+    }
+
     /** Get the source code of the node, if available. */
     public @Nullable String getText() {
         var text = tree.getText();

src/test/java/io/github/treesitter/jtreesitter/NodeTest.java

@@ -251,18 +251,26 @@ void getNamedDescendantBytes() {
     @DisplayName("getNamedDescendant(points)")
     void getNamedDescendantPoints() {
         Point startPoint = new Point(0, 6), endPoint = new Point(0, 9);
-        var descendant = node.getDescendant(startPoint, endPoint).orElseThrow();
+        var descendant = node.getNamedDescendant(startPoint, endPoint).orElseThrow();
         assertEquals("identifier", descendant.getGrammarType());
     }
 
     @Test
+    @SuppressWarnings("removal")
     void getChildContainingDescendant() {
         var descendant = node.getChild(0).orElseThrow();
         descendant = descendant.getChild(0).orElseThrow();
         var child = node.getChildContainingDescendant(descendant);
         assertEquals("class_declaration", child.orElseThrow().getType());
     }
 
+    @Test
+    void getChildWithDescendant() {
+        var descendant = node.getChild(0).orElseThrow();
+        var child = node.getChildWithDescendant(descendant);
+        assertEquals("class_declaration", child.orElseThrow().getType());
+    }
+
     @Test
     void getText() {
         var child = node.getDescendant(6, 9).orElseThrow();