tree_haver 2.0.0 → 3.0.0

data/lib/tree_haver/backends/java.rb

@@ -228,13 +228,57 @@ module TreeHaver
       # All Java backend implementation classes require JRuby and cannot be tested on MRI/CRuby.
       # JRuby-specific CI jobs would test this code.
       class Language
+        include Comparable
+
         attr_reader :impl
 
+        # The backend this language is for
+        # @return [Symbol]
+        attr_reader :backend
+
+        # The path this language was loaded from (if known)
+        # @return [String, nil]
+        attr_reader :path
+
+        # The symbol name (if known)
+        # @return [String, nil]
+        attr_reader :symbol
+
         # @api private
-        def initialize(impl)
+        def initialize(impl, path: nil, symbol: nil)
           @impl = impl
+          @backend = :java
+          @path = path
+          @symbol = symbol
+        end
+
+        # Compare languages for equality
+        #
+        # Java languages are equal if they have the same backend, path, and symbol.
+        # Path and symbol uniquely identify a loaded language.
+        #
+        # @param other [Object] object to compare with
+        # @return [Integer, nil] -1, 0, 1, or nil if not comparable
+        def <=>(other)
+          return unless other.is_a?(Language)
+          return unless other.backend == @backend
+
+          # Compare by path first, then symbol
+          cmp = (@path || "") <=> (other.path || "")
+          return cmp unless cmp.zero?
+
+          (@symbol || "") <=> (other.symbol || "")
+        end
+
+        # Hash value for this language (for use in Sets/Hashes)
+        # @return [Integer]
+        def hash
+          [@backend, @path, @symbol].hash
         end
 
+        # Alias eql? to ==
+        alias_method :eql?, :==
+
         # Load a language from a shared library
         #
         # There are three ways java-tree-sitter can load shared libraries:
@@ -298,7 +342,7 @@ module TreeHaver
               combined_lookup = grammar_lookup.or(Java.runtime_lookup)
 
               java_lang = Java.java_classes[:Language].load(combined_lookup, sym)
-              new(java_lang)
+              new(java_lang, path: path, symbol: symbol)
             rescue ::Java::JavaLang::RuntimeException => e
               cause = e.cause
               root_cause = cause&.cause || cause
@@ -354,7 +398,7 @@ module TreeHaver
               # java-tree-sitter's Language.load(String) searches for the language
               # in the classpath using standard naming conventions
               java_lang = Java.java_classes[:Language].load(name)
-              new(java_lang)
+              new(java_lang, symbol: "tree_sitter_#{name}")
             rescue ::Java::JavaLang::RuntimeException => e
               raise TreeHaver::NotAvailable,
                 "Failed to load language '#{name}': #{e.message}. " \
@@ -383,43 +427,48 @@ module TreeHaver
 
         # Set the language for this parser
         #
-        # @param lang [Language] the language to use
+        # Note: TreeHaver::Parser unwraps language objects before calling this method.
+        # This backend receives the Language wrapper's inner impl (java Language object).
+        #
+        # @param lang [Object] the Java language object (already unwrapped)
         # @return [void]
         def language=(lang)
-          java_lang = lang.is_a?(Language) ? lang.impl : lang
-          @parser.language = java_lang
+          # lang is already unwrapped by TreeHaver::Parser
+          @parser.language = lang
         end
 
         # Parse source code
         #
         # @param source [String] the source code to parse
-        # @return [TreeHaver::Tree] wrapped tree
+        # @return [Tree] raw backend tree (wrapping happens in TreeHaver::Parser)
         def parse(source)
           java_tree = @parser.parse(source)
-          inner_tree = Tree.new(java_tree)
-          TreeHaver::Tree.new(inner_tree, source: source)
+          # Return raw Java::Tree - TreeHaver::Parser will wrap it
+          Tree.new(java_tree)
         end
 
         # Parse source code with optional incremental parsing
         #
+        # Note: old_tree is already unwrapped by TreeHaver::Parser before reaching this method.
+        # The backend receives the raw Tree wrapper's impl, not a TreeHaver::Tree.
+        #
         # When old_tree is provided and has been edited, tree-sitter will reuse
         # unchanged nodes for better performance.
         #
