Declare input and output types of commands (#6796)

* Add failing test that list of ints and floats is List<Number>

* Start defining subtype relation

* Make it possible to declare input and output types for commands

- Enforce them in tests

* Declare input and output types of commands

* Add formatted signatures to `help commands` table

* Revert SyntaxShape::Table -> Type::Table change

* Revert unnecessary derive(Hash) on SyntaxShape

Co-authored-by: JT <547158+jntrnr@users.noreply.github.com>

crates/nu-command/src/math/abs.rs

@@ -1,6 +1,6 @@
 use nu_protocol::ast::Call;
 use nu_protocol::engine::{Command, EngineState, Stack};
-use nu_protocol::{Category, Example, PipelineData, ShellError, Signature, Span, Value};
+use nu_protocol::{Category, Example, PipelineData, ShellError, Signature, Span, Type, Value};
 
 #[derive(Clone)]
 pub struct SubCommand;
@@ -11,11 +11,14 @@ impl Command for SubCommand {
     }
 
     fn signature(&self) -> Signature {
-        Signature::build("math abs").category(Category::Math)
+        Signature::build("math abs")
+            .input_output_types(vec![(Type::Number, Type::Number)])
+            .vectorizes_over_list(true)
+            .category(Category::Math)
     }
 
     fn usage(&self) -> &str {
-        "Returns absolute values of a list of numbers"
+        "Returns the absolute value of a number"
     }
 
     fn search_terms(&self) -> Vec<&str> {
@@ -38,7 +41,7 @@ impl Command for SubCommand {
 
     fn examples(&self) -> Vec<Example> {
         vec![Example {
-            description: "Get absolute of each value in a list of numbers",
+            description: "Compute absolute value of each number in a list of numbers",
             example: "[-50 -100.0 25] | math abs",
             result: Some(Value::List {
                 vals: vec![

crates/nu-command/src/math/avg.rs

@@ -2,7 +2,7 @@ use crate::math::reducers::{reducer_for, Reduce};
 use crate::math::utils::run_with_function;
 use nu_protocol::ast::Call;
 use nu_protocol::engine::{Command, EngineState, Stack};
-use nu_protocol::{Category, Example, PipelineData, ShellError, Signature, Span, Value};
+use nu_protocol::{Category, Example, PipelineData, ShellError, Signature, Span, Type, Value};
 
 #[derive(Clone)]
 pub struct SubCommand;
@@ -13,11 +13,13 @@ impl Command for SubCommand {
     }
 
     fn signature(&self) -> Signature {
-        Signature::build("math avg").category(Category::Math)
+        Signature::build("math avg")
+            .input_output_types(vec![(Type::List(Box::new(Type::Number)), Type::Number)])
+            .category(Category::Math)
     }
 
     fn usage(&self) -> &str {
-        "Finds the average of a list of numbers or tables"
+        "Returns the average of a list of numbers"
     }
 
     fn search_terms(&self) -> Vec<&str> {
@@ -36,7 +38,7 @@ impl Command for SubCommand {
 
     fn examples(&self) -> Vec<Example> {
         vec![Example {
-            description: "Get the average of a list of numbers",
+            description: "Compute the average of a list of numbers",
             example: "[-50 100.0 25] | math avg",
             result: Some(Value::Float {
                 val: 25.0,

crates/nu-command/src/math/ceil.rs

@@ -1,6 +1,6 @@
 use nu_protocol::ast::Call;
 use nu_protocol::engine::{Command, EngineState, Stack};
-use nu_protocol::{Category, Example, PipelineData, ShellError, Signature, Span, Value};
+use nu_protocol::{Category, Example, PipelineData, ShellError, Signature, Span, Type, Value};
 
 #[derive(Clone)]
 pub struct SubCommand;
@@ -11,11 +11,14 @@ impl Command for SubCommand {
     }
 
     fn signature(&self) -> Signature {
-        Signature::build("math ceil").category(Category::Math)
+        Signature::build("math ceil")
+            .input_output_types(vec![(Type::Number, Type::Int)])
+            .vectorizes_over_list(true)
+            .category(Category::Math)
     }
 
     fn usage(&self) -> &str {
-        "Applies the ceil function to a list of numbers"
+        "Returns the ceil of a number (smallest integer greater than or equal to that number)"
     }
 
     fn search_terms(&self) -> Vec<&str> {

crates/nu-command/src/math/eval.rs

@@ -2,7 +2,7 @@ use nu_engine::CallExt;
 use nu_protocol::ast::Call;
 use nu_protocol::engine::{Command, EngineState, Stack};
 use nu_protocol::{
-    Category, Example, PipelineData, ShellError, Signature, Span, Spanned, SyntaxShape, Value,
+    Category, Example, PipelineData, ShellError, Signature, Span, Spanned, SyntaxShape, Type, Value,
 };
 
 #[derive(Clone)]
@@ -23,6 +23,7 @@ impl Command for SubCommand {
 
     fn signature(&self) -> Signature {
         Signature::build("math eval")
+            .input_output_types(vec![(Type::String, Type::Number)])
             .optional(
                 "math expression",
                 SyntaxShape::String,

crates/nu-command/src/math/floor.rs

@@ -1,6 +1,6 @@
 use nu_protocol::ast::Call;
 use nu_protocol::engine::{Command, EngineState, Stack};
-use nu_protocol::{Category, Example, PipelineData, ShellError, Signature, Span, Value};
+use nu_protocol::{Category, Example, PipelineData, ShellError, Signature, Span, Type, Value};
 
 #[derive(Clone)]
 pub struct SubCommand;
@@ -11,11 +11,14 @@ impl Command for SubCommand {
     }
 
     fn signature(&self) -> Signature {
-        Signature::build("math floor").category(Category::Math)
+        Signature::build("math floor")
+            .input_output_types(vec![(Type::Number, Type::Int)])
+            .vectorizes_over_list(true)
+            .category(Category::Math)
     }
 
     fn usage(&self) -> &str {
-        "Applies the floor function to a list of numbers"
+        "Returns the floor of a number (largest integer less than or equal to that number)"
     }
 
     fn search_terms(&self) -> Vec<&str> {

crates/nu-command/src/math/max.rs

@@ -2,7 +2,7 @@ use crate::math::reducers::{reducer_for, Reduce};
 use crate::math::utils::run_with_function;
 use nu_protocol::ast::Call;
 use nu_protocol::engine::{Command, EngineState, Stack};
-use nu_protocol::{Category, Example, PipelineData, ShellError, Signature, Span, Value};
+use nu_protocol::{Category, Example, PipelineData, ShellError, Signature, Span, Type, Value};
 
 #[derive(Clone)]
 pub struct SubCommand;
@@ -13,11 +13,16 @@ impl Command for SubCommand {
     }
 
     fn signature(&self) -> Signature {
-        Signature::build("math max").category(Category::Math)
+        Signature::build("math max")
+            .input_output_types(vec![
+                (Type::List(Box::new(Type::Number)), Type::Number),
+                (Type::Table(vec![]), Type::Record(vec![])),
+            ])
+            .category(Category::Math)
     }
 
     fn usage(&self) -> &str {
-        "Finds the maximum within a list of numbers or tables"
+        "Returns the maximum of a list of numbers, or of columns in a table"
     }
 
     fn search_terms(&self) -> Vec<&str> {
@@ -35,11 +40,22 @@ impl Command for SubCommand {
     }
 
     fn examples(&self) -> Vec<Example> {
-        vec![Example {
-            description: "Find the maximum of list of numbers",
-            example: "[-50 100 25] | math max",
-            result: Some(Value::test_int(100)),
-        }]
+        vec![
+            Example {
+                description: "Find the maximum of list of numbers",
+                example: "[-50 100 25] | math max",
+                result: Some(Value::test_int(100)),
+            },
+            Example {
+                description: "Find the maxima of the columns of a table",
+                example: "[{a: 1 b: 3} {a: 2 b: -1}] | math max",
+                result: Some(Value::Record {
+                    cols: vec!["a".to_string(), "b".to_string()],
+                    vals: vec![Value::test_int(2), Value::test_int(3)],
+                    span: Span::test_data(),
+                }),
+            },
+        ]
     }
 }
 

crates/nu-command/src/math/median.rs

@@ -4,7 +4,7 @@ use crate::math::avg::average;
 use crate::math::utils::run_with_function;
 use nu_protocol::ast::Call;
 use nu_protocol::engine::{Command, EngineState, Stack};
-use nu_protocol::{Category, Example, PipelineData, ShellError, Signature, Span, Value};
+use nu_protocol::{Category, Example, PipelineData, ShellError, Signature, Span, Type, Value};
 
 #[derive(Clone)]
 pub struct SubCommand;
@@ -15,11 +15,16 @@ impl Command for SubCommand {
     }
 
     fn signature(&self) -> Signature {
-        Signature::build("math median").category(Category::Math)
+        Signature::build("math median")
+            .input_output_types(vec![
+                (Type::List(Box::new(Type::Number)), Type::Number),
+                (Type::Table(vec![]), Type::Record(vec![])),
+            ])
+            .category(Category::Math)
     }
 
     fn usage(&self) -> &str {
-        "Gets the median of a list of numbers"
+        "Computes the median of a list of numbers"
     }
 
     fn search_terms(&self) -> Vec<&str> {
@@ -37,14 +42,25 @@ impl Command for SubCommand {
     }
 
     fn examples(&self) -> Vec<Example> {
-        vec![Example {
-            description: "Get the median of a list of numbers",
-            example: "[3 8 9 12 12 15] | math median",
-            result: Some(Value::Float {
-                val: 10.5,
-                span: Span::test_data(),
-            }),
-        }]
+        vec![
+            Example {
+                description: "Compute the median of a list of numbers",
+                example: "[3 8 9 12 12 15] | math median",
+                result: Some(Value::Float {
+                    val: 10.5,
+                    span: Span::test_data(),
+                }),
+            },
+            Example {
+                description: "Compute the medians of the columns of a table",
+                example: "[{a: 1 b: 3} {a: 2 b: -1} {a: -3 b: 5}] | math median",
+                result: Some(Value::Record {
+                    cols: vec!["a".to_string(), "b".to_string()],
+                    vals: vec![Value::test_int(1), Value::test_int(3)],
+                    span: Span::test_data(),
+                }),
+            },
+        ]
     }
 }
 

crates/nu-command/src/math/min.rs

@@ -2,7 +2,7 @@ use crate::math::reducers::{reducer_for, Reduce};
 use crate::math::utils::run_with_function;
 use nu_protocol::ast::Call;
 use nu_protocol::engine::{Command, EngineState, Stack};
-use nu_protocol::{Category, Example, PipelineData, ShellError, Signature, Span, Value};
+use nu_protocol::{Category, Example, PipelineData, ShellError, Signature, Span, Type, Value};
 
 #[derive(Clone)]
 pub struct SubCommand;
@@ -13,7 +13,12 @@ impl Command for SubCommand {
     }
 
     fn signature(&self) -> Signature {
-        Signature::build("math min").category(Category::Math)
+        Signature::build("math min")
+            .input_output_types(vec![
+                (Type::List(Box::new(Type::Number)), Type::Number),
+                (Type::Table(vec![]), Type::Record(vec![])),
+            ])
+            .category(Category::Math)
     }
 
     fn usage(&self) -> &str {
@@ -35,11 +40,22 @@ impl Command for SubCommand {
     }
 
     fn examples(&self) -> Vec<Example> {
-        vec![Example {
-            description: "Get the minimum of a list of numbers",
-            example: "[-50 100 25] | math min",
-            result: Some(Value::test_int(-50)),
-        }]
+        vec![
+            Example {
+                description: "Compute the minimum of a list of numbers",
+                example: "[-50 100 25] | math min",
+                result: Some(Value::test_int(-50)),
+            },
+            Example {
+                description: "Compute the minima of the columns of a table",
+                example: "[{a: 1 b: 3} {a: 2 b: -1}] | math min",
+                result: Some(Value::Record {
+                    cols: vec!["a".to_string(), "b".to_string()],
+                    vals: vec![Value::test_int(1), Value::test_int(-1)],
+                    span: Span::test_data(),
+                }),
+            },
+        ]
     }
 }
 

crates/nu-command/src/math/mode.rs

@@ -1,7 +1,7 @@
 use crate::math::utils::run_with_function;
 use nu_protocol::ast::Call;
 use nu_protocol::engine::{Command, EngineState, Stack};
-use nu_protocol::{Category, Example, PipelineData, ShellError, Signature, Span, Value};
+use nu_protocol::{Category, Example, PipelineData, ShellError, Signature, Span, Type, Value};
 use std::cmp::Ordering;
 
 #[derive(Clone)]
@@ -36,11 +36,19 @@ impl Command for SubCommand {
     }
 
     fn signature(&self) -> Signature {
-        Signature::build("math mode").category(Category::Math)
+        Signature::build("math mode")
+            .input_output_types(vec![
+                (
+                    Type::List(Box::new(Type::Number)),
+                    Type::List(Box::new(Type::Number)),
+                ),
+                (Type::Table(vec![]), Type::Record(vec![])),
+            ])
+            .category(Category::Math)
     }
 
     fn usage(&self) -> &str {
-        "Gets the most frequent element(s) from a list of numbers or tables"
+        "Returns the most frequent element(s) from a list of numbers or tables"
     }
 
     fn search_terms(&self) -> Vec<&str> {
@@ -58,14 +66,34 @@ impl Command for SubCommand {
     }
 
     fn examples(&self) -> Vec<Example> {
-        vec![Example {
-            description: "Get the mode(s) of a list of numbers",
-            example: "[3 3 9 12 12 15] | math mode",
-            result: Some(Value::List {
-                vals: vec![Value::test_int(3), Value::test_int(12)],
-                span: Span::test_data(),
-            }),
-        }]
+        vec![
+            Example {
+                description: "Compute the mode(s) of a list of numbers",
+                example: "[3 3 9 12 12 15] | math mode",
+                result: Some(Value::List {
+                    vals: vec![Value::test_int(3), Value::test_int(12)],
+                    span: Span::test_data(),
+                }),
+            },
+            Example {
+                description: "Compute the mode(s) of the columns of a table",
+                example: "[{a: 1 b: 3} {a: 2 b: -1} {a: 1 b: 5}] | math mode",
+                result: Some(Value::Record {
+                    cols: vec!["a".to_string(), "b".to_string()],
+                    vals: vec![
+                        Value::List {
+                            vals: vec![Value::test_int(1)],
+                            span: Span::test_data(),
+                        },
+                        Value::List {
+                            vals: vec![Value::test_int(-1), Value::test_int(3), Value::test_int(5)],
+                            span: Span::test_data(),
+                        },
+                    ],
+                    span: Span::test_data(),
+                }),
+            },
+        ]
     }
 }
 

crates/nu-command/src/math/product.rs

@@ -2,7 +2,7 @@ use crate::math::reducers::{reducer_for, Reduce};
 use crate::math::utils::run_with_function;
 use nu_protocol::ast::Call;
 use nu_protocol::engine::{Command, EngineState, Stack};
-use nu_protocol::{Category, Example, PipelineData, ShellError, Signature, Span, Value};
+use nu_protocol::{Category, Example, PipelineData, ShellError, Signature, Span, Type, Value};
 
 #[derive(Clone)]
 pub struct SubCommand;
@@ -13,11 +13,13 @@ impl Command for SubCommand {
     }
 
     fn signature(&self) -> Signature {
-        Signature::build("math product").category(Category::Math)
+        Signature::build("math product")
+            .input_output_types(vec![(Type::List(Box::new(Type::Number)), Type::Number)])
+            .category(Category::Math)
     }
 
     fn usage(&self) -> &str {
-        "Finds the product of a list of numbers or tables"
+        "Returns the product of a list of numbers or the products of each column of a table"
     }
 
     fn search_terms(&self) -> Vec<&str> {
@@ -36,7 +38,7 @@ impl Command for SubCommand {
 
     fn examples(&self) -> Vec<Example> {
         vec![Example {
-            description: "Get the product of a list of numbers",
+            description: "Compute the product of a list of numbers",
             example: "[2 3 3 4] | math product",
             result: Some(Value::test_int(72)),
         }]

crates/nu-command/src/math/round.rs

@@ -2,7 +2,7 @@ use nu_engine::CallExt;
 use nu_protocol::ast::Call;
 use nu_protocol::engine::{Command, EngineState, Stack};
 use nu_protocol::{
-    Category, Example, PipelineData, ShellError, Signature, Span, SyntaxShape, Value,
+    Category, Example, PipelineData, ShellError, Signature, Span, SyntaxShape, Type, Value,
 };
 
 #[derive(Clone)]
@@ -15,6 +15,8 @@ impl Command for SubCommand {
 
     fn signature(&self) -> Signature {
         Signature::build("math round")
+            .input_output_types(vec![(Type::Number, Type::Number)])
+            .vectorizes_over_list(true)
             .named(
                 "precision",
                 SyntaxShape::Number,
@@ -25,11 +27,11 @@ impl Command for SubCommand {
     }
 
     fn usage(&self) -> &str {
-        "Applies the round function to a list of numbers"
+        "Returns the input number rounded to the specified precision"
     }
 
     fn search_terms(&self) -> Vec<&str> {
-        vec!["approx", "rough"]
+        vec!["approx", "closest", "nearest"]
     }
 
     fn run(

crates/nu-command/src/math/sqrt.rs

@@ -1,6 +1,6 @@
 use nu_protocol::ast::Call;
 use nu_protocol::engine::{Command, EngineState, Stack};
-use nu_protocol::{Category, Example, PipelineData, ShellError, Signature, Span, Value};
+use nu_protocol::{Category, Example, PipelineData, ShellError, Signature, Span, Type, Value};
 
 #[derive(Clone)]
 pub struct SubCommand;
@@ -11,11 +11,14 @@ impl Command for SubCommand {
     }
 
     fn signature(&self) -> Signature {
-        Signature::build("math sqrt").category(Category::Math)
+        Signature::build("math sqrt")
+            .input_output_types(vec![(Type::Number, Type::Number)])
+            .vectorizes_over_list(true)
+            .category(Category::Math)
     }
 
     fn usage(&self) -> &str {
-        "Applies the square root function to a list of numbers"
+        "Returns the square root of the input number"
     }
 
     fn search_terms(&self) -> Vec<&str> {
@@ -38,7 +41,7 @@ impl Command for SubCommand {
 
     fn examples(&self) -> Vec<Example> {
         vec![Example {
-            description: "Apply the square root function to a list of numbers",
+            description: "Compute the square root of each number in a list",
             example: "[9 16] | math sqrt",
             result: Some(Value::List {
                 vals: vec![Value::test_int(3), Value::test_int(4)],

crates/nu-command/src/math/stddev.rs

@@ -2,7 +2,7 @@ use super::variance::compute_variance as variance;
 use crate::math::utils::run_with_function;
 use nu_protocol::ast::Call;
 use nu_protocol::engine::{Command, EngineState, Stack};
-use nu_protocol::{Category, Example, PipelineData, ShellError, Signature, Span, Value};
+use nu_protocol::{Category, Example, PipelineData, ShellError, Signature, Span, Type, Value};
 
 #[derive(Clone)]
 pub struct SubCommand;
@@ -14,12 +14,17 @@ impl Command for SubCommand {
 
     fn signature(&self) -> Signature {
         Signature::build("math stddev")
-            .switch("sample", "calculate sample standard deviation", Some('s'))
+            .input_output_types(vec![(Type::List(Box::new(Type::Number)), Type::Number)])
+            .switch(
+                "sample",
+                "calculate sample standard deviation (i.e. using N-1 as the denominator)",
+                Some('s'),
+            )
             .category(Category::Math)
     }
 
     fn usage(&self) -> &str {
-        "Finds the stddev of a list of numbers or tables"
+        "Returns the standard deviation of a list of numbers, or of each column in a table"
     }
 
     fn search_terms(&self) -> Vec<&str> {
@@ -47,7 +52,7 @@ impl Command for SubCommand {
     fn examples(&self) -> Vec<Example> {
         vec![
             Example {
-                description: "Get the stddev of a list of numbers",
+                description: "Compute the standard deviation of a list of numbers",
                 example: "[1 2 3 4 5] | math stddev",
                 result: Some(Value::Float {
                     val: std::f64::consts::SQRT_2,
@@ -55,7 +60,7 @@ impl Command for SubCommand {
                 }),
             },
             Example {
-                description: "Get the sample stddev of a list of numbers",
+                description: "Compute the sample standard deviation of a list of numbers",
                 example: "[1 2 3 4 5] | math stddev -s",
                 result: Some(Value::Float {
                     val: 1.5811388300841898,

crates/nu-command/src/math/sum.rs

@@ -2,7 +2,7 @@ use crate::math::reducers::{reducer_for, Reduce};
 use crate::math::utils::run_with_function;
 use nu_protocol::ast::Call;
 use nu_protocol::engine::{Command, EngineState, Stack};
-use nu_protocol::{Category, Example, PipelineData, ShellError, Signature, Span, Value};
+use nu_protocol::{Category, Example, PipelineData, ShellError, Signature, Span, Type, Value};
 
 #[derive(Clone)]
 pub struct SubCommand;
@@ -13,15 +13,17 @@ impl Command for SubCommand {
     }
 
     fn signature(&self) -> Signature {
-        Signature::build("math sum").category(Category::Math)
+        Signature::build("math sum")
+            .input_output_types(vec![(Type::List(Box::new(Type::Number)), Type::Number)])
+            .category(Category::Math)
     }
 
     fn usage(&self) -> &str {
-        "Finds the sum of a list of numbers or tables"
+        "Returns the sum of a list of numbers or of each column in a table"
     }
 
     fn search_terms(&self) -> Vec<&str> {
-        vec!["plus", "add", "+"]
+        vec!["plus", "add", "total", "+"]
     }
 
     fn run(

crates/nu-command/src/math/variance.rs

@@ -1,7 +1,7 @@
 use crate::math::utils::run_with_function;
 use nu_protocol::ast::Call;
 use nu_protocol::engine::{Command, EngineState, Stack};
-use nu_protocol::{Category, Example, PipelineData, ShellError, Signature, Span, Value};
+use nu_protocol::{Category, Example, PipelineData, ShellError, Signature, Span, Type, Value};
 
 #[derive(Clone)]
 pub struct SubCommand;
@@ -13,12 +13,17 @@ impl Command for SubCommand {
 
     fn signature(&self) -> Signature {
         Signature::build("math variance")
-            .switch("sample", "calculate sample variance", Some('s'))
+            .input_output_types(vec![(Type::List(Box::new(Type::Number)), Type::Number)])
+            .switch(
+                "sample",
+                "calculate sample variance (i.e. using N-1 as the denominator)",
+                Some('s'),
+            )
             .category(Category::Math)
     }
 
     fn usage(&self) -> &str {
-        "Finds the variance of a list of numbers or tables"
+        "Returns the variance of a list of numbers or of each column in a table"
     }
 
     fn search_terms(&self) -> Vec<&str> {