feature/tree-sitter 639821d49a 3/6: Allow checking for outdated nodes in tree-sitter

[Yuan Fu]

branch: feature/tree-sitter
commit 639821d49ab9497908d8d3bcd472aed558c251e1
Author: Yuan Fu <casouri@gmail.com>
Commit: Yuan Fu <casouri@gmail.com>

    Allow checking for outdated nodes in tree-sitter
    
    Now you can run (treesit-node-check node 'outdated).
    
    * doc/lispref/parsing.texi (Accessing Node Information): Update
    manual.
    * src/treesit.c (Ftreesit_node_check): Add new property 'outdated'.
    * test/src/treesit-tests.el (treesit-node-check): Add tests.
---
 doc/lispref/parsing.texi  | 13 ++++++++++---
 src/treesit.c             | 15 ++++++++++++---
 test/src/treesit-tests.el |  7 +++++--
 3 files changed, 27 insertions(+), 8 deletions(-)

diff --git a/doc/lispref/parsing.texi b/doc/lispref/parsing.texi
index 2ea229ec90..d73057321e 100644
--- a/doc/lispref/parsing.texi
+++ b/doc/lispref/parsing.texi
@@ -930,6 +930,11 @@ is not yet in its final form.
 A node can be ``extra'': such nodes represent things like comments,
 which can appear anywhere in the text.
 
+@cindex tree-sitter outdated node
+@cindex outdated node, tree-sitter
+A node can be ``outdated'': If its parser has reparse at least once
+after the node was created, the node is outdated.
+
 @cindex tree-sitter node that has error
 @cindex has error, tree-sitter node
 A node ``has error'' if the text it spans contains a syntax error.  It
@@ -938,14 +943,16 @@ has an error.
 
 @defun treesit-node-check node property
 This function checks if @var{node} has the specified @var{property}.
-@var{property} can be @code{named}, @code{missing}, @code{extra}, or
-@code{has-error}.
+@var{property} can be @code{named}, @code{missing}, @code{extra},
+@code{outdated}, or @code{has-error}.
 @end defun
 
 @defun treesit-node-type node
 Named nodes have ``types'' (@pxref{tree-sitter node type, node type}).
 For example, a named node can be a @code{string_literal} node, where
-@code{string_literal} is its type.
+@code{string_literal} is its type.  The type of an anonymous node is
+just the text that node represents, e.g., the type of a @samp{,} node
+is just @samp{,}.
 
 This function returns @var{node}'s type as a string.
 @end defun
diff --git a/src/treesit.c b/src/treesit.c
index 0b9f0e98d9..1e1238eefd 100644
--- a/src/treesit.c
+++ b/src/treesit.c
@@ -1723,7 +1723,7 @@ DEFUN ("treesit-node-check",
        Ftreesit_node_check, Streesit_node_check, 2, 2, 0,
        doc: /* Return non-nil if NODE has PROPERTY, nil otherwise.
 
-PROPERTY could be `named', `missing', `extra', or `has-error'.
+PROPERTY could be `named', `missing', `extra', `outdated', or `has-error'.
 
 Named nodes correspond to named rules in the language definition,
 whereas "anonymous" nodes correspond to string literals in the
@@ -1735,17 +1735,25 @@ certain kinds of syntax errors, i.e., should be there 
but not there.
 Extra nodes represent things like comments, which are not required the
 language definition, but can appear anywhere.
 
+A node is "outdated" if the parser has reparsed at least once after
+the node was created.
+
 A node "has error" if itself is a syntax error or contains any syntax
 errors.  */)
   (Lisp_Object node, Lisp_Object property)
 {
   if (NILP (node)) return Qnil;
-  treesit_check_node (node);
+  CHECK_TS_NODE (node);
   CHECK_SYMBOL (property);
   treesit_initialize ();
 
   TSNode treesit_node = XTS_NODE (node)->node;
   bool result;
+
+  if (EQ (property, Qoutdated))
+    return treesit_node_uptodate_p (node) ? Qnil : Qt;
+
+  treesit_check_node (node);
   if (EQ (property, Qnamed))
     result = ts_node_is_named (treesit_node);
   else if (EQ (property, Qmissing))
@@ -1756,7 +1764,7 @@ errors.  */)
     result = ts_node_has_error (treesit_node);
   else
     signal_error ("Expecting `named', `missing', `extra', "
-                 "or `has-error', but got",
+                 "`outdated', or `has-error', but got",
                  property);
   return result ? Qt : Qnil;
 }
@@ -2918,6 +2926,7 @@ syms_of_treesit (void)
   DEFSYM (Qnamed, "named");
   DEFSYM (Qmissing, "missing");
   DEFSYM (Qextra, "extra");
+  DEFSYM (Qoutdated, "outdated");
   DEFSYM (Qhas_error, "has-error");
 
   DEFSYM (Qnot_found, "not-found");
diff --git a/test/src/treesit-tests.el b/test/src/treesit-tests.el
index 9b8e3466f2..2a3f43916a 100644
--- a/test/src/treesit-tests.el
+++ b/test/src/treesit-tests.el
@@ -516,8 +516,11 @@ visible_end.)"
     (should (treesit-node-check comment-node 'extra))
     (should (treesit-node-check array-node 'has-error))
     (should-error (treesit-node-check array-node 'xxx))
-    ;; TODO: Test for `missing'.
-    ))
+    (should (treesit-node-check (treesit-node-child array-node -1)
+                                'missing))
+    (goto-char (point-max))
+    (insert "]")
+    (should (treesit-node-check array-node 'outdated))))
 
 (ert-deftest treesit-misc ()
   "Misc helper functions."