tree_haver 7.1.8 → 7.1.10

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: dd8a2bf5d9e6895f75c2fb3e686b1c9ff857327f9c2204415e321376a6f9b080
-  data.tar.gz: bf8489bd8e6205fbb950e67699dc6aec5d90de8a986646e1faeec6477c1e75a5
+  metadata.gz: c442758cd9e4d17f3088f4b501db45cae5a6b041db3fa3a31797bd2021b1a486
+  data.tar.gz: 33741a50778080021bdd02e11e87fe03f54e5631a2032d6dd51ab2a8c1434a1b
 SHA512:
-  metadata.gz: 598312346e2540cada502c8b50d660ce22bc59fc1a77991e56e025ad3bd68c7e629db880cccb9bf2f8b48b61693c44f0392251ddb31c0b411325b5189f8df71b
-  data.tar.gz: a0dd401a8237aa13bcae96111bc17ef3cc245b94cbb0124258413eb0d0f2d78cc7cf1cd32db50ec842d6137677f8d5067b7549743c5e1a6e457dbdafd8a290a7
+  metadata.gz: fcf407fba26bdba32f80ecebf92b6d946a6c176f187da0a6ee928e877723cd97a5bcca732811bf5695c8bb112a5b75614768f9e3d57cd9bcf4b50807e14fa390
+  data.tar.gz: f210d2e7d3673870097c56a22a2380a51a98620c2c39a6bf00ad2b66f54e4e96837ee26bc57caf8151eb0ae134d6e519090d9d1c15429c1a160e2e2d646e6468

data/lib/tree_haver/backends/ffi.rb

@@ -613,7 +613,7 @@ module TreeHaver
           ok = Native.ts_parser_set_language(@parser, ptr)
           raise TreeHaver::NotAvailable, 'Failed to set language on parser' unless ok
 
-          lang # rubocop:disable Lint/Void (intentional return value)
+          lang # (intentional return value)
         end
 
         # Parse source code into a syntax tree

data/lib/tree_haver/backends/rust.rb

@@ -207,7 +207,7 @@ module TreeHaver
           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 # rubocop:disable Lint/Void (intentional return value)
+          lang # (intentional return value)
         end
 
         # Parse source code

data/lib/tree_haver/backends/rust_tslp.rb

