tree_haver 3.0.0 → 3.1.1

data/lib/tree_haver/grammar_finder.rb

@@ -135,17 +135,49 @@ module TreeHaver
     # 3. Common system installation paths
     #
     # @note Paths from ENV are validated using {PathValidator.safe_library_path?}
-    #   to prevent path traversal and other attacks. Invalid ENV paths are ignored.
+    #   to prevent path traversal and other attacks. Invalid ENV paths cause
+    #   an error to be raised (Principle of Least Surprise - explicit paths must work).
+    #
+    # @note Setting the ENV variable to an empty string explicitly disables
+    #   this grammar. This allows fallback to alternative backends (e.g., Citrus).
     #
     # @return [String, nil] the path to the library, or nil if not found
+    # @raise [TreeHaver::NotAvailable] if ENV variable is set to an invalid path
     # @see #find_library_path_safe For stricter validation (trusted directories only)
     def find_library_path
       # Check environment variable first (highest priority)
-      env_path = ENV[env_var_name]
-      if env_path
+      # Use key? to distinguish between "not set" and "set to empty"
+      if ENV.key?(env_var_name)
+        env_path = ENV[env_var_name]
+
+        # :nocov: defensive - ENV.key? true with nil value is rare edge case
+        if env_path.nil?
+          @env_rejection_reason = "explicitly disabled (set to nil)"
+          return
+        end
+        # :nocov:
+
+        # Empty string means "explicitly skip this grammar"
+        # This allows users to disable tree-sitter for specific languages
+        # and fall back to alternative backends like Citrus
+        if env_path.empty?
+          @env_rejection_reason = "explicitly disabled (set to empty string)"
+          return
+        end
+
         # Store why env path was rejected for better error messages
         @env_rejection_reason = validate_env_path(env_path)
-        return env_path if @env_rejection_reason.nil?
+
+        # Principle of Least Surprise: If user explicitly sets an ENV variable
+        # to a path, that path MUST work. Don't silently fall back to auto-discovery.
+        if @env_rejection_reason
+          raise TreeHaver::NotAvailable,
+            "#{env_var_name} is set to #{env_path.inspect} but #{@env_rejection_reason}. " \
+              "Either fix the path, unset the variable to use auto-discovery, " \
+              "or set it to empty string to explicitly disable this grammar."
+        end
+
+        return env_path
       end
 
       # Search all paths (these are constructed from trusted base dirs)
@@ -188,11 +220,67 @@ module TreeHaver
       end
     end
 
-    # Check if the grammar library is available
+    # Check if the grammar library is available AND usable
     #
-    # @return [Boolean] true if the library can be found
+    # This checks:
+    # 1. The grammar library file exists
+    # 2. The tree-sitter runtime is functional (can create a parser)
+    #
+    # This prevents registering grammars when tree-sitter isn't actually usable,
+    # allowing clean fallback to alternative backends like Citrus.
+    #
+    # @return [Boolean] true if the library can be found AND tree-sitter runtime works
     def available?
-      !find_library_path.nil?
+      path = find_library_path
+      return false if path.nil?
+
+      # Check if tree-sitter runtime is actually functional
+      # This is cached at the class level since it's the same for all grammars
+      self.class.tree_sitter_runtime_usable?
+    end
+
+    # Backends that use tree-sitter (require native runtime libraries)
+    # Other backends (Citrus, Prism, Psych, etc.) don't use tree-sitter
+    TREE_SITTER_BACKENDS = [
+      TreeHaver::Backends::MRI,
+      TreeHaver::Backends::FFI,
+      TreeHaver::Backends::Rust,
+      TreeHaver::Backends::Java,
+    ].freeze
+
+    class << self
+      # Check if the tree-sitter runtime is usable
+      #
+      # Tests whether we can actually create a tree-sitter parser.
+      # Result is cached since this is expensive and won't change during runtime.
+      #
+      # @return [Boolean] true if tree-sitter runtime is functional
+      def tree_sitter_runtime_usable?
+        return @tree_sitter_runtime_usable if defined?(@tree_sitter_runtime_usable)
+
+        @tree_sitter_runtime_usable = begin
+          # Try to create a parser using the current backend
+          mod = TreeHaver.resolve_backend_module(nil)
+
+          # Only tree-sitter backends are relevant here
+          # Non-tree-sitter backends (Citrus, Prism, Psych, etc.) don't use grammar files
+          return false if mod.nil?
+          return false unless TREE_SITTER_BACKENDS.include?(mod)
+
+          # Try to instantiate a parser - this will fail if runtime isn't available
+          mod::Parser.new
+          true
+        rescue NoMethodError, FFI::NotFoundError, LoadError, NotAvailable => _e
+          false
+        end
+      end
+
+      # Reset the cached tree-sitter runtime check (for testing)
+      #
+      # @api private
+      def reset_runtime_check!
+        remove_instance_variable(:@tree_sitter_runtime_usable) if defined?(@tree_sitter_runtime_usable)
+      end
     end
 
     # Check if the grammar library is available in a trusted directory
