tree_haver 3.2.2 → 3.2.4

data/lib/tree_haver.rb

@@ -16,7 +16,7 @@ require_relative "tree_haver/version"
 #
 # == Backends
 #
-# Supports 10 backends:
+# Supports 9 backends:
 # - Tree-sitter: MRI (C), Rust, FFI, Java
 # - Native parsers: Prism (Ruby), Psych (YAML), Commonmarker (Markdown), Markly (GFM)
 # - Pure Ruby: Citrus (portable fallback)
@@ -108,6 +108,7 @@ module TreeHaver
   # Autoload internal modules
   autoload :LibraryPathUtils, File.join(__dir__, "tree_haver", "library_path_utils")
   autoload :LanguageRegistry, File.join(__dir__, "tree_haver", "language_registry")
+  autoload :BackendAPI, File.join(__dir__, "tree_haver", "backend_api")
 
   # Base error class for TreeHaver exceptions
   # @see https://github.com/Faveod/ruby-tree-sitter/pull/83 for inherit from Exception reasoning
@@ -179,6 +180,9 @@ module TreeHaver
   # - {Backends::Java} - Uses JRuby's Java integration
   # - {Backends::Citrus} - Uses Citrus PEG parser (pure Ruby, portable)
   # - {Backends::Prism} - Uses Ruby's built-in Prism parser (Ruby-only, stdlib in 3.4+)
+  # - {Backends::Psych} - Uses Ruby's built-in Psych parser (YAML-only, stdlib)
+  # - {Backends::Commonmarker} - Uses commonmarker gem (Markdown)
+  # - {Backends::Markly} - Uses markly gem (Markdown/GFM)
   module Backends
     autoload :MRI, File.join(__dir__, "tree_haver", "backends", "mri")
     autoload :Rust, File.join(__dir__, "tree_haver", "backends", "rust")
@@ -208,6 +212,17 @@ module TreeHaver
       commonmarker: [], # Commonmarker has no conflicts with other backends
       markly: [],       # Markly has no conflicts with other backends
     }.freeze
+
+    # Pure Ruby backends that parse specific languages
+    # These are language-specific and register themselves via LanguageRegistry
+    #
+    # @return [Hash{Symbol => Hash}] Maps backend name to language and module info
+    PURE_RUBY_BACKENDS = {
+      prism: {language: :ruby, module_name: "Prism"},
+      psych: {language: :yaml, module_name: "Psych"},
+      commonmarker: {language: :markdown, module_name: "Commonmarker"},
+      markly: {language: :markdown, module_name: "Markly"},
+    }.freeze
   end
 
   # Security utilities for validating paths before loading shared libraries
@@ -266,6 +281,11 @@ module TreeHaver
   # Parser class for parsing source code into syntax trees
   autoload :Parser, File.join(__dir__, "tree_haver", "parser")
 
+  # Native tree-sitter backends that support loading shared libraries (.so files)
+  # These backends wrap the tree-sitter C library via various bindings.
+  # Pure Ruby backends (Citrus, Prism, Psych, Commonmarker, Markly) are excluded.
+  NATIVE_BACKENDS = %i[mri rust ffi java].freeze
+
   # Get the current backend selection
   #
   # @return [Symbol] one of :auto, :mri, :rust, :ffi, :java, or :citrus
@@ -345,18 +365,92 @@ module TreeHaver
     # @example
     #   TreeHaver.backend  # => :auto
     def backend
