fix: fix annotated tags in git detection bug (#149)

Author: wislertt

.claude/plan/01-fix-annotated-tag-bug.md

@@ -0,0 +1,144 @@
+# Plan: Fix Annotated Tag Detection Bug
+
+**Status**: In Progress (Phase 1 & 2 Complete, Phase 3 In Progress)
+**Priority**: High
+**Context**: zerv flow and zerv version commands do not properly detect annotated tags, causing version detection to fail when repositories use annotated tags instead of lightweight tags.
+
+## Goals
+
+1. Add comprehensive support for annotated tags in test utilities
+2. Create test cases that replicate the annotated tag bug
+3. Fix any issues in tag detection logic for annotated tags
+4. Ensure both annotated and lightweight tags work correctly
+
+## Implementation Plan
+
+### Phase 1: Enhance Test Infrastructure
+
+1. **Add annotated tag support to GitOperations trait**
+    - Extend the `GitOperations` trait with a new method: `create_annotated_tag(&self, test_dir: &TestDir, tag: &str, message: &str) -> io::Result<()>`
+    - Implement for both `NativeGit` and `DockerGit`
+    - Use `git tag -a <tag> -m "<message>"` command
+
+2. **Add annotated tag support to GitRepoFixture**
+    - Add `create_annotated_tag(self, tag: &str, message: &str) -> Self` method
+    - Add `with_annotated_tag(self, tag: &str, message: &str) -> Self` builder-style method
+    - Add static constructor: `GitRepoFixture::tagged_annotated(tag: &str, message: &str) -> Result<Self>`
+
+### Phase 2: Create Comprehensive Test Cases
+
+1. **Create annotated tag test mirroring existing lightweight tag test**
+    - Duplicate `test_get_latest_tag_comprehensive` as `test_get_latest_tag_comprehensive_annotated`
+    - Use annotated tags instead of lightweight tags
+    - Test all scenarios: single tag, multiple tags, mixed formats, commit distances
+
+2. **Test mixed tag type scenarios**
+    - Repository with both annotated and lightweight tags on same commit
+    - Repository with annotated tags on different commits
+    - Timestamp behavior differences between tag types
+
+3. **Test edge cases**
+    - Annotated tag with special characters in message
+    - Multiple annotated tags with different timestamps
+    - Annotated tags with GPG signatures (if applicable)
+
+### Phase 3: Investigate and Fix Bug
+
+1. **Debug current tag detection with annotated tags**
+    - Run existing git commands against repositories with annotated tags
+    - Identify which commands fail or return unexpected results
+    - Check if `git tag --merged` handles annotated tags correctly
+    - Verify timestamp extraction works for both tag types
+
+2. **Fix tag detection logic if needed**
+    - Update `get_merged_tags()` if it doesn't include annotated tags
+    - Fix timestamp handling in `get_tag_timestamp()` if there are issues
+    - Ensure `get_tag_commit_hash()` works correctly for annotated tags
+
+3. **Update git command execution**
+    - Check if any git commands need different flags for annotated tags
+    - Verify error handling covers annotated tag-specific failures
+
+### Phase 4: Integration Testing
+
+1. **Test with zerv flow command**
+    - Create integration test using `TestCommand` with annotated tag repository
+    - Verify version output is correct
+    - Test all format options (auto, semver, pep440)
+
+2. **Test with zerv version command**
+    - Similar integration test for standalone version command
+    - Verify consistency between flow and version commands
+
+3. **Test real-world scenarios**
+    - Import a real git repository with annotated tags
+    - Test version detection on complex histories
+
+## Testing Strategy
+
+### Unit Tests
+
+- Test new annotated tag creation methods in test utilities
+- Test tag type detection (`git cat-file -t`)
+- Test timestamp extraction for both tag types
+- Test version parsing with annotated tags
+
+### Integration Tests
+
+- Use `ZERV_TEST_NATIVE_GIT=false ZERV_TEST_DOCKER=true` for Docker-based tests
+- Create comprehensive test scenarios covering all tag combinations
+- Test with multiple version formats
+
+### Manual Verification
+
+- Create test repositories manually with annotated tags
+- Verify zerv commands work correctly
+- Compare behavior with lightweight tags
+
+## Success Criteria
+
+1. ✅ All tests pass with annotated tags
+2. ✅ zerv flow detects annotated tags correctly
+3. ✅ zerv version detects annotated tags correctly
+4. ✅ Mixed repositories (both tag types) work correctly
+5. ✅ No regression in lightweight tag functionality
+6. ✅ Test coverage includes annotated tag scenarios
+
+## Documentation Updates
+
+1. Update testing documentation to mention annotated tag support
+2. Add examples of creating annotated tags in tests
+3. Document any differences in behavior between tag types
+
+## Files to Modify
+
+### New Files
+
+- None
+
+### Modified Files
+
+- `src/test_utils/git/mod.rs` - Add annotated tag method to trait
+- `src/test_utils/git/native.rs` - Implement annotated tag creation
+- `src/test_utils/git/docker.rs` - Implement annotated tag creation with verification
+- `src/test_utils/git/fixtures.rs` - Add annotated tag fixture methods
+- `src/vcs/git.rs` - Add comprehensive annotated tag tests
+- `tests/integration_tests/` - Add integration tests for annotated tags
+
+## Risk Assessment
+
+**Low Risk**:
+
+- Adding new methods to test utilities doesn't affect existing code
+- Tests are additive and don't change existing behavior
+
+**Medium Risk**:
+
+- Bug fixes to tag detection logic might affect lightweight tag behavior
+- Need thorough regression testing
+
+**Mitigation**:
+
+- Run full test suite after each change
+- Keep lightweight tag tests intact
+- Test with real repositories before merging

.claude/plan/02-rewrite-get-latest-tag-for-annotated-tags.md

@@ -0,0 +1,177 @@
+# Plan: Rewrite get_latest_tag to Properly Detect Annotated Tags
+
+**Status**: Planned
+**Priority**: High
+**Context**: The current `get_latest_tag` implementation in src/vcs/git.rs cannot properly detect annotated tags because it uses `git tag --merged HEAD` which doesn't correctly handle the topological order of commits and their associated tags. The TODO comment in the code outlines the correct approach.
+
+## Goals
+
+1. Rewrite `get_latest_tag` method to use topological commit traversal
+2. Ensure both annotated and lightweight tags are detected correctly
+3. Make `test_get_latest_tag_comprehensive_annotated` test pass
+4. Maintain backward compatibility with existing functionality
+
+## Implementation Plan
+
+### Step 1: Understand the Current Algorithm's Limitations
+
+The current algorithm:
+
+1. Gets all merged tags using `git tag --merged HEAD --sort=-committerdate`
+2. Finds the latest valid version tag from this list
+3. Gets the commit hash for that tag
+4. Gets all tags pointing to that commit
+5. Filters and finds the maximum version tag
+
+**Problems:**
+
+- `git tag --merged` doesn't guarantee topological order
+- May miss tags on commits that are not direct ancestors
+- Doesn't properly handle multiple tags on the same commit
+
+### Step 2: Implement the New Algorithm
+
+Following the TODO comment's guidance, the new algorithm will:
+
+1. **Get all commits from HEAD in topological order**
+
+    ```bash
+    git rev-list --topo-order HEAD
+    ```
+
+    This returns commits in topological order (parents before children)
+
+2. **Iterate through each commit and find tags pointing at it**
+
+    ```bash
+    git tag --points-at <commit-hash>
+    ```
+
+3. **Filter and validate tags for each commit**
+    - Use `GitUtils::filter_only_valid_tags(&tags, format)`
+    - If no valid tags found, continue to next commit
+
+4. **Find the maximum version tag among valid tags**
+    - Use `GitUtils::find_max_version_tag(&valid_tags)`
+    - Return the first found (since we're in topological order)
+
+### Step 3: Code Implementation
+
+First, add a helper method to get commits in topological order:
+
+```rust
+/// Get all commits from HEAD in topological order
+fn get_commits_in_topo_order(&self) -> Result<Vec<String>> {
+    let commits_output = self.run_git_command(&["rev-list", "--topo-order", "HEAD"])?;
+    Ok(commits_output
+        .lines()
+        .map(|line| line.trim().to_string())
+        .filter(|hash| !hash.is_empty())
+        .collect())
+}
+```
+
+Then, the new `get_latest_tag` method will reuse the existing `get_all_tags_from_commit_hash`:
+
+```rust
+fn get_latest_tag(&self, format: &str) -> Result<Option<String>> {
+    // Get all commits from HEAD in topological order
+    let commits = self.get_commits_in_topo_order()?;
+
+    // Process each commit in topological order
+    for commit_hash in commits {
+        // Get all tags pointing to this commit (reusing existing function)
+        let tags = self.get_all_tags_from_commit_hash(&commit_hash)?;
+
+        // If no tags, continue to next commit
+        if tags.is_empty() {
+            continue;
+        }
+
+        // Filter tags by format
+        let valid_tags = GitUtils::filter_only_valid_tags(&tags, format);
+
+        // If no valid tags, continue to next commit
+        if valid_tags.is_empty() {
+            continue;
+        }
+
+        // Find and return the maximum version tag
+        if let Some(max_tag) = GitUtils::find_max_version_tag(&valid_tags)? {
+            return Ok(Some(max_tag));
+        }
+    }
+
+    // No valid tags found
+    Ok(None)
+}
+```
+
+Note: No changes needed to `get_tags_pointing_at_commit` or `get_all_tags_from_commit_hash` - we'll reuse the existing `get_all_tags_from_commit_hash` function.
+
+### Step 4: Testing Strategy
+
+1. **Enable the commented-out test cases**
+    - Uncomment all test scenarios in `test_get_latest_tag_comprehensive_annotated`
+    - Ensure the test uses proper annotated tag creation
+
+2. **Run the test to verify the fix**
+
+    ```bash
+    ZERV_TEST_NATIVE_GIT=false ZERV_TEST_DOCKER=true cargo test test_get_latest_tag_comprehensive_annotated
+    ```
+
+3. **Run existing tests to ensure no regression**
+    ```bash
+    ZERV_TEST_NATIVE_GIT=false ZERV_TEST_DOCKER=true cargo test
+    ```
+
+### Step 5: Additional Considerations
+
+1. **Performance**: The new algorithm may be slower as it checks each commit
+    - Consider adding early termination if we find a tag on HEAD
+    - Cache results if needed
+
+2. **Edge cases to handle**:
+    - Empty repositories (no commits)
+    - Repositories with no tags
+    - Mixed annotated and lightweight tags
+    - Tags with GPG signatures
+
+3. **Error handling**:
+    - Handle empty output from `git rev-list`
+    - Ensure proper error propagation
+
+## Success Criteria
+
+1. ✅ `test_get_latest_tag_comprehensive_annotated` test passes
+2. ✅ All existing tag-related tests still pass
+3. ✅ Both annotated and lightweight tags work correctly
+4. ✅ No performance regression for typical repositories
+5. ✅ Proper error handling for edge cases
+
+## Files to Modify
+
+### Modified Files
+
+- `src/vcs/git.rs` - Add the `get_commits_in_topo_order` helper method and rewrite the `get_latest_tag` method (lines 131-151) to use topological commit traversal
+
+## Risk Assessment
+
+**Medium Risk**:
+
+- Changing a core algorithm that affects version detection
+- Potential performance impact on large repositories
+
+**Mitigation**:
+
+- Thorough testing with various repository types
+- Performance benchmarking on large commit histories
+- Keep the existing algorithm as a fallback if needed
+
+## Notes
+
+- The implementation follows the exact guidance from the TODO comment
+- This approach is more robust as it checks commits in topological order
+- The algorithm will work correctly for both annotated and lightweight tags
+- No changes needed to test utilities as they already support annotated tags

.github/workflows/cd.yml

@@ -37,6 +37,12 @@ jobs:
                   "${{ fromJson(needs.zerv-versioning.outputs.versions).v_semver_major }}",
                   "${{ fromJson(needs.zerv-versioning.outputs.versions).v_semver_major_minor }}"
                 ]
+            # TODO: update this after release
+            # tags: >-
+            #     [
+            #       "${{ fromJson(needs.zerv-versioning.outputs.versions).v_major }}",
+            #       "${{ fromJson(needs.zerv-versioning.outputs.versions).v_major_minor }}"
+            #     ]
 
     # ====================================================
     # Test and Lint

.github/workflows/shared-zerv-versioning.yml

@@ -60,6 +60,13 @@ on:
                         "v_semver_major": "v{{ major }}",
                         "v_semver_major_minor": "v{{ major }}.{{ minor }}"
                     }
+                # TODO: update this after release
+                # default: >-
+                #     {
+                #         "docker_tag": "{{ semver_obj.docker }}",
+                #         "v_major": "v{{ major | default(value="0") }}",
+                #         "v_major_minor": "v{{ major | default(value="0") }}{{ prefix_if(value=minor, prefix=".") }}"
+                #     }
             custom_outputs:
                 type: string
                 required: false