CodeVetter · Repo Unpack · Contributor handoff
nodejs/node
Read `AGENTS.md` first — it is binding policy, not advice, and it forbids an agent from pushing, opening PRs, or posting comments without active human oversight. Code style in `lib/` is not ordinary JavaScript: everything goes through `primordials` to be immune to user monkey-patching, and a custom ESLint plugin enforces it. Before editing, understand that `lib/` is snapshotted at build time, so top-level side effects in bootstrap files have outsized consequences. Nothing in `deps/` should be hand-edited. The realistic verification loop is a full build followed by targeted `tools/test.py` runs, not a fast unit-test cycle.
- `AGENTS.md` requires `Signed-off-by:` from the human contributor and an `Assisted-by: <agent name>` annotation, and explicitly prohibits `Signed-off-by:`/`Co-authored-by:` naming an agent, pushing to any branch or tag, and creating unsupervised PRs or issues.
- Read these first, in order: `AGENTS.md`, `CONTRIBUTING.md`, `doc/contributing/primordials.md`, `doc/contributing/cpp-style-guide.md`, and `lib/internal/bootstrap/node.js` (whose header comment is the best single explanation of startup ordering).
- Every file in `lib/` destructures from `primordials` at the top (`ArrayPrototypePush`, `StringPrototypeStartsWith`, `ObjectFreeze`, …) instead of using built-in methods directly; new code must match this or `tools/eslint-rules` will reject it.
- Never hand-edit `deps/`: `deps/crates/Cargo.toml` states 'This manifest is generated by node-core-utils. Do not modify it directly', and dependency bumps are driven by `tools/dep_updaters/` and scheduled workflows.
- Anything added to `lib/internal/bootstrap/` must be synchronous and must not read argv or env at top level, because it is executed at snapshot-build time; runtime-dependent setup belongs in `pre_execution.js` or a `lib/internal/main/` script.
- Verification loop: `./configure && make -j<n>` then `python3 tools/test.py parallel/test-<pattern>` for targeted runs; full validation is `make test-only` (build addons + cctest + jstest + tooltest without rebuilding docs).
- Lint before proposing a change: `make lint` runs js/cpp/md/yaml; `make lint-ci` adds Python lint and a merge-conflict-marker scan across `benchmark deps doc lib src test tools` that fails the build on stray `<<<<<<<`/`>>>>>>>`.
- Safe edit boundary: a feature that is JS-only (a new provider, a runner reporter, a stream helper) can be added without touching C++. Anything needing a new syscall, a new option, or a new permission scope requires coordinated edits across `src/node_options.{cc,h}`, `src/node_binding.h`, and `pre_execution.js`. (inferred)
- Trap: options are read twice — once at parse time into `EnvironmentOptions` and again in JS via `getOptionValue()` after `refreshRuntimeOptions()`. Caching an option value at JS module scope before that call yields a stale snapshot-time value.
- Trap: `permission.js` memoizes `_permission`, `_audit`, and `_ffi` on first read, so an option consulted before `refreshRuntimeOptions()` is frozen for the process lifetime.
- Trap: worker option state is not the main thread's — `src/node_worker.cc` overwrites `vfs_load` to false per worker, so a JS-side `getOptionValue('--vfs-load')` reasoning must account for thread identity.
- Trap: `test/ffi`, `test/sqlite`, `test/addons`, `test/js-native-api`, and `test/node-api` all need a build step (`make build-ffi-tests`, etc.) before `tools/test.py` will pass on them; failures there on a fresh tree usually mean 'not built', not 'broken'.
- CI asserts the tree is unchanged after tests run, so any test that writes into the repo (rather than a tmpdir) will fail the Linux workflow even if the assertions pass.
- Use `test/common/index.js` capability predicates (`hasFFI`, `hasDtls`, `hasQuic`, `hasSQLite`, `hasTemporal`, `hasCrypto`) to guard new tests for conditionally-compiled features rather than assuming a full-featured build.
- Public API changes are incomplete without the matching `doc/api/*.md` page and YAML metadata block (`added: vX.Y.Z`, `Stability: 1 - Experimental`), as every subsystem in this tree carries one.