-      @backend ||= case (ENV["TREE_HAVER_BACKEND"] || :auto).to_s # rubocop:disable ThreadSafety/ClassInstanceVariable
-      when "mri" then :mri
-      when "rust" then :rust
-      when "ffi" then :ffi
-      when "java" then :java
-      when "citrus" then :citrus
-      when "prism" then :prism
-      when "psych" then :psych
-      when "commonmarker" then :commonmarker
-      when "markly" then :markly
-      else :auto
+      return @backend if defined?(@backend) && @backend # rubocop:disable ThreadSafety/ClassInstanceVariable
+
+      @backend = parse_single_backend_env # rubocop:disable ThreadSafety/ClassInstanceVariable
+    end
+
+    # Valid native backend names (require native extensions)
+    VALID_NATIVE_BACKENDS = %w[mri rust ffi java].freeze
+
+    # Valid pure Ruby backend names (no native extensions)
+    VALID_RUBY_BACKENDS = %w[citrus prism psych commonmarker markly].freeze
+
+    # All valid backend names
+    VALID_BACKENDS = (VALID_NATIVE_BACKENDS + VALID_RUBY_BACKENDS + %w[auto none]).freeze
+
+    # Get allowed native backends from TREE_HAVER_NATIVE_BACKEND environment variable
+    #
+    # Supports comma-separated values like "mri,ffi".
+    # Special values:
+    # - "auto" or empty/unset: automatically select from available native backends
+    # - "none": no native backends allowed (pure Ruby only)
+    #
+    # @return [Array<Symbol>] list of allowed native backend symbols, or [:auto] or [:none]
+    # @example Allow only MRI and FFI
+    #   # TREE_HAVER_NATIVE_BACKEND=mri,ffi
+    #   TreeHaver.allowed_native_backends  # => [:mri, :ffi]
+    # @example Auto-select native backends (default)
+    #   # TREE_HAVER_NATIVE_BACKEND not set, empty, or "auto"
+    #   TreeHaver.allowed_native_backends  # => [:auto]
+    # @example Disable all native backends
+    #   # TREE_HAVER_NATIVE_BACKEND=none
+    #   TreeHaver.allowed_native_backends  # => [:none]
+    def allowed_native_backends
+      @allowed_native_backends ||= parse_backend_list_env("TREE_HAVER_NATIVE_BACKEND", VALID_NATIVE_BACKENDS) # rubocop:disable ThreadSafety/ClassInstanceVariable
+    end
+
+    # Get allowed Ruby backends from TREE_HAVER_RUBY_BACKEND environment variable
+    #
+    # Supports comma-separated values like "citrus,prism".
+    # Special values:
+    # - "auto" or empty/unset: automatically select from available Ruby backends
+    # - "none": no Ruby backends allowed (native only)
+    #
+    # @return [Array<Symbol>] list of allowed Ruby backend symbols, or [:auto] or [:none]
+    # @example Allow only Citrus
+    #   # TREE_HAVER_RUBY_BACKEND=citrus
+    #   TreeHaver.allowed_ruby_backends  # => [:citrus]
+    # @example Auto-select Ruby backends (default)
+    #   # TREE_HAVER_RUBY_BACKEND not set, empty, or "auto"
+    #   TreeHaver.allowed_ruby_backends  # => [:auto]
+    def allowed_ruby_backends
+      @allowed_ruby_backends ||= parse_backend_list_env("TREE_HAVER_RUBY_BACKEND", VALID_RUBY_BACKENDS) # rubocop:disable ThreadSafety/ClassInstanceVariable
+    end
+
+    # Check if a specific backend is allowed based on environment variables
+    #
+    # Checks TREE_HAVER_NATIVE_BACKEND for native backends and
+    # TREE_HAVER_RUBY_BACKEND for pure Ruby backends.
+    #
+    # @param backend_name [Symbol, String] the backend to check
+    # @return [Boolean] true if the backend is allowed
+    # @example
+    #   # TREE_HAVER_NATIVE_BACKEND=mri
+    #   TreeHaver.backend_allowed?(:mri)    # => true
+    #   TreeHaver.backend_allowed?(:ffi)    # => false
+    #   TreeHaver.backend_allowed?(:citrus) # => true (Ruby backends use separate env var)
+    def backend_allowed?(backend_name)
+      backend_sym = backend_name.to_sym
+
+      # Check if it's a native backend
+      if VALID_NATIVE_BACKENDS.include?(backend_sym.to_s)
+        allowed = allowed_native_backends
+        return true if allowed == [:auto]
+        return false if allowed == [:none]
+        return allowed.include?(backend_sym)
+      end
+
+      # Check if it's a Ruby backend
+      if VALID_RUBY_BACKENDS.include?(backend_sym.to_s)
+        allowed = allowed_ruby_backends
+        return true if allowed == [:auto]
+        return false if allowed == [:none]
+        return allowed.include?(backend_sym)
       end
+
+      # Unknown backend or :auto - allow
+      true
     end
 
     # Set the backend to use
