Adds a nickel test subcommand for testing examples in docs. (#2020)

* Doctests

* Add a custom_transform method

* Make the vm private again

* Update doc

* Add some snapshot tests

* Split out closurized and non-closurized variants of eval_record_spine

* Fix doc link

* Add some docs, but not sure where they should go

* Make report_as_str honor the color setting

* Separate the stdout and stderr outputs more intentionally

* Commit the other snapshots

cli/Cargo.toml

@@ -18,7 +18,7 @@ bench = false
 [features]
 default = ["repl", "doc", "format", "spanned-deser"]
 repl = ["nickel-lang-core/repl"]
-doc = ["nickel-lang-core/doc"]
+doc = ["nickel-lang-core/doc", "comrak"]
 format = ["nickel-lang-core/format", "dep:tempfile"]
 spanned-deser = ["nickel-lang-core/spanned-deser"]
 metrics = ["dep:metrics", "dep:metrics-util", "nickel-lang-core/metrics"]
@@ -39,6 +39,10 @@ clap_complete = { workspace = true }
 metrics = { workspace = true, optional = true }
 metrics-util = { workspace = true, optional = true }
 
+comrak = { workspace = true, optional = true }
+once_cell.workspace = true
+regex.workspace = true
+
 [dev-dependencies]
 nickel-lang-utils.workspace = true
 test-generator.workspace = true

cli/src/cli.rs

@@ -13,7 +13,7 @@ use nickel_lang_core::error::report::ErrorFormat;
 use crate::repl::ReplCommand;
 
 #[cfg(feature = "doc")]
-use crate::doc::DocCommand;
+use crate::{doc::DocCommand, doctest::TestCommand};
 
 #[cfg(feature = "format")]
 use crate::format::FormatCommand;
@@ -63,7 +63,7 @@ pub struct GlobalOptions {
 /// Available subcommands.
 #[derive(clap::Subcommand, Debug)]
 pub enum Command {
-    /// Evaluate a Nickel program and pretty-print the result.
+    /// Evaluates a Nickel program and pretty-prints the result.
     Eval(EvalCommand),
     /// Converts the parsed representation (AST) back to Nickel source code and
     /// prints it. Used for debugging purpose
@@ -72,14 +72,17 @@ pub enum Command {
     Export(ExportCommand),
     /// Prints the metadata attached to an attribute, given as a path
     Query(QueryCommand),
-    /// Typechecks the program but do not run it
+    /// Typechecks the program but does not run it
     Typecheck(TypecheckCommand),
     /// Starts a REPL session
     #[cfg(feature = "repl")]
     Repl(ReplCommand),
     /// Generates the documentation files for the specified nickel file
     #[cfg(feature = "doc")]
     Doc(DocCommand),
+    /// Tests the documentation examples in the specified nickel file
+    #[cfg(feature = "doc")]
+    Test(TestCommand),
     /// Format Nickel files
     #[cfg(feature = "format")]
     Format(FormatCommand),