quillmark_core/
version.rs

1//! # Version Management
2//!
3//! Semantic versioning (MAJOR.MINOR.PATCH) for Quill template references.
4//! Two-segment (`MAJOR.MINOR`) versions are also accepted; patch defaults to 0.
5//!
6//! Key types: [`Version`], [`VersionSelector`], [`QuillReference`].
7
8use std::cmp::Ordering;
9use std::fmt;
10use std::str::FromStr;
11
12/// Semantic version number (MAJOR.MINOR.PATCH).
13/// Two-segment form (`MAJOR.MINOR`) is also accepted; patch defaults to 0.
14#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
15pub struct Version {
16    pub major: u32,
17    pub minor: u32,
18    pub patch: u32,
19}
20
21impl Version {
22    pub fn new(major: u32, minor: u32, patch: u32) -> Self {
23        Self {
24            major,
25            minor,
26            patch,
27        }
28    }
29}
30
31impl FromStr for Version {
32    type Err = String;
33
34    fn from_str(s: &str) -> Result<Self, Self::Err> {
35        let parts: Vec<&str> = s.split('.').collect();
36
37        if !matches!(parts.len(), 2 | 3) {
38            return Err(format!(
39                "Invalid version format '{}': expected MAJOR.MINOR.PATCH or MAJOR.MINOR (e.g., '2.1.0' or '2.1')",
40                s
41            ));
42        }
43
44        let major = parts[0]
45            .parse::<u32>()
46            .map_err(|_| format!("Invalid major version '{}': must be a number", parts[0]))?;
47
48        let minor = parts[1]
49            .parse::<u32>()
50            .map_err(|_| format!("Invalid minor version '{}': must be a number", parts[1]))?;
51
52        let patch = if parts.len() == 3 {
53            parts[2]
54                .parse::<u32>()
55                .map_err(|_| format!("Invalid patch version '{}': must be a number", parts[2]))?
56        } else {
57            0
58        };
59
60        Ok(Version {
61            major,
62            minor,
63            patch,
64        })
65    }
66}
67
68impl fmt::Display for Version {
69    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
70        write!(f, "{}.{}.{}", self.major, self.minor, self.patch)
71    }
72}
73
74impl PartialOrd for Version {
75    fn partial_cmp(&self, other: &Self) -> Option<Ordering> {
76        Some(self.cmp(other))
77    }
78}
79
80impl Ord for Version {
81    fn cmp(&self, other: &Self) -> Ordering {
82        match self.major.cmp(&other.major) {
83            Ordering::Equal => match self.minor.cmp(&other.minor) {
84                Ordering::Equal => self.patch.cmp(&other.patch),
85                other => other,
86            },
87            other => other,
88        }
89    }
90}
91
92/// Specifies which version of a Quill template to use.
93#[derive(Debug, Clone, PartialEq, Eq, Hash)]
94pub enum VersionSelector {
95    /// Match exactly this version (e.g., "@2.1.0")
96    Exact(Version),
97    /// Match latest patch version in this minor series (e.g., "@2.1")
98    Minor(u32, u32),
99    /// Match latest minor/patch version in this major series (e.g., "@2")
100    Major(u32),
101    /// Match the highest version available (e.g., "@latest" or unspecified)
102    Latest,
103}
104
105impl FromStr for VersionSelector {
106    type Err = String;
107
108    fn from_str(s: &str) -> Result<Self, Self::Err> {
109        let version_str = s.strip_prefix('@').unwrap_or(s);
110
111        if version_str.is_empty() || version_str == "latest" {
112            return Ok(VersionSelector::Latest);
113        }
114
115        let parts: Vec<&str> = version_str.split('.').collect();
116
117        match parts.len() {
118            3 => {
119                let version = Version::from_str(version_str)?;
120                Ok(VersionSelector::Exact(version))
121            }
122            2 => {
123                let major = parts[0].parse::<u32>().map_err(|_| {
124                    format!("Invalid major version '{}': must be a number", parts[0])
125                })?;
126                let minor = parts[1].parse::<u32>().map_err(|_| {
127                    format!("Invalid minor version '{}': must be a number", parts[1])
128                })?;
129                Ok(VersionSelector::Minor(major, minor))
130            }
131            1 => {
132                let major = version_str.parse::<u32>().map_err(|_| {
133                    format!(
134                        "Invalid version selector '{}': expected number, MAJOR.MINOR, MAJOR.MINOR.PATCH, or 'latest'",
135                        version_str
136                    )
137                })?;
138                Ok(VersionSelector::Major(major))
139            }
140            _ => Err(format!(
141                "Invalid version selector '{}': expected number, MAJOR.MINOR, MAJOR.MINOR.PATCH, or 'latest'",
142                version_str
143            )),
144        }
145    }
146}
147
148impl fmt::Display for VersionSelector {
149    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
150        match self {
151            VersionSelector::Exact(v) => write!(f, "@{}", v),
152            VersionSelector::Minor(major, minor) => write!(f, "@{}.{}", major, minor),
153            VersionSelector::Major(m) => write!(f, "@{}", m),
154            VersionSelector::Latest => write!(f, "@latest"),
155        }
156    }
157}
158
159/// Canonical, author-facing `$quill` reference grammar.
160const QUILL_REF_HINT: &str = "A $quill reference is `<name>` or `<name>@<selector>`. \
161The name must match `[a-z_][a-z0-9_]*` (start with a lowercase letter or underscore, then \
162lowercase letters, digits, or underscores). The optional version selector is \
163`@MAJOR.MINOR.PATCH` (exact), `@MAJOR.MINOR` (latest patch in that minor series), `@MAJOR` \
164(latest in that major series), or `@latest`; omitting the selector means latest.";
165
166/// Single source of truth for the grammar [`QuillReference::from_str`] enforces:
167/// bindings surface it (schema `describe`, validation hints) and it rides as the
168/// `hint` on the `parse::invalid_quill_reference` diagnostic, so error and
169/// describe text can't drift from the parser. Sibling of `document`'s
170/// `FORMAT_RULES` / `blueprint_instruction`.
171pub fn quill_ref_hint() -> &'static str {
172    QUILL_REF_HINT
173}
174
175/// Complete reference to a Quill template with name and version selector.
176///
177/// Name charset: `[a-z_][a-z0-9_]*`. Selector defaults to `Latest` when omitted.
178#[derive(Debug, Clone, PartialEq, Eq, Hash)]
179pub struct QuillReference {
180    pub name: String,
181    pub selector: VersionSelector,
182}
183
184impl QuillReference {
185    pub fn new(name: String, selector: VersionSelector) -> Self {
186        Self { name, selector }
187    }
188
189    pub fn latest(name: String) -> Self {
190        Self {
191            name,
192            selector: VersionSelector::Latest,
193        }
194    }
195}
196
197impl FromStr for QuillReference {
198    type Err = String;
199
200    fn from_str(s: &str) -> Result<Self, Self::Err> {
201        let separator_idx = s.find('@');
202
203        let (name_part, version_part_opt) = match separator_idx {
204            Some(idx) => (&s[..idx], Some(&s[idx + 1..])),
205            None => (s, None),
206        };
207
208        if name_part.is_empty() {
209            return Err("Quill name cannot be empty".to_string());
210        }
211
212        let name = name_part.to_string();
213
214        if !name
215            .chars()
216            .next()
217            .is_some_and(|c| c.is_ascii_lowercase() || c == '_')
218        {
219            return Err(format!(
220                "Invalid Quill name '{}': must start with lowercase letter or underscore",
221                name
222            ));
223        }
224        if !name
225            .chars()
226            .all(|c| c.is_ascii_lowercase() || c.is_ascii_digit() || c == '_')
227        {
228            return Err(format!(
229                "Invalid Quill name '{}': must contain only lowercase letters, digits, and underscores",
230                name
231            ));
232        }
233
234        let selector = if let Some(version_part) = version_part_opt {
235            VersionSelector::from_str(&format!("@{}", version_part))?
236        } else {
237            VersionSelector::Latest
238        };
239
240        Ok(QuillReference { name, selector })
241    }
242}
243
244impl fmt::Display for QuillReference {
245    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
246        match &self.selector {
247            VersionSelector::Latest => write!(f, "{}", self.name),
248            _ => write!(f, "{}{}", self.name, self.selector),
249        }
250    }
251}
252
253#[cfg(test)]
254mod tests {
255    use super::*;
256
257    #[test]
258    fn test_version_parsing() {
259        let v = Version::from_str("2.1.0").unwrap();
260        assert_eq!(v.major, 2);
261        assert_eq!(v.minor, 1);
262        assert_eq!(v.patch, 0);
263        assert_eq!(v.to_string(), "2.1.0");
264
265        let v2 = Version::from_str("1.2.3").unwrap();
266        assert_eq!(v2.major, 1);
267        assert_eq!(v2.minor, 2);
268        assert_eq!(v2.patch, 3);
269        assert_eq!(v2.to_string(), "1.2.3");
270    }
271
272    #[test]
273    fn test_version_parsing_two_segment_backward_compat() {
274        let v = Version::from_str("2.1").unwrap();
275        assert_eq!(v.major, 2);
276        assert_eq!(v.minor, 1);
277        assert_eq!(v.patch, 0);
278        assert_eq!(v.to_string(), "2.1.0");
279    }
280
281    #[test]
282    fn test_version_invalid() {
283        assert!(Version::from_str("2").is_err());
284        assert!(Version::from_str("2.1.0.0").is_err());
285        assert!(Version::from_str("abc").is_err());
286        assert!(Version::from_str("2.x").is_err());
287        assert!(Version::from_str("2.1.x").is_err());
288    }
289
290    #[test]
291    fn test_version_ordering() {
292        let v1_0_0 = Version::new(1, 0, 0);
293        let v1_0_1 = Version::new(1, 0, 1);
294        let v1_1_0 = Version::new(1, 1, 0);
295        let v2_0_0 = Version::new(2, 0, 0);
296        let v2_1_0 = Version::new(2, 1, 0);
297
298        assert!(v1_0_0 < v1_0_1);
299        assert!(v1_0_1 < v1_1_0);
300        assert!(v1_1_0 < v2_0_0);
301        assert!(v2_0_0 < v2_1_0);
302        assert_eq!(v1_0_0, v1_0_0);
303    }
304
305    #[test]
306    fn test_version_selector_parsing() {
307        let exact = VersionSelector::from_str("@2.1.0").unwrap();
308        assert_eq!(exact, VersionSelector::Exact(Version::new(2, 1, 0)));
309
310        let minor = VersionSelector::from_str("@2.1").unwrap();
311        assert_eq!(minor, VersionSelector::Minor(2, 1));
312
313        let major = VersionSelector::from_str("@2").unwrap();
314        assert_eq!(major, VersionSelector::Major(2));
315
316        let latest1 = VersionSelector::from_str("@latest").unwrap();
317        assert_eq!(latest1, VersionSelector::Latest);
318
319        // Empty string also means Latest
320        let latest2 = VersionSelector::from_str("").unwrap();
321        assert_eq!(latest2, VersionSelector::Latest);
322    }
323
324    #[test]
325    fn test_version_selector_without_at() {
326        let exact = VersionSelector::from_str("2.1.0").unwrap();
327        assert_eq!(exact, VersionSelector::Exact(Version::new(2, 1, 0)));
328
329        let minor = VersionSelector::from_str("2.1").unwrap();
330        assert_eq!(minor, VersionSelector::Minor(2, 1));
331
332        let major = VersionSelector::from_str("2").unwrap();
333        assert_eq!(major, VersionSelector::Major(2));
334    }
335
336    #[test]
337    fn test_version_selector_display() {
338        assert_eq!(
339            VersionSelector::Exact(Version::new(2, 1, 0)).to_string(),
340            "@2.1.0"
341        );
342        assert_eq!(VersionSelector::Minor(2, 1).to_string(), "@2.1");
343        assert_eq!(VersionSelector::Major(2).to_string(), "@2");
344        assert_eq!(VersionSelector::Latest.to_string(), "@latest");
345    }
346
347    #[test]
348    fn test_quill_reference_parsing() {
349        let ref1 = QuillReference::from_str("resume_template@2.1.0").unwrap();
350        assert_eq!(ref1.name, "resume_template");
351        assert_eq!(ref1.selector, VersionSelector::Exact(Version::new(2, 1, 0)));
352
353        let ref1b = QuillReference::from_str("resume_template@2.1").unwrap();
354        assert_eq!(ref1b.selector, VersionSelector::Minor(2, 1));
355
356        let ref2 = QuillReference::from_str("resume_template@2").unwrap();
357        assert_eq!(ref2.selector, VersionSelector::Major(2));
358
359        let ref3 = QuillReference::from_str("resume_template@latest").unwrap();
360        assert_eq!(ref3.selector, VersionSelector::Latest);
361
362        // No @ suffix — defaults to Latest
363        let ref4 = QuillReference::from_str("resume_template").unwrap();
364        assert_eq!(ref4.name, "resume_template");
365        assert_eq!(ref4.selector, VersionSelector::Latest);
366    }
367
368    #[test]
369    fn test_quill_reference_invalid_names() {
370        assert!(QuillReference::from_str("Resume@2.1.0").is_err());
371        assert!(QuillReference::from_str("1resume@2.1.0").is_err());
372        assert!(QuillReference::from_str("resume-template@2.1.0").is_err());
373        assert!(QuillReference::from_str("resume.template@2.1.0").is_err());
374        assert!(QuillReference::from_str("resume_template@2.1.0").is_ok());
375        assert!(QuillReference::from_str("_private@2.1.0").is_ok());
376        assert!(QuillReference::from_str("template2@2.1.0").is_ok());
377    }
378
379    #[test]
380    fn test_quill_reference_display() {
381        let ref1 = QuillReference::new(
382            "resume".to_string(),
383            VersionSelector::Exact(Version::new(2, 1, 0)),
384        );
385        assert_eq!(ref1.to_string(), "resume@2.1.0");
386
387        let ref1b = QuillReference::new("resume".to_string(), VersionSelector::Minor(2, 1));
388        assert_eq!(ref1b.to_string(), "resume@2.1");
389
390        let ref2 = QuillReference::new("resume".to_string(), VersionSelector::Major(2));
391        assert_eq!(ref2.to_string(), "resume@2");
392
393        let ref3 = QuillReference::new("resume".to_string(), VersionSelector::Latest);
394        assert_eq!(ref3.to_string(), "resume");
395    }
396
397    #[test]
398    fn test_quill_ref_hint_describes_the_grammar() {
399        let hint = quill_ref_hint();
400        assert!(!hint.is_empty());
401        // Pin the charset and selector forms so the hint can't drift from `from_str`.
402        assert!(hint.contains("[a-z_][a-z0-9_]*"), "got: {hint}");
403        assert!(hint.contains("@latest"), "got: {hint}");
404        assert!(hint.contains("@MAJOR.MINOR.PATCH"), "got: {hint}");
405    }
406}
quillmark_core/version.rs

quillmark_core/
version.rs
