feat: generalize back compat

[jorgerangel-msft]

Generalize backward-compatibility handling into base TypeProvider

Moves the backward-compatibility algorithms out of individual providers into the base TypeProvider/BackCompatHelper so all providers inherit them automatically.

Generalized into the base:

• Parameter reorder & name restoration
• Hidden overloads for new optional non-body parameters
• Non-abstract-base type preservation
• Public-constructor promotion on abstract bases
• ApiCompat baseline awareness

New:

• Fixed-enum removed-member resurrection (int/long), honoring baseline-accepted removals
• Fixed-enum member value preservation

fixes: #10583

[pkg-pr-new]

Open in StackBlitz

npm i https://pkg.pr.new/@typespec/http-client-csharp@10988

commit: bf51751

[github-actions]

No changes needing a change description found.

[Copilot]

Pull request overview

This PR generalizes and centralizes backward-compatibility behaviors in the C# generator by moving shared algorithms into TypeProvider/BackCompatHelper, extending ApiCompat baseline parsing to cover field/enum-value suppressions, and enhancing enum back-compat to preserve/re-add explicit numeric values from the last contract. It also adds extensive unit tests and expected-output fixtures to validate the new behaviors.

Changes:

• Introduces BackCompatHelper and updates TypeProvider to apply default method/constructor back-compat behaviors (parameter reorder, parameter-name restoration, overloads for new optional parameters, ctor modifier promotion).
• Extends ApiCompatBaseline parsing to recognize field/enum-member suppressions (including EnumValuesMustMatch) and uses these suppressions to skip back-compat resurrection where applicable.
• Updates fixed-enum back-compat to preserve explicit numeric values from the last contract, re-add removed integer members (when not baseline-suppressed), and adds tests/fixtures.

Reviewed changes

Copilot reviewed 47 out of 48 changed files in this pull request and generated 6 comments.

Show a summary per file

