lutaml-model 0.8.0 → 0.8.2

data/lib/lutaml/model/adapter_resolver.rb

@@ -0,0 +1,410 @@
+# frozen_string_literal: true
+
+module Lutaml
+  module Model
+    # Single authority for adapter resolution: (format, type_name) → adapter class.
+    #
+    # Consolidates adapter metadata, loading, validation, and auto-detection
+    # that was previously spread across Config, Configuration, and FormatRegistry.
+    #
+    # Resolution chain (in order):
+    #   1. Thread-local AdapterScope override
+    #   2. Explicitly configured type (from Config.xml_adapter_type =)
+    #   3. Lazy auto-detected type (cached after first probe)
+    #   4. Default from format metadata
+    #   5. Raise FormatAdapterNotSpecifiedError
+    #
+    # @example Configure an adapter
+    #   AdapterResolver.set_adapter_type(:xml, :nokogiri)
+    #
+    # @example Resolve an adapter
+    #   adapter_class = AdapterResolver.adapter_for(:xml)
+    #
+    # @example Per-operation override
+    #   adapter_class = AdapterResolver.resolved_adapter_class(:xml, :ox)
+    #
+    class AdapterResolver
+      class << self
+        # --- Resolution ---
+
+        # Resolve the adapter class for a format using the full resolution chain.
+        #
+        # @param format [Symbol] the format name (:xml, :json, etc.)
+        # @return [Class, nil] the adapter class or nil
+        def adapter_for(format)
+          # 1. Thread-local scope override
+          scope_override = AdapterScope.override_for(format)
+          if scope_override
+            return resolved_adapter_class(format, scope_override)
+          end
+
+          # 2. Explicitly configured type
+          configured = configured_type(format)
+          if configured
+            adapter = resolved[format]
+            return adapter if adapter
+          end
+
+          # 3. Lazy auto-detection (cached)
+          detected = detected_types[format]
+          if detected.nil? && !detected_formats.key?(format)
+            result = detect_adapter_for(format)
+            if result
+              detected_formats[format] = true
+              detected_types[format] = result
+              return load_and_cache(format, result)
+            end
+            detected_formats[format] = true
+          elsif detected
+            return load_and_cache(format, detected)
+          end
+
+          # 4. Default from metadata
+          default = metadata.dig(format, :default)
+          if default
+            return load_and_cache(format, default)
+          end
+
+          # 5. No adapter available
+          nil
+        end
+
+        # Set the adapter type for a format (validates and loads).
+        #
+        # @param format [Symbol] the format name
+        # @param type_name [Symbol] the adapter type name (:nokogiri, :ox, etc.)
+        # @return [Class] the loaded adapter class
+        def set_adapter_type(format, type_name)
+          type_name = type_name.to_sym
+          validate!(format, type_name)
+          configured_types[format] = type_name
+          resolved[format] = load_adapter(format, type_name)
+        end
+
+        # Store a pre-resolved adapter class for a format.
+        #
+        # Used by FormatRegistry.register for key-value formats that have
+        # a fixed adapter class (not selectable by type name).
+        #
+        # @param format [Symbol] the format name
+        # @param adapter_class [Class] the adapter class
+        # @return [void]
+        def set_adapter_class(format, adapter_class)
+          resolved[format] = adapter_class
+          configured_types[format] = :__fixed__
+        end
+
+        # Load and resolve an adapter class by type name.
+        # Used for per-operation overrides (from_xml adapter: :ox).
+        #
+        # @param format [Symbol] the format name
+        # @param type_name [Symbol, String] the adapter type name
+        # @return [Class] the adapter class
+        def resolved_adapter_class(format, type_name)
+          type_name = type_name.to_sym
+          validate!(format, type_name)
+          load_adapter(format, type_name)
+        end
+
+        # --- Metadata Registration ---
+
+        # Register adapter metadata for a format (available adapters, default).
+        #
+        # Called by FormatRegistry.register for formats with selectable adapters.
+        #
+        # @param format [Symbol] the format name
+        # @param options [Hash] { available: [...], default: :name }
+        # @return [void]
+        def register_metadata(format, options)
+          metadata[format] = options
+        end
+
+        # Register a fixed adapter class for a format with a single adapter.
+        #
+        # Used for key-value formats (json, yaml, hash, etc.) that have
+        # exactly one adapter. Creates metadata so validation works.
+        #
+        # @param format [Symbol] the format name
+        # @param adapter_class [Class] the adapter class
+        # @param adapter_name [Symbol] the adapter type name (e.g., :standard)
+        # @return [void]
+        def register_fixed(format, adapter_class, adapter_name)
+          metadata[format] = {
+            available: [adapter_name],
+            default: adapter_name,
+          }
+          resolved[format] = adapter_class
+          configured_types[format] = adapter_name
+        end
+
+        # Get the configured type name for a format.
+        #
+        # @param format [Symbol] the format name
+        # @return [Symbol, nil] the type name or nil
+        def configured_type(format)
+          configured_types[format]
+        end
+
+        # --- Reset ---
+
+        # Clear all state (for testing reset).
+        #
+        # @return [void]
+        def reset!
+          @metadata = nil
+          @configured_types = nil
+          @resolved = nil
+          @detected_types = nil
+          @detected_formats = nil
+        end
+
+        private
+
+        # Internal state accessors
+
+        def metadata
+          @metadata ||= {}
+        end
+
+        def configured_types
+          @configured_types ||= {}
+        end
+
+        def resolved
+          @resolved ||= {}
+        end
+
+        def detected_types
+          @detected_types ||= {}
+        end
+
+        def detected_formats
+          @detected_formats ||= {}
+        end
+
+        # Load adapter and cache the result.
+        #
+        # @param format [Symbol] the format name
+        # @param type_name [Symbol] the adapter type name
+        # @return [Class] the adapter class
+        def load_and_cache(format, type_name)
+          resolved[format] ||= load_adapter(format, type_name)
+        end
+
+        # Load an adapter file and resolve to its class.
+        #
+        # @param format [Symbol] the format name
+        # @param type_name [Symbol] the adapter type name
+        # @return [Class] the adapter class
+        def load_adapter(format, type_name)
+          adapter = format.to_s
+          type = normalize_type_name(type_name, format)
+
+          load_adapter_file(adapter, type)
+          load_moxml_adapter(type_name, format)
+
+          class_for(adapter, type)
+        end
+
+        # Normalize type name to file/class name pattern.
+        #
+        # @param type_name [Symbol] raw type name
+        # @param format [Symbol] format name
+        # @return [String] normalized type name (e.g., "nokogiri_adapter")
+        def normalize_type_name(type_name, format)
+          if type_name.to_s.start_with?("multi_json")
+            "multi_json_adapter"
+          else
+            "#{type_name.to_s.gsub("_#{format}", '')}_adapter"
+          end
+        end
+
+        # Load the adapter file.
+        #
+        # @param adapter [String] format name as string
+        # @param type [String] normalized type name
+        def load_adapter_file(adapter, type)
+          loader = FormatRegistry.adapter_loader_for(adapter.to_sym)
+          if loader.respond_to?(:load_adapter_file)
+            loader.load_adapter_file(adapter, type)
+            return
+          end
+
+          # Default key-value adapter loading
+          adapter_path = if RuntimeCompatibility.opal?
+                           "lutaml/key_value/adapter/#{adapter}/#{type}"
+                         else
+                           File.join(File.dirname(__FILE__), "../key_value/adapter",
+                                     adapter, type)
+                         end
+          require adapter_path
+        rescue LoadError
+          raise UnknownAdapterTypeError.new(adapter, type), cause: nil
+        end
+
+        # Load the Moxml adapter for XML and similar formats.
+        #
+        # @param type_name [Symbol] raw type name
+        # @param format [Symbol] format name
+        def load_moxml_adapter(type_name, format)
+          loader = FormatRegistry.adapter_loader_for(format)
+          if loader.respond_to?(:load_moxml_adapter)
+            loader.load_moxml_adapter(type_name,
+                                      format)
+          end
+        end
+
+        # Resolve the adapter class from the type name.
+        #
+        # @param adapter [String] format name as string
+        # @param type [String] normalized type name
+        # @return [Class] the adapter class
+        def class_for(adapter, type)
+          loader = FormatRegistry.adapter_loader_for(adapter.to_sym)
+          if loader.respond_to?(:class_for)
+            return loader.class_for(adapter, type)
+          end
+
+          # Default key-value adapter class resolution
+          KeyValue::Adapter.const_get(to_class_name(adapter))
+            .const_get(to_class_name(type))
+        end
+
+        # Validate that the adapter type is available for the format.
+        #
+        # @param format [Symbol] the format name
+        # @param type_name [Symbol] the adapter type name
+        # @raise [ArgumentError] if format or adapter is unknown
+        def validate!(format, type_name)
+          adapter_config = metadata[format]
+
+          unless adapter_config
+            all_formats = metadata.keys
+            available_formats = all_formats.map { |f| "`:#{f}`" }.join(", ")
+            raise ArgumentError,
+                  "Unknown format: `:#{format}`. Available formats: #{available_formats}."
+          end
+
+          if format == :toml && type_name == :tomlib && RuntimeCompatibility.windows?
+            raise ArgumentError,
+                  "The `:tomlib` adapter is not supported on Windows due to " \
+                  "segmentation fault issues. Please use `:toml_rb` instead."
+          end
+
+          available = adapter_config[:available]
+          return unless available
+          return if available.include?(type_name)
+
+          available_list = available.map { |a| "`:#{a}`" }.join(", ")
+          closest = find_suggestion(type_name.to_s, available.map(&:to_s))
+
+          msg = "Unknown adapter: `:#{type_name}` for `:#{format}` format. " \
+                "Available adapters: #{available_list}."
+          msg += " Did you mean `:#{closest}`?" if closest
+
+          raise ArgumentError, msg
+        end
+
+        # Find closest string match for suggestions.
+        #
+        # @param input [String]
+        # @param candidates [Array<String>]
+        # @return [String, nil]
+        def find_suggestion(input, candidates)
+          return nil if input.nil? || input.empty?
+
+          candidates.min_by do |candidate|
+            levenshtein_distance(input.downcase, candidate.downcase)
+          end.tap do |closest|
+            max_dist = ([input.length, closest.length].max / 2) + 1
+            return nil if closest && levenshtein_distance(input.downcase,
+                                                          closest.downcase) > max_dist
+          end
+        end
+
+        # Calculate Levenshtein distance.
+        #
+        # @param lhs [String]
+        # @param rhs [String]
+        # @return [Integer]
+        def levenshtein_distance(lhs, rhs)
+          return lhs.length if rhs.empty?
+          return rhs.length if lhs.empty?
+
+          matrix = Array.new(lhs.length + 1) do |i|
+            Array.new(rhs.length + 1) do |j|
+              if i.zero?
+                j
+              else
+                (j.zero? ? i : 0)
+              end
+            end
+          end
+
+          (1..lhs.length).each do |i|
+            (1..rhs.length).each do |j|
+              cost = lhs[i - 1] == rhs[j - 1] ? 0 : 1
+              matrix[i][j] = [
+                matrix[i - 1][j] + 1,
+                matrix[i][j - 1] + 1,
+                matrix[i - 1][j - 1] + cost,
+              ].min
+            end
+          end
+
+          matrix[lhs.length][rhs.length]
+        end
+
+        # Auto-detect available adapter for a format.
+        #
+        # @param format [Symbol] the format name
+        # @return [Symbol, nil] the detected adapter type name
+        def detect_adapter_for(format)
+          case format
+          when :xml
+            detect_xml_adapter
+          when :toml
+            detect_toml_adapter
+          else
+            metadata.dig(format, :default)
+          end
+        end
+
+        # Detect available XML adapter.
+        #
+        # @return [Symbol, nil] :nokogiri, :ox, :oga, :rexml, or nil
+        def detect_xml_adapter
+          return :oga if RuntimeCompatibility.opal?
+          return :nokogiri if Utils.safe_load("nokogiri", :Nokogiri)
+          return :ox if Utils.safe_load("ox", :Ox)
+          return :oga if Utils.safe_load("oga", :Oga)
+          return :rexml if Utils.safe_load("rexml", :REXML)
+
+          nil
+        end
+
+        # Detect available TOML adapter.
+        #
+        # @return [Symbol, nil] :tomlib, :toml_rb, or nil
+        def detect_toml_adapter
+          return nil if RuntimeCompatibility.opal?
+
+          if RuntimeCompatibility.windows?
+            return :toml_rb if Utils.safe_load("toml-rb", :TomlRb)
+
+            return nil
+          end
+
+          return :tomlib if Utils.safe_load("tomlib", :Tomlib)
+          return :toml_rb if Utils.safe_load("toml-rb", :TomlRb)
+
+          nil
+        end
+
+        def to_class_name(str)
+          str.to_s.split("_").map(&:capitalize).join
+        end
+      end
+    end
+  end
+end

