feat(lsp): snippet style completion for commands (#15494)

# Description

For example: here's what happens after selecting the `if` command from
the completion menu:

<img width="318" alt="image"
src="https://github.com/user-attachments/assets/752a3bae-ce92-4473-bc96-01032d9295aa"
/>

<img width="319" alt="image"
src="https://github.com/user-attachments/assets/c4bf0c25-ec42-4416-b93e-4925a4650e73"
/>

Missing arguments are inserted as placeholders in a snippet, just as
function name completions in other lsp servers like rust-analyzer and
clangd.

# User-Facing Changes

Press tab to navigate
Flags still need to be added manually

# Tests + Formatting

Refined

# After Submitting

crates/nu-lsp/src/completion.rs

@@ -3,12 +3,13 @@ use std::sync::Arc;
 use crate::{span_to_range, uri_to_path, LanguageServer};
 use lsp_types::{
     CompletionItem, CompletionItemKind, CompletionItemLabelDetails, CompletionParams,
-    CompletionResponse, CompletionTextEdit, Documentation, MarkupContent, MarkupKind, TextEdit,
+    CompletionResponse, CompletionTextEdit, Documentation, InsertTextFormat, MarkupContent,
+    MarkupKind, TextEdit,
 };
 use nu_cli::{NuCompleter, SuggestionKind};
 use nu_protocol::{
     engine::{CommandType, Stack},
-    Span,
+    PositionalArg, Span, SyntaxShape,
 };
 
 impl LanguageServer {
@@ -45,27 +46,71 @@ impl LanguageServer {
             results
                 .into_iter()
                 .map(|r| {
-                    let decl_id = r.kind.clone().and_then(|kind| {
+                    let decl_id = r.kind.as_ref().and_then(|kind| {
                         matches!(kind, SuggestionKind::Command(_))
                             .then_some(engine_state.find_decl(r.suggestion.value.as_bytes(), &[])?)
                     });
 
-                    let mut label_value = r.suggestion.value;
+                    let mut snippet_text = r.suggestion.value.clone();
-                    if r.suggestion.append_whitespace {
+                    let mut doc_string = r.suggestion.extra.map(|ex| ex.join("\n"));
-                        label_value.push(' ');
+                    let mut insert_text_format = None;
+                    let mut idx = 1;
+                    // use snippet as `insert_text_format` for command argument completion
+                    if let Some(decl_id) = decl_id {
+                        let cmd = engine_state.get_decl(decl_id);
+                        doc_string = Some(Self::get_decl_description(cmd, true));
+                        insert_text_format = Some(InsertTextFormat::SNIPPET);
+                        let signature = cmd.signature();
+                        // add curly brackets around block arguments
+                        let block_wrapper = |arg: &PositionalArg, text: String| -> String {
+                            if matches!(arg.shape, SyntaxShape::Block | SyntaxShape::MatchBlock) {
+                                format!("{{ {text} }}")
+                            } else {
+                                text
+                            }
+                        };
+
+                        for required in signature.required_positional {
+                            snippet_text.push(' ');
+                            snippet_text.push_str(
+                                block_wrapper(&required, format!("${{{}:{}}}", idx, required.name))
+                                    .as_str(),
+                            );
+                            idx += 1;
+                        }
+                        for optional in signature.optional_positional {
+                            snippet_text.push(' ');
+                            snippet_text.push_str(
+                                block_wrapper(
+                                    &optional,
+                                    format!("${{{}:{}?}}", idx, optional.name),
+                                )
+                                .as_str(),
+                            );
+                            idx += 1;
+                        }
+                        if let Some(rest) = signature.rest_positional {
+                            snippet_text
+                                .push_str(format!(" ${{{}:...{}}}", idx, rest.name).as_str());
+                            idx += 1;
+                        }
+                    }
+                    // no extra space for a command with args expanded in the snippet
+                    if idx == 1 && r.suggestion.append_whitespace {
+                        snippet_text.push(' ');
                     }
 
                     let span = r.suggestion.span;
                     let text_edit = Some(CompletionTextEdit::Edit(TextEdit {
                         range: span_to_range(&Span::new(span.start, span.end), file, 0),
-                        new_text: label_value.clone(),
+                        new_text: snippet_text,
                     }));
 
                     CompletionItem {
-                        label: label_value,
+                        label: r.suggestion.value,
                         label_details: r
                             .kind
-                            .clone()
+                            .as_ref()
                             .map(|kind| match kind {
                                 SuggestionKind::Value(t) => t.to_string(),
                                 SuggestionKind::Command(cmd) => cmd.to_string(),
@@ -80,14 +125,7 @@ impl LanguageServer {
                                 description: Some(s),
                             }),
                         detail: r.suggestion.description,
-                        documentation: r
+                        documentation: doc_string.map(|value| {
-                            .suggestion
-                            .extra
-                            .map(|ex| ex.join("\n"))
-                            .or(decl_id.map(|decl_id| {
-                                Self::get_decl_description(engine_state.get_decl(decl_id), true)
-                            }))
-                            .map(|value| {
                             Documentation::MarkupContent(MarkupContent {
                                 kind: MarkupKind::Markdown,
                                 value,
@@ -95,6 +133,7 @@ impl LanguageServer {
                         }),
                         kind: Self::lsp_completion_item_kind(r.kind),
                         text_edit,
+                        insert_text_format,
                         ..Default::default()
                     }
                 })
@@ -310,8 +349,9 @@ mod tests {
                     "detail": "Alias a command (with optional flags) to a new name.",
                     "textEdit": {
                         "range": { "start": { "line": 0, "character": 0 }, "end": { "line": 0, "character": 0 }, },
-                        "newText": "alias "
+                        "newText": "alias ${1:name} ${2:initial_value}"
                     },
+                    "insertTextFormat": 2,
                     "kind": 14
                 }
             ])
@@ -327,8 +367,9 @@ mod tests {
                     "detail": "Alias a command (with optional flags) to a new name.",
                     "textEdit": {
                         "range": { "start": { "line": 3, "character": 2 }, "end": { "line": 3, "character": 2 }, },
-                        "newText": "alias "
+                        "newText": "alias ${1:name} ${2:initial_value}"
                     },
+                    "insertTextFormat": 2,
                     "kind": 14
                 }
             ])
@@ -369,8 +410,9 @@ mod tests {
                     "detail": "Trim whitespace or specific character.",
                     "textEdit": {
                         "range": { "start": { "line": 0, "character": 8 }, "end": { "line": 0, "character": 13 }, },
-                        "newText": "str trim "
+                        "newText": "str trim ${1:...rest}"
                     },
+                    "insertTextFormat": 2,
                     "kind": 3
                 }
             ])
@@ -488,7 +530,7 @@ mod tests {
                     "detail": "Alias a command (with optional flags) to a new name.",
                     "textEdit": {
                         "range": { "start": { "line": 0, "character": 5 }, "end": { "line": 0, "character": 5 }, },
-                        "newText": "alias "
+                        "newText": "alias ${1:name} ${2:initial_value}"
                     },
                     "kind": 14
                 },