feat!: add search::MatchKind, which is available for any search::Match.

With it the caller can learn how or why the pathspec matched,
which allows to make decisions based on it that are relevant
to the user interface.

Author: Byron

gix-pathspec/src/search/matching.rs

@@ -1,6 +1,8 @@
 use bstr::{BStr, BString, ByteSlice};
 use gix_glob::pattern::Case;
 
+use crate::search::MatchKind;
+use crate::search::MatchKind::*;
 use crate::{
     search::{Match, Spec},
     MagicSignature, Pattern, Search, SearchMode,
@@ -53,9 +55,10 @@ impl Search {
 
             let case = if ignore_case { Case::Fold } else { Case::Sensitive };
             let mut is_match = mapping.value.pattern.always_matches();
+            let mut how = Always;
             if !is_match {
                 is_match = if mapping.pattern.first_wildcard_pos.is_none() {
-                    match_verbatim(mapping, relative_path, is_dir, case)
+                    match_verbatim(mapping, relative_path, is_dir, case, &mut how)
                 } else {
                     let wildmatch_mode = match mapping.value.pattern.search_mode {
                         SearchMode::ShellGlob => Some(gix_glob::wildmatch::Mode::empty()),
@@ -72,12 +75,13 @@ impl Search {
                                 wildmatch_mode,
                             );
                             if !is_match {
-                                match_verbatim(mapping, relative_path, is_dir, case)
+                                match_verbatim(mapping, relative_path, is_dir, case, &mut how)
                             } else {
+                                how = mapping.pattern.first_wildcard_pos.map_or(Verbatim, |_| WildcardMatch);
                                 true
                             }
                         }
-                        None => match_verbatim(mapping, relative_path, is_dir, case),
+                        None => match_verbatim(mapping, relative_path, is_dir, case, &mut how),
                     }
                 }
             }
@@ -97,6 +101,7 @@ impl Search {
             is_match.then_some(Match {
                 pattern: &mapping.value.pattern,
                 sequence_number: mapping.sequence_number,
+                kind: how,
             })
         });
 
