tree_haver 3.2.2 → 3.2.4

data/lib/tree_haver/rspec/dependency_tags.rb

@@ -125,6 +125,9 @@ require "set"
 # [:citrus_backend]
 #   Citrus gem is available.
 #
+# [:rbs_backend]
+#   RBS gem is available (official RBS parser, MRI only).
+#
 # ==== Ruby Engine Tags (*_engine)
 #
 # [:mri_engine]
@@ -153,6 +156,9 @@ require "set"
 # [:jsonc_grammar]
 #   tree-sitter-jsonc grammar is available and parsing works.
 #
+# [:rbs_grammar]
+#   tree-sitter-rbs grammar is available and parsing works.
+#
 # ==== Language Parsing Capability Tags (*_parsing)
 #
 # [:toml_parsing]
@@ -161,21 +167,29 @@ require "set"
 # [:markdown_parsing]
 #   At least one markdown parser (commonmarker OR markly) is available.
 #
+# [:rbs_parsing]
+#   At least one RBS parser (rbs gem OR tree-sitter-rbs) is available.
+#
 # [:native_parsing]
 #   A native tree-sitter backend and grammar are available.
 #
-# ==== Specific Library Tags
+# ==== Specific Library Tags (*_gem)
 #
-# [:toml_rb]
+# [:toml_rb_gem]
 #   toml-rb gem is available (Citrus backend for TOML).
 #
+# [:rbs_gem]
+#   rbs gem is available (official RBS parser, MRI only).
+#   Note: Also available as :rbs_backend for consistency with other parser backends.
+#
 # === Negated Tags (run when dependency is NOT available)
 #
 # All positive tags have negated versions prefixed with `not_`:
-# - :not_mri_backend, :not_rust_backend, :not_java_backend, etc.
+# - :not_mri_backend, :not_rust_backend, :not_java_backend, :not_rbs_backend, etc.
 # - :not_mri_engine, :not_jruby_engine, :not_truffleruby_engine
-# - :not_libtree_sitter, :not_bash_grammar, :not_toml_grammar, etc.
-# - :not_toml_parsing, :not_markdown_parsing
+# - :not_libtree_sitter, :not_bash_grammar, :not_toml_grammar, :not_rbs_grammar, etc.
+# - :not_toml_parsing, :not_markdown_parsing, :not_rbs_parsing
+# - :not_toml_rb_gem, :not_rbs_gem
 #
 # == Backend Conflict Protection
 #
@@ -200,6 +214,63 @@ module TreeHaver
     # Dependency detection helpers for conditional test execution
     module DependencyTags
       class << self
+        # ============================================================
+        # Backend Selection via Environment Variables
+        # ============================================================
+        #
+        # Three environment variables control backend availability:
+        #
+        # TREE_HAVER_BACKEND - Single backend selection (the primary one to use)
+        #   Values: auto, mri, ffi, rust, java, citrus, prism, psych, commonmarker, markly
+        #   Default: auto
+        #
+        # TREE_HAVER_NATIVE_BACKEND - Allow list for native backends
+        #   Values: all, none, or comma-separated list (mri, ffi, rust, java)
+        #   Default: all (empty or unset)
+        #   Example: TREE_HAVER_NATIVE_BACKEND=mri,ffi
+        #
+        # TREE_HAVER_RUBY_BACKEND - Allow list for pure Ruby backends
+        #   Values: all, none, or comma-separated list (citrus, prism, psych, commonmarker, markly)
+        #   Default: all (empty or unset)
+        #   Example: TREE_HAVER_RUBY_BACKEND=citrus
+        #
+        # This ensures tests tagged with :mri_backend only run when MRI is allowed, etc.
+
+        # Get the selected backend from TREE_HAVER_BACKEND
+        #
+        # @return [Symbol] the selected backend (:auto if not set)
+        def selected_backend
+          return @selected_backend if defined?(@selected_backend)
+          @selected_backend = TreeHaver.backend
+        end
+
+        # Get allowed native backends from TREE_HAVER_NATIVE_BACKEND
+        #
+        # @return [Array<Symbol>] list of allowed native backends, or [:all] or [:none]
+        def allowed_native_backends
+          return @allowed_native_backends if defined?(@allowed_native_backends)
+          @allowed_native_backends = TreeHaver.allowed_native_backends
+        end
+
+        # Get allowed Ruby backends from TREE_HAVER_RUBY_BACKEND
+        #
+        # @return [Array<Symbol>] list of allowed Ruby backends, or [:all] or [:none]
+        def allowed_ruby_backends
+          return @allowed_ruby_backends if defined?(@allowed_ruby_backends)
+          @allowed_ruby_backends = TreeHaver.allowed_ruby_backends
+        end
+
+        # Check if a specific backend is allowed based on environment variables
+        #
+        # Delegates to TreeHaver.backend_allowed? which handles both
+        # TREE_HAVER_NATIVE_BACKEND and TREE_HAVER_RUBY_BACKEND.
+        #
+        # @param backend [Symbol] the backend to check (:mri, :ffi, :citrus, etc.)
+        # @return [Boolean] true if the backend is allowed
+        def backend_allowed?(backend)
+          TreeHaver.backend_allowed?(backend)
+        end
+
         # ============================================================
         # TreeHaver Backend Availability
         # ============================================================
