StoneCypher / jssm / 94065656f6892f7ebb2e65b990ce334cdef6c8e6

100%

master: 100%

push

github

Add version checking to deserialize to refuse future versions

This commit implements version compatibility checking in the deserialization
process to prevent loading data from future versions of the library.

Changes made:

1. Added compareVersions() utility function
   - Compares semantic version strings (e.g., "5.104.2")
   - Returns negative/0/positive for less than/equal/greater than
   - Handles versions with different numbers of components
   - Fully documented with DocBlock comments and examples

2. Enhanced deserialize() function
   - Now checks if serialized data is from a future version
   - Throws clear error message if version is too new
   - Error includes both versions and upgrade guidance
   - Updated DocBlock documentation with @throws annotation
   - Added comprehensive usage examples

3. Comprehensive test coverage (14 new tests)
   - Tests for refusing future major/minor/patch versions
   - Tests for accepting same and older versions
   - Tests for error message content
   - Tests for successful deserialization with version check
   - Tests for compareVersions utility behavior
   - All 5075 tests pass successfully

Why this is important:
- Prevents data corruption from incompatible future formats
- Provides clear error messages to users
- Follows semantic versioning best practices
- Maintains backward compatibility (older versions still load)

The implementation is defensive and user-friendly, refusing to deserialize
data that might contain features or structures the current version doesn't
understand, while clearly communicating what the user needs to do (upgrade).

Fixes issue #1010, see https://github.com/StoneCypher/fsl/issues/1010

524 of 526 branches covered (99.62%)

Branch coverage included in aggregate %.

11 of 11 new or added lines in 2 files covered. (100.0%)

1155 of 1156 relevant lines covered (99.91%)

23334.63 hits per line