yarn.lock: you can't `sed` a graph

After the first workarounds, a lockfile-graph library appeared — and it changed what a fix even is: not a text edit, but graph surgery. How lockgraph rebuilt yarn-audit-fix from the inside, down to the unglamorous work of emitting a file that still installs.

• yarn audit [still does not] fix
• yarn.lock: you can't sed a graph
• yarn.lock: may the --force be with you

TL;DR

• A lockfile fix is not string replacement. Bump a package and its transitive closure can change, its checksums change, and the file still has to reproduce under --immutable. Miss any of those and you've shipped a lockfile that doesn't install.
• lockgraph parses every Yarn lockfile — Classic (v1) through Berry (v4–v10, Yarn 2 onward) — into one dependency graph; the fix is a transformation on that graph, serialized back to the original format. Registry-only, spawn-free — no npm/yarn child process.
• The hard part is the closure: re-resolve the upgraded node's dependencies the way yarn install would — honoring a project's declared resolutions pins rather than silently resolving around them — and recompute checksums, so the result passes yarn install --immutable.
• Field proof: a real monorepo build broke because a simple-git bump needed two sub-packages it never received. The graph model adds them.

Recap: the wall

Part 1 ended on the difficulty that actually matters:

Bump one entry and its transitive dependencies should change too — but Yarn doesn't reload a patched entry's dependencies for you. A correct fix has to re-resolve subtrees against the registry and keep the lockfile internally consistent and deterministic. With PnP and Yarn's strict linker, a naive in-place edit yields an install that doesn't reproduce.

A lockfile isn't a list of versions; it's a resolved graph — every package, every edge, pinned and checksummed so an install is byte-reproducible. "Fix the vulnerability" means edit the graph and keep it resolved. A sed one-liner gives you a file that lints fine and installs wrong: you can't sed the graph underneath it.

So we stopped editing text and started editing the graph.

One graph for every Yarn lockfile

Underneath the tool is a separate, single-purpose library — lockgraph — whose only job is to turn lockfiles into a graph and back:

detect(text)            → which format is this?
parse(text, format)     → a dependency Graph (nodes = packages, edges = ranges)
…transform the graph…
stringify(graph, format) → text in the SAME format, quirks preserved

The formats it round-trips for us: Yarn Classic yarn.lock (v1) and Yarn Berry (the v4 through v10 schemas, Yarn 2 onward). One model, many serializers. That's the leverage: the fix is written once, against the graph, and every Yarn schema gets it. The serializer's job is to be boring — emit the exact dialect Yarn expects, down to key ordering and quoting, so a clean tool run produces a diff that's only the fix.

The same library also round-trips npm, pnpm, bun, and Deno locks through one model, but that breadth is its own story. Here, every lock is a yarn.lock.

A node is a resolved package (lodash@4.17.20, with its integrity, its dependency ranges). An edge is "this descriptor (lodash@^4) resolves to that node." Once the file is a graph, a security fix is just graph surgery: move a node, rewire its edges, complete what's now missing, drop what's now orphaned.

The pipeline

Five steps, all over HTTP to a registry, no subprocess.

1. Advisories, straight from the registry

The library hands us the package set that actually needs auditing — graph.registryPackages() — which is locator-aware: it skips workspace members, link: / portal: / patch: / file: / git: entries, and anything whose version isn't real semver. Those can't have a registry advisory and shouldn't be POSTed.

That set goes to the registry's bulk audit endpoint (/-/npm/v1/security/advisories/bulk), chunked, over plain HTTPS — the same endpoint yarn npm audit proxies, talked to directly. Auth is resolved from your project config (.npmrc, .yarnrc.yml, env), host-bound and https-only: a token declared for one registry is never attached to a request to another host, and never sent over http. Scoped packages route to their own registry with their own credential.

What comes back is normalized into a report: severity and CVSS, the GHSA/CVE refs, and — because advisory ranges are the awkward data from Part 1 — a patched range derived from the vulnerable one. --audit-level and --ignore (npm id or GHSA) filter here. When a package carries several advisories they merge: the vulnerable ranges OR together, the patched ranges AND together.

2. Choosing the fix version

For each vulnerable node we ask the registry for the lowest published version that clears the merged advisory set. Lowest, not latest — the smallest move that makes you safe is the least likely to break you.

