Module project 

Project-level mutations: operations on a directory that holds a package.json — keep the lock and node_modules/ in step with the manifest (sync), upgrade dependencies within their ranges (upgrade, previewable with plan_upgrade), and remove them (remove).

The manifest/lockfile transforms stay pure in crate::package_json; this module is the file IO + orchestration that composes them with crate::registry resolution and crate::install, the same way the CLI’s add / upgrade verbs do. Each mutating call rewrites package.json and a fresh v3 package-lock.json, then installs the locked tree (every tarball sha512-verified).

Structs

Change

A single dependency version-range change — the unit of an upgrade plan (from → to).

Functions

bump_floor

For a caret/tilde range, return it with the floor set to version (^3.1.0 + 3.4.2 → ^3.4.2). None for any other shape (exact pin, *, comparator range) — left as written.

plan_upgrade

Compute the upgrade plan without writing anything (the dry-run): for each selected registry dependency, re-resolve within its range and, when the range floats (^/~), bump its floor to the resolved version. An empty packages means every dependency; exact pins and complex ranges are left untouched (npm honors them too), so they never appear as a Change.

read_manifest

Read and parse <dir>/package.json, erroring clearly if it is missing or not a JSON object.

remove

Remove dependencies (= npm remove): drop each named dependency from package.json, rewrite the lock, and reinstall the resolved tree. Returns the names actually removed (a name absent from dependencies is skipped) and the reinstalled tree.

sync

Make package-lock.json + node_modules/ a function of the manifest: write a fresh v3 lockfile from the resolved registry dependency tree (licenses per detail), then install from it (every tarball’s sha512 verified). Returns the installed packages. Non-registry deps (git/file:) are recorded in the manifest but not resolved.

upgrade

Upgrade dependencies within their ranges (= npm update): compute the plan (plan_upgrade against the public registry), apply each Change to package.json, then sync. Returns the applied changes and the freshly installed tree. A run with no floating updates leaves package.json byte-identical — the manifest is rewritten only when a range actually changed.

write_manifest

Write a manifest back as pretty JSON (npm’s two-space indent + trailing newline).