Command-wide completions (nushell#16765)

- closes nushell#14504
- closes nushell#14806
- partially addresses nushell#5035

---

Added `attr complete external`, which enables using the external
completer for `extern` and custom command `def`initions:

```nushell
@complete external
def --wrapped jc [...args] {
    ^jc ...$args | from json
}
```

Added `attr complete` which uses another command (similar to the `arg:
string@"command"`) to provide completions for _all arguments_ of a
command:

```nushell
def fish-completer [spans: list<string>] {
	^fish ...
}

def carapace-completer [spans: list<string>] {
    ^carapace ...
}

@complete fish-completer
extern git []

@complete carapace-completer
def --env get-env [name] { $env | get $name }

@complete carapace-completer
def --env set-env [name, value] { load-env { $name: $value } }

@complete carapace-completer
def --env unset-env [name] { hide-env $name }
```


Also includes the following bugfix:

- `spans: list<string>` argument provided to the external completer (and
completer commands used with `attr complete` with this addition)
previously had invalid spans (from `Span::unknown`).
These values now have correct spans pointing to their location in the
source code.

Author: Bahex

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

@@ -12,6 +12,7 @@ use reedline::Suggestion;
 
 use super::{SemanticSuggestion, completion_options::NuMatcher};
 
+// TODO: Add a toggle for quoting multi word commands. Useful for: `which` and `attr complete`
 pub struct CommandCompletion {
     /// Whether to include internal commands
     pub internals: bool,

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

@@ -3,11 +3,12 @@ use crate::completions::{
     completer::map_value_completions,
 };
 use nu_engine::eval_call;
+use nu_parser::{FlatShape, flatten_expression};
 use nu_protocol::{
-    DeclId, PipelineData, Span, Type, Value,
+    BlockId, DeclId, IntoSpanned, PipelineData, ShellError, Span, Spanned, Type, Value, VarId,
     ast::{Argument, Call, Expr, Expression},
     debugger::WithoutDebug,
-    engine::{EngineState, Stack, StateWorkingSet},
+    engine::{Closure, EngineState, Stack, StateWorkingSet},
 };
 use std::collections::HashMap;
 
@@ -166,3 +167,170 @@ impl<T: Completer> Completer for CustomCompletion<T> {
         }
     }
 }
+
+pub fn get_command_arguments(
+    working_set: &StateWorkingSet<'_>,
+    element_expression: &Expression,
+) -> Spanned<Vec<Spanned<String>>> {
+    let span = element_expression.span(&working_set);
+    flatten_expression(working_set, element_expression)
+        .iter()
+        .map(|(span, shape)| {
+            let bytes = working_set.get_span_contents(match shape {
+                // Use expanded alias span
+                FlatShape::External(span) => **span,
+                _ => *span,
+            });
+            String::from_utf8_lossy(bytes)
+                .into_owned()
+                .into_spanned(*span)
+        })
+        .collect::<Vec<_>>()
+        .into_spanned(span)
+}
+
+pub struct CommandWideCompletion<'e> {
+    block_id: BlockId,
+    captures: Vec<(VarId, Value)>,
+    expression: &'e Expression,
+    strip: bool,
+    pub need_fallback: bool,
+}
+
+impl<'a> CommandWideCompletion<'a> {
+    pub fn command(
+        working_set: &StateWorkingSet<'_>,
+        decl_id: DeclId,
+        expression: &'a Expression,
+        strip: bool,
+    ) -> Option<Self> {
+        let block_id = (decl_id.get() < working_set.num_decls())
+            .then(|| working_set.get_decl(decl_id))
+            .and_then(|command| command.block_id())?;
+
+        Some(Self {
+            block_id,
+            captures: vec![],
+            expression,
+            strip,
+            need_fallback: false,
+        })
+    }
+
+    pub fn closure(closure: &'a Closure, expression: &'a Expression, strip: bool) -> Self {
+        Self {
+            block_id: closure.block_id,
+            captures: closure.captures.clone(),
+            expression,
+            strip,
+            need_fallback: false,
+        }
+    }
+}
+
+impl<'a> Completer for CommandWideCompletion<'a> {
+    fn fetch(
+        &mut self,
+        working_set: &StateWorkingSet,
+        stack: &Stack,
+        _prefix: impl AsRef<str>,
+        span: Span,
+        offset: usize,
+        _options: &CompletionOptions,
+    ) -> Vec<SemanticSuggestion> {
+        let Spanned {
+            item: mut args,
+            span: args_span,
+        } = get_command_arguments(working_set, self.expression);
+
+        let mut new_span = span;
+        // strip the placeholder
+        if self.strip
+            && let Some(last) = args.last_mut()
+        {
+            last.item.pop();
+            new_span = Span::new(span.start, span.end.saturating_sub(1));
+        }
+
+        let block = working_set.get_block(self.block_id);
+        let mut callee_stack = stack.captures_to_stack_preserve_out_dest(self.captures.clone());
+
+        if let Some(pos_arg) = block.signature.required_positional.first()
+            && let Some(var_id) = pos_arg.var_id
+        {
+            callee_stack.add_var(
+                var_id,
+                Value::list(
+                    args.into_iter()
+                        .map(|Spanned { item, span }| Value::string(item, span))
+                        .collect(),
+                    args_span,
+                ),
+            );
+        }
+        let mut engine_state = working_set.permanent_state.clone();
+        let _ = engine_state.merge_delta(working_set.delta.clone());
+
+        let result = nu_engine::eval_block::<WithoutDebug>(
+            &engine_state,
+            &mut callee_stack,
+            block,
+            PipelineData::empty(),
+        )
+        .map(|p| p.body);
+
+        if let Some(results) = convert_whole_command_completion_results(offset, new_span, result) {
+            results
+        } else {
+            self.need_fallback = true;
+            vec![]
+        }
+    }
+}
+
+/// Converts the output of the external completion closure and whole command custom completion
+/// commands'
+fn convert_whole_command_completion_results(
+    offset: usize,
+    span: Span,
+    result: Result<PipelineData, nu_protocol::ShellError>,
+) -> Option<Vec<SemanticSuggestion>> {
+    let value = match result.and_then(|pipeline_data| pipeline_data.into_value(span)) {
+        Ok(value) => value,
+        Err(err) => {
+            log::error!(
+                "{}",
+                ShellError::GenericError {
+                    error: "nu::shell::completion".into(),
+                    msg: "failed to eval completer block".into(),
+                    span: None,
+                    help: None,
+                    inner: vec![err],
+                }
+            );
+            return Some(vec![]);
+        }
+    };
+
+    match value {
+        Value::List { vals, .. } => Some(map_value_completions(
+            vals.iter(),
+            Span::new(span.start, span.end),
+            offset,
+        )),
+        Value::Nothing { .. } => None,
+        _ => {
+            log::error!(
+                "{}",
+                ShellError::GenericError {
+                    error: "nu::shell::completion".into(),
+                    msg: "completer returned invalid value of type".into(),
+                    span: None,
+                    help: None,
+                    inner: vec![],
+                },
+            );
+            Some(vec![])
+        }
+    }
+}

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

