tree_haver 3.2.2 → 3.2.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: db807cd904d2fd3878705c02e63288b1c650853c3509431abf23d3ac4f9e83e2
-  data.tar.gz: d6e9e8299e6dc85a8d856f8a93ae592fe823d5da94cbc624cf1c0bcdafa9adcc
+  metadata.gz: 02ffefe8f7a777c04ca0682c3bae06f92d383eacdf2e852755dd6e517cff68bf
+  data.tar.gz: a44f91a685d4736f7eac5a81cc04f43e274e18f8af8904eaa4e1247bf1779764
 SHA512:
-  metadata.gz: f8b457ef8362cf164d91da763776bd273b9d04f96fca557f597a54b42b102b2b1b8ee5b0a7e98335a12bbe072945b0fd1205e351a4afa4e9e106542263450c70
-  data.tar.gz: afca005da881caf5cbfdc7e8317e0accf9fca803a2d1582a510daaf1da5f80e46c9987a4f71913366503eee5f30e1dba4dd7ad7d7eaec6821ef9c2f2edbccf11
+  metadata.gz: e0d54671ac5cecea3e8496da4e5a9cf9f4ef4c3abd7bcb926f0d8830e230b2d850845e4a49e824e0144c79c35e7477abf6ee9f4a7284637c1fc0c0ff6ff15033
+  data.tar.gz: 8f7487bd3fba0f8d03128a32a485db360a1db5d97161f2885918992dd516140c37006d7bf2bc7d8f86867ad597fe5920683f126bd1d30c2257764aab19b37c88

data/CHANGELOG.md

@@ -30,6 +30,47 @@ Please file a bug if you notice a violation of semantic versioning.
 
 ### Security
 
+## [3.2.3] - 2026-01-02
+
+- TAG: [v3.2.3][3.2.3t]
+- COVERAGE: 94.91% -- 2088/2200 lines in 22 files
+- BRANCH COVERAGE: 81.37% -- 738/907 branches in 22 files
+- 90.14% documented
+
+### Fixed
+
+- **`parser_for` now respects explicitly requested non-native backends** - Previously,
+  `parser_for` would always try tree-sitter backends first and only fall back to alternative
+  backends if tree-sitter was unavailable. Now it checks `effective_backend` and skips
+  tree-sitter attempts entirely when a non-native backend is explicitly requested via:
+  - `TREE_HAVER_BACKEND=citrus` (or `prism`, `psych`, `commonmarker`, `markly`)
+  - `TreeHaver.backend = :citrus`
+  - `TreeHaver.with_backend(:citrus) { ... }`
+
+  Native backends (`:mri`, `:rust`, `:ffi`, `:java`) still use tree-sitter grammar discovery.
+
+- **`load_tree_sitter_language` now correctly ignores Citrus registrations** - Previously,
+  if a language was registered with Citrus first, `load_tree_sitter_language` would
+  incorrectly try to use it even when a native backend was explicitly requested. Now it
+  only uses registrations that have a `:tree_sitter` key, allowing proper backend switching
+  between Citrus and native tree-sitter backends.
+
+- **`load_tree_sitter_language` now validates registered paths exist** - Previously,
+  if a language had a stale/invalid tree-sitter registration with a non-existent path
+  (e.g., from a test), the code would try to use it and fail. Now it checks
+  `File.exist?(path)` before using a registered path, falling back to auto-discovery
+  via `GrammarFinder` if the registered path doesn't exist.
+
+- **`Language.method_missing` no longer falls back to Citrus when native backend explicitly requested** -
+  Previously, when tree-sitter loading failed (e.g., .so file missing), the code would
+  silently fall back to Citrus even if the user explicitly requested `:mri`, `:rust`,
+  `:ffi`, or `:java`. Now fallback to Citrus only happens when `effective_backend` is `:auto`.
+  This is a **breaking change** for users who relied on silent fallback behavior.
+
+- **Simplified `parser_for` implementation** - Refactored from complex nested conditionals to
+  cleaner helper methods (`load_tree_sitter_language`, `load_citrus_language`). The logic is
+  now easier to follow and maintain.
+
 ## [3.2.2] - 2026-01-01
 
 - TAG: [v3.2.2][3.2.2t]
