pnpm-store-project-mirror-breaks-vitest-glob

# pnpm's project hardlink mirror makes vitest glob a test from outside the root ## Symptom In a git worktree, after `pnpm install`, the test runner reports the SAME test file failing from two paths — the real one and a store path: ``` FAIL apps/pwa/test/foo.test.tsx FAIL Library/pnpm/store/v10/projects/<hash>/test/foo.test.tsx Error: Cannot find package '@/components/...' imported from .../test/foo.test.tsx ``` Sibling tests in the same directory (with the identical `import X from "@/..."`) pass. Only a **new or recently-written** test file trips it. tsc/biome are fine; it's purely a test-discovery/alias-resolution error. ## Root cause `pnpm install` content-addresses the project and **hardlinks the entire project tree — including `test/` — into `~/Library/pnpm/store/v<n>/projects/<hash>/`** (the per-project side-effects store, hash derived from the project). Those are hardlinks (same inode), not symlinks, so they're real files at a second path. The test runner's file glob (vitest `include: ["test/**/*.test.{ts,tsx}"]`, resolved against the vite `root`) ends up discovering the file via that out-of-root store path. There, the `@` alias — defined as `fileURLToPath(new URL("./", import.meta.url))` = the project dir — and vite's "allowed root" don't cover the store location, so `@/...` resolves to nothing → "Cannot find package". The reason a *fresh* file triggers it is link/glob ordering; older files happen to resolve to the in-root copy. Confirm with an inode compare: ```bash ls -i test/foo.test.tsx ls -i ~/Library/pnpm/store/v10/projects/<hash>/test/foo.test.tsx # SAME inode → hardlink mirror ``` ## Fix Delete the stale store-project mirror. It's hardlinks — removing the store copy does NOT touch your real working-tree files (the other hardlink survives): ```bash rm -rf ~/Library/pnpm/store/v10/projects/<hash> npx vitest run test/foo.test.tsx # now a single, in-root path → @/ resolves ``` (Find `<hash>` from the failing path in the runner output, or `ls ~/Library/pnpm/store/v*/projects/`.) ## Prevention - **Run the test suite against a symlinked `node_modules`, not a fresh in-worktree `pnpm install`.** Symlinking the worktree's `node_modules` to a sibling worktree that has the same deps (e.g. `ln -s ../../main/apps/pwa/node_modules node_modules`) avoids creating the project store mirror entirely. Do the real `pnpm install` only when you need a real `node_modules` for the production build (`next build` rejects the symlink — see below), and clear the mirror afterward if you then run tests. - The symlink trick is also why `next build` (Turbopack) fails with "Symlink node_modules is invalid, it points out of the filesystem root" — so the usual pattern is: **symlink for tests, real install for build.** Just remember the real install plants the store mirror. - This is worktree-specific: multiple worktrees of the same package share the same project hash, so one worktree's install can leave a mirror that another worktree's runner then globs. ## Generalization Any content-addressed package manager (pnpm, and Bun's global cache) can create hardlinked copies of your source outside the project root. When a glob-based tool (test runner, linter, bundler) reports a file from a `store`/`cache` path you never wrote, suspect a hardlink mirror — `ls -i` to confirm the shared inode, and delete the out-of-root copy rather than your real files.