lutaml-model 0.8.23 → 0.8.28

data/lib/lutaml/xml/leptris/element.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+module Lutaml
+  module Xml
+    class LeptrisElement < AdapterElement
+      def initialize(node, parent: nil, default_namespace: nil)
+        @raw_text = node.raw_content if node.is_a?(Moxml::Text)
+        super
+      end
+
+      private
+
+      def adapter_class
+        Lutaml::Xml::Adapter::LeptrisAdapter
+      end
+
+      def build_text_for_xml
+        @raw_text || @text
+      end
+
+      def build_element_xml(builder)
+        builder.create_and_add_element(name,
+                                       prefix: namespace_prefix,
+                                       attributes: build_attributes(self)) do |xml|
+          children.each { |child| child.build_xml(xml) }
+        end
+      end
+
+      def attribute_value_for_build(attr)
+        attr.raw_value
+      end
+    end
+  end
+end

data/lib/lutaml/xml/namespace_collector.rb

@@ -566,9 +566,10 @@ module Lutaml
                 # Resolve type using child model's register context
                 mapper_class = options[:mapper_class]
                 child_register = if mapper_class
-                                   Lutaml::Model::Register.resolve_for_child(
-                                     mapper_class, @register
-                                   )
+                                   (@register_for ||= {})[mapper_class] ||=
+                                     Lutaml::Model::Register.resolve_for_child(
+                                       mapper_class, @register
+                                     )
                                  else
                                    @register
                                  end

data/lib/lutaml/xml/plan_compiler.rb

