feat(lua-types): types for vim.api.* (#24523)

.gitattributes

@@ -6,6 +6,8 @@ runtime/doc/*   linguist-documentation
 runtime/doc/builtin.txt linguist-generated
 
 runtime/lua/vim/_meta/vimfn.lua linguist-generated
+runtime/lua/vim/_meta/api.lua linguist-generated
+runtime/lua/vim/_meta/api_keysets.lua linguist-generated
 
 src/xdiff/**    linguist-vendored
 src/cjson/**    linguist-vendored

.github/workflows/api-docs.yml

@@ -23,8 +23,13 @@ jobs:
       - name: Install dependencies
         run: |
           sudo apt-get update
+          ./.github/scripts/install_deps.sh
           sudo env DEBIAN_FRONTEND=noninteractive apt-get install -y doxygen python3 python3-msgpack
 
+      - name: Build metadata
+        run: |
+          make api-metadata
+
       - name: Generate docs
         id: docs
         run: |

.luacheckrc

@@ -45,6 +45,7 @@ exclude_files = {
   'test/functional/fixtures/lua/syntax_error.lua',
   'runtime/lua/vim/treesitter/_meta.lua',
   'runtime/lua/vim/_meta/vimfn.lua',
+  'runtime/lua/vim/_meta/api.lua',
   'runtime/lua/vim/re.lua',
   'src/nvim/eval.lua',
 }

Makefile

@@ -131,7 +131,7 @@ functionaltest-lua: | nvim
 FORMAT=formatc formatlua format
 LINT=lintlua lintsh lintc clang-tidy lintcommit lint
 TEST=functionaltest unittest
-generated-sources benchmark $(FORMAT) $(LINT) $(TEST): | build/.ran-cmake
+generated-sources benchmark $(FORMAT) $(LINT) $(TEST) api-metadata: | build/.ran-cmake
 	$(CMAKE_PRG) --build build --target $@
 
 test: $(TEST)

runtime/doc/news.txt

@@ -132,6 +132,11 @@ The following new APIs and features were added.
 • |vim.wo| can now be double indexed for |:setlocal| behaviour. Currently only
   `0` for the buffer index is currently supported.
 
+• Lua type annotations for:
+  • `vim.*`
+  • `vim.fn.*`
+  • `vim.api.*`
+
 ==============================================================================
 CHANGED FEATURES                                                 *news-changed*
 

runtime/lua/vim/_meta/api_keysets.lua

@@ -0,0 +1,249 @@
+--- @meta
+-- THIS FILE IS GENERATED
+-- DO NOT EDIT
+error('Cannot require a meta file')
+
+--- @class vim.api.keyset.clear_autocmds
+--- @field buffer any
+--- @field event any
+--- @field group any
+--- @field pattern any
+
+--- @class vim.api.keyset.cmd
+--- @field cmd any
+--- @field range any
+--- @field count any
+--- @field reg any
+--- @field bang any
+--- @field args any
+--- @field magic any
+--- @field mods any
+--- @field nargs any
+--- @field addr any
+--- @field nextcmd any
+
+--- @class vim.api.keyset.cmd_magic
+--- @field file any
+--- @field bar any
+
+--- @class vim.api.keyset.cmd_mods
+--- @field silent any
+--- @field emsg_silent any
+--- @field unsilent any
+--- @field filter any
+--- @field sandbox any
+--- @field noautocmd any
+--- @field browse any
+--- @field confirm any
+--- @field hide any
+--- @field horizontal any
+--- @field keepalt any
+--- @field keepjumps any
+--- @field keepmarks any
+--- @field keeppatterns any
+--- @field lockmarks any
+--- @field noswapfile any
+--- @field tab any
+--- @field verbose any
+--- @field vertical any
+--- @field split any
+
+--- @class vim.api.keyset.cmd_mods_filter
+--- @field pattern any
+--- @field force any
+
+--- @class vim.api.keyset.cmd_opts
+--- @field output any
+
+--- @class vim.api.keyset.context
+--- @field types any
+
+--- @class vim.api.keyset.create_augroup
+--- @field clear any
+
+--- @class vim.api.keyset.create_autocmd
+--- @field buffer any
+--- @field callback any
+--- @field command any
+--- @field desc any
+--- @field group any
+--- @field nested any
+--- @field once any
+--- @field pattern any
+
+--- @class vim.api.keyset.echo_opts
+--- @field verbose any
+
+--- @class vim.api.keyset.eval_statusline
+--- @field winid any
+--- @field maxwidth any
+--- @field fillchar any
+--- @field highlights any
+--- @field use_winbar any
+--- @field use_tabline any
+--- @field use_statuscol_lnum any
+
+--- @class vim.api.keyset.exec_autocmds
+--- @field buffer any
+--- @field group any
+--- @field modeline any
+--- @field pattern any
+--- @field data any
+
+--- @class vim.api.keyset.exec_opts
+--- @field output any
+
+--- @class vim.api.keyset.float_config
+--- @field row any
+--- @field col any
+--- @field width any
+--- @field height any
+--- @field anchor any
+--- @field relative any
+--- @field win any
+--- @field bufpos any
+--- @field external any
+--- @field focusable any
+--- @field zindex any
+--- @field border any
+--- @field title any
+--- @field title_pos any
+--- @field style any
+--- @field noautocmd any
+
+--- @class vim.api.keyset.get_autocmds
+--- @field event any
+--- @field group any
+--- @field pattern any
+--- @field buffer any
+
+--- @class vim.api.keyset.get_commands
+--- @field builtin any
+
+--- @class vim.api.keyset.get_highlight
+--- @field id any
+--- @field name any
+--- @field link any
+
+--- @class vim.api.keyset.highlight
+--- @field bold any
+--- @field standout any
+--- @field strikethrough any
+--- @field underline any
+--- @field undercurl any
+--- @field underdouble any
+--- @field underdotted any
+--- @field underdashed any
+--- @field italic any
+--- @field reverse any
+--- @field altfont any
+--- @field nocombine any
+--- @field default_ any
+--- @field cterm any
+--- @field foreground any
+--- @field fg any
+--- @field background any
+--- @field bg any
+--- @field ctermfg any
+--- @field ctermbg any
+--- @field special any
+--- @field sp any
+--- @field link any
+--- @field global_link any
+--- @field fallback any
+--- @field blend any
+--- @field fg_indexed any
+--- @field bg_indexed any
+
+--- @class vim.api.keyset.highlight_cterm
+--- @field bold any
+--- @field standout any
+--- @field strikethrough any
+--- @field underline any
+--- @field undercurl any
+--- @field underdouble any
+--- @field underdotted any
+--- @field underdashed any
+--- @field italic any
+--- @field reverse any
+--- @field altfont any
+--- @field nocombine any
+
+--- @class vim.api.keyset.keymap
+--- @field noremap any
+--- @field nowait any
+--- @field silent any
+--- @field script any
+--- @field expr any
+--- @field unique any
+--- @field callback any
+--- @field desc any
+--- @field replace_keycodes any
+
+--- @class vim.api.keyset.option
+--- @field scope any
+--- @field win any
+--- @field buf any
+--- @field filetype any
+
+--- @class vim.api.keyset.runtime
+--- @field is_lua any
+--- @field do_source any
+
+--- @class vim.api.keyset.set_decoration_provider
+--- @field on_start any
+--- @field on_buf any
+--- @field on_win any
+--- @field on_line any
+--- @field on_end any
+--- @field _on_hl_def any
+--- @field _on_spell_nav any
+
+--- @class vim.api.keyset.set_extmark
+--- @field id any
+--- @field end_line any
+--- @field end_row any
+--- @field end_col any
+--- @field hl_group any
+--- @field virt_text any
+--- @field virt_text_pos any
+--- @field virt_text_win_col any
+--- @field virt_text_hide any
+--- @field hl_eol any
+--- @field hl_mode any
+--- @field ephemeral any
+--- @field priority any
+--- @field right_gravity any
+--- @field end_right_gravity any
+--- @field virt_lines any
+--- @field virt_lines_above any
+--- @field virt_lines_leftcol any
+--- @field strict any
+--- @field sign_text any
+--- @field sign_hl_group any
+--- @field number_hl_group any
+--- @field line_hl_group any
+--- @field cursorline_hl_group any
+--- @field conceal any
+--- @field spell any
+--- @field ui_watched any
+
+--- @class vim.api.keyset.user_command
+--- @field addr any
+--- @field bang any
+--- @field bar any
+--- @field complete any
+--- @field count any
+--- @field desc any
+--- @field force any
+--- @field keepscript any
+--- @field nargs any
+--- @field preview any
+--- @field range any
+--- @field register_ any
+
+--- @class vim.api.keyset.win_text_height
+--- @field start_row any
+--- @field end_row any
+--- @field start_vcol any
+--- @field end_vcol any

runtime/lua/vim/_meta/vimfn.lua

@@ -1,6 +1,7 @@
 --- @meta
 -- THIS FILE IS GENERATED
 -- DO NOT EDIT
+error('Cannot require a meta file')
 
 --- Return the absolute value of {expr}.  When {expr} evaluates to
 --- a |Float| abs() returns a |Float|.  When {expr} can be

scripts/gen_eval_files.lua

@@ -1,7 +1,35 @@
 #!/usr/bin/env -S nvim -l
 -- Generator for src/nvim/eval.lua
 
-local funcs = require('src/nvim/eval').funcs
+--- @class vim.api.metadata
+--- @field name string
+--- @field parameters {[1]:string,[2]:string}[]
+--- @field return_type string
+--- @field deprecated_since integer
+--- @field eval boolean
+--- @field fast boolean
+--- @field handler_id integer
+--- @field impl_name string
+--- @field lua boolean
+--- @field method boolean
+--- @field remote boolean
+--- @field since integer
+
+local LUA_META_HEADER = {
+  '--- @meta',
+  '-- THIS FILE IS GENERATED',
+  '-- DO NOT EDIT',
+  "error('Cannot require a meta file')",
+}
+
+local LUA_API_META_HEADER = {
+  '--- @meta',
+  '-- THIS FILE IS GENERATED',
+  '-- DO NOT EDIT',
+  "error('Cannot require a meta file')",
+  '',
+  'vim.api = {}',
+}
 
 local LUA_KEYWORDS = {
   ['and'] = true,
@@ -13,6 +41,47 @@ local LUA_KEYWORDS = {
   ['repeat'] = true,
 }
 
+local API_TYPES = {
+  Window = 'integer',
+  Tabpage = 'integer',
+  Buffer = 'integer',
+  Boolean = 'boolean',
+  Object = 'any',
+  Integer = 'integer',
+  String = 'string',
+  Array = 'any[]',
+  LuaRef = 'function',
+  Dictionary = 'table<string,any>',
+  Float = 'number',
+  void = '',
+}
+
+--- Convert an API type to Lua
+--- @param t string
+--- @return string
+local function api_type(t)
+  if t:match('^ArrayOf%(([z-aA-Z]+), %d+%') then
+    print(t:match('^ArrayOf%(([z-aA-Z]+), %d+%'))
+  end
+  local as0 = t:match('^ArrayOf%((.*)%)')
+  if as0 then
+    local as = vim.split(as0, ', ', { plain = true })
+    return api_type(as[1]) .. '[]'
+  end
+
+  local d = t:match('^Dict%((.*)%)')
+  if d then
+    return 'vim.api.keyset.' .. d
+  end
+
+  local d0 = t:match('^DictionaryOf%((.*)%)')
+  if d0 then
+    return 'table<string,' .. api_type(d0) .. '>'
+  end
+
+  return API_TYPES[t] or t
+end
+
 --- @param f string
 --- @param params {[1]:string,[2]:string}[]|true
 local function render_fun_sig(f, params)
@@ -41,8 +110,8 @@ end
 
 --- Uniquify names
 --- Fix any names that are lua keywords
---- @param params {[1]:string,[2]:string}[]
---- @return {[1]:string,[2]:string}[]
+--- @param params {[1]:string,[2]:string,[3]:string}[]
+--- @return {[1]:string,[2]:string,[3]:string}[]
 local function process_params(params)
   local seen = {} --- @type table<string,true>
   local sfx = 1
@@ -62,6 +131,170 @@ local function process_params(params)
   return params
 end
 
+--- @class vim.gen_vim_doc_fun
+--- @field signature string
+--- @field doc string[]
+--- @field parameters_doc table<string,string>
+--- @field return string[]
+--- @field seealso string[]
+--- @field annotations string[]
+
+--- @return table<string, vim.EvalFn>
+local function get_api_funcs()
+  local mpack_f = assert(io.open('build/api_metadata.mpack', 'rb'))
+  local metadata = vim.mpack.decode(mpack_f:read('*all')) --[[@as vim.api.metadata[] ]]
+  local ret = {} --- @type table<string, vim.EvalFn>
+
+  local doc_mpack_f = assert(io.open('runtime/doc/api.mpack', 'rb'))
+  local doc_metadata = vim.mpack.decode(doc_mpack_f:read('*all')) --[[@as table<string,vim.gen_vim_doc_fun>]]
+
+  for _, fun in ipairs(metadata) do
+    local fdoc = doc_metadata[fun.name]
+
+    local params = {} --- @type {[1]:string,[2]:string}[]
+    for _, p in ipairs(fun.parameters) do
+      local ptype, pname = p[1], p[2]
+      params[#params + 1] = {
+        pname,
+        api_type(ptype),
+        fdoc and fdoc.parameters_doc[pname] or nil,
+      }
+    end
+
+    local r = {
+      signature = 'NA',
+      name = fun.name,
+      params = params,
+      returns = api_type(fun.return_type),
+      deprecated = fun.deprecated_since ~= nil,
+    }
+
+    if fdoc then
+      if #fdoc.doc > 0 then
+        r.desc = table.concat(fdoc.doc, '\n')
+      end
+      r.return_desc = (fdoc['return'] or {})[1]
+    end
+
+    ret[fun.name] = r
+  end
+  return ret
+end
+
+--- Convert vimdoc references to markdown literals
+--- Convert vimdoc codeblocks to markdown codeblocks
+--- @param x string
+--- @return string
+local function norm_text(x)
+  return (
+    x:gsub('|([^ ]+)|', '`%1`')
+      :gsub('>lua', '\n```lua')
+      :gsub('>vim', '\n```vim')
+      :gsub('\n<$', '\n```')
+      :gsub('\n<\n', '\n```\n')
+  )
+end
+
+--- @param _f string
+--- @param fun vim.EvalFn
+--- @param write fun(line: string)
+local function render_api_fun(_f, fun, write)
+  if not vim.startswith(fun.name, 'nvim_') then
+    return
+  end
+
+  write('')
+
+  if vim.startswith(fun.name, 'nvim__') then
+    write('--- @private')
+  end
+
+  if fun.deprecated then
+    write('--- @deprecated')
+  end
+
+  local desc = fun.desc
+  if desc then
+    for _, l in ipairs(vim.split(norm_text(desc), '\n', { plain = true })) do
+      write('--- ' .. l)
+    end
+    write('---')
+  end
+
+  local param_names = {} --- @type string[]
+  local params = process_params(fun.params)
+  for _, p in ipairs(params) do
+    param_names[#param_names + 1] = p[1]
+    local pdesc = p[3]
+    if pdesc then
+      local pdesc_a = vim.split(norm_text(pdesc), '\n', { plain = true })
+      write('--- @param ' .. p[1] .. ' ' .. p[2] .. ' ' .. pdesc_a[1])
+      for i = 2, #pdesc_a do
+        if not pdesc_a[i] then
+          break
+        end
+        write('--- ' .. pdesc_a[i])
+      end
+    else
+      write('--- @param ' .. p[1] .. ' ' .. p[2])
+    end
+  end
+  if fun.returns ~= '' then
+    if fun.returns_desc then
+      write('--- @return ' .. fun.returns .. ' : ' .. fun.returns_desc)
+    else
+      write('--- @return ' .. fun.returns)
+    end
+  end
+  local param_str = table.concat(param_names, ', ')
+
+  write(string.format('function vim.api.%s(%s) end', fun.name, param_str))
+end
+
+--- @return table<string, vim.EvalFn>
+local function get_api_keysets()
+  local mpack_f = assert(io.open('build/api_metadata.mpack', 'rb'))
+
+  --- @diagnostic disable-next-line:no-unknown
+  local metadata = assert(vim.mpack.decode(mpack_f:read('*all')))
+
+  local ret = {} --- @type table<string, vim.EvalFn>
+
+  --- @type {[1]: string, [2]: {[1]: string, [2]: string}[] }[]
+  local keysets = metadata.keysets
+
+  for _, keyset in ipairs(keysets) do
+    local kname = keyset[1]
+    local kdef = keyset[2]
+    for _, field in ipairs(kdef) do
+      field[2] = api_type(field[2])
+    end
+    ret[kname] = {
+      signature = 'NA',
+      name = kname,
+      params = kdef,
+    }
+  end
+
+  return ret
+end
+
+--- @param _f string
+--- @param fun vim.EvalFn
+--- @param write fun(line: string)
+local function render_api_keyset(_f, fun, write)
+  write('')
+  write('--- @class vim.api.keyset.' .. fun.name)
+  for _, p in ipairs(fun.params) do
+    write('--- @field ' .. p[1] .. ' ' .. p[2])
+  end
+end
+
+--- @return table<string, vim.EvalFn>
+local function get_eval_funcs()
+  return require('src/nvim/eval').funcs
+end
+
 --- @param f string
 --- @param fun vim.EvalFn
 --- @param write fun(line: string)
@@ -83,6 +316,7 @@ local function render_vimfn(f, fun, write)
     local desc = fun.desc
 
     if desc then
+      --- @type string
       desc = desc:gsub('\n%s*\n%s*$', '\n')
       for _, l in ipairs(vim.split(desc, '\n', { plain = true })) do
         l = l:gsub('^      ', ''):gsub('\t', '  '):gsub('@', '\\@')
@@ -184,6 +418,7 @@ end
 
 --- @class nvim.gen_eval_files.elem
 --- @field path string
+--- @field funcs fun(): table<string, vim.EvalFn>
 --- @field render fun(f:string,fun:vim.EvalFn,write:fun(line:string))
 --- @field header? string[]
 --- @field footer? string[]
@@ -192,15 +427,25 @@ end
 local CONFIG = {
   {
     path = 'runtime/lua/vim/_meta/vimfn.lua',
+    header = LUA_META_HEADER,
+    funcs = get_eval_funcs,
     render = render_vimfn,
-    header = {
-      '--- @meta',
-      '-- THIS FILE IS GENERATED',
-      '-- DO NOT EDIT',
   },
+  {
+    path = 'runtime/lua/vim/_meta/api.lua',
+    header = LUA_API_META_HEADER,
+    funcs = get_api_funcs,
+    render = render_api_fun,
+  },
+  {
+    path = 'runtime/lua/vim/_meta/api_keysets.lua',
+    header = LUA_META_HEADER,
+    funcs = get_api_keysets,
+    render = render_api_keyset,
   },
   {
     path = 'runtime/doc/builtin.txt',
+    funcs = get_eval_funcs,
     render = render_eval_doc,
     header = {
       '*builtin.txt*	Nvim',
@@ -261,6 +506,8 @@ local function render(elem)
     write(l)
   end
 
+  local funcs = elem.funcs()
+
   --- @type string[]
   local fnames = vim.tbl_keys(funcs)
   table.sort(fnames)

src/nvim/CMakeLists.txt

@@ -857,4 +857,6 @@ add_custom_target(generated-sources DEPENDS
   ${NVIM_GENERATED_SOURCES}
 )
 
+add_custom_target(api-metadata DEPENDS ${API_METADATA})
+
 add_subdirectory(po)

src/nvim/eval.lua

@@ -16,9 +16,10 @@
 --- @field fast? boolean Function can run in |api-fast| events. Defaults to false.
 --- @field deprecated? true
 --- @field returns? string|false
+--- @field returns_desc? string
 --- @field signature string
 --- @field desc? string
---- @field params {[1]:string, [2]:string}[]
+--- @field params {[1]:string, [2]:string, [3]:string}[]
 --- @field lua? false Do not render type information
 --- @field tags? string[] Extra tags
 --- @field data? string Used by gen_eval.lua

src/nvim/generators/gen_api_dispatch.lua

@@ -71,7 +71,7 @@ local function add_keyset(val)
     if field.type ~= 'Object' then
       error 'not yet implemented: types other than Object'
     end
-    table.insert(keys, field.name)
+    table.insert(keys, {field.name, field.type})
   end
   table.insert(keysets, {val.keyset_name, keys})
 end
@@ -242,13 +242,16 @@ for _,keyset in ipairs(keysets) do
     return key
   end
 
+  local key_names = {}
   for i = 1,#keys do
-    if vim.endswith(keys[i], "_") then
-      keys[i] = string.sub(keys[i],1, #(keys[i]) - 1)
-      special[keys[i]] = true
+    local kname = keys[i][1]
+    if vim.endswith(kname, "_") then
+      kname = string.sub(kname,1, #kname - 1)
+      special[kname] = true
     end
+    key_names[i] = kname
   end
-  local neworder, hashfun = hashy.hashy_hash(name, keys, function (idx)
+  local neworder, hashfun = hashy.hashy_hash(name, key_names, function (idx)
     return name.."_table["..idx.."].str"
   end)
 
@@ -502,6 +505,7 @@ output:write(hashfun)
 
 output:close()
 
+functions.keysets = keysets
 local mpack_output = io.open(mpack_outputf, 'wb')
 mpack_output:write(mpack.encode(functions))
 mpack_output:close()