Plugin: support custom completions in command flags (nushell#16859)

Closes: nushell#15766

It's similar to nushell#16383, but
allows to generate completion dynamically, which can be useful for
plugin commands.

To implement this, I added a new `get_dynamic_completion` method to
`Command` trait, so nushell gets the ability to ask plugins for a
completion. Here is how it goes when I type `plugin-cmd --flag1 <tab>`.
1. the completion logic detect it's behind a flag, and it should have a
value, then it goes to `ArgValueDynamicCompletion`
2. inside `ArgValueDynamicCompletion` it calls
`get_dynamic_completion(ArgType::Flag(flag1))` on the command, which can
be plugin command, and it will issue a
`get_dynamic_completion(ArgType::Flag(flag1))` call to the plugin
3. the plugin returns `Some(Vec<DynamicSemanticSuggestion>)` if there
are available items.

It also supports dynamic completion for positional arguments, here is
how it goes when I type `plugin-cmd x<tab>`.
1. the completion logic detect it's behind a flag, and it should have a
value, then it goes to `ArgValueDynamicCompletion`
2. inside `ArgValueDynamicCompletion` it calls
`get_dynamic_completion(ArgType::Positional(0))` on the command, which
can be plugin command, and it will issue a
`get_dynamic_completion(ArgType::Positional(0))` call to the plugin
3. the plugin returns `Some(Vec<DynamicSemanticSuggestion>)` if there
are available items.

## Release notes summary - What our users need to know

### Plugin developer: auto completion is available for plugin command
arguments.

User can define auto completions for plugin commands, here is the way to
define this:

```rust
impl PluginCommand for FlagCompletion {
    type Plugin = ExamplePlugin;
    ...

    fn get_dynamic_completion(
        &self,
        _plugin: &Self::Plugin,
        _engine: &EngineInterface,
        arg_type: ArgType,
    ) -> Option<Vec<DynamicSemanticSuggestion>> {
        match arg_type {
            // enable completion for flag.
            ArgType::Flag(flag_name) => match flag_name {
                "flag1" => Some(vec!["flag_val1".to_string().into(), "flag_val2".to_string().into()]),
                "flag2" => Some(vec!["flag_val3".to_string().into(), "flag_val4".to_string().into()]),
                // for other flags don't need to provide a completion
                _ => None,
            },
            // enable completion for positional arguments.
            ArgType::Positional(index) => None,
        }
    }
}
```
For the detailed example, you can refer to `get_dynamic_completion` in
`crates/nu_plugin_example/src/commands/arg_completion.rs`.

## Tasks after submitting
- [ ] Update the
[documentation](https://github.com/nushell/nushell.github.io)

Author: WindSoilder

crates/nu-cli/src/completions/arg_value_dynamic_completion.rs

@@ -0,0 +1,58 @@
+use crate::completions::{
+    Completer, CompletionOptions, SemanticSuggestion, completion_options::NuMatcher,
+};
+use nu_protocol::{
+    DeclId, Span,
+    engine::{ArgType, Stack, StateWorkingSet},
+};
+
+pub struct ArgValueDynamicCompletion<'a> {
+    pub decl_id: DeclId,
+    pub arg_type: ArgType<'a>,
+    pub need_fallback: &'a mut bool,
+}
+
+impl<'a> Completer for ArgValueDynamicCompletion<'a> {
+    // TODO: move the logic of `argument_completion_helper` here.
+    fn fetch(
+        &mut self,
+        working_set: &StateWorkingSet,
+        stack: &Stack,
+        prefix: impl AsRef<str>,
+        span: Span,
+        offset: usize,
+        options: &CompletionOptions,
+    ) -> Vec<SemanticSuggestion> {
+        // the `prefix` is the value of a flag
+        // if user input `--foo abc`, then the `prefix` here is abc.
+        // the name of flag is saved in `self.flag_name`.
+        let mut matcher = NuMatcher::new(prefix, options, true);
+
+        let decl = working_set.get_decl(self.decl_id);
+        let mut stack = stack.to_owned();
+        match decl.get_dynamic_completion(working_set.permanent_state, &mut stack, &self.arg_type) {
+            Ok(Some(items)) => {
+                for i in items {
+                    let suggestion = SemanticSuggestion::from_dynamic_suggestion(
+                        i,
+                        reedline::Span {
+                            start: span.start - offset,
+                            end: span.end - offset,
+                        },
+                        None,
+                    );
+                    matcher.add_semantic_suggestion(suggestion);
+                }
+            }
+            Ok(None) => *self.need_fallback = true,
+            Err(e) => {
+                log::error!(
+                    "error on fetching dynamic suggestion on {} with {:?}: {e}",
+                    decl.name(),
+                    self.arg_type
+                );
+            }
+        }
+        matcher.suggestion_results()
+    }
+}

crates/nu-cli/src/completions/attribute_completions.rs

@@ -1,10 +1,7 @@
 use super::{SemanticSuggestion, completion_options::NuMatcher};
-use crate::{
-    SuggestionKind,
-    completions::{Completer, CompletionOptions},
-};
+use crate::completions::{Completer, CompletionOptions};
 use nu_protocol::{
-    Span,
+    Span, SuggestionKind,
     engine::{Stack, StateWorkingSet},
 };
 use reedline::Suggestion;

crates/nu-cli/src/completions/base.rs

@@ -1,6 +1,6 @@
 use crate::completions::CompletionOptions;
 use nu_protocol::{
-    DeclId, Span,
+    DynamicSuggestion, Span, SuggestionKind,
     engine::{Stack, StateWorkingSet},
 };
 use reedline::Suggestion;
@@ -25,18 +25,25 @@ pub struct SemanticSuggestion {
     pub kind: Option<SuggestionKind>,
 }
 
-// TODO: think about name: maybe suggestion context?
-#[derive(Clone, Debug, PartialEq)]
-pub enum SuggestionKind {
-    Command(nu_protocol::engine::CommandType, Option<DeclId>),
-    Value(nu_protocol::Type),
-    CellPath,
-    Directory,
-    File,
-    Flag,
-    Module,
-    Operator,
-    Variable,
+impl SemanticSuggestion {
+    pub fn from_dynamic_suggestion(
+        suggestion: DynamicSuggestion,
+        span: reedline::Span,
+        style: Option<nu_ansi_term::Style>,
+    ) -> Self {
+        SemanticSuggestion {
+            suggestion: Suggestion {
+                value: suggestion.value,
+                description: suggestion.description,
+                extra: suggestion.extra,
+                append_whitespace: suggestion.append_whitespace,
+                match_indices: suggestion.match_indices,
+                style,
+                span,
+            },
+            kind: suggestion.kind,
+        }
+    }
 }
 
 impl From<Suggestion> for SemanticSuggestion {

crates/nu-cli/src/completions/cell_path_completions.rs

@@ -1,9 +1,9 @@
 use std::borrow::Cow;
 
-use crate::completions::{Completer, CompletionOptions, SemanticSuggestion, SuggestionKind};
+use crate::completions::{Completer, CompletionOptions, SemanticSuggestion};
 use nu_engine::{column::get_columns, eval_variable};
 use nu_protocol::{
-    ShellError, Span, Value,
+    ShellError, Span, SuggestionKind, Value,
     ast::{Expr, Expression, FullCellPath, PathMember},
     engine::{Stack, StateWorkingSet},
     eval_const::eval_constant,

crates/nu-cli/src/completions/command_completions.rs

@@ -1,11 +1,8 @@
 use std::collections::HashSet;
 
-use crate::{
-    SuggestionKind,
-    completions::{Completer, CompletionOptions},
-};
+use crate::completions::{Completer, CompletionOptions};
 use nu_protocol::{
-    Category, Span,
+    Category, Span, SuggestionKind,
     engine::{CommandType, Stack, StateWorkingSet},
 };
 use reedline::Suggestion;

crates/nu-cli/src/completions/completer.rs

@@ -1,20 +1,21 @@
 use crate::completions::{
-    AttributableCompletion, AttributeCompletion, CellPathCompletion, CommandCompletion, Completer,
-    CompletionOptions, CustomCompletion, DirectoryCompletion, DotNuCompletion,
-    ExportableCompletion, FileCompletion, FlagCompletion, OperatorCompletion, VariableCompletion,
-    base::{SemanticSuggestion, SuggestionKind},
+    ArgValueDynamicCompletion, AttributableCompletion, AttributeCompletion, CellPathCompletion,
+    CommandCompletion, Completer, CompletionOptions, CustomCompletion, DirectoryCompletion,
+    DotNuCompletion, ExportableCompletion, FileCompletion, FlagCompletion, OperatorCompletion,
+    VariableCompletion, base::SemanticSuggestion,
 };
 use nu_color_config::{color_record_to_nustyle, lookup_ansi_color_style};
 use nu_parser::{parse, parse_module_file_or_dir};
 use nu_protocol::{
-    CommandWideCompleter, Completion, GetSpan, Span, Type, Value,
+    CommandWideCompleter, Completion, GetSpan, Span, SuggestionKind, Type, Value,
     ast::{
         Argument, Block, Expr, Expression, FindMapResult, ListItem, PipelineRedirection,
         RedirectionTarget, Traverse,
     },
-    engine::{EngineState, Stack, StateWorkingSet},
+    engine::{ArgType, EngineState, Stack, StateWorkingSet},
 };
 use reedline::{Completer as ReedlineCompleter, Suggestion};
+use std::borrow::Cow;
 use std::sync::Arc;
 
 use super::{StaticCompletion, custom_completions::CommandWideCompletion};
@@ -571,9 +572,42 @@ impl NuCompleter {
                         0..0,
                         match arg {
                             // flags
-                            Argument::Named(_) | Argument::Unknown(_)
-                                if prefix.starts_with(b"-") =>
-                            {
+                            Argument::Named((name, _, val)) if prefix.starts_with(b"-") => {
+                                match val {
+                                    None => flag_completion_helper(),
+                                    // It's required because it's edge case of lsp completion for
+                                    // flag name itself.
+                                    Some(val) if !val.span.contains(pos) => {
+                                        flag_completion_helper()
+                                    }
+                                    Some(_) => {
+                                        // TODO: add a test to flag value completion in nu-lsp/src/completion.rs
+                                        //
+                                        // Completed flag value.
+                                        // strip from `--foo ..a|` and `--foo=..a|` to `..a`, and also remove the place holder.
+                                        // to make a user friendly completion items.
+                                        let (new_span, prefix) = strip_placeholder_with_rsplit(
+                                            working_set,
+                                            &span,
+                                            |b| *b == b'=' || *b == b' ',
+                                            strip,
+                                        );
+                                        let ctx =
+                                            Context::new(working_set, new_span, prefix, offset);
+                                        let mut flag_value_completion = ArgValueDynamicCompletion {
+                                            decl_id: call.decl_id,
+                                            arg_type: ArgType::Flag(Cow::from(
+                                                name.as_ref().item.as_str(),
+                                            )),
+                                            // flag value doesn't need to fallback, just fill a
+                                            // temp value false.
+                                            need_fallback: &mut false,
+                                        };
+                                        self.process_completion(&mut flag_value_completion, &ctx)
+                                    }
+                                }
+                            }
+                            Argument::Unknown(_) if prefix.starts_with(b"-") => {
                                 flag_completion_helper()
                             }
                             // only when `strip` == false
@@ -582,7 +616,21 @@ impl NuCompleter {
                             Argument::Positional(expr) => {
                                 let command_head = working_set.get_decl(call.decl_id).name();
                                 positional_arg_indices.push(arg_idx);
-                                let mut need_fallback = suggestions.is_empty();
+                                let mut dynamic_completion_need_fallback = false;
+                                let mut positional_value_completion = ArgValueDynamicCompletion {
+                                    decl_id: call.decl_id,
+                                    arg_type: ArgType::Positional(arg_idx),
+                                    need_fallback: &mut dynamic_completion_need_fallback,
+                                };
+
+                                // try argument dynamic completion defined by Command first.
+                                let value_completion_result =
+                                    self.process_completion(&mut positional_value_completion, &ctx);
+                                if !value_completion_result.is_empty() {
+                                    return value_completion_result;
+                                }
+                                let mut need_fallback =
+                                    suggestions.is_empty() && dynamic_completion_need_fallback;
                                 let results = self.argument_completion_helper(
                                     PositionalArguments {
                                         command_head,

crates/nu-cli/src/completions/directory_completions.rs

@@ -3,13 +3,13 @@ use crate::completions::{
     completion_common::{AdjustView, adjust_if_intermediate, complete_item},
 };
 use nu_protocol::{
-    Span,
+    Span, SuggestionKind,
     engine::{EngineState, Stack, StateWorkingSet},
 };
 use reedline::Suggestion;
 use std::path::Path;
 
-use super::{SemanticSuggestion, SuggestionKind, completion_common::FileSuggestion};
+use super::{SemanticSuggestion, completion_common::FileSuggestion};
 
 pub struct DirectoryCompletion;
 

crates/nu-cli/src/completions/dotnu_completions.rs

@@ -1,10 +1,10 @@
 use crate::completions::{
-    Completer, CompletionOptions, SemanticSuggestion, SuggestionKind,
-    completion_common::FileSuggestion, completion_options::NuMatcher,
+    Completer, CompletionOptions, SemanticSuggestion, completion_common::FileSuggestion,
+    completion_options::NuMatcher,
 };
 use nu_path::expand_tilde;
 use nu_protocol::{
-    Span,
+    Span, SuggestionKind,
     engine::{Stack, StateWorkingSet, VirtualPath},
 };
 use reedline::Suggestion;

crates/nu-cli/src/completions/exportable_completions.rs

@@ -1,9 +1,9 @@
 use crate::completions::{
-    Completer, CompletionOptions, SemanticSuggestion, SuggestionKind,
-    completion_common::surround_remove, completion_options::NuMatcher,
+    Completer, CompletionOptions, SemanticSuggestion, completion_common::surround_remove,
+    completion_options::NuMatcher,
 };
 use nu_protocol::{
-    ModuleId, Span,
+    ModuleId, Span, SuggestionKind,
     engine::{Stack, StateWorkingSet},
 };
 use reedline::Suggestion;

crates/nu-cli/src/completions/file_completions.rs

@@ -3,13 +3,13 @@ use crate::completions::{
     completion_common::{AdjustView, adjust_if_intermediate, complete_item},
 };
 use nu_protocol::{
-    Span,
+    Span, SuggestionKind,
     engine::{Stack, StateWorkingSet},
 };
 use reedline::Suggestion;
 use std::path::Path;
 
-use super::{SemanticSuggestion, SuggestionKind};
+use super::SemanticSuggestion;
 
 pub struct FileCompletion;