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
This PR is part of #22907
---------
Signed-off-by: HasanAlrimawi <141642411+HasanAlrimawi@users.noreply.github.com>
Co-authored-by: Bartek Iwańczuk <biwanczuk@gmail.com>
implement require(esm) using `op_import_sync` from deno_core.
possible future changes:
- cts and mts
- replace Deno.core.evalContext to optimize esm syntax detection
Fixes: https://github.com/denoland/deno/issues/25487
This commit removes all occurrences of `--unstable` flag
from all the tests that are run in CI.
Turns out none of the tests actually required that flag
anymore.
This commit improves error messages for unstable APIs:
- `--unstable-broadcast-channel`
- `--unstable-cron`
- `--unstable-http`
- `--unstable-kv`
- `--unstable-temporal`
By providing information and hints what went wrong and how the
error can be fixed. It reuses the same infra that was added in
https://github.com/denoland/deno/pull/21764.
The long form "files" config has been flattened into the parent.
Old:
```json
{
"test": {
"files": {
"include": ["**/*.ts"],
"exclude": ["ignore.ts"]
}
}
}
```
New:
```json
{
"test": {
"include": ["**/*.ts"],
"exclude": ["ignore.ts"]
}
}
```
This was deprecated some time ago, but we're removing it now in Deno
2.0.
Closes #25415
The map field has been empty for years now and we don't want the emit
file to be exposed so it allows us to iterate on making the cache
faster. Additionally, it's racy/unreliable to rely on this information.
Instead, people should emit the TS files themselves using tools like
deno_emit, typescript, esbuild, etc.
Closes https://github.com/denoland/deno/issues/17703
This commit adds support for executing top-level `.cjs` files,
as well as import `.cjs` files from within npm packages.
This works only for `.cjs` files, the contents of sibling `package.json`
are not consulted for the `"type"` field.
Closes https://github.com/denoland/deno/issues/25384
---------
Signed-off-by: David Sherret <dsherret@users.noreply.github.com>
Co-authored-by: Luca Casonato <hello@lcas.dev>
Co-authored-by: David Sherret <dsherret@users.noreply.github.com>
Running a file like:
```
import "@std/dotenv/load";
```
Without a mapping in `imports` field of `deno.json` or `dependencies` of
`package.json`
will now error out with a hint:
```
error: Relative import path "@std/dotenv/load" not prefixed with / or ./ or ../
hint: Try running `deno add @std/dotenv/load`
at [WILDCARD]bare_specifier_without_import/main.ts:1:8
```
Closes https://github.com/denoland/deno/issues/24699
---------
Co-authored-by: David Sherret <dsherret@users.noreply.github.com>
This allows using npm deps of jsr deps without having to add them to the
root package.json.
Works by taking the package requirement and scanning the
`node_modules/.deno` directory for the best matching package, so it
relies on deno's node_modules structure.
Additionally to make the transition from package.json to deno.json
easier, Deno now:
1. Installs npm deps in a deno.json at the same time as installing npm
deps from a package.json.
2. Uses the alias in the import map for `node_modules/<alias>` for
better package.json compatiblity.
`--allow-run` even with an allow list has essentially been
`--allow-all`... this locks it down more.
1. Resolves allow list for `--allow-run=` on startup to an absolute
path, then uses these paths when evaluating if a command can execute.
Also, adds these paths to `--deny-write`
1. Resolves the environment (cwd and env vars) before evaluating
permissions and before executing a command. Then uses this environment
to evaluate the permissions and then evaluate the command.
This PR serves as a part of #22907 .
---------
Signed-off-by: David Sherret <dsherret@users.noreply.github.com>
Co-authored-by: Bartek Iwańczuk <biwanczuk@gmail.com>
Co-authored-by: David Sherret <dsherret@users.noreply.github.com>
Remove `--allow-hrtime` and `--deny-hrtime`. We are doing this because
it is already possible to get access to high resolution timers through
workers and SharedArrayBuffer.
Co-authored-by: Bartek Iwańczuk <biwanczuk@gmail.com>