"Lowest that clears the merged set" has a subtlety worth showing. Take lodash at 4.17.20 with five advisories. If four are fixed by 4.17.21 but one is only fixed in 4.18.0, the AND of their patched ranges is >=4.18.0, and the lowest version satisfying that is 4.18.0. So the tool lands on 4.18.0 — not because it prefers newer, but because that's the floor where every advisory is cleared at once.

Then the compatibility gate, which is the default safety rail: a fix is applied only if the new version still satisfies every surviving consumer's declared range. If clearing the advisory requires a cross-major jump that breaks a parent's ^x range, the default declines and reports it rather than quietly breaking your build — and --force is there for when you've decided to take the major bump.

There's a second rail alongside consumer ranges: a project's own resolutions. Pin a transitive version deliberately, and a fix that ignored that pin would emit a lockfile contradicting its own package.json. So resolutions bound the remediation too, and yaf takes the same line npm audit fix --force takes with a user's override. A pin holding a version the fix can't satisfy is authoritative: yaf leaves it and reports it, never silently rewriting your pin. A pin whose range still admits the fix is honored — the fix resolves within it. Either way the emitted lock agrees with what yarn install would produce. This is where modeling pays off: the graph library treats resolutions as first-class constraints rather than a special case bolted onto the patcher, so "don't violate a known pin" is a property of the resolution step, not an afterthought.

3. The transformation

Now the graph surgery, in three moves.

Rebind (modify with a replaceVersion operation): add the patched node and redirect the edges that pointed at the old one onto it. The operation reports back what it disturbed — which nodes it just added, which it left orphaned — and that report seeds the next step.

Complete the closure (complete): this is the step the naive tools skip and the one Part 1 called the hard part. The new version's own dependencies may differ from the old one's. So we walk the newly-added nodes, fetch each one's metadata, and for every dependency it declares we either reuse the resolution the lock already records for that descriptor or resolve a new one and wire it in. And those new nodes have new dependencies of their own — so it's re-resolution, then re-resolution of whatever that dragged in, and again, until a pass turns up nothing new.

Crucially, new descriptors resolve to the highest published version that satisfies the range — because that's exactly what a fresh yarn install would pick. Match that policy and the lockfile you emit equals the lockfile Yarn would compute; diverge from it and --immutable rejects you. (More on that below.)

Here's the field case, concretely. A monorepo build broke with:

Error: Cannot find module '@simple-git/args-pathspec'

simple-git past 3.34 had split its argument handling into two new packages. A version-only bump moved simple-git and left the lockfile believing it had no new dependencies — so the install never fetched them. Before:

"simple-git@npm:^3.10.0":
  version: 3.24.0
  dependencies:
    "@kwsites/file-exists": ^1.1.1
    # …no @simple-git/* — they didn't exist yet at 3.24

After the graph fix:

"simple-git@npm:^3.10.0":
  version: 3.36.0
  dependencies:
    "@kwsites/file-exists": ^1.1.1
    "@simple-git/args-pathspec": ^1.0.3   # ← re-resolved + wired
    "@simple-git/argv-parser": ^1.1.0     # ←

"@simple-git/args-pathspec@npm:^1.0.3":   # ← added to the graph
  version: 1.0.4
"@simple-git/argv-parser@npm:^1.1.0":     # ←
  version: 1.1.1

Prune (pruneOrphans, an option of the same completion pass): the bump can also strand a subtree — the old version's unique dependencies, now referenced by nothing. Those get garbage-collected. With one guard that took a round of debugging to get right: a real lockfile already contains "danglers" — entries with no incoming edge that Yarn nonetheless keeps. If the prune is too eager and GCs those, yarn install --immutable notices the file changed and fails (YN0028). So the prune starts only from what the fix itself stranded — nodes that had an incoming edge before the bump and have none after — and cascades from there. A dangler that was already there never enters the sweep.

4. Making it reproduce: checksums

A Berry entry carries an integrity checksum; a freshly-added node doesn't have one yet, and a lock with the line missing isn't finished — the next install writes it in and leaves your tree dirty. So the last step (refurbish) fetches each new package's tarball and recomputes the hash.

