feat(cli): evaluate code snippets in JSDoc and markdown (#25220)

This commit lets `deno test --doc` command actually evaluate code snippets in
JSDoc and markdown files.

## How it works

1. Extract code snippets from JSDoc or code fences
2. Convert them into pseudo files by wrapping them in `Deno.test(...)`
3. Register the pseudo files as in-memory files
4. Run type-check and evaluation

We apply some magic at the step 2 - let's say we have the following file named
`mod.ts` as an input:

````ts
/**
 * ```ts
 * import { assertEquals } from "jsr:@std/assert/equals";
 *
 * assertEquals(add(1, 2), 3);
 * ```
 */
export function add(a: number, b: number) {
  return a + b;
}
````

This is virtually transformed into:

```ts
import { assertEquals } from "jsr:@std/assert/equals";
import { add } from "files:///path/to/mod.ts";

Deno.test("mod.ts$2-7.ts", async () => {
  assertEquals(add(1, 2), 3);
});
```

Note that a new import statement is inserted here to make `add` function
available. In a nutshell, all items exported from `mod.ts` become available in
the generated pseudo file with this automatic import insertion.

The intention behind this design is that, from library user's standpoint, it
should be very obvious that this `add` function is what this example code is
attached to. Also, if there is an explicit import statement like
`import { add } from "./mod.ts"`, this import path `./mod.ts` is not helpful for
doc readers because they will need to import it in a different way.

The automatic import insertion has some edge cases, in particular where there is
a local variable in a snippet with the same name as one of the exported items.
This case is addressed by employing swc's scope analysis (see test cases for
more details).

## "type-checking only" mode stays around

This change will likely impact a lot of existing doc tests in the ecosystem
because some doc tests rely on the fact that they are not evaluated - some cause
side effects if executed, some throw errors at runtime although they do pass the
type check, etc. To help those tests gradually transition to the ones runnable
with the new `deno test --doc`, we will keep providing the ability to run
type-checking only via `deno check --doc`. Additionally there is a `--doc-only`
option added to the `check` subcommand too, which is useful when you want to
type-check on code snippets in markdown files, as normal `deno check` command
doesn't accept markdown.

## Demo

https://github.com/user-attachments/assets/47e9af73-d16e-472d-b09e-1853b9e8f5ce

---

Closes #4716

2 files changed, 96 insertions, 10 deletions