data/lib/lutaml/model/adapter_scope.rb

@@ -0,0 +1,64 @@
+# frozen_string_literal: true
+
+module Lutaml
+  module Model
+    # Thread-local scoped adapter override stack.
+    #
+    # Provides block-scoped adapter overrides for testing and library stacking.
+    # Each thread has its own stack — no mutex needed.
+    #
+    # @example Testing with a specific adapter
+    #   Lutaml::Model::Config.with_adapter(xml: :ox) do
+    #     MyClass.from_xml(xml)  # Uses Ox
+    #   end
+    #   # Outside the block, reverts to configured default
+    #
+    # @example Library stacking
+    #   # Library A guarantees Ox internally
+    #   def self.parse(data)
+    #     Config.with_adapter(xml: :nokogiri) { MyModel.from_xml(data) }
+    #   end
+    #
+    class AdapterScope
+      STACK_KEY = :__lutaml_adapter_scope_stack
+      EMPTY = {}.freeze
+
+      # Push adapter overrides and yield. Restores previous scope on exit.
+      #
+      # @param overrides [Hash{Symbol => Symbol}] format => adapter type name
+      #   e.g., { xml: :ox, json: :oj }
+      # @yield block within which overrides are active
+      # @return [Object] the block's return value
+      def self.with(overrides)
+        stack = Thread.current[STACK_KEY] ||= []
+        stack.push(overrides)
+        yield
+      ensure
+        stack.pop
+        Thread.current[STACK_KEY] = nil if stack.empty?
+      end
+
+      # Return the current scope's overrides hash.
+      #
+      # @return [Hash{Symbol => Symbol}] current overrides or empty hash
+      def self.current
+        Thread.current[STACK_KEY]&.last || EMPTY
+      end
+
+      # Return the override for a specific format from the current scope.
+      #
+      # @param format [Symbol] the format name (:xml, :json, etc.)
+      # @return [Symbol, nil] the adapter type name or nil
+      def self.override_for(format)
+        current[format]
+      end
+
+      # Clear all scope state (for testing reset).
+      #
+      # @return [void]
+      def self.reset!
+        Thread.current[STACK_KEY] = nil
+      end
+    end
+  end
+end

