tree_haver 3.1.0 → 3.1.2

data/lib/tree_haver/backends/prism.rb

@@ -319,6 +319,8 @@ module TreeHaver
       #
       # @api private
       class Node
+        include Enumerable
+
         # @return [::Prism::Node] the underlying Prism node
         attr_reader :inner_node
 
@@ -553,27 +555,26 @@ module TreeHaver
 
         # Get the parent node
         #
-        # @note Prism nodes don't have built-in parent references.
-        #       This always returns nil. Use tree traversal instead.
-        # @return [nil]
+        # @raise [NotImplementedError] Prism nodes don't have parent references
+        # @return [void]
         def parent
-          nil  # Prism doesn't track parent references
+          raise NotImplementedError, "Prism backend does not support parent navigation"
         end
 
         # Get next sibling
         #
-        # @note Prism nodes don't have sibling references.
-        # @return [nil]
+        # @raise [NotImplementedError] Prism nodes don't have sibling references
+        # @return [void]
         def next_sibling
-          nil
+          raise NotImplementedError, "Prism backend does not support sibling navigation"
         end
 
         # Get previous sibling
         #
-        # @note Prism nodes don't have sibling references.
-        # @return [nil]
+        # @raise [NotImplementedError] Prism nodes don't have sibling references
+        # @return [void]
         def prev_sibling
-          nil
+          raise NotImplementedError, "Prism backend does not support sibling navigation"
         end
 
         # String representation for debugging

data/lib/tree_haver/backends/psych.rb

@@ -231,6 +231,7 @@ module TreeHaver
       # - Alias: YAML anchor reference
       class Node
         include Comparable
+        include Enumerable
 
         # @return [::Psych::Nodes::Node] The underlying Psych node
         attr_reader :inner_node
@@ -446,6 +447,30 @@ module TreeHaver
           "#<TreeHaver::Backends::Psych::Node type=#{type} children=#{child_count}>"
         end
 
+        # Get the next sibling
+        #
+        # @raise [NotImplementedError] Psych nodes don't have sibling references
+        # @return [void]
+        def next_sibling
+          raise NotImplementedError, "Psych backend does not support sibling navigation"
+        end
+
+        # Get the previous sibling
+        #
+        # @raise [NotImplementedError] Psych nodes don't have sibling references
+        # @return [void]
+        def prev_sibling
+          raise NotImplementedError, "Psych backend does not support sibling navigation"
+        end
+
+        # Get the parent node
+        #
+        # @raise [NotImplementedError] Psych nodes don't have parent references
+        # @return [void]
+        def parent
+          raise NotImplementedError, "Psych backend does not support parent navigation"
+        end
+
         # Psych-specific: Get the anchor name for Alias/anchored nodes
         #
         # @return [String, nil] Anchor name

data/lib/tree_haver/backends/rust.rb

@@ -12,7 +12,7 @@ module TreeHaver
     # suitable for editor/IDE use cases where performance is critical.
     #
     # @note This backend works on MRI Ruby. JRuby/TruffleRuby support is unknown.
-    # @see https://github.com/anthropics/tree_stump tree_stump
+    # @see https://github.com/joker1007/tree_stump tree_stump
     module Rust
       @load_attempted = false
       @loaded = false

data/lib/tree_haver/grammar_finder.rb

@@ -135,12 +135,14 @@ 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)
@@ -148,6 +150,13 @@ module TreeHaver
       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
@@ -158,7 +167,17 @@ module TreeHaver
 
         # 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)
@@ -321,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
     #

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