@@ -674,7 +715,9 @@ Despite the major version bump to 3.0.0 (following semver due to the breaking `L
 
 - Initial release
 
-[Unreleased]: https://github.com/kettle-rb/tree_haver/compare/v3.2.2...HEAD
+[Unreleased]: https://github.com/kettle-rb/tree_haver/compare/v3.2.3...HEAD
+[3.2.3]: https://github.com/kettle-rb/tree_haver/compare/v3.2.2...v3.2.3
+[3.2.3t]: https://github.com/kettle-rb/tree_haver/releases/tag/v3.2.3
 [3.2.2]: https://github.com/kettle-rb/tree_haver/compare/v3.2.1...v3.2.2
 [3.2.2t]: https://github.com/kettle-rb/tree_haver/releases/tag/v3.2.2
 [3.2.1]: https://github.com/kettle-rb/tree_haver/compare/v3.2.0...v3.2.1

data/LICENSE.txt

@@ -1,6 +1,6 @@
 The MIT License (MIT)
 
-Copyright (c) 2025 Peter H. Boling
+Copyright (c) 2025-2026 Peter H. Boling
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

data/README.md

@@ -1788,7 +1788,7 @@ See [LICENSE.txt](LICENSE.txt) for the official [Copyright Notice](https://opens
 
 <ul>
     <li>
-        Copyright (c) 2025 Peter H. Boling, of
+        Copyright (c) 2025-2026 Peter H. Boling, of
         <a href="https://discord.gg/3qme4XHNKN">
             Galtzo.com
             <picture>
@@ -1977,7 +1977,7 @@ Thanks for RTFM. ☺️
 [📌gitmoji]: https://gitmoji.dev
 [📌gitmoji-img]: https://img.shields.io/badge/gitmoji_commits-%20%F0%9F%98%9C%20%F0%9F%98%8D-34495e.svg?style=flat-square
 [🧮kloc]: https://www.youtube.com/watch?v=dQw4w9WgXcQ
-[🧮kloc-img]: https://img.shields.io/badge/KLOC-2.190-FFDD67.svg?style=for-the-badge&logo=YouTube&logoColor=blue
+[🧮kloc-img]: https://img.shields.io/badge/KLOC-2.200-FFDD67.svg?style=for-the-badge&logo=YouTube&logoColor=blue
 [🔐security]: SECURITY.md
 [🔐security-img]: https://img.shields.io/badge/security-policy-259D6C.svg?style=flat
 [📄copyright-notice-explainer]: https://opensource.stackexchange.com/questions/5778/why-do-licenses-such-as-the-mit-license-specify-a-single-year

data/lib/tree_haver/language.rb

@@ -211,10 +211,13 @@ module TreeHaver
 
         # No tree-sitter path registered - check for Citrus fallback
         # This enables auto-fallback when tree-sitter grammar is not installed
-        # but a Citrus grammar (pure Ruby) is available
-        citrus_reg = all_backends[:citrus]
-        if citrus_reg && citrus_reg[:grammar_module]
-          return Backends::Citrus::Language.new(citrus_reg[:grammar_module])
+        # but a Citrus grammar (pure Ruby) is available.
+        # Only fall back when backend is :auto - explicit native backend requests should fail.
+        if TreeHaver.effective_backend == :auto
+          citrus_reg = all_backends[:citrus]
+          if citrus_reg && citrus_reg[:grammar_module]
+            return Backends::Citrus::Language.new(citrus_reg[:grammar_module])
+          end
         end
 
         # No appropriate registration found
@@ -237,17 +240,29 @@ module TreeHaver
       # - FFI can't find required symbols like ts_parser_new (FFI::NotFoundError)
       # - Invalid arguments were provided (ArgumentError)
       #
+      # Fallback to Citrus ONLY happens when:
+      # - The effective backend is :auto (user didn't explicitly request a native backend)
+      # - A Citrus grammar is registered for the language
+      #
+      # If the user explicitly requested a native backend (:mri, :rust, :ffi, :java),
+      # we should NOT silently fall back to Citrus - that would violate the user's intent.
+      #
       # @param error [Exception] the original error
       # @param all_backends [Hash] all registered backends for the language
-      # @return [Backends::Citrus::Language] if Citrus fallback available
-      # @raise [Exception] re-raises original error if no fallback
+      # @return [Backends::Citrus::Language] if Citrus fallback available and allowed
+      # @raise [Exception] re-raises original error if no fallback or fallback not allowed
       # @api private
       def handle_tree_sitter_load_failure(error, all_backends)
-        citrus_reg = all_backends[:citrus]
-        if citrus_reg && citrus_reg[:grammar_module]
-          return Backends::Citrus::Language.new(citrus_reg[:grammar_module])
+        # Only fall back to Citrus when backend is :auto
+        # If user explicitly requested a native backend, respect that choice
+        effective = TreeHaver.effective_backend
+        if effective == :auto
+          citrus_reg = all_backends[:citrus]
+          if citrus_reg && citrus_reg[:grammar_module]
+            return Backends::Citrus::Language.new(citrus_reg[:grammar_module])
+          end
         end
-        # No Citrus fallback available, re-raise the original error
+        # No Citrus fallback allowed or available, re-raise the original error
         raise error
       end
     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.3"
   end
 
   # Traditional location for VERSION constant

data/lib/tree_haver.rb

@@ -16,7 +16,7 @@ require_relative "tree_haver/version"
 #
 # == Backends
 #
-# Supports 10 backends:
+# Supports 9 backends:
 # - Tree-sitter: MRI (C), Rust, FFI, Java
 # - Native parsers: Prism (Ruby), Psych (YAML), Commonmarker (Markdown), Markly (GFM)
 # - Pure Ruby: Citrus (portable fallback)
@@ -266,6 +266,11 @@ module TreeHaver
   # Parser class for parsing source code into syntax trees
   autoload :Parser, File.join(__dir__, "tree_haver", "parser")
 
+  # Native tree-sitter backends that support loading shared libraries (.so files)
+  # These backends wrap the tree-sitter C library via various bindings.
+  # Pure Ruby backends (Citrus, Prism, Psych, Commonmarker, Markly) are excluded.
+  NATIVE_BACKENDS = %i[mri rust ffi java].freeze
+
   # Get the current backend selection
   #
   # @return [Symbol] one of :auto, :mri, :rust, :ffi, :java, or :citrus
@@ -590,11 +595,6 @@ module TreeHaver
       mod
     end
 
-    # Native tree-sitter backends that support loading shared libraries (.so files)
-    # These backends wrap the tree-sitter C library via various bindings.
-    # Pure Ruby backends (Citrus, Prism, Psych, Commonmarker, Markly) are excluded.
-    NATIVE_BACKENDS = %i[mri rust ffi java].freeze
-
     # Resolve a native tree-sitter backend module (for from_library)
     #
     # This method is similar to resolve_backend_module but ONLY considers
@@ -836,114 +836,107 @@ module TreeHaver
 
     # Create a parser configured for a specific language
     #
-    # This is the recommended high-level API for creating a parser. It handles:
-    # 1. Checking if the language is already registered
-    # 2. Auto-discovering tree-sitter grammar via GrammarFinder
-    # 3. Falling back to Citrus grammar if tree-sitter is unavailable
-    # 4. Creating and configuring the parser
+    # Respects the effective backend setting (via TREE_HAVER_BACKEND env var,
+    # TreeHaver.backend=, or with_backend block).
     #
     # @param language_name [Symbol, String] the language to parse (e.g., :toml, :json, :bash)
     # @param library_path [String, nil] optional explicit path to tree-sitter grammar library
     # @param symbol [String, nil] optional tree-sitter symbol name (defaults to "tree_sitter_<name>")
     # @param citrus_config [Hash, nil] optional Citrus fallback configuration
-    # @option citrus_config [String] :gem_name gem name for the Citrus grammar
-    # @option citrus_config [String] :grammar_const fully qualified constant name for grammar module
     # @return [TreeHaver::Parser] configured parser with language set
     # @raise [TreeHaver::NotAvailable] if no parser backend is available for the language
     #
     # @example Basic usage (auto-discovers grammar)
     #   parser = TreeHaver.parser_for(:toml)
-    #   tree = parser.parse("[package]\nname = \"my-app\"")
     #
-    # @example With explicit library path
-    #   parser = TreeHaver.parser_for(:toml, library_path: "/custom/path/libtree-sitter-toml.so")
-    #
-    # @example With Citrus fallback configuration
-    #   parser = TreeHaver.parser_for(:toml,
-    #     citrus_config: { gem_name: "toml-rb", grammar_const: "TomlRB::Document" }
-    #   )
+    # @example Force Citrus backend
+    #   TreeHaver.with_backend(:citrus) { TreeHaver.parser_for(:toml) }
     def parser_for(language_name, library_path: nil, symbol: nil, citrus_config: nil)
       name = language_name.to_sym
       symbol ||= "tree_sitter_#{name}"
+      requested = effective_backend
 
-      # Step 1: Try to get the language (may already be registered)
-      language = begin
-        # Check if already registered and loadable
-        if registered_language(name)
-          Language.public_send(name, path: library_path, symbol: symbol)
-        end
-      rescue NotAvailable, ArgumentError, LoadError
-        nil
-      end
+      # Determine which backends to try based on effective_backend
+      try_tree_sitter = (requested == :auto) || NATIVE_BACKENDS.include?(requested)
+      try_citrus = (requested == :auto) || (requested == :citrus)
 
-      # Step 2: If not registered, try GrammarFinder for tree-sitter
-      unless language
-        # Principle of Least Surprise: If user provides an explicit path,
-        # it MUST exist. Don't silently fall back to auto-discovery.
-        if library_path && !library_path.empty?
-          unless File.exist?(library_path)
-            raise NotAvailable,
-              "Specified parser path does not exist: #{library_path}"
-          end
-          begin
-            register_language(name, path: library_path, symbol: symbol)
-            language = Language.public_send(name)
-          rescue NotAvailable, ArgumentError, LoadError => e
-            # Re-raise with more context since user explicitly provided this path
-            raise NotAvailable,
-              "Failed to load parser from specified path #{library_path}: #{e.message}"
-          end
-        else
-          # Auto-discover via GrammarFinder (no explicit path provided)
-          begin
-            finder = GrammarFinder.new(name)
-            if finder.available?
-              finder.register!
-              language = Language.public_send(name)
-            end
-          rescue NotAvailable, ArgumentError, LoadError
-            language = nil
-          end
-        end
-      end
+      language = nil
 
-      # Step 3: Try Citrus fallback if tree-sitter failed
-      unless language
-        # Use explicit config, or fall back to built-in defaults for known languages
-        citrus_config ||= CITRUS_DEFAULTS[name] || {}
-
-        # Only attempt if we have the required configuration
-        if citrus_config[:gem_name] && citrus_config[:grammar_const]
-          begin
-            citrus_finder = CitrusGrammarFinder.new(
-              language: name,
-              gem_name: citrus_config[:gem_name],
-              grammar_const: citrus_config[:grammar_const],
-              require_path: citrus_config[:require_path],
-            )
-            if citrus_finder.available?
-              citrus_finder.register!
-              language = Language.public_send(name)
-            end
-          rescue NotAvailable, ArgumentError, LoadError, NameError, TypeError
-            language = nil
-          end
-        end
+      # Try tree-sitter if applicable
+      if try_tree_sitter && !language
+        language = load_tree_sitter_language(name, library_path: library_path, symbol: symbol)
       end
 
-      # Step 4: Raise if nothing worked
-      unless language
-        raise NotAvailable,
-          "No parser available for #{name}. " \
-            "Install tree-sitter-#{name} or the appropriate Ruby gem. " \
-            "Set TREE_SITTER_#{name.to_s.upcase}_PATH for custom grammar location."
+      # Try Citrus if applicable
+      if try_citrus && !language
+        language = load_citrus_language(name, citrus_config: citrus_config)
       end
 
-      # Step 5: Create and configure parser
+      # Raise if nothing worked
+      raise NotAvailable, "No parser available for #{name}. " \
+        "Install tree-sitter-#{name} or configure a Citrus grammar." unless language
+
+      # Create and configure parser
       parser = Parser.new
       parser.language = language
       parser
     end
+
+    private
+
+    # Load a tree-sitter language, either from registry or via auto-discovery
+    # @return [Language, nil]
+    # @raise [NotAvailable] if explicit library_path is provided but doesn't exist or can't load
+    def load_tree_sitter_language(name, library_path: nil, symbol: nil)
+      # If explicit path provided, it must work - don't swallow errors
+      if library_path && !library_path.empty?
+        raise NotAvailable, "Specified parser path does not exist: #{library_path}" unless File.exist?(library_path)
+        register_language(name, path: library_path, symbol: symbol)
+        return Language.public_send(name)
+      end
+
+      # Auto-discovery: errors are acceptable, just return nil
+      begin
+        # Try already-registered tree-sitter language (not Citrus)
+        # But only if the registered path actually exists - ignore stale/test registrations
+        registration = registered_language(name)
+        ts_reg = registration&.dig(:tree_sitter)
+        if ts_reg && ts_reg[:path] && File.exist?(ts_reg[:path])
+          return Language.public_send(name, symbol: symbol)
+        end
+
+        # Auto-discover via GrammarFinder
+        finder = GrammarFinder.new(name)
+        if finder.available?
+          finder.register!
+          return Language.public_send(name)
+        end
+      rescue NotAvailable, ArgumentError, LoadError
+        # Auto-discovery failed, that's okay
+      end
+
+      nil
+    end
+
+    # Load a Citrus language from configuration or defaults
+    # @return [Language, nil]
+    def load_citrus_language(name, citrus_config: nil)
+      config = citrus_config || CITRUS_DEFAULTS[name] || {}
+      return unless config[:gem_name] && config[:grammar_const]
+
+      finder = CitrusGrammarFinder.new(
+        language: name,
+        gem_name: config[:gem_name],
+        grammar_const: config[:grammar_const],
+        require_path: config[:require_path],
+      )
+      return unless finder.available?
+
+      finder.register!
+      Language.public_send(name)
+    rescue NotAvailable, ArgumentError, LoadError, NameError, TypeError
+      nil
+    end
   end
 
   # Language and Parser classes have been moved to separate files:

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: tree_haver
 version: !ruby/object:Gem::Version
-  version: 3.2.2
+  version: 3.2.3
 platform: ruby
 authors:
 - Peter H. Boling
@@ -292,10 +292,10 @@ licenses:
 - MIT
 metadata:
   homepage_uri: https://tree-haver.galtzo.com/
-  source_code_uri: https://github.com/kettle-rb/tree_haver/tree/v3.2.2
-  changelog_uri: https://github.com/kettle-rb/tree_haver/blob/v3.2.2/CHANGELOG.md
+  source_code_uri: https://github.com/kettle-rb/tree_haver/tree/v3.2.3
+  changelog_uri: https://github.com/kettle-rb/tree_haver/blob/v3.2.3/CHANGELOG.md
   bug_tracker_uri: https://github.com/kettle-rb/tree_haver/issues
-  documentation_uri: https://www.rubydoc.info/gems/tree_haver/3.2.2
+  documentation_uri: https://www.rubydoc.info/gems/tree_haver/3.2.3
   funding_uri: https://github.com/sponsors/pboling
   wiki_uri: https://github.com/kettle-rb/tree_haver/wiki
   news_uri: https://www.railsbling.com/tags/tree_haver