-        # @param old_tree [TreeHaver::Tree, nil] previous tree for incremental parsing
+        # @param old_tree [Tree, nil] previous backend tree for incremental parsing (already unwrapped)
         # @param source [String] the source code to parse
-        # @return [TreeHaver::Tree] wrapped tree
+        # @return [Tree] raw backend tree (wrapping happens in TreeHaver::Parser)
         # @see https://tree-sitter.github.io/java-tree-sitter/io/github/treesitter/jtreesitter/Parser.html#parse(io.github.treesitter.jtreesitter.Tree,java.lang.String)
         def parse_string(old_tree, source)
+          # old_tree is already unwrapped to Tree wrapper's impl by TreeHaver::Parser
           if old_tree
-            # Unwrap TreeHaver::Tree to get inner tree
-            inner_old_tree = old_tree.respond_to?(:inner_tree) ? old_tree.inner_tree : old_tree
-            java_old_tree = inner_old_tree.is_a?(Tree) ? inner_old_tree.impl : inner_old_tree
+            java_old_tree = old_tree.is_a?(Tree) ? old_tree.impl : old_tree
             java_tree = @parser.parse(java_old_tree, source)
           else
             java_tree = @parser.parse(source)
           end
-          inner_tree = Tree.new(java_tree)
-          TreeHaver::Tree.new(inner_tree, source: source)
+          # Return raw Java::Tree - TreeHaver::Parser will wrap it
+          Tree.new(java_tree)
         end
       end
 

data/lib/tree_haver/backends/mri.rb

@@ -28,7 +28,7 @@ module TreeHaver
           return @loaded if @load_attempted # rubocop:disable ThreadSafety/ClassInstanceVariable
           @load_attempted = true # rubocop:disable ThreadSafety/ClassInstanceVariable
           begin
-            require "ruby_tree_sitter"
+            require "tree_sitter" # Note: gem is ruby_tree_sitter but requires tree_sitter
 
             @loaded = true # rubocop:disable ThreadSafety/ClassInstanceVariable
           rescue LoadError
@@ -37,6 +37,15 @@ module TreeHaver
           @loaded # rubocop:disable ThreadSafety/ClassInstanceVariable
         end
 
+        # Reset the load state (primarily for testing)
+        #
+        # @return [void]
+        # @api private
+        def reset!
+          @load_attempted = false # rubocop:disable ThreadSafety/ClassInstanceVariable
+          @loaded = false # rubocop:disable ThreadSafety/ClassInstanceVariable
+        end
+
         # Get capabilities supported by this backend
         #
         # @return [Hash{Symbol => Object}] capability map
@@ -56,19 +65,112 @@ module TreeHaver
 
       # Wrapper for ruby_tree_sitter Language
       #
-      # This is a thin pass-through to ::TreeSitter::Language from ruby_tree_sitter.
+      # Wraps ::TreeSitter::Language from ruby_tree_sitter to provide a consistent
+      # API across all backends.
       class Language
-        # Load a language from a shared library path
+        include Comparable
+
+        # The wrapped TreeSitter::Language object
+        # @return [::TreeSitter::Language]
+        attr_reader :inner_language
+
+        # The backend this language is for
+        # @return [Symbol]
+        attr_reader :backend
+
+        # The path this language was loaded from (if known)
+        # @return [String, nil]
+        attr_reader :path
+
+        # The symbol name (if known)
+        # @return [String, nil]
+        attr_reader :symbol
+
+        # @api private
+        # @param lang [::TreeSitter::Language] the language object from ruby_tree_sitter
+        # @param path [String, nil] path language was loaded from
+        # @param symbol [String, nil] symbol name
+        def initialize(lang, path: nil, symbol: nil)
+          @inner_language = lang
+          @backend = :mri
+          @path = path
+          @symbol = symbol
+        end
+
+        # Compare languages for equality
+        #
+        # MRI languages are equal if they have the same backend, path, and symbol.
+        # Path and symbol uniquely identify a loaded language.
+        #
+        # @param other [Object] object to compare with
+        # @return [Integer, nil] -1, 0, 1, or nil if not comparable
+        def <=>(other)
+          return unless other.is_a?(Language)
+          return unless other.backend == @backend
+
+          # Compare by path first, then symbol
+          cmp = (@path || "") <=> (other.path || "")
+          return cmp unless cmp.zero?
+
+          (@symbol || "") <=> (other.symbol || "")
+        end
+
+        # Hash value for this language (for use in Sets/Hashes)
+        # @return [Integer]
+        def hash
+          [@backend, @path, @symbol].hash
+        end
+
+        # Alias eql? to ==
+        alias_method :eql?, :==
+
+        # Convert to the underlying TreeSitter::Language for passing to parser
+        #
+        # @return [::TreeSitter::Language]
+        def to_language
+          @inner_language
+        end
+        alias_method :to_ts_language, :to_language
+
+        # Load a language from a shared library (preferred method)
         #
         # @param path [String] absolute path to the language shared library
