add find_upwards

Author: jamestrew

lua/plenary/path2.lua

@@ -64,6 +64,8 @@
 ---   seems unnecessary... just do `Path:new("some/file/path"):read()`
 ---
 --- - renamed `iter` into `iter_lines` for more clarity
+---
+--- - `find_upwards` returns `nil` if file not found rather than an empty string
 
 local bit = require "plenary.bit"
 local uv = vim.loop
@@ -1421,4 +1423,28 @@ function Path:walk(top_down)
   end
 end
 
+--- Search for a filename up from the current path, including the current
+--- directory, searching up to the root directory.
+--- Returns the `Path` of the first item found.
+--- Returns `nil` if filename is not found.
+---@param filename string
+---@return plenary.Path2?
+function Path:find_upwards(filename)
+  vim.validate { filename = { filename, "s" } }
+
+  if self:is_dir() then
+    local target = self / filename
+    if target:exists() then
+      return target
+    end
+  end
+
+  for parent in self:iter_parents() do
+    local target = Path:new { parent, filename }
+    if target:exists() then
+      return target
+    end
+  end
+end
+
 return Path

tests/plenary/path2_spec.lua

@@ -1101,4 +1101,26 @@ SOFTWARE.]]
       assert.are.same(should, data)
     end)
   end)
+
+  describe("find_upwards", function()
+    it_cross_plat("finds file in current dir", function()
+      local p = Path:new "lua/plenary"
+      local res = assert(p:find_upwards "busted.lua")
+      local expect = Path:new "lua/plenary/busted.lua"
+      assert.are.same(expect, res)
+    end)
+
+    it_cross_plat("finds file in parent dir", function()
+      local p = Path:new "lua/plenary"
+      local res = assert(p:find_upwards "say.lua")
+      local expect = Path:new "lua/say.lua"
+      assert.are.same(expect, res)
+    end)
+
+    it_cross_plat("doesn't find file", function()
+      local p = Path:new "."
+      local res = p:find_upwards "aisohtenaishoetnaishoetnasihoetnashitoen"
+      assert.is_nil(res)
+    end)
+  end)
 end)