refactor: deprecate create_comment_suggestion

Author: jakubbortlik

README.md

@@ -204,5 +204,6 @@ These `keymaps` are active in the reviewer window (the diff view).
 ```
 c	Create a comment for the lines that the following {motion} moves over
 s	Create a suggestion for the lines that the following {motion} moves over
+S	Create a suggestion with preview in a new tab for the lines that the following {motion} moves over
 a	Jump to the comment in the discussion tree
 ```

doc/gitlab.nvim.txt

@@ -449,20 +449,19 @@ the configuration.
 
 REVIEWING AN MR                                  *gitlab.nvim.reviewing-an-mr*
 
-The `review` action will open a diff of the changes. You can leave comments
-using the `create_comment` action, and add suggestions for changes with the
-`create_comment_suggestion` command:
+The `review` action opens a diff of the changes (see |gitlab.nvim.review|).
+Alternatively, use `choose_merge_request` for more flexibility in choosing the
+MR (see |gitlab.nvim.choose_merge_request|).
 >lua
     require("gitlab").review()
-    require("gitlab").create_comment()
-    require("gitlab").create_comment_suggestion()
+    require("gitlab").choose_merge_request({ labels = {"include_mrs_with_label"} })
 <
-For suggesting changes you can use `create_comment_suggestion` in visual mode
-which prefills the comment window with Gitlab’s suggest changes
-<https://docs.gitlab.com/ee/user/project/merge_requests/reviews/suggestions.html>
-code block with prefilled code from the visual selection. Just like the
-summary, all the different kinds of comments are saved via the
-`keymaps.popup.perform_action` keybinding.
+You can leave comments in the reviewer windows using the `keymaps.reviewer`
+keybindings which work in normal mode as operators and in visual mode they
+create comments on the selected lines. Alternatively, you can use the
+`create_comment` action in your custom mappings (see
+|gitlab.nvim.create_comment|). See `settings.keymaps.popup` for the
+keybindings available in the popup windows.
 
 DRAFT NOTES                                       *gitlab.nvim.draft-comments*
 
@@ -883,27 +882,26 @@ gitlab.create_comment() ~
 Opens a popup to create a comment on the selected line(s) in the current
 buffer. Must be called when focused on the reviewer pane (see the
 |gitlab.nvim.review| command). In normal mode comments on the current line. In
-visual mode comments on the selected lines
+visual mode comments on the selected lines:
 >lua
   require("gitlab").create_comment()
+  require("gitlab").create_comment({ with_suggestion = true })
 <
-You can use the `keymaps.popup.perform_linewise_action` keybinding (by default
-`ZA`) to attach a file to the comment. After the comment is typed, submit it
-to Gitlab via the `keymaps.popup.perform_action` keybinding, by default `ZZ`.
-Discard the comment with `keymaps.popup.discard_changes` (`ZQ`), otherwise if
-you close the popup with something like `<c-w>q`, the comment contents are
-saved to the temporary register(s) (|gitlab.nvim.temp-registers|).
-
-                                                                *gitlab.nvim.create_comment_suggestion*
-gitlab.create_comment_suggestion() ~
-
-Opens a popup to create a comment suggestion (aka a comment that makes a committable
-change suggestion to the currently selected lines).
->lua
-  require("gitlab").create_comment_suggestion()
-<
-After the comment is typed, submit it to Gitlab via the
-`keymaps.popup.perform_linewise_action` keybinding, by default `ZA`.
+    Parameters: ~
+        • {opts}: (table|nil) Keyword arguments that can be used to include
+          a suggestion in the comment.
+            • {with_suggestion} (boolean) When true, pastes into the comment
+              buffer Gitlab’s suggestion code block prefilled with the
+              original text from the visual selection. See
+              https://docs.gitlab.com/ee/user/project/merge_requests/reviews/suggestions.html.
+
+In the popup, you can use the `keymaps.popup.perform_linewise_action`
+keybinding (by default `ZA`) to attach a file to the comment. After the
+comment is typed, submit it to Gitlab via the `keymaps.popup.perform_action`
+keybinding, by default `ZZ`. Discard the comment with
+`keymaps.popup.discard_changes` (`ZQ`), otherwise if you close the popup with
+something like `<c-w>q`, the comment contents are saved to the temporary
+register(s) (|gitlab.nvim.temp-registers|).
 
                                                                 *gitlab.nvim.create_mr*
 gitlab.create_mr({opts}) ~

