tree_haver 3.2.0 → 3.2.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 4086bd0349e2cfd205314110a7af3b8548530cc8d5f4328d84ecc38f840744f9
-  data.tar.gz: 01c27844a370a8235518002d6947226061931a127de6473b495d99ac4549cefd
+  metadata.gz: 3da36f96aa78d0995c76a3cbd6451889066b65d219414938e098ef9949df317f
+  data.tar.gz: 11e11da6c9f53e439d4226700c981466c3b47f0b9411d2e97a5211edade8d81d
 SHA512:
-  metadata.gz: 1a77445cd016d4cf0d5cb0cf28aee79e6a664578ac2da92babc663e3df483f024f1c17c434ef19d4941cf25dd6674aea68177d71c096b75e3d83315d4d0e222a
-  data.tar.gz: a53b817c9a24181d7b2b17810977f0978085c0603ca07b41f9189a221d1e3a7cd0b2e7751e53f4440883ea02e22c262de6b965ca9dedb4bf7bc6282ff29d57c3
+  metadata.gz: 1dce9daf70fc5573d579d699724601756db9758170fdb0e7be759ea9572a3d02fa491766786c708172e0f66c2473ae9e0da97fb20bddf7b185d93e285cc8bd3e
+  data.tar.gz: eaf3a3649233933b523a7f8e49831b7d5c7f00da268d805c7cbc043176424b5b4214da607bbe7e57e03dcd9072269dfedf3feba4383a828e6cb1abb89394b5c8

data/CHANGELOG.md

@@ -30,6 +30,85 @@ Please file a bug if you notice a violation of semantic versioning.
 
 ### Security
 