@@ -220,6 +291,10 @@ module TreeHaver
         #
         # @return [Boolean] true if FFI backend is usable
         def ffi_available?
+          # If TREE_HAVER_BACKEND explicitly selects a different native backend,
+          # FFI is not available for testing
+          return false unless backend_allowed?(:ffi)
+
           # TruffleRuby's FFI doesn't support STRUCT_BY_VALUE return types
           # (used by ts_tree_root_node, ts_node_child, ts_node_start_point, etc.)
           return false if truffleruby?
@@ -250,6 +325,10 @@ module TreeHaver
         def mri_backend_available?
           return @mri_backend_available if defined?(@mri_backend_available)
 
+          # If TREE_HAVER_BACKEND explicitly selects a different native backend,
+          # MRI is not available for testing
+          return @mri_backend_available = false unless backend_allowed?(:mri)
+
           # ruby_tree_sitter is a C extension that only works on MRI
           return @mri_backend_available = false unless mri?
 
@@ -273,6 +352,10 @@ module TreeHaver
         #
         # @return [Boolean] true if FFI backend is usable in isolation
         def ffi_backend_only_available?
+          # If TREE_HAVER_BACKEND explicitly selects a different native backend,
+          # FFI is not available for testing
+          return false unless backend_allowed?(:ffi)
+
           # TruffleRuby's FFI doesn't support STRUCT_BY_VALUE return types
           return false if truffleruby?
 
@@ -307,6 +390,10 @@ module TreeHaver
         def mri_backend_only_available?
           return @mri_backend_only_available if defined?(@mri_backend_only_available)
 
+          # If TREE_HAVER_BACKEND explicitly selects a different native backend,
+          # MRI is not available for testing
+          return @mri_backend_only_available = false unless backend_allowed?(:mri)
+
           # ruby_tree_sitter is a C extension that only works on MRI
           return @mri_backend_only_available = false unless mri?
 
@@ -327,6 +414,10 @@ module TreeHaver
         def rust_backend_available?
           return @rust_backend_available if defined?(@rust_backend_available)
 
+          # If TREE_HAVER_BACKEND explicitly selects a different native backend,
+          # Rust is not available for testing
+          return @rust_backend_available = false unless backend_allowed?(:rust)
+
           # tree_stump uses magnus which requires MRI's C API
           return @rust_backend_available = false unless mri?
 
@@ -338,12 +429,58 @@ module TreeHaver
           end
         end
 
-        # Check if Java backend is available (requires JRuby + java-tree-sitter / jtreesitter)
+        # Check if Java backend is available AND can actually load grammars
+        #
+        # The Java backend requires:
+        # 1. Running on JRuby
+        # 2. java-tree-sitter (jtreesitter) JAR available
+        # 3. Grammars built for java-tree-sitter's Foreign Function Memory API
         #
-        # @return [Boolean] true if Java backend is available
+        # Note: Standard `.so` files built for MRI's tree-sitter C bindings are NOT
+        # compatible with java-tree-sitter. You need grammar JARs from Maven Central
+        # or libraries specifically built for Java FFM API.
+        #
+        # @return [Boolean] true if Java backend is available and can load grammars
         def java_backend_available?
           return @java_backend_available if defined?(@java_backend_available)
