feat: Add Search::prefix_directory() and Search::longest_common_directory().

That way it's possible to use the common-prefix safely in a situation
where a directory is required, while offering the ability to maximize
the common prefix at the expense of an additional check to see if
the longest possible directory is actually accessible.

Author: Byron

gix-pathspec/src/search/mod.rs

@@ -1,6 +1,8 @@
 use bstr::{BStr, ByteSlice};
+use std::borrow::Cow;
+use std::path::Path;
 
-use crate::{Pattern, Search};
+use crate::{MagicSignature, Pattern, Search};
 
 /// Describes a matching pattern within a search for ignored paths.
 #[derive(PartialEq, Eq, Debug, Hash, Ord, PartialOrd, Clone)]
@@ -56,6 +58,44 @@ impl Search {
             .find(|p| !p.value.pattern.is_excluded())
             .map_or("".into(), |m| m.value.pattern.path[..self.common_prefix_len].as_bstr())
     }
+
+    /// Returns a guaranteed-to-be-directory that is shared across all pathspecs, in its repository-relative form.
+    /// Thus to be valid, it must be joined with the worktree root.
+    /// The prefix is the CWD within a worktree passed when [normalizing](crate::Pattern::normalize) the pathspecs.
+    ///
+    /// Note that it may well be that the directory isn't available even though there is a [`common_prefix()`](Self::common_prefix),
+    /// as they are not quire the same.
+    ///
+    /// See also: [`maybe_prefix_directory()`](Self::longest_common_directory).
+    pub fn prefix_directory(&self) -> Cow<'_, Path> {
+        gix_path::from_bstr(
+            self.patterns
+                .iter()
+                .find(|p| !p.value.pattern.is_excluded())
+                .map_or("".into(), |m| m.value.pattern.prefix_directory()),
+        )
+    }
+
+    /// Return the longest possible common directory that is shared across all non-exclusive pathspecs.
+    /// It must be tested for existence by joining it with a suitable root before being able to use it.
+    /// Note that if it is returned, it's guaranteed to be longer than the [prefix-directory](Self::prefix_directory).
+    ///
+    /// Returns `None` if the returned directory would be empty, or if all pathspecs are exclusive.
+    pub fn longest_common_directory(&self) -> Option<Cow<'_, Path>> {
+        let first_non_excluded = self.patterns.iter().find(|p| !p.value.pattern.is_excluded())?;
+        let common_prefix = first_non_excluded.value.pattern.path[..self.common_prefix_len].as_bstr();
+        let stripped_prefix = if first_non_excluded
+            .value
+            .pattern
+            .signature
+            .contains(MagicSignature::MUST_BE_DIR)
+        {
+            common_prefix
+        } else {
+            common_prefix[..common_prefix.rfind_byte(b'/')?].as_bstr()
+        };
+        Some(gix_path::from_bstr(stripped_prefix))
+    }
 }
 
 #[derive(Default, Clone, Debug)]

gix-pathspec/tests/search/mod.rs

@@ -330,6 +330,40 @@ fn simplified_search_handles_nil() -> crate::Result {
     Ok(())
 }
 
