tree_haver 3.0.0 → 3.1.1

data/lib/tree_haver/rspec.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+# TreeHaver RSpec Integration
+#
+# This file provides RSpec helpers and configuration for testing
+# code that uses TreeHaver. Require this in your spec_helper.rb:
+#
+#   require "tree_haver/rspec"
+#
+# This will load:
+# - Dependency tags for conditional test execution
+# - (Future) Additional test helpers as needed
+#
+# @example spec_helper.rb
+#   require "tree_haver/rspec"
+#
+#   RSpec.configure do |config|
+#     # Your additional configuration...
+#   end
+#
+# @see TreeHaver::RSpec::DependencyTags
+
+require_relative "rspec/dependency_tags"

data/lib/tree_haver/tree.rb

@@ -156,7 +156,7 @@ module TreeHaver
       raise unless e.name == :edit || e.message.include?("edit")
       raise TreeHaver::NotAvailable,
         "Incremental parsing not supported by current backend. " \
-          "Use MRI (ruby_tree_sitter), Rust (tree_stump), or Java (java-tree-sitter) backend."
+          "Use MRI (ruby_tree_sitter), Rust (tree_stump), or Java (java-tree-sitter / jtreesitter) backend."
     end
 
     private

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.0.0"
+    VERSION = "3.1.1"
   end
 
   # Traditional location for VERSION constant

data/lib/tree_haver.rb

@@ -10,12 +10,17 @@ require "set"
 require_relative "tree_haver/version"
 require_relative "tree_haver/language_registry"
 
-# TreeHaver is a cross-Ruby adapter for the tree-sitter parsing library.
+# TreeHaver is a cross-Ruby adapter for code parsing with 10 backends.
 #
-# It provides a unified API for parsing source code using tree-sitter grammars,
-# working seamlessly across MRI Ruby, JRuby, and TruffleRuby.
+# Provides a unified API for parsing source code across MRI Ruby, JRuby, and TruffleRuby
+# using tree-sitter grammars or language-specific native parsers.
 #
-# @example Basic usage with TOML
+# Supports 10 backends:
+# - Tree-sitter: MRI (C), Rust, FFI, Java
+# - Native parsers: Prism (Ruby), Psych (YAML), Commonmarker (Markdown), Markly (GFM)
+# - Pure Ruby: Citrus (portable fallback)
+#
+# @example Basic usage with tree-sitter
 #   # Load a language grammar
 #   language = TreeHaver::Language.from_library(
 #     "/usr/local/lib/libtree-sitter-toml.so",
@@ -30,8 +35,28 @@ require_relative "tree_haver/language_registry"
 #   tree = parser.parse("[package]\nname = \"my-app\"")
 #   root = tree.root_node
 #
-#   # Traverse the AST
-#   root.each { |child| puts child.type }
+#   # Use unified Position API (works across all backends)
+#   puts root.start_line      # => 1 (1-based)
+#   puts root.source_position # => {start_line:, end_line:, start_column:, end_column:}
+#
+# @example Using language-specific backends
+#   # Parse Ruby with Prism
+#   TreeHaver.backend = :prism
+#   parser = TreeHaver::Parser.new
+#   parser.language = TreeHaver::Backends::Prism::Language.ruby
+#   tree = parser.parse("class Example; end")
+#
+#   # Parse YAML with Psych
+#   TreeHaver.backend = :psych
+#   parser = TreeHaver::Parser.new
+#   parser.language = TreeHaver::Backends::Psych::Language.yaml
+#   tree = parser.parse("key: value")
+#
+#   # Parse Markdown with Commonmarker
+#   TreeHaver.backend = :commonmarker
+#   parser = TreeHaver::Parser.new
+#   parser.language = TreeHaver::Backends::Commonmarker::Language.markdown
+#   tree = parser.parse("# Heading\nParagraph")
 #
 # @example Using language registration
 #   TreeHaver.register_language(:toml, path: "/usr/local/lib/libtree-sitter-toml.so")
@@ -43,22 +68,21 @@ require_relative "tree_haver/language_registry"
 #   finder.register! if finder.available?
 #   language = TreeHaver::Language.toml
 #
-# @example Using GrammarFinder in a *-merge gem
-#   # Each merge gem (toml-merge, json-merge, bash-merge) uses the same pattern
-#   finder = TreeHaver::GrammarFinder.new(:toml)  # or :json, :bash, etc.
-#   if finder.available?
-#     finder.register!
-#   else
-#     warn finder.not_found_message
-#   end
-#
 # @example Selecting a backend