-          @java_backend_available = jruby? && TreeHaver::Backends::Java.available?
+
+          # If TREE_HAVER_BACKEND explicitly selects a different native backend,
+          # Java is not available for testing
+          return @java_backend_available = false unless backend_allowed?(:java)
+
+          # Must be on JRuby and have java-tree-sitter classes available
+          return @java_backend_available = false unless jruby?
+          return @java_backend_available = false unless TreeHaver::Backends::Java.available?
+
+          # Try to actually load a grammar to verify the backend works end-to-end
+          # This catches the case where Java classes load but grammars fail
+          # (e.g., when using MRI-built .so files on JRuby)
+          @java_backend_available = java_grammar_loadable?
+        end
+
+        # Check if Java backend can actually load a grammar
+        #
+        # This does a live test by trying to load a TOML grammar via the Java backend.
+        # It catches the common failure case where java-tree-sitter is available but
+        # the grammar .so files are incompatible (built for MRI, not java-tree-sitter).
+        #
+        # @return [Boolean] true if a grammar can be loaded via Java backend
+        # @api private
+        def java_grammar_loadable?
+          return false unless jruby?
+
+          path = find_toml_grammar_path
+          return false unless path && File.exist?(path)
+
+          TreeHaver.with_backend(:java) do
+            TreeHaver::Backends::Java::Language.from_library(path, symbol: "tree_sitter_toml")
+          end
+          true
+        rescue TreeHaver::NotAvailable, TreeHaver::Error, LoadError
+          false
+        rescue StandardError
+          # Catch any other Java-related errors
+          false
         end
 
         # Check if libtree-sitter runtime library is loadable
@@ -496,12 +633,53 @@ module TreeHaver
           @tree_sitter_jsonc_available = grammar_works?(:jsonc, '{"key": "value" /* comment */}')
         end
 
+        # Check if tree-sitter-rbs grammar is available and working
+        #
+        # @return [Boolean] true if rbs grammar works
+        def tree_sitter_rbs_available?
+          return @tree_sitter_rbs_available if defined?(@tree_sitter_rbs_available)
+          @tree_sitter_rbs_available = grammar_works?(:rbs, "class Foo end")
+        end
+
+        # Check if the RBS gem is available and functional
+        #
+        # The RBS gem only works on MRI Ruby (C extension).
+        #
+        # @return [Boolean] true if rbs gem is available and can parse RBS
+        def rbs_gem_available?
+          return @rbs_gem_available if defined?(@rbs_gem_available)
+          @rbs_gem_available = begin
+            require "rbs"
+            # Verify it can actually parse - just requiring isn't enough
+            buffer = ::RBS::Buffer.new(name: "test.rbs", content: "class Foo end")
+            ::RBS::Parser.parse_signature(buffer)
+            true
+          rescue LoadError
+            false
+          rescue StandardError
+            false
+          end
+        end
+
+        # Alias for rbs_gem_available? - for consistency with other backends
+        # Use :rbs_backend tag in specs for consistency with :prism_backend, :psych_backend, etc.
+        #
+        # @return [Boolean] true if rbs gem is available
+        alias_method :rbs_backend_available?, :rbs_gem_available?
+
+        # Check if at least one RBS backend is available
+        #
+        # @return [Boolean] true if any RBS backend works
+        def any_rbs_backend_available?
+          rbs_gem_available? || tree_sitter_rbs_available?
+        end
+
         # Check if toml-rb gem is available and functional (Citrus backend for TOML)
         #
         # @return [Boolean] true if toml-rb gem is available and can parse TOML
-        def toml_rb_available?
-          return @toml_rb_available if defined?(@toml_rb_available)
-          @toml_rb_available = begin
+        def toml_rb_gem_available?
+          return @toml_rb_gem_available if defined?(@toml_rb_gem_available)
+          @toml_rb_gem_available = begin
             require "toml-rb"
             # Verify it can actually parse - just requiring isn't enough
             TomlRB.parse('key = "value"')
@@ -517,7 +695,7 @@ module TreeHaver
         #
         # @return [Boolean] true if any TOML backend works
         def any_toml_backend_available?
-          tree_sitter_toml_available? || toml_rb_available?
+          tree_sitter_toml_available? || toml_rb_gem_available?
         end
 
         # Check if at least one markdown backend is available