data/lib/lutaml/model/config.rb

@@ -2,17 +2,13 @@
 
 module Lutaml
   module Model
-    # Configuration module - single entry point for all configuration
+    # Configuration module - single entry point for all configuration.
+    #
+    # Delegates adapter resolution to AdapterResolver and scoped overrides
+    # to AdapterScope. Keeps the configure block API for backward compatibility.
     module Config
       extend self
 
-      # Bootstrap format lists for key-value adapter method definition.
-      # At runtime, prefer FormatRegistry.formats for dynamic format discovery.
-      # NOTE: XML is NOT listed here — it registers dynamically via FormatRegistry
-      # when `require "lutaml/xml"` is called.
-      AVAILABLE_FORMATS = %i[json jsonl yaml toml hash].freeze
-      KEY_VALUE_FORMATS = AVAILABLE_FORMATS
-
       # Dynamic format discovery from FormatRegistry
       def available_formats
         FormatRegistry.formats
@@ -28,9 +24,26 @@ module Lutaml
         @instance ||= Configuration.new
       end
 
-      # Adapter storage - used by FormatRegistry for dynamic format registration
-      def adapters
-        @adapters ||= {}
+      # Block-scoped adapter override (thread-safe).
+      #
+      # Pushes adapter overrides onto a thread-local stack for the duration
+      # of the block. Restores previous state on exit.
+      #
+      # @param overrides [Hash{Symbol => Symbol}] format => adapter type name
+      # @yield block within which overrides are active
+      # @return [Object] the block's return value
+      #
+      # @example Testing with a specific adapter
+      #   Config.with_adapter(xml: :ox) do
+      #     MyClass.from_xml(xml)  # Uses Ox
+      #   end
+      #
+      # @example Library stacking
+      #   Config.with_adapter(xml: :nokogiri, toml: :tomlib) do
+      #     MyModel.from_xml(data)
+      #   end
+      def with_adapter(**overrides, &)
+        AdapterScope.with(overrides, &)
       end
 
       # Delegate configure to Configuration
