feat(npm): experimental Yarn PnP zero-install support

[mh0pe]

Summary

This is an experimental Yarn PnP zero-install importer. rules_js never runs
Yarn and never synthesizes a node_modules tree. The caller supplies labels
for the checked-in yarn.lock, .pnp.data.json, .pnp.cjs,
.pnp.integrity.json, .yarnrc.yml, cache archives, and any unplugged runtime
files.

Repository analysis parses Yarn Berry lockfile versions 6, 8, and 10 and
cross-validates the generated PnP graph: roots and top-level fallback state,
dependency edges and aliases, virtual-to-physical locators, link types, cache
and unplugged locations, and lockfile bindings. It generates
pnp_js_binary / pnp_js_test wrappers plus pnp_verify_test.

The integrity manifest binds file type, executable mode, and sha512 for the
resolver, graph, config, lockfile, every cache archive, and every referenced
unplugged file. Runtime verification happens before .pnp.cjs is loaded,
rejects noncanonical or escaping paths and source symlinks, checks exact cache
and unplugged tree membership, and independently checks lockfile checksums when
present. Valid lock entries without a checksum remain protected by the
integrity manifest; an active unplugged package may retain one matching
lock-backed source archive.

Version support

• Yarn 4.18.0 / lockfile v10: import, verification, and runtime execution,
  covered by e2e/pnp_zero_install with real peer-virtualized React packages
  and an unplugged package.
• Yarn 3.8.7 / lockfile v6: import and verification, covered by
  e2e/pnp_zero_install_yarn3. Yarn 3 runtime execution under Bazel is not
  claimed; the fixture README documents the generated runtime's multi-path
  recursion limitation.
• Lockfile v8 remains supported by the parser and unit coverage.

Known limitations: CommonJS PnP only (.pnp.loader.mjs / ESM is not yet
supported), Yarn-generated cache and unplugged path conventions are recognized
rather than invented, and these wrappers do not compose with rules that
require a linked node_modules layout.

Changes are visible to end-users: yes

• Searched for relevant documentation and updated as needed: yes (fixture
  READMEs and inline API documentation)
• Breaking change (forces users to change their own code or config): no
• Suggested release notes appear below: yes

Suggested release note: experimental support for consuming integrity-bound
Yarn PnP zero-install projects in Bazel without executing Yarn or creating a
node_modules tree.

Test plan

Fresh direct validation on the final reconstructed tree:

• Buildifier 8.2.1 format check and lint: passed for all 11 authored
  Starlark/BUILD files.
• node --test npm/private/pnp/pnp_verify_test.mjs: 14/14 passed, including
  corrupted archives, graph/config mutation, executable-mode binding, path
  traversal, source symlinks, and exact unplugged-tree controls.
• Both integrity manifests regenerate byte-for-byte; direct verification
  passes for the Yarn 4 and Yarn 3 fixtures.
• Yarn 4.18.0: install --immutable --immutable-cache --check-cache passed;
  yarn node main.js printed pnp-zero-install-ok.
• Yarn 3.8.7: install --immutable --immutable-cache --check-cache passed
  (import/verification support only).
• git diff --check, Git object connectivity, and clean-worktree checks
  passed. Read-only self-review found and fixed a standalone-verifier ..
  path traversal mismatch; no P0/P1/P2 findings remain.

Earlier focused, forced-uncached Bazel 7.7.1 validation executed 13/13 focused
tests (126 packages, 7,555 configured targets, 51.009s). That run predates the
final formatting, copy-mode, and path-traversal hardening, so it is supporting
evidence rather than a final-head Bazel result.

The full Yarn 4 //... gate is not claimed green. After repairing the
local Node cache artifact, the final authorized warmed run on the HFS-backed
workspace emitted zero package, target, action, or test progress for 30
minutes and was stopped by its exact process handle (exit 143). This is
qualified as a local Bazel/filesystem infrastructure block; the direct gates
above are the current final-head evidence.

[CLAassistant]

All committers have signed the CLA.

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 9bc6ffccd1

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[jbedard]

Why? Does modern yarn provide a strict lockfile describing the exact structure of node_modules similar to pnpm? Seeing 3000 line .js files implies no to me, and I would not want to support such a feature.

[mh0pe]

You’re right on the core distinction: modern Yarn pins the logical resolution graph, not the exact physical node_modules topology. The final representation is derived from the lockfile together with manifests, configuration, the selected linker, and the Yarn version.

This PR compensates by running pinned Yarn to export a stricter graph and verified archives, which explains the adapter size and creates a larger maintenance boundary than the original description made clear. I don’t think this broad exporter is appropriate to merge upstream as-is, so I’ve updated the description to say that explicitly and will keep this implementation in the fork.

If Yarn support is potentially in scope, I can instead open a small design proposal for a PnP-focused importer based on Yarn’s generated PnP representation and checked-in cache, without asking rules_js to maintain this exporter.

[jbedard]

rules_js should never run yarn, running pnpm to convert yarn to pnpm-lock is an edge case we handle but not part of the standard workflow

If we support yarn the lockfile must be deterministic without any rules_js logic deciding the node_modules layout which I assume is what a lot of this PR is doing

[mh0pe]

@jbedard Took your last comment as the spec and replaced this PR's content entirely —
code instead of the design proposal I'd offered. The exporter is gone.

What's here now is a PnP zero-install importer: rules_js never executes yarn,
and nothing in rules_js decides a layout. The developer checks in what
yarn install generated (.pnp.data.json, yarn.lock, .pnp.cjs, the cache
zips), Starlark cross-validates the data file against the lockfile, and a
generated test re-hashes every cache archive against yarn.lock at build time.
Under PnP there's no node_modules for anyone to decide — the checked-in
registry is the layout, reviewed the same way pnpm-lock.yaml is.

Authored surface is ~1,100 lines; the diff looks bigger because two
Yarn-generated .pnp.cjs e2e fixtures are checked in. Yarn 4 is supported
end-to-end including runtime under Bazel (tested on 7.7.1 and 8.4.2); Yarn 3
is import/verify only, for a reason documented in the fixture. Honest gaps:
CJS-only runtime so far, and it doesn't compose with node_modules-shaped
rules yet.

Apologies for the force-push over the old review context — the previous
architecture wasn't worth preserving in the diff. If this shape is worth
reviewing I'll take it wherever you want it to go; if it's still out of
scope, say so and I'll close. I'm trying to avoid maintaining a fork for the #2 package manager in the JS ecosystem.