feat!: breakdown code action callbacks

Instead of having a single `on_success` callback, we now have one per
code action kind.

Each callback receives a payload with the context of its corresponding
code action.

See the types in `helpers.lua` for details.

The `on_success` callback is now deprecated and will be removed soon.

README.md

@@ -72,25 +72,42 @@ local config = {
   encode_json = function(cspell_tbl)
   end,
 
+  ---@param payload UseSuggestionSuccess
+  on_use_suggestion = function(payload)
+  end
+
+  ---@param payload AddToJSONSuccess
+  on_add_to_json = function(payload)
+      -- For example, you can format the cspell config file after you add a word
+      os.execute(
+          string.format(
+              "jq -S '.words |= sort' %s > %s.tmp && mv %s.tmp %s",
+              payload.cspell_config_path,
+              payload.cspell_config_path,
+              payload.cspell_config_path,
+              payload.cspell_config_path
+          )
+      )
+  end
 
+  ---@param payload AddToDictionarySuccess
+  on_add_to_dictionary = function(payload)
+      -- For example, you can sort the dictionary after adding a word
+      os.execute(
+          string.format(
+              "sort %s -o %s",
+              payload.cspell_config_path,
+              payload.cspell_config_path
+          )
+      )
+  end
+
+  --- DEPRECATED
   --- Callback after a successful execution of a code action.
   ---@param cspell_config_file_path string|nil
   ---@param params GeneratorParams
-  ---@action_name 'use_suggestion'|'add_to_json'|'add_to_dictionary'
+  ---@param action_name 'use_suggestion'|'add_to_json'|'add_to_dictionary'
   on_success = function(cspell_config_file_path, params, action_name)
-      -- For example, you can format the cspell config file after you add a word
-      if action_name == 'add_to_json' then
-          os.execute(
-              string.format(
-                  "cat %s | jq -S '.words |= sort' | tee %s > /dev/null",
-                  cspell_config_file_path,
-                  cspell_config_file_path
-              )
-          )
-      end
-
-      -- Note: The cspell_config_file_path param could be nil for the
-      -- 'use_suggestion' action
   end
 }
 

lua/cspell/code_actions/init.lua

@@ -77,10 +77,27 @@ return make_builtin({
                             h.set_word(diagnostic, suggestion)
 
                             local on_success = code_action_config.on_success
+                            local on_use_suggestion = code_action_config.on_success
 
                             if on_success then
+                                vim.notify_once(
+                                    "The on_success callback is deprecated, use on_use_suggestion instead",
+                                    vim.log.levels.INFO,
+                                    { title = "cspell.nvim" }
+                                )
                                 on_success(cspell and cspell.path, params, "use_suggestion")
                             end
+
+                            if on_use_suggestion then
+                                ---@type UseSuggestionSuccess
+                                local payload = {
+                                    misspelled_word = diagnostic.user_data.misspelled,
+                                    suggestion = suggestion,
+                                    cspell_config_path = cspell and cspell.path,
+                                    generator_params = params,
+                                }
+                                on_use_suggestion(payload)
+                            end
                         end,
                     })
                 end

lua/cspell/code_actions/make_add_to_dictionary_action.lua

@@ -13,6 +13,7 @@ return function(opts)
     ---@type CSpellSourceConfig
     local code_action_config = opts.params:get_config()
     local on_success = code_action_config.on_success
+    local on_add_to_dictionary = code_action_config.on_add_to_dictionary
     -- The null-ls diagnostic reports the wrong range for the CSpell error if
     -- the line contains a unicode character.
     -- As a workaround, we read the misspelled word from the diagnostic's
@@ -45,8 +46,24 @@ return function(opts)
             h.set_word(opts.diagnostic, opts.word)
 
             if on_success then
+                vim.notify_once(
+                    "The on_success callback is deprecated, use on_add_to_dictionary instead",
+                    vim.log.levels.INFO,
+                    { title = "cspell.nvim" }
+                )
                 on_success(opts.cspell.path, opts.params, "add_to_dictionary")
             end
+
+            if on_add_to_dictionary then
+                ---@type AddToDictionarySuccess
+                local payload = {
+                    new_word = misspelled_word,
+                    generator_params = opts.params,
+                    cspell_config_path = opts.cspell.path,
+                    dictionary_path = opts.dictionary.path,
+                }
+                on_add_to_dictionary(payload)
+            end
         end,
     }
 end

lua/cspell/code_actions/make_add_to_json.lua

@@ -12,6 +12,7 @@ return function(opts)
     ---@type CSpellSourceConfig
     local code_action_config = opts.params:get_config()
     local on_success = code_action_config.on_success
+    local on_add_to_json = code_action_config.on_add_to_json
     local encode_json = code_action_config.encode_json or vim.json.encode
     -- The null-ls diagnostic reports the wrong range for the CSpell error if
     -- the line contains a unicode character.
@@ -48,8 +49,23 @@ return function(opts)
             h.set_word(opts.diagnostic, opts.word)
 
             if on_success then
+                vim.notify_once(
+                    "The on_success callback is deprecated, use on_add_to_json instead",
+                    vim.log.levels.INFO,
+                    { title = "cspell.nvim" }
+                )
                 on_success(cspell.path, opts.params, "add_to_json")
             end
+
+            if on_add_to_json then
+                ---@type AddToJSONSuccess
+                local add_to_json_success = {
+                    new_word = misspelled_word,
+                    cspell_config_path = cspell.path,
+                    generator_params = opts.params,
+                }
+                on_add_to_json(add_to_json_success)
+            end
         end,
     }
 end

lua/cspell/helpers.lua

@@ -261,3 +261,23 @@ return M
 ---@field decode_json function|nil
 ---@field encode_json function|nil
 ---@field on_success function|nil
+---@field on_add_to_json function|nil
+---@field on_add_to_dictionary function|nil
+---@field on_use_suggestion function|nil
+
+---@class UseSuggestionSuccess
+---@field misspelled_word string
+---@field suggestion string
+---@field cspell_config_path string|nil
+---@field generator_params GeneratorParams
+
+---@class AddToJSONSuccess
+---@field new_word string
+---@field cspell_config_path string
+---@field generator_params GeneratorParams
+
+---@class AddToDictionarySuccess
+---@field new_word string
+---@field cspell_config_path string
+---@field generator_params GeneratorParams
+---@field dictionary_path string