Make requests easier to extend

[st0012]

Motivation

This is part of #808

Currently, to make a listener-based request extensible, we need to:

• Update its constructor to initialise an array of external listeners
• Implement a few interfaces like merge_response! and merge_external_listeners_responses!
• Remember to call merge_external_listeners_responses! in the executor.rb before accessing the response

It's not easy to remember all of them at the same time. And when it's not implemented correctly, we'd rely on runtime information to figure out what's missing.

So with this change, I want to utilise Sorbet as much as possible, while reducing the APIs that need to be implemented.

Implementation

• When extending a listener class, we change its parent class from Listener to the new ExtensibleListener class. Sorbet would then require a few more interfaces on its child class than Listener's.
• To make ExtensibleListener#response merge external responses automatically, I changed Listener's response interface to _response. This will prevent individual listener classes from overriding the response method when declaring its ResponseType.
• I also changed a few utility scripts (e.g. doc check) as ExtensibleListener is Listener's child class but is abstract.

One shortfall of this approach is that if initialize_external_listener uses ivars to initialise external listeners, super needs to be called after the ivars are initialised. And this could not be type-checked. (Ideally we should prepend a module for such order-dependant requirement, but it's not supported by Sorbet)

Automated Tests

All existing tests should pass

Manual Tests

[vinistock]

Nice. This will really help ensuring consistency in extensible requests.

What's the breaking change though?

[vinistock]

Let's leverage Sorbet for this instead. We can just add a signature and we shouldn't need this check.

[st0012]

I've tried it but maybe I was doing something wrong because it's like wrestling with Sorbet with little benefit due to the dynamic class definition:

1. We need to add extend T::Sig to CodeLensExpectationsTest instead of the extension test class.

2. In this case, we need to add override to the signature of create_code_lens_listener. But Sorbet would complain that there's nothing to override about, which I think is also due to dynamic class definition?
   

3. If there's any runtime type checking error, it will be swallowed in RubyLsp::Result instead of being raised

   

So eventually I decided that it's not worth the effort here.

[vinistock]

Oh, right. Yeah, Sorbet doesn't play well with Class.new.

[vinistock]

Oh, right. Yeah, Sorbet doesn't play well with Class.new.