Files

T

can1357 fb72f5d6a6 refactor: restructured filesystem scan cache integration and extracted discovery profiles

- Refactored filesystem scan cache integration to use pre-scanned entries from fs_cache module instead of manual directory walking in grep.rs.
- Extracted filesystem scan cache invalidation helpers into dedicated fs-cache-invalidation.ts module with three functions: invalidateFsScanAfterWrite, invalidateFsScanAfterDelete, and invalidateFsScanAfterRename.
- Centralized file mention discovery profile configuration into getMentionCandidateDiscoveryProfile() function for improved maintainability.
- Added comprehensive documentation of filesystem-scan cache architecture contract including cache key specifications, TTL policies, and invalidation patterns.
- Updated CHANGELOG.md to document filesystem scan cache invalidation helpers and named discovery profile for file mention candidates.

2026-02-13 15:06:32 +01:00

1.9 KiB

Raw Blame History

FS scan cache architecture

This document defines the shared filesystem-scan cache contract used by pi-natives discovery/search callers.

Cache key contract

Cache entries are keyed by:

root (absolute search root path)
include_hidden (hidden-file visibility)
use_gitignore (ignore-rule behavior)

Callers with different visibility/ignore semantics must use different profiles so they do not share incompatible cache entries.

Freshness and recheck contract

crates/pi-natives/src/fs_cache.rs owns global policy:

FS_SCAN_CACHE_TTL_MS (default 1000)
FS_SCAN_EMPTY_RECHECK_MS (default 200)
FS_SCAN_CACHE_MAX_ENTRIES (default 16)

get_or_scan() returns cache_age_ms so callers can decide whether an empty filtered result should trigger force_rescan().

Current callers using this contract:

fd (fuzzyFind) uses empty-result fast recheck.
grep consumes shared scan entries and applies grep-specific glob/type filtering on top.

Invalidation contract

Mutation-triggered invalidation is explicit and path-based via invalidateFsScanCache.

Coding-agent routes invalidation through packages/coding-agent/src/tools/fs-cache-invalidation.ts:

invalidateFsScanAfterWrite(path)
invalidateFsScanAfterDelete(path)
invalidateFsScanAfterRename(oldPath, newPath) (invalidates both paths)

Write/edit flows call these helpers after successful filesystem mutation.

Caller discovery profiles

Callers should not build ad-hoc discovery flags inline. Use named profile/policy helpers at callsites.

Current profile boundaries:

File mention candidate discovery (file-mentions.ts): hidden on, gitignore on, node_modules included.
TUI fuzzy @ discovery (autocomplete.ts): hidden on, gitignore on, bounded result count.
TUI local path prefix completion keeps a separate per-directory readdir cache as an intentional latency fast-path; global fuzzy discovery remains on natives shared scan cache.

1.9 KiB Raw Blame History