feat(analyzers): EXP0036 — flag IExpressiveQueryable<T> chain dropouts

ExpressiveQueryableDropoutAnalyzer fires once at the call site where a
chain leaves IExpressiveQueryable<T> and returns plain IQueryable<T>,
surfacing the root cause instead of the downstream symptoms. Catches
user-defined helpers that take/return IQueryable<T>, third-party
extensions, and other implicit upcasts that silently strip the
ExpressiveSharp rewrite layer.

Exemptions: .AsQueryable() (sanctioned downcast), [NotExpressive] on
the offending method (intentional dropout), terminating calls whose
result is not IQueryable<T>, and methods whose result is still
IExpressiveQueryable<T> (chain preserved).

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

Author: koenbeuk

docs/reference/diagnostics.md

@@ -38,6 +38,7 @@ See [Troubleshooting](./troubleshooting) for symptom-oriented guidance -- find t
 | [EXP0033](#exp0033) | Error | `[ExpressiveProperty]` requires an expression-bodied property stub | -- |
 | [EXP0034](#exp0034) | Error | `[ExpressiveProperty]` requires an instance stub | -- |
 | [EXP0035](#exp0035) | Error | `[ExpressiveProperty]` target shadows inherited member | -- |
+| [EXP0036](#exp0036) | Info | `IExpressiveQueryable<T>` chain dropped to plain `IQueryable<T>` | -- |
 | [EXP1001](#exp1001) | Warning | Replace `[Projectable]` with `[Expressive]` | [Replace attribute](#exp1001-fix) |
 | [EXP1002](#exp1002) | Warning | Replace `UseProjectables()` with `UseExpressives()` | [Replace method call](#exp1002-fix) |
 | [EXP1003](#exp1003) | Warning | Replace Projectables namespace | [Replace namespace](#exp1003-fix) |
@@ -645,6 +646,57 @@ on an override
 
 ---
 
+### EXP0036 -- `IExpressiveQueryable<T>` chain dropped to plain `IQueryable<T>` {#exp0036}
+
+**Severity:** Info
+**Category:** Usage
+
+**Message:**
+```
+'{0}' returns IQueryable<T> from an IExpressiveQueryable<T> receiver, dropping the expressive
+chain. Downstream LINQ skips ExpressiveSharp rewriting and [Expressive] members may evaluate
+on the client. Add an IExpressiveQueryable<T>-typed overload of '{0}', wrap the result with
+.AsExpressive(), or mark the method [NotExpressive] if the dropout is intentional.
+```
+
+**Cause:** A method invocation is being made on a receiver that implements `IExpressiveQueryable<T>`, but the method's return type is plain `IQueryable<T>` (or some derivative that is not also expressive). The chain loses its expressive type at this call site, and every downstream LINQ operation on the result skips ExpressiveSharp's rewrite step — `[Expressive]` members in subsequent `Where` / `Select` / `Include` / etc. fall back to runtime delegate invocation, which most providers cannot translate and will evaluate on the client.
+
+The diagnostic fires once, at the dropout point itself, regardless of how many further calls follow.
+
+**Common dropout shapes:**
+
+```csharp
+// User-defined helper typed on plain IQueryable<T> — drops the chain.
+public static IQueryable<T> Filter<T>(this IQueryable<T> source) => source.Where(...);
+
+db.Orders.AsExpressiveDbSet().Filter()  // ⚠ EXP0036 fires on .Filter()
+    .Include(o => o.Customer)           // chain is plain from here on
+    .ToList();
+```
+
+**Fix (preferred):** Add a sibling overload typed on `IExpressiveQueryable<T>` that returns `IExpressiveQueryable<T>`:
+
+```csharp
+public static IExpressiveQueryable<T> Filter<T>(this IExpressiveQueryable<T> source)
+    => source.Where(...);
+```
+
+**Fix (when the helper can't be modified):** wrap the result with `.AsExpressive()` to restore the chain:
+
+```csharp
+db.Orders.AsExpressiveDbSet()
+    .ThirdPartyHelper()      // returns plain IQueryable<Order>
+    .AsExpressive()          // re-wrap
+    .Include(o => o.Customer);
+```
+
+**Exemptions:**
+
+- `.AsQueryable()` — the standard explicit downcast — is sanctioned and never reported.
+- Marking the offending method with `[NotExpressive]` suppresses the diagnostic at every call site, for cases where the dropout is intentional (the helper performs work that genuinely needs to run on the client).
+
+---
+
 ## Migration Diagnostics (EXP1001--EXP1003)
 
 These diagnostics are emitted by the `MigrationAnalyzer` in the `ExpressiveSharp.EntityFrameworkCore.CodeFixers` package. They detect usage of the legacy `EntityFrameworkCore.Projectables` library and offer automated code fixes to migrate to ExpressiveSharp.

src/ExpressiveSharp.CodeFixers/ExpressiveQueryableDropoutAnalyzer.cs

@@ -0,0 +1,108 @@
+using System.Collections.Immutable;
+using ExpressiveSharp.CodeFixers.Internal;
+using Microsoft.CodeAnalysis;
+using Microsoft.CodeAnalysis.CSharp;
+using Microsoft.CodeAnalysis.CSharp.Syntax;
+using Microsoft.CodeAnalysis.Diagnostics;
+
+namespace ExpressiveSharp.CodeFixers;
+
+/// <summary>
+/// Reports EXP0036 at the *dropout call* itself: a method invocation whose receiver implements
+/// <c>IExpressiveQueryable&lt;T&gt;</c> but whose return type is plain <c>IQueryable&lt;T&gt;</c>.
+/// The chain stops being expressive at this call; downstream LINQ skips ExpressiveSharp rewriting.
+/// </summary>
+/// <remarks>
+/// Exemptions:
+/// <list type="bullet">
+///   <item><description><c>AsQueryable()</c> — sanctioned explicit downcast.</description></item>
+///   <item><description>Methods marked <c>[NotExpressive]</c> — opt-out for intentional dropouts.</description></item>
+/// </list>
+/// </remarks>
+[DiagnosticAnalyzer(LanguageNames.CSharp)]
+public sealed class ExpressiveQueryableDropoutAnalyzer : DiagnosticAnalyzer
+{
+    public static readonly DiagnosticDescriptor ExpressiveQueryableDropout = new(
+        id: "EXP0036",
+        title: "IExpressiveQueryable<T> chain dropped to plain IQueryable<T>",
+        messageFormat: "'{0}' returns IQueryable<T> from an IExpressiveQueryable<T> receiver, dropping the expressive chain. Downstream LINQ skips ExpressiveSharp rewriting and [Expressive] members may evaluate on the client. Add an IExpressiveQueryable<T>-typed overload of '{0}', wrap the result with .AsExpressive(), or mark the method [NotExpressive] if the dropout is intentional.",
+        category: "Usage",
+        defaultSeverity: DiagnosticSeverity.Info,
+        isEnabledByDefault: true,
+        description: "Once an IExpressiveQueryable<T> chain is upcast back to plain IQueryable<T>, the ExpressiveSharp rewrite layer is no longer applied to subsequent calls. User-defined helpers that take and return IQueryable<T> are the most common cause; sibling overloads typed on IExpressiveQueryable<T> preserve the chain.");
+
+    public override ImmutableArray<DiagnosticDescriptor> SupportedDiagnostics =>
+        ImmutableArray.Create(ExpressiveQueryableDropout);
+
+    public override void Initialize(AnalysisContext context)
+    {
+        context.ConfigureGeneratedCodeAnalysis(GeneratedCodeAnalysisFlags.None);
+        context.EnableConcurrentExecution();
+        context.RegisterSyntaxNodeAction(AnalyzeInvocation, SyntaxKind.InvocationExpression);
+    }
+
+    private static void AnalyzeInvocation(SyntaxNodeAnalysisContext context)
+    {
+        var invocation = (InvocationExpressionSyntax)context.Node;
+
+        if (invocation.Expression is not MemberAccessExpressionSyntax memberAccess)
+            return;
+
+        var calledName = memberAccess.Name.Identifier.Text;
+
+        // Sanctioned explicit downcast — user knows exactly what they're doing.
+        if (calledName == "AsQueryable")
+            return;
+
+        var symbolInfo = context.SemanticModel.GetSymbolInfo(invocation, context.CancellationToken);
+        if (symbolInfo.Symbol is not IMethodSymbol method)
+            return;
+
+        // Method-level opt-out. Honored same as EXP0027 honors it on referenced members.
+        if (ExpressiveSymbolHelpers.HasNotExpressiveAttribute(method))
+            return;
+
+        var receiverType = context.SemanticModel.GetTypeInfo(
+            memberAccess.Expression, context.CancellationToken).Type;
+        if (receiverType is null)
+            return;
+        if (!ExpressiveSymbolHelpers.IsOrImplementsExpressiveQueryable(receiverType))
+            return;
+
+        var resultType = context.SemanticModel.GetTypeInfo(invocation, context.CancellationToken).Type;
+        if (resultType is null)
+            return;
+
+        // Terminating calls (.ToList, .Count, scalars, void) don't continue the chain — no dropout.
+        if (!ImplementsIQueryable(resultType))
+            return;
+
+        // Still expressive — chain preserved, no dropout.
+        if (ExpressiveSymbolHelpers.IsOrImplementsExpressiveQueryable(resultType))
+            return;
+
+        context.ReportDiagnostic(Diagnostic.Create(
+            ExpressiveQueryableDropout,
+            memberAccess.Name.GetLocation(),
+            properties: null,
+            calledName));
+    }
+
+    private static bool ImplementsIQueryable(ITypeSymbol type)
+    {
+        if (IsIQueryable(type))
+            return true;
+
+        foreach (var iface in type.AllInterfaces)
+        {
+            if (IsIQueryable(iface))
+                return true;
+        }
+
+        return false;
+    }
+
+    private static bool IsIQueryable(ITypeSymbol type) =>
+        type.Name == "IQueryable" &&
+        type.ContainingNamespace?.ToDisplayString() == "System.Linq";
+}