refactor: introduce restore keys for cache

[SukkaW]

Add restoreKeys for restoring the store cache.

The idea is that we currently include the pnpm-lock.yaml content hash within the cache primary key. This means even if only one dependency has changed, the entire pnpm-lock.yaml content hash changes, and the entire pnpm store cache is now thrown away.

But we don't have to invalidate the entire store. Other dependencies' cache may still be utilized. We can still restore the previous store cache, and only the changed dependencies need to be and will be downloaded.

restoreKeys doesn't change the fact that the cache is still miss (primaryKey), so during the post action we still upload the latest pnpm store to a new cache entry.

Summary by CodeRabbit

Summary by CodeRabbit

• Bug Fixes
  • Improved dependency cache restoration by allowing partially matching pnpm caches to be reused when an exact cache match is unavailable.
  • Corrected cache-hit reporting so dependencies are reinstalled when the lockfile changes, even if a partial cache is restored.

[qodo-code-review]

Qodo reviews are paused for this user.

Troubleshooting steps vary by plan Learn more →

On a Teams plan?
Reviews resume once this user has a paid seat and their Git account is linked in Qodo.
Link Git account →

Using GitHub Enterprise Server, GitLab Self-Managed, or Bitbucket Data Center?
These require an Enterprise plan - Contact us
Contact us →

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro Plus

Run ID: e40af624-40f5-47fd-a983-8dcd8295f53c

📥 Commits

Reviewing files that changed from the base of the PR and between 13bdc8a and 0adcde8.

⛔ Files ignored due to path filters (1)

• dist/index.js is excluded by !**/dist/**

📒 Files selected for processing (1)

• src/cache-restore/run.ts

🚧 Files skipped from review as they are similar to previous changes (1)

• src/cache-restore/run.ts

📜 Recent review details

⏰ Context from checks skipped due to timeout. (2)

• GitHub Check: Smoke (windows / v9.15.5)
• GitHub Check: Standalone Windows self-update (PATH regression)

---

📝 Walkthrough

Walkthrough

runRestoreCache now passes an OS and architecture based pnpm cache-key prefix to restoreCache. It reports cache-hit only when the restored key exactly matches the primary key.

Changes

Cache restore fallback

Layer / File(s)	Summary
Add restore-key prefix and exact-hit reporting src/cache-restore/run.ts	runRestoreCache passes a runner-specific pnpm restore-key prefix and reports cache-hit only for an exact primary-key match. Partial cache restoration remains available.

Estimated code review effort: 2 (Simple) | ~10 minutes

Suggested reviewers: zkochan

Poem

A rabbit checks the cache with care,
An exact key marks treasure there.
By OS and arch, fallback runs,
Then fresh installs start when needed.
Hop, restore, and build with cheer!

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly describes the main change: adding restore keys for cache restoration.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[coderabbitai]

Actionable comments posted: 1

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@src/cache-restore/run.ts`:
- Around line 21-27: Update the cache-hit handling around restoreCache in run so
it reports true only when the returned cache key exactly equals primaryKey;
preserve restoring contents for restoreKeys prefix matches while returning
cache-hit=false. Add a regression test covering a restore-key match and
verifying dependency installation remains reachable.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro Plus

Run ID: c1c1d484-d0ad-4c1c-94f4-21b1ec789dac

📥 Commits

Reviewing files that changed from the base of the PR and between 0ebf471 and 13bdc8a.

📒 Files selected for processing (1)

• src/cache-restore/run.ts

📜 Review details

⏰ Context from checks skipped due to timeout. (1)

• GitHub Check: Standalone Windows self-update (PATH regression)

⚠️ CI failures not shown inline (2)

GitHub Actions: pr-check / 0_check-dist.txt: refactor: introduce restore keys for cache

Conclusion: failure

View job details

##[group]Run git diff --exit-code dist/index.js
 �[36;1mgit diff --exit-code dist/index.js�[0m
 shell: /usr/bin/bash -e {0}
 env:
   PNPM_HOME: /home/runner/setup-pnpm/node_modules/.bin
 ##[endgroup]
 diff --git a/dist/index.js b/dist/index.js
 index 1866127..b11810d 100644
 Binary files a/dist/index.js and b/dist/index.js differ
 ##[error]Process completed with exit code 1.

---

GitHub Actions: pr-check / check-dist: refactor: introduce restore keys for cache

Conclusion: failure

View job details

##[group]Run git diff --exit-code dist/index.js
 �[36;1mgit diff --exit-code dist/index.js�[0m
 shell: /usr/bin/bash -e {0}
 env:
   PNPM_HOME: /home/runner/setup-pnpm/node_modules/.bin
 ##[endgroup]
 diff --git a/dist/index.js b/dist/index.js
 index 1866127..b11810d 100644
 Binary files a/dist/index.js and b/dist/index.js differ
 ##[error]Process completed with exit code 1.

🧰 Additional context used

🧠 Learnings (1)

📚 Learning: 2026-05-11T12:04:07.383Z

Learnt from: zkochan
Repo: pnpm/action-setup PR: 256
File: src/install-pnpm/run.ts:150-166
Timestamp: 2026-05-11T12:04:07.383Z
Learning: In pnpm/action-setup, when validating or forwarding the version value used for `pnpm self-update` and/or `devEngines.packageManager.version`, do not restrict it to exact versions or tags only—pnpm supports semver ranges for these inputs. Ensure any code that parses/validates `devEngines.packageManager.version` (and the value passed to `pnpm self-update`) allows range syntax such as `^`, `~`, and comparators (e.g. `>=8 <10`) instead of rejecting anything that isn’t a single exact version. Note: the plain `packageManager` field is different, so apply this “allow semver ranges” rule specifically to `devEngines.packageManager.version` / `self-update` handling.

Applied to files:

• src/cache-restore/run.ts

[BlackHole1]

LGTM. setup-node has similar logic: https://github.com/actions/setup-node/blob/e51e5fe84fc33b4c73ebe40526b2694712b5b858/src/cache-restore.ts#L43-L64

[SukkaW]

@zkochan Would you mind reviewing and merging this one, too? I believe there are some pnpm@10 users in the wild that may still benefit from this small change.