@@ -0,0 +1,253 @@
+# frozen_string_literal: true
+
+module Lutaml
+  module Xml
+    # Phase 5 slice: compile a model's XML mapping into a
+    # Leptris::XML::Descriptor plan and materialize whole documents in
+    # one native pass (leptris_plan_walk) — no moxml wrapper tree, no
+    # per-element Ruby dispatch. Measured on the 200-item probe:
+    # walk+hydrate 8.7x faster, 82% fewer allocations than the
+    # interpretive path, hydration-equal output.
+    #
+    # A model compiles when EVERY rule is plan-shaped; richer rows
+    # defer their subtree verbatim and interpret post-walk rather
+    # than opting the whole model out:
+    #   - map_attribute / map_element / content / raw rows
+    #   - Value-scalar types or nested Serializables
+    #   - custom methods, polymorphism, unions, and ordered/mixed
+    #     children capture :raw and interpret post-walk
+    #   - ordered/mixed root mappings compile; the entry points
+    #     reconstruct element_order from the node surface
+    #   - attributes not derived/union/polymorphic
+    #
+    # The fast path is opt-in (Config.xml_plan_fast_path) while the
+    # full semantics audit (parent links, consolidation, ordering
+    # metadata) completes.
+    module PlanCompiler
+      # Isolated holder: suites freeze model classes; a cache on a
+      # frozen constant would be immutable (TypeProbeCache precedent).
+      PLAN_CACHE = ::Class.new do
+        class << self
+          def cache
+            @cache ||= {}
+          end
+        end
+      end.cache
+
+      class << self
+        def compile(model_class, register)
+          key = [model_class, register]
+          return PLAN_CACHE[key] if PLAN_CACHE.key?(key)
+
+          PLAN_CACHE[key] = build(model_class, register)
+        end
+
+        private
+
+        def build(model_class, register)
+          return nil unless model_class.is_a?(Class) &&
+            model_class.include?(::Lutaml::Model::Serialize)
+
+          mapping = model_class.mappings_for(:xml, register)
+          return nil unless compilable_mapping?(mapping)
+
+          rows = []
+          attr_rows = [] # [[rule, attr]] hydration metadata
+          plan_attrs = [] # [{name:, kind:}] rows for the engine plan
+          compiled = [] # [rule, attr, kind, spelling, delegate_target]
+          cdata = false
+          mixed_content = false
+          needs_nodes = false
+          collection_defaults = [] # collection attrs with element rows
+          tag = 100 # type_tag echo space for callback-routed rows
+          model_ns = plan_namespace(model_class, mapping, register)
+
+          # Collection rows are NATIVE since leptris 1.9.178 —
+          # collection values echo name and type_tag (the #220 gap is
+          # closed), so any number routes without callbacks.
+          true
+
+          mapping.mappings(register).each do |rule|
+            delegate_target = nil
+            attr = if rule.delegate
+                     delegate_target = model_class.attributes(register)[rule.delegate]
+                     t = delegate_target&.type(register)
+                     if t.is_a?(Class) && t.include?(::Lutaml::Model::Serialize)
+                       t.attributes(register)[rule.to]
+                     end
+                   else
+                     model_class.attributes(register)[rule.to]
+                   end
+            return nil if attr.nil?
+            return nil if attr.derived?
+
+            # Interpretive hydration materializes every mapped
+            # collection, present or not; the fast path mirrors with
+            # constructor-time empty arrays.
+            unless rule.attribute? || !attr.collection?
+              collection_defaults << attr.name.to_sym
+            end
+
+            # Fragment deferrals lose ancestor namespace context —
+            # ns-qualified models keep those rules interpretive.
+            fragment_needed = rule.has_custom_method_for_deserialization? ||
+              rule.polymorphic_mapping? || attr.polymorphic? || attr.union?
+            return nil if fragment_needed && model_ns
+
+            if rule.attribute?
+              return nil unless scalar_type?(attr, register)
+
+              attr_rows << [rule, attr]
+              plan_attrs << { name: rule.name.to_s }
+            elsif rule.content_mapping?
+              return nil if content_rows(rows) >= 1
+
+              mixed_content = true
+              compiled << [rule, attr,
+                           attr.collection? ? :content : :content_deferred,
+                           nil, delegate_target]
+              rows << { name: "__content__#{compiled.size}", kind: :content }
+            elsif rule.raw_mapping? || rule.raw == :element
+              compiled << [rule, attr, :raw, nil, delegate_target]
+              rows << { name: rule.name.to_s, kind: :raw }
+            elsif rule.has_custom_method_for_deserialization?
+              needs_nodes = true
+              compiled << [rule, attr, :custom_method, nil, delegate_target]
+              rows << { name: rule.name.to_s, kind: :raw }
+            elsif rule.polymorphic_mapping? || attr.polymorphic? || attr.union?
+              type = attr.type(register)
+              return nil unless serializable_type?(type) || attr.union?
+
+              needs_nodes = true
+              compiled << [rule, attr, :polymorphic, nil, delegate_target]
+              rows << { name: rule.name.to_s, kind: :raw }
+            else
+              type = attr.type(register)
+              if serializable_type?(type)
+                child = compile(type, register)
+                return nil unless child
+
+                if child[:ordered]
+                  # Ordered/mixed children need element_order on their
+                  # instances; the walk hands back plan values, not
+                  # source nodes, so the subtree defers interpretively
+                  # (the fragment parse runs the full machinery,
+                  # order included).
+                  return nil if model_ns
+
+                  needs_nodes = true
+                  compiled << [rule, attr, :ordered_deferred, nil,
+                               delegate_target]
+                  rows << { name: rule.name.to_s, kind: :raw }
+                else
+                  compiled << [rule, attr, :nested, nil, delegate_target]
+                  needs_nodes ||= child[:needs_nodes]
+                  nested_row = { name: rule.name.to_s, kind: :nested,
+                                 plan: child[:tree] }
+                  nested_row[:ns] = child_ns(rule, model_ns) if rule.namespace_set?
+                  rows << nested_row
+                end
+              elsif rule.multiple_mappings?
+                rule.name.each do |spelling|
+                  compiled << [rule, attr, :spelling, spelling.to_s,
+                               delegate_target]
+                  rows << { name: spelling.to_s, kind: :callback,
+                            type_tag: (tag += 1) }
+                end
+              else
+                return nil unless scalar_type?(attr, register)
+
+                row = { name: rule.name.to_s }
+                row[:ns] = child_ns(rule, model_ns) if rule.namespace_set?
+
+                if attr.collection?
+                  compiled << [rule, attr, :collection_native, nil,
+                               delegate_target]
+                  rows << row.merge(kind: :collection)
+                else
+                  cdata ||= rule.cdata
+                  compiled << [rule, attr, :scalar, nil, delegate_target]
+                  rows << row.merge(kind: :scalar)
+                end
+              end
+            end
+          end
+
+          flags = []
+          flags << :cdata if cdata
+          flags << :mixed_content if mixed_content
+          flags << :ns_lenient if model_ns
+          tree = { name: mapping.root_element.to_s,
+                   attributes: plan_attrs, children: rows }
+          tree[:ns] = model_ns if model_ns
+          tree[:flags] = flags unless flags.empty?
+          begin
+            # Lazy: the Opal boot loads this file, and leptris is a
+            # native gem there — the require only belongs on the
+            # engines-enabled path.
+            require "leptris/xml/descriptor"
+            descriptor = ::Leptris::XML::Descriptor.build(**tree)
+          rescue StandardError
+            return nil
+          end
+
+          { descriptor: descriptor, tree: tree, rows: compiled,
+            attr_rows: attr_rows, mapping: mapping,
+            ordered: mapping.ordered? || mapping.mixed_content?,
+            needs_nodes: needs_nodes,
+            collection_defaults: collection_defaults }
+        end
+
+        def compilable_mapping?(mapping)
+          mapping.root_element &&
+            !(mapping.respond_to?(:root_mappings) && mapping.root_mappings)
+        end
+
+        # Attribute for a rule — delegate rules resolve against their
+        # target model's attributes.
+        def attr_of(model_class, rule, register)
+          attr = model_class.attributes(register)[rule.to]
+          return attr if attr || !rule.delegate
+
+          target = model_class.attributes(register)[rule.delegate]
+          t = target&.type(register)
+          if t.is_a?(Class) && t.include?(::Lutaml::Model::Serialize)
+            t.attributes(register)[rule.to]
+          end
+        end
+
+        # Rule-level namespace → ChildPlan ns form (leptris 1.9.178):
+        # the child binds by local name under the rule's URI with any
+        # prefix. Blank-namespace rules (xmlns="") match :none.
+        def child_ns(rule, _model_ns)
+          uri = rule.namespace
+          return { exact: uri.to_s } if uri && !uri.to_s.empty?
+
+          :none
+        end
+
+        def content_rows(rows)
+          rows.count { |r| r[:kind] == :content }
+        end
+
+        # Model-level namespace: exact URI match with lenient prefixes
+        # — children bind by local name under any prefix the document
+        # bound to the URI (#754 adoption semantics on the engine).
+        def plan_namespace(_model_class, mapping, _register)
+          ns_class = mapping.namespace_class if mapping.respond_to?(:namespace_class)
+          ns_class&.uri ? { exact: ns_class.uri.to_s } : nil
+        end
+
+        def scalar_type?(attr, register)
+          type = attr.type(register)
+          type.is_a?(Class) && type < ::Lutaml::Model::Type::Value &&
+            !attr.custom_collection?
+        end
+
+        def serializable_type?(type)
+          type.is_a?(Class) && type.include?(::Lutaml::Model::Serialize)
+        end
+      end
+    end
+  end
+end

