tree_haver 3.1.2 → 3.2.1

data/lib/tree_haver/rspec/dependency_tags.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+require "set"
+
 # TreeHaver RSpec Dependency Tags
 #
 # This module provides dependency detection helpers for conditional test execution
@@ -49,49 +51,59 @@
 #     # This test only runs when Psych is available
 #   end
 #
-#   it "requires Commonmarker backend", :commonmarker do
+#   it "requires Commonmarker backend", :commonmarker_backend do
 #     # This test only runs when commonmarker gem is available
 #   end
 #
-#   it "requires Markly backend", :markly do
+#   it "requires Markly backend", :markly_backend do
 #     # This test only runs when markly gem is available
 #   end
 #
-#   it "requires Citrus TOML grammar", :citrus_toml do
-#     # This test only runs when toml-rb with Citrus grammar is available
+#   it "requires Citrus backend", :citrus_backend do
+#     # This test only runs when Citrus gem is available
 #   end
 #
 # @example Language-specific grammar tags (for *-merge gems)
-#   it "requires tree-sitter-bash", :tree_sitter_bash do
+#   it "requires tree-sitter-bash", :bash_grammar do
 #     # This test only runs when bash grammar is available and parsing works
 #   end
 #
-#   it "requires tree-sitter-json", :tree_sitter_json do
+#   it "requires tree-sitter-json", :json_grammar do
 #     # This test only runs when json grammar is available and parsing works
 #   end
 #
-# @example Inner-merge dependencies (for markdown-merge CodeBlockMerger)
-#   it "requires toml-merge", :toml_merge do
-#     # This test only runs when toml-merge is fully functional
-#   end
+# == Available Tags
 #
-#   it "requires prism-merge", :prism_merge do
-#     # This test only runs when prism-merge is fully functional
-#   end
+# === Naming Conventions
 #
-# == Available Tags
+# - `*_backend` = TreeHaver backends (mri, rust, ffi, java, prism, psych, commonmarker, markly, citrus)
+# - `*_engine` = Ruby engines (mri, jruby, truffleruby)
+# - `*_grammar` = tree-sitter grammar files (.so)
+# - `*_parsing` = any parsing capability for a language (combines multiple backends/grammars)
+# - `*_merge` = ast-merge family gems (toml-merge, json-merge, etc.)
 #
 # === Positive Tags (run when dependency IS available)
 #
-# ==== TreeHaver Backend Tags
+# ==== TreeHaver Backend Tags (*_backend)
 #
-# [:ffi]
+# [:ffi_backend]
 #   FFI backend is available. Checked dynamically per-test because FFI becomes
 #   unavailable after MRI backend is used (due to libtree-sitter runtime conflicts).
+#   Legacy alias: :ffi
+#
+# [:ffi_backend_only]
+#   ISOLATED FFI tag - use when running FFI tests in isolation (e.g., ffi_specs task).
+#   Does NOT trigger mri_backend_available? check, preventing MRI from being loaded.
+#   Use this tag for tests that must run before MRI backend is loaded.
 #
 # [:mri_backend]
 #   ruby_tree_sitter gem is available.
 #
+# [:mri_backend_only]
+#   ISOLATED MRI tag - use when running MRI tests and FFI must not be checked.
+#   Does NOT trigger ffi_available? check, preventing FFI availability detection.
+#   Use this tag for tests that should run without FFI interference.
+#
 # [:rust_backend]
 #   tree_stump gem is available.
 #
@@ -104,83 +116,66 @@
 # [:psych_backend]
 #   Psych is available (stdlib, should always be true).
 #
-# [:commonmarker]
+# [:commonmarker_backend]
 #   commonmarker gem is available.
 #
-# [:markly]
+# [:markly_backend]
 #   markly gem is available.
 #
-# [:citrus_toml]
-#   toml-rb gem with Citrus grammar is available.
+# [:citrus_backend]
+#   Citrus gem is available.
 #
-# ==== Ruby Engine Tags
+# ==== Ruby Engine Tags (*_engine)
 #
-# [:jruby]
+# [:mri_engine]
+#   Running on MRI (CRuby).
+#
+# [:jruby_engine]
 #   Running on JRuby.
 #
-# [:truffleruby]
+# [:truffleruby_engine]
 #   Running on TruffleRuby.
 #
