test(bitmanipulation): strengthen Xs3Conversion tests with mutation r… - #50

• Document protected bit-manipulation invariants and alignment conditions in Xs3Conversion Javadoc
• Add mutation-resistant regression tests specifically protecting 4-bit nibble alignment (shift * 4, line 66) and decimal base-10 accumulation (multiplier *= 10, line 42)
• Cover smallest valid input fixtures (zero binary/xs3, positive single-digit 1 <-> 0x4), ordinary fixtures (1234 <-> 0x4567, 25 <-> 0x58), and bijective round-trip across [0, 999]
• Add automated verification check runner work/R45-T010/check.py verifying clean build and rejection of deliberate mutants

• I have read CONTRIBUTING.md.
• This pull request is all my own work -- I have not plagiarized it.
• All filenames are in PascalCase.
• All functions and variable names follow Java naming conventions.
• All new algorithms have a URL in their comments that points to Wikipedia or other similar explanations.
• All new algorithms include a corresponding test class that validates their functionality.
• All new code is formatted with clang-format -i --style=file path/to/your/file.java

Description

This pull request resolves task R45-T010 / Issue #10 by strengthening the test suite of Xs3Conversion.java against subtle semantic regressions and plausible one-line mistakes. It documents protected algorithmic invariants (nibble alignment and decimal base-10 weighting), adds dedicated mutation-resistant tests, validates smallest valid and ordinary fixtures, verifies bijective property round-trips, and implements an automated check runner in work/R45-T010/check.py that demonstrates the test suite reliably catches and rejects plausible one-line mutants.

Related Issue

Closes #10
Related to: #10

Type of Change

• Tests (adds mutation-resistant regression tests, fixture tests, and property checks)
• Documentation update (documents protected invariants and alignment conditions in Javadoc)
• Bug fix (non-breaking change which fixes an issue)
• New feature (non-breaking change which adds functionality)
• Breaking change (fix or feature that would cause existing functionality to not work as expected)

Changes Made

1. Javadoc Documentation (Xs3Conversion.java):

   • Documented protected invariants on xs3ToBinary: each 4-bit nibble represents an Excess-3 digit decoded by subtracting 3, and place value reconstruction relies on decimal base-10 multiplier accumulation (multiplier *= 10, line 42).
   • Documented protected invariants on binaryToXs3: decimal digits are biased by +3, and nibble positioning requires 4-bit alignment scaling (shift * 4, line 66) to prevent bit overlap and corruption across multi-digit numbers.

2. Unit & Mutation-Resistant Regression Tests (Xs3ConversionTest.java):

   • testSmallestValidInputZeroFixture: Verifies boundary handling for zero input (xs3ToBinary(0) == 0, binaryToXs3(0) == 0x0).
   • testSmallestValidPositiveSingleDigitFixture: Verifies smallest positive digit (binary = 1 -> 0x4, xs3 = 0x4 -> 1).
   • testOrdinaryInputDocumentationFixture: Verifies documentation fixture (1234 <-> 0x4567).
   • testOrdinaryInputTwoDigitFixture: Verifies multi-digit fixture (25 <-> 0x58).
   • testMutationResistanceNibbleShiftAlignment: Directly guards against mutant altering shift * 4 to shift (line 66). On input 25, the mutant returns 10 (0xA) instead of expected 88 (0x58).
   • testMutationResistanceMultiplierAccumulation: Directly guards against mutant altering multiplier *= 10 to multiplier *= 16 (line 42). On input 0x58, the mutant returns 37 instead of expected 25.
   • testBijectiveRoundTripAllDigitsAndMultiDigits: Property check asserting xs3ToBinary(binaryToXs3(i)) == i across all integers $i \in [0, 999]$.
   • testPrivateConstructorContract: Reflection contract test verifying private constructor encapsulation.

3. Automated Verification Harness (work/R45-T010/):

   • Implemented check.py runner logging environment metadata (Python 3.15, OpenJDK 21, Maven 3.10) and executing mvn test -Dtest=Xs3ConversionTest and mvn checkstyle:check.
   • Executes temporary mutation experiments on Xs3Conversion.java asserting both mutants are rejected by the regression tests, and guarantees the working tree is restored cleanly.
   • Generated results.json and evidence.md confirming 14/14 tests passing on clean code with 0 checkstyle violations.

Screenshots / Recordings

• Native test suite execution output: