feat(utils): add function utils.fs.make_relative()

Author: broken-pen

lua/orgmode/utils/fs.lua

@@ -63,4 +63,37 @@ function M.trim_common_root(paths)
   return result
 end
 
+---@param filepath string an absolute path
+---@param base string an absolute path to an ancestor of filepath;
+---                   here, `'.'` represents the current working directory, and
+---                   *not* the current file's directory.
+---@return string filepath_relative_to_base
+function M.make_relative(filepath, base)
+  vim.validate({
+    filepath = { filepath, 'string', false },
+    base = { base, 'string', false },
+  })
+  filepath = vim.fn.fnamemodify(filepath, ':p')
+  base = vim.fn.fnamemodify(base, ':p')
+  if base:sub(-1) ~= '/' then
+    base = base .. '/'
+  end
+  local levels_up = 0
+  for parent in vim.fs.parents(base) do
+    if parent:sub(-1) ~= '/' then
+      parent = parent .. '/'
+    end
+    if vim.startswith(filepath, parent) then
+      filepath = filepath:sub(parent:len() + 1)
+      if levels_up > 0 then
+        return vim.fs.joinpath(string.rep('..', levels_up, '/'), filepath)
+      end
+      return vim.fs.joinpath('.', filepath)
+    end
+    levels_up = levels_up + 1
+  end
+  -- No common root, just return the absolute path.
+  return filepath
+end
+
 return M

tests/plenary/utils/fs_spec.lua

@@ -86,3 +86,51 @@ describe('get_real_path', function()
     assert.is.False(fs_utils.get_real_path('.'))
   end)
 end)
+
+describe('make_relative', function()
+  local path = fs_utils.get_real_path(file.filename) ---@cast path string
+  local basename = vim.fs.basename(path)
+  local dirname = vim.fs.dirname(path)
+  local dirname_slash = vim.fs.joinpath(dirname, '')
+  local root = path
+  for parent in vim.fs.parents(path) do
+    root = parent
+  end
+
+  it('gets the basename', function()
+    local expected = vim.fs.joinpath('.', basename)
+    local actual = fs_utils.make_relative(path, dirname)
+    assert.are.same(expected, actual)
+  end)
+
+  it('gets the basename with trailing slash', function()
+    local expected = vim.fs.joinpath('.', basename)
+    local actual = fs_utils.make_relative(path, dirname_slash)
+    assert.are.same(expected, actual)
+  end)
+
+  it('works one level up', function()
+    local parent_name = vim.fs.basename(dirname)
+    local expected = vim.fs.joinpath('.', parent_name, basename)
+    local actual = fs_utils.make_relative(path, vim.fs.dirname(dirname))
+    assert.are.same(expected, actual)
+  end)
+
+  it('works one level up with trailing slash', function()
+    local parent_name = vim.fs.basename(dirname)
+    local expected = vim.fs.joinpath('.', parent_name, basename)
+    local actual = fs_utils.make_relative(path, vim.fs.dirname(dirname) .. '/')
+    assert.are.same(expected, actual)
+  end)
+
+  it('produces a relative path even at the root', function()
+    local relpath = fs_utils.make_relative(path, root)
+    assert(vim.endswith(path, relpath))
+  end)
+
+  it('climbs up via ..', function()
+    local relpath = fs_utils.make_relative(root, path)
+    local only_cdup = vim.regex('\\V\\(../\\)\\+')
+    assert(only_cdup:match_str(relpath))
+  end)
+end)