diff --git a/tests/integration/check_tests.rs b/tests/integration/check_tests.rs
index 1ccec41eb..121dcb837 100644
--- a/tests/integration/check_tests.rs
+++ b/tests/integration/check_tests.rs
@@ -185,8 +185,8 @@ fn reload_flag() {
 fn typecheck_declarations_ns() {
   let context = TestContextBuilder::for_jsr().build();
   let args = vec![
-    "test".to_string(),
-    "--doc".to_string(),
+    "check".to_string(),
+    "--doc-only".to_string(),
     util::root_path()
       .join("cli/tsc/dts/lib.deno.ns.d.ts")
       .to_string_lossy()
@@ -208,8 +208,8 @@ fn typecheck_declarations_ns() {
 fn typecheck_declarations_unstable() {
   let context = TestContext::default();
   let args = vec![
-    "test".to_string(),
-    "--doc".to_string(),
+    "check".to_string(),
+    "--doc-only".to_string(),
     util::root_path()
       .join("cli/tsc/dts/lib.deno.unstable.d.ts")
       .to_string_lossy()
diff --git a/tests/integration/watcher_tests.rs b/tests/integration/watcher_tests.rs
index 27c59a27d..56686cd14 100644
--- a/tests/integration/watcher_tests.rs
+++ b/tests/integration/watcher_tests.rs
@@ -1022,6 +1022,8 @@ async fn test_watch_doc() {
   let mut child = util::deno_cmd()
     .current_dir(t.path())
     .arg("test")
+    .arg("--config")
+    .arg(util::deno_config_path())
     .arg("--watch")
     .arg("--doc")
     .arg(t.path())
@@ -1039,26 +1041,110 @@ async fn test_watch_doc() {
   wait_contains("Test finished", &mut stderr_lines).await;
 
   let foo_file = t.path().join("foo.ts");
+  let foo_file_url = foo_file.url_file();
   foo_file.write(
     r#"
-    export default function foo() {}
+    export function add(a: number, b: number) {
+      return a + b;
+    }
+  "#,
+  );
+
+  wait_contains("ok | 0 passed | 0 failed", &mut stdout_lines).await;
+  wait_contains("Test finished", &mut stderr_lines).await;
+
+  // Trigger a type error
+  foo_file.write(
+    r#"
+    /**
+     * ```ts
+     * const sum: string = add(1, 2);
+     * ```
+     */
+    export function add(a: number, b: number) {
+      return a + b;
+    }
   "#,
   );
 
+  assert_eq!(
+    skip_restarting_line(&mut stderr_lines).await,
+    format!("Check {foo_file_url}$3-6.ts")
+  );
+  assert_eq!(
+    next_line(&mut stderr_lines).await.unwrap(),
+    "error: TS2322 [ERROR]: Type 'number' is not assignable to type 'string'."
+  );
+  assert_eq!(
+    next_line(&mut stderr_lines).await.unwrap(),
+    "    const sum: string = add(1, 2);"
+  );
+  assert_eq!(next_line(&mut stderr_lines).await.unwrap(), "          ~~~");
+  assert_eq!(
+    next_line(&mut stderr_lines).await.unwrap(),
+    format!("    at {foo_file_url}$3-6.ts:3:11")
+  );
+  wait_contains("Test failed", &mut stderr_lines).await;
+
+  // Trigger a runtime error
   foo_file.write(
     r#"
     /**
      * ```ts
-     * import foo from "./foo.ts";
+     * import { assertEquals } from "@std/assert/equals";
+     *
+     * assertEquals(add(1, 2), 4);
      * ```
      */
-    export default function foo() {}
+    export function add(a: number, b: number) {
+      return a + b;
+    }
   "#,
   );
 
-  // We only need to scan for a Check file://.../foo.ts$3-6 line that
-  // corresponds to the documentation block being type-checked.
-  assert_contains!(skip_restarting_line(&mut stderr_lines).await, "foo.ts$3-6");
+  wait_contains("running 1 test from", &mut stdout_lines).await;
+  assert_contains!(
+    next_line(&mut stdout_lines).await.unwrap(),
+    &format!("{foo_file_url}$3-8.ts ... FAILED")
+  );
+  wait_contains("ERRORS", &mut stdout_lines).await;
+  wait_contains(
+    "error: AssertionError: Values are not equal.",
+    &mut stdout_lines,
+  )
+  .await;
+  wait_contains("-   3", &mut stdout_lines).await;
+  wait_contains("+   4", &mut stdout_lines).await;
+  wait_contains("FAILURES", &mut stdout_lines).await;
+  wait_contains("FAILED | 0 passed | 1 failed", &mut stdout_lines).await;
+
+  wait_contains("Test failed", &mut stderr_lines).await;
+
+  // Fix the runtime error
+  foo_file.write(
+    r#"
+    /**
+     * ```ts
+     * import { assertEquals } from "@std/assert/equals";
+     *
+     * assertEquals(add(1, 2), 3);
+     * ```
+     */
+    export function add(a: number, b: number) {
+      return a + b;
+    }
+  "#,
+  );
+
+  wait_contains("running 1 test from", &mut stdout_lines).await;
+  assert_contains!(
+    next_line(&mut stdout_lines).await.unwrap(),
+    &format!("{foo_file_url}$3-8.ts ... ok")
+  );
+  wait_contains("ok | 1 passed | 0 failed", &mut stdout_lines).await;
+
+  wait_contains("Test finished", &mut stderr_lines).await;
+
   check_alive_then_kill(child);
 }