Make C# back-compat aware of ApiCompat baseline files (#11048)

## Problem

The backward-compatibility system uses `LastContractView` to keep
generated APIs source-compatible with the previous version: it
resurrects removed public members and preserves a property's previous
type. But when a breaking change has **already been accepted** in an
[ApiCompat](https://github.com/dotnet/sdk/tree/main/src/Compatibility)
baseline (suppression) file — conventionally
`eng/apicompatbaselines/<AssemblyName>.txt` in the Azure SDK — that
back-compat behavior fights the accepted decision: it re-introduces
intentionally-removed API and can reference types that no longer exist.

Example baseline entries:

```
TypesMustExist : Type 'Azure.AI.Projects.Agents.ProjectsAgentProtocol' does not exist in the implementation but it does exist in the contract.
MembersMustExist : Member 'public Azure.AI.Projects.Agents.ProtocolVersionRecord Azure.AI.Projects.Agents.ProjectsAgentsModelFactory.ProtocolVersionRecord(Azure.AI.Projects.Agents.ProjectsAgentProtocol, System.String)' does not exist in the implementation but it does exist in the contract.
```

## Fix

- Add `ApiCompatBaseline` (`Microsoft.TypeSpec.Generator.SourceInput`):
a tolerant parser for ApiCompat baseline files that understands
`TypesMustExist` and `MembersMustExist` suppressions. Member matching
uses declaring-type full name + member name + parameter count (arity),
avoiding brittle parameter-type string comparisons. Type suppression
implies all of its members are suppressed.
- Discover the baseline file by walking up from the project directory to
`eng/apicompatbaselines/<PrimaryNamespace>.txt`
(`GeneratedCodeWorkspace.LoadApiCompatBaseline`), expose the parsed
baseline on `SourceInputModel`, and wire loading into `CSharpGen`.
- **Skip resurrected members** in the model factory back-compat path
(`ModelFactoryProvider.BuildMethodsForBackCompatibility`): a removed
factory method whose removal is accepted in the baseline is not
regenerated.
- **Allow property type changes** in `ModelProvider.BuildProperties`:
the generator normally reverts a property to its previous
(last-contract) type to avoid a breaking change. When that previous type
— or a type nested within it (e.g. a collection element type) — is an
accepted baseline removal, preserving it would reference a now-deleted
type, so the current (spec) type is kept instead. Added
`ApiCompatBaseline.ReferencesSuppressedType` (recurses into generic
arguments) and a `BaselineAcceptedRemovalSkipped` change category.

The remaining back-compat consumers (`ModelProvider` constructors, the
enum providers, `ClientProvider`, and `RestClientProvider`) can be made
baseline-aware the same way as a follow-up; this is documented in
`docs/backward-compatibility.md`.

## Tests

- `ApiCompatBaselineTests` — parser coverage (types, methods,
constructors, property accessors, generic-arg arity, unknown/malformed
lines) and `ReferencesSuppressedType` (direct + nested generic
argument).
-
`ModelFactoryProviderTests.BackCompatibility_SuppressedByApiCompatBaselineNotRegenerated`
— a baselined factory method is **not** regenerated.
-
`ModelProviderTests.BackCompat_PropertyTypeChangeAllowedWhenPreviousTypeSuppressed`
— a property whose previous type is a baseline-accepted removal takes
its current spec type.
- Full `Microsoft.TypeSpec.Generator.Tests` suite passes (1552 tests).

---------

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Author: JoshLove-msft

packages/http-client-csharp/generator/Microsoft.TypeSpec.Generator/src/CSharpGen.cs

@@ -59,7 +59,8 @@ public async Task ExecuteAsync()
 
             CodeModelGenerator.Instance.SourceInputModel = new SourceInputModel(
                 await customCodeWorkspace.GetCompilationAsync(),
-                await GeneratedCodeWorkspace.LoadBaselineContract());
+                await GeneratedCodeWorkspace.LoadBaselineContract(),
+                GeneratedCodeWorkspace.LoadApiCompatBaseline());
 
             GeneratedCodeWorkspace generatedCodeWorkspace = await GeneratedCodeWorkspace.Create(isCustomCodeProject: false);
 

packages/http-client-csharp/generator/Microsoft.TypeSpec.Generator/src/EmitterRpc/BackCompatibilityChangeCategory.cs

@@ -42,5 +42,8 @@ public enum BackCompatibilityChangeCategory
 
         /// <summary>A back-compat overload of a client method was added because new optional non-body parameter(s) were introduced relative to the last contract.</summary>
         SvcMethodNewOptionalParameterOverloadAdded,
+
+        /// <summary>A back-compat change was skipped because the removal was accepted in the ApiCompat baseline.</summary>
+        BaselineAcceptedRemovalSkipped,
     }
 }

packages/http-client-csharp/generator/Microsoft.TypeSpec.Generator/src/EmitterRpc/Emitter.cs

@@ -181,6 +181,7 @@ public void WriteBufferedMessages()
             BackCompatibilityChangeCategory.ModelFactoryMethodAdded => "Model Factory Method Added For Back-Compat",
             BackCompatibilityChangeCategory.ModelFactoryMethodSkipped => "Model Factory Method Back-Compat Skipped",
             BackCompatibilityChangeCategory.SvcMethodNewOptionalParameterOverloadAdded => "Method Back-Compat Overload Added For New Optional Parameter",
