tree_haver 5.0.5 → 7.1.0

data/lib/tree_haver/backend_api.rb

@@ -28,6 +28,19 @@ module TreeHaver
   #   TreeHaver::BackendAPI.validate_node!(node_instance)
   #
   module BackendAPI
+    # Descriptive levels for backend comment support.
+    #
+    # - :full - backend can expose comment nodes plus strong attachment hints
+    # - :partial - backend can expose comments, but ownership/attachment is incomplete
+    # - :nodes_only - backend can surface comment nodes/tokens only
+    # - :none - backend does not expose comments through TreeHaver
+    COMMENT_SUPPORT_LEVELS = %i[
+      full
+      partial
+      nodes_only
+      none
+    ].freeze
+
     # Required methods for Language class/instances
     #
     # All backends MUST implement `from_library` for API consistency.
@@ -120,7 +133,7 @@ module TreeHaver
       has_error?: %i[has_error],
       missing?: %i[is_missing? is_missing],
       next_sibling: %i[next_named_sibling],
-      prev_sibling: %i[previous_sibling previous_named_sibling prev_named_sibling],
+      prev_sibling: %i[previous_sibling previous_named_sibling prev_named_sibling]
     }.freeze
 
     class << self
@@ -134,7 +147,7 @@ module TreeHaver
           valid: true,
           errors: [],
           warnings: [],
-          capabilities: {},
+          capabilities: {}
         }
 
         # Check module-level methods
@@ -144,7 +157,7 @@ module TreeHaver
         if backend_module.const_defined?(:Language)
           validate_language(backend_module::Language, results)
         else
-          results[:errors] << "Missing Language class"
+          results[:errors] << 'Missing Language class'
           results[:valid] = false
         end
 
@@ -152,7 +165,7 @@ module TreeHaver
         if backend_module.const_defined?(:Parser)
           validate_parser(backend_module::Parser, results)
         else
-          results[:errors] << "Missing Parser class"
+          results[:errors] << 'Missing Parser class'
           results[:valid] = false
         end
 
@@ -160,20 +173,18 @@ module TreeHaver
         if backend_module.const_defined?(:Tree)
           validate_tree(backend_module::Tree, results)
         else
-          results[:warnings] << "No Tree class (backend returns raw trees)"
+          results[:warnings] << 'No Tree class (backend returns raw trees)'
         end
 
         # Check Node class if present (wrapper backends)
         if backend_module.const_defined?(:Node)
           validate_node_class(backend_module::Node, results, strict: strict)
         else
-          results[:warnings] << "No Node class (backend returns raw nodes, TreeHaver::Node will wrap)"
+          results[:warnings] << 'No Node class (backend returns raw nodes, TreeHaver::Node will wrap)'
         end
 
         # Fail on warnings in strict mode
-        if strict && results[:warnings].any?
-          results[:valid] = false
-        end
+        results[:valid] = false if strict && results[:warnings].any?
 
         results
       end
@@ -188,9 +199,9 @@ module TreeHaver
         results = validate(backend_module, strict: strict)
         unless results[:valid]
           raise TreeHaver::Error,
-            "Backend #{backend_module.name} API validation failed:\n  " \
-              "Errors: #{results[:errors].join(", ")}\n  " \
-              "Warnings: #{results[:warnings].join(", ")}"
+                "Backend #{backend_module.name} API validation failed:\n  " \
+                  "Errors: #{results[:errors].join(', ')}\n  " \
+                  "Warnings: #{results[:warnings].join(', ')}"
         end
         results
       end
@@ -205,7 +216,7 @@ module TreeHaver
           errors: [],
           warnings: [],
           supported_methods: [],
-          unsupported_methods: [],
+          unsupported_methods: []
         }
 
         # Check required methods
@@ -235,13 +246,51 @@ module TreeHaver
 
       def validate_module_methods(mod, results)
         unless mod.singleton_class.method_defined?(:available?)
-          results[:errors] << "Missing module method: available?"
+          results[:errors] << 'Missing module method: available?'
           results[:valid] = false
         end
 
         unless mod.singleton_class.method_defined?(:capabilities)
-          results[:warnings] << "Missing module method: capabilities"
+          results[:warnings] << 'Missing module method: capabilities'
+          return
         end