-# [:mri]
-#   Running on MRI (CRuby).
-#
-# ==== Grammar/Library Tags
+# ==== Tree-Sitter Grammar Tags (*_grammar)
 #
 # [:libtree_sitter]
 #   libtree-sitter.so is loadable via FFI.
 #
-# [:toml_grammar]
-#   A TOML grammar library is available (via TREE_SITTER_TOML_PATH env var).
-#
-# [:native_parsing]
-#   Both libtree_sitter and toml_grammar are available.
-#
-# ==== Language-Specific Grammar Tags (for *-merge gems)
-#
-# [:tree_sitter_bash]
+# [:bash_grammar]
 #   tree-sitter-bash grammar is available and parsing works.
 #
-# [:tree_sitter_toml]
+# [:toml_grammar]
 #   tree-sitter-toml grammar is available and parsing works.
 #
-# [:tree_sitter_json]
+# [:json_grammar]
 #   tree-sitter-json grammar is available and parsing works.
 #
-# [:tree_sitter_jsonc]
+# [:jsonc_grammar]
 #   tree-sitter-jsonc grammar is available and parsing works.
 #
-# [:toml_rb]
-#   toml-rb gem is available (Citrus backend for TOML).
-#
-# [:toml_backend]
-#   At least one TOML backend (tree-sitter or toml-rb) is available.
-#
-# [:markdown_backend]
-#   At least one markdown backend (markly or commonmarker) is available.
+# ==== Language Parsing Capability Tags (*_parsing)
 #
-# ==== Inner-Merge Dependency Tags (for markdown-merge CodeBlockMerger)
+# [:toml_parsing]
+#   At least one TOML parser (tree-sitter-toml OR toml-rb/Citrus) is available.
 #
-# [:toml_merge]
-#   toml-merge gem is available and functional.
+# [:markdown_parsing]
+#   At least one markdown parser (commonmarker OR markly) is available.
 #
-# [:json_merge]
-#   json-merge gem is available and functional.
+# [:native_parsing]
+#   A native tree-sitter backend and grammar are available.
 #
-# [:prism_merge]
-#   prism-merge gem is available and functional.
+# ==== Specific Library Tags
 #
-# [:psych_merge]
-#   psych-merge gem is available and functional.
+# [:toml_rb]
+#   toml-rb gem is available (Citrus backend for TOML).
 #
 # === 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
-# - :not_jruby, :not_truffleruby, :not_mri
-# - :not_libtree_sitter, :not_toml_grammar
-# - :not_tree_sitter_bash, :not_tree_sitter_toml, :not_tree_sitter_json, :not_tree_sitter_jsonc
-# - :not_toml_rb, :not_toml_backend, :not_markdown_backend
-# - :not_toml_merge, :not_json_merge, :not_prism_merge, :not_psych_merge
+# - :not_mri_backend, :not_rust_backend, :not_java_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
 #
 # == Backend Conflict Protection
 #
@@ -225,6 +220,10 @@ module TreeHaver
         #
         # @return [Boolean] true if FFI backend is usable
         def ffi_available?
+          # 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?
+
           # Try to actually use the FFI backend
           path = find_toml_grammar_path
           return false unless path && File.exist?(path)
@@ -235,10 +234,14 @@ module TreeHaver
           true
         rescue TreeHaver::BackendConflict, TreeHaver::NotAvailable, LoadError
           false
+        rescue StandardError
+          # Catch any other FFI-related errors (e.g., Polyglot::ForeignException)
+          false
         end
 
         # Check if ruby_tree_sitter gem is available (MRI backend)
         #
+        # The MRI backend only works on MRI Ruby (C extension).
         # When this returns true, it also records MRI backend usage with
         # TreeHaver.record_backend_usage(:mri). This is critical for conflict
         # detection - without it, FFI would not know that MRI has been loaded.
@@ -246,8 +249,13 @@ module TreeHaver
         # @return [Boolean] true if ruby_tree_sitter gem is available
         def mri_backend_available?
           return @mri_backend_available if defined?(@mri_backend_available)
+
+          # ruby_tree_sitter is a C extension that only works on MRI
+          return @mri_backend_available = false unless mri?
+
           @mri_backend_available = begin
-            require "ruby_tree_sitter"
+            # Note: gem is ruby_tree_sitter but requires tree_sitter
+            require "tree_sitter"
             # Record that MRI backend is now loaded - this is critical for
             # conflict detection with FFI backend
             TreeHaver.record_backend_usage(:mri)
@@ -257,11 +265,71 @@ module TreeHaver
           end
         end
 
+        # Check if FFI backend is available WITHOUT loading MRI first
+        #
+        # This is used for the :ffi_backend_only tag which runs FFI tests
+        # in isolation before MRI can be loaded. Unlike ffi_available?,
+        # this method does NOT check mri_backend_available?.
+        #
+        # @return [Boolean] true if FFI backend is usable in isolation
+        def ffi_backend_only_available?
+          # TruffleRuby's FFI doesn't support STRUCT_BY_VALUE return types
+          return false if truffleruby?
+
+          # Check if FFI gem is available without loading tree_sitter
+          begin
+            require "ffi"
+          rescue LoadError
+            return false
+          end
+
+          # Try to actually use the FFI backend
+          path = find_toml_grammar_path
+          return false unless path && File.exist?(path)
+
+          TreeHaver.with_backend(:ffi) do
+            TreeHaver::Language.from_library(path, symbol: "tree_sitter_toml")
+          end
+          true
+        rescue TreeHaver::BackendConflict, TreeHaver::NotAvailable, LoadError
+          false
+        rescue StandardError
+          # Catch any other FFI-related errors
+          false
+        end
+
+        # Check if MRI backend is available WITHOUT checking FFI availability
+        #
+        # This is used for the :mri_backend_only tag which runs MRI tests
+        # without triggering any FFI availability checks.
+        #
+        # @return [Boolean] true if MRI backend is usable
+        def mri_backend_only_available?
+          return @mri_backend_only_available if defined?(@mri_backend_only_available)
+
+          # ruby_tree_sitter is a C extension that only works on MRI
+          return @mri_backend_only_available = false unless mri?
+
+          @mri_backend_only_available = begin
+            require "tree_sitter"
+            TreeHaver.record_backend_usage(:mri)
+            true
+          rescue LoadError
+            false
+          end
+        end
+
         # Check if tree_stump gem is available (Rust backend)
         #
+        # The Rust backend only works on MRI Ruby (magnus uses MRI's C API).
+        #
         # @return [Boolean] true if tree_stump gem is available
         def rust_backend_available?
           return @rust_backend_available if defined?(@rust_backend_available)
+
+          # tree_stump uses magnus which requires MRI's C API
+          return @rust_backend_available = false unless mri?
+
           @rust_backend_available = begin
             require "tree_stump"
             true
@@ -289,6 +357,10 @@ module TreeHaver
             true
           rescue TreeHaver::NotAvailable, LoadError
             false
+          rescue StandardError
+            # TruffleRuby raises Polyglot::ForeignException when FFI
+            # encounters unsupported types like STRUCT_BY_VALUE
+            false
           end
         end
 
@@ -306,9 +378,18 @@ module TreeHaver
         # Grammar paths should be configured via TREE_SITTER_TOML_PATH environment variable.
         # This keeps configuration explicit and avoids magic path guessing.
         #
-        # @return [String, nil] path from environment variable, or nil if not set
+        # @return [String, nil] path to TOML grammar library, or nil if not found
         def find_toml_grammar_path
-          ENV["TREE_SITTER_TOML_PATH"]
+          # First check environment variable
+          env_path = ENV["TREE_SITTER_TOML_PATH"]
+          return env_path if env_path && File.exist?(env_path)
+
+          # Use GrammarFinder to search standard paths
+          finder = TreeHaver::GrammarFinder.new(:toml, validate: false)
+          finder.find_library_path
+        rescue StandardError
+          # GrammarFinder might not be available or might fail
+          nil
         end
 
         # Check if commonmarker gem is available
@@ -343,22 +424,14 @@ module TreeHaver
           @psych_available = TreeHaver::Backends::Psych.available?
         end
 
-        # Check if toml-rb with Citrus grammar is available
+        # Check if Citrus backend is available
         #
-        # @return [Boolean] true if toml-rb gem with Citrus grammar is available
-        def citrus_toml_available?
-          return @citrus_toml_available if defined?(@citrus_toml_available)
-          @citrus_toml_available = begin
-            require "toml-rb"
-            finder = TreeHaver::CitrusGrammarFinder.new(
-              language: :toml,
-              gem_name: "toml-rb",
-              grammar_const: "TomlRB::Document",
-            )
-            finder.available?
-          rescue LoadError, NameError
-            false
-          end
+        # This checks if the citrus gem is installed and the backend works.
+        #
+        # @return [Boolean] true if Citrus backend is available
+        def citrus_available?
+          return @citrus_available if defined?(@citrus_available)
+          @citrus_available = TreeHaver::Backends::Citrus.available?
         end
 
         # ============================================================
@@ -423,16 +496,20 @@ module TreeHaver
           @tree_sitter_jsonc_available = grammar_works?(:jsonc, '{"key": "value" /* comment */}')
         end
 
-        # Check if toml-rb gem is available (Citrus backend for TOML)
+        # Check if toml-rb gem is available and functional (Citrus backend for TOML)
         #
-        # @return [Boolean] true if toml-rb gem is available
+        # @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
             require "toml-rb"
+            # Verify it can actually parse - just requiring isn't enough
+            TomlRB.parse('key = "value"')
             true
           rescue LoadError
             false
+          rescue StandardError
+            false
           end
         end
 
@@ -450,41 +527,13 @@ module TreeHaver
           markly_available? || commonmarker_available?
         end
 
-        # ============================================================
-        # Inner-Merge Dependencies (for markdown-merge CodeBlockMerger)
-        # These check both gem availability AND backend functionality
-        # ============================================================
-
-        # Check if toml-merge is available and functional
-        #
-        # @return [Boolean] true if toml-merge works
-        def toml_merge_available?
-          return @toml_merge_available if defined?(@toml_merge_available)
-          @toml_merge_available = inner_merge_works?("toml/merge", "Toml::Merge::SmartMerger", "key = 'test'")
-        end
-
-        # Check if json-merge is available and functional
-        #
-        # @return [Boolean] true if json-merge works
-        def json_merge_available?
-          return @json_merge_available if defined?(@json_merge_available)
-          @json_merge_available = inner_merge_works?("json/merge", "Json::Merge::SmartMerger", '{"a":1}')
-        end
-
-        # Check if prism-merge is available and functional
-        #
-        # @return [Boolean] true if prism-merge works
-        def prism_merge_available?
-          return @prism_merge_available if defined?(@prism_merge_available)
-          @prism_merge_available = inner_merge_works?("prism/merge", "Prism::Merge::SmartMerger", "puts 1")
-        end
-
-        # Check if psych-merge is available and functional
-        #
-        # @return [Boolean] true if psych-merge works
-        def psych_merge_available?
-          return @psych_merge_available if defined?(@psych_merge_available)
-          @psych_merge_available = inner_merge_works?("psych/merge", "Psych::Merge::SmartMerger", "key: value")
+        def any_native_grammar_available?
+          libtree_sitter_available? && (
+            tree_sitter_bash_available? ||
+              tree_sitter_toml_available? ||
+              tree_sitter_json_available? ||
+              tree_sitter_jsonc_available?
+          )
         end
 
         # ============================================================
@@ -496,37 +545,33 @@ module TreeHaver
         # @return [Hash{Symbol => Boolean}] map of dependency name to availability
         def summary
           {
-            # TreeHaver backends
-            ffi: ffi_available?,
+            # TreeHaver backends (*_backend)
+            ffi_backend: ffi_available?,
             mri_backend: mri_backend_available?,
             rust_backend: rust_backend_available?,
             java_backend: java_backend_available?,
-            prism: prism_available?,
-            psych: psych_available?,
-            commonmarker: commonmarker_available?,
-            markly: markly_available?,
-            citrus_toml: citrus_toml_available?,
-            # Libraries
-            libtree_sitter: libtree_sitter_available?,
-            toml_grammar: toml_grammar_available?,
-            # Ruby engines
+            prism_backend: prism_available?,
+            psych_backend: psych_available?,
+            commonmarker_backend: commonmarker_available?,
+            markly_backend: markly_available?,
+            citrus_backend: citrus_available?,
+            # Ruby engines (*_engine)
             ruby_engine: RUBY_ENGINE,
-            jruby: jruby?,
-            truffleruby: truffleruby?,
-            mri: mri?,
-            # Language grammars
-            tree_sitter_bash: tree_sitter_bash_available?,
-            tree_sitter_toml: tree_sitter_toml_available?,
-            tree_sitter_json: tree_sitter_json_available?,
-            tree_sitter_jsonc: tree_sitter_jsonc_available?,
+            mri_engine: mri?,
+            jruby_engine: jruby?,
+            truffleruby_engine: truffleruby?,
+            # Tree-sitter grammars (*_grammar)
+            libtree_sitter: libtree_sitter_available?,
+            bash_grammar: tree_sitter_bash_available?,
+            toml_grammar: tree_sitter_toml_available?,
+            json_grammar: tree_sitter_json_available?,
+            jsonc_grammar: tree_sitter_jsonc_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?,
-            any_toml_backend: any_toml_backend_available?,
-            any_markdown_backend: any_markdown_backend_available?,
-            # Inner-merge dependencies
-            toml_merge: toml_merge_available?,
-            json_merge: json_merge_available?,
-            prism_merge: prism_merge_available?,
-            psych_merge: psych_merge_available?,
           }
         end
 
