Skip to main content

docsrs_cli/domain/
crate_ref.rs

1//! Crate reference with optional `name@version` sugar.
2
3use crate::error::{AppError, AppResult, ErrorDetail, Subject};
4
5use super::{CrateName, VersionArg};
6
7/// Crate reference with optional `name@version` sugar (R2).
8///
9/// Accepts plain names (`serde`) or `@`-qualified versions (`clap@4.5.0`,
10/// `std@stable`). The `@` form is agent-friendly sugar equivalent to
11/// `--crate-version`.
12#[derive(Debug, Clone, PartialEq, Eq)]
13pub struct CrateRef {
14    /// Validated crate name.
15    pub name: CrateName,
16    /// Version from `@…` when present.
17    pub version: Option<VersionArg>,
18}
19
20impl CrateRef {
21    /// Parse `crate` or `crate@version`.
22    ///
23    /// # Errors
24    ///
25    /// Returns [`crate::error::ErrorKind::InvalidInput`] for empty parts, illegal names, or
26    /// invalid version tokens (including a forbidden `v` SemVer prefix).
27    ///
28    /// # Examples
29    ///
30    /// ```
31    /// use docsrs_cli::domain::CrateRef;
32    ///
33    /// let plain = CrateRef::parse("tokio").expect("ok");
34    /// assert_eq!(plain.name.as_str(), "tokio");
35    /// assert!(plain.version.is_none());
36    ///
37    /// let at = CrateRef::parse("clap@4.5.0").expect("ok");
38    /// assert_eq!(at.name.as_str(), "clap");
39    /// assert_eq!(at.version.as_ref().unwrap().as_str(), "4.5.0");
40    /// ```
41    pub fn parse(raw: &str) -> AppResult<Self> {
42        let raw = raw.trim();
43        if raw.is_empty() {
44            return Err(AppError::of(ErrorDetail::Empty {
45                subject: Subject::CrateName,
46            }));
47        }
48        if let Some((name_part, ver_part)) = raw.split_once('@') {
49            if name_part.is_empty() {
50                return Err(AppError::of(ErrorDetail::CrateRefEmptyName));
51            }
52            if ver_part.is_empty() {
53                return Err(AppError::of(ErrorDetail::CrateRefEmptyVersion));
54            }
55            if ver_part.contains('@') {
56                return Err(AppError::of(ErrorDetail::CrateRefMultipleAt));
57            }
58            let name = CrateName::parse(name_part)?;
59            let version = VersionArg::parse(ver_part)?;
60            Ok(Self {
61                name,
62                version: Some(version),
63            })
64        } else {
65            Ok(Self {
66                name: CrateName::parse(raw)?,
67                version: None,
68            })
69        }
70    }
71
72    /// Merge `@version` sugar with an optional `--crate-version` flag.
73    ///
74    /// Precedence: when both are present they must agree; otherwise the
75    /// non-empty source wins. Missing both → `latest`.
76    ///
77    /// # Errors
78    ///
79    /// Returns [`crate::error::ErrorKind::InvalidInput`] on conflicting versions or invalid flag.
80    pub fn into_name_and_version(
81        self,
82        crate_version_flag: Option<&str>,
83    ) -> AppResult<(CrateName, VersionArg)> {
84        let flag = crate_version_flag.map(str::trim).filter(|s| !s.is_empty());
85        match (self.version, flag) {
86            (Some(from_at), Some(flag_raw)) => {
87                let from_flag = VersionArg::parse(flag_raw)?;
88                if from_at.as_str() != from_flag.as_str() {
89                    return Err(AppError::of(ErrorDetail::ConflictingVersions {
90                        from_ref: from_at.as_str().to_string(),
91                        from_flag: from_flag.as_str().to_string(),
92                    }));
93                }
94                Ok((self.name, from_at))
95            }
96            (Some(from_at), None) => Ok((self.name, from_at)),
97            (None, flag_raw) => Ok((self.name, VersionArg::parse_opt(flag_raw)?)),
98        }
99    }
100}
101
102#[cfg(test)]
103mod tests {
104    use super::*;
105
106    #[test]
107    fn crate_ref_plain_and_at_version() {
108        let p = CrateRef::parse("serde").unwrap();
109        assert_eq!(p.name.as_str(), "serde");
110        assert!(p.version.is_none());
111        let (n, v) = p.into_name_and_version(None).unwrap();
112        assert_eq!(n.as_str(), "serde");
113        assert_eq!(v.as_str(), "latest");
114
115        let at = CrateRef::parse("clap@4.5.0").unwrap();
116        assert_eq!(at.name.as_str(), "clap");
117        assert_eq!(at.version.as_ref().unwrap().as_str(), "4.5.0");
118        let (n, v) = at.into_name_and_version(None).unwrap();
119        assert_eq!(v.as_str(), "4.5.0");
120        assert_eq!(n.as_str(), "clap");
121    }
122
123    #[test]
124    fn crate_ref_merge_and_errors() {
125        let at = CrateRef::parse("tokio@1.0.0").unwrap();
126        let (n, v) = at.clone().into_name_and_version(Some("1.0.0")).unwrap();
127        assert_eq!(n.as_str(), "tokio");
128        assert_eq!(v.as_str(), "1.0.0");
129        assert!(
130            CrateRef::parse("tokio@1.0.0")
131                .unwrap()
132                .into_name_and_version(Some("2.0.0"))
133                .is_err()
134        );
135        assert!(CrateRef::parse("clap@v4.5.0").is_err());
136        assert!(CrateRef::parse("@1.0.0").is_err());
137        assert!(CrateRef::parse("clap@").is_err());
138        assert!(CrateRef::parse("a@b@c").is_err());
139        let plain = CrateRef::parse("once_cell").unwrap();
140        let (_, v) = plain.into_name_and_version(Some("1.21.0")).unwrap();
141        assert_eq!(v.as_str(), "1.21.0");
142    }
143}