yarn.lock: may the `--force` be with you

Part 2 brought Yarn level with npm audit fix; this part goes past it. --force is the one move npm already had — the rest is new: gate a fix on the Node you target, the licenses you allow, the module format it must keep, and scope it to production, or to the one workspace you're touching.

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

TL;DR

• "Lowest version that clears the advisory" (Part 2) is necessary, not sufficient: that fix — or the closure it drags in — can need a newer Node than you target, a license you don't allow, or fall outside a range you pinned. --immutable won't catch it — it checks the lockfile reproduces, not that the result runs or complies.
• Landing a fix is a dial. --force bends ranges and rewrites package.json to force a patch in; the opt-in constraints — --engines, --license, --package-type — pull the other way, applying a fix only if it won't introduce a new break, and --safe flips the automatable ones on together. The contract is guarantee-or-flag: a compatible fix or an attributed skip, never a silent incompatible one.
• Two more knobs narrow which advisories, not just how a fix resolves: --production skips dev-only vulnerabilities (they never ship), --workspace scopes a monorepo fix to the packages you name.
• Every skip is attributed — the axis, the package, the versions it tried — so you can widen, exclude, or accept. Constraints, --safe, scoping, and precise suppression (--ignore a CVE, --exclude a package) are all things npm audit fix doesn't do: this is where yaf leads it, not mirrors it.

The fix that installed clean and broke anyway

Part 2 ended on a strong claim: the patched lockfile passes yarn install --immutable, byte-for-byte what Yarn would compute. That invariant is real, and it's the whole design — but it's worth being clear about what it doesn't promise.

Immutable mode is a reproducibility oracle. It verifies that the lockfile agrees with itself and with your manifests — same versions, same checksums, no drift. It does not verify that the versions it locked will run. Berry doesn't check a dependency's engines at install at all (npm merely warns, EBADENGINE); licenses aren't its concern either; and a range you declared is checked for consistency, not for whether the fix was a good idea.

A security bump moves a package to its lowest patched version — and that version's dependencies, re-resolved the Part-2 way to the highest satisfying version, pull in a transitive whose recent major quietly dropped old Node support. lru-cache@11 wants Node 20; glob@11, rimraf@6 — same. Your project targets Node 18. yarn install is delighted: the graph resolves, the checksums match, --immutable exits 0. Then CI runs the suite on Node 18 and something three levels down throws SyntaxError on a syntax it doesn't recognize, or the process exits on an engines assertion. The fix was "correct" by every check we'd built — and it broke the build.

We hit exactly this on a real project: clean remediation, green install, and it died on Node 18 in CI. The lockfile was right; the fix was wrong for that project.

So a fix has a footprint beyond the advisory — and the real question is how much of your project it's allowed to reshape to land. That's a dial. At one end, --force: bend a consumer's range, rewrite a manifest, take the major bump — make it fit. At the other, the constraints and --safe: apply a fix only if it leaves your Node, your licenses, and your declared ranges alone. The rest of this part is those two ends, and the default that sits between them.

--force: break to fix

The forceful end of the dial is the oldest flag in the tool, and the bluntest. By default a fix has to fit: it must stay within every surviving consumer's declared range and within the range you declared for a direct dependency in package.json. When it can't — the only patched version is a semver-major that overshoots a parent's ^1, or a dependency you pinned exactly — the default declines and reports, because quietly applying it would hand you a lockfile your own manifests forbid:

