SKILL.md
1,264 tokens · o200k_base · 5,233 bytes
Source excerpt starting at line 1.---name: node-compatdescription: Run a Node.js compatibility test, diagnose failures, and either fix the implementation, skip, or ignore the test. Use when asked to work on node compat tests.argument-hint: <test-name>allowed-tools: Bash Read Write Edit Glob Grep Agent--- # Node Compat Test Work on Node.js compatibility test `$ARGUMENTS`. ## Step 1: Build and run the test ```sh./x build./x test-compat $ARGUMENTS``` If the test passes, report success and ensure test is specified in`tests/node_compat/config.jsonc`. ## Step 2: Diagnose the failure Read the test file to understand what it tests: ```sh# Tests live under tests/node_compat/test/``` Use `Grep` and `Read` to find the test source, then analyze: 1. **What Node.js API or behavior is being tested?**2. **What is the actual error or assertion failure?**3. **Where is the relevant Deno implementation?** Check `ext/node/` (polyfills, ops, internal bindings), `runtime/`, or `cli/`. Read the corresponding Node.js docs and/or source code to understand theexpected behavior. ## Step 3: Classify the failure Determine which category this failure falls into: ### A. Fixable bug The Deno implementation is wrong or incomplete, but can be corrected. Thisincludes: - Missing method/property on a polyfill- Wrong return value or error type- Missing event emission- Incorrect argument handling- Hard-to-fix but still fundamentally implementable behaviors **Action:** Fix the implementation (Step 4). ### B. Inherent incompatibility The test relies on Node.js internals or architecture that Deno fundamentallycannot or will not support: - `internalBinding()` calls to Node's C++ layer- Node.js-specific CLI flags (`--inspect`, `--prof`, etc.)- V8 internals exposed through Node-specific APIs- Node.js-specific build/addon tooling (node-gyp internals)- Tests for Node.js's own test infrastructure **Action:** Ignore the test with a reason (Step 5). ### C. Not worth fixing The test exercises an edge case or behavior that is technically possible butprovides negligible value: - Extremely obscure error message wording differences- Node.js-specific deprecation warnings- Behavior that no real-world code depends on **Action:** Ignore or skip the test with a reason (Step 5). ## Step 4: Fix the implementation If the failure is fixable: 1. Locate the relevant code in `ext/node/` (or elsewhere).2. Implement the fix. Match Node.js behavior - check Node.js docs and/or source code, not just what "seems right."3. Use lazy-loaded imports where possible.4. Use primordials for internal JS code to avoid prototype pollution.5. Rebuild the source code with `./x build` - this is paramount, changes won't take effect until you do.6. Re-run the test to verify the fix: ```sh./x test-compat $ARGUMENTS``` 6. Once the test passes, make sure the test is listed in `tests/node_compat/config.jsonc` with an empty config: ```jsonc"category/test-name.js": {}``` The entries in `config.jsonc` are sorted alphabetically within their category.Place the new entry in the correct position. ## Step 5: Skip or ignore the test If the test cannot or should not be fixed, update`tests/node_compat/config.jsonc`. ### Ignore (test should never run — inherent incompatibility) ```jsonc"category/test-name.js": { "ignore": true, "reason": "Brief, specific explanation of why this can't work in Deno"}``` `"reason"` must be specified otherwise the lint step will fail! ### Platform-specific skip If the test only fails on certain platforms: ```jsonc"category/test-name.js": { "windows": false}``` ### Expected failure (test runs but fails with known output) If you want the test to run but expect a specific failure: ```jsonc"category/test-name.js": { "exitCode": 1, "output": "[WILDCARD]specific error message[WILDCARD]", "reason": "Brief explanation of why this fails"}``` This is a good middle ground for tests that are generally compatible but have aspecific known issue. If a fix is ever done this assertion will notify theimplementer to update the config. ### Writing good reasons Reasons should be specific and actionable. Good examples: - "Tests Node.js internal C++ binding (internalBinding('zlib').Zlib) which is not implemented in Deno"- "requires `deno --interactive` flag (not yet implemented)"- "URL.createObjectURL does not throw ERR_INVALID_ARG_TYPE for non-Blob arguments" Bad examples: - "Not supported" (too vague)- "Doesn't work" (says nothing)- "Node-specific" (which part?) ## Step 6: Verify Re-run the test one final time to confirm the outcome matches expectations: ```sh./x test-compat $ARGUMENTS``` ## Config reference The full schema for `config.jsonc` entries is in`tests/node_compat/schema.json`. ## PR title conventions When opening a PR for node-compat work, use the appropriate prefix: - `test:` — when the PR only updates `tests/node_compat/config.jsonc` to skip, ignore, or otherwise reclassify tests without changing implementation code.- `fix(ext/node):` — when the PR actually fixes the implementation so a previously failing test now passes (typically changes under `ext/node/` plus enabling the test in `config.jsonc`).
Discovery context
Discovered by repository scan. No exact path reference found in the snapshot’s root CLAUDE.md.