Rust: Add Herb Rust FFI Bindings (#767)

This pull request adds Rust bindings for Herb using FFI (Foreign
Function Interface) via `bindgen`, allowing Rust applications to parse
and analyze ERB templates with the same implementation as the native C,
Ruby C-Extension, C++ Emscripten WASM, Java JNI, and the C++ Node.js
NAPI bindings.

Building the Rust bindings is requires a Rust toolchain, Bundler, Prism,
and a C compiler:

```bash
cd rust
make all
```

Once built, you can use the `herb-rust` CLI tool:

#### **`herb-rust version`**
```
herb rust v0.7.5, libprism v1.6.0, libherb v0.7.5 (Rust FFI)
```

#### **`herb-rust lex examples/test.html.erb`**
```js
#<Herb::Token type="TOKEN_HTML_TAG_START" value="<" range=[0, 1] start=(1:0) end=(1:1)>
#<Herb::Token type="TOKEN_IDENTIFIER" value="h1" range=[1, 3] start=(1:1) end=(1:3)>
#<Herb::Token type="TOKEN_WHITESPACE" value=" " range=[3, 4] start=(1:3) end=(1:4)>
#<Herb::Token type="TOKEN_IDENTIFIER" value="class" range=[4, 9] start=(1:4) end=(1:9)>
#<Herb::Token type="TOKEN_EQUALS" value="=" range=[9, 10] start=(1:9) end=(1:10)>
#<Herb::Token type="TOKEN_QUOTE" value="\"" range=[10, 11] start=(1:10) end=(1:11)>
#<Herb::Token type="TOKEN_IDENTIFIER" value="title" range=[11, 16] start=(1:11) end=(1:16)>
#<Herb::Token type="TOKEN_QUOTE" value="\"" range=[16, 17] start=(1:16) end=(1:17)>
#<Herb::Token type="TOKEN_HTML_TAG_END" value=">" range=[17, 18] start=(1:17) end=(1:18)>
#<Herb::Token type="TOKEN_ERB_START" value="<%=" range=[18, 21] start=(1:18) end=(1:21)>
#<Herb::Token type="TOKEN_ERB_CONTENT" value=" content " range=[21, 30] start=(1:21) end=(1:30)>
#<Herb::Token type="TOKEN_ERB_END" value="%>" range=[30, 32] start=(1:30) end=(1:32)>
#<Herb::Token type="TOKEN_HTML_TAG_START_CLOSE" value="</" range=[32, 34] start=(1:32) end=(1:34)>
#<Herb::Token type="TOKEN_IDENTIFIER" value="h1" range=[34, 36] start=(1:34) end=(1:36)>
#<Herb::Token type="TOKEN_HTML_TAG_END" value=">" range=[36, 37] start=(1:36) end=(1:37)>
#<Herb::Token type="TOKEN_NEWLINE" value="\n" range=[37, 38] start=(1:37) end=(2:0)>
#<Herb::Token type="TOKEN_EOF" value="<EOF>" range=[38, 38] start=(2:0) end=(2:0)>
```

#### **`herb-rust parse examples/test.html.erb`**
```js
@ DocumentNode (location: (1:0)-(2:0))
└── children: (2 items)
    ├── @ HTMLElementNode (location: (1:0)-(1:37))
    │   ├── open_tag: 
    │   │   └── @ HTMLOpenTagNode (location: (1:0)-(1:18))
    │   │       ├── tag_opening: "<" (location: (1:0)-(1:1))
    │   │       ├── tag_name: "h1" (location: (1:1)-(1:3))
    │   │       ├── tag_closing: ">" (location: (1:17)-(1:18))
    │   │       ├── children: (1 item)
    │   │       │   └── @ HTMLAttributeNode (location: (1:4)-(1:17))
    │   │       │       ├── name: 
    │   │       │       │   └── @ HTMLAttributeNameNode (location: (1:4)-(1:9))
    │   │       │       │       └── children: (1 item)
    │   │       │       │           └── @ LiteralNode (location: (1:4)-(1:9))
    │   │       │       │               └── content: "class"
    │   │       │       │   
    │   │       │       ├── equals: "=" (location: (1:9)-(1:10))
    │   │       │       └── value: 
    │   │       │           └── @ HTMLAttributeValueNode (location: (1:10)-(1:17))
    │   │       │               ├── open_quote: "\"" (location: (1:10)-(1:11))
    │   │       │               ├── children: (1 item)
    │   │       │               │   └── @ LiteralNode (location: (1:11)-(1:16))
    │   │       │               │       └── content: "title"
    │   │       │               ├── close_quote: "\"" (location: (1:16)-(1:17))
    │   │       │               └── quoted: true
    │   │       └── is_void: false
    │   │   
    │   ├── tag_name: "h1" (location: (1:1)-(1:3))
    │   ├── body: (1 item)
    │   │   └── @ ERBContentNode (location: (1:18)-(1:32))
    │   │       ├── tag_opening: "<%=" (location: (1:18)-(1:21))
    │   │       ├── content: " content " (location: (1:21)-(1:30))
    │   │       ├── tag_closing: "%>" (location: (1:30)-(1:32))
    │   │       ├── parsed: false
    │   │       └── valid: false
    │   ├── close_tag: 
    │   │   └── @ HTMLCloseTagNode (location: (1:32)-(1:37))
    │   │       ├── tag_opening: "</" (location: (1:32)-(1:34))
    │   │       ├── tag_name: "h1" (location: (1:34)-(1:36))
    │   │       ├── children: []
    │   │       └── tag_closing: ">" (location: (1:36)-(1:37))
    │   │   
    │   ├── is_void: false
    │   └── source: "HTML"
    │   
    └── @ HTMLTextNode (location: (1:37)-(2:0))
        └── content: "\n"
```

Resolves #647

Author: marcoroth

.envrc

@@ -5,3 +5,4 @@ export PATH="$PWD/javascript/packages/language-server/bin:$PATH"
 export PATH="$PWD/javascript/packages/highlighter/bin:$PATH"
 export PATH="$PWD/javascript/packages/stimulus-lint/bin:$PATH"
 export PATH="$PWD/java/bin:$PATH"
+export PATH="$PWD/rust/bin:$PATH"

.gitattributes

@@ -5,6 +5,7 @@ templates/**/*.h.erb linguist-language=C
 templates/**/*.java.erb linguist-language=Java
 templates/**/*.js.erb linguist-language=JavaScript
 templates/**/*.rb.erb linguist-language=Ruby
+templates/**/*.rs.erb linguist-language=Rust
 templates/**/*.ts.erb linguist-language=TypeScript
 
 # Template-generated RBS files

.github/labeler.yml

@@ -22,6 +22,7 @@ rust:
   - changed-files:
     - any-glob-to-any-file:
       - '**/*.rs'
+      - '**/*.rs.erb'
       - '**/Cargo.toml'
       - '**/Cargo.lock'
 

.github/workflows/rust.yml

@@ -0,0 +1,68 @@
+name: Rust
+
+on:
+  push:
+    branches:
+      - main
+  pull_request:
+
+permissions:
+  actions: read
+  contents: read
+
+jobs:
+  build:
+    name: Build
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Set up Rust
+        uses: actions-rust-lang/setup-rust-toolchain@v1
+        with:
+          toolchain: stable
+          components: clippy
+
+      - name: Set up Rust Nightly (for rustfmt)
+        uses: actions-rust-lang/setup-rust-toolchain@v1
+        with:
+          toolchain: nightly
+          components: rustfmt
+
+      - name: Rust Cache
+        uses: Swatinem/rust-cache@v2
+        with:
+          workspaces: rust
+
+      - name: Set up Ruby
+        uses: ruby/setup-ruby@v1
+        with:
+          bundler-cache: true
+
+      - name: bundle install
+        run: bundle install
+
+      - name: Render Templates
+        run: bundle exec rake templates
+
+      - name: Compile Herb
+        run: bundle exec rake make
+
+      - name: Check Rust formatting
+        run: make format-check
+        working-directory: rust
+
+      - name: Clippy
+        run: make lint
+        working-directory: rust
+
+      - name: Build Rust
+        run: make build
+        working-directory: rust
+
+      - name: Run Rust tests
+        run: make test
+        working-directory: rust

.gitignore

@@ -108,6 +108,9 @@ javascript/packages/node/extension/nodes.h
 lib/herb/ast/nodes.rb
 lib/herb/errors.rb
 lib/herb/visitor.rb
+rust/src/ast/nodes.rs
+rust/src/errors.rs
+rust/src/nodes.rs
 sig/serialized_ast_errors.rbs
 sig/serialized_ast_nodes.rbs
 src/ast_nodes.c
@@ -126,6 +129,10 @@ wasm/nodes.h
 java/target/
 java/.java_compiled
 
+# Rust Build Artifacts
+rust/target/
+rust/Cargo.lock
+
 # NX Monorepo
 .nx/
 .nx/cache

.rubocop.yml

@@ -93,6 +93,7 @@ Metrics/ClassLength:
 Metrics/ModuleLength:
   Exclude:
     - test/**/*.rb
+    - templates/**/*.rb
 
 Metrics/BlockLength:
   Max: 30
@@ -118,6 +119,7 @@ Metrics/PerceivedComplexity:
     - lib/herb/project.rb
     - lib/herb/engine.rb
     - lib/herb/engine/**/*.rb
+    - templates/template.rb
     - test/**/*.rb
     - bin/**/*
 

docs/.vitepress/config/theme.mts

@@ -98,6 +98,14 @@ const defaultSidebar = [
           { text: "Reference", link: "/bindings/java/reference" },
         ],
       },
