feat(test): add support for type checking documentation (denoland#10521)

This commit adds support for type checking codeblocks in the JS doc 
comments.

Author: caspervonb

cli/ast.rs

@@ -304,6 +304,22 @@ impl ParsedModule {
     self.leading_comments.clone()
   }
 
+  /// Get the module's comments.
+  pub fn get_comments(&self) -> Vec<Comment> {
+    let mut comments = Vec::new();
+    let (leading_comments, trailing_comments) = self.comments.borrow_all();
+
+    for value in leading_comments.values() {
+      comments.append(&mut value.clone());
+    }
+
+    for value in trailing_comments.values() {
+      comments.append(&mut value.clone());
+    }
+
+    comments
+  }
+
   /// Get a location for a given span within the module.
   pub fn get_location(&self, span: &Span) -> Location {
     self.source_map.lookup_char_pos(span.lo).into()

cli/flags.rs

@@ -96,6 +96,7 @@ pub enum DenoSubcommand {
     script: String,
   },
   Test {
+    doc: bool,
     no_run: bool,
     fail_fast: bool,
     quiet: bool,
@@ -984,6 +985,12 @@ fn test_subcommand<'a, 'b>() -> App<'a, 'b> {
         .help("Cache test modules, but don't run tests")
         .takes_value(false),
     )
+    .arg(
+      Arg::with_name("doc")
+        .long("doc")
+        .help("UNSTABLE: type check code blocks")
+        .takes_value(false),
+    )
     .arg(
       Arg::with_name("fail-fast")
         .long("fail-fast")
@@ -1667,6 +1674,7 @@ fn test_parse(flags: &mut Flags, matches: &clap::ArgMatches) {
   runtime_args_parse(flags, matches, true, true);
 
   let no_run = matches.is_present("no-run");
+  let doc = matches.is_present("doc");
   let fail_fast = matches.is_present("fail-fast");
   let allow_none = matches.is_present("allow-none");
   let quiet = matches.is_present("quiet");
@@ -1711,6 +1719,7 @@ fn test_parse(flags: &mut Flags, matches: &clap::ArgMatches) {
   flags.coverage_dir = matches.value_of("coverage").map(String::from);
   flags.subcommand = DenoSubcommand::Test {
     no_run,
+    doc,
     fail_fast,
     quiet,
     include,
@@ -3357,6 +3366,7 @@ mod tests {
       Flags {
         subcommand: DenoSubcommand::Test {
           no_run: true,
+          doc: false,
           fail_fast: false,
           filter: Some("- foo".to_string()),
           allow_none: true,

cli/main.rs

@@ -914,6 +914,7 @@ async fn test_command(
   flags: Flags,
   include: Option<Vec<String>>,
   no_run: bool,
+  doc: bool,
   fail_fast: bool,
   quiet: bool,
   allow_none: bool,
@@ -924,6 +925,8 @@ async fn test_command(
     env::set_var("DENO_UNSTABLE_COVERAGE_DIR", coverage_dir);
   }
 
+  // TODO(caspervonb) move this chunk into tools::test_runner.
+
   let program_state = ProgramState::build(flags.clone()).await?;
 
   let include = include.unwrap_or_else(|| vec![".".to_string()]);
@@ -944,16 +947,29 @@ async fn test_command(
 
     let paths_to_watch: Vec<_> = include.iter().map(PathBuf::from).collect();
 
+    // TODO(caspervonb) clean this up.
     let resolver = |changed: Option<Vec<PathBuf>>| {
-      let test_modules_result =
-        test_runner::collect_test_module_specifiers(include.clone(), &cwd);
+      let doc_modules_result = test_runner::collect_test_module_specifiers(
+        include.clone(),
+        &cwd,
+        fs_util::is_supported_ext,
+      );
+
+      let test_modules_result = test_runner::collect_test_module_specifiers(
+        include.clone(),
+        &cwd,
+        tools::test_runner::is_supported,
+      );
+
       let paths_to_watch = paths_to_watch.clone();
       let paths_to_watch_clone = paths_to_watch.clone();
 
       let handler = handler.clone();
       let program_state = program_state.clone();
       let files_changed = changed.is_some();
       async move {
+        let doc_modules = if doc { doc_modules_result? } else { Vec::new() };
+
         let test_modules = test_modules_result?;
 
         let mut paths_to_watch = paths_to_watch_clone;
@@ -976,6 +992,12 @@ async fn test_command(
         }
         let graph = builder.get_graph();
 
+        for specifier in doc_modules {
+          if let Ok(path) = specifier.to_file_path() {
+            paths_to_watch.push(path);
+          }
+        }
+
         for specifier in test_modules {
           fn get_dependencies<'a>(
             graph: &'a module_graph::Graph,
@@ -1070,6 +1092,7 @@ async fn test_command(
           program_state.clone(),
           permissions.clone(),
           lib.clone(),
+          modules_to_reload.clone(),
           modules_to_reload,
           no_run,
           fail_fast,
@@ -1084,13 +1107,27 @@ async fn test_command(
     )
     .await?;
   } else {
-    let test_modules =
-      test_runner::collect_test_module_specifiers(include, &cwd)?;
+    let doc_modules = if doc {
+      test_runner::collect_test_module_specifiers(
+        include.clone(),
+        &cwd,
+        fs_util::is_supported_ext,
+      )?
+    } else {
+      Vec::new()
+    };
+
+    let test_modules = test_runner::collect_test_module_specifiers(
+      include.clone(),
+      &cwd,
+      tools::test_runner::is_supported,
+    )?;
 
     let failed = test_runner::run_tests(
       program_state.clone(),
       permissions,
       lib,
+      doc_modules,
       test_modules,
       no_run,
       fail_fast,
@@ -1235,6 +1272,7 @@ fn get_subcommand(
     DenoSubcommand::Run { script } => run_command(flags, script).boxed_local(),
     DenoSubcommand::Test {
       no_run,
+      doc,
       fail_fast,
       quiet,
       include,
@@ -1245,6 +1283,7 @@ fn get_subcommand(
       flags,
       include,
       no_run,
+      doc,
       fail_fast,
       quiet,
       allow_none,

cli/tests/integration_tests.rs

@@ -2580,6 +2580,12 @@ mod integration {
       output: "test/deno_test.out",
     });
 
+    itest!(doc {
+      args: "test --doc --allow-all test/doc.ts",
+      exit_code: 1,
+      output: "test/doc.out",
+    });
+
     itest!(allow_all {
       args: "test --unstable --allow-all test/allow_all.ts",
       exit_code: 0,

cli/tests/test/doc.out

@@ -0,0 +1,5 @@
+Check [WILDCARD]/doc.ts:2-7
+error: TS2367 [ERROR]: This condition will always return 'false' since the types 'string' and 'number' have no overlap.
+console.assert(example() == 42);
+               ~~~~~~~~~~~~~~~
+    at [WILDCARD]/doc.ts:2-7.ts:3:16

cli/tests/test/doc.ts

@@ -0,0 +1,10 @@
+/**
+ * ```
+ * import { example } from "./doc.ts";
+ *
+ * console.assert(example() == 42);
+ * ```
+ */
+export function example(): string {
+  return "example";
+}