@@ -858,6 +858,98 @@ fn external_completer_invalid() {
     assert!(suggestions.is_empty());
 }
 
+#[test]
+fn command_wide_completion_external() {
+    let mut completer = custom_completer();
+
+    let sample = /* lang=nu */ r#"
+        @complete external
+        extern "gh" []
+
+        gh alias one two"#;
+
+    let suggestions = completer.complete(sample, sample.len());
+    let expected = vec!["gh", "alias", "one", "two"];
+    match_suggestions(&expected, &suggestions);
+}
+
+#[test]
+fn command_wide_completion_custom() {
+    let mut completer = custom_completer();
+
+    let sample = /* lang=nu */ r#"
+        def "nu-complete foo" [spans: list] {
+            $spans ++ [some more]
+        }
+
+        @complete "nu-complete foo"
+        def --wrapped "foo" [...rest] {}
+
+        foo bar baz"#;
+
+    let suggestions = completer.complete(sample, sample.len());
+    let expected = vec!["foo", "bar", "baz", "some", "more"];
+    match_suggestions(&expected, &suggestions);
+}
+
+#[test]
+fn parameter_completion_overrides_command_wide_completion() {
+    let mut completer = custom_completer();
+
+    let sample = /* lang=nu */ r#"
+        def "nu-complete cmd" [spans: list] {
+            [command wide completion]
+        }
+
+        def "nu-complete cmd bar" [] {
+            [bar specific]
+        }
+
+        @complete "nu-complete cmd"
+        def --wrapped "cmd" [
+            foo: string,
+            bar: string@"nu-complete cmd bar",
+            ...rest
+        ] {}
+
+        cmd one "#;
+
+    let suggestions = completer.complete(sample, sample.len());
+    let expected = vec!["bar", "specific"];
+    match_suggestions(&expected, &suggestions);
+}
+
+#[test]
+fn command_wide_completion_flag_completion() {
+    let mut completer = custom_completer();
+
+    let sample = /* lang=nu */ r#"
+        def "nu-complete cmd" [spans: list] {
+            let last = $spans | last
+            [command wide --with --external]
+            | where $it starts-with $last
+        }
+
+        def "nu-complete cmd bar" [] {
+            [bar specific]
+        }
+
+        @complete "nu-complete cmd"
+        def --wrapped "cmd" [
+            --switch(-s)
+            --flag(-f): string
+            foo: string,
+            bar: string@"nu-complete cmd bar",
+            ...rest
+        ] {}
+
+        cmd -"#;
+
+    let suggestions = completer.complete(sample, sample.len());
+    let expected = vec!["--flag", "--switch", "-f", "-s", "--with", "--external"];
+    match_suggestions(&expected, &suggestions);
+}
+
 #[test]
 fn file_completions() {
     // Create a new engine