Deprecate register and add plugin use (#12607)

# Description

Adds a new keyword, `plugin use`. Unlike `register`, this merely loads
the signatures from the plugin cache file. The file is configurable with
the `--plugin-config` option either to `nu` or to `plugin use` itself,
just like the other `plugin` family of commands. At the REPL, one might
do this to replace `register`:

```nushell
> plugin add ~/.cargo/bin/nu_plugin_foo
> plugin use foo
```

This will not work in a script, because `plugin use` is a keyword and
`plugin add` does not evaluate at parse time (intentionally). This means
we no longer run random binaries during parse.

The `--plugins` option has been added to allow running `nu` with certain
plugins in one step. This is used especially for the `nu_with_plugins!`
test macro, but I'd imagine is generally useful. The only weird quirk is
that it has to be a list, and we don't really do this for any of our
other CLI args at the moment.

`register` now prints a deprecation parse warning.

This should fix #11923, as we now have a complete alternative to
`register`.

# User-Facing Changes

- Add `plugin use` command
- Deprecate `register`
- Add `--plugins` option to `nu` to replace a common use of `register`

# Tests + Formatting

I think I've tested it thoroughly enough and every existing test passes.
Testing nu CLI options and alternate config files is a little hairy and
I wish there were some more generic helpers for this, so this will go on
my TODO list for refactoring.

- 🟢 `toolkit fmt`
- 🟢 `toolkit clippy`
- 🟢 `toolkit test`
- 🟢 `toolkit test stdlib`

# After Submitting

- [ ] Update plugins sections of book
- [ ] Release notes

crates/nu-protocol/src/ast/expression.rs

@@ -108,6 +108,13 @@ impl Expression {
         }
     }
 
