Add in-repository Tree-sitter parser and grammar for Bash++

.github/workflows/tree-sitter.yml

@@ -0,0 +1,45 @@
+name: Tree-sitter Parser
+
+on:
+  pull_request:
+    paths:
+      - ".github/workflows/tree-sitter.yml"
+      - "examples/**/*.bpp"
+      - "makefile"
+      - "test-suite/**/*.bpp"
+      - "tree-sitter-bashpp/**"
+      - "wiki/_includes/code/snippets/**/*.bpp"
+  push:
+    branches: ["main"]
+    paths:
+      - ".github/workflows/tree-sitter.yml"
+      - "examples/**/*.bpp"
+      - "makefile"
+      - "test-suite/**/*.bpp"
+      - "tree-sitter-bashpp/**"
+      - "wiki/_includes/code/snippets/**/*.bpp"
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+
+      - name: Set up Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: "22"
+          cache: npm
+          cache-dependency-path: tree-sitter-bashpp/package-lock.json
+
+      - name: Install dependencies
+        working-directory: tree-sitter-bashpp
+        run: npm ci
+
+      - name: Test parser
+        run: make test-tree-sitter

.gitignore

@@ -11,3 +11,9 @@ debian/*.7
 vscode/node_modules
 vscode/*.vsix
 vscode/dist
+tree-sitter-bashpp/node_modules
+tree-sitter-bashpp/.cache
+tree-sitter-bashpp/src/grammar.json
+tree-sitter-bashpp/src/node-types.json
+tree-sitter-bashpp/src/parser.c
+tree-sitter-bashpp/src/tree_sitter

README.md

@@ -70,6 +70,7 @@ Language server-specific prerequisites:
  - `nlohmann-json3-dev`
 
 Optional:
+ - `nodejs` and `npm` for developing the Tree-sitter parser
  - `pandoc` and `perl` for building the documentation
  - `debhelper` for building the Debian package and keeping version numbers up-to-date via `dpkg-parsechangelog`
 
@@ -86,6 +87,8 @@ $ sudo apt install build-essential flex bison libutfcpp-dev pandoc perl debhelpe
 $ make          # Build the Bash++ compiler and language server, bin/bpp and bin/bpp-lsp
 $ make manpages # Build the manpages, which can then be found under debian/
 $ make test     # Run the test suite to verify the compiler works correctly
+$ make tree-sitter      # Generate the optional Tree-sitter parser
+$ make test-tree-sitter # Test the parser against the repository's Bash++ sources
 ```
 
 ## Using the compiler

makefile

@@ -17,13 +17,22 @@ test:
 vscode:
 	@cd vscode && $(MAKE) --no-print-directory
 
+tree-sitter:
+	@$(MAKE) -C tree-sitter-bashpp --no-print-directory generate
+
+test-tree-sitter:
+	@$(MAKE) -C tree-sitter-bashpp --no-print-directory test
+
 clean-vscode:
 	@cd vscode && $(MAKE) --no-print-directory clean
 	@echo "Cleaned up VSCode extension files."
 
-clean: clean-flexbison clean-lsp clean-meta clean-objects clean-bin clean-std clean-manpages clean-technical-docs clean-vscode
+clean-tree-sitter:
+	@$(MAKE) -C tree-sitter-bashpp --no-print-directory clean
+
+clean: clean-flexbison clean-lsp clean-meta clean-objects clean-bin clean-std clean-manpages clean-technical-docs clean-vscode clean-tree-sitter
 
-.PHONY: all test vscode clean-vscode
+.PHONY: all test vscode tree-sitter test-tree-sitter clean-vscode clean-tree-sitter
 
 ifeq ($(filter clean%,$(MAKECMDGOALS)),)
 -include $(shell find bin -name '*.d' 2>/dev/null)

tree-sitter-bashpp/LICENSE

@@ -0,0 +1,15 @@
+Copyright (C) 2026 Bash++ contributors
+
+This file is part of Bash++.
+
+Bash++ is free software: you can redistribute it and/or modify it under the
+terms of the GNU General Public License as published by the Free Software
+Foundation, either version 3 of the License, or (at your option) any later
+version.
+
+Bash++ is distributed in the hope that it will be useful, but WITHOUT ANY
+WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR
+A PARTICULAR PURPOSE. See the GNU General Public License for more details.
+
+You should have received a copy of the GNU General Public License along with
+Bash++. If not, see <https://www.gnu.org/licenses/>.

tree-sitter-bashpp/Makefile

@@ -0,0 +1,20 @@
+.PHONY: all dependencies generate test clean
+
+all: generate
+
+dependencies: node_modules/.package-lock.json
+
+node_modules/.package-lock.json: package-lock.json
+	npm ci
+
+generate: dependencies
+	npm run generate
+
+test: dependencies
+	npm run generate
+	npm run lint
+	npm test
+	npm run test:repository
+
+clean:
+	rm -rf node_modules .cache src/grammar.json src/node-types.json src/parser.c src/tree_sitter

tree-sitter-bashpp/README.md

@@ -0,0 +1,53 @@
+# Tree-sitter Bash++
+
+This directory contains the Tree-sitter parser for Bash++. It extends the
+upstream [`tree-sitter-bash`](https://github.com/tree-sitter/tree-sitter-bash)
+0.25.1 grammar so that Bash syntax remains owned and tested by the Bash parser.
+The parser is kept in this repository because the compiler sources, examples,
+and documentation snippets are its compatibility suite.
+
+## Development
+
+From the repository root, install the locked dependencies and generate the
+tracked parser sources:
+
+```sh
+make tree-sitter
+```
+
+Run generation, linting, corpus tests, and repository-wide parsing:
+
+```sh
+make test-tree-sitter
+```
+
+Generated parser sources under `src/` are build artifacts and are not committed.
+Run `make tree-sitter` before compiling the parser or packaging an editor
+integration.
+
+The corpus is grouped by Bash compatibility, declarations, expressions,
+Bash interactions, and error recovery. Repository parsing covers every `.bpp`
+file under `examples/`, `test-suite/`, and `wiki/_includes/code/snippets/`.
+`parser-errors-1.bpp` and `parser-errors-2.bpp` are intentionally malformed and
+are asserted separately as recovery cases.
+
+## Grammar Interface
+
+Named nodes and fields in `grammar.js` are the parser's public interface.
+They cover classes and members, object and pointer declarations, references,
+assignments, allocation and casts, supershells, and Bash++ interpolation in
+Bash constructs. Future highlighting queries and editor integrations should
+consume these nodes rather than infer structure from source text.
+
+The external scanner is inherited from `tree-sitter-bash` and adapted only for
+Bash++ tokens that require lookahead, such as declaration types, assignment
+references, reference boundaries, and heredoc interpolation.
+
+## Scope and Licensing
+
+This milestone contains only the parser. It intentionally excludes highlighting
+queries, editor configuration, language bindings, and language-server support.
+
+New parser work is licensed under GPL-3.0-or-later. Adapted
+`tree-sitter-bash` material retains its MIT notice under
+`THIRD_PARTY_LICENSES/`.

tree-sitter-bashpp/THIRD_PARTY_LICENSES/tree-sitter-bash-MIT.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2017 Max Brunsfeld
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

tree-sitter-bashpp/eslint.config.mjs

@@ -0,0 +1,5 @@
+import treeSitter from 'eslint-config-treesitter';
+
+export default [
+  ...treeSitter,
+];