+## [3.2.1] - 2025-12-31
+
+- TAG: [v3.2.1][3.2.1t]
+- COVERAGE: 94.75% -- 2075/2190 lines in 22 files
+- BRANCH COVERAGE: 81.35% -- 733/901 branches in 22 files
+- 90.14% documented
+
+### Added
+
+- `TreeHaver::LibraryPathUtils` module for consistent path parsing across all backends
+  - `derive_symbol_from_path(path)` - derives tree-sitter symbol (e.g., `tree_sitter_toml`) from library path
+  - `derive_language_name_from_path(path)` - derives language name (e.g., `toml`) from library path
+  - `derive_language_name_from_symbol(symbol)` - strips `tree_sitter_` prefix from symbol
+  - Handles various naming conventions: `libtree-sitter-toml.so`, `libtree_sitter_toml.so`, `tree-sitter-toml.so`, `toml.so`
+- Isolated backend RSpec tags for running tests without loading conflicting backends
+  - `:ffi_backend_only` - runs FFI tests without triggering `mri_backend_available?` check
+  - `:mri_backend_only` - runs MRI tests without triggering `ffi_available?` check
+  - Uses `TreeHaver::Backends::BLOCKED_BY` to dynamically determine which availability checks to skip
+  - Enables `rake ffi_specs` to run FFI tests before MRI is loaded
+- `DependencyTags.ffi_backend_only_available?` - checks FFI availability without loading MRI
+- `DependencyTags.mri_backend_only_available?` - checks MRI availability without checking FFI
+
+### Changed
+
+- All backends now use shared `LibraryPathUtils` for path parsing
+  - MRI, Rust, FFI, and Java backends updated for consistency
+  - Ensures identical behavior across all tree-sitter backends
+- `TreeHaver::Language` class extracted to `lib/tree_haver/language.rb`
+  - No API changes, just file organization
+  - Loaded via autoload for lazy loading
+- `TreeHaver::Parser` class extracted to `lib/tree_haver/parser.rb`
+  - No API changes, just file organization
+  - Loaded via autoload for lazy loading
+- Backend availability exclusions in `dependency_tags.rb` are now dynamic
+  - Uses `TreeHaver::Backends::BLOCKED_BY` to skip availability checks for blocked backends
+  - When running with `--tag ffi_backend_only`, MRI availability is not checked
+  - Prevents MRI from being loaded before FFI tests can run
+- Rakefile `ffi_specs` task now uses `:ffi_backend_only` tag
+  - Ensures FFI tests run without loading MRI backend first
+
+### Fixed
+
+- Rakefile now uses correct RSpec tags for FFI isolation
+  - The `ffi_specs` task uses `:ffi_backend_only` to prevent MRI from loading
+  - The `remaining_specs` task excludes `:ffi_backend_only` tests
+  - Tags in Rakefile align with canonical tags from `dependency_tags.rb`
+- `TreeHaver::RSpec::DependencyTags.mri_backend_available?` now uses correct require path
+  - Was: `require "ruby_tree_sitter"` (wrong - causes LoadError)
+  - Now: `require "tree_sitter"` (correct - gem name is ruby_tree_sitter but require path is tree_sitter)
+  - This fix ensures the MRI backend is correctly detected as available in CI environments
+- `TreeHaver::Backends::MRI::Language.from_library` now properly derives symbol from path
+  - Previously, calling `from_library(path)` without `symbol:` would fail because `language_name` was nil
+  - Now delegates to private `from_path` after deriving symbol, ensuring proper language name derivation
+  - `from_path` is now private (but still accessible via `send` for testing if needed)
+  - Extracts language name from paths like `/usr/lib/libtree-sitter-toml.so` → `tree_sitter_toml`
+  - Handles both dash and underscore separators in filenames
+  - Handles simple language names like `toml.so` → `tree_sitter_toml`
+- `TreeHaver::Backends::MRI::Parser#language=` now unwraps `TreeHaver::Backends::MRI::Language` wrappers
+  - Accepts both raw `TreeSitter::Language` and wrapped `TreeHaver::Backends::MRI::Language`
+- `TreeHaver::GrammarFinder.tree_sitter_runtime_usable?` no longer references `FFI::NotFoundError` directly
+  - Prevents `NameError` when FFI gem is not loaded
+- `TreeHaver::Parser#initialize` no longer references `FFI::NotFoundError` directly in rescue clause
+  - Uses `defined?(::FFI::NotFoundError)` check to safely handle FFI errors when FFI is loaded
+  - Prevents `NameError: uninitialized constant TreeHaver::Parser::FFI` when FFI gem is not available
+  - Extracted error handling to `handle_parser_creation_failure` private method for clarity
+- RSpec `dependency_tags.rb` now correctly detects `--tag` options during configuration
+  - RSpec's `config.inclusion_filter.rules` is empty during configuration phase
+  - Now parses `ARGV` directly to detect `--tag ffi_backend_only` and similar tags
+  - Skips grammar availability checks (which load MRI) when running isolated backend tests
+  - Skips full dependency summary in `before(:suite)` when backends are blocked
+- `TreeHaver::Backends::FFI.reset!` now uses consistent pattern with other backends
+  - Was using `@ffi_gem_available` with `defined?()` check, which returned truthy after `reset!` set it to nil
+  - Now uses `@load_attempted` / `@loaded` pattern like MRI, Rust, Citrus, Prism, Psych, etc.
+  - This fixes FFI tests failing after the first test when `reset!` was called in `after` blocks
+- `TreeHaver::Language.method_missing` no longer references `FFI::NotFoundError` directly in rescue clause
+  - Uses `defined?(::FFI::NotFoundError)` check to safely handle FFI errors when FFI is loaded
+  - Prevents `NameError` when FFI gem is not available but tree-sitter backends are used
+  - Extracted Citrus fallback logic to `handle_tree_sitter_load_failure` private method
+
 ## [3.2.0] - 2025-12-30
 
 - TAG: [v3.2.0][3.2.0t]