@@ -39,24 +52,43 @@ module Lutaml
         self
       end
 
-      # Set adapter for a format (used by FormatRegistry)
-      def set_adapter_for(format, adapter)
-        adapters[format] = adapter
+      # Get adapter class for a format using the full resolution chain.
+      #
+      # @param format [Symbol] the format name
+      # @return [Class, nil] the adapter class or nil
+      def adapter_for(format)
+        AdapterResolver.adapter_for(format)
       end
 
-      # Get adapter for a format
-      def adapter_for(format)
-        adapters[format] || instance.get_adapter(format)
+      # Store a pre-resolved adapter class for a format.
+      #
+      # @param format [Symbol] the format name
+      # @param adapter [Class] the adapter class
+      def set_adapter_for(format, adapter)
+        AdapterResolver.set_adapter_class(format, adapter)
       end
 
-      # Delegate adapter setters to Configuration
+      # Dynamic adapter type accessors for boot-time formats.
+      # Additional formats (xml, etc.) get their accessors registered
+      # via FormatRegistry.register which calls define_adapter_type_methods.
+      AVAILABLE_FORMATS = %i[json jsonl yaml toml hash yamls].freeze
+      KEY_VALUE_FORMATS = AVAILABLE_FORMATS
+
       AVAILABLE_FORMATS.each do |format|
