tree_haver 4.0.5 → 5.0.1

data/lib/tree_haver/point.rb

@@ -7,6 +7,9 @@ module TreeHaver
   # - Hash access: point[:row], point[:column]
   # - Method access: point.row, point.column
   #
+  # TreeHaver::Point is an alias for TreeHaver::Base::Point, which is a Struct
+  # providing all the necessary functionality.
+  #
   # @example Method access
   #   point = TreeHaver::Point.new(5, 10)
   #   point.row    # => 5
@@ -18,48 +21,7 @@ module TreeHaver
   #
   # @example Converting to hash
   #   point.to_h # => {row: 5, column: 10}
-  class Point
-    attr_reader :row, :column
-
-    # Create a new Point
-    #
-    # @param row [Integer] the row (line) number, 0-indexed
-    # @param column [Integer] the column number, 0-indexed
-    def initialize(row, column)
-      @row = row
-      @column = column
-    end
-
-    # Hash-like access for compatibility
-    #
-    # @param key [Symbol, String] :row or :column
-    # @return [Integer, nil] the value or nil if key not recognized
-    def [](key)
-      case key
-      when :row, "row" then @row
-      when :column, "column" then @column
-      end
-    end
-
-    # Convert to a hash
-    #
-    # @return [Hash{Symbol => Integer}]
-    def to_h
-      {row: @row, column: @column}
-    end
-
-    # String representation
-    #
-    # @return [String]
-    def to_s
-      "(#{@row}, #{@column})"
-    end
-
-    # Inspect representation
-    #
-    # @return [String]
-    def inspect
-      "#<TreeHaver::Point row=#{@row} column=#{@column}>"
-    end
-  end
+  #
+  # @see Base::Point The underlying Struct implementation
+  Point = Base::Point
 end

data/lib/tree_haver/rspec/dependency_tags.rb

@@ -162,7 +162,7 @@ require "set"
 # ==== Language Parsing Capability Tags (*_parsing)
 #
 # [:toml_parsing]
-#   At least one TOML parser (tree-sitter-toml OR toml-rb/Citrus) is available.
+#   At least one TOML parser (tree-sitter-toml OR toml-rb/Citrus OR toml/Parslet) is available.
 #
 # [:markdown_parsing]
 #   At least one markdown parser (commonmarker OR markly) is available.
@@ -531,25 +531,26 @@ module TreeHaver
           nil
         end
 
-        # Check if commonmarker gem is available
+        # ============================================================
+        # Dynamic Backend Availability (via BackendRegistry)
+        # ============================================================
         #
-        # Uses BackendRegistry which allows commonmarker-merge to register its checker.
+        # External gems register tags with BackendRegistry.register_tag which
+        # dynamically defines *_available? methods on this module.
         #
-        # @return [Boolean] true if commonmarker gem is available
-        def commonmarker_available?
-          return @commonmarker_available if defined?(@commonmarker_available)
-          @commonmarker_available = TreeHaver::BackendRegistry.available?(:commonmarker)
-        end
-
-        # Check if markly gem is available
+        # @example External gem registers a tag
+        #   TreeHaver::BackendRegistry.register_tag(
+        #     :my_backend_backend,
+        #     category: :backend,
+        #     require_path: "my_backend/merge"
+        #   ) { MyBackend::Merge::Backend.available? }
         #
-        # Uses BackendRegistry which allows markly-merge to register its checker.
+        #   # The registration automatically defines:
+        #   TreeHaver::RSpec::DependencyTags.my_backend_available?  # => true/false
         #
-        # @return [Boolean] true if markly gem is available
-        def markly_available?
-          return @markly_available if defined?(@markly_available)
-          @markly_available = TreeHaver::BackendRegistry.available?(:markly)
-        end
+        # Built-in backends (prism, psych, citrus, parslet) have explicit methods
+        # defined below. External backends get methods defined dynamically when
+        # their gem calls register_tag.
 
         # Check if prism gem is available
         #
