tree_haver 4.0.5 → 5.0.1

data/lib/tree_haver/backend_registry.rb

@@ -22,27 +22,44 @@ module TreeHaver
   # - **External backends** (commonmarker-merge, markly-merge, rbs-merge) register
   #   their checkers when their backend module is loaded
   #
+  # == Full Tag Registration
+  #
+  # External gems can register complete tag support using {register_tag}:
+  # - Tag name (e.g., :commonmarker_backend)
+  # - Category (:backend, :gem, :parsing, :grammar)
+  # - Availability checker
+  # - Optional require path for lazy loading
+  #
+  # This enables tree_haver/rspec/dependency_tags to automatically configure
+  # RSpec exclusion filters for any registered tag without hardcoded knowledge.
+  #
   # == Thread Safety
   #
   # All operations are thread-safe using a Mutex for synchronization.
   # Results are cached after first check for performance.
   #
-  # @example Registering a backend availability checker (in your gem)
+  # @example Registering a backend availability checker (simple form)
   #   # In commonmarker-merge/lib/commonmarker/merge/backend.rb
   #   TreeHaver::BackendRegistry.register_availability_checker(:commonmarker) do
   #     available?
   #   end
   #
+  # @example Registering a full tag with require path (preferred for external gems)
+  #   TreeHaver::BackendRegistry.register_tag(
+  #     :commonmarker_backend,
+  #     category: :backend,
+  #     backend_name: :commonmarker,
+  #     require_path: "commonmarker/merge"
+  #   ) { Commonmarker::Merge::Backend.available? }
+  #
   # @example Checking backend availability
   #   TreeHaver::BackendRegistry.available?(:commonmarker)  # => true/false
   #   TreeHaver::BackendRegistry.available?(:markly)        # => true/false
   #   TreeHaver::BackendRegistry.available?(:rbs)           # => true/false
   #
-  # @example Checking if a checker is registered
-  #   TreeHaver::BackendRegistry.registered?(:commonmarker) # => true/false
-  #
-  # @example Getting all registered backends
-  #   TreeHaver::BackendRegistry.registered_backends # => [:mri, :rust, :ffi, ...]
+  # @example Getting all registered tags
+  #   TreeHaver::BackendRegistry.registered_tags # => [:commonmarker_backend, :markly_backend, ...]
+  #   TreeHaver::BackendRegistry.tags_by_category(:backend) # => [...]
   #
   # @see TreeHaver::RSpec::DependencyTags Uses BackendRegistry for dynamic backend detection
   # @api public
@@ -50,15 +67,83 @@ module TreeHaver
     @mutex = Mutex.new
     @availability_checkers = {} # rubocop:disable ThreadSafety/MutableClassInstanceVariable
     @availability_cache = {} # rubocop:disable ThreadSafety/MutableClassInstanceVariable
+    @tag_registry = {} # rubocop:disable ThreadSafety/MutableClassInstanceVariable
+
+    # Tag categories for organizing dependency tags
+    # @api private
+    CATEGORIES = %i[backend gem parsing grammar engine other].freeze
 
     module_function
 
