Draft semantic index (#1143)

Part of #1141 

Implements scopes and symbol tables. Prelude to implementing use-def
maps.

To get oriented:
- See comments documenting the new data structures in
`src/semantic_index.rs`
- See `tests/builder.rs` documenting the behaviour of the recursive
descent in `src/builder.rs`.

Author: lionel-

AGENTS.md

@@ -19,9 +19,19 @@ The codebase is organized as a Rust workspace containing multiple crates:
 - **harp**: Rust wrappers for R objects and interfaces
 - **libr**: Bindings to R (dynamically loaded using `dlopen`/`LoadLibrary`)
 - **amalthea**: A Rust framework for building Jupyter and Positron kernels
+- **oak_index**: Per-file semantic index for R (scopes, symbols, definitions, uses)
 - **echo**: A toy kernel for testing the kernel framework
 - **stdext**: Extensions to Rust's standard library used by the other projects
 
+### External dependencies (R parser)
+
+The `oak_index` and `ark` crates depend on the R parser from [posit-dev/air](https://github.com/posit-dev/air), pinned by git revision in the workspace `Cargo.toml`. The relevant crates are re-exported under `aether_` prefixes:
+
+- **`aether_syntax`** (`air_r_syntax`): Typed CST nodes (`RIdentifier`, `RBinaryExpression`, `RFunctionDefinition`, etc.), `RSyntaxKind`, `RSyntaxNode`, `RSyntaxToken`.
+- **`aether_parser`** (`air_r_parser`): `parse()` function that produces an `RRoot` CST.
+
+Source code for these crates lives in `posit-dev/air` under `crates/air_r_syntax/` and `crates/air_r_parser/`. When looking up type definitions, AST node variants, or syntax kinds, consult that repository.
+
 ## Common Development Commands
 
 ### Building the Project

Cargo.lock

@@ -15,6 +15,7 @@ members = [
     "crates/echo",
     "crates/harp",
     "crates/libr",
+    "crates/oak_index",
     "crates/stdext",
 ]
 
@@ -74,6 +75,7 @@ log = "0.4.18"
 mime_guess = "2.0.4"
 nix = { version = "0.26.2", features = ["signal"] }
 notify = "6.0.0"
+oak_index = { path = "crates/oak_index" }
 once_cell = "1.17.1"
 parking_lot = "0.12.3"
 paste = "1.0.14"

Cargo.toml

@@ -0,0 +1,22 @@
+[package]
+name = "oak_index"
+version = "0.1.0"
+description = """
+Per-file semantic index for R: scopes, symbols, bindings, and uses.
+"""
+
+authors.workspace = true
+edition.workspace = true
+license.workspace = true
+rust-version.workspace = true
+
+[lints]
+workspace = true
+
+[dependencies]
+aether_syntax.workspace = true
+biome_rowan.workspace = true
+rustc-hash.workspace = true
+
+[dev-dependencies]
+aether_parser.workspace = true