112 lines
3.4 KiB
Markdown
112 lines
3.4 KiB
Markdown
## File context domain split
|
|
|
|
Refactor `context/file.tsx` into focused modules with unchanged API.
|
|
|
|
---
|
|
|
|
### Summary
|
|
|
|
`packages/app/src/context/file.tsx` still combines path normalization, file-content caching/eviction, file-tree loading, watcher event handling, and file-view persistence orchestration. Recent refactoring extracted generic scoped-cache primitives to `packages/app/src/utils/scoped-cache.ts`, but most file-domain behavior remains in one module. This spec separates those concerns while preserving the existing `useFile()` interface.
|
|
|
|
---
|
|
|
|
### Goals
|
|
|
|
- Keep `useFile()` API stable for all callers.
|
|
- Extract independent domains into dedicated modules.
|
|
- Improve readability and lower risk for future file-tree/perf changes.
|
|
- Preserve current caching and watcher semantics.
|
|
|
|
---
|
|
|
|
### Non-goals
|
|
|
|
- No redesign of file tree UI.
|
|
- No change to backend file APIs.
|
|
- No simultaneous refactor of `components/file-tree.tsx` in this workstream.
|
|
|
|
---
|
|
|
|
### Parallel ownership (important)
|
|
|
|
This workstream owns:
|
|
|
|
- `packages/app/src/context/file.tsx`
|
|
- New files under `packages/app/src/context/file/**`
|
|
- `packages/app/src/utils/scoped-cache.ts` (only when required for file-view cache extraction)
|
|
|
|
This workstream must not edit:
|
|
|
|
- `packages/app/src/context/global-sync.tsx` (spec 12)
|
|
- `packages/app/src/pages/session.tsx` (spec 09)
|
|
- `packages/app/src/components/prompt-input.tsx` (spec 11)
|
|
|
|
---
|
|
|
|
### Current state
|
|
|
|
- File size: ~751 LOC.
|
|
- `packages/app/src/utils/scoped-cache.ts` now exists as a shared cache primitive used by file view persistence.
|
|
- Multiple domains in one module:
|
|
- path normalization/parsing
|
|
- LRU content memory management
|
|
- tree node/directory state management
|
|
- event-driven watcher invalidation
|
|
- per-session view cache bootstrapping
|
|
|
|
---
|
|
|
|
### Proposed module split
|
|
|
|
Create `packages/app/src/context/file/` modules such as:
|
|
|
|
- `path.ts` - normalize/strip helpers.
|
|
- `content-cache.ts` - content LRU + byte caps.
|
|
- `view-cache.ts` - per-session file view persistence cache (building on `createScopedCache`).
|
|
- `tree-store.ts` - directory/node store and list/expand/collapse actions.
|
|
- `watcher.ts` - watcher event handling and invalidation routines.
|
|
|
|
`file.tsx` remains the provider entry that composes these modules.
|
|
|
|
---
|
|
|
|
### Phased steps
|
|
|
|
1. Extract path helper functions with no behavior changes.
|
|
2. Extract content cache and eviction logic.
|
|
3. Extract file-specific view-cache loading/pruning logic on top of `createScopedCache`.
|
|
4. Extract tree-store list/refresh/toggle actions.
|
|
5. Extract watcher update handler and wire cleanup.
|
|
6. Keep `useFile()` return shape unchanged.
|
|
|
|
---
|
|
|
|
### Acceptance criteria
|
|
|
|
- `useFile()` API remains backward compatible.
|
|
- `context/file.tsx` is reduced significantly (target: under 350 LOC).
|
|
- Tree loading/refresh and content eviction behavior remain unchanged.
|
|
- Watcher-driven reload behavior still works for changed/added/deleted files.
|
|
|
|
---
|
|
|
|
### Validation plan
|
|
|
|
- Typecheck: `bun run typecheck` (from `packages/app`).
|
|
- Targeted e2e checks:
|
|
- `e2e/files/file-tree.spec.ts`
|
|
- `e2e/files/file-viewer.spec.ts`
|
|
- `e2e/files/file-open.spec.ts`
|
|
- Manual checks:
|
|
- directory expand/collapse and refresh
|
|
- large file navigation and cache reuse
|
|
- watcher-driven updates in active file tabs
|
|
|
|
---
|
|
|
|
### Handoff notes
|
|
|
|
- Keep tree/data stores colocated with their mutation helpers.
|
|
- Avoid changing persisted key names or cache key shapes in this pass.
|
|
- Save broader API cleanups for a follow-up once modules are stable.
|