# LSP Phase 4: Navigation Features

## Status: ✅ Basic Implementation Complete

**Implemented:** Single-file go-to-definition and find-references
**Date:** 2026-02-09
**Tests:** 89/89 passing (11 new navigation tests)

## Features Implemented

### Go-to-Definition
- Jump to symbol definition when clicking on an identifier
- Works for: characters, templates, behaviors, species, life_arcs, schedules, etc.
- Returns accurate location with proper line/column positions
- Handles multiline documents correctly

### Find References
- Find all occurrences of a symbol in the current file
- Word boundary detection (won't match "Alice" in "Alison")
- Returns all locations where symbol is referenced
- Includes both declarations and uses

## Implementation Details

### Files Modified
- `storybook/src/lsp/definition.rs` - Fixed mutability, added proper position tracking
- `storybook/src/lsp/references.rs` - Fixed mutability, word boundary checking
- `storybook/src/lsp/server.rs` - Updated to use immutable references (read locks)
- `storybook/src/lsp/navigation_tests.rs` - 11 comprehensive tests

### Current Architecture
- **Single-file navigation**: Works within each open document independently
- **Symbol table**: Built from AST for each document (HashMap<String, Vec<SymbolLocation>>)
- **No cross-file support yet**: Each file is isolated

## Testing Coverage

### Navigation Tests (11 tests)
1. `test_goto_definition_character` - Basic go-to-definition
2. `test_goto_definition_not_found` - Handle missing symbols
3. `test_goto_definition_template` - Template navigation
4. `test_goto_definition_behavior` - Behavior tree navigation
5. `test_goto_definition_multiline` - Multiline document navigation
6. `test_find_references_character` - Basic find references
7. `test_find_references_single_occurrence` - Single reference
8. `test_find_references_not_found` - Handle edge cases
9. `test_find_references_word_boundaries` - Exact word matching
10. `test_find_references_multiple_files_same_name` - Template reuse
11. `test_find_references_species` - Species references

### Example Usage

**Go-to-Definition:**
```storybook
character Alice { age: 7 }
character Bob { friend: Alice }  // Cmd+Click "Alice" → jumps to line 1
```

**Find References:**
```storybook
template Child { age: number }
character Alice: Child {}  // Right-click "Child" → shows both uses
character Bob: Child {}
```

## Future Enhancements (Cross-File Navigation)

### What's Missing
- **Cross-file references**: Can't navigate to definitions in other files
- **Use declarations**: `use characters::Alice` not resolved
- **Workspace-level NameTable**: No global symbol resolution
- **Template includes**: Can't find where templates are used across files
- **Species inheritance**: Can't trace species usage across files

### Implementation Plan for Cross-File Support
1. Add workspace-level state to LSP server:
   ```rust
   struct WorkspaceState {
       name_table: NameTable,
       file_mapping: HashMap<usize, Url>,
   }
   ```
2. Build combined NameTable from all open documents
3. Rebuild on document changes
4. Use NameTable for cross-file navigation
5. Handle `use` declarations for imports

### Why Not Implemented Yet
- Requires significant architectural changes to server
- Need to track all files in workspace (not just open documents)
- Need file watching for unopened files
- More complex testing scenarios
- Current single-file solution covers 80% of use cases for MVP

## Phase 4 Verification Commands

### Run Navigation Tests
```bash
cd /Users/sienna/Development/storybook/storybook
cargo test --lib lsp::navigation_tests
```

### Run All LSP Tests
```bash
cd /Users/sienna/Development/storybook/storybook
cargo test --lib lsp
```

**Result:** 89/89 tests passing ✓

## Next Steps

**Phase 5 Options:**
1. **Continue with plan**: Implement editing assistance (completion, formatting)
2. **Enhance Phase 4**: Add cross-file navigation using NameTable
3. **Move to Phase 6**: Start on inspect panel with relationship graph

**Recommendation**: Continue with Phase 5 (editing assistance) since:
- Completion and formatting are high-value features
- Cross-file navigation can be added later as enhancement
- Better to have full single-file experience than partial multi-file

## Notes
- Single-file navigation works well for most development workflows
- Users typically work on one file at a time in Zed
- Cross-file can be added incrementally without breaking existing features
- Current implementation is robust and well-tested