feat: add "experimental" key to parsers

feat(ci): mark parsers as experimental in README

4 files changed, 56 insertions, 1 deletions

diff --git a/README.md b/README.md
index 24e6a7aa1..beb834e9d 100644
--- a/README.md
+++ b/README.md
@@ -140,6 +140,10 @@ For `nvim-treesitter` to support a specific feature for a specific language requ
 
 The following is a list of languages for which a parser can be installed through `:TSInstall`; a checked box means that `nvim-treesitter` also contains queries at least for the `highlight` module.
 
+Experimental parsers are parsers that are maintained, but not stable enough for
+daily use yet. They are excluded from automatic installation when
+`ensure_installed` is set to `"maintained"`.
+
 We are looking for maintainers to add more parsers and to write query files for their languages.
 
 <!--This section of the README is automatically updated by a CI job-->
diff --git a/lua/nvim-treesitter/parsers.lua b/lua/nvim-treesitter/parsers.lua
index cb3013a59..c54ebfa50 100644
--- a/lua/nvim-treesitter/parsers.lua
+++ b/lua/nvim-treesitter/parsers.lua
@@ -546,6 +546,8 @@ list.verilog = {
   },
   used_by = { "systemverilog" },
   maintainers = { "@zegervdv" },
+  -- The parser still uses API version 12, because it does not compile with 13
+  experimental = true,
 }
 
 -- Parsers for injections
@@ -772,6 +774,7 @@ function M.maintained_parsers()
   local has_tree_sitter_cli = vim.fn.executable "tree-sitter" == 1 and vim.fn.executable "node" == 1
   return vim.tbl_filter(function(lang)
     return M.list[lang].maintainers
+      and not M.list[lang].experimental
       and (has_tree_sitter_cli or not M.list[lang].install_info.requires_generate_from_grammar)
   end, M.available_parsers())
 end
diff --git a/scripts/update-readme.lua b/scripts/update-readme.lua
index 194f20551..2942a8ce6 100755
--- a/scripts/update-readme.lua
+++ b/scripts/update-readme.lua
@@ -19,7 +19,9 @@ for _, v in ipairs(sorted_parsers) do
     generated_text = generated_text
       .. "- [x] "
       .. link
-      .. " (maintained by "
+      .. " ("
+      .. (v.parser.experimental and "experimental, " or "")
+      .. "maintained by "
       .. table.concat(v.parser.maintainers, ", ")
       .. ")\n"
   else
diff --git a/tests/unit/parsers_spec.lua b/tests/unit/parsers_spec.lua
new file mode 100644
index 000000000..d40578b87
--- /dev/null
+++ b/tests/unit/parsers_spec.lua
@@ -0,0 +1,46 @@
+local stub = require "luassert.stub"
+local parsers = require "nvim-treesitter.parsers"
+
+describe("maintained_parsers", function()
+  before_each(function()
+    stub(vim.fn, "executable")
+  end)
+
+  after_each(function()
+    vim.fn.executable:clear()
+  end)
+
+  it("does not return experimental parsers", function()
+    local old_list = parsers.list
+    parsers.list = {
+      c = {
+        install_info = {
+          url = "https://github.com/tree-sitter/tree-sitter-c",
+          files = { "src/parser.c" },
+        },
+        maintainers = { "@vigoux" },
+      },
+      d = {
+        install_info = {
+          url = "https://github.com/CyberShadow/tree-sitter-d",
+          files = { "src/parser.c", "src/scanner.cc" },
+          requires_generate_from_grammar = true,
+        },
+        maintainers = { "@nawordar" },
+        experimental = true,
+      },
+      haskell = {
+        install_info = {
+          url = "https://github.com/tree-sitter/tree-sitter-haskell",
+          files = { "src/parser.c", "src/scanner.cc" },
+        },
+      },
+    }
+
+    local expected = { "c" }
+
+    assert.same(parsers.maintained_parsers(), expected)
+
+    parsers.list = old_list
+  end)
+end)