Address review comments

doc/rocks.txt

@@ -426,18 +426,20 @@ api.source_runtime_dir()                                *api.source_runtime_dir*
     @deprecated Use the rtp.nvim luarock
 
 
-InstallRockOpts : rocks.AddOpts                                *InstallRockOpts*
+rocks.InstallOpts                                *InstallRockOpts*
+    Fields: ~
+      {config_path?}  (string)           Config file path to use for installing the rock relative to the base config file
+      {callback?}     (fun(rock:Rock))   Invoked upon successful completion
 
 
                                                                    *api.install*
-api.install({rock_name}, {version?}, {callback?}, {opts?})
-    Invoke ':Rocks install' with a callback
+api.install({rock_name}, {version?}, {opts?})
+    Invoke ':Rocks install'
 
     Parameters: ~
-        {rock_name}  (rock_name)        #The rock name
-        {version?}   (string)           The version of the rock to use
-        {callback?}  (fun(rock:Rock))   Invoked upon successful completion
-        {opts?}      (InstallRockOpts)  Installation options
+        {rock_name}  (rock_name)          #The rock name
+        {version?}   (string)             The version of the rock to use
+        {opts?}      (rocks.InstallOpts)  Installation options
 
 
 ==============================================================================

lua/rocks/api/init.lua

@@ -188,14 +188,26 @@ function api.source_runtime_dir(dir)
     require("rtp_nvim").source_rtp_dir(dir)
 end
 
----@class InstallRockOpts: rocks.AddOpts
+---@class rocks.InstallOpts
+---@field skip_prompts? boolean Whether to skip any "search 'dev' manifest prompts
+---@field cmd? 'install' | 'update' Command used to invoke this function. Default: `'install'`
+---@field config_path? string Config file path to use for installing the rock relative to the base config file
+---@field callback? fun(rock: Rock) Invoked upon successful completion
 
----Invoke ':Rocks install' with a callback
+---Invoke ':Rocks install'
 ---@param rock_name rock_name #The rock name
 ---@param version? string The version of the rock to use
----@param callback? fun(rock: Rock) Invoked upon successful completion
----@param opts? InstallRockOpts Installation options
-function api.install(rock_name, version, callback, opts)
+---@param opts? rocks.InstallOpts  Installation options
+function api.install(rock_name, version, opts)
+    if type(opts) == "function" then
+        vim.deprecate(
+            "rocks.api.install(rock_name, version, callback)",
+            "rocks.api.install(rocks_name, version, { callback = cb })",
+            "3.0.0",
+            "rocks.nvim"
+        )
+        opts = { callback = callback }
+    end
     operations.add({ rock_name, version }, callback, opts --[[@as rocks.AddOpts]])
 end
 

lua/rocks/operations/add.lua

@@ -64,12 +64,12 @@ end
 ---@field skip_prompts? boolean Whether to skip any "search 'dev' manifest prompts
 ---@field cmd? 'install' | 'update' Command used to invoke this function. Default: `'install'`
 ---@field config_path? string Config file path to use for installing the rock relative to the base config file
+---@field callback? fun(rock: Rock) Invoked upon successful completion
 
 --- Adds a new rock and updates the `rocks.toml` file
 ---@param arg_list string[] #Argument list, potentially used by external handlers. The first argument is the package, e.g. the rock name
----@param callback? fun(rock: Rock)
 ---@param opts? rocks.AddOpts
-add.add = function(arg_list, callback, opts)
+add.add = function(arg_list, opts)
     opts = opts or {}
     opts.cmd = opts.cmd or "install"
     local is_install = opts.cmd == "install"
