docs: record the exact-prerelease gap in the pnpm override key

Codex review on 4321a19: `vite@*` does not match a declaration pinning an exact prerelease. pnpm compares with semver.intersects(declaredSpec, keyRange), which is asymmetric for prereleases: intersects('8.0.0-beta.18', '*') is false while the reverse is true. My earlier justification checked the wrong argument order.

Verified on pnpm 11.20.0: a bare key redirects an exact-prerelease declaration, the ranged key does not. No range string avoids it, because node-semver only admits a prerelease when a comparator carries the same version tuple. A prerelease RANGE (^8.0.0-beta.1) still matches, and pnpm 12.0.0-rc.3 matches the exact form too, so the gap is pnpm 9-11 only. A bare key would close it but is what clobbers catalog:, so below pnpm 12 the two cannot both hold.

Corrects the comments and guide text that claimed the range keeps the override on every valid semver range.

Author: fengmk2

docs/guide/migrate-rules.md

@@ -86,10 +86,14 @@ Related rules:
   `vitest@*`). pnpm applies an override by replacing the declared spec on every
   manifest, importer manifests included. A bare key matches any spec, including
   `catalog:`, and `vp up` then rewrites that reference to a concrete version.
-  The `@*` range keeps the override on the transitive and peer declarations it
-  exists for. It leaves `catalog:` references to the catalog, which already
-  resolves them to Vite+ core. Migration re-keys a project that still holds the
-  bare key, and keeps its named-catalog choice.
+  The `@*` range keeps the override on the semver ranges that transitive and
+  peer declarations use. It leaves `catalog:` references to the catalog, which
+  already resolves them to Vite+ core. Migration re-keys a project that still
+  holds the bare key, and keeps its named-catalog choice.
+- On pnpm 9 to 11 that range does not match a declaration that pins an exact
+  prerelease, such as `vite: "8.0.0-beta.18"`, so the override skips it and pnpm
+  can install a separate upstream Vite. A prerelease range such as
+  `^8.0.0-beta.1` still matches, and pnpm 12 matches the exact form as well.
 - The direct-entry rule above is pnpm-specific. Bun mirrors its core alias as
   a direct dependency for its peer resolver, and npm browser-provider layouts
   may need a top-level `vite` edge so nested Vitest packages can resolve

docs/guide/upgrade.md

@@ -71,7 +71,7 @@ If you migrated with `vp migrate`, your project pins `vitest` to an exact versio
 - **Yarn:** a `vitest` entry under `resolutions` in `package.json`
 - **pnpm:** a `vitest@*` entry under `overrides` in `pnpm-workspace.yaml` — unless your `package.json` already had a `pnpm` field, in which case it lives under `pnpm.overrides` in `package.json` instead (pnpm ignores `pnpm-workspace.yaml` overrides when `package.json` defines `pnpm.overrides`)
 
-Under pnpm the managed keys use an explicit `@*` range (`vite@*`, `vitest@*`). pnpm applies an override by replacing the declared spec on every manifest, importer manifests included. A bare key matches any spec, including `catalog:`. The `@*` range keeps the override on the transitive and peer declarations it exists for, and leaves `catalog:` references intact. `vp up` therefore no longer rewrites them to a concrete version.
+Under pnpm the managed keys use an explicit `@*` range (`vite@*`, `vitest@*`). pnpm applies an override by replacing the declared spec on every manifest, importer manifests included. A bare key matches any spec, including `catalog:`. The `@*` range keeps the override on the semver ranges that transitive and peer declarations use, and leaves `catalog:` references intact. `vp up` therefore no longer rewrites them to a concrete version. On pnpm 9 to 11 the range does not match a declaration that pins an exact prerelease (`vite: "8.0.0-beta.18"`); a prerelease range such as `^8.0.0-beta.1` still matches, and pnpm 12 matches both.
 
 A Vite+ release can bump the bundled Vitest. Because that pin also applies to `vite-plus`'s own `vitest` dependency, an out-of-date pin keeps installing the previous runner even after you upgrade `vite-plus` — splitting Vitest's internals (mocks, `expect`, runner state) between the pinned copy and the one `vp test` loads.
 

packages/cli/src/migration/migrator/shared.ts

@@ -173,13 +173,24 @@ export const LEGACY_WRAPPER_FALLBACK_VERSIONS: Record<string, string> = {
  * catalog during resolution, and `pnpm update` then writes the resolved core
  * alias into that importer's package.json (issue #2309).
  *
- * The `@*` range keeps the override on every valid semver range. Transitive and
- * peer `vite` declarations always use such a range, and they are the reason this
- * override exists. The range also leaves `catalog:` specs alone, because `*` is
- * a valid semver range and `catalog:` is not, so pnpm's `isIntersectingRange`
- * never matches the two. The installed result does not change: an importer that
- * references the catalog already resolves to the aliased core through its
- * catalog entry.
+ * The `@*` range keeps the override on the declared semver ranges that
+ * transitive and peer `vite` declarations use, and those declarations are the
+ * reason this override exists. The range leaves `catalog:` specs alone, because
+ * `catalog:` is not a valid semver range, so pnpm's `isIntersectingRange`
+ * rejects it before it compares anything. The installed result does not change:
+ * an importer that references the catalog already resolves to the aliased core
+ * through its catalog entry.
+ *
+ * KNOWN GAP on pnpm 9 to 11. A declaration that pins an EXACT prerelease, such
+ * as `vite: "8.0.0-beta.18"`, escapes the override. pnpm compares with
+ * `semver.intersects(declaredSpec, keyRange)`, and that call is asymmetric for
+ * prereleases: it returns false for an exact prerelease against a wildcard
+ * range, even though the arguments in the other order return true. No range
+ * string avoids this, because node-semver only admits a prerelease when a
+ * comparator carries the same version tuple. A prerelease RANGE such as
+ * `^8.0.0-beta.1` still matches, and pnpm 12 matches the exact form too. A bare
+ * key would cover this case, but a bare key is what clobbers `catalog:`, so
+ * below pnpm 12 the two cannot both hold.
  *
  * This applies to pnpm only. npm and bun `overrides`, and yarn `resolutions`,
  * keep bare keys. Those package managers have no `catalog:` importer specs to