feat(dirman): use pathlib for all dirman operations (nvim-neorg#1354)

.github/workflows/.luarc.json

@@ -6,6 +6,7 @@
     "lua/?/init.lua"
   ],
   "Lua.workspace.library": [
+    "/home/runner/work/neorg/neorg/lua_modules/share/lua/5.1",
     "/home/runner/work/neorg/neorg/deps/neovim/runtime/lua",
     "/home/runner/work/neorg/neorg/deps/neodev.nvim/types/stable"
   ],

.github/workflows/luarocks.yml

@@ -30,3 +30,4 @@ jobs:
             lua-utils.nvim == 1.0.2
             plenary.nvim == 0.1.4
             nui.nvim == 0.3.0
+            pathlib.nvim ~> 2

.github/workflows/typecheck.yml

@@ -14,18 +14,26 @@ jobs:
       - name: Checkout Code
         uses: actions/checkout@v3
 
-      - name: Checkout dependency neodev
+      - name: Checkout dependency neodev # get neodev and neovim/runtime for builtin types
         uses: actions/checkout@v3
         with:
           repository: "folke/neodev.nvim"
           path: "deps/neodev.nvim"
-
       - name: Checkout neovim for type annotations
         uses: actions/checkout@v3
         with:
           repository: "neovim/neovim"
           path: "deps/neovim"
 
+      - uses: leafo/gh-actions-lua@v9 # get luarocks dependencies for their types (eg `PathlibPath`)
+        with:
+          luaVersion: "5.1"
+      - uses: leafo/gh-actions-luarocks@v4
+      - name: install dependencies
+        run: |
+          luarocks init
+          luarocks install --only-deps ./*.rockspec
+
       - name: Type Check Code Base
         uses: mrcjkb/[email protected]
         with:

.gitignore

@@ -1,2 +1,5 @@
 wiki/
 test.norg
+/luarocks
+/lua_modules
+/.luarocks

.luarc.json

@@ -5,5 +5,6 @@
         "_neorg_module_autocommand_triggered",
         "vim"
     ],
-    "workspace.checkThirdParty": false
+    "Lua.diagnostics.libraryFiles": "Disable",
+    "Lua.workspace.checkThirdParty": false
 }

build.lua

@@ -16,6 +16,7 @@ vim.schedule(function()
         "lua-utils.nvim == 1.0.2",
         "plenary.nvim == 0.1.4",
         "nui.nvim == 0.3.0",
+        "pathlib.nvim ~> 2",
     })
 
     package.loaded["neorg"] = nil

lua/neorg/core/modules.lua

@@ -512,8 +512,9 @@ function modules.load_module_as_dependency(module_name, parent_module, cfg)
 end
 
 --- Retrieves the public API exposed by the module.
---- @param module_name string The name of the module to retrieve.
---- @return neorg.module.public?
+--- @generic T
+--- @param module_name `T` The name of the module to retrieve.
+--- @return T?
 function modules.get_module(module_name)
     if not modules.is_module_loaded(module_name) then
         log.trace("Attempt to get module with name", module_name, "failed - module is not loaded.")

lua/neorg/core/utils.lua

@@ -178,10 +178,11 @@ function utils.notify(msg, log_level)
 end
 
 --- Opens up an array of files and runs a callback for each opened file.
---- @param files string[] An array of files to open.
+--- @param files (string|PathlibPath)[] An array of files to open.
 --- @param callback fun(buffer: integer, filename: string) The callback to invoke for each file.
 function utils.read_files(files, callback)
     for _, file in ipairs(files) do
+        file = tostring(file)
         local bufnr = vim.uri_to_bufnr(vim.uri_from_fname(file))
 
         local should_delete = not vim.api.nvim_buf_is_loaded(bufnr)

lua/neorg/modules/core/completion/module.lua

@@ -50,8 +50,9 @@ module.private = {
     engine = nil,
 
     --- Get a list of all norg files in current workspace. Returns { workspace_path, norg_files }
-    --- @return table?
+    --- @return { [1]: PathlibPath, [2]: PathlibPath[]|nil }|nil
     get_norg_files = function()
+        ---@type core.dirman
         local dirman = neorg.modules.get_module("core.dirman")
         if not dirman then
             return nil
@@ -89,6 +90,7 @@ module.private = {
     --- @param file string file path, norg syntax accepted
     --- @return table<string>
     get_lines = function(file)
+        ---@type core.dirman.utils
         local dirutils = neorg.modules.get_module("core.dirman.utils")
         if not dirutils then
             return {}
@@ -168,6 +170,7 @@ module.private = {
 
     generate_file_links = function(context, _prev, _saved, _match)
         local res = {}
+        ---@type core.dirman
         local dirman = neorg.modules.get_module("core.dirman")
         if not dirman then
             return {}
@@ -179,14 +182,16 @@ module.private = {
         end
 
         local closing_chars = module.private.get_closing_chars(context, true)
-        for _, file in pairs(files[2]) do
-            assert(type(file) == "string")
+        for _, filepath in pairs(files[2]) do
+            local file = tostring(filepath)
             local bufnr = dirman.get_file_bufnr(file)
 
             if vim.api.nvim_get_current_buf() ~= bufnr then
-                -- using -6 to go to the end (-1) and remove '.norg' 5 more chars
-                local link = "{:$" .. file:sub(#files[1] + 1, -6) .. closing_chars
-                table.insert(res, link)
+                local rel = filepath:relative_to(files[1], false)
+                if rel and rel:len() > 0 then
+                    local link = "{:$/" .. rel:with_suffix(""):tostring() .. closing_chars
+                    table.insert(res, link)
+                end
             end
         end
 
@@ -219,7 +224,7 @@ module.private = {
     end,
 
     --- The node context for normal norg (ie. not in a code block)
-    normal_norg = function(current, previous)
+    normal_norg = function(current, previous, _, _)
         -- If no previous node exists then try verifying the current node instead
         if not previous then
             return current and (current:type() ~= "translation_unit" or current:type() == "document") or false
@@ -251,7 +256,7 @@ module.load = function()
     end
 
     -- Set a special function in the integration module to allow it to communicate with us
-    module.private.engine.invoke_completion_engine = function(context)
+    module.private.engine.invoke_completion_engine = function(context) ---@diagnostic disable-line
         return module.public.complete(context) ---@diagnostic disable-line -- TODO: type error workaround <pysan3>
     end
 
@@ -526,8 +531,8 @@ module.public = {
 
     --- Parses the public completion table and attempts to find all valid matches
     ---@param context table #The context provided by the integration engine
-    ---@param prev table #The previous table of completions - used for descent
-    ---@param saved string #The saved regex in the form of a string, used to concatenate children nodes with parent nodes' regexes
+    ---@param prev table? #The previous table of completions - used for descent
+    ---@param saved string? #The saved regex in the form of a string, used to concatenate children nodes with parent nodes' regexes
     complete = function(context, prev, saved)
         -- If the save variable wasn't passed then set it to an empty string
         saved = saved or ""
@@ -560,7 +565,7 @@ module.public = {
                         -- If the type of completion data we're dealing with is a string then attempt to parse it
                         if type(completion_data.node) == "string" then
                             -- Split the completion node string down every pipe character
-                            local split = vim.split(completion_data.node, "|")
+                            local split = vim.split(completion_data.node --[[@as string]], "|")
                             -- Check whether the first character of the string is an exclamation mark
                             -- If this is present then it means we're looking for a node that *isn't* the one we specify
                             local negate = split[1]:sub(0, 1) == "!"