@@ -383,6 +477,101 @@ module TreeHaver
     #   TreeHaver.reset_backend!(to: :ffi)
     def reset_backend!(to: :auto)
       @backend = to&.to_sym # rubocop:disable ThreadSafety/ClassInstanceVariable
+      @allowed_native_backends = nil # rubocop:disable ThreadSafety/ClassInstanceVariable
+      @allowed_ruby_backends = nil # rubocop:disable ThreadSafety/ClassInstanceVariable
+    end
+
+    # Register built-in pure Ruby backends in the LanguageRegistry
+    #
+    # This registers Prism, Psych, Commonmarker, and Markly using the same
+    # registration API that external backends use. This ensures consistent
+    # behavior whether a backend is built-in or provided by an external gem.
+    #
+    # Called automatically when TreeHaver is first used, but can be called
+    # manually in tests or when reset! has cleared the registry.
+    #
+    # @return [void]
+    # @example Manual registration (usually not needed)
+    #   TreeHaver.register_builtin_backends!
+    def register_builtin_backends!
+      Backends::PURE_RUBY_BACKENDS.each do |backend_type, info|
+        language = info[:language]
+        module_name = info[:module_name]
+
+        # Get the backend module
+        backend_mod = Backends.const_get(module_name)
+        next unless backend_mod
+
+        # Register if available (lazy check - doesn't require the gem yet)
+        LanguageRegistry.register(
+          language,
+          backend_type,
+          backend_module: backend_mod,
+          gem_name: module_name.downcase,
+        )
+      end
+    end
+
+    # Check if built-in backends have been registered
+    #
+    # @return [Boolean]
+    # @api private
+    def builtin_backends_registered?
+      @builtin_backends_registered ||= false # rubocop:disable ThreadSafety/ClassInstanceVariable
+    end
+
+    # Ensure built-in backends are registered (idempotent)
+    #
+    # @return [void]
+    # @api private
+    def ensure_builtin_backends_registered!
+      return if builtin_backends_registered?
+      register_builtin_backends!
+      @builtin_backends_registered = true # rubocop:disable ThreadSafety/ClassInstanceVariable
+    end
+
+    # Parse TREE_HAVER_BACKEND environment variable (single backend)
+    #
+    # @return [Symbol] the backend symbol (:auto if not set or invalid)
+    # @api private
+    def parse_single_backend_env
+      env_value = ENV["TREE_HAVER_BACKEND"]
+      return :auto if env_value.nil? || env_value.strip.empty?
+
+      name = env_value.strip.downcase
+      return :auto unless VALID_BACKENDS.include?(name) && name != "all" && name != "none"
+
+      name.to_sym
+    end
+
+    # Parse a backend list environment variable
+    #
+    # @param env_var [String] the environment variable name
+    # @param valid_backends [Array<String>] list of valid backend names
+    # @return [Array<Symbol>] list of backend symbols, or [:auto] or [:none]
+    # @api private
+    def parse_backend_list_env(env_var, valid_backends)
+      env_value = ENV[env_var]
+
+      # Empty or unset means "auto"
+      return [:auto] if env_value.nil? || env_value.strip.empty?
+
+      normalized = env_value.strip.downcase
+
+      # Handle special values
+      return [:auto] if normalized == "auto"
+      return [:none] if normalized == "none"
+
+      # Split on comma and parse each backend
+      backends = normalized.split(",").map(&:strip).uniq
+
+      # Convert to symbols, filtering out invalid ones
+      parsed = backends.filter_map do |name|
+        valid_backends.include?(name) ? name.to_sym : nil
+      end
+
+      # Return :auto if no valid backends found
+      parsed.empty? ? [:auto] : parsed
     end
 
     # Thread-local backend context storage
@@ -569,7 +758,11 @@ module TreeHaver
       # Return nil if the module doesn't exist
       return unless mod
 
-      # Check for backend conflicts FIRST, before checking availability
+      # Check if the backend is allowed by environment variables FIRST
+      # This enforces TREE_HAVER_NATIVE_BACKEND and TREE_HAVER_RUBY_BACKEND as hard restrictions
+      return if requested && requested != :auto && !backend_allowed?(requested)
+
+      # Check for backend conflicts, before checking availability
       # This is critical because the conflict causes the backend to report unavailable
       # We want to raise a clear error explaining WHY it's unavailable
       # Use the requested backend name directly (not capabilities) because