-#   TreeHaver.backend = :ffi  # Force FFI backend
-#   TreeHaver.backend = :mri  # Force MRI backend
-#   TreeHaver.backend = :auto # Auto-select (default)
+#   TreeHaver.backend = :mri          # Force MRI (ruby_tree_sitter)
+#   TreeHaver.backend = :rust         # Force Rust (tree_stump)
+#   TreeHaver.backend = :ffi          # Force FFI
+#   TreeHaver.backend = :java         # Force Java (JRuby)
+#   TreeHaver.backend = :prism        # Force Prism (Ruby)
+#   TreeHaver.backend = :psych        # Force Psych (YAML)
+#   TreeHaver.backend = :commonmarker # Force Commonmarker (Markdown)
+#   TreeHaver.backend = :markly       # Force Markly (GFM)
+#   TreeHaver.backend = :citrus       # Force Citrus (pure Ruby)
+#   TreeHaver.backend = :auto         # Auto-select (default)
 #
 # @see https://tree-sitter.github.io/tree-sitter/ tree-sitter documentation
 # @see GrammarFinder For automatic grammar library discovery
+# @see Backends For available parsing backends
 module TreeHaver
   # Base error class for TreeHaver exceptions
   # @see https://github.com/Faveod/ruby-tree-sitter/pull/83 for inherit from Exception reasoning
@@ -115,12 +139,17 @@ module TreeHaver
   # - {Backends::FFI} - Uses Ruby FFI to call libtree-sitter directly
   # - {Backends::Java} - Uses JRuby's Java integration
   # - {Backends::Citrus} - Uses Citrus PEG parser (pure Ruby, portable)
+  # - {Backends::Prism} - Uses Ruby's built-in Prism parser (Ruby-only, stdlib in 3.4+)
   module Backends
     autoload :MRI, File.join(__dir__, "tree_haver", "backends", "mri")
     autoload :Rust, File.join(__dir__, "tree_haver", "backends", "rust")
     autoload :FFI, File.join(__dir__, "tree_haver", "backends", "ffi")
     autoload :Java, File.join(__dir__, "tree_haver", "backends", "java")
     autoload :Citrus, File.join(__dir__, "tree_haver", "backends", "citrus")
+    autoload :Prism, File.join(__dir__, "tree_haver", "backends", "prism")
+    autoload :Psych, File.join(__dir__, "tree_haver", "backends", "psych")
+    autoload :Commonmarker, File.join(__dir__, "tree_haver", "backends", "commonmarker")
+    autoload :Markly, File.join(__dir__, "tree_haver", "backends", "markly")
 
     # Known backend conflicts
     #
@@ -135,6 +164,10 @@ module TreeHaver
       ffi: [:mri],  # FFI segfaults if MRI (ruby_tree_sitter) has been loaded
       java: [],
       citrus: [],
+      prism: [],        # Prism has no conflicts with other backends
+      psych: [],        # Psych has no conflicts with other backends
+      commonmarker: [], # Commonmarker has no conflicts with other backends
+      markly: [],       # Markly has no conflicts with other backends
     }.freeze
   end
 
@@ -179,6 +212,9 @@ module TreeHaver
   # @see CitrusGrammarFinder
   autoload :CitrusGrammarFinder, File.join(__dir__, "tree_haver", "citrus_grammar_finder")
 
+  # Point class for position information (row, column)
+  autoload :Point, File.join(__dir__, "tree_haver", "point")
+
   # Unified Node wrapper providing consistent API across backends
   autoload :Node, File.join(__dir__, "tree_haver", "node")
 
@@ -201,7 +237,10 @@ module TreeHaver
     # @return [Boolean]
     # @example Disable protection for testing
     #   TreeHaver.backend_protect = false
-    attr_writer :backend_protect
+    def backend_protect=(value)
+      @backend_protect_mutex ||= Mutex.new
+      @backend_protect_mutex.synchronize { @backend_protect = value }
+    end
 
     # Check if backend conflict protection is enabled
     #
@@ -267,6 +306,10 @@ module TreeHaver
       when "ffi" then :ffi
       when "java" then :java
       when "citrus" then :citrus
+      when "prism" then :prism
+      when "psych" then :psych
+      when "commonmarker" then :commonmarker
+      when "markly" then :markly
       else :auto
       end
     end
@@ -463,6 +506,14 @@ module TreeHaver
         Backends::Java
       when :citrus
         Backends::Citrus
+      when :prism
+        Backends::Prism
+      when :psych
+        Backends::Psych
+      when :commonmarker
+        Backends::Commonmarker
+      when :markly
+        Backends::Markly
       when :auto
         backend_module  # Fall back to normal resolution for :auto
       else
@@ -519,6 +570,14 @@ module TreeHaver
         Backends::Java
       when :citrus
         Backends::Citrus
+      when :prism
+        Backends::Prism
+      when :psych
+        Backends::Psych
+      when :commonmarker
+        Backends::Commonmarker
+      when :markly
+        Backends::Markly
       else
         # auto-select: prefer native/fast backends, fall back to pure Ruby (Citrus)
         if defined?(RUBY_ENGINE) && RUBY_ENGINE == "jruby" && Backends::Java.available?
