Custom command attributes (#14906)

# Description
Add custom command attributes.

- Attributes are placed before a command definition and start with a `@`
character.
- Attribute invocations consist of const command call. The command's
name must start with "attr ", but this prefix is not used in the
invocation.
- A command named `attr example` is invoked as an attribute as
`@example`
-   Several built-in attribute commands are provided as part of this PR
    -   `attr example`: Attaches an example to the commands help text
        ```nushell
        # Double numbers
        @example "double an int"  { 5 | double }   --result 10
        @example "double a float" { 0.5 | double } --result 1.0
        def double []: [number -> number] {
            $in * 2
        }
        ```
    -   `attr search-terms`: Adds search terms to a command
    -   ~`attr env`: Equivalent to using `def --env`~
- ~`attr wrapped`: Equivalent to using `def --wrapped`~ shelved for
later discussion
    -   several testing related attributes in `std/testing`
- If an attribute has no internal/special purpose, it's stored as
command metadata that can be obtained with `scope commands`.
- This allows having attributes like `@test` which can be used by test
runners.
-   Used the `@example` attribute for `std` examples.
-   Updated the std tests and test runner to use `@test` attributes
-   Added completions for attributes

# User-Facing Changes
Users can add examples to their own command definitions, and add other
arbitrary attributes.

# Tests + Formatting

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

# After Submitting
- Add documentation about the attribute syntax and built-in attributes
- `help attributes`

---------

Co-authored-by: 132ikl <132@ikl.sh>

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

@@ -0,0 +1,97 @@
+use super::{completion_options::NuMatcher, SemanticSuggestion};
+use crate::{
+    completions::{Completer, CompletionOptions},
+    SuggestionKind,
+};
+use nu_protocol::{
+    engine::{Stack, StateWorkingSet},
+    Span,
+};
+use reedline::Suggestion;
+
+pub struct AttributeCompletion;
+pub struct AttributableCompletion;
+
+impl Completer for AttributeCompletion {
+    fn fetch(
+        &mut self,
+        working_set: &StateWorkingSet,
+        _stack: &Stack,
+        _prefix: &[u8],
+        span: Span,
+        offset: usize,
+        _pos: usize,
+        options: &CompletionOptions,
+    ) -> Vec<SemanticSuggestion> {
+        let partial = working_set.get_span_contents(span);
+        let mut matcher = NuMatcher::new(String::from_utf8_lossy(partial), options.clone());
+
+        let attr_commands = working_set.find_commands_by_predicate(
+            |s| {
+                s.strip_prefix(b"attr ")
+                    .map(String::from_utf8_lossy)
+                    .is_some_and(|name| matcher.matches(&name))
+            },
+            true,
+        );
+
+        for (name, desc, ty) in attr_commands {
+            let name = name.strip_prefix(b"attr ").unwrap_or(&name);
+            matcher.add_semantic_suggestion(SemanticSuggestion {
+                suggestion: Suggestion {
+                    value: String::from_utf8_lossy(name).into_owned(),
+                    description: desc,
+                    style: None,
+                    extra: None,
+                    span: reedline::Span {
+                        start: span.start - offset,
+                        end: span.end - offset,
+                    },
+                    append_whitespace: false,
+                },
+                kind: Some(SuggestionKind::Command(ty)),
+            });
+        }
+
+        matcher.results()
+    }
+}
+
+impl Completer for AttributableCompletion {
+    fn fetch(
+        &mut self,
+        working_set: &StateWorkingSet,
+        _stack: &Stack,
+        _prefix: &[u8],
+        span: Span,
+        offset: usize,
+        _pos: usize,
+        options: &CompletionOptions,
+    ) -> Vec<SemanticSuggestion> {
+        let partial = working_set.get_span_contents(span);
+        let mut matcher = NuMatcher::new(String::from_utf8_lossy(partial), options.clone());
+
+        for s in ["def", "extern", "export def", "export extern"] {
+            let decl_id = working_set
+                .find_decl(s.as_bytes())
+                .expect("internal error, builtin declaration not found");
+            let cmd = working_set.get_decl(decl_id);
+            matcher.add_semantic_suggestion(SemanticSuggestion {
+                suggestion: Suggestion {
+                    value: cmd.name().into(),
+                    description: Some(cmd.description().into()),
+                    style: None,
+                    extra: None,
+                    span: reedline::Span {
+                        start: span.start - offset,
+                        end: span.end - offset,
+                    },
+                    append_whitespace: false,
+                },
+                kind: Some(SuggestionKind::Command(cmd.command_type())),
+            });
+        }
+
+        matcher.results()
+    }
+}

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

@@ -1,7 +1,7 @@
 use crate::completions::{
-    CellPathCompletion, CommandCompletion, Completer, CompletionOptions, CustomCompletion,
-    DirectoryCompletion, DotNuCompletion, FileCompletion, FlagCompletion, OperatorCompletion,
-    VariableCompletion,
+    AttributableCompletion, AttributeCompletion, CellPathCompletion, CommandCompletion, Completer,
+    CompletionOptions, CustomCompletion, DirectoryCompletion, DotNuCompletion, FileCompletion,
+    FlagCompletion, OperatorCompletion, VariableCompletion,
 };
 use log::debug;
 use nu_color_config::{color_record_to_nustyle, lookup_ansi_color_style};
@@ -63,6 +63,15 @@ fn find_pipeline_element_by_position<'a>(
             .map(FindMapResult::Found)
             .unwrap_or_default(),
         Expr::Var(_) => FindMapResult::Found(expr),
+        Expr::AttributeBlock(ab) => ab
+            .attributes
+            .iter()
+            .map(|attr| &attr.expr)
+            .chain(Some(ab.item.as_ref()))
+            .find_map(|expr| expr.find_map(working_set, &closure))
+            .or(Some(expr))
+            .map(FindMapResult::Found)
+            .unwrap_or_default(),
         _ => FindMapResult::Continue,
     }
 }