@@ -590,11 +783,6 @@ module TreeHaver
       mod
     end
 
-    # Native tree-sitter backends that support loading shared libraries (.so files)
-    # These backends wrap the tree-sitter C library via various bindings.
-    # Pure Ruby backends (Citrus, Prism, Psych, Commonmarker, Markly) are excluded.
-    NATIVE_BACKENDS = %i[mri rust ffi java].freeze
-
     # Resolve a native tree-sitter backend module (for from_library)
     #
     # This method is similar to resolve_backend_module but ONLY considers
@@ -643,8 +831,14 @@ module TreeHaver
       end
 
       native_priority.each do |backend|
+        # Rescue BackendConflict to allow iteration to continue
+        # This enables graceful fallback when a backend is blocked
+
         mod = resolve_backend_module(backend)
         return mod if mod
+      rescue BackendConflict
+        # This backend is blocked by a previously used backend, try the next one
+        next
       end
 
       nil # No native backend available
@@ -664,7 +858,19 @@ module TreeHaver
     #     puts "Using #{mod.capabilities[:backend]} backend"
     #   end
     def backend_module
-      case effective_backend  # Changed from: backend
+      requested = effective_backend  # Changed from: backend
+
+      # For explicit backends (not :auto), check for conflicts first
+      # If the backend is blocked, fall through to auto-select
+      if requested != :auto && backend_protect?
+        conflicts = conflicting_backends_for(requested)
+        unless conflicts.empty?
+          # The explicitly requested backend is blocked - fall through to auto-select
+          requested = :auto
+        end
+      end
+
+      case requested
       when :mri
         Backends::MRI
       when :rust
@@ -685,15 +891,16 @@ module TreeHaver
         Backends::Markly
       else
         # auto-select: prefer native/fast backends, fall back to pure Ruby (Citrus)
-        if defined?(RUBY_ENGINE) && RUBY_ENGINE == "jruby" && Backends::Java.available?
+        # Each backend must be both allowed (by ENV) and available (gem installed)
+        if defined?(RUBY_ENGINE) && RUBY_ENGINE == "jruby" && backend_allowed?(:java) && Backends::Java.available?
           Backends::Java
-        elsif defined?(RUBY_ENGINE) && RUBY_ENGINE == "ruby" && Backends::MRI.available?
+        elsif defined?(RUBY_ENGINE) && RUBY_ENGINE == "ruby" && backend_allowed?(:mri) && Backends::MRI.available?
           Backends::MRI
-        elsif defined?(RUBY_ENGINE) && RUBY_ENGINE == "ruby" && Backends::Rust.available?
+        elsif defined?(RUBY_ENGINE) && RUBY_ENGINE == "ruby" && backend_allowed?(:rust) && Backends::Rust.available?
           Backends::Rust
-        elsif Backends::FFI.available?
+        elsif backend_allowed?(:ffi) && Backends::FFI.available?
           Backends::FFI
-        elsif Backends::Citrus.available?
+        elsif backend_allowed?(:citrus) && Backends::Citrus.available?
           Backends::Citrus  # Pure Ruby fallback
         else
           # No backend available
@@ -761,6 +968,8 @@ module TreeHaver
     # @param path [String, nil] absolute path to the language shared library (for tree-sitter)
     # @param symbol [String, nil] optional exported factory symbol (e.g., "tree_sitter_toml")
     # @param grammar_module [Module, nil] Citrus grammar module that responds to .parse(source)
+    # @param backend_module [Module, nil] pure Ruby backend module with Language/Parser classes
+    # @param backend_type [Symbol, nil] backend type for backend_module (defaults to module name)
     # @param gem_name [String, nil] optional gem name for error messages
     # @return [void]
     # @example Register tree-sitter grammar only
@@ -775,6 +984,13 @@ module TreeHaver
     #     grammar_module: TomlRB::Document,
     #     gem_name: "toml-rb"
     #   )
+    # @example Register pure Ruby backend (external gem like rbs-merge)
+    #   TreeHaver.register_language(
+    #     :rbs,
+    #     backend_module: Rbs::Merge::Backends::RbsBackend,
+    #     backend_type: :rbs,
+    #     gem_name: "rbs"
+    #   )
     # @example Register BOTH backends in separate calls
     #   TreeHaver.register_language(
     #     :toml,
