improv+docs: better config validation to handle breaking changes

Closes #39.

Author: smjonas

README.md

@@ -1,5 +1,5 @@
 # live-command.nvim
-![version](https://img.shields.io/badge/version-2.1.0-brightgreen)
+![version](https://img.shields.io/badge/version-2.2.0-brightgreen)
 
 > :exclamation: Version 2.0 has been released with breaking changes! Be sure to check out the [migration guide](./migrate_to_v2.md).
 
@@ -74,20 +74,17 @@ an existing command to run on each keypress, specified via the `cmd` field.
 
 ## :gear: Customization
 
-All of the following options can be set globally (affecting all custom commands), or per command.
-
-To change the default options globally, use the `defaults` table. The default settings are:
+If you wish to customize the plugin, supply any settings that differ from the defaults
+to the `setup` function. The following shows the default options:
 
 ```lua
 require("live-command").setup {
-  defaults = {
-    enable_highlighting = true,
-    inline_highlighting = true,
-    hl_groups = {
-      insertion = "DiffAdd",
-      deletion = "DiffDelete",
-      change = "DiffChange",
-    },
+  enable_highlighting = true,
+  inline_highlighting = true,
+  hl_groups = {
+    insertion = "DiffAdd",
+    deletion = "DiffDelete",
+    change = "DiffChange",
   },
 }
 ```

lua/live-command/config_validator.lua

@@ -14,23 +14,103 @@ local user_command = require("live-command.user_command")
 ---@field hl_groups livecmd.Config.HlGroups?
 ---@field commands table<string, livecmd.CommandSpec>
 
-local show_diagnostics_message = function(config)
-  local message = [[
-Version 2.0 of live-command.nvim has dropped support for the "args" and "range" keys in the command specification.
-The following commands in your configuration are affected: %s. Please remove or modify them.
-See the migration guide for more information: https://github.com/smjonas/live-command.nvim/blob/main/migrate_to_v2.md
-  ]]
+local get_affected_cmd_names = function(config, is_affected_cmd_fn)
   local affected_cmds = {}
   for cmd_name, cmd_spec in pairs(config.commands) do
-    if cmd_spec.args ~= nil or cmd_spec.range ~= nil then
+    if is_affected_cmd_fn(cmd_spec) then
       table.insert(affected_cmds, '"' .. cmd_name .. '"')
     end
   end
-  local cmd_names = table.concat(affected_cmds, ", ")
-  local formatted_message = string.format(message, cmd_names)
+  return table.concat(affected_cmds, ", "), #affected_cmds
+end
+
+local get_args_range_diagnostics_message = function(config)
+  local message = [[
+- Dropped support for the "args" and "range" keys in the command specification:
+The following commands in your configuration are affected: %s. Please remove or modify them.
+
+]]
+  local cmd_names, cmd_count = get_affected_cmd_names(config, function(cmd_spec)
+    return cmd_spec.args ~= nil or cmd_spec.range ~= nil
+  end)
+  if cmd_count == 0 then
+    return ""
+  end
+  return string.format(message, cmd_names)
+end
+
+local get_per_command_diagnostics_message = function(config)
+  local message = [[
+- Dropped support for per-command options:
+You can no longer set any of the options "enable_highlighting", "inline_highlighting" or "hl_groups" for individual commands.
+The following commands are affected: %s.
+Please just set the options for all commands like this:
+require("live-command").setup {
+  enable_highlighting = ...,
+  inline_highlighting = ...,
+  hl_groups = {
+    ...
+  },
+}
+
+]]
+  local cmd_names, cmd_count = get_affected_cmd_names(config, function(cmd_spec)
+    return cmd_spec.enable_highlighting ~= nil or cmd_spec.inline_highlighting ~= nil or cmd_spec.hl_groups ~= nil
+  end)
+  if cmd_count == 0 then
+    return ""
+  end
+  return string.format(message, cmd_names)
+end
+
+local get_defaults_diagnostics_message = function(config)
+  if config.defaults == nil then
+    return ""
+  end
+  return [[
+- Inlined the "defaults" option:
+To set any of the options "enable_highlighting", "inline_highlighting" or "hl_groups", you should no longer use the "defaults" table.
+Instead, just set the options like this:
+require("live-command").setup {
+  enable_highlighting = ...,
+  inline_highlighting = ...,
+  hl_groups = {
+    ...
+  },
+}
+
+]]
+end
+
+local show_diagnostics_message = function(config)
+  local message = [[
+Version 2.x of live-command.nvim has introduced some changes to the configuration:
+%s%s%sSee the migration guide for more information: https://github.com/smjonas/live-command.nvim/blob/main/migrate_to_v2.md
+]]
+  local warning_msg_1 = get_args_range_diagnostics_message(config)
+  local warning_msg_2 = get_per_command_diagnostics_message(config)
+  local warning_msg_3 = get_defaults_diagnostics_message(config)
+  local formatted_message = message:format(warning_msg_1, warning_msg_2, warning_msg_3)
   vim.notify(formatted_message, vim.log.levels.INFO)
 end
 
+local are_unsupported_features_used = function(config)
+  if config.defaults ~= nil then
+    return true
+  end
+  for _, cmd_spec in pairs(config.commands) do
+    if
+      cmd_spec.args ~= nil
+      or cmd_spec.range ~= nil
+      or cmd_spec.enable_highlighting ~= nil
+      or cmd_spec.inline_highlighting ~= nil
+      or cmd_spec.hl_groups ~= nil
+    then
+      return true
+    end
+  end
+end
+
 ---@param config livecmd.Config
 M.validate_config = function(config)
   vim.validate {
@@ -40,16 +120,14 @@ M.validate_config = function(config)
     hl_groups = { config.hl_groups, "table" },
     commands = { config.commands, "table" },
   }
-  for cmd_name, cmd_spec in pairs(config.commands) do
-    if cmd_spec.args ~= nil or cmd_spec.range ~= nil then
-      vim.notify(
-        '[live-command.nvim] Some unsupported features are used in your config. Please run ":LiveCommand diagnose" for details.',
-        vim.log.levels.WARN
-      )
-      user_command.register_argument_handler("diagnose", function()
-        show_diagnostics_message(config)
-      end)
-    end
+  if are_unsupported_features_used(config) then
+    vim.notify(
+      '[live-command.nvim] Some unsupported features are used in your config. Please run ":LiveCommand diagnose" for details.',
+      vim.log.levels.WARN
+    )
+    user_command.register_argument_handler("diagnose", function()
+      show_diagnostics_message(config)
+    end)
   end
 end
 

lua/live-command/init.lua

@@ -147,6 +147,6 @@ M.setup = function(user_config)
   create_autocmds()
 end
 
-M.version = "2.1.0"
+M.version = "2.2.0"
 
 return M

migrate_to_v2.md

@@ -1,23 +1,62 @@
 # Migration to v2.x
 This is a guide for users looking to migrate to version `2.x` of `live-command`.
-If you'd prefer to avoid breaking changes, you can pin the plugin to tag [`1.x`](https://github.com/smjonas/live-command.nvim/releases/tag/1.x) tag.
+If you'd prefer to avoid breaking changes, you can pin the plugin to the tag [`1.x`](https://github.com/smjonas/live-command.nvim/releases/tag/1.x).
 
 ## What's new in version 2.0?
 Version 2.0 is a complete rewrite, aimed at improving maintainability and future extensibility.
 It introduces a simplified user-facing API, alongside improvements to the architecture of the plugin and the addition of a new `:Preview` command.
 
 **Breaking changes**:
+- The `defaults` table containing the options `enable_highlighting`,
+  `inline_highlighting` and `hl_groups` has been inlined.
+- The options `enable_highlighting`, `inline_highlighting` and `hl_groups` can now no
+  longer be supplied per command. Instead use the top-level options.
 - Custom command specifications now only consist of a `cmd` value (a string). The `args`
-  and `range` fields have been removed. See [next section](#how-can-i-migrate-from-older-versions) for details.
+  and `range` fields have been removed.
 
-**New feature**:
+See [next section](#how-can-i-migrate-from-older-versions) on how to handle the breaking changes.
+
+**New features**:
 - A new generic `:Preview` command allows you to preview any command without needing to
   define it in your configuration. This is useful for testing `live-command`'s capabilities
   or for previewing commands you use infrequently, where creating a separate user command doesn't
   seem necessary. The command accepts a range or count. Example: `:'<,'>Preview norm daw`
   previews the deletion of the first word in the selected lines.
+- A new user command `:LiveCommand`. Running `:LiveCommand log` will print useful debugging
+  information while `:LiveCommand diagnose` shows instructions on how to adjust your config if you're
+  using features that are no longer supported.
 
 ## How can I migrate from older versions?
+### Adjusting the configuration
+In versions `1.x`, the following was a valid configuration:
+```lua
+require("live-command").setup {
+  defaults = {
+    inline_highlighting = false,
+  },
+  commands = {
+    Norm = {
+      cmd = norm, hl_groups = { deletion = "SomeHlGroup" },
+    },
+  },
+}
+```
+In version `2.x`, the `defaults` table has been inlined and you can no longer set some options for individual commands.
+If there are any issues with your configuration, a warning message will be displayed. You can then run `:LiveCommand diagnose`
+to view more detailed instructions on how to adjust your configuration.
+
+To fix the example configuration given above, change it to this:
+```lua
+require("live-command").setup {
+  inline_highlighting = false,
+  hl_groups = { deletion = "SomeHlGroup" },
+  commands = {
+    Norm = { cmd = norm },
+  },
+}
+```
+
+### A custom :Reg command
 In versions `1.x`, the following example demonstrated how to preview the results of a macro:
 ```lua
 local commands = {