data/lib/lutaml/xml/plan_hydrator.rb

@@ -0,0 +1,341 @@
+# frozen_string_literal: true
+
+module Lutaml
+  module Xml
+    # Hydrates model instances from a Descriptor#walk PlanValue tree,
+    # keyed by each value's producing row name (never position — rows
+    # for missing elements are simply absent). Native rows build
+    # constructor kwargs; deferred rows (custom methods, polymorphism,
+    # unions) capture their subtree verbatim and interpret it
+    # post-walk — the fragment parse runs the existing interpretive
+    # machinery on just that island. Delegate rules hydrate
+    # post-instance onto their target object. Collection rows route
+    # natively when a single one exists, else through callback rows
+    # (their values echo name and type_tag; native collection values
+    # echo neither — leptris-ruby#220).
+    module PlanHydrator
+      class << self
+        # plan: the compiler's entry for model_class
+        # value: the walk root PlanValue (element)
+        # node: the parsed source element (leptris); ordered/mixed
+        #   plans rebuild element_order from it and ordered children
+        #   hydrate natively against their own nodes
+        def call(model_class, plan, value, parent: nil, node: nil)
+          buckets = node && plan[:needs_nodes] ? element_buckets(node) : nil
+          attr_kwargs = attributes_kwargs(plan, value)
+          child_kwargs, children, delegates =
+            children_kwargs(model_class, plan, value, buckets)
+          plan[:collection_defaults].each do |name|
+            next if attr_kwargs.key?(name) || child_kwargs.key?(name)
+
+            child_kwargs[name] = []
+          end
+          instance = model_class.new(**attr_kwargs, **child_kwargs)
+          instance.lutaml_parent = parent if parent
+          instance.lutaml_root ||= parent&.lutaml_root || parent
+          instance.element_order = PlanOrder.build(node) if node && plan[:ordered]
+          children.each do |child|
+            child.lutaml_parent = instance
+            child.lutaml_root ||= instance.lutaml_root || instance
+          end
+          interpret_deferred(model_class, plan, value, instance, node, buckets)
+          route_delegates(delegates, instance)
+          instance
+        end
+
+        private
+
+        def register
+          Lutaml::Model::Config.default_register
+        end
+
+        def attributes_kwargs(plan, value)
+          kwargs = {}
+          plan[:attr_rows].each do |rule, attr|
+            v = value.attribute(rule.name.to_s)
+            next if v.nil?
+
+            v = v.split(rule.delimiter) if rule.delimiter
+            if rule.as_list && rule.as_list[:import]
+              v = rule.as_list[:import].call(v)
+            end
+            kwargs[attr.name.to_sym] = v
+          end
+          kwargs
+        end
+
+        # Returns [kwargs, hydrated_child_instances, delegate_values]
+        # — child instances come back so the caller can decorate
+        # parent/root links once the parent exists; delegate values
+        # wait for the instance (their target object must exist).
+        def children_kwargs(_model_class, plan, value, buckets = nil)
+          grouped = group_children(value)
+          buckets = nil unless buckets && plan[:needs_nodes]
+          kwargs = {}
+          children = []
+          delegates = []
+          spellings = Hash.new { |h, k| h[k] = [] }
+          plan[:rows].each do |rule, attr, kind, spelling, delegate|
+            case kind
+            when :scalar
+              # Raw passthrough: the model constructor is the single
+              # cast authority — pre-casting here doubled every cast.
+              # Class transforms still apply before assignment.
+              v = grouped.dig(rule.name.to_s, 0)&.string_value
+              unless v.nil?
+                v = rule.transform_value(attr, v, :from, :xml) if rule.transform.is_a?(Class)
+                assign(kwargs, delegates, delegate, rule, attr, v)
+              end
+            when :raw, :custom_method, :polymorphic, :content_deferred
+              # interpreted post-instance (interpret_deferred)
+            when :content
+              assign(kwargs, delegates, delegate, rule, attr,
+                     content_runs(value))
+            when :ordered_deferred
+              # With a source node the child hydrates natively: one
+              # walk against its own node + element_order from the
+              # node's children. Without one (direct PlanHydrator
+              # use), the subtree fragment-parses interpretively.
+              if buckets
+                child_type = attr.type(register)
+                child_plan = PlanCompiler.compile(child_type, register)
+                items = buckets.fetch(rule.name.to_s, []).map do |n|
+                  call(child_type, child_plan,
+                       child_plan[:descriptor].walk(n), node: n)
+                end
+                unless items.empty?
+                  children.concat(items)
+                  assign(kwargs, delegates, delegate, rule, attr,
+                         attr.collection? ? items : items.first)
+                end
+              end
+            when :collection_cb
+              values = grouped[rule.name.to_s].to_a.map(&:string_value)
+              if rule.transform.is_a?(Class)
+                values = values.map { |v| rule.transform_value(attr, v, :from, :xml) }
+              end
+              unless values.empty?
+                assign(kwargs, delegates, delegate, rule, attr, values)
+              end
+            when :collection_native
+              values = native_collection(value, rule.name.to_s)
+              unless values.nil?
+                assign(kwargs, delegates, delegate, rule, attr, values)
+              end
+            when :spelling
+              spellings[[rule, attr]] << grouped[spelling.to_s].to_a
+            when :nested
+              child_type = attr.type(register)
+              child_plan = PlanCompiler.compile(child_type, register)
+              cursor = if child_plan[:needs_nodes] && buckets
+                         buckets.fetch(rule.name.to_s, [])
+                       end
+              items = grouped.fetch(rule.name.to_s, []).each_with_index
+                .map do |v, i|
+                  call(child_type, child_plan, v,
+                       node: cursor && cursor[i])
+                end
+              next if items.empty?
+
+              children.concat(items)
+              assign(kwargs, delegates, delegate, rule, attr,
+                     attr.collection? ? items : items.first)
+            end
+          end
+          unless spellings.empty?
+            spellings.each do |(rule, attr), groups|
+              # Interpretive order for shared-attribute groups is
+              # spelling-group order (first spelling's matches, then
+              # the next's), not interleaved document order.
+              values = groups.compact.flatten.map(&:string_value)
+              next if values.empty?
+
+              delegate = delegate_of(plan, rule)
+              assign(kwargs, delegates, delegate, rule, attr,
+                     attr.collection? ? values : values.first)
+            end
+          end
+          [kwargs, children, delegates]
+        end
+
+        # Deferred islands: raw subtrees become wrapper elements via a
+        # fragment parse, then the interpretive machinery runs on just
+        # that island — custom method invocation with an
+        # element-shaped argument, or the polymorphic/union cast.
+        # With the source node available the island wraps the ORIGINAL
+        # node (no fragment parse — the reparse dominated deferred
+        # hydration). Ordered children only land here without a node.
+        def interpret_deferred(model_class, plan, value, instance, node = nil,
+                               buckets = nil)
+          plan[:rows].each do |rule, attr, kind, _spelling, _delegate|
+            case kind
+            when :content_deferred
+              runs = content_runs(value)
+              next if runs.empty?
+
+              # Non-collection content attrs hold the joined text
+              # (the interpretive path assigns element text, the runs
+              # concatenated).
+              instance.public_send(:"#{attr.name}=", runs.join)
+            when :raw
+              raws = raw_strings(value, rule)
+              next if raws.empty?
+
+              instance.public_send(:"#{attr.name}=",
+                                   attr.collection? ? raws : raws.first)
+            when :custom_method
+              elements = deferred_elements(value, rule, buckets)
+              next if elements.empty?
+
+              args = attr.collection? ? elements : elements.first
+              rule.deserialize(instance, args,
+                               model_class.attributes(register),
+                               model_class)
+            when :ordered_deferred
+              next if node # hydrated natively in children_kwargs
+
+              results = deferred_elements(value, rule, buckets).map do |element|
+                attr.cast(element, :xml, register,
+                          lutaml_parent: instance,
+                          lutaml_root: instance.lutaml_root || instance)
+              end
+              next if results.empty?
+
+              instance.public_send(:"#{attr.name}=",
+                                   attr.collection? ? results : results.first)
+            when :polymorphic
+              results = deferred_elements(value, rule, buckets).map do |element|
+                attr.cast(element, :xml, register,
+                          polymorphic: rule.polymorphic,
+                          lutaml_parent: instance,
+                          lutaml_root: instance.lutaml_root || instance)
+              end
+              next if results.empty?
+
+              instance.public_send(:"#{attr.name}=",
+                                   attr.collection? ? results : results.first)
+            end
+          end
+        end
+
+        # Wrapper elements for deferred rows: the ORIGINAL source
+        # nodes bridged through moxml's wrapper cache (wrapper
+        # construction only, no parse), falling back to a fragment
+        # parse of the captured subtree when no node is available.
+        # Both lists are document-ordered for the row's name.
+        def deferred_elements(value, rule, buckets)
+          nodes = buckets && buckets[rule.name.to_s]
+          return nodes.map { |n| bridge_element(n) } if nodes
+
+          raw_strings(value, rule).map { |raw| fragment_element(raw) }
+        end
+
+        def bridge_element(node)
+          Lutaml::Xml::LeptrisElement.new(
+            Moxml::Node.wrap(node, bridge_context),
+          )
+        end
+
+        def bridge_context
+          @bridge_context ||= Moxml::Context.new(:leptris)
+        end
+
+        def route_delegates(delegates, instance)
+          delegates.each do |rule, delegate_attr, attr, v|
+            target = instance.public_send(rule.delegate)
+            unless target
+              # the interpretive path instantiates absent delegate
+              # targets; mirror it
+              target = delegate_attr.type(register).new
+              instance.public_send(:"#{rule.delegate}=", target)
+            end
+            target.public_send(:"#{attr.name}=", v)
+          end
+        end
+
+        def delegate_of(plan, rule)
+          entry = plan[:rows].find { |r, _, _k, _| r.equal?(rule) }
+          entry && entry[4]
+        end
+
+        # Delegate rules hold their values for post-instance routing
+        # (the target object must exist first); plain rules land in
+        # kwargs directly.
+        def assign(kwargs, delegates, delegate, rule, attr, value)
+          if delegate
+            delegates << [rule, delegate, attr, value]
+          else
+            kwargs[attr.name.to_sym] = value
+          end
+        end
+
+        def content_runs(value)
+          out = []
+          value.count.times do |i|
+            c = value.at(i)
+            next unless c.name.nil? && c.kind == :collection
+
+            out.concat(Array.new(c.count) { |j| c.at(j).string_value })
+          end
+          out
+        end
+
+        # Native collection rows echo their producing row's name
+        # (leptris 1.9.178).
+        def native_collection(value, name)
+          value.count.times do |i|
+            c = value.at(i)
+            next unless c.kind == :collection && c.name == name
+
+            return Array.new(c.count) { |j| c.at(j).string_value }
+          end
+          nil
+        end
+
+        def raw_strings(value, rule)
+          out = []
+          value.count.times do |idx|
+            child = value.at(idx)
+            if child.name == rule.name.to_s && child.kind == :raw
+              out << child.string_value
+            end
+          end
+          out
+        end
+
+        # Fragment deferral: parse the captured subtree back into a
+        # wrapper element. Ancestor namespace context is absent (the
+        # compiler only defers on namespace-free model chains).
+        def fragment_element(raw)
+          Lutaml::Xml::Adapter::LeptrisAdapter.parse(raw).root
+        end
+
+        def group_children(value)
+          grouped = {}
+          value.count.times do |i|
+            child = value.at(i)
+            next if child.name.nil? # content runs, read separately
+
+            (grouped[child.name] ||= []) << child
+          end
+          grouped
+        end
+
+        # Element children bucketed by local name, document order
+        # preserved — the node-side mirror of group_children for
+        # ordered-child hydration. Only built when the plan's subtree
+        # needs source nodes; namespace-qualified models never get
+        # here (the compiler keeps them interpretive).
+        def element_buckets(node)
+          buckets = {}
+          node.children.each do |child|
+            next unless child.is_a?(::Leptris::XML::Element)
+
+            (buckets[child.name] ||= []) << child
+          end
+          buckets
+        end
+      end
+    end
+  end
+end

