feat!: update tier 1 parsers to versions

.github/workflows/update-parsers.yml

@@ -10,7 +10,11 @@ env:
 
 jobs:
   update-parsers:
-    name: Update parsers
+    strategy:
+      fail-fast: false
+      matrix:
+        tier: [1, 2]
+    name: Update parsers tier ${{ matrix.tier }}
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v4
@@ -35,7 +39,7 @@ jobs:
           (cd "$BIN_DIR"; unzip stylua*.zip)
 
       - name: Update parsers
-        run: ./scripts/update-parsers.lua
+        run: ./scripts/update-parsers.lua --tier=${{ matrix.tier }}
 
       - name: Create Pull Request
         uses: peter-evans/create-pull-request@v7
@@ -44,12 +48,13 @@ jobs:
           token: ${{ steps.app-token.outputs.token }}
           sign-commits: true
           commit-message: "bot(parsers): update ${{ env.UPDATED_PARSERS }}"
-          title: "Update parsers: ${{ env.UPDATED_PARSERS }}"
+          title: "Update parsers (tier ${{ matrix.tier }}): ${{ env.UPDATED_PARSERS }}"
           body: "[beep boop](https://github.com/peter-evans/create-pull-request)"
-          branch: update-parsers-pr
+          branch: update-parsers-tier-${{ matrix.tier }}
           base: ${{ github.head_ref }}
 
       - name: Enable Pull Request Automerge
+        if: ${{ matrix.tier == 2 }}
         env:
           GH_TOKEN: ${{ steps.app-token.outputs.token }}
-        run: gh pr merge --rebase --auto update-parsers-pr
+        run: gh pr merge --rebase --auto update-parsers-tier-2

CONTRIBUTING.md

@@ -36,6 +36,11 @@ zimbu = {
 
 **Note:** The "maintainers" here refers to the person maintaining the **queries** in `nvim-treesitter`, not the parser maintainers (who likely don't use Neovim). The maintainers' duty is to review issues and PRs related to the query and to keep them updated with respect to parser changes.
 
+**Note:** To qualify for Tier 1 ("stable"), a parser needs to
+ * make releases following semver (_patch_ for fixes not affecting queries; _minor_ for changes introducing new nodes or patterns; _major_ for changes removing nodes or previously valid patterns);
+ * provide WASM release artifacts;
+ * include and maintain reference queries.
+
 2. If the parser name is not the same as the Vim filetype, add an entry to the `filetypes` table in `plugin/filetypes.lua`:
 
 ```lua

TODO.md

@@ -4,8 +4,6 @@ This document lists the planned and finished changes in this rewrite towards [Nv
 
 ## TODO
 
-- [ ] **`parsers.lua`:** track versioned releases for tier 1
-- [ ] **`parsers.lua`:** add WASM support (tier 1)
 - [ ] **`install.lua`:** migrate to async v2
 - [ ] **tests:** remove custom crate, plenary dependency
 - [ ] **documentation:** consolidate, autogenerate?
@@ -29,3 +27,4 @@ This document lists the planned and finished changes in this rewrite towards [Nv
 - [X] remove locals from highlighting (cf. https://github.com/nvim-treesitter/nvim-treesitter/issues/3944#issuecomment-1458782497)
 - [X] drop ensure_install (replace with install)
 - [X] **CI:** switch to ts_query_ls, add update readme as check (remove update job)
+- [X] **CI:** track versioned releases for tier 1

scripts/install-parsers.lua

@@ -2,7 +2,7 @@
 
 local generate = false
 local update = false
-local max_jobs = nil ---@as integer
+local max_jobs = nil ---@type integer?
 local parsers = {}
 for i = 1, #_G.arg do
   if _G.arg[i] == '--generate' then

scripts/update-parsers.lua

@@ -1,4 +1,18 @@
 #!/usr/bin/env -S nvim -l
+-- Update parsers to latest version (tier 1, stable) or commit (tier 2, unstable)
+--
+-- Usage:
+-- nvim -l update-parsers.lua            # update all (stable and unstable) parsers
+-- nvim -l update-parsers.lua --tier=1   # update stable parsers to latest version
+-- nvim -l update-parsers.lua --tier=2   # update unstable parsers to latest commit
+
+local tier = nil ---@type integer?
+for i = 1, #_G.arg do
+  if _G.arg[i]:find('^%-%-tier=') then
+    tier = tonumber(_G.arg[i]:match('=(%d+)'))
+  end
+end
+
 vim.opt.runtimepath:append('.')
 local util = require('nvim-treesitter.util')
 local parsers = require('nvim-treesitter.parsers')
@@ -8,9 +22,21 @@ local updates = {} ---@type string[]
 
 -- check for new revisions
 for k, p in pairs(parsers) do
-  if p.tier <= 2 and p.install_info then
+  if p.tier <= 2 and (tier == nil or p.tier == tier) and p.install_info then
     print('Updating ' .. k)
-    jobs[k] = vim.system({ 'git', 'ls-remote', p.install_info.url })
+    local cmd = p.tier == 1
+        and {
+          'git',
+          '-c',
+          'versionsort.suffix=-',
+          'ls-remote',
+          '--tags',
+          '--refs',
+          '--sort=v:refname',
+          p.install_info.url,
+        }
+      or { 'git', 'ls-remote', p.install_info.url }
+    jobs[k] = vim.system(cmd)
   end
 
   if #vim.tbl_keys(jobs) % 100 == 0 or next(parsers, k) == nil then
@@ -21,18 +47,23 @@ for k, p in pairs(parsers) do
       local info = parsers[name].install_info
       assert(info)
 
-      local branch = info.branch
-      local line = 1
-      if branch then
-        for j, l in ipairs(stdout) do
-          if l:find(vim.pesc(branch)) then
-            line = j
-            break
+      local sha ---@type string
+      if parsers[name].tier == 1 then
+        sha = stdout[#stdout - 1]:match('v[%d%.]+$')
+      else
+        local branch = info.branch
+        local line = 1
+        if branch then
+          for j, l in ipairs(stdout) do
+            if l:find(vim.pesc(branch)) then
+              line = j
+              break
+            end
           end
         end
+        sha = vim.split(stdout[line], '\t')[1]
       end
 
-      local sha = vim.split(stdout[line], '\t')[1]
       if info.revision ~= sha then
         info.revision = sha
         updates[#updates + 1] = name