File	Description
packages/http-client-csharp/generator/Microsoft.TypeSpec.Generator/test/TestHelpers/TestTypeProvider.cs	Extends test provider to support constructor back-compat scenarios.
packages/http-client-csharp/generator/Microsoft.TypeSpec.Generator/test/SourceInput/TestData/ApiCompatBaselineTests/Baseline.txt	Adds baseline lines for field and enum-value suppressions.
packages/http-client-csharp/generator/Microsoft.TypeSpec.Generator/test/SourceInput/ApiCompatBaselineTests.cs	Adds tests for parsing MembersMustExist fields and EnumValuesMustMatch lines.
packages/http-client-csharp/generator/Microsoft.TypeSpec.Generator/test/Providers/TypeProviderTests.cs	Adds coverage for generalized TypeProvider back-compat behaviors (reorder, defaults, ctor modifiers, abstract preservation, overloads, param-name restoration).
packages/http-client-csharp/generator/Microsoft.TypeSpec.Generator/test/Providers/TestData/TypeProviderTests/FindPreviousParameterNameLooksUpLastContract/TestClient.cs	Last-contract fixture for parameter-name lookup tests.
packages/http-client-csharp/generator/Microsoft.TypeSpec.Generator/test/Providers/TestData/TypeProviderTests/CustomTypeProviderReorderPreservesValueTypeDefaults/CustomReorderValueTypeDefaultsType.cs	Last-contract fixture for default literal preservation during reorder.
packages/http-client-csharp/generator/Microsoft.TypeSpec.Generator/test/Providers/TestData/TypeProviderTests/CustomTypeProviderReorderPreservesValueTypeDefaults.cs	Expected generated output for reorder + literal default preservation.
packages/http-client-csharp/generator/Microsoft.TypeSpec.Generator/test/Providers/TestData/TypeProviderTests/CustomTypeProviderInheritsParameterReorderBackCompat/CustomReorderType.cs	Last-contract fixture validating base reorder behavior for derived providers.
packages/http-client-csharp/generator/Microsoft.TypeSpec.Generator/test/Providers/TestData/TypeProviderTests/CustomTypeProviderInheritsParameterReorderBackCompat.cs	Expected output for reorder-restored signature.
packages/http-client-csharp/generator/Microsoft.TypeSpec.Generator/test/Providers/TestData/TypeProviderTests/BuildMethodsForBackCompatibilitySkipsReorderAcceptedInBaseline/SkipReorderType.cs	Last-contract fixture for baseline-accepted reorder removal.
packages/http-client-csharp/generator/Microsoft.TypeSpec.Generator/test/Providers/TestData/TypeProviderTests/BuildMethodsForBackCompatibilitySkipsReorderAcceptedInBaseline.txt	Baseline fixture suppressing the reorder-related “missing member” report.
packages/http-client-csharp/generator/Microsoft.TypeSpec.Generator/test/Providers/TestData/TypeProviderTests/BuildMethodsForBackCompatibilitySkipsReorderAcceptedInBaseline.cs	Expected output ensuring current (non-restored) order is kept.
packages/http-client-csharp/generator/Microsoft.TypeSpec.Generator/test/Providers/TestData/TypeProviderTests/BuildMethodsForBackCompatibilityRestoresPreviousParameterName/TestClient.cs	Last-contract fixture for parameter name restoration.
packages/http-client-csharp/generator/Microsoft.TypeSpec.Generator/test/Providers/TestData/TypeProviderTests/BuildMethodsForBackCompatibilityRestoresPreviousParameterName.cs	Expected output verifying parameter rename propagation into method body.
packages/http-client-csharp/generator/Microsoft.TypeSpec.Generator/test/Providers/TestData/TypeProviderTests/BuildMethodsForBackCompatibilityRestoredNameDoesNotSplitDeclarations/TestClient.cs	Last-contract fixture for declaration-splitting regression test.
packages/http-client-csharp/generator/Microsoft.TypeSpec.Generator/test/Providers/TestData/TypeProviderTests/BuildMethodsForBackCompatibilityRestoredNameDoesNotSplitDeclarations.cs	Expected output ensuring restored name doesn’t produce multiple declarations.
packages/http-client-csharp/generator/Microsoft.TypeSpec.Generator/test/Providers/TestData/TypeProviderTests/BuildMethodsForBackCompatibilityKeepsUnpublishedParameterName/TestClient.cs	Last-contract fixture for “unpublished param keeps name” behavior.
packages/http-client-csharp/generator/Microsoft.TypeSpec.Generator/test/Providers/TestData/TypeProviderTests/BuildMethodsForBackCompatibilityKeepsUnpublishedParameterName.cs	Expected output verifying no rename when not present in last contract.
packages/http-client-csharp/generator/Microsoft.TypeSpec.Generator/test/Providers/TestData/TypeProviderTests/BuildMethodsForBackCompatibilityAddsOverloadForNewOptionalParameter/NewOptionalParamType.cs	Last-contract fixture for overload generation on new optional params.
packages/http-client-csharp/generator/Microsoft.TypeSpec.Generator/test/Providers/TestData/TypeProviderTests/BuildMethodsForBackCompatibilityAddsOverloadForNewOptionalParameter.cs	Expected output showing hidden overload delegating to current method.
packages/http-client-csharp/generator/Microsoft.TypeSpec.Generator/test/Providers/TestData/TypeProviderTests/BuildDeclarationModifiersPreservesNonAbstractFromLastContract/NonAbstractPreservedType.cs	Last-contract fixture for abstract→non-abstract preservation test.
packages/http-client-csharp/generator/Microsoft.TypeSpec.Generator/test/Providers/TestData/TypeProviderTests/BuildConstructorsForBackCompatibilityPromotesPrivateProtectedToPublic/PromoteCtorType.cs	Last-contract fixture for ctor modifier promotion on abstract base types.
packages/http-client-csharp/generator/Microsoft.TypeSpec.Generator/test/Providers/TestData/TypeProviderTests/BuildConstructorsForBackCompatibilityKeepsModifierOnNonAbstractType/KeepCtorType.cs	Last-contract fixture for negative ctor modifier promotion case.
packages/http-client-csharp/generator/Microsoft.TypeSpec.Generator/test/Providers/EnumProviders/TestData/EnumProviderTests/BackCompat_StringEnumRemovedValueNotReadded/MockInputEnum.cs	Last-contract fixture for string enum removal behavior.
packages/http-client-csharp/generator/Microsoft.TypeSpec.Generator/test/Providers/EnumProviders/TestData/EnumProviderTests/BackCompat_LongEnumRemovedValueReadded/MockInputEnum.cs	Last-contract fixture for long enum value preservation/re-add.
packages/http-client-csharp/generator/Microsoft.TypeSpec.Generator/test/Providers/EnumProviders/TestData/EnumProviderTests/BackCompat_LastContractExposesEnumMemberValues/MockInputEnum.cs	Last-contract fixture verifying explicit enum values are observable via Roslyn.
packages/http-client-csharp/generator/Microsoft.TypeSpec.Generator/test/Providers/EnumProviders/TestData/EnumProviderTests/BackCompat_IntEnumRemovedValueReadded/MockInputEnum.cs	Last-contract fixture for int enum member re-add behavior.
packages/http-client-csharp/generator/Microsoft.TypeSpec.Generator/test/Providers/EnumProviders/TestData/EnumProviderTests/BackCompat_IntEnumRemovedValueNotReaddedWhenBaselineAccepts/MockInputEnum.cs	Last-contract fixture for baseline-accepted removal of enum value.
packages/http-client-csharp/generator/Microsoft.TypeSpec.Generator/test/Providers/EnumProviders/TestData/EnumProviderTests/BackCompat_IntEnumRemovedValueNotReaddedWhenBaselineAccepts.txt	Baseline fixture suppressing enum-value mismatch to honor removal.
packages/http-client-csharp/generator/Microsoft.TypeSpec.Generator/test/Providers/EnumProviders/TestData/EnumProviderTests/BackCompat_IntEnumRemovedMiddleValueReadded/MockInputEnum.cs	Last-contract fixture for “removed middle member” re-add behavior.
packages/http-client-csharp/generator/Microsoft.TypeSpec.Generator/test/Providers/EnumProviders/TestData/EnumProviderTests/BackCompat_IntEnumNonContiguousValuesPreserved/MockInputEnum.cs	Last-contract fixture for non-contiguous explicit int values preservation.
packages/http-client-csharp/generator/Microsoft.TypeSpec.Generator/test/Providers/EnumProviders/EnumProviderTests.cs	Updates/extends enum back-compat tests for explicit values, removals, and baseline suppression.
packages/http-client-csharp/generator/Microsoft.TypeSpec.Generator/src/Utilities/BackCompatHelper.cs	New shared back-compat helper for methods/parameters/overloads and baseline checks.
packages/http-client-csharp/generator/Microsoft.TypeSpec.Generator/src/SourceInput/ApiCompatBaseline.cs	Adds parsing for field/enum-member suppressions and EnumValuesMustMatch.
packages/http-client-csharp/generator/Microsoft.TypeSpec.Generator/src/Providers/TypeProvider.cs	Adds generalized default back-compat behaviors for methods/constructors and preserves non-abstract types.
packages/http-client-csharp/generator/Microsoft.TypeSpec.Generator/src/Providers/ModelProvider.cs	Removes model-specific abstract/ctor back-compat logic now covered by base TypeProvider.
packages/http-client-csharp/generator/Microsoft.TypeSpec.Generator/src/Providers/ModelFactoryProvider.cs	Switches to shared baseline check + shared parameter-name restoration helper.
packages/http-client-csharp/generator/Microsoft.TypeSpec.Generator/src/Providers/FixedEnumProvider.cs	Preserves explicit numeric values from last contract; re-adds removed integer enum members unless baseline-suppressed; refactors “append new members” helper.
packages/http-client-csharp/generator/Microsoft.TypeSpec.Generator/src/Providers/ApiVersionEnumProvider.cs	Reuses shared “append new members not in last contract” helper.
packages/http-client-csharp/generator/Microsoft.TypeSpec.Generator/src/Primitives/CodeWriterDeclaration.cs	Makes requested name mutable to support in-place renames.
packages/http-client-csharp/generator/Microsoft.TypeSpec.Generator/src/Expressions/VariableExpression.cs	Updates renames to mutate declaration in-place instead of replacing it.
packages/http-client-csharp/generator/Microsoft.TypeSpec.Generator/src/EmitterRpc/Emitter.cs	Adds log display label for enum-member re-add category.
packages/http-client-csharp/generator/Microsoft.TypeSpec.Generator/src/EmitterRpc/BackCompatibilityChangeCategory.cs	Adds enum-member re-add change category.
packages/http-client-csharp/generator/Microsoft.TypeSpec.Generator.ClientModel/src/Providers/MultipartFormDataSerializationDefinition.cs	Opts out of generalized method back-compat for serialization definition types.
packages/http-client-csharp/generator/Microsoft.TypeSpec.Generator.ClientModel/src/Providers/MrwSerializationTypeDefinition.cs	Opts out of generalized method back-compat for MRW serialization types.
packages/http-client-csharp/generator/Microsoft.TypeSpec.Generator.ClientModel/src/Providers/ExtensibleEnumSerializationProvider.cs	Opts out of generalized method back-compat for extensible enum serialization provider.
packages/http-client-csharp/generator/Microsoft.TypeSpec.Generator.ClientModel/src/Providers/ClientProvider.cs	Refactors to call base generalized method back-compat, then patches convenience-method invocations + applies AZC0002 suppression for new overloads.
packages/http-client-csharp/generator/docs/backward-compatibility-extensibility.md	Adds documentation describing intended back-compat extensibility model and pipeline.