@@ -252,6 +340,9 @@ module TreeHaver
       env_value = ENV[env_var_name]
       msg += if env_value && @env_rejection_reason
         " #{env_var_name} is set to #{env_value.inspect} but #{@env_rejection_reason}."
+      elsif env_value && File.exist?(env_value) && !self.class.tree_sitter_runtime_usable?
+        " #{env_var_name} is set and file exists, but no tree-sitter runtime is available. " \
+          "Add ruby_tree_sitter, ffi, or tree_stump gem to your Gemfile."
       elsif env_value
         " #{env_var_name} is set but was not used (file may have been removed)."
       else

data/lib/tree_haver/language_registry.rb

@@ -11,20 +11,26 @@ module TreeHaver
   # switching, benchmarking, and fallback scenarios.
   #
   # Registration structure:
+  # ```ruby
   # @registrations = {
   #   toml: {
   #     tree_sitter: { path: "/path/to/lib.so", symbol: "tree_sitter_toml" },
   #     citrus: { grammar_module: TomlRB::Document, gem_name: "toml-rb" }
   #   }
   # }
+  # ```
   #
   # @example Register tree-sitter grammar
+  # ```ruby
   #   TreeHaver::LanguageRegistry.register(:toml, :tree_sitter,
   #     path: "/path/to/lib.so", symbol: "tree_sitter_toml")
+  # ```
   #
   # @example Register Citrus grammar
+  # ```ruby
   #   TreeHaver::LanguageRegistry.register(:toml, :citrus,
   #     grammar_module: TomlRB::Document, gem_name: "toml-rb")
+  # ```
   #
   # @api private
   module LanguageRegistry

data/lib/tree_haver/node.rb

@@ -1,40 +1,6 @@
 # frozen_string_literal: true
 
 module TreeHaver
-  # Point class that works as both a Hash and an object with row/column accessors
-  #
-  # This provides compatibility with code expecting either:
-  # - Hash access: point[:row], point[:column]
-  # - Method access: point.row, point.column
-  class Point
-    attr_reader :row, :column
-
-    def initialize(row, column)
-      @row = row
-      @column = column
-    end
-
-    # Hash-like access for compatibility
-    def [](key)
-      case key
-      when :row, "row" then @row
-      when :column, "column" then @column
-      end
-    end
-
-    def to_h
-      {row: @row, column: @column}
-    end
-
-    def to_s
-      "(#{@row}, #{@column})"
-    end
-
-    def inspect
-      "#<TreeHaver::Point row=#{@row} column=#{@column}>"
-    end
-  end
-
   # Unified Node wrapper providing a consistent API across all backends
   #
   # This class wraps backend-specific node objects (TreeSitter::Node, TreeStump::Node, etc.)
@@ -95,6 +61,7 @@ module TreeHaver
   # @note This is the key to tree_haver's "write once, run anywhere" promise
   class Node
     include Comparable
+    include Enumerable
 
     # The wrapped backend-specific node object
     #
@@ -165,10 +132,20 @@ module TreeHaver
     def start_point
       if @inner_node.respond_to?(:start_point)
         point = @inner_node.start_point
-        Point.new(point.row, point.column)
+        # Handle both Point objects and hashes
+        if point.is_a?(Hash)
+          Point.new(point[:row], point[:column])
+        else
+          Point.new(point.row, point.column)
+        end
       elsif @inner_node.respond_to?(:start_position)
         point = @inner_node.start_position
-        Point.new(point.row, point.column)
+        # Handle both Point objects and hashes
+        if point.is_a?(Hash)
+          Point.new(point[:row], point[:column])
+        else
+          Point.new(point.row, point.column)
+        end
       else
         raise TreeHaver::Error, "Backend node does not support start_point/start_position"
       end
