fix(migrate): convert Yarn PnP projects

fengmk2 · fengmk2 · commit b637fa9e7c1e · 2026-06-23T17:06:21.000+08:00
diff --git a/packages/cli/snap-tests-global/migration-standalone-yarn4-idempotent/snap.txt b/packages/cli/snap-tests-global/migration-standalone-yarn4-idempotent/snap.txt
@@ -1,7 +1,12 @@
-> vp migrate --no-interactive # standalone Yarn writes catalog specs on the first pass
+> vp migrate --no-interactive # implicit Yarn Berry PnP converts before the first pass
+
+⚠ Vite+ does not currently support Yarn Plug'n'Play (PnP).
+
+✔ Switched Yarn to node-modules mode
 ◇ Migrated . to Vite+
 • Node <semver>  yarn <semver>
 • 2 config updates applied, 1 file had imports rewritten
+• Package manager settings configured
 
 > cat package.json # migrated dependency specs use the Yarn catalog immediately
 {
diff --git a/packages/cli/snap-tests-global/migration-standalone-yarn4-idempotent/steps.json b/packages/cli/snap-tests-global/migration-standalone-yarn4-idempotent/steps.json
@@ -1,6 +1,6 @@
 {
   "commands": [
-    "vp migrate --no-interactive # standalone Yarn writes catalog specs on the first pass",
+    "vp migrate --no-interactive # implicit Yarn Berry PnP converts before the first pass",
     "cat package.json # migrated dependency specs use the Yarn catalog immediately",
     "cat .yarnrc.yml # managed catalog entries are available to those specs",
     "cat example.spec.ts # ordinary Vitest imports use the Vite+ public surface",
diff --git a/packages/cli/snap-tests-global/migration-upgrade-required-vitest-peer-metadata-npm/snap.txt b/packages/cli/snap-tests-global/migration-upgrade-required-vitest-peer-metadata-npm/snap.txt
@@ -1,5 +1,4 @@
-> node -e "const fs = require('node:fs'); fs.mkdirSync('node_modules', { recursive: true }); fs.cpSync('.fixture/vite-plugin-gherkin', 'node_modules/vite-plugin-gherkin', { recursive: true })" # simulate installed dependency metadata
-> vp migrate --no-interactive # required Vitest peer is detected without a Vitest package name
+> vp migrate --no-interactive # clean checkout conservatively preserves existing Vitest
 ◇ Migrated . to Vite+
 • Node <semver>  npm <semver>
 • Package manager settings configured
@@ -25,6 +24,7 @@
   }
 }
 
-> vp migrate --no-interactive # metadata-based peer provisioning is stable on rerun
+> node -e "const fs = require('node:fs'); fs.mkdirSync('node_modules', { recursive: true }); fs.cpSync('.fixture/vite-plugin-gherkin', 'node_modules/vite-plugin-gherkin', { recursive: true })" # simulate installed dependency metadata
+> vp migrate --no-interactive # metadata confirms the unnamed required Vitest peer
 This project is already using Vite+! Happy coding!
 
diff --git a/packages/cli/snap-tests-global/migration-upgrade-required-vitest-peer-metadata-npm/steps.json b/packages/cli/snap-tests-global/migration-upgrade-required-vitest-peer-metadata-npm/steps.json
@@ -1,8 +1,8 @@
 {
   "commands": [
-    "node -e \"const fs = require('node:fs'); fs.mkdirSync('node_modules', { recursive: true }); fs.cpSync('.fixture/vite-plugin-gherkin', 'node_modules/vite-plugin-gherkin', { recursive: true })\" # simulate installed dependency metadata",
-    "vp migrate --no-interactive # required Vitest peer is detected without a Vitest package name",
+    "vp migrate --no-interactive # clean checkout conservatively preserves existing Vitest",
     "cat package.json # package-local Vitest and its shared override remain aligned",
-    "vp migrate --no-interactive # metadata-based peer provisioning is stable on rerun"
+    "node -e \"const fs = require('node:fs'); fs.mkdirSync('node_modules', { recursive: true }); fs.cpSync('.fixture/vite-plugin-gherkin', 'node_modules/vite-plugin-gherkin', { recursive: true })\" # simulate installed dependency metadata",
+    "vp migrate --no-interactive # metadata confirms the unnamed required Vitest peer"
   ]
 }
diff --git a/packages/cli/snap-tests-global/migration-upgrade-vitest-exact-peer-yarn4/snap.txt b/packages/cli/snap-tests-global/migration-upgrade-vitest-exact-peer-yarn4/snap.txt
@@ -1,4 +1,8 @@
-> vp migrate --no-interactive # Yarn PnP exact peer should receive package-local vitest
+> vp migrate --no-interactive # Yarn PnP converts to node-modules before exact-peer migration
+
+⚠ Vite+ does not currently support Yarn Plug'n'Play (PnP).
+
+✔ Switched Yarn to node-modules mode
 ◇ Migrated . to Vite+
 • Node <semver>  yarn <semver>
 • Package manager settings configured
@@ -24,8 +28,8 @@
   }
 }
 