-    # Register an availability checker for a backend
+    # Register a full dependency tag with all metadata
+    #
+    # This is the preferred method for external gems to register their availability
+    # with complete tag support. It registers both the availability checker and
+    # the tag metadata needed for RSpec configuration.
+    #
+    # When a tag is registered, this also dynamically defines a `*_available?` method
+    # on `TreeHaver::RSpec::DependencyTags` if it doesn't already exist.
+    #
+    # @param tag_name [Symbol] the RSpec tag name (e.g., :commonmarker_backend)
+    # @param category [Symbol] one of :backend, :gem, :parsing, :grammar, :engine, :other
+    # @param backend_name [Symbol, nil] the backend name for availability checks (defaults to tag without suffix)
+    # @param require_path [String, nil] optional require path to load before checking availability
+    # @param checker [#call, nil] a callable that returns true if available
+    # @yield Block form of checker (alternative to passing a callable)
+    # @yieldreturn [Boolean] true if the tag's dependency is available
+    # @return [void]
+    #
+    # @example Register a backend tag with require path
+    #   TreeHaver::BackendRegistry.register_tag(
+    #     :commonmarker_backend,
+    #     category: :backend,
+    #     require_path: "commonmarker/merge"
+    #   ) { Commonmarker::Merge::Backend.available? }
+    #
+    # @example Register a gem tag
+    #   TreeHaver::BackendRegistry.register_tag(
+    #     :toml_gem,
+    #     category: :gem,
+    #     require_path: "toml"
+    #   ) { defined?(TOML) }
+    def register_tag(tag_name, category:, backend_name: nil, require_path: nil, checker: nil, &block)
+      callable = checker || block
+      raise ArgumentError, "Must provide a checker callable or block" unless callable
+      raise ArgumentError, "Checker must respond to #call" unless callable.respond_to?(:call)
+      raise ArgumentError, "Invalid category: #{category}" unless CATEGORIES.include?(category)
+
+      tag_sym = tag_name.to_sym
+      # Derive backend_name from tag_name if not provided (e.g., :commonmarker_backend -> :commonmarker)
+      derived_backend = backend_name || tag_sym.to_s.sub(/_backend$/, "").to_sym
+
+      @mutex.synchronize do
+        @tag_registry[tag_sym] = {
+          category: category,
+          backend_name: derived_backend,
+          require_path: require_path,
+          checker: callable,
+        }
+        # Also register as availability checker for the backend name
+        @availability_checkers[derived_backend] = callable
+        # Clear caches
+        @availability_cache.delete(derived_backend)
+      end
+
+      # Dynamically define the availability method on DependencyTags
+      # This happens outside the mutex to avoid potential deadlock
+      define_availability_method(derived_backend, tag_sym)
+
+      nil
+    end
+
+    # Register an availability checker for a backend (simple form)
     #
     # The checker should be a callable (lambda/proc/block) that returns true if
     # the backend is available and can be used. The checker is called lazily
     # (only when {available?} is first called for this backend).
     #
+    # For full tag support including require paths, use {register_tag} instead.
+    #
     # @param backend_name [Symbol, String] the backend name (e.g., :commonmarker, :markly)
     # @param checker [#call, nil] a callable that returns true if the backend is available
     # @yield Block form of checker (alternative to passing a callable)
@@ -206,10 +291,118 @@ module TreeHaver
       @mutex.synchronize do
         @availability_checkers.clear
         @availability_cache.clear
+        @tag_registry.clear
       end
       nil
     end
 
