feat(versioning): add code fixes for incompatible version errors

[archerzz]

• add code fixes for incompatible version errors
• fix inconsistent error messages
• add unit test cases
• remove redundant codes

resolve #4842

[azure-sdk]

All changed packages have been documented.

• ✅ @typespec/versioning

Show changes

@typespec/versioning - feature ✏️

add code fixes for incompatible version errors

[azure-sdk]

You can try these changes here

🛝 Playground	🌐 Website	📚 Next docs	🛝 VSCode Extension

[archerzz]

A few issues worth mentioning.

Fix Parameter Versions

I cannot insert @added(Version.V3) with a space in the following case:

@added(Versions.v2)
model Foo {}

op test(param: Foo): void;

Ideally, it should be op test(@added(Version.V2) param:Foo): void;. But actually, the fix is:

op test(@added(Version.V2)
param:Foo): void;

The reason is that the type of param is ModelProperty, not FunctionParameter. So, I don't know if the type is a model or a parameter. For models, we should insert a decorator with newline. And for parameters, we should insert a decorator with a space. To maintain maximum compatibility, I choose to insert the decorator with a new line.

Fix by Insertion

In this PR, I only provide fixes to insert @added and @removed. However, if you check those test cases, you'll realize that we could fix by deleting or replacing existing decorators. However, I didn't find an easy and safe way to delete or replace, so I choose to only insert, which in some cases will look stupid thought it still works.

@added(Versions.V3)
@added(Versions.V2) // a better fix is to replace `@added(Versions.V3)`
model Foo {};

@removed(Versions.V2)
@added(Versions.V2) // a better fix is to delete `@removed(Versions.V2)`
model Foo{};

Alternative fixes

Some error cases can have other ways to fix. But that requires more context which is not available in the validation logic, unless we do more changes. For example,

@added(Versions.v3)
model Foo {}
        
model Bar {
  foo: Foo;
}

The error is reported on Bar.foo. We can fix by adding @added(Versions.v2) to Bar.foo. Or we can add the same decorator to Bar. I choose to fix in where the error is reported to minimize the changes.

[witemple-msft]

Looks good to me. I think these codefixes may sometimes not do what the user wants, but will be right enough of the time to be valuable to our users who are using versioning but sometimes miss these added/removed decorators where they're needed.