feat(perf): optimize materialization and sync caching

[fbosch]

Summary

Cache docs presence checks and optimize path normalization.

Changes

• Cache docs presence checks in sync to avoid repeated lookups
• Optimize path normalization by computing once before sort
• Replace existence check with try-catch for better performance

Summary by CodeRabbit

• Chores

  • Updated Node.js versions in CI workflows to test against versions 18, 20, and 22.
  • Added benchmarks directory to gitignore.

• Refactor

  • Improved internal data structure handling for better maintainability.

• Performance

  • Optimized file presence checks with caching to reduce repeated filesystem access.
  • Enhanced error handling for file validation operations.

[coderabbitai]

Warning

Rate limit exceeded

@fbosch has exceeded the limit for the number of commits that can be reviewed per hour. Please wait 48 minutes and 46 seconds before requesting another review.

⌛ How to resolve this issue?

After the wait time has elapsed, a review can be triggered using the @coderabbitai review command as a PR comment. Alternatively, push new commits to this PR.

We recommend that you space out your commits to avoid hitting the rate limit.

🚦 How do rate limits work?

CodeRabbit enforces hourly rate limits for each developer per organization.

Our paid plans have higher rate limits than the trial, open-source and free plans. In all cases, we re-allow further reviews after a brief timeout.

Please see our FAQ for further information.

📝 Walkthrough

Walkthrough

Node.js versions updated across GitHub Actions workflows (audit, CI, and package preview), benchmarks directory added to gitignore, and source code refactored to optimize file handling through entries array precomputation, docsPresence caching, and stat-based verification.

Changes

Cohort / File(s)	Summary
GitHub Actions Node.js Updates .github/workflows/audit.yml, .github/workflows/pkg-pr-new-preview.yml	Node.js version updated from 20 to 22 in setup steps.
GitHub Actions CI Matrix .github/workflows/ci.yml	Added matrix configuration for node-version [18, 20, 22] to test across multiple Node.js versions; setup step now uses dynamic matrix value.
Git Configuration .gitignore	Added benchmarks/ directory to ignore rules.
Source Code Refactoring src/materialize.ts	Refactored to use intermediate entries array pairing relative paths with precomputed normalized values; sorting, iteration, and batch processing now operate on structured entries rather than raw file list.
Sync Optimization src/sync.ts	Added docsPresence caching map to avoid repeated filesystem checks; force flag short-circuits doc verification.
Verify Logic src/verify.ts	Replaced pre-check file existence with exception-driven stat-based approach inside verifyDir; ENOENT and ENOTDIR errors treated as missing files.

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~20 minutes

Poem

🐰 Hop, hop, Node versions flow,
Matrix tests across the row,
Entries cached, stats precise,
Benchmarks ignored—oh so nice!
Swift and lean, our code takes flight,
Refactored paths shining bright! ✨

🚥 Pre-merge checks | ✅ 3

✅ Passed checks (3 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The pull request title accurately summarizes the main changes: performance optimizations in materialization path normalization and sync caching for docs presence checks.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Post copyable unit tests in a comment
• Commit unit tests in branch feature/performance-optimizations

---

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 and usage tips.}

[pkg-pr-new]

Open in StackBlitz

npx https://pkg.pr.new/fbosch/docs-cache@14

commit: b388bfe

[Copilot]

Pull request overview

This pull request implements performance optimizations in the caching and materialization logic. The changes focus on reducing redundant filesystem operations and path computations.

Changes:

• Replaced duplicate filesystem existence checks with try-catch pattern in verification
• Added caching for docs presence checks to avoid repeated lookups during sync operations
• Optimized path normalization by computing once before sorting instead of multiple times

Reviewed changes

Copilot reviewed 6 out of 7 changed files in this pull request and generated no comments.

File	Description
src/verify.ts	Replaced exists() + stat() calls with single stat() call in try-catch for better performance
src/sync.ts	Added Map-based cache for docs presence checks to avoid redundant filesystem lookups
src/materialize.ts	Pre-computed normalized paths once before sorting instead of computing them multiple times during sort and processing
.gitignore	Added benchmarks/ directory to ignore benchmark data

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[coderabbitai]

Actionable comments posted: 1

🤖 Fix all issues with AI agents

In `@src/verify.ts`:
- Around line 49-61: The inner catch currently rethrows non-ENOENT/ENOTDIR
errors but the outer catch converts any thrown error into a "missing manifest"
result, masking real IO/permission failures; update the outer catch to inspect
the thrown error (cast to NodeJS.ErrnoException and read .code) and only
increment missingCount/continue when code === "ENOENT" or code === "ENOTDIR",
otherwise rethrow the error so permission/IO errors from stat/filePath are
propagated; reference the stat(filePath) call, the inner error handling (error
as NodeJS.ErrnoException).code, and the missingCount variable when making this
change.