@@ -669,6 +728,111 @@ module TreeHaver
     def registered_language(name)
       LanguageRegistry.registered(name)
     end
+
+    # 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
+    #
+    # @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" }
+    #   )
+    def parser_for(language_name, library_path: nil, symbol: nil, citrus_config: nil)
+      name = language_name.to_sym
+      symbol ||= "tree_sitter_#{name}"
+
+      # 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
+
+      # 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
+
+      # Step 3: Try Citrus fallback if tree-sitter failed
+      unless language
+        citrus_config ||= {}
+        begin
+          citrus_finder = CitrusGrammarFinder.new(
+            language: name,
+            gem_name: citrus_config[:gem_name],
+            grammar_const: citrus_config[:grammar_const],
+          )
+          if citrus_finder.available?
+            citrus_finder.register!
+            language = Language.public_send(name)
+          end
+        rescue NotAvailable, ArgumentError, LoadError, NameError
+          language = nil
+        end
+      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."
+      end
+
+      # Step 5: Create and configure parser
+      parser = Parser.new
+      parser.language = language
+      parser
+    end
   end
 
   # Represents a tree-sitter language grammar
@@ -827,7 +991,8 @@ module TreeHaver
               "Registered backends: #{all_backends.keys.inspect}"
         end
 
-        # For tree-sitter backends, use the path
+        # For tree-sitter backends, try to load from path
+        # If that fails, fall back to Citrus if available
         if reg && reg[:path]
           path = kwargs[:path] || args.first || reg[:path]
           # Symbol priority: kwargs override > registration > derive from method_name
@@ -842,7 +1007,30 @@ module TreeHaver
           # Using symbol-derived name ensures ruby_tree_sitter gets the correct language name
           # e.g., "toml" not "toml_both" when symbol is "tree_sitter_toml"
           name = kwargs[:name] || symbol&.sub(/\Atree_sitter_/, "")
-          return from_library(path, symbol: symbol, name: name)
+
+          begin
+            return from_library(path, symbol: symbol, name: name)
+          rescue NotAvailable, ArgumentError, LoadError, FFI::NotFoundError => _e
+            # Tree-sitter failed to load - check for Citrus fallback
+            # This handles cases where:
+            # - The .so file doesn't exist or can't be loaded (NotAvailable, LoadError)
+            # - FFI can't find required symbols like ts_parser_new (FFI::NotFoundError)
+            # - Invalid arguments were provided (ArgumentError)
+            citrus_reg = all_backends[:citrus]
+            if citrus_reg && citrus_reg[:grammar_module]
+              return Backends::Citrus::Language.new(citrus_reg[:grammar_module])
+            end
+            # No Citrus fallback available, re-raise the original error
+            raise
+          end
+        end
+
+        # 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])
         end
 
         # No appropriate registration found
@@ -913,8 +1101,28 @@ module TreeHaver
         end
       end
 
-      @impl = mod::Parser.new
-      @explicit_backend = backend  # Remember for introspection (always a Symbol or nil)
+      # Try to create the parser, with fallback to Citrus if tree-sitter fails
+      # This enables auto-fallback when tree-sitter runtime isn't available
+      begin
+        @impl = mod::Parser.new
+        @explicit_backend = backend  # Remember for introspection (always a Symbol or nil)
+      rescue NoMethodError, FFI::NotFoundError, LoadError => e
+        # Tree-sitter backend failed (likely missing runtime library)
+        # Try Citrus as fallback if we weren't explicitly asked for a specific backend
+        if backend.nil? || backend == :auto
+          if Backends::Citrus.available?
+            @impl = Backends::Citrus::Parser.new
+            @explicit_backend = :citrus
+          else
+            # No fallback available, re-raise original error
+            raise NotAvailable, "Tree-sitter backend failed: #{e.message}. " \
+              "Citrus fallback not available. Install tree-sitter runtime or citrus gem."
+          end
+        else
+          # Explicit backend was requested, don't fallback
+          raise
+        end
+      end
     end
 
     # Get the backend this parser is using (for introspection)
@@ -952,12 +1160,23 @@ module TreeHaver
     # @example
     #   parser.language = TreeHaver::Language.from_library("/path/to/grammar.so")
     def language=(lang)
+      # Check if this is a Citrus language - if so, we need a Citrus parser
+      # This enables automatic backend switching when tree-sitter fails and
+      # falls back to Citrus
+      if lang.is_a?(Backends::Citrus::Language)
+        unless @impl.is_a?(Backends::Citrus::Parser)
+          # Switch to Citrus parser to match the Citrus language
+          @impl = Backends::Citrus::Parser.new
+          @explicit_backend = :citrus
+        end
+      end
+
       # Unwrap the language before passing to backend
       # Backends receive raw language objects, never TreeHaver wrappers
       inner_lang = unwrap_language(lang)
       @impl.language = inner_lang
       # Return the original (possibly wrapped) language for consistency
