feat(mocks): add ReturnsAsync typed factory overload with method parameters

[thomhurst]

Summary

Closes #5361

The Returns method generates typed factory overloads that provide access to the actual method parameters (e.g. Returns((string key) => ...)), but ReturnsAsync was missing equivalent overloads. This meant users had to use .Returns with a blocking .Result call to access parameters in async methods.

Changes

• Generates a typed ReturnsAsync(Func<T1, ..., Task<TReturn>> factory) overload for async mock methods that have parameters (both Task<T> and ValueTask<T>)
• Adds ComputedRawReturnWithArgsBehavior and ReturnsRaw(Func<object?[], object?>) in the runtime library to support the generated code
• Refactors the three-branch typed overload emission in the source generator into a shared EmitTypedOverloads helper
• Adds 7 new tests covering typed ReturnsAsync, Callback, and Throws overloads on async Task<T> and ValueTask<T> methods

Before

// Had to use .Returns with blocking .Result to access method parameters
mock
    .DoSomethingAsync(Any<Func<Task<string>>>())
    .Returns(factory => factory.Invoke().Result);

After

// Typed ReturnsAsync factory with access to method parameters
mock
    .GetNameAsync(Any<string>())
    .ReturnsAsync((string key) => Task.FromResult($"value-{key}"));

// Also works with ValueTask<T>
mock
    .ComputeAsync(Any<int>())
    .ReturnsAsync((int input) => new ValueTask<int>(input * 10));

Test plan

• All 96 source generator snapshot tests pass
• All 739+ mock runtime tests pass (including 7 new tests)
• Full typed overload coverage matrix verified for async methods:

Overload	Task<T>	ValueTask<T>
ReturnsAsync(typed factory)	✅	✅
Callback(typed action)	✅	✅
Throws(typed factory)	✅	✅
ReturnsAsync + Then chain	✅	—

[codacy-production]

Up to standards ✅

🟢 Issues 0 issues

Results:
0 new issues

View in Codacy

🟢 Metrics 17 complexity

Metric	Results
Complexity	17

View in Codacy

_{TIP This summary will be updated as you push new changes. Give us feedback}

[claude]

Code Review

This is a clean, well-scoped feature addition. The implementation is consistent with existing patterns and the test coverage is thorough.

What's Good

Consistency with existing ReturnsAsync pattern
The new GenerateTypedReturnsAsyncOverload generates EnsureSetup().ReturnsRaw(args => (object?)factory(castArgs)), which is exactly consistent with the parameterless factory overload at line 893:

// Existing zero-arg ReturnsAsync (line 893)
EnsureSetup().ReturnsRaw(() => (object?)taskFactory())
// New typed-param ReturnsAsync (this PR)
EnsureSetup().ReturnsRaw(args => (object?)factory(castArgs))

This symmetry is the right design — the Task<T>/ValueTask<T> object is returned as-is (not awaited), which is correct since the mock method's return type is the task.

EmitTypedOverloads refactor
The extraction into a shared helper reduces ~15 lines of duplication cleanly and correctly threads isAsync/fullReturnType through both the NET9+ and fallback branches. The resulting call sites at lines 214–222 are much easier to read.

Test coverage
Seven tests covering Task, ValueTask, chaining with .Then(), Callback, and Throws on async methods — exactly the coverage matrix the feature needs.

---

One Concern: Null-forgiving on nullable reference types in cast args

In the generated code for Interface_With_Nullable_Reference_Type_Parameters:

EnsureSetup().ReturnsRaw(args => (object?)factory((string?)args[0]!));

The ! null-forgiving operator is applied to a cast to string? (a nullable type). This is pre-existing in Callback and Returns overloads (same BuildCastArgs helper), so this PR doesn't introduce it. But it's technically misleading: a caller passing null for a string? parameter will have args[0] == null, and the ! tells the compiler "not null" on something that can legitimately be null. At runtime it's harmless (the cast to string? accepts null), but it muddies intent.

This is pre-existing technical debt in BuildCastArgs rather than a problem with this PR, but it's worth tracking if the null-handling story for casts is ever cleaned up.

---

Minor Observation

The fullReturnType parameter passed into EmitTypedOverloads is the full task type (e.g. global::System.Threading.Tasks.Task<string>). For the #if NET9_0_OR_GREATER branch and the #else branch, the same fullReturnType is passed — this is correct since the return type doesn't change across TFMs, only the parameter list differs. Verified in context.

---

Overall: Solid implementation. The feature fills a real gap (avoiding .Result blocking in mock factories) and the implementation is consistent with existing infrastructure. Good to merge.

[claude]

Follow-up Review

The previous review noted one concern about the misleading null-forgiving ! operator on nullable cast args — the follow-up commit 051a8aec ("fix: remove misleading null-forgiving operator on nullable cast args") directly addresses it.

Concern Addressed

The CastArg helper now correctly distinguishes:

private static string CastArg(MockParameterModel p, int index)
{
    // For nullable types, skip the null-forgiving operator since the value can legitimately be null.
    // For non-nullable types, ! suppresses the object? -> T conversion warning.
    var bang = p.FullyQualifiedType.EndsWith("?") ? "" : "!";
    return $"({p.FullyQualifiedType})args[{index}]{bang}";
}

This is the right fix. Using EndsWith("?") to detect nullable reference types is a reasonable heuristic at codegen time — it correctly handles string?, object?, T? etc. without needing full Roslyn type analysis.

The snapshot update confirms the generated output is now correct: (string?)args[0] (no bang) vs (string)args[0]! (with bang).

One Minor Note

EndsWith("?") will also match nullable value types like int? — but that's fine since nullable value types also accept null legitimately, so omitting ! is equally correct there.

---

Overall: Both commits are clean, the concern from the first review has been properly resolved. This PR is ready to merge.