feat: implement parse_version_from_tag (#57)

- implement parse_version_from_tag
- implement vcs_data_to_zerv_vars

Author: wislertt

.dev/03-phase2-implementation-plan.md

@@ -86,6 +86,9 @@ fn populate_vars_by_tier(vars: &mut ZervVars, tier: VersionTier, schema: &ZervFo
 ```rust
 #[derive(Parser)]
 struct VersionArgs {
+    /// Version string (only used with --source string)
+    version: Option<String>,
+
     #[arg(long, default_value = "git")]
     source: String,
 
@@ -291,14 +294,33 @@ tests/integration/
 
 ## Implementation Order
 
-### Step 1: VCS Integration (2-3 days)
+### Step 1: VCS Integration ✅ COMPLETE (3 days)
+
+**Key Achievements:**
+
+- **Type-safe pipeline functions**: `parse_version_from_tag` and `vcs_data_to_zerv_vars` with clean separation of concerns
+- **Auto-detection logic**: SemVer-first parsing with PEP440 fallback for maximum compatibility
+- **Real VCS data testing**: Docker-based fixtures with `OnceLock` session-like caching for edge case discovery
+- **Reusable test infrastructure**: VCS fixtures moved to `test_utils` for cross-module usage
+- **Comprehensive test coverage**: 38 parameterized test cases covering edge cases and unnormalized forms
+- **Production ready**: All linting issues resolved, 1131 tests passing, 97.38% coverage maintained
 
-1. Create `src/pipeline/vcs_integration.rs`
-2. Implement `vcs_data_to_zerv_vars`
-3. Add tag parsing logic
-4. Unit tests for conversion
+**Files Created/Modified:**
 
-### Step 2: Schema System (1-2 days)
+- `src/pipeline/mod.rs` - Module orchestration with re-exports
+- `src/pipeline/parse_version_from_tag.rs` - Version parsing with auto-detection
+- `src/pipeline/vcs_data_to_zerv_vars.rs` - VCS to ZervVars conversion
+- `src/test_utils/vcs_fixtures.rs` - Reusable real VCS data fixtures
+- `src/version/version_object.rs` - Enhanced with unified format handling
+
+1. ✅ Create `src/pipeline/` module with focused functions
+2. ✅ Implement `parse_version_from_tag` - extracts base version from tag string with auto-detection (SemVer first, then PEP440)
+3. ✅ Implement `vcs_data_to_zerv_vars` - converts VcsData to ZervVars using elegant `VersionObject::into()` pattern
+4. ✅ Comprehensive unit tests with real VCS data fixtures using `OnceLock` session-like caching
+5. ✅ Moved VCS fixtures to `test_utils` for reusability across codebase
+6. ✅ All 1131 tests pass with 97.38% coverage maintained
+
+### Step 2: Schema System (1-2 days) 🔄 NEXT
 
 1. Create `src/schema/` module
 2. Implement RON parsing
@@ -335,15 +357,17 @@ pub fn run_version_pipeline(args: VersionArgs) -> Result<String> {
     let vcs = detect_vcs(&std::env::current_dir()?)?;
     let vcs_data = vcs.get_vcs_data()?;
 
-    // 2. Convert to ZervVars
-    let base_version = parse_version_from_tag(&vcs_data.tag_version);
-    let mut vars = vcs_data_to_zerv_vars(vcs_data, base_version);
+    // 2. Resolve version source (VCS tag or CLI string)
+    let vcs_data = resolve_version_source(vcs_data, args.version)?;
+
+    // 3. Convert to ZervVars
+    let vars = vcs_data_to_zerv_vars(vcs_data)?;
 
-    // 3. Apply schema
+    // 4. Apply schema
     let schema = get_schema(&args.schema, &args.schema_ron)?;
     let zerv = Zerv::new(schema, vars);
 
-    // 4. Output format
+    // 5. Output format
     match args.output_format.as_deref() {
         Some("pep440") => Ok(PEP440::from_zerv(&zerv)?.to_string()),
         Some("semver") => Ok(SemVer::from_zerv(&zerv)?.to_string()),
@@ -442,10 +466,25 @@ $ zerv check "1.2.3" --format pep440
 ## Timeline Estimate
 
 - **Total**: 5-7 days focused development
-- **Milestone 1**: VCS integration working (Day 3)
+- **Milestone 1**: VCS integration working ✅ COMPLETE (Day 3)
 - **Milestone 2**: Basic CLI pipeline + check command (Day 5)
 - **Milestone 3**: Full Phase 2 complete (Day 7)
 
+## Progress Summary
+
+**✅ COMPLETED (Day 3):**
+
+- Step 1: VCS Integration with comprehensive testing and real data fixtures
+- Enhanced type safety with `VersionObject` enum and unified format handling
+- Production-ready code with full lint compliance and test coverage
+
+**🔄 NEXT STEPS:**
+
+- Step 2: Schema System (RON parsing, presets)
+- Step 3: CLI Pipeline (version command implementation)
+- Step 4: Check Command (validation with auto-detection)
+- Step 5: Integration Tests (end-to-end validation)
+
 **Note**: `zerv check` adds minimal complexity since we already have complete PEP440/SemVer parsers.
 
 This plan leverages the solid Phase 1 foundation to rapidly implement the core pipeline functionality needed for a functional alpha release.

src/lib.rs

@@ -1,5 +1,6 @@
 pub mod cli;
 pub mod error;
+pub mod pipeline;
 #[cfg(any(test, feature = "test-utils"))]
 pub mod test_utils;
 pub mod vcs;

src/pipeline/mod.rs

@@ -0,0 +1,5 @@
+pub mod parse_version_from_tag;
+pub mod vcs_data_to_zerv_vars;
+
+pub use parse_version_from_tag::parse_version_from_tag;
+pub use vcs_data_to_zerv_vars::vcs_data_to_zerv_vars;

src/pipeline/parse_version_from_tag.rs

@@ -0,0 +1,149 @@
+use crate::version::{PEP440, SemVer, VersionObject};
+use std::str::FromStr;
+
+/// Parse version from tag string with optional format specification
+pub fn parse_version_from_tag(tag: &str, input_format: Option<&str>) -> Option<VersionObject> {
+    match input_format {
+        Some(format) => VersionObject::parse_with_format(tag, format),
+        None => {
+            // Auto-detection: try SemVer first, then PEP440
+            if let Ok(semver) = SemVer::from_str(tag) {
+                return Some(VersionObject::SemVer(semver));
+            }
+
+            if let Ok(pep440) = PEP440::from_str(tag) {
+                return Some(VersionObject::PEP440(pep440));
+            }
+
+            None
+        }
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use rstest::rstest;
+
+    #[rstest]
+    // Basic SemVer cases (auto-detection should pick SemVer first)
+    #[case("1.2.3", "1.2.3", "semver")]
+    #[case("v1.2.3", "1.2.3", "semver")]
+    #[case("0.0.0", "0.0.0", "semver")]
+    #[case("10.20.30", "10.20.30", "semver")]
+    // SemVer with pre-release
+    #[case("1.0.0-alpha", "1.0.0-alpha", "semver")]
+    #[case("1.0.0-alpha.1", "1.0.0-alpha.1", "semver")]
+    #[case("1.0.0-beta.2", "1.0.0-beta.2", "semver")]
+    #[case("1.0.0-rc.1", "1.0.0-rc.1", "semver")]
+    // SemVer with build metadata
+    #[case("1.0.0+build.1", "1.0.0+build.1", "semver")]
+    #[case("1.0.0-alpha.1+build.123", "1.0.0-alpha.1+build.123", "semver")]
+    // PEP440-specific cases (should fall back to PEP440)
+    #[case("1.2.3a1", "1.2.3a1", "pep440")]
+    #[case("1.2.3b2", "1.2.3b2", "pep440")]
+    #[case("1.2.3rc3", "1.2.3rc3", "pep440")]
+    #[case("1.2.3.post1", "1.2.3.post1", "pep440")]
+    #[case("1.2.3.dev1", "1.2.3.dev1", "pep440")]
+    #[case("2!1.2.3", "2!1.2.3", "pep440")]
+    // PEP440 unnormalized forms
+    #[case("1.2.3_alpha1", "1.2.3a1", "pep440")]
+    #[case("1.2.3.ALPHA.1", "1.2.3a1", "pep440")]
+    #[case("1.2.3.POST.1", "1.2.3.post1", "pep440")]
+    // Complex PEP440 cases
+    #[case(
+        "2!1.2.3a1.post1.dev1+local.1",
+        "2!1.2.3a1.post1.dev1+local.1",
+        "pep440"
+    )]
+    fn test_parse_version_from_tag_auto_detection(
+        #[case] tag: &str,
+        #[case] expected_str: &str,
+        #[case] expected_format: &str,
+    ) {
+        let version = parse_version_from_tag(tag, None).unwrap();
+
+        // Direct comparison - no conversion needed!
+        assert_eq!(version.format_str(), expected_format);
+
+        match expected_format {
+            "semver" => {
+                if let VersionObject::SemVer(semver) = version {
+                    let expected: SemVer = expected_str.parse().unwrap();
+                    assert_eq!(semver, expected);
+                } else {
+                    panic!("Expected SemVer, got {version:?}");
+                }
+            }
+            "pep440" => {
+                if let VersionObject::PEP440(pep440) = version {
+                    let expected: PEP440 = expected_str.parse().unwrap();
+                    assert_eq!(pep440, expected);
+                } else {
+                    panic!("Expected PEP440, got {version:?}");
+                }
+            }
+            _ => panic!("Unknown expected format: {expected_format}"),
+        }
+    }
+
+    #[rstest]
+    #[case("1.2.3", "1.2.3")]
+    #[case("v1.2.3", "1.2.3")]
+    #[case("1.2.3a1", "1.2.3a1")]
+    #[case("2!1.2.3.post1.dev1", "2!1.2.3.post1.dev1")]
+    #[case("1.2.3_alpha1", "1.2.3a1")] // unnormalized
+    fn test_parse_version_from_tag_explicit_pep440(#[case] tag: &str, #[case] expected_str: &str) {
+        let version = parse_version_from_tag(tag, Some("pep440")).unwrap();
+
+        if let VersionObject::PEP440(pep440) = version {
+            let expected: PEP440 = expected_str.parse().unwrap();
+            assert_eq!(pep440, expected);
+        } else {
+            panic!("Expected PEP440, got {version:?}");
+        }
+    }
+
+    #[rstest]
+    #[case("1.2.3", "1.2.3")]
+    #[case("v1.2.3", "1.2.3")]
+    #[case("1.0.0-alpha.1", "1.0.0-alpha.1")]
+    #[case("1.0.0+build.123", "1.0.0+build.123")]
+    #[case("1.0.0-alpha.1+build.123", "1.0.0-alpha.1+build.123")]
+    fn test_parse_version_from_tag_explicit_semver(#[case] tag: &str, #[case] expected_str: &str) {
+        let version = parse_version_from_tag(tag, Some("semver")).unwrap();
+
+        if let VersionObject::SemVer(semver) = version {
+            let expected: SemVer = expected_str.parse().unwrap();
+            assert_eq!(semver, expected);
+        } else {
+            panic!("Expected SemVer, got {version:?}");
+        }
+    }
+
+    #[rstest]
+    #[case("invalid")]
+    #[case("")]
+    #[case("abc.def.ghi")]
+    fn test_parse_version_from_tag_invalid(#[case] tag: &str) {
+        let version = parse_version_from_tag(tag, None);
+        assert!(version.is_none());
+    }
+
+    #[rstest]
+    #[case("1.2.3", "unknown")]
+    #[case("1.2.3", "invalid")]
+    #[case("1.2.3", "custom")]
+    fn test_parse_version_from_tag_unknown_format(#[case] tag: &str, #[case] format: &str) {
+        let version = parse_version_from_tag(tag, Some(format));
+        assert!(version.is_none());
+    }
+
+    #[rstest]
+    #[case("1.2.3a1", "semver")] // PEP440 format with SemVer parser
+    #[case("1.2.3.post1", "semver")] // PEP440 post-release with SemVer parser
+    fn test_parse_version_from_tag_wrong_format(#[case] tag: &str, #[case] format: &str) {
+        let version = parse_version_from_tag(tag, Some(format));
+        assert!(version.is_none());
+    }
+}

src/pipeline/vcs_data_to_zerv_vars.rs

@@ -0,0 +1,73 @@
+use super::parse_version_from_tag::parse_version_from_tag;
+use crate::error::ZervError;
+use crate::vcs::VcsData;
+use crate::version::ZervVars;
+
+/// Convert VCS data to ZervVars
+pub fn vcs_data_to_zerv_vars(vcs_data: VcsData) -> Result<ZervVars, ZervError> {
+    // Parse version from tag_version
+    let version = if let Some(ref tag_version) = vcs_data.tag_version {
+        parse_version_from_tag(tag_version, None).ok_or_else(|| {
+            ZervError::Io(std::io::Error::other("Failed to parse version from tag"))
+        })?
+    } else {
+        return Err(ZervError::Io(std::io::Error::other("No version tag found")));
+    };
+
+    let mut vars: ZervVars = version.into();
+
+    // VCS-specific fields
+    vars.distance = Some(vcs_data.distance as u64);
+    vars.current_branch = vcs_data.current_branch;
+    vars.dirty = Some(vcs_data.is_dirty);
+    vars.current_commit_hash = Some(vcs_data.commit_hash_short);
+    vars.tag_timestamp = vcs_data.tag_timestamp.map(|t| t as u64);
+
+    Ok(vars)
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use crate::test_utils::{get_real_pep440_vcs_data, get_real_semver_vcs_data};
+
+    #[test]
+    #[ignore = "docker"]
+    fn test_vcs_data_to_zerv_vars_real_semver() {
+        let vcs_data = get_real_semver_vcs_data().clone();
+        let vars = vcs_data_to_zerv_vars(vcs_data).unwrap();
+
+        assert_eq!(
+            (vars.major, vars.minor, vars.patch),
+            (Some(1), Some(2), Some(3))
+        );
+        assert_eq!(vars.distance, Some(1)); // 1 commit after tag
+        assert!(vars.current_commit_hash.is_some());
+        assert!(vars.tag_timestamp.is_some());
+    }
+
+    #[test]
+    #[ignore = "docker"]
+    fn test_vcs_data_to_zerv_vars_real_pep440() {
+        let vcs_data = get_real_pep440_vcs_data().clone();
+        let vars = vcs_data_to_zerv_vars(vcs_data).unwrap();
+
+        assert_eq!(
+            (vars.major, vars.minor, vars.patch),
+            (Some(2), Some(0), Some(1))
+        );
+        assert_eq!(vars.distance, Some(1)); // 1 commit after tag
+        assert!(vars.current_commit_hash.is_some());
+        assert!(vars.tag_timestamp.is_some());
+    }
+
+    #[test]
+    fn test_vcs_data_to_zerv_vars_no_tag() {
+        let vcs_data = VcsData {
+            tag_version: None,
+            ..Default::default()
+        };
+        let result = vcs_data_to_zerv_vars(vcs_data);
+        assert!(result.is_err());
+    }
+}

src/test_utils/mod.rs

@@ -1,5 +1,7 @@
 pub mod dir;
 pub mod git;
+pub mod vcs_fixtures;
 
 pub use dir::TestDir;
 pub use git::DockerGit;
+pub use vcs_fixtures::{get_real_pep440_vcs_data, get_real_semver_vcs_data};

src/test_utils/vcs_fixtures.rs

@@ -0,0 +1,41 @@
+use super::{DockerGit, TestDir};
+use crate::vcs::{Vcs, VcsData, git::GitVcs};
+use std::sync::OnceLock;
+
+static SEMVER_VCS_DATA: OnceLock<VcsData> = OnceLock::new();
+static PEP440_VCS_DATA: OnceLock<VcsData> = OnceLock::new();
+
+fn create_vcs_data_with_tag(tag: &str, filename: &str, content: &str, commit_msg: &str) -> VcsData {
+    let test_dir = TestDir::new().expect("Failed to create test dir");
+    let docker_git = DockerGit::new();
+
+    docker_git
+        .init_repo(&test_dir)
+        .expect("Failed to init repo");
+    docker_git
+        .create_tag(&test_dir, tag)
+        .expect("Failed to create tag");
+
+    test_dir
+        .create_file(filename, content)
+        .expect("Failed to create file");
+    docker_git
+        .create_commit(&test_dir, commit_msg)
+        .expect("Failed to create commit");
+
+    let git_vcs = GitVcs::new(test_dir.path()).expect("Failed to create GitVcs");
+    git_vcs.get_vcs_data().expect("Failed to get VCS data")
+}
+
+/// Get real VCS data with SemVer tag (v1.2.3) and 1 commit distance
+pub fn get_real_semver_vcs_data() -> &'static VcsData {
+    SEMVER_VCS_DATA.get_or_init(|| {
+        create_vcs_data_with_tag("v1.2.3", "feature.txt", "new feature", "Add feature")
+    })
+}
+
+/// Get real VCS data with PEP440 tag (2.0.1a1) and 1 commit distance
+pub fn get_real_pep440_vcs_data() -> &'static VcsData {
+    PEP440_VCS_DATA
+        .get_or_init(|| create_vcs_data_with_tag("2.0.1a1", "fix.txt", "bug fix", "Fix bug"))
+}