data/lib/lutaml/xml/plan_order.rb

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+module Lutaml
+  module Xml
+    # Reconstructs element_order for ordered/mixed models from the
+    # leptris node surface in one native pass, mirroring the
+    # interpretive AdapterElement#order contract: text runs, CDATA,
+    # comments, PIs, and element entries (local name + namespace
+    # uri/prefix) in document order, frozen like the interpretive
+    # product.
+    module PlanOrder
+      TEXT_MARKER = "text"
+      CDATA_MARKER = "#cdata-section"
+      COMMENT_MARKER = "comment"
+
+      class << self
+        def build(node)
+          node.children.filter_map { |child| entry_for(child) }
+            .each(&:freeze).freeze
+        end
+
+        private
+
+        def entry_for(child)
+          case child
+          when ::Leptris::XML::CDATA
+            Element.new("Text", CDATA_MARKER,
+                        text_content: child.content, node_type: :cdata)
+          when ::Leptris::XML::Text
+            Element.new("Text", TEXT_MARKER,
+                        text_content: child.text, node_type: :text)
+          when ::Leptris::XML::Comment
+            Element.new("Comment", COMMENT_MARKER,
+                        text_content: child.content, node_type: :comment)
+          when ::Leptris::XML::ProcessingInstruction
+            Element.new("ProcessingInstruction", child.name,
+                        text_content: child.content.to_s.sub(/\A\s+/, ""),
+                        node_type: :processing_instruction)
+          when ::Leptris::XML::Element
+            ns = child.namespace
+            Element.new("Element", child.name,
+                        node_type: :element,
+                        namespace_uri: ns&.values&.first,
+                        namespace_prefix: ns&.keys&.first)
+          end
+        end
+      end
+    end
+  end
+end