feat: Add indexAssets() and tryAssetPathSync() to CacheBustingConfig

[nielsenko]

Description

Adds synchronous path lookups to CacheBustingConfig, enabling integration with synchronous template engines (Mustache lambdas, Ninja filters, etc.).

• Add indexAssets() to CacheBustingConfig - walks fileSystemRoot, computes hashes, populates an internal cache
• Add tryAssetPathSync() - sync cache lookup, returns original path if not cached
• assetPath() and tryAssetPath() now populate the cache as a side-effect
• StaticHandler.directory() automatically calls indexAssets() when a cacheBustingConfig is provided; the future is awaited on first request

Related Issues

• Fixes: Extend the web templates to support cache busted references serverpod#4678

Pre-Launch Checklist

• This update focuses on a single feature or bug fix.
• I have read and followed the Dart Style Guide and formatted the code using dart format.
• I have referenced at least one issue this PR fixes or is related to.
• I have updated/added relevant documentation (doc comments with ///).
• I have added new tests to verify the changes.
• All existing and new tests pass successfully.
• I have documented any breaking changes below.

Breaking Changes

• No breaking changes.

Additional Notes

None.

Summary by CodeRabbit

• New Features
  • Introduced caching mechanism for asset paths to improve lookup performance.
  • Added bulk asset indexing to automatically discover and optimize asset paths throughout your application.
  • Added synchronous asset path lookup for cached assets, enabling faster access without async operations.

[coderabbitai]

Important

Review skipped

Auto reviews are disabled on this repository. Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

📝 Walkthrough

Walkthrough

This PR extends CacheBustingConfig with internal caching capabilities. An internal cache map is introduced to store computed cache-busted paths, assetPath() is modified to populate and retrieve from this cache, indexAssets() method walks the file system to pre-populate the cache, and tryAssetPathSync() provides synchronous cache lookups.

Changes

Cohort / File(s)	Summary
Cache Busting Configuration packages/relic_io/lib/src/io/static/cache_busting_config.dart	Added private cache field to store computed cache-busted paths. Modified assetPath() to check and update cache. Added indexAssets() to recursively traverse fileSystemRoot and pre-populate cache. Added tryAssetPathSync() for synchronous cached lookups with fallback to input path.
Cache Busting Tests packages/relic_io/test/static/cache_busting_config_test.dart	Added comprehensive tests validating cache behavior before/after indexing, consistency between assetPath() and tryAssetPathSync() results, handling of nested files, non-cached paths, and paths outside mount prefix.

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~20 minutes

Possibly related PRs

• feat: Adds support for cache busting #192: Initial implementation of cache-busting feature with CacheBustingConfig and asset path hashing; this PR builds upon it by adding internal caching and bulk indexing capabilities.

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title accurately and concisely describes the primary feature additions: indexAssets() and tryAssetPathSync() methods added to CacheBustingConfig.
Description check	✅ Passed	The description covers all required template sections: detailed description of changes, related issue reference, and a completed pre-launch checklist. Documentation and tests are mentioned as completed.
Linked Issues check	✅ Passed	The PR implements core requirements from issue #4678: adding synchronous path lookups (tryAssetPathSync) and bulk indexing (indexAssets) to support template engines, with cache population as a side-effect of assetPath/tryAssetPath.
Out of Scope Changes check	✅ Passed	All changes are focused on adding caching functionality to CacheBustingConfig and corresponding tests, aligning with the objectives to enable synchronous template engine integration.
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

Tip

Issue Planner is now in beta. Read the docs and try it out! Share your feedback on Discord.

---

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

[nielsenko]

@CodeRabbit review

[codecov]

Codecov Report

❌ Patch coverage is 95.00000% with 1 line in your changes missing coverage. Please review.
✅ Project coverage is 91.45%. Comparing base (cba19d0) to head (8f4409f).
⚠️ Report is 1 commits behind head on main.

Files with missing lines	Patch %	Lines
...lic_io/lib/src/io/static/cache_busting_config.dart	94.11%	1 Missing ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##             main     #332      +/-   ##
==========================================
+ Coverage   91.44%   91.45%   +0.01%     
==========================================
  Files          97       97              
  Lines        3797     3816      +19     
  Branches     1935     1943       +8     
==========================================
+ Hits         3472     3490      +18     
- Misses        325      326       +1     

Flag	Coverage Δ
relic_core	91.20% <ø> (ø)
relic_io	93.33% <95.00%> (+0.06%)	⬆️

Flags with carried forward coverage won't be shown. Click here to find out more.

☔ View full report in Codecov by Sentry.
📢 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.

[coderabbitai]

✅ Actions performed

Review triggered.

Note: CodeRabbit is an incremental review system and does not re-review already reviewed commits. This command is applicable only when automatic reviews are paused.

[coderabbitai]

🧹 Nitpick comments (1)

packages/relic_io/lib/src/io/static/cache_busting_config.dart (1)

121-138: Consider clearing _cache at the start of indexAssets.

If indexAssets() is called more than once (e.g., after a file is deleted or renamed), stale entries from the previous run will persist because the cache is never cleared. If this is intended to be called only once at startup, a doc comment noting that would be helpful; otherwise, adding _cache.clear() at the top would make repeated calls idempotent.

Suggested fix

  Future<void> indexAssets() async {
+   _cache.clear();
    final resolvedRootPath = fileSystemRoot.resolveSymbolicLinksSync();

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@packages/relic_io/lib/src/io/static/cache_busting_config.dart` around lines
121 - 138, The indexAssets method can leave stale entries when run multiple
times; make it idempotent by clearing the in-memory cache at the start of
indexAssets (call _cache.clear()) so previous runs' entries are removed before
re-indexing, or if intended to be one-time only add a doc comment to indexAssets
explaining it must only be called once; locate the indexAssets function and add
the _cache.clear() call as the first action (or add the explanatory doc comment
above the indexAssets declaration).

🤖 Prompt for all review comments with AI agents

Verify each finding against the current code and only fix it if needed.

Nitpick comments:
In `@packages/relic_io/lib/src/io/static/cache_busting_config.dart`:
- Around line 121-138: The indexAssets method can leave stale entries when run
multiple times; make it idempotent by clearing the in-memory cache at the start
of indexAssets (call _cache.clear()) so previous runs' entries are removed
before re-indexing, or if intended to be one-time only add a doc comment to
indexAssets explaining it must only be called once; locate the indexAssets
function and add the _cache.clear() call as the first action (or add the
explanatory doc comment above the indexAssets declaration).

[marcelomendoncasoares]

Just one minor question and suggestion on the tests, but LGTM!