@@ -0,0 +1,301 @@
+# frozen_string_literal: true
+
+require 'json'
+require 'digest'
+
+module TreeHaver
+  module Backends
+    # Explicit Magnus bridge to the canonical Rust TreeHaver/TSLP substrate.
+    #
+    # This backend deliberately exposes only the normalized tree contract. It
+    # does not replace the direct Ruby language-pack or tree_stump backends.
+    module RustTslp
+      class << self
+        attr_reader :unavailable_reason
+
+        def available?
+          return @loaded if @load_attempted
+
+          @load_attempted = true
+          @loaded = load_host
+        end
+
+        def reset!
+          @load_attempted = false
+          @loaded = false
+          @unavailable_reason = nil
+        end
+
+        def capabilities
+          return {} unless available?
+
+          {
+            backend: :rust_tslp,
+            query: false,
+            bytes_field: true,
+            incremental: false,
+            comment_support: :nodes_only,
+            language_pack: true,
+            provenance: :rust_tree_haver
+          }
+        end
+
+        def register_language_parser(language)
+          return unless available?
+
+          # Cache only registrations made by this adapter, never adopt a foreign
+          # duplicate ID. An external removal therefore fails closed on parse.
+          REGISTRATION_MUTEX.synchronize do
+            @registrations ||= {}
+            key = [::StructuredmergeCore, language.to_s]
+            @registrations[key] ||= ::StructuredmergeCore.register_language_pack_parser(
+              "tree_haver.rust_tslp.#{language}", language.to_s
+            ).id
+          end
+        end
+
+        private
+
+        # rubocop:disable Metrics/MethodLength
+        def load_host
+          unless RUBY_ENGINE == 'ruby'
+            @unavailable_reason = 'the Rust TreeHaver Magnus bridge requires MRI Ruby'
+            return false
+          end
+
+          require 'structuredmerge_core' unless defined?(::StructuredmergeCore)
+          unless ::StructuredmergeCore.respond_to?(:parse_sources) && ::StructuredmergeCore.respond_to?(:register_language_pack_parser)
+            @unavailable_reason = 'structuredmerge-core does not expose typed Rust parser registration'
+            return false
+          end
+
+          true
+        rescue LoadError => e
+          @unavailable_reason = e.message
+          false
+        rescue StandardError => e
+          @unavailable_reason = e.message
+          false
+        end
+        # rubocop:enable Metrics/MethodLength
+      end
+
+      REGISTRATION_MUTEX = Mutex.new
+
+      # Identifies a language parsed by the canonical Rust substrate.
+      class Language < TreeHaver::Base::Language
+        def initialize(name)
+          super(name, backend: :rust_tslp, options: {})
+        end
+
+        class << self
+          def from_library(_path = nil, symbol: nil, name: nil) # rubocop:disable Lint/UnusedMethodArgument
+            new(name || :unknown)
+          end
+        end
+      end
+
+      # Parses source into the Rust normalized tree representation.
+      class Parser < TreeHaver::Base::Parser
+        # rubocop:disable Metrics/AbcSize, Metrics/MethodLength
+        def parse(source)
+          raise TreeHaver::NotAvailable, unavailable_message unless RustTslp.available?
+          raise TreeHaver::NotAvailable, 'Rust TSLP language is not set' unless language
+
+          normalized_source = normalize_source_encoding(source)
+          core = ::StructuredmergeCore
+          provider_id = RustTslp.register_language_parser(language.name)
+          crlf = normalized_source.scan("\r\n").length
+          descriptor = core::SourceDescriptor.new(
+            source_id: 'tree_haver.source', role: 'source', byte_length: normalized_source.bytesize,
+            sha256: Digest::SHA256.hexdigest(normalized_source), encoding: 'utf8',
+            bom: normalized_source.start_with?("\uFEFF"), final_newline: normalized_source.end_with?("\n", "\r"),
+            line_endings: core::LineEndings.new(lf: normalized_source.count("\n") - crlf,
+                                                crlf: crlf, bare_cr: normalized_source.count("\r") - crlf)
+          )
+          request = core::ParseRequest.new(
+            schema: 'structuredmerge.parse-request/v1', request_id: 'tree_haver.parse',
+            source: core::SourceInput.new(descriptor: descriptor, bytes: normalized_source.bytes),
+            language: language.name.to_s, dialect: nil,
+            selection: core::ParserSelection.new(backend_id: provider_id, preference: [], required_capabilities: []),
+            options: core::ParseOptions.new(comments: true, diagnostics: true, tokens: false, native_extensions: true),
+            metadata: {}, extra: {}
+          )
+          limits = core::ParseLimits.new(max_batch_items: 1, max_input_bytes: 64 * 1024 * 1024,
+                                         max_nodes: 1_000_000, max_diagnostics: 1000)
+          result = core.parse_sources([request], limits).fetch(0)
+          Tree.new(result, source: normalized_source, language: language.name)
+        end
+        # rubocop:enable Metrics/AbcSize, Metrics/MethodLength
+
+        private
+
+        def normalize_source_encoding(source)
+          if [Encoding::UTF_8, Encoding::BINARY, Encoding::US_ASCII].include?(source.encoding)
+            utf8 = source.dup.force_encoding(Encoding::UTF_8)
+            return utf8.freeze if utf8.valid_encoding?
+          end
+
+          raise TreeHaver::NotAvailable, 'Rust TreeHaver normalized parsing requires valid UTF-8 source bytes'
+        end
+
+        def unavailable_message
+          detail = RustTslp.unavailable_reason.to_s
+          detail = 'unknown reason' if detail.empty?
+          "Rust TreeHaver normalized parser is unavailable: #{detail}"
+        end
+      end
+
+      # Wraps one validated Rust normalized parse result.
+      class Tree < TreeHaver::Base::Tree
+        attr_reader :diagnostics, :language, :provenance
+
+        def initialize(result, source:, language:)
+          validate_result!(result)
+          super(result, source: source)
+          @language = language.to_s
+          @nodes_by_id = result.parsed.nodes.to_h { |node| [node.id, node] }
+          @root_id = result.parsed.root_id
+          @diagnostics = result.parsed.diagnostics.map(&:message)
+          @provenance = {
+            'backend_ref' => { 'id' => result.backend.id },
+            'language' => @language, 'runtime' => result.backend.runtime,
+            'parser' => result.backend.parser, 'parser_version' => result.backend.parser_version
+          }
+        end
+
+        def root_node
+          Node.new(
+            @nodes_by_id.fetch(@root_id),
+            nodes_by_id: @nodes_by_id,
+            source: source,
+            lines: lines,
+            language: language
+          )
+        end
+
+        def errors
+          diagnostics
+        end
+
+        private
+
+        def validate_result!(result)
+          nodes = result.parsed.nodes
+          root_id = result.parsed.root_id
+          valid_root = root_id.is_a?(String) && nodes.any? { |node| node.id == root_id }
+          return if valid_root
+
+          raise TreeHaver::Error, 'Rust TreeHaver returned an invalid normalized tree'
+        end
+      end
+
+      # Adapts normalized node records to TreeHaver's node contract.
+      class Node < TreeHaver::Base::Node
+        # Preserve the established TreeHaver surface when the two language-pack
+        # implementations expose equivalent JSON5 grammar nodes under different
+        # native names.
+        NODE_TYPE_ALIASES = {
+          'json5' => {
+            'file' => 'document',
+            'member' => 'pair'
+          }
+        }.freeze
+
+        attr_reader :language
+
+        def initialize(node, nodes_by_id:, source: nil, lines: nil, language: nil)
+          super(node, source: source, lines: lines)
+          @nodes_by_id = nodes_by_id
+          @language = language.to_s
+        end
+
+        def type
+          NODE_TYPE_ALIASES.fetch(language, {}).fetch(native_type, native_type)
+        end
+
+        def native_type = inner_node.native_type
+
+        def start_byte = span.range.start_byte
+        def end_byte = span.range.end_byte
+        def start_point = symbolize_point(span.start_point)
+        def end_point = symbolize_point(span.end_point)
+        def child_count = inner_node.children.length
+        def named? = inner_node.named
+
+        def has_error? # rubocop:disable Naming/PredicatePrefix
+          inner_node.has_error
+        end
+
+        def error? = has_error?
+        def missing? = inner_node.missing
+
+        def extra?
+          extension = inner_node.extensions.find do |item|
+            item.schema == 'tree-haver.tree-sitter.node/v1' && item.namespace == 'tree-sitter'
+          end
+          raise TreeHaver::Error, 'Rust TreeHaver omitted native node flags' unless extension
+
+          # Alef transports only the open extension payload as JSON, not the tree.
+          JSON.parse(extension.payload).fetch('extra')
+        end
+
+        def text
+          source.byteslice(start_byte...end_byte)
+        end
+
+        def child(index)
+          edge = inner_node.children[index]
+          edge && wrap(@nodes_by_id.fetch(edge.node_id))
+        end
+
+        def children
+          inner_node.children.map { |edge| wrap(@nodes_by_id.fetch(edge.node_id)) }
+        end
+
+        def child_by_field_name(name)
+          edge = inner_node.children.find { |item| item.field_name == name.to_s }
+          edge && wrap(@nodes_by_id.fetch(edge.node_id))
+        end
+
+        def parent
+          parent_id = inner_node.parent_id
+          parent_id && wrap(@nodes_by_id.fetch(parent_id))
+        end
+
+        def next_sibling
+          sibling_at(1)
+        end
+
+        def prev_sibling
+          sibling_at(-1)
+        end
+
+        private
+
+        def span = inner_node.span
+
+        def symbolize_point(point)
+          { row: point.row, column: point.column }
+        end
+
+        def wrap(node)
+          self.class.new(node, nodes_by_id: @nodes_by_id, source: source, lines: lines, language: language)
+        end
+
+        def sibling_at(offset)
+          parent_node = parent
+          return unless parent_node
+
+          siblings = parent_node.inner_node.children.map(&:node_id)
+          index = siblings.index(inner_node.id)
+          sibling_index = index&.+(offset)
+          return unless sibling_index&.between?(0, siblings.length - 1)
+
+          sibling_id = siblings[sibling_index]
+          sibling_id && wrap(@nodes_by_id.fetch(sibling_id))
+        end
+      end
+    end
+  end
+end

