Support open generics in polymorphic serialization in System.Text.Json (#127318)

## Summary

Adds support for applying `[JsonDerivedType(typeof(Derived<>))]` to a
generic base type. The polymorphic resolver and source generator each
unify the open derived type against the closed base and, when a single
closed derived type can be constructed, register it for serialization.

This is groundwork for the upcoming C# [closed hierarchies][closed]
language feature, which allows generic closed base classes. Today,
polymorphic serialization requires every derived type to be spelled out
as a fully closed generic instantiation — workable for non-generic
hierarchies, but impractical for generic ones where each combination of
the base's type arguments yields a distinct closed instantiation that
the author would otherwise have to enumerate by hand.

Tracking: part of the work for #125449.

[closed]:
https://github.com/dotnet/csharplang/blob/main/proposals/closed-hierarchies.md

## Patterns now admitted

Each example uses regular classes; for each pattern the derived
attribute is declared once with an open generic, and the closed forms
are resolved per serialized instantiation of the base. All of these
compile (source generator) and round-trip (reflection):

1. **Matching arity / identity binding** — derived passes the base's
type parameter through unchanged.

   ```csharp
   [JsonDerivedType(typeof(Derived<>), "d")]
   public class Base<T> { ... }
   public class Derived<T> : Base<T> { ... }

   // Base<int>     → Derived<int>
   // Base<string>  → Derived<string>
   ```

2. **Reordered parameters** — derived rebinds the base's parameters in a
different position.

   ```csharp
   [JsonDerivedType(typeof(Derived<,>), "d")]
   public class Base<T1, T2> { ... }
   public class Derived<U, V> : Base<V, U> { ... }

   // Base<int, string> → Derived<string, int>
   ```

3. **Partial concretization in the derived's base spec** — derived fixes
some of the base's parameters to concrete types and leaves others open.

   ```csharp
   [JsonDerivedType(typeof(Derived<>), "d")]
   public class Base<T1, T2> { ... }
   public class Derived<T> : Base<T, int> { ... }

   // Base<string, int> → Derived<string>
   // Base<bool, int>   → Derived<bool>
   ```

4. **Wrapped / nested type arguments** — derived's type parameter shows
up inside a generic construction (or array) in the base spec.

   ```csharp
   [JsonDerivedType(typeof(Derived<>), "d")]
   public class Base<T> { ... }
   public class Derived<T> : Base<List<T>> { ... }

   // Base<List<int>> → Derived<int>

   [JsonDerivedType(typeof(ArrayDerived<>), "a")]
   public class ArrayDerived<T> : Base<T[]> { ... }

   // Base<int[]> → ArrayDerived<int>
   ```

5. **Interface bases** — same unification logic applies when the base is
a generic interface.

   ```csharp
   [JsonDerivedType(typeof(Derived<>), "d")]
   public interface IBase<T> { ... }
   public class Derived<T> : IBase<T> { ... }

   // IBase<int> → Derived<int>
   ```

6. **Type parameters from enclosing types** — derived inherits part of
its type arguments from an outer generic class.

   ```csharp
   [JsonDerivedType(typeof(Outer<>.Leaf<>), "leaf")]
   public class Base<T> { ... }

   public class Outer<T>
   {
       public class Leaf<U> : Base<(T, U)> { ... }
   }

   // Base<(int, string)> → Outer<int>.Leaf<string>
   ```

## Patterns still not supported (loud failure)

Each of these emits **SYSLIB1229** at source-generation time and throws
`InvalidOperationException` at reflection-resolver `Configure()` time.
The restrictions mirror the C# closed-hierarchies rules ("all of the
derived's type parameters must be used in the base class
specification"), with the additional requirement that the unification be
unambiguous.

1. **Ground-position mismatch** — derived constrains a base parameter to
a concrete type that the closed base doesn't agree with.

   ```csharp
   [JsonDerivedType(typeof(Derived<>), "d")]
   public class Base<T1, T2> { ... }
   public class Derived<T> : Base<T, int> { ... }

// Base<int, string> → ✗ (Derived requires T2 == int, but base has T2 ==
string)
   ```

2. **Wrapping not present on the closed base** — derived's base spec
wraps the parameter in a generic that the closed base doesn't carry.

   ```csharp
   [JsonDerivedType(typeof(Derived<>), "d")]
   public class Base<T> { ... }
   public class Derived<T> : Base<List<T>> { ... }

   // Base<int>       → ✗ (closed base T is `int`, not `List<...>`)
   // Base<List<int>> → ✓ Derived<int>  (admitted by pattern #4)
   ```

3. **Unbound derived type parameters** — derived declares more type
parameters than the base substitution can pin down (the
closed-hierarchies spec rejects this form directly).

   ```csharp
   [JsonDerivedType(typeof(Derived<,>), "d")]
   public class Base<T> { ... }
   public class Derived<T, U> : Base<T> { ... }

   // Base<int> → ✗ (U is unbound)
   ```

4. **Constraint violation under the resolved substitution** —
unification succeeds structurally but the closed derived type would
violate a `where` constraint.

   ```csharp
   [JsonDerivedType(typeof(Derived<>), "d")]
   public class Base<T> { ... }
   public class Derived<T> : Base<T> where T : struct { ... }

   // Base<string> → ✗ (string does not satisfy `where T : struct`)
   ```

5. **Ambiguous match** — derived implements two distinct constructions
of the same generic base, so the closed base could correspond to either.

   ```csharp
   [JsonDerivedType(typeof(Derived<>), "d")]
   public interface IBase<T> { ... }
   public class Derived<T> : IBase<T>, IBase<int> { ... }

   // IBase<int> → ✗ (could be Derived<int> or Derived<T> for any T)
   ```

6. **Arity / shape mismatch** — derived's open form has no constructed
base in common with the closed base at all.

   ```csharp
   [JsonDerivedType(typeof(Derived<>), "d")]
   public class Base { ... }                // non-generic
   public class Derived<T> : Base { ... }

   // Base → ✗ (closed base has no type arguments to bind T)
   ```

## Diagnostic

| ID | Severity | Message |
| ---------- | -------- |
---------------------------------------------------------------------------------------
|
| SYSLIB1229 | Warning | The open generic derived type `'{0}'` could not
be resolved against base `'{1}'`: `{2}` |

SYSLIB1229 is `#pragma`-suppressible, in which case the offending
derived entry is simply skipped from the generated metadata.

## Checklist

- [x] New tests in `JsonSourceGeneratorDiagnosticsTests` and
`PolymorphicTests.CustomTypeHierarchies` cover every supported and
unsupported pattern listed above.
- [x] Reflection resolver and source generator carry cross-referencing
comments on their two `TryResolveOpenGenericDerivedType` implementations
so the algorithms stay in sync.
- [x] SYSLIB1229 added to `docs/project/list-of-diagnostics.md`.
- [x] All reviewer feedback addressed.
- [x] All review threads resolved.

Co-authored-by: Eirik Tsarpalis <eirik.tsarpalis@gmail.com>
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Author: 3 people

docs/project/list-of-diagnostics.md

@@ -274,7 +274,7 @@ The diagnostic id values reserved for .NET Libraries analyzer warnings are `SYSL
 |  __`SYSLIB1226`__ | 'JsonIgnoreCondition.Always' is not valid on type-level 'JsonIgnoreAttribute' annotations. |
 |  __`SYSLIB1227`__ | Union case types cannot be unambiguously classified by JSON value type. |
 |  __`SYSLIB1228`__ | Union type shape is not a valid C# union. |
-|  __`SYSLIB1229`__ | _`SYSLIB1220`-`SYSLIB1229` reserved for System.Text.Json.SourceGeneration._ |
+|  __`SYSLIB1229`__ | Open generic derived type could not be resolved for the polymorphic base type. |
 |  __`SYSLIB1230`__ | Deriving from a `GeneratedComInterface`-attributed interface defined in another assembly is not supported. |
 |  __`SYSLIB1231`__ | _`SYSLIB1230`-`SYSLIB1239` reserved for Microsoft.Interop.ComInterfaceGenerator._ |
 |  __`SYSLIB1232`__ | _`SYSLIB1230`-`SYSLIB1239` reserved for Microsoft.Interop.ComInterfaceGenerator._ |

src/libraries/System.Text.Json/gen/Helpers/RoslynExtensions.cs

@@ -147,6 +147,14 @@ internal static class DiagnosticDescriptors
                 category: JsonConstants.SystemTextJsonSourceGenerationName,
                 defaultSeverity: DiagnosticSeverity.Warning,
                 isEnabledByDefault: true);
+
+            public static DiagnosticDescriptor OpenGenericDerivedTypeCouldNotBeResolved { get; } = DiagnosticDescriptorHelper.Create(
+                id: "SYSLIB1229",
+                title: new LocalizableResourceString(nameof(SR.OpenGenericDerivedTypeCouldNotBeResolvedTitle), SR.ResourceManager, typeof(FxResources.System.Text.Json.SourceGeneration.SR)),
+                messageFormat: new LocalizableResourceString(nameof(SR.OpenGenericDerivedTypeCouldNotBeResolvedMessageFormat), SR.ResourceManager, typeof(FxResources.System.Text.Json.SourceGeneration.SR)),
+                category: JsonConstants.SystemTextJsonSourceGenerationName,
+                defaultSeverity: DiagnosticSeverity.Warning,
+                isEnabledByDefault: true);
         }
     }
 }

src/libraries/System.Text.Json/gen/JsonSourceGenerator.DiagnosticDescriptors.cs

@@ -5,6 +5,7 @@
 using System.Collections.Immutable;
 using System.Diagnostics;
 using System.Diagnostics.CodeAnalysis;
+using System.Globalization;
 using System.Linq;
 using System.Text.Json.Serialization;
 using System.Threading;
@@ -938,6 +939,20 @@ private void ProcessTypeCustomAttributes(
                     {
                         Debug.Assert(attributeData.ConstructorArguments.Length > 0);
                         var derivedType = (ITypeSymbol)attributeData.ConstructorArguments[0].Value!;
+
+                        if (derivedType is INamedTypeSymbol { IsUnboundGenericType: true } unboundDerived)
+                        {
+                            if (!TryResolveOpenGenericDerivedType(
+                                    unboundDerived, typeToGenerate.Type,
+                                    out INamedTypeSymbol? resolvedType, out string? failureReason))
+                            {
+                                ReportDiagnostic(DiagnosticDescriptors.OpenGenericDerivedTypeCouldNotBeResolved, attributeData.GetLocation(), derivedType.ToDisplayString(), typeToGenerate.Type.ToDisplayString(), failureReason);
+                                continue;
+                            }
+
+                            derivedType = resolvedType!;
+                        }
+
                         TypeRef derivedTypeRef = EnqueueType(derivedType, typeToGenerate.Mode);
 
                         object? typeDiscriminator = null;
@@ -1021,6 +1036,211 @@ namedUnionType is not null &&
                 }
             }
 
+            /// <summary>
+            /// Source-gen-side resolver: closes <paramref name="unboundDerived"/> against
+            /// <paramref name="baseType"/> via structural unification at compile time.
+            /// Returns <c>true</c> when the registration can be closed to a unique concrete
+            /// type. Returns <c>false</c> with a localized <paramref name="failureReason"/>
+            /// suitable for inclusion in a diagnostic when the derived type cannot be
+            /// resolved against this particular base.
+            ///
+            /// IMPORTANT: This implementation MIRRORS the reflection resolver
+            /// <c>DefaultJsonTypeInfoResolver.Helpers.TryResolveOpenGenericDerivedType</c>
+            /// in src/System/Text/Json/Serialization/Metadata/DefaultJsonTypeInfoResolver.Helpers.cs.
+            /// Both implementations -- the structural unbound pre-check, the per-ancestor
+            /// unification, and the ambiguity detection -- must be kept in lockstep so that
+            /// source-gen and reflection produce the same closed type for the same registration.
+            /// Any algorithmic change here must be applied in the reflection mirror as well.
+            /// </summary>
+            private bool TryResolveOpenGenericDerivedType(
+                INamedTypeSymbol unboundDerived,
+                ITypeSymbol baseType,
+                out INamedTypeSymbol? resolvedType,
+                out string? failureReason)
+            {
+                resolvedType = null;
+                failureReason = null;
+
+                if (baseType is not INamedTypeSymbol { IsGenericType: true } constructedBase)
+                {
+                    failureReason = SR.Polymorphism_OpenGeneric_Reason_NotAssignable;
+                    return false;
+                }
+
+                INamedTypeSymbol derivedDefinition = unboundDerived.OriginalDefinition;
+                INamedTypeSymbol baseDefinition = constructedBase.OriginalDefinition;
+
+                // Collect every ancestor of the derived type definition whose original
+                // definition matches the base type definition. For classes there is at
+                // most one ancestor; for interfaces a derived type can implement the same
+                // interface definition multiple times with different type arguments.
+                List<INamedTypeSymbol> matchingBases = derivedDefinition
+                    .GetCompatibleGenericBaseTypes(baseDefinition)
+                    .ToList();
+
+                if (matchingBases.Count == 0)
+                {
+                    failureReason = SR.Polymorphism_OpenGeneric_Reason_NotAssignable;
+                    return false;
+                }
+
+                // The full set of generic parameters we must bind includes the parameters
+                // of the derived type definition AS WELL AS those declared by enclosing
+                // generic types (Outer<T>.Derived needs T bound from Outer).
+                List<ITypeParameterSymbol> requiredParams = derivedDefinition.GetAllTypeParameters();
+                ImmutableArray<ITypeSymbol> constructedBaseArgs = constructedBase.TypeArguments;
+
+                // Structural unbound pre-check: every required parameter must appear at least
+                // once somewhere in some matching ancestor's type arguments. If a parameter
+                // never appears at all, no closed base could ever bind it -- the derived
+                // definition is malformed regardless of which closed base it is registered
+                // against.
+                HashSet<ITypeParameterSymbol> referencedParams = new(SymbolEqualityComparer.Default);
+                foreach (INamedTypeSymbol mb in matchingBases)
+                {
+                    foreach (ITypeSymbol arg in mb.TypeArguments)
+                    {
+                        CollectReferencedParameters(arg, referencedParams);
+                    }
+                }
+                foreach (ITypeParameterSymbol required in requiredParams)
+                {
+                    if (!referencedParams.Contains(required))
+                    {
+                        failureReason = string.Format(
+                            CultureInfo.InvariantCulture,
+                            SR.Polymorphism_OpenGeneric_Reason_UnboundParameter,
+                            required.Name);
+                        return false;
+                    }
+                }
+
+                Dictionary<ITypeParameterSymbol, ITypeSymbol>? successfulSubstitution = null;
+                int successCount = 0;
+
+                foreach (INamedTypeSymbol matchingBase in matchingBases)
+                {
+                    ImmutableArray<ITypeSymbol> matchingBaseArgs = matchingBase.TypeArguments;
+                    Debug.Assert(matchingBaseArgs.Length == constructedBaseArgs.Length,
+                        "matchingBase and constructedBase share the same generic definition, so arity must match.");
+
+                    var substitution = new Dictionary<ITypeParameterSymbol, ITypeSymbol>(requiredParams.Count, SymbolEqualityComparer.Default);
+                    bool unified = true;
+                    for (int i = 0; i < matchingBaseArgs.Length; i++)
+                    {
+                        if (!matchingBaseArgs[i].TryUnifyWith(constructedBaseArgs[i], substitution))
+                        {
+                            unified = false;
+                            break;
+                        }
+                    }
+
+                    if (!unified)
+                    {
+                        continue;
+                    }
+
+                    // Unification succeeded for every position. Every required parameter must be
+                    // bound; otherwise the resulting closed type would have unbound type arguments
+                    // (an unspeakable type). A sibling ancestor may still bind this parameter, so
+                    // failure here is not fatal -- just move on to the next matching ancestor.
+                    bool allBound = true;
+                    foreach (ITypeParameterSymbol p in requiredParams)
+                    {
+                        if (!substitution.ContainsKey(p))
+                        {
+                            allBound = false;
+                            break;
+                        }
+                    }
+
+                    if (!allBound)
+                    {
+                        continue;
+                    }
+
+                    successCount++;
+                    if (successCount == 1)
+                    {
+                        successfulSubstitution = substitution;
+                    }
+                    else
+                    {
+                        failureReason = SR.Polymorphism_OpenGeneric_Reason_AmbiguousMatch;
+                        return false;
+                    }
+                }
+
+                if (successCount == 0 || successfulSubstitution is null)
+                {
+                    failureReason = SR.Polymorphism_OpenGeneric_Reason_UnificationFailed;
+                    return false;
+                }
+
+                // Validate constraints up front so the generated code will compile.
+                // Note: HasNotNullConstraint is not enforced because `notnull` is not a
+                // runtime-enforced constraint. Reflection MakeGenericType accepts e.g.
+                // string? for `where T : notnull`; source-gen must match that behavior.
+                if (!_knownSymbols.Compilation.TryValidateGenericConstraints(requiredParams, successfulSubstitution, out ITypeParameterSymbol? failedParam, out ITypeSymbol? failedArg))
+                {
+                    failureReason = string.Format(
+                        CultureInfo.InvariantCulture,
+                        SR.Polymorphism_OpenGeneric_Reason_ConstraintViolation,
+                        failedParam.Name,
+                        failedArg?.ToDisplayString() ?? string.Empty);
+                    return false;
+                }
+
+                // Build closedArgs in declaration order using the merged substitution.
+                ITypeSymbol[] closedArgs = new ITypeSymbol[requiredParams.Count];
+                for (int i = 0; i < requiredParams.Count; i++)
+                {
+                    closedArgs[i] = successfulSubstitution[requiredParams[i]];
+                }
+
+                // Note: ConstructWithEnclosingTypeArguments takes the parameters in the order
+                // they appear when listed as TypeParameters on the type and on its enclosing types.
+                // GetAllTypeParameters preserves that order (outer-to-inner, declaration order).
+                resolvedType = derivedDefinition.ConstructWithEnclosingTypeArguments(closedArgs);
+                return true;
+            }
+
+            private static void CollectReferencedParameters(ITypeSymbol pattern, HashSet<ITypeParameterSymbol> set)
+            {
+                switch (pattern)
+                {
+                    case ITypeParameterSymbol tp:
+                        set.Add(tp);
+                        return;
+
+                    case IArrayTypeSymbol array:
+                        CollectReferencedParameters(array.ElementType, set);
+                        return;
+
+                    case IPointerTypeSymbol pointer:
+                        CollectReferencedParameters(pointer.PointedAtType, set);
+                        return;
+
+                    case INamedTypeSymbol { IsGenericType: true } named:
+                        // Walk ContainingType to collect type parameters declared on enclosing
+                        // generic types (e.g. T in Outer<T>.Box<U>). Roslyn's TypeArguments is
+                        // leaf-only, while the reflection mirror uses Type.GetGenericArguments()
+                        // which flattens enclosing + leaf. Without this recursion, the unbound
+                        // pre-check would spuriously reject patterns whose only reference to a
+                        // type parameter lives in the enclosing type.
+                        if (named.ContainingType is { IsGenericType: true } containing)
+                        {
+                            CollectReferencedParameters(containing, set);
+                        }
+
+                        foreach (ITypeSymbol arg in named.TypeArguments)
+                        {
+                            CollectReferencedParameters(arg, set);
+                        }
+                        return;
+                }
+            }
+
             /// <summary>
             /// Checks whether the type is recognized as a union.
             /// </summary>

src/libraries/System.Text.Json/gen/JsonSourceGenerator.Parser.cs

@@ -219,4 +219,25 @@
   <data name="UnionTypeShapeNotSupportedMessageFormat" xml:space="preserve">
     <value>Union type '{0}' does not match the C# union shape convention: it must declare at least one public single-parameter case constructor and a public instance property named 'Value' with type 'object'.</value>
   </data>
+  <data name="OpenGenericDerivedTypeCouldNotBeResolvedTitle" xml:space="preserve">
+    <value>Open generic derived type could not be resolved for the polymorphic base type.</value>
+  </data>
+  <data name="OpenGenericDerivedTypeCouldNotBeResolvedMessageFormat" xml:space="preserve">
+    <value>The open generic derived type '{0}' could not be resolved for the polymorphic base type '{1}': {2}.</value>
+  </data>
+  <data name="Polymorphism_OpenGeneric_Reason_NotAssignable" xml:space="preserve">
+    <value>the derived type is not assignable to the base type</value>
+  </data>
+  <data name="Polymorphism_OpenGeneric_Reason_UnificationFailed" xml:space="preserve">
+    <value>the base type's arguments do not match the derived type's base specification</value>
+  </data>
+  <data name="Polymorphism_OpenGeneric_Reason_UnboundParameter" xml:space="preserve">
+    <value>the type parameter '{0}' of the derived type is not bound by the base type's arguments</value>
+  </data>
+  <data name="Polymorphism_OpenGeneric_Reason_ConstraintViolation" xml:space="preserve">
+    <value>the constraint on type parameter '{0}' is not satisfied by '{1}'</value>
+  </data>
+  <data name="Polymorphism_OpenGeneric_Reason_AmbiguousMatch" xml:space="preserve">
+    <value>the derived type matches the base type through multiple ancestors</value>
+  </data>
 </root>

src/libraries/System.Text.Json/gen/Resources/Strings.resx

@@ -132,6 +132,41 @@
         <target state="translated">Typ obsahuje více členů s komentářem JsonExtensionDataAttribute</target>
         <note />
       </trans-unit>
+      <trans-unit id="OpenGenericDerivedTypeCouldNotBeResolvedMessageFormat">
+        <source>The open generic derived type '{0}' could not be resolved for the polymorphic base type '{1}': {2}.</source>
+        <target state="new">The open generic derived type '{0}' could not be resolved for the polymorphic base type '{1}': {2}.</target>
+        <note />
+      </trans-unit>
+      <trans-unit id="Polymorphism_OpenGeneric_Reason_AmbiguousMatch">
+        <source>the derived type matches the base type through multiple ancestors</source>
+        <target state="new">the derived type matches the base type through multiple ancestors</target>
+        <note />
+      </trans-unit>
+      <trans-unit id="Polymorphism_OpenGeneric_Reason_ConstraintViolation">
+        <source>the constraint on type parameter '{0}' is not satisfied by '{1}'</source>
+        <target state="new">the constraint on type parameter '{0}' is not satisfied by '{1}'</target>
+        <note />
+      </trans-unit>
+      <trans-unit id="Polymorphism_OpenGeneric_Reason_NotAssignable">
+        <source>the derived type is not assignable to the base type</source>
+        <target state="new">the derived type is not assignable to the base type</target>
+        <note />
+      </trans-unit>
+      <trans-unit id="Polymorphism_OpenGeneric_Reason_UnboundParameter">
+        <source>the type parameter '{0}' of the derived type is not bound by the base type's arguments</source>
+        <target state="new">the type parameter '{0}' of the derived type is not bound by the base type's arguments</target>
+        <note />
+      </trans-unit>
+      <trans-unit id="Polymorphism_OpenGeneric_Reason_UnificationFailed">
+        <source>the base type's arguments do not match the derived type's base specification</source>
+        <target state="new">the base type's arguments do not match the derived type's base specification</target>
+        <note />
+      </trans-unit>
+      <trans-unit id="OpenGenericDerivedTypeCouldNotBeResolvedTitle">
+        <source>Open generic derived type could not be resolved for the polymorphic base type.</source>
+        <target state="new">Open generic derived type could not be resolved for the polymorphic base type.</target>
+        <note />
+      </trans-unit>
       <trans-unit id="TypeContainsRefLikeMemberFormat">
         <source>The type '{0}' includes the ref like property, field or constructor parameter '{1}'. No source code will be generated for the property, field or constructor.</source>
         <target state="translated">Typ {0} zahrnuje ref-like parametr vlastnosti, pole nebo konstruktoru {1}. Pro vlastnost, pole nebo konstruktor se nevygeneruje žádný zdrojový kód.</target>