+    # ============================================================
+    # Tag Registry Methods
+    # ============================================================
+
+    # Get all registered tag names
+    #
+    # @return [Array<Symbol>] list of registered tag names
+    #
+    # @example
+    #   TreeHaver::BackendRegistry.registered_tags
+    #   # => [:commonmarker_backend, :markly_backend, :toml_gem, ...]
+    def registered_tags
+      @mutex.synchronize do
+        @tag_registry.keys.dup
+      end
+    end
+
+    # Get tags filtered by category
+    #
+    # @param category [Symbol] one of :backend, :gem, :parsing, :grammar, :engine, :other
+    # @return [Array<Symbol>] list of tag names in that category
+    #
+    # @example
+    #   TreeHaver::BackendRegistry.tags_by_category(:backend)
+    #   # => [:commonmarker_backend, :markly_backend, :mri_backend, ...]
+    def tags_by_category(category)
+      @mutex.synchronize do
+        @tag_registry.select { |_, meta| meta[:category] == category }.keys
+      end
+    end
+
+    # Get tag metadata
+    #
+    # @param tag_name [Symbol] the tag name
+    # @return [Hash, nil] tag metadata or nil if not registered
+    #
+    # @example
+    #   TreeHaver::BackendRegistry.tag_metadata(:commonmarker_backend)
+    #   # => { category: :backend, backend_name: :commonmarker, require_path: "commonmarker/merge", checker: #<Proc> }
+    def tag_metadata(tag_name)
+      @mutex.synchronize do
+        @tag_registry[tag_name.to_sym]&.dup
+      end
+    end
+
+    # Check if a tag is registered
+    #
+    # @param tag_name [Symbol] the tag name
+    # @return [Boolean] true if the tag is registered
+    def tag_registered?(tag_name)
+      @mutex.synchronize do
+        @tag_registry.key?(tag_name.to_sym)
+      end
+    end
+
+    # Check if a tag's dependency is available
+    #
+    # This method handles require paths: if the tag has a require_path, it will
+    # attempt to load the gem before checking availability. This enables lazy
+    # loading of external gems.
+    #
+    # @param tag_name [Symbol] the tag name to check
+    # @return [Boolean] true if the tag's dependency is available
+    #
+    # @example
+    #   TreeHaver::BackendRegistry.tag_available?(:commonmarker_backend)  # => true/false
+    def tag_available?(tag_name)
+      tag_sym = tag_name.to_sym
+
+      # Get tag metadata
+      meta = @mutex.synchronize { @tag_registry[tag_sym] }
+
+      # If tag not registered, check if it's a backend name with _backend suffix
+      unless meta
+        # Try to derive backend name (e.g., :commonmarker_backend -> :commonmarker)
+        backend_name = tag_sym.to_s.sub(/_backend$/, "").to_sym
+        return available?(backend_name) if backend_name != tag_sym
+        return false
+      end
+
+      # Try to load the gem if require_path is specified
+      if meta[:require_path]
+        begin
+          require meta[:require_path]
+        rescue LoadError
+          # Gem not available
+          return false
+        end
+      end
+
+      # Check availability using the backend name
+      available?(meta[:backend_name])
+    end
+
+    # Get a summary of all registered tags and their availability
+    #
+    # @return [Hash{Symbol => Boolean}] map of tag name to availability
+    #
+    # @example
+    #   TreeHaver::BackendRegistry.tag_summary
+    #   # => { commonmarker_backend: true, markly_backend: false, ... }
+    def tag_summary
+      @mutex.synchronize { @tag_registry.keys.dup }.each_with_object({}) do |tag, result|
+        result[tag] = tag_available?(tag)
+      end
+    end
+
     # Check a built-in TreeHaver backend
     #
     # Attempts to find the backend module at `TreeHaver::Backends::<Name>` and
@@ -230,5 +423,35 @@ module TreeHaver
       false
     end
     private_class_method :check_builtin_backend
+
+    # Dynamically define an availability method on DependencyTags
+    #
+    # This creates a `*_available?` method that checks tag_available? with
+    # memoization. The method is only defined if DependencyTags is loaded
+    # and doesn't already have a method with that name.
+    #
+    # @param backend_name [Symbol] the backend name (e.g., :commonmarker)
+    # @param tag_name [Symbol] the tag name (e.g., :commonmarker_backend)
+    # @return [void]
+    # @api private
+    def define_availability_method(backend_name, tag_name)
+      method_name = :"#{backend_name}_available?"
+
+      # Only define if DependencyTags is loaded
+      return unless defined?(TreeHaver::RSpec::DependencyTags)
+
+      deps = TreeHaver::RSpec::DependencyTags
+
+      # Don't override existing methods (built-in backends have explicit methods)
+      return if deps.respond_to?(method_name)
+
+      # Define the method dynamically
+      ivar = :"@#{backend_name}_available"
+      deps.define_singleton_method(method_name) do
+        return instance_variable_get(ivar) if instance_variable_defined?(ivar)
+        instance_variable_set(ivar, TreeHaver::BackendRegistry.tag_available?(tag_name))
+      end
+    end
+    private_class_method :define_availability_method
   end
 end

data/lib/tree_haver/backends/citrus.rb

@@ -45,8 +45,10 @@ module TreeHaver
             @loaded = true # rubocop:disable ThreadSafety/ClassInstanceVariable
           rescue LoadError
             @loaded = false # rubocop:disable ThreadSafety/ClassInstanceVariable
+            # :nocov: defensive code - StandardError during require is extremely rare
           rescue StandardError
             @loaded = false # rubocop:disable ThreadSafety/ClassInstanceVariable