data/lib/tree_haver/backends/tslp.rb

@@ -8,11 +8,20 @@ module TreeHaver
     # process API is not a TreeHaver parser backend and must not be used as a
     # merge-gem integration surface.
     module Tslp
-      @load_attempted = false
+      # Transient grammar hot-load failures (for example a failed on-demand
+      # download of the tree-sitter-language-pack bundle) are retried on later
+      # availability probes instead of latching for the whole process. After
+      # this many consecutive transient failures the backend latches as
+      # unavailable so a dead network cannot slow every later parse attempt.
+      TRANSIENT_FAILURE_RETRY_LIMIT = 3
+
       @loaded = false
+      @permanently_unavailable = false
+      @transient_failures = 0
       @unavailable_reason = nil
       @language_availability = {}
       @language_unavailable_reasons = {}
+      @language_attempts = {}
       PARSER_SMOKE_SOURCES = {
         'json' => '{}',
         'json5' => '{}',
@@ -28,35 +37,91 @@ module TreeHaver
       }.freeze
       DEFAULT_PARSER_SMOKE_SOURCE = ''
 
+      # Grammar hot-load failures caused by the on-demand bundle download
+      # (network flake, transient GitHub release fetch failure, cache lock
+      # contention) must not latch the backend for the whole process.
+      TRANSIENT_FAILURE_PATTERN = /
+        Download\ error
+        | Download\ cache\ lock\ error
+        | Failed\ to\ fetch\ manifest
+        | Failed\ to\ download
+        | Failed\ to\ read\ (cached|download)
+        | connection\ (refused|reset)
+        | timed?\ out
+        | timeout
+        | temporarily
+      /xi
+
       class << self
         attr_reader :unavailable_reason
 
         def available?
