Skip to main content

docsrs_cli/domain/
crate_name.rs

1//! Validated crates.io / stdlib crate name.
2
3use std::fmt;
4use std::str::FromStr;
5use std::sync::LazyLock;
6
7use regex::Regex;
8
9use crate::config::MAX_CRATE_NAME_CHARS;
10use crate::error::{AppError, AppResult, ErrorKind};
11
12use super::regex::compile_bounded_regex;
13
14/// Canonical stdlib crate names documented on `doc.rust-lang.org` (single source).
15pub(crate) const STDLIB_NAMES: &[&str] = &["std", "core", "alloc"];
16
17/// True when `name` is a Rust standard library crate (`std` / `core` / `alloc`).
18///
19/// Accepts raw strings for HTML scrape / allowlist helpers. Prefer
20/// [`CrateName::is_stdlib`] when a validated name is already in hand.
21#[must_use]
22pub fn is_stdlib_name(name: &str) -> bool {
23    STDLIB_NAMES.contains(&name)
24}
25
26/// Validated crates.io / stdlib crate name.
27#[repr(transparent)]
28#[derive(Debug, Clone, PartialEq, Eq, Hash)]
29pub struct CrateName(String);
30
31impl CrateName {
32    /// Parses and validates a crate name (trim, length, charset).
33    ///
34    /// # Errors
35    ///
36    /// Returns [`ErrorKind::InvalidInput`] when the name is empty, too long, or
37    /// contains characters outside the crates.io charset.
38    ///
39    /// # Examples
40    ///
41    /// ```
42    /// use docsrs_cli::domain::CrateName;
43    ///
44    /// let name = CrateName::parse("tokio").expect("valid");
45    /// assert_eq!(name.as_str(), "tokio");
46    /// assert!(CrateName::parse("").is_err());
47    /// ```
48    pub fn parse(name: &str) -> AppResult<Self> {
49        let name = name.trim();
50        if name.is_empty() {
51            return Err(AppError::new(
52                ErrorKind::InvalidInput,
53                "crate name is empty",
54            ));
55        }
56        if name.chars().count() > MAX_CRATE_NAME_CHARS {
57            return Err(AppError::new(
58                ErrorKind::InvalidInput,
59                format!("crate name exceeds {MAX_CRATE_NAME_CHARS} characters"),
60            ));
61        }
62        static RE: LazyLock<Regex> = LazyLock::new(|| {
63            compile_bounded_regex(r"^[a-zA-Z][a-zA-Z0-9_-]*$")
64                .expect("hardcoded crate-name regex is valid by construction")
65        });
66        if !RE.is_match(name) {
67            return Err(AppError::new(
68                ErrorKind::InvalidInput,
69                format!("invalid crate name '{name}'"),
70            ));
71        }
72        Ok(Self(name.to_string()))
73    }
74
75    /// Borrow the validated name.
76    #[must_use]
77    pub fn as_str(&self) -> &str {
78        &self.0
79    }
80
81    /// True for `std` / `core` / `alloc` (docs on doc.rust-lang.org).
82    #[must_use]
83    pub fn is_stdlib(&self) -> bool {
84        is_stdlib_name(self.as_str())
85    }
86}
87
88impl AsRef<str> for CrateName {
89    fn as_ref(&self) -> &str {
90        self.as_str()
91    }
92}
93
94impl fmt::Display for CrateName {
95    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
96        f.write_str(self.as_str())
97    }
98}
99
100impl FromStr for CrateName {
101    type Err = AppError;
102
103    /// Parses via [`CrateName::parse`].
104    ///
105    /// # Errors
106    ///
107    /// Returns [`ErrorKind::InvalidInput`] for empty, oversized, or illegal names.
108    fn from_str(s: &str) -> Result<Self, Self::Err> {
109        Self::parse(s)
110    }
111}
112
113impl TryFrom<&str> for CrateName {
114    type Error = AppError;
115
116    /// Converts via [`CrateName::parse`].
117    ///
118    /// # Errors
119    ///
120    /// Returns [`ErrorKind::InvalidInput`] for empty, oversized, or illegal names.
121    fn try_from(value: &str) -> Result<Self, Self::Error> {
122        Self::parse(value)
123    }
124}
125
126#[cfg(test)]
127mod tests {
128    use super::*;
129    use std::mem::size_of;
130
131    #[test]
132    fn crate_name_ok_and_stdlib() {
133        let s = CrateName::parse("serde").unwrap();
134        assert_eq!(s.as_str(), "serde");
135        assert!(!s.is_stdlib());
136        assert!(CrateName::parse("async-trait").unwrap().as_str() == "async-trait");
137        for n in STDLIB_NAMES {
138            let c = CrateName::parse(n).unwrap();
139            assert!(c.is_stdlib(), "{n}");
140            assert!(is_stdlib_name(n));
141        }
142        assert!(!is_stdlib_name("serde"));
143    }
144
145    #[test]
146    fn crate_name_err() {
147        assert!(CrateName::parse("").is_err());
148        assert!(CrateName::parse("1bad").is_err());
149        assert!(CrateName::parse(&"a".repeat(MAX_CRATE_NAME_CHARS + 1)).is_err());
150    }
151
152    #[test]
153    fn crate_name_transparent_layout() {
154        assert_eq!(size_of::<CrateName>(), size_of::<String>());
155    }
156}