Add which function for finding executables in PATH

Cargo.toml

@@ -31,6 +31,7 @@ dirs = "5.0.1"
 dotenvy = "0.15"
 edit-distance = "2.0.0"
 heck = "0.5.0"
+is_executable = "1.0.4"
 lexiclean = "0.0.1"
 libc = "0.2.0"
 num_cpus = "1.15.0"

README.md

@@ -1675,6 +1675,23 @@ set unstable
 foo := env('FOO') || 'DEFAULT_VALUE'
 ```
 
+- `which(exe)`<sup>master</sup> — Retrieves the full path of `exe` according
+  to the `PATH`. Returns an empty string if no executable named `exe` exists.
+
+```just
+bash := which("bash")
+nexist := which("does-not-exist")
+
+@test:
+    echo "bash: '{{bash}}'"
+    echo "nexist: '{{nexist}}'"
+```
+
+```console
+bash: '/bin/bash'
+nexist: ''
+```
+
 #### Invocation Information
 
 - `is_dependency()` - Returns the string `true` if the current recipe is being

src/function.rs

@@ -112,6 +112,7 @@ pub(crate) fn get(name: &str) -> Option<Function> {
     "uppercase" => Unary(uppercase),
     "uuid" => Nullary(uuid),
     "without_extension" => Unary(without_extension),
+    "which" => Unary(which),
     _ => return None,
   };
   Some(function)
@@ -661,6 +662,52 @@ fn uuid(_context: Context) -> FunctionResult {
   Ok(uuid::Uuid::new_v4().to_string())
 }
 
+fn which(context: Context, s: &str) -> FunctionResult {
+  use is_executable::IsExecutable;
+
+  let cmd = Path::new(s);
+
+  let candidates = match cmd.components().count() {
+    0 => return Err("empty command".into()),
+    1 => {
+      // cmd is a regular command
+      let path_var = env::var_os("PATH").ok_or("Environment variable `PATH` is not set")?;
+      env::split_paths(&path_var)
+        .map(|path| path.join(cmd))
+        .collect()
+    }
+    _ => {
+      // cmd contains a path separator, treat it as a path
+      vec![cmd.into()]
+    }
+  };
+
+  for mut candidate in candidates {
+    if candidate.is_relative() {
+      // This candidate is a relative path, either because the user invoked `which("rel/path")`,
+      // or because there was a relative path in `PATH`. Resolve it to an absolute path,
+      // relative to the working directory of the just invocation.
+      candidate = context
+        .evaluator
+        .context
+        .working_directory()
+        .join(candidate);
+    }
+
+    if candidate.is_executable() {
+      return candidate.to_str().map(str::to_string).ok_or_else(|| {
+        format!(
+          "Executable path is not valid unicode: {}",
+          candidate.display()
+        )
+      });
+    }
+  }
+
+  // No viable candidates; return an empty string
+  Ok(String::new())
+}
+
 fn without_extension(_context: Context, path: &str) -> FunctionResult {
   let parent = Utf8Path::new(path)
     .parent()

tests/lib.rs

@@ -119,6 +119,7 @@ mod timestamps;
 mod undefined_variables;
 mod unexport;
 mod unstable;
+mod which_function;
 #[cfg(windows)]
 mod windows;
 #[cfg(target_family = "windows")]

tests/test.rs

@@ -205,6 +205,31 @@ impl Test {
     self
   }
 
+  pub(crate) fn make_executable(self, path: impl AsRef<Path>) -> Self {
+    let file = self.tempdir.path().join(path);
+
+    // Make sure it exists first, as a sanity check.
+    assert!(file.exists(), "file does not exist: {}", file.display());
+
+    // Windows uses file extensions to determine whether a file is executable.
+    // Other systems don't care. To keep these tests cross-platform, just make
+    // sure all executables end with ".exe" suffix.
+    assert!(
+      file.extension() == Some("exe".as_ref()),
+      "executable file does not end with .exe: {}",
+      file.display()
+    );
+
+    println!("hi: {}", file.display());
+
+    if !cfg!(windows) {
+      let perms = std::os::unix::fs::PermissionsExt::from_mode(0o755);
+      fs::set_permissions(file, perms).unwrap();
+    }
+
+    self
+  }
+
   pub(crate) fn expect_file(mut self, path: impl AsRef<Path>, content: impl AsRef<[u8]>) -> Self {
     let path = path.as_ref();
     self

tests/which_function.rs

@@ -0,0 +1,199 @@
+use super::*;
+
+#[test]
+fn finds_executable() {
+  let tmp = tempdir();
+  let path = PathBuf::from(tmp.path());
+
+  Test::with_tempdir(tmp)
+    .justfile("p := which('hello.exe')")
+    .args(["--evaluate", "p"])
+    .write("hello.exe", "#!/usr/bin/env bash\necho hello\n")
+    .make_executable("hello.exe")
+    .env("PATH", path.to_str().unwrap())
+    .stdout(format!("{}", path.join("hello.exe").display()))
+    .run();
+}
+
+#[test]
+fn prints_empty_string_for_missing_executable() {
+  let tmp = tempdir();
+  let path = PathBuf::from(tmp.path());
+
+  Test::with_tempdir(tmp)
+    .justfile("p := which('goodbye.exe')")
+    .args(["--evaluate", "p"])
+    .write("hello.exe", "#!/usr/bin/env bash\necho hello\n")
+    .make_executable("hello.exe")
+    .env("PATH", path.to_str().unwrap())
+    .stdout("")
+    .run();
+}
+
+#[test]
+fn skips_non_executable_files() {
+  let tmp = tempdir();
+  let path = PathBuf::from(tmp.path());
+
+  Test::with_tempdir(tmp)
+    .justfile("p := which('hi')")
+    .args(["--evaluate", "p"])
+    .write("hello.exe", "#!/usr/bin/env bash\necho hello\n")
+    .make_executable("hello.exe")
+    .write("hi", "just some regular file")
+    .env("PATH", path.to_str().unwrap())
+    .stdout("")
+    .run();
+}
+
+#[test]
+fn supports_multiple_paths() {
+  let tmp = tempdir();
+  let path = PathBuf::from(tmp.path());
+  let path_var = env::join_paths([
+    path.join("subdir1").to_str().unwrap(),
+    path.join("subdir2").to_str().unwrap(),
+  ])
+  .unwrap();
+
+  Test::with_tempdir(tmp)
+    .justfile("p := which('hello1.exe') + '+' + which('hello2.exe')")
+    .args(["--evaluate", "p"])
+    .write("subdir1/hello1.exe", "#!/usr/bin/env bash\necho hello\n")
+    .make_executable("subdir1/hello1.exe")
+    .write("subdir2/hello2.exe", "#!/usr/bin/env bash\necho hello\n")
+    .make_executable("subdir2/hello2.exe")
+    .env("PATH", path_var.to_str().unwrap())
+    .stdout(format!(
+      "{}+{}",
+      path.join("subdir1").join("hello1.exe").display(),
+      path.join("subdir2").join("hello2.exe").display(),
+    ))
+    .run();
+}
+
+#[test]
+fn supports_shadowed_executables() {
+  enum Variation {
+    Dir1Dir2, // PATH=/tmp/.../dir1:/tmp/.../dir2
+    Dir2Dir1, // PATH=/tmp/.../dir2:/tmp/.../dir1
+  }
+
+  for variation in [Variation::Dir1Dir2, Variation::Dir2Dir1] {
+    let tmp = tempdir();
+    let path = PathBuf::from(tmp.path());
+
+    let path_var = match variation {
+      Variation::Dir1Dir2 => env::join_paths([
+        path.join("dir1").to_str().unwrap(),
+        path.join("dir2").to_str().unwrap(),
+      ]),
+      Variation::Dir2Dir1 => env::join_paths([
+        path.join("dir2").to_str().unwrap(),
+        path.join("dir1").to_str().unwrap(),
+      ]),
+    }
+    .unwrap();
+
+    let stdout = match variation {
+      Variation::Dir1Dir2 => format!("{}", path.join("dir1").join("shadowed.exe").display()),
+      Variation::Dir2Dir1 => format!("{}", path.join("dir2").join("shadowed.exe").display()),
+    };
+
+    Test::with_tempdir(tmp)
+      .justfile("p := which('shadowed.exe')")
+      .args(["--evaluate", "p"])
+      .write("dir1/shadowed.exe", "#!/usr/bin/env bash\necho hello\n")
+      .make_executable("dir1/shadowed.exe")
+      .write("dir2/shadowed.exe", "#!/usr/bin/env bash\necho hello\n")
+      .make_executable("dir2/shadowed.exe")
+      .env("PATH", path_var.to_str().unwrap())
+      .stdout(stdout)
+      .run();
+  }
+}
+
+#[test]
+fn ignores_nonexecutable_candidates() {
+  let tmp = tempdir();
+  let path = PathBuf::from(tmp.path());
+
+  let path_var = env::join_paths([
+    path.join("dummy").to_str().unwrap(),
+    path.join("subdir").to_str().unwrap(),
+    path.join("dummy").to_str().unwrap(),
+  ])
+  .unwrap();
+
+  let dummy_exe = if cfg!(windows) {
+    "dummy/foo"
+  } else {
+    "dummy/foo.exe"
+  };
+
+  Test::with_tempdir(tmp)
+    .justfile("p := which('foo.exe')")
+    .args(["--evaluate", "p"])
+    .write("subdir/foo.exe", "#!/usr/bin/env bash\necho hello\n")
+    .make_executable("subdir/foo.exe")
+    .write(dummy_exe, "#!/usr/bin/env bash\necho hello\n")
+    .env("PATH", path_var.to_str().unwrap())
+    .stdout(format!("{}", path.join("subdir").join("foo.exe").display()))
+    .run();
+}
+
+#[test]
+fn handles_absolute_path() {
+  let tmp = tempdir();
+  let path = PathBuf::from(tmp.path());
+  let abspath = path.join("subdir").join("foo.exe");
+
+  Test::with_tempdir(tmp)
+    .justfile(format!("p := which('{}')", abspath.display()))
+    .write("subdir/foo.exe", "#!/usr/bin/env bash\necho hello\n")
+    .make_executable("subdir/foo.exe")
+    .write("pathdir/foo.exe", "#!/usr/bin/env bash\necho hello\n")
+    .make_executable("pathdir/foo.exe")
+    .env("PATH", path.join("pathdir").to_str().unwrap())
+    .args(["--evaluate", "p"])
+    .stdout(format!("{}", abspath.display()))
+    .run();
+}
+
+#[test]
+fn handles_dotslash() {
+  let tmp = tempdir();
+  let path = tmp.path().canonicalize().unwrap();
+  // canonicalize() is necessary here to account for the justfile prepending
+  // the canonicalized working directory to './foo.exe'.
+
+  Test::with_tempdir(tmp)
+    .justfile("p := which('./foo.exe')")
+    .args(["--evaluate", "p"])
+    .write("foo.exe", "#!/usr/bin/env bash\necho hello\n")
+    .make_executable("foo.exe")
+    .write("pathdir/foo.exe", "#!/usr/bin/env bash\necho hello\n")
+    .make_executable("pathdir/foo.exe")
+    .env("PATH", path.join("pathdir").to_str().unwrap())
+    .stdout(format!("{}", path.join(".").join("foo.exe").display()))
+    .run();
+}
+
+#[test]
+fn handles_dir_slash() {
+  let tmp = tempdir();
+  let path = tmp.path().canonicalize().unwrap();
+  // canonicalize() is necessary here to account for the justfile prepending
+  // the canonicalized working directory to 'subdir/foo.exe'.
+
+  Test::with_tempdir(tmp)
+    .justfile("p := which('subdir/foo.exe')")
+    .args(["--evaluate", "p"])
+    .write("subdir/foo.exe", "#!/usr/bin/env bash\necho hello\n")
+    .make_executable("subdir/foo.exe")
+    .write("pathdir/foo.exe", "#!/usr/bin/env bash\necho hello\n")
+    .make_executable("pathdir/foo.exe")
+    .env("PATH", path.join("pathdir").to_str().unwrap())
+    .stdout(format!("{}", path.join("subdir").join("foo.exe").display()))
+    .run();
+}