Split --force into named flags for the two things it does

[zkochan]

Summary

--force on pnpm install bundles two unrelated guarantees. Proposal: give each a name, and keep --force as the documented union so nothing breaks.

What --force means in pnpm v12 today

1. Install what this host cannot run. The per-snapshot installability check is bypassed, so a package whose cpu / os / libc / engines do not match is materialized instead of skipped.
2. Materialize every slot again, changed or not. The repeat-install fast path, the frozen tree's up-to-date probe, the plan pass's current-lockfile and global-virtual-store skips, and the link pass's per-slot completion-marker skip are all switched off, and the recorded skip set is discarded.

These serve unrelated intents. (1) is "I am building a Linux image on a Mac." (2) is "my node_modules is wrong, rebuild it." Someone reaching for (2) also gets foreign-platform optional dependencies materialized into their tree, which they did not ask for and are unlikely to notice. Predictability is a core requirement in PHILOSOPHY.md, and one flag silently doing two things is in tension with it.

Why this is smaller than it looks

pnpm v11's --force carries at least six meanings:

meaning	v11 site
bypass installability	lockfileToDepGraph.ts:206
refetch into the store, ignoring the verified copy	packageRequester.ts:601
force a full resolution	install/index.ts:1931
accept an incompatible lockfile version	readLockfiles.ts:62
skip the node_modules purge confirmation	extendInstallOptions.ts:295
relink everything	link.ts:375

v12 has already shed three of them. There is no force_full_resolution and no ignore_incompatible, and store corruption is healed on the default path by check_pkg_files_integrity (verifyStoreIntegrity defaults to true) rather than needing --force. So the decomposition only has to cover the two above.

Prior art

Three patterns:

• Grab-bag --force — npm, bun. npm's own documentation lists roughly ten unrelated effects.
• Namespaced sub-forces — dpkg, with --force-depends, --force-overwrite, --force-confnew, --force-help and --force-all.
• One named flag per concern — cargo, composer, pip, yarn berry. pip deliberately says --force-reinstall rather than --force. composer has --ignore-platform-reqs. yarn berry has --check-cache, --refresh-lockfile, --immutable. cargo reserves --force for cargo install, where it means exactly one thing.

The useful signal is the direction of travel: tools that began with a blunt force have carved named flags out of it, not the reverse. npm added --legacy-peer-deps because --force was too coarse for peer conflicts; composer split out --ignore-platform-reqs; git added --force-with-lease.

Proposal

Not dpkg-style --force-* namespacing — it keeps the word that means nothing and adds combinatorics. Name each concern:

• --ignore-platform-checks for (1), or fold it into the existing supportedArchitectures setting, which already covers this ground at config level
• --reinstall for (2)
• --force stays, documented as the union of both

This is additive, so it is not a breaking change, and it fits PHILOSOPHY.md's preference for expressing older features as cases of a new model rather than accumulating special cases. Existing CI scripts and npm muscle memory keep working.

Out of scope

• pnpm store currently has only add and status. If a "check my store and repair it" entry point is ever wanted it belongs there as a store subcommand, not as another meaning on --force.
• verify_file skips re-hashing when a file's mtime is within 100 ms of its recorded checked_at, so corruption that preserves mtime is not caught. Narrow, and unrelated to flag naming, but it is the one store-integrity case --force could in principle address and currently does not.

Background

Came out of review on #15040, which fixed --force suppressing the slot re-import that runs correctly by default (#15030). That fix belongs to meaning (2); this issue is about the naming, not the behavior.

---

Written by an agent (Claude Code, claude-opus-5).

[Ayush442842q]

@zkochan I can work on this issue.

Just want to clarify one detail: should both --ignore-platform-checks and --reinstall be exposed as .npmrc settings as well (e.g. ignore-platform-checks=true), or strictly as CLI flags on pnpm install / add / deploy?

Happy to put together a PR for pacquet once aligned.