release: Storybook v0.2.0 - Major syntax and features update

BREAKING CHANGES: - Relationship syntax now requires blocks for all participants - Removed self/other perspective blocks from relationships - Replaced 'guard' keyword with 'if' for behavior tree decorators Language Features: - Add tree-sitter grammar with improved if/condition disambiguation - Add comprehensive tutorial and reference documentation - Add SBIR v0.2.0 binary format specification - Add resource linking system for behaviors and schedules - Add year-long schedule patterns (day, season, recurrence) - Add behavior tree enhancements (named nodes, decorators) Documentation: - Complete tutorial series (9 chapters) with baker family examples - Complete reference documentation for all language features - SBIR v0.2.0 specification with binary format details - Added locations and institutions documentation Examples: - Convert all examples to baker family scenario - Add comprehensive working examples Tooling: - Zed extension with LSP integration - Tree-sitter grammar for syntax highlighting - Build scripts and development tools Version Updates: - Main package: 0.1.0 → 0.2.0 - Tree-sitter grammar: 0.1.0 → 0.2.0 - Zed extension: 0.1.0 → 0.2.0 - Storybook editor: 0.1.0 → 0.2.0
2026-02-13 21:52:03 +00:00
parent 80332971b8
commit 16deb5d237
290 changed files with 90316 additions and 5827 deletions
--- a/.serena/memories/lsp-phase4-navigation.md
+++ b/.serena/memories/lsp-phase4-navigation.md
@@ -0,0 +1,127 @@
+# 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
--- a/.serena/memories/lsp-testing-status.md
+++ b/.serena/memories/lsp-testing-status.md
@@ -0,0 +1,142 @@
+# LSP Testing Status (Phase 3 Complete)
+
+## Summary
+✅ **Phase 3 (LSP Server Core Features) testing complete**
+- All LSP tests passing: 78/78 ✓
+- All tree-sitter grammar tests passing: 27/27 ✓
+- Code coverage significantly improved
+- Behavior tree support fully tested in both LSP and tree-sitter
+
+## Test Coverage
+
+### LSP Tests (78 total)
+Location: `/Users/sienna/Development/storybook/storybook/src/lsp/`
+
+#### Behavior Tests (8 tests) - `behavior_tests.rs`
+- ✅ test_behavior_parsing
+- ✅ test_behavior_symbols
+- ✅ test_behavior_symbol_kinds
+- ✅ test_behavior_in_document_symbols
+- ✅ test_behavior_with_subtrees
+- ✅ test_behavior_simple_action
+- ✅ test_behavior_selectors_and_sequences
+
+#### Diagnostics Tests (15 tests) - `diagnostics_tests.rs`
+- ✅ Parse error detection and reporting
+- ✅ Error position tracking
+- ✅ Error severity levels
+- ✅ Utility functions (byte_offset_to_position, create_diagnostic)
+- ✅ Edge cases (empty input, whitespace, comments only)
+
+#### Document Edge Tests (20 tests) - `document_edge_tests.rs`
+- ✅ Word-at-offset with unicode, underscores, boundaries
+- ✅ Document updates and symbol table management
+- ✅ All declaration types: species, characters, templates, life_arcs, schedules, behaviors, institutions
+- ✅ Symbol extraction for all entity types
+
+#### Existing Tests (35 tests)
+- Integration tests, formatting, hover, completion, definition, references, symbols
+
+### Tree-sitter Grammar Tests (27 total)
+Location: `/Users/sienna/Development/storybook/tree-sitter-storybook/test/corpus/`
+
+#### Behavior Tests (7 tests) - `behaviors.txt`
+- ✅ Simple Behavior (single action)
+- ✅ Selector Behavior (? { ... })
+- ✅ Sequence Behavior (> { ... })
+- ✅ Nested Behavior (selectors + sequences)
+- ✅ Repeat Behavior (* { ... })
+- ✅ Behavior with Subtree (@path::notation)
+- ✅ Complex Nested Behavior (all node types)
+
+#### Declaration Tests (17 tests) - `declarations.txt`
+- ✅ All declaration types (use, character, template, life_arc, schedule, behavior, etc.)
+
+#### Basic Tests (3 tests) - `basic.txt`
+- ✅ Simple character, use declaration, prose block
+
+## Coverage Improvements
+
+**Before testing push:**
+- document.rs: 80.11%
+- symbols.rs: 93.04%
+- diagnostics.rs: 0%
+- behavior support: untested
+- Total LSP tests: 34
+
+**After testing push:**
+- document.rs: 97.79% (+17.68%)
+- symbols.rs: 95.24% (+2.20%)
+- diagnostics.rs: fully tested
+- behavior support: comprehensive test coverage
+- Total LSP tests: 78 (+44 new tests, +129% increase)
+
+## Run Commands
+
+### LSP Tests
+```bash
+cd /Users/sienna/Development/storybook/storybook
+cargo test --lib lsp
+```
+
+### Tree-sitter Tests
+```bash
+cd /Users/sienna/Development/storybook/tree-sitter-storybook
+npm run test
+```
+
+**Note:** If Bash tool fails, use Serena's `execute_shell_command` instead.
+
+## Behavior Tree Support Verified
+
+Both LSP and tree-sitter grammar now have comprehensive behavior tree support:
+
+### Node Types Tested:
+- **action_node**: Simple action identifiers (e.g., `walk_around`)
+- **selector_node**: `? { ... }` - Try options in order until one succeeds
+- **sequence_node**: `> { ... }` - Execute children in sequence
+- **repeat_node**: `* { ... }` - Repeat child forever
+- **subtree_node**: `@path::to::tree` - Reference external behavior tree
+
+### Syntax Examples:
+```storybook
+behavior SimpleBehavior {
+    walk_around
+}
+
+behavior ComplexBehavior {
+    ? {
+        > {
+            check_threat
+            flee_to_safety
+        }
+        > {
+            check_resources
+            gather_resources
+        }
+        * {
+            idle
+        }
+    }
+}
+
+behavior WithSubtree {
+    > {
+        @helpers::check_preconditions
+        main_action
+    }
+}
+```
+
+## Next Steps (Phase 4)
+- Navigation features (go-to-definition, find references)
+- Cross-file symbol resolution
+- Template includes and species references
+
+## Files Modified
+- Created: `storybook/src/lsp/behavior_tests.rs`
+- Created: `storybook/src/lsp/diagnostics_tests.rs`
+- Created: `storybook/src/lsp/document_edge_tests.rs`
+- Created: `tree-sitter-storybook/test/corpus/behaviors.txt`
+- Modified: `storybook/src/lsp/mod.rs` (added test modules)
+- Modified: `storybook/src/lsp/server.rs` (fixed imports and mutability)
--- a/.serena/memories/tree-sitter-commands.md
+++ b/.serena/memories/tree-sitter-commands.md
@@ -0,0 +1,88 @@
+# Tree-sitter Grammar Commands
+
+## Location
+Tree-sitter grammar is at: `/Users/sienna/Development/storybook/tree-sitter-storybook/`
+
+## Running Tests
+
+**Use Serena's execute_shell_command when Bash tool fails:**
+```bash
+cd /Users/sienna/Development/storybook/tree-sitter-storybook && npm run test
+```
+
+This runs the tree-sitter test suite against all corpus files in `test/corpus/`.
+
+## Test Corpus Structure
+
+Test files are in `test/corpus/*.txt` format:
+```
+==================
+Test Name
+==================
+
+[input code]
+
+---
+
+[expected parse tree]
+```
+
+### Key Parse Tree Patterns for Behaviors:
+
+1. **All declarations wrap in `(declaration ...)`**
+2. **Behavior nodes wrap children in `(behavior_node ...)`**
+3. **Paths have internal structure:**
+   ```
+   (path
+     (path_segments
+       (identifier)
+       (identifier)))
+   ```
+   Not just `(path)`
+
+### Example Behavior Test Structure:
+```
+behavior SimpleBehavior {
+    walk_around
+}
+
+---
+
+(source_file
+  (declaration
+    (behavior
+      name: (identifier)
+      root: (behavior_node
+        (action_node (identifier))))))
+```
+
+## Regenerating Parser
+
+If grammar.js changes:
+```bash
+cd /Users/sienna/Development/storybook/tree-sitter-storybook && npm run build
+```
+
+This runs `tree-sitter generate` and compiles the parser.
+
+## Test Results (as of 2026-02-09)
+
+✅ All 27 tests passing:
+- 17 declaration tests
+- 7 behavior tree tests (selector, sequence, repeat, nested, subtree, etc.)
+- 3 basic tests
+
+## Behavior Tree Node Types Tested
+
+- `action_node` - Simple action identifiers
+- `selector_node` - `? { ... }` - Try options in order
+- `sequence_node` - `> { ... }` - Execute in sequence
+- `repeat_node` - `* { ... }` - Repeat forever
+- `subtree_node` - `@path::to::tree` - Reference external behavior
+
+## Common Issues
+
+1. **Bash tool failing with exit code 1** - Use Serena's execute_shell_command instead
+2. **Path structure mismatch** - Remember paths include path_segments wrapper
+3. **Missing declaration wrapper** - All top-level items wrap in `(declaration ...)`
+4. **Missing behavior_node wrapper** - Behavior children wrap in `(behavior_node ...)`