storybook/.serena/memories/lsp-phase4-navigation.md

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>)
• 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:

character Alice { age: 7 }
character Bob { friend: Alice }  // Cmd+Click "Alice" → jumps to line 1

Find References:

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:

   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

cd /Users/sienna/Development/storybook/storybook
cargo test --lib lsp::navigation_tests

Run All LSP Tests

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