feat: Client-side on-type formatting support

[SCWells72]

This adds support for configurable client-side on-type formatting that helps to keep the code in LSP-based files properly formatted as certain keys are typed, specifically close brace, statement terminators, and completion triggers.

Here's an example of the behavior without this feature for close brace:

and with this feature for close brace:

Similarly, here's an example of the behavior without this feature for statement terminator:

and with this feature for statement terminator:

Finally, here's an example of the behavior without this feature for completion trigger:

and with this feature for completion trigger:

As you can hopefully see in each case, without this feature, no contextually-aware formatting is applied as the user types, and with this feature, the code is generally kept pretty well-formatted on-the-fly.

Note that this is specifically client-side on-type formatting which is obviously different than the related LSP capability which seems to have very little support, at least in language servers I've tried (specifically TypeScript and CSS).

[SCWells72]

I noticed that isRangeFormattingSupported() was missing from the docs so I added it.

[SCWells72]

And everything below here is for the client config options of this new feature.

[SCWells72]

Part of the config of this feature is the scope to which formatting should be applied when an enabled key has been typed. Because some language servers may not report very good code blocks (CSS doesn't seem to), for example, it may be desirable to enable this feature so that the entire file is formatted properly when certain keys are typed. The default are detailed below for each aspect of the feature.

[SCWells72]

Added the new options to LSPFormattingFeature as well.

[SCWells72]

Encapsulated this so that it can be used externally.

[SCWells72]

Made this more robust so that if a code block text range anchored by a brace pair character does not yield a code block, it will search for a code block as if not anchored.

[SCWells72]

This is just a result of additional encapsulation of how selection ranges are converted into text ranges.

[SCWells72]

Made the brace pairs available externally but as an internal API.

[SCWells72]

Had to make this public so I marked it as @ApiStatus.Internal.

[SCWells72]

This is the actual typedHandler implementation that does the real work.

[SCWells72]

Close brace handling if enabled.

[SCWells72]

Statement terminator handling if enabled.

[SCWells72]

Completion trigger handling if enabled.

[SCWells72]

As stated above, we don't want typing to trigger a language server to start, so we look for a started language server that supports the current file. Is this the best way to ask that question?

We specifically want the started language server that supports the current file, not just whether or not any started language server supports the file.

[SCWells72]

This can be configured for file scope if desired, but if the language server provides enough information for reliable code blocks, it should be configured for code block scope (which is the default, of course).

[SCWells72]

Because we don't have access to an actual AST/PSI tree here, we have to use a bit of a heuristic to find the statement. Language server support for selection ranges is almost always directly bound to the underlying AST, and therefore one of the selection ranges shouuld be for a statement in that language. And that selection range will be for full lines where extension of range start to line start and range end to line end is already performed by LSPSelectionRangeSupport.getSelectionTextRanges(). So the selection range that represents a contiguous range of full lines should in fact be the entire statement. Let me know if that doesn't make sense because it's the foundation upon which statement scope operates.

[SCWells72]

If we found a contiguous range of full lines that (ignoring trailing whitespace) end in the statement terminator character that was just typed, this is the range of the statement to be formatted.

[SCWells72]

Again, it's valid to configure format-on-statement terminator to be for a more broad scope including the surrounding code block or file if that works better (or at all) for the associated language server. The default, of course, is statement scope.

[SCWells72]

For a completion trigger character, we just need to format that single character.

[SCWells72]

Again, this is the result of encapsulation of selection range-to-text range conversion.

[SCWells72]

And this is that encapsulation.

[SCWells72]

This is the same change that was made in #744 to facilitate client configuration-based testing.

[SCWells72]

These are the actual new client config settings for this feature.

[SCWells72]

And we have to add the configurable formatting feature.

[SCWells72]

And we use client config to respond to these questions in the user-defined version of the feature.

[SCWells72]

I'm not sure why this is showing up as so different here, but the only real change is to make it client-configurable. If you hide white space-only changes in the diff, it should be more clear.

[SCWells72]

Register the typedHandler for client-side on-type formatting.

[SCWells72]

JSON schema updates for the new client-side formatting settings and moving onTypeFormatting.enabled to format.onTypeFormatting.serverSide.enabled.

[SCWells72]

These are the new client configuration options for client-side on-type formatting.

[SCWells72]

While updating the on-type formatting docs for this feature, I added details on how to disable server-side on-type formatting if desired.

[SCWells72]

And I documented client-side on-type formatting extensively including the TypeScript server configuration example and a demo.

[SCWells72]

I also wanted to call out the relationship between server-side and client-side on-type formatting if the former is available in the language server and enabled and the latter is also enabled in config.

[angelozerr]

Thanks so much for having taken time to write this doc, it is excellent!

[SCWells72]

I also updated the code block provider documentation to clearly state that code blocks are derived using selection ranges first and then folding ranges if necessary.

[SCWells72]

This looks like it was removed but it's actually still right above the "Code block provider" section.

[SCWells72]

These now reflect the schema from our discussion today, specifically:

{
  "format": {
    "onTypeFormatting": {
      "serverSide": {
        "enabled": false
      },
      "clientSide": {
        "formatOnCloseBrace": true,
        "formatOnStatementTerminator": true,
        "formatOnStatementTerminatorCharacters": ";",
        "formatOnCompletionTrigger": true
      }
    }
  }
}

[SCWells72]

These are all the additions for client-side on-type formatting behavior based on client config.

[SCWells72]

These are just the changes from the client config schema restructuring.

[SCWells72]

Had to update these for the new client config schema.

[SCWells72]

@angelozerr this should now be ready for review again. It takes into account all of the discussions we've had on the topic so far, and it also updates the docs pretty extensively to explain this feature.

It's obviously a longer set of changes, so I'd recommend checking out the branch and playing with it against the TypeScript language server as you're reviewing it. You can also try it against other language servers, but see this comment about the level of support available in other language servers.

Please let me know what you need in order to get this one moving along toward a merge as it does significantly enhance the editor experience for JavaScript/TypeScript at the very least, and it's also the foundation for the last two pending PRs that I have in my queue right now.

[angelozerr]

Please add @nullable to parameters

[SCWells72]

This is one of the things about the plugin SDK that kind of drives me crazy...not all of the methods in EPs are properly annotated for parameter/return value nullability. Here's the definition of that method in the EP interface:

public interface CodeBlockProvider {
  @Nullable
  TextRange getCodeBlockRange(Editor editor, PsiFile psiFile);
}

I generally assume that anything not explicitly annotated as @NotNull is @Nullable, but in this case, looking at other implementations, it looks like it's safe to treat them as @NotNull:

    public @Nullable TextRange getCodeBlockRange(Editor editor, PsiFile psiFile) {
        int at = editor.getCaretModel().getOffset();
        ...
        PsiElement block1 = findBlock(psiFile.findElementAt(at));
    }

So in this instance, I've retained the exact signature of the interface method and added a defensive check just in case.

I can add @Nullable annotations to the parameters, but it would result in a deviation from the EP interface signature. Do you still want me to add them, or does that explain their absence?

[angelozerr]

No no dont add it if sdk doesnt define it. I though it was a miss

[angelozerr]

Please remove this code and uses getLanguageServers with proper filter (ex started status) like you did in an another pr

[SCWells72]

Done. The same commit also ensures that it doesn't even attempt range formatting if not supported by the language server, and I added a Go language unit test to confirm that change since that language server supports file formatting but not range formatting.

[SCWells72]

In each case, we confirm that the configured scope is supported by the language server's formatter before even trying to format. As stated elsewhere, for language server's that don't support range formatting -- or support it pooly, e.g., the CSS language server -- the user can still enable formatting on close brace and/or statement terminator and have it format the entire file if desired.

[SCWells72]

Completion trigger on-type formatting is only range-based.

[SCWells72]

This ensures that the file formatter or range formatter is used as appropriate.

[SCWells72]

Added this Go language server-specific test to verify behavior for a language server that doesn't support range formatting but does support file formatting.

[SCWells72]

Derived test classes can specify that the tested language server doesn't support range formatting if appropriate.

[SCWells72]

Created fresh branch/PR #785 to avoid issues from cumulative merging/rebasing over the past month. This should be considered the authoritative description of and discussion about these changes, but #785 is the vehicle by which they are merged.