Skip to content

Commit fcc8915

Browse files
DanielFGrayDanielFGray
committed
add ideas file
1 parent 662c152 commit fcc8915

1 file changed

Lines changed: 394 additions & 0 deletions

File tree

‎FEATURE_IDEAS.md‎

Lines changed: 394 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,394 @@
1+
# Effect Dev TUI - Feature Ideas
2+
3+
This document contains planned features that leverage existing capabilities from the Effect DevTools ecosystem without requiring editor integration.
4+
5+
## Quick Wins (High Value, Low Effort)
6+
7+
### 1. Span Duration Statistics
8+
9+
**Effort**: Low
10+
**Value**: High
11+
12+
Display aggregated statistics for spans with the same name:
13+
14+
- Min/Avg/Max/P95 duration
15+
- Total count
16+
- Success/failure rates
17+
18+
**Implementation**: Add aggregation logic to store that groups spans by name and calculates statistics. Display in span details panel or new dedicated stats section.
19+
20+
**Why**: Provides immediate performance analysis insights using data already collected.
21+
22+
---
23+
24+
### 2. Span Count by Status
25+
26+
**Effort**: Low
27+
**Value**: Medium
28+
29+
Show count of running vs ended spans in the header/status bar.
30+
31+
**Implementation**: Add computed properties that count spans by status, display in header next to total count.
32+
33+
**Why**: Quick visual indicator of active work and system state.
34+
35+
---
36+
37+
### 3. Export/Save Snapshot
38+
39+
**Effort**: Low
40+
**Value**: High
41+
42+
Add command to save current spans/metrics to JSON file for later analysis.
43+
44+
**Implementation**: Add command (e.g., `s` key) that writes `store.spans` and `store.metrics` to timestamped JSON file.
45+
46+
**Why**: Essential for debugging, sharing with team, comparing system states, or post-mortem analysis.
47+
48+
---
49+
50+
### 4. Metric History with ASCII Sparklines
51+
52+
**Effort**: Medium
53+
**Value**: High
54+
55+
Keep last N values for each metric and display trend as ASCII sparkline (e.g., `▁▂▃▅▇`).
56+
57+
**Implementation**:
58+
59+
- Add ring buffer to store for each metric (configurable size, default 20-50 samples)
60+
- Render sparkline in metric details using Unicode block characters
61+
- Show trend direction indicator (↑↓→)
62+
63+
**Why**: Metrics are currently static snapshots. Seeing trends helps identify patterns, regressions, and anomalies.
64+
65+
---
66+
67+
## Medium Effort Features
68+
69+
### 5. Span Filter by Attributes
70+
71+
**Effort**: Medium
72+
**Value**: Medium
73+
74+
Extend current span filter to search within span attributes, not just name.
75+
76+
**Implementation**: Modify filter logic in `spanTree.tsx` to include attribute key/value pairs in search. Syntax could be `name:value` or just search all.
77+
78+
**Why**: Many important details are in attributes. Current name-only filter is limiting.
79+
80+
---
81+
82+
### 6. Trace ID Grouping/Filtering
83+
84+
**Effort**: Medium
85+
**Value**: Medium-High
86+
87+
Filter or group spans by trace ID to focus on a single request flow.
88+
89+
**Implementation**:
90+
91+
- Add trace ID selector (similar to client dropdown)
92+
- Filter span tree to only show spans matching selected trace
93+
- Show trace count in header
94+
95+
**Why**: When multiple concurrent traces are active, helps isolate and follow a single request flow.
96+
97+
---
98+
99+
### 7. Metric Comparison Mode
100+
101+
**Effort**: Medium
102+
**Value**: Medium
103+
104+
Select two metrics and display side-by-side comparison or diff.
105+
106+
**Implementation**:
107+
108+
- Add multi-select state for metrics (Shift+Enter to add to comparison)
109+
- Split metric details panel to show both
110+
- Highlight differences in values/trends
111+
112+
**Why**: Useful for comparing related metrics (e.g., request count vs error count, before/after deployment).
113+
114+
---
115+
116+
## Easy Convenience Features
117+
118+
### 8. Span Tree Collapse All/Expand All
119+
120+
**Effort**: Low
121+
**Value**: Low-Medium
122+
123+
Add hotkeys to collapse or expand the entire span tree at once.
124+
125+
**Implementation**:
126+
127+
- `E` key: expand all (add all span IDs to `expandedSpanIds`)
128+
- `C` key: collapse all (clear `expandedSpanIds`, or only keep root level)
129+
130+
**Why**: Navigation convenience when dealing with large span trees.
131+
132+
---
133+
134+
### 9. Metrics Poll Interval Control
135+
136+
**Effort**: Low
137+
**Value**: Low
138+
139+
Add hotkeys to increase/decrease metrics polling interval dynamically.
140+
141+
**Implementation**:
142+
143+
- `+`/`-` keys (when metrics focused) to adjust interval
144+
- Display current interval in status bar
145+
- Persist preference
146+
147+
**Why**: VS Code extension has this as config. Allows users to balance between freshness and performance.
148+
149+
---
150+
151+
### 10. Span Event Timeline
152+
153+
**Effort**: Low
154+
**Value**: Medium
155+
156+
Display span events inline in the span tree or details panel with relative timestamps.
157+
158+
**Implementation**:
159+
160+
- Enhance `SpanDetailsPanel` to show `span.events` array
161+
- Display event name, relative time from span start, and attributes
162+
163+
**Why**: Events are already collected but not prominently displayed. VS Code extension shows them in tree nodes.
164+
165+
---
166+
167+
## Future Ideas (Require More Design)
168+
169+
### 11. Histogram Visualization
170+
171+
Display histogram buckets visually as ASCII bar chart in metric details.
172+
173+
### 12. Span Search History
174+
175+
Keep history of recent span filter queries for quick re-application.
176+
177+
### 13. Metric Alerts/Thresholds
178+
179+
Visual indicators when metrics exceed configured thresholds.
180+
181+
### 14. Client-Specific Views
182+
183+
Save layout/filter preferences per client.
184+
185+
### 15. Span Timeline View
186+
187+
Waterfall/flamegraph-style visualization of span relationships (inspired by VS Code's TraceViewer component).
188+
189+
---
190+
191+
## Implementation Priority
192+
193+
**Phase 1** (Quick wins for immediate value):
194+
195+
1. Span Duration Statistics
196+
2. Export/Save Snapshot
197+
3. Span Count by Status
198+
199+
**Phase 2** (Enhanced observability): 4. Metric History with Sparklines 5. Span Filter by Attributes 6. Span Event Timeline
200+
201+
**Phase 3** (Advanced features): 7. Trace ID Grouping 8. Metric Comparison Mode 9. Remaining convenience features
202+
203+
---
204+
205+
## Advanced TypeScript/AST-Powered Features (Standalone TUI)
206+
207+
These features extend the existing fixer experiment by leveraging the TypeScript Compiler API and Recast for advanced static analysis and code transformation. All work without editor integration.
208+
209+
### 16. Dependency Graph Viewer (ASCII)
210+
211+
**Effort**: Medium
212+
**Value**: High
213+
214+
Build and visualize a project-wide service dependency graph using ASCII art:
215+
216+
```
217+
┌─────────────────┐
218+
│ HttpClient │
219+
└────────┬────────┘
220+
│ requires
221+
┌────┴────┐
222+
▼ ▼
223+
┌────────┐ ┌────────┐
224+
│ Config │ │ Logger │
225+
└────────┘ └────────┘
226+
```
227+
228+
**Implementation**:
229+
230+
- Extend `layerResolverCore.ts` to build a full project-wide layer/service index
231+
- Use `recast` + box-drawing characters to render tree/graph visualization
232+
- Toggle with hotkey (e.g., `g` in Fix tab) to switch between list and graph view
233+
- Highlight circular dependencies in red/bold
234+
- Show "orphaned" layers (defined but never provided)
235+
236+
**Why**: Complements the current fixer (which handles individual missing requirements) with a holistic view of the entire Effect architecture. Makes it easier to understand and refactor complex layer compositions.
237+
238+
---
239+
240+
### 17. Effect Health Check / Linter
241+
242+
**Effort**: Medium
243+
**Value**: High
244+
245+
Dedicated "Health" or "Lint" tab that runs a suite of static checks:
246+
247+
- Unused layers (defined but never provided anywhere)
248+
- Unhandled errors (Effects with `never` error type that could still fail at runtime)
249+
- Missing `Effect.provide` wraps on `Effect.run*` calls
250+
- Inconsistent layer naming (e.g., `ConfigLayer` vs `ConfigLive` inconsistencies)
251+
- Potential schema validation gaps (if Effect Schema is used)
252+
- Services provided multiple times (conflicting layer compositions)
253+
254+
**Implementation**:
255+
256+
- Create `healthCheck.ts` module that runs multiple validator functions
257+
- Each validator returns structured results with file:line references
258+
- Display as a scrollable checklist in a dedicated UI panel
259+
- Each item has metadata: file, line, severity (error/warn/info), suggestion
260+
261+
**Why**: Proactive quality checks prevent runtime errors and enforce architecture consistency. Particularly valuable for Effect newcomers learning best practices.
262+
263+
---
264+
265+
### 18. Batch Fixer with Preview & Rollback
266+
267+
**Effort**: Medium
268+
**Value**: High
269+
270+
Extend the current single-file layer fixer to handle bulk operations:
271+
272+
- "Fix All Missing Requirements" command that applies fixes across all affected files
273+
- **Preview mode**: Show all planned changes before applying
274+
- Display diff-style view of what will be modified
275+
- User can deselect specific changes before committing
276+
- **Backup & Rollback**:
277+
- Automatically backup modified files before applying changes
278+
- Provide quick rollback if changes break the build
279+
- Multi-file status feedback showing progress
280+
281+
**Implementation**:
282+
283+
- Batch `applyLayerFix` calls with transaction-like semantics
284+
- Generate preview data structure before writing files
285+
- Add backup files (`.bak` or version control) before modifications
286+
- Persist rollback info so user can undo if needed
287+
288+
**Why**: Applies your powerful fixer to real-world scenarios where entire projects need layer composition fixes. The preview/rollback reduces risk.
289+
290+
---
291+
292+
### 19. Effect API Usage & Pattern Report
293+
294+
**Effort**: Low
295+
**Value**: Medium
296+
297+
Scan the codebase and generate a report on Effect API usage patterns:
298+
299+
- **Most used APIs**: `pipe`, `map`, `flatMap`, `gen`, `all`, `race`, etc.
300+
- **Pattern distribution**: Effect-gen vs pipe style prevalence
301+
- **Deprecated API usage**: Flag any outdated Effect patterns (version-aware)
302+
- **Service density**: Average services per Layer, max depth of compositions
303+
- **Error handling patterns**: How many Effects handle errors vs rely on defaults
304+
305+
**Implementation**:
306+
307+
- Extend `layerResolverCore.ts` to add AST visitors for common Effect call patterns
308+
- Parse source files and count pattern occurrences
309+
- Display as a statistics panel or exportable report
310+
- Show trends over time if snapshots are saved/compared
311+
312+
**Why**: Provides visibility into codebase architecture and style. Useful for refactoring efforts, onboarding, and identifying technical debt.
313+
314+
---
315+
316+
### 20. Span → Source File Correlation
317+
318+
**Effort**: Medium
319+
**Value**: High
320+
321+
Hybrid approach combining runtime observability with static analysis:
322+
323+
- When viewing a span in the Observability tab, the span's **source location** is extracted (if available in tracer attributes)
324+
- Display as `file:line` reference in span details
325+
- **Integration options**:
326+
- Show the filename and context snippet in the TUI (read-only display)
327+
- Provide a command that opens the file in `$EDITOR` at that location
328+
- Alternatively, print file:line references that user can copy into their editor
329+
330+
**Implementation**:
331+
332+
- Track span origins in the tracer (if not already done) via stack trace analysis or instrumentation
333+
- Store `sourceFile` and `sourceLine` in span metadata
334+
- When displaying span details, check for these attributes
335+
- Add command `o` (open) to spawn `$EDITOR` or `code --goto file:line`
336+
337+
**Why**: This is a TUI advantage over static tools: you can correlate runtime behavior with source code without editor integration. Developers can see "this span came from src/handlers/checkout.ts:145" and navigate there.
338+
339+
---
340+
341+
### 21. Effect Schema Analysis & Documentation
342+
343+
**Effort**: Medium
344+
**Value**: Medium
345+
346+
For projects using Effect Schema, provide analysis and documentation:
347+
348+
- Scan for `Schema.Struct`, `Schema.Literal`, `Schema.decode`, etc.
349+
- Generate a **schema catalog** showing all defined schemas with their fields/types
350+
- Display as tree view with collapsible type definitions
351+
- Validate schema definitions (e.g., warn if schema has no encoder, only decoder)
352+
- Show **schema coverage**: which domain types have schemas defined
353+
354+
**Implementation**:
355+
356+
- Extend AST analysis to recognize Schema patterns
357+
- Parse Schema definitions to extract field names, types, validators
358+
- Display in a dedicated "Schemas" tab or sub-panel of Health check
359+
- Compare schemas across versions if multiple snapshot exports exist
360+
361+
**Why**: Makes schema usage discoverable and enforces best practices. Useful for API documentation and data validation debugging.
362+
363+
---
364+
365+
### 22. Dead Code & Unused Service Detection
366+
367+
**Effort**: Medium
368+
**Value**: Medium
369+
370+
Extend static analysis to find potentially unused code in an Effect context:
371+
372+
- **Unused layers**: Layers defined but never required or provided anywhere
373+
- **Unused services**: Services defined but never consumed
374+
- **Unreachable branches**: Dead code paths in Effect.if, Effect.match, etc.
375+
- **Orphaned effects**: Effect values constructed but never run or returned
376+
- **Unused span names**: Spans defined but no actual traces contain them (requires runtime data)
377+
378+
**Implementation**:
379+
380+
- Leverage type checker to trace service consumption across the project
381+
- Build a service dependency graph and identify unreachable nodes
382+
- Use AST visitors to find constructed Effects that aren't passed through any runtime call
383+
- Cross-reference with runtime trace data for "unused spans in practice"
384+
385+
**Why**: Helps clean up Effect code and identify incomplete refactorings. The combination of static + runtime analysis reveals both theoretical and practical dead code.
386+
387+
---
388+
389+
## Notes
390+
391+
- All features work without editor integration
392+
- Leverage existing data structures from Effect DevTools
393+
- Follow existing keyboard-driven TUI patterns
394+
- Maintain performance with large datasets (use filtering/pagination)

0 commit comments

Comments
 (0)