@@ -89,15 +89,15 @@ add.add = function(arg_list, callback, opts)
     nio.run(function()
         helpers.semaphore.with(function()
             local user_rocks = helpers.parse_rocks_toml(opts.config_path)
-            local handler = handlers.get_install_handler_callback(user_rocks --[[@as MutRocksTomlRef]], arg_list)
+            local handler = handlers.get_install_handler_callback(user_rocks, arg_list)
             if type(handler) == "function" then
                 local function report_progress(message)
                     progress_handle:report({
                         message = message,
                     })
                 end
                 handler(report_progress, report_error, helpers.manage_rock_stub)
-                user_rocks()
+                helpers.write_rocks_toml_await(user_rocks)
                 nio.scheduler()
                 progress_handle:finish()
                 return
@@ -216,14 +216,14 @@ Use 'Rocks %s {rock_name}' or install rocks-git.nvim.
             else
                 user_rocks.plugins[rock_name] = installed_rock.version
             end
-            user_rocks()
+            helpers.write_rocks_toml_await(user_rocks)
             cache.populate_all_rocks_state_caches()
             vim.schedule(function()
                 helpers.postInstall()
                 if success then
                     progress_handle:finish()
-                    if callback then
-                        callback(installed_rock)
+                    if opts.callback then
+                        opts.callback(installed_rock)
                     end
                 else
                     progress_handle:cancel()

lua/rocks/operations/handlers.lua

@@ -28,6 +28,7 @@ function handlers.register_handler(handler)
     table.insert(_handlers, handler)
 end
 
+---@overload fun(rocks_toml_ref: MultiMutRocksTomlWrapper, arg_list: string[]): rock_handler_callback | nil
 ---@param rocks_toml_ref MutRocksTomlRef
 ---@param arg_list string[]
 ---@return rock_handler_callback | nil
@@ -64,6 +65,7 @@ function handlers.get_sync_handler_callback(spec)
         end)
 end
 
+---@overload fun(rocks_toml_ref: MultiMutRocksTomlWrapper): rock_handler_callback[]
 ---@param rocks_toml_ref MutRocksTomlRef
 ---@return rock_handler_callback[]
 function handlers.get_update_handler_callbacks(rocks_toml_ref)

lua/rocks/operations/helpers/init.lua

@@ -48,13 +48,11 @@ function helpers.parse_rocks_toml(config_path)
         -- For non-base configs, add it to the list of imports in the base config
         if base_rocks_toml.import then
             local i = 0
-            while true do
+            local import_path
+            repeat
                 i = i + 1
-                local import = base_rocks_toml.import[i]
-                if not import or import == config_path then
-                    break
-                end
-            end
+                import_path = base_rocks_toml.import[i]
+            until import_path == nil or import_path == config_path
             base_rocks_toml.import[i] = config_path
         else
             base_rocks_toml.import = { config_path }
@@ -87,6 +85,20 @@ function helpers.parse_rocks_toml(config_path)
     return multi_mut_rocks_toml_wrapper.new(rocks_toml_configs)
 end
 
+--- Write a the config files in an async context
+---@type async fun(rocks_toml: MultiMutRocksTomlWrapper)
+function helpers.write_rocks_toml_await(rocks_toml)
+    rocks_toml(function(configs)
+        for _, tbl in ipairs(configs) do
+            if tbl.path ~= nil then
+                fs.write_file_await(tbl.path, "w", tostring(tbl.config))
+            end
+        end
+    end)
+end
+
+---@overload fun(rocks_toml: MultiMutRocksTomlWrapper, rock_name: rock_name): "plugins"|"rocks"|nil
+---@overload fun(rocks_toml: MultiMutRocksTomlWrapper, rock_name: rock_name): rock_config_table|nil
 ---@param rocks_toml MutRocksTomlRef
 ---@param rock_name rock_name
 ---@return "plugins"|"rocks"|nil rocks_key The key of the table containing the rock entry

lua/rocks/operations/helpers/multi_mut_rocks_toml_wrapper.lua

@@ -58,13 +58,10 @@ MultiMutRocksTomlWrapper.__newindex = function(self, key, value)
 end
 
 --- Write to all rocks toml config files in an async context
----@type async fun(self: MultiMutRocksTomlWrapper)
-MultiMutRocksTomlWrapper.__call = function(self)
-    for _, tbl in ipairs(self.configs) do
-        if tbl.path ~= nil then
-            fs.write_file_await(tbl.path, "w", tostring(tbl.config))
-        end
-    end
+---@param self MultiMutRocksTomlWrapper
+---@param func fun(configs: MutRocksTomlRefWithPath[])
+MultiMutRocksTomlWrapper.__call = function(self, func)
+    func(self.configs)
 end
 
 --- Function to create a new wrapper

lua/rocks/operations/pin.lua

@@ -24,7 +24,7 @@ pin.pin = function(rock_name)
     nio.run(function()
         helpers.semaphore.with(function()
             local user_config = helpers.parse_rocks_toml()
-            local rocks_key, user_rock = helpers.get_rock_and_key(user_config --[[@as MutRocksTomlRef]], rock_name)
+            local rocks_key, user_rock = helpers.get_rock_and_key(user_config, rock_name)
             if not rocks_key then
                 vim.schedule(function()
                     vim.notify(rock_name .. " not found in rocks.toml", vim.log.levels.ERROR)

lua/rocks/operations/prune.lua

@@ -55,7 +55,7 @@ prune.prune = function(rock_name)
                 progress_handle:report({ message = message, title = "Error" })
                 success = false
             end
-            user_config()
+            helpers.write_rocks_toml_await(user_config)
             local user_rocks = config.get_user_rocks()
             handlers.prune_user_rocks(user_rocks, report_progress, report_error)
             adapter.synchronise_site_symlinks()

lua/rocks/operations/unpin.lua

@@ -24,7 +24,7 @@ unpin.unpin = function(rock_name)
     nio.run(function()
         helpers.semaphore.with(function()
             local user_config = helpers.parse_rocks_toml()
-            local rocks_key, user_rock = helpers.get_rock_and_key(user_config --[[@as MutRocksTomlRef]], rock_name)
+            local rocks_key, user_rock = helpers.get_rock_and_key(user_config, rock_name)
             if not rocks_key or not user_rock then
                 vim.schedule(function()
                     vim.notify(rock_name .. " not found in rocks.toml", vim.log.levels.ERROR)
@@ -39,7 +39,7 @@ unpin.unpin = function(rock_name)
             else
                 user_config[rocks_key][rock_name].pin = nil
             end
-            user_config()
+            helpers.write_rocks_toml_await(user_config)
             vim.schedule(function()
                 vim.notify(("%s unpinned"):format(rock_name), vim.log.levels.INFO)
             end)

lua/rocks/operations/update.lua

@@ -93,7 +93,7 @@ update.update = function(on_complete, opts)
                 ---@param key rock_name
                 ---@param rock OutdatedRock
                 function(acc, key, rock)
-                    local _, user_rock = helpers.get_rock_and_key(user_rocks --[[@as MutRocksTomlRef]], rock.name)
+                    local _, user_rock = helpers.get_rock_and_key(user_rocks, rock.name)
                     if user_rock and not user_rock.pin then
                         acc[key] = rock
                     end
@@ -108,7 +108,7 @@ update.update = function(on_complete, opts)
             if config.reinstall_dev_rocks_on_update then
                 to_update = add_dev_rocks_for_update(to_update)
             end
-            local external_update_handlers = handlers.get_update_handler_callbacks(user_rocks --[[@as MutRocksTomlRef]])
+            local external_update_handlers = handlers.get_update_handler_callbacks(user_rocks)
 
             local total_update_count = #to_update + #external_update_handlers
 
@@ -161,16 +161,15 @@ update.update = function(on_complete, opts)
             for _, installed_rock in pairs(state.installed_rocks()) do
                 ---@type rock_name
                 local rock_name = installed_rock.name
-                local rocks_key, user_rock =
-                    helpers.get_rock_and_key(user_rocks --[[@as MutRocksTomlRef]], installed_rock.name)
+                local rocks_key, user_rock = helpers.get_rock_and_key(user_rocks, installed_rock.name)
                 if user_rock and user_rock.version then
                     -- Rock is configured as a table -> Update version.
                     user_rocks[rocks_key][rock_name].version = installed_rock.version
                 elseif user_rock then -- Only insert the version if there's an entry in rocks.toml
                     user_rocks[rocks_key][rock_name] = installed_rock.version
                 end
             end
-            user_rocks()
+            helpers.write_rocks_toml_await(user_rocks)
             nio.scheduler()
             if not vim.tbl_isempty(error_handles) then
                 local message = "Update completed with errors! Run ':Rocks log' for details."