Refactor parser implementation with improved tree structure and error recovery
- Add comprehensive parser implementation documentation
- Update parser.rs with improved tree building logic
- Enhance AST and syntax tree traversal
- Update all parser test snapshots
- Add parser tree reference documentation
- Improve error recovery in parser
- Fix clippy warning: mark ParserCheckpoint as Copy
feat(baml_syntax): Add Rowan-based syntax tree infrastructure for BAML
Introduces a lossless, incremental syntax tree representation for BAML source code
using the Rowan library (same as rust-analyzer). This provides the foundation for
all language tooling including parsing, semantic analysis, and IDE features.
## What is a Syntax Tree?
A syntax tree represents the grammatical structure of source code. Unlike traditional
ASTs, Rowan syntax trees are:
- Lossless: preserve all source text including whitespace and comments
- Incremental: support efficient updates when code changes
- Lazy: nodes are created on-demand during traversal
- Parent-aware: nodes can traverse up to their parents
## Key Components
**SyntaxKind**: Defines all possible elements in BAML code
- Tokens: WORD, INTEGER, L_BRACE, ARROW, etc.
- Nodes: FUNCTION_DEF, CLASS_DEF, TYPE_EXPR, etc.
**Typed AST Nodes**: Provide ergonomic access to tree structure
```rust
// Example from tests:
let function = source_file.items()
.find_map(|item| match item {
Item::Function(f) => Some(f),
_ => None,
})
.unwrap();
assert_eq!(function.name().unwrap().text(), "GetUser");
```
**Tree Builder**: Enables programmatic tree construction for testing
```rust
let tree = SyntaxTreeBuilder::build_function(
"GetUser",
&[("id", "int"), ("name", "string")],
"User"
);
// Produces: function GetUser(id: int, name: string) -> User { ... }
```
**Traversal Utilities**: Navigate and query syntax trees
- Find nodes by type at specific text positions
- Search for ancestors/descendants of specific kinds
- Filter out trivia (whitespace/comments) when needed
## Why This Matters
This infrastructure enables:
- Error-resilient parsing (partial trees even with syntax errors)
- Incremental re-parsing (only changed portions)
- Precise source locations for diagnostics
- Code formatting that preserves comments
- Refactoring tools that maintain code style
- IDE features like go-to-definition and hover
The lossless property means we can perfectly reconstruct the original source,
essential for formatters and refactoring tools that need to preserve user intent.