From 361287fb56bd9a649281f6d2cf27e4a3b745fb4d Mon Sep 17 00:00:00 2001
From: Will Lillis <will.lillis24@gmail.com>
Date: Mon, 3 Nov 2025 01:46:05 -0500
Subject: [PATCH 01/14] fix(cli)!: deprecate `--build` flag for `generate`
 command

---
 crates/cli/src/main.rs   |  7 ++++---
 docs/src/cli/generate.md | 11 -----------
 2 files changed, 4 insertions(+), 14 deletions(-)

diff --git a/crates/cli/src/main.rs b/crates/cli/src/main.rs
index 9f895987..d9f8c174 100644
--- a/crates/cli/src/main.rs
+++ b/crates/cli/src/main.rs
@@ -114,13 +114,13 @@ struct Generate {
     /// Only generate `grammar.json` and `node-types.json`
     #[arg(long)]
     pub no_parser: bool,
-    /// Compile all defined languages in the current dir
+    /// Deprecated: use the `build` command
     #[arg(long, short = 'b')]
     pub build: bool,
-    /// Compile a parser in debug mode
+    /// Deprecated: use the `build` command
     #[arg(long, short = '0')]
     pub debug_build: bool,
-    /// The path to the directory containing the parser library
+    /// Deprecated: use the `build` command
     #[arg(long, value_name = "PATH")]
     pub libdir: Option<PathBuf>,
     /// The path to output the generated source files
@@ -905,6 +905,7 @@ impl Generate {
             }
         }
         if self.build {
+            warn!("--build is deprecated, use the `build` command");
             if let Some(path) = self.libdir {
                 loader = loader::Loader::with_parser_lib_path(path);
             }
diff --git a/docs/src/cli/generate.md b/docs/src/cli/generate.md
index 9014e0ea..32c8437a 100644
--- a/docs/src/cli/generate.md
+++ b/docs/src/cli/generate.md
@@ -34,17 +34,6 @@ The ABI to use for parser generation. The default is ABI 15, with ABI 14 being a
 
 Only generate `grammar.json` and `node-types.json`
 
-### `-0/--debug-build`
-
-Compile the parser with debug flags enabled. This is useful when debugging issues that require a debugger like `gdb` or `lldb`.
-
-### `--libdir <PATH>`
-
-The directory to place the compiled parser(s) in.
-On Unix systems, the default path is `$XDG_CACHE_HOME/tree-sitter` if `$XDG_CACHE_HOME` is set,
-otherwise `$HOME/.config/tree-sitter` is used. On Windows, the default path is `%LOCALAPPDATA%\tree-sitter` if available,
-otherwise `$HOME\AppData\Local\tree-sitter` is used.
-
 ### `-o/--output`
 
 The directory to place the generated parser in. The default is `src/` in the current directory.

From 13ff3935ac902ce050d29559072f31e4b4876536 Mon Sep 17 00:00:00 2001
From: "dependabot[bot]" <49699333+dependabot[bot]@users.noreply.github.com>
Date: Mon, 10 Nov 2025 21:22:31 +0000
Subject: [PATCH 02/14] build(deps): bump the cargo group with 3 updates

Bumps the cargo group with 3 updates: [cc](https://github.com/rust-lang/cc-rs), [libloading](https://github.com/nagisa/rust_libloading) and [schemars](https://github.com/GREsau/schemars).


Updates `cc` from 1.2.44 to 1.2.45
- [Release notes](https://github.com/rust-lang/cc-rs/releases)
- [Changelog](https://github.com/rust-lang/cc-rs/blob/main/CHANGELOG.md)
- [Commits](https://github.com/rust-lang/cc-rs/compare/cc-v1.2.44...cc-v1.2.45)

Updates `libloading` from 0.8.9 to 0.9.0
- [Commits](https://github.com/nagisa/rust_libloading/compare/0.8.9...0.9.0)

Updates `schemars` from 1.0.4 to 1.0.5
- [Release notes](https://github.com/GREsau/schemars/releases)
- [Changelog](https://github.com/GREsau/schemars/blob/master/CHANGELOG.md)
- [Commits](https://github.com/GREsau/schemars/compare/v1.0.4...v1.0.5)

---
updated-dependencies:
- dependency-name: cc
  dependency-version: 1.2.45
  dependency-type: direct:production
  update-type: version-update:semver-patch
  dependency-group: cargo
- dependency-name: libloading
  dependency-version: 0.9.0
  dependency-type: direct:production
  update-type: version-update:semver-minor
  dependency-group: cargo
- dependency-name: schemars
  dependency-version: 1.0.5
  dependency-type: direct:production
  update-type: version-update:semver-patch
  dependency-group: cargo
...

Signed-off-by: dependabot[bot] <support@github.com>
---
 Cargo.lock | 26 ++++++++++++++++++--------
 Cargo.toml |  6 +++---
 2 files changed, 21 insertions(+), 11 deletions(-)

diff --git a/Cargo.lock b/Cargo.lock
index 8cf0a189..4021396a 100644
--- a/Cargo.lock
+++ b/Cargo.lock
@@ -187,9 +187,9 @@ checksum = "d71b6127be86fdcfddb610f7182ac57211d4b18a3e9c82eb2d17662f2227ad6a"
 
 [[package]]
 name = "cc"
-version = "1.2.44"
+version = "1.2.45"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "37521ac7aabe3d13122dc382493e20c9416f299d2ccd5b3a5340a2570cdeb0f3"
+checksum = "35900b6c8d709fb1d854671ae27aeaa9eec2f8b01b364e1619a40da3e6fe2afe"
 dependencies = [
  "find-msvc-tools",
  "shlex",
@@ -236,7 +236,7 @@ checksum = "0b023947811758c97c59bf9d1c188fd619ad4718dcaa767947df1cadb14f39f4"
 dependencies = [
  "glob",
  "libc",
- "libloading",
+ "libloading 0.8.9",
 ]
 
 [[package]]
@@ -1058,6 +1058,16 @@ dependencies = [
  "windows-link",
 ]
 
+[[package]]
+name = "libloading"
+version = "0.9.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "754ca22de805bb5744484a5b151a9e1a8e837d5dc232c2d7d8c2e3492edc8b60"
+dependencies = [
+ "cfg-if",
+ "windows-link",
+]
+
 [[package]]
 name = "libm"
 version = "0.2.15"
@@ -1621,9 +1631,9 @@ dependencies = [
 
 [[package]]
 name = "schemars"
-version = "1.0.4"
+version = "1.1.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "82d20c4491bc164fa2f6c5d44565947a52ad80b9505d8e36f8d54c27c739fcd0"
+checksum = "9558e172d4e8533736ba97870c4b2cd63f84b382a3d6eb063da41b91cce17289"
 dependencies = [
  "dyn-clone",
  "ref-cast",
@@ -1634,9 +1644,9 @@ dependencies = [
 
 [[package]]
 name = "schemars_derive"
-version = "1.0.4"
+version = "1.1.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "33d020396d1d138dc19f1165df7545479dcd58d93810dc5d646a16e55abefa80"
+checksum = "301858a4023d78debd2353c7426dc486001bddc91ae31a76fb1f55132f7e2633"
 dependencies = [
  "proc-macro2",
  "quote",
@@ -2079,7 +2089,7 @@ dependencies = [
  "etcetera",
  "fs4",
  "indoc",
- "libloading",
+ "libloading 0.9.0",
  "log",
  "once_cell",
  "regex",
diff --git a/Cargo.toml b/Cargo.toml
index 521ad684..5afc53b5 100644
--- a/Cargo.toml
+++ b/Cargo.toml
@@ -106,7 +106,7 @@ ansi_colours = "1.2.3"
 anstyle = "1.0.13"
 anyhow = "1.0.100"
 bstr = "1.12.0"
-cc = "1.2.44"
+cc = "1.2.45"
 clap = { version = "4.5.51", features = [
   "cargo",
   "derive",
@@ -128,7 +128,7 @@ heck = "0.5.0"
 html-escape = "0.2.13"
 indexmap = "2.11.4"
 indoc = "2.0.6"
-libloading = "0.8.9"
+libloading = "0.9.0"
 log = { version = "0.4.28", features = ["std"] }
 memchr = "2.7.6"
 once_cell = "1.21.3"
@@ -137,7 +137,7 @@ rand = "0.8.5"
 regex = "1.11.3"
 regex-syntax = "0.8.6"
 rustc-hash = "2.1.1"
-schemars = "1.0.4"
+schemars = "1.0.5"
 semver = { version = "1.0.27", features = ["serde"] }
 serde = { version = "1.0.219", features = ["derive"] }
 serde_json = { version = "1.0.145", features = ["preserve_order"] }

From 7657cc9d356e922790e0cb9648f3d3dc8880761c Mon Sep 17 00:00:00 2001
From: Will Lillis <will.lillis24@gmail.com>
Date: Wed, 12 Nov 2025 00:02:44 -0500
Subject: [PATCH 03/14] fix(dsl): add `ReservedRule` to `Rule` type definition

---
 crates/cli/npm/dsl.d.ts | 1 +
 1 file changed, 1 insertion(+)

diff --git a/crates/cli/npm/dsl.d.ts b/crates/cli/npm/dsl.d.ts
index 3ad9ea2a..accdb95f 100644
--- a/crates/cli/npm/dsl.d.ts
+++ b/crates/cli/npm/dsl.d.ts
@@ -29,6 +29,7 @@ type Rule =
   | PrecRule
   | Repeat1Rule
   | RepeatRule
+  | ReservedRule
   | SeqRule
   | StringRule
   | SymbolRule<string>

From 12a31536e1f8d1afdd2add375139cb31ac0e1c1a Mon Sep 17 00:00:00 2001
From: Marcono1234 <Marcono1234@users.noreply.github.com>
Date: Wed, 12 Nov 2025 15:55:28 +0100
Subject: [PATCH 04/14] fix(docs): don't show mdbook help popup when using
 query editor

---
 docs/src/assets/js/playground.js | 5 +++--
 1 file changed, 3 insertions(+), 2 deletions(-)

diff --git a/docs/src/assets/js/playground.js b/docs/src/assets/js/playground.js
index 595fe565..2b4b5708 100644
--- a/docs/src/assets/js/playground.js
+++ b/docs/src/assets/js/playground.js
@@ -146,8 +146,9 @@ window.initializePlayground = async (opts) => {
   });
 
   queryEditor.on('keydown', (_, event) => {
-    if (event.key === 'ArrowLeft' || event.key === 'ArrowRight') {
-      event.stopPropagation(); // Prevent mdBook from going back/forward
+    const key = event.key;
+    if (key === 'ArrowLeft' || key === 'ArrowRight' || key === '?') {
+      event.stopPropagation(); // Prevent mdBook from going back/forward, or showing help
     }
   });
 

From 67cb3cb88146dd9ce3a098e33ac0374b5ce1e22d Mon Sep 17 00:00:00 2001
From: WillLillis <wlillis@umass.edu>
Date: Fri, 3 Oct 2025 22:32:50 -0400
Subject: [PATCH 05/14] refactor(loader)!: transition from anyhow to thiserror

---
 Cargo.lock                  |   2 +-
 crates/loader/Cargo.toml    |   2 +-
 crates/loader/src/loader.rs | 714 +++++++++++++++++++++++-------------
 3 files changed, 471 insertions(+), 247 deletions(-)

diff --git a/Cargo.lock b/Cargo.lock
index 4021396a..90c00db3 100644
--- a/Cargo.lock
+++ b/Cargo.lock
@@ -2084,7 +2084,6 @@ version = "0.1.5"
 name = "tree-sitter-loader"
 version = "0.26.0"
 dependencies = [
- "anyhow",
  "cc",
  "etcetera",
  "fs4",
@@ -2097,6 +2096,7 @@ dependencies = [
  "serde",
  "serde_json",
  "tempfile",
+ "thiserror 2.0.16",
  "tree-sitter",
  "tree-sitter-highlight",
  "tree-sitter-tags",
diff --git a/crates/loader/Cargo.toml b/crates/loader/Cargo.toml
index ba6aa0f4..cecae218 100644
--- a/crates/loader/Cargo.toml
+++ b/crates/loader/Cargo.toml
@@ -28,7 +28,6 @@ wasm = ["tree-sitter/wasm"]
 default = ["tree-sitter-highlight", "tree-sitter-tags"]
 
 [dependencies]
-anyhow.workspace = true
 cc.workspace = true
 etcetera.workspace = true
 fs4.workspace = true
@@ -41,6 +40,7 @@ semver.workspace = true
 serde.workspace = true
 serde_json.workspace = true
 tempfile.workspace = true
+thiserror.workspace = true
 
 tree-sitter = { workspace = true }
 tree-sitter-highlight = { workspace = true, optional = true }
diff --git a/crates/loader/src/loader.rs b/crates/loader/src/loader.rs
index 39099797..08d6af84 100644
--- a/crates/loader/src/loader.rs
+++ b/crates/loader/src/loader.rs
@@ -14,11 +14,9 @@ use std::{
     path::{Path, PathBuf},
     process::Command,
     sync::LazyLock,
-    time::SystemTime,
+    time::{SystemTime, SystemTimeError},
 };
 
-use anyhow::Error;
-use anyhow::{anyhow, Context, Result};
 use etcetera::BaseStrategy as _;
 use fs4::fs_std::FileExt;
 use libloading::{Library, Symbol};
@@ -27,11 +25,14 @@ use once_cell::unsync::OnceCell;
 use regex::{Regex, RegexBuilder};
 use semver::Version;
 use serde::{Deserialize, Deserializer, Serialize};
+use thiserror::Error;
 use tree_sitter::Language;
 #[cfg(any(feature = "tree-sitter-highlight", feature = "tree-sitter-tags"))]
 use tree_sitter::QueryError;
 #[cfg(feature = "tree-sitter-highlight")]
 use tree_sitter::QueryErrorKind;
+#[cfg(feature = "wasm")]
+use tree_sitter::WasmError;
 #[cfg(feature = "tree-sitter-highlight")]
 use tree_sitter_highlight::HighlightConfiguration;
 #[cfg(feature = "tree-sitter-tags")]
@@ -40,6 +41,210 @@ use tree_sitter_tags::{Error as TagsError, TagsConfiguration};
 static GRAMMAR_NAME_REGEX: LazyLock<Regex> =
     LazyLock::new(|| Regex::new(r#""name":\s*"(.*?)""#).unwrap());
 
+pub type LoaderResult<T> = Result<T, LoaderError>;
+
+#[derive(Debug, Error)]
+pub enum LoaderError {
+    #[error(transparent)]
+    Compiler(CompilerError),
+    #[error("Parser compilation failed.\nStdout: {0}\nStderr: {1}")]
+    Compilation(String, String),
+    #[error("Failed to execute curl for {0} -- {1}")]
+    Curl(String, std::io::Error),
+    #[error("Failed to load language in current directory:\n{0}")]
+    CurrentDirectoryLoad(Box<Self>),
+    #[error("External file path {0} is outside of parser directory {1}")]
+    ExternalFile(String, String),
+    #[error("Failed to extract archive {0} to {1}")]
+    Extraction(String, String),
+    #[error("Failed to load language for file name {0}:\n{1}")]
+    FileNameLoad(String, Box<Self>),
+    #[error("Failed to parse the language name from grammar.json at {0}")]
+    GrammarJSON(String),
+    #[error(transparent)]
+    HomeDir(#[from] etcetera::HomeDirError),
+    #[error(transparent)]
+    IO(IoError),
+    #[error(transparent)]
+    Library(LibraryError),
+    #[error("Failed to compare binary and source timestamps:\n{0}")]
+    ModifiedTime(Box<Self>),
+    #[error("No language found")]
+    NoLanguage,
+    #[error(transparent)]
+    Query(LoaderQueryError),
+    #[error(transparent)]
+    ScannerSymbols(ScannerSymbolError),
+    #[error("Failed to load language for scope '{0}':\n{1}")]
+    ScopeLoad(String, Box<Self>),
+    #[error(transparent)]
+    Serialization(#[from] serde_json::Error),
+    #[error(transparent)]
+    Symbol(SymbolError),
+    #[error(transparent)]
+    Tags(#[from] TagsError),
+    #[error("Failed to execute tar for {0} -- {1}")]
+    Tar(String, std::io::Error),
+    #[error(transparent)]
+    Time(#[from] SystemTimeError),
+    #[error("Unknown scope '{0}'")]
+    UnknownScope(String),
+    #[error("Failed to download wasi-sdk from {0}")]
+    WasiSDKDownload(String),
+    #[error(transparent)]
+    WasiSDKClang(#[from] WasiSDKClangError),
+    #[error("Unsupported platform for wasi-sdk")]
+    WasiSDKPlatform,
+    #[cfg(feature = "wasm")]
+    #[error(transparent)]
+    Wasm(#[from] WasmError),
+    #[error("Failed to run wasi-sdk clang -- {0}")]
+    WasmCompiler(std::io::Error),
+    #[error("wasi-sdk clang command failed: {0}")]
+    WasmCompilation(String),
+}
+
+#[derive(Debug, Error)]
+pub struct CompilerError {
+    pub error: std::io::Error,
+    pub command: Box<Command>,
+}
+
+impl std::fmt::Display for CompilerError {
+    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
+        write!(
+            f,
+            "Failed to execute the C compiler with the following command:\n{:?}\nError: {}",
+            *self.command, self.error
+        )?;
+        Ok(())
+    }
+}
+
+#[derive(Debug, Error)]
+pub struct IoError {
+    pub error: std::io::Error,
+    pub path: Option<String>,
+}
+
+impl IoError {
+    fn new(error: std::io::Error, path: Option<&Path>) -> Self {
+        Self {
+            error,
+            path: path.map(|p| p.to_string_lossy().to_string()),
+        }
+    }
+}
+
+impl std::fmt::Display for IoError {
+    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
+        write!(f, "{}", self.error)?;
+        if let Some(ref path) = self.path {
+            write!(f, " ({path})")?;
+        }
+        Ok(())
+    }
+}
+
+#[derive(Debug, Error)]
+pub struct LibraryError {
+    pub error: libloading::Error,
+    pub path: String,
+}
+
+impl std::fmt::Display for LibraryError {
+    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
+        write!(
+            f,
+            "Error opening dynamic library {} -- {}",
+            self.path, self.error
+        )?;
+        Ok(())
+    }
+}
+
+#[derive(Debug, Error)]
+pub struct LoaderQueryError {
+    pub error: QueryError,
+    pub file: Option<String>,
+}
+
+impl std::fmt::Display for LoaderQueryError {
+    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
+        if let Some(ref path) = self.file {
+            writeln!(f, "Error in query file {path}:")?;
+        }
+        write!(f, "{}", self.error)?;
+        Ok(())
+    }
+}
+
+#[derive(Debug, Error)]
+pub struct SymbolError {
+    pub error: libloading::Error,
+    pub symbol_name: String,
+    pub path: String,
+}
+
+impl std::fmt::Display for SymbolError {
+    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
+        write!(
+            f,
+            "Failed to load symbol {} from {} -- {}",
+            self.symbol_name, self.path, self.error
+        )?;
+        Ok(())
+    }
+}
+
+#[derive(Debug, Error)]
+pub struct ScannerSymbolError {
+    pub missing: Vec<String>,
+}
+
+impl std::fmt::Display for ScannerSymbolError {
+    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
+        writeln!(
+            f,
+            "Missing required functions in the external scanner, parsing won't work without these!\n"
+        )?;
+        for symbol in &self.missing {
+            writeln!(f, "  `{symbol}`")?;
+        }
+        writeln!(
+            f,
+            "You can read more about this at https://tree-sitter.github.io/tree-sitter/creating-parsers/4-external-scanners\n"
+        )?;
+        Ok(())
+    }
+}
+
+#[derive(Debug, Error)]
+pub struct WasiSDKClangError {
+    pub wasi_sdk_dir: String,
+    pub possible_executables: Vec<&'static str>,
+    download: bool,
+}
+
+impl std::fmt::Display for WasiSDKClangError {
+    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
+        if self.download {
+            write!(
+                f,
+                "Failed to find clang executable in downloaded wasi-sdk at '{}'.",
+                self.wasi_sdk_dir
+            )?;
+        } else {
+            write!(f, "TREE_SITTER_WASI_SDK_PATH is set to '{}', but no clang executable found in 'bin/' directory.", self.wasi_sdk_dir)?;
+        }
+
+        let possible_exes = self.possible_executables.join(", ");
+        write!(f, " Looked for: {possible_exes}.")?;
+
+        Ok(())
+    }
+}
+
 #[derive(Default, Deserialize, Serialize)]
 pub struct Config {
     #[serde(default)]
@@ -143,9 +348,10 @@ pub struct TreeSitterJSON {
 }
 
 impl TreeSitterJSON {
-    pub fn from_file(path: &Path) -> Result<Self> {
-        Ok(serde_json::from_str(&fs::read_to_string(
-            path.join("tree-sitter.json"),
+    pub fn from_file(path: &Path) -> LoaderResult<Self> {
+        let path = path.join("tree-sitter.json");
+        Ok(serde_json::from_str(&fs::read_to_string(&path).map_err(
+            |e| LoaderError::IO(IoError::new(e, Some(path.as_path()))),
         )?)?)
     }
 
@@ -432,7 +638,7 @@ impl<'a> CompileConfig<'a> {
 unsafe impl Sync for Loader {}
 
 impl Loader {
-    pub fn new() -> Result<Self> {
+    pub fn new() -> LoaderResult<Self> {
         let parser_lib_path = if let Ok(path) = env::var("TREE_SITTER_LIBDIR") {
             PathBuf::from(path)
         } else {
@@ -441,7 +647,9 @@ impl Loader {
                     .cache_dir() // `$HOME/Library/Caches/`
                     .join("tree-sitter");
                 if legacy_apple_path.exists() && legacy_apple_path.is_dir() {
-                    std::fs::remove_dir_all(legacy_apple_path)?;
+                    std::fs::remove_dir_all(&legacy_apple_path).map_err(|e| {
+                        LoaderError::IO(IoError::new(e, Some(legacy_apple_path.as_path())))
+                    })?;
                 }
             }
 
@@ -491,7 +699,7 @@ impl Loader {
         self.highlight_names.lock().unwrap().clone()
     }
 
-    pub fn find_all_languages(&mut self, config: &Config) -> Result<()> {
+    pub fn find_all_languages(&mut self, config: &Config) -> LoaderResult<()> {
         if config.parser_directories.is_empty() {
             warn!(concat!(
                 "You have not configured any parser directories!\n",
@@ -503,7 +711,7 @@ impl Loader {
         for parser_container_dir in &config.parser_directories {
             if let Ok(entries) = fs::read_dir(parser_container_dir) {
                 for entry in entries {
-                    let entry = entry?;
+                    let entry = entry.map_err(|e| LoaderError::IO(IoError::new(e, None)))?;
                     if let Some(parser_dir_name) = entry.file_name().to_str() {
                         if parser_dir_name.starts_with("tree-sitter-") {
                             self.find_language_configurations_at_path(
@@ -519,7 +727,7 @@ impl Loader {
         Ok(())
     }
 
-    pub fn languages_at_path(&mut self, path: &Path) -> Result<Vec<(Language, String)>> {
+    pub fn languages_at_path(&mut self, path: &Path) -> LoaderResult<Vec<(Language, String)>> {
         if let Ok(configurations) = self.find_language_configurations_at_path(path, true) {
             let mut language_ids = configurations
                 .iter()
@@ -530,7 +738,7 @@ impl Loader {
             language_ids
                 .into_iter()
                 .map(|(id, name)| Ok((self.language_for_id(id)?, name)))
-                .collect::<Result<Vec<_>>>()
+                .collect::<LoaderResult<Vec<_>>>()
         } else {
             Ok(Vec::new())
         }
@@ -547,7 +755,7 @@ impl Loader {
     pub fn language_configuration_for_scope(
         &self,
         scope: &str,
-    ) -> Result<Option<(Language, &LanguageConfiguration)>> {
+    ) -> LoaderResult<Option<(Language, &LanguageConfiguration)>> {
         for configuration in &self.language_configurations {
             if configuration.scope.as_ref().is_some_and(|s| s == scope) {
                 let language = self.language_for_id(configuration.language_id)?;
@@ -560,14 +768,19 @@ impl Loader {
     pub fn language_configuration_for_first_line_regex(
         &self,
         path: &Path,
-    ) -> Result<Option<(Language, &LanguageConfiguration)>> {
+    ) -> LoaderResult<Option<(Language, &LanguageConfiguration)>> {
         self.language_configuration_ids_by_first_line_regex
             .iter()
             .try_fold(None, |_, (regex, ids)| {
                 if let Some(regex) = Self::regex(Some(regex)) {
-                    let file = fs::File::open(path)?;
+                    let file = fs::File::open(path)
+                        .map_err(|e| LoaderError::IO(IoError::new(e, Some(path))))?;
                     let reader = BufReader::new(file);
-                    let first_line = reader.lines().next().transpose()?;
+                    let first_line = reader
+                        .lines()
+                        .next()
+                        .transpose()
+                        .map_err(|e| LoaderError::IO(IoError::new(e, Some(path))))?;
                     if let Some(first_line) = first_line {
                         if regex.is_match(&first_line) && !ids.is_empty() {
                             let configuration = &self.language_configurations[ids[0]];
@@ -584,7 +797,7 @@ impl Loader {
     pub fn language_configuration_for_file_name(
         &self,
         path: &Path,
-    ) -> Result<Option<(Language, &LanguageConfiguration)>> {
+    ) -> LoaderResult<Option<(Language, &LanguageConfiguration)>> {
         // Find all the language configurations that match this file name
         // or a suffix of the file name.
         let configuration_ids = path
@@ -611,8 +824,8 @@ impl Loader {
                 // If multiple language configurations match, then determine which
                 // one to use by applying the configurations' content regexes.
                 else {
-                    let file_contents = fs::read(path)
-                        .with_context(|| format!("Failed to read path {}", path.display()))?;
+                    let file_contents =
+                        fs::read(path).map_err(|e| LoaderError::IO(IoError::new(e, Some(path))))?;
                     let file_contents = String::from_utf8_lossy(&file_contents);
                     let mut best_score = -2isize;
                     let mut best_configuration_id = None;
@@ -656,7 +869,7 @@ impl Loader {
     pub fn language_configuration_for_injection_string(
         &self,
         string: &str,
-    ) -> Result<Option<(Language, &LanguageConfiguration)>> {
+    ) -> LoaderResult<Option<(Language, &LanguageConfiguration)>> {
         let mut best_match_length = 0;
         let mut best_match_position = None;
         for (i, configuration) in self.language_configurations.iter().enumerate() {
@@ -683,11 +896,11 @@ impl Loader {
     pub fn language_for_configuration(
         &self,
         configuration: &LanguageConfiguration,
-    ) -> Result<Language> {
+    ) -> LoaderResult<Language> {
         self.language_for_id(configuration.language_id)
     }
 
-    fn language_for_id(&self, id: usize) -> Result<Language> {
+    fn language_for_id(&self, id: usize) -> LoaderResult<Language> {
         let (path, language, externals) = &self.languages_by_id[id];
         language
             .get_or_try_init(|| {
@@ -706,20 +919,23 @@ impl Loader {
         grammar_path: &Path,
         output_path: PathBuf,
         flags: &[&str],
-    ) -> Result<()> {
+    ) -> LoaderResult<()> {
         let src_path = grammar_path.join("src");
         let mut config = CompileConfig::new(&src_path, None, Some(output_path));
         config.flags = flags;
         self.load_language_at_path(config).map(|_| ())
     }
 
-    pub fn load_language_at_path(&self, mut config: CompileConfig) -> Result<Language> {
+    pub fn load_language_at_path(&self, mut config: CompileConfig) -> LoaderResult<Language> {
         let grammar_path = config.src_path.join("grammar.json");
         config.name = Self::grammar_json_name(&grammar_path)?;
         self.load_language_at_path_with_name(config)
     }
 
-    pub fn load_language_at_path_with_name(&self, mut config: CompileConfig) -> Result<Language> {
+    pub fn load_language_at_path_with_name(
+        &self,
+        mut config: CompileConfig,
+    ) -> LoaderResult<Language> {
         let mut lib_name = config.name.clone();
         let language_fn_name = format!("tree_sitter_{}", config.name.replace('-', "_"));
         if self.debug_build {
@@ -732,7 +948,9 @@ impl Loader {
         }
 
         if config.output_path.is_none() {
-            fs::create_dir_all(&self.parser_lib_path)?;
+            fs::create_dir_all(&self.parser_lib_path).map_err(|e| {
+                LoaderError::IO(IoError::new(e, Some(self.parser_lib_path.as_path())))
+            })?;
         }
 
         let mut recompile = self.force_rebuild || config.output_path.is_some(); // if specified, always recompile
@@ -766,8 +984,7 @@ impl Loader {
         );
 
         if !recompile {
-            recompile = needs_recompile(&output_path, &paths_to_check)
-                .with_context(|| "Failed to compare source and binary timestamps")?;
+            recompile = needs_recompile(&output_path, &paths_to_check)?;
         }
 
         #[cfg(feature = "wasm")]
@@ -784,7 +1001,8 @@ impl Loader {
                 )?;
             }
 
-            let wasm_bytes = fs::read(&output_path)?;
+            let wasm_bytes = fs::read(&output_path)
+                .map_err(|e| LoaderError::IO(IoError::new(e, Some(output_path.as_path()))))?;
             return Ok(wasm_store.load_language(&config.name, &wasm_bytes)?);
         }
 
@@ -808,33 +1026,42 @@ impl Loader {
             if lock_file.try_lock_exclusive().is_err() {
                 // if we can't acquire the lock, another process is compiling the parser, wait for
                 // it and don't recompile
-                lock_file.lock_exclusive()?;
+                lock_file
+                    .lock_exclusive()
+                    .map_err(|e| LoaderError::IO(IoError::new(e, Some(lock_path.as_path()))))?;
                 recompile = false;
             } else {
                 // if we can acquire the lock, check if the lock file is older than 30 seconds, a
                 // run that was interrupted and left the lock file behind should not block
                 // subsequent runs
-                let time = lock_file.metadata()?.modified()?.elapsed()?.as_secs();
+                let time = lock_file
+                    .metadata()
+                    .map_err(|e| LoaderError::IO(IoError::new(e, Some(lock_path.as_path()))))?
+                    .modified()
+                    .map_err(|e| LoaderError::IO(IoError::new(e, Some(lock_path.as_path()))))?
+                    .elapsed()?
+                    .as_secs();
                 if time > 30 {
-                    fs::remove_file(&lock_path)?;
+                    fs::remove_file(&lock_path)
+                        .map_err(|e| LoaderError::IO(IoError::new(e, Some(lock_path.as_path()))))?;
                     recompile = true;
                 }
             }
         }
 
         if recompile {
-            fs::create_dir_all(lock_path.parent().unwrap()).with_context(|| {
-                format!(
-                    "Failed to create directory {}",
-                    lock_path.parent().unwrap().display()
-                )
-            })?;
+            let parent_path = lock_path.parent().unwrap();
+            fs::create_dir_all(parent_path)
+                .map_err(|e| LoaderError::IO(IoError::new(e, Some(parent_path))))?;
             let lock_file = fs::OpenOptions::new()
                 .create(true)
                 .truncate(true)
                 .write(true)
-                .open(&lock_path)?;
-            lock_file.lock_exclusive()?;
+                .open(&lock_path)
+                .map_err(|e| LoaderError::IO(IoError::new(e, Some(lock_path.as_path()))))?;
+            lock_file
+                .lock_exclusive()
+                .map_err(|e| LoaderError::IO(IoError::new(e, Some(lock_path.as_path()))))?;
 
             self.compile_parser_to_dylib(&config, &lock_file, &lock_path)?;
 
@@ -846,17 +1073,22 @@ impl Loader {
         Self::load_language(&output_path, &language_fn_name)
     }
 
-    pub fn load_language(path: &Path, function_name: &str) -> Result<Language> {
-        let library = unsafe { Library::new(path) }
-            .with_context(|| format!("Error opening dynamic library {}", path.display()))?;
+    pub fn load_language(path: &Path, function_name: &str) -> LoaderResult<Language> {
+        let library = unsafe { Library::new(path) }.map_err(|e| {
+            LoaderError::Library(LibraryError {
+                error: e,
+                path: path.to_string_lossy().to_string(),
+            })
+        })?;
         let language = unsafe {
             let language_fn = library
                 .get::<Symbol<unsafe extern "C" fn() -> Language>>(function_name.as_bytes())
-                .with_context(|| {
-                    format!(
-                        "Failed to load symbol {function_name} from {}",
-                        path.display()
-                    )
+                .map_err(|e| {
+                    LoaderError::Symbol(SymbolError {
+                        error: e,
+                        symbol_name: function_name.to_string(),
+                        path: path.to_string_lossy().to_string(),
+                    })
                 })?;
             language_fn()
         };
@@ -869,7 +1101,7 @@ impl Loader {
         config: &CompileConfig,
         lock_file: &fs::File,
         lock_path: &Path,
-    ) -> Result<(), Error> {
+    ) -> LoaderResult<()> {
         let mut cc_config = cc::Build::new();
         cc_config
             .cargo_metadata(false)
@@ -940,30 +1172,34 @@ impl Loader {
             None
         };
 
-        let output = command.output().with_context(|| {
-            format!("Failed to execute the C compiler with the following command:\n{command:?}")
+        let output = command.output().map_err(|e| {
+            LoaderError::Compiler(CompilerError {
+                error: e,
+                command: Box::new(command),
+            })
         })?;
 
         if let Some(temp_dir) = temp_dir {
             let _ = fs::remove_dir_all(temp_dir);
         }
 
-        FileExt::unlock(lock_file)?;
-        fs::remove_file(lock_path)?;
+        FileExt::unlock(lock_file)
+            .map_err(|e| LoaderError::IO(IoError::new(e, Some(lock_path))))?;
+        fs::remove_file(lock_path)
+            .map_err(|e| LoaderError::IO(IoError::new(e, Some(lock_path))))?;
 
         if output.status.success() {
             Ok(())
         } else {
-            Err(anyhow!(
-                "Parser compilation failed.\nStdout: {}\nStderr: {}",
-                String::from_utf8_lossy(&output.stdout),
-                String::from_utf8_lossy(&output.stderr)
+            Err(LoaderError::Compilation(
+                String::from_utf8_lossy(&output.stdout).to_string(),
+                String::from_utf8_lossy(&output.stderr).to_string(),
             ))
         }
     }
 
     #[cfg(unix)]
-    fn check_external_scanner(&self, name: &str, library_path: &Path) -> Result<()> {
+    fn check_external_scanner(&self, name: &str, library_path: &Path) -> LoaderResult<()> {
         let prefix = if cfg!(any(target_os = "macos", target_os = "ios")) {
             "_"
         } else {
@@ -1015,22 +1251,9 @@ impl Loader {
                 }
 
                 if !must_have.is_empty() {
-                    let missing = must_have
-                        .iter()
-                        .map(|f| format!("  `{f}`"))
-                        .collect::<Vec<_>>()
-                        .join("\n");
-
-                    return Err(anyhow!(format!(
-                        indoc::indoc! {"
-                            Missing required functions in the external scanner, parsing won't work without these!
-
-                            {}
-
-                            You can read more about this at https://tree-sitter.github.io/tree-sitter/creating-parsers/4-external-scanners
-                        "},
-                        missing,
-                    )));
+                    return Err(LoaderError::ScannerSymbols(ScannerSymbolError {
+                        missing: must_have,
+                    }));
                 }
             }
         }
@@ -1039,7 +1262,7 @@ impl Loader {
     }
 
     #[cfg(windows)]
-    fn check_external_scanner(&self, _name: &str, _library_path: &Path) -> Result<()> {
+    fn check_external_scanner(&self, _name: &str, _library_path: &Path) -> LoaderResult<()> {
         // TODO: there's no nm command on windows, whoever wants to implement this can and should :)
 
         // let mut must_have = vec![
@@ -1059,7 +1282,7 @@ impl Loader {
         src_path: &Path,
         scanner_filename: Option<&Path>,
         output_path: &Path,
-    ) -> Result<(), Error> {
+    ) -> LoaderResult<()> {
         let clang_executable = self.ensure_wasi_sdk_exists()?;
 
         let output_name = "output.wasm";
@@ -1085,17 +1308,17 @@ impl Loader {
             command.arg(scanner_filename);
         }
 
-        let output = command.output().context("Failed to run wasi-sdk clang")?;
+        let output = command.output().map_err(LoaderError::WasmCompiler)?;
 
         if !output.status.success() {
-            return Err(anyhow!(
-                "wasi-sdk clang command failed: {}",
-                String::from_utf8_lossy(&output.stderr)
+            return Err(LoaderError::WasmCompilation(
+                String::from_utf8_lossy(&output.stderr).to_string(),
             ));
         }
 
-        fs::rename(src_path.join(output_name), output_path)
-            .context("failed to rename Wasm output file")?;
+        let current_path = src_path.join(output_name);
+        fs::rename(&current_path, output_path)
+            .map_err(|e| LoaderError::IO(IoError::new(e, Some(current_path.as_path()))))?;
 
         Ok(())
     }
@@ -1105,7 +1328,7 @@ impl Loader {
         &self,
         archive_path: &Path,
         destination: &Path,
-    ) -> Result<(), Error> {
+    ) -> LoaderResult<()> {
         let status = Command::new("tar")
             .arg("-xzf")
             .arg(archive_path)
@@ -1113,13 +1336,12 @@ impl Loader {
             .arg("-C")
             .arg(destination)
             .status()
-            .with_context(|| format!("Failed to execute tar for {}", archive_path.display()))?;
+            .map_err(|e| LoaderError::Tar(archive_path.to_string_lossy().to_string(), e))?;
 
         if !status.success() {
-            return Err(anyhow!(
-                "Failed to extract archive {} to {}",
-                archive_path.display(),
-                destination.display()
+            return Err(LoaderError::Extraction(
+                archive_path.to_string_lossy().to_string(),
+                destination.to_string_lossy().to_string(),
             ));
         }
 
@@ -1130,7 +1352,7 @@ impl Loader {
     /// and returns the path to the `clang` executable.
     ///
     /// If `TREE_SITTER_WASI_SDK_PATH` is set, it will use that path to look for the clang executable.
-    fn ensure_wasi_sdk_exists(&self) -> Result<PathBuf, Error> {
+    fn ensure_wasi_sdk_exists(&self) -> LoaderResult<PathBuf> {
         let possible_executables = if cfg!(windows) {
             vec![
                 "clang.exe",
@@ -1151,18 +1373,18 @@ impl Loader {
                 }
             }
 
-            return Err(anyhow!(
-                "TREE_SITTER_WASI_SDK_PATH is set to '{}', but no clang executable found in 'bin/' directory. \
-                 Looked for: {}",
-                wasi_sdk_dir.display(),
-                possible_executables.join(", ")
-            ));
+            return Err(LoaderError::WasiSDKClang(WasiSDKClangError {
+                wasi_sdk_dir: wasi_sdk_dir.to_string_lossy().to_string(),
+                possible_executables,
+                download: false,
+            }));
         }
 
         let cache_dir = etcetera::choose_base_strategy()?
             .cache_dir()
             .join("tree-sitter");
-        fs::create_dir_all(&cache_dir)?;
+        fs::create_dir_all(&cache_dir)
+            .map_err(|e| LoaderError::IO(IoError::new(e, Some(cache_dir.as_path()))))?;
 
         let wasi_sdk_dir = cache_dir.join("wasi-sdk");
 
@@ -1173,7 +1395,8 @@ impl Loader {
             }
         }
 
-        fs::create_dir_all(&wasi_sdk_dir)?;
+        fs::create_dir_all(&wasi_sdk_dir)
+            .map_err(|e| LoaderError::IO(IoError::new(e, Some(wasi_sdk_dir.as_path()))))?;
 
         let arch_os = if cfg!(target_os = "macos") {
             if cfg!(target_arch = "aarch64") {
@@ -1194,7 +1417,7 @@ impl Loader {
                 "x86_64-linux"
             }
         } else {
-            return Err(anyhow!("Unsupported platform for wasi-sdk"));
+            return Err(LoaderError::WasiSDKPlatform);
         };
 
         let sdk_filename = format!("wasi-sdk-25.0-{arch_os}.tar.gz");
@@ -1212,15 +1435,14 @@ impl Loader {
             .arg(&temp_tar_path)
             .arg(&sdk_url)
             .status()
-            .with_context(|| format!("Failed to execute curl for {sdk_url}"))?;
+            .map_err(|e| LoaderError::Curl(sdk_url.clone(), e))?;
 
         if !status.success() {
-            return Err(anyhow!("Failed to download wasi-sdk from {sdk_url}",));
+            return Err(LoaderError::WasiSDKDownload(sdk_url));
         }
 
         info!("Extracting wasi-sdk to {}...", wasi_sdk_dir.display());
-        self.extract_tar_gz_with_strip(&temp_tar_path, &wasi_sdk_dir)
-            .context("Failed to extract wasi-sdk archive")?;
+        self.extract_tar_gz_with_strip(&temp_tar_path, &wasi_sdk_dir)?;
 
         fs::remove_file(temp_tar_path).ok();
         for exe in &possible_executables {
@@ -1230,11 +1452,11 @@ impl Loader {
             }
         }
 
-        Err(anyhow!(
-            "Failed to find clang executable in downloaded wasi-sdk at '{}'. Looked for: {}",
-            wasi_sdk_dir.display(),
-            possible_executables.join(", ")
-        ))
+        Err(LoaderError::WasiSDKClang(WasiSDKClangError {
+            wasi_sdk_dir: wasi_sdk_dir.to_string_lossy().to_string(),
+            possible_executables,
+            download: true,
+        }))
     }
 
     #[must_use]
@@ -1274,115 +1496,121 @@ impl Loader {
         &mut self,
         parser_path: &Path,
         set_current_path_config: bool,
-    ) -> Result<&[LanguageConfiguration]> {
+    ) -> LoaderResult<&[LanguageConfiguration]> {
         let initial_language_configuration_count = self.language_configurations.len();
 
-        let ts_json = TreeSitterJSON::from_file(parser_path);
-        if let Ok(config) = ts_json {
-            let language_count = self.languages_by_id.len();
-            for grammar in config.grammars {
-                // Determine the path to the parser directory. This can be specified in
-                // the tree-sitter.json, but defaults to the directory containing the
-                // tree-sitter.json.
-                let language_path = parser_path.join(grammar.path.unwrap_or(PathBuf::from(".")));
+        match TreeSitterJSON::from_file(parser_path) {
+            Ok(config) => {
+                let language_count = self.languages_by_id.len();
+                for grammar in config.grammars {
+                    // Determine the path to the parser directory. This can be specified in
+                    // the tree-sitter.json, but defaults to the directory containing the
+                    // tree-sitter.json.
+                    let language_path =
+                        parser_path.join(grammar.path.unwrap_or(PathBuf::from(".")));
 
-                // Determine if a previous language configuration in this package.json file
-                // already uses the same language.
-                let mut language_id = None;
-                for (id, (path, _, _)) in
-                    self.languages_by_id.iter().enumerate().skip(language_count)
-                {
-                    if language_path == *path {
-                        language_id = Some(id);
+                    // Determine if a previous language configuration in this package.json file
+                    // already uses the same language.
+                    let mut language_id = None;
+                    for (id, (path, _, _)) in
+                        self.languages_by_id.iter().enumerate().skip(language_count)
+                    {
+                        if language_path == *path {
+                            language_id = Some(id);
+                        }
                     }
-                }
 
-                // If not, add a new language path to the list.
-                let language_id = if let Some(language_id) = language_id {
-                    language_id
-                } else {
-                    self.languages_by_id.push((
+                    // If not, add a new language path to the list.
+                    let language_id = if let Some(language_id) = language_id {
+                        language_id
+                    } else {
+                        self.languages_by_id.push((
                             language_path,
                             OnceCell::new(),
-                            grammar.external_files.clone().into_vec().map(|files| {
-                                files.into_iter()
-                                    .map(|path| {
-                                       let path = parser_path.join(path);
-                                        // prevent p being above/outside of parser_path
-                                        if path.starts_with(parser_path) {
-                                            Ok(path)
-                                        } else {
-                                            Err(anyhow!(
-                                                "External file path {} is outside of parser directory {}", path.display(), parser_path.display(),
-                                            ))
-                                        }
-                                    })
-                                    .collect::<Result<Vec<_>>>()
-                            }).transpose()?,
+                            grammar
+                                .external_files
+                                .clone()
+                                .into_vec()
+                                .map(|files| {
+                                    files
+                                        .into_iter()
+                                        .map(|path| {
+                                            let path = parser_path.join(path);
+                                            // prevent p being above/outside of parser_path
+                                            if path.starts_with(parser_path) {
+                                                Ok(path)
+                                            } else {
+                                                Err(LoaderError::ExternalFile(
+                                                    path.to_string_lossy().to_string(),
+                                                    parser_path.to_string_lossy().to_string(),
+                                                ))
+                                            }
+                                        })
+                                        .collect::<LoaderResult<Vec<_>>>()
+                                })
+                                .transpose()?,
                         ));
-                    self.languages_by_id.len() - 1
-                };
+                        self.languages_by_id.len() - 1
+                    };
 
-                let configuration = LanguageConfiguration {
-                    root_path: parser_path.to_path_buf(),
-                    language_name: grammar.name,
-                    scope: Some(grammar.scope),
-                    language_id,
-                    file_types: grammar.file_types.unwrap_or_default(),
-                    content_regex: Self::regex(grammar.content_regex.as_deref()),
-                    first_line_regex: Self::regex(grammar.first_line_regex.as_deref()),
-                    injection_regex: Self::regex(grammar.injection_regex.as_deref()),
-                    injections_filenames: grammar.injections.into_vec(),
-                    locals_filenames: grammar.locals.into_vec(),
-                    tags_filenames: grammar.tags.into_vec(),
-                    highlights_filenames: grammar.highlights.into_vec(),
-                    #[cfg(feature = "tree-sitter-highlight")]
-                    highlight_config: OnceCell::new(),
-                    #[cfg(feature = "tree-sitter-tags")]
-                    tags_config: OnceCell::new(),
-                    #[cfg(feature = "tree-sitter-highlight")]
-                    highlight_names: &self.highlight_names,
-                    #[cfg(feature = "tree-sitter-highlight")]
-                    use_all_highlight_names: self.use_all_highlight_names,
-                    _phantom: PhantomData,
-                };
+                    let configuration = LanguageConfiguration {
+                        root_path: parser_path.to_path_buf(),
+                        language_name: grammar.name,
+                        scope: Some(grammar.scope),
+                        language_id,
+                        file_types: grammar.file_types.unwrap_or_default(),
+                        content_regex: Self::regex(grammar.content_regex.as_deref()),
+                        first_line_regex: Self::regex(grammar.first_line_regex.as_deref()),
+                        injection_regex: Self::regex(grammar.injection_regex.as_deref()),
+                        injections_filenames: grammar.injections.into_vec(),
+                        locals_filenames: grammar.locals.into_vec(),
+                        tags_filenames: grammar.tags.into_vec(),
+                        highlights_filenames: grammar.highlights.into_vec(),
+                        #[cfg(feature = "tree-sitter-highlight")]
+                        highlight_config: OnceCell::new(),
+                        #[cfg(feature = "tree-sitter-tags")]
+                        tags_config: OnceCell::new(),
+                        #[cfg(feature = "tree-sitter-highlight")]
+                        highlight_names: &self.highlight_names,
+                        #[cfg(feature = "tree-sitter-highlight")]
+                        use_all_highlight_names: self.use_all_highlight_names,
+                        _phantom: PhantomData,
+                    };
 
-                for file_type in &configuration.file_types {
-                    self.language_configuration_ids_by_file_type
-                        .entry(file_type.clone())
-                        .or_default()
-                        .push(self.language_configurations.len());
-                }
-                if let Some(first_line_regex) = &configuration.first_line_regex {
-                    self.language_configuration_ids_by_first_line_regex
-                        .entry(first_line_regex.to_string())
-                        .or_default()
-                        .push(self.language_configurations.len());
-                }
+                    for file_type in &configuration.file_types {
+                        self.language_configuration_ids_by_file_type
+                            .entry(file_type.clone())
+                            .or_default()
+                            .push(self.language_configurations.len());
+                    }
+                    if let Some(first_line_regex) = &configuration.first_line_regex {
+                        self.language_configuration_ids_by_first_line_regex
+                            .entry(first_line_regex.to_string())
+                            .or_default()
+                            .push(self.language_configurations.len());
+                    }
 
-                self.language_configurations.push(unsafe {
-                    mem::transmute::<LanguageConfiguration<'_>, LanguageConfiguration<'static>>(
-                        configuration,
-                    )
-                });
+                    self.language_configurations.push(unsafe {
+                        mem::transmute::<LanguageConfiguration<'_>, LanguageConfiguration<'static>>(
+                            configuration,
+                        )
+                    });
 
-                if set_current_path_config && self.language_configuration_in_current_path.is_none()
-                {
-                    self.language_configuration_in_current_path =
-                        Some(self.language_configurations.len() - 1);
+                    if set_current_path_config
+                        && self.language_configuration_in_current_path.is_none()
+                    {
+                        self.language_configuration_in_current_path =
+                            Some(self.language_configurations.len() - 1);
+                    }
                 }
             }
-        } else if let Err(e) = ts_json {
-            match e.downcast_ref::<std::io::Error>() {
-                // This is noisy, and not really an issue.
-                Some(e) if e.kind() == std::io::ErrorKind::NotFound => {}
-                _ => {
-                    warn!(
-                        "Failed to parse {} -- {e}",
-                        parser_path.join("tree-sitter.json").display()
-                    );
-                }
+            Err(LoaderError::Serialization(e)) => {
+                warn!(
+                    "Failed to parse {} -- {e}",
+                    parser_path.join("tree-sitter.json").display()
+                );
             }
+            _ => {}
         }
 
         // If we didn't find any language configurations in the tree-sitter.json file,
@@ -1432,32 +1660,21 @@ impl Loader {
         pattern.and_then(|r| RegexBuilder::new(r).multi_line(true).build().ok())
     }
 
-    fn grammar_json_name(grammar_path: &Path) -> Result<String> {
-        let file = fs::File::open(grammar_path).with_context(|| {
-            format!("Failed to open grammar.json at {}", grammar_path.display())
-        })?;
+    fn grammar_json_name(grammar_path: &Path) -> LoaderResult<String> {
+        let file = fs::File::open(grammar_path)
+            .map_err(|e| LoaderError::IO(IoError::new(e, Some(grammar_path))))?;
 
         let first_three_lines = BufReader::new(file)
             .lines()
             .take(3)
-            .collect::<Result<Vec<_>, _>>()
-            .with_context(|| {
-                format!(
-                    "Failed to read the first three lines of grammar.json at {}",
-                    grammar_path.display()
-                )
-            })?
+            .collect::<Result<Vec<_>, std::io::Error>>()
+            .map_err(|_| LoaderError::GrammarJSON(grammar_path.to_string_lossy().to_string()))?
             .join("\n");
 
         let name = GRAMMAR_NAME_REGEX
             .captures(&first_three_lines)
             .and_then(|c| c.get(1))
-            .ok_or_else(|| {
-                anyhow!(
-                    "Failed to parse the language name from grammar.json at {}",
-                    grammar_path.display()
-                )
-            })?;
+            .ok_or_else(|| LoaderError::GrammarJSON(grammar_path.to_string_lossy().to_string()))?;
 
         Ok(name.as_str().to_string())
     }
@@ -1469,34 +1686,34 @@ impl Loader {
         scope: Option<&str>,
         // path to dynamic library, name of language
         lib_info: Option<&(PathBuf, &str)>,
-    ) -> Result<Language> {
+    ) -> LoaderResult<Language> {
         if let Some((ref lib_path, language_name)) = lib_info {
             let language_fn_name = format!("tree_sitter_{}", language_name.replace('-', "_"));
             Self::load_language(lib_path, &language_fn_name)
         } else if let Some(scope) = scope {
             if let Some(config) = self
                 .language_configuration_for_scope(scope)
-                .with_context(|| format!("Failed to load language for scope '{scope}'"))?
+                .map_err(|e| LoaderError::ScopeLoad(scope.to_string(), Box::new(e)))?
             {
                 Ok(config.0)
             } else {
-                Err(anyhow!("Unknown scope '{scope}'"))
+                Err(LoaderError::UnknownScope(scope.to_string()))
             }
-        } else if let Some((lang, _)) = self
-            .language_configuration_for_file_name(path)
-            .with_context(|| {
-                format!(
-                    "Failed to load language for file name {}",
-                    path.file_name().unwrap().to_string_lossy()
-                )
-            })?
+        } else if let Some((lang, _)) =
+            self.language_configuration_for_file_name(path)
+                .map_err(|e| {
+                    LoaderError::FileNameLoad(
+                        path.file_name().unwrap().to_string_lossy().to_string(),
+                        Box::new(e),
+                    )
+                })?
         {
             Ok(lang)
         } else if let Some(id) = self.language_configuration_in_current_path {
             Ok(self.language_for_id(self.language_configurations[id].language_id)?)
         } else if let Some(lang) = self
             .languages_at_path(current_dir)
-            .with_context(|| "Failed to load language in current directory")?
+            .map_err(|e| LoaderError::CurrentDirectoryLoad(Box::new(e)))?
             .first()
             .cloned()
         {
@@ -1504,7 +1721,7 @@ impl Loader {
         } else if let Some(lang) = self.language_configuration_for_first_line_regex(path)? {
             Ok(lang.0)
         } else {
-            Err(anyhow!("No language found"))
+            Err(LoaderError::NoLanguage)
         }
     }
 
@@ -1539,7 +1756,7 @@ impl LanguageConfiguration<'_> {
         &self,
         language: Language,
         paths: Option<&[PathBuf]>,
-    ) -> Result<Option<&HighlightConfiguration>> {
+    ) -> LoaderResult<Option<&HighlightConfiguration>> {
         let (highlights_filenames, injections_filenames, locals_filenames) = match paths {
             Some(paths) => (
                 Some(
@@ -1604,7 +1821,9 @@ impl LanguageConfiguration<'_> {
                         &locals_query,
                     )
                     .map_err(|error| match error.kind {
-                        QueryErrorKind::Language => Error::from(error),
+                        QueryErrorKind::Language => {
+                            LoaderError::Query(LoaderQueryError { error, file: None })
+                        }
                         _ => {
                             if error.offset < injections_query.len() {
                                 Self::include_path_in_query_error(
@@ -1647,7 +1866,7 @@ impl LanguageConfiguration<'_> {
     }
 
     #[cfg(feature = "tree-sitter-tags")]
-    pub fn tags_config(&self, language: Language) -> Result<Option<&TagsConfiguration>> {
+    pub fn tags_config(&self, language: Language) -> LoaderResult<Option<&TagsConfiguration>> {
         self.tags_config
             .get_or_try_init(|| {
                 let (tags_query, tags_ranges) =
@@ -1691,7 +1910,7 @@ impl LanguageConfiguration<'_> {
         ranges: &[(PathBuf, Range<usize>)],
         source: &str,
         start_offset: usize,
-    ) -> Error {
+    ) -> LoaderError {
         let offset_within_section = error.offset - start_offset;
         let (path, range) = ranges
             .iter()
@@ -1701,7 +1920,10 @@ impl LanguageConfiguration<'_> {
         error.row = source[range.start..offset_within_section]
             .matches('\n')
             .count();
-        Error::from(error).context(format!("Error in query file {}", path.display()))
+        LoaderError::Query(LoaderQueryError {
+            error,
+            file: Some(path.to_string_lossy().to_string()),
+        })
     }
 
     #[allow(clippy::type_complexity)]
@@ -1710,7 +1932,7 @@ impl LanguageConfiguration<'_> {
         &self,
         paths: Option<&[PathBuf]>,
         default_path: &str,
-    ) -> Result<(String, Vec<(PathBuf, Range<usize>)>)> {
+    ) -> LoaderResult<(String, Vec<(PathBuf, Range<usize>)>)> {
         let mut query = String::new();
         let mut path_ranges = Vec::new();
         if let Some(paths) = paths {
@@ -1718,7 +1940,7 @@ impl LanguageConfiguration<'_> {
                 let abs_path = self.root_path.join(path);
                 let prev_query_len = query.len();
                 query += &fs::read_to_string(&abs_path)
-                    .with_context(|| format!("Failed to read query file {}", path.display()))?;
+                    .map_err(|e| LoaderError::IO(IoError::new(e, Some(abs_path.as_path()))))?;
                 path_ranges.push((path.clone(), prev_query_len..query.len()));
             }
         } else {
@@ -1738,7 +1960,7 @@ impl LanguageConfiguration<'_> {
             let path = queries_path.join(default_path);
             if path.exists() {
                 query = fs::read_to_string(&path)
-                    .with_context(|| format!("Failed to read query file {}", path.display()))?;
+                    .map_err(|e| LoaderError::IO(IoError::new(e, Some(path.as_path()))))?;
                 path_ranges.push((PathBuf::from(default_path), 0..query.len()));
             }
         }
@@ -1747,20 +1969,22 @@ impl LanguageConfiguration<'_> {
     }
 }
 
-fn needs_recompile(lib_path: &Path, paths_to_check: &[PathBuf]) -> Result<bool> {
+fn needs_recompile(lib_path: &Path, paths_to_check: &[PathBuf]) -> LoaderResult<bool> {
     if !lib_path.exists() {
         return Ok(true);
     }
-    let lib_mtime = mtime(lib_path)
-        .with_context(|| format!("Failed to read mtime of {}", lib_path.display()))?;
+    let lib_mtime = mtime(lib_path).map_err(|e| LoaderError::ModifiedTime(Box::new(e)))?;
     for path in paths_to_check {
-        if mtime(path)? > lib_mtime {
+        if mtime(path).map_err(|e| LoaderError::ModifiedTime(Box::new(e)))? > lib_mtime {
             return Ok(true);
         }
     }
     Ok(false)
 }
 
-fn mtime(path: &Path) -> Result<SystemTime> {
-    Ok(fs::metadata(path)?.modified()?)
+fn mtime(path: &Path) -> LoaderResult<SystemTime> {
+    fs::metadata(path)
+        .map_err(|e| LoaderError::IO(IoError::new(e, Some(path))))?
+        .modified()
+        .map_err(|e| LoaderError::IO(IoError::new(e, Some(path))))
 }

From db2d221ae9d5521e1e6527f3426d8d15b091fd9d Mon Sep 17 00:00:00 2001
From: WillLillis <wlillis@umass.edu>
Date: Sat, 4 Oct 2025 00:48:35 -0400
Subject: [PATCH 06/14] fix(generate): remove leftover imports of anyhow

---
 Cargo.lock                                             | 1 -
 crates/generate/Cargo.toml                             | 1 -
 crates/generate/src/generate.rs                        | 1 -
 crates/generate/src/node_types.rs                      | 1 -
 crates/generate/src/parse_grammar.rs                   | 1 -
 crates/generate/src/prepare_grammar.rs                 | 1 -
 crates/generate/src/prepare_grammar/expand_tokens.rs   | 1 -
 crates/generate/src/prepare_grammar/extract_tokens.rs  | 1 -
 crates/generate/src/prepare_grammar/flatten_grammar.rs | 1 -
 crates/generate/src/prepare_grammar/intern_symbols.rs  | 1 -
 crates/generate/src/prepare_grammar/process_inlines.rs | 1 -
 11 files changed, 11 deletions(-)

diff --git a/Cargo.lock b/Cargo.lock
index 90c00db3..1297ecd3 100644
--- a/Cargo.lock
+++ b/Cargo.lock
@@ -2046,7 +2046,6 @@ dependencies = [
 name = "tree-sitter-generate"
 version = "0.26.0"
 dependencies = [
- "anyhow",
  "bitflags 2.10.0",
  "dunce",
  "indexmap",
diff --git a/crates/generate/Cargo.toml b/crates/generate/Cargo.toml
index 09fc1850..5e93bf40 100644
--- a/crates/generate/Cargo.toml
+++ b/crates/generate/Cargo.toml
@@ -25,7 +25,6 @@ load = ["dep:semver"]
 qjs-rt = ["load", "rquickjs", "pathdiff"]
 
 [dependencies]
-anyhow.workspace = true
 bitflags = "2.9.4"
 dunce = "1.0.5"
 indexmap.workspace = true
diff --git a/crates/generate/src/generate.rs b/crates/generate/src/generate.rs
index c4a1ec84..612a5fa8 100644
--- a/crates/generate/src/generate.rs
+++ b/crates/generate/src/generate.rs
@@ -7,7 +7,6 @@ use std::{
     process::{Command, Stdio},
 };
 
-use anyhow::Result;
 use bitflags::bitflags;
 use log::warn;
 use node_types::VariableInfo;
diff --git a/crates/generate/src/node_types.rs b/crates/generate/src/node_types.rs
index 0a964105..2dde0c49 100644
--- a/crates/generate/src/node_types.rs
+++ b/crates/generate/src/node_types.rs
@@ -1,6 +1,5 @@
 use std::collections::{BTreeMap, BTreeSet, HashMap, HashSet};
 
-use anyhow::Result;
 use serde::Serialize;
 use thiserror::Error;
 
diff --git a/crates/generate/src/parse_grammar.rs b/crates/generate/src/parse_grammar.rs
index c48477f0..de8f0a97 100644
--- a/crates/generate/src/parse_grammar.rs
+++ b/crates/generate/src/parse_grammar.rs
@@ -1,6 +1,5 @@
 use std::collections::HashSet;
 
-use anyhow::Result;
 use log::warn;
 use regex::Regex;
 use serde::{Deserialize, Serialize};
diff --git a/crates/generate/src/prepare_grammar.rs b/crates/generate/src/prepare_grammar.rs
index 8c35c741..58e0869c 100644
--- a/crates/generate/src/prepare_grammar.rs
+++ b/crates/generate/src/prepare_grammar.rs
@@ -12,7 +12,6 @@ use std::{
     mem,
 };
 
-use anyhow::Result;
 pub use expand_tokens::ExpandTokensError;
 pub use extract_tokens::ExtractTokensError;
 pub use flatten_grammar::FlattenGrammarError;
diff --git a/crates/generate/src/prepare_grammar/expand_tokens.rs b/crates/generate/src/prepare_grammar/expand_tokens.rs
index 4d8b4f11..acfb9ba3 100644
--- a/crates/generate/src/prepare_grammar/expand_tokens.rs
+++ b/crates/generate/src/prepare_grammar/expand_tokens.rs
@@ -1,4 +1,3 @@
-use anyhow::Result;
 use regex_syntax::{
     hir::{Class, Hir, HirKind},
     ParserBuilder,
diff --git a/crates/generate/src/prepare_grammar/extract_tokens.rs b/crates/generate/src/prepare_grammar/extract_tokens.rs
index a1fddbe6..a7b4f227 100644
--- a/crates/generate/src/prepare_grammar/extract_tokens.rs
+++ b/crates/generate/src/prepare_grammar/extract_tokens.rs
@@ -1,6 +1,5 @@
 use std::collections::HashMap;
 
-use anyhow::Result;
 use serde::Serialize;
 use thiserror::Error;
 
diff --git a/crates/generate/src/prepare_grammar/flatten_grammar.rs b/crates/generate/src/prepare_grammar/flatten_grammar.rs
index cb0f1dae..3bec17bf 100644
--- a/crates/generate/src/prepare_grammar/flatten_grammar.rs
+++ b/crates/generate/src/prepare_grammar/flatten_grammar.rs
@@ -1,6 +1,5 @@
 use std::collections::HashMap;
 
-use anyhow::Result;
 use serde::Serialize;
 use thiserror::Error;
 
diff --git a/crates/generate/src/prepare_grammar/intern_symbols.rs b/crates/generate/src/prepare_grammar/intern_symbols.rs
index 241e6e99..92f0f095 100644
--- a/crates/generate/src/prepare_grammar/intern_symbols.rs
+++ b/crates/generate/src/prepare_grammar/intern_symbols.rs
@@ -1,4 +1,3 @@
-use anyhow::Result;
 use log::warn;
 use serde::Serialize;
 use thiserror::Error;
diff --git a/crates/generate/src/prepare_grammar/process_inlines.rs b/crates/generate/src/prepare_grammar/process_inlines.rs
index f20e182d..d4b7dc18 100644
--- a/crates/generate/src/prepare_grammar/process_inlines.rs
+++ b/crates/generate/src/prepare_grammar/process_inlines.rs
@@ -1,6 +1,5 @@
 use std::collections::HashMap;
 
-use anyhow::Result;
 use serde::Serialize;
 use thiserror::Error;
 

From 7eb23d9f3cae0876dec541f06da633b066f583e7 Mon Sep 17 00:00:00 2001
From: WillLillis <wlillis@umass.edu>
Date: Sat, 4 Oct 2025 01:22:02 -0400
Subject: [PATCH 07/14] refactor(config)!: transition from anyhow to thiserror

---
 Cargo.lock                              |  2 +-
 crates/config/Cargo.toml                |  2 +-
 crates/config/src/tree_sitter_config.rs | 79 ++++++++++++++++++++-----
 3 files changed, 66 insertions(+), 17 deletions(-)

diff --git a/Cargo.lock b/Cargo.lock
index 1297ecd3..726289b9 100644
--- a/Cargo.lock
+++ b/Cargo.lock
@@ -2035,11 +2035,11 @@ dependencies = [
 name = "tree-sitter-config"
 version = "0.26.0"
 dependencies = [
- "anyhow",
  "etcetera",
  "log",
  "serde",
  "serde_json",
+ "thiserror 2.0.16",
 ]
 
 [[package]]
diff --git a/crates/config/Cargo.toml b/crates/config/Cargo.toml
index b9bc239e..641b434b 100644
--- a/crates/config/Cargo.toml
+++ b/crates/config/Cargo.toml
@@ -20,8 +20,8 @@ path = "src/tree_sitter_config.rs"
 workspace = true
 
 [dependencies]
-anyhow.workspace = true
 etcetera.workspace = true
 log.workspace = true
 serde.workspace = true
 serde_json.workspace = true
+thiserror.workspace = true
diff --git a/crates/config/src/tree_sitter_config.rs b/crates/config/src/tree_sitter_config.rs
index 85dc003d..17b1d384 100644
--- a/crates/config/src/tree_sitter_config.rs
+++ b/crates/config/src/tree_sitter_config.rs
@@ -1,12 +1,54 @@
 #![cfg_attr(not(any(test, doctest)), doc = include_str!("../README.md"))]
 
-use std::{env, fs, path::PathBuf};
+use std::{
+    env, fs,
+    path::{Path, PathBuf},
+};
 
-use anyhow::{Context, Result};
 use etcetera::BaseStrategy as _;
 use log::warn;
 use serde::{Deserialize, Serialize};
 use serde_json::Value;
+use thiserror::Error;
+
+pub type ConfigResult<T> = Result<T, ConfigError>;
+
+#[derive(Debug, Error)]
+pub enum ConfigError {
+    #[error("Bad JSON config {0} -- {1}")]
+    ConfigRead(String, serde_json::Error),
+    #[error(transparent)]
+    HomeDir(#[from] etcetera::HomeDirError),
+    #[error(transparent)]
+    IO(IoError),
+    #[error(transparent)]
+    Serialization(#[from] serde_json::Error),
+}
+
+#[derive(Debug, Error)]
+pub struct IoError {
+    pub error: std::io::Error,
+    pub path: Option<String>,
+}
+
+impl IoError {
+    fn new(error: std::io::Error, path: Option<&Path>) -> Self {
+        Self {
+            error,
+            path: path.map(|p| p.to_string_lossy().to_string()),
+        }
+    }
+}
+
+impl std::fmt::Display for IoError {
+    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
+        write!(f, "{}", self.error)?;
+        if let Some(ref path) = self.path {
+            write!(f, " ({path})")?;
+        }
+        Ok(())
+    }
+}
 
 /// Holds the contents of tree-sitter's configuration file.
 ///
@@ -23,7 +65,7 @@ pub struct Config {
 }
 
 impl Config {
-    pub fn find_config_file() -> Result<Option<PathBuf>> {
+    pub fn find_config_file() -> ConfigResult<Option<PathBuf>> {
         if let Ok(path) = env::var("TREE_SITTER_DIR") {
             let mut path = PathBuf::from(path);
             path.push("config.json");
@@ -46,8 +88,12 @@ impl Config {
                 .join("tree-sitter")
                 .join("config.json");
             if legacy_apple_path.is_file() {
-                fs::create_dir_all(xdg_path.parent().unwrap())?;
-                fs::rename(&legacy_apple_path, &xdg_path)?;
+                let xdg_dir = xdg_path.parent().unwrap();
+                fs::create_dir_all(xdg_dir)
+                    .map_err(|e| ConfigError::IO(IoError::new(e, Some(xdg_dir))))?;
+                fs::rename(&legacy_apple_path, &xdg_path).map_err(|e| {
+                    ConfigError::IO(IoError::new(e, Some(legacy_apple_path.as_path())))
+                })?;
                 warn!(
                     "Your config.json file has been automatically migrated from \"{}\" to \"{}\"",
                     legacy_apple_path.display(),
@@ -67,7 +113,7 @@ impl Config {
         Ok(None)
     }
 
-    fn xdg_config_file() -> Result<PathBuf> {
+    fn xdg_config_file() -> ConfigResult<PathBuf> {
         let xdg_path = etcetera::choose_base_strategy()?
             .config_dir()
             .join("tree-sitter")
@@ -84,7 +130,7 @@ impl Config {
     ///     [`etcetera::choose_base_strategy`](https://docs.rs/etcetera/*/etcetera/#basestrategy)
     ///   - `$HOME/.tree-sitter/config.json` as a fallback from where tree-sitter _used_ to store
     ///     its configuration
-    pub fn load(path: Option<PathBuf>) -> Result<Self> {
+    pub fn load(path: Option<PathBuf>) -> ConfigResult<Self> {
         let location = if let Some(path) = path {
             path
         } else if let Some(path) = Self::find_config_file()? {
@@ -94,9 +140,9 @@ impl Config {
         };
 
         let content = fs::read_to_string(&location)
-            .with_context(|| format!("Failed to read {}", location.to_string_lossy()))?;
+            .map_err(|e| ConfigError::IO(IoError::new(e, Some(location.as_path()))))?;
         let config = serde_json::from_str(&content)
-            .with_context(|| format!("Bad JSON config {}", location.to_string_lossy()))?;
+            .map_err(|e| ConfigError::ConfigRead(location.to_string_lossy().to_string(), e))?;
         Ok(Self { location, config })
     }
 
@@ -106,7 +152,7 @@ impl Config {
     /// disk.
     ///
     /// (Note that this is typically only done by the `tree-sitter init-config` command.)
-    pub fn initial() -> Result<Self> {
+    pub fn initial() -> ConfigResult<Self> {
         let location = if let Ok(path) = env::var("TREE_SITTER_DIR") {
             let mut path = PathBuf::from(path);
             path.push("config.json");
@@ -119,17 +165,20 @@ impl Config {
     }
 
     /// Saves this configuration to the file that it was originally loaded from.
-    pub fn save(&self) -> Result<()> {
+    pub fn save(&self) -> ConfigResult<()> {
         let json = serde_json::to_string_pretty(&self.config)?;
-        fs::create_dir_all(self.location.parent().unwrap())?;
-        fs::write(&self.location, json)?;
+        let config_dir = self.location.parent().unwrap();
+        fs::create_dir_all(config_dir)
+            .map_err(|e| ConfigError::IO(IoError::new(e, Some(config_dir))))?;
+        fs::write(&self.location, json)
+            .map_err(|e| ConfigError::IO(IoError::new(e, Some(self.location.as_path()))))?;
         Ok(())
     }
 
     /// Parses a component-specific configuration from the configuration file.  The type `C` must
     /// be [deserializable](https://docs.rs/serde/*/serde/trait.Deserialize.html) from a JSON
     /// object, and must only include the fields relevant to that component.
-    pub fn get<C>(&self) -> Result<C>
+    pub fn get<C>(&self) -> ConfigResult<C>
     where
         C: for<'de> Deserialize<'de>,
     {
@@ -140,7 +189,7 @@ impl Config {
     /// Adds a component-specific configuration to the configuration file.  The type `C` must be
     /// [serializable](https://docs.rs/serde/*/serde/trait.Serialize.html) into a JSON object, and
     /// must only include the fields relevant to that component.
-    pub fn add<C>(&mut self, config: C) -> Result<()>
+    pub fn add<C>(&mut self, config: C) -> ConfigResult<()>
     where
         C: Serialize,
     {

From 61c21aa408710019fc81c14a9b213dd762d5c5bd Mon Sep 17 00:00:00 2001
From: WillLillis <wlillis@umass.edu>
Date: Sat, 4 Oct 2025 03:21:20 -0400
Subject: [PATCH 08/14] refactor(generate)!: include path when available in IO
 errors

---
 crates/generate/src/generate.rs | 138 +++++++++++++++++++-------------
 crates/generate/src/quickjs.rs  |   6 +-
 2 files changed, 87 insertions(+), 57 deletions(-)

diff --git a/crates/generate/src/generate.rs b/crates/generate/src/generate.rs
index 612a5fa8..6a005637 100644
--- a/crates/generate/src/generate.rs
+++ b/crates/generate/src/generate.rs
@@ -80,8 +80,8 @@ pub type GenerateResult<T> = Result<T, GenerateError>;
 pub enum GenerateError {
     #[error("Error with specified path -- {0}")]
     GrammarPath(String),
-    #[error("{0}")]
-    IO(String),
+    #[error(transparent)]
+    IO(IoError),
     #[cfg(feature = "load")]
     #[error(transparent)]
     LoadGrammarFile(#[from] LoadGrammarError),
@@ -100,9 +100,28 @@ pub enum GenerateError {
     SuperTypeCycle(#[from] SuperTypeCycleError),
 }
 
-impl From<std::io::Error> for GenerateError {
-    fn from(value: std::io::Error) -> Self {
-        Self::IO(value.to_string())
+#[derive(Debug, Error, Serialize)]
+pub struct IoError {
+    pub error: String,
+    pub path: Option<String>,
+}
+
+impl IoError {
+    fn new(error: &std::io::Error, path: Option<&Path>) -> Self {
+        Self {
+            error: error.to_string(),
+            path: path.map(|p| p.to_string_lossy().to_string()),
+        }
+    }
+}
+
+impl std::fmt::Display for IoError {
+    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
+        write!(f, "{}", self.error)?;
+        if let Some(ref path) = self.path {
+            write!(f, " ({path})")?;
+        }
+        Ok(())
     }
 }
 
@@ -117,18 +136,11 @@ pub enum LoadGrammarError {
     #[error("Failed to load grammar.js -- {0}")]
     LoadJSGrammarFile(#[from] JSError),
     #[error("Failed to load grammar.json -- {0}")]
-    IO(String),
+    IO(IoError),
     #[error("Unknown grammar file extension: {0:?}")]
     FileExtension(PathBuf),
 }
 
-#[cfg(feature = "load")]
-impl From<std::io::Error> for LoadGrammarError {
-    fn from(value: std::io::Error) -> Self {
-        Self::IO(value.to_string())
-    }
-}
-
 #[cfg(feature = "load")]
 #[derive(Debug, Error, Serialize)]
 pub enum ParseVersionError {
@@ -136,8 +148,8 @@ pub enum ParseVersionError {
     Version(String),
     #[error("{0}")]
     JSON(String),
-    #[error("{0}")]
-    IO(String),
+    #[error(transparent)]
+    IO(IoError),
 }
 
 #[cfg(feature = "load")]
@@ -152,8 +164,21 @@ pub enum JSError {
     JSRuntimeUtf8 { runtime: String, error: String },
     #[error("`{runtime}` process exited with status {code}")]
     JSRuntimeExit { runtime: String, code: i32 },
-    #[error("{0}")]
-    IO(String),
+    #[error("Failed to open stdin for `{runtime}`")]
+    JSRuntimeStdin { runtime: String },
+    #[error("Failed to write {item} to `{runtime}`'s stdin -- {error}")]
+    JSRuntimeWrite {
+        runtime: String,
+        item: String,
+        error: String,
+    },
+    #[error("Failed to read output from `{runtime}` -- {error}")]
+    JSRuntimeRead { runtime: String, error: String },
+    #[error(transparent)]
+    IO(IoError),
+    #[cfg(feature = "qjs-rt")]
+    #[error("Failed to get relative path")]
+    RelativePath,
     #[error("Could not parse this package's version as semver -- {0}")]
     Semver(String),
     #[error("Failed to serialze grammar JSON -- {0}")]
@@ -163,13 +188,6 @@ pub enum JSError {
     QuickJS(String),
 }
 
-#[cfg(feature = "load")]
-impl From<std::io::Error> for JSError {
-    fn from(value: std::io::Error) -> Self {
-        Self::IO(value.to_string())
-    }
-}
-
 #[cfg(feature = "load")]
 impl From<serde_json::Error> for JSError {
     fn from(value: serde_json::Error) -> Self {
@@ -230,7 +248,8 @@ where
             .try_exists()
             .map_err(|e| GenerateError::GrammarPath(e.to_string()))?
         {
-            fs::create_dir_all(&path_buf)?;
+            fs::create_dir_all(&path_buf)
+                .map_err(|e| GenerateError::IO(IoError::new(&e, Some(path_buf.as_path()))))?;
             repo_path = path_buf;
             repo_path.join("grammar.js")
         } else {
@@ -247,15 +266,12 @@ where
     let header_path = src_path.join("tree_sitter");
 
     // Ensure that the output directory exists
-    fs::create_dir_all(&src_path)?;
+    fs::create_dir_all(&src_path)
+        .map_err(|e| GenerateError::IO(IoError::new(&e, Some(src_path.as_path()))))?;
 
     if grammar_path.file_name().unwrap() != "grammar.json" {
-        fs::write(src_path.join("grammar.json"), &grammar_json).map_err(|e| {
-            GenerateError::IO(format!(
-                "Failed to write grammar.json to {} -- {e}",
-                src_path.display()
-            ))
-        })?;
+        fs::write(src_path.join("grammar.json"), &grammar_json)
+            .map_err(|e| GenerateError::IO(IoError::new(&e, Some(src_path.as_path()))))?;
     }
 
     // If our job is only to generate `grammar.json` and not `parser.c`, stop here.
@@ -297,7 +313,8 @@ where
 
     write_file(&src_path.join("parser.c"), c_code)?;
     write_file(&src_path.join("node-types.json"), node_types_json)?;
-    fs::create_dir_all(&header_path)?;
+    fs::create_dir_all(&header_path)
+        .map_err(|e| GenerateError::IO(IoError::new(&e, Some(header_path.as_path()))))?;
     write_file(&header_path.join("alloc.h"), ALLOC_HEADER)?;
     write_file(&header_path.join("array.h"), ARRAY_HEADER)?;
     write_file(&header_path.join("parser.h"), PARSER_HEADER)?;
@@ -413,9 +430,8 @@ fn read_grammar_version(repo_path: &Path) -> Result<Option<Version>, ParseVersio
         let json = path
             .exists()
             .then(|| {
-                let contents = fs::read_to_string(path.as_path()).map_err(|e| {
-                    ParseVersionError::IO(format!("Failed to read `{}` -- {e}", path.display()))
-                })?;
+                let contents = fs::read_to_string(path.as_path())
+                    .map_err(|e| ParseVersionError::IO(IoError::new(&e, Some(path.as_path()))))?;
                 serde_json::from_str::<TreeSitterJson>(&contents).map_err(|e| {
                     ParseVersionError::JSON(format!("Failed to parse `{}` -- {e}", path.display()))
                 })
@@ -449,14 +465,16 @@ pub fn load_grammar_file(
     }
     match grammar_path.extension().and_then(|e| e.to_str()) {
         Some("js") => Ok(load_js_grammar_file(grammar_path, js_runtime)?),
-        Some("json") => Ok(fs::read_to_string(grammar_path)?),
+        Some("json") => Ok(fs::read_to_string(grammar_path)
+            .map_err(|e| LoadGrammarError::IO(IoError::new(&e, Some(grammar_path))))?),
         _ => Err(LoadGrammarError::FileExtension(grammar_path.to_owned()))?,
     }
 }
 
 #[cfg(feature = "load")]
 fn load_js_grammar_file(grammar_path: &Path, js_runtime: Option<&str>) -> JSResult<String> {
-    let grammar_path = dunce::canonicalize(grammar_path)?;
+    let grammar_path = dunce::canonicalize(grammar_path)
+        .map_err(|e| JSError::IO(IoError::new(&e, Some(grammar_path))))?;
 
     #[cfg(feature = "qjs-rt")]
     if js_runtime == Some("native") {
@@ -497,7 +515,9 @@ fn load_js_grammar_file(grammar_path: &Path, js_runtime: Option<&str>) -> JSResu
     let mut js_stdin = js_process
         .stdin
         .take()
-        .ok_or_else(|| JSError::IO(format!("Failed to open stdin for `{js_runtime}`")))?;
+        .ok_or_else(|| JSError::JSRuntimeStdin {
+            runtime: js_runtime.to_string(),
+        })?;
 
     let cli_version = Version::parse(env!("CARGO_PKG_VERSION"))?;
     write!(
@@ -507,21 +527,26 @@ fn load_js_grammar_file(grammar_path: &Path, js_runtime: Option<&str>) -> JSResu
          globalThis.TREE_SITTER_CLI_VERSION_PATCH = {};",
         cli_version.major, cli_version.minor, cli_version.patch,
     )
-    .map_err(|e| {
-        JSError::IO(format!(
-            "Failed to write tree-sitter version to `{js_runtime}`'s stdin -- {e}"
-        ))
-    })?;
-    js_stdin.write(include_bytes!("./dsl.js")).map_err(|e| {
-        JSError::IO(format!(
-            "Failed to write grammar dsl to `{js_runtime}`'s stdin -- {e}"
-        ))
+    .map_err(|e| JSError::JSRuntimeWrite {
+        runtime: js_runtime.to_string(),
+        item: "tree-sitter version".to_string(),
+        error: e.to_string(),
     })?;
+    js_stdin
+        .write(include_bytes!("./dsl.js"))
+        .map_err(|e| JSError::JSRuntimeWrite {
+            runtime: js_runtime.to_string(),
+            item: "grammar dsl".to_string(),
+            error: e.to_string(),
+        })?;
     drop(js_stdin);
 
     let output = js_process
         .wait_with_output()
-        .map_err(|e| JSError::IO(format!("Failed to read output from `{js_runtime}` -- {e}")))?;
+        .map_err(|e| JSError::JSRuntimeRead {
+            runtime: js_runtime.to_string(),
+            error: e.to_string(),
+        })?;
     match output.status.code() {
         Some(0) => {
             let stdout = String::from_utf8(output.stdout).map_err(|e| JSError::JSRuntimeUtf8 {
@@ -537,9 +562,15 @@ fn load_js_grammar_file(grammar_path: &Path, js_runtime: Option<&str>) -> JSResu
                 grammar_json = &stdout[pos + 1..];
 
                 let mut stdout = std::io::stdout().lock();
-                stdout.write_all(node_output.as_bytes())?;
-                stdout.write_all(b"\n")?;
-                stdout.flush()?;
+                stdout
+                    .write_all(node_output.as_bytes())
+                    .map_err(|e| JSError::IO(IoError::new(&e, None)))?;
+                stdout
+                    .write_all(b"\n")
+                    .map_err(|e| JSError::IO(IoError::new(&e, None)))?;
+                stdout
+                    .flush()
+                    .map_err(|e| JSError::IO(IoError::new(&e, None)))?;
             }
 
             Ok(serde_json::to_string_pretty(&serde_json::from_str::<
@@ -559,8 +590,7 @@ fn load_js_grammar_file(grammar_path: &Path, js_runtime: Option<&str>) -> JSResu
 
 #[cfg(feature = "load")]
 pub fn write_file(path: &Path, body: impl AsRef<[u8]>) -> GenerateResult<()> {
-    fs::write(path, body)
-        .map_err(|e| GenerateError::IO(format!("Failed to write {:?} -- {e}", path.file_name())))
+    fs::write(path, body).map_err(|e| GenerateError::IO(IoError::new(&e, Some(path))))
 }
 
 #[cfg(test)]
diff --git a/crates/generate/src/quickjs.rs b/crates/generate/src/quickjs.rs
index 689615fc..848030e8 100644
--- a/crates/generate/src/quickjs.rs
+++ b/crates/generate/src/quickjs.rs
@@ -10,7 +10,7 @@ use rquickjs::{
     Context, Ctx, Function, Module, Object, Runtime, Type, Value,
 };
 
-use super::{JSError, JSResult};
+use super::{IoError, JSError, JSResult};
 
 const DSL: &[u8] = include_bytes!("dsl.js");
 
@@ -266,10 +266,10 @@ pub fn execute_native_runtime(grammar_path: &Path) -> JSResult<String> {
     let loader = ScriptLoader::default().with_extension("mjs");
     runtime.set_loader(resolver, loader);
 
-    let cwd = std::env::current_dir()?;
+    let cwd = std::env::current_dir().map_err(|e| JSError::IO(IoError::new(&e, None)))?;
     let relative_path = pathdiff::diff_paths(grammar_path, &cwd)
         .map(|p| p.to_string_lossy().to_string())
-        .ok_or_else(|| JSError::IO("Failed to get relative path".to_string()))?;
+        .ok_or(JSError::RelativePath)?;
 
     context.with(|ctx| -> JSResult<String> {
         let globals = ctx.globals();

From 0df2916920760371a73e7618c40c88221f0329f9 Mon Sep 17 00:00:00 2001
From: Christian Clason <c.clason@uni-graz.at>
Date: Fri, 31 Oct 2025 11:58:20 +0100
Subject: [PATCH 09/14] bulild(deps): cargo update

---
 Cargo.lock | 28 ++++++++++++++--------------
 1 file changed, 14 insertions(+), 14 deletions(-)

diff --git a/Cargo.lock b/Cargo.lock
index 726289b9..03146c9b 100644
--- a/Cargo.lock
+++ b/Cargo.lock
@@ -67,22 +67,22 @@ dependencies = [
 
 [[package]]
 name = "anstyle-query"
-version = "1.1.4"
+version = "1.1.5"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "9e231f6134f61b71076a3eab506c379d4f36122f2af15a9ff04415ea4c3339e2"
+checksum = "40c48f72fd53cd289104fc64099abca73db4166ad86ea0b4341abe65af83dadc"
 dependencies = [
- "windows-sys 0.60.2",
+ "windows-sys 0.61.2",
 ]
 
 [[package]]
 name = "anstyle-wincon"
-version = "3.0.10"
+version = "3.0.11"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "3e0633414522a32ffaac8ac6cc8f748e090c5717661fddeea04219e2344f5f2a"
+checksum = "291e6a250ff86cd4a820112fb8898808a366d8f9f58ce16d1f538353ad55747d"
 dependencies = [
  "anstyle",
  "once_cell_polyfill",
- "windows-sys 0.60.2",
+ "windows-sys 0.61.2",
 ]
 
 [[package]]
@@ -1401,9 +1401,9 @@ dependencies = [
 
 [[package]]
 name = "quote"
-version = "1.0.41"
+version = "1.0.42"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "ce25767e7b499d1b604768e7cde645d14cc8584231ea6b295e9c9eb22c02e1d1"
+checksum = "a338cc41d27e6cc6dce6cefc13a0729dfbb81c262b1f519331575dd80ef3067f"
 dependencies = [
  "proc-macro2",
 ]
@@ -1784,9 +1784,9 @@ checksum = "7da8b5736845d9f2fcb837ea5d9e2628564b3b043a70948a3f0b778838c5fb4f"
 
 [[package]]
 name = "syn"
-version = "2.0.108"
+version = "2.0.110"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "da58917d35242480a05c2897064da0a80589a2a0476c9a3f2fdc83b53502e917"
+checksum = "a99801b5bd34ede4cf3fc688c5919368fea4e4814a4664359503e6015b280aea"
 dependencies = [
  "proc-macro2",
  "quote",
@@ -2039,7 +2039,7 @@ dependencies = [
  "log",
  "serde",
  "serde_json",
- "thiserror 2.0.16",
+ "thiserror 2.0.17",
 ]
 
 [[package]]
@@ -2095,7 +2095,7 @@ dependencies = [
  "serde",
  "serde_json",
  "tempfile",
- "thiserror 2.0.16",
+ "thiserror 2.0.17",
  "tree-sitter",
  "tree-sitter-highlight",
  "tree-sitter-tags",
@@ -2123,9 +2123,9 @@ dependencies = [
 
 [[package]]
 name = "unicode-ident"
-version = "1.0.20"
+version = "1.0.22"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "462eeb75aeb73aea900253ce739c8e18a67423fadf006037cd3ff27e82748a06"
+checksum = "9312f7c4f6ff9069b165498234ce8be658059c6728633667c526e27dc2cf1df5"
 
 [[package]]
 name = "unicode-segmentation"

From 57e3a7b2ca5837677c7198d47207d6e15eaa7a73 Mon Sep 17 00:00:00 2001
From: Valeriy Kosikhin <vkosikhin@gmail.com>
Date: Mon, 17 Nov 2025 15:17:25 +0300
Subject: [PATCH 10/14] fix(loader): set correct runtime host for cc while
 cross-compiling

Pass the BUILD_TARGET variable from the build environment as 'host' for
the cc crate. Otherwise, when cross-compiled, cc will keep looking for a
cross-compiler instead of the native one on the target system.

Signed-off-by: Valeriy Kosikhin <vkosikhin@gmail.com>
---
 crates/loader/src/loader.rs | 6 ++++--
 1 file changed, 4 insertions(+), 2 deletions(-)

diff --git a/crates/loader/src/loader.rs b/crates/loader/src/loader.rs
index 08d6af84..cf2c1a77 100644
--- a/crates/loader/src/loader.rs
+++ b/crates/loader/src/loader.rs
@@ -557,7 +557,6 @@ impl Config {
 }
 
 const BUILD_TARGET: &str = env!("BUILD_TARGET");
-const BUILD_HOST: &str = env!("BUILD_HOST");
 
 pub struct LanguageConfiguration<'a> {
     pub scope: Option<String>,
@@ -1107,7 +1106,10 @@ impl Loader {
             .cargo_metadata(false)
             .cargo_warnings(false)
             .target(BUILD_TARGET)
-            .host(BUILD_HOST)
+            // BUILD_TARGET from the build environment becomes a runtime host for cc.
+            // Otherwise, when cross compiled, cc will keep looking for a cross-compiler
+            // on the target system instead of the native compiler.
+            .host(BUILD_TARGET)
             .debug(self.debug_build)
             .file(&config.parser_path)
             .includes(&config.header_paths)

From 3072d35ed5f7dcd01a67c9ee04264e8bd9a730f7 Mon Sep 17 00:00:00 2001
From: "dependabot[bot]" <49699333+dependabot[bot]@users.noreply.github.com>
Date: Mon, 17 Nov 2025 21:13:38 +0000
Subject: [PATCH 11/14] build(deps): bump the cargo group with 2 updates

Bumps the cargo group with 2 updates: [cc](https://github.com/rust-lang/cc-rs) and [wasmparser](https://github.com/bytecodealliance/wasm-tools).


Updates `cc` from 1.2.45 to 1.2.46
- [Release notes](https://github.com/rust-lang/cc-rs/releases)
- [Changelog](https://github.com/rust-lang/cc-rs/blob/main/CHANGELOG.md)
- [Commits](https://github.com/rust-lang/cc-rs/compare/cc-v1.2.45...cc-v1.2.46)

Updates `wasmparser` from 0.240.0 to 0.241.2
- [Release notes](https://github.com/bytecodealliance/wasm-tools/releases)
- [Commits](https://github.com/bytecodealliance/wasm-tools/commits)

---
updated-dependencies:
- dependency-name: cc
  dependency-version: 1.2.46
  dependency-type: direct:production
  update-type: version-update:semver-patch
  dependency-group: cargo
- dependency-name: wasmparser
  dependency-version: 0.241.2
  dependency-type: direct:production
  update-type: version-update:semver-minor
  dependency-group: cargo
...

Signed-off-by: dependabot[bot] <support@github.com>
---
 Cargo.lock | 14 +++++++-------
 Cargo.toml |  4 ++--
 2 files changed, 9 insertions(+), 9 deletions(-)

diff --git a/Cargo.lock b/Cargo.lock
index 03146c9b..ce5d678b 100644
--- a/Cargo.lock
+++ b/Cargo.lock
@@ -187,9 +187,9 @@ checksum = "d71b6127be86fdcfddb610f7182ac57211d4b18a3e9c82eb2d17662f2227ad6a"
 
 [[package]]
 name = "cc"
-version = "1.2.45"
+version = "1.2.46"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "35900b6c8d709fb1d854671ae27aeaa9eec2f8b01b364e1619a40da3e6fe2afe"
+checksum = "b97463e1064cb1b1c1384ad0a0b9c8abd0988e2a91f52606c80ef14aadb63e36"
 dependencies = [
  "find-msvc-tools",
  "shlex",
@@ -664,9 +664,9 @@ dependencies = [
 
 [[package]]
 name = "find-msvc-tools"
-version = "0.1.4"
+version = "0.1.5"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "52051878f80a721bb68ebfbc930e07b65ba72f2da88968ea5c06fd6ca3d3a127"
+checksum = "3a3076410a55c90011c298b04d0cfa770b00fa04e1e3c97d3f6c9de105a03844"
 
 [[package]]
 name = "fnv"
@@ -2026,7 +2026,7 @@ dependencies = [
  "tree-sitter-tests-proc-macro",
  "unindent",
  "walkdir",
- "wasmparser 0.240.0",
+ "wasmparser 0.241.2",
  "webbrowser",
  "widestring",
 ]
@@ -2270,9 +2270,9 @@ dependencies = [
 
 [[package]]
 name = "wasmparser"
-version = "0.240.0"
+version = "0.241.2"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "b722dcf61e0ea47440b53ff83ccb5df8efec57a69d150e4f24882e4eba7e24a4"
+checksum = "46d90019b1afd4b808c263e428de644f3003691f243387d30d673211ee0cb8e8"
 dependencies = [
  "bitflags 2.10.0",
  "hashbrown 0.15.5",
diff --git a/Cargo.toml b/Cargo.toml
index 5afc53b5..cc3520fe 100644
--- a/Cargo.toml
+++ b/Cargo.toml
@@ -106,7 +106,7 @@ ansi_colours = "1.2.3"
 anstyle = "1.0.13"
 anyhow = "1.0.100"
 bstr = "1.12.0"
-cc = "1.2.45"
+cc = "1.2.46"
 clap = { version = "4.5.51", features = [
   "cargo",
   "derive",
@@ -150,7 +150,7 @@ tiny_http = "0.12.0"
 topological-sort = "0.2.2"
 unindent = "0.2.4"
 walkdir = "2.5.0"
-wasmparser = "0.240.0"
+wasmparser = "0.241.2"
 webbrowser = "1.0.5"
 
 tree-sitter = { version = "0.26.0", path = "./lib" }

From f3012a999d94c65254a6fd91e4da0928e1369c99 Mon Sep 17 00:00:00 2001
From: Antonin Delpeuch <antonin@delpeuch.eu>
Date: Mon, 13 Oct 2025 23:07:05 +0200
Subject: [PATCH 12/14] feat(bindings): expose the queries dynamically

Available in the Rust, Python, and Node bindings

Co-authored-by: ObserverOfTime <chronobserver@disroot.org>
---
 crates/cli/src/init.rs                 | 223 +++++++++++++++++++++----
 crates/cli/src/templates/.editorconfig |   2 +-
 crates/cli/src/templates/__init__.py   |  33 ++--
 crates/cli/src/templates/__init__.pyi  |  18 +-
 crates/cli/src/templates/build.rs      |  17 ++
 crates/cli/src/templates/index.d.ts    |  39 ++++-
 crates/cli/src/templates/index.js      |  26 ++-
 crates/cli/src/templates/lib.rs        |  19 ++-
 crates/loader/src/loader.rs            |  34 ++--
 9 files changed, 335 insertions(+), 76 deletions(-)

diff --git a/crates/cli/src/init.rs b/crates/cli/src/init.rs
index 62923441..deb64292 100644
--- a/crates/cli/src/init.rs
+++ b/crates/cli/src/init.rs
@@ -14,7 +14,11 @@ use semver::Version;
 use serde::{Deserialize, Serialize};
 use serde_json::{Map, Value};
 use tree_sitter_generate::write_file;
-use tree_sitter_loader::{Author, Bindings, Grammar, Links, Metadata, PathsJSON, TreeSitterJSON};
+use tree_sitter_loader::{
+    Author, Bindings, Grammar, Links, Metadata, PathsJSON, TreeSitterJSON,
+    DEFAULT_HIGHLIGHTS_QUERY_FILE_NAME, DEFAULT_INJECTIONS_QUERY_FILE_NAME,
+    DEFAULT_LOCALS_QUERY_FILE_NAME, DEFAULT_TAGS_QUERY_FILE_NAME,
+};
 
 const CLI_VERSION: &str = env!("CARGO_PKG_VERSION");
 const CLI_VERSION_PLACEHOLDER: &str = "CLI_VERSION";
@@ -60,6 +64,11 @@ const AUTHOR_EMAIL_PLACEHOLDER_GRAMMAR: &str = " PARSER_AUTHOR_EMAIL";
 
 const FUNDING_URL_PLACEHOLDER: &str = "FUNDING_URL";
 
+const HIGHLIGHTS_QUERY_PATH_PLACEHOLDER: &str = "HIGHLIGHTS_QUERY_PATH";
+const INJECTIONS_QUERY_PATH_PLACEHOLDER: &str = "INJECTIONS_QUERY_PATH";
+const LOCALS_QUERY_PATH_PLACEHOLDER: &str = "LOCALS_QUERY_PATH";
+const TAGS_QUERY_PATH_PLACEHOLDER: &str = "TAGS_QUERY_PATH";
+
 const GRAMMAR_JS_TEMPLATE: &str = include_str!("./templates/grammar.js");
 const PACKAGE_JSON_TEMPLATE: &str = include_str!("./templates/package.json");
 const GITIGNORE_TEMPLATE: &str = include_str!("./templates/gitignore");
@@ -205,6 +214,10 @@ struct GenerateOpts<'a> {
     camel_parser_name: &'a str,
     title_parser_name: &'a str,
     class_name: &'a str,
+    highlights_query_path: &'a str,
+    injections_query_path: &'a str,
+    locals_query_path: &'a str,
+    tags_query_path: &'a str,
 }
 
 pub fn generate_grammar_files(
@@ -255,6 +268,20 @@ pub fn generate_grammar_files(
         .clone()
         .unwrap_or_else(|| format!("TreeSitter{}", language_name.to_upper_camel_case()));
 
+    fn pathsjson_to_variable<'a>(paths_json: &'a PathsJSON, default: &'a PathBuf) -> &'a str {
+        match paths_json {
+            PathsJSON::Empty => Some(default),
+            PathsJSON::Single(path_buf) => Some(path_buf),
+            PathsJSON::Multiple(paths) => paths.first(),
+        }
+        .map_or("", |path| path.as_os_str().to_str().unwrap_or(""))
+    }
+
+    let default_highlights_path = Path::new("queries").join(DEFAULT_HIGHLIGHTS_QUERY_FILE_NAME);
+    let default_injections_path = Path::new("queries").join(DEFAULT_INJECTIONS_QUERY_FILE_NAME);
+    let default_locals_path = Path::new("queries").join(DEFAULT_LOCALS_QUERY_FILE_NAME);
+    let default_tags_path = Path::new("queries").join(DEFAULT_TAGS_QUERY_FILE_NAME);
+
     let generate_opts = GenerateOpts {
         author_name: authors
             .map(|a| a.first().map(|a| a.name.as_str()))
@@ -281,6 +308,22 @@ pub fn generate_grammar_files(
         camel_parser_name: &camel_name,
         title_parser_name: &title_name,
         class_name: &class_name,
+        highlights_query_path: pathsjson_to_variable(
+            &tree_sitter_config.grammars[0].highlights,
+            &default_highlights_path,
+        ),
+        injections_query_path: pathsjson_to_variable(
+            &tree_sitter_config.grammars[0].injections,
+            &default_injections_path,
+        ),
+        locals_query_path: pathsjson_to_variable(
+            &tree_sitter_config.grammars[0].locals,
+            &default_locals_path,
+        ),
+        tags_query_path: pathsjson_to_variable(
+            &tree_sitter_config.grammars[0].tags,
+            &default_tags_path,
+        ),
     };
 
     // Create package.json
@@ -388,8 +431,47 @@ pub fn generate_grammar_files(
     // Generate Rust bindings
     if tree_sitter_config.bindings.rust {
         missing_path(bindings_dir.join("rust"), create_dir)?.apply(|path| {
-            missing_path(path.join("lib.rs"), |path| {
+            missing_path_else(path.join("lib.rs"), allow_update, |path| {
                 generate_file(path, LIB_RS_TEMPLATE, language_name, &generate_opts)
+            }, |path| {
+                let mut contents = fs::read_to_string(path)?;
+                if !contents.contains("#[cfg(with_highlights_query)]") {
+                let replacement = indoc! {r#"
+                    #[cfg(with_highlights_query)]
+                    /// The syntax highlighting query for this grammar.
+                    pub const HIGHLIGHTS_QUERY: &str = include_str!("../../HIGHLIGHTS_QUERY_PATH");
+
+                    #[cfg(with_injections_query)]
+                    /// The language injection query for this grammar.
+                    pub const INJECTIONS_QUERY: &str = include_str!("../../INJECTIONS_QUERY_PATH");
+
+                    #[cfg(with_locals_query)]
+                    /// The local variable query for this grammar.
+                    pub const LOCALS_QUERY: &str = include_str!("../../LOCALS_QUERY_PATH");
+
+                    #[cfg(with_tags_query)]
+                    /// The symbol tagging query for this grammar.
+                    pub const TAGS_QUERY: &str = include_str!("../../TAGS_QUERY_PATH");
+                    "#}
+                    .replace("HIGHLIGHTS_QUERY_PATH", generate_opts.highlights_query_path)
+                    .replace("INJECTIONS_QUERY_PATH", generate_opts.injections_query_path)
+                    .replace("LOCALS_QUERY_PATH", generate_opts.locals_query_path)
+                    .replace("TAGS_QUERY_PATH", generate_opts.tags_query_path);
+                contents = contents
+                    .replace(
+                        indoc! {r#"
+                        // NOTE: uncomment these to include any queries that this grammar contains:
+
+                        // pub const HIGHLIGHTS_QUERY: &str = include_str!("../../queries/highlights.scm");
+                        // pub const INJECTIONS_QUERY: &str = include_str!("../../queries/injections.scm");
+                        // pub const LOCALS_QUERY: &str = include_str!("../../queries/locals.scm");
+                        // pub const TAGS_QUERY: &str = include_str!("../../queries/tags.scm");
+                        "#},
+                        &replacement,
+                    );
+                }
+                write_file(path, contents)?;
+                Ok(())
             })?;
 
             missing_path_else(
@@ -397,27 +479,29 @@ pub fn generate_grammar_files(
                 allow_update,
                 |path| generate_file(path, BUILD_RS_TEMPLATE, language_name, &generate_opts),
                 |path| {
-                    let replacement = indoc!{r#"
-                        c_config.flag("-utf-8");
+                    let mut contents = fs::read_to_string(path)?;
+                    if !contents.contains("wasm32-unknown-unknown") {
+                        let replacement = indoc!{r#"
+                            c_config.flag("-utf-8");
 
-                        if std::env::var("TARGET").unwrap() == "wasm32-unknown-unknown" {
-                            let Ok(wasm_headers) = std::env::var("DEP_TREE_SITTER_LANGUAGE_WASM_HEADERS") else {
-                                panic!("Environment variable DEP_TREE_SITTER_LANGUAGE_WASM_HEADERS must be set by the language crate");
-                            };
-                            let Ok(wasm_src) =
-                                std::env::var("DEP_TREE_SITTER_LANGUAGE_WASM_SRC").map(std::path::PathBuf::from)
-                            else {
-                                panic!("Environment variable DEP_TREE_SITTER_LANGUAGE_WASM_SRC must be set by the language crate");
-                            };
+                            if std::env::var("TARGET").unwrap() == "wasm32-unknown-unknown" {
+                                let Ok(wasm_headers) = std::env::var("DEP_TREE_SITTER_LANGUAGE_WASM_HEADERS") else {
+                                    panic!("Environment variable DEP_TREE_SITTER_LANGUAGE_WASM_HEADERS must be set by the language crate");
+                                };
+                                let Ok(wasm_src) =
+                                    std::env::var("DEP_TREE_SITTER_LANGUAGE_WASM_SRC").map(std::path::PathBuf::from)
+                                else {
+                                    panic!("Environment variable DEP_TREE_SITTER_LANGUAGE_WASM_SRC must be set by the language crate");
+                                };
 
-                            c_config.include(&wasm_headers);
-                            c_config.files([
-                                wasm_src.join("stdio.c"),
-                                wasm_src.join("stdlib.c"),
-                                wasm_src.join("string.c"),
-                            ]);
-                        }
-                    "#};
+                                c_config.include(&wasm_headers);
+                                c_config.files([
+                                    wasm_src.join("stdio.c"),
+                                    wasm_src.join("stdlib.c"),
+                                    wasm_src.join("string.c"),
+                                ]);
+                            }
+                        "#};
 
                     let indented_replacement = replacement
                         .lines()
@@ -425,11 +509,48 @@ pub fn generate_grammar_files(
                         .collect::<Vec<_>>()
                         .join("\n");
 
-                    let mut contents = fs::read_to_string(path)?;
-                    if !contents.contains("wasm32-unknown-unknown") {
                         contents = contents.replace(r#"    c_config.flag("-utf-8");"#, &indented_replacement);
                     }
 
+                    // Introduce configuration variables for dynamic query inclusion
+                    if !contents.contains("with_highlights_query") {
+                        let replaced = indoc! {r#"
+                                c_config.compile("tree-sitter-KEBAB_PARSER_NAME");
+                            }"#}
+                            .replace("KEBAB_PARSER_NAME", &language_name.to_kebab_case());
+
+                        let replacement = indoc! {r#"
+                                c_config.compile("tree-sitter-KEBAB_PARSER_NAME");
+
+                                println!("cargo:rustc-check-cfg=cfg(with_highlights_query)");
+                                if !"HIGHLIGHTS_QUERY_PATH".is_empty() && std::path::Path::new("HIGHLIGHTS_QUERY_PATH").exists() {
+                                    println!("cargo:rustc-cfg=with_highlights_query");
+                                }
+                                println!("cargo:rustc-check-cfg=cfg(with_injections_query)");
+                                if !"INJECTIONS_QUERY_PATH".is_empty() && std::path::Path::new("INJECTIONS_QUERY_PATH").exists() {
+                                    println!("cargo:rustc-cfg=with_injections_query");
+                                }
+                                println!("cargo:rustc-check-cfg=cfg(with_locals_query)");
+                                if !"LOCALS_QUERY_PATH".is_empty() && std::path::Path::new("LOCALS_QUERY_PATH").exists() {
+                                    println!("cargo:rustc-cfg=with_locals_query");
+                                }
+                                println!("cargo:rustc-check-cfg=cfg(with_tags_query)");
+                                if !"TAGS_QUERY_PATH".is_empty() && std::path::Path::new("TAGS_QUERY_PATH").exists() {
+                                    println!("cargo:rustc-cfg=with_tags_query");
+                                }
+                            }"#}
+                            .replace("KEBAB_PARSER_NAME", &language_name.to_kebab_case())
+                            .replace("HIGHLIGHTS_QUERY_PATH", generate_opts.highlights_query_path)
+                            .replace("INJECTIONS_QUERY_PATH", generate_opts.injections_query_path)
+                            .replace("LOCALS_QUERY_PATH", generate_opts.locals_query_path)
+                            .replace("TAGS_QUERY_PATH", generate_opts.tags_query_path);
+
+                        contents = contents.replace(
+                            &replaced,
+                            &replacement,
+                        );
+                    }
+
                     write_file(path, contents)?;
                     Ok(())
                 },
@@ -468,7 +589,7 @@ pub fn generate_grammar_files(
                 |path| generate_file(path, INDEX_JS_TEMPLATE, language_name, &generate_opts),
                 |path| {
                     let contents = fs::read_to_string(path)?;
-                    if !contents.contains("new URL") {
+                    if !contents.contains("Object.defineProperty") {
                         warn!("Replacing index.js");
                         generate_file(path, INDEX_JS_TEMPLATE, language_name, &generate_opts)?;
                     }
@@ -476,9 +597,19 @@ pub fn generate_grammar_files(
                 },
             )?;
 
-            missing_path(path.join("index.d.ts"), |path| {
-                generate_file(path, INDEX_D_TS_TEMPLATE, language_name, &generate_opts)
-            })?;
+            missing_path_else(
+                path.join("index.d.ts"),
+                allow_update,
+                |path| generate_file(path, INDEX_D_TS_TEMPLATE, language_name, &generate_opts),
+                |path| {
+                    let contents = fs::read_to_string(path)?;
+                    if !contents.contains("export default binding") {
+                        warn!("Replacing index.d.ts");
+                        generate_file(path, INDEX_D_TS_TEMPLATE, language_name, &generate_opts)?;
+                    }
+                    Ok(())
+                },
+            )?;
 
             missing_path_else(
                 path.join("binding_test.js"),
@@ -717,9 +848,21 @@ pub fn generate_grammar_files(
                 },
             )?;
 
-            missing_path(lang_path.join("__init__.py"), |path| {
-                generate_file(path, INIT_PY_TEMPLATE, language_name, &generate_opts)
-            })?;
+            missing_path_else(
+                lang_path.join("__init__.py"),
+                allow_update,
+                |path| {
+                    generate_file(path, INIT_PY_TEMPLATE, language_name, &generate_opts)
+                },
+                |path| {
+                    let contents = fs::read_to_string(path)?;
+                    if !contents.contains("uncomment these to include any queries") {
+                        warn!("Replacing __init__.py");
+                        generate_file(path, INIT_PY_TEMPLATE, language_name, &generate_opts)?;
+                    }
+                    Ok(())
+                },
+            )?;
 
             missing_path_else(
                 lang_path.join("__init__.pyi"),
@@ -727,7 +870,10 @@ pub fn generate_grammar_files(
                 |path| generate_file(path, INIT_PYI_TEMPLATE, language_name, &generate_opts),
                 |path| {
                     let mut contents = fs::read_to_string(path)?;
-                    if !contents.contains("CapsuleType") {
+                    if contents.contains("uncomment these to include any queries") {
+                        warn!("Replacing __init__.pyi");
+                        generate_file(path, INIT_PYI_TEMPLATE, language_name, &generate_opts)?;
+                    } else if !contents.contains("CapsuleType") {
                         contents = contents
                             .replace(
                                 "from typing import Final",
@@ -990,7 +1136,20 @@ fn generate_file(
             PARSER_VERSION_PLACEHOLDER,
             &generate_opts.version.to_string(),
         )
-        .replace(PARSER_CLASS_NAME_PLACEHOLDER, generate_opts.class_name);
+        .replace(PARSER_CLASS_NAME_PLACEHOLDER, generate_opts.class_name)
+        .replace(
+            HIGHLIGHTS_QUERY_PATH_PLACEHOLDER,
+            generate_opts.highlights_query_path,
+        )
+        .replace(
+            INJECTIONS_QUERY_PATH_PLACEHOLDER,
+            generate_opts.injections_query_path,
+        )
+        .replace(
+            LOCALS_QUERY_PATH_PLACEHOLDER,
+            generate_opts.locals_query_path,
+        )
+        .replace(TAGS_QUERY_PATH_PLACEHOLDER, generate_opts.tags_query_path);
 
     if let Some(name) = generate_opts.author_name {
         replacement = replacement.replace(AUTHOR_NAME_PLACEHOLDER, name);
diff --git a/crates/cli/src/templates/.editorconfig b/crates/cli/src/templates/.editorconfig
index 65330c40..c4650c59 100644
--- a/crates/cli/src/templates/.editorconfig
+++ b/crates/cli/src/templates/.editorconfig
@@ -7,7 +7,7 @@ charset = utf-8
 indent_style = space
 indent_size = 2
 
-[*.js]
+[*.{js,ts}]
 indent_style = space
 indent_size = 2
 
diff --git a/crates/cli/src/templates/__init__.py b/crates/cli/src/templates/__init__.py
index fd137b0f..784887a7 100644
--- a/crates/cli/src/templates/__init__.py
+++ b/crates/cli/src/templates/__init__.py
@@ -6,32 +6,33 @@ from ._binding import language
 
 
 def _get_query(name, file):
-    query = _files(f"{__package__}.queries") / file
-    globals()[name] = query.read_text()
+    try:
+        query = _files(f"{__package__}") / file
+        globals()[name] = query.read_text()
+    except FileNotFoundError:
+        globals()[name] = None
     return globals()[name]
 
 
 def __getattr__(name):
-    # NOTE: uncomment these to include any queries that this grammar contains:
-
-    # if name == "HIGHLIGHTS_QUERY":
-    #     return _get_query("HIGHLIGHTS_QUERY", "highlights.scm")
-    # if name == "INJECTIONS_QUERY":
-    #     return _get_query("INJECTIONS_QUERY", "injections.scm")
-    # if name == "LOCALS_QUERY":
-    #     return _get_query("LOCALS_QUERY", "locals.scm")
-    # if name == "TAGS_QUERY":
-    #     return _get_query("TAGS_QUERY", "tags.scm")
+    if name == "HIGHLIGHTS_QUERY":
+        return _get_query("HIGHLIGHTS_QUERY", "HIGHLIGHTS_QUERY_PATH")
+    if name == "INJECTIONS_QUERY":
+        return _get_query("INJECTIONS_QUERY", "INJECTIONS_QUERY_PATH")
+    if name == "LOCALS_QUERY":
+        return _get_query("LOCALS_QUERY", "LOCALS_QUERY_PATH")
+    if name == "TAGS_QUERY":
+        return _get_query("TAGS_QUERY", "TAGS_QUERY_PATH")
 
     raise AttributeError(f"module {__name__!r} has no attribute {name!r}")
 
 
 __all__ = [
     "language",
-    # "HIGHLIGHTS_QUERY",
-    # "INJECTIONS_QUERY",
-    # "LOCALS_QUERY",
-    # "TAGS_QUERY",
+    "HIGHLIGHTS_QUERY",
+    "INJECTIONS_QUERY",
+    "LOCALS_QUERY",
+    "TAGS_QUERY",
 ]
 
 
diff --git a/crates/cli/src/templates/__init__.pyi b/crates/cli/src/templates/__init__.pyi
index 5c63215d..5c88ff6c 100644
--- a/crates/cli/src/templates/__init__.pyi
+++ b/crates/cli/src/templates/__init__.pyi
@@ -1,11 +1,17 @@
 from typing import Final
 from typing_extensions import CapsuleType
 
-# NOTE: uncomment these to include any queries that this grammar contains:
+HIGHLIGHTS_QUERY: Final[str] | None
+"""The syntax highlighting query for this grammar."""
 
-# HIGHLIGHTS_QUERY: Final[str]
-# INJECTIONS_QUERY: Final[str]
-# LOCALS_QUERY: Final[str]
-# TAGS_QUERY: Final[str]
+INJECTIONS_QUERY: Final[str] | None
+"""The language injection query for this grammar."""
 
-def language() -> CapsuleType: ...
+LOCALS_QUERY: Final[str] | None
+"""The local variable query for this grammar."""
+
+TAGS_QUERY: Final[str] | None
+"""The symbol tagging query for this grammar."""
+
+def language() -> CapsuleType:
+    """The tree-sitter language function for this grammar."""
diff --git a/crates/cli/src/templates/build.rs b/crates/cli/src/templates/build.rs
index 272d8961..e3fffe4b 100644
--- a/crates/cli/src/templates/build.rs
+++ b/crates/cli/src/templates/build.rs
@@ -36,4 +36,21 @@ fn main() {
     }
 
     c_config.compile("tree-sitter-KEBAB_PARSER_NAME");
+
+    println!("cargo:rustc-check-cfg=cfg(with_highlights_query)");
+    if !"HIGHLIGHTS_QUERY_PATH".is_empty() && std::path::Path::new("HIGHLIGHTS_QUERY_PATH").exists() {
+        println!("cargo:rustc-cfg=with_highlights_query");
+    }
+    println!("cargo:rustc-check-cfg=cfg(with_injections_query)");
+    if !"INJECTIONS_QUERY_PATH".is_empty() && std::path::Path::new("INJECTIONS_QUERY_PATH").exists() {
+        println!("cargo:rustc-cfg=with_injections_query");
+    }
+    println!("cargo:rustc-check-cfg=cfg(with_locals_query)");
+    if !"LOCALS_QUERY_PATH".is_empty() && std::path::Path::new("LOCALS_QUERY_PATH").exists() {
+        println!("cargo:rustc-cfg=with_locals_query");
+    }
+    println!("cargo:rustc-check-cfg=cfg(with_tags_query)");
+    if !"TAGS_QUERY_PATH".is_empty() && std::path::Path::new("TAGS_QUERY_PATH").exists() {
+        println!("cargo:rustc-cfg=with_tags_query");
+    }
 }
diff --git a/crates/cli/src/templates/index.d.ts b/crates/cli/src/templates/index.d.ts
index 528e060f..24576d32 100644
--- a/crates/cli/src/templates/index.d.ts
+++ b/crates/cli/src/templates/index.d.ts
@@ -18,10 +18,43 @@ type NodeInfo =
       children: ChildNode[];
     });
 
-type Language = {
+/**
+ * The tree-sitter language object for this grammar.
+ *
+ * @see {@linkcode https://tree-sitter.github.io/node-tree-sitter/interfaces/Parser.Language.html Parser.Language}
+ *
+ * @example
+ * import Parser from "tree-sitter";
+ * import CAMEL_PARSER_NAME from "tree-sitter-KEBAB_PARSER_NAME";
+ *
+ * const parser = new Parser();
+ * parser.setLanguage(CAMEL_PARSER_NAME);
+ */
+declare const binding: {
+  /**
+   * The inner language object.
+   * @private
+   */
   language: unknown;
+
+  /**
+   * The content of the `node-types.json` file for this grammar.
+   *
+   * @see {@linkplain https://tree-sitter.github.io/tree-sitter/using-parsers/6-static-node-types Static Node Types}
+   */
   nodeTypeInfo: NodeInfo[];
+
+  /** The syntax highlighting query for this grammar. */
+  HIGHLIGHTS_QUERY?: string;
+
+  /** The language injection query for this grammar. */
+  INJECTIONS_QUERY?: string;
+
+  /** The local variable query for this grammar. */
+  LOCALS_QUERY?: string;
+
+  /** The symbol tagging query for this grammar. */
+  TAGS_QUERY?: string;
 };
 
-declare const language: Language;
-export = language;
+export default binding;
diff --git a/crates/cli/src/templates/index.js b/crates/cli/src/templates/index.js
index 4b363040..b3edc2e3 100644
--- a/crates/cli/src/templates/index.js
+++ b/crates/cli/src/templates/index.js
@@ -1,3 +1,4 @@
+import { readFileSync } from "node:fs";
 import { fileURLToPath } from "node:url";
 
 const root = fileURLToPath(new URL("../..", import.meta.url));
@@ -8,8 +9,29 @@ const binding = typeof process.versions.bun === "string"
   : (await import("node-gyp-build")).default(root);
 
 try {
-  const nodeTypes = await import(`${root}/src/node-types.json`, {with: {type: "json"}});
+  const nodeTypes = await import(`${root}/src/node-types.json`, { with: { type: "json" } });
   binding.nodeTypeInfo = nodeTypes.default;
-} catch (_) {}
+} catch { }
+
+const queries = [
+  ["HIGHLIGHTS_QUERY", `${root}/HIGHLIGHTS_QUERY_PATH`],
+  ["INJECTIONS_QUERY", `${root}/INJECTIONS_QUERY_PATH`],
+  ["LOCALS_QUERY", `${root}/LOCALS_QUERY_PATH`],
+  ["TAGS_QUERY", `${root}/TAGS_QUERY_PATH`],
+];
+
+for (const [prop, path] of queries) {
+  Object.defineProperty(binding, prop, {
+    configurable: true,
+    enumerable: true,
+    get() {
+      delete binding[prop];
+      try {
+        binding[prop] = readFileSync(path, "utf8");
+      } catch { }
+      return binding[prop];
+    }
+  });
+}
 
 export default binding;
diff --git a/crates/cli/src/templates/lib.rs b/crates/cli/src/templates/lib.rs
index 8478f488..1e8c9ca3 100644
--- a/crates/cli/src/templates/lib.rs
+++ b/crates/cli/src/templates/lib.rs
@@ -32,12 +32,21 @@ pub const LANGUAGE: LanguageFn = unsafe { LanguageFn::from_raw(tree_sitter_PARSE
 /// [`node-types.json`]: https://tree-sitter.github.io/tree-sitter/using-parsers/6-static-node-types
 pub const NODE_TYPES: &str = include_str!("../../src/node-types.json");
 
-// NOTE: uncomment these to include any queries that this grammar contains:
+#[cfg(with_highlights_query)]
+/// The syntax highlighting query for this grammar.
+pub const HIGHLIGHTS_QUERY: &str = include_str!("../../HIGHLIGHTS_QUERY_PATH");
 
-// pub const HIGHLIGHTS_QUERY: &str = include_str!("../../queries/highlights.scm");
-// pub const INJECTIONS_QUERY: &str = include_str!("../../queries/injections.scm");
-// pub const LOCALS_QUERY: &str = include_str!("../../queries/locals.scm");
-// pub const TAGS_QUERY: &str = include_str!("../../queries/tags.scm");
+#[cfg(with_injections_query)]
+/// The language injection query for this grammar.
+pub const INJECTIONS_QUERY: &str = include_str!("../../INJECTIONS_QUERY_PATH");
+
+#[cfg(with_locals_query)]
+/// The local variable query for this grammar.
+pub const LOCALS_QUERY: &str = include_str!("../../LOCALS_QUERY_PATH");
+
+#[cfg(with_tags_query)]
+/// The symbol tagging query for this grammar.
+pub const TAGS_QUERY: &str = include_str!("../../TAGS_QUERY_PATH");
 
 #[cfg(test)]
 mod tests {
diff --git a/crates/loader/src/loader.rs b/crates/loader/src/loader.rs
index cf2c1a77..7c2e5226 100644
--- a/crates/loader/src/loader.rs
+++ b/crates/loader/src/loader.rs
@@ -245,6 +245,14 @@ impl std::fmt::Display for WasiSDKClangError {
     }
 }
 
+pub const DEFAULT_HIGHLIGHTS_QUERY_FILE_NAME: &str = "highlights.scm";
+
+pub const DEFAULT_INJECTIONS_QUERY_FILE_NAME: &str = "injections.scm";
+
+pub const DEFAULT_LOCALS_QUERY_FILE_NAME: &str = "locals.scm";
+
+pub const DEFAULT_TAGS_QUERY_FILE_NAME: &str = "tags.scm";
+
 #[derive(Default, Deserialize, Serialize)]
 pub struct Config {
     #[serde(default)]
@@ -1764,21 +1772,21 @@ impl LanguageConfiguration<'_> {
                 Some(
                     paths
                         .iter()
-                        .filter(|p| p.ends_with("highlights.scm"))
+                        .filter(|p| p.ends_with(DEFAULT_HIGHLIGHTS_QUERY_FILE_NAME))
                         .cloned()
                         .collect::<Vec<_>>(),
                 ),
                 Some(
                     paths
                         .iter()
-                        .filter(|p| p.ends_with("tags.scm"))
+                        .filter(|p| p.ends_with(DEFAULT_TAGS_QUERY_FILE_NAME))
                         .cloned()
                         .collect::<Vec<_>>(),
                 ),
                 Some(
                     paths
                         .iter()
-                        .filter(|p| p.ends_with("locals.scm"))
+                        .filter(|p| p.ends_with(DEFAULT_LOCALS_QUERY_FILE_NAME))
                         .cloned()
                         .collect::<Vec<_>>(),
                 ),
@@ -1793,7 +1801,7 @@ impl LanguageConfiguration<'_> {
                     } else {
                         self.highlights_filenames.as_deref()
                     },
-                    "highlights.scm",
+                    DEFAULT_HIGHLIGHTS_QUERY_FILE_NAME,
                 )?;
                 let (injections_query, injection_ranges) = self.read_queries(
                     if injections_filenames.is_some() {
@@ -1801,7 +1809,7 @@ impl LanguageConfiguration<'_> {
                     } else {
                         self.injections_filenames.as_deref()
                     },
-                    "injections.scm",
+                    DEFAULT_INJECTIONS_QUERY_FILE_NAME,
                 )?;
                 let (locals_query, locals_ranges) = self.read_queries(
                     if locals_filenames.is_some() {
@@ -1809,7 +1817,7 @@ impl LanguageConfiguration<'_> {
                     } else {
                         self.locals_filenames.as_deref()
                     },
-                    "locals.scm",
+                    DEFAULT_LOCALS_QUERY_FILE_NAME,
                 )?;
 
                 if highlights_query.is_empty() {
@@ -1871,10 +1879,12 @@ impl LanguageConfiguration<'_> {
     pub fn tags_config(&self, language: Language) -> LoaderResult<Option<&TagsConfiguration>> {
         self.tags_config
             .get_or_try_init(|| {
-                let (tags_query, tags_ranges) =
-                    self.read_queries(self.tags_filenames.as_deref(), "tags.scm")?;
-                let (locals_query, locals_ranges) =
-                    self.read_queries(self.locals_filenames.as_deref(), "locals.scm")?;
+                let (tags_query, tags_ranges) = self
+                    .read_queries(self.tags_filenames.as_deref(), DEFAULT_TAGS_QUERY_FILE_NAME)?;
+                let (locals_query, locals_ranges) = self.read_queries(
+                    self.locals_filenames.as_deref(),
+                    DEFAULT_LOCALS_QUERY_FILE_NAME,
+                )?;
                 if tags_query.is_empty() {
                     Ok(None)
                 } else {
@@ -1947,7 +1957,9 @@ impl LanguageConfiguration<'_> {
             }
         } else {
             // highlights.scm is needed to test highlights, and tags.scm to test tags
-            if default_path == "highlights.scm" || default_path == "tags.scm" {
+            if default_path == DEFAULT_HIGHLIGHTS_QUERY_FILE_NAME
+                || default_path == DEFAULT_TAGS_QUERY_FILE_NAME
+            {
                 warn!(
                     concat!(
                         "You should add a `{}` entry pointing to the {} path in the `tree-sitter` ",

From 0e1f715ef1b2b5b69530284f64b1969c4cb625a8 Mon Sep 17 00:00:00 2001
From: Antonin Delpeuch <antonin@delpeuch.eu>
Date: Wed, 5 Nov 2025 15:16:33 +0100
Subject: [PATCH 13/14] Move PathsJSON method, reformat

---
 crates/cli/src/init.rs      | 47 ++++++++++++++-----------------------
 crates/loader/src/loader.rs | 11 +++++++++
 2 files changed, 28 insertions(+), 30 deletions(-)

diff --git a/crates/cli/src/init.rs b/crates/cli/src/init.rs
index deb64292..0164cc8f 100644
--- a/crates/cli/src/init.rs
+++ b/crates/cli/src/init.rs
@@ -268,15 +268,6 @@ pub fn generate_grammar_files(
         .clone()
         .unwrap_or_else(|| format!("TreeSitter{}", language_name.to_upper_camel_case()));
 
-    fn pathsjson_to_variable<'a>(paths_json: &'a PathsJSON, default: &'a PathBuf) -> &'a str {
-        match paths_json {
-            PathsJSON::Empty => Some(default),
-            PathsJSON::Single(path_buf) => Some(path_buf),
-            PathsJSON::Multiple(paths) => paths.first(),
-        }
-        .map_or("", |path| path.as_os_str().to_str().unwrap_or(""))
-    }
-
     let default_highlights_path = Path::new("queries").join(DEFAULT_HIGHLIGHTS_QUERY_FILE_NAME);
     let default_injections_path = Path::new("queries").join(DEFAULT_INJECTIONS_QUERY_FILE_NAME);
     let default_locals_path = Path::new("queries").join(DEFAULT_LOCALS_QUERY_FILE_NAME);
@@ -308,22 +299,18 @@ pub fn generate_grammar_files(
         camel_parser_name: &camel_name,
         title_parser_name: &title_name,
         class_name: &class_name,
-        highlights_query_path: pathsjson_to_variable(
-            &tree_sitter_config.grammars[0].highlights,
-            &default_highlights_path,
-        ),
-        injections_query_path: pathsjson_to_variable(
-            &tree_sitter_config.grammars[0].injections,
-            &default_injections_path,
-        ),
-        locals_query_path: pathsjson_to_variable(
-            &tree_sitter_config.grammars[0].locals,
-            &default_locals_path,
-        ),
-        tags_query_path: pathsjson_to_variable(
-            &tree_sitter_config.grammars[0].tags,
-            &default_tags_path,
-        ),
+        highlights_query_path: tree_sitter_config.grammars[0]
+            .highlights
+            .to_variable_value(&default_highlights_path),
+        injections_query_path: tree_sitter_config.grammars[0]
+            .injections
+            .to_variable_value(&default_injections_path),
+        locals_query_path: tree_sitter_config.grammars[0]
+            .locals
+            .to_variable_value(&default_locals_path),
+        tags_query_path: tree_sitter_config.grammars[0]
+            .tags
+            .to_variable_value(&default_tags_path),
     };
 
     // Create package.json
@@ -503,11 +490,11 @@ pub fn generate_grammar_files(
                             }
                         "#};
 
-                    let indented_replacement = replacement
-                        .lines()
-                        .map(|line| if line.is_empty() { line.to_string() } else { format!("    {line}") })
-                        .collect::<Vec<_>>()
-                        .join("\n");
+                        let indented_replacement = replacement
+                            .lines()
+                            .map(|line| if line.is_empty() { line.to_string() } else { format!("    {line}") })
+                            .collect::<Vec<_>>()
+                            .join("\n");
 
                         contents = contents.replace(r#"    c_config.flag("-utf-8");"#, &indented_replacement);
                     }
diff --git a/crates/loader/src/loader.rs b/crates/loader/src/loader.rs
index 7c2e5226..28618be6 100644
--- a/crates/loader/src/loader.rs
+++ b/crates/loader/src/loader.rs
@@ -284,6 +284,17 @@ impl PathsJSON {
     const fn is_empty(&self) -> bool {
         matches!(self, Self::Empty)
     }
+
+    /// Represent this set of paths as a string that can be included in templates
+    #[must_use]
+    pub fn to_variable_value<'a>(&'a self, default: &'a PathBuf) -> &'a str {
+        match self {
+            Self::Empty => Some(default),
+            Self::Single(path_buf) => Some(path_buf),
+            Self::Multiple(paths) => paths.first(),
+        }
+        .map_or("", |path| path.as_os_str().to_str().unwrap_or(""))
+    }
 }
 
 #[derive(Serialize, Deserialize, Clone)]

From 877782a8a41d830f9e7f0f22dfcb67b3c2e50418 Mon Sep 17 00:00:00 2001
From: Will Lillis <will.lillis24@gmail.com>
Date: Sat, 1 Nov 2025 05:25:00 -0400
Subject: [PATCH 14/14] fix(docs): update cli docs to reflect changes to
 various subcommand arguments

---
 crates/cli/src/main.rs     | 11 +++--------
 docs/src/cli/fuzz.md       | 12 ++++++++++++
 docs/src/cli/generate.md   |  6 +++++-
 docs/src/cli/highlight.md  |  4 ++++
 docs/src/cli/parse.md      | 14 +++++++++++---
 docs/src/cli/playground.md |  8 ++++----
 docs/src/cli/query.md      | 12 ++++++++++++
 docs/src/cli/tags.md       |  4 ++++
 docs/src/cli/test.md       | 12 ++++++++++++
 docs/src/cli/version.md    |  8 ++++++++
 10 files changed, 75 insertions(+), 16 deletions(-)

diff --git a/crates/cli/src/main.rs b/crates/cli/src/main.rs
index d9f8c174..1c7fa957 100644
--- a/crates/cli/src/main.rs
+++ b/crates/cli/src/main.rs
@@ -261,15 +261,10 @@ struct Parse {
     #[arg(long)]
     pub open_log: bool,
     /// Deprecated: use --json-summary
-    #[arg(
-        long,
-        short = 'j',
-        conflicts_with = "json_summary",
-        conflicts_with = "stat"
-    )]
+    #[arg(long, conflicts_with = "json_summary", conflicts_with = "stat")]
     pub json: bool,
     /// Output parsing results in a JSON format
-    #[arg(long, conflicts_with = "json", conflicts_with = "stat")]
+    #[arg(long, short = 'j', conflicts_with = "json", conflicts_with = "stat")]
     pub json_summary: bool,
     /// The path to an alternative config.json file
     #[arg(long)]
@@ -348,7 +343,7 @@ struct Test {
     /// Show only the pass-fail overview tree
     #[arg(long)]
     pub overview_only: bool,
-    /// Output the test summary in a JSON output
+    /// Output the test summary in a JSON format
     #[arg(long)]
     pub json_summary: bool,
 }
diff --git a/docs/src/cli/fuzz.md b/docs/src/cli/fuzz.md
index 1f79bc00..7f97f9ba 100644
--- a/docs/src/cli/fuzz.md
+++ b/docs/src/cli/fuzz.md
@@ -17,6 +17,18 @@ A list of test names to skip fuzzing.
 
 The directory containing the parser. This is primarily useful in multi-language repositories.
 
+### `-p/--grammar-path`
+
+The path to the directory containing the grammar.
+
+### `--lib-path`
+
+The path to the parser's dynamic library. This is used instead of the cached or automatically generated dynamic library.
+
+### `--lang-name`
+
+If `--lib-path` is used, the name of the language used to extract the library's language function
+
 ### `--edits <EDITS>`
 
 The maximum number of edits to perform. The default is 3.
diff --git a/docs/src/cli/generate.md b/docs/src/cli/generate.md
index 32c8437a..c373b1e2 100644
--- a/docs/src/cli/generate.md
+++ b/docs/src/cli/generate.md
@@ -44,7 +44,7 @@ Print the overview of states from the given rule. This is useful for debugging a
 item sets for all given states in a given rule. To solely view state count numbers for rules, pass in `-` for the rule argument.
 To view the overview of states for every rule, pass in `*` for the rule argument.
 
-### `--json`
+### `--json-summary`
 
 Report conflicts in a JSON format.
 
@@ -54,3 +54,7 @@ The path to the JavaScript runtime executable to use when generating the parser.
 Note that you can also set this with `TREE_SITTER_JS_RUNTIME`. Starting from version 0.26.0, you can
 also pass in `native` to use the native QuickJS runtime that comes bundled with the CLI. This avoids
 the dependency on a JavaScript runtime entirely.
+
+### `--disable-optimization`
+
+Disable optimizations when generating the parser. Currently, this only affects the merging of compatible parse states.
diff --git a/docs/src/cli/highlight.md b/docs/src/cli/highlight.md
index 1378e0f6..82c9e25c 100644
--- a/docs/src/cli/highlight.md
+++ b/docs/src/cli/highlight.md
@@ -57,3 +57,7 @@ The path to an alternative configuration (`config.json`) file. See [the init-con
 ### `-n/--test-number <TEST_NUMBER>`
 
 Highlight the contents of a specific test.
+
+### `-r/--rebuild`
+
+Force a rebuild of the parser before running the fuzzer.
diff --git a/docs/src/cli/parse.md b/docs/src/cli/parse.md
index 9f76b550..178d97b5 100644
--- a/docs/src/cli/parse.md
+++ b/docs/src/cli/parse.md
@@ -1,8 +1,8 @@
 # `tree-sitter parse`
 
 The `parse` command parses source files using a Tree-sitter parser. You can pass any number of file paths and glob patterns
-to `tree-sitter parse`, and it will parse all the given files. The command will exit with a non-zero status code if any
-parse errors occurred.
+to `tree-sitter parse`, and it will parse all the given files. If no paths are provided, input will be parsed from stdin.
+The command will exit with a non-zero status code if any parse errors occurred.
 
 ```bash
 tree-sitter parse [OPTIONS] [PATHS]... # Aliases: p
@@ -18,6 +18,14 @@ The path to a file that contains paths to source files to parse.
 
 The path to the directory containing the grammar.
 
+### `-l/--lib-path`
+
+The path to the parser's dynamic library. This is used instead of the cached or automatically generated dynamic library.
+
+### `--lang-name`
+
+If `--lib-path` is used, the name of the language used to extract the library's language function
+
 ### `--scope <SCOPE>`
 
 The language scope to use for parsing. This is useful when the language is ambiguous.
@@ -81,7 +89,7 @@ in `UTF-16BE` or `UTF-16LE`. If no `BOM` is present, `UTF-8` is the default. One
 
 When using the `--debug-graph` option, open the log file in the default browser.
 
-### `-j/--json`
+### `-j/--json-summary`
 
 Output parsing results in a JSON format.
 
diff --git a/docs/src/cli/playground.md b/docs/src/cli/playground.md
index 0dbff469..7c2ef598 100644
--- a/docs/src/cli/playground.md
+++ b/docs/src/cli/playground.md
@@ -13,10 +13,6 @@ For this to work, you must have already built the parser as a Wasm module. This
 
 ## Options
 
-### `-e/--export <EXPORT_PATH>`
-
-Export static playground files to the specified directory instead of serving them.
-
 ### `-q/--quiet`
 
 Don't automatically open the playground in the default browser.
@@ -24,3 +20,7 @@ Don't automatically open the playground in the default browser.
 ### `--grammar-path <GRAMMAR_PATH>`
 
 The path to the directory containing the grammar and wasm files.
+
+### `-e/--export <EXPORT_PATH>`
+
+Export static playground files to the specified directory instead of serving them.
diff --git a/docs/src/cli/query.md b/docs/src/cli/query.md
index ed96aa51..395ca486 100644
--- a/docs/src/cli/query.md
+++ b/docs/src/cli/query.md
@@ -12,6 +12,14 @@ tree-sitter query [OPTIONS] <QUERY_PATH> [PATHS]... # Aliases: q
 
 The path to the directory containing the grammar.
 
+### `--lib-path`
+
+The path to the parser's dynamic library. This is used instead of the cached or automatically generated dynamic library.
+
+### `--lang-name`
+
+If `--lib-path` is used, the name of the language used to extract the library's language function
+
 ### `-t/--time`
 
 Print the time taken to execute the query on the file.
@@ -51,3 +59,7 @@ The path to an alternative configuration (`config.json`) file. See [the init-con
 ### `-n/--test-number <TEST_NUMBER>`
 
 Query the contents of a specific test.
+
+### `-r/--rebuild`
+
+Force a rebuild of the parser before executing the query.
diff --git a/docs/src/cli/tags.md b/docs/src/cli/tags.md
index 80ee1baa..a48fabb4 100644
--- a/docs/src/cli/tags.md
+++ b/docs/src/cli/tags.md
@@ -36,3 +36,7 @@ The path to an alternative configuration (`config.json`) file. See [the init-con
 ### `-n/--test-number <TEST_NUMBER>`
 
 Generate tags from the contents of a specific test.
+
+### `-r/--rebuild`
+
+Force a rebuild of the parser before running the tags.
diff --git a/docs/src/cli/test.md b/docs/src/cli/test.md
index c1724745..401bcd39 100644
--- a/docs/src/cli/test.md
+++ b/docs/src/cli/test.md
@@ -24,6 +24,14 @@ Only run tests from the given filename in the corpus.
 
 The path to the directory containing the grammar.
 
+### `--lib-path`
+
+The path to the parser's dynamic library. This is used instead of the cached or automatically generated dynamic library.
+
+### `--lang-name`
+
+If `--lib-path` is used, the name of the language used to extract the library's language function
+
 ### `-u/--update`
 
 Update the expected output of tests.
@@ -78,3 +86,7 @@ Force a rebuild of the parser before running tests.
 ### `--overview-only`
 
 Only show the overview of the test results, and not the diff.
+
+### `--json-summary`
+
+Output the test summary in a JSON format.
diff --git a/docs/src/cli/version.md b/docs/src/cli/version.md
index e8f7a840..ab699d2a 100644
--- a/docs/src/cli/version.md
+++ b/docs/src/cli/version.md
@@ -42,3 +42,11 @@ tree-sitter version
 ### `-p/--grammar-path <PATH>`
 
 The path to the directory containing the grammar.
+
+### `--bump`
+
+Automatically bump the version. Possible values are:
+
+- `patch`: Bump the patch version.
+- `minor`: Bump the minor version.
+- `major`: Bump the major version.