@@ -795,7 +1011,7 @@ module TreeHaver
     #     gem_name: "toml-rb"
     #   )
     #   # Now TreeHaver::Language.toml works with ANY backend!
-    def register_language(name, path: nil, symbol: nil, grammar_module: nil, gem_name: nil)
+    def register_language(name, path: nil, symbol: nil, grammar_module: nil, backend_module: nil, backend_type: nil, gem_name: nil)
       # Register tree-sitter backend if path provided
       # Note: Uses `if` not `elsif` so both backends can be registered in one call
       if path
@@ -813,9 +1029,17 @@ module TreeHaver
         LanguageRegistry.register(name, :citrus, grammar_module: grammar_module, gem_name: gem_name)
       end
 
+      # Register pure Ruby backend if backend_module provided
+      # This is used by external gems (like rbs-merge) to register their own backends
+      if backend_module
+        # Derive backend_type from module name if not provided
+        type = backend_type || backend_module.name.split("::").last.downcase.to_sym
+        LanguageRegistry.register(name, type, backend_module: backend_module, gem_name: gem_name)
+      end
+
       # Require at least one backend to be registered
-      if path.nil? && grammar_module.nil?
-        raise ArgumentError, "Must provide at least one of: path (tree-sitter) or grammar_module (Citrus)"
+      if path.nil? && grammar_module.nil? && backend_module.nil?
+        raise ArgumentError, "Must provide at least one of: path (tree-sitter), grammar_module (Citrus), or backend_module (pure Ruby)"
       end
 
       # Note: No early return! This method intentionally processes both `if` blocks
@@ -836,114 +1060,152 @@ module TreeHaver
 
     # Create a parser configured for a specific language
     #
-    # This is the recommended high-level API for creating a parser. It handles:
-    # 1. Checking if the language is already registered
-    # 2. Auto-discovering tree-sitter grammar via GrammarFinder
-    # 3. Falling back to Citrus grammar if tree-sitter is unavailable
-    # 4. Creating and configuring the parser
+    # Respects the effective backend setting (via TREE_HAVER_BACKEND env var,
+    # TreeHaver.backend=, or with_backend block).
+    #
+    # Supports three types of backends:
+    # 1. Tree-sitter native backends (auto-discovered or explicit path)
+    # 2. Citrus grammars (pure Ruby, via CITRUS_DEFAULTS or explicit config)
+    # 3. Pure Ruby backends (registered via backend_module, e.g., Prism, Psych, RBS)
     #
-    # @param language_name [Symbol, String] the language to parse (e.g., :toml, :json, :bash)
+    # @param language_name [Symbol, String] the language to parse (e.g., :toml, :json, :ruby, :yaml, :rbs)
     # @param library_path [String, nil] optional explicit path to tree-sitter grammar library
     # @param symbol [String, nil] optional tree-sitter symbol name (defaults to "tree_sitter_<name>")
     # @param citrus_config [Hash, nil] optional Citrus fallback configuration
-    # @option citrus_config [String] :gem_name gem name for the Citrus grammar
-    # @option citrus_config [String] :grammar_const fully qualified constant name for grammar module
     # @return [TreeHaver::Parser] configured parser with language set
     # @raise [TreeHaver::NotAvailable] if no parser backend is available for the language
     #
     # @example Basic usage (auto-discovers grammar)
     #   parser = TreeHaver.parser_for(:toml)
-    #   tree = parser.parse("[package]\nname = \"my-app\"")
     #
-    # @example With explicit library path
-    #   parser = TreeHaver.parser_for(:toml, library_path: "/custom/path/libtree-sitter-toml.so")
+    # @example Force Citrus backend
+    #   TreeHaver.with_backend(:citrus) { TreeHaver.parser_for(:toml) }
     #
-    # @example With Citrus fallback configuration
-    #   parser = TreeHaver.parser_for(:toml,
-    #     citrus_config: { gem_name: "toml-rb", grammar_const: "TomlRB::Document" }
-    #   )
+    # @example Use registered pure Ruby backend (e.g., RBS)
+    #   # First, rbs-merge registers its backend:
+    #   # TreeHaver.register_language(:rbs, backend_module: Rbs::Merge::RbsBackend, backend_type: :rbs)
+    #   parser = TreeHaver.parser_for(:rbs)
     def parser_for(language_name, library_path: nil, symbol: nil, citrus_config: nil)
