JS: native package-lock.json regeneration without executing npm

[timtebeek]

Motivation

• When a dependency recipe edits a package.json, the sibling lock file must be regenerated to match. That previously ran npm install --package-lock-only --ignore-scripts --legacy-peer-deps in a temp directory — which fails at fleet scale for environmental reasons unrelated to the edit (npm missing from the worker, registry credentials not reaching the sandbox), leaving the manifest changed and the lock stale with only truncated subprocess stderr to act on (moderneinc/customer-requests#2893).

• This PR replaces the npm shell-out with a native Java engine — no node or npm execution anywhere in the regeneration path — applying the approach shipped for Python in Python: native Pipfile.lock and uv.lock regeneration without executing package managers #8283/Python: native poetry.lock and pdm.lock regeneration without executing package managers #8285/Python: native uv.lock delta resolution (greedy-forward resolver) #8292. Design and constraints are in ADR 0011 (submitted as Proposed; acceptance is part of this review). Yarn Classic/Berry, pnpm and Bun keep the shell-out until they go native; the npm shell-out is deleted, not kept as a fallback.

Why npm is tractable (and where it is not)

• One registry request per moving package. The full packument carries each version's dependencies, engines, license, funding, bin and dist.integrity — npm itself resolves with fullMetadata: true (verified in arborist). No tarball is ever downloaded; Python's metadata ladder has no analogue here.
• The lock records the requested state. The root "" entry mirrors the manifest's dependency blocks, so the edit set falls out of a diff with no external oracle — and diffing against the lock (not the pre-edit manifest) means an earlier recipe's edit in the same run is reconciled too.
• Emission is deterministic. npm writes the lock via json-stringify-nice(data, swKeyOrder, indent) — a full-document re-serialization. The writer ports it exactly, including an Intl-collator-equivalent key comparator pinned by Node-generated vectors, so untouched entries are preserved byte-for-byte by construction.
• The hard part is placement. package-lock.json records a physical node_modules tree; whether a package lands hoisted or nested is arborist's placeDep decision. Everything that would require placing or displacing packages fails loud.

Accuracy contract

Ported from ADR 0009 and held by construction:

1. Byte-identical to npm for every edit the engine performs — asserted against goldens recorded from real npm 11.17.0.
2. Minimal change — only the edited package and what its requirements force actually move.
3. Fail loud, never guess — anything unprovable emits no lock and a structured failure; the manifest edit still applies, and CI's npm ci catches the stale pin (the defer-to-CI composition from ADR 0010).

Handled natively: version moves proven in both directions (the new version's requirements resolve satisfied from its location with nested copies shadowing and overrides substituted, and every dependent that resolved the old copy still accepts the new version); removals with an orphan sweep and dep-flag recoloring via arborist's own calc-dep-flags algorithm (applied only where the edit changed an entry's color — pre-existing drift is never rewritten as a side effect); top-level additions that fit without displacement; range edits the current pin already satisfies (zero network); version selection matching npm-pick-manifest's latest-dist-tag preference.

Fail-loud: cascading placement, peer conflicts, workspace and link: locks, git/file/alias/tarball specs, bundled dependencies, lockfileVersion < 3, override edits that move a pin (the recorded override fixture shows npm re-places overridden copies — nesting them under dependents — rather than substituting in place), and any lock failing the parse→emit round-trip check.

Summary

• internal/semver — node-semver versions/ranges ported from npm/node-semver's desugaring pipeline, driven by its own fixture corpus (200 transposed rows) plus the prerelease-exclusion rule.
• internal/registry — packument client on the run's HttpSender; .npmrc resolution mirroring npm (scoped registries, the npm-registry-fetch auth-key walk, ${VAR} expansion failing only when used); host overrides via JavaScriptExecutionContextView + NpmRegistryCredentials (the MavenExecutionContextView pattern).
• internal/npmlock — NpmLockWriter (byte-exact emission), NpmLockTree (visibility-walk edge resolution, calc-dep-flags port doubling as the reachability sweep), NpmLockEngine (orchestration), all behind the existing LockFileRegeneration seam.
• Failure surface — Result gains a structured Failure{reason, package, registry, detail}; failures warn both the manifest and the unchanged lock file and land in a new NodeLockRegenerationFailures data table, so fleet-scale runs can aggregate why locks did not regenerate — and size the next phase (cascade/placement) on data, per ADR 0010's sizing-before-building sequence.

Two deliberate, environment-decoupling divergences from a local npm run (documented in the ADR): engines-based version deprioritization is ignored (npm's depends on the locally running node version), and v1/v2 locks fail loud instead of being wholesale-rewritten to v3 as modern npm would.

Tests

All offline, pure JVM — no node, npm, or network at test time:

• Scenario goldens recorded from real npm 11.17.0 (src/test/resources/npmlock/, regenerable via record.sh): before/after manifests, before/after locks, and full packuments captured together. The engine's output is asserted byte-identical to npm's for upgrade, range-edit, removal-with-orphans, upgrade-with-orphans, leaf-add, dev-recoloring, and scoped-package scenarios; a routed HttpSender asserts exactly the expected requests and nothing more.
• node-semver conformance via the upstream fixture corpus; collation pinned by Node-Intl-sorted vectors; round-trip byte identity over every recorded lock.
• Recipe-level: full scan → edit → regenerate → marker-overlay flow, including the failure path asserting warnings on both files plus the data-table row.
• Registry config: scoped registries, auth-key walk, base64 _password, env expansion, view overrides.

Known follow-ups

• Cascading upgrades and additions requiring placement (the arborist placeDep/canPlace semantics) — the data table will size demand first.
• pnpm / Yarn Classic native engines on the same layers; Yarn Berry is constrained by its zip-repack checksum (see ADR 0011).
• UpgradeTransitiveDependencyVersion (overrides) currently always defers to CI for npm, since override moves are placement.