feat(treesitter): add query_linter from nvim-treesitter/playground (#22784)

Co-authored-by: clason <clason@users.noreply.github.com>
Co-authored-by: lewis6991 <lewis6991@users.noreply.github.com>

3 files changed, 42 insertions, 0 deletions

diff --git a/runtime/doc/filetype.txt b/runtime/doc/filetype.txt
index f69ffeabfe..175c531950 100644
--- a/runtime/doc/filetype.txt
+++ b/runtime/doc/filetype.txt
@@ -663,6 +663,20 @@ To disable this behavior, set the following variable in your vimrc: >
 
 	let g:python_recommended_style = 0
 
+QUERY					                *ft-query-plugin*
+
+
+Linting of tree-sitter queries for installed parsers using
+|lua-treesitter-query_linter| is enabled by default on
+`BufEnter` and `BufWrite`. To change the events that
+trigger linting, use >lua
+
+	vim.g.query_lint_on = { 'InsertLeave', 'TextChanged' }
+<
+To disable linting completely, set >lua
+
+	vim.g.query_lint_on = {}
+<
 
 QF QUICKFIX					    *qf.vim* *ft-qf-plugin*
 
diff --git a/runtime/doc/news.txt b/runtime/doc/news.txt
index 2a776ea30a..c343525a09 100644
--- a/runtime/doc/news.txt
+++ b/runtime/doc/news.txt
@@ -39,6 +39,12 @@ The following new APIs or features were added.
 iterators |luaref-in|.
 • Added |vim.keycode()| for translating keycodes in a string.
 
+• Added automatic linting of treesitter query files (see |ft-query-plugin|).
+  Automatic linting can be turned off via >lua
+	vim.g.query_lint_on = {}
+<
+• Enabled treesitter highlighting for treesitter query files by default.
+
 ==============================================================================
 CHANGED FEATURES                                                 *news-changed*
 
diff --git a/runtime/doc/treesitter.txt b/runtime/doc/treesitter.txt
index dc1afe89f8..32c97ce3ad 100644
--- a/runtime/doc/treesitter.txt
+++ b/runtime/doc/treesitter.txt
@@ -841,6 +841,28 @@ get_files({lang}, {query_name}, {is_included})
         string[] query_files List of files to load for given query and
         language
 
+lint({buf}, {opts})                              *vim.treesitter.query.lint()*
+    Lint treesitter queries using installed parser, or clear lint errors.
+
+    Use |treesitter-parsers| in runtimepath to check the query file in {buf}
+    for errors:
+
+    • verify that used nodes are valid identifiers in the grammar.
+    • verify that predicates and directives are valid.
+    • verify that top-level s-expressions are valid.
+
+    The found diagnostics are reported using |diagnostic-api|. By default, the
+    parser used for verification is determined by the containing folder of the
+    query file, e.g., if the path is `**/lua/highlights.scm` , the parser for the `lua` language will be used.
+
+    Parameters: ~
+      • {buf}   (integer) Buffer handle
+      • {opts}  (QueryLinterOpts|nil) Optional keyword arguments:
+                • langs (string|string[]|nil) Language(s) to use for checking
+                  the query. If multiple languages are specified, queries are
+                  validated for all of them
+                • clear (boolean) if `true`, just clear current lint errors
+
 list_directives()                     *vim.treesitter.query.list_directives()*
     Lists the currently available directives to use in queries.