feat(treesitter)!: don't parse tree in get_parser() or start()

**Problem:** `vim.treesitter.get_parser()` and `vim.treesitter.start()`
both parse the tree before returning it. This is problematic because if
this is a sync parse, it will stall the editor on large files. If it is
an async parse, the functions return stale trees.

**Solution:** Remove this parsing side effect and leave it to the user
to parse the returned trees, either synchronously or asynchronously.

6 files changed, 18 insertions, 9 deletions

diff --git a/runtime/doc/news.txt b/runtime/doc/news.txt
index 96f0ec1aa7..3b1c38b8d9 100644
--- a/runtime/doc/news.txt
+++ b/runtime/doc/news.txt
@@ -158,6 +158,11 @@ TREESITTER
   if no languages are explicitly registered.
 • |vim.treesitter.language.add()| returns `true` if a parser was loaded
   successfully and `nil,errmsg` otherwise instead of throwing an error.
+• |vim.treesitter.get_parser()| and |vim.treesitter.start()| no longer parse
+  the tree before returning. Scripts must call |LanguageTree:parse()| explicitly. >lua
+    local p = vim.treesitter.get_parser(0, 'c')
+    p:parse()
+<
 
 TUI
 
diff --git a/runtime/lua/vim/treesitter.lua b/runtime/lua/vim/treesitter.lua
index 9b7c8233d8..0269699dfd 100644
--- a/runtime/lua/vim/treesitter.lua
+++ b/runtime/lua/vim/treesitter.lua
@@ -61,8 +61,6 @@ function M._create_parser(bufnr, lang, opts)
     { on_bytes = bytes_cb, on_detach = detach_cb, on_reload = reload_cb, preview = true }
   )
 
-  self:parse(nil, function() end)
-
   return self
 end
 
diff --git a/runtime/lua/vim/treesitter/highlighter.lua b/runtime/lua/vim/treesitter/highlighter.lua
index 04e6ee8a9e..be138885d5 100644
--- a/runtime/lua/vim/treesitter/highlighter.lua
+++ b/runtime/lua/vim/treesitter/highlighter.lua
@@ -148,8 +148,6 @@ function TSHighlighter.new(tree, opts)
     vim.opt_local.spelloptions:append('noplainbuffer')
   end)
 
-  self.tree:parse(nil, function() end)
-
   return self
 end
 
diff --git a/test/functional/treesitter/language_spec.lua b/test/functional/treesitter/language_spec.lua
index 120a15d7f9..a93b1063a1 100644
--- a/test/functional/treesitter/language_spec.lua
+++ b/test/functional/treesitter/language_spec.lua
@@ -117,6 +117,7 @@ describe('treesitter language API', function()
       '<node translation_unit>',
       exec_lua(function()
         local langtree = vim.treesitter.get_parser(0, 'c')
+        langtree:parse()
         local tree = langtree:tree_for_range({ 1, 3, 1, 3 })
         return tostring(tree:root())
       end)
@@ -133,6 +134,7 @@ describe('treesitter language API', function()
       '<node translation_unit>',
       exec_lua(function()
         local langtree = vim.treesitter.get_parser(0, 'c')
+        langtree:parse()
         local tree = langtree:tree_for_range({ 10, 10, 10, 10 })
         return tostring(tree:root())
       end)
@@ -149,6 +151,7 @@ describe('treesitter language API', function()
       '<node primitive_type>',
       exec_lua(function()
         local langtree = vim.treesitter.get_parser(0, 'c')
+        langtree:parse()
         local node = langtree:named_node_for_range({ 1, 3, 1, 3 })
         return tostring(node)
       end)
@@ -160,6 +163,7 @@ describe('treesitter language API', function()
 
     exec_lua(function()
       _G.langtree = vim.treesitter.get_parser(0, 'lua')
+      _G.langtree:parse()
       _G.node = _G.langtree:node_for_range({ 0, 3, 0, 3 })
     end)
 
diff --git a/test/functional/treesitter/node_spec.lua b/test/functional/treesitter/node_spec.lua
index c87a56b160..9839022c5e 100644
--- a/test/functional/treesitter/node_spec.lua
+++ b/test/functional/treesitter/node_spec.lua
@@ -20,6 +20,7 @@ describe('treesitter node API', function()
     insert('F')
     exec_lua(function()
       vim.treesitter.start(0, 'lua')
+      vim.treesitter.get_parser(0):parse()
       vim.treesitter.get_node():tree()
       vim.treesitter.get_node():tree()
       collectgarbage()
@@ -45,6 +46,7 @@ describe('treesitter node API', function()
     -- this buffer doesn't have filetype set!
     insert('local foo = function() end')
     exec_lua(function()
+      vim.treesitter.get_parser(0, 'lua'):parse()
       _G.node = vim.treesitter.get_node({
         bufnr = 0,
         pos = { 0, 6 }, -- on "foo"
diff --git a/test/functional/treesitter/parser_spec.lua b/test/functional/treesitter/parser_spec.lua
index 6f9faddbe3..825c2b8f29 100644
--- a/test/functional/treesitter/parser_spec.lua
+++ b/test/functional/treesitter/parser_spec.lua
@@ -1142,11 +1142,13 @@ print()
       feed(':set ft=help<cr>')
 
       exec_lua(function()
-        vim.treesitter.get_parser(0, 'vimdoc', {
-          injections = {
-            vimdoc = '((codeblock (language) @injection.language (code) @injection.content) (#set! injection.include-children))',
-          },
-        })
+        vim.treesitter
+          .get_parser(0, 'vimdoc', {
+            injections = {
+              vimdoc = '((codeblock (language) @injection.language (code) @injection.content) (#set! injection.include-children))',
+            },
+          })
+          :parse()
       end)
     end)