lutaml-model 0.7.7 → 0.8.1

data/lib/lutaml/model/serialize/initialization.rb

@@ -0,0 +1,308 @@
+# frozen_string_literal: true
+
+module Lutaml
+  module Model
+    module Serialize
+      # Handles initialization and namespace methods for Serialize::ClassMethods
+      #
+      # Extracted from serialize.rb to improve code organization.
+      # Provides methods for class initialization and namespace handling.
+      module Initialization
+        # Class-level namespace getter/setter.
+        #
+        # No-op by default. When XML format is loaded, this is overridden
+        # via prepend to provide XML namespace handling.
+        #
+        # @param _ns_class [Class, nil] Namespace class (handled by format modules)
+        # @return [Class, nil] the namespace class
+        def namespace(_ns_class = nil)
+          @namespace_class
+        end
+
+        # Get the namespace URI for this Model
+        #
+        # @return [String, nil] the namespace URI
+        def namespace_uri
+          nil
+        end
+
+        # Get the default namespace prefix for this Model
+        #
+        # @return [String, nil] the namespace prefix
+        def namespace_prefix
+          nil
+        end
+
+        # Set the register context for this Model class.
+        #
+        # This is called by Register#register_model to ensure the class
+        # knows its register context for proper instance initialization.
+        #
+        # @param register_id [Symbol] The register ID
+        # @return [void]
+        def set_register_context(register_id)
+          return if instance_variable_defined?(:@register)
+
+          @register = register_id
+        end
+
+        # Get or set the default register for this Model class.
+        #
+        # Override in subclasses to specify a preferred default register context.
+        # This allows versioned schemas (e.g., MML v2, v3) to use their own
+        # register by default when instances are created without explicit register.
+        #
+        # @return [Symbol, nil] The default register ID or nil to use Config.default_register
+        #
+        # @example
+        #   module Mml
+        #     class V2Base < Lutaml::Model::Serializable
+        #       def self.lutaml_default_register
+        #         :mml_v2
+        #       end
+        #     end
+        #   end
+        #
+        #   class Mml::V2::Math < V2Base
+        #     # Mml::V2::Math.new uses :mml_v2 by default
+        #   end
+        def lutaml_default_register
+          nil
+        end
+
+        # Handle inheritance by copying parent's configuration
+        #
+        # @param subclass [Class] The inheriting class
+        def inherited(subclass)
+          super
+          subclass.initialize_attrs(self)
+        end
+
+        # Handle inclusion by extending with ClassMethods
+        #
+        # @param base [Class] The including class
+        def included(base)
+          base.extend(ClassMethods)
+          base.initialize_attrs(self)
+        end
+
+        # Initialize class attributes from a source class
+        #
+        # @param source_class [Class] The source class to copy from
+        def initialize_attrs(source_class)
+          @mappings = Utils.deep_dup(source_class.instance_variable_get(:@mappings)) || {}
+          @attributes = Utils.deep_dup(source_class.instance_variable_get(:@attributes)) || {}
+          @choice_attributes = deep_duplicate_choice_attributes(source_class)
+          @register_records = Utils.deep_dup(
+            source_class.instance_variable_get(:@register_records),
+          ) || ::Hash.new do |hash, key|
+                 hash[key] = { attributes: {}, choice_attributes: [] }
+               end
+          instance_variable_set(:@model, self)
+        end
+
+        # Deep duplicate choice attributes from a source class
+        #
+        # @param source_class [Class] The source class
+        # @return [Array] The duplicated choice attributes
+        def deep_duplicate_choice_attributes(source_class, register = nil)
+          choice_attrs = Array(source_class.instance_variable_get(:@choice_attributes))
+          choice_attrs.map do |choice_attr|
+            choice_attr.deep_duplicate(self, register)
+          end
+        end
+
+        # Get all attributes for this model
+        #
+        # Merges class-level attributes with register-specific attributes.
+        #
+        # @param register [Symbol, nil] The register context
+        # @return [Hash] The attributes hash
+        def attributes(register = nil)
+          ensure_imports!(register) if finalized?
+          if @register_records&.any?
+            @attributes.merge(@register_records[extract_register_id(register)][:attributes])
+          else
+            @attributes
+          end
+        end
+
+        # Get all choice attributes for this model
+        #
+        # Merges class-level choice attributes with register-specific choice attributes.
+        #
+        # @param register [Symbol, nil] The register context
+        # @return [Array] The choice attributes array
+        def choice_attributes(register = nil)
+          ensure_imports!(register) if finalized?
+          if @register_records&.any?
+            @choice_attributes + @register_records[extract_register_id(register)][:choice_attributes]
+          else
+            @choice_attributes
+          end
+        end
+
+        # Ensure all imports are resolved
+        #
+        # @param register [Symbol, nil] The register context
+        def ensure_imports!(register = nil)
+          ensure_model_imports!(register)
+          ensure_choice_imports!(register)
+          ensure_restrict_attributes!(register)
+          # Hook for format-specific mapping import resolution.
+          # XML overrides this to call mappings[:xml]&.ensure_mappings_imported!(register)
+          ensure_format_mapping_imports!(register)
+        end
+
+        # Hook for format-specific mapping import resolution.
+        # Override in format modules (e.g., XML prepends to resolve XML mapping imports).
+        #
+        # @param _register [Symbol, nil] The register context
+        def ensure_format_mapping_imports!(_register = nil)
+          # No-op by default; XML overrides via prepend
+        end
+
+        # Clear all cached data for this model class
+        #
+        # Centralized caching (Phase 11.5):
+        # - Type caches: GlobalContext.resolver
+        # - Mapping caches: TransformationRegistry
+        # - Transformation caches: TransformationRegistry
+        #
+        # @param register_id [Symbol, nil] If provided, only clear cache for this specific context
+        def clear_cache(register_id = nil)
+          # Clear centralized type cache in GlobalContext.resolver
+          if defined?(Lutaml::Model::GlobalContext)
+            GlobalContext.resolver.clear_cache(register_id)
+          end
+
+          # Clear centralized mapping and transformation caches
+          # (Single Source of Truth - no longer uses instance variables)
+          TransformationRegistry.instance.clear
+
+          # Clear import resolution guard flags so imports can be re-resolved
+          instance_variables.each do |ivar|
+            remove_instance_variable(ivar) if ivar.to_s.start_with?("@_imports_resolved_")
+          end
+        end
+
+        # Get or set the model class
+        #
+        # @param klass [Class, nil] The model class to set
+        # @return [Class] The model class
+        def model(klass = nil)
+          if klass
+            @model = klass
+            add_custom_handling_methods_to_model(klass)
+          else
+            @model
+          end
+        end
+
+        # Add custom handling methods to a model class
+        #
+        # @param klass [Class] The model class
+        def add_custom_handling_methods_to_model(klass)
+          Utils.add_method_if_not_defined(klass,
+                                          :using_default_for) do |attribute_name|
+            @using_default ||= {}
+            @using_default[attribute_name] = true
+          end
+
+          Utils.add_method_if_not_defined(klass,
+                                          :value_set_for) do |attribute_name|
+            @using_default ||= {}
+            @using_default[attribute_name] = false
+          end
+
+          Utils.add_method_if_not_defined(klass,
+                                          :using_default?) do |attribute_name|
+            @using_default ||= {}
+            !!@using_default[attribute_name]
+          end
+
+          # Hook for format-specific model methods (e.g., XML adds ordered, mixed, element_order)
+          add_format_specific_model_methods(klass)
+        end
+
+        # Hook for format-specific model methods.
+        # XML overrides via FormatConversion prepend to add XML accessors.
+        #
+        # @param _klass [Class] The model class
+        def add_format_specific_model_methods(_klass)
+          # No-op by default
+        end
+
+        # Cast a value (pass-through implementation)
+        #
+        # @param value [Object] The value to cast
+        # @return [Object] The same value
+        def cast(value)
+          value
+        end
+
+        # Define a choice constraint
+        #
+        # @param min [Integer] Minimum number of choices
+        # @param max [Integer] Maximum number of choices
+        # @param block [Proc] The choice definition block
+        def choice(min: 1, max: 1, format: nil, &block)
+          @choice_attributes << Choice.new(self, min, max,
+                                           format: format).tap do |c|
+            c.instance_eval(&block)
+          end
+        end
+
+        # Get the register record for a specific register ID
+        #
+        # @param register_id [Symbol, nil] The register context
+        # @return [Hash, nil] The register record hash or nil
+        def register_record(register_id = nil)
+          register_records[extract_register_id(register_id)]
+        end
+
+        # Convert register parameter to symbol
+        #
+        # @param name [Symbol, String, nil] The register name
+        # @return [Symbol, nil] The register name as a symbol
+        def register(name)
+          name&.to_sym
+        end
+
+        # Allocate an instance for deserialization without calling initialize.
+        #
+        # Skips the expensive initialize_attributes pass (which iterates all
+        # attributes to set defaults). The XML mapping pipeline sets values
+        # directly via rule.deserialize instead. Uses Hash.new(true) as the
+        # default for @using_default so that using_default? returns true for
+        # all attributes until value_set_for is called.
+        #
+        # @param register [Symbol, nil] The register context
+        # @return [Object] The allocated instance
+        def allocate_for_deserialization(register = nil)
+          instance = allocate
+          register_id = extract_register_id(register)
+          instance.init_deserialization_state(register_id)
+          instance.send(:define_singleton_attribute_methods)
+          instance.send(:register_in_reference_store)
+          instance
+        end
+
+        private
+
+        # Extract and normalize register ID with default fallback
+        #
+        # Resolution order:
+        # 1. Explicit register parameter
+        # 2. Class's lutaml_default_register (for versioned schemas)
+        # 3. Global Config.default_register
+        #
+        # @param register [Symbol, String, nil] The register identifier
+        # @return [Symbol] The normalized register ID
+        def extract_register_id(register)
+          register&.to_sym || lutaml_default_register || Lutaml::Model::Config.default_register
+        end
+      end
+    end
+  end
+end

