ADR 0015: Vendor Node’s lib/path.js and the passing subset of Node’s tests

  • Status: accepted (2026-10-21)
  • Context:
    • The quality bar for ClientVM includes a ported subset of Node’s own test/parallel suite run against the compat layer.
    • Seeded fuzzing (5b) of path.win32 against Node 24.11 kept finding divergences in edge cases: reserved device names, the CVE-2024-36139 drive-letter guard, and UNC roots. Each fix to our port was a new chance to differ.
    • path is pure string code with no I/O, so Node’s own source runs unchanged in a browser.
  • Decision:
    • path: scripts/vendor-node-path.mjs downloads lib/path.js from the v24.11.0 tag and checks its SHA-256. It wraps the file in a factory and writes packages/node-compat/src/vendor/node-path.ts, which is not edited by hand. packages/node-compat/src/path.ts supplies what the file imports from Node’s internals: a small primordials shim, the argument validators, process.cwd(), and the glob matcher.
    • Tests: scripts/vendor-node-tests.mjs takes a discovery run’s results and copies the passing tests from Node’s test/parallel into test/conformance/node-tests, unmodified. It also copies test/common, the fixtures those tests reference, and Node’s LICENSE. test/e2e/node-tests.spec.ts runs all of them in CI, so a test that stops passing fails the build.
    • Vendored files keep Node’s license (MIT) and are excluded from formatting, linting and the SPDX header check. NOTICE credits them.
  • Consequences:
    • path behaves like Node 24.11 by construction. Upgrading Node means re-running the script with a new tag and hash.
    • The test subset is a ratchet: it only grows when a discovery run is re-vendored. Pass rates per module are published in compatibility.md.
    • The repository carries about 3.4 MB of Node test files.

Edit this page on GitHub ↗Markdown