That's harder than it sounds. Berry's checksum isn't the tarball's hash: it's computed over the package's cache archive, a zip whose bytes depend on how Yarn compressed it — the lock's cacheKey. To reproduce it you rebuild that archive the way Yarn would: with a pure-JS deflate where the layout is known to be reproducible, and with Yarn's own zip layer (@yarnpkg/libzip) where it isn't. Before trusting either, the tool proves the recipe on a package your lock already has a checksum for — rebuild it, compare — and fills the new ones only on a match.

When that proof fails — no fetchable tarball, or a compression profile it can't match byte-for-byte — it doesn't write a wrong checksum: it omits those lines and says so, naming the reason:

Could not compute checksums for N package(s) (tarball-unavailable: N) —
run `yarn install` to finish the lockfile.

A plain yarn install recovers every one of them in a single pass, changing nothing else. It's the one place the user's own yarn can re-enter the loop — only for checksums the tool couldn't prove — and it's the same two-step the maintainers' own muscle memory already expects: apply the fix, then install.

5. The invariant

Put the pieces together and you get the property the whole design is for:

The patched lockfile resolves exactly as Yarn would and, with every checksum in, passes yarn install --immutable with no rewrite.

That holds because of three choices that have to agree: completion resolves to the highest satisfying version (= what yarn install picks), the prune leaves pre-existing danglers alone (= what Yarn keeps), and checksums are recomputed and proven, never guessed (= what Yarn verifies). Break any one and immutable mode catches it.

Does it actually reproduce? A real-world test

The simple-git break above came from a real qiwi/mware build (PR #275). So that's where we test the claim, on the real repo, at the commit before the fix:

1. Check out the pre-fix commit in a throwaway worktree. simple-git is 3.24.0; the @simple-git/* packages are absent.
2. Run yarn-audit-fix. It bumps simple-git to 3.36.0 (plus fifteen other fixes), completes the closure — the two sub-packages appear and are wired in — and recomputes the checksum of every package it added.
3. Verify with the user's own Yarn: straight to yarn install --immutable, on a cold cache.

The result that matters: --immutable exits 0 and leaves the file byte-for-byte as it was, no YN0028. And every checksum the tool computed is the one Yarn writes itself — let Yarn fill them in on the same resolutions and it lands on the identical file, byte for byte. The graph the tool produced is the graph a clean install would have produced, and so is the file.

A note on portability

Registry-only means there's no second package manager to install and nothing platform-specific to shell out to — it's just HTTP and graph manipulation. The graph library assumes as little as it can: fetch is polyfilled (via node-fetch-native) rather than taken for granted, and it runs on Node 14.18. The one piece borrowed from Yarn — its zip layer, the price of byte-exact checksums — is what sets the tool's floor at Node 18.12. yarn-audit-fix declares no engines of its own, so installing it never raises an EBADENGINE on its own behalf.

The side effect: real lockfiles are the test suite

Because the parser is its own library, separate from the fixer, it can run across a large corpus of real-world lockfiles — and real lockfiles are stranger than any fixture you'd think to write. Every odd one in the wild becomes a test you didn't author.

That's how a quiet auth bug surfaced. A .yarnrc.yml declaring a scoped registry with a token was dropping it silently: the registry URL was stored under one normalized form and looked up under another, so the two never matched, and requests to that scope went out unauthenticated with nothing to flag it. No fixture would have guessed the exact URL shape that triggered it; a real config had it. Fixed once in the shared parser, it's gone everywhere that parser runs.

Where this goes

None of this is an argument that Yarn should have shipped audit fix years ago — Part 1 is sympathetic to why it didn't. It's a demonstration that the hard part is tractable outside the package manager: treat the lockfile as a graph, re-resolve instead of replace, and check yourself against --immutable.

There's a catch that reproducibility alone doesn't cover, though: a lockfile can install perfectly and still be the wrong fix — one that needs a newer Node than you target, or a license you don't allow, or a version outside a range you pinned on purpose. Making the fix not just reproducible but right for your project is its own problem.

Sources / links

• The library: lockgraph — parse / stringify, and the modify / complete / refurbish operations the pipeline drives; the cross-format conversion + loss reference is CONVERT.md.
• The tool: yarn-audit-fix (npm).
• Earlier notes: Yarn audit fix: workaround, The missing yarn audit fix for Yarn 2+ Berry