@@ -180,15 +157,71 @@ module TreeHaver
     def end_point
       if @inner_node.respond_to?(:end_point)
         point = @inner_node.end_point
-        Point.new(point.row, point.column)
+        # Handle both Point objects and hashes
+        if point.is_a?(Hash)
+          Point.new(point[:row], point[:column])
+        else
+          Point.new(point.row, point.column)
+        end
       elsif @inner_node.respond_to?(:end_position)
         point = @inner_node.end_position
-        Point.new(point.row, point.column)
+        # Handle both Point objects and hashes
+        if point.is_a?(Hash)
+          Point.new(point[:row], point[:column])
+        else
+          Point.new(point.row, point.column)
+        end
       else
         raise TreeHaver::Error, "Backend node does not support end_point/end_position"
       end
     end
 
+    # Get the 1-based line number where this node starts
+    #
+    # Convenience method that converts 0-based row to 1-based line number.
+    # This is useful for error messages and matching with editor line numbers.
+    #
+    # @return [Integer] 1-based line number
+    def start_line
+      start_point.row + 1
+    end
+
+    # Get the 1-based line number where this node ends
+    #
+    # Convenience method that converts 0-based row to 1-based line number.
+    #
+    # @return [Integer] 1-based line number
+    def end_line
+      end_point.row + 1
+    end
+
+    # Get position information as a hash
+    #
+    # Returns a hash with 1-based line numbers and 0-based columns.
+    # This format is compatible with *-merge gems' FileAnalysisBase.
+    #
+    # @return [Hash{Symbol => Integer}] Position hash
+    # @example
+    #   node.source_position
+    #   # => { start_line: 1, end_line: 3, start_column: 0, end_column: 10 }
+    def source_position
+      {
+        start_line: start_line,
+        end_line: end_line,
+        start_column: start_point.column,
+        end_column: end_point.column,
+      }
+    end
+
+    # Get the first child node
+    #
+    # Convenience method for iteration patterns that expect first_child.
+    #
+    # @return [Node, nil] First child node or nil if no children
+    def first_child
+      child(0)
+    end
+
     # Get the node's text content
     #
     # @return [String]
@@ -435,10 +468,10 @@ module TreeHaver
 
       # Compare by position first (start_byte, then end_byte)
       cmp = start_byte <=> other.start_byte
-      return cmp unless cmp.zero?
+      return cmp if cmp.nonzero?
 
       cmp = end_byte <=> other.end_byte
-      return cmp unless cmp.zero?
+      return cmp if cmp.nonzero?
 
       # For nodes at the same position with same span, compare by type
       type <=> other.type

data/lib/tree_haver/point.rb

@@ -0,0 +1,65 @@
+# frozen_string_literal: true
+
+module TreeHaver
+  # Point class that works as both a Hash and an object with row/column accessors
+  #
+  # This provides compatibility with code expecting either:
+  # - Hash access: point[:row], point[:column]
+  # - Method access: point.row, point.column
+  #
+  # @example Method access
+  #   point = TreeHaver::Point.new(5, 10)
+  #   point.row    # => 5
+  #   point.column # => 10
+  #
+  # @example Hash-like access
+  #   point[:row]    # => 5
+  #   point[:column] # => 10
+  #
+  # @example Converting to hash
+  #   point.to_h # => {row: 5, column: 10}
+  class Point
+    attr_reader :row, :column
+
+    # Create a new Point
+    #
+    # @param row [Integer] the row (line) number, 0-indexed
+    # @param column [Integer] the column number, 0-indexed
+    def initialize(row, column)
+      @row = row
+      @column = column
+    end
+
+    # Hash-like access for compatibility
+    #
+    # @param key [Symbol, String] :row or :column
+    # @return [Integer, nil] the value or nil if key not recognized
+    def [](key)
+      case key
+      when :row, "row" then @row
+      when :column, "column" then @column
+      end
+    end
+
+    # Convert to a hash
+    #
+    # @return [Hash{Symbol => Integer}]
+    def to_h
+      {row: @row, column: @column}
+    end
+
+    # String representation
+    #
+    # @return [String]
+    def to_s
+      "(#{@row}, #{@column})"
+    end
+
+    # Inspect representation
+    #
+    # @return [String]
+    def inspect
+      "#<TreeHaver::Point row=#{@row} column=#{@column}>"
+    end
+  end
+end