-          return @loaded if @load_attempted
+          return true if @loaded
+          return false if @permanently_unavailable
+
+          @loaded = probe_availability
+          return true if @loaded
+
+          if transient_reason?(@unavailable_reason) && @transient_failures < TRANSIENT_FAILURE_RETRY_LIMIT
+            # Leave the backend probeable so a later availability check retries
+            # the on-demand grammar download instead of failing every parse for
+            # the rest of the process.
+            @transient_failures += 1
+            return false
+          end
 
-          @load_attempted = true
+          @permanently_unavailable = true
+          false
+        end
+
+        # Reason the last per-language probe failed, when known.
+        def language_unavailable_reason(language_name)
+          @language_unavailable_reasons[language_name.to_s]
+        end
+
+        # Pre-download and pre-load grammars through the language pack's
+        # hot-load API before any parse/smoke probing happens. This turns the
+        # on-demand download (which otherwise fires inside the first
+        # availability probe and can transiently fail) into an explicit,
+        # attributable warm-up step.
+        #
+        # @param languages [Array<String, Symbol>] grammar names to prefetch
+        # @return [Hash] {attempted:, prefetched:, failures: {name => reason}}
+        def prefetch(languages)
+          names = languages.map(&:to_s).uniq
           begin
             require 'tree_sitter_language_pack' unless defined?(::TreeSitterLanguagePack)
-            @loaded = parser_api_available?
-            if !@loaded && @unavailable_reason.to_s.empty?
-              @unavailable_reason = 'tree_sitter_language_pack parser API is not exposed'
-            end
           rescue LoadError => e
-            @loaded = false
-            @unavailable_reason = e.message
+            return prefetch_skip_report('tree_sitter_language_pack is not installed', e.message, names)
+          end
+
+          unless ::TreeSitterLanguagePack.respond_to?(:prefetch)
+            return prefetch_skip_report('tree_sitter_language_pack does not expose prefetch', nil, names)
+          end
+
+          failures = {}
+          prefetched = names.select do |name|
+            ::TreeSitterLanguagePack.prefetch([name])
+            true
           rescue StandardError => e
-            @loaded = false
-            @unavailable_reason = e.message
+            failures[name] = e.message
+            false
           end
-          @loaded
+          { attempted: true, prefetched: prefetched, failures: failures }
+        end
+
+        def transient_reason?(reason)
+          !reason.to_s.empty? && TRANSIENT_FAILURE_PATTERN.match?(reason.to_s)
         end
 
         def reset!