@@ -577,6 +578,16 @@ module TreeHaver
           @citrus_available = TreeHaver::BackendRegistry.available?(:citrus)
         end
 
+        # Check if Parslet backend is available
+        #
+        # This checks if the parslet gem is installed and the backend works.
+        #
+        # @return [Boolean] true if Parslet backend is available
+        def parslet_available?
+          return @parslet_available if defined?(@parslet_available)
+          @parslet_available = TreeHaver::BackendRegistry.available?(:parslet)
+        end
+
         # ============================================================
         # Ruby Engine Detection
         # ============================================================
@@ -697,18 +708,44 @@ module TreeHaver
           end
         end
 
+        # Check if toml gem is available and functional (Parslet backend for TOML)
+        #
+        # @return [Boolean] true if toml gem is available and can parse TOML
+        def toml_gem_available?
+          return @toml_gem_available if defined?(@toml_gem_available)
+          @toml_gem_available = begin
+            require "toml"
+            # Verify it can actually parse - just requiring isn't enough
+            source_toml = <<~TOML
+              # My Information
+              [machine]
+              host = "localhost"
+            TOML
+            TOML.load(source_toml)
+            true
+          rescue LoadError
+            false
+          rescue StandardError
+            false
+          end
+        end
+
         # Check if at least one TOML backend is available
         #
         # @return [Boolean] true if any TOML backend works
         def any_toml_backend_available?
-          tree_sitter_toml_available? || toml_rb_gem_available?
+          tree_sitter_toml_available? || toml_rb_gem_available? || toml_gem_available?
         end
 
         # Check if at least one markdown backend is available
         #
+        # Uses BackendRegistry.tag_available? to check external backends that may
+        # not have their methods defined yet (registered by external gems).
+        #
         # @return [Boolean] true if any markdown backend works
         def any_markdown_backend_available?
-          markly_available? || commonmarker_available?
+          TreeHaver::BackendRegistry.tag_available?(:markly_backend) ||
+            TreeHaver::BackendRegistry.tag_available?(:commonmarker_backend)
         end
 
         def any_native_grammar_available?
@@ -780,44 +817,69 @@ module TreeHaver
           # Use stored blocked_backends if available, otherwise compute dynamically
           blocked = @blocked_backends || compute_blocked_backends
 
