Add .clangd config schema and default file associations

[rapgenic]

This PR adds a default file association (as YAML) for clangd related files

• .clangd
• .clang-tidy
• .clang-format

And includes a simple schema for the config file. This, when combined with the YAML extension for VSCode, provides additional simple validation, completion and documentation.

I wrote the schema based on the documentation on the page https://clangd.llvm.org/config.html

[njames93]

While this is very nice, there is a glaring issue with versioning. Newer versions of clangd may support extra fields in the config which would potentially result in warning of unknown keys from vscode. Likewise the compliment is also true of this extension supporting keys from a newer versions of clangd than the one installed, this would result in clangd warning about an unknown key when it parses the file.

Another potential flaw is the plan to give the global config file support for extra global scope keys. Which obviously shouldn't be completed inside a project config option.

[rapgenic]

@njames93 thanks for your thoughts!

Before going on I think that my purpose with this PR is to add a simple, low-cost solution for providing documentation and completion for the config file (which as of now is quite simple as well). This means that it won't be as functional as an ad hoc solution (which probably should be implemented in clangd itself), however it is fairly useful even though it has a few limitation. The main advantage of this method is in my opinion that it is simple and easy to maintain.

I'll briefly answer to your points:

While this is very nice, there is a glaring issue with versioning. Newer versions of clangd may support extra fields in the config which would potentially result in warning of unknown keys from vscode.

The easiest solution would be adding the new properties to the schema as soon they're implemented (it's just about adding ~5 LOC in the schema). If that's not feasible it should be enough to remove the "additionalProperties": false directive, which would allow unknown properties.

Likewise the compliment is also true of this extension supporting keys from a newer versions of clangd than the one installed, this would result in clangd warning about an unknown key when it parses the file.

I do not think that having completion but not support for newer options is a problem: in the end (even right now without the completion) the config file might have been created for use with a new version but actually used with an older version, and it would just show up with a warning that some options are not supported. I agree that having completions for non supported options might not be ideal, but it's enough to update clangd to solve it (or one might want to write the config with newer version support in mind).

Another potential flaw is the plan to give the global config file support for extra global scope keys. Which obviously shouldn't be completed inside a project config option.

Also right, but again, this is deliberately simple, so I imagine that if such options were included in a non global file, a warning (from clangd itself) would appear reminding the user that they will be ignored.

In the end I think that even with the limitations you exposed this still gives a better user experience than just editing a plain file while constantly jumping to the documentation.

[rapgenic]

Also non project configuration is stored in a file with a different name than .clangd, so a different schema could be applied.

[rapgenic]

The YAML extension also has a more advanced API that allows to provide a schema programmatically when opening a file. This would allow to add and remove properties according to which file was opened and clangd version; I can try to implement that, but I am not sure it is worth the effort. More opinions are welcome!

p.s. sorry for the spam, that is the last one ;)

[njames93]

I'm not sure its entirely worth the effort. Down the line we may want to have clangd work as a language server for its own configuration files. This will have the advantage that it would work for any client. All it would need to do is activate on .clangd or tidy/format files. This would result in things like completions/documentation always being in line with the installed clangd version.

[i-ky]

@rapgenic, I would love to see your work as a standalone extension, because clang-tidy and clang-format can be used independently of clangd.

[sam-mccall]

I really like how straightforward and declarative this approach is.
The reliance on another extension means we'll only benefit people who happen to have that installed, I suppose.
But I think the "portable" alternatives like having clangd itself act as a language server for these files bring too much complexity.

The versioning thing could be a bit confusing but still seems much better than not having any assistance at all.

Clangd itself provides diagnostics for validating (if the config is loaded), so hopefully the overlap isn't too confusing.

One of my main concerns is keeping this up to date: we already have several copies of the config schema (one in ConfigFragment.h, a mostly-duplicate in Config.h, one on the website) and this would add one more. This makes maintaining the config format even more of a chore.
The most obvious solution is to generate all these from a single file, and the JSON-schema format maybe isn't a terrible choice...

I'd like to think about this a bit more!

[rapgenic]

The most obvious solution is to generate all these from a single file, and the JSON-schema format maybe isn't a terrible choice...

Another possibility might be to store the schema in a custom format in the LLVM codebase (which might be more useful to generate the c++ structures), and have clangd generate on initialization a JSON schema. The schema could then be sent to the client via the initialization response and then registered on the fly (this would require the use of the API I mentioned earlier, but I have already some working code that could be adapted easily). This would also solve any issue related to versioning, I guess, as the schema is provided directly by the server and will contain only the options known by the server. Downside to this is that we'd lose some of the simplicity of this approach by adding some glue TS code.

The reliance on another extension means we'll only benefit people who happen to have that installed, I suppose.

We might show a popup when opening .clangd, suggesting to install the YAML extension for completion support.

I would love to see your work as a standalone extension

@i-ky I do understand why you'd like that, however I presume you're mostly interested in clang-format and clang-tidy files, for which I have not tried to write a schema yet. Right now I am more focused on the .clangd file (simpler and easier to begin experimenting with), but I suppose that they might be included eventually. However it seems a waste of resources to duplicate the extension, maybe a clangd.disableIntellisense option might be an acceptable alternative?