@@ -598,21 +643,6 @@ module TreeHaver
           end
           false
         end
-
-        # Generic helper to check if an inner-merge gem is available and functional
-        #
-        # @param require_path [String] the require path for the gem
-        # @param merger_class [String] the full class name of the SmartMerger
-        # @param test_source [String] sample source code to test merging
-        # @return [Boolean] true if the merger can be instantiated
-        def inner_merge_works?(require_path, merger_class, test_source)
-          require require_path
-          klass = Object.const_get(merger_class)
-          klass.new(test_source, test_source)
-          true
-        rescue LoadError, NameError, TreeHaver::Error, TreeHaver::NotAvailable
-          false
-        end
       end
     end
   end
@@ -633,14 +663,23 @@ RSpec.configure do |config|
         puts "  #{var}: #{value.inspect}"
       end
 
-      puts "\n=== TreeHaver Test Dependencies ==="
-      deps.summary.each do |dep, available|
-        status = case available
-        when true then "✓ available"
-        when false then "✗ not available"
-        else available.to_s
+      # Only print full dependency summary if we're not running with blocked backends
+      # The summary calls grammar availability checks which would load blocked backends
+      current_blocked = TreeHaver::RSpec::DependencyTags.instance_variable_get(:@blocked_backends) || Set.new
+      if current_blocked.any?
+        puts "\n=== TreeHaver Test Dependencies (limited - running isolated tests) ==="
+        puts "  blocked_backends: #{current_blocked.to_a.inspect}"
+        puts "  (Skipping full summary to avoid loading blocked backends)"
+      else
+        puts "\n=== TreeHaver Test Dependencies ==="
+        deps.summary.each do |dep, available|
+          status = case available
+          when true then "✓ available"
+          when false then "✗ not available"
+          else available.to_s
+          end
+          puts "  #{dep}: #{status}"
         end
-        puts "  #{dep}: #{status}"
       end
       puts "===================================\n"
     end
@@ -649,96 +688,237 @@ RSpec.configure do |config|
   # ============================================================
   # TreeHaver Backend Tags
   # ============================================================
+  # Tags: *_backend - require a specific TreeHaver backend to be available
+  #
+  # Native backends (load .so files):
+  #   :ffi_backend, :mri_backend, :rust_backend, :java_backend
+  # Pure-Ruby backends:
+  #   :prism_backend, :psych_backend, :commonmarker_backend, :markly_backend, :citrus_backend
+  #
+  # Isolated backend tags (for running tests without loading conflicting backends):
+  #   :ffi_backend_only - runs FFI tests without loading MRI backend
+  #   :mri_backend_only - runs MRI tests without checking FFI availability
+
+  # FFI backend exclusion:
+  # If MRI has already been used, FFI is blocked and will never be available.
+  # In this case, exclude FFI tests tagged with :ffi_backend entirely rather than
+  # showing them as pending.
+  #
+  # NOTE: We do NOT exclude :ffi_backend_only here because the Rakefile uses
+  # `--tag ~ffi_backend_only` for the remaining_specs task. RSpec interprets
+  # `--tag ~X` as an include filter with key "~X", which conflicts with
+  # filter_run_excluding. Instead, :ffi_backend_only tests will be skipped
+  # via the before(:each) hook below when FFI is not available.
+  if TreeHaver.backends_used.include?(:mri)
+    config.filter_run_excluding(ffi_backend: true)
+  end
 
   # FFI availability is checked dynamically per-test (not at load time)
   # because FFI becomes unavailable after MRI backend is used.