-> cat .yarnrc.yml # shared catalog should include the aligned vitest
-nodeLinker: pnp
+> cat .yarnrc.yml # linker conversion and aligned Vitest catalog are persisted
+nodeLinker: node-modules
 catalog:
   vite: npm:@voidzero-dev/vite-plus-core@latest
   vite-plus: latest
diff --git a/packages/cli/snap-tests-global/migration-upgrade-vitest-exact-peer-yarn4/steps.json b/packages/cli/snap-tests-global/migration-upgrade-vitest-exact-peer-yarn4/steps.json
@@ -1,8 +1,8 @@
 {
   "env": {},
   "commands": [
-    "vp migrate --no-interactive # Yarn PnP exact peer should receive package-local vitest",
+    "vp migrate --no-interactive # Yarn PnP converts to node-modules before exact-peer migration",
     "cat package.json # direct deps and resolutions should use the managed catalog/version",
-    "cat .yarnrc.yml # shared catalog should include the aligned vitest"
+    "cat .yarnrc.yml # linker conversion and aligned Vitest catalog are persisted"
   ]
 }
diff --git a/packages/cli/snap-tests-global/migration-upgrade-vitest-retained-references-npm/config/tsconfig.test.json b/packages/cli/snap-tests-global/migration-upgrade-vitest-retained-references-npm/config/tsconfig.test.json
@@ -0,0 +1,5 @@
+{
+  "compilerOptions": {
+    "types": ["vitest/globals"]
+  }
+}
diff --git a/packages/cli/snap-tests-global/migration-upgrade-vitest-retained-references-npm/resolve.cjs b/packages/cli/snap-tests-global/migration-upgrade-vitest-retained-references-npm/resolve.cjs
@@ -0,0 +1 @@
+module.exports = require.resolve('vitest');
diff --git a/packages/cli/snap-tests-global/migration-upgrade-vitest-retained-references-npm/snap.txt b/packages/cli/snap-tests-global/migration-upgrade-vitest-retained-references-npm/snap.txt
@@ -30,6 +30,16 @@
   }
 }
 
+> cat config/tsconfig.test.json # nested compilerOptions.types is also retained
+{
+  "compilerOptions": {
+    "types": ["vitest/globals"]
+  }
+}
+
+> cat resolve.cjs # require.resolve remains an upstream Vitest reference
+module.exports = require.resolve('vitest');
+
 > cat version.ts # vitest/package.json remains intentionally unre-written
 import metadata from 'vitest/package.json';
 
diff --git a/packages/cli/snap-tests-global/migration-upgrade-vitest-retained-references-npm/steps.json b/packages/cli/snap-tests-global/migration-upgrade-vitest-retained-references-npm/steps.json
@@ -3,6 +3,8 @@
     "vp migrate --no-interactive # retained upstream references require package-local Vitest",
     "cat package.json # Vitest dependency and override stay aligned",
     "cat tsconfig.json # compilerOptions.types remains an upstream Vitest reference",
+    "cat config/tsconfig.test.json # nested compilerOptions.types is also retained",
+    "cat resolve.cjs # require.resolve remains an upstream Vitest reference",
     "cat version.ts # vitest/package.json remains intentionally unre-written",
     "vp migrate --no-interactive # retained references remain stable on rerun"
   ]
