feat(assertions): enhance Map method to support automatic pending link transfer

[thomhurst]

No description provided.

[claude]

Claude finished @thomhurst's task —— View job

---

PR Review: Map Method Enhancement

Review Checklist

• Analyze main implementation changes in AssertionContext.cs
• Review API surface changes in PublicAPI files
• Check code quality and best practices
• Identify potential bugs or issues
• Assess performance considerations
• Evaluate security concerns
• Review test coverage implications
• Provide comprehensive feedback

📝 Review Summary

This PR enhances the Map method in AssertionContext<TValue> to support automatic pending link transfer, enabling proper cross-type assertion chaining. The changes are well-designed and address a specific need for type-transforming assertions.

✅ Code Quality & Best Practices

Strengths:

• Clear API design: The new overload uses Func<EvaluationContext<TValue>, EvaluationContext<TNew>> which provides flexibility for complex transformations
• Excellent documentation: Comprehensive XML docs with concrete examples (Assert.That(str).HasLength(3).And.Match(@"\d+").And.Captured<int>(1))
• Consistent patterns: Follows existing patterns used in TypeOfAssertion.cs:35 and ParseAssertions.cs:239
• Backward compatibility: Original Map(Func<TValue?, TNew?>) now delegates to the new implementation
• Single responsibility: Each method has a clear, focused purpose

Code structure looks good:

// Transfer pending links from source context to handle cross-type chaining
var (pendingAssertion, combinerType) = ConsumePendingLink();
if (pendingAssertion != null)
{
    newContext.PendingPreWork = async () => await pendingAssertion.ExecuteCoreAsync();
}

🔍 Technical Analysis

Correct implementation:

• ✅ Properly consumes pending links using ConsumePendingLink()
• ✅ Correctly transfers ExpressionBuilder to maintain error message context
• ✅ Sets up PendingPreWork to execute previous assertions before transformation
• ✅ Follows async/await patterns correctly

API surface changes are minimal and appropriate:

• Only one new method signature added to public API
• No breaking changes to existing functionality

🚀 Performance Considerations

Good performance characteristics:

• ✅ No additional allocations beyond necessary async delegate
• ✅ Lazy execution via PendingPreWork - only executes when needed
• ✅ Reuses existing ExpressionBuilder and EvaluationContext infrastructure
• ✅ Single consumption of pending links prevents double execution

🔐 Security Assessment

No security concerns identified:

• ✅ No reflection or dynamic code generation
• ✅ Properly typed generic methods
• ✅ No external dependencies or unsafe operations
• ✅ Exception handling delegated to existing assertion execution paths

🧪 Test Coverage

Excellent test coverage already exists:

• Tests in ParseAssertionTests.cs show comprehensive scenarios:
  • WhenParsedInto_WithAnd_PreviousAssertion_ShouldPass/Fail
  • WhenParsedInto_ComplexChain_AllChecked
  • Cross-type chaining with multiple assertions
• Similar patterns exist in TypeAssertionTests.cs

🎯 Use Case Validation

This enhancement enables important assertion patterns like:

// String assertions followed by parsed value assertions
await Assert.That("123")
    .HasLength(3)           // String assertion
    .And.WhenParsedInto<int>()  // Type transformation with link transfer
    .IsGreaterThan(100);    // Int assertion on parsed value

// Type checking with continued assertions
await Assert.That(obj)
    .IsNotNull()           // Object assertion  
    .And.IsTypeOf<string>()    // Type transformation with link transfer
    .HasLength(5);         // String assertion on cast value

📋 Minor Suggestions

1. Consider adding example to method summary: The existing example is excellent - consider adding one more showing the simplest case
2. API consistency: The new method follows TUnit patterns well - no changes needed

✅ Overall Assessment

Excellent implementation that:

• Solves a real need for cross-type assertion chaining
• Maintains backward compatibility
• Follows established patterns in the codebase
• Has comprehensive test coverage
• Introduces no performance or security issues
• Properly handles the complexity of pending link transfer

Recommendation: ✅ Approve

This is a well-designed enhancement that improves the assertion library's capability without introducing risks or breaking changes.