-          @load_attempted = false
           @loaded = false
+          @permanently_unavailable = false
+          @transient_failures = 0
           @unavailable_reason = nil
           @language_availability = {}
           @language_unavailable_reasons = {}
+          @language_attempts = {}
         end
 
         def capabilities
@@ -78,17 +143,62 @@ module TreeHaver
           name = language_name.to_s
           return @language_availability.fetch(name) if @language_availability.key?(name)
 
-          @language_availability[name] = smoke_parse_language(name)
-          @language_unavailable_reasons[name] = @unavailable_reason unless @language_availability.fetch(name)
-          @language_availability.fetch(name)
+          available = smoke_parse_language(name)
+          if available
+            @language_availability[name] = true
+            @language_unavailable_reasons.delete(name)
+            return true
+          end
+
+          reason = @language_unavailable_reasons[name] = @unavailable_reason
+          attempts = (@language_attempts[name] = @language_attempts.fetch(name, 0) + 1)
+          if transient_reason?(reason) && attempts < TRANSIENT_FAILURE_RETRY_LIMIT
+            # Do not memoize: a later probe retries the on-demand hot load.
+            return false
+          end
+
+          @language_availability[name] = false
+          false
         rescue StandardError => e
+          name = language_name.to_s
           @unavailable_reason = e.message
-          @language_unavailable_reasons[language_name.to_s] = e.message
+          @language_unavailable_reasons[name] = e.message
+          attempts = (@language_attempts[name] = @language_attempts.fetch(name, 0) + 1)
+          # Memoize only after exhausting the transient retry budget; raising
+          # here is how the on-demand grammar download reports failures.
+          @language_availability[name] = false if attempts >= TRANSIENT_FAILURE_RETRY_LIMIT
           false
         end
 
         private
 
+        def prefetch_skip_report(reason, detail, names)
+          @unavailable_reason = detail if detail
+          {
+            attempted: false,
+            reason: reason,
+            prefetched: [],
+            failures: names.to_h { |name| [name, reason] }
+          }
+        end
+
+        def probe_availability
+          require 'tree_sitter_language_pack' unless defined?(::TreeSitterLanguagePack)
+          loaded = parser_api_available?
+          if !loaded && @unavailable_reason.to_s.empty?
+            @unavailable_reason = 'tree_sitter_language_pack parser API is not exposed'
+          end
+          loaded
+        rescue LoadError => e
+          # A missing gem is permanent for the process lifetime.
+          @unavailable_reason = e.message
+          @permanently_unavailable = true
+          false
+        rescue StandardError => e
+          @unavailable_reason = e.message
+          false
+        end
+
         def parser_api_available?
           return false unless ::TreeSitterLanguagePack.respond_to?(:get_parser)
           return false unless defined?(::TreeSitterLanguagePack::Parser)

data/lib/tree_haver/grammar_finder.rb

@@ -314,12 +314,14 @@ module TreeHaver
     # @raise [NotAvailable] if library not found and raise_on_missing is true
     def register!(raise_on_missing: false)
       if tree_sitter_language_pack_parser_available?
+        backend_module, backend_type, gem_name = language_pack_registration
         TreeHaver.register_language(
           @language_name,
-          backend_module: TreeHaver::Backends::Tslp,
-          backend_type: :tslp,
-          gem_name: 'tree_sitter_language_pack'
+          backend_module: backend_module,
+          backend_type: backend_type,
+          gem_name: gem_name
         )
+        backend_module.register_language_parser(@language_name) if backend_type == :rust_tslp
         return true
       end
 
@@ -377,6 +379,14 @@ module TreeHaver
 
     private
 
+    def language_pack_registration
+      if TreeHaver.effective_backend == :rust_tslp
+        [TreeHaver::Backends::RustTslp, :rust_tslp, 'structuredmerge-core']
+      else
+        [TreeHaver::Backends::Tslp, :tslp, 'tree_sitter_language_pack']
+      end
+    end
+
     def registered_tree_sitter_registration
       TreeHaver::LanguageRegistry.registered(@language_name, :tree_sitter)
     end