-  config.before(:each, :ffi) do
+  # When running with :ffi_backend_only tag, this hook defers to the isolated check.
+  config.before(:each, :ffi_backend) do |example|
+    # If also tagged with :ffi_backend_only, let that hook handle the check
+    next if example.metadata[:ffi_backend_only]
+
     skip "FFI backend not available (MRI backend may have been used)" unless deps.ffi_available?
   end
 
-  config.filter_run_excluding(mri_backend: true) unless deps.mri_backend_available?
-  config.filter_run_excluding(rust_backend: true) unless deps.rust_backend_available?
-  config.filter_run_excluding(java_backend: true) unless deps.java_backend_available?
-  config.filter_run_excluding(prism_backend: true) unless deps.prism_available?
-  config.filter_run_excluding(psych_backend: true) unless deps.psych_available?
-  config.filter_run_excluding(commonmarker: true) unless deps.commonmarker_available?
-  config.filter_run_excluding(markly: true) unless deps.markly_available?
-  config.filter_run_excluding(citrus_toml: true) unless deps.citrus_toml_available?
+  # ISOLATED FFI TAG: Checked dynamically but does NOT trigger mri_backend_available?
+  # Use this tag for tests that must run before MRI is loaded (e.g., in ffi_specs task)
+  config.before(:each, :ffi_backend_only) do
+    skip "FFI backend not available (isolated check)" unless deps.ffi_backend_only_available?
+  end
+
+  # ISOLATED MRI TAG: Checked dynamically but does NOT trigger ffi_available?
+  # Use this tag for tests that should run without FFI interference
+  config.before(:each, :mri_backend_only) do
+    skip "MRI backend not available (isolated check)" unless deps.mri_backend_only_available?
+  end
 
   # ============================================================
-  # Ruby Engine Tags
+  # Dynamic Backend Exclusions (using BLOCKED_BY)
   # ============================================================
+  # When running with *_backend_only tags, we skip availability checks for
+  # backends that would block the isolated backend. This prevents loading
+  # conflicting backends before isolated tests run.
+  #
+  # For example, when running with --tag ffi_backend_only:
+  # - FFI is blocked by [:mri] (from BLOCKED_BY)
+  # - So we skip mri_backend_available? to prevent loading MRI
+  #
+  # This is dynamic based on TreeHaver::Backends::BLOCKED_BY configuration.
+
+  # Map of backend symbols to their availability check methods
+  backend_availability_methods = {
+    mri: :mri_backend_available?,
+    rust: :rust_backend_available?,
+    ffi: :ffi_available?,
+    java: :java_backend_available?,
+    prism: :prism_available?,
+    psych: :psych_available?,
+    commonmarker: :commonmarker_available?,
+    markly: :markly_available?,
+    citrus: :citrus_available?,
+  }
+
+  # Map of backend symbols to their RSpec tag names
+  backend_tags = {
+    mri: :mri_backend,
+    rust: :rust_backend,
+    ffi: :ffi_backend,
+    java: :java_backend,
+    prism: :prism_backend,
+    psych: :psych_backend,
+    commonmarker: :commonmarker_backend,
+    markly: :markly_backend,
+    citrus: :citrus_backend,
+  }
+
+  # Determine which backends should NOT have availability checked
+  # based on which *_backend_only tag is being run
+  blocked_backends = Set.new
+
+  # Check which *_backend_only tags are being run and block their conflicting backends
+  # config.inclusion_filter contains tags passed via --tag on command line
+  inclusion_rules = config.inclusion_filter.rules
+
+  # If filter.rules is empty, check ARGV directly for --tag options
+  # This handles the case where RSpec hasn't processed filters yet during configuration
+  if inclusion_rules.empty?
+    ARGV.each_with_index do |arg, i|
+      if arg == "--tag" && ARGV[i + 1]
+        tag_str = ARGV[i + 1]
+        # Skip exclusion tags (prefixed with ~) - they are NOT inclusion filters
+        next if tag_str.start_with?("~")
+        tag_value = tag_str.to_sym
+        inclusion_rules[tag_value] = true
+      elsif arg.start_with?("--tag=")
+        tag_str = arg.sub("--tag=", "")
+        # Skip exclusion tags (prefixed with ~) - they are NOT inclusion filters
+        next if tag_str.start_with?("~")
+        tag_value = tag_str.to_sym
+        inclusion_rules[tag_value] = true
+      end
+    end
+  end
+
+  TreeHaver::Backends::BLOCKED_BY.each do |backend, blockers|
+    # Check if we're running this backend's isolated tests
+    isolated_tag = :"#{backend}_backend_only"
+    if inclusion_rules[isolated_tag]
+      # Add all backends that would block this one
+      blockers.each { |blocker| blocked_backends << blocker }
+    end
+  end
+
+  # Store blocked_backends in a module variable so before(:suite) can access it
+  TreeHaver::RSpec::DependencyTags.instance_variable_set(:@blocked_backends, blocked_backends)
+
+  # Now configure exclusions, skipping availability checks for blocked backends
+  backend_tags.each do |backend, tag|
+    next if blocked_backends.include?(backend)
 