@@ -545,6 +723,10 @@ module TreeHaver
         # @return [Hash{Symbol => Boolean}] map of dependency name to availability
         def summary
           {
+            # Backend selection from environment variables
+            selected_backend: selected_backend,
+            allowed_native_backends: allowed_native_backends,
+            allowed_ruby_backends: allowed_ruby_backends,
             # TreeHaver backends (*_backend)
             ffi_backend: ffi_available?,
             mri_backend: mri_backend_available?,
@@ -555,6 +737,7 @@ module TreeHaver
             commonmarker_backend: commonmarker_available?,
             markly_backend: markly_available?,
             citrus_backend: citrus_available?,
+            rbs_backend: rbs_backend_available?,
             # Ruby engines (*_engine)
             ruby_engine: RUBY_ENGINE,
             mri_engine: mri?,
@@ -566,12 +749,15 @@ module TreeHaver
             toml_grammar: tree_sitter_toml_available?,
             json_grammar: tree_sitter_json_available?,
             jsonc_grammar: tree_sitter_jsonc_available?,
+            rbs_grammar: tree_sitter_rbs_available?,
             any_native_grammar: any_native_grammar_available?,
             # Language parsing capabilities (*_parsing)
             toml_parsing: any_toml_backend_available?,
             markdown_parsing: any_markdown_backend_available?,
-            # Specific libraries
-            toml_rb: toml_rb_available?,
+            rbs_parsing: any_rbs_backend_available?,
+            # Specific libraries (*_gem)
+            toml_rb_gem: toml_rb_gem_available?,
+            rbs_gem: rbs_gem_available?,
           }
         end
 
@@ -598,10 +784,24 @@ module TreeHaver
         # @return [void]
         def reset!
           instance_variables.each do |ivar|
+            # Don't reset ENV-based values
+            next if %i[@selected_backend @allowed_native_backends @allowed_ruby_backends].include?(ivar)
             remove_instance_variable(ivar) if ivar.to_s.end_with?("_available")
           end
         end
 
+        # Reset selected backend caches (useful for testing with different ENV values)
+        #
+        # Also resets TreeHaver's backend caches.
+        #
+        # @return [void]
+        def reset_selected_backend!
+          remove_instance_variable(:@selected_backend) if defined?(@selected_backend)
+          remove_instance_variable(:@allowed_native_backends) if defined?(@allowed_native_backends)
+          remove_instance_variable(:@allowed_ruby_backends) if defined?(@allowed_ruby_backends)
+          TreeHaver.reset_backend!
+        end
+
         private
 
         # Generic helper to check if a grammar works by parsing test source
@@ -655,6 +855,24 @@ RSpec.configure do |config|
   # Define exclusion filters for optional dependencies
   # Tests tagged with these will be skipped when the dependency is not available
 
+  # ============================================================
+  # Backend Protection for Test Suites
+  # ============================================================
+  #
+  # TreeHaver protects against backend conflicts by default (e.g., FFI cannot
+  # be used after MRI has been loaded because it would cause a segfault).
+  # This protection remains enabled in test suites to prevent crashes.
+  #
+  # If you need to test multiple incompatible backends in the same process
+  # (accepting the risk of segfaults), you can disable protection:
+  #   TREE_HAVER_BACKEND_PROTECT=false bundle exec rspec
+  #
+  # Note: The recommended approach is to run separate test processes for
+  # incompatible backends using RSpec tags or separate CI jobs.
+  if ENV["TREE_HAVER_BACKEND_PROTECT"] == "false"
+    TreeHaver.backend_protect = false
+  end
+
   config.before(:suite) do
     # Print dependency summary if TREE_HAVER_DEBUG is set
     if ENV["TREE_HAVER_DEBUG"]
@@ -759,6 +977,7 @@ RSpec.configure do |config|
     commonmarker: :commonmarker_available?,
     markly: :markly_available?,
     citrus: :citrus_available?,
+    rbs: :rbs_backend_available?,
   }
 
   # Map of backend symbols to their RSpec tag names
@@ -772,6 +991,7 @@ RSpec.configure do |config|
     commonmarker: :commonmarker_backend,
     markly: :markly_backend,
     citrus: :citrus_backend,
+    rbs: :rbs_backend,
   }
 
   # Determine which backends should NOT have availability checked
@@ -793,10 +1013,7 @@ RSpec.configure do |config|
   env_backend = ENV["TREE_HAVER_BACKEND"]
   if env_backend && !env_backend.empty? && env_backend != "auto"
     backend_sym = env_backend.to_sym
-    blockers = TreeHaver::Backends::BLOCKED_BY[backend_sym]
-    if blockers
-      blockers.each { |blocker| blocked_backends << blocker }
-    end
+    TreeHaver::Backends::BLOCKED_BY[backend_sym]&.each { |blocker| blocked_backends << blocker }
   end
 
   # Check which *_backend_only tags are being run and block their conflicting backends
