fix(data): bound metadata version cache

[afc163]

Summary

• cap the per-process historical metadata cache at 32 requested version keys
• evict the oldest inserted cache entry when the cap is exceeded
• add a regression test for cache retention and eviction
• document the cache bound in spec.md

Verification

• npx vitest run src/__tests__/version-loader.test.ts (70 tests)
• npm run typecheck
• npm run build
• npx vitest run --reporter=dot --testTimeout=10000 --maxWorkers=1 --no-file-parallelism (49 files, 684 tests)
• git diff --check

[coderabbitai]

Warning

Review limit reached

@afc163, you've reached your PR review limit, so we couldn't start this review.

Next review available in: 34 minutes

Enable usage-based reviews in Billing to review now. Otherwise, wait until the next included review is available.
You're only billed for reviews past your plan's rate limits ($0.25/file).

How can I continue?

After more reviews become available, a review can be triggered using the @coderabbitai review command as a PR comment. Alternatively, push new commits to this PR.

To avoid repeated limits, reduce automatic review volume by pausing incremental auto-reviews earlier, using label-based review opt-in, excluding WIP or generated PR titles, or requesting reviews manually when the PR is ready. If your team needs uninterrupted high-volume reviews, an organization admin can enable usage-based reviews.

How do review limits work?

CodeRabbit enforces per-developer PR review limits for each organization. Most developers receive the normal plan review availability.

For paid Pro and Pro+ PR reviews, CodeRabbit uses adaptive limits for sustained high-volume activity. When a developer's recent PR review activity reaches the 95th percentile or higher among CodeRabbit users, additional reviews become available more gradually as earlier reviews age out of the rolling window.

Please refer docs for additional details.

Review details

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: 035bba33-85ca-42cc-80d1-cefb27af75f6

📥 Commits

Reviewing files that changed from the base of the PR and between abbbe31 and ebf8642.

📒 Files selected for processing (3)

• spec.md
• src/__tests__/version-loader.test.ts
• src/data/loader.ts

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch codex/bound-metadata-cache

---

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.}

[github-actions]

📦 Package Size Report

Metric	Size	Diff
Packed	25.69 MB	+0.08 KB (+0.0%)
Unpacked	26.77 MB	+0.23 KB (+0.0%)

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 99.69%. Comparing base (abbbe31) to head (ebf8642).

Additional details and impacted files

@@           Coverage Diff           @@
##             main     #199   +/-   ##
=======================================
  Coverage   99.69%   99.69%           
=======================================
  Files          40       40           
  Lines        2603     2608    +5     
  Branches      803      804    +1     
=======================================
+ Hits         2595     2600    +5     
  Misses          8        8           

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

[gemini-code-assist]

Code Review

This pull request introduces a cache eviction policy for historical metadata, limiting the cache size to 32 entries using a FIFO eviction strategy. It also adds a corresponding unit test and updates the specification documentation. The reviewer suggested replacing the while loop with an if statement when evicting the oldest cache entry, as the cache size can only exceed the limit by one at a time, making the code simpler and safer.

Important

The consumer version of Gemini Code Assist on GitHub is being sunset. Starting June 18, 2026, new organization installations will be blocked, and all code review activity will officially cease on July 17, 2026.
For more details on the timeline and next steps, please review the Help Documentation.

[gemini-code-assist]

Since entries are added to the cache one at a time, the cache size can only exceed MAX_METADATA_CACHE_ENTRIES by at most 1. Using an if statement instead of a while loop is simpler, more idiomatic, and safer as it completely eliminates any theoretical risk of an infinite loop.

Suggested change

	while (metadataCache.size > MAX_METADATA_CACHE_ENTRIES) {
	const oldestKey = metadataCache.keys().next().value;
	if (oldestKey === undefined) break;
	metadataCache.delete(oldestKey);
	}
	if (metadataCache.size > MAX_METADATA_CACHE_ENTRIES) {
	const oldestKey = metadataCache.keys().next().value;
	if (oldestKey !== undefined) {
	metadataCache.delete(oldestKey);
	}
	}