feat: deprecate lsp.color config and add warning for Neovim 0.12+ users

Author: sidlatau

README.md

@@ -276,14 +276,6 @@ require("flutter-tools").setup {
     auto_open = false -- if true this will open the outline automatically when it is first populated
   },
   lsp = {
-    color = { -- show the derived colours for dart variables
-      enabled = false, -- whether or not to highlight color variables at all, only supported on flutter >= 2.10
-      background = false, -- highlight the background
-      background_color = nil, -- required, when background is transparent (i.e. background_color = { r = 19, g = 17, b = 24},)
-      foreground = false, -- highlight the foreground
-      virtual_text = true, -- show the highlight using virtual text
-      virtual_text_str = "■", -- the virtual text character to highlight
-    },
     on_attach = my_custom_on_attach,
     capabilities = my_custom_capabilities, -- e.g. lsp_status capabilities
     --- OR you can specify a function to deactivate or change or control how the config is created
@@ -308,6 +300,30 @@ require("flutter-tools").setup {
 You can override any options available in the `lspconfig` setup, this call essentially wraps
 it and adds some extra `flutter` specific handlers and utilisation options.
 
+### Document colors
+
+Plugin-managed `lsp.color` rendering is deprecated and will be removed when flutter-tools.nvim requires Neovim `0.12+`.
+
+On Neovim `0.12+`, use the built-in LSP document color support instead:
+
+```lua
+vim.api.nvim_create_autocmd("LspAttach", {
+  callback = function(ev)
+    vim.lsp.document_color.enable(true, { bufnr = ev.buf })
+  end,
+})
+```
+
+If you want to opt out of Neovim's built-in document colors for some buffers:
+
+```lua
+vim.api.nvim_create_autocmd("LspAttach", {
+  callback = function(ev)
+    vim.lsp.document_color.enable(false, { bufnr = ev.buf })
+  end,
+})
+```
+
 **NOTE:**
 By default this plugin excludes analysis of the packages in the flutter SDK. If for example
 you jump to the definition of `StatelessWidget`, the lsp will not try and index the 100s (maybe 1000s) of

doc/flutter-tools.txt

@@ -312,14 +312,6 @@ both are set.
         auto_open = false -- if true this will open the outline automatically when it is first populated
       },
       lsp = {
-        color = { -- show the derived colours for dart variables
-          enabled = false, -- whether or not to highlight color variables at all, only supported on flutter >= 2.10
-          background = false, -- highlight the background
-          background_color = nil, -- required, when background is transparent (i.e. background_color = { r = 19, g = 17, b = 24},)
-          foreground = false, -- highlight the foreground
-          virtual_text = true, -- show the highlight using virtual text
-          virtual_text_str = "■", -- the virtual text character to highlight
-        },
         on_attach = my_custom_on_attach,
         capabilities = my_custom_capabilities, -- e.g. lsp_status capabilities
         --- OR you can specify a function to deactivate or change or control how the config is created
@@ -345,6 +337,32 @@ You can override any options available in the `lspconfig` setup, this call
 essentially wraps it and adds some extra `flutter` specific handlers and
 utilisation options.
 
+
+DOCUMENT COLORS ~
+
+Plugin-managed `lsp.color` rendering is deprecated and will be removed when
+flutter-tools.nvim requires Neovim `0.12+`.
+
+On Neovim `0.12+`, use the built-in LSP document color support instead:
+
+>lua
+    vim.api.nvim_create_autocmd("LspAttach", {
+      callback = function(ev)
+        vim.lsp.document_color.enable(true, { bufnr = ev.buf })
+      end,
+    })
+<
+
+If you want to opt out of Neovim's built-in document colors for some buffers:
+
+>lua
+    vim.api.nvim_create_autocmd("LspAttach", {
+      callback = function(ev)
+        vim.lsp.document_color.enable(false, { bufnr = ev.buf })
+      end,
+    })
+<
+
 **NOTE:** By default this plugin excludes analysis of the packages in the
 flutter SDK. If for example you jump to the definition of `StatelessWidget`,
 the lsp will not try and index the 100s (maybe 1000s) of files in that

lua/flutter-tools/config.lua

@@ -155,15 +155,46 @@ local deprecations = {
     fallback = "widget_guides",
     message = "please use 'widget_guides' instead",
   },
+  lsp = {
+    nested = {
+      color = {
+        when = function() return vim.fn.has("nvim-0.12") == 1 end,
+        message = "plugin-managed document colors are deprecated and will be removed when flutter-tools.nvim requires Neovim 0.12+. On Neovim 0.12+, use vim.lsp.document_color.enable() instead",
+      },
+    },
+  },
 }
 
+local function notify_deprecation(key, message)
+  vim.defer_fn(function()
+    ui.notify(fmt("%s is deprecated: %s", key, message), ui.WARN, { once = true })
+  end, 1000)
+end
+
+local function should_notify_deprecation(deprecation)
+  return not deprecation.when or deprecation.when()
+end
+
+local function handle_nested_deprecation(prefix, value, deprecation)
+  if type(value) ~= "table" or type(deprecation.nested) ~= "table" then return end
+  for key, nested_value in pairs(value) do
+    local nested_deprecation = deprecation.nested[key]
+    if nested_deprecation then
+      if nested_deprecation.message and should_notify_deprecation(nested_deprecation) then
+        notify_deprecation(("%s.%s"):format(prefix, key), nested_deprecation.message)
+      end
+      handle_nested_deprecation(("%s.%s"):format(prefix, key), nested_value, nested_deprecation)
+    end
+  end
+end
+
 local function handle_deprecation(key, value, conf)
   local deprecation = deprecations[key]
   if not deprecation then return end
-  vim.defer_fn(
-    function() ui.notify(fmt("%s is deprecated: %s", key, deprecation.message), ui.WARN) end,
-    1000
-  )
+  if deprecation.message and should_notify_deprecation(deprecation) then
+    notify_deprecation(key, deprecation.message)
+  end
+  handle_nested_deprecation(key, value, deprecation)
   if deprecation.fallback then conf[deprecation.fallback] = value end
 end
 

tests/config_spec.lua

@@ -0,0 +1,80 @@
+describe("config", function()
+  local config
+  local ui
+  local notifications
+  local original_has
+
+  before_each(function()
+    notifications = {}
+    original_has = vim.fn.has
+
+    package.loaded["flutter-tools.config"] = nil
+    package.loaded["flutter-tools.ui"] = nil
+
+    ui = require("flutter-tools.ui")
+    ui.notify = function(msg, level) table.insert(notifications, { msg = msg, level = level }) end
+
+    config = require("flutter-tools.config")
+  end)
+
+  after_each(function()
+    vim.fn.has = original_has
+    package.loaded["flutter-tools.config"] = nil
+    package.loaded["flutter-tools.ui"] = nil
+  end)
+
+  it("warns when lsp.color is configured on Neovim 0.12+", function()
+    vim.fn.has = function(feature)
+      if feature == "nvim-0.12" then return 1 end
+      return original_has(feature)
+    end
+
+    config.set({
+      lsp = {
+        color = {
+          enabled = true,
+        },
+      },
+    })
+
+    vim.wait(1200)
+
+    assert.equal(1, #notifications)
+    assert.equal(
+      "lsp.color is deprecated: plugin-managed document colors are deprecated and will be removed when flutter-tools.nvim requires Neovim 0.12+. On Neovim 0.12+, use vim.lsp.document_color.enable() instead",
+      notifications[1].msg
+    )
+    assert.equal(ui.WARN, notifications[1].level)
+  end)
+
+  it("does not warn when lsp.color is configured before Neovim 0.12", function()
+    vim.fn.has = function(feature)
+      if feature == "nvim-0.12" then return 0 end
+      return original_has(feature)
+    end
+
+    config.set({
+      lsp = {
+        color = {
+          enabled = true,
+        },
+      },
+    })
+
+    vim.wait(1200)
+
+    assert.same({}, notifications)
+  end)
+
+  it("does not warn when lsp.color is omitted", function()
+    config.set({
+      lsp = {
+        debug = config.debug_levels.DEBUG,
+      },
+    })
+
+    vim.wait(1200)
+
+    assert.same({}, notifications)
+  end)
+end)