Skip to main content

docsrs_cli/domain/
match_mode.rs

1//! Text match policy for `search-in-crate`.
2
3use crate::error::{AppError, AppResult, ErrorKind};
4
5/// Text match policy for `search-in-crate` (GAP-001 / GAP-019).
6#[derive(Debug, Clone, Copy, PartialEq, Eq, Default, serde::Serialize, serde::Deserialize)]
7#[serde(rename_all = "snake_case")]
8pub enum MatchMode {
9    /// Leaf name equals query (case-insensitive).
10    Exact,
11    /// Exact leaf or leaf starts with query — product default.
12    #[default]
13    Prefix,
14    /// Substring match on full path (legacy / opt-in).
15    Substring,
16}
17
18impl MatchMode {
19    /// Stable wire / CLI token.
20    #[must_use]
21    pub fn as_str(self) -> &'static str {
22        match self {
23            Self::Exact => "exact",
24            Self::Prefix => "prefix",
25            Self::Substring => "substring",
26        }
27    }
28
29    /// Parse CLI token (`exact` | `prefix` | `substring`).
30    ///
31    /// # Errors
32    ///
33    /// Returns [`ErrorKind::InvalidInput`] for unknown tokens.
34    pub fn parse(input: &str) -> AppResult<Self> {
35        match input.trim().to_ascii_lowercase().as_str() {
36            "exact" => Ok(Self::Exact),
37            "prefix" => Ok(Self::Prefix),
38            "substring" | "contains" | "substr" => Ok(Self::Substring),
39            other => Err(AppError::new(
40                ErrorKind::InvalidInput,
41                format!("unknown match mode '{other}' (expected exact|prefix|substring)"),
42            )),
43        }
44    }
45
46    /// Score a hit name against the query (lower is better). `None` = no match.
47    ///
48    /// `query` accepts any [`AsRef<str>`] (validated [`super::SearchQuery`] or
49    /// raw leaf text from HTML hits).
50    #[must_use]
51    pub fn score(self, name: &str, query: impl AsRef<str>) -> Option<u8> {
52        let q = query.as_ref().trim();
53        if q.is_empty() {
54            return Some(0);
55        }
56        let q = q.to_ascii_lowercase();
57        let name_l = name.to_ascii_lowercase();
58        let leaf = name_l.rsplit("::").next().unwrap_or(name_l.as_str());
59        let exact_leaf = leaf == q;
60        let prefix_leaf = leaf.starts_with(&q);
61        let exact_path = name_l == q;
62        let contains = name_l.contains(&q) || leaf.contains(&q);
63        match self {
64            Self::Exact => {
65                if exact_leaf {
66                    Some(0)
67                } else if exact_path {
68                    Some(1)
69                } else {
70                    None
71                }
72            }
73            Self::Prefix => {
74                if exact_leaf {
75                    Some(0)
76                } else if prefix_leaf {
77                    Some(1)
78                } else if exact_path {
79                    Some(2)
80                } else {
81                    None
82                }
83            }
84            Self::Substring => {
85                if exact_leaf {
86                    Some(0)
87                } else if prefix_leaf {
88                    Some(1)
89                } else if exact_path {
90                    Some(2)
91                } else if contains {
92                    Some(3)
93                } else {
94                    None
95                }
96            }
97        }
98    }
99}
100
101impl std::str::FromStr for MatchMode {
102    type Err = AppError;
103    fn from_str(s: &str) -> Result<Self, Self::Err> {
104        Self::parse(s)
105    }
106}