@@ -297,6 +306,29 @@ impl NuCompleter {
                 let index = pos - span.start;
                 let prefix = &current_span[..index];
 
+                if let Expr::AttributeBlock(ab) = &element_expression.expr {
+                    let last_attr = ab.attributes.last().expect("at least one attribute");
+                    if let Expr::Garbage = last_attr.expr.expr {
+                        return self.process_completion(
+                            &mut AttributeCompletion,
+                            &working_set,
+                            prefix,
+                            new_span,
+                            fake_offset,
+                            pos,
+                        );
+                    } else {
+                        return self.process_completion(
+                            &mut AttributableCompletion,
+                            &working_set,
+                            prefix,
+                            new_span,
+                            fake_offset,
+                            pos,
+                        );
+                    }
+                }
+
                 // Flags completion
                 if prefix.starts_with(b"-") {
                     // Try to complete flag internally

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

@@ -1,3 +1,4 @@
+mod attribute_completions;
 mod base;
 mod cell_path_completions;
 mod command_completions;
@@ -12,6 +13,7 @@ mod flag_completions;
 mod operator_completions;
 mod variable_completions;
 
+pub use attribute_completions::{AttributableCompletion, AttributeCompletion};
 pub use base::{Completer, SemanticSuggestion, SuggestionKind};
 pub use cell_path_completions::CellPathCompletion;
 pub use command_completions::CommandCompletion;

crates/nu-cli/src/syntax_highlight.rs

@@ -309,6 +309,7 @@ fn find_matching_block_end_in_expr(
             .unwrap_or(expression.span.start);
 
         return match &expression.expr {
+            // TODO: Can't these be handled with an `_ => None` branch? Refactor
             Expr::Bool(_) => None,
             Expr::Int(_) => None,
             Expr::Float(_) => None,
@@ -335,6 +336,28 @@ fn find_matching_block_end_in_expr(
             Expr::Nothing => None,
             Expr::Garbage => None,
 
+            Expr::AttributeBlock(ab) => ab
+                .attributes
+                .iter()
+                .find_map(|attr| {
+                    find_matching_block_end_in_expr(
+                        line,
+                        working_set,
+                        &attr.expr,
+                        global_span_offset,
+                        global_cursor_offset,
+                    )
+                })
+                .or_else(|| {
+                    find_matching_block_end_in_expr(
+                        line,
+                        working_set,
+                        &ab.item,
+                        global_span_offset,
+                        global_cursor_offset,
+                    )
+                }),
+
             Expr::Table(table) => {
                 if expr_last == global_cursor_offset {
                     // cursor is at table end