path: root/src/gen/gen_lsp.lua

#!/usr/bin/env -S nvim -l
-- Generates lua-ls annotations for lsp.

local USAGE = [[
Generates lua-ls annotations for lsp.

Also updates types in runtime/lua/vim/lsp/protocol.lua

Usage:
  src/gen/gen_lsp.lua [options]

Options:
  --version <version>  LSP version to use (default: 3.18)
  --out <out>          Output file (default: runtime/lua/vim/lsp/_meta/protocol.lua)
  --help               Print this help message
]]

--- The LSP protocol JSON data (it's partial, non-exhaustive).
--- https://raw.githubusercontent.com/microsoft/language-server-protocol/gh-pages/_specifications/lsp/3.18/metaModel/metaModel.schema.json
--- @class vim._gen_lsp.Protocol
--- @field requests vim._gen_lsp.Request[]
--- @field notifications vim._gen_lsp.Notification[]
--- @field structures vim._gen_lsp.Structure[]
--- @field enumerations vim._gen_lsp.Enumeration[]
--- @field typeAliases vim._gen_lsp.TypeAlias[]

--- @class vim._gen_lsp.Notification
--- @field deprecated? string
--- @field documentation? string
--- @field messageDirection string
--- @field clientCapability? string
--- @field serverCapability? string
--- @field method vim.lsp.protocol.Method
--- @field params? any
--- @field proposed? boolean
--- @field registrationMethod? string
--- @field registrationOptions? any
--- @field since? string

--- @class vim._gen_lsp.Request : vim._gen_lsp.Notification
--- @field errorData? any
--- @field partialResult? any
--- @field result any

--- @class vim._gen_lsp.Structure translated to @class
--- @field deprecated? string
--- @field documentation? string
--- @field extends? { kind: string, name: string }[]
--- @field mixins? { kind: string, name: string }[]
--- @field name string
--- @field properties? vim._gen_lsp.Property[]  members, translated to @field
--- @field proposed? boolean
--- @field since? string

--- @class vim._gen_lsp.StructureLiteral translated to anonymous @class.
--- @field deprecated? string
--- @field description? string
--- @field properties vim._gen_lsp.Property[]
--- @field proposed? boolean
--- @field since? string

--- @class vim._gen_lsp.Property translated to @field
--- @field deprecated? string
--- @field documentation? string
--- @field name string
--- @field optional? boolean
--- @field proposed? boolean
--- @field since? string
--- @field type { kind: string, name: string }

--- @class vim._gen_lsp.Enumeration translated to @enum
--- @field deprecated string?
--- @field documentation string?
--- @field name string?
--- @field proposed boolean?
--- @field since string?
--- @field suportsCustomValues boolean?
--- @field values { name: string, value: string, documentation?: string, since?: string }[]

--- @class vim._gen_lsp.TypeAlias translated to @alias
--- @field deprecated? string?
--- @field documentation? string
--- @field name string
--- @field proposed? boolean
--- @field since? string
--- @field type vim._gen_lsp.Type

--- @class vim._gen_lsp.Type
--- @field kind string a common field for all Types.
--- @field name? string for ReferenceType, BaseType
--- @field element? any for ArrayType
--- @field items? vim._gen_lsp.Type[] for OrType, AndType
--- @field key? vim._gen_lsp.Type for MapType
--- @field value? string|vim._gen_lsp.Type for StringLiteralType, MapType, StructureLiteralType

--- @param fname string
--- @param text string
local function tofile(fname, text)
  local f = assert(io.open(fname, 'w'), ('failed to open: %s'):format(fname))
  f:write(text)
  f:close()
  print('Written to:', fname)
end

---@param opt vim._gen_lsp.opt
---@return vim._gen_lsp.Protocol
local function read_json(opt)
  local uri = 'https://raw.githubusercontent.com/microsoft/language-server-protocol/gh-pages/_specifications/lsp/'
    .. opt.version
    .. '/metaModel/metaModel.json'
  print('Reading ' .. uri)

  local res = vim.system({ 'curl', '--no-progress-meter', uri, '-o', '-' }):wait()
  if res.code ~= 0 or (res.stdout or ''):len() < 999 then
    print(('URL failed: %s'):format(uri))
    vim.print(res)
    error(res.stdout)
  end
  return vim.json.decode(res.stdout)
end

--- Gets the Lua symbol for a given fully-qualified LSP method name.
--- @param s string
--- @return string
local function to_luaname(s)
  -- "$/" prefix is special: https://microsoft.github.io/language-server-protocol/specification/#dollarRequests
  return (s:gsub('^%$', 'dollar'):gsub('/', '_'))
end

--- @param a vim._gen_lsp.Notification
--- @param b vim._gen_lsp.Notification
--- @return boolean
local function compare_method(a, b)
  return to_luaname(a.method) < to_luaname(b.method)
end

--- @param item vim._gen_lsp.Request|vim._gen_lsp.Notification
--- @return string?
local function registration_provider(item)
  local server_capability = item.serverCapability
  if not server_capability then
    return nil
  end
  if vim.startswith(server_capability, 'workspace.') then
    return server_capability
  end
  return server_capability:match('^[^%.]+')
end

---@param structures table<string,vim._gen_lsp.Structure>
---@param type vim._gen_lsp.Type
---@param seen? table<string,true>
---@return boolean
local function supports_static_registration(structures, type, seen)
  if type.kind == 'reference' then
    if type.name == 'StaticRegistrationOptions' then
      return true
    end

    seen = seen or {}
    if seen[type.name] then
      return false
    end
    seen[type.name] = true

    local structure = structures[type.name]
    if not structure then
      return false
    end
    local bases = {}
    vim.list_extend(bases, structure.extends or {})
    vim.list_extend(bases, structure.mixins or {})
    for _, base in ipairs(bases) do
      if supports_static_registration(structures, base, seen) then
        return true
      end
    end
  elseif type.kind == 'and' or type.kind == 'or' then
    for _, item in ipairs(type.items) do
      if supports_static_registration(structures, item, seen) then
        return true
      end
    end
  end

  return false
end

---@param protocol vim._gen_lsp.Protocol
local function write_to_vim_protocol(protocol)
  local all = {} --- @type (vim._gen_lsp.Request|vim._gen_lsp.Notification)[]
  vim.list_extend(all, protocol.notifications)
  vim.list_extend(all, protocol.requests)

  local structures = {} --- @type table<string,vim._gen_lsp.Structure>
  for _, structure in ipairs(protocol.structures) do
    structures[structure.name] = structure
  end

  table.sort(all, compare_method)
  table.sort(protocol.requests, compare_method)
  table.sort(protocol.notifications, compare_method)

  local output = { '-- Generated by gen_lsp.lua, keep at end of file.' }

  do -- methods
    for _, dir in ipairs({ 'clientToServer', 'serverToClient' }) do
      local dir1 = dir:sub(1, 1):upper() .. dir:sub(2)
      local alias = ('vim.lsp.protocol.Method.%s'):format(dir1)
      for _, b in ipairs({
        { title = 'Request', methods = protocol.requests },
        { title = 'Notification', methods = protocol.notifications },
      }) do
        output[#output + 1] = ('--- LSP %s (direction: %s)'):format(b.title, dir)
        output[#output + 1] = ('--- @alias %s.%s'):format(alias, b.title)
        for _, item in ipairs(b.methods) do
          if item.messageDirection == dir or item.messageDirection == 'both' then
            output[#output + 1] = ("--- | '%s',"):format(item.method)
          end
        end
        output[#output + 1] = ''
      end

      vim.list_extend(output, {
        ('--- LSP Message (direction: %s).'):format(dir),
        ('--- @alias %s'):format(alias),
        ('--- | %s.Request'):format(alias),
        ('--- | %s.Notification'):format(alias),
        '',
      })
    end

    vim.list_extend(output, {
      '--- @alias vim.lsp.protocol.Method',
      '--- | vim.lsp.protocol.Method.ClientToServer',
      '--- | vim.lsp.protocol.Method.ServerToClient',
      '',
      '-- Generated by gen_lsp.lua, keep at end of file.',
      '--- @deprecated Use `vim.lsp.protocol.Method` instead.',
      '--- @enum vim.lsp.protocol.Methods',
      '--- @see https://microsoft.github.io/language-server-protocol/specification/#metaModel',
      '--- LSP method names.',
      'protocol.Methods = {',
    })

    for _, item in ipairs(all) do
      if item.method then
        if item.documentation then
          local document = vim.split(item.documentation, '\n?\n', { trimempty = true })
          for _, docstring in ipairs(document) do
            output[#output + 1] = '  --- ' .. docstring
          end
        end
        output[#output + 1] = ("  %s = '%s',"):format(to_luaname(item.method), item.method)
      end
    end
    output[#output + 1] = '}'
  end

  do -- registrationMethods
    local found = {} --- @type table<string, boolean>
    vim.list_extend(output, {
      '',
      '-- Generated by gen_lsp.lua, keep at end of file.',
      '--- LSP registration methods',
      '---@alias vim.lsp.protocol.Method.Registration',
    })
    for _, item in ipairs(all) do
      if item.registrationMethod and not found[item.registrationMethod] then
        vim.list_extend(output, {
          ("--- | '%s'"):format(item.registrationMethod or item.method),
        })
        found[item.registrationMethod or item.method] = true
      end
    end
  end

  do -- capabilities
    vim.list_extend(output, {
      '',
      '-- stylua: ignore start',
      '-- Generated by gen_lsp.lua, keep at end of file.',
      '--- Maps method names to the required client capability',
      'protocol._provider_to_client_registration = {',
    })

    local providers = {} --- @type table<string, string>
    for _, item in ipairs(all) do
      local provider = registration_provider(item)
      if item.registrationOptions and not providers[provider] and item.clientCapability then
        if
          item.clientCapability == item.serverCapability
          and not (item.serverCapability and vim.startswith(item.serverCapability, 'workspace.'))
        then
          provider = nil
        end
        local key = provider or item.method
        providers[key] = item.clientCapability
      end
    end

    ---@type { provider: string, path : string }[]
    local found_entries = {}
    for key, value in pairs(providers) do
      found_entries[#found_entries + 1] = { provider = key, path = value }
    end
    table.sort(found_entries, function(a, b)
      return a.provider < b.provider
    end)
    for _, entry in ipairs(found_entries) do
      output[#output + 1] = ("  ['%s'] = { %s },"):format(
        entry.provider,
        "'" .. entry.path:gsub('%.', "', '") .. "'"
      )
    end

    output[#output + 1] = '}'
    output[#output + 1] = '-- stylua: ignore end'

    vim.list_extend(output, {
      '',
      '-- stylua: ignore start',
      '-- Generated by gen_lsp.lua, keep at end of file.',
      '--- Maps method names to dynamic/static registration providers',
      'protocol._request_name_to_registration_provider = {',
    })

    for _, item in ipairs(all) do
      local provider = registration_provider(item) or item.method
      output[#output + 1] = ("  ['%s'] = '%s',"):format(item.method, provider)
    end

    output[#output +