lutaml-model 0.8.84 → 0.8.85

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: bb58244732a933926315e3f93bd7cf1963420c5f916959ca7e57df9984199d76
-  data.tar.gz: a49e9a5a2ddc4fb14d94f38d4fac696f4d0697002c0ea8d378c62973071c0539
+  metadata.gz: 7fcfb57e6eb2cff5a7cd47dbe44e7e2baceb10ea5e8f8c22c13fa712d5c8a1fb
+  data.tar.gz: 35c30ed77dfee8d8a06a7a9f8f32f94178c3f092f54d949f831f6a29842d6b27
 SHA512:
-  metadata.gz: 78e7b90bafe01c25e64c61be3e2a385b3fd883a67bb53870617c428e1d317b2034dcd09031f952b45df4f65ae56e7d183fbd8c1e626fb2ce71f9a710f3321537
-  data.tar.gz: 442ec5f74ccf68b468e648018aaf846b79874ba5b52327ea36c31ff10482ab5e7acef8ecb4f7a3a6b9d48cc85237c4be7c7b7ac0f4e37a5ca8cbfaccc4e99b10
+  metadata.gz: 45bf3b55c3d356307035278d46709818fdd8ba4a1520741a58117f7419263b3c438f57097a8e736f1a87dac765bc6523e12479dd54b408aee44a23577f9d3726
+  data.tar.gz: 0c6a92ec24a172e016ee0484a2579efed9c3f0c5c653e85ad2509ae441bb71fcffd6c68c4f72d17a250f4587e21af6072116783cf8229cb997692c48cdcc3d1d

data/lib/compat/opal/lutaml_model_boot.rb

@@ -147,6 +147,7 @@ require "lutaml/xml/format"
 require "lutaml/xml/format_chooser"
 require "lutaml/xml/hoisting_algorithm"
 require "lutaml/xml/html_entities"
+require "lutaml/xml/leptris"
 require "lutaml/xml/listener"
 require "lutaml/xml/mapping"
 require "lutaml/xml/mapping_rule"
@@ -170,11 +171,6 @@ require "lutaml/xml/oga"
 require "lutaml/xml/parse_session"
 require "lutaml/xml/parsed_namespace_declaration"
 require "lutaml/xml/parsed_namespace_set"
-require "lutaml/xml/plan_compiler"
-require "lutaml/xml/plan_hydrator"
-require "lutaml/xml/plan_order"
-require "lutaml/xml/plan_serializer"
-require "lutaml/xml/plan_walk"
 require "lutaml/xml/polymorphic_value_handler"
 require "lutaml/xml/qualified_inheritance_strategy"
 require "lutaml/xml/rexml"
@@ -386,6 +382,11 @@ require "lutaml/xml/error/namespace_mismatch_error"
 require "lutaml/xml/error/schema_validation_error"
 require "lutaml/xml/error/xml_configuration_error"
 require "lutaml/xml/error/xml_error"
+require "lutaml/xml/leptris/plan_compiler"
+require "lutaml/xml/leptris/plan_hydrator"
+require "lutaml/xml/leptris/plan_order"
+require "lutaml/xml/leptris/plan_serializer"
+require "lutaml/xml/leptris/plan_walk"
 require "lutaml/xml/oga/element"
 require "lutaml/xml/ox/element"
 require "lutaml/xml/rexml/element"

data/lib/lutaml/key_value/transform.rb

@@ -345,7 +345,9 @@ options)
       end
 
       def valid_mapping?(rule, options)
-        return false if rule.respond_to?(:serialize?) && !rule.serialize?
+        # rule is always Lutaml::Model::MappingRule; serialize? is
+        # statically defined (the hydrate-only marker).
+        return false unless rule.serialize?
 
         only = options[:only]
         except = options[:except]

data/lib/lutaml/model/mapping/mapping.rb

@@ -3,6 +3,19 @@ module Lutaml
     class Mapping
       include DeepDupable
 
+      # Uniform interface across mapping families: every mapping
+      # answers these, so consumers call them unconditionally. The
+      # families that carry the feature override (KeyValue's
+      # root_mappings, Xml's namespace_class); the base defaults make
+      # the absence explicit instead of probed.
+      def root_mappings
+        false
+      end
+
+      def namespace_class
+        nil
+      end
+
       attr_writer :mappings
 
       def initialize

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

@@ -102,11 +102,11 @@ module Lutaml
           return nil unless adapter_name.to_s.end_with?("LeptrisAdapter")
 
           register = Lutaml::Model::Config.default_register
-          plan = Lutaml::Xml::PlanCompiler.compile(self, register)
+          plan = Lutaml::Xml::Leptris::PlanCompiler.compile(self, register)
           return nil unless plan && !plan[:namespaced] &&
-            Lutaml::Xml::PlanSerializer.serializable?(plan)
+            Lutaml::Xml::Leptris::PlanSerializer.serializable?(plan)
 
-          Lutaml::Xml::PlanSerializer.call(instance, plan)
+          Lutaml::Xml::Leptris::PlanSerializer.call(instance, plan)
         end
 
         # Whole-document native materialization (Phase 5): compile the
@@ -126,14 +126,14 @@ module Lutaml
           return nil unless adapter_name.to_s.end_with?("LeptrisAdapter")
 
           register = Lutaml::Model::Config.default_register
-          plan = Lutaml::Xml::PlanCompiler.compile(self, register)
+          plan = Lutaml::Xml::Leptris::PlanCompiler.compile(self, register)
           return nil unless plan
 
           root = ::Leptris::XML.parse(data.to_s).root
           return nil if root.nil?
           return nil unless root.name == plan[:tree][:name]
 
-          Lutaml::Xml::PlanHydrator.call(self, plan,
+          Lutaml::Xml::Leptris::PlanHydrator.call(self, plan,
                                          plan[:descriptor].walk(root),
                                          node: root)
         rescue ::Leptris::XML::ParseError => e

data/lib/lutaml/model/version.rb

@@ -2,6 +2,6 @@
 
 module Lutaml
   module Model
-    VERSION = "0.8.84"
+    VERSION = "0.8.85"
   end
 end

data/lib/lutaml/xml/format.rb

@@ -22,11 +22,9 @@ end
 module Lutaml
   module Xml
     autoload :HtmlEntities, "#{__dir__}/html_entities"
-    autoload :PlanCompiler, "#{__dir__}/plan_compiler"
-    autoload :PlanHydrator, "#{__dir__}/plan_hydrator"
-    autoload :PlanOrder, "#{__dir__}/plan_order"
-    autoload :PlanSerializer, "#{__dir__}/plan_serializer"
-    autoload :PlanWalk, "#{__dir__}/plan_walk"
+    # The leptris plan fast path lives under its own namespace; its
+    # autoloads and the leptris version gate live in lutaml/xml/leptris.
+    autoload :Leptris, "#{__dir__}/leptris"
     # Error module for XML-specific errors
     module Error
       autoload :XmlError, "#{__dir__}/error/xml_error"

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

@@ -0,0 +1,372 @@
+# frozen_string_literal: true
+
+module Lutaml
+  module Xml
+    module Leptris
+      # 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
+        # TODO.perf/15: env-gated histogram of why models opt out of the
+        # plan path. Set PLAN_COMPILE_STATS=1 and read PlanCompiler.stats
+        # after a parse. Zero cost when disabled.
+        def self.stats
+          @stats ||= Hash.new(0)
+        end
+
+        def self.opt_out!(clause)
+          @plan_stats ||= Hash.new(0)
+          @plan_stats[clause] += 1 if ENV["PLAN_COMPILE_STATS"]
+          nil
+        end
+
+        # 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)
+            # Version gate, not a capability probe: the plan path needs
+            # leptris >= 1.9.273.0 (the child-handles snapshot). Older
+            # gems take the interpretive path via the nil opt-out.
+            return nil unless Leptris.plan_path_compatible?
+
+            # A child model's declared lutaml_default_register takes
+            # precedence over the ambient (parent) register — the same
+            # contract the interpretive path applies through
+            # Register.resolve_for_child. Without this, plan compilation
+            # resolves the child's symbol attribute types in the parent
+            # context and raises UnknownTypeError for ids registered only
+            # in the child's own register (#876).
+            register = Lutaml::Model::Register.resolve_for_child(
+              model_class, register
+            )
+
+            key = [model_class, register]
+            return PLAN_CACHE[key] if PLAN_CACHE.key?(key)
+
+            # Cycle guard: a self-referential model (JATS sec-in-sec) must
+            # resolve to nil — the interpretive pipeline owns it. The guard
+            # is THREAD-LOCAL (a shared in-progress set races: a concurrent
+            # same-key compile would cache false permanently — the #828
+            # lesson); the nil at the cycle point is NOT cached — the
+            # outermost build completes and caches the real verdict.
+            stack = (Thread.current[:plan_compiler_stack] ||= [])
+            return nil if stack.include?(key)
+
+            stack.push(key)
+            begin
+              PLAN_CACHE[key] = build(model_class, register)
+            ensure
+              stack.pop
+            end
+          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 opt_out!(:attr_nil) if attr.nil?
+              return opt_out!(:derived) if attr.derived?
+
+              # Partition rows (TODO 34 step 2) ride native predicates
+              # only in the plain-capture shape; any other when_attribute
+              # shape stays interpretive (the suite pins nested-target
+              # partitions to the interpretive path).
+              unless rule.when_attribute.empty?
+                t = attr.type(register)
+                plain_partition = !rule.delegate &&
+                  !rule.has_custom_method_for_deserialization? &&
+                  !rule.polymorphic_mapping? &&
+                  !attr.polymorphic? && !attr.union? &&
+                  !(t.is_a?(Class) &&
+                    t.include?(::Lutaml::Model::Serialize))
+                return opt_out!(:non_plain_partition) unless plain_partition
+              end
+
+              # 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 opt_out!(:fragment_with_ns) if fragment_needed && model_ns
+
+              if rule.attribute?
+                return opt_out!(:non_scalar) unless scalar_type?(attr, register)
+                # Attribute plan rows are local-name keyed; a type-level
+                # namespace makes the attribute (URI, local)-identified
+                # (lutaml-model#744) — the interpretive matcher owns it
+                # until plan rows carry namespace identity.
+                return opt_out!(:attr_type_ns) if attr.type_namespace_class(register)
+
+                attr_rows << [rule, attr]
+                plan_attrs << { name: rule.name.to_s }
+              elsif rule.content_mapping?
+                return opt_out!(:multi_content) 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 opt_out!(:non_serializable_poly) 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 opt_out!(:child_uncompilable) 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 opt_out!(:ordered_child_with_ns) 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 opt_out!(:non_scalar) unless scalar_type?(attr, register)
+
+                  row = { name: rule.name.to_s }
+                  row[:ns] = child_ns(rule, model_ns) if rule.namespace_set?
+                  # lutaml-model#88: same-name rows partitioned by the
+                  # rule's discriminator ride the engine's exclusive
+                  # predicate match (leptris 1.9.221+, #1272).
+                  row[:when] = rule.when_attribute unless rule.when_attribute.empty?
+
+                  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
+
+            row_tags = partition_row_tags!(compiled, rows, tag)
+
+            # The plan serializer does not emit namespace declarations —
+            # namespaced models serialize through the interpretive
+            # writer (lutaml-model#847: standalone to_xml under leptris
+            # dropped the element xmlns entirely).
+            namespaced = !model_ns.nil? || rows.any? { |r| r[:ns] }
+
+            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,
+              row_tags: row_tags, namespaced: namespaced,
+              ordered: mapping.ordered? || mapping.mixed_content?,
+              needs_nodes: needs_nodes,
+              collection_defaults: collection_defaults }
+          end
+
+          def compilable_mapping?(mapping)
+            # Mapping's uniform interface: root_mappings defaults to
+            # false on the base (KeyValue overrides with its own).
+            mapping.root_element && !mapping.root_mappings
+          end
+
+          # Partition bookkeeping for when_attribute rows (#88, TODO
+          # 34 step 2): the engine matches same-name rows exclusively —
+          # first matching row wins — so predicate rows must PRECEDE any
+          # plain sibling on the same name (a plain-first order
+          # double-captures: the plain row takes everything and the
+          # predicates still claim their matches). Every row of a
+          # partitioned name gets a distinct type_tag; plan values echo
+          # it back, giving the hydrator row-exact routing with no
+          # per-occurrence re-derivation. Returns {compiled_index =>
+          # tag} (nil when the model has no partitions). compiled and
+          # rows are parallel and stay in lockstep through the reorder.
+          def partition_row_tags!(compiled, rows, tag)
+            by_name = rows.each_with_index
+              .group_by { |(row, _)| row[:name] }
+              .select { |_name, pairs| pairs.any? { |(row, _)| row[:when] } }
+            return nil if by_name.empty?
+
+            permutation = by_name.each_value.flat_map do |pairs|
+              pairs.sort_by { |(row, i)| [row[:when] ? 0 : 1, i] }
+                .map(&:last)
+            end
+            remaining = (0...rows.length).to_a - permutation
+            permutation.concat(remaining)
+
+            row_tags = {}
+            permutation.each_with_index do |old_index, new_index|
+              row = rows[old_index]
+              next unless by_name.key?(row[:name])
+
+              tag += 1
+              row[:type_tag] = tag
+              row_tags[new_index] = tag
+            end
+            rows.replace(permutation.map { |i| rows[i] })
+            compiled.replace(permutation.map { |i| compiled[i] })
+            row_tags
+          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)
+            # Mapping's uniform interface: namespace_class defaults
+            # to nil on the base (Xml overrides).
+            ns_class = mapping.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
+end