feat: show warning if unsupported features are detected

Author: smjonas

README.md

@@ -70,34 +70,7 @@ require("live-command").setup {
 ```
 
 Each command you want to preview requires a name (must be upper-case) and the name of
-an existing command that is run on each keypress.
-
-Here is a list of available settings:
-
-| Key         | Type     | Description
-| ----------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------
-| cmd         | string   | The name of an existing command to preview.
-| args        | string? \| function(arg: string?, opts: table) -> string | Arguments passed to the command. If a function, takes in the options passed to the command and must return the transformed argument(s) `cmd` will be called with. `opts` has the same structure as the `opts` table passed to the `nvim_create_user_command` callback function. If `nil`, the arguments are supplied from the command-line while the user is typing the command.
-| range       | string?  | The range to prepend to the command. Set this to `""` if you don't want the new command to receive a count, e.g. when turning `:9Reg a` into `:norm 9@a`. If `nil`, the range will be supplied from the command entered.
-
-### Example
-The following example creates a `:Reg` command which allows you to preview the effects of macros (e.g. `:5Reg a` to run macro `a` five times).
-```lua
-local commands = {
-  Reg = {
-    cmd = "norm",
-    -- This will transform ":5Reg a" into ":norm 5@a"
-    args = function(opts)
-      return (opts.count == -1 and "" or opts.count) .. "@" .. opts.args
-    end,
-    range = "",
-  },
-}
-
-require("live-command").setup {
-  commands = commands,
-}
-```
+an existing command that is run on each keypress via the `cmd` field.
 
 ## :gear: Customization
 

lua/live-command/config_validator.lua

@@ -1,5 +1,7 @@
 local M = {}
 
+local user_command = require("live-command.user_command")
+
 ---@class livecmd.Config.HlGroups
 ---@field insertion string|false
 ---@field deletion string|false
@@ -12,6 +14,23 @@ local M = {}
 ---@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 affected_cmds = {}
+  for cmd_name, cmd_spec in pairs(config.commands) do
+    if cmd_spec.args ~= nil or cmd_spec.range ~= nil then
+      table.insert(affected_cmds, '"' .. cmd_name .. '"')
+    end
+  end
+  local cmd_names = table.concat(affected_cmds, ", ")
+  local formatted_message = string.format(message, cmd_names)
+  vim.notify(formatted_message, vim.log.levels.INFO)
+end
+
 ---@param config livecmd.Config
 M.validate_config = function(config)
   vim.validate {
@@ -21,6 +40,17 @@ 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
+  end
 end
 
 return M

migrate_to_v2.md

@@ -1,6 +1,6 @@
 # Migration to v2.0
 This is a guide for users that want to migrate to version `2.0` of `live-command`.
-If you want to stay on the previous major version, you can pin the plugin to the tag [`1.x`](https://github.com/smjonas/live-command.nvim/releases/tag/1.x).
+If you want to avoid any breaking changes, you can pin the plugin to the tag [`1.x`](https://github.com/smjonas/live-command.nvim/releases/tag/1.x).
 
 ## What has changed in version 2.0?
 Version 2.0 is a rewrite of the plugin for better maintainability and future extensibility.

tests/e2e_spec.lua

@@ -38,6 +38,12 @@ describe("create_preview_command works for", function()
     assert.are_same({ "First line", "line" }, get_lines())
   end)
 
+  it("norm command with range", function()
+    create_preview_cmd("Norm", { cmd = "norm" })
+    vim.cmd("1,2Norm daw")
+    assert.are_same({ "line", "line" }, get_lines())
+  end)
+
   it("g command", function()
     create_preview_cmd("G", { cmd = "g" })
     vim.cmd("G/Second/d")