Design for formatting options

[lionel-]

We have two competing goals:

• Consistency of formatting across IDEs. It should not matter whether you are using Positron, vim, or VS Code. The formatter should produce the same output. The main way to ensure this consistency is the air.toml configuration file.

• Consistent of formatting within IDEs. Indentation should be consistent with formatting. IDE-specific settings for formatting (indent style, width, etc) should be taken into account in the absence of an air.toml file.

Configuration of indentation is a complex landscape:

• We want our own air.toml config file
• IDEs have user/global settings (sometimes language-specific)
• There are IDE-specific config files for a project such as Rproj and VS Code workspace settings
• There are cross-IDEs config files such as editorconfig (https://editorconfig.org/)

The CLI is a tool that is independent of IDEs. The only way to configure it is via air.toml. However the LSP also needs to care about IDE settings.

IDE settings

The IDE can communicate settings via:

• Settings watched by the server and communicated by the client via the didChangeConfiguration LSP notification. The indentation configuration can be requested for each document of interest, which allows the client to resolve global/language/project settings. For the purpose of the server, this is just "user configuration".

• The DocumentFormattingOptions passed as argument to formatting requests. In the case of VS Code / Positron, this is the most accurate / up-to-date way of getting formatting settings. Unfortunately, changing the specific indentation settings of an editor (e.g. via the status bar or command palette) doesn't trigger a didChangeConfiguration notification.

  Although this should be the preferred way of ingesting formatting settings, watching the client's configuration is also important because some formatting tasks will not be initiated by a format request but by an assist or other refactoring tasks which might not pass formatting options.

  When we get a formatting request that does have formatting options, we should treat it as a notification and update settings for the document. This way further formatting operations such as described in the previous paragraph will have up-to-date settings if a VS Code / Positron user changed editor settings.

editorconfig and the like

In the LSP we probably don't want to deal with things like editorconfig and instead let IDEs handle these, e.g. via https://marketplace.visualstudio.com/items?itemName=EditorConfig.EditorConfig. We can treat these settings as "IDE settings".

For the CLI it might be nice to handle editorconfig in some way. We could provide a tool to generate an air.toml file from an editorconfig file. This would simplify things internally.

air.toml support in IDEs

Up to now we've discussed how Air should respect IDE settings for formatting in the absence of an air.toml file. But we also need to think about the opposite: how can IDE respect Air settings in the presence of an air.toml file?

IDEs do not always consult the LSP for formatting tasks. For instance, VS Code and Positron have internal rules to do indentation. We can implement format-as-you-type for \n but the LSP response comes noticeably later, causing a noticeable indentation change. So it's still desirable to keep the indentation settings in sync. In general there are other actions for which the LSP is never consulted, such as moving lines up or down.

To achieve intra-IDE consistency for indentation, the IDE should be sensitive to the configuration in air.toml. This is the job of IDE extensions. Should they provide a command to update workspace settings from the air.toml file? Should they detect mismatches and let the user know via notification?

Summary

In general we want to respect this order of precedence in the LSP:

air.toml > IDE settings > Default Air settings

And the CLI is simply:

air.toml > Default Air settings

This way we should be able to keep the complexity of formatting configuration to a manageable level.