feat(dirman)!: use pathlib for all dirman operations

[pysan3]

Pathlib.nvim

pathlib.nvim is a plugin which aims to decrease the difficulties of path management across mutliple OSs in neovim. The plugin API is heavily inspired by Python’s pathlib.path with tweaks to fit neovim usage.

You can search through the methods at: https://pysan3.github.io/pathlib.nvim/search.html

Commits

feat(spec): add pathlib.nvim to dependency

This adds pathlib.nvim to neorg's dependencies managed by .github/workflows/luarocks.yml and build.lua.

This commit also changes the typecheck CI to install all its dependencies defined by *.rockspec and use the packages for type annotations. Thanks to this change, types like PathlibPath (defined in pathlib.nvim) also get annotated as a valid type and will be type-checked against.

You will want to do this with local development as well.

$ luarocks init --no-gitignore  # RUN THIS ONLY ONCE

$ luarocks install --only-deps ./neorg-scm-1.rockspec  # Run this each time dependency changes

After running these commands, packages will be installed under ./lua_modules and those packages will be picked up by lua_ls thanks to config in ./.luarc.json and you will get all nvim-cmp completions!

docs(annotation): add better type annotations

Some updates to type annotations unrelated to dirman to make life easier with completions.

feat(dirman)!: use pathlib for all dirman operations

This commit contains all the breaking changes.

Some of the public facing APIs from dirman now returns a PathlibPath object instead of a string.
Besides, there is a new function dirman.utils.expand_pathlib which is meant to replace dirman.utils.expand_path.
I have not deprecated expand_path just yet since it is used in some places in the codebase, and if I deprecate it now, typecheck CI will complain about it resulting to ❌.

Some notable changes to modules other than dirman are as follows.

• core.completion
  • This uses dirman.get_norg_files to get the list of norg files under the workspace.
  • It does string manipulation of the file paths to generate the completion options.
  • I changed the code to make it work with pathlib which result in a much cleaner code.
• core.summary
  • path:len() == string.len(tostring(path)) so,
  • string.len(ws_root) won't work but ws_root:len() will call Path.len or string.len based on the type but result in the same value.
    • How clever!

@vhyrro I know you are busy but please take your time to read through the changes.
I tried my best to keep the diff as little as possible so that the diff explains what pathlib brings to the table (especially this commit).
I hope after you read through the changes, you already have some good understanding of how to use the library.
Of course if you have any question, feel free to ping me anytime.

I labeled this PR with feat! flagging it as a breaking change (which will increase the major version). Do you agree?
I think neorg v9 is labeled to bring the v3 parser so I'm not sure if introducing pathlib is worth making a major jump already.

[pysan3]

@vhyrro You see that with this change, the string passed to module_name will literally mean the return type and type annotation works awesome.

[vhyrro]

All LGTM! Tested all of the functions and they seem to work in the same way, good work.

Since the old function is still supported (simply deprecated in the annotations), I think we can merge this without a breaking change. After all, adding dependencies is no longer a breaker :)