lua/gitlab/actions/comment.lua

@@ -223,14 +223,30 @@ end
 --- Creates a comment on the selected line(s) in the current buffer.
 --- In normal mode comments on the current line.
 --- In visual mode comments on the whole selection.
-M.create_comment = function()
+---@param opts CreateCommentsOpts?
+M.create_comment = function(opts)
+  opts = opts or {}
   M.location = Location.new()
   if not M.can_create_comment(false) then
     return
   end
 
+  local suggestion_lines = require("gitlab.actions.suggestions").build_suggestion(
+    vim.api.nvim_buf_get_lines(0, 0, -1, false),
+    M.location.visual_range.start_line,
+    M.location.visual_range.end_line
+  )
+
   local layout = M.create_comment_layout({ unlinked = false })
   layout:mount()
+
+  if opts.with_suggestion then
+    vim.schedule(function()
+      if suggestion_lines then
+        vim.api.nvim_buf_set_lines(M.comment_popup.bufnr, 0, -1, false, suggestion_lines)
+      end
+    end)
+  end
 end
 
 --- This function will open a a popup to create a "note" (e.g. unlinked comment)
@@ -240,63 +256,6 @@ M.create_note = function()
   layout:mount()
 end
 
----Given the current visually selected area of text, builds text to fill in the
----comment popup with a suggested change
----@return LineRange|nil
-local build_suggestion = function()
-  local current_line = vim.api.nvim_win_get_cursor(0)[1]
-  local range_length = M.location.visual_range.end_line - M.location.visual_range.start_line
-  local backticks = "```"
-  local selected_lines = u.get_lines(M.location.visual_range.start_line, M.location.visual_range.end_line)
-
-  for _, line in ipairs(selected_lines) do
-    if string.match(line, "^```%S*$") then
-      backticks = "````"
-      break
-    end
-  end
-
-  local suggestion_start
-  if M.location.visual_range.start_line == current_line then
-    suggestion_start = backticks .. "suggestion:-0+" .. range_length
-  elseif M.location.visual_range.end_line == current_line then
-    suggestion_start = backticks .. "suggestion:-" .. range_length .. "+0"
-  else
-    --- This should never happen afaik
-    u.notify("Unexpected suggestion position", vim.log.levels.ERROR)
-    return nil
-  end
-  suggestion_start = suggestion_start
-  local suggestion_lines = {}
-  table.insert(suggestion_lines, suggestion_start)
-  vim.list_extend(suggestion_lines, selected_lines)
-  table.insert(suggestion_lines, backticks)
-
-  return suggestion_lines
-end
-
---- This function will open a a popup to create a suggestion comment
---- on the changed/updated line in the current MR
---- See: https://docs.gitlab.com/ee/user/project/merge_requests/reviews/suggestions.html
-M.create_comment_suggestion = function()
-  M.location = Location.new()
-  if not M.can_create_comment(true) then
-    u.press_escape()
-    return
-  end
-
-  local suggestion_lines = build_suggestion()
-
-  local layout = M.create_comment_layout({ unlinked = false })
-  layout:mount()
-
-  vim.schedule(function()
-    if suggestion_lines then
-      vim.api.nvim_buf_set_lines(M.comment_popup.bufnr, 0, -1, false, suggestion_lines)
-    end
-  end)
-end
-
 --- This function will create a new tab with a suggestion preview for the changed/updated line in
 --- the current MR.
 M.create_comment_with_suggestion = function()

lua/gitlab/annotations.lua

@@ -143,6 +143,9 @@
 ---@field commit_id string  -- This will always be ""
 ---@field line_code string
 ---@field position NotePosition