@@ -862,7 +1079,7 @@ RSpec.configure do |config|
   # Tree-Sitter Grammar Tags
   # ============================================================
   # Tags: *_grammar - require a specific tree-sitter grammar (.so file)
-  #   :bash_grammar, :toml_grammar, :json_grammar, :jsonc_grammar
+  #   :bash_grammar, :toml_grammar, :json_grammar, :jsonc_grammar, :rbs_grammar
   #
   # Also: :libtree_sitter - requires the libtree-sitter runtime library
   #
@@ -879,6 +1096,7 @@ RSpec.configure do |config|
     config.filter_run_excluding(toml_grammar: true) unless deps.tree_sitter_toml_available?
     config.filter_run_excluding(json_grammar: true) unless deps.tree_sitter_json_available?
     config.filter_run_excluding(jsonc_grammar: true) unless deps.tree_sitter_jsonc_available?
+    config.filter_run_excluding(rbs_grammar: true) unless deps.tree_sitter_rbs_available?
   end
 
   # ============================================================
@@ -887,6 +1105,7 @@ RSpec.configure do |config|
   # Tags: *_parsing - require ANY parser for a language (any backend that can parse it)
   #   :toml_parsing   - any TOML parser (tree-sitter-toml OR toml-rb/Citrus)
   #   :markdown_parsing - any Markdown parser (commonmarker OR markly)
+  #   :rbs_parsing    - any RBS parser (rbs gem OR tree-sitter-rbs)
   #   :native_parsing - any native tree-sitter backend + grammar
   #
   # NOTE: any_toml_backend_available? calls tree_sitter_toml_available? which
@@ -895,16 +1114,20 @@ RSpec.configure do |config|
   unless isolated_test_mode
     config.filter_run_excluding(toml_parsing: true) unless deps.any_toml_backend_available?
     config.filter_run_excluding(markdown_parsing: true) unless deps.any_markdown_backend_available?
+    config.filter_run_excluding(rbs_parsing: true) unless deps.any_rbs_backend_available?
     config.filter_run_excluding(native_parsing: true) unless deps.any_native_grammar_available?
   end
 
   # ============================================================
   # Specific Library Tags
   # ============================================================
-  # Tags for specific gems/libraries (not backends, but dependencies)
-  #   :toml_rb - the toml-rb gem (Citrus-based TOML parser)
+  # Tags for specific gems/libraries (*_gem suffix)
+  #   :toml_rb_gem - the toml-rb gem (Citrus-based TOML parser)
+  #   :rbs_gem - the rbs gem (official RBS parser, MRI only)
+  #   Note: :rbs_backend is also available as an alias for :rbs_gem
 
-  config.filter_run_excluding(toml_rb: true) unless deps.toml_rb_available?
+  config.filter_run_excluding(toml_rb_gem: true) unless deps.toml_rb_gem_available?
+  config.filter_run_excluding(rbs_gem: true) unless deps.rbs_gem_available?
 
   # ============================================================
   # Negated Tags (run when dependency is NOT available)
@@ -937,12 +1160,15 @@ RSpec.configure do |config|
     config.filter_run_excluding(not_toml_grammar: true) if deps.tree_sitter_toml_available?
     config.filter_run_excluding(not_json_grammar: true) if deps.tree_sitter_json_available?
     config.filter_run_excluding(not_jsonc_grammar: true) if deps.tree_sitter_jsonc_available?
+    config.filter_run_excluding(not_rbs_grammar: true) if deps.tree_sitter_rbs_available?
 
     # Language parsing capabilities
     config.filter_run_excluding(not_toml_parsing: true) if deps.any_toml_backend_available?
     config.filter_run_excluding(not_markdown_parsing: true) if deps.any_markdown_backend_available?
+    config.filter_run_excluding(not_rbs_parsing: true) if deps.any_rbs_backend_available?
   end
 
   # Specific libraries
-  config.filter_run_excluding(not_toml_rb: true) if deps.toml_rb_available?
+  config.filter_run_excluding(not_toml_rb_gem: true) if deps.toml_rb_gem_available?
+  config.filter_run_excluding(not_rbs_gem: true) if deps.rbs_gem_available?
 end

data/lib/tree_haver/version.rb

@@ -10,7 +10,7 @@ module TreeHaver
     # Current version of the tree_haver gem
     #
     # @return [String] the version string (e.g., "3.0.0")
-    VERSION = "3.2.2"
+    VERSION = "3.2.4"
   end
 
   # Traditional location for VERSION constant