feat(vitest): add --stale CLI option for iterative test running

[holyhli]

Description

Adds a --stale CLI option inspired by Elixir Mix's --stale option that runs only test files whose transitive module dependencies have changed since the last --stale run.

Primary Use Case - Agentic Coding Systems: Modern agentic coding tools (Claude Code, GitHub Copilot Workspace, OpenCode, Cursor with Composer, etc.) build harness systems that rely heavily on unit tests for validation. These agents run tests continuously during their development loops, and running full test suites dramatically slows their iteration time. --stale provides the fast feedback cycle agents need by running only affected tests.

Secondary Use Case - Human Development: Developers making small iterative changes also benefit from faster test cycles without requiring git.

How it works:

• Uses filesystem modification times (mtimes) stored in a manifest
• Tracks transitive dependencies recursively via Vite's module graph
• First run: executes all tests, generates manifest
• Subsequent runs: only runs tests with changed dependencies

Resolves #9917

Please don't delete this checklist! Before submitting the PR, please make sure you do the following:

• It's really useful if your PR references an issue where it is discussed ahead of time. ✅ See feat: add --stale CLI option for agentic coding systems #9917 for feature discussion
• Ideally, include a test that fails without this PR but passes with it. ✅ Added 6 comprehensive tests in test/cli/test/stale.test.ts
• Please, don't make changes to pnpm-lock.yaml unless you introduce a new test example. ✅ No changes to pnpm-lock.yaml
• Please check Allow edits by maintainers to make review process faster. ← Please enable this on GitHub

Tests

• Run the tests with pnpm test:ci. ✅ All tests pass:
  • CI=true pnpm test stale.test.ts — 6/6 tests pass
  • CI=true pnpm test git-changed.test.ts — 5/5 tests pass (no regression)
  • pnpm build — All 17 packages build successfully
  • pnpm typecheck — Zero type errors

Documentation

• If you introduce new functionality, document it. ✅ Documentation added:
  • Manual prose section in docs/guide/cli.md
  • Auto-generated CLI table in docs/guide/cli-generated.md
  • JSDoc comments in code

Changesets

• Changes in changelog are generated from PR name. ✅ PR title: feat(vitest): add --stale CLI option for iterative test running
  • Prefix: feat: ✓
  • Clear description ✓
  • Breaking changes: None

---

Implementation Highlights

Agentic System Benefits:

• ⚡ Fast feedback loops: Only affected tests run → agents iterate faster
• 🎯 Precision: Transitive dependency tracking ensures no missed tests
• 🔄 Stateless: No git required → works in any environment (containers, CI, local)
• 📊 Predictable: Manifest-based → deterministic test selection

Technical Design:

• Mutually exclusive with --changed (enforced at config resolution)
• Honors forceRerunTriggers (config changes → full suite)
• Watch mode compatible (seeds initial run, then watch takes over)
• Integrates cleanly with existing Vite module graph
• Manifest stored in Vitest cache directory (node_modules/.vite/vitest/)

Example - Agentic Workflow:

# Agent makes a change to src/utils/parser.ts
vitest run --stale
# ✓ Only runs tests that import parser.ts (directly or transitively)
# ✓ ~10x faster than full suite
# ✓ Agent gets immediate feedback on whether change broke anything

# Agent makes another change
vitest run --stale
# ✓ Only new affected tests run
# ✓ Agent continues rapid iteration

[netlify]

✅ Deploy Preview for vitest-dev ready!

Built without sensitive environment variables

Name	Link
🔨 Latest commit	f43c300
🔍 Latest deploy log	https://app.netlify.com/projects/vitest-dev/deploys/69bc2c39890d750008925726
😎 Deploy Preview	https://deploy-preview-9916--vitest-dev.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.

---

To edit notification comments on pull requests, go to your Netlify project configuration.

[AriPerkkio]

Let's first see if custom VCS provider approach would be better solution. It's good to post issue first in feature requests that introduce new changes like this.

• #9917 (comment)