Snapshots: Complete advanced diff output and scale behavior

[bcherrington]

Current state and gap

Snapshot diff commands exist and compare two snapshots, with path filtering and table or JSON output. Advanced output contracts, CI semantics, rename limitations, and large-repository behavior remain incomplete.

Acceptance criteria

• Support snapshot IDs and documented latest semantics.
• Define summary, paths-only, and JSON schemas and stable exit codes for detected differences versus operational failure.
• Document backend limitations for rename or move detection and metadata comparison.
• Process large comparisons iteratively where the backend permits and show bounded progress.
• Add focused functional tests and performance coverage.

[github-actions]

🔍 Issue Triage Analysis

Priority Level: Medium-High

• Rationale: This is part of Phase 4 completion work with existing foundation already implemented. The basic diff functionality exists but needs enhancement for production readiness.

Issue Type: Enhancement

• Category: Feature enhancement/completion
• Scope: Extending existing snapshot diff functionality with advanced features

Complexity Estimate: Medium-High

• Technical Complexity: Moderate - building on existing diff_snapshots() implementation
• Implementation Areas: CLI enhancements, output formatting, performance optimization, filtering logic
• Testing Requirements: Comprehensive test coverage for various scenarios and edge cases

Current State Analysis

✅ Already Implemented:

• Basic snapshots diff command with two snapshot ID comparison
• Core diff_snapshots() service method in SnapshotService
• Rich console output with summary statistics and detailed file listings
• Metadata comparison support (--metadata flag)
• Basic error handling and validation

❌ Missing Features (per acceptance criteria):

• Compare by latest tags (currently only supports explicit IDs)
• Path/pattern filtering for diff results
• Multiple output formats (summary, paths-only, JSON)
• CI-suitable exit codes
• Rename/move detection and documentation
• Performance optimizations (streaming/iterative processing)
• Progress reporting for large repositories
• Updated benchmarks

Suggested Labels

• ✅ enhancement (already applied)
• ✅ area:cli (already applied)
• ✅ area:snapshots (already applied)
• Recommend adding: complexity:medium-high, priority:medium-high, phase:4, service-layer

Team/Component:

• Primary: CLI/Snapshots team
• Secondary: Performance optimization team (for large repo handling)
• Files involved: src/TimeLocker/cli.py, src/TimeLocker/services/snapshot_service.py

Dependencies:

