[api-extractor] feature request: add inferred `in` and `out` to generics in api report

[phryneas]

Summary

It would be great if api-extractor could add in and out information to generics in the api report, as changing a generic from in to out or vice versa can cause breaking changes for consumers.

Details

Quoting from a Twitter thread where I came up with that idea:

We had a type MockedResponse that had a covariant (implicit out) generic argument in the past. That means, MockedResponse<Foo> was assignable to MockedResponse<unknown>, or more important, could be an array member of Array<MockedResponse<unknown>> with unknown being the default. That means, people could write

const mocks: MockedResponse[] = [ ...specificiallyTypedMockedResponses ]

Now, we added a method that referenced that genereric argument in a contravariant position (an input position) to the type. The implicit out switched to an implicit in. As a result, the userspace code above would now error. The thing is: this is semantically correct if the user would ever manually call variableMatcher. But the user doesn't. Our library calls it, and from the perspective of our library, we don't need the contravariance here.

The implicit change from out to in went unnoticed and broke userspace code without introducing any additional safety.

Had we hand-annotated the out from the start, this would not have gone unnoticed - it would have either been an intentional trade-off kinda-breaking change in our types, or we could have avoided shipping it.

I am hoping that at some point, the API reports generated by api-extractor will make in and out visible in their api reports to make breaking api changes like this visible.

The PR to resolve it does some horrible type yoga to make this an out type again, because we know better™️ how it's actually used - but I hope we can get around that in the first place in the future.

Standard questions

This is a feature request so I believe these don't really apply.