feat(mocks): span return .Returns() support, out span params, and in param tests

[thomhurst]

Summary

• Add .Returns() support for methods returning ReadOnlySpan<T> / Span<T> — span values are stored as arrays via OutRefContext at index -1 and reconstructed at invocation time
• Add out/ref parameter support for span types via array conversion pattern (.ToArray() at setup, new Span<T>(array) at readback)
• Add test coverage for in (readonly ref) parameters which were implemented but untested

Changes

Source generator (5 files):

• MockMemberModel / MockParameterModel — added SpanReturnElementType and SpanElementType properties
• MemberDiscovery — detect ReadOnlySpan<T> / Span<T> via MetadataName + namespace
• MockMembersBuilder — generate Returns(SpanType) on void wrapper class for span returns; typed SetsOut/SetsRef methods for span out/ref params
• MockImplBuilder — EmitSpanReturnReadback reads index -1 from OutRefContext to reconstruct span return values; updated all 3 impl paths (interface, wrap, partial)

Tests (4 new files, 99 new tests):

• OutRefSpanTests.cs — 4 basic out ReadOnlySpan<byte> tests
• ComprehensiveOutRefSpanTests.cs — 70 tests across 10 classes (out Span, out ReadOnlySpan, multiple out params, ref+out combos, dual spans, sequential patterns)
• SpanReturnTests.cs — 14 tests for span-returning methods (.Returns, Callback, Throws, verification, arg matching, large data)
• InParameterTests.cs — 15 tests for in parameters (matching, returns, callbacks, throws, verification, structs, predicates)

Test plan

• All 592 TUnit.Mocks.Tests pass (dotnet run --framework net10.0)
• All 11 source generator snapshot tests pass
• Source generator builds with zero errors/warnings

[claude]

Code Review — Span Return + Out/Ref Span + In Parameter Support