-  config.filter_run_excluding(jruby: true) unless deps.jruby?
-  config.filter_run_excluding(truffleruby: true) unless deps.truffleruby?
-  config.filter_run_excluding(mri: true) unless deps.mri?
+    # FFI is handled specially with before(:each) hook above
+    next if backend == :ffi
+
+    availability_method = backend_availability_methods[backend]
+    config.filter_run_excluding(tag => true) unless deps.public_send(availability_method)
+  end
 
   # ============================================================
-  # Library/Grammar Tags
+  # Ruby Engine Tags
   # ============================================================
+  # Tags: *_engine - require a specific Ruby engine
+  #   :mri_engine, :jruby_engine, :truffleruby_engine
 
-  config.filter_run_excluding(libtree_sitter: true) unless deps.libtree_sitter_available?
-  config.filter_run_excluding(toml_grammar: true) unless deps.toml_grammar_available?
-  config.filter_run_excluding(native_parsing: true) unless deps.libtree_sitter_available? && deps.toml_grammar_available?
+  config.filter_run_excluding(mri_engine: true) unless deps.mri?
+  config.filter_run_excluding(jruby_engine: true) unless deps.jruby?
+  config.filter_run_excluding(truffleruby_engine: true) unless deps.truffleruby?
 
   # ============================================================
-  # Language-Specific Grammar Tags
+  # Tree-Sitter Grammar Tags
   # ============================================================
+  # Tags: *_grammar - require a specific tree-sitter grammar (.so file)
+  #   :bash_grammar, :toml_grammar, :json_grammar, :jsonc_grammar
+  #
+  # Also: :libtree_sitter - requires the libtree-sitter runtime library
+  #
+  # NOTE: When running with *_backend_only tags, we skip these checks to avoid
+  # loading blocked backends. The grammar checks use TreeHaver.parser_for which
+  # would load the default backend (MRI) and block FFI.
+
+  # Skip grammar availability checks if any backend is blocked
+  # (i.e., we're running isolated backend tests)
+  if blocked_backends.none?
+    config.filter_run_excluding(libtree_sitter: true) unless deps.libtree_sitter_available?
+    config.filter_run_excluding(bash_grammar: true) unless deps.tree_sitter_bash_available?
+    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?
+  end
 
-  config.filter_run_excluding(tree_sitter_bash: true) unless deps.tree_sitter_bash_available?
-  config.filter_run_excluding(tree_sitter_toml: true) unless deps.tree_sitter_toml_available?
-  config.filter_run_excluding(tree_sitter_json: true) unless deps.tree_sitter_json_available?
-  config.filter_run_excluding(tree_sitter_jsonc: true) unless deps.tree_sitter_jsonc_available?
-  config.filter_run_excluding(toml_rb: true) unless deps.toml_rb_available?
-  config.filter_run_excluding(toml_backend: true) unless deps.any_toml_backend_available?
-  config.filter_run_excluding(markdown_backend: true) unless deps.any_markdown_backend_available?
+  # ============================================================
+  # Language Parsing Capability Tags
+  # ============================================================
+  # 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)
+  #   :native_parsing - any native tree-sitter backend + grammar
+  #
+  # NOTE: any_toml_backend_available? calls tree_sitter_toml_available? which
+  # triggers grammar_works? and loads MRI. Skip when running isolated tests.
+
+  if blocked_backends.none?
+    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(native_parsing: true) unless deps.any_native_grammar_available?
+  end
 
   # ============================================================
-  # Inner-Merge Dependency Tags
+  # Specific Library Tags
   # ============================================================