@@ -399,11 +409,15 @@ module TreeHaver
       return @tree_sitter_language_pack_parser_available if defined?(@tree_sitter_language_pack_parser_available)
 
       @tree_sitter_language_pack_parser_available = begin
-        require 'tree_sitter_language_pack' unless defined?(::TreeSitterLanguagePack)
-        TreeHaver::Backends::Tslp.available? &&
-          ::TreeSitterLanguagePack.respond_to?(:has_language) &&
-          ::TreeSitterLanguagePack.has_language(@language_name.to_s) &&
-          TreeHaver::Backends::Tslp.parser_available_for?(@language_name)
+        if TreeHaver.effective_backend == :rust_tslp
+          TreeHaver::Backends::RustTslp.available?
+        else
+          require 'tree_sitter_language_pack' unless defined?(::TreeSitterLanguagePack)
+          TreeHaver::Backends::Tslp.available? &&
+            ::TreeSitterLanguagePack.respond_to?(:has_language) &&
+            ::TreeSitterLanguagePack.has_language(@language_name.to_s) &&
+            TreeHaver::Backends::Tslp.parser_available_for?(@language_name)
+        end
       rescue LoadError
         false
       rescue StandardError => e

data/lib/tree_haver/language_pack.rb

@@ -9,9 +9,14 @@ module TreeHaver
     id: 'kreuzberg-language-pack',
     family: 'tree-sitter'
   ).freeze
+  RUST_TSLP_BACKEND = BackendReference.new(
+    id: 'rust_tslp',
+    family: 'tree-sitter'
+  ).freeze
 
   BackendRegistry.register(TSLP_BACKEND)
   BackendRegistry.register(KREUZBERG_LANGUAGE_PACK_BACKEND)
+  BackendRegistry.register(RUST_TSLP_BACKEND)
   BackendRegistry.register_availability_checker(:tslp) do
     Backends::Tslp.available?
   end

data/lib/tree_haver/version.rb

@@ -4,7 +4,7 @@ module TreeHaver
   # Version namespace for this gem.
   module Version
     # Current gem version.
-    VERSION = '7.1.8'
+    VERSION = '7.1.10'
   end
   # Current gem version exposed at the traditional constant location.
   VERSION = Version::VERSION # Traditional Constant Location

data/lib/tree_haver.rb

@@ -32,6 +32,7 @@ require_relative 'tree_haver/backends/ffi'
 require_relative 'tree_haver/backends/rust'
 require_relative 'tree_haver/backends/java'
 require_relative 'tree_haver/backends/tslp'
+require_relative 'tree_haver/backends/rust_tslp'
 require_relative 'tree_haver/grammar_finder'
 require_relative 'tree_haver/citrus_grammar_finder'
 require_relative 'tree_haver/parslet_grammar_finder'
@@ -50,7 +51,8 @@ module TreeHaver
   RUBY_BACKENDS = %i[citrus parslet prism psych commonmarker markly rbs].freeze
   VALID_NATIVE_BACKENDS = NATIVE_BACKENDS.map(&:to_s).freeze
   VALID_RUBY_BACKENDS = RUBY_BACKENDS.map(&:to_s).freeze
