Neovim 0.11 migration

[TheRealLorenz]

Based on #3494.

This PR introduces the minimal effort to port every configuration to neovim 0.11.The default_configuration field has most of the times everything that's needed, but there are come exceptions that where changed:

• commands field became raw calls to vim.api.nvim_buf_create_user_command inside on_attach.
• root_dir became:
  • root_markers whenever the file list was simple didn't need to mach *
  • if the logic was complicated, or needed to match something like '*.c', it was wrapped to work with vim.lsp.Config's root_dir.
• on_config_change became before_init. I don't actually know if this is the correct approach, but looking around the documentation of nvim-lspconfig a saw that it was defined as the function that gets called as soon as the config have root_dir, and so I thought before_init might be the closest alternative.
• docs.description became a luadoc annotation prefaced by @brief.
• single_file_support = false?

Needs #3666

[justinmk]

I think we should skip to Phase 2. The old configs have already been quasi-frozen for a few months. Now it's time to formalize that.

So I suggest:

• copy-paste all the old configs to lsp/*
• do the bare-minimum changes to make them work with vim.lsp.config

[TheRealLorenz]

• copy-paste all the old configs to lsp/*

• do the bare-minimum changes to make them work with vim.lsp.config

Ok, that's probably better. What about descriptions? Should I annotate the config table with them?

[justinmk]

Descriptions should probably be luadoc comments at the top of the config. Then we'll need to update the generator in this repo to read those. WDYT @lewis6991 ?

[lewis6991]

sgtm

[TheRealLorenz]

Update

Now I'll port the LSPs that I usually use first, just because I can test them more easily.

I added the register_commands function, because the old functions didn't seem very ergonomic for this new use case.

For the LuaDoc: should I annotate a local config = { ... } or can i just annotate while I return like I'm doing now?

[justinmk]

Sorry, I just remembered something:

The plan is to extend wrap_old_config() while adding files under lsp/ until all servers are supported.

The point of the wrapper was to not have to create configs under lsp/ until Phase 2. The wrapper, if possible, would make vim.lsp.config.enable('foo') work automatically by wrapping the old configs. Without having to write a bunch of per-config code.

If that's possible, then that's still the least-risk approach to start with.

[justinmk]

Suggested change

	function M.register_commands(commands)
	function M.def_commands(commands)

[TheRealLorenz]

Sorry, I just remembered something:

The plan is to extend wrap_old_config() while adding files under lsp/ until all servers are supported.

The point of the wrapper was to not have to create configs under lsp/ until Phase 2. The wrapper, if possible, would make vim.lsp.config.enable('foo') work automatically by wrapping the old configs. Without having to write a bunch of per-config code.

If that's possible, then that's still the least-risk approach to start with.

I didn't find a feasible approach to it, so I figured we could just port the configs. In the meanwhile I baked in some modifications that wuold fit the new configuration, but I'm more than happy to break things down in separate PRs.

If you prefer a more conservative approach, I could also remove the new Command interface and def_commands function.

I also thought would be smart to use builtin neovim 0.11 in the migrated configs, because those would be used obviously just in neovim>=0.11, but I could just make a really simple migration with little to no effect to the current configurations. This was also meant to use less functions fromlspconfig.utils, as I saw that was a future goal of the plugin.

[justinmk]

if a wrapper that works automatically isn't possible, then yes we should skip to Phase 2 and start migrating configs. and the old configs are frozen.

If you prefer a more conservative approach, I could also remove the new Command interface and def_commands function.

why is there a new Command interface? where did that requirement come from?

[TheRealLorenz]

why is there a new Command interface? where did that requirement come from?

Just because the old Commands had a weird syntax which required more complicated parsing (why is there a opt_alias table?). I get it was probably for compatibility issues, but now we can change things more freely.

That being said, I could revert it no problem.

For context, I'm referring to this (probably) over complicated function:
https://github.com/TheRealLorenz/nvim-lspconfig/blob/ea2e1e4dcf9860ee6d58369bb54b7dd246a6e0a1/lua/lspconfig/util.lua#L66C1-L84C7

This was my suggested solution:
https://github.com/TheRealLorenz/nvim-lspconfig/blob/ea2e1e4dcf9860ee6d58369bb54b7dd246a6e0a1/lua/lspconfig/util.lua#L98-L101

[justinmk]

The commands thing is not supported until we upstream (if necessary) to vim.lsp.config.

The entire purpose of this exercise is to stop depending on framework code in lspconfig, not to replace it with a new flavor.

If the new configs want to have "commands", then for now they will need to hardcode calls to nvim_buf_create_user_command.

Or else figure out a way to do Phase 1 only, and pause Phase 2 until we have a proper answer for the commands situation. neovim/neovim#28329

[TheRealLorenz]

The commands thing is not supported until we upstream (if necessary) to vim.lsp.config.

The entire purpose of this exercise is to stop depending on framework code in lspconfig, not to replace it with a new flavor.

If the new configs want to have "commands", then for now they will need to hardcode calls to nvim_buf_create_user_command.

Or else figure out a way to do Phase 1 only, and pause Phase 2 until we have a proper answer for the commands situation. neovim/neovim#28329

Fine with me to hardcode nvim_buf_create_user_command calls.

What about util.root_pattern()? In most cases it can simply be root_markers, but sometimes a little bit more complicated approach is needed. In that case should I also hardcode it? Then there's also async.run_job(), should I hardcode that one too? Or should we drop these more complicated features altogether?

These types of things are required in order to port more complicated configs (e.g. clangd or rust_analyzer) that have custom commands and/or custom setup logic.

[TheRealLorenz]

Update

• commands field became raw calls to vim.api.nvim_buf_create_user_command inside on_attach.
• root_dir became:
  • root_markers whenever the file list was simple didn't need to mach *
  • if the logic was complicated, or needed to match something like '*.c', it was wrapped to work with vim.lsp.Config's root_dir.
• on_config_change became before_init. I don't actually know if this is the correct approach, but looking around the documentation of nvim-lspconfig a saw that it was defined as the function that gets called as soon as the config have root_dir, and so I thought before_init might be the closest alternative.
• docs.description became a luadoc annotation prefaced by @brief.
• single_file_support = false?

Needs #3666

Started to port in alphabetical order. Skipping the ones with single_file_support = false and on_new_config for now.

[TheRealLorenz]

Probably LSPs which have single_file_support = false could simply be ported as something like

{
  ...
  root_dir = function (bufnr, done_callback)
    local root = -- compute root
    done_callback(root or vim.fs.dirname(vim.api.nvim_buf_get_name(bufnr))) -- either
    -- done_callback(root or vim.fn.getcwd()) -- or
  end,
  ...

[TheRealLorenz]

@justinmk Sorry to bother.

The "easier" migration is done, now there are just the LSPs which have single_file_support = false and on_new_config left.

Is it feasibile to move on_new_config to a plain before_init? I could wait for neovim/neovim#32287

What's the suggested way to handle single_file_support = false? workspace_required isn't currently available on neovim 0.11 as you already know.

I had an idea which consisted of:
lua

{
  root_dir = function(bufnr, done_callback)
    local root = -- compute root
    if root then
      done_callback(root)
      return
    end
  end,
}

Which shouldn't start the server given that done_callback is not called when the root is nil.

EDIT: Probably this PR could wait until those features are sorted out and implemented in neovim.

[TheRealLorenz]

There are just 31 LSPs which still need to be ported. If we decide to wait, we could temporarily port these configs as empty files which tells the user to use require('lspconfig')['<server_name>'].setup{} or simply not port them at all.

[lewis6991]

The version of vim.lsp.config in 0.11 was never intended to be useable by 100% of servers, more like 80-90%. We can punt the other server setups to 0.12+ when (or if) vim.lsp.config can accommodate those. Since there is only ~30 of them, maybe we can just list them as needing setup() to work?

[TheRealLorenz]

Just to have a reminder, these are the LSPs which rely on on_new_config:

• angularls
• apex_ls
• astro
• bqnlsp
• cadence
• codeqlls
• drools_lsp
• eslint
• glint
• haxe_language_server
• jsonnet_ls
• leanls
• mdx_analyzer
• omnisharp
• openedge_ls
• powershell_es
• relay_lsp
• sourcery
• tailwindcss
• vdmj
• volar
• zls

These are the ones which have single_file_support = false:

• biome
• bitbake_ls
• ccls
• delphi_ls
• efm
• gh_actions_ls
• matlab_ls
• oxlint
• postgres_lsp

[TheRealLorenz]

The version of vim.lsp.config in 0.11 was never intended to be useable by 100% of servers, more like 80-90%. We can punt the other server setups to 0.12+ when (or if) vim.lsp.config can accommodate those. Since there is only ~30 of them, maybe we can just list them as needing setup() to work?

Seems pretty reasonable to me. Should I also update the README and/or the docs?

[TheRealLorenz]

The README is now updated, but what about the docs? Probably the docgen and templates should be updated this new way of configuring servers is completely stable. So should I flag these new features as beta or something?

[aliou]

Hey! I've been using this branch for the past few days and noticed an unexpected side effect to this change:

• commands field became raw calls to vim.api.nvim_buf_create_user_command inside on_attach.

In my config, I have the following:

vim.lsp.config('*', {
  root_markers = { '.git', '.root' },
  on_attach = function(client, bufnr)
    -- Configure mappings for the current buffer based on the method the server supports.
    maps.on_attach(client, bufnr)

    vim.notify('Attached to ' .. client.name, vim.log.levels.DEBUG)
  end,
} --[[@as vim.lsp.Config]])

The on_attach callback is called for all of the enabled servers except the ones overriding on_attach (e.g. basedpyright).

This also occurs if I configure the server directly using vim.lsp.config('SERVER', { ... }).

I think this is because of the order files are present in the rtp, with lspconfig being after my config? In any case, since I don't use the commands created, I added this to after/lsp/basedpyright.lua:

return {
  on_attach = function(client, bufnr)
    local config_on_attach = vim.lsp.config['*'].on_attach
    if not config_on_attach then return end

    config_on_attach(client, bufnr)
  end
}

Is this how I am supposed to handle this or is there another way? Should there be a mention of this edge case in the readme?