Skipped (package.json pins these to a range the fix can't satisfy; re-run with --force …):
  lodash (pinned → "4.17.11" in packages/foo/package.json)

--force overrides that. It takes the cross-major bump past a consumer that wanted the old line, and — the newer half of this — rewrites the direct-dependency range in your package.json so manifest and lockfile agree again ("lodash": "4.17.11" → "4.18.0", "~4.17.0" → "~4.18.0", preserving your operator). In a monorepo it finds the pin in the workspace that declared it and rewrites that file, not the root. Both moves — cross the range, rewrite the pin — are exactly where the community plugin (Part 1) stops: it fixes within a package's range and, when the only patch lies outside it, reports no compatible patched version and gives up on it. --force is the out-of-range flag its roadmap wanted.

It works the same across formats: Berry models workspace→dependency edges in the graph, so its compatibility gate (Part 2) can already see a workspace consumer; Yarn Classic can't, so reading the manifests is the uniform path — and it adds the --force rewrite the edge-only gate never had. Same move as npm audit fix --force, done out loud.

It earns its Star Wars reputation, though. The case against npm audit fix --force is concrete: it installs versions outside your declared ranges — semver-major, 1.2.0 straight to 5.0.0 if that's where the patch lives — so a function you call gets renamed or removed and the app won't start, or starts and quietly returns wrong answers. One forced top-level bump cascades into dozens of moved transitives, each its own chance to break. It can even oscillate — downgrade, upgrade, downgrade — into a lockfile that differs from one run to the next. And a green test suite is thin cover: the real break tends to hide in an integration seam or an edge case that surfaces months later, sometimes as a fresh vulnerability in a version nobody has battle-tested yet.

yaf's --force is that instinct, narrowed. It bumps to the lowest version that clears the advisory, never the latest, so the jump is the smallest one that works; it moves the vulnerable package and re-resolves its closure, not the whole tree; and it stays bounded by the Part 2 reproducibility check and whatever constraints you've set. So --force here means bend the ranges that block this fix, not take the resolver off its leash. Sometimes the real fix is the major bump and you'd rather the tool take it and say so than hand you a red pipeline — but it's opt-in, loud, and paired with an opposite.

--safe: skip to stabilize

That was the forceful end. The other runs on the opposite instinct: when landing a fix would break something new, skip it — leave the vulnerability flagged rather than trade it for a fresh breakage. It's the newer half, and still finding its edges. Before its mechanics, the policy, because it too departs from what npm does, on purpose.

Run npm audit fix and a bump that needs a newer engine still gets applied; you get an EBADENGINE warning and a lockfile that installs. That's the package-manager default: resolve the highest thing that satisfies semver, warn, move on. It's a reasonable default for an always-on installer.

It's the wrong default for an opt-in remediation flag. If you go out of your way to tell the tool "this fix has to run on Node 18," you don't want a warning buried in install output three CI steps later — you want one of two things: a fix that actually meets the bar, or a clear refusal that names what it couldn't satisfy.

So the constraints are off unless you ask; ask, and highest-satisfying-that-also-passes replaces highest-satisfying-and-warn. When nothing passes, the default is to skip that one fix and report it — leave the vulnerability, tell you exactly why — with --on-conflict=stop to turn any such skip into a hard error for a CI gate that must not proceed on a half-fix.

Engines: will the fix run on the Node you target?

yarn-audit-fix --engines.node='>=18'

Reads as: apply a fix only if its completed closure runs on Node ≥ 18. Every newly-pulled transitive is now selected as the highest in-range version whose own engines.node admits your floor. The lru-cache@11 from the opening is rejected for needing Node 20; if an in-range lru-cache@10 line runs on 18, that's what lands. If nothing in range clears the bar, the fix is skipped and attributed (below).

Three ways to name the target, because "what Node do you support" has three real answers:

• A range — --engines.node='>=18'. Explicit, unambiguous, what CI should use.
• Bare — --engines.node, meaning the Node running the CLI. Cheapest, and the report flags that it may differ from your project's target (the classic footgun: you're on 22, prod is on 18).
• floor — --engines.node=floor, meaning the highest engine floor your project already requires. We read the root package.json, every workspace manifest, and every hoisted package in node_modules, take the maximum engines lower bound, and target that. The invariant it encodes: a fix must not raise the floor your tree already stands on. If the tree already needs 18, a fix is fine as long as it doesn't quietly push you to 20.

The check is lenient in the npm sense — a package that declares no engines makes no claim and is accepted (rejecting the silent majority would be useless). And it's not just for node: --engines.npm='>=9' gates the same way on any engine your closure declares.

One subtlety that matters for correctness: the gate covers the fix version itself, not only its closure. Completion re-resolves the transitives, but the package you're bumping to is placed directly — so a fix that lands on a version whose own engines exceed your target would slip past a closure-only check. A pre-apply pass runs the same constraints against the fix version before it's committed; if the fix itself doesn't fit, it's skipped with "the fix version itself is not permitted." Closure and seed, both gated.

Licenses: does the fix pass your policy?

yarn-audit-fix --license.allow=MIT,ISC,Apache-2.0,BSD-3-Clause
# or the other direction:
yarn-audit-fix --license.deny=GPL-3.0