-        # @return [::TreeSitter::Language] the loaded language handle
+        # @param symbol [String] the exported symbol name (e.g., "tree_sitter_json")
+        # @param name [String, nil] optional language name (unused by MRI backend)
+        # @return [Language] wrapped language handle
         # @raise [TreeHaver::NotAvailable] if ruby_tree_sitter is not available
         # @example
-        #   lang = TreeHaver::Backends::MRI::Language.from_path("/usr/local/lib/libtree-sitter-toml.so")
+        #   lang = TreeHaver::Backends::MRI::Language.from_library("/path/to/lib.so", symbol: "tree_sitter_json")
         class << self
-          def from_path(path)
+          def from_library(path, symbol: nil, name: nil)
             raise TreeHaver::NotAvailable, "ruby_tree_sitter not available" unless MRI.available?
-            ::TreeSitter::Language.load(path)
+
+            # ruby_tree_sitter's TreeSitter::Language.load takes (language_name, path_to_so)
+            # where language_name is the language identifier (e.g., "toml", "json")
+            # 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_/, "")
+            ts_lang = ::TreeSitter::Language.load(language_name, path)
+            new(ts_lang, path: path, symbol: symbol)
+          rescue NameError => e
+            # TreeSitter constant doesn't exist - backend not loaded
+            raise TreeHaver::NotAvailable, "ruby_tree_sitter not available: #{e.message}"
+          rescue TreeSitter::TreeSitterError => e
+            # TreeSitter errors inherit from Exception (not StandardError) in ruby_tree_sitter v2+
+            # This includes: ParserNotFoundError, LanguageLoadError, SymbolNotFoundError, etc.
+            raise TreeHaver::NotAvailable, "Could not load language: #{e.message}"
+          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
@@ -83,35 +185,70 @@ module TreeHaver
         def initialize
           raise TreeHaver::NotAvailable, "ruby_tree_sitter not available" unless MRI.available?
           @parser = ::TreeSitter::Parser.new
+        rescue NameError => e
+          # TreeSitter constant doesn't exist - backend not loaded
+          raise TreeHaver::NotAvailable, "ruby_tree_sitter not available: #{e.message}"
+        rescue TreeSitter::TreeSitterError => e
+          # TreeSitter errors inherit from Exception (not StandardError) in ruby_tree_sitter v2+
+          raise TreeHaver::NotAvailable, "Could not create parser: #{e.message}"
         end
 
         # Set the language for this parser
         #
-        # @param lang [::TreeSitter::Language] the language to use
+        # 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
+        # @raise [TreeHaver::NotAvailable] if setting language fails
         def language=(lang)
+          # lang is already unwrapped by TreeHaver::Parser, use directly
           @parser.language = lang
+          # Verify it was set
+          raise TreeHaver::NotAvailable, "Language not set correctly" if @parser.language.nil?
+
+          # Return the language object
+          lang
+        rescue TreeSitter::TreeSitterError => e
+          # TreeSitter errors inherit from Exception (not StandardError) in ruby_tree_sitter v2+
+          raise TreeHaver::NotAvailable, "Could not set language: #{e.message}"
         end
 
         # Parse source code
         #
+        # ruby_tree_sitter provides parse_string for string input
+        #
         # @param source [String] the source code to parse
-        # @return [TreeHaver::Tree] wrapped tree
+        # @return [::TreeSitter::Tree] raw tree (NOT wrapped - wrapping happens in TreeHaver::Parser)
+        # @raise [TreeHaver::NotAvailable] if parsing returns nil (usually means language not set)
         def parse(source)
