This commit fixes issues with the pseudo test file generation logic,
namely:
- `export`s declared in snippets
- auto import insertion for `default export`
## Case 1: `export`s declared in snippets
In the previous implementation, `export`s declared in snippets were
moved to the top level of the module in the generated pseudo test file.
This is required because `export` must be at the top level.
This becomes a problem if such a `export` has a body, containing a
reference to a local variable. Suppose we extract this snippet from
JSDoc:
```ts
const logger = createLogger("my-awesome-module");
export function sum(a: number, b: number): number {
logger.debug("sum called");
return a + b;
}
```
This gets converted into the following invalid code (note that `export
function sum` is moved to the top level, but its body references
`logger` variable which can't be referenced from here):
```ts
export function sum(a: number, b: number): number {
logger.debug("sum called");
return a + b;
}
Deno.test("./base.ts$1-7.ts", async () => {
const logger = createLogger("my-awesome-module");
});
```
To resolve this issue, this commit adds a logic to remove the `export`
keyword, allowing the exported items to stay in the `Deno.test` block
scope, like so:
```ts
Deno.test("./base.ts$1-7.ts", async () => {
const logger = createLogger("my-awesome-module");
function sum(a: number, b: number): number {
logger.debug("sum called");
return a + b;
}
});
```
## Case 2: default export
Previously `default export foo` was not captured by the export
collector, so auto import insertion didn't work for this case. To put it
concretely, the following code snippet didn't work when run with `deno
test --doc` because `import foo from "file:///path/to/mod.ts"` didn't
get inserted automatically:
```ts
/**
* ```ts
* console.log(foo);
* ```
*
* @module
*/
const foo = 42;
export default foo;
```
This commit fixes this issue and the above example works fine.
---
Fixes #25718
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