+
+        validate_capabilities_hash(mod.capabilities, results)
+      end
+
+      def validate_capabilities_hash(capabilities, results)
+        return if capabilities.nil? || capabilities.empty?
+
+        unless capabilities.is_a?(Hash)
+          results[:errors] << 'Backend capabilities must return a Hash'
+          results[:valid] = false
+          return
+        end
+
+        comment_support = capabilities[:comment_support]
+        if comment_support.nil?
+          results[:warnings] << 'Capabilities missing :comment_support'
+          return
+        end
+
+        unless COMMENT_SUPPORT_LEVELS.include?(comment_support)
+          results[:errors] << "Invalid :comment_support #{comment_support.inspect}; expected one of #{COMMENT_SUPPORT_LEVELS.inspect}"
+          results[:valid] = false
+          return
+        end
+
+        results[:capabilities][:comment_support] = comment_support
+
+        return unless capabilities.key?(:comment_attachment_hints)
+
+        attachment_hints = capabilities[:comment_attachment_hints]
+        unless [true, false].include?(attachment_hints)
+          results[:errors] << "Invalid :comment_attachment_hints #{attachment_hints.inspect}; expected true or false"
+          results[:valid] = false
+          return
+        end
+
+        results[:capabilities][:comment_attachment_hints] = attachment_hints
       end
 
       def validate_language(klass, results)
@@ -249,19 +298,17 @@ module TreeHaver
         # Language-specific backends should implement it to ignore path/symbol
         # and return their single language (for API consistency)
         unless klass.singleton_class.method_defined?(:from_library)
-          results[:errors] << "Language missing required class method: 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.singleton_class.method_defined?(m) }
-        if optional_methods.any?
-          results[:capabilities][:language_shortcuts] = optional_methods
-        end
+        results[:capabilities][:language_shortcuts] = optional_methods if optional_methods.any?
 
         results[:capabilities][:language] = {
           class_methods: LANGUAGE_CLASS_METHODS.select { |m| klass.singleton_class.method_defined?(m) } +
-            optional_methods,
+                         optional_methods
         }
       end
 
@@ -282,9 +329,7 @@ module TreeHaver
         end
 
         PARSER_OPTIONAL_METHODS.each do |method|
-          unless klass.method_defined?(method)
-            results[:warnings] << "Parser missing optional method: #{method}"
-          end
+          results[:warnings] << "Parser missing optional method: #{method}" unless klass.method_defined?(method)
         end
       end
 
@@ -297,9 +342,7 @@ module TreeHaver
         end
 
         TREE_OPTIONAL_METHODS.each do |method|
-          unless klass.method_defined?(method)
-            results[:warnings] << "Tree missing optional method: #{method}"
-          end
+          results[:warnings] << "Tree missing optional method: #{method}" unless klass.method_defined?(method)
         end
       end
 
@@ -312,20 +355,20 @@ module TreeHaver
         end
 
         NODE_OPTIONAL_METHODS.each do |method|
-          unless has_method_or_alias?(klass, method)
-            msg = "Node missing optional method: #{method}"
-            if strict
-              results[:errors] << msg
-              results[:valid] = false
-            else
-              results[:warnings] << msg
-            end
+          next if has_method_or_alias?(klass, method)
+
+          msg = "Node missing optional method: #{method}"
+          if strict
+            results[:errors] << msg
+            results[:valid] = false
+          else
+            results[:warnings] << msg
           end
         end
 
         results[:capabilities][:node] = {
           required: NODE_INSTANCE_METHODS.select { |m| has_method_or_alias?(klass, m) },
-          optional: NODE_OPTIONAL_METHODS.select { |m| has_method_or_alias?(klass, m) },
+          optional: NODE_OPTIONAL_METHODS.select { |m| has_method_or_alias?(klass, m) }
         }
       end
 

data/lib/tree_haver/backend_context.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+module TreeHaver
+  BACKEND_CONTEXT_KEY = :structured_merge_tree_haver_backend
+
+  module_function
+
+  def current_backend_id
+    Thread.current[BACKEND_CONTEXT_KEY]
+  end
+
+  def with_backend(backend_id)
+    validate_backend_id!(backend_id)
+
+    previous_backend = Thread.current[BACKEND_CONTEXT_KEY]
+    Thread.current[BACKEND_CONTEXT_KEY] = backend_id.to_s
+    yield
+  ensure
+    Thread.current[BACKEND_CONTEXT_KEY] = previous_backend
+  end
+
+  def validate_backend_id!(backend_id)
+    return if BackendRegistry.fetch(backend_id.to_s)
+
+    raise ArgumentError, "Unknown tree_haver backend #{backend_id}."
+  end
+  private_class_method :validate_backend_id!
+end