+            BackCompatibilityChangeCategory.BaselineAcceptedRemovalSkipped => "Back-Compat Skipped For ApiCompat Baseline Accepted Removal",
             _ => category.ToString(),
         };
 

packages/http-client-csharp/generator/Microsoft.TypeSpec.Generator/src/PostProcessing/GeneratedCodeWorkspace.cs

@@ -16,6 +16,7 @@
 using Microsoft.CodeAnalysis.Simplification;
 using Microsoft.TypeSpec.Generator.Primitives;
 using Microsoft.TypeSpec.Generator.Providers;
+using Microsoft.TypeSpec.Generator.SourceInput;
 using Microsoft.TypeSpec.Generator.Utilities;
 using NuGet.Configuration;
 
@@ -364,6 +365,32 @@ internal static async Task AddPackageReferencesFromProject()
             }
         }
 
+        /// <summary>
+        /// Locates and parses the ApiCompat baseline (suppression) file for the current library, if
+        /// present. The file is expected at <c>eng/apicompatbaselines/&lt;AssemblyName&gt;.txt</c>
+        /// relative to a repository root discovered by walking up from the project directory.
+        /// Returns <see cref="ApiCompatBaseline.Empty"/> when no baseline file is found.
+        /// </summary>
+        internal static ApiCompatBaseline LoadApiCompatBaseline()
+        {
+            var packageName = CodeModelGenerator.Instance.TypeFactory.PrimaryNamespace;
+            var directory = new DirectoryInfo(CodeModelGenerator.Instance.Configuration.ProjectDirectory);
+
+            while (directory != null)
+            {
+                var candidate = Path.Combine(directory.FullName, "eng", "apicompatbaselines", $"{packageName}.txt");
+                if (File.Exists(candidate))
+                {
+                    CodeModelGenerator.Instance.Emitter.Debug($"Loading ApiCompat baseline from {candidate}");
+                    return ApiCompatBaseline.FromFile(candidate);
+                }
+
+                directory = directory.Parent;
+            }
+
+            return ApiCompatBaseline.Empty;
+        }
+
         internal static async Task<Compilation?> LoadBaselineContract()
         {
             var packageName = CodeModelGenerator.Instance.TypeFactory.PrimaryNamespace;

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

@@ -116,6 +116,19 @@ protected internal sealed override IReadOnlyList<MethodProvider> BuildMethodsFor
                     continue;
                 }
 
+                // If the removal of this factory method has already been accepted in the ApiCompat
+                // baseline, honor that decision and do not resurrect a compatibility shim for it.
+                if (CodeModelGenerator.Instance.SourceInputModel?.ApiCompatBaseline.IsMemberSuppressed(
+                        Type.FullyQualifiedName,
+                        previousMethod.Signature.Name,
+                        previousMethod.Signature.Parameters.Count) == true)
+                {
+                    CodeModelGenerator.Instance.Emitter.Info(
+                        $"Skipping back-compat shim for '{Type.FullyQualifiedName}.{previousMethod.Signature.Name}'; removal is accepted in the ApiCompat baseline.",
+                        BackCompatibilityChangeCategory.BaselineAcceptedRemovalSkipped);
+                    continue;
+                }
+
                 List<MethodSignature> currentOverloads = [];
                 bool foundCompatibleOverload = false;
 

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

@@ -620,10 +620,22 @@ protected internal override PropertyProvider[] BuildProperties()
                     LastContractPropertiesMap.TryGetValue(outputProperty.Name, out var lastContractPropertyType) &&
                     !lastContractPropertyType.Equals(outputProperty.Type))
                 {
-                    outputProperty.Type = lastContractPropertyType.ApplyInputSpecProperty(property);
-                    CodeModelGenerator.Instance.Emitter.Info(
-                        $"Changed property '{Name}.{outputProperty.Name}' type to '{lastContractPropertyType}' to match last contract.",
-                        BackCompatibilityChangeCategory.PropertyTypePreserved);
+                    // If the previous property type (or a type nested in it) has been intentionally
+                    // removed and that removal is accepted in the ApiCompat baseline, preserving it
+                    // would reference a now-deleted type. Honor the baseline and allow the new type.
+                    if (CodeModelGenerator.Instance.SourceInputModel?.ApiCompatBaseline.ReferencesSuppressedType(lastContractPropertyType) == true)
+                    {
+                        CodeModelGenerator.Instance.Emitter.Info(
+                            $"Allowing property '{Name}.{outputProperty.Name}' type change to '{outputProperty.Type}'; previous type '{lastContractPropertyType}' is an accepted removal in the ApiCompat baseline.",
+                            BackCompatibilityChangeCategory.BaselineAcceptedRemovalSkipped);
+                    }
+                    else
+                    {
+                        outputProperty.Type = lastContractPropertyType.ApplyInputSpecProperty(property);
+                        CodeModelGenerator.Instance.Emitter.Info(
+                            $"Changed property '{Name}.{outputProperty.Name}' type to '{lastContractPropertyType}' to match last contract.",
+                            BackCompatibilityChangeCategory.PropertyTypePreserved);
+                    }
                 }
 
                 if (!isDiscriminator)