tree_haver 5.0.0 → 5.0.2

data/lib/tree_haver/backend_api.rb

@@ -234,12 +234,12 @@ module TreeHaver
       private
 
       def validate_module_methods(mod, results)
-        unless mod.respond_to?(:available?)
+        unless mod.singleton_class.method_defined?(:available?)
           results[:errors] << "Missing module method: available?"
           results[:valid] = false
         end
 
-        unless mod.respond_to?(:capabilities)
+        unless mod.singleton_class.method_defined?(:capabilities)
           results[:warnings] << "Missing module method: capabilities"
         end
       end
@@ -248,26 +248,26 @@ module TreeHaver
         # from_library is REQUIRED for all backends
         # Language-specific backends should implement it to ignore path/symbol
         # and return their single language (for API consistency)
-        unless klass.respond_to?(:from_library)
+        unless klass.singleton_class.method_defined?(:from_library)
           results[:errors] << "Language missing required class method: from_library"
           results[:valid] = false
         end
 
         # Check for optional convenience methods
-        optional_methods = LANGUAGE_OPTIONAL_CLASS_METHODS.select { |m| klass.respond_to?(m) }
+        optional_methods = LANGUAGE_OPTIONAL_CLASS_METHODS.select { |m| klass.singleton_class.method_defined?(m) }
         if optional_methods.any?
           results[:capabilities][:language_shortcuts] = optional_methods
         end
 
         results[:capabilities][:language] = {
-          class_methods: LANGUAGE_CLASS_METHODS.select { |m| klass.respond_to?(m) } +
+          class_methods: LANGUAGE_CLASS_METHODS.select { |m| klass.singleton_class.method_defined?(m) } +
             optional_methods,
         }
       end
 
       def validate_parser(klass, results)
         PARSER_CLASS_METHODS.each do |method|
-          unless klass.respond_to?(method)
+          unless klass.singleton_class.method_defined?(method)
             results[:errors] << "Parser missing class method: #{method}"
             results[:valid] = false
           end
@@ -275,14 +275,14 @@ module TreeHaver
 
         # Check instance methods by inspecting the class
         PARSER_INSTANCE_METHODS.each do |method|
-          unless klass.instance_methods.include?(method) || klass.private_instance_methods.include?(method)
+          unless klass.method_defined?(method) || klass.private_method_defined?(method)
             results[:errors] << "Parser missing instance method: #{method}"
             results[:valid] = false
           end
         end
 
         PARSER_OPTIONAL_METHODS.each do |method|
-          unless klass.instance_methods.include?(method)
+          unless klass.method_defined?(method)
             results[:warnings] << "Parser missing optional method: #{method}"
           end
         end
@@ -290,14 +290,14 @@ module TreeHaver
 
       def validate_tree(klass, results)
         TREE_INSTANCE_METHODS.each do |method|
-          unless klass.instance_methods.include?(method)
+          unless klass.method_defined?(method)
             results[:errors] << "Tree missing instance method: #{method}"
             results[:valid] = false
           end
         end
 
         TREE_OPTIONAL_METHODS.each do |method|
-          unless klass.instance_methods.include?(method)
+          unless klass.method_defined?(method)
             results[:warnings] << "Tree missing optional method: #{method}"
           end
         end
@@ -330,11 +330,11 @@ module TreeHaver
       end
 
       def has_method_or_alias?(klass, method)
-        return true if klass.instance_methods.include?(method)
+        return true if klass.method_defined?(method)
 
         # Check aliases
         aliases = NODE_ALIASES[method] || []
-        aliases.any? { |alt| klass.instance_methods.include?(alt) }
+        aliases.any? { |alt| klass.method_defined?(alt) }
       end
 
       def responds_to_with_aliases?(obj, method)

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/grammar_finder.rb

@@ -264,12 +264,13 @@ module TreeHaver
 
           # Only tree-sitter backends are relevant here
           # Non-tree-sitter backends (Citrus, Prism, Psych, etc.) don't use grammar files
-          return false if mod.nil?
-          return false unless TREE_SITTER_BACKENDS.include?(mod)
-
-          # Try to instantiate a parser - this will fail if runtime isn't available
-          mod::Parser.new
-          true
+          if mod.nil? || !TREE_SITTER_BACKENDS.include?(mod)
+            false
+          else
+            # Try to instantiate a parser - this will fail if runtime isn't available
+            mod::Parser.new
+            true
+          end
         rescue NoMethodError, LoadError, NotAvailable => _e
           # Note: FFI::NotFoundError inherits from LoadError, so it's caught here too
           false

data/lib/tree_haver/parser.rb

@@ -364,10 +364,12 @@ module TreeHaver
 
       case lang.backend
       when :mri
-        lang.to_language if lang.respond_to?(:to_language)
-        lang.inner_language if lang.respond_to?(:inner_language)
+        return lang.to_language if lang.respond_to?(:to_language)
+        return lang.inner_language if lang.respond_to?(:inner_language)
+        lang
       when :rust
-        lang.name if lang.respond_to?(:name)
+        return lang.name if lang.respond_to?(:name)
+        lang
       when :ffi
         lang  # FFI needs wrapper for to_ptr
       when :java