Merge pull request #48 from EFNext/feat/smart-diagnostics

Add NotExpressive attribute and related analyzer

Author: koenbeuk

docs/reference/diagnostics.md

@@ -32,11 +32,13 @@ See [Troubleshooting](./troubleshooting) for symptom-oriented guidance -- find t
 | [EXP0017](#exp0017) | Error | `[ExpressiveFor]` return type mismatch | -- |
 | [EXP0019](#exp0019) | Error | `[ExpressiveFor]` conflicts with `[Expressive]` | -- |
 | [EXP0020](#exp0020) | Error | Duplicate `[ExpressiveFor]` mapping | -- |
+| [EXP0027](#exp0027) | Info | Plain `IQueryable` chain references an `[Expressive]` member without `.AsExpressive()` | [Wrap with `.AsExpressive()`](#exp0027-fix) |
 | [EXP0031](#exp0031) | Error | `[ExpressiveProperty]` target name is already defined | -- |
 | [EXP0032](#exp0032) | Error | `[ExpressiveProperty]` requires a partial containing type | -- |
 | [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) |
@@ -475,12 +477,45 @@ Duplicate [ExpressiveFor] mapping for member '{0}' on type '{1}'; only one stub
 
 ---
 
+### EXP0027 -- Plain `IQueryable` chain references an `[Expressive]` member without `.AsExpressive()` {#exp0027}
+
+**Severity:** Info
+**Category:** Usage
+
+**Message:**
+```
+LINQ method '{0}' on a plain IQueryable<T> references the [Expressive] member '{1}'.
+Without .AsExpressive(), the member's body will not be inlined into the expression tree;
+the provider may evaluate the call in memory or fail to translate it. Wrap the source
+with .AsExpressive().
+```
+
+**Cause:** A LINQ method on a plain `IQueryable<T>` receiver (one that is not `IExpressiveQueryable<T>`) is invoked with a lambda whose body references an `[Expressive]` member. Because the chain is not expressive-aware, the source generator does not rewrite the lambda into an expression tree that inlines the member's body — the underlying query provider receives a call to the runtime delegate. Most providers cannot translate this and will either evaluate the call client-side (silent overfetch) or throw at execution time.
+
+**Fix:** Wrap the chain root with `.AsExpressive()` so that subsequent LINQ methods flow through the ExpressiveSharp delegate-based overloads, which inline `[Expressive]` member bodies at compile time.
+
+```csharp
+// Before — IsAdult is silently evaluated on the client.
+var adults = users.Where(u => u.IsAdult).ToList();
+
+// After — IsAdult is inlined into the expression tree before the provider sees it.
+var adults = users.AsExpressive().Where(u => u.IsAdult).ToList();
+```
+
+When you intentionally want to evaluate a member at runtime (e.g., it captures process state), mark the member with `[NotExpressive]` to suppress the diagnostic at every call site.
+
+#### Code Fix: Wrap source with `.AsExpressive()` {#exp0027-fix}
+
+The IDE offers a single code action: **Wrap source with `.AsExpressive()`**. It walks the LINQ chain to the leftmost non-LINQ expression, wraps it with `.AsExpressive()`, and inserts `using ExpressiveSharp;` if it is not already imported.
+
+---
+
 ## `[ExpressiveProperty]` Diagnostics (EXP0031--EXP0035)
 
 These diagnostics apply to `[ExpressiveProperty]` stubs, which ask the generator to emit a new property on the stub's containing partial type. See [`[ExpressiveProperty]` Attribute](./expressive-property) for the full feature reference.
 
 ::: info Replacing `[Expressive(Projectable = true)]`
-`[ExpressiveProperty]` replaces the now-removed `[Expressive(Projectable = true)]`. Diagnostic codes `EXP0021`--`EXP0030` were retired along with that feature and are not reused. The migration recipe is in [Migration from Projectables](../guide/migration-from-projectables#migrating-usememberbody).
+`[ExpressiveProperty]` replaces the now-removed `[Expressive(Projectable = true)]`. Diagnostic codes `EXP0021`--`EXP0026` and `EXP0028`--`EXP0030` were retired along with that feature and are not reused. (EXP0027 has been reassigned to the [plain-IQueryable analyzer](#exp0027).) The migration recipe is in [Migration from Projectables](../guide/migration-from-projectables#migrating-usememberbody).
 :::
 
 ### EXP0031 -- Target name is already defined {#exp0031}
@@ -611,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.

docs/reference/expressive-attribute.md

@@ -136,6 +136,27 @@ ExpressiveOptions.Default.AddTransformers(new RemoveNullConditionalPatterns());
 expr.ExpandExpressives(); // RemoveNullConditionalPatterns applied automatically
 ```
 
+## Opting Out: `[NotExpressive]`
+
+Use `[NotExpressive]` to mark a member that *looks* expressive-eligible (it has an expression body that the source generator could lift) but should intentionally remain runtime-evaluated. The attribute suppresses the analyzer suggestions:
+
+- [EXP0013](./diagnostics#exp0013) — "Member could benefit from `[Expressive]`"
+- [EXP0027](./diagnostics#exp0027) — "Plain `IQueryable` chain references an `[Expressive]` member without `.AsExpressive()`"
+
+```csharp
+public class Order
+{
+    public Guid Id { get; set; }
+
+    // Always evaluated in-memory — captures process-local state that would not
+    // survive translation. Suppress the "could be [Expressive]" suggestion.
+    [NotExpressive]
+    public string DebugLabel => $"{Id} (pid {System.Environment.ProcessId})";
+}
+```
+
+`[NotExpressive]` cannot be combined with `[Expressive]` on the same member.
+
 ## Complete Example
 
 ::: expressive-sample

src/ExpressiveSharp.Abstractions/NotExpressiveAttribute.cs

@@ -0,0 +1,17 @@
+namespace ExpressiveSharp;
+
+/// <summary>
+/// Suppresses ExpressiveSharp diagnostics that suggest decorating this member with
+/// <see cref="ExpressiveAttribute"/> or wrapping a query in <c>.AsExpressive()</c>.
+/// </summary>
+/// <remarks>
+/// Use this attribute on members whose bodies look expandable but should intentionally
+/// remain runtime-evaluated — for example, when the body relies on side effects, captures
+/// state that would not survive translation, or is deliberately client-side.
+/// </remarks>
+[AttributeUsage(
+    AttributeTargets.Method | AttributeTargets.Property | AttributeTargets.Constructor,
+    Inherited = true, AllowMultiple = false)]
+public sealed class NotExpressiveAttribute : Attribute
+{
+}

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";
+}

src/ExpressiveSharp.CodeFixers/Internal/ExpressiveSymbolHelpers.cs

@@ -0,0 +1,87 @@
+using System.Threading;
+using Microsoft.CodeAnalysis;
+using Microsoft.CodeAnalysis.CSharp.Syntax;
+
+namespace ExpressiveSharp.CodeFixers.Internal;
+
+/// <summary>
+/// Shared classification helpers used by the diagnostics that reason about
+/// <c>[Expressive]</c>-eligible members and Expressive query chains.
+/// </summary>
+internal static class ExpressiveSymbolHelpers
+{
+    public static bool HasExpressiveAttribute(ISymbol symbol)
+        => HasAttribute(symbol, "ExpressiveAttribute");
+
+    public static bool HasNotExpressiveAttribute(ISymbol symbol)
+        => HasAttribute(symbol, "NotExpressiveAttribute");
+
+    private static bool HasAttribute(ISymbol symbol, string attributeTypeName)
+    {
+        foreach (var attr in symbol.GetAttributes())
+        {
+            var attrClass = attr.AttributeClass;
+            if (attrClass is null)
+                continue;
+            if (attrClass.Name == attributeTypeName &&
+                attrClass.ContainingNamespace?.ToDisplayString() == "ExpressiveSharp")
+                return true;
+        }
+        return false;
+    }
+
+    /// <summary>
+    /// Returns true when the symbol declares an inspectable body (expression-bodied or block-bodied)
+    /// that the source generator could lift into an expression tree if <c>[Expressive]</c> were applied.
+    /// </summary>
+    public static bool HasExpandableBody(ISymbol symbol, CancellationToken ct)
+    {
+        foreach (var syntaxRef in symbol.DeclaringSyntaxReferences)
+        {
+            var syntax = syntaxRef.GetSyntax(ct);
+
+            if (syntax is MethodDeclarationSyntax methodDecl)
+            {
+                if (methodDecl.ExpressionBody is not null || methodDecl.Body is not null)
+                    return true;
+            }
+            else if (syntax is PropertyDeclarationSyntax propDecl)
+            {
+                if (propDecl.ExpressionBody is not null)
+                    return true;
+
+                if (propDecl.AccessorList is not null)
+                {
+                    foreach (var accessor in propDecl.AccessorList.Accessors)
+                    {
+                        if (accessor.IsKind(Microsoft.CodeAnalysis.CSharp.SyntaxKind.GetAccessorDeclaration) &&
+                            (accessor.ExpressionBody is not null || accessor.Body is not null))
+                            return true;
+                    }
+                }
+            }
+        }
+        return false;
+    }
+
+    /// <summary>
+    /// Returns true when the type is or implements <c>ExpressiveSharp.IExpressiveQueryable&lt;T&gt;</c>.
+    /// </summary>
+    public static bool IsOrImplementsExpressiveQueryable(ITypeSymbol type)
+    {
+        if (IsExpressiveQueryableType(type))
+            return true;
+
+        foreach (var iface in type.AllInterfaces)
+        {
+            if (IsExpressiveQueryableType(iface))
+                return true;
+        }
+
+        return false;
+    }
+
+    private static bool IsExpressiveQueryableType(ITypeSymbol type) =>
+        type.Name == "IExpressiveQueryable" &&
+        type.ContainingNamespace?.ToDisplayString() == "ExpressiveSharp";
+}