-          tree = @parser.parse(source)
-          TreeHaver::Tree.new(tree, source: source)
+          # ruby_tree_sitter's parse_string(old_tree, string) method
+          # Pass nil for old_tree (initial parse)
+          # Return raw tree - TreeHaver::Parser will wrap it
+          tree = @parser.parse_string(nil, source)
+          raise TreeHaver::NotAvailable, "Parse returned nil - is language set?" if tree.nil?
+          tree
+        rescue TreeSitter::TreeSitterError => e
+          # TreeSitter errors inherit from Exception (not StandardError) in ruby_tree_sitter v2+
+          raise TreeHaver::NotAvailable, "Could not parse source: #{e.message}"
         end
 
         # Parse source code with optional incremental parsing
         #
-        # @param old_tree [TreeHaver::Tree, nil] previous tree for incremental parsing
+        # Note: old_tree should already be unwrapped by TreeHaver::Parser before reaching this method.
+        # The backend receives the raw inner tree (::TreeSitter::Tree or nil), not a wrapped TreeHaver::Tree.
+        #
+        # @param old_tree [::TreeSitter::Tree, nil] previous tree for incremental parsing (already unwrapped)
         # @param source [String] the source code to parse
-        # @return [TreeHaver::Tree] wrapped tree
+        # @return [::TreeSitter::Tree] raw tree (NOT wrapped - wrapping happens in TreeHaver::Parser)
+        # @raise [TreeHaver::NotAvailable] if parsing fails
         def parse_string(old_tree, source)
-          # Unwrap if TreeHaver::Tree to get inner tree for incremental parsing
-          inner_old_tree = old_tree.respond_to?(:inner_tree) ? old_tree.inner_tree : old_tree
-          tree = @parser.parse_string(inner_old_tree, source)
-          TreeHaver::Tree.new(tree, source: source)
+          # old_tree is already unwrapped by TreeHaver::Parser, pass it directly
+          # Return raw tree - TreeHaver::Parser will wrap it
+          @parser.parse_string(old_tree, source)
+        rescue TreeSitter::TreeSitterError => e
+          # TreeSitter errors inherit from Exception (not StandardError) in ruby_tree_sitter v2+
+          raise TreeHaver::NotAvailable, "Could not parse source: #{e.message}"
         end
       end
     end

data/lib/tree_haver/backends/rust.rb

@@ -54,14 +54,14 @@ module TreeHaver
         # @return [Hash{Symbol => Object}] capability map
         # @example
         #   TreeHaver::Backends::Rust.capabilities
-        #   # => { backend: :rust, query: true, bytes_field: true, incremental: true }
+        #   # => { backend: :rust, query: true, bytes_field: true, incremental: false }
         def capabilities
           return {} unless available?
           {
             backend: :rust,
             query: true,
             bytes_field: true,
-            incremental: true,
+            incremental: false,  # TreeStump doesn't currently expose incremental parsing to Ruby
           }
         end
       end
@@ -72,16 +72,52 @@ module TreeHaver
       # tree_stump uses a registration-based API where languages are registered
       # by name, then referenced by that name when setting parser language.
       class Language
+        include Comparable
+
         # The registered language name
         # @return [String]
         attr_reader :name
 
+        # The backend this language is for
+        # @return [Symbol]
+        attr_reader :backend
+
+        # The path this language was loaded from (if known)
+        # @return [String, nil]
+        attr_reader :path
+
         # @api private
         # @param name [String] the registered language name
-        def initialize(name)
+        # @param path [String, nil] path language was loaded from
+        def initialize(name, path: nil)
           @name = name
+          @backend = :rust
+          @path = path
+        end
+
+        # Compare languages for equality
+        #
+        # Rust languages are equal if they have the same backend and name.
+        # Name uniquely identifies a registered language in TreeStump.
+        #
+        # @param other [Object] object to compare with
+        # @return [Integer, nil] -1, 0, 1, or nil if not comparable
+        def <=>(other)
+          return unless other.is_a?(Language)
+          return unless other.backend == @backend
+
+          @name <=> other.name
         end
 
+        # Hash value for this language (for use in Sets/Hashes)
+        # @return [Integer]
+        def hash
+          [@backend, @name].hash
+        end
+
+        # Alias eql? to ==
+        alias_method :eql?, :==
+
         # Load a language from a shared library path
         #
         # @param path [String] absolute path to the language shared library