@@ -112,6 +117,7 @@ impl Search {
             Some(Match {
                 pattern: &MATCH_ALL_STAND_IN,
                 sequence_number: patterns_len,
+                kind: Always,
             })
         } else {
             res
@@ -185,16 +191,18 @@ fn match_verbatim(
     relative_path: &BStr,
     is_dir: bool,
     case: Case,
+    how: &mut MatchKind,
 ) -> bool {
     let pattern_len = mapping.value.pattern.path.len();
     let mut relative_path_ends_with_slash_at_pattern_len = false;
-    let match_is_allowed = relative_path.get(pattern_len).map_or_else(
-        || relative_path.len() == pattern_len,
+    let (match_is_allowed, probably_how) = relative_path.get(pattern_len).map_or_else(
+        || (relative_path.len() == pattern_len, Verbatim),
         |b| {
             relative_path_ends_with_slash_at_pattern_len = *b == b'/';
-            relative_path_ends_with_slash_at_pattern_len
+            (relative_path_ends_with_slash_at_pattern_len, Prefix)
         },
     );
+    *how = probably_how;
     let pattern_requirement_is_met = !mapping.pattern.mode.contains(gix_glob::pattern::Mode::MUST_BE_DIR)
         || (relative_path_ends_with_slash_at_pattern_len || is_dir);
 

gix-pathspec/src/search/mod.rs

@@ -9,6 +9,22 @@ pub struct Match<'a> {
     pub pattern: &'a Pattern,
     /// The number of the sequence the matching pathspec was in, or the line of pathspec file it was read from if [Search::source] is not `None`.
     pub sequence_number: usize,
+    /// How the pattern matched.
+    pub kind: MatchKind,
+}
+
+/// Describe how a pathspec pattern matched.
+#[derive(Copy, Clone, PartialEq, Eq, Debug, Hash, Ord, PartialOrd)]
+pub enum MatchKind {
+    /// The match happened because there wasn't any pattern, which matches all, or because there was a nil pattern or one with an empty path.
+    /// Thus this is not a match by merit.
+    Always,
+    /// The first part of a pathspec matches, like `dir/` that matches `dir/a`.
+    Prefix,
+    /// The whole pathspec matched and used a wildcard match, like `a/*` matching `a/file`.
+    WildcardMatch,
+    /// The entire pathspec matched, letter by letter, e.g. `a/file` matching `a/file`.
+    Verbatim,
 }
 
 mod init;

gix-pathspec/tests/search/mod.rs

@@ -1,3 +1,5 @@
+use bstr::BStr;
+use gix_pathspec::search::MatchKind::*;
 use std::path::Path;
 
 #[test]
@@ -10,29 +12,67 @@ fn no_pathspecs_match_everything() -> crate::Result {
     let mut search = gix_pathspec::Search::from_specs([], None, Path::new(""))?;
     assert_eq!(search.patterns().count(), 0, "nothing artificial is added");
     let m = search
-        .pattern_matching_relative_path("hello".into(), None, &mut |_, _, _, _| {
-            unreachable!("must not be called")
-        })
+        .pattern_matching_relative_path("hello".into(), None, &mut no_attrs)
         .expect("matches");
     assert_eq!(m.pattern.prefix_directory(), "", "there is no prefix as none was given");
+    assert_eq!(m.kind, Always, "no pathspec always matches");
     assert_eq!(
         m.sequence_number, 0,
         "this is actually a fake pattern, as we have to match even though there isn't anything"
     );
-
     assert!(search.can_match_relative_path("anything".into(), None));
+    Ok(())
+}
 
+#[test]
+fn starts_with() -> crate::Result {
+    let mut search = gix_pathspec::Search::from_specs(pathspecs(&["a/*"]), None, Path::new(""))?;
+    assert!(
+        search
+            .pattern_matching_relative_path("a".into(), Some(false), &mut no_attrs)
+            .is_none(),
+        "this can only match if it's a directory"
+    );
+    assert!(
+        search
+            .pattern_matching_relative_path("a".into(), Some(true), &mut no_attrs)
+            .is_none(),
+        "can't match as the '*' part is missing in value"
+    );
+    assert!(
+        search.can_match_relative_path("a".into(), Some(true)),
+        "prefix-matches work though"
+    );
+    assert!(
+        search.can_match_relative_path("a".into(), Some(false)),
+        "but not if it's a file"
+    );
+    assert!(
+        search.can_match_relative_path("a".into(), None),
+        "if unspecified, we match for good measure"
+    );
+    assert_eq!(
+        search
+            .pattern_matching_relative_path("a/file".into(), None, &mut no_attrs)
+            .expect("matches")
+            .kind,
+        WildcardMatch,
+        "a wildmatch is always performed here, even though it looks like a prefix"
+    );
     Ok(())
 }
 
 #[test]
 fn simplified_search_respects_must_be_dir() -> crate::Result {
     let mut search = gix_pathspec::Search::from_specs(pathspecs(&["a/be/"]), None, Path::new(""))?;
-    search
-        .pattern_matching_relative_path("a/be/file".into(), Some(false), &mut |_, _, _, _| {
-            unreachable!("must not be called")
-        })
-        .expect("matches as this is a prefix match");
+    assert_eq!(
+        search
+            .pattern_matching_relative_path("a/be/file".into(), Some(false), &mut no_attrs)
+            .expect("matches as this is a prefix match")
+            .kind,
+        Prefix,
+        "a verbatim part of the spec matches"
+    );
     assert!(
         !search.can_match_relative_path("any".into(), Some(false)),
         "not our directory: a, and must be dir"
@@ -79,7 +119,7 @@ fn simplified_search_respects_must_be_dir() -> crate::Result {
     );
     assert!(
         search
-            .pattern_matching_relative_path("a/b".into(), None, &mut |_, _, _, _| unreachable!("must not be called"))
+            .pattern_matching_relative_path("a/b".into(), None, &mut no_attrs)
             .is_none(),
         "no match if it's not the whole pattern that matches"
     );
@@ -183,21 +223,20 @@ fn no_pathspecs_respect_prefix() -> crate::Result {
     );
     assert!(
         search
-            .pattern_matching_relative_path("hello".into(), None, &mut |_, _, _, _| unreachable!(
-                "must not be called"
-            ))
+            .pattern_matching_relative_path("hello".into(), None, &mut no_attrs)
             .is_none(),
         "not the right prefix"
     );
     assert!(!search.can_match_relative_path("hello".into(), None));
     let m = search
-        .pattern_matching_relative_path("a/b".into(), None, &mut |_, _, _, _| unreachable!("must not be called"))
+        .pattern_matching_relative_path("a/b".into(), None, &mut no_attrs)
         .expect("match");
     assert_eq!(
         m.pattern.prefix_directory(),
         "a",
         "the prefix directory matched verbatim"
     );
+    assert_eq!(m.kind, Prefix, "the common path also works like a prefix");
     assert!(search.can_match_relative_path("a/".into(), Some(true)));
     assert!(search.can_match_relative_path("a".into(), Some(true)));
     assert!(!search.can_match_relative_path("a".into(), Some(false)));
@@ -249,7 +288,7 @@ fn prefixes_are_always_case_sensitive() -> crate::Result {
             .iter()
             .filter(|relative_path| {
                 search
-                    .pattern_matching_relative_path(relative_path.as_str().into(), Some(false), &mut |_, _, _, _| false)
+                    .pattern_matching_relative_path(relative_path.as_str().into(), Some(false), &mut no_attrs)
                     .is_some()
             })
             .collect();
@@ -442,3 +481,7 @@ mod baseline {
         Ok((root, items, expected))
     }
 }
+
+fn no_attrs(_: &BStr, _: gix_glob::pattern::Case, _: bool, _: &mut gix_attributes::search::Outcome) -> bool {
+    unreachable!("must not be called")
+}