+      {
+        text: "Rust",
+        collapsed: false,
+        items: [
+          { text: "Installation", link: "/bindings/rust/" },
+          { text: "Reference", link: "/bindings/rust/reference" },
+        ],
+      },
       { text: "WebAssembly", link: "/projects/webassembly" },
     ],
   },

docs/docs/bindings/java/index.md

@@ -10,6 +10,7 @@ Herb provides official Java bindings through JNI (Java Native Interface) to the
 > Herb also has bindings for:
 > - [Ruby](/bindings/ruby/)
 > - [JavaScript/Node.js](/bindings/javascript/)
+> - [Rust](/bindings/rust/)
 
 ## Installation
 

docs/docs/bindings/javascript/index.md

@@ -8,6 +8,7 @@ Herb supports both **browser** and **Node.js** environments with separate packag
 > Herb also has bindings for:
 > - [Ruby](/bindings/ruby/)
 > - [Java](/bindings/java/)
+> - [Rust](/bindings/rust/)
 
 ## Installation
 

docs/docs/bindings/ruby/index.md

@@ -10,6 +10,7 @@ Herb is bundled and packaged up as a precompiled RubyGem and available to be ins
 > Herb also has bindings for:
 > - [JavaScript/Node.js](/bindings/javascript/)
 > - [Java](/bindings/java/)
+> - [Rust](/bindings/rust/)
 
 ## Installation