Copilot instructions

1# Deno Development Guide for GitHub Copilot
2 
3## Network Access
4 
5The development tools in this repository need network access to function. When
6running `tools/format.js` or `tools/lint.js`, ensure the following domains are
7reachable:
8 
9- `https://jsr.io` — Deno's package registry, used for `@std/*` imports
10- `https://dprint.dev` and `https://plugins.dprint.dev` — the formatter
11  (`tools/format.js`) runs `npm:dprint` which downloads WASM plugins from
12  `plugins.dprint.dev`
13 
14If you are running in a sandboxed environment, you must allowlist these domains
15or the tools will fail with network errors.
16 
17## High Level Overview
18 
19The user-visible interface and high-level integration is in the `deno` crate
20(located in `./cli`).
21 
22This includes flag parsing, subcommands, package management tooling, etc. Flag
23parsing is in `cli/args/flags.rs`. Tools are in `cli/tools/<tool>`.
24 
25The `deno_runtime` crate (`./runtime`) assembles the JavaScript runtime,
26including all of the "extensions" (native functionality exposed to JavaScript).
27The extensions themselves are in the `ext/` directory, and provide system access
28to JavaScript — for instance filesystem operations and networking.
29 
30### Key Directories
31 
32- `cli/` — User-facing CLI implementation, subcommands, and tools
33- `runtime/` — JavaScript runtime assembly and integration
34- `ext/` — Extensions providing native functionality to JS (fs, net, etc.)
35- `libs/` — Shared Rust crates (core, resolver, npm, node_resolver, serde_v8,
36  etc.)
37- `tests/specs/` — Integration tests (spec tests)
38- `tests/unit/` — Unit tests
39- `tests/testdata/` — Test fixtures and data files
40 
41### Key Files to Understand First
42 
431. `cli/main.rs` — Entry point, command routing
442. `cli/args/flags.rs` — CLI flag parsing and structure
453. `runtime/worker.rs` — Worker/runtime initialization
464. `runtime/permissions.rs` — Permission system
475. `cli/module_loader.rs` — Module loading and resolution
48 
49### Common Patterns
50 
51- **Ops** — Rust functions exposed to JavaScript (in `ext/` directories)
52- **Extensions** — Collections of ops and JS code providing functionality
53- **Workers** — JavaScript execution contexts (main worker, web workers)
54- **Resources** — Managed objects passed between Rust and JS (files, sockets,
55  etc.)
56 
57## Building
58 
59```bash
60# Check for compilation errors (fast, no binary output)
61cargo check
62 
63# Build debug binary
64cargo build --bin deno
65 
66# Build release version (slow, optimized)
67cargo build --release
68 
69# Run the dev build
70./target/debug/deno eval 'console.log("Hello from dev build")'
71```
72 
73## Code Quality
74 
75Before committing, always run the formatter and linter:
76 
77```bash
78# Format all code (uses dprint under the hood)
79./tools/format.js
80 
81# Lint all code (JS + Rust via clippy)
82./tools/lint.js
83 
84# Lint only JS/TS (faster, skips clippy)
85./tools/lint.js --js
86 
87# Lint only Rust
88./tools/lint.js --rs
89```
90 
91The formatter (`tools/format.js`) runs `dprint` via `npm:dprint@0.47.2`. It
92formats TypeScript, JavaScript, JSON, Markdown, YAML, and Rust (via `rustfmt`).
93Configuration is in `.dprint.json`.
94 
95The linter (`tools/lint.js`) runs `deno lint` for JS/TS and `cargo clippy` for
96Rust.
97 
98## Testing
99 
100```bash
101# Run all tests
102cargo test
103 
104# Filter tests by name
105cargo test &lt;nameOfTest&gt;
106 
107# Run tests in a specific package
108cargo test -p deno_core
109 
110# Run just the CLI integration tests
111cargo test --bin deno
112 
113# Run spec tests only
114cargo test specs
115 
116# Run a specific spec test
117cargo test spec::test_name
118```
119 
120### Test Organization
121 
122- **Spec tests** (`tests/specs/`) — Main integration tests
123- **Unit tests** — Inline with source code in each module
124- **Integration tests** (`tests/integration/`) — Additional integration tests
125- **WPT** (`tests/wpt/`) — Web Platform Tests for web standards compliance
126 
127### Spec Tests
128 
129The main form of integration test is the "spec" test in `tests/specs/`. Each
130test has a `__test__.jsonc` file describing CLI commands to run and expected
131output. The schema is in `tests/specs/schema.json`.
132 
133Example `__test__.jsonc`:
134 
135```jsonc
136{
137  "tests": {
138    "basic_case": {
139      "args": "run main.ts",
140      "output": "expected.out"
141    }
142  }
143}
144```
145 
146Output assertions support wildcards:
147 
148- `[WILDCARD]` — matches 0 or more characters (crosses newlines)
149- `[WILDLINE]` — matches to end of line
150- `[WILDCHAR]` — matches one character
151- `[WILDCHARS(N)]` — matches N characters
152- `[UNORDERED_START]` / `[UNORDERED_END]` — matches lines in any order
153 
154## Git Workflow and Pull Requests
155 
156### PR Title Linting
157 
158PR titles are validated by CI (see `.github/workflows/pr.ts`). The title must
159follow [Conventional Commits](https://www.conventionalcommits.org) and start
160with one of these prefixes:
161 
162- `feat:` — new features
163- `fix:` — bug fixes
164- `chore:` — maintenance tasks
165- `perf:` — performance improvements
166- `ci:` — CI changes
167- `cleanup:` — code cleanup
168- `docs:` — documentation
169- `bench:` — benchmarks
170- `build:` — build system changes
171- `refactor:` — refactoring
172- `test:` — test changes
173- `Revert` — reverting a previous commit
174- `Reland` — relanding a reverted commit
175- `BREAKING` — breaking changes
176 
177Additionally, deno_core/v8 upgrades must NOT use `chore:` — use `feat:`, `fix:`,
178or `refactor:` instead, with a title describing the actual change.
179 
180Release PRs (titles matching `X.Y.Z`) are also valid.
181 
182The validation script is at `tools/verify_pr_title.js`.
183 
184### Workflow Rules
185 
186- Create feature branches with descriptive names
187- Commit with clear, descriptive messages
188- Never force push — all commits are squashed on merge
189- Keep changes minimal and focused; avoid drive-by changes
190- Before committing, run `tools/format.js` and `tools/lint.js`
191 
192## Development Workflows
193 
194### Adding a New CLI Subcommand
195 
1961. Define the command structure in `cli/args/flags.rs`
1972. Add the command handler in `cli/tools/<command_name>.rs` or
198   `cli/tools/<command_name>/mod.rs`
1993. Wire it up in `cli/main.rs`
2004. Add spec tests in `tests/specs/<command_name>/`
201 
202### Modifying or Adding an Extension
203 
2041. Navigate to `ext/<extension_name>/`
2052. Rust code provides the ops exposed to JavaScript
2063. JavaScript code in the extension provides higher-level APIs
2074. Update `runtime/worker.rs` to register a new extension
2085. Add tests in the extension's directory
209 
210## Debugging
211 
212```bash
213# Verbose logging
214DENO_LOG=debug ./target/debug/deno run script.ts
215 
216# Module-specific logging
217DENO_LOG=deno_core=debug ./target/debug/deno run script.ts
218 
219# Full backtrace on panic
220RUST_BACKTRACE=1 ./target/debug/deno run script.ts
221 
222# V8 inspector
223./target/debug/deno run --inspect-brk script.ts
224```
225 
226In Rust code: `eprintln!("Debug: {:?}", var);` or `dbg!(var);`
227 
228## Pull Request Reviews
229 
230### Before commenting, verify your claims
231 
232- If you claim something is missing (a stub, a test, error handling), search the
233  full diff AND the existing codebase before commenting. Do not flag missing
234  code that already exists elsewhere in the PR or the repository.
235- If you suggest a code change, verify it compiles and does not break the
236  intended behavior. Do not suggest fixes that contradict the PR's stated goal.
237- Do not duplicate your own comments. If you already flagged an issue, do not
238  post a second comment about the same thing.
239 
240### Focus on high-value issues
241 
242Prioritize these (in order):
243 
2441. **Correctness bugs** — logic errors, race conditions (e.g. spurious wakeups
245   on `Condvar`), use-after-free, null derefs
2462. **Public API leaks** — internal fields accidentally exposed in public return
247   types
2483. **Security** — unsafe blocks with incorrect safety invariants, unsanitized
249   inputs at system boundaries
2504. **Missing error handling** — errors silently swallowed where they should
251   propagate, or propagated where they should be caught
252 
253Do NOT comment on:
254 
255- Style preferences already enforced by the project's formatter (dprint) and
256  linter (clippy + deno lint)
257- Suggesting longer timeouts or shorter delays in tests without evidence of
258  flakiness
259- Minor documentation wording unless it is actively misleading
260- Hypothetical edge cases that cannot realistically occur (e.g. a process having
261  > 256 direct children)
262 
263### Understand the runtime model before suggesting fixes
264 
265Deno embeds V8 and uses a single-threaded async event loop (tokio). Code that
266looks like a busy-spin may actually be required because:
267 
268- `poll_sessions(None)` in the inspector drives async I/O — parking the thread
269  prevents WebSocket close frames from being processed, causing deadlocks
270- The event loop must keep running for futures to make progress; blocking the
271  main thread stops the I/O reactor
272- Some loops intentionally spin to allow the waker/poller to process events each
273  iteration
274 
275Before suggesting `sleep`, `park`, or backoff in a polling loop, check whether
276the loop body drives async I/O that would stall if the thread were blocked.
277 
278### Trace through the actual code path, not just the function signature
279 
280A common review mistake is looking at a function's local behavior without
281tracing its callers and the runtime context. For example:
282 
283- A function that "doesn't check field X" may not need to because callers
284  guarantee X is consumed before the check runs (e.g., `handshake` is always
285  `take()`n at the top of `poll_sessions` before any session-count checks)
286- A heuristic that "doesn't handle case Y" may already handle it through a
287  different code path (e.g., dotenv comment detection via `#` prefix check
288  happens before the inner-quote fallback is reached)
289 
290### Don't suggest fixes that introduce circular dependencies
291 
292In parsers and state machines, be careful not to suggest fixes that require
293knowing the answer to the question being solved. For example, suggesting "detect
294where the comment starts before matching quotes" is circular when the quote
295matching is what determines where the value (and thus the comment) begins.
296 
297### Verify suggestions against existing tests
298 
299Before suggesting a change, check whether the codebase already has test coverage
300for the case in question. The `test_valid_env` test in `libs/dotenv/lib.rs`
301covers many edge cases including inline comments with quotes
302(`EDGE_CASE_INLINE_COMMENTS`). Running existing tests before and after a
303suggested change catches regressions.
304 
305### Match existing patterns in the codebase
306 
307When suggesting changes to a function, look for similar functions nearby that
308solve analogous problems. If the existing pattern (e.g., `wait_for_session`)
309uses a specific flag/mechanism, understand why before suggesting a different
310approach for a similar function (e.g., `wait_for_sessions_disconnect`). The
311difference may be intentional.
312 
313### Deno-specific conventions
314 
315- Ops use the `#[op2]` macro. Fast ops use `#[op2(fast)]`.
316- Internal symbols in JS (`ext/process/40_process.js`, `ext/node/polyfills/`)
317  use the `k` prefix convention: `kIpc`, `kSerialization`, `kInputOption`. Flag
318  deviations.
319- Node.js compatibility code is in `ext/node/polyfills/`. When reviewing these
320  files, check behavior against Node.js docs, not just Deno conventions. Some
321  patterns (like synchronous `throw` in `spawn()` for EPERM but async error
322  event for ENOENT) are intentional Node.js compatibility.
323 
324### When suggesting error handling changes
325 
326- Check whether the function's callers expect the error to propagate or be
327  swallowed. Do not suggest propagating errors in paths that are intentionally
328  best-effort (e.g. killing already-exited processes).
329- When suggesting a specific error variant or code change, verify the types
330  actually match. For example, `Option::or_else` takes `FnOnce() -> Option<T>`,
331  not `FnOnce(E) -> ...`.
332- If a Rust function returns `Result` and an `Option` is needed, use `.ok()`
333  before `.or_else()` or `.unwrap_or()`.
334 
335### Platform-specific code
336 
337- `#[cfg(unix)]` code that calls `find_descendant_pids` or similar must have
338  stubs for non-Linux/non-macOS Unix targets. Check that
339  `#[cfg(all(unix, not(target_os = "linux"), not(target_os = "macos")))]` stubs
340  exist before flagging missing platform support.
341- Windows `unsafe` blocks using `windows_sys` are common for process management.
342  Verify handle cleanup (`CloseHandle`) but do not flag the `unsafe` usage
343  itself.
344 
345## Troubleshooting
346 
347- **Slow compile times**: Use `cargo check`, `--bin deno`, or `sccache`
348- **Build failures on macOS**: Run `xcode-select --install`
349- **Build failures on Linux**: Install `build-essential`
350- **Spec test failures**: Check output diffs, use `[WILDCARD]` for
351  non-deterministic parts
352- **Permission errors**: Ensure test files have correct permissions
353