+      # Ensure built-in pure Ruby backends are registered
+      ensure_builtin_backends_registered!
+
       name = language_name.to_sym
       symbol ||= "tree_sitter_#{name}"
-
-      # Step 1: Try to get the language (may already be registered)
-      language = begin
-        # Check if already registered and loadable
-        if registered_language(name)
-          Language.public_send(name, path: library_path, symbol: symbol)
-        end
-      rescue NotAvailable, ArgumentError, LoadError
-        nil
-      end
-
-      # Step 2: If not registered, try GrammarFinder for tree-sitter
-      unless language
-        # Principle of Least Surprise: If user provides an explicit path,
-        # it MUST exist. Don't silently fall back to auto-discovery.
-        if library_path && !library_path.empty?
-          unless File.exist?(library_path)
-            raise NotAvailable,
-              "Specified parser path does not exist: #{library_path}"
-          end
-          begin
-            register_language(name, path: library_path, symbol: symbol)
-            language = Language.public_send(name)
-          rescue NotAvailable, ArgumentError, LoadError => e
-            # Re-raise with more context since user explicitly provided this path
-            raise NotAvailable,
-              "Failed to load parser from specified path #{library_path}: #{e.message}"
-          end
-        else
-          # Auto-discover via GrammarFinder (no explicit path provided)
-          begin
-            finder = GrammarFinder.new(name)
-            if finder.available?
-              finder.register!
-              language = Language.public_send(name)
+      requested = effective_backend
+
+      # Determine which backends to try based on effective_backend
+      try_tree_sitter = (requested == :auto) || NATIVE_BACKENDS.include?(requested)
+      try_citrus = (requested == :auto) || (requested == :citrus)
+
+      language = nil
+      parser = nil
+
+      # First, check for registered pure Ruby backends
+      # These take precedence when explicitly requested or when no other backend is available
+      registration = registered_language(name)
+      # Find any registered backend_module (not tree_sitter or citrus)
+      registration&.each do |backend_type, config|
+        next if %i[tree_sitter citrus].include?(backend_type)
+        next unless config[:backend_module]
+
+        backend_mod = config[:backend_module]
+        # Check if this backend is available
+        next unless backend_mod.respond_to?(:available?) && backend_mod.available?
+
+        # If a specific backend was requested, only use if it matches
+        next if requested != :auto && requested != backend_type
+
+        # Create parser from the backend module
+        if backend_mod.const_defined?(:Parser)
+          parser = backend_mod::Parser.new
+          if backend_mod.const_defined?(:Language)
+            lang_class = backend_mod::Language
+            # Try to get language by name (e.g., Language.ruby, Language.yaml, Language.rbs)
+            if lang_class.respond_to?(name)
+              parser.language = lang_class.public_send(name)
+            elsif lang_class.respond_to?(:from_library)
+              parser.language = lang_class.from_library(nil, name: name)
             end
-          rescue NotAvailable, ArgumentError, LoadError
-            language = nil
           end
+          return parser
         end
       end
 
-      # Step 3: Try Citrus fallback if tree-sitter failed
-      unless language
-        # Use explicit config, or fall back to built-in defaults for known languages
-        citrus_config ||= CITRUS_DEFAULTS[name] || {}
-
-        # Only attempt if we have the required configuration
-        if citrus_config[:gem_name] && citrus_config[:grammar_const]
-          begin
-            citrus_finder = CitrusGrammarFinder.new(
-              language: name,
-              gem_name: citrus_config[:gem_name],
-              grammar_const: citrus_config[:grammar_const],
-              require_path: citrus_config[:require_path],
-            )
-            if citrus_finder.available?
-              citrus_finder.register!
-              language = Language.public_send(name)
-            end
-          rescue NotAvailable, ArgumentError, LoadError, NameError, TypeError
-            language = nil
-          end
-        end
+      # Try tree-sitter if applicable
+      if try_tree_sitter && !language
+        language = load_tree_sitter_language(name, library_path: library_path, symbol: symbol)
       end
 
