Command argument introspection

[rwols]

The arguments for a workspace/executeCommand are currently any[].

That makes sense, but this means an editor wanting to present these server commands to an end-user must write manual code. There must be an understanding of the argument types of a particular server.

What I've seen in the wild is that most commands either take no arguments, or some variation/permutation of [$row, $col, $uri, "user-input", some-fixed-number, "more-user-input"].

I propose introspection for the signature of a server command that servers can describe in their ServerCapabilities.

export interface CommandDescriptor {
    /**
     * To be displayed to the end-user, e.g. "Extract Function"
     * A client is allowed to decorate this string further, e.g. present it as "My LSP Client: Extract Function".
     */
    caption: string

    /**
     * The identifier of this command to be sent to the server, e.g. "extract-function"
     */
    name: string

    /**
     * A description of the arguments.
     */
    args: CommandArgumentDescriptor[]
}

export type CommandArgumentDescriptorKind = 'client-derived' | 'constant' | 'input-text' | 'input-list';

export interface CommandArgumentDescriptor {

    kind: CommandArgumentDescriptorKind

    /**
     * If kind == 'client-derived', then 'what' is one of 'line', 'character', 'uri' (maybe add 'position'?)
     * 
     * If kind == 'constant', then 'what' contains the constant string to be put into the argument list.
     * 
     * If kind == 'input-text', then 'what' contains the caption to show to the user when presenting an input field.
     * 
     * If kind == 'input-list', then 'what' is a list of options to choose from, presented to the user.
     */
    what: string | string[]
}

The ExecuteCommandOptions from a server should be modified for this:

export interface ExecuteCommandOptions extends WorkDoneProgressOptions {
    /**
     * The commands to be executed on the server
     */
    commands: string[] | CommandDescriptor[]
}

That is, commands is either a list of strings, or a list of dicts. If it is a list of dicts, then it is understood that the server supports command argument descriptors. They can consequently be parsed by client.