Same machine, different axis: apply a fix only if every new package it pulls in carries an allowed SPDX license (or none of a denied one). A security bump that drags a copyleft transitive into a proprietary codebase is exactly the kind of thing you'd rather catch at remediation time than at legal review.

There's a data wrinkle worth surfacing, because it drove a real change in the pipeline. The registry's abbreviated package document — the compact "corgi" metadata the completion walk fetches for speed — carries engines but not license. So the engine gate is free (it reads metadata we already have), while the license gate has to fetch the full manifest for a candidate to see its license field. The tool exposes that full-manifest fetch through the same scope-aware, host-bound registry client the rest of the pipeline uses, and the license gate reaches for it only when a candidate actually needs licensing — cheap gates first, so a version an in-memory engine check already rejected never triggers a license round-trip.

v1 compares single SPDX ids. An SPDX expression — (MIT OR Apache-2.0) — isn't something a token match can decide: under OR, one allowed license should clear the whole thing, but a naive scan trips on the disallowed half. So rather than guess, an unresolvable expression is treated as unevaluable and, under the "guarantee-or-flag" contract, flagged rather than silently accepted.

Package format: does the fix stay require-able?

yarn-audit-fix --package-type=cjs

A third axis, built on a limit worth stating plainly: we can't verify a change fully, but we can check its consistency. A good chunk of the ecosystem has gone ESM-only — a package flips to "type": "module", drops its CommonJS entry, and now require('that-package') throws ERR_REQUIRE_ESM. A security bump that lands on such a version, or drags one in transitively, breaks every CommonJS require of it at runtime — cleanly, past every install check.

We can't run your code to know whether that break is real for you. But we can check the thing that makes it possible: does the fix's closure stay require-able? --package-type=cjs rejects a new package that's ESM-only — "type": "module" with no CJS main and no require/default export condition. A package that makes no type claim is CommonJS by default and passes; a dual-mode one (an ESM build plus a require export) passes; only the genuinely ESM-only versions are held back.

Unlike engines and license, this isn't a library built-in — and that's deliberate. True require(ESM) compatibility is per-edge and Node-version-gated (newer Node keeps relaxing it), so a node-local yes/no is an approximation, not a proof. lockgraph ships engines and license as built-in conditions and takes custom ones through the same seam; yaf plugs its module-format check in there — checking entry-point consistency, which it can, and staying upfront that it isn't checking behaviour, which it can't.

Scope: which advisories, not just which fix

--force and --safe tune how a fix lands. A separate control tunes how much gets fixed at all — because not every advisory is worth acting on in every context, and the smallest change that clears the risk is usually the right one.

--production fixes only advisories reachable from your production dependencies. A vulnerability that lives entirely under devDependencies — in a test runner, a bundler, some linter's transitive — never ships, so patching it churns the lockfile for a risk your users never run. --production leaves those flagged and fixes the rest. The split can't be read from the lockfile — yarn.lock records no dev/prod distinction; every edge is just depends on. So it's computed from each package.json, walked over the graph: start at the production dependencies, follow the edges, and a package is in scope only if production actually reaches it.

--workspace=<glob> narrows a monorepo fix to the packages you name — --workspace=packages/api, --workspace='@scope/*'. Remediating one service's advisories in a fifty-package repo without touching the other forty-nine keeps the diff reviewable and the blast radius small. A workspace pulled in as a dependency of one you selected contributes only its production closure, so a neighbour's dev tree never leaks into your fix.

Two more narrow by identity rather than reach. --ignore drops a specific advisory before the fix starts — a GHSA or npm-advisory-id glob — so a CVE you've assessed and accepted (a dev-only false positive, a disputed report) never triggers a bump. --exclude holds a package still by name and optional version range: --exclude='lodash@>=2 <3' leaves that line alone wherever it sits in the tree, however deep. Neither has an equivalent in npm audit fix — to fix everything except one CVE, or to freeze one nested package, you'd reach for overrides or a third-party audit wrapper.

They all compose into one precise instruction — --production --workspace=packages/api --safe, with --ignore / --exclude trimming the exceptions you've already vetted — so the fix set is exactly the one you meant, not everything the audit happened to return.

Attribution: a skip you can act on