-      # Step 4: Raise if nothing worked
-      unless language
-        raise NotAvailable,
-          "No parser available for #{name}. " \
-            "Install tree-sitter-#{name} or the appropriate Ruby gem. " \
-            "Set TREE_SITTER_#{name.to_s.upcase}_PATH for custom grammar location."
+      # Try Citrus if applicable
+      if try_citrus && !language
+        language = load_citrus_language(name, citrus_config: citrus_config)
       end
 
-      # Step 5: Create and configure parser
+      # Raise if nothing worked
+      raise NotAvailable, "No parser available for #{name}. " \
+        "Install tree-sitter-#{name} or configure a Citrus grammar." unless language
+
+      # Create and configure parser
       parser = Parser.new
       parser.language = language
       parser
     end
+
+    private
+
+    # Load a tree-sitter language, either from registry or via auto-discovery
+    # @return [Language, nil]
+    # @raise [NotAvailable] if explicit library_path is provided but doesn't exist or can't load
+    def load_tree_sitter_language(name, library_path: nil, symbol: nil)
+      # If explicit path provided, it must work - don't swallow errors
+      if library_path && !library_path.empty?
+        raise NotAvailable, "Specified parser path does not exist: #{library_path}" unless File.exist?(library_path)
+        register_language(name, path: library_path, symbol: symbol)
+        return Language.public_send(name)
+      end
+
+      # Auto-discovery: errors are acceptable, just return nil
+      begin
+        # Try already-registered tree-sitter language (not Citrus)
+        # But only if the registered path actually exists - ignore stale/test registrations
+        registration = registered_language(name)
+        ts_reg = registration&.dig(:tree_sitter)
+        if ts_reg && ts_reg[:path] && File.exist?(ts_reg[:path])
+          return Language.public_send(name, symbol: symbol)
+        end
+
+        # Auto-discover via GrammarFinder
+        finder = GrammarFinder.new(name)
+        if finder.available?
+          finder.register!
+          return Language.public_send(name)
+        end
+      rescue NotAvailable, ArgumentError, LoadError
+        # Auto-discovery failed, that's okay
+      end
+
+      nil
+    end
+
+    # Load a Citrus language from configuration or defaults
+    # @return [Language, nil]
+    def load_citrus_language(name, citrus_config: nil)
+      config = citrus_config || CITRUS_DEFAULTS[name] || {}
+      return unless config[:gem_name] && config[:grammar_const]
+
+      finder = CitrusGrammarFinder.new(
+        language: name,
+        gem_name: config[:gem_name],
+        grammar_const: config[:grammar_const],
+        require_path: config[:require_path],
+      )
+      return unless finder.available?
+
+      finder.register!
+      Language.public_send(name)
+    rescue NotAvailable, ArgumentError, LoadError, NameError, TypeError
+      nil
+    end
   end
 
   # Language and Parser classes have been moved to separate files:

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: tree_haver
 version: !ruby/object:Gem::Version
-  version: 3.2.2
+  version: 3.2.4
 platform: ruby
 authors:
 - Peter H. Boling
@@ -260,6 +260,7 @@ files:
 - RUBOCOP.md
 - SECURITY.md
 - lib/tree_haver.rb
+- lib/tree_haver/backend_api.rb
 - lib/tree_haver/backends/citrus.rb
 - lib/tree_haver/backends/commonmarker.rb
 - lib/tree_haver/backends/ffi.rb
@@ -292,10 +293,10 @@ licenses:
 - MIT
 metadata:
   homepage_uri: https://tree-haver.galtzo.com/
-  source_code_uri: https://github.com/kettle-rb/tree_haver/tree/v3.2.2
-  changelog_uri: https://github.com/kettle-rb/tree_haver/blob/v3.2.2/CHANGELOG.md
+  source_code_uri: https://github.com/kettle-rb/tree_haver/tree/v3.2.4
+  changelog_uri: https://github.com/kettle-rb/tree_haver/blob/v3.2.4/CHANGELOG.md
   bug_tracker_uri: https://github.com/kettle-rb/tree_haver/issues
-  documentation_uri: https://www.rubydoc.info/gems/tree_haver/3.2.2
+  documentation_uri: https://www.rubydoc.info/gems/tree_haver/3.2.4
   funding_uri: https://github.com/sponsors/pboling
   wiki_uri: https://github.com/kettle-rb/tree_haver/wiki
   news_uri: https://www.railsbling.com/tags/tree_haver