+#[test]
+fn longest_common_directory_no_prefix() -> crate::Result {
+    let search = gix_pathspec::Search::from_specs(pathspecs(&["tests/a/", "tests/b/", ":!*.sh"]), None, Path::new(""))?;
+    assert_eq!(search.common_prefix(), "tests/");
+    assert_eq!(search.prefix_directory(), Path::new(""));
+    assert_eq!(
+        search.longest_common_directory().expect("present").to_string_lossy(),
+        "tests/",
+        "trailing slashes are not stripped"
+    );
+    Ok(())
+}
+
+#[test]
+fn longest_common_directory_with_prefix() -> crate::Result {
+    let search = gix_pathspec::Search::from_specs(
+        pathspecs(&["tests/a/", "tests/b/", ":!*.sh"]),
+        Some(Path::new("a/b")),
+        Path::new(""),
+    )?;
+    assert_eq!(search.common_prefix(), "a/b/tests/");
+    assert_eq!(
+        search.prefix_directory().to_string_lossy(),
+        "a/b",
+        "trailing slashes are not contained"
+    );
+    assert_eq!(
+        search.longest_common_directory().expect("present").to_string_lossy(),
+        "a/b/tests/",
+        "trailing slashes are present, they don't matter"
+    );
+    Ok(())
+}
+
 #[test]
 fn init_with_exclude() -> crate::Result {
     let search = gix_pathspec::Search::from_specs(pathspecs(&["tests/", ":!*.sh"]), None, Path::new(""))?;
@@ -339,6 +373,16 @@ fn init_with_exclude() -> crate::Result {
         "re-orded so that excluded are first"
     );
     assert_eq!(search.common_prefix(), "tests");
+    assert_eq!(
+        search.prefix_directory(),
+        Path::new(""),
+        "there was no prefix during initialization"
+    );
+    assert_eq!(
+        search.longest_common_directory(),
+        Some(Path::new("tests").into()),
+        "but this works here, and it should be tested"
+    );
     assert!(
         search.can_match_relative_path("tests".into(), Some(true)),
         "prefix matches"
@@ -388,40 +432,49 @@ fn prefixes_are_always_case_sensitive() -> crate::Result {
     let path = gix_testtools::scripted_fixture_read_only("match_baseline_files.sh")?.join("paths");
     let items = baseline::parse_paths(path)?;
 
-    for (spec, prefix, common_prefix, expected) in [
-        (":(icase)bar", "FOO", "FOO", &["FOO/BAR", "FOO/bAr", "FOO/bar"] as &[_]),
-        (":(icase)bar", "F", "F", &[]),
-        (":(icase)bar", "FO", "FO", &[]),
-        (":(icase)../bar", "fOo", "", &["BAR", "bAr", "bar"]),
-        ("../bar", "fOo", "bar", &["bar"]),
-        ("    ", "", "    ", &["    "]),    // whitespace can match verbatim
-        ("  hi*", "", "  hi", &["  hi  "]), // whitespace can match with globs as well
-        (":(icase)../bar", "fO", "", &["BAR", "bAr", "bar"]), // prefixes are virtual, and don't have to exist at all.
+    for (spec, prefix, common_prefix, expected, expected_common_dir) in [
+        (
+            ":(icase)bar",
+            "FOO",
+            "FOO",
+            &["FOO/BAR", "FOO/bAr", "FOO/bar"] as &[_],
+            "FOO",
+        ),
+        (":(icase)bar", "F", "F", &[], "F"),
+        (":(icase)bar", "FO", "FO", &[], "FO"),
+        (":(icase)../bar", "fOo", "", &["BAR", "bAr", "bar"], ""),
+        ("../bar", "fOo", "bar", &["bar"], ""),
+        ("    ", "", "    ", &["    "], ""),    // whitespace can match verbatim
+        ("  hi*", "", "  hi", &["  hi  "], ""), // whitespace can match with globs as well
+        (":(icase)../bar", "fO", "", &["BAR", "bAr", "bar"], ""), // prefixes are virtual, and don't have to exist at all.
         (
             ":(icase)../foo/bar",
             "FOO",
             "",
             &[
                 "FOO/BAR", "FOO/bAr", "FOO/bar", "fOo/BAR", "fOo/bAr", "fOo/bar", "foo/BAR", "foo/bAr", "foo/bar",
             ],
+            "",
         ),
-        ("../foo/bar", "FOO", "foo/bar", &["foo/bar"]),
+        ("../foo/bar", "FOO", "foo/bar", &["foo/bar"], ""),
         (
             ":(icase)../foo/../fOo/bar",
             "FOO",
             "",
             &[
                 "FOO/BAR", "FOO/bAr", "FOO/bar", "fOo/BAR", "fOo/bAr", "fOo/bar", "foo/BAR", "foo/bAr", "foo/bar",
             ],
+            "",
         ),
-        ("../foo/../fOo/BAR", "FOO", "fOo/BAR", &["fOo/BAR"]),
+        ("../foo/../fOo/BAR", "FOO", "fOo/BAR", &["fOo/BAR"], ""),
     ] {
         let mut search = gix_pathspec::Search::from_specs(
             gix_pathspec::parse(spec.as_bytes(), Default::default()),
             Some(Path::new(prefix)),
             Path::new(""),
         )?;
         assert_eq!(search.common_prefix(), common_prefix, "{spec} {prefix}");
+        assert_eq!(search.prefix_directory(), Path::new(expected_common_dir));
         let actual: Vec<_> = items
             .iter()
             .filter(|relative_path| {
@@ -453,13 +506,13 @@ fn prefixes_are_always_case_sensitive() -> crate::Result {
 
 #[test]
 fn common_prefix() -> crate::Result {
-    for (specs, prefix, expected) in [
-        (&["foo/bar", ":(icase)foo/bar"] as &[_], None, ""),
-        (&["foo/bar", "foo"], None, "foo"),
-        (&["foo/bar/baz", "foo/bar/"], None, "foo/bar"), // directory trailing slashes are ignored, but that prefix shouldn't care anyway
-        (&[":(icase)bar", ":(icase)bart"], Some("foo"), "foo"), // only case-sensitive portions count
-        (&["bar", "bart"], Some("foo"), "foo/bar"),      // otherwise everything that matches counts
-        (&["bar", "bart", "ba"], Some("foo"), "foo/ba"),
+    for (specs, prefix, expected_common_prefix, expected_common_dir) in [
+        (&["foo/bar", ":(icase)foo/bar"] as &[_], None, "", ""),
+        (&["foo/bar", "foo"], None, "foo", ""),
+        (&["foo/bar/baz", "foo/bar/"], None, "foo/bar", ""), // directory trailing slashes are ignored, but that prefix shouldn't care anyway
+        (&[":(icase)bar", ":(icase)bart"], Some("foo"), "foo", "foo"), // only case-sensitive portions count
+        (&["bar", "bart"], Some("foo"), "foo/bar", "foo"),   // otherwise everything that matches counts
+        (&["bar", "bart", "ba"], Some("foo"), "foo/ba", "foo"),
     ] {
         let search = gix_pathspec::Search::from_specs(
             specs
@@ -468,7 +521,12 @@ fn common_prefix() -> crate::Result {
             prefix.map(Path::new),
             Path::new(""),
         )?;
-        assert_eq!(search.common_prefix(), expected, "{specs:?} {prefix:?}");
+        assert_eq!(search.common_prefix(), expected_common_prefix, "{specs:?} {prefix:?}");
+        assert_eq!(
+            search.prefix_directory(),
+            Path::new(expected_common_dir),
+            "{specs:?} {prefix:?}"
+        );
     }
     Ok(())
 }