-      lang
+      lang # rubocop:disable Lint/Void (intentional return value)
     end
 
     private
@@ -1028,6 +1247,14 @@ module TreeHaver
         return lang.impl if lang.respond_to?(:impl)
       when :citrus
         return lang.grammar_module if lang.respond_to?(:grammar_module)
+      when :prism
+        return lang  # Prism backend expects the Language wrapper
+      when :psych
+        return lang  # Psych backend expects the Language wrapper
+      when :commonmarker
+        return lang  # Commonmarker backend expects the Language wrapper
+      when :markly
+        return lang  # Markly backend expects the Language wrapper
       else
         # Unknown backend (e.g., test backend)
         # Try generic unwrapping methods for flexibility in testing

data/sig/tree_haver.rbs

@@ -1,6 +1,9 @@
 # Type definitions for TreeHaver
 #
-# TreeHaver is a cross-Ruby adapter for the tree-sitter parsing library
+# TreeHaver is a cross-Ruby adapter for code parsing with 10 backends:
+# - Tree-sitter: MRI, Rust, FFI, Java
+# - Native parsers: Prism (Ruby), Psych (YAML), Commonmarker (Markdown), Markly (GFM)
+# - Pure Ruby: Citrus
 
 module TreeHaver
   VERSION: String
@@ -134,6 +137,20 @@ module TreeHaver
     # Get the end point (row, column)
     def end_point: () -> Point
 
+    # Position API - consistent across all backends
+    # Get 1-based line number where node starts
+    def start_line: () -> Integer
+
+    # Get 1-based line number where node ends
+    def end_line: () -> Integer
+
+    # Get complete position information as hash
+    # Returns {start_line:, end_line:, start_column:, end_column:}
+    def source_position: () -> Hash[Symbol, Integer]
+
+    # Get first child node (convenience method)
+    def first_child: () -> Node?
+
     # Get the number of child nodes
     def child_count: () -> Integer
 

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: tree_haver
 version: !ruby/object:Gem::Version
-  version: 3.0.0
+  version: 3.1.1
 platform: ruby
 authors:
 - Peter H. Boling
@@ -133,6 +133,26 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '3.0'
+- !ruby/object:Gem::Dependency
+  name: kettle-soup-cover
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.1'
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 1.1.1
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.1'
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 1.1.1
 - !ruby/object:Gem::Dependency
   name: kettle-test
   requirement: !ruby/object:Gem::Requirement
@@ -241,9 +261,13 @@ files:
 - SECURITY.md
 - lib/tree_haver.rb
 - lib/tree_haver/backends/citrus.rb
+- lib/tree_haver/backends/commonmarker.rb
 - lib/tree_haver/backends/ffi.rb
 - lib/tree_haver/backends/java.rb
+- lib/tree_haver/backends/markly.rb
 - lib/tree_haver/backends/mri.rb
+- lib/tree_haver/backends/prism.rb
+- lib/tree_haver/backends/psych.rb
 - lib/tree_haver/backends/rust.rb
 - lib/tree_haver/citrus_grammar_finder.rb
 - lib/tree_haver/compat.rb
@@ -251,6 +275,9 @@ files:
 - lib/tree_haver/language_registry.rb
 - lib/tree_haver/node.rb
 - lib/tree_haver/path_validator.rb
+- lib/tree_haver/point.rb
+- lib/tree_haver/rspec.rb
+- lib/tree_haver/rspec/dependency_tags.rb
 - lib/tree_haver/tree.rb
 - lib/tree_haver/version.rb
 - sig/tree_haver.rbs
@@ -262,10 +289,10 @@ licenses:
 - MIT
 metadata:
   homepage_uri: https://tree-haver.galtzo.com/
-  source_code_uri: https://github.com/kettle-rb/tree_haver/tree/v3.0.0
-  changelog_uri: https://github.com/kettle-rb/tree_haver/blob/v3.0.0/CHANGELOG.md
+  source_code_uri: https://github.com/kettle-rb/tree_haver/tree/v3.1.1
+  changelog_uri: https://github.com/kettle-rb/tree_haver/blob/v3.1.1/CHANGELOG.md
   bug_tracker_uri: https://github.com/kettle-rb/tree_haver/issues
-  documentation_uri: https://www.rubydoc.info/gems/tree_haver/3.0.0
+  documentation_uri: https://www.rubydoc.info/gems/tree_haver/3.1.1
   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
@@ -295,7 +322,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 4.0.1
+rubygems_version: 4.0.3
 specification_version: 4
 summary: "\U0001F334 Cross-Ruby adapter for tree-sitter parsing that works on MRI,
   JRuby, and TruffleRuby"