feat(api): introduce preload hooks for rocks.nvim extensions (#209)

doc/rocks.txt

@@ -5,6 +5,7 @@ rocks.nvim ··································
 rocks.nvim commands ··········································· |rocks.commands|
 rocks.nvim configuration ········································ |rocks.config|
 rocks.nvim Lua API ················································· |rocks.api|
+rocks.nvim API hooks ········································· |rocks.api.hooks|
 rocks.nvim logging API ············································· |rocks.log|
 
 ==============================================================================
@@ -240,6 +241,23 @@ api.source_runtime_dir({dir})                           *api.source_runtime_dir*
         {dir}  (string)  The runtime directory to source
 
 
+==============================================================================
+rocks.nvim API hooks                                           *rocks.api.hooks*
+
+
+Hooks that rocks.nvim modules can inject behaviour into.
+Intended for use by modules that extend this plugin.
+
+
+
+ |preload|
+ By providing a module with the pattern, `rocks-<extension>.rocks.hooks.preload`,
+ rocks.nvim modules can execute code before rocks.nvim loads any plugins.
+
+ To be able to use this feature, a rocks.nvim extension *must* be named with a 'rocks-'
+ prefix.
+
+
 ==============================================================================
 rocks.nvim logging API                                               *rocks.log*
 

lua/rocks/api/hooks.lua

@@ -0,0 +1,68 @@
+---@mod rocks.api.hooks rocks.nvim API hooks
+---
+---@brief [[
+---
+---Hooks that rocks.nvim modules can inject behaviour into.
+---Intended for use by modules that extend this plugin.
+---
+---@brief ]]
+
+-- Copyright (C) 2024 Neorocks Org.
+--
+-- License:    GPLv3
+-- Created:    19 Mar 2024
+-- Updated:    19 Mar 2024
+-- Homepage:   https://github.com/nvim-neorocks/rocks.nvim
+-- Maintainers: NTBBloodbath <[email protected]>, Vhyrro <[email protected]>, mrcjkb <[email protected]>
+
+local hooks = {}
+
+---@param rock RockSpec
+---@return string | nil
+local function get_rocks_extension_module_name(rock)
+    return rock.name:match("(rocks%-[^%.%-]+)")
+end
+
+---Find a preload hook by rock name
+---@param rock_name rock_name
+---@return function | nil
+local function search_for_preload_hook(rock_name)
+    local mod_name = rock_name .. ".rocks.hooks.preload"
+    if package.loaded[mod_name] then
+        return
+    end
+    for _, searcher in ipairs(package.loaders) do
+        local loader = searcher(mod_name)
+        if type(loader) == "function" then
+            package.preload[mod_name] = loader
+            return loader
+        end
+    end
+end
+
+---@brief [[
+---
+--- |preload|
+--- By providing a module with the pattern, `rocks-<extension>.rocks.hooks.preload`,
+--- rocks.nvim modules can execute code before rocks.nvim loads any plugins.
+---
+--- To be able to use this feature, a rocks.nvim extension *must* be named with a 'rocks-'
+--- prefix.
+---
+---@brief ]]
+
+---@package
+---@param user_rocks RockSpec[]
+function hooks.run_preload_hooks(user_rocks)
+    for _, rock_spec in pairs(user_rocks) do
+        local rock_extension_module_name = not rock_spec.opt and get_rocks_extension_module_name(rock_spec)
+        local hook = rock_extension_module_name and search_for_preload_hook(rock_extension_module_name)
+        if hook then
+            -- NOTE We want this to panic if it fails, as it could otherwise
+            -- lead to harder to debug error messages.
+            hook()
+        end
+    end
+end
+
+return hooks

lua/rocks/runtime.lua

@@ -164,8 +164,8 @@ end
 ---NOTE: We don't want this to be async,
 ---to ensure Neovim sources `after/plugin` scripts
 ---after we source start plugins.
-function runtime.source_start_plugins()
-    local user_rocks = config.get_user_rocks()
+---@param user_rocks RockSpec[]
+function runtime.source_start_plugins(user_rocks)
     for _, rock_spec in pairs(user_rocks) do
         if not rock_spec.opt and rock_spec.version and rock_spec.name ~= constants.ROCKS_NVIM then
             -- Append to rtp first in case a plugin needs another plugin's `autoload`

nix/test-overlay.nix

@@ -34,7 +34,7 @@
     ];
     text = ''
       mkdir -p doc
-      lemmy-help lua/rocks/{init,commands,config/init,api,log}.lua > doc/rocks.txt
+      lemmy-help lua/rocks/{init,commands,config/init,api/{init,hooks},log}.lua > doc/rocks.txt
     '';
   };
 in {

plugin/rocks.lua

@@ -26,7 +26,9 @@ end
 
 adapter.init()
 
---- We don't want to run this async, to ensure plugins are sourced before `after/plugin`
-require("rocks.runtime").source_start_plugins()
+--- We don't want to run this async, to ensure proper initialisation order
+local user_rocks = config.get_user_rocks()
+require("rocks.api.hooks").run_preload_hooks(user_rocks)
+require("rocks.runtime").source_start_plugins(user_rocks)
 
 vim.g.rocks_nvim_loaded = true