-          {
+          result = {
             # Backend selection from environment variables
             selected_backend: selected_backend,
             allowed_native_backends: allowed_native_backends,
             allowed_ruby_backends: allowed_ruby_backends,
-            # TreeHaver backends (*_backend) - skip blocked backends to avoid loading them
-            ffi_backend: blocked.include?(:ffi) ? :blocked : ffi_available?,
-            mri_backend: blocked.include?(:mri) ? :blocked : mri_backend_available?,
-            rust_backend: blocked.include?(:rust) ? :blocked : rust_backend_available?,
-            java_backend: blocked.include?(:java) ? :blocked : java_backend_available?,
-            prism_backend: blocked.include?(:prism) ? :blocked : prism_available?,
-            psych_backend: blocked.include?(:psych) ? :blocked : psych_available?,
-            commonmarker_backend: blocked.include?(:commonmarker) ? :blocked : commonmarker_available?,
-            markly_backend: blocked.include?(:markly) ? :blocked : markly_available?,
-            citrus_backend: blocked.include?(:citrus) ? :blocked : citrus_available?,
-            rbs_backend: blocked.include?(:rbs) ? :blocked : rbs_backend_available?,
-            # Ruby engines (*_engine)
-            ruby_engine: RUBY_ENGINE,
-            mri_engine: mri?,
-            jruby_engine: jruby?,
-            truffleruby_engine: truffleruby?,
-            # Tree-sitter grammars (*_grammar) - also respect blocked backends
-            # since grammar checks may load backends
-            libtree_sitter: libtree_sitter_available?,
-            bash_grammar: blocked.include?(:mri) ? :blocked : tree_sitter_bash_available?,
-            toml_grammar: blocked.include?(:mri) ? :blocked : tree_sitter_toml_available?,
-            json_grammar: blocked.include?(:mri) ? :blocked : tree_sitter_json_available?,
-            jsonc_grammar: blocked.include?(:mri) ? :blocked : tree_sitter_jsonc_available?,
-            rbs_grammar: blocked.include?(:mri) ? :blocked : tree_sitter_rbs_available?,
-            any_native_grammar: blocked.include?(:mri) ? :blocked : any_native_grammar_available?,
-            # Language parsing capabilities (*_parsing)
-            toml_parsing: any_toml_backend_available?,
-            markdown_parsing: any_markdown_backend_available?,
-            rbs_parsing: any_rbs_backend_available?,
-            # Specific libraries (*_gem)
-            toml_rb_gem: toml_rb_gem_available?,
-            rbs_gem: rbs_gem_available?,
           }
+
+          # Built-in TreeHaver backends (*_backend) - skip blocked backends to avoid loading them
+          builtin_backends = {
+            ffi: :ffi_available?,
+            mri: :mri_backend_available?,
+            rust: :rust_backend_available?,
+            java: :java_backend_available?,
+            prism: :prism_available?,
+            psych: :psych_available?,
+            citrus: :citrus_available?,
+            parslet: :parslet_available?,
+            rbs: :rbs_backend_available?,
+          }
+
+          builtin_backends.each do |backend, method|
+            tag = :"#{backend}_backend"
+            result[tag] = blocked.include?(backend) ? :blocked : public_send(method)
+          end
+
+          # Dynamically registered backends from BackendRegistry
+          TreeHaver::BackendRegistry.registered_tags.each do |tag_name|
+            next if result.key?(tag_name) # Don't override built-ins
+
+            meta = TreeHaver::BackendRegistry.tag_metadata(tag_name)
+            next unless meta && meta[:category] == :backend
+
+            backend = meta[:backend_name]
+            result[tag_name] = blocked.include?(backend) ? :blocked : TreeHaver::BackendRegistry.tag_available?(tag_name)
+          end
+
+          # Ruby engines (*_engine)
+          result[:ruby_engine] = RUBY_ENGINE
+          result[:mri_engine] = mri?
+          result[:jruby_engine] = jruby?
+          result[:truffleruby_engine] = truffleruby?
+
+          # Tree-sitter grammars (*_grammar) - also respect blocked backends
+          # since grammar checks may load backends
+          result[:libtree_sitter] = libtree_sitter_available?
+          result[:bash_grammar] = blocked.include?(:mri) ? :blocked : tree_sitter_bash_available?
+          result[:toml_grammar] = blocked.include?(:mri) ? :blocked : tree_sitter_toml_available?
+          result[:json_grammar] = blocked.include?(:mri) ? :blocked : tree_sitter_json_available?
+          result[:jsonc_grammar] = blocked.include?(:mri) ? :blocked : tree_sitter_jsonc_available?
+          result[:rbs_grammar] = blocked.include?(:mri) ? :blocked : tree_sitter_rbs_available?
+          result[:any_native_grammar] = blocked.include?(:mri) ? :blocked : any_native_grammar_available?
+
+          # Language parsing capabilities (*_parsing)
+          result[:toml_parsing] = any_toml_backend_available?
+          result[:markdown_parsing] = any_markdown_backend_available?
+          result[:rbs_parsing] = any_rbs_backend_available?
+
+          # Specific libraries (*_gem)
+          result[:toml_rb_gem] = toml_rb_gem_available?
+          result[:toml_gem] = toml_gem_available?
+          result[:rbs_gem] = rbs_gem_available?
+
+          result
         end
 
         # Get environment variable summary for debugging
@@ -873,7 +935,7 @@ module TreeHaver
         # @param test_source [String] sample source code to parse
         # @return [Boolean] true if parsing works without errors
         def grammar_works?(language, test_source)
-          debug = ENV["TREE_HAVER_DEBUG"]
+          debug = !ENV.fetch("TREE_HAVER_DEBUG", "false").casecmp?("false")
           env_var = "TREE_SITTER_#{language.to_s.upcase}_PATH"
           env_value = ENV[env_var]
 
@@ -938,7 +1000,7 @@ RSpec.configure do |config|
 
   config.before(:suite) do
     # Print dependency summary if TREE_HAVER_DEBUG is set
-    if ENV["TREE_HAVER_DEBUG"]
+    unless ENV.fetch("TREE_HAVER_DEBUG", "false").casecmp?("false")
       puts "\n=== TreeHaver Environment Variables ==="
       deps.env_summary.each do |var, value|
         puts "  #{var}: #{value.inspect}"
@@ -1029,33 +1091,35 @@ RSpec.configure do |config|
   #
   # 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?,
-    rbs: :rbs_backend_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,
-    rbs: :rbs_backend,
-  }
+  # Build backend maps dynamically from BackendRegistry and built-in backends
+  # This allows external gems to register and automatically get tag support
+  backend_availability_methods = {}
+  backend_tags = {}
+
+  # Built-in backends (always present in tree_haver)
+  builtin_backends = %i[mri rust ffi java prism psych citrus parslet rbs]
+  builtin_backends.each do |backend|
+    # Special case for ffi which uses ffi_available? not ffi_backend_available?
+    availability_method = (backend == :ffi) ? :ffi_available? : :"#{backend}_available?"
+    # Special case for backends that use *_backend_available? naming
+    availability_method = :"#{backend}_backend_available?" if %i[mri rust java rbs].include?(backend)
+
+    backend_availability_methods[backend] = availability_method
+    backend_tags[backend] = :"#{backend}_backend"
+  end
+
+  # Add dynamically registered backends from BackendRegistry
+  # This picks up external gems like commonmarker-merge, markly-merge, etc.
+  TreeHaver::BackendRegistry.registered_tags.each do |tag_name|
+    meta = TreeHaver::BackendRegistry.tag_metadata(tag_name)
+    next unless meta && meta[:category] == :backend
+
+    backend_name = meta[:backend_name]
+    next if backend_availability_methods.key?(backend_name) # Don't override built-ins
+
+    backend_availability_methods[backend_name] = :"#{backend_name}_available?"
+    backend_tags[backend_name] = tag_name
+  end
 
   # Determine which backends should NOT have availability checked
   # based on which *_backend_only tag is being run OR which backend is
