Make plugins able to find and call other commands (#13407)

# Description

Adds functionality to the plugin interface to support calling internal
commands from plugins. For example, using `view ir --json`:

```rust
let closure: Value = call.req(0)?;

let Some(decl_id) = engine.find_decl("view ir")? else {
    return Err(LabeledError::new("`view ir` not found"));
};

let ir_json = engine.call_decl(
    decl_id,
    EvaluatedCall::new(call.head)
        .with_named("json".into_spanned(call.head), Value::bool(true, call.head))
        .with_positional(closure),
    PipelineData::Empty,
    true,
    false,
)?.into_value()?.into_string()?;

let ir = serde_json::from_value(&ir_json);

// ...
```

# User-Facing Changes

Plugin developers can now use `EngineInterface::find_decl()` and
`call_decl()` to call internal commands, which could be handy for
formatters like `to csv` or `to nuon`, or for reflection commands that
help gain insight into the engine.

# Tests + Formatting
- 🟢 `toolkit fmt`
- 🟢 `toolkit clippy`
- 🟢 `toolkit test`
- 🟢 `toolkit test stdlib`

# After Submitting
- [ ] release notes
- [ ] update plugin protocol documentation: `FindDecl`, `CallDecl`
engine calls; `Identifier` engine call response

crates/nu-plugin-protocol/src/evaluated_call.rs

@@ -27,6 +27,82 @@ pub struct EvaluatedCall {
 }
 
 impl EvaluatedCall {
+    /// Create a new [`EvaluatedCall`] with the given head span.
+    pub fn new(head: Span) -> EvaluatedCall {
+        EvaluatedCall {
+            head,
+            positional: vec![],
+            named: vec![],
+        }
+    }
+
+    /// Add a positional argument to an [`EvaluatedCall`].
+    ///
+    /// # Example
+    ///
+    /// ```rust
+    /// # use nu_protocol::{Value, Span, IntoSpanned};
+    /// # use nu_plugin_protocol::EvaluatedCall;
+    /// # let head = Span::test_data();
+    /// let mut call = EvaluatedCall::new(head);
+    /// call.add_positional(Value::test_int(1337));
+    /// ```
+    pub fn add_positional(&mut self, value: Value) -> &mut Self {
+        self.positional.push(value);
+        self
+    }
+
+    /// Add a named argument to an [`EvaluatedCall`].
+    ///
+    /// # Example
+    ///
+    /// ```rust
+    /// # use nu_protocol::{Value, Span, IntoSpanned};
+    /// # use nu_plugin_protocol::EvaluatedCall;
+    /// # let head = Span::test_data();
+    /// let mut call = EvaluatedCall::new(head);
+    /// call.add_named("foo".into_spanned(head), Value::test_string("bar"));
+    /// ```
+    pub fn add_named(&mut self, name: Spanned<impl Into<String>>, value: Value) -> &mut Self {
+        self.named.push((name.map(Into::into), Some(value)));
+        self
+    }
+
+    /// Add a flag argument to an [`EvaluatedCall`]. A flag argument is a named argument with no
+    /// value.
+    ///
+    /// # Example
+    ///
+    /// ```rust
+    /// # use nu_protocol::{Value, Span, IntoSpanned};
+    /// # use nu_plugin_protocol::EvaluatedCall;
+    /// # let head = Span::test_data();
+    /// let mut call = EvaluatedCall::new(head);
+    /// call.add_flag("pretty".into_spanned(head));
+    /// ```
+    pub fn add_flag(&mut self, name: Spanned<impl Into<String>>) -> &mut Self {
+        self.named.push((name.map(Into::into), None));
+        self
+    }
+
+    /// Builder variant of [`.add_positional()`].
+    pub fn with_positional(mut self, value: Value) -> Self {
+        self.add_positional(value);
+        self
+    }
+
+    /// Builder variant of [`.add_named()`].
+    pub fn with_named(mut self, name: Spanned<impl Into<String>>, value: Value) -> Self {
+        self.add_named(name, value);
+        self
+    }
+
+    /// Builder variant of [`.add_flag()`].
+    pub fn with_flag(mut self, name: Spanned<impl Into<String>>) -> Self {
+        self.add_flag(name);
+        self
+    }
+
     /// Try to create an [`EvaluatedCall`] from a command `Call`.
     pub fn try_from_call(
         call: &Call,
@@ -192,6 +268,16 @@ impl EvaluatedCall {
         Ok(false)
     }
 
+    /// Returns the [`Span`] of the name of an optional named argument.
+    ///
+    /// This can be used in errors for named arguments that don't take values.
+    pub fn get_flag_span(&self, flag_name: &str) -> Option<Span> {
+        self.named
+            .iter()
+            .find(|(name, _)| name.item == flag_name)
+            .map(|(name, _)| name.span)
+    }
+
     /// Returns the [`Value`] of an optional named argument
     ///
     /// # Examples

crates/nu-plugin-protocol/src/lib.rs

@@ -22,7 +22,7 @@ mod tests;
 pub mod test_util;
 
 use nu_protocol::{
-    ast::Operator, engine::Closure, ByteStreamType, Config, LabeledError, PipelineData,
+    ast::Operator, engine::Closure, ByteStreamType, Config, DeclId, LabeledError, PipelineData,
     PluginMetadata, PluginSignature, ShellError, Span, Spanned, Value,
 };
 use nu_utils::SharedCow;
@@ -494,6 +494,21 @@ pub enum EngineCall<D> {
         /// Whether to redirect stderr from external commands
         redirect_stderr: bool,
     },
+    /// Find a declaration by name
+    FindDecl(String),
+    /// Call a declaration with args
+    CallDecl {
+        /// The id of the declaration to be called (can be found with `FindDecl`)
+        decl_id: DeclId,
+        /// Information about the call (head span, arguments, etc.)
+        call: EvaluatedCall,
+        /// Pipeline input to the call
+        input: D,
+        /// Whether to redirect stdout from external commands
+        redirect_stdout: bool,
+        /// Whether to redirect stderr from external commands
+        redirect_stderr: bool,
+    },
 }
 
 impl<D> EngineCall<D> {
@@ -511,6 +526,8 @@ impl<D> EngineCall<D> {
             EngineCall::LeaveForeground => "LeaveForeground",
             EngineCall::GetSpanContents(_) => "GetSpanContents",
             EngineCall::EvalClosure { .. } => "EvalClosure",
+            EngineCall::FindDecl(_) => "FindDecl",
+            EngineCall::CallDecl { .. } => "CallDecl",
         }
     }
 
@@ -544,6 +561,20 @@ impl<D> EngineCall<D> {
                 redirect_stdout,
                 redirect_stderr,
             },
+            EngineCall::FindDecl(name) => EngineCall::FindDecl(name),
+            EngineCall::CallDecl {
+                decl_id,
+                call,
+                input,
+                redirect_stdout,
+                redirect_stderr,
+            } => EngineCall::CallDecl {
+                decl_id,
+                call,
+                input: f(input)?,
+                redirect_stdout,
+                redirect_stderr,
+            },
         })
     }
 }
@@ -556,6 +587,7 @@ pub enum EngineCallResponse<D> {
     PipelineData(D),
     Config(SharedCow<Config>),
     ValueMap(HashMap<String, Value>),
+    Identifier(usize),
 }
 
 impl<D> EngineCallResponse<D> {
@@ -570,6 +602,7 @@ impl<D> EngineCallResponse<D> {
             EngineCallResponse::PipelineData(data) => EngineCallResponse::PipelineData(f(data)?),
             EngineCallResponse::Config(config) => EngineCallResponse::Config(config),
             EngineCallResponse::ValueMap(map) => EngineCallResponse::ValueMap(map),
+            EngineCallResponse::Identifier(id) => EngineCallResponse::Identifier(id),
         })
     }
 }