feat(lua): add vim.async

Problem: Nvim has many Lua APIs that start callback-driven work: timers,
jobs, libuv handles, and other event-loop tasks. Callers that need to
sequence or cancel that work have to build their own coroutine wrappers,
task bookkeeping, and cleanup rules. This makes async control flow hard
to share, test, and document.

Solution: Add `vim.async`, a structured-concurrency module vendored from
async.nvim. It provides task handles, await/pawait helpers,
sleep/timeout helpers, completion-order iteration, and semaphores on top
of Nvim's event loop.

The API follows the same broad model as Trio: async work has an owner,
tasks are awaited explicitly, and cancellation is cooperative. Include
generated vimdoc with an introductory overview and examples, a news
entry, and functional tests for the new module.

AI-assisted

1 files changed, 60 insertions, 7 deletions

diff --git a/src/gen/gen_vimdoc.lua b/src/gen/gen_vimdoc.lua
index 4d92c94be8..a2a5043851 100755
--- a/src/gen/gen_vimdoc.lua
+++ b/src/gen/gen_vimdoc.lua
@@ -61,6 +61,9 @@ local INDENTATION = 4
 --- @field fn_helptag_fmt? fun(fun: nvim.gen_vimdoc.HelptagTarget): string
 ---
 --- @field append_only? string[]
+---
+--- Merge parsed files into the first section instead of rendering one section per file.
+--- @field merge_files? boolean
 
 ---@alias nvim.gen_vimdoc.HelptagTarget
 ---| nvim.luacats.parser.fun
@@ -359,6 +362,35 @@ local config = {
       return fmt('lsp-%s', name:lower())
     end,
   },
+  async = {
+    filename = 'lua-async.txt',
+    section_order = {
+      'async.lua',
+    },
+    merge_files = true,
+    files = {
+      'runtime/lua/vim/async.lua',
+      'runtime/lua/vim/async/_core.lua',
+      'runtime/lua/vim/async/_semaphore.lua',
+    },
+    section_fmt = function()
+      return 'Lua module: vim.async'
+    end,
+    helptag_fmt = function()
+      return 'lua-async'
+    end,
+    fn_xform = function(fun)
+      if fun.module == 'vim.async._core' or fun.module == 'vim.async._semaphore' then
+        fun.module = 'vim.async'
+      end
+      if fun.name == 'new_semaphore' then
+        fun.name = 'semaphore'
+      end
+      if fun.classvar == 'M' then
+        fun.classvar = nil
+      end
+    end,
+  },
   diagnostic = {
     filename = 'diagnostic.txt',
     section_order = {
@@ -1248,6 +1280,10 @@ local function gen_target(cfg)
     end
   end
 
+  local merged_classes = {} --- @type table<string,nvim.luacats.parser.class>
+  local merged_funs = {} --- @type nvim.luacats.parser.fun[]
+  local merged_briefs = {} --- @type string[]
+
   for f, r in vim.spairs(file_results) do
     local classes, funs, briefs = r[1], r[2], r[3]
 
@@ -1267,14 +1303,31 @@ local function gen_target(cfg)
 
     print('    Processing file:', f)
 
-    -- FIXME: Using f_base will confuse `_meta/protocol.lua` with `protocol.lua`
-    local f_base = vim.fs.basename(f)
-    sections[f_base] = make_section(
-      f_base,
+    if cfg.merge_files then
+      merged_classes = vim.tbl_extend('error', merged_classes, classes)
+      vim.list_extend(merged_funs, funs)
+      vim.list_extend(merged_briefs, briefs)
+    else
+      -- FIXME: Using f_base will confuse `_meta/protocol.lua` with `protocol.lua`
+      local f_base = vim.fs.basename(f)
+      sections[f_base] = make_section(
+        f_base,
+        cfg,
+        render_briefs(briefs, cfg),
+        render_funs(funs, all_classes, cfg),
+        render_classes(classes, funs, cfg)
+      )
+    end
+  end
+
+  if cfg.merge_files then
+    local section_file = cfg.section_order[1]
+    sections[section_file] = make_section(
+      section_file,
       cfg,
-      render_briefs(briefs, cfg),
-      render_funs(funs, all_classes, cfg),
-      render_classes(classes, funs, cfg)
+      render_briefs(merged_briefs, cfg),
+      render_funs(merged_funs, all_classes, cfg),
+      render_classes(merged_classes, merged_funs, cfg)
     )
   end