@@ -102,7 +138,7 @@ module TreeHaver
             # The name is used to derive the symbol automatically (tree_sitter_<name>)
             lang_name = name || File.basename(path, ".*").sub(/^libtree-sitter-/, "")
             ::TreeStump.register_lang(lang_name, path)
-            new(lang_name)
+            new(lang_name, path: path)
           rescue RuntimeError => e
             raise TreeHaver::NotAvailable, "Failed to load language from #{path}: #{e.message}"
           end
@@ -128,11 +164,16 @@ module TreeHaver
 
         # Set the language for this parser
         #
-        # @param lang [Language, String] the language to use (Language wrapper or name string)
+        # Note: TreeHaver::Parser unwraps language objects before calling this method.
+        # When called from TreeHaver::Parser, receives String (language name).
+        # For backward compatibility and backend tests, also handles Language wrapper.
+        #
+        # @param lang [Language, String] the language wrapper or name string
         # @return [Language, String] the language that was set
         def language=(lang)
-          # tree_stump uses set_language with a string name
+          # Extract language name (handle both wrapper and raw string)
           lang_name = lang.respond_to?(:name) ? lang.name : lang.to_s
+          # tree_stump uses set_language with a string name
           @parser.set_language(lang_name)
           lang
         end
@@ -140,22 +181,24 @@ module TreeHaver
         # Parse source code
         #
         # @param source [String] the source code to parse
-        # @return [TreeHaver::Tree] wrapped tree
+        # @return [TreeStump::Tree] raw backend tree (wrapping happens in TreeHaver::Parser)
         def parse(source)
-          tree = @parser.parse(source)
-          TreeHaver::Tree.new(tree, source: source)
+          # Return raw tree_stump tree - TreeHaver::Parser will wrap it
+          @parser.parse(source)
         end
 
         # Parse source code with optional incremental parsing
         #
-        # @param old_tree [TreeHaver::Tree, nil] previous tree for incremental parsing
+        # Note: TreeStump does not currently expose incremental parsing to Ruby.
+        # The parse method always does a full parse, ignoring old_tree.
+        #
+        # @param old_tree [TreeHaver::Tree, nil] previous tree for incremental parsing (ignored)
         # @param source [String] the source code to parse
-        # @return [TreeHaver::Tree] wrapped tree
-        def parse_string(old_tree, source)
-          # tree_stump doesn't have parse_string, use parse instead
-          # TODO: Check if tree_stump supports incremental parsing
-          tree = @parser.parse(source)
-          TreeHaver::Tree.new(tree, source: source)
+        # @return [TreeStump::Tree] raw backend tree (wrapping happens in TreeHaver::Parser)
+        def parse_string(old_tree, source) # rubocop:disable Lint/UnusedMethodArgument
+          # TreeStump's parse method only accepts source as a single argument
+          # and internally always passes None for the old tree (no incremental parsing support)
+          @parser.parse(source)
         end
       end
     end

data/lib/tree_haver/citrus_grammar_finder.rb

