Skip to main content

docsrs_cli/domain/
crate_ref.rs

1//! Crate reference with optional `name@version` sugar.
2
3use crate::error::{AppError, AppResult, ErrorKind};
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 [`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::new(
45                ErrorKind::InvalidInput,
46                "crate name is empty",
47            ));
48        }
49        if let Some((name_part, ver_part)) = raw.split_once('@') {
50            if name_part.is_empty() {
51                return Err(AppError::new(
52                    ErrorKind::InvalidInput,
53                    "crate name is empty before '@'",
54                ));
55            }
56            if ver_part.is_empty() {
57                return Err(AppError::new(
58                    ErrorKind::InvalidInput,
59                    "version is empty after '@'",
60                ));
61            }
62            if ver_part.contains('@') {
63                return Err(AppError::new(
64                    ErrorKind::InvalidInput,
65                    "crate reference must contain at most one '@'",
66                ));
67            }
68            let name = CrateName::parse(name_part)?;
69            let version = VersionArg::parse(ver_part)?;
70            Ok(Self {
71                name,
72                version: Some(version),
73            })
74        } else {
75            Ok(Self {
76                name: CrateName::parse(raw)?,
77                version: None,
78            })
79        }
80    }
81
82    /// Merge `@version` sugar with an optional `--crate-version` flag.
83    ///
84    /// Precedence: when both are present they must agree; otherwise the
85    /// non-empty source wins. Missing both → `latest`.
86    ///
87    /// # Errors
88    ///
89    /// Returns [`ErrorKind::InvalidInput`] on conflicting versions or invalid flag.
90    pub fn into_name_and_version(
91        self,
92        crate_version_flag: Option<&str>,
93    ) -> AppResult<(CrateName, VersionArg)> {
94        let flag = crate_version_flag
95            .map(str::trim)
96            .filter(|s| !s.is_empty());
97        match (self.version, flag) {
98            (Some(from_at), Some(flag_raw)) => {
99                let from_flag = VersionArg::parse(flag_raw)?;
100                if from_at.as_str() != from_flag.as_str() {
101                    return Err(AppError::new(
102                        ErrorKind::InvalidInput,
103                        format!(
104                            "conflicting versions: crate@{} vs --crate-version {}",
105                            from_at.as_str(),
106                            from_flag.as_str()
107                        ),
108                    ));
109                }
110                Ok((self.name, from_at))
111            }
112            (Some(from_at), None) => Ok((self.name, from_at)),
113            (None, flag_raw) => Ok((self.name, VersionArg::parse_opt(flag_raw)?)),
114        }
115    }
116}
117
118#[cfg(test)]
119mod tests {
120    use super::*;
121
122    #[test]
123    fn crate_ref_plain_and_at_version() {
124        let p = CrateRef::parse("serde").unwrap();
125        assert_eq!(p.name.as_str(), "serde");
126        assert!(p.version.is_none());
127        let (n, v) = p.into_name_and_version(None).unwrap();
128        assert_eq!(n.as_str(), "serde");
129        assert_eq!(v.as_str(), "latest");
130
131        let at = CrateRef::parse("clap@4.5.0").unwrap();
132        assert_eq!(at.name.as_str(), "clap");
133        assert_eq!(at.version.as_ref().unwrap().as_str(), "4.5.0");
134        let (n, v) = at.into_name_and_version(None).unwrap();
135        assert_eq!(v.as_str(), "4.5.0");
136        assert_eq!(n.as_str(), "clap");
137    }
138
139    #[test]
140    fn crate_ref_merge_and_errors() {
141        let at = CrateRef::parse("tokio@1.0.0").unwrap();
142        let (n, v) = at.clone().into_name_and_version(Some("1.0.0")).unwrap();
143        assert_eq!(n.as_str(), "tokio");
144        assert_eq!(v.as_str(), "1.0.0");
145        assert!(
146            CrateRef::parse("tokio@1.0.0")
147                .unwrap()
148                .into_name_and_version(Some("2.0.0"))
149                .is_err()
150        );
151        assert!(CrateRef::parse("clap@v4.5.0").is_err());
152        assert!(CrateRef::parse("@1.0.0").is_err());
153        assert!(CrateRef::parse("clap@").is_err());
154        assert!(CrateRef::parse("a@b@c").is_err());
155        let plain = CrateRef::parse("once_cell").unwrap();
156        let (_, v) = plain.into_name_and_version(Some("1.21.0")).unwrap();
157        assert_eq!(v.as_str(), "1.21.0");
158    }
159}