• ✅ No blocking dependencies identified
• ✅ Foundation already exists in current codebase
• ⚠️ May benefit from completion of Configuration Service enhancements (issue Config: Complete migration to the centralized configuration boundary #30) for better repo handling

Reproducibility: N/A (Enhancement request)

Acceptance Criteria Assessment: ✅ Well-defined

• Clear, actionable requirements with specific feature expectations
• Performance considerations explicitly mentioned
• Testing and documentation requirements specified

Similar Issues:

• Related to issue Snapshots: Complete scalable path and optional content search #29 (Snapshots: Implement content and path-based search) - both enhance snapshot operations
• Part of broader Phase 4 completion work alongside issues Security: Reconcile the repository credential resolution contract #28-CLI: Decide and implement an optional interactive shell #33

📋 Recommendations

Next Steps:

1. Immediate: Add recommended labels for better categorization
2. Planning: Break down into smaller implementation tasks:
   • Add tag-based comparison support
   • Implement filtering options (path/pattern)
   • Add output format options (JSON, summary, paths-only)
   • Enhance exit codes for CI integration
   • Add performance optimizations
   • Update documentation and tests

Implementation Approach:

• Phase 1: Extend CLI argument parsing and service method signatures
• Phase 2: Implement filtering and output formatting
• Phase 3: Add performance optimizations and progress reporting
• Phase 4: Comprehensive testing and documentation

Effort Estimate: 2-3 development days

• Day 1: CLI enhancements and basic filtering
• Day 2: Output formats and performance optimizations
• Day 3: Testing, documentation, and edge case handling

Potential Assignees:

• Developers familiar with CLI implementation and snapshot services
• Team members working on Phase 4 completion tasks

Risk Assessment: Low

• Building on solid existing foundation
• Well-defined requirements
• No external dependencies
• Clear testing strategy

This issue is ready for implementation and represents a logical next step in completing the snapshot management functionality.

[github-actions]

🔍 Issue Triage Analysis

Priority Level: Medium

• Urgency: Medium - Feature enhancement for existing functionality
• Impact: Medium - Improves user experience and CLI capabilities but not blocking core functionality
• User Value: High - Advanced diff capabilities are valuable for backup management workflows

Issue Type: Enhancement/Feature Request

• Category: CLI Feature Enhancement
• Scope: Snapshot management functionality expansion

Complexity Estimate: Medium

• Implementation Effort: ~3-5 days for a skilled developer
• Testing Requirements: Moderate - needs unit tests, integration tests, and performance benchmarks
• Documentation Impact: Medium - CLI help, user guides, and examples need updates

Current Implementation Status ✅

After analyzing the codebase, I found that basic snapshot diff functionality is already implemented:

• ✅ Core snapshots diff command exists in CLI (src/TimeLocker/cli.py:2585)
• ✅ SnapshotService.diff_snapshots() method implemented (src/TimeLocker/services/snapshot_service.py:389)
• ✅ SnapshotDiffResult data model defined (src/TimeLocker/interfaces/data_models.py:225)
• ✅ Basic output formatting with Rich terminal display
• ✅ Metadata comparison support (--metadata flag)
• ✅ Repository selection (--repository flag)

Missing Features for "Advanced" Diff 🚧

Based on the acceptance criteria, these enhancements are needed:

1. Compare by latest tags - Currently only supports snapshot IDs
2. Path/pattern filtering - No filtering options implemented
3. Multiple output formats - Only Rich terminal output, missing JSON and summary modes
4. CI-suitable exit codes - Basic error handling but no specific exit codes
5. Rename/move detection - Basic restic diff parsing, may need enhancement
6. Performance optimizations - No streaming/iterative processing for large repos
7. Progress reporting - No progress indication for large comparisons

Suggested Labels 🏷️

• ✅ enhancement (already applied)
• ✅ area:cli (already applied)
• ✅ area:snapshots (already applied)
• Recommend adding: priority:medium, complexity:medium, good-first-issue (for specific sub-tasks)

Team/Component Assignment 👥

• Primary: CLI/Snapshot team
• Secondary: Performance team (for optimization requirements)
• Files involved:
  • src/TimeLocker/cli.py (CLI enhancements)
  • src/TimeLocker/services/snapshot_service.py (service layer)
  • src/TimeLocker/interfaces/data_models.py (data models if needed)

Dependencies & Blockers 🔗

• No blocking dependencies identified
• Prerequisite: Issue Security: Reconcile the repository credential resolution contract #28 (Credential Service integration) should be completed first for better security
• Related: Issues Snapshots: Complete scalable path and optional content search #29 (snapshot search) and Config: Complete migration to the centralized configuration boundary #30 (config service) share similar patterns

Reproducibility Assessment ✅

• Clear acceptance criteria: Well-defined requirements
• Testable: Each feature can be independently tested
• Measurable: Performance benchmarks mentioned

Risk Assessment ⚠️

• Low Risk: Building on existing, working functionality
• Performance Concern: Large repository handling needs careful implementation
• Backward Compatibility: Should maintain existing CLI interface

📋 Recommended Next Steps

Immediate Actions

1. Break down into sub-tasks - Create separate issues for each missing feature
2. Update labels - Add priority:medium and complexity:medium
3. Assign to CLI team - Based on area:cli label

Implementation Approach

1. Phase 1: Add tag comparison and basic filtering (1-2 days)
2. Phase 2: Implement output formats (JSON, summary) (1 day)
3. Phase 3: Performance optimizations and progress reporting (2 days)
4. Phase 4: Testing and documentation (1 day)

Additional Information Needed ❓

• Performance targets: What constitutes "acceptable performance" for large repos?
• Output format specifications: Exact JSON schema requirements?
• CI integration examples: Specific exit code requirements?

Similar Issues 🔄

This issue follows the same pattern as:

• Issue Snapshots: Complete scalable path and optional content search #29 (Snapshots: search functionality)
• Issue Config: Complete migration to the centralized configuration boundary #30 (Config: enhanced operations)
• Part of the broader Phase 4 refactoring initiative

---

Recommendation: This is a well-defined enhancement that builds on solid existing functionality. Ready for implementation with medium priority.