Generate back-compat overload when a service method gains a new optional non-body parameter (microsoft#10532)

Adding an optional parameter to a service method is non-breaking in
TypeSpec but breaks generated C# clients (callers binding to the old
method signature fail to resolve). The generator now mirrors the
[Service-Driven
Evolution](https://github.com/Azure/azure-sdk-for-net/blob/main/doc/DataPlaneCodeGeneration/ServiceDrivenEvolution.md#a-method-gets-a-new-optional-parameter)
guidance and emits a hidden overload matching the previous contract's
signature.

### Changes

- **`ClientProvider.BuildMethodsForBackCompatibility`** — after
parameter reordering, scans `LastContractView.Methods` for previous
signatures whose parameters are a same-order subset of a current method,
where every extra current parameter is optional and **non-body**. Emits
a hidden `[EditorBrowsable(Never)]` `ScmMethodProvider` overload (same
`ScmMethodKind` as the current method) that delegates to the current
method via the `This.Invoke(string methodName,
IReadOnlyList<ValueExpression> arguments)` snippet, passing `default`
for each new parameter. Async overloads delegate without `await` so the
back-compat method itself remains non-async. The reordering and
new-optional-parameter passes are factored into private helpers
(`ProcessBackCompatForParameterReordering` and
`ProcessBackCompatForNewOptionalParameters`) which share a single
`currentMethodSignatures` dictionary and mutate the same
`materializedMethods` list. The new-optional-parameter pass skips
`ScmMethodProvider`s with `Kind == CreateRequest` and only generates
overloads for matched candidates whose `Kind` is `Convenience` or
`Protocol`, inheriting that `Kind`/`ServiceMethod` from the current
method. The candidate match collapses the `ScmMethodProvider` /
`Convenience|Protocol` filter into the candidates loop's pattern match,
and `currentMethodSignatures.TryAdd` is reused both for dedup and to
make new overloads visible to subsequent iterations (no auxiliary lists
or sets).
- **Body parameters are intentionally excluded** per the linked
guidance, since adding a body parameter typically reflects a schema
change handled elsewhere.
-
**`BackCompatibilityChangeCategory.SvcMethodNewOptionalParameterOverloadAdded`**
— new category surfaced in the emitter end-of-run summary.
- **Tests** — `BackCompatibility_NewOptionalNonBodyParameterAdded`,
`BackCompatibility_MultipleNewOptionalNonBodyParametersAdded`,
`BackCompatibility_NewOptionalNonBodyParameterAddedWithModelBody`
(covers an `InputModelType` request body),
`BackCompatibility_NewOptionalNonBodyParameterAddedWithPathAndHeaderParameters`
(covers a method whose previous contract mixes a path parameter with a
required query and a required header),
`BackCompatibility_NewOptionalBodyParameterDoesNotAddBackCompatOverload`,
`BackCompatibility_NewRequiredParameterDoesNotAddBackCompatOverload`.
All six tests run `TypeProviderWriter.Write()` on the affected client
wrapped in a `FilteredMethodsTypeProvider` so the expected `.cs`
fixtures under `TestData/ClientProviderTests/` only contain the affected
operation's protocol + convenience + back-compat methods.
- **Docs** — new "Client Methods" section in `backward-compatibility.md`
showing the full generated client (current sync/async then back-compat
sync/async) with one-sentence per-overload comments, the optional
default shown as `default`, the `async` modifier on the current async
method, and the back-compat delegating call using named arguments.
Includes a note verifying [Azure SDK parameter
ordering](https://azure.github.io/azure-sdk/dotnet_implementation.html#parameter-presence-and-ordering)
and a note explaining why the async back-compat overload returns the
`Task` directly without `await`.

### Example

Previous contract:

```csharp
public virtual ClientResult GetData(int p1, BinaryContent body, RequestOptions options = null);
public virtual Task<ClientResult> GetDataAsync(int p1, BinaryContent body, RequestOptions options = null);
```

Current TypeSpec adds an optional `@query p2?: boolean`. Generated
client:

```csharp
// Current sync method generated from the updated TypeSpec.
public virtual ClientResult GetData(int p1, BinaryContent body, bool? p2 = default, RequestOptions options = null) { /* ... */ }

// Current async method generated from the updated TypeSpec.
public virtual async Task<ClientResult> GetDataAsync(int p1, BinaryContent body, bool? p2 = default, RequestOptions options = null) { /* ... */ }

// Back-compat sync overload matching the previous contract's signature.
[EditorBrowsable(EditorBrowsableState.Never)]
public virtual ClientResult GetData(int p1, BinaryContent body, RequestOptions options)
    => this.GetData(p1: p1, body: body, p2: default, options: options);

// Back-compat async overload matching the previous contract's signature.
[EditorBrowsable(EditorBrowsableState.Never)]
public virtual Task<ClientResult> GetDataAsync(int p1, BinaryContent body, RequestOptions options)
    => this.GetDataAsync(p1: p1, body: body, p2: default, options: options);
```

Defaults are stripped from the back-compat signature to avoid ambiguous
call sites with the current method.

---------

Co-authored-by: copilot-swe-agent[bot] <198982749+Copilot@users.noreply.github.com>
Co-authored-by: jorgerangel-msft <102122018+jorgerangel-msft@users.noreply.github.com>

Author: Copilot

packages/http-client-csharp/generator/Microsoft.TypeSpec.Generator.ClientModel/src/Providers/ClientProvider.cs

@@ -1256,16 +1256,29 @@ protected override ScmMethodProvider[] BuildMethods()
 
         protected sealed override IReadOnlyList<MethodProvider> BuildMethodsForBackCompatibility(IEnumerable<MethodProvider> originalMethods)
         {
+            List<MethodProvider> materializedMethods = [.. originalMethods];
+
             if (LastContractView?.Methods == null || LastContractView.Methods.Count == 0)
             {
-                return [.. originalMethods];
+                return materializedMethods;
             }
 
-            var currentMethodSignatures = BuildCurrentMethodSignatures(originalMethods);
+            var currentMethodSignatures = BuildCurrentMethodSignatures(materializedMethods);
+
+            ProcessBackCompatForParameterReordering(materializedMethods, currentMethodSignatures);
+            ProcessBackCompatForNewOptionalParameters(materializedMethods, currentMethodSignatures);
+
+            return materializedMethods;
+        }
+
+        private void ProcessBackCompatForParameterReordering(
+            IList<MethodProvider> materializedMethods,
+            Dictionary<MethodSignature, MethodProvider> currentMethodSignatures)
+        {
             var updatedSignatureToOriginal = new Dictionary<MethodSignature, MethodSignature>(MethodSignature.MethodSignatureComparer);
             var methodsWithReorderedParams = new List<MethodProvider>();
 
-            foreach (var previousMethod in LastContractView.Methods)
+            foreach (var previousMethod in LastContractView!.Methods)
             {
                 if (!ShouldProcessMethodForBackCompat(previousMethod.Signature, currentMethodSignatures))
                 {
@@ -1290,10 +1303,8 @@ protected sealed override IReadOnlyList<MethodProvider> BuildMethodsForBackCompa
 
             if (methodsWithReorderedParams.Count > 0)
             {
-                UpdateConvenienceMethodsForBackCompat(originalMethods, methodsWithReorderedParams, updatedSignatureToOriginal);
+                UpdateConvenienceMethodsForBackCompat(materializedMethods, methodsWithReorderedParams, updatedSignatureToOriginal);
             }
-
-            return [.. originalMethods];
         }
 
         private Dictionary<MethodSignature, MethodProvider> BuildCurrentMethodSignatures(IEnumerable<MethodProvider> originalMethods)
@@ -1748,5 +1759,151 @@ private static void UpdateXmlDocProviderForParamReorder(
                 xmlDocs.Update(parameters: reorderedParamDocs);
             }
         }
+
+        private void ProcessBackCompatForNewOptionalParameters(
+            List<MethodProvider> methods,
+            Dictionary<MethodSignature, MethodProvider> currentMethodSignatures)
+        {
+            var currentMethodsByName = new Dictionary<string, List<MethodProvider>>();
+            foreach (var method in currentMethodSignatures.Values)
+            {
+                if (method is ScmMethodProvider { Kind: ScmMethodKind.CreateRequest })
+                {
+                    continue;
+                }
+
+                if (!currentMethodsByName.TryGetValue(method.Signature.Name, out var list))
+                {
+                    list = [];
+                    currentMethodsByName[method.Signature.Name] = list;
+                }
+                list.Add(method);
+            }
+
+            foreach (var previousMethod in LastContractView!.Methods)
+            {
+                var previousSignature = previousMethod.Signature;
+
+                if (!previousSignature.Modifiers.HasFlag(MethodSignatureModifiers.Public) &&
+                    !previousSignature.Modifiers.HasFlag(MethodSignatureModifiers.Protected))
+                {
+                    continue;
+                }
+
+                if (currentMethodSignatures.ContainsKey(previousSignature) ||
+                    !currentMethodsByName.TryGetValue(previousSignature.Name, out var candidates))
+                {
+                    continue;
+                }
+
+                ScmMethodProvider? matchedCurrent = null;
+                foreach (var candidate in candidates)
+                {
+                    if (candidate is ScmMethodProvider { Kind: ScmMethodKind.Convenience or ScmMethodKind.Protocol } scmCandidate &&
+                        HasNewOptionalNonBodyParametersOnly(previousSignature, scmCandidate.Signature))
+                    {
+                        matchedCurrent = scmCandidate;
+                        break;
+                    }
+                }
+
+                if (matchedCurrent is null)
+                {
+                    continue;
+                }
+
+                var overload = BuildBackCompatOverloadForNewOptionalParameters(previousMethod, matchedCurrent);
+                if (overload == null || !currentMethodSignatures.TryAdd(overload.Signature, overload))
+                {
+                    continue;
+                }
+
+                methods.Add(overload);
+                CodeModelGenerator.Instance.Emitter.Debug(
+                    $"Added back-compat overload for '{Name}.{previousSignature.Name}' to handle new optional parameter(s) introduced relative to the last contract.",
+                    BackCompatibilityChangeCategory.SvcMethodNewOptionalParameterOverloadAdded);
+            }
+        }
+
+        // Returns true when currentSignature contains all parameters of previousSignature in the same
+        // relative order, every "extra" parameter is optional, and none of the extras are body parameters.
+        private static bool HasNewOptionalNonBodyParametersOnly(
+            MethodSignature previousSignature,
+            MethodSignature currentSignature)
+        {
+            if (currentSignature.Parameters.Count <= previousSignature.Parameters.Count)
+            {
+                return false;
+            }
+
+            if (previousSignature.ReturnType is null
+                ? currentSignature.ReturnType is not null
+                : !previousSignature.ReturnType.AreNamesEqual(currentSignature.ReturnType))
+            {
+                return false;
+            }
+
+            // Walk current parameters and ensure previous parameters appear in the same relative order
+            // (matched by variable name and type), with every "extra" parameter being optional and non-body.
+            int previousIndex = 0;
+            for (int currentIndex = 0; currentIndex < currentSignature.Parameters.Count; currentIndex++)
+            {
+                var currentParam = currentSignature.Parameters[currentIndex];
+
+                if (previousIndex < previousSignature.Parameters.Count)
+                {
+                    var previousParam = previousSignature.Parameters[previousIndex];
+                    if (currentParam.Name.ToVariableName() == previousParam.Name.ToVariableName() &&
+                        currentParam.Type.AreNamesEqual(previousParam.Type))
+                    {
+                        previousIndex++;
+                        continue;
+                    }
+                }
+
+                if (currentParam.DefaultValue is null)
+                {
+                    return false;
+                }
+
+                if (currentParam.Location == ParameterLocation.Body)
+                {
+                    return false;
+                }
+            }
+
+            return previousIndex == previousSignature.Parameters.Count;
+        }
+
+        private ScmMethodProvider? BuildBackCompatOverloadForNewOptionalParameters(
+            MethodProvider previousMethod,
+            ScmMethodProvider currentMethod)
+        {
+            var previousSignature = previousMethod.Signature;
+            var currentSignature = currentMethod.Signature;
+
+            var previousParamsByName = new Dictionary<string, ParameterProvider>();
+            foreach (var p in previousSignature.Parameters)
+            {
+                previousParamsByName.TryAdd(p.Name, p);
+            }
+
+            var arguments = new List<ValueExpression>(currentSignature.Parameters.Count);
+            foreach (var currentParam in currentSignature.Parameters)
+            {
+                ValueExpression value = previousParamsByName.TryGetValue(currentParam.Name, out var prevParam)
+                    ? prevParam
+                    : (currentParam.DefaultValue ?? Default);
+                arguments.Add(PositionalReference(currentParam.Name, value));
+            }
+
+            return new ScmMethodProvider(
+                signature: MethodSignatureHelper.BuildBackCompatMethodSignature(previousSignature, hideMethod: true),
+                bodyStatements: Return(This.Invoke(currentSignature.Name, arguments)),
+                enclosingType: this,
+                methodKind: currentMethod.Kind,
+                xmlDocProvider: previousMethod.XmlDocs,
+                serviceMethod: currentMethod.ServiceMethod);
+        }
     }
 }