+            # :nocov:
           end
           @loaded # rubocop:disable ThreadSafety/ClassInstanceVariable
         end
@@ -108,6 +110,22 @@ module TreeHaver
           @backend = :citrus
         end
 
+        # Get the language name
+        #
+        # Derives a name from the grammar module name.
+        #
+        # @return [Symbol] language name
+        def language_name
+          # Derive name from grammar module (e.g., TomlRB::Document -> :toml)
+          return :unknown unless @grammar_module.respond_to?(:name) && @grammar_module.name
+
+          name = @grammar_module.name.to_s.split("::").first.downcase
+          name.sub(/rb$/, "").to_sym
+        end
+
+        # Alias for language_name (API compatibility)
+        alias_method :name, :language_name
+
         # Compare languages for equality
         #
         # Citrus languages are equal if they have the same backend and grammar_module.
@@ -192,23 +210,31 @@ module TreeHaver
 
         # Set the grammar for this parser
         #
-        # Note: TreeHaver::Parser unwraps language objects before calling this method.
-        # This backend receives the raw Citrus grammar module (unwrapped), not the Language wrapper.
+        # Accepts either a Citrus::Language wrapper or a raw Citrus grammar module.
+        # When passed a Language wrapper, extracts the grammar_module from it.
+        # When passed a raw grammar module, uses it directly.
         #
-        # @param grammar [Module] Citrus grammar module with a parse method
+        # This flexibility allows both patterns:
+        #   parser.language = TreeHaver::Backends::Citrus::Language.new(TomlRB::Document)
+        #   parser.language = TomlRB::Document  # Also works
+        #
+        # @param grammar [Language, Module] Citrus Language wrapper or grammar module
         # @return [void]
-        # @example
-        #   require "toml-rb"
-        #   # TreeHaver::Parser unwraps Language.new(TomlRB::Document) to just TomlRB::Document
-        #   parser.language = TomlRB::Document  # Backend receives unwrapped module
         def language=(grammar)
-          # grammar is already unwrapped by TreeHaver::Parser
-          unless grammar.respond_to?(:parse)
+          # Accept Language wrapper or raw grammar module
+          actual_grammar = case grammar
+          when Language
+            grammar.grammar_module
+          else
+            grammar
+          end
+
+          unless actual_grammar.respond_to?(:parse)
             raise ArgumentError,
-              "Expected Citrus grammar module with parse method, " \
+              "Expected Citrus grammar module with parse method or Language wrapper, " \
                 "got #{grammar.class}"
           end
-          @grammar = grammar
+          @grammar = actual_grammar
         end
 
         # Parse source code
@@ -247,13 +273,18 @@ module TreeHaver
       # Wraps a Citrus::Match (which represents the parse tree) to provide
       # tree-sitter-compatible API.
       #
+      # Inherits from Base::Tree to get shared methods like #errors, #warnings,
+      # #comments, #has_error?, and #inspect.
+      #
       # @api private
-      class Tree
-        attr_reader :root_match, :source
+      class Tree < TreeHaver::Base::Tree
+        # The raw Citrus::Match root
+        # @return [Citrus::Match] The root match
+        attr_reader :root_match
 
         def initialize(root_match, source)
           @root_match = root_match
-          @source = source
+          super(root_match, source: source)
         end
 
         def root_node
@@ -273,22 +304,24 @@ module TreeHaver
       # - matches: child matches
       # - captures: named groups
       #
+      # Inherits from Base::Node to get shared methods like #first_child, #last_child,
+      # #to_s, #inspect, #==, #<=>, #source_position, #start_line, #end_line, etc.
+      #
       # Language-specific helpers can be mixed in for convenience:
       #   require "tree_haver/backends/citrus/toml_helpers"
       #   TreeHaver::Backends::Citrus::Node.include(TreeHaver::Backends::Citrus::TomlHelpers)
       #
       # @api private
-      class Node
-        include Comparable
-        include Enumerable
-
-        attr_reader :match, :source
+      class Node < TreeHaver::Base::Node
+        attr_reader :match
 
         def initialize(match, source)
           @match = match