A gate that silently drops fixes is worse than no gate — you'd never know a vulnerability was left behind, or why. So every skip carries its reason, composed from the constraint you set, the axis that rejected, the package that blocked, and the versions it tried:

Constraints: node >=18
Skipped (constraints — no fix keeps the closure within the policy [node >=18];
         relax it, --exclude the package, or accept the newer dep):
  some-tool@1.4.0 → 2.0.0 — needs lru-cache@^11.0.0
    - lru-cache@11.5.2: engines.node '20 || >=22' does not support node 18.0.0 (target '>=18')
    - lru-cache@11.0.0: engines.node '20 || >=22' does not support node 18.0.0 (target '>=18')

From that you know precisely what to do: widen the target if 20 is actually fine, --exclude some-tool to accept the residual risk deliberately, or pin lru-cache yourself. The vulnerability is still there — but it's visible and explained, which is the whole difference between "skipped" and "swept under the rug." The license axis reads the same, with license MIT not permitted in the reason slot; a rejected fix version reads "the fix version itself is not permitted."

For a pipeline, the same account comes as data: --dry-run --json prints what would be upgraded and what would be skipped — each skip with its reason (consumer-range, override-pin, manifest-pin, constraint, out-of-scope) — as one JSON object, before anything is written. A CI step can gate on what a fix would leave behind, not just on what it would change.

Under the hood

Three properties hold it in line: off by default, no effect on the reproducibility guarantee, and no claim beyond what it checks.

Off means off. With no constraint set, the apply path is exactly Part 2's: rebind everything, complete the closure once, byte-identical output — the golden and real-world fixtures prove it. The constraint machinery is a branch you only enter by opting in.

Tentative apply, immutable graphs. When constraints are active, each fix is applied and its closure completed on a trial graph, and committed only if it clears every gate; a fix that hits a dead end is discarded and the graph is left exactly as it was, then the next fix is tried. That's clean precisely because the graph library is immutable — modify and complete return new graphs rather than mutating in place, so "try this fix, and if it doesn't pass, pretend it never happened" is just don't keep the result. No rollback, no partial state. The constraints themselves ride the library's own resolution seam — the same step that already honored resolutions (Part 2) also runs your acceptance gates — so "don't pick an engine-incompatible version" is a property of resolution, next to "don't violate a known pin," not a filter bolted on afterward.

It's a bet, not a proof. The safe end rests on one wager: that checking each fix against its own declared metadata — the version it lands on, and the ones it drags in — is enough, without a solver backtracking the whole tree. That check is node-local, which buys a single guarantee: it can only be too cautious, never too permissive. It won't hand you an engine-incompatible or ESM-only pin. At worst it over-reports, refusing a fix a backtracking resolver might have landed by picking a lower parent upstream. That case is narrow, and the skip report names it, so you close it by hand. So far it holds; the corners get named and narrowed one at a time.

Where this leaves the tool

Part 2's claim was the fix reproduces. Part 3's is a step further: the fix reproduces **and fits** — runs on the Node you target, passes the license policy you set, agrees with the ranges you declared, across every workspace in a monorepo. All opt-in, all guarantee-or-flag, all attributed when they can't.

The lowest patched version clears the advisory. Whether it's the right version, only your project can answer — so the tool leaves that call to you, and flags the ones where the answer is "not this one."

There's a single stance under all of it. --force says apply everything, break what you must. The constraints are its mirror image — there's even a --safe flag that flips the automatable ones on together: apply what fits, leave what doesn't for a deliberate hand. Update what you safely can now, and schedule the engine bump, the license swap, or the ESM migration as its own change rather than smuggling it inside a security patch. The tool's job is to make the split legible: what it fixed, what it couldn't, and why.

If Yarn ships a native audit fix one day, we'll retire ours happily — constraints and all. Until then, it fixes your lockfile, and names the fixes it can't land without breaking something else.

Sources / links

• The tool: yarn-audit-fix (npm) — --engines.<engine>, --license.allow/.deny, --package-type, --safe, --on-conflict, --production, --workspace, --json, and the --force manifest rewrite.
• The library: lockgraph — the complete step's constraint seam (engines / license conditions, plus custom ones) and the immutable graph operations the tentative apply relies on; the per-format specs (including the missing dev/prod marker) live under docs/spec/formats.
• Background: Why npm audit fix --force is risky, SPDX license list, EBADENGINE in npm