# avril's path build

The lexical operations in `lexical.ts` are adapted by hand from Node.js
`lib/path.js` at v22.16.0 (commit
`9774069718d9f80578079d252dddf37ae6fd550d`, tag `v22.16.0`, `2025-05-21`),
whose MIT license and copyright header are preserved at the top of that
file. `urls.ts` (file URL conversion) is original avril code; its behavior
follows Node's `fileURLToPath`/`pathToFileURL` and the WHATWG URL standard
where noted in `docs/path.md`.

There is no pristine upstream copy or patch file here: only the path
algorithms and minimal input validators were carried over, not Node's
`internal/constants`, `internal/validators`, `process`, or `glob` support,
so a mechanical patch would be mostly deletions. `lexical.ts` keeps the
upstream structure and explanatory comments to stay comparable with the
source; local differences from upstream are:

- `process.cwd()` is avril's permission-checked `op_process_cwd`, called
  only when relative, root-relative, or drive-relative input actually needs
  it. Fully qualified inputs need no read grant, and a missing grant throws
  the usual `PermissionDenied` instead of being swallowed.
- `process.env[`=${device}`]` (Windows per-drive directories) is not read
  and introduces no environment permission: a requested drive matching the
  working directory's drive reuses it, otherwise resolution falls back to
  that drive's root.
- Explicit POSIX semantics on Windows use Node's POSIX view of the working
  directory (separators converted, drive indicator truncated).
- `validateString`/`validateObject` throw plain `TypeError`s; no error codes.
  `validateObject` rejects functions, like Node's default validation.
- `glob`/`matchesGlob` and legacy `_makeLong` are omitted, as are the
  recursive `win32`/`posix` self-references.
- All builtins used during calls are captured through
  `ext:core/primordials` (extended with the string and array helpers path
  code needs). String splitting uses a small `splitOnChar` helper rather
  than `String.prototype.split`, so a poisoned `Symbol.split` hook on the
  separator cannot dispatch. No `RegExp`, no `for`-`of` over arrays, no
  guest-global lookups.

`urls.ts` captures the WHATWG URL class, its property getters, and the
standard `encodeURIComponent`/`decodeURIComponent` at module scope.
Percent-decoding delegates malformed-escape, overlong, and range validation
to the standard codec (re-wrapped as `TypeError`); NUL bytes and lone
surrogates are still checked explicitly, as is the encoded-separator scan.
The kept-literal ASCII set matches Node's `pathToFileURL` table exactly
(verified differentially over bytes 1-127), with `~` escaped manually
because the standard codec leaves it alone. `api.ts` builds each frozen
variant namespace once so all three entry modules share identity.

To re-verify against upstream:

```sh
git init node && git -C node remote add origin https://github.com/nodejs/node.git
git -C node fetch --depth=1 origin v22.16.0
git -C node checkout --detach -q FETCH_HEAD
diff <(git -C node show HEAD:lib/path.js) exts/path/src/lexical.ts
```

expecting type annotations and the adaptations listed above (plus the wrapper split into
`main.ts`/`posix.ts`/`win32.ts`/`api.ts` and the URL helpers in `urls.ts`).