feat(baml_syntax): Add Rowan-based syntax tree infrastructure for BAML (#2687)

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.

<!-- CURSOR_SUMMARY -->
---

> [!NOTE]
> Adds a Rowan-backed, lossless syntax tree for BAML with typed AST
nodes, builder and traversal utilities, expands SyntaxKind, and updates
the parser/tests to use SOURCE_FILE as the root.
> 
> - **baml_syntax**:
> - **SyntaxKind**: Expand and reorganize token/node kinds; add helpers
(`is_trivia`, `is_literal`, `is_operator`) and conversions.
> - **Typed AST**: Add node wrappers (e.g., `SourceFile`, `FunctionDef`,
`ClassDef`) and `Item` enum with accessors (names, params, fields).
> - **Builder**: Introduce `SyntaxTreeBuilder` with helpers to build
functions/classes for tests.
> - **Traversal**: Add utilities for ancestor/descendant lookup, token
iteration, error checks, and trimmed ranges.
>   - **Lib exports & tests**: Wire modules and add unit tests.
> - **baml_parser**:
>   - Wrap tokens under `SOURCE_FILE` in stub `parse_file`.
> - **Tests/Snapshots**:
>   - Update expected root node from `ROOT` to `SOURCE_FILE`.
> 
> <sup>Written by [Cursor
Bugbot](https://cursor.com/dashboard?tab=bugbot) for commit
d28d9bd. This will update automatically
on new commits. Configure
[here](https://cursor.com/dashboard?tab=bugbot).</sup>
<!-- /CURSOR_SUMMARY -->

Author: hellovai

baml_language/crates/baml_parser/src/parser.rs

@@ -13,12 +13,12 @@ use crate::ParseError;
 ///
 /// Returns the green tree and any parse errors encountered.
 ///
-/// **STUB**: Currently just wraps all tokens in a ROOT node.
+/// **STUB**: Currently just wraps all tokens in a `SOURCE_FILE` node.
 pub fn parse_file(tokens: &[Token]) -> (GreenNode, Vec<ParseError>) {
     let mut builder = GreenNodeBuilder::new();
     let errors = Vec::new();
 
-    builder.start_node(SyntaxKind::ROOT.into());
+    builder.start_node(SyntaxKind::SOURCE_FILE.into());
 
     // Stub: Just add all tokens as-is
     for token in tokens {

baml_language/crates/baml_syntax/src/ast.rs

@@ -0,0 +1,220 @@
+//! Typed AST node wrappers for ergonomic tree access.
+
+use crate::{SyntaxKind, SyntaxNode, SyntaxToken};
+use rowan::ast::AstNode;
+
+/// Trait for all AST nodes.
+pub trait BamlAstNode: AstNode<Language = crate::BamlLanguage> {
+    /// Get the syntax kind of this node.
+    fn kind(&self) -> SyntaxKind {
+        self.syntax().kind()
+    }
+}
+
+/// Macro to define AST node types.
+macro_rules! ast_node {
+    ($name:ident, $kind:ident) => {
+        #[derive(Debug, Clone, PartialEq, Eq, Hash)]
+        pub struct $name {
+            syntax: SyntaxNode,
+        }
+
+        impl BamlAstNode for $name {}
+
+        impl AstNode for $name {
+            type Language = crate::BamlLanguage;
+
+            fn can_cast(kind: <Self::Language as rowan::Language>::Kind) -> bool {
+                kind == SyntaxKind::$kind.into()
+            }
+
+            fn cast(syntax: SyntaxNode) -> Option<Self> {
+                if Self::can_cast(syntax.kind()) {
+                    Some(Self { syntax })
+                } else {
+                    None
+                }
+            }
+
+            fn syntax(&self) -> &SyntaxNode {
+                &self.syntax
+            }
+        }
+    };
+}
+
+// Define all AST node types
+ast_node!(SourceFile, SOURCE_FILE);
+ast_node!(FunctionDef, FUNCTION_DEF);
+ast_node!(ClassDef, CLASS_DEF);
+ast_node!(EnumDef, ENUM_DEF);
+ast_node!(ClientDef, CLIENT_DEF);
+ast_node!(TestDef, TEST_DEF);
+ast_node!(RetryPolicyDef, RETRY_POLICY_DEF);
+ast_node!(TemplateStringDef, TEMPLATE_STRING_DEF);
+ast_node!(TypeAliasDef, TYPE_ALIAS_DEF);
+
+ast_node!(ParameterList, PARAMETER_LIST);
+ast_node!(Parameter, PARAMETER);
+ast_node!(FunctionBody, FUNCTION_BODY);
+ast_node!(Field, FIELD);
+ast_node!(EnumVariant, ENUM_VARIANT);
+ast_node!(ConfigBlock, CONFIG_BLOCK);
+ast_node!(ConfigItem, CONFIG_ITEM);
+
+ast_node!(TypeExpr, TYPE_EXPR);
+ast_node!(Attribute, ATTRIBUTE);
+ast_node!(BlockAttribute, BLOCK_ATTRIBUTE);
+
+ast_node!(Expr, EXPR);
+ast_node!(LetStmt, LET_STMT);
+ast_node!(IfExpr, IF_EXPR);
+ast_node!(WhileStmt, WHILE_STMT);
+ast_node!(ForExpr, FOR_EXPR);
+ast_node!(BlockExpr, BLOCK_EXPR);
+
+// Implement accessor methods
+impl SourceFile {
+    /// Iterate over all top-level items in the file.
+    pub fn items(&self) -> impl Iterator<Item = Item> {
+        self.syntax.children().filter_map(Item::cast)
+    }
+}
+
+impl FunctionDef {
+    /// Get the function name.
+    pub fn name(&self) -> Option<SyntaxToken> {
+        self.syntax
+            .children_with_tokens()
+            .filter_map(rowan::NodeOrToken::into_token)
+            .filter(|token| {
+                token.kind() == SyntaxKind::WORD && token.parent() == Some(self.syntax.clone())
+            })
+            .nth(1) // Skip the "function" keyword, get the second WORD
+    }
+
+    /// Get the parameter list.
+    pub fn param_list(&self) -> Option<ParameterList> {
+        self.syntax.children().find_map(ParameterList::cast)
+    }
+
+    /// Get the return type.
+    pub fn return_type(&self) -> Option<TypeExpr> {
+        self.syntax.children().find_map(TypeExpr::cast)
+    }
+
+    /// Get the function body.
+    pub fn body(&self) -> Option<FunctionBody> {
+        self.syntax.children().find_map(FunctionBody::cast)
+    }
+}
+
+impl ParameterList {
+    /// Get all parameters.
+    pub fn params(&self) -> impl Iterator<Item = Parameter> {
+        self.syntax.children().filter_map(Parameter::cast)
+    }
+}
+
+impl ClassDef {
+    /// Get the class name.
+    pub fn name(&self) -> Option<SyntaxToken> {
+        self.syntax
+            .children_with_tokens()
+            .filter_map(rowan::NodeOrToken::into_token)
+            .filter(|token| {
+                token.kind() == SyntaxKind::WORD && token.parent() == Some(self.syntax.clone())
+            })
+            .nth(1) // Skip the "class" keyword, get the second WORD
+    }
+
+    /// Get all fields.
+    pub fn fields(&self) -> impl Iterator<Item = Field> {
+        self.syntax.children().filter_map(Field::cast)
+    }
+
+    /// Get block attributes (@@dynamic).
+    pub fn block_attributes(&self) -> impl Iterator<Item = BlockAttribute> {
+        self.syntax.children().filter_map(BlockAttribute::cast)
+    }
+}
+
+impl Field {
+    /// Get the field name.
+    pub fn name(&self) -> Option<SyntaxToken> {
+        self.syntax
+            .children_with_tokens()
+            .filter_map(rowan::NodeOrToken::into_token)
+            .find(|token| token.kind() == SyntaxKind::WORD)
+    }
+
+    /// Get the field type.
+    pub fn ty(&self) -> Option<TypeExpr> {
+        self.syntax.children().find_map(TypeExpr::cast)
+    }
+
+    /// Get field attributes (@alias, @description, etc.).
+    pub fn attributes(&self) -> impl Iterator<Item = Attribute> {
+        self.syntax.children().filter_map(Attribute::cast)
+    }
+}
+
+/// Enum for any top-level item.
+#[derive(Debug, Clone, PartialEq, Eq, Hash)]
+pub enum Item {
+    Function(FunctionDef),
+    Class(ClassDef),
+    Enum(EnumDef),
+    Client(ClientDef),
+    Test(TestDef),
+    RetryPolicy(RetryPolicyDef),
+    TemplateString(TemplateStringDef),
+    TypeAlias(TypeAliasDef),
+}
+
+impl AstNode for Item {
+    type Language = crate::BamlLanguage;
+
+    fn can_cast(kind: <Self::Language as rowan::Language>::Kind) -> bool {
+        matches!(
+            kind,
+            SyntaxKind::FUNCTION_DEF
+                | SyntaxKind::CLASS_DEF
+                | SyntaxKind::ENUM_DEF
+                | SyntaxKind::CLIENT_DEF
+                | SyntaxKind::TEST_DEF
+                | SyntaxKind::RETRY_POLICY_DEF
+                | SyntaxKind::TEMPLATE_STRING_DEF
+                | SyntaxKind::TYPE_ALIAS_DEF
+        )
+    }
+
+    fn cast(syntax: SyntaxNode) -> Option<Self> {
+        match syntax.kind() {
+            SyntaxKind::FUNCTION_DEF => Some(Item::Function(FunctionDef { syntax })),
+            SyntaxKind::CLASS_DEF => Some(Item::Class(ClassDef { syntax })),
+            SyntaxKind::ENUM_DEF => Some(Item::Enum(EnumDef { syntax })),
+            SyntaxKind::CLIENT_DEF => Some(Item::Client(ClientDef { syntax })),
+            SyntaxKind::TEST_DEF => Some(Item::Test(TestDef { syntax })),
+            SyntaxKind::RETRY_POLICY_DEF => Some(Item::RetryPolicy(RetryPolicyDef { syntax })),
+            SyntaxKind::TEMPLATE_STRING_DEF => {
+                Some(Item::TemplateString(TemplateStringDef { syntax }))
+            }
+            SyntaxKind::TYPE_ALIAS_DEF => Some(Item::TypeAlias(TypeAliasDef { syntax })),
+            _ => None,
+        }
+    }
+
+    fn syntax(&self) -> &SyntaxNode {
+        match self {
+            Item::Function(it) => it.syntax(),
+            Item::Class(it) => it.syntax(),
+            Item::Enum(it) => it.syntax(),
+            Item::Client(it) => it.syntax(),
+            Item::Test(it) => it.syntax(),
+            Item::RetryPolicy(it) => it.syntax(),
+            Item::TemplateString(it) => it.syntax(),
+            Item::TypeAlias(it) => it.syntax(),
+        }
+    }
+}

baml_language/crates/baml_syntax/src/builder.rs

@@ -0,0 +1,158 @@
+//! Utilities for building syntax trees programmatically.
+//! Primarily used for testing.
+
+use crate::SyntaxKind;
+use rowan::{GreenNode, GreenNodeBuilder};
+
+/// Builder for constructing syntax trees.
+pub struct SyntaxTreeBuilder {
+    builder: GreenNodeBuilder<'static>,
+}
+
+impl SyntaxTreeBuilder {
+    /// Create a new tree builder.
+    pub fn new() -> Self {
+        Self {
+            builder: GreenNodeBuilder::new(),
+        }
+    }
+
+    /// Start a new node of the given kind.
+    pub fn start_node(&mut self, kind: SyntaxKind) {
+        self.builder.start_node(kind.into());
+    }
+
+    /// Finish the current node.
+    pub fn finish_node(&mut self) {
+        self.builder.finish_node();
+    }
+
+    /// Add a token to the tree.
+    pub fn token(&mut self, kind: SyntaxKind, text: &str) {
+        self.builder.token(kind.into(), text);
+    }
+
+    /// Add whitespace.
+    pub fn ws(&mut self, text: &str) {
+        self.token(SyntaxKind::WHITESPACE, text);
+    }
+
+    /// Add a newline.
+    pub fn nl(&mut self) {
+        self.token(SyntaxKind::NEWLINE, "\n");
+    }
+
+    /// Build and consume the builder, returning the green tree.
+    pub fn finish(self) -> GreenNode {
+        self.builder.finish()
+    }
+
+    /// Build a simple function for testing.
+    pub fn build_function(name: &str, params: &[(&str, &str)], ret_type: &str) -> GreenNode {
+        let mut builder = Self::new();
+
+        builder.start_node(SyntaxKind::SOURCE_FILE);
+        builder.start_node(SyntaxKind::FUNCTION_DEF);
+
+        // function keyword
+        builder.token(SyntaxKind::WORD, "function");
+        builder.ws(" ");
+
+        // function name
+        builder.token(SyntaxKind::WORD, name);
+
+        // parameters
+        builder.start_node(SyntaxKind::PARAMETER_LIST);
+        builder.token(SyntaxKind::L_PAREN, "(");
+
+        for (i, (param_name, param_type)) in params.iter().enumerate() {
+            if i > 0 {
+                builder.token(SyntaxKind::COMMA, ",");
+                builder.ws(" ");
+            }
+
+            builder.start_node(SyntaxKind::PARAMETER);
+            builder.token(SyntaxKind::WORD, param_name);
+            builder.token(SyntaxKind::COLON, ":");
+            builder.ws(" ");
+            builder.start_node(SyntaxKind::TYPE_EXPR);
+            builder.token(SyntaxKind::WORD, param_type);
+            builder.finish_node(); // TYPE_EXPR
+            builder.finish_node(); // PARAMETER
+        }
+
+        builder.token(SyntaxKind::R_PAREN, ")");
+        builder.finish_node(); // PARAMETER_LIST
+
+        // return type
+        builder.ws(" ");
+        builder.token(SyntaxKind::ARROW, "->");
+        builder.ws(" ");
+        builder.start_node(SyntaxKind::TYPE_EXPR);
+        builder.token(SyntaxKind::WORD, ret_type);
+        builder.finish_node(); // TYPE_EXPR
+
+        // body
+        builder.ws(" ");
+        builder.start_node(SyntaxKind::FUNCTION_BODY);
+        builder.token(SyntaxKind::L_BRACE, "{");
+        builder.nl();
+        builder.ws("  ");
+        builder.token(SyntaxKind::WORD, "client");
+        builder.ws(" ");
+        builder.token(SyntaxKind::WORD, "GPT4");
+        builder.nl();
+        builder.token(SyntaxKind::R_BRACE, "}");
+        builder.finish_node(); // FUNCTION_BODY
+
+        builder.finish_node(); // FUNCTION_DEF
+        builder.finish_node(); // SOURCE_FILE
+
+        builder.finish()
+    }
+
+    /// Build a simple class for testing.
+    pub fn build_class(name: &str, fields: &[(&str, &str)]) -> GreenNode {
+        let mut builder = Self::new();
+
+        builder.start_node(SyntaxKind::SOURCE_FILE);
+        builder.start_node(SyntaxKind::CLASS_DEF);
+
+        // class keyword
+        builder.token(SyntaxKind::WORD, "class");
+        builder.ws(" ");
+
+        // class name
+        builder.token(SyntaxKind::WORD, name);
+        builder.ws(" ");
+
+        // body
+        builder.token(SyntaxKind::L_BRACE, "{");
+        builder.nl();
+
+        // fields
+        for (field_name, field_type) in fields {
+            builder.ws("  ");
+            builder.start_node(SyntaxKind::FIELD);
+            builder.token(SyntaxKind::WORD, field_name);
+            builder.ws(" ");
+            builder.start_node(SyntaxKind::TYPE_EXPR);
+            builder.token(SyntaxKind::WORD, field_type);
+            builder.finish_node(); // TYPE_EXPR
+            builder.finish_node(); // FIELD
+            builder.nl();
+        }
+
+        builder.token(SyntaxKind::R_BRACE, "}");
+        builder.finish_node(); // CLASS_DEF
+        builder.finish_node(); // SOURCE_FILE
+
+        builder.finish()
+    }
+}
+
+impl Default for SyntaxTreeBuilder {
+    fn default() -> Self {
+        Self::new()
+    }
+}