+        define_method(:"#{format}_adapter") do
+          AdapterResolver.adapter_for(format)
+        end
+
+        define_method(:"#{format}_adapter=") do |adapter_klass|
+          AdapterResolver.set_adapter_class(format, adapter_klass)
+        end
+
         define_method(:"#{format}_adapter_type=") do |type_name|
-          instance.set_adapter(format, type_name)
+          AdapterResolver.set_adapter_type(format, type_name)
         end
 
         define_method(:"#{format}_adapter_type") do
-          instance.adapter_for(format)
+          AdapterResolver.configured_type(format)
         end
       end
 
@@ -84,7 +116,38 @@ module Lutaml
         instance.default_context_id = value
       end
 
-      # Utility method
+      # Define dynamic adapter type accessor methods for a format.
+      # Called by FormatRegistry.register when a new format is registered.
+      #
+      # Defines two pairs of methods:
+      #   - #{format}_adapter / #{format}_adapter= — adapter class getter/setter
+      #   - #{format}_adapter_type / #{format}_adapter_type= — type name getter/setter
+      #
+      # @param format [Symbol] the format name
+      def define_adapter_type_methods(format)
+        return if respond_to?(:"#{format}_adapter_type=")
+
+        # Adapter class getter (returns Class)
+        define_method(:"#{format}_adapter") do
+          AdapterResolver.adapter_for(format)
+        end
+
+        # Adapter class setter (accepts Class)
+        define_method(:"#{format}_adapter=") do |adapter_klass|
+          AdapterResolver.set_adapter_class(format, adapter_klass)
+        end
+
+        # Adapter type name setter (accepts Symbol like :nokogiri)
+        define_method(:"#{format}_adapter_type=") do |type_name|
+          AdapterResolver.set_adapter_type(format, type_name)
+        end
+
+        # Adapter type name getter (returns Symbol or nil)
+        define_method(:"#{format}_adapter_type") do
+          AdapterResolver.configured_type(format)
+        end
+      end
+
       def to_class_name(str)
         str.to_s.split("_").map(&:capitalize).join
       end