+  # Tags for specific gems/libraries (not backends, but dependencies)
+  #   :toml_rb - the toml-rb gem (Citrus-based TOML parser)
 
-  config.filter_run_excluding(toml_merge: true) unless deps.toml_merge_available?
-  config.filter_run_excluding(json_merge: true) unless deps.json_merge_available?
-  config.filter_run_excluding(prism_merge: true) unless deps.prism_merge_available?
-  config.filter_run_excluding(psych_merge: true) unless deps.psych_merge_available?
+  config.filter_run_excluding(toml_rb: true) unless deps.toml_rb_available?
 
   # ============================================================
   # Negated Tags (run when dependency is NOT available)
   # ============================================================
+  # Prefix: not_* - exclude tests when the dependency IS available
 
-  # NOTE: :not_ffi tag is not provided because FFI availability is dynamic.
+  # NOTE: :not_ffi_backend tag is not provided because FFI availability is dynamic.
 
-  # TreeHaver backends
-  config.filter_run_excluding(not_mri_backend: true) if deps.mri_backend_available?
-  config.filter_run_excluding(not_rust_backend: true) if deps.rust_backend_available?
-  config.filter_run_excluding(not_java_backend: true) if deps.java_backend_available?
-  config.filter_run_excluding(not_prism_backend: true) if deps.prism_available?
-  config.filter_run_excluding(not_psych_backend: true) if deps.psych_available?
-  config.filter_run_excluding(not_commonmarker: true) if deps.commonmarker_available?
-  config.filter_run_excluding(not_markly: true) if deps.markly_available?
-  config.filter_run_excluding(not_citrus_toml: true) if deps.citrus_toml_available?
+  # TreeHaver backends - handled dynamically to respect blocked backends
+  backend_tags.each do |backend, tag|
+    next if blocked_backends.include?(backend)
+
+    # FFI is handled specially (availability is always dynamic)
+    next if backend == :ffi
+
+    negated_tag = :"not_#{tag}"
+    availability_method = backend_availability_methods[backend]
+    config.filter_run_excluding(negated_tag => true) if deps.public_send(availability_method)
+  end
 
   # Ruby engines
-  config.filter_run_excluding(not_jruby: true) if deps.jruby?
-  config.filter_run_excluding(not_truffleruby: true) if deps.truffleruby?
-  config.filter_run_excluding(not_mri: true) if deps.mri?
-
-  # Libraries/grammars
-  config.filter_run_excluding(not_libtree_sitter: true) if deps.libtree_sitter_available?
-  config.filter_run_excluding(not_toml_grammar: true) if deps.toml_grammar_available?
-
-  # Language grammars
-  config.filter_run_excluding(not_tree_sitter_bash: true) if deps.tree_sitter_bash_available?
-  config.filter_run_excluding(not_tree_sitter_toml: true) if deps.tree_sitter_toml_available?
-  config.filter_run_excluding(not_tree_sitter_json: true) if deps.tree_sitter_json_available?
-  config.filter_run_excluding(not_tree_sitter_jsonc: true) if deps.tree_sitter_jsonc_available?
+  config.filter_run_excluding(not_mri_engine: true) if deps.mri?
+  config.filter_run_excluding(not_jruby_engine: true) if deps.jruby?
+  config.filter_run_excluding(not_truffleruby_engine: true) if deps.truffleruby?
+
+  # Tree-sitter grammars - skip when running isolated backend tests
+  if blocked_backends.none?
+    config.filter_run_excluding(not_libtree_sitter: true) if deps.libtree_sitter_available?
+    config.filter_run_excluding(not_bash_grammar: true) if deps.tree_sitter_bash_available?
+    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?
+
+    # 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?
+  end
+
+  # Specific libraries
   config.filter_run_excluding(not_toml_rb: true) if deps.toml_rb_available?
-  config.filter_run_excluding(not_toml_backend: true) if deps.any_toml_backend_available?
-  config.filter_run_excluding(not_markdown_backend: true) if deps.any_markdown_backend_available?
-
-  # Inner-merge dependencies
-  config.filter_run_excluding(not_toml_merge: true) if deps.toml_merge_available?
-  config.filter_run_excluding(not_json_merge: true) if deps.json_merge_available?
-  config.filter_run_excluding(not_prism_merge: true) if deps.prism_merge_available?
-  config.filter_run_excluding(not_psych_merge: true) if deps.psych_merge_available?
 end