can1357
fb72f5d6a6
- 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.
51 lines
1.9 KiB
Markdown
51 lines
1.9 KiB
Markdown
# 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.
|