feat: add wasm-bindgen target (closes beda-software#13)

Add a `wasm` feature flag that compiles the FHIRPath parser and SDC
expression analyzer to WebAssembly via wasm-bindgen. The WASM bindings
expose parse(), annotate_expression(), analyze_expression(), and
QuestionnaireIndex to JavaScript consumers.

- Add wasm-bindgen and serde-wasm-bindgen as optional dependencies
- Add Serialize derives to AST and analysis types for JS interop
- Add serde rename attributes for snake_case/tagged enum serialization
- Add hand-written TypeScript type definitions in wasm/
- Add CI job to build WASM and upload artifacts
- Add rlib to crate-type to support both cdylib and test builds

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: axelv

.github/workflows/build.yaml

@@ -28,7 +28,9 @@ jobs:
       run: uv python install ${{ matrix.python-version }}
     - name: Install dependencies
       run: uv sync --extra test
-    - name: Run tests
+    - name: Run Rust tests
+      run: cargo test --no-default-features
+    - name: Run Python tests
       run: uv run pytest
     - name: Upload coverage to Codecov
       uses: codecov/codecov-action@v4
@@ -40,3 +42,25 @@ jobs:
         flags: unittests
         name: codecov-umbrella
         verbose: true
+
+  wasm:
+    runs-on: ubuntu-latest
+    steps:
+    - uses: actions/checkout@v4
+    - name: Install Rust toolchain
+      uses: dtolnay/rust-toolchain@stable
+      with:
+        targets: wasm32-unknown-unknown
+    - name: Install wasm-pack
+      run: curl https://rustwasm.github.io/wasm-pack/installer/init.sh -sSf | sh
+    - name: Build WASM
+      run: wasm-pack build --target web --features wasm --no-default-features
+    - name: Overlay custom package metadata and types
+      run: |
+        cp wasm/package.json pkg/package.json
+        cp wasm/fhirpath_wasm.d.ts pkg/fhirpath_wasm.d.ts
+    - name: Upload WASM artifacts
+      uses: actions/upload-artifact@v4
+      with:
+        name: wasm-pkg
+        path: pkg/

.gitignore

@@ -74,6 +74,9 @@ docs/_build/
 # Rust / Cargo build artifacts
 target/
 
+# wasm-pack build output
+pkg/
+
 # Jupyter Notebook
 .ipynb_checkpoints
 

Cargo.lock

@@ -5,13 +5,16 @@ edition = "2021"
 
 [lib]
 name = "_rust"
-crate-type = ["cdylib"]
+crate-type = ["cdylib", "rlib"]
 
 [features]
 default = ["python"]
 python = ["dep:pyo3"]
+wasm = ["dep:wasm-bindgen", "dep:serde-wasm-bindgen"]
 
 [dependencies]
 pyo3 = { version = "0.25", features = ["extension-module"], optional = true }
 serde = { version = "1", features = ["derive"] }
 serde_json = "1"
+wasm-bindgen = { version = "0.2", optional = true }
+serde-wasm-bindgen = { version = "0.6", optional = true }

Cargo.toml

@@ -6,13 +6,14 @@
 
 // ── Core types ──────────────────────────────────────────────────────────
 
-#[derive(Debug, Clone, PartialEq)]
+#[derive(Debug, Clone, PartialEq, serde::Serialize)]
 pub struct Span {
     pub start: usize,
     pub end: usize,
 }
 
-#[derive(Debug, Clone, PartialEq)]
+#[derive(Debug, Clone, PartialEq, serde::Serialize)]
+#[serde(rename_all = "snake_case")]
 pub enum ValueAccessor {
     /// `.answer.value` (bare)
     Value,
@@ -22,7 +23,8 @@ pub enum ValueAccessor {
     Display,
 }
 
-#[derive(Debug, Clone, PartialEq)]
+#[derive(Debug, Clone, PartialEq, serde::Serialize)]
+#[serde(tag = "type", rename_all = "snake_case")]
 pub enum AnnotationKind {
     /// Path navigating to a QR answer value.
     AnswerReference {
@@ -39,19 +41,21 @@ pub enum AnnotationKind {
     },
 }
 
-#[derive(Debug, Clone, PartialEq)]
+#[derive(Debug, Clone, PartialEq, serde::Serialize)]
 pub struct Annotation {
     pub span: Span,
     pub kind: AnnotationKind,
 }
 
-#[derive(Debug, Clone, PartialEq)]
+#[derive(Debug, Clone, PartialEq, serde::Serialize)]
+#[serde(rename_all = "snake_case")]
 pub enum Severity {
     Error,
     Warning,
 }
 
-#[derive(Debug, Clone, PartialEq)]
+#[derive(Debug, Clone, PartialEq, serde::Serialize)]
+#[serde(rename_all = "snake_case")]
 pub enum DiagnosticCode {
     UnknownLinkId,
     UnreachableLinkId,
@@ -61,7 +65,7 @@ pub enum DiagnosticCode {
     ContextUnreachableFromParent,
 }
 
-#[derive(Debug, Clone, PartialEq)]
+#[derive(Debug, Clone, PartialEq, serde::Serialize)]
 pub struct Diagnostic {
     pub span: Span,
     pub severity: Severity,
@@ -86,7 +90,7 @@ pub struct AnalysisContext {
 }
 
 /// Result of analyzing a FHIRPath expression.
-#[derive(Debug, Clone, PartialEq)]
+#[derive(Debug, Clone, PartialEq, serde::Serialize)]
 pub struct ExpressionAnalysis {
     pub annotations: Vec<Annotation>,
     pub diagnostics: Vec<Diagnostic>,

src/analyze/mod.rs

@@ -1,2 +1,5 @@
 #[cfg(feature = "python")]
 pub mod python;
+
+#[cfg(feature = "wasm")]
+pub mod wasm;

src/bindings/mod.rs

@@ -0,0 +1,71 @@
+#![cfg(feature = "wasm")]
+
+use wasm_bindgen::prelude::*;
+
+use crate::analyze;
+
+/// Parse a FHIRPath expression string into an AST.
+///
+/// Returns the AST as a JavaScript object.
+#[wasm_bindgen]
+pub fn parse(expr: &str) -> Result<JsValue, JsError> {
+    let ast = crate::parse(expr).map_err(|e| JsError::new(&e.0))?;
+    serde_wasm_bindgen::to_value(&ast).map_err(|e| JsError::new(&e.to_string()))
+}
+
+/// Annotate a FHIRPath expression, extracting answer references,
+/// item references, and coded values.
+///
+/// Returns `Annotation[]` as a JavaScript value.
+#[wasm_bindgen]
+pub fn annotate_expression(expr: &str) -> Result<JsValue, JsError> {
+    let annotations =
+        analyze::annotate_expression(expr).map_err(|e| JsError::new(&e.to_string()))?;
+    serde_wasm_bindgen::to_value(&annotations).map_err(|e| JsError::new(&e.to_string()))
+}
+
+/// A Questionnaire index for use in expression analysis.
+///
+/// Build one from a FHIR Questionnaire JSON string, then pass it
+/// to `analyze_expression` for semantic validation.
+#[wasm_bindgen]
+pub struct QuestionnaireIndex {
+    inner: analyze::QuestionnaireIndex,
+}
+
+#[wasm_bindgen]
+impl QuestionnaireIndex {
+    /// Build a `QuestionnaireIndex` from a FHIR Questionnaire JSON string.
+    #[wasm_bindgen(constructor)]
+    pub fn new(questionnaire_json: &str) -> Result<QuestionnaireIndex, JsError> {
+        let value: serde_json::Value = serde_json::from_str(questionnaire_json)
+            .map_err(|e| JsError::new(&format!("Invalid JSON: {e}")))?;
+        Ok(QuestionnaireIndex {
+            inner: analyze::QuestionnaireIndex::build(&value),
+        })
+    }
+}
+
+/// Analyze a FHIRPath expression in the context of a Questionnaire.
+///
+/// Returns `{ annotations: Annotation[], diagnostics: Diagnostic[] }`.
+///
+/// - `expr` -- the FHIRPath expression string
+/// - `index` -- a `QuestionnaireIndex` built from the Questionnaire
+/// - `scope_link_id` -- optional linkId of the item scope (for reachability checks)
+/// - `parent_context_expr` -- optional parent context expression (raw FHIRPath)
+#[wasm_bindgen]
+pub fn analyze_expression(
+    expr: &str,
+    index: &QuestionnaireIndex,
+    scope_link_id: Option<String>,
+    parent_context_expr: Option<String>,
+) -> Result<JsValue, JsError> {
+    let context = analyze::AnalysisContext {
+        scope_link_id,
+        parent_context_expr,
+    };
+    let result = analyze::analyze_expression(expr, &index.inner, &context)
+        .map_err(|e| JsError::new(&e.to_string()))?;
+    serde_wasm_bindgen::to_value(&result).map_err(|e| JsError::new(&e.to_string()))
+}

src/bindings/wasm.rs

@@ -2,7 +2,7 @@
 
 use crate::lexer::{Token, TokenKind};
 
-#[derive(Debug, Clone)]
+#[derive(Debug, Clone, serde::Serialize)]
 pub struct AstNode {
     pub node_type: &'static str,
     pub terminal_node_text: Vec<String>,