@@ -580,7 +659,9 @@ Despite the major version bump to 3.0.0 (following semver due to the breaking `L
 
 - Initial release
 
-[Unreleased]: https://github.com/kettle-rb/tree_haver/compare/v3.2.0...HEAD
+[Unreleased]: https://github.com/kettle-rb/tree_haver/compare/v3.2.1...HEAD
+[3.2.1]: https://github.com/kettle-rb/tree_haver/compare/v3.2.0...v3.2.1
+[3.2.1t]: https://github.com/kettle-rb/tree_haver/releases/tag/v3.2.1
 [3.2.0]: https://github.com/kettle-rb/tree_haver/compare/v3.1.2...v3.2.0
 [3.2.0t]: https://github.com/kettle-rb/tree_haver/releases/tag/v3.2.0
 [3.1.2]: https://github.com/kettle-rb/tree_haver/compare/v3.1.1...v3.1.2

data/README.md

@@ -1977,7 +1977,7 @@ Thanks for RTFM. ☺️
 [📌gitmoji]: https://gitmoji.dev
 [📌gitmoji-img]: https://img.shields.io/badge/gitmoji_commits-%20%F0%9F%98%9C%20%F0%9F%98%8D-34495e.svg?style=flat-square
 [🧮kloc]: https://www.youtube.com/watch?v=dQw4w9WgXcQ
-[🧮kloc-img]: https://img.shields.io/badge/KLOC-2.496-FFDD67.svg?style=for-the-badge&logo=YouTube&logoColor=blue
+[🧮kloc-img]: https://img.shields.io/badge/KLOC-2.190-FFDD67.svg?style=for-the-badge&logo=YouTube&logoColor=blue
 [🔐security]: SECURITY.md
 [🔐security-img]: https://img.shields.io/badge/security-policy-259D6C.svg?style=flat
 [📄copyright-notice-explainer]: https://opensource.stackexchange.com/questions/5778/why-do-licenses-such-as-the-mit-license-specify-a-single-year

data/lib/tree_haver/backends/ffi.rb

@@ -56,9 +56,10 @@ module TreeHaver
         # @note Returns false on TruffleRuby because TruffleRuby's FFI doesn't support
         #   STRUCT_BY_VALUE return types (used by ts_tree_root_node, ts_node_child, etc.)
         def ffi_gem_available?
-          return @ffi_gem_available if defined?(@ffi_gem_available)
+          return @loaded if @load_attempted
 
-          @ffi_gem_available = begin
+          @load_attempted = true
+          @loaded = begin
             # TruffleRuby's FFI doesn't support STRUCT_BY_VALUE return types
             # which tree-sitter uses extensively (ts_tree_root_node, ts_node_child, etc.)
             return false if RUBY_ENGINE == "truffleruby"
@@ -75,7 +76,8 @@ module TreeHaver
         # @return [void]
         # @api private
         def reset!
-          @ffi_gem_available = nil
+          @load_attempted = false
+          @loaded = false
         end
 
         # Get capabilities supported by this backend
@@ -395,14 +397,14 @@ module TreeHaver
             end
 
             requested = symbol || ENV["TREE_SITTER_LANG_SYMBOL"]
-            base = File.basename(path)
-            guessed_lang = base.sub(/^libtree[-_]sitter[-_]/, "").sub(/\.(so(\.\d+)?)|\.dylib|\.dll\z/, "")
+            # Use shared utility for consistent symbol derivation across backends
+            guessed_symbol = LibraryPathUtils.derive_symbol_from_path(path)
             # If an override was provided (arg or ENV), treat it as strict and do not fall back.
             # Only when no override is provided do we attempt guessed and default candidates.
             candidates = if requested && !requested.to_s.empty?
               [requested]
             else
-              [(guessed_lang.empty? ? nil : "tree_sitter_#{guessed_lang}"), "tree_sitter_toml"].compact
+              [guessed_symbol, "tree_sitter_toml"].compact.uniq
             end
 
             func = nil

data/lib/tree_haver/backends/java.rb

@@ -316,9 +316,11 @@ module TreeHaver
           def from_library(path, symbol: nil, name: nil)
             raise TreeHaver::NotAvailable, "Java backend not available" unless Java.available?
 
-            # Derive symbol from name or path if not provided
-            base_name = File.basename(path, ".*").sub(/^lib/, "")
-            sym = symbol || "tree_sitter_#{name || base_name.sub(/^tree-sitter-/, "")}"
+            # Use shared utility for consistent symbol derivation across backends
+            # If symbol not provided, derive from name or path
+            sym = symbol || LibraryPathUtils.derive_symbol_from_path(path)
+            # If name was provided, use it to override the derived symbol
+            sym = "tree_sitter_#{name}" if name && !symbol
 
             begin
               arena = ::Java::JavaLangForeign::Arena.global

data/lib/tree_haver/backends/mri.rb

@@ -166,6 +166,21 @@ module TreeHaver
         #   lang = TreeHaver::Backends::MRI::Language.from_library("/path/to/lib.so", symbol: "tree_sitter_json")
         class << self
           def from_library(path, symbol: nil, name: nil)
+            # Derive symbol from path if not provided using shared utility
+            symbol ||= LibraryPathUtils.derive_symbol_from_path(path)
+            from_path(path, symbol: symbol, name: name)
+          end
+
+          private
+
+          # Load a language from a shared library path (internal implementation)
+          #
+          # @param path [String] absolute path to the language shared library
+          # @param symbol [String] the exported symbol name (e.g., "tree_sitter_json")
+          # @param name [String, nil] optional language name
+          # @return [Language] wrapped language handle
+          # @api private
+          def from_path(path, symbol: nil, name: nil)
             raise TreeHaver::NotAvailable, "ruby_tree_sitter not available" unless MRI.available?
 
             # ruby_tree_sitter's TreeSitter::Language.load takes (language_name, path_to_so)
@@ -173,8 +188,8 @@ module TreeHaver
             # NOT the full symbol name (e.g., NOT "tree_sitter_toml")
             # and path_to_so is the full path to the .so file
             #
-            # If name is not provided, derive it from symbol by stripping "tree_sitter_" prefix
-            language_name = name || symbol&.sub(/\Atree_sitter_/, "")
+            # If name is not provided, derive it from symbol using shared utility
+            language_name = name || LibraryPathUtils.derive_language_name_from_symbol(symbol)
             ts_lang = ::TreeSitter::Language.load(language_name, path)
             new(ts_lang, path: path, symbol: symbol)
           rescue NameError => e
@@ -190,16 +205,6 @@ module TreeHaver
               raise # Re-raise if it's not a TreeSitter error
             end
           end
-
-          # Load a language from a shared library path (legacy method)
-          #
-          # @param path [String] absolute path to the language shared library
-          # @param symbol [String] the exported symbol name (e.g., "tree_sitter_json")
-          # @return [Language] wrapped language handle
-          # @deprecated Use {from_library} instead
-          def from_path(path, symbol: nil)
-            from_library(path, symbol: symbol)
-          end
         end
       end
 
@@ -229,19 +234,17 @@ module TreeHaver
 
         # Set the language for this parser
         #
-        # Note: TreeHaver::Parser unwraps language objects before calling this method.
-        # This backend receives raw ::TreeSitter::Language objects, never wrapped ones.
-        #
-        # @param lang [::TreeSitter::Language] the language to use (already unwrapped)
-        # @return [::TreeSitter::Language] the language that was set
+        # @param lang [::TreeSitter::Language, TreeHaver::Backends::MRI::Language] the language to use
+        # @return [::TreeSitter::Language, TreeHaver::Backends::MRI::Language] the language that was set
         # @raise [TreeHaver::NotAvailable] if setting language fails
         def language=(lang)
-          # lang is already unwrapped by TreeHaver::Parser, use directly
-          @parser.language = lang
+          # Unwrap if it's a TreeHaver wrapper
+          inner_lang = lang.respond_to?(:inner_language) ? lang.inner_language : lang
+          @parser.language = inner_lang
           # Verify it was set
           raise TreeHaver::NotAvailable, "Language not set correctly" if @parser.language.nil?
 
-          # Return the language object
+          # Return the original language object (wrapped or unwrapped)
           lang
         rescue Exception => e # rubocop:disable Lint/RescueException
           # TreeSitter errors inherit from Exception (not StandardError) in ruby_tree_sitter v2+

data/lib/tree_haver/backends/rust.rb

@@ -149,16 +149,15 @@ module TreeHaver
 
             # tree_stump uses TreeStump.register_lang(name, path) to register languages
             # The name is used to derive the symbol automatically (tree_sitter_<name>)
-            lang_name = name || File.basename(path, ".*").sub(/^libtree-sitter-/, "")
+            # Use shared utility for consistent path parsing across backends
+            lang_name = name || LibraryPathUtils.derive_language_name_from_path(path)
             ::TreeStump.register_lang(lang_name, path)
             new(lang_name, path: path)
           rescue RuntimeError => e
             raise TreeHaver::NotAvailable, "Failed to load language from #{path}: #{e.message}"
           end
 
-          # Alias for compatibility
-          #
-          # @see from_library
+          # Backward-compatible alias for from_library
           alias_method :from_path, :from_library
         end
       end

data/lib/tree_haver/grammar_finder.rb

@@ -270,7 +270,10 @@ module TreeHaver
           # Try to instantiate a parser - this will fail if runtime isn't available
           mod::Parser.new
           true
-        rescue NoMethodError, FFI::NotFoundError, LoadError, NotAvailable => _e
+        rescue NoMethodError, LoadError, NotAvailable => _e
+          false
+        rescue StandardError => _e
+          # Catch FFI::NotFoundError and other errors when FFI is loaded
           false
         end
       end

data/lib/tree_haver/language.rb

@@ -0,0 +1,255 @@
+# frozen_string_literal: true
+
+module TreeHaver
+  # Represents a language grammar for parsing source code
+  #
+  # Language is the entry point for loading and using grammars. It provides
+  # a unified interface that works across all backends (MRI, Rust, FFI, Java, Citrus).
+  #
+  # For tree-sitter backends, languages are loaded from shared library files (.so/.dylib/.dll).
+  # For pure-Ruby backends (Citrus, Prism, Psych), languages are built-in or provided by gems.
+  #
+  # == Loading Languages
+  #
+  # The primary way to load a language is via registration:
+  #
+  #   TreeHaver.register_language(:toml, path: "/path/to/libtree-sitter-toml.so")
+  #   language = TreeHaver::Language.toml
+  #
+  # For explicit loading without registration:
+  #
+  #   language = TreeHaver::Language.from_library(
+  #     "/path/to/libtree-sitter-toml.so",
+  #     symbol: "tree_sitter_toml"
+  #   )
+  #
+  # For ruby_tree_sitter compatibility:
+  #
+  #   language = TreeHaver::Language.load("toml", "/path/to/libtree-sitter-toml.so")
+  #
+  # @example Register and load a language
+  #   TreeHaver.register_language(:toml, path: "/path/to/grammar.so")
+  #   language = TreeHaver::Language.toml
+  class Language
+    class << self
+      # Load a language grammar from a shared library (ruby_tree_sitter compatibility)
+      #
+      # This method provides API compatibility with ruby_tree_sitter which uses
+      # `Language.load(name, path)`.
+      #
+      # @param name [String] the language name (e.g., "toml")
+      # @param path [String] absolute path to the language shared library
+      # @param validate [Boolean] if true, validates the path for safety (default: true)
+      # @return [Language] loaded language handle
+      # @raise [NotAvailable] if the library cannot be loaded
+      # @raise [ArgumentError] if the path fails security validation
+      # @example
+      #   language = TreeHaver::Language.load("toml", "/usr/local/lib/libtree-sitter-toml.so")
+      def load(name, path, validate: true)
+        from_library(path, symbol: "tree_sitter_#{name}", name: name, validate: validate)
+      end
+
+      # Load a language grammar from a shared library
+      #
+      # The library must export a function that returns a pointer to a TSLanguage struct.
+      # By default, TreeHaver looks for a symbol named "tree_sitter_<name>".
+      #
+      # == Security
+      #
+      # By default, paths are validated using {PathValidator} to prevent path traversal
+      # and other attacks. Set `validate: false` to skip validation (not recommended
+      # unless you've already validated the path).
+      #
+      # @param path [String] absolute path to the language shared library (.so/.dylib/.dll)
+      # @param symbol [String, nil] name of the exported function (defaults to auto-detection)
+      # @param name [String, nil] logical name for the language (used in caching)
+      # @param validate [Boolean] if true, validates path and symbol for safety (default: true)
+      # @param backend [Symbol, String, nil] optional backend to use (overrides context/global)
+      # @return [Language] loaded language handle
+      # @raise [NotAvailable] if the library cannot be loaded or the symbol is not found
+      # @raise [ArgumentError] if path or symbol fails security validation
+      # @example
+      #   language = TreeHaver::Language.from_library(
+      #     "/usr/local/lib/libtree-sitter-toml.so",
+      #     symbol: "tree_sitter_toml",
+      #     name: "toml"
+      #   )
+      # @example With explicit backend
+      #   language = TreeHaver::Language.from_library(
+      #     "/usr/local/lib/libtree-sitter-toml.so",
+      #     symbol: "tree_sitter_toml",
+      #     backend: :ffi
+      #   )
+      def from_library(path, symbol: nil, name: nil, validate: true, backend: nil)
+        if validate
+          unless PathValidator.safe_library_path?(path)
+            errors = PathValidator.validation_errors(path)
+            raise ArgumentError, "Unsafe library path: #{path.inspect}. Errors: #{errors.join("; ")}"
+          end
+
+          if symbol && !PathValidator.safe_symbol_name?(symbol)
+            raise ArgumentError, "Unsafe symbol name: #{symbol.inspect}. " \
+              "Symbol names must be valid C identifiers."
+          end
+        end
+
+        # from_library only works with tree-sitter backends that support .so files
+        # Pure Ruby backends (Citrus, Prism, Psych, Commonmarker, Markly) don't support from_library
+        mod = TreeHaver.resolve_native_backend_module(backend)
+
+        if mod.nil?
+          if backend
+            raise NotAvailable, "Requested backend #{backend.inspect} is not available or does not support shared libraries"
+          else
+            raise NotAvailable,
+              "No native tree-sitter backend is available for loading shared libraries. " \
+                "Available native backends (MRI, Rust, FFI, Java) require platform-specific setup. " \
+                "For pure-Ruby parsing, use backend-specific Language classes directly (e.g., Prism, Psych, Citrus)."
+          end
+        end
+
+        # Backend must implement .from_library; fallback to .from_path for older impls
+        # Include effective backend AND ENV vars in cache key since they affect loading
+        effective_b = TreeHaver.resolve_effective_backend(backend)
+        key = [effective_b, path, symbol, name, ENV["TREE_SITTER_LANG_SYMBOL"]]
+        LanguageRegistry.fetch(key) do
+          if mod::Language.respond_to?(:from_library)
+            mod::Language.from_library(path, symbol: symbol, name: name)
+          else
+            mod::Language.from_path(path)
+          end
+        end
+      end
+      # Alias for {from_library}
+      # @see from_library
+      alias_method :from_path, :from_library
+
+      # Dynamic helper to load a registered language by name
+      #
+      # After registering a language with {TreeHaver.register_language},
+      # you can load it using a method call. The appropriate backend will be
+      # used based on registration and current backend.
+      #
+      # @example With tree-sitter
+      #   TreeHaver.register_language(:toml, path: "/path/to/libtree-sitter-toml.so")
+      #   language = TreeHaver::Language.toml
+      #
+      # @example With both backends
+      #   TreeHaver.register_language(:toml,
+      #     path: "/path/to/libtree-sitter-toml.so", symbol: "tree_sitter_toml")
+      #   TreeHaver.register_language(:toml,
+      #     grammar_module: TomlRB::Document)
+      #   language = TreeHaver::Language.toml  # Uses appropriate grammar for active backend
+      #
+      # @param method_name [Symbol] the registered language name
+      # @param args [Array] positional arguments
+      # @param kwargs [Hash] keyword arguments
+      # @return [Language] loaded language handle
+      # @raise [NoMethodError] if the language name is not registered
+      def method_missing(method_name, *args, **kwargs, &block)
+        # Resolve only if the language name was registered
+        all_backends = TreeHaver.registered_language(method_name)
+        return super unless all_backends
+
+        # Check current backend
+        current_backend = TreeHaver.backend_module
+
+        # Determine which backend type to use
+        backend_type = if current_backend == Backends::Citrus
+          :citrus
+        else
+          :tree_sitter  # MRI, Rust, FFI, Java all use tree-sitter
+        end
+
+        # Get backend-specific registration
+        reg = all_backends[backend_type]
+
+        # If Citrus backend is active
+        if backend_type == :citrus
+          if reg && reg[:grammar_module]
+            return Backends::Citrus::Language.new(reg[:grammar_module])
+          end
+
+          # Fall back to error if no Citrus grammar registered
+          raise NotAvailable,
+            "Citrus backend is active but no Citrus grammar registered for :#{method_name}. " \
+              "Either register a Citrus grammar or use a tree-sitter backend. " \
+              "Registered backends: #{all_backends.keys.inspect}"
+        end
+
+        # For tree-sitter backends, try to load from path
+        # If that fails, fall back to Citrus if available
+        if reg && reg[:path]
+          path = kwargs[:path] || args.first || reg[:path]
+          # Symbol priority: kwargs override > registration > derive from method_name
+          symbol = if kwargs.key?(:symbol)
+            kwargs[:symbol]
+          elsif reg[:symbol]
+            reg[:symbol]
+          else
+            "tree_sitter_#{method_name}"
+          end
+          # Name priority: kwargs override > derive from symbol (strip tree_sitter_ prefix)
+          # Using symbol-derived name ensures ruby_tree_sitter gets the correct language name
+          # e.g., "toml" not "toml_both" when symbol is "tree_sitter_toml"
+          name = kwargs[:name] || symbol&.sub(/\Atree_sitter_/, "")
+
+          begin
+            return from_library(path, symbol: symbol, name: name)
+          rescue NotAvailable, ArgumentError, LoadError => e
+            # Tree-sitter failed to load - check for Citrus fallback
+            handle_tree_sitter_load_failure(e, all_backends)
+          rescue => e
+            # Also catch FFI::NotFoundError if FFI is loaded (can't reference directly as FFI may not exist)
+            if defined?(::FFI::NotFoundError) && e.is_a?(::FFI::NotFoundError)
+              handle_tree_sitter_load_failure(e, all_backends)
+            else
+              raise
+            end
+          end
+        end
+
+        # No tree-sitter path registered - check for Citrus fallback
+        # This enables auto-fallback when tree-sitter grammar is not installed
+        # but a Citrus grammar (pure Ruby) is available
+        citrus_reg = all_backends[:citrus]
+        if citrus_reg && citrus_reg[:grammar_module]
+          return Backends::Citrus::Language.new(citrus_reg[:grammar_module])
+        end
+
+        # No appropriate registration found
+        raise ArgumentError,
+          "No grammar registered for :#{method_name} compatible with #{backend_type} backend. " \
+            "Registered backends: #{all_backends.keys.inspect}"
+      end
+
+      # @api private
+      def respond_to_missing?(method_name, include_private = false)
+        !!TreeHaver.registered_language(method_name) || super
+      end
+
+      private
+
+      # Handle tree-sitter load failure with optional Citrus fallback
+      #
+      # This handles cases where:
+      # - The .so file doesn't exist or can't be loaded (NotAvailable, LoadError)
+      # - FFI can't find required symbols like ts_parser_new (FFI::NotFoundError)
+      # - Invalid arguments were provided (ArgumentError)
+      #
+      # @param error [Exception] the original error
+      # @param all_backends [Hash] all registered backends for the language
+      # @return [Backends::Citrus::Language] if Citrus fallback available
+      # @raise [Exception] re-raises original error if no fallback
+      # @api private
+      def handle_tree_sitter_load_failure(error, all_backends)
+        citrus_reg = all_backends[:citrus]
+        if citrus_reg && citrus_reg[:grammar_module]
+          return Backends::Citrus::Language.new(citrus_reg[:grammar_module])
+        end
+        # No Citrus fallback available, re-raise the original error
+        raise error
+      end
+    end
+  end
+end

data/lib/tree_haver/library_path_utils.rb

@@ -0,0 +1,80 @@
+# frozen_string_literal: true
+
+module TreeHaver
+  # Utility methods for deriving tree-sitter symbol and language names from library paths
+  #
+  # This module provides consistent path parsing across all backends that load
+  # tree-sitter grammar libraries from shared object files (.so/.dylib/.dll).
+  #
+  # @example
+  #   TreeHaver::LibraryPathUtils.derive_symbol_from_path("/usr/lib/libtree-sitter-toml.so")
+  #   # => "tree_sitter_toml"
+  #
+  #   TreeHaver::LibraryPathUtils.derive_language_name_from_path("/usr/lib/libtree-sitter-toml.so")
+  #   # => "toml"
+  module LibraryPathUtils
+    module_function
+
+    # Derive the tree-sitter symbol name from a library path
+    #
+    # Symbol names are the exported C function names (e.g., "tree_sitter_toml")
+    # that return a pointer to the TSLanguage struct.
+    #
+    # Handles various naming conventions:
+    # - libtree-sitter-toml.so → tree_sitter_toml
+    # - libtree_sitter_toml.so → tree_sitter_toml
+    # - tree-sitter-toml.so → tree_sitter_toml
+    # - tree_sitter_toml.so → tree_sitter_toml
+    # - toml.so → tree_sitter_toml (assumes simple language name)
+    #
+    # @param path [String, nil] path like "/usr/lib/libtree-sitter-toml.so"
+    # @return [String, nil] symbol like "tree_sitter_toml", or nil if path is nil
+    def derive_symbol_from_path(path)
+      return unless path
+
+      # Extract filename without extension: "libtree-sitter-toml" or "toml"
+      filename = File.basename(path, ".*")
+
+      # Handle multi-part extensions like .so.0.24
+      filename = filename.sub(/\.so(\.\d+)*\z/, "")
+
+      # Match patterns and normalize to tree_sitter_<lang>
+      case filename
+      when /\Alib[-_]?tree[-_]sitter[-_](.+)\z/
+        "tree_sitter_#{Regexp.last_match(1).tr("-", "_")}"
+      when /\Atree[-_]sitter[-_](.+)\z/
+        "tree_sitter_#{Regexp.last_match(1).tr("-", "_")}"
+      else
+        # Assume filename is just the language name (e.g., "toml.so" -> "tree_sitter_toml")
+        # Also strip "lib" prefix if present (e.g., "libtoml.so" -> "tree_sitter_toml")
+        lang = filename.sub(/\Alib/, "").tr("-", "_")
+        "tree_sitter_#{lang}"
+      end
+    end
+
+    # Derive the language name from a library path
+    #
+    # Language names are the short identifiers (e.g., "toml", "json", "ruby")
+    # used by some backends (like tree_stump/Rust) to register grammars.
+    #
+    # @param path [String, nil] path like "/usr/lib/libtree-sitter-toml.so"
+    # @return [String, nil] language name like "toml", or nil if path is nil
+    def derive_language_name_from_path(path)
+      symbol = derive_symbol_from_path(path)
+      return unless symbol
+
+      # Strip the "tree_sitter_" prefix to get the language name
+      symbol.sub(/\Atree_sitter_/, "")
+    end
+
+    # Derive language name from a symbol
+    #
+    # @param symbol [String, nil] symbol like "tree_sitter_toml"
+    # @return [String, nil] language name like "toml", or nil if symbol is nil
+    def derive_language_name_from_symbol(symbol)
+      return unless symbol
+
+      symbol.sub(/\Atree_sitter_/, "")
+    end
+  end
+end