f8e17ee2ab
FileHeatmap component is fully integrated into main TUI app: - Keyboard shortcut 'H' toggles heatmap view - Real-time file access aggregation from event store - Shows most-touched files with multiple sort modes - All tests passing (943 tests, including 130 FileHeatmap tests) Additional fixes: - Fixed ErrorGroupPanel options to support bottom property - Added vitest globals configuration for proper TypeScript support - Fixed type assertions in server.test.ts - Created comprehensive integration documentation Co-Authored-By: Claude Worker <noreply@anthropic.com>
141 lines
4.2 KiB
Markdown
141 lines
4.2 KiB
Markdown
# FileHeatmap Integration Summary
|
|
|
|
## Overview
|
|
The FileHeatmap component is fully integrated into the FABRIC TUI application, providing real-time visualization of file modification patterns and collision detection.
|
|
|
|
## Integration Points
|
|
|
|
### 1. Component Instantiation
|
|
**Location:** `src/tui/app.ts:136-143`
|
|
```typescript
|
|
this.fileHeatmap = new FileHeatmap({
|
|
parent: this.screen,
|
|
top: 1,
|
|
left: 0,
|
|
width: '100%',
|
|
bottom: 1,
|
|
});
|
|
this.fileHeatmap.getElement().hide();
|
|
```
|
|
|
|
### 2. Keyboard Shortcut
|
|
**Key:** `H` (uppercase)
|
|
**Location:** `src/tui/app.ts:270-272`
|
|
- Toggles between default view and heatmap view
|
|
- Pressing `H` again or `Escape` returns to default view
|
|
|
|
### 3. Data Aggregation
|
|
**Location:** `src/tui/app.ts:401-404, 673-679`
|
|
|
|
The heatmap aggregates file access counts from the event store:
|
|
```typescript
|
|
this.fileHeatmap.updateData(
|
|
(opts) => this.store.getFileHeatmap(opts),
|
|
() => this.store.getFileHeatmapStats()
|
|
);
|
|
```
|
|
|
|
**Store Methods:**
|
|
- `getFileHeatmap(options)` - Returns sorted file entries (src/store.ts:501-585)
|
|
- `getFileHeatmapStats()` - Returns aggregate statistics (src/store.ts:590-637)
|
|
|
|
### 4. Features
|
|
- **Real-time updates:** Heatmap updates automatically when new events are added
|
|
- **Multiple sort modes:**
|
|
- Modifications (default)
|
|
- Recent activity
|
|
- Worker count
|
|
- Collision priority
|
|
- **Filtering:**
|
|
- Collisions only mode (`c` key)
|
|
- Directory filtering
|
|
- **Heat levels:**
|
|
- Cold (1-2 modifications)
|
|
- Warm (3-5 modifications)
|
|
- Hot (6-10 modifications)
|
|
- Critical (11+ modifications)
|
|
- **Worker tracking:** Shows which workers are modifying each file
|
|
- **Collision detection:** Highlights files with concurrent modifications
|
|
|
|
### 5. View Management
|
|
**Location:** `src/tui/app.ts:388-409`
|
|
|
|
View mode state machine:
|
|
- `default` - Worker grid + Activity stream
|
|
- `heatmap` - Full-screen file heatmap
|
|
- `dag` - Dependency DAG view
|
|
- `replay` - Session replay
|
|
- `errors` - Error groups
|
|
|
|
### 6. Help Text
|
|
**Location:** `src/tui/app.ts:601-614`
|
|
```
|
|
Heatmap View:
|
|
s - Cycle sort mode
|
|
c - Toggle collisions only
|
|
Esc - Return to default view
|
|
```
|
|
|
|
## Test Coverage
|
|
|
|
### Component Tests
|
|
- **FileHeatmap.test.ts:** 51 tests covering UI component behavior
|
|
- **fileHeatmap.test.ts:** 20 tests covering heatmap logic
|
|
- **FileHeatmap.test.tsx:** 15 tests covering web frontend
|
|
- **app.test.ts:** 44 tests including heatmap integration
|
|
|
|
**Total:** 130 tests covering FileHeatmap functionality
|
|
**Status:** ✅ All tests passing
|
|
|
|
## Usage
|
|
|
|
1. Start FABRIC TUI: `npm start` or `npm run tui`
|
|
2. Press `H` to open the file heatmap view
|
|
3. Use `s` to cycle through sort modes:
|
|
- Modifications (default)
|
|
- Recent activity
|
|
- Worker count
|
|
- Collision priority
|
|
4. Press `c` to filter for files with collisions only
|
|
5. Use `j/k` or arrow keys to navigate files
|
|
6. Press `Esc` to return to the default view
|
|
|
|
## Technical Details
|
|
|
|
### Data Flow
|
|
```
|
|
LogEvents → Store.add() → FileModificationTracker
|
|
↓
|
|
Store.getFileHeatmap()
|
|
↓
|
|
FileHeatmap.updateData()
|
|
↓
|
|
FileHeatmap.render()
|
|
```
|
|
|
|
### Performance
|
|
- File modifications tracked in-memory with `Map<string, FileModificationTracker>`
|
|
- Efficient O(1) lookups for file access patterns
|
|
- Configurable max entries limit (default: 50)
|
|
- Timestamps stored for interval calculations
|
|
|
|
### Collision Detection
|
|
The heatmap integrates with the collision detection system to highlight:
|
|
- **Active collisions** (⚠ red): Multiple workers modifying same file within 5s window
|
|
- **Potential collisions** (⚡ yellow): Multiple workers actively working on same file
|
|
- **Safe files** (no indicator): Single worker or no recent conflicts
|
|
|
|
## Related Files
|
|
- Component: `src/tui/components/FileHeatmap.ts`
|
|
- Integration: `src/tui/app.ts`
|
|
- Store logic: `src/store.ts`
|
|
- Tests: `src/tui/components/FileHeatmap.test.ts`, `src/tui/app.test.ts`
|
|
- Types: `src/types.ts` (FileHeatmapEntry, FileHeatmapStats, HeatmapOptions)
|
|
|
|
## Completion Status
|
|
✅ **COMPLETE** - FileHeatmap is fully integrated and functional
|
|
- Keyboard shortcut 'H' working
|
|
- Data aggregation from store working
|
|
- Real-time updates working
|
|
- All tests passing (943 total)
|
|
- Help documentation included
|