feat: add DecimalEqualsAssertion for decimal comparisons with tolerance

[thomhurst]

Fixes #3494

[claude]

Claude finished @thomhurst's task —— View job

---

Code Review Complete ✅

I've thoroughly reviewed the DecimalEqualsAssertion implementation. Here's my comprehensive analysis:

🟢 Positive Aspects

Implementation Quality

• Clean inheritance pattern: The DecimalEqualsAssertion correctly extends ToleranceBasedEqualsAssertion<decimal, decimal>, following the established pattern used by other numeric types (double, float, long)
• Consistent API: Uses the same .Within() tolerance pattern as other numeric assertions, providing a familiar developer experience
• Proper mathematical precision: Uses Math.Abs(actual - expected) for difference calculation, which is appropriate for decimal arithmetic

Test Coverage

• Comprehensive scenarios: Tests cover exact equality, tolerance-based comparison (success/failure), and edge cases
• Appropriate conditional compilation: Uses #if NET for tolerance tests since the feature relies on ToleranceBasedEqualsAssertion which may have framework dependencies
• Good test naming: Clear, descriptive test method names that communicate intent

API Consistency

• Snapshot updates are correct: All 4 framework-specific API verification files were properly updated with the new public surface area
• Extension method generation: The analyzer correctly generates DecimalEqualsAssertionExtensions for fluent API access

🟡 Areas for Improvement

Critical: Missing Dual-Mode Implementation

According to TUnit's MANDATORY RULE #1 from CLAUDE.md: "ALL changes must work identically in both source-generated and reflection modes"

Issue: The implementation only adds the assertion class but doesn't include corresponding reflection-mode support in TUnit.Engine.

Evidence:

• ✅ Source-gen mode: DecimalEqualsAssertion class in TUnit.Assertions
• ❌ Reflection mode: No equivalent handling found in TUnit.Engine

Recommendation: Verify that the reflection engine can properly discover and execute decimal equality assertions, or add explicit support if needed.

Tolerance Validation

The current implementation doesn't validate tolerance values:

// Consider adding validation in DecimalEqualsAssertion.Within()
if (tolerance < 0)
    throw new ArgumentException("Tolerance must be non-negative", nameof(tolerance));

Documentation

• Missing XML documentation for the DecimalEqualsAssertion class
• No usage examples showing the .Within() tolerance feature

🟢 Security & Performance

Security: ✅ No Concerns

• No external dependencies or unsafe operations
• No potential for injection attacks or data exposure
• Mathematical operations are safe and deterministic

Performance: ✅ Optimized

• Efficient implementation using direct decimal arithmetic
• No unnecessary allocations in hot paths
• Leverages the proven ToleranceBasedEqualsAssertion base class pattern

📋 Compliance Checklist

Based on TUnit's verification requirements:

• ✅ Modern C# syntax: Uses collection expressions and appropriate patterns
• ✅ Snapshot tests accepted: All API verification files properly updated
• ✅ No performance regression: Lightweight implementation
• ⚠️ Dual-mode support: NEEDS VERIFICATION - unclear if reflection mode handles this correctly
• ✅ AOT/trimming compatible: No reflection or dynamic code generation
• ✅ Thread-safe: Stateless implementation with no shared mutable state

🎯 Recommendations

1. HIGH PRIORITY: Verify dual-mode compliance by testing in reflection mode
2. MEDIUM: Add tolerance validation in the Within() method
3. LOW: Add XML documentation for better IntelliSense support

🏆 Overall Assessment

This is a high-quality implementation that follows TUnit's established patterns and provides a valuable feature for decimal comparisons. The code is clean, well-tested, and consistent with the framework's design principles. The main concern is ensuring compliance with TUnit's dual-mode requirement.

Recommendation: ✅ Approve with verification - Confirm reflection mode support, then this PR is ready to merge.

---