+    pub fn as_filepath(&self) -> Option<(String, bool)> {
+        match &self.expr {
+            Expr::Filepath(string, quoted) => Some((string.clone(), *quoted)),
+            _ => None,
+        }
+    }
+
     pub fn as_import_pattern(&self) -> Option<ImportPattern> {
         match &self.expr {
             Expr::ImportPattern(pattern) => Some(*pattern.clone()),

crates/nu-protocol/src/errors/parse_error.rs

@@ -439,6 +439,19 @@ pub enum ParseError {
     #[diagnostic(code(nu::parser::file_not_found))]
     FileNotFound(String, #[label("File not found: {0}")] Span),
 
+    #[error("Plugin not found")]
+    #[diagnostic(
+        code(nu::parser::plugin_not_found),
+        help("plugins need to be added to the plugin cache file before your script is run (see `plugin add`)"),
+    )]
+    PluginNotFound {
+        name: String,
+        #[label("Plugin not found: {name}")]
+        name_span: Span,
+        #[label("in this cache file")]
+        plugin_config_span: Option<Span>,
+    },
+
     #[error("Invalid literal")] // <problem> in <entity>.
     #[diagnostic()]
     InvalidLiteral(String, String, #[label("{0} in {1}")] Span),
@@ -544,6 +557,7 @@ impl ParseError {
             ParseError::SourcedFileNotFound(_, s) => *s,
             ParseError::RegisteredFileNotFound(_, s) => *s,
             ParseError::FileNotFound(_, s) => *s,
+            ParseError::PluginNotFound { name_span, .. } => *name_span,
             ParseError::LabeledError(_, _, s) => *s,
             ParseError::ShellAndAnd(s) => *s,
             ParseError::ShellOrOr(s) => *s,

crates/nu-protocol/src/errors/parse_warning.rs

@@ -5,19 +5,21 @@ use thiserror::Error;
 
 #[derive(Clone, Debug, Error, Diagnostic, Serialize, Deserialize)]
 pub enum ParseWarning {
-    #[error("Deprecated: {0}")]
-    DeprecatedWarning(
-        String,
-        String,
-        #[label = "`{0}` is deprecated and will be removed in 0.90. Please use `{1}` instead, more info: https://www.nushell.sh/book/custom_commands.html"]
-        Span,
-    ),
+    #[error("Deprecated: {old_command}")]
+    #[diagnostic(help("for more info: {url}"))]
+    DeprecatedWarning {
+        old_command: String,
+        new_suggestion: String,
+        #[label("`{old_command}` is deprecated and will be removed in 0.94. Please {new_suggestion} instead")]
+        span: Span,
+        url: String,
+    },
 }
 
 impl ParseWarning {
     pub fn span(&self) -> Span {
         match self {
-            ParseWarning::DeprecatedWarning(_, _, s) => *s,
+            ParseWarning::DeprecatedWarning { span, .. } => *span,
         }
     }
 }

crates/nu-protocol/src/errors/shell_error.rs

@@ -750,17 +750,19 @@ pub enum ShellError {
         span: Span,
     },
 
-    /// The cached plugin data (in `$nu.plugin-path`) for a plugin is invalid.
+    /// The cached plugin data for a plugin is invalid.
     ///
     /// ## Resolution
     ///
-    /// `register` the plugin again to update the data, or remove it.
+    /// `plugin add` the plugin again to update the data, or remove it with `plugin rm`.
     #[error("The cached plugin data for `{plugin_name}` is invalid")]
     #[diagnostic(code(nu::shell::plugin_cache_data_invalid))]
     PluginCacheDataInvalid {
         plugin_name: String,
-        #[help("try registering the plugin again with `{}`")]
-        register_command: String,
+        #[label("plugin `{plugin_name}` loaded here")]
+        span: Option<Span>,
+        #[help("the format in the plugin cache file is not compatible with this version of Nushell.\n\nTry adding the plugin again with `{}`")]
+        add_command: String,
     },
 
     /// A plugin failed to load.

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

@@ -1,11 +1,10 @@
 use std::path::{Path, PathBuf};
 
-use crate::{ParseError, Spanned};
+use crate::{ParseError, ShellError, Spanned};
 
-/// Error when an invalid plugin filename was encountered. This can be converted to [`ParseError`]
-/// if a span is added.
+/// Error when an invalid plugin filename was encountered.
 #[derive(Debug, Clone)]
-pub struct InvalidPluginFilename;
+pub struct InvalidPluginFilename(PathBuf);
 
 impl std::fmt::Display for InvalidPluginFilename {
     fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
@@ -23,6 +22,18 @@ impl From<Spanned<InvalidPluginFilename>> for ParseError {
     }
 }
 
+impl From<Spanned<InvalidPluginFilename>> for ShellError {
+    fn from(error: Spanned<InvalidPluginFilename>) -> ShellError {
+        ShellError::GenericError {
+            error: format!("Invalid plugin filename: {}", error.item.0.display()),
+            msg: "not a valid plugin filename".into(),
+            span: Some(error.span),
+            help: Some("valid Nushell plugin filenames must start with `nu_plugin_`".into()),
+            inner: vec![],
+        }
+    }
+}
+
 #[derive(Debug, Clone, PartialEq, Eq, PartialOrd, Ord, Hash)]
 pub struct PluginIdentity {
     /// The filename used to start the plugin
@@ -35,17 +46,25 @@ pub struct PluginIdentity {
 
 impl PluginIdentity {
     /// Create a new plugin identity from a path to plugin executable and shell option.
+    ///
+    /// The `filename` must be an absolute path. Canonicalize before trying to construct the
+    /// [`PluginIdentity`].
     pub fn new(
         filename: impl Into<PathBuf>,
         shell: Option<PathBuf>,
     ) -> Result<PluginIdentity, InvalidPluginFilename> {
-        let filename = filename.into();
+        let filename: PathBuf = filename.into();
+
+        // Must pass absolute path.
+        if filename.is_relative() {
+            return Err(InvalidPluginFilename(filename));
+        }
 
         let name = filename
             .file_stem()
             .map(|stem| stem.to_string_lossy().into_owned())
             .and_then(|stem| stem.strip_prefix("nu_plugin_").map(|s| s.to_owned()))
-            .ok_or(InvalidPluginFilename)?;
+            .ok_or_else(|| InvalidPluginFilename(filename.clone()))?;
 
         Ok(PluginIdentity {
             filename,
@@ -89,30 +108,42 @@ impl PluginIdentity {
             .expect("fake plugin identity path is invalid")
     }
 
-    /// A command that could be used to register the plugin, for suggesting in errors.
-    pub fn register_command(&self) -> String {
+    /// A command that could be used to add the plugin, for suggesting in errors.
+    pub fn add_command(&self) -> String {
         if let Some(shell) = self.shell() {
             format!(
-                "register --shell '{}' '{}'",
+                "plugin add --shell '{}' '{}'",
                 shell.display(),
                 self.filename().display(),
             )
         } else {
-            format!("register '{}'", self.filename().display())
+            format!("plugin add '{}'", self.filename().display())
         }
     }
+
+    /// A command that could be used to reload the plugin, for suggesting in errors.
+    pub fn use_command(&self) -> String {
+        format!("plugin use '{}'", self.name())
+    }
 }
 
 #[test]
 fn parses_name_from_path() {
     assert_eq!("test", PluginIdentity::new_fake("test").name());
     assert_eq!("test_2", PluginIdentity::new_fake("test_2").name());
+    let absolute_path = if cfg!(windows) {
+        r"C:\path\to\nu_plugin_foo.sh"
+    } else {
+        "/path/to/nu_plugin_foo.sh"
+    };
     assert_eq!(
         "foo",
-        PluginIdentity::new("nu_plugin_foo.sh", Some("sh".into()))
+        PluginIdentity::new(absolute_path, Some("sh".into()))
             .expect("should be valid")
             .name()
     );
+    // Relative paths should be invalid
+    PluginIdentity::new("nu_plugin_foo.sh", Some("sh".into())).expect_err("should be invalid");
     PluginIdentity::new("other", None).expect_err("should be invalid");
     PluginIdentity::new("", None).expect_err("should be invalid");
 }