data/lib/lutaml/model/serialize/model_import.rb

@@ -0,0 +1,357 @@
+# frozen_string_literal: true
+
+module Lutaml
+  module Model
+    module Serialize
+      # Handles model import/export methods for Serialize::ClassMethods
+      #
+      # Extracted from serialize.rb to improve code organization.
+      # Provides methods for importing attributes and mappings from other models.
+      module ModelImport
+        # Check if register has a root mapping (XML-specific)
+        #
+        # Returns false by default. When Lutaml::Xml is loaded,
+        # this is overridden to check XML mappings via prepend.
+        #
+        # @param register [Symbol, nil] The register to check
+        # @return [Boolean] True if the model has a root mapping
+        def root?(_register = nil)
+          false
+        end
+
+        # Raise error if importing a model with a root element
+        #
+        # @param model [Class] The model to check
+        # @param register [Symbol, nil] The register context
+        # @raise [ImportModelWithRootError] If model has a root mapping
+        def import_model_with_root_error(model, register = nil)
+          return unless model.root?(register)
+
+          raise Lutaml::Model::ImportModelWithRootError.new(model)
+        end
+
+        # Import attributes from another model
+        #
+        # Deferred path (model is a Symbol/String): stores model reference per-register
+        # and resolves lazily on first access via ensure_imports!.
+        #
+        # Immediate path (model is a Class): merges into class-level @attributes
+        # for default register, or register-specific storage for non-default registers.
+        #
+        # @param model [Class, Symbol, String] The model to import from
+        # @param register_id [Symbol, nil] The register context
+        def import_model_attributes(model, register_id = nil)
+          if model.is_a?(Symbol) || model.is_a?(String)
+            reg = extract_register_id(register_id)
+            importable_models[:import_model_attributes] << model.to_sym
+            @models_imported = (@models_imported || {}).merge(reg => false)
+            @choices_imported = (@choices_imported || {}).merge(reg => false)
+            setup_trace_point
+            return
+          end
+
+          reg = extract_register_id(register_id)
+          if reg != :default
+            register_only_import_model_attributes(model, register_id)
+            return
+          end
+
+          # Default register: merge into class-level storage
+          model.attributes.each_value { |attr| define_attribute_methods(attr) }
+          @attributes.merge!(Utils.deep_dup(model.attributes))
+          @choice_attributes.concat(deep_duplicate_choice_attributes(model))
+          # Ensure @models_imported is a hash; migrate from legacy nil/false state
+          @models_imported ||= {}
+          @models_imported[reg] = true
+        end
+
+        # Import mappings from another model
+        #
+        # Delegates to format-specific import_model_mappings which stores in
+        # register-specific storage when register_id is non-default.
+        #
+        # @param model [Class] The model to import from
+        # @param register_id [Symbol, nil] The register context
+        def import_model_mappings(model, register_id = nil)
+          Lutaml::Model::FormatRegistry.formats.each do |format|
+            next unless model.mappings.key?(format)
+
+            klass = ::Lutaml::Model::Config.mappings_class_for(format)
+            @mappings[format] ||= klass.new
+            mapping = @mappings[format]
+            if mapping.respond_to?(:import_model_mappings)
+              mapping.import_model_mappings(model,
+                                            register_id)
+            end
+          end
+        end
+
+        # Import both attributes and mappings from another model
+        #
+        # @param model [Class, Symbol, String] The model to import from
+        # @param register_id [Symbol, nil] The register context
+        def import_model(model, register_id = nil)
+          if model.is_a?(Symbol) || model.is_a?(String)
+            reg = extract_register_id(register_id)
+            importable_models[:import_model] << model.to_sym
+            @models_imported = (@models_imported || {}).merge(reg => false)
+            @choices_imported = (@choices_imported || {}).merge(reg => false)
+            setup_trace_point
+            return
+          end
+
+          import_model_attributes(model, register_id)
+          import_model_mappings(model, register_id)
+        end
+
+        # Import attributes from another model into register-specific storage only.
+        # Used for non-default registers where attributes should NOT be merged
+        # into the class-level @attributes.
+        #
+        # @param model [Class] The model to import from
+        # @param register_id [Symbol] The register context (must be non-default)
+        def register_only_import_model_attributes(model, register_id)
+          model.attributes(register_id).each_value do |attr|
+            define_attribute_methods(attr, register_id)
+          end
+
+          @register_records[register_id] ||= { attributes: {},
+                                               choice_attributes: [] }
+          @register_records[register_id][:attributes].merge!(Utils.deep_dup(model.attributes(register_id)))
+          @register_records[register_id][:choice_attributes].concat(
+            deep_duplicate_choice_attributes(model, register_id),
+          )
+        end
+        private :register_only_import_model_attributes
+
+        # Get hash of importable models (deferred imports)
+        #
+        # @return [MappingHash] Hash of method names to model arrays
+        def importable_models
+          @importable_models ||= MappingHash.new { |h, k| h[k] = [] }
+        end
+
+        # Get hash of restrict attributes (deferred restrictions)
+        #
+        # @return [MappingHash] Hash of attribute names to options
+        def restrict_attributes
+          @restrict_attributes ||= MappingHash.new
+        end
+
+        # Get hash of importable choices (deferred choice imports)
+        #
+        # @return [MappingHash] Nested hash of choices to imports
+        def importable_choices
+          @importable_choices ||= MappingHash.new do |h, k|
+            h[k] = MappingHash.new do |h1, k1|
+              h1[k1] = []
+            end
+          end
+        end
+
+        # Ensure all model imports are resolved for a specific register
+        #
+        # @param register_id [Symbol, nil] The register context
+        def ensure_model_imports!(register_id = nil)
+          register_id ||= Lutaml::Model::Config.default_register
+          @models_imported = {} if @models_imported.nil? || @models_imported == false
+          return if @models_imported[register_id] || Utils.present?(@register_records[register_id][:attributes])
+
+          @models_imported[register_id] = true
+          all_resolved = true
+
+          importable_models.each do |method, models|
+            models.uniq.each do |model|
+              model_class = begin
+                Lutaml::Model::GlobalContext.resolve_type(model, register_id)
+              rescue Lutaml::Model::UnknownTypeError
+                nil
+              end
+
+              if model_class.nil?
+                all_resolved = false
+                next
+              end
+
+              if model_class.is_a?(Class) && model_class.include?(Lutaml::Model::Serialize)
+                model_class.ensure_imports!(register_id)
+              end
+
+              import_model_with_root_error(model_class, register_id)
+              @model.public_send(method, model_class, register_id)
+            end
+          end
+
+          @models_imported[register_id] = all_resolved
+        end
+
+        # Ensure all choice imports are resolved for a specific register
+        #
+        # @param register_id [Symbol, nil] The register context
+        def ensure_choice_imports!(register_id = nil)
+          register_id ||= Lutaml::Model::Config.default_register
+          @choices_imported = {} if @choices_imported.nil? || @choices_imported == false
+          return if @choices_imported[register_id] || Utils.present?(@register_records[register_id][:choice_attributes])
+
+          @choices_imported[register_id] = true
+          all_resolved = true
+
+          importable_choices.each do |choice, choice_imports|
+            choice_imports.each do |method, models|
+              models.uniq.each do |model|
+                model_class = begin
+                  Lutaml::Model::GlobalContext.resolve_type(model, register_id)
+                rescue Lutaml::Model::UnknownTypeError
+                  nil
+                end
+
+                if model_class.nil?
+                  all_resolved = false
+                  next
+                end
+
+                if model_class.is_a?(Class) && model_class.include?(Lutaml::Model::Serialize)
+                  model_class.ensure_imports!(register_id)
+                end
+
+                choice.public_send(method, model_class, register_id)
+              end
+            end
+          end
+
+          @choices_imported[register_id] = true if all_resolved
+        end
+
+        # Ensure all restrict attributes are applied
+        #
+        # @param register_id [Symbol, nil] The register context
+        def ensure_restrict_attributes!(register_id = nil)
+          return if restrict_attributes.empty?
+
+          attrs = restrict_attributes.dup
+          restrict_attributes.clear
+          register_id ||= Lutaml::Model::Config.default_register
+          attrs.each do |name, options_list|
+            options_list[:register] = register_id
+            restrict(name, options_list)
+          end
+        end
+
+        # Setup trace point to detect class finalization
+        #
+        # Uses TracePoint to detect when a class definition is complete,
+        # allowing deferred import resolution.
+        def setup_trace_point
+          @trace ||= TracePoint.new(:end) do |_tp|
+            if include?(Lutaml::Model::Serialize)
+              @finalized = true
+              # NOTE: Do NOT resolve imports here - it's too early in the load process
+              # Classes being imported may not be defined yet, causing circular errors
+              # Imports will be resolved lazily on first use via ensure_imports!
+              # BUT they will be resolved RECURSIVELY, preventing redundant resolution
+              @trace.disable
+            end
+          end
+          @trace.enable unless @trace.enabled?
+        end
+
+        # Check if the class has been finalized
+        #
+        # @return [Boolean] True if the class definition is complete
+        def finalized?
+          @finalized
+        end
+
+        # Check for conflicting sort configurations (XML-specific)
+        #
+        # Returns false by default. XML overrides to check @mappings[:xml].ordered?
+        #
+        # @return [Boolean] True if there's a conflict
+        def collection_with_conflicting_sort?
+          false
+        end
+
+        # Check and validate sort configurations
+        #
+        # @raise [SortingConfigurationConflictError] If there's a conflict
+        def check_sort_configs!
+          return unless collection_with_conflicting_sort?
+
+          raise Lutaml::Model::SortingConfigurationConflictError.new
+        end
+
+        # Recursively ensure all child model imports are resolved
+        #
+        # Walks through all attributes and ensures any Serializable types
+        # have BOTH model-level imports (attributes) AND mapping-level imports (XML) resolved
+        # before serialization/deserialization begins.
+        #
+        # CRITICAL PERFORMANCE FIX (Session 122):
+        # Uses a visited set to prevent redundant processing in large schemas.
+        # Without this, OOXML-scale schemas (hundreds of classes) create exponential cascades.
+        #
+        # @param register [Symbol] the register ID
+        # @param visited [Set<Class>, nil] classes already processed (internal use only)
+        # @return [void]
+        def ensure_child_imports_resolved!(register, visited = nil)
+          return unless finalized?
+
+          # Normalize register to Symbol for use in instance variable name
+          reg_id = case register
+                   when Symbol then register
+                   when String then register.to_sym
+                   when Lutaml::Model::Register then register.id
+                   else register
+                   end
+
+          # Guard: skip if already resolved for this register.
+          # After the first call, all imports ARE resolved — subsequent calls are pure waste.
+          resolved_key = :"@_imports_resolved_#{reg_id}"
+          if instance_variable_get(resolved_key)
+            return
+          end
+
+          # Create visited set ONLY at top level (first call)
+          # All recursive calls share the SAME set to prevent redundant processing
+          visited ||= Set.new
+
+          return if visited.include?(self) # Already processed this class
+
+          visited.add(self) # Mark as visited BEFORE processing to prevent cycles
+
+          # Mark as resolved BEFORE processing to prevent redundant top-level calls
+          instance_variable_set(resolved_key, true)
+
+          # CRITICAL: Use direct instance variable access to avoid triggering ensure_imports!
+          # Calling attributes(register) would trigger ensure_imports! which creates circular chains
+          attrs = @attributes || {}
+          attrs.each_value do |attr|
+            type_class = attr.type(register)
+            next unless type_class
+            # Check if type_class is a Serializable class that needs import resolution
+            next unless type_class.is_a?(Class) && type_class < Lutaml::Model::Serialize
+            next if visited.include?(type_class) # Skip if already visited
+
+            # Mark child as visited BEFORE processing to prevent cycles
+            visited.add(type_class)
+
+            # Use child's own register if it has one, otherwise use parent's register
+            # This ensures versioned schemas (e.g., MML v2 with lutaml_default_register = :mml_v2)
+            # have their imports resolved in the correct context
+            type_class_register = Lutaml::Model::Register.resolve_for_child(
+              type_class, register
+            )
+
+            # Ensure model-level imports (attributes, choices, and format-specific mappings)
+            # ensure_imports! calls ensure_format_mapping_imports! which is overridden by XML
+            type_class.ensure_imports!(type_class_register)
+
+            # Recursively process child's children, passing THE SAME visited set
+            type_class.ensure_child_imports_resolved!(type_class_register,
+                                                      visited)
+          end
+        end
+      end
+    end
+  end
+end