Skip to main content

docsrs_cli/domain/
version.rs

1//! Validated crate version token.
2
3use std::fmt;
4use std::str::FromStr;
5use std::sync::LazyLock;
6
7use regex::Regex;
8
9use crate::config::MAX_VERSION_CHARS;
10use crate::error::{AppError, AppResult, ErrorKind};
11
12use super::regex::compile_bounded_regex;
13
14/// Validated crate version token (`latest`, channel, or SemVer without `v` prefix).
15#[repr(transparent)]
16#[derive(Debug, Clone, PartialEq, Eq, Hash)]
17pub struct VersionArg(String);
18
19impl VersionArg {
20    /// Parse optional CLI version; empty/`None` → `latest`.
21    ///
22    /// # Errors
23    ///
24    /// Propagates [`ErrorKind::InvalidInput`] from [`Self::parse`] when the
25    /// provided token is present and invalid.
26    pub fn parse_opt(raw: Option<&str>) -> AppResult<Self> {
27        let v = raw
28            .map(str::trim)
29            .filter(|s| !s.is_empty())
30            .unwrap_or("latest");
31        Self::parse(v)
32    }
33
34    /// Parses a non-optional version token.
35    ///
36    /// # Errors
37    ///
38    /// Returns [`ErrorKind::InvalidInput`] for unknown channels, `v`-prefixed
39    /// SemVer, build metadata, or malformed versions.
40    pub fn parse(v: &str) -> AppResult<Self> {
41        let v = v.trim();
42        if v.chars().count() > MAX_VERSION_CHARS {
43            return Err(AppError::new(
44                ErrorKind::InvalidInput,
45                format!("version exceeds {MAX_VERSION_CHARS} characters"),
46            ));
47        }
48        if v == "latest" {
49            return Ok(Self(v.to_string()));
50        }
51        if matches!(v, "stable" | "beta" | "nightly") {
52            return Ok(Self(v.to_string()));
53        }
54        if v.starts_with('v') || v.starts_with('V') {
55            return Err(AppError::new(
56                ErrorKind::InvalidInput,
57                "version must not start with 'v' prefix",
58            ));
59        }
60        if v.contains('+') {
61            return Err(AppError::new(
62                ErrorKind::InvalidInput,
63                "version build metadata is not accepted",
64            ));
65        }
66        static RE: LazyLock<Regex> = LazyLock::new(|| {
67            compile_bounded_regex(r"^\d+\.\d+\.\d+(-[0-9A-Za-z.-]+)?$")
68                .expect("hardcoded semver-ish version regex is valid by construction")
69        });
70        if !RE.is_match(v) {
71            return Err(AppError::new(
72                ErrorKind::InvalidInput,
73                format!("invalid version '{v}'"),
74            ));
75        }
76        Ok(Self(v.to_string()))
77    }
78
79    /// Borrow the version token.
80    #[must_use]
81    pub fn as_str(&self) -> &str {
82        &self.0
83    }
84
85    /// Map to rustdoc channel for stdlib paths (`latest` → `stable`).
86    ///
87    /// Single source of truth for channel mapping (TYPE-L-010).
88    #[must_use]
89    pub fn stdlib_channel(&self) -> &str {
90        match self.as_str() {
91            "latest" => "stable",
92            other => other,
93        }
94    }
95}
96
97impl AsRef<str> for VersionArg {
98    fn as_ref(&self) -> &str {
99        self.as_str()
100    }
101}
102
103impl fmt::Display for VersionArg {
104    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
105        f.write_str(self.as_str())
106    }
107}
108
109impl FromStr for VersionArg {
110    type Err = AppError;
111
112    /// Parses via [`VersionArg::parse`].
113    ///
114    /// # Errors
115    ///
116    /// Returns [`ErrorKind::InvalidInput`] for unknown channels or malformed versions.
117    fn from_str(s: &str) -> Result<Self, Self::Err> {
118        Self::parse(s)
119    }
120}
121
122#[cfg(test)]
123mod tests {
124    use super::*;
125    use std::mem::size_of;
126
127    #[test]
128    fn version_arg_policy() {
129        assert_eq!(VersionArg::parse_opt(None).unwrap().as_str(), "latest");
130        assert_eq!(VersionArg::parse_opt(Some("")).unwrap().as_str(), "latest");
131        assert_eq!(VersionArg::parse("1.0.0").unwrap().as_str(), "1.0.0");
132        assert_eq!(
133            VersionArg::parse("stable").unwrap().stdlib_channel(),
134            "stable"
135        );
136        assert_eq!(
137            VersionArg::parse("latest").unwrap().stdlib_channel(),
138            "stable"
139        );
140        assert!(VersionArg::parse("v1.0.0").is_err());
141        assert!(VersionArg::parse("1.0.0+build").is_err());
142        assert!(VersionArg::parse("not-a-version").is_err());
143    }
144
145    #[test]
146    fn version_arg_transparent_layout() {
147        assert_eq!(size_of::<VersionArg>(), size_of::<String>());
148    }
149}