@@ -1183,7 +1247,7 @@ RSpec.configure do |config|
   # 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)
+  #   :toml_parsing   - any TOML parser (tree-sitter-toml OR toml-rb/Citrus OR toml/Parslet)
   #   :markdown_parsing - any Markdown parser (commonmarker OR markly)
   #   :rbs_parsing    - any RBS parser (rbs gem OR tree-sitter-rbs)
   #   :native_parsing - any native tree-sitter backend + grammar
@@ -1202,10 +1266,12 @@ RSpec.configure do |config|
   # Specific Library Tags
   # ============================================================
   # Tags for specific gems/libraries (*_gem suffix)
+  #   :toml_gem - the toml gem (Parslet-based TOML parser)
   #   :toml_rb_gem - the toml-rb gem (Citrus-based TOML parser)
   #   :rbs_gem - the rbs gem (official RBS parser, MRI only)
   #   Note: :rbs_backend is also available as an alias for :rbs_gem
 
+  config.filter_run_excluding(toml_gem: true) unless deps.toml_gem_available?
   config.filter_run_excluding(toml_rb_gem: true) unless deps.toml_rb_gem_available?
   config.filter_run_excluding(rbs_gem: true) unless deps.rbs_gem_available?
 
@@ -1249,6 +1315,7 @@ RSpec.configure do |config|
   end
 
   # Specific libraries