diff --git a/packages/cli/src/migration/__tests__/migrator.spec.ts b/packages/cli/src/migration/__tests__/migrator.spec.ts
@@ -40,9 +40,80 @@ const {
   detectIncompatibleEslintIntegration,
   preflightGitHooksSetup,
   detectLegacyGitHooksMigrationCandidate,
+  detectYarnPnpMode,
+  configureYarnNodeModulesMode,
   setPackageManager,
 } = await import('../migrator.js');
 
+describe('Yarn PnP migration preflight', () => {
+  let tmpDir: string;
+  const savedEnv: Record<string, string | undefined> = {};
+  const isolatedEnv = ['HOME', 'USERPROFILE', 'YARN_NODE_LINKER'] as const;
+
+  beforeEach(() => {
+    tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'vp-test-yarn-pnp-'));
+    for (const key of isolatedEnv) {
+      savedEnv[key] = process.env[key];
+      delete process.env[key];
+    }
+    const cleanHome = path.join(tmpDir, '.home');
+    fs.mkdirSync(cleanHome);
+    process.env.HOME = cleanHome;
+    process.env.USERPROFILE = cleanHome;
+  });
+
+  afterEach(() => {
+    fs.rmSync(tmpDir, { recursive: true, force: true });
+    for (const key of isolatedEnv) {
+      if (savedEnv[key] === undefined) {
+        delete process.env[key];
+      } else {
+        process.env[key] = savedEnv[key];
+      }
+    }
+  });
+
+  it('detects explicit and implicit Yarn Berry PnP modes', () => {
+    fs.writeFileSync(path.join(tmpDir, '.yarnrc.yml'), 'nodeLinker: pnp\n');
+    expect(detectYarnPnpMode(tmpDir, '4.12.0')).toEqual({ source: 'configuration' });
+
+    fs.rmSync(path.join(tmpDir, '.yarnrc.yml'));
+    expect(detectYarnPnpMode(tmpDir, '4.12.0')).toEqual({ source: 'default' });
+    expect(detectYarnPnpMode(tmpDir, 'latest')).toEqual({ source: 'default' });
+  });
+
+  it('does not classify Yarn Classic or node-modules configuration as PnP', () => {
+    expect(detectYarnPnpMode(tmpDir, '1.22.22')).toBeUndefined();
+    fs.writeFileSync(path.join(tmpDir, '.yarnrc.yml'), 'nodeLinker: node-modules\n');
+    expect(detectYarnPnpMode(tmpDir, '4.12.0')).toBeUndefined();
+  });
+
+  it('honours YARN_NODE_LINKER over project configuration', () => {
+    fs.writeFileSync(path.join(tmpDir, '.yarnrc.yml'), 'nodeLinker: node-modules\n');
+    process.env.YARN_NODE_LINKER = 'pnp';
+    expect(detectYarnPnpMode(tmpDir, '4.12.0')).toEqual({ source: 'environment' });
+
+    process.env.YARN_NODE_LINKER = 'node-modules';
+    fs.writeFileSync(path.join(tmpDir, '.yarnrc.yml'), 'nodeLinker: pnp\n');
+    expect(detectYarnPnpMode(tmpDir, '4.12.0')).toBeUndefined();
+  });
+
+  it('converts the project rc without discarding other settings and is idempotent', () => {
+    fs.writeFileSync(
+      path.join(tmpDir, '.yarnrc.yml'),
+      'nodeLinker: pnp\nnmHoistingLimits: workspaces\ncatalog:\n  react: ^19.0.0\n',
+    );
+
+    expect(configureYarnNodeModulesMode(tmpDir)).toBe(true);
+    expect(readYamlObject(path.join(tmpDir, '.yarnrc.yml'))).toEqual({
+      nodeLinker: 'node-modules',
+      nmHoistingLimits: 'workspaces',
+      catalog: { react: '^19.0.0' },
+    });
+    expect(configureYarnNodeModulesMode(tmpDir)).toBe(false);
+  });
+});
+
 describe('rewritePackageJson', () => {
   it('should rewrite package.json scripts and extract staged config', async () => {
     const pkg = {
@@ -1586,6 +1657,37 @@ describe('ensureVitePlusBootstrap', () => {
     expect(detectVitePlusBootstrapPending(tmpDir, PackageManager.yarn)).toBe(false);
   });
 
+  it('preserves existing Vitest when dependency peer metadata is unavailable', () => {
+    fs.writeFileSync(
+      path.join(tmpDir, 'package.json'),
+      JSON.stringify({
+        name: 'test',
+        devDependencies: {
+          'vite-plus': 'latest',
+          'vite-plugin-gherkin': '0.2.0',
+          vitest: '^4.1.0',
+        },
+        overrides: {
+          vite: 'npm:@voidzero-dev/vite-plus-core@latest',
+          vitest: '^4.1.0',
+        },
+        devEngines: {
+          packageManager: { name: 'npm', version: '10.33.0', onFail: 'download' },
+        },
+      }),
+    );
+
+    ensureVitePlusBootstrap(makeWorkspaceInfo(tmpDir, PackageManager.npm));
+
+    const pkg = readJson(path.join(tmpDir, 'package.json')) as {
+      devDependencies: Record<string, string>;
+      overrides: Record<string, string>;
+    };
+    expect(pkg.devDependencies.vitest).toBe(VITEST_VERSION);
+    expect(pkg.overrides.vitest).toBe(VITEST_VERSION);
+    expect(detectVitePlusBootstrapPending(tmpDir, PackageManager.npm)).toBe(false);
+  });
+
   it.each([
     {
       name: 'compilerOptions.types',
@@ -1595,6 +1697,17 @@ describe('ensureVitePlusBootstrap', () => {
           JSON.stringify({ compilerOptions: { types: ['vitest/globals'] } }),
         ),
     },
+    {
+      name: 'nested compilerOptions.types',
+      writeReference: (projectPath: string) => {
+        const configDir = path.join(projectPath, 'config');
+        fs.mkdirSync(configDir);
+        fs.writeFileSync(
+          path.join(configDir, 'tsconfig.test.json'),
+          JSON.stringify({ compilerOptions: { types: ['vitest/globals'] } }),
+        );
+      },
+    },
     {
       name: 'vitest/package.json',
       writeReference: (projectPath: string) =>
@@ -1603,6 +1716,14 @@ describe('ensureVitePlusBootstrap', () => {
           "import metadata from 'vitest/package.json';\nconsole.log(metadata.version);\n",
         ),
     },
+    {
+      name: 'require.resolve',
+      writeReference: (projectPath: string) =>
+        fs.writeFileSync(
+          path.join(projectPath, 'resolve.cjs'),
+          "module.exports = require.resolve('vitest');\n",
+        ),
+    },
   ])('keeps package-local Vitest for retained $name references', ({ writeReference }) => {
     fs.writeFileSync(
       path.join(tmpDir, 'package.json'),
diff --git a/packages/cli/src/migration/bin.ts b/packages/cli/src/migration/bin.ts
diff --git a/packages/cli/src/migration/migrator.ts b/packages/cli/src/migration/migrator.ts
diff --git a/rfcs/migrate-existing-projects.md b/rfcs/migrate-existing-projects.md

Original file line number	Diff line number	Diff line change
`@@ -1,6 +1,6 @@`
`1`	`1`	`{`
`2`	`2`	`"commands": [`
`3`		`- "vp migrate --no-interactive # standalone Yarn writes catalog specs on the first pass",`
	`3`	`+ "vp migrate --no-interactive # implicit Yarn Berry PnP converts before the first pass",`
`4`	`4`	`"cat package.json # migrated dependency specs use the Yarn catalog immediately",`
`5`	`5`	`"cat .yarnrc.yml # managed catalog entries are available to those specs",`
`6`	`6`	`"cat example.spec.ts # ordinary Vitest imports use the Vite+ public surface",`
Original file line number	Diff line number	Diff line change
`@@ -1,5 +1,4 @@`
`1`		`-> node -e "const fs = require('node:fs'); fs.mkdirSync('node_modules', { recursive: true }); fs.cpSync('.fixture/vite-plugin-gherkin', 'node_modules/vite-plugin-gherkin', { recursive: true })" # simulate installed dependency metadata`
`2`		`-> vp migrate --no-interactive # required Vitest peer is detected without a Vitest package name`
	`1`	`+> vp migrate --no-interactive # clean checkout conservatively preserves existing Vitest`
`3`	`2`	`◇ Migrated . to Vite+`
`4`	`3`	`• Node <semver> npm <semver>`
`5`	`4`	`• Package manager settings configured`
`@@ -25,6 +24,7 @@`
`25`	`24`	`}`
`26`	`25`	`}`
`27`	`26`
`28`		`-> vp migrate --no-interactive # metadata-based peer provisioning is stable on rerun`
	`27`	`+> node -e "const fs = require('node:fs'); fs.mkdirSync('node_modules', { recursive: true }); fs.cpSync('.fixture/vite-plugin-gherkin', 'node_modules/vite-plugin-gherkin', { recursive: true })" # simulate installed dependency metadata`
	`28`	`+> vp migrate --no-interactive # metadata confirms the unnamed required Vitest peer`
`29`	`29`	`This project is already using Vite+! Happy coding!`
`30`	`30`
Original file line number	Diff line number	Diff line change
`@@ -1,8 +1,8 @@`
`1`	`1`	`{`
`2`	`2`	`"commands": [`
`3`		`- "node -e \"const fs = require('node:fs'); fs.mkdirSync('node_modules', { recursive: true }); fs.cpSync('.fixture/vite-plugin-gherkin', 'node_modules/vite-plugin-gherkin', { recursive: true })\" # simulate installed dependency metadata",`
`4`		`- "vp migrate --no-interactive # required Vitest peer is detected without a Vitest package name",`
	`3`	`+ "vp migrate --no-interactive # clean checkout conservatively preserves existing Vitest",`
`5`	`4`	`"cat package.json # package-local Vitest and its shared override remain aligned",`
`6`		`- "vp migrate --no-interactive # metadata-based peer provisioning is stable on rerun"`
	`5`	`+ "node -e \"const fs = require('node:fs'); fs.mkdirSync('node_modules', { recursive: true }); fs.cpSync('.fixture/vite-plugin-gherkin', 'node_modules/vite-plugin-gherkin', { recursive: true })\" # simulate installed dependency metadata",`
	`6`	`+ "vp migrate --no-interactive # metadata confirms the unnamed required Vitest peer"`
`7`	`7`	`]`
`8`	`8`	`}`
Original file line number	Diff line number	Diff line change
`@@ -1,8 +1,8 @@`
`1`	`1`	`{`
`2`	`2`	`"env": {},`
`3`	`3`	`"commands": [`
`4`		`- "vp migrate --no-interactive # Yarn PnP exact peer should receive package-local vitest",`
	`4`	`+ "vp migrate --no-interactive # Yarn PnP converts to node-modules before exact-peer migration",`
`5`	`5`	`"cat package.json # direct deps and resolutions should use the managed catalog/version",`
`6`		`- "cat .yarnrc.yml # shared catalog should include the aligned vitest"`
	`6`	`+ "cat .yarnrc.yml # linker conversion and aligned Vitest catalog are persisted"`
`7`	`7`	`]`
`8`	`8`	`}`
-Original file line number
+Diff line change
@@ @@ -0,0 +1,5 @@ @@
 +{
 +  "compilerOptions": {
 +    "types": ["vitest/globals"]
 +  }
 +}
Original file line number	Diff line number	Diff line change
`@@ -0,0 +1 @@`
	`1`	`+module.exports = require.resolve('vitest');`
Original file line number	Diff line number	Diff line change
`@@ -3,6 +3,8 @@`
`3`	`3`	`"vp migrate --no-interactive # retained upstream references require package-local Vitest",`
`4`	`4`	`"cat package.json # Vitest dependency and override stay aligned",`
`5`	`5`	`"cat tsconfig.json # compilerOptions.types remains an upstream Vitest reference",`
	`6`	`+ "cat config/tsconfig.test.json # nested compilerOptions.types is also retained",`
	`7`	`+ "cat resolve.cjs # require.resolve remains an upstream Vitest reference",`
`6`	`8`	`"cat version.ts # vitest/package.json remains intentionally unre-written",`
`7`	`9`	`"vp migrate --no-interactive # retained references remain stable on rerun"`
`8`	`10`	`]`