@@ -0,0 +1,170 @@
+# frozen_string_literal: true
+
+module TreeHaver
+  # Utility for finding and registering Citrus grammar gems.
+  #
+  # CitrusGrammarFinder provides language-agnostic discovery of Citrus grammar
+  # gems. Given a language name and gem information, it attempts to load the
+  # grammar and register it with tree_haver.
+  #
+  # Unlike tree-sitter grammars (which are .so files), Citrus grammars are
+  # Ruby modules that respond to .parse(source). This class handles the
+  # discovery and registration of these grammars.
+  #
+  # @example Basic usage with toml-rb
+  #   finder = TreeHaver::CitrusGrammarFinder.new(
+  #     language: :toml,
+  #     gem_name: "toml-rb",
+  #     grammar_const: "TomlRB::Document"
+  #   )
+  #   finder.register! if finder.available?
+  #
+  # @example With custom require path
+  #   finder = TreeHaver::CitrusGrammarFinder.new(
+  #     language: :json,
+  #     gem_name: "json-rb",
+  #     grammar_const: "JsonRB::Grammar",
+  #     require_path: "json/rb"
+  #   )
+  #
+  # @see GrammarFinder For tree-sitter grammar discovery
+  class CitrusGrammarFinder
+    # @return [Symbol] the language identifier
+    attr_reader :language_name
+
+    # @return [String] the gem name to require
+    attr_reader :gem_name
+
+    # @return [String] the constant path to the grammar (e.g., "TomlRB::Document")
+    attr_reader :grammar_const
+
+    # @return [String, nil] custom require path (defaults to gem_name with dashes to slashes)
+    attr_reader :require_path
+
+    # Initialize a Citrus grammar finder
+    #
+    # @param language [Symbol, String] the language name (e.g., :toml, :json)
+    # @param gem_name [String] the gem name (e.g., "toml-rb")
+    # @param grammar_const [String] constant path to grammar (e.g., "TomlRB::Document")
+    # @param require_path [String, nil] custom require path (defaults to gem_name with dashes→slashes)
+    def initialize(language:, gem_name:, grammar_const:, require_path: nil)
+      @language_name = language.to_sym
+      @gem_name = gem_name
+      @grammar_const = grammar_const
+      @require_path = require_path || gem_name.tr("-", "/")
+      @load_attempted = false
+      @available = false
+      @grammar_module = nil
+    end
+
+    # Check if the Citrus grammar is available
+    #
+    # Attempts to require the gem and resolve the grammar constant.
+    # Result is cached after first call.
+    #
+    # @return [Boolean] true if grammar is available
+    def available?
+      return @available if @load_attempted
+
+      @load_attempted = true
+      begin
+        # Try to require the gem
+        require @require_path
+
+        # Try to resolve the constant
+        @grammar_module = resolve_constant(@grammar_const)
+
+        # Verify it responds to parse
+        unless @grammar_module.respond_to?(:parse)
+          warn("#{@grammar_const} doesn't respond to :parse")
+          @available = false
+          return false
+        end
+
+        @available = true
+      rescue LoadError => e
+        # Always show LoadError for debugging
+        warn("CitrusGrammarFinder: Failed to load '#{@require_path}': #{e.class}: #{e.message}")
+        @available = false
+      rescue NameError => e
+        # Always show NameError for debugging
+        warn("CitrusGrammarFinder: Failed to resolve '#{@grammar_const}': #{e.class}: #{e.message}")
+        @available = false
+      rescue => e
+        # Catch any other errors
+        warn("CitrusGrammarFinder: Unexpected error: #{e.class}: #{e.message}")
+        warn(e.backtrace.first(3).join("\n")) if ENV["TREE_HAVER_DEBUG"]
+        @available = false
+      end
+
+      @available
+    end
+
+    # Get the resolved grammar module
+    #
+    # @return [Module, nil] the grammar module if available
+    def grammar_module
+      available? # Ensure we've tried to load
+      @grammar_module
+    end
+
+    # Register this Citrus grammar with TreeHaver
+    #
+    # After registration, the language can be used via:
+    #   TreeHaver::Language.{language_name}
+    #
+    # @param raise_on_missing [Boolean] if true, raises when grammar not available
+    # @return [Boolean] true if registration succeeded
+    # @raise [NotAvailable] if grammar not available and raise_on_missing is true
+    def register!(raise_on_missing: false)
+      unless available?
+        if raise_on_missing
+          raise NotAvailable, not_found_message
+        end
+        return false
+      end
+
+      TreeHaver.register_language(
+        @language_name,
+        grammar_module: @grammar_module,
+        gem_name: @gem_name,
+      )
+      true
+    end
+
+    # Get debug information about the search
+    #
+    # @return [Hash] diagnostic information
+    def search_info
+      {
+        language: @language_name,
+        gem_name: @gem_name,
+        grammar_const: @grammar_const,
+        require_path: @require_path,
+        available: available?,
+        grammar_module: @grammar_module&.name,
+      }
+    end
+
+    # Get a human-readable error message when grammar is not found
+    #
+    # @return [String] error message with installation hints
+    def not_found_message
+      "Citrus grammar for #{@language_name} not found. " \
+        "Install #{@gem_name} gem: gem install #{@gem_name}"
+    end
+
+    private
+
+    # Resolve a constant path like "TomlRB::Document"
+    #
+    # @param const_path [String] constant path
+    # @return [Object] the constant
+    # @raise [NameError] if constant not found
+    def resolve_constant(const_path)
+      const_path.split("::").reduce(Object) do |mod, const_name|
+        mod.const_get(const_name)
+      end
+    end
+  end
+end