+  config.filter_run_excluding(not_toml_gem: true) if deps.toml_gem_available?
   config.filter_run_excluding(not_toml_rb_gem: true) if deps.toml_rb_gem_available?
   config.filter_run_excluding(not_rbs_gem: true) if deps.rbs_gem_available?
 end

data/lib/tree_haver/rspec/testable_node.rb

@@ -0,0 +1,217 @@
+# frozen_string_literal: true
+
+# Ensure TreeHaver::Node and TreeHaver::Point are loaded
+require "tree_haver"
+
+module TreeHaver
+  module RSpec
+    # A mock inner node that provides the minimal interface TreeHaver::Node expects.
+    #
+    # This is what TreeHaver::Node wraps - it simulates the backend-specific node
+    # (like tree-sitter's Node, Markly::Node, etc.)
+    #
+    # @api private
+    class MockInnerNode
+      attr_reader :type, :start_byte, :end_byte, :children_data
+
+      def initialize(
+        type:,
+        text: nil,
+        start_byte: 0,
+        end_byte: nil,
+        start_row: 0,
+        start_column: 0,
+        end_row: nil,
+        end_column: nil,
+        children: []
+      )
+        @type = type.to_s
+        @text_content = text
+        @start_byte = start_byte
+        @end_byte = end_byte || (text ? start_byte + text.length : start_byte)
+        @start_row = start_row
+        @start_column = start_column
+        @end_row = end_row || start_row
+        @end_column = end_column || (text ? start_column + text.length : start_column)
+        @children_data = children
+      end
+
+      def start_point
+        TreeHaver::Point.new(@start_row, @start_column)
+      end
+
+      def end_point
+        TreeHaver::Point.new(@end_row, @end_column)
+      end
+
+      def child_count
+        @children_data.length
+      end
+
+      def child(index)
+        return if index.nil? || index < 0 || index >= @children_data.length
+
+        @children_data[index]
+      end
+
+      # Return children array (for enumerable behavior)
+      def children
+        @children_data
+      end
+
+      def first_child
+        @children_data.first
+      end
+
+      def last_child
+        @children_data.last
+      end
+
+      # Iterate over children
+      def each(&block)
+        return enum_for(:each) unless block
+
+        @children_data.each(&block)
+      end
+
+      def named?
+        true
+      end
+
+      # Test nodes are always valid (no parse errors)
+      def has_error?
+        false
+      end
+
+      # Test nodes are never missing (not error recovery insertions)
+      def missing?
+        false
+      end
+
+      # Some backends provide text directly
+      def text
+        @text_content
+      end
+
+      # For backends that use string_content (like Markly/Commonmarker)
+      def string_content
+        @text_content
+      end
+    end
+
+    # A real TreeHaver::Node that wraps a MockInnerNode.
+    #
+    # This gives us full TreeHaver::Node behavior (#text, #type, #source_position, etc.)
+    # while allowing us to control the underlying data for testing.
+    #
+    # TestableNode is designed for testing code that works with TreeHaver nodes
+    # without requiring an actual parser backend. It creates real TreeHaver::Node
+    # instances with controlled, predictable data.
+    #
+    # @example Creating a testable node
+    #   node = TreeHaver::RSpec::TestableNode.create(
+    #     type: :heading,
+    #     text: "## My Heading",
+    #     start_line: 1
+    #   )
+    #   node.text       # => "## My Heading"
+    #   node.type       # => "heading"
+    #   node.start_line # => 1
+    #
+    # @example Creating with children
+    #   parent = TreeHaver::RSpec::TestableNode.create(
+    #     type: :document,
+    #     text: "# Title\n\nParagraph",
+    #     children: [
+    #       { type: :heading, text: "# Title", start_line: 1 },
+    #       { type: :paragraph, text: "Paragraph", start_line: 3 },
+    #     ]
+    #   )
+    #
+    # @example Using the convenience constant
+    #   # After requiring tree_haver/rspec/testable_node, you can use:
+    #   node = TestableNode.create(type: :paragraph, text: "Hello")
+    #
+    class TestableNode < TreeHaver::Node
+      class << self
+        # Create a TestableNode with the given attributes.
+        #
+        # @param type [Symbol, String] Node type (e.g., :heading, :paragraph)
+        # @param text [String] The text content of the node
+        # @param start_line [Integer] 1-based start line number (default: 1)
+        # @param end_line [Integer, nil] 1-based end line number (default: calculated from text)
+        # @param start_column [Integer] 0-based start column (default: 0)
+        # @param end_column [Integer, nil] 0-based end column (default: calculated from text)
+        # @param start_byte [Integer] Start byte offset (default: 0)
+        # @param end_byte [Integer, nil] End byte offset (default: calculated from text)
+        # @param children [Array<Hash>] Child node specifications
+        # @param source [String, nil] Full source text (default: uses text param)
+        # @return [TestableNode]
+        def create(
+          type:,
+          text: "",
+          start_line: 1,
+          end_line: nil,
+          start_column: 0,
+          end_column: nil,
+          start_byte: 0,
+          end_byte: nil,
+          children: [],
+          source: nil
+        )
+          # Convert 1-based line to 0-based row
+          start_row = start_line - 1
+          end_row = end_line ? end_line - 1 : start_row + text.count("\n")
+
+          # Calculate end_column if not provided
+          if end_column.nil?
+            lines = text.split("\n", -1)
+            end_column = lines.last&.length || 0
+          end
+
+          # Build children as MockInnerNodes
+          child_nodes = children.map do |child_spec|
+            MockInnerNode.new(**child_spec)
+          end
+
+          inner = MockInnerNode.new(
+            type: type,
+            text: text,
+            start_byte: start_byte,
+            end_byte: end_byte,
+            start_row: start_row,
+            start_column: start_column,
+            end_row: end_row,
+            end_column: end_column,
+            children: child_nodes,
+          )
+
+          # Create a real TreeHaver::Node wrapping our mock
+          # Pass source so TreeHaver::Node can extract text if needed
+          new(inner, source: source || text)
+        end
+
+        # Create multiple nodes from an array of specifications.
+        #
+        # @param specs [Array<Hash>] Array of node specifications
+        # @return [Array<TestableNode>]
+        def create_list(*specs)
+          specs.flatten.map { |spec| create(**spec) }
+        end
+      end
+
+      # Additional test helper methods
+
+      # Check if this is a testable node (for test assertions)
+      #
+      # @return [Boolean] true
+      def testable?
+        true
+      end
+    end
+  end
+end
+
+# Make TestableNode available at top level for convenience in specs.
+# This allows specs to use `TestableNode.create(...)` without the full namespace.
+TestableNode = TreeHaver::RSpec::TestableNode

data/lib/tree_haver/rspec.rb

@@ -9,7 +9,7 @@
 #
 # This will load:
 # - Dependency tags for conditional test execution
-# - (Future) Additional test helpers as needed
+# - TestableNode for creating mock nodes in tests
 #
 # @example spec_helper.rb
 #   require "tree_haver/rspec"
@@ -18,6 +18,16 @@
 #     # Your additional configuration...
 #   end
 #
+# @example Using TestableNode
+#   node = TestableNode.create(
+#     type: :heading,
+#     text: "## My Heading",
+#     start_line: 1
+#   )
+#   expect(node.type).to eq("heading")
+#
 # @see TreeHaver::RSpec::DependencyTags
+# @see TreeHaver::RSpec::TestableNode
 
 require_relative "rspec/dependency_tags"
+require_relative "rspec/testable_node"

data/lib/tree_haver/version.rb

@@ -10,7 +10,7 @@ module TreeHaver
     # Current version of the tree_haver gem
     #
     # @return [String] the version string
-    VERSION = "4.0.5"
+    VERSION = "5.0.1"
   end
 
   # Traditional location for VERSION constant