-          @source = source
+          super(match, source: source)
         end
 
+        # -- Required API Methods (from Base::Node) ----------------------------
+
         # Get node type from Citrus rule name
         #
         # Uses Citrus grammar introspection to dynamically determine node types.
@@ -308,6 +341,50 @@ module TreeHaver
           extract_type_from_event(@match.events.first)
         end
 
+        def start_byte
+          @match.offset
+        end
+
+        def end_byte
+          @match.offset + @match.length
+        end
+
+        def children
+          return [] unless @match.respond_to?(:matches)
+          @match.matches.map { |m| Node.new(m, @source) }
+        end
+
+        # -- Overridden Methods ------------------------------------------------
+
+        # Override start_point to calculate from source
+        def start_point
+          calculate_point(@match.offset)
+        end
+
+        # Override end_point to calculate from source
+        def end_point
+          calculate_point(@match.offset + @match.length)
+        end
+
+        # Override text to use Citrus match string
+        def text
+          @match.string
+        end
+
+        # Override child_count for efficiency (avoid building full children array)
+        def child_count
+          @match.respond_to?(:matches) ? @match.matches.size : 0
+        end
+
+        # Override child to handle negative indices properly
+        def child(index)
+          return if index.negative?
+          return unless @match.respond_to?(:matches)
+          return if index >= @match.matches.size
+
+          Node.new(@match.matches[index], @source)
+        end
+
         # Check if this node represents a structural element vs a terminal/token
         #
         # Uses Citrus grammar's terminal? method to determine if this is
@@ -387,99 +464,6 @@ module TreeHaver
           "unknown"
         end
 
-        public
-
-        def start_byte
-          @match.offset
-        end
-
-        def end_byte
-          @match.offset + @match.length
-        end
-
-        def start_point
-          calculate_point(@match.offset)
-        end
-
-        def end_point
-          calculate_point(@match.offset + @match.length)
-        end
-
-        # Get the 1-based line number where this node starts
-        #
-        # @return [Integer] 1-based line number
-        def start_line
-          start_point[:row] + 1
-        end
-
-        # Get the 1-based line number where this node ends
-        #
-        # @return [Integer] 1-based line number
-        def end_line
-          end_point[:row] + 1
-        end
-
-        # Get position information as a hash
-        #
-        # Returns a hash with 1-based line numbers and 0-based columns.
-        # Compatible with *-merge gems' FileAnalysisBase.
-        #
-        # @return [Hash{Symbol => Integer}] Position hash
-        def source_position
-          {
-            start_line: start_line,
-            end_line: end_line,
-            start_column: start_point[:column],
-            end_column: end_point[:column],
-          }
-        end
-
-        # Get the first child node
-        #
-        # @return [Node, nil] First child or nil
-        def first_child
-          child(0)
-        end
-
-        def text
-          @match.string
-        end
-
-        def child_count
-          @match.respond_to?(:matches) ? @match.matches.size : 0
-        end
-
-        def child(index)
-          return unless @match.respond_to?(:matches)
-          return if index >= @match.matches.size
-
-          Node.new(@match.matches[index], @source)
-        end
-
-        def children
-          return [] unless @match.respond_to?(:matches)
-          @match.matches.map { |m| Node.new(m, @source) }
-        end
-
-        def each(&block)
-          return to_enum(__method__) unless block_given?
-          children.each(&block)
-        end
-
-        def has_error?
-          false  # Citrus raises on parse error, so successful parse has no errors
-        end
-
-        def missing?
-          false  # Citrus doesn't have the concept of missing nodes
-        end
-
-        def named?
-          true  # Citrus matches are typically "named" in tree-sitter terminology
-        end
-
-        private
-
         def calculate_point(offset)
           return {row: 0, column: 0} if offset <= 0
 
@@ -494,7 +478,7 @@ module TreeHaver
         end
       end
 
-      # Register availability checker for RSpec dependency tags
+      # Register the availability checker for RSpec dependency tags
       TreeHaver::BackendRegistry.register_availability_checker(:citrus) do
         available?
       end