fix: correct XML docs, remove dead symbol comparisons, add wrapper tests (#1067)

Remove dead comparisons against IReturns (arity 0) and IReturns1 (arity 1)
from IsMatchingFluentSymbol. These types resolve to null in Moq 4.18+ and
the comparisons always evaluated to false.

Fix XML doc comments for accuracy:
- IsMatchingFluentSymbol: correct type parameter names, clarify arity-0/1
  resolve to null rather than claiming non-existence
- ImplementsMoqFluentInterface: describe behavior, not caller intent
- IsCallbackRaisesMethod: include ISetupGetter and ISetupSetter in summary
- IsFluentChainWrapperMethod: state assumption rather than assertion
- IsWrapperMethod: mention raises methods in exclusion list
- MockRepositoryCreate: fix doc that said "Of" instead of "Create"

Add test coverage for ReturnsAsync wrapper, ValueTask wrapper, and
NoOpPassthrough (documenting accepted false-negative tradeoff).

Deduplicate MoqKnownSymbolsTests added by upstream merge.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: rjmurillo

src/Analyzers/MethodSetupShouldSpecifyReturnValueAnalyzer.cs

@@ -189,9 +189,9 @@ private static bool HasReturnValueSpecification(
             }
 
             // When a non-Moq method (e.g., an extension method) appears in the chain,
-            // check if its return type implements a Moq fluent interface. A return type
-            // like IReturns<TMock, TResult> indicates the method wraps the setup
-            // configuration internally and preserves the fluent chain.
+            // check if its return type implements a Moq fluent interface. The analyzer
+            // assumes such methods handle return value specification internally or pass
+            // the chain through for further configuration.
             if (IsFluentChainWrapperMethod(symbolInfo, knownSymbols))
             {
                 return true;
@@ -241,8 +241,9 @@ private static bool HasReturnValueSymbol(SymbolInfo symbolInfo, MoqKnownSymbols
 
     /// <summary>
     /// Determines whether a method in the chain is a wrapper (e.g., an extension method)
-    /// whose return type implements a Moq fluent interface. Such methods wrap the setup
-    /// configuration internally (calling Returns/Throws inside) and return the fluent chain.
+    /// whose return type implements a Moq fluent interface. Such methods are assumed to
+    /// handle return value specification internally, as indicated by their Moq fluent
+    /// return type.
     /// </summary>
     private static bool IsFluentChainWrapperMethod(SymbolInfo symbolInfo, MoqKnownSymbols knownSymbols)
     {
@@ -261,9 +262,9 @@ private static bool IsFluentChainWrapperMethod(SymbolInfo symbolInfo, MoqKnownSy
 
     /// <summary>
     /// Returns true when <paramref name="method"/> is a user-defined wrapper whose return
-    /// type implements a Moq fluent interface. Known Moq return-value and callback methods
-    /// are excluded because they are already handled by <see cref="HasReturnValueSymbol"/>
-    /// and <see cref="IsKnownReturnValueMethodName"/>.
+    /// type implements a Moq fluent interface. Known Moq return-value, callback, and raises
+    /// methods are excluded because they are already handled by earlier checks in the
+    /// chain walk.
     /// </summary>
     private static bool IsWrapperMethod(IMethodSymbol method, MoqKnownSymbols knownSymbols)
     {

src/Common/ISymbolExtensions.Moq.cs

@@ -188,15 +188,13 @@ internal static bool IsMoqRaisesMethod(this ISymbol symbol, MoqKnownSymbols know
     }
 
     /// <summary>
-    /// Determines whether a type symbol implements any Moq fluent interface from the
-    /// <c>Moq.Language</c> or <c>Moq.Language.Flow</c> namespaces. Used to detect
-    /// wrapper methods (e.g., extension methods) that internally configure the setup
-    /// chain and return a Moq fluent type.
+    /// Determines whether a type symbol is or implements any Moq fluent interface from
+    /// the <c>Moq.Language</c> or <c>Moq.Language.Flow</c> namespaces.
     /// </summary>
-    /// <param name="typeSymbol">The return type of the method to check.</param>
+    /// <param name="typeSymbol">The type symbol to check.</param>
     /// <param name="knownSymbols">Known Moq symbols resolved from the compilation.</param>
     /// <returns>
-    /// <see langword="true"/> if the type implements or is a Moq fluent interface;
+    /// <see langword="true"/> if the type is or implements a Moq fluent interface;
     /// otherwise, <see langword="false"/>.
     /// </returns>
     internal static bool ImplementsMoqFluentInterface(this ITypeSymbol typeSymbol, MoqKnownSymbols knownSymbols)
@@ -226,11 +224,11 @@ private static bool IsConcreteSetupPhraseRaisesMethod(ISymbol symbol, MoqKnownSy
     }
 
     /// <summary>
-    /// Checks if the symbol is a Raises method from ICallback interfaces.
+    /// Checks if the symbol is a Raises method from ICallback, ISetupGetter, or ISetupSetter interfaces.
     /// </summary>
     /// <param name="symbol">The symbol to check.</param>
     /// <param name="knownSymbols">The known symbols for type checking.</param>
-    /// <returns>True if the symbol is a callback Raises method; otherwise false.</returns>
+    /// <returns>True if the symbol is a Raises method from one of these interfaces; otherwise false.</returns>
     private static bool IsCallbackRaisesMethod(ISymbol symbol, MoqKnownSymbols knownSymbols)
     {
         return symbol.IsInstanceOf(knownSymbols.ICallbackRaises) ||
@@ -319,23 +317,29 @@ private static bool HasMoqFluentInterfaceInHierarchy(ITypeSymbol typeSymbol, Moq
 
     /// <summary>
     /// Compares a type symbol against the set of known Moq fluent interface symbols
-    /// that indicate a return value has been or can be configured.
+    /// that indicate the fluent chain is active and a return value can be configured.
     /// </summary>
     /// <remarks>
     /// <para>
     /// This method intentionally excludes <c>ICallback</c>, <c>ICallback{TMock}</c>, and
     /// <c>ICallback{TMock, TResult}</c> because these interfaces do not inherit from
-    /// <c>IReturns</c> and do not indicate that a return value has been configured.
-    /// Types like <c>ISetup{TMock, TResult}</c> that inherit from <c>IReturns</c> are
-    /// still caught via <see cref="HasMoqFluentInterfaceInHierarchy"/> when checking
+    /// <c>IReturns{TMock, TResult}</c> and do not indicate that a return value can be
+    /// configured. Types like <c>ISetup{TMock, TResult}</c> that inherit from
+    /// <c>IReturns{TMock, TResult}</c> are still caught via
+    /// <see cref="HasMoqFluentInterfaceInHierarchy"/> when checking
     /// <see cref="ITypeSymbol.AllInterfaces"/>.
     /// </para>
     /// <para>
-    /// Only symbols that exist in Moq are checked. <c>Moq.Language.IReturns</c> (arity 0)
-    /// and <c>Moq.Language.IReturns`1</c> (arity 1) do not exist in Moq; only
-    /// <c>Moq.Language.IReturns`2</c> exists. <c>IReturnsResult{TMock}</c> is the actual
-    /// return type of <c>.Returns()</c> and <c>.ReturnsAsync()</c>, and
-    /// <c>IThrowsResult</c> is the return type of <c>.Throws()</c>.
+    /// Only <c>IReturns{TMock, TResult}</c> (arity 2) is checked. <c>Moq.Language.IReturns</c>
+    /// (arity 0) and <c>Moq.Language.IReturns{T}</c> (arity 1) resolve to null in Moq 4.18+
+    /// and are not part of the fluent setup chain.
+    /// </para>
+    /// <para>
+    /// <c>IThrows</c>, <c>ISetup{TResult}</c>, <c>ISetupGetter{TMock, TProperty}</c>, and
+    /// <c>ISetupSetter{TMock, TProperty}</c> are included because a wrapper method may
+    /// return these types directly. <c>IReturnsResult{TMock}</c> is the return type of
+    /// <c>.Returns()</c> and <c>.ReturnsAsync()</c>. <c>IThrowsResult</c> is the return
+    /// type of <c>.Throws()</c>.
     /// </para>
     /// </remarks>
     private static bool IsMatchingFluentSymbol(INamedTypeSymbol type, MoqKnownSymbols knownSymbols)

src/Common/WellKnown/MoqKnownSymbols.cs

@@ -246,7 +246,7 @@ internal MoqKnownSymbols(Compilation compilation)
     internal INamedTypeSymbol? MockRepository => TypeProvider.GetOrCreateTypeByMetadataName("Moq.MockRepository");
 
     /// <summary>
-    /// Gets the methods for <c>Moq.MockRepository.Of</c>.
+    /// Gets the methods for <c>Moq.MockRepository.Create</c>.
     /// </summary>
     /// <remarks>
     /// <c>MockRepository</c> is a subclass of <c>MockFactory</c>.

tests/Moq.Analyzers.Test/Common/MoqKnownSymbolsTests.cs

@@ -158,20 +158,6 @@ public void IThrows_WithoutMoqReference_ReturnsNull()
         Assert.Null(symbols.IThrows);
     }
 
-    [Fact]
-    public void IReturnsResult1_WithoutMoqReference_ReturnsNull()
-    {
-        MoqKnownSymbols symbols = CreateSymbolsWithoutMoq();
-        Assert.Null(symbols.IReturnsResult1);
-    }
-
-    [Fact]
-    public void IThrowsResult_WithoutMoqReference_ReturnsNull()
-    {
-        MoqKnownSymbols symbols = CreateSymbolsWithoutMoq();
-        Assert.Null(symbols.IThrowsResult);
-    }
-
     [Fact]
     public void ReturnsExtensions_WithoutMoqReference_ReturnsNull()
     {
@@ -235,6 +221,20 @@ public void NonVoidSetupPhrase2_WithoutMoqReference_ReturnsNull()
         Assert.Null(symbols.NonVoidSetupPhrase2);
     }
 
+    [Fact]
+    public void IReturnsResult1_WithoutMoqReference_ReturnsNull()
+    {
+        MoqKnownSymbols symbols = CreateSymbolsWithoutMoq();
+        Assert.Null(symbols.IReturnsResult1);
+    }
+
+    [Fact]
+    public void IThrowsResult_WithoutMoqReference_ReturnsNull()
+    {
+        MoqKnownSymbols symbols = CreateSymbolsWithoutMoq();
+        Assert.Null(symbols.IThrowsResult);
+    }
+
     [Fact]
     public void IRaiseable_WithoutMoqReference_ReturnsNull()
     {
@@ -840,23 +840,6 @@ public async Task IThrows_WithMoqReference_ReturnsNamedTypeSymbol()
         Assert.Equal("IThrows", symbols.IThrows!.Name);
     }
 
-    [Fact]
-    public async Task IReturnsResult1_WithMoqReference_ReturnsNamedTypeSymbol()
-    {
-        MoqKnownSymbols symbols = await CreateSymbolsWithMoqAsync();
-        Assert.NotNull(symbols.IReturnsResult1);
-        Assert.Equal("IReturnsResult", symbols.IReturnsResult1!.Name);
-        Assert.Equal(1, symbols.IReturnsResult1.Arity);
-    }
-
-    [Fact]
-    public async Task IThrowsResult_WithMoqReference_ReturnsNamedTypeSymbol()
-    {
-        MoqKnownSymbols symbols = await CreateSymbolsWithMoqAsync();
-        Assert.NotNull(symbols.IThrowsResult);
-        Assert.Equal("IThrowsResult", symbols.IThrowsResult!.Name);
-    }
-
     [Fact]
     public async Task IThrowsThrows_WithMoqReference_ReturnsNonEmpty()
     {
@@ -933,6 +916,24 @@ public async Task IRaise1_WithMoqReference_ReturnsNamedTypeSymbol()
         Assert.Equal(1, symbols.IRaise1!.Arity);
     }
 
+    [Fact]
+    public async Task IReturnsResult1_WithMoqReference_ReturnsNamedTypeSymbol()
+    {
+        MoqKnownSymbols symbols = await CreateSymbolsWithMoqAsync();
+        Assert.NotNull(symbols.IReturnsResult1);
+        Assert.Equal("IReturnsResult", symbols.IReturnsResult1!.Name);
+        Assert.Equal(1, symbols.IReturnsResult1.Arity);
+    }
+
+    [Fact]
+    public async Task IThrowsResult_WithMoqReference_ReturnsNamedTypeSymbol()
+    {
+        MoqKnownSymbols symbols = await CreateSymbolsWithMoqAsync();
+        Assert.NotNull(symbols.IThrowsResult);
+        Assert.Equal("IThrowsResult", symbols.IThrowsResult!.Name);
+        Assert.Equal(0, symbols.IThrowsResult.Arity);
+    }
+
     [Fact]
     public void Task_WithCoreReferences_ReturnsNamedTypeSymbol()
     {

tests/Moq.Analyzers.Test/MethodSetupShouldSpecifyReturnValueAnalyzerTests.cs

@@ -442,7 +442,7 @@ public static IEnumerable<object[]> Issue1067_WrappedSetupTestData()
             new Mock<IFoo>().Setup(x => x.DoSomething("test")).ReturnsTrue();
             """],
 
-            // Extension method on async setup returning Task result wrapper
+            // Extension method returning IReturns<TMock, Task<int>> that calls Returns internally
             ["""
             var moq = new Mock<IFoo>();
             moq.Setup(x => x.BarAsync()).ReturnsOneAsync();
@@ -459,6 +459,27 @@ public static IEnumerable<object[]> Issue1067_WrappedSetupTestData()
             var moq = new Mock<IFoo>();
             moq.Setup(x => x.GetValue()).ThrowsInvalidOp();
             """],
+
+            // Extension method on async setup that calls ReturnsAsync internally
+            ["""
+            var moq = new Mock<IFoo>();
+            moq.Setup(x => x.BarAsync()).ReturnsOneAsyncViaReturnsAsync();
+            """],
+
+            // Extension method on ValueTask setup using Returns(new ValueTask<T>(...))
+            ["""
+            var moq = new Mock<IFoo>();
+            moq.Setup(x => x.BazValueTaskAsync()).ReturnsOneValueTask();
+            """],
+
+            // Accepted false negative: no-op passthrough returning a fluent type without
+            // calling Returns. The analyzer cannot inspect the wrapper body, so it assumes
+            // methods returning fluent types handle configuration internally. Documented
+            // tradeoff: this suppresses Moq1203 even though no return value is configured.
+            ["""
+            var moq = new Mock<IFoo>();
+            moq.Setup(x => x.GetValue()).NoOpPassthrough();
+            """],
         ];
 
         return data.WithNamespaces().WithNewMoqReferenceAssemblyGroups();
@@ -653,6 +674,7 @@ public interface IFoo
                 int GetValue();
                 int Calculate(int a, int b);
                 Task<int> BarAsync();
+                ValueTask<int> BazValueTaskAsync();
                 void DoVoidMethod();
                 void ProcessData(string data);
                 string Name { get; set; }
@@ -710,6 +732,26 @@ public static Task AsTask<TMock, TResult>(this ISetup<TMock, TResult> setup)
                 {
                     return Task.CompletedTask;
                 }
+
+                public static IReturns<TMock, Task<int>> ReturnsOneAsyncViaReturnsAsync<TMock>(this IReturns<TMock, Task<int>> mock)
+                    where TMock : class
+                {
+                    mock.ReturnsAsync(1);
+                    return mock;
+                }
+
+                public static IReturns<TMock, ValueTask<int>> ReturnsOneValueTask<TMock>(this IReturns<TMock, ValueTask<int>> mock)
+                    where TMock : class
+                {
+                    mock.Returns(new ValueTask<int>(1));
+                    return mock;
+                }
+
+                public static ISetup<TMock, TResult> NoOpPassthrough<TMock, TResult>(this ISetup<TMock, TResult> setup)
+                    where TMock : class
+                {
+                    return setup;
+                }
             }
 
             internal class UnitTest