-  VALID_BACKENDS = (VALID_NATIVE_BACKENDS + VALID_RUBY_BACKENDS + %w[auto none tslp kreuzberg-language-pack]).freeze
+  VALID_BACKENDS = (VALID_NATIVE_BACKENDS + VALID_RUBY_BACKENDS + %w[auto none tslp rust_tslp
+                                                                     kreuzberg-language-pack]).freeze
   DEFAULT_BACKEND_ID = 'tslp'
   NATIVE_BACKEND_REFERENCES = NATIVE_BACKENDS.to_h do |backend_name|
     [
@@ -76,6 +78,9 @@ module TreeHaver
     BackendRegistry.register_tag(:java_backend, category: :backend, backend_name: :java) do
       Backends::Java.available?
     end
+    BackendRegistry.register_tag(:rust_tslp_backend, category: :backend, backend_name: :rust_tslp) do
+      Backends::RustTslp.available?
+    end
   end
 
   def default_backend_id
@@ -253,6 +258,19 @@ module TreeHaver
     LanguageRegistry.registered(name)
   end
 
+  # Warm up language-pack grammars through their hot-load/prefetch API so the
+  # on-demand grammar download happens explicitly, up front, instead of firing
+  # inside the first availability smoke probe during a merge.
+  #
+  # Safe to call with the TSLP backend unavailable or absent: reports
+  # attempted: false with a reason instead of raising.
+  #
+  # @param languages [Array<String, Symbol>] grammar names to prefetch
+  # @return [Hash] prefetch report (see Backends::Tslp.prefetch)
+  def prefetch_languages(languages)
+    Backends::Tslp.prefetch(languages)
+  end
+
   def register_language(name, path: nil, symbol: nil, grammar_module: nil, grammar_class: nil, backend_module: nil,
                         backend_type: nil, gem_name: nil, contract: nil)
     LanguageRegistry.register(name, :tree_sitter, path: path, symbol: symbol, contract: contract) if path
@@ -340,7 +358,21 @@ module TreeHaver
       return parser_for_registered_backend(name, backend_type, registrations)
     end
 
-    raise NotAvailable, "No parser registered for #{name}"
+    raise NotAvailable, no_parser_registered_message(name)
+  end
+
+  # Build the "No parser registered" error message, surfacing why the
+  # tree-sitter-language-pack backend declined the language (for example a
+  # failed on-demand grammar download) so CI logs are attributable instead of
+  # misleading.
+  def no_parser_registered_message(name)
+    message = "No parser registered for #{name}"
+    language_reason = Backends::Tslp.language_unavailable_reason(name)
+    backend_reason = Backends::Tslp.unavailable_reason
+    reasons = [language_reason, backend_reason].map(&:to_s).reject(&:empty?).uniq
+    return message if reasons.empty?
+
+    "#{message} (tree_sitter_language_pack: #{reasons.join('; ')})"
   end
 
   def ruby_reference_parser_backend_contract_report
@@ -407,7 +439,9 @@ module TreeHaver
            elsif (registered_type = registered_backend_type_for_requested_backend(backend_id, registrations))
              registered_type
            elsif backend_ref&.family == 'tree-sitter'
-             :tree_sitter
+             registrations.find do |registered_type, config|
+               registration_contract(registered_type, config) == :tree_sitter
+             end&.first || :tree_sitter
            else
              backend_id.to_s.to_sym
            end
@@ -452,7 +486,7 @@ module TreeHaver
   def parser_for_registered_backend(name, backend_type, registrations)
     config = registrations.fetch(backend_type)
     case backend_type
-    when :psych, :prism, :commonmarker, :markly, :rbs
+    when :psych, :prism, :commonmarker, :markly, :rbs, :rust_tslp
       parser_for_backend_module(config.fetch(:backend_module), name)
     when :citrus
       parser_for_citrus(config.fetch(:grammar_module))
@@ -562,6 +596,8 @@ module TreeHaver
       Backends::Java
     when :tslp, :"kreuzberg-language-pack"
       Backends::Tslp
+    when :rust_tslp
+      Backends::RustTslp
     when :citrus
       Backends::Citrus
     when :parslet

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: tree_haver
 version: !ruby/object:Gem::Version
-  version: 7.1.8
+  version: 7.1.10
 platform: ruby
 authors:
 - Peter H. Boling
@@ -71,7 +71,7 @@ dependencies:
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: 1.16.2
+        version: 1.17.0
     - - "<"
       - !ruby/object:Gem::Version
         version: '2.0'
@@ -81,7 +81,7 @@ dependencies:
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: 1.16.2
+        version: 1.17.0
     - - "<"
       - !ruby/object:Gem::Version
         version: '2.0'
@@ -111,20 +111,20 @@ dependencies:
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '3.0'
+        version: '3.1'
     - - ">="
       - !ruby/object:Gem::Version
-        version: 3.0.31
+        version: 3.1.8
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '3.0'
+        version: '3.1'
     - - ">="
       - !ruby/object:Gem::Version
-        version: 3.0.31
+        version: 3.1.8
 - !ruby/object:Gem::Dependency
   name: bundler-audit
   requirement: !ruby/object:Gem::Requirement
@@ -202,7 +202,7 @@ dependencies:
         version: '3.2'
     - - ">="
       - !ruby/object:Gem::Version
-        version: 3.2.3
+        version: 3.2.5
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
@@ -212,7 +212,7 @@ dependencies:
         version: '3.2'
     - - ">="
       - !ruby/object:Gem::Version
-        version: 3.2.3
+        version: 3.2.5
 - !ruby/object:Gem::Dependency
   name: kettle-test
   requirement: !ruby/object:Gem::Requirement
@@ -222,7 +222,7 @@ dependencies:
         version: '2.0'
     - - ">="
       - !ruby/object:Gem::Version
-        version: 2.0.21
+        version: 2.0.23
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
@@ -232,7 +232,7 @@ dependencies:
         version: '2.0'
     - - ">="
       - !ruby/object:Gem::Version
-        version: 2.0.21
+        version: 2.0.23
 - !ruby/object:Gem::Dependency
   name: turbo_tests2
   requirement: !ruby/object:Gem::Requirement
@@ -242,7 +242,7 @@ dependencies:
         version: '3.2'
     - - ">="
       - !ruby/object:Gem::Version
-        version: 3.2.7
+        version: 3.2.14
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
@@ -252,7 +252,7 @@ dependencies:
         version: '3.2'
     - - ">="
       - !ruby/object:Gem::Version
-        version: 3.2.7
+        version: 3.2.14
 - !ruby/object:Gem::Dependency
   name: ruby-progressbar
   requirement: !ruby/object:Gem::Requirement
@@ -276,7 +276,7 @@ dependencies:
         version: '1.0'
     - - ">="
       - !ruby/object:Gem::Version
-        version: 1.0.8
+        version: 1.0.9
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
@@ -286,7 +286,7 @@ dependencies:
         version: '1.0'
     - - ">="
       - !ruby/object:Gem::Version
-        version: 1.0.8
+        version: 1.0.9
 - !ruby/object:Gem::Dependency
   name: gitmoji-regex
   requirement: !ruby/object:Gem::Requirement
@@ -296,7 +296,7 @@ dependencies:
         version: '2.0'
     - - ">="
       - !ruby/object:Gem::Version
-        version: 2.0.12
+        version: 2.0.15
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
@@ -306,7 +306,7 @@ dependencies:
         version: '2.0'
     - - ">="
       - !ruby/object:Gem::Version
-        version: 2.0.12
+        version: 2.0.15
 - !ruby/object:Gem::Dependency
   name: toml
   requirement: !ruby/object:Gem::Requirement
@@ -357,6 +357,7 @@ files:
 - lib/tree_haver/backends/prism.rb
 - lib/tree_haver/backends/psych.rb
 - lib/tree_haver/backends/rust.rb
+- lib/tree_haver/backends/rust_tslp.rb
 - lib/tree_haver/backends/tslp.rb
 - lib/tree_haver/base/comment.rb
 - lib/tree_haver/base/language.rb
@@ -389,10 +390,10 @@ licenses:
 - PolyForm-Small-Business-1.0.0
 metadata:
   homepage_uri: https://structuredmerge.org
-  source_code_uri: https://github.com/structuredmerge/structuredmerge-ruby/tree/v7.1.8
-  changelog_uri: https://github.com/structuredmerge/structuredmerge-ruby/blob/v7.1.8/CHANGELOG.md
+  source_code_uri: https://github.com/structuredmerge/structuredmerge-ruby/tree/v7.1.10
+  changelog_uri: https://github.com/structuredmerge/structuredmerge-ruby/blob/v7.1.10/CHANGELOG.md
   bug_tracker_uri: https://github.com/structuredmerge/structuredmerge-ruby/issues
-  documentation_uri: https://www.rubydoc.info/gems/tree_haver/7.1.8
+  documentation_uri: https://www.rubydoc.info/gems/tree_haver/7.1.10
   funding_uri: https://github.com/sponsors/pboling
   wiki_uri: https://github.com/structuredmerge/structuredmerge-ruby/wiki
   news_uri: https://www.railsbling.com/tags/tree_haver
@@ -423,7 +424,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 4.0.17
+rubygems_version: 4.0.20
 specification_version: 4
 summary: "\U0001F334 Structured Merge parser abstraction and process analysis for
   Ruby"