This is a well-motivated set of changes that fills real gaps in TUnit.Mocks. The array-conversion pattern for span storage is the right approach (ref structs can't be boxed), and the test coverage is thorough. A few architectural concerns worth addressing:

---

Issue 1: Magic constant -1 creates a hidden, fragile contract

The most significant concern is using integer literal -1 as the storage key for span return values across two independently-generated code locations.

In MockMembersBuilder.cs:

// generated Returns(SpanType) method:
public {wrapperName} Returns({spanReturnType} value) {{ EnsureSetup().SetsOutParameter(-1, value.ToArray()); return this; }}

In MockImplBuilder.cs (EmitSpanReturnReadback):

writer.AppendLine($"if (__outRef.TryGetValue(-1, out var __spanRet)) return new {method.ReturnType}(({method.SpanReturnElementType}[])__spanRet!);");

This is a silent contract between two code-generation paths. The number -1 has no documentation at either site, and there is nothing preventing a future change from colliding with it (e.g., if parameter indexing ever went negative).

Better approach: Define a named constant in a shared location so the contract is explicit:

// In OutRefContext or a sibling constants class:
/// <summary>Reserved index used to store the return value for span-returning methods.</summary>
public const int SpanReturnValueIndex = -1;

Then reference OutRefContext.SpanReturnValueIndex in both generators. The generated code itself can still emit the literal, but the source of truth becomes self-documenting.

---

Issue 2: Code duplication between EmitOutRefReadback and EmitSpanReturnReadback

EmitSpanReturnReadback essentially reimplements the out/ref parameter reading loop from EmitOutRefReadback, then appends the span-return readback. The param-iteration block is copy-pasted nearly verbatim.

Why this matters: The two copies can drift. If a third case is added to parameter readback (e.g., a new ref struct subtype), it must be updated in both places.

Better approach: Extract the parameter-reading loop into a shared private helper, then compose:

private static void EmitOutRefParamReadback(CodeWriter writer, MockMemberModel method)
{
    // loop over out/ref params — single source of truth
    for (int i = 0; i < method.Parameters.Length; i++)
    {
        var p = method.Parameters[i];
        if (p.IsRefStruct && p.SpanElementType is null) continue;
        if (p.Direction == ParameterDirection.Out || p.Direction == ParameterDirection.Ref)
        {
            if (p.SpanElementType is not null)
                writer.AppendLine($"...");
            else
                writer.AppendLine($"...");
        }
    }
}

private static void EmitOutRefReadback(CodeWriter writer, MockMemberModel method)
{
    writer.AppendLine("var __outRef = global::TUnit.Mocks.Setup.OutRefContext.Consume();");
    using (writer.Block("if (__outRef is not null)"))
        EmitOutRefParamReadback(writer, method);
}

private static void EmitSpanReturnReadback(CodeWriter writer, MockMemberModel method)
{
    writer.AppendLine("var __outRef = global::TUnit.Mocks.Setup.OutRefContext.Consume();");
    using (writer.Block("if (__outRef is not null)"))
    {
        EmitOutRefParamReadback(writer, method);  // reuse
        writer.AppendLine($"if (__outRef.TryGetValue(-1, out var __spanRet)) return new {method.ReturnType}(({method.SpanReturnElementType}[])__spanRet!);");
    }
    writer.AppendLine("return default;");
}

---

Issue 3: GenerateVoidUnifiedClass signature extension with optional params

Adding optional parameters to an existing method is a low-risk change here (it's private, source-generated only), but the pattern is slightly misleading — the function is now generating fundamentally different code paths depending on whether spanReturnElementType is null.

Minor suggestion: A small parameter record or breaking these into separate methods (or overloads) would make the branching explicit. This is a lower-priority concern given it's internal to the generator.

---

Positives

• GetSpanElementType — clean implementation using MetadataName + namespace rather than display strings; robust against aliasing.
• Thread safety — [ThreadStatic] in OutRefContext correctly isolates parallel test execution.
• Model equality — SpanElementType and SpanReturnElementType are correctly included in Equals and GetHashCode on both model types.
• Test coverage — 99 tests across 4 files covering empty spans, data, throws, callbacks, verification, arg matchers, and mixed params is excellent.
• The #if NET9_0_OR_GREATER guard in ComprehensiveOutRefSpanTests for ref struct arg matching is the right approach.
• Fallback return default; in EmitSpanReturnReadback correctly handles the no-setup path.

---

Summary

Severity	Concern
Medium	Magic -1 literal — define a named constant
Low	Duplicated out/ref param loop — extract shared helper
Nit	Optional params on GenerateVoidUnifiedClass

The span array-conversion pattern is the right design for ref struct serialization. Addressing the -1 constant would significantly improve maintainability.

[claude]

Follow-up Review

Good news: both primary concerns from the previous review have been fully addressed in the second commit (d70a5a09).

---

Issue 1 (Magic -1 literal) — ✅ Resolved

OutRefContext.SpanReturnValueIndex = -1 is now a named constant, and both generation sites reference it via the fully qualified name:

• MockMembersBuilder.cs: EnsureSetup().SetsOutParameter(global::TUnit.Mocks.Setup.OutRefContext.SpanReturnValueIndex, value.ToArray())
• MockImplBuilder.cs (EmitSpanReturnReadback): __outRef.TryGetValue(global::TUnit.Mocks.Setup.OutRefContext.SpanReturnValueIndex, ...)

The public documentation on the constant (Parameter indices are always >= 0, so -1 is safe from collision) makes the contract self-evident.

---

Issue 2 (Duplicated out/ref param loop) — ✅ Resolved

EmitOutRefParamAssignments is now the single source of truth for parameter readback, called from both EmitOutRefReadback and EmitSpanReturnReadback. The split-continue guard (if (p.IsRefStruct && p.SpanElementType is null) continue;) correctly handles the non-span ref struct skip in one place.

---

Issue 3 (Optional params on GenerateVoidUnifiedClass) — Accepted as-is

This was a nit; the current approach is pragmatic and low-risk for an internal generator method. No action needed.

---

No new concerns

The PR is clean. The GetSpanElementType detection, model equality/hash updates, and test coverage all remain solid. Approved.