+
+---@class CreateCommentsOpts Options for the create_comment function.
+---@field with_suggestion boolean When true, paste the default suggestion into the comment buffer.
 ---
 ---
 --- Plugin Settings

lua/gitlab/init.lua

@@ -79,7 +79,13 @@ return {
     u.notify("create_multiline_comment() is deprecated, use create_comment()", vim.log.levels.WARN)
     comment.create_comment()
   end),
-  create_comment_suggestion = async.sequence({ info, revisions }, comment.create_comment_suggestion),
+  create_comment_suggestion = async.sequence({ info, revisions }, function()
+    u.notify(
+      "create_comment_suggestion() is deprecated, use create_comment({with_suggestion=true})",
+      vim.log.levels.WARN
+    )
+    comment.create_comment({ with_suggestion = true })
+  end),
   create_comment_with_suggestion = async.sequence({ info, revisions }, comment.create_comment_with_suggestion),
   move_to_discussion_tree_from_diagnostic = async.sequence({}, discussions.move_to_discussion_tree),
   create_note = async.sequence({ info }, comment.create_note),

lua/gitlab/reviewer/init.lua

@@ -328,12 +328,14 @@ end
 ---@param callback string Name of the gitlab.nvim API function to call
 M.execute_callback = function(callback)
   return function()
+    local opts = M.callback_opts
+    M.callback_opts = nil
     vim.api.nvim_cmd({ cmd = "normal", bang = true, args = { "'[V']" } }, {})
-    local _, err = pcall(
-      vim.api.nvim_cmd,
-      { cmd = "lua", args = { ("require'gitlab'.%s()"):format(callback) }, mods = { lockmarks = true } },
-      {}
-    )
+    local _, err = pcall(vim.api.nvim_cmd, {
+      cmd = "lua",
+      args = { ("require'gitlab'.%s(%s)"):format(callback, vim.inspect(opts or {})) },
+      mods = { lockmarks = true },
+    }, {})
     vim.api.nvim_win_set_cursor(M.old_winnr, M.old_cursor_position)
     vim.opt.operatorfunc = M.old_opfunc
     if err ~= "" then
@@ -345,10 +347,12 @@ end
 ---Set the operatorfunc that will work on the lines defined by the motion that follows after the
 ---operator mapping, and enter the operator-pending mode.
 ---@param cb string Name of the gitlab.nvim API function to call, e.g., "create_comment".
-local function execute_operatorfunc(cb)
+---@param opts table? Optional arguments for the callback.
+local function execute_operatorfunc(cb, opts)
   M.old_opfunc = vim.opt.operatorfunc
   M.old_winnr = vim.api.nvim_get_current_win()
   M.old_cursor_position = vim.api.nvim_win_get_cursor(M.old_winnr)
+  M.callback_opts = opts
   vim.opt.operatorfunc = ("v:lua.require'gitlab.reviewer'.execute_callback'%s'"):format(cb)
   -- Use the operator count before motion to allow, e.g., 2cc == c2c
   local count = M.operator_count > 0 and tostring(M.operator_count) or ""
@@ -413,8 +417,7 @@ M.set_keymaps = function(bufnr)
     -- Set operator keybinding
     vim.keymap.set("n", keymaps.reviewer.create_suggestion, function()
       M.operator_count = vim.v.count
-      M.operator = keymaps.reviewer.create_suggestion
-      execute_operatorfunc("create_comment_suggestion")
+      execute_operatorfunc("create_comment", { with_suggestion = true })
     end, {
       buffer = bufnr,
       desc = "Create suggestion for range of motion",
@@ -423,7 +426,7 @@ M.set_keymaps = function(bufnr)
 
     -- Set visual mode keybinding
     vim.keymap.set("v", keymaps.reviewer.create_suggestion, function()
-      require("gitlab").create_comment_suggestion()
+      require("gitlab").create_comment({ with_suggestion = true })
     end, {
       buffer = bufnr,
       desc = "Create suggestion for selected text",