{"owner":"denoland","repo":"deno","hasSkills":true,"hasMcp":false,"mcpConfig":null,"found":["CLAUDE.md"],"skills":{"CLAUDE.md":"# Deno Development Guide\n\n## Table of Contents\n\n- [Git workflow](#git-workflow)\n- [High Level Overview](#high-level-overview)\n- [Quick Start](#quick-start)\n- [Commands](#commands)\n- [Testing](#testing)\n- [Development Workflows](#development-workflows)\n- [Debugging](#debugging)\n- [Codebase Navigation](#codebase-navigation)\n- [Troubleshooting](#troubleshooting)\n\n## Git workflow\n\nDeno uses a GH based standard git workflow. The main branch is `main`. All\ndevelopment happens in feature branches, which are then merged into `main` via\npull requests.\n\nWhen the feature is finished and ready to for review, follow these steps:\n\n- Create a new git branch, if you haven't already, with a descriptive name\n  (e.g., `feature/new-cli-command` or `fix/bug-in-worker-threads`).\n- Commit your changes with clear and descriptive commit messages.\n- Push your branch to the remote repository.\n- Open a pull request (PR) against the `main` branch on GitHub.\n- Before committing, make sure `tools/format.js` is run to format your code\n- Before committing, if only non-Rust was changed, make sure to run\n  `tools/lint.js --js` and fix any lint errors before committing\n- If you changed Rust code, make sure to run `tools/lint.js` and fix any lint\n  errors before committing\n- In the PR description, provide a clear summary of the changes you made, why\n  they were necessary, and any relevant context or links to related issues.\n- When pushing updates to the PR, make sure to never force push. Create as many\n  commits as you need, all of them get squashed when the PR is merged, so there\n  is no need to rewrite history. This also allows reviewers to see the\n  incremental changes you made in response to feedback.\n- Keep your changes minimal, don't do drive-by changes in a PR. If you need to\n  make a change that is not directly related to the PR, create a separate PR for\n  it. This keeps the review process focused and efficient.\n\n## High Level Overview\n\nThe user visible interface and high level integration is in the `deno` crate\n(located in `./cli`).\n\nThis includes flag parsing, subcommands, package management tooling, etc. Flag\nparsing is in `cli/args/flags.rs`. Tools are in `cli/tools/<tool>`.\n\nThe `deno_runtime` crate (`./runtime`) assembles the JavaScript runtime,\nincluding all \"extensions\" (native functionality exposed to JavaScript). The\nextensions themselves are in the `ext/` directory, and provide system access to\nJavaScript – for instance filesystem operations and networking.\n\n### Key Directories\n\n- `cli/` - User-facing CLI implementation, subcommands, and tools\n- `runtime/` - JavaScript runtime assembly and integration\n- `ext/` - Extensions providing native functionality to JS (fs, net, etc.)\n- `tests/specs/` - Integration tests (spec tests)\n- `tests/unit/` - Unit tests\n- `tests/testdata/` - Test fixtures and data files\n\n## Quick Start\n\nBefore building, install the required prerequisites (Rust, native compilers,\ncmake, protobuf, etc.) and clone with `--recurse-submodules` as described in\n[`.github/CONTRIBUTING.md`](.github/CONTRIBUTING.md#building-from-source).\n\n### Building Deno\n\nTo compile after making changes:\n\n```bash\ncargo build\n```\n\nFor faster iteration during development (less optimization):\n\n```bash\ncargo build --bin deno\n```\n\nExecute your development build:\n\n```bash\n./target/debug/deno eval 'console.log(\"Hello from dev build\")'\n```\n\n### Running with your changes\n\n```bash\n# Run a local file\n./target/debug/deno run path/to/file.ts\n\n# Run with permissions\n./target/debug/deno run --allow-net --allow-read script.ts\n\n# Run the REPL\n./target/debug/deno\n```\n\n## Commands\n\n### Compilation and Checks\n\n```bash\n# Check for compilation errors (fast, no binary output)\ncargo check\n\n# Check specific package\ncargo check -p deno_runtime\n\n# Build release version (slow, optimized)\ncargo build --release\n```\n\n### Code Quality\n\n```bash\n# Lint the code\n./tools/lint.js\n\n# Format the code\n./tools/format.js\n\n# Both lint and format\n./tools/format.js && ./tools/lint.js\n```\n\n## Testing\n\n### Running Tests\n\n```bash\n# Run all tests (this takes a while)\ncargo test\n\n# Filter tests by name\ncargo test <nameOfTest>\n\n# Run tests in a specific package\ncargo test -p deno_core\n\n# Run just the CLI integration tests\ncargo test --bin deno\n\n# Run spec tests only\ncargo test specs\n\n# Run a specific spec test\ncargo test spec::test_name\n```\n\n### Unit Tests (`tests/unit/`)\n\nJavaScript/TypeScript unit tests live in `tests/unit/` as `*_test.ts` files. Run\nthem via `cargo test`:\n\n```bash\n# Run all unit tests in a specific file\ncargo test unit::webcrypto_test\n\n# Run all unit tests\ncargo test unit::\n\n# Run Node.js compatibility unit tests (tests/unit_node/)\ncargo test unit_node::crypto_test\n\n# Run all Node.js compat unit tests\ncargo test unit_node::\n```\n\nDo NOT run these directly with `./target/debug/deno test` — they depend on the\ncargo test harness for correct setup.\n\n### Test Organization\n\n- **Spec tests** (`tests/specs/`) - Main integration tests, CLI command\n  execution and output validation\n- **Unit tests** (`tests/unit/`) - JavaScript/TypeScript unit tests for runtime\n  APIs\n- **Integration tests** (`tests/integration/`) - Additional integration tests\n- **WPT** (`tests/wpt/`) - Web Platform Tests for web standards compliance\n\n## \"spec\" tests\n\nThe main form of integration test in deno is the \"spec\" test. These tests can be\nfound in `tests/specs`. The idea is that you have a `__test__.jsonc` file that\nlays out one or more tests, where a test is a CLI command to execute and the\noutput is captured and asserted against.\n\nThe name of the test comes from the directory the `__test__.jsonc` appears in.\n\n### Creating a New Spec Test\n\n1. Create a directory in `tests/specs/` with a descriptive name\n2. Add a `__test__.jsonc` file describing your test steps\n3. Add any input files needed for the test\n4. Add `.out` files for expected output (or inline in `__test__.jsonc`)\n\nExample:\n\n```\ntests/specs/my_feature/\n  __test__.jsonc\n  main.ts\n  expected.out\n```\n\n### `__test__.jsonc` schema\n\nThe schema for `__test__.jsonc` can be found in `tests/specs/schema.json`.\n\nExample test structure:\n\n```jsonc\n{\n  \"tests\": {\n    \"basic_case\": {\n      \"args\": \"run main.ts\",\n      \"output\": \"expected.out\"\n    },\n    \"with_flag\": {\n      \"steps\": [\n        {\n          \"args\": \"run --allow-net main.ts\",\n          \"output\": \"[WILDCARD]success[WILDCARD]\"\n        }\n      ]\n    }\n  }\n}\n```\n\n### Output assertions\n\nThe expected output can be inline in a `__test__.jsonc` file or in a file ending\nwith `.out`. For a given test step, the `output` field tells you either the\ninline expectation or the name of the file containing the **expectation**. The\nexpectation uses a small matching language to support wildcards and things like\nthat. A literal character means you expect that exact character, so `Foo bar`\nwould expect the output to be \"Foo bar\". Then there are things with special\nmeanings:\n\n- `[WILDCARD]` : matches 0 or more of any character, like `.*` in regex. this\n  can cross newlines\n- `[WILDLINE]` : matches 0 or more of any character, ending at the end of a line\n- `[WILDCHAR]` - match the next character\n- `[WILDCHARS(5)]` - match any of the next 5 characters\n- `[UNORDERED_START]` followed by many lines then `[UNORDERED_END]` will match\n  the lines in any order (useful for non-deterministic output)\n- `[# example]` - line comments start with `[#` and end with `]`\n\nExample `.out` file:\n\n```\nCheck file://[WILDCARD]/main.ts\n[WILDCARD]\nSuccessfully compiled [WILDLINE]\n```\n\n## Development Workflows\n\n### Adding a New CLI Subcommand\n\n1. Define the command structure in `cli/args/flags.rs`\n2. Add the command handler in `cli/tools/<command_name>.rs` or\n   `cli/tools/<command_name>/mod.rs`\n3. Wire it up in `cli/main.rs`\n4. Add spec tests in `tests/specs/<command_name>/`\n\nExample files to reference:\n\n- Simple command: `cli/tools/fmt.rs`\n- Complex command: `cli/tools/test/`\n\n### Modifying or Adding an Extension\n\n1. Navigate to `ext/<extension_name>/` (e.g., `ext/fs/`, `ext/net/`)\n2. Rust code provides the ops (operations) exposed to JavaScript\n3. JavaScript code in the extension provides the higher-level APIs\n4. Update `runtime/worker.rs` to register the extension if new\n5. Add tests in the extension's directory\n\n### Updating Dependencies\n\n```bash\n# Update Cargo dependencies\ncargo update\n\n# Update to latest compatible versions\ncargo upgrade  # Requires cargo-edit: cargo install cargo-edit\n\n# Check for outdated dependencies\ncargo outdated  # Requires cargo-outdated\n```\n\n## Debugging\n\n### Debugging Rust Code\n\nUse `lldb` directly:\n\n```bash\nlldb ./target/debug/deno\n(lldb) run eval 'console.log(\"test\")'\n```\n\n### Debugging JavaScript Runtime Issues\n\nUse println debugging.\n\n### Verbose Logging\n\n```bash\n# Set Rust log level\nDENO_LOG=debug ./target/debug/deno run script.ts\n\n# Specific module logging\nDENO_LOG=deno_core=debug ./target/debug/deno run script.ts\n```\n\n### Debug Prints\n\nIn Rust code:\n\n```rust\neprintln!(\"Debug: {:?}\", some_variable);\ndbg!(some_variable);\n```\n\nIn JavaScript/TypeScript code:\n\n```javascript\nconsole.log(\"Debug:\", value);\n```\n\n## Codebase Navigation\n\n### Key Files to Understand First\n\n1. `cli/main.rs` - Entry point, command routing\n2. `cli/args/flags.rs` - CLI flag parsing and structure\n3. `runtime/worker.rs` - Worker/runtime initialization\n4. `runtime/permissions.rs` - Permission system\n5. `cli/module_loader.rs` - Module loading and resolution\n\n### Common Patterns\n\n- **Ops** - Rust functions exposed to JavaScript (in `ext/` directories)\n- **Extensions** - Collections of ops and JS code providing functionality\n- **Workers** - JavaScript execution contexts (main worker, web workers)\n- **Resources** - Managed objects passed between Rust and JS (files, sockets,\n  etc.)\n\n### Finding Examples\n\n- Need to add a CLI flag? Look at similar commands in `cli/args/flags.rs`\n- Need to add an op? Look at ops in relevant `ext/` directory (e.g.,\n  `ext/fs/lib.rs`)\n- Need to add a tool? Reference existing tools in `cli/tools/`\n\n## Troubleshooting\n\n### Build Failures\n\n**Error: linking with `cc` failed**\n\n- Make sure you have the required system dependencies\n- On macOS: `xcode-select --install`\n- On Linux: Install `build-essential` or equivalent\n\n**Error: failed to download dependencies**\n\n- Check internet connection\n- Try `cargo clean` then rebuild\n- Check if behind a proxy, configure cargo accordingly\n\nFor other build failures (missing `cmake`, `stdarg.h`, etc.), see the full\nprerequisites in\n[`.github/CONTRIBUTING.md`](.github/CONTRIBUTING.md#building-from-source).\n\n### Test Failures\n\n**Spec test failures**\n\n- Check the test output carefully for differences\n- Update `.out` files if output format changed intentionally\n- Use `[WILDCARD]` for non-deterministic parts of output\n\n**Flaky tests**\n\n- Add `[UNORDERED_START]`/`[UNORDERED_END]` for order-independent output\n- Check for race conditions in test code\n- May need to increase timeouts or add retries\n\n### Permission Issues\n\n**Tests failing with permission errors**\n\n- Ensure test files have correct permissions\n- Check that test setup properly grants necessary permissions\n\n### Performance Issues\n\n**Slow compile times**\n\n- Use `cargo check` instead of `cargo build` when possible\n- Use `--bin deno` to build only the main binary\n- Use `sccache` or `mold` linker for faster builds\n- Consider using `cargo-watch` for incremental builds\n\n### Runtime Debugging\n\n**Crashes or panics**\n\n- Run with `RUST_BACKTRACE=1` for full backtrace\n- Use `RUST_BACKTRACE=full` for even more detail\n- Check for unwrap() calls that might panic\n\n**Unexpected behavior**\n\n- Add debug prints liberally\n- Check permission grants - many features require explicit permissions\n\n### Getting Help\n\n- Check existing issues on GitHub\n- Look at recent PRs for similar changes\n- Review the Discord community for discussions\n- When in doubt, ask! The maintainers are helpful\n"},"files":{"CLAUDE.md":"# Deno Development Guide\n\n## Table of Contents\n\n- [Git workflow](#git-workflow)\n- [High Level Overview](#high-level-overview)\n- [Quick Start](#quick-start)\n- [Commands](#commands)\n- [Testing](#testing)\n- [Development Workflows](#development-workflows)\n- [Debugging](#debugging)\n- [Codebase Navigation](#codebase-navigation)\n- [Troubleshooting](#troubleshooting)\n\n## Git workflow\n\nDeno uses a GH based standard git workflow. The main branch is `main`. All\ndevelopment happens in feature branches, which are then merged into `main` via\npull requests.\n\nWhen the feature is finished and ready to for review, follow these steps:\n\n- Create a new git branch, if you haven't already, with a descriptive name\n  (e.g., `feature/new-cli-command` or `fix/bug-in-worker-threads`).\n- Commit your changes with clear and descriptive commit messages.\n- Push your branch to the remote repository.\n- Open a pull request (PR) against the `main` branch on GitHub.\n- Before committing, make sure `tools/format.js` is run to format your code\n- Before committing, if only non-Rust was changed, make sure to run\n  `tools/lint.js --js` and fix any lint errors before committing\n- If you changed Rust code, make sure to run `tools/lint.js` and fix any lint\n  errors before committing\n- In the PR description, provide a clear summary of the changes you made, why\n  they were necessary, and any relevant context or links to related issues.\n- When pushing updates to the PR, make sure to never force push. Create as many\n  commits as you need, all of them get squashed when the PR is merged, so there\n  is no need to rewrite history. This also allows reviewers to see the\n  incremental changes you made in response to feedback.\n- Keep your changes minimal, don't do drive-by changes in a PR. If you need to\n  make a change that is not directly related to the PR, create a separate PR for\n  it. This keeps the review process focused and efficient.\n\n## High Level Overview\n\nThe user visible interface and high level integration is in the `deno` crate\n(located in `./cli`).\n\nThis includes flag parsing, subcommands, package management tooling, etc. Flag\nparsing is in `cli/args/flags.rs`. Tools are in `cli/tools/<tool>`.\n\nThe `deno_runtime` crate (`./runtime`) assembles the JavaScript runtime,\nincluding all \"extensions\" (native functionality exposed to JavaScript). The\nextensions themselves are in the `ext/` directory, and provide system access to\nJavaScript – for instance filesystem operations and networking.\n\n### Key Directories\n\n- `cli/` - User-facing CLI implementation, subcommands, and tools\n- `runtime/` - JavaScript runtime assembly and integration\n- `ext/` - Extensions providing native functionality to JS (fs, net, etc.)\n- `tests/specs/` - Integration tests (spec tests)\n- `tests/unit/` - Unit tests\n- `tests/testdata/` - Test fixtures and data files\n\n## Quick Start\n\nBefore building, install the required prerequisites (Rust, native compilers,\ncmake, protobuf, etc.) and clone with `--recurse-submodules` as described in\n[`.github/CONTRIBUTING.md`](.github/CONTRIBUTING.md#building-from-source).\n\n### Building Deno\n\nTo compile after making changes:\n\n```bash\ncargo build\n```\n\nFor faster iteration during development (less optimization):\n\n```bash\ncargo build --bin deno\n```\n\nExecute your development build:\n\n```bash\n./target/debug/deno eval 'console.log(\"Hello from dev build\")'\n```\n\n### Running with your changes\n\n```bash\n# Run a local file\n./target/debug/deno run path/to/file.ts\n\n# Run with permissions\n./target/debug/deno run --allow-net --allow-read script.ts\n\n# Run the REPL\n./target/debug/deno\n```\n\n## Commands\n\n### Compilation and Checks\n\n```bash\n# Check for compilation errors (fast, no binary output)\ncargo check\n\n# Check specific package\ncargo check -p deno_runtime\n\n# Build release version (slow, optimized)\ncargo build --release\n```\n\n### Code Quality\n\n```bash\n# Lint the code\n./tools/lint.js\n\n# Format the code\n./tools/format.js\n\n# Both lint and format\n./tools/format.js && ./tools/lint.js\n```\n\n## Testing\n\n### Running Tests\n\n```bash\n# Run all tests (this takes a while)\ncargo test\n\n# Filter tests by name\ncargo test <nameOfTest>\n\n# Run tests in a specific package\ncargo test -p deno_core\n\n# Run just the CLI integration tests\ncargo test --bin deno\n\n# Run spec tests only\ncargo test specs\n\n# Run a specific spec test\ncargo test spec::test_name\n```\n\n### Unit Tests (`tests/unit/`)\n\nJavaScript/TypeScript unit tests live in `tests/unit/` as `*_test.ts` files. Run\nthem via `cargo test`:\n\n```bash\n# Run all unit tests in a specific file\ncargo test unit::webcrypto_test\n\n# Run all unit tests\ncargo test unit::\n\n# Run Node.js compatibility unit tests (tests/unit_node/)\ncargo test unit_node::crypto_test\n\n# Run all Node.js compat unit tests\ncargo test unit_node::\n```\n\nDo NOT run these directly with `./target/debug/deno test` — they depend on the\ncargo test harness for correct setup.\n\n### Test Organization\n\n- **Spec tests** (`tests/specs/`) - Main integration tests, CLI command\n  execution and output validation\n- **Unit tests** (`tests/unit/`) - JavaScript/TypeScript unit tests for runtime\n  APIs\n- **Integration tests** (`tests/integration/`) - Additional integration tests\n- **WPT** (`tests/wpt/`) - Web Platform Tests for web standards compliance\n\n## \"spec\" tests\n\nThe main form of integration test in deno is the \"spec\" test. These tests can be\nfound in `tests/specs`. The idea is that you have a `__test__.jsonc` file that\nlays out one or more tests, where a test is a CLI command to execute and the\noutput is captured and asserted against.\n\nThe name of the test comes from the directory the `__test__.jsonc` appears in.\n\n### Creating a New Spec Test\n\n1. Create a directory in `tests/specs/` with a descriptive name\n2. Add a `__test__.jsonc` file describing your test steps\n3. Add any input files needed for the test\n4. Add `.out` files for expected output (or inline in `__test__.jsonc`)\n\nExample:\n\n```\ntests/specs/my_feature/\n  __test__.jsonc\n  main.ts\n  expected.out\n```\n\n### `__test__.jsonc` schema\n\nThe schema for `__test__.jsonc` can be found in `tests/specs/schema.json`.\n\nExample test structure:\n\n```jsonc\n{\n  \"tests\": {\n    \"basic_case\": {\n      \"args\": \"run main.ts\",\n      \"output\": \"expected.out\"\n    },\n    \"with_flag\": {\n      \"steps\": [\n        {\n          \"args\": \"run --allow-net main.ts\",\n          \"output\": \"[WILDCARD]success[WILDCARD]\"\n        }\n      ]\n    }\n  }\n}\n```\n\n### Output assertions\n\nThe expected output can be inline in a `__test__.jsonc` file or in a file ending\nwith `.out`. For a given test step, the `output` field tells you either the\ninline expectation or the name of the file containing the **expectation**. The\nexpectation uses a small matching language to support wildcards and things like\nthat. A literal character means you expect that exact character, so `Foo bar`\nwould expect the output to be \"Foo bar\". Then there are things with special\nmeanings:\n\n- `[WILDCARD]` : matches 0 or more of any character, like `.*` in regex. this\n  can cross newlines\n- `[WILDLINE]` : matches 0 or more of any character, ending at the end of a line\n- `[WILDCHAR]` - match the next character\n- `[WILDCHARS(5)]` - match any of the next 5 characters\n- `[UNORDERED_START]` followed by many lines then `[UNORDERED_END]` will match\n  the lines in any order (useful for non-deterministic output)\n- `[# example]` - line comments start with `[#` and end with `]`\n\nExample `.out` file:\n\n```\nCheck file://[WILDCARD]/main.ts\n[WILDCARD]\nSuccessfully compiled [WILDLINE]\n```\n\n## Development Workflows\n\n### Adding a New CLI Subcommand\n\n1. Define the command structure in `cli/args/flags.rs`\n2. Add the command handler in `cli/tools/<command_name>.rs` or\n   `cli/tools/<command_name>/mod.rs`\n3. Wire it up in `cli/main.rs`\n4. Add spec tests in `tests/specs/<command_name>/`\n\nExample files to reference:\n\n- Simple command: `cli/tools/fmt.rs`\n- Complex command: `cli/tools/test/`\n\n### Modifying or Adding an Extension\n\n1. Navigate to `ext/<extension_name>/` (e.g., `ext/fs/`, `ext/net/`)\n2. Rust code provides the ops (operations) exposed to JavaScript\n3. JavaScript code in the extension provides the higher-level APIs\n4. Update `runtime/worker.rs` to register the extension if new\n5. Add tests in the extension's directory\n\n### Updating Dependencies\n\n```bash\n# Update Cargo dependencies\ncargo update\n\n# Update to latest compatible versions\ncargo upgrade  # Requires cargo-edit: cargo install cargo-edit\n\n# Check for outdated dependencies\ncargo outdated  # Requires cargo-outdated\n```\n\n## Debugging\n\n### Debugging Rust Code\n\nUse `lldb` directly:\n\n```bash\nlldb ./target/debug/deno\n(lldb) run eval 'console.log(\"test\")'\n```\n\n### Debugging JavaScript Runtime Issues\n\nUse println debugging.\n\n### Verbose Logging\n\n```bash\n# Set Rust log level\nDENO_LOG=debug ./target/debug/deno run script.ts\n\n# Specific module logging\nDENO_LOG=deno_core=debug ./target/debug/deno run script.ts\n```\n\n### Debug Prints\n\nIn Rust code:\n\n```rust\neprintln!(\"Debug: {:?}\", some_variable);\ndbg!(some_variable);\n```\n\nIn JavaScript/TypeScript code:\n\n```javascript\nconsole.log(\"Debug:\", value);\n```\n\n## Codebase Navigation\n\n### Key Files to Understand First\n\n1. `cli/main.rs` - Entry point, command routing\n2. `cli/args/flags.rs` - CLI flag parsing and structure\n3. `runtime/worker.rs` - Worker/runtime initialization\n4. `runtime/permissions.rs` - Permission system\n5. `cli/module_loader.rs` - Module loading and resolution\n\n### Common Patterns\n\n- **Ops** - Rust functions exposed to JavaScript (in `ext/` directories)\n- **Extensions** - Collections of ops and JS code providing functionality\n- **Workers** - JavaScript execution contexts (main worker, web workers)\n- **Resources** - Managed objects passed between Rust and JS (files, sockets,\n  etc.)\n\n### Finding Examples\n\n- Need to add a CLI flag? Look at similar commands in `cli/args/flags.rs`\n- Need to add an op? Look at ops in relevant `ext/` directory (e.g.,\n  `ext/fs/lib.rs`)\n- Need to add a tool? Reference existing tools in `cli/tools/`\n\n## Troubleshooting\n\n### Build Failures\n\n**Error: linking with `cc` failed**\n\n- Make sure you have the required system dependencies\n- On macOS: `xcode-select --install`\n- On Linux: Install `build-essential` or equivalent\n\n**Error: failed to download dependencies**\n\n- Check internet connection\n- Try `cargo clean` then rebuild\n- Check if behind a proxy, configure cargo accordingly\n\nFor other build failures (missing `cmake`, `stdarg.h`, etc.), see the full\nprerequisites in\n[`.github/CONTRIBUTING.md`](.github/CONTRIBUTING.md#building-from-source).\n\n### Test Failures\n\n**Spec test failures**\n\n- Check the test output carefully for differences\n- Update `.out` files if output format changed intentionally\n- Use `[WILDCARD]` for non-deterministic parts of output\n\n**Flaky tests**\n\n- Add `[UNORDERED_START]`/`[UNORDERED_END]` for order-independent output\n- Check for race conditions in test code\n- May need to increase timeouts or add retries\n\n### Permission Issues\n\n**Tests failing with permission errors**\n\n- Ensure test files have correct permissions\n- Check that test setup properly grants necessary permissions\n\n### Performance Issues\n\n**Slow compile times**\n\n- Use `cargo check` instead of `cargo build` when possible\n- Use `--bin deno` to build only the main binary\n- Use `sccache` or `mold` linker for faster builds\n- Consider using `cargo-watch` for incremental builds\n\n### Runtime Debugging\n\n**Crashes or panics**\n\n- Run with `RUST_BACKTRACE=1` for full backtrace\n- Use `RUST_BACKTRACE=full` for even more detail\n- Check for unwrap() calls that might panic\n\n**Unexpected behavior**\n\n- Add debug prints liberally\n- Check permission grants - many features require explicit permissions\n\n### Getting Help\n\n- Check existing issues on GitHub\n- Look at recent PRs for similar changes\n- Review the Discord community for discussions\n- When in doubt, ask! The maintainers are helpful\n"},"items":[{"name":"CLAUDE.md","path":"CLAUDE.md","title":"CLAUDE.md","content":"# Deno Development Guide\n\n## Table of Contents\n\n- [Git workflow](#git-workflow)\n- [High Level Overview](#high-level-overview)\n- [Quick Start](#quick-start)\n- [Commands](#commands)\n- [Testing](#testing)\n- [Development Workflows](#development-workflows)\n- [Debugging](#debugging)\n- [Codebase Navigation](#codebase-navigation)\n- [Troubleshooting](#troubleshooting)\n\n## Git workflow\n\nDeno uses a GH based standard git workflow. The main branch is `main`. All\ndevelopment happens in feature branches, which are then merged into `main` via\npull requests.\n\nWhen the feature is finished and ready to for review, follow these steps:\n\n- Create a new git branch, if you haven't already, with a descriptive name\n  (e.g., `feature/new-cli-command` or `fix/bug-in-worker-threads`).\n- Commit your changes with clear and descriptive commit messages.\n- Push your branch to the remote repository.\n- Open a pull request (PR) against the `main` branch on GitHub.\n- Before committing, make sure `tools/format.js` is run to format your code\n- Before committing, if only non-Rust was changed, make sure to run\n  `tools/lint.js --js` and fix any lint errors before committing\n- If you changed Rust code, make sure to run `tools/lint.js` and fix any lint\n  errors before committing\n- In the PR description, provide a clear summary of the changes you made, why\n  they were necessary, and any relevant context or links to related issues.\n- When pushing updates to the PR, make sure to never force push. Create as many\n  commits as you need, all of them get squashed when the PR is merged, so there\n  is no need to rewrite history. This also allows reviewers to see the\n  incremental changes you made in response to feedback.\n- Keep your changes minimal, don't do drive-by changes in a PR. If you need to\n  make a change that is not directly related to the PR, create a separate PR for\n  it. This keeps the review process focused and efficient.\n\n## High Level Overview\n\nThe user visible interface and high level integration is in the `deno` crate\n(located in `./cli`).\n\nThis includes flag parsing, subcommands, package management tooling, etc. Flag\nparsing is in `cli/args/flags.rs`. Tools are in `cli/tools/<tool>`.\n\nThe `deno_runtime` crate (`./runtime`) assembles the JavaScript runtime,\nincluding all \"extensions\" (native functionality exposed to JavaScript). The\nextensions themselves are in the `ext/` directory, and provide system access to\nJavaScript – for instance filesystem operations and networking.\n\n### Key Directories\n\n- `cli/` - User-facing CLI implementation, subcommands, and tools\n- `runtime/` - JavaScript runtime assembly and integration\n- `ext/` - Extensions providing native functionality to JS (fs, net, etc.)\n- `tests/specs/` - Integration tests (spec tests)\n- `tests/unit/` - Unit tests\n- `tests/testdata/` - Test fixtures and data files\n\n## Quick Start\n\nBefore building, install the required prerequisites (Rust, native compilers,\ncmake, protobuf, etc.) and clone with `--recurse-submodules` as described in\n[`.github/CONTRIBUTING.md`](.github/CONTRIBUTING.md#building-from-source).\n\n### Building Deno\n\nTo compile after making changes:\n\n```bash\ncargo build\n```\n\nFor faster iteration during development (less optimization):\n\n```bash\ncargo build --bin deno\n```\n\nExecute your development build:\n\n```bash\n./target/debug/deno eval 'console.log(\"Hello from dev build\")'\n```\n\n### Running with your changes\n\n```bash\n# Run a local file\n./target/debug/deno run path/to/file.ts\n\n# Run with permissions\n./target/debug/deno run --allow-net --allow-read script.ts\n\n# Run the REPL\n./target/debug/deno\n```\n\n## Commands\n\n### Compilation and Checks\n\n```bash\n# Check for compilation errors (fast, no binary output)\ncargo check\n\n# Check specific package\ncargo check -p deno_runtime\n\n# Build release version (slow, optimized)\ncargo build --release\n```\n\n### Code Quality\n\n```bash\n# Lint the code\n./tools/lint.js\n\n# Format the code\n./tools/format.js\n\n# Both lint and format\n./tools/format.js && ./tools/lint.js\n```\n\n## Testing\n\n### Running Tests\n\n```bash\n# Run all tests (this takes a while)\ncargo test\n\n# Filter tests by name\ncargo test <nameOfTest>\n\n# Run tests in a specific package\ncargo test -p deno_core\n\n# Run just the CLI integration tests\ncargo test --bin deno\n\n# Run spec tests only\ncargo test specs\n\n# Run a specific spec test\ncargo test spec::test_name\n```\n\n### Unit Tests (`tests/unit/`)\n\nJavaScript/TypeScript unit tests live in `tests/unit/` as `*_test.ts` files. Run\nthem via `cargo test`:\n\n```bash\n# Run all unit tests in a specific file\ncargo test unit::webcrypto_test\n\n# Run all unit tests\ncargo test unit::\n\n# Run Node.js compatibility unit tests (tests/unit_node/)\ncargo test unit_node::crypto_test\n\n# Run all Node.js compat unit tests\ncargo test unit_node::\n```\n\nDo NOT run these directly with `./target/debug/deno test` — they depend on the\ncargo test harness for correct setup.\n\n### Test Organization\n\n- **Spec tests** (`tests/specs/`) - Main integration tests, CLI command\n  execution and output validation\n- **Unit tests** (`tests/unit/`) - JavaScript/TypeScript unit tests for runtime\n  APIs\n- **Integration tests** (`tests/integration/`) - Additional integration tests\n- **WPT** (`tests/wpt/`) - Web Platform Tests for web standards compliance\n\n## \"spec\" tests\n\nThe main form of integration test in deno is the \"spec\" test. These tests can be\nfound in `tests/specs`. The idea is that you have a `__test__.jsonc` file that\nlays out one or more tests, where a test is a CLI command to execute and the\noutput is captured and asserted against.\n\nThe name of the test comes from the directory the `__test__.jsonc` appears in.\n\n### Creating a New Spec Test\n\n1. Create a directory in `tests/specs/` with a descriptive name\n2. Add a `__test__.jsonc` file describing your test steps\n3. Add any input files needed for the test\n4. Add `.out` files for expected output (or inline in `__test__.jsonc`)\n\nExample:\n\n```\ntests/specs/my_feature/\n  __test__.jsonc\n  main.ts\n  expected.out\n```\n\n### `__test__.jsonc` schema\n\nThe schema for `__test__.jsonc` can be found in `tests/specs/schema.json`.\n\nExample test structure:\n\n```jsonc\n{\n  \"tests\": {\n    \"basic_case\": {\n      \"args\": \"run main.ts\",\n      \"output\": \"expected.out\"\n    },\n    \"with_flag\": {\n      \"steps\": [\n        {\n          \"args\": \"run --allow-net main.ts\",\n          \"output\": \"[WILDCARD]success[WILDCARD]\"\n        }\n      ]\n    }\n  }\n}\n```\n\n### Output assertions\n\nThe expected output can be inline in a `__test__.jsonc` file or in a file ending\nwith `.out`. For a given test step, the `output` field tells you either the\ninline expectation or the name of the file containing the **expectation**. The\nexpectation uses a small matching language to support wildcards and things like\nthat. A literal character means you expect that exact character, so `Foo bar`\nwould expect the output to be \"Foo bar\". Then there are things with special\nmeanings:\n\n- `[WILDCARD]` : matches 0 or more of any character, like `.*` in regex. this\n  can cross newlines\n- `[WILDLINE]` : matches 0 or more of any character, ending at the end of a line\n- `[WILDCHAR]` - match the next character\n- `[WILDCHARS(5)]` - match any of the next 5 characters\n- `[UNORDERED_START]` followed by many lines then `[UNORDERED_END]` will match\n  the lines in any order (useful for non-deterministic output)\n- `[# example]` - line comments start with `[#` and end with `]`\n\nExample `.out` file:\n\n```\nCheck file://[WILDCARD]/main.ts\n[WILDCARD]\nSuccessfully compiled [WILDLINE]\n```\n\n## Development Workflows\n\n### Adding a New CLI Subcommand\n\n1. Define the command structure in `cli/args/flags.rs`\n2. Add the command handler in `cli/tools/<command_name>.rs` or\n   `cli/tools/<command_name>/mod.rs`\n3. Wire it up in `cli/main.rs`\n4. Add spec tests in `tests/specs/<command_name>/`\n\nExample files to reference:\n\n- Simple command: `cli/tools/fmt.rs`\n- Complex command: `cli/tools/test/`\n\n### Modifying or Adding an Extension\n\n1. Navigate to `ext/<extension_name>/` (e.g., `ext/fs/`, `ext/net/`)\n2. Rust code provides the ops (operations) exposed to JavaScript\n3. JavaScript code in the extension provides the higher-level APIs\n4. Update `runtime/worker.rs` to register the extension if new\n5. Add tests in the extension's directory\n\n### Updating Dependencies\n\n```bash\n# Update Cargo dependencies\ncargo update\n\n# Update to latest compatible versions\ncargo upgrade  # Requires cargo-edit: cargo install cargo-edit\n\n# Check for outdated dependencies\ncargo outdated  # Requires cargo-outdated\n```\n\n## Debugging\n\n### Debugging Rust Code\n\nUse `lldb` directly:\n\n```bash\nlldb ./target/debug/deno\n(lldb) run eval 'console.log(\"test\")'\n```\n\n### Debugging JavaScript Runtime Issues\n\nUse println debugging.\n\n### Verbose Logging\n\n```bash\n# Set Rust log level\nDENO_LOG=debug ./target/debug/deno run script.ts\n\n# Specific module logging\nDENO_LOG=deno_core=debug ./target/debug/deno run script.ts\n```\n\n### Debug Prints\n\nIn Rust code:\n\n```rust\neprintln!(\"Debug: {:?}\", some_variable);\ndbg!(some_variable);\n```\n\nIn JavaScript/TypeScript code:\n\n```javascript\nconsole.log(\"Debug:\", value);\n```\n\n## Codebase Navigation\n\n### Key Files to Understand First\n\n1. `cli/main.rs` - Entry point, command routing\n2. `cli/args/flags.rs` - CLI flag parsing and structure\n3. `runtime/worker.rs` - Worker/runtime initialization\n4. `runtime/permissions.rs` - Permission system\n5. `cli/module_loader.rs` - Module loading and resolution\n\n### Common Patterns\n\n- **Ops** - Rust functions exposed to JavaScript (in `ext/` directories)\n- **Extensions** - Collections of ops and JS code providing functionality\n- **Workers** - JavaScript execution contexts (main worker, web workers)\n- **Resources** - Managed objects passed between Rust and JS (files, sockets,\n  etc.)\n\n### Finding Examples\n\n- Need to add a CLI flag? Look at similar commands in `cli/args/flags.rs`\n- Need to add an op? Look at ops in relevant `ext/` directory (e.g.,\n  `ext/fs/lib.rs`)\n- Need to add a tool? Reference existing tools in `cli/tools/`\n\n## Troubleshooting\n\n### Build Failures\n\n**Error: linking with `cc` failed**\n\n- Make sure you have the required system dependencies\n- On macOS: `xcode-select --install`\n- On Linux: Install `build-essential` or equivalent\n\n**Error: failed to download dependencies**\n\n- Check internet connection\n- Try `cargo clean` then rebuild\n- Check if behind a proxy, configure cargo accordingly\n\nFor other build failures (missing `cmake`, `stdarg.h`, etc.), see the full\nprerequisites in\n[`.github/CONTRIBUTING.md`](.github/CONTRIBUTING.md#building-from-source).\n\n### Test Failures\n\n**Spec test failures**\n\n- Check the test output carefully for differences\n- Update `.out` files if output format changed intentionally\n- Use `[WILDCARD]` for non-deterministic parts of output\n\n**Flaky tests**\n\n- Add `[UNORDERED_START]`/`[UNORDERED_END]` for order-independent output\n- Check for race conditions in test code\n- May need to increase timeouts or add retries\n\n### Permission Issues\n\n**Tests failing with permission errors**\n\n- Ensure test files have correct permissions\n- Check that test setup properly grants necessary permissions\n\n### Performance Issues\n\n**Slow compile times**\n\n- Use `cargo check` instead of `cargo build` when possible\n- Use `--bin deno` to build only the main binary\n- Use `sccache` or `mold` linker for faster builds\n- Consider using `cargo-watch` for incremental builds\n\n### Runtime Debugging\n\n**Crashes or panics**\n\n- Run with `RUST_BACKTRACE=1` for full backtrace\n- Use `RUST_BACKTRACE=full` for even more detail\n- Check for unwrap() calls that might panic\n\n**Unexpected behavior**\n\n- Add debug prints liberally\n- Check permission grants - many features require explicit permissions\n\n### Getting Help\n\n- Check existing issues on GitHub\n- Look at recent PRs for similar changes\n- Review the Discord community for discussions\n- When in doubt, ask! The maintainers are helpful\n","category":"root","tokens":2966}]}