lutaml-model 0.8.22 → 0.8.24

data/lib/lutaml/xml/plan_compiler.rb

@@ -0,0 +1,139 @@
+# 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 only when EVERY rule is plan-shaped; anything
+    # richer keeps the interpretive path (all-or-nothing per model):
+    #   - map_attribute / map_element rows only
+    #   - element rows: Value-scalar types or nested Serializables
+    #   - no content/raw mappings, custom methods, delegates,
+    #     polymorphism, transforms, multiple spellings, namespaces,
+    #     ordered mappings, hash_mappings, root_mappings
+    #   - 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] in children order
+          mapping.mappings(register).each do |rule|
+            attr = model_class.attributes(register)[rule.to]
+            return nil if attr.nil?
+            return nil if attr.derived? || attr.union? || attr.polymorphic?
+
+            if rule.attribute?
+              return nil unless scalar_type?(attr, register)
+
+              attr_rows << [rule, attr]
+              plan_attrs << { name: rule.name.to_s }
+            else
+              return nil unless plan_element_row?(rule)
+
+              type = attr.type(register)
+              if serializable_type?(type)
+                child = compile(type, register)
+                return nil unless child
+
+                compiled << [rule, attr, :nested]
+                rows << { name: rule.name.to_s, kind: :nested,
+                          plan: child[:tree] }
+              else
+                return nil unless scalar_type?(attr, register)
+
+                kind = attr.collection? ? :collection : :scalar
+                # Collection row values carry neither name nor type_tag
+                # echo (leptris 1.9.174): hydration can only attribute
+                # them unambiguously with a single collection row per
+                # element.
+                if kind == :collection && rows.count { |r| r[:kind] == :collection } >= 1
+                  return nil
+                end
+
+                compiled << [rule, attr, kind]
+                rows << { name: rule.name.to_s, kind: kind }
+              end
+            end
+          end
+
+          tree = { name: mapping.root_element.to_s, attributes: plan_attrs,
+                   children: rows }
+          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 }
+        end
+
+        def compilable_mapping?(mapping)
+          !mapping.ordered? && mapping.root_element &&
+            !(mapping.respond_to?(:root_mappings) && mapping.root_mappings)
+        end
+
+        def plan_element_row?(rule)
+          !rule.raw_mapping? && !rule.content_mapping? &&
+            !rule.delegate && !rule.multiple_mappings? &&
+            !rule.namespace_set? && !rule.cdata &&
+            !rule.mixed_content && !rule.as_list && !rule.delimiter &&
+            !rule.has_custom_method_for_deserialization? &&
+            !rule.polymorphic_mapping? &&
+            !(rule.transform.is_a?(Hash) && !rule.transform.empty?) &&
+            !rule.transform.is_a?(Class)
+        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,80 @@
+# 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). Builds constructor
+    # kwargs recursively and instantiates through .new, so typing,
+    # defaults, and collection semantics all ride the constructor.
+    module PlanHydrator
+      class << self
+        # plan: the compiler's entry for model_class
+        # value: the walk root PlanValue (element)
+        def call(model_class, plan, value)
+          kwargs = attributes_kwargs(plan, value)
+          kwargs.merge!(children_kwargs(model_class, plan, value))
+          model_class.new(**kwargs)
+        end
+
+        private
+
+        def attributes_kwargs(plan, value)
+          kwargs = {}
+          plan[:attr_rows].each do |rule, attr|
+            v = value.attribute(rule.name.to_s)
+            kwargs[attr.name.to_sym] = v unless v.nil?
+          end
+          kwargs
+        end
+
+        def children_kwargs(_model_class, plan, value)
+          register = Lutaml::Model::Config.default_register
+          grouped = group_children_by_name(value)
+
+          kwargs = {}
+          plan[:rows].each do |rule, attr, kind|
+            values = grouped[kind == :collection ? :__collection : rule.name.to_s]
+            next if values.nil? || values.empty?
+
+            kwargs[attr.name.to_sym] =
+              case kind
+              when :scalar
+                values.first.string_value
+              when :collection
+                # One collection-row value per element; its items are
+                # the individual scalar matches.
+                values.flat_map do |cv|
+                  Array.new(cv.count) { |i| cv.at(i).string_value }
+                end
+              when :nested
+                child_plan = PlanCompiler.compile(attr.type(register),
+                                                  register)
+                items = values.map do |v|
+                  call(attr.type(register), child_plan, v)
+                end
+                attr.collection? ? items : items.first
+              end
+          end
+          kwargs
+        end
+
+        # Scalar and nested values echo their producing row's name;
+        # collection values echo neither name nor type_tag, so with the
+        # compiler's single-collection-row guard they are attributed by
+        # kind.
+        def group_children_by_name(value)
+          grouped = {}
+          value.count.times do |i|
+            child = value.at(i)
+            key = child.name || (child.kind == :collection ? :__collection : nil)
+            next if key.nil?
+
+            (grouped[key] ||= []) << child
+          end
+          grouped
+        end
+      end
+    end
+  end
+end

data/lib/lutaml/xml/transformation/custom_method_wrapper.rb

@@ -80,6 +80,14 @@ module Lutaml
         require "moxml" unless defined?(Moxml)
         fragment_doc = Moxml.new.parse(fragment_string, fragment: true)
         add_fragment_children_to_parent(fragment_doc, parent)
+      rescue Moxml::ParseError
+        # Engines without a fragment mode (leptris today, lutaml/moxml#188)
+        # reject multiple top-level nodes; re-parse under a synthetic root
+        # and lift its children.
+        wrapped = Moxml.new.parse(
+          "<lutaml-fragment>#{fragment_string}</lutaml-fragment>",
+        )
+        add_fragment_children_to_parent(wrapped.root, parent)
       rescue LoadError
         append_raw_content(parent, fragment_string)
       end

data/lib/lutaml/xml/transformation.rb

@@ -264,6 +264,8 @@ module Lutaml
           root, model_instance, options,
           compiled_rules, model_class, register_id
         ) do |action, rule, value, set_xsi_nil|
+          next if action == :apply_rule && duplicate_element_rules[rule]
+
           rule_options = options.merge(current_model: model_instance)
           case action
           when :apply_rule
@@ -291,6 +293,32 @@ module Lutaml
       # @param root [XmlElement] Root element
       # @param model_instance [Object] The model instance
       # @param options [Hash] Options
+      # Reader for the precomputed skip set (#765).
+      def duplicate_element_rules
+        @duplicate_element_rules
+      end
+
+      # lutaml-model#765: several element rules may target one attribute
+      # (spelling tolerance, e.g. editorial-group vs editorialgroup). The
+      # extra spellings exist for parse tolerance only — serialization
+      # emits the value once, under the first declared spelling. Derived
+      # once at compile time (transformations are frozen and shared).
+      def after_compile
+        seen = {}
+        @duplicate_element_rules = {}
+        compiled_rules.each do |rule|
+          next unless rule.option(:mapping_type) == :element
+
+          key = rule.attribute_name.to_s
+          if seen.key?(key)
+            @duplicate_element_rules[rule] = true
+          else
+            seen[key] = true
+          end
+        end
+        @duplicate_element_rules.freeze
+      end
+
       def apply_standard_rules(root, model_instance, options)
         attr_order = model_instance.is_a?(Lutaml::Model::Serialize) &&
           model_instance.attribute_order
@@ -303,6 +331,7 @@ module Lutaml
 
         rules.each do |rule|
           next unless valid_mapping?(rule, options)
+          next if duplicate_element_rules[rule]
 
           rule_options = options.merge(current_model: model_instance)
           apply_rule(root, rule, model_instance, rule_options, model_class,

data/lib/lutaml/xml/xml_element.rb

@@ -299,7 +299,7 @@ module Lutaml
       end
 
       def text
-        return @text if children.empty?
+        return @text if @children.empty?
         return @computed_text if defined?(@computed_text)
 
         @computed_text = if content_bearing_children_count > 1
@@ -393,7 +393,11 @@ module Lutaml
 
         @children_index = {}
         @children.each do |child|
-          next if child.is_a?(XmlElement) && child.processing_instruction?
+          # Index element children only: the index serves by-name element
+          # lookup, and AdapterElement keeps non-element children raw
+          # (lazily wrapped) until #children is read.
+          next unless child.is_a?(XmlElement)
+          next if child.processing_instruction?
 
           key = child.namespaced_name
           @children_index[key] ||= []

data/lib/lutaml/yaml/adapter/yeptris_adapter.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+require "yeptris"
+require "yeptris/yaml"
+require_relative "standard_adapter"
+
+module Lutaml
+  module Yaml
+    module Adapter
+      # YAML over the yeptris engine (libyeptris C11). Uses the native
+      # Yeptris::YAML surface, which does not rebind or interact with the
+      # Psych constant, so it coexists with the standard adapter in one
+      # process. Inherits the document/generation contract; only the
+      # engine calls differ.
+      #
+      # Semantic notes vs the standard adapter's Psych.safe_load:
+      # implicit typing is parity-verified (compat_11 schema); anchors
+      # and aliases always resolve; a tagged value without a core type
+      # materializes as plain data instead of raising DisallowedClass.
+      class YeptrisAdapter < StandardAdapter
+        def self.parse(yaml, _options = {})
+          # rubocop:disable-next Naming/VariableNumber -- upstream schema literal
+          Yeptris::YAML.load(yaml, schema: :compat_11)
+        end
+
+        def to_yaml(_options = {})
+          attributes_to_serialize = if @attributes.is_a?(Lutaml::KeyValue::DataModel::Element)
+                                      # Unwrap __root__ wrapper to get actual content
+                                      @attributes.to_hash["__root__"]
+                                    else
+                                      # Legacy Hash input (backward compatibility)
+                                      @attributes
+                                    end
+
+          Yeptris::YAML.dump(attributes_to_serialize)
+        end
+      end
+    end
+  end
+end

data/lib/lutaml/yaml/adapter.rb

@@ -8,6 +8,11 @@ module Lutaml
       autoload :MappingRule, "#{__dir__}/adapter/mapping_rule"
       autoload :Transform, "#{__dir__}/adapter/transform"
       autoload :StandardAdapter, "#{__dir__}/adapter/standard_adapter"
+      # MRI-only native engine adapter (libyeptris FFI)
+      Lutaml::Model::RuntimeCompatibility.autoload_native(
+        self,
+        YeptrisAdapter: "#{__dir__}/adapter/yeptris_adapter",
+      )
     end
   end
 end

data/lib/lutaml/yaml/format.rb

@@ -21,7 +21,7 @@ Lutaml::Model::FormatRegistry.register(
   transformer: Lutaml::Yaml::Adapter::Transform,
   key_value: true,
   adapter_options: {
-    available: %i[standard standard_yaml],
+    available: %i[standard standard_yaml yeptris],
     default: :standard,
   },
 )

data/lib/tasks/performance.rake

@@ -63,6 +63,11 @@ namespace :performance do
     run_bench("#{BENCH_DIR}/bench_unitsml.rb")
   end
 
+  desc "XML model-pipeline performance probe (from_xml/to_xml i/s + allocs)"
+  task :probe_xml do
+    require_relative "performance_probe_xml"
+  end
+
   # --- Gate comparison ---
 
   desc "Compare downstream benchmark JSON results (gate enforcement)"

data/lib/tasks/performance_comparator.rb

@@ -12,9 +12,9 @@ class PerformanceComparator
 
   BENCHMARK_MATRIX = {
     xml: %i[nokogiri ox oga rexml],
-    json: %i[standard_json multi_json oj],
-    yaml: %i[standard_yaml],
-    toml: %i[toml_rb tomlib],
+    json: %i[standard_json multi_json oj yeptris],
+    yaml: %i[standard_yaml yeptris],
+    toml: %i[toml_rb tomlib teptris],
   }.freeze
 
   DIRECTIONS = %i[from to].freeze
@@ -107,8 +107,24 @@ class PerformanceComparator
     in [:toml, :tomlib]
       # Skip tomlib on Windows due to segmentation fault issues
       Gem.win_platform?
+    in [:yaml | :json, :yeptris]
+      # yeptris ships prebuilt platform gems for linux/darwin only
+      Gem.win_platform?
+    in [:toml, :teptris]
+      teptris_loadable?
     else
       false
     end
   end
+
+  # A teptris platform gem whose native library cannot load (the 0.2.17/
+  # 0.2.18 x86_64-linux/x64-mingw-ucrt soname gap) must skip its cell,
+  # not crash the comparator run.
+  def teptris_loadable?
+    require "teptris"
+    false
+  rescue LoadError, StandardError
+    warn "performance comparator: teptris not loadable here — skipping its cell"
+    true
+  end
 end

data/lib/tasks/performance_probe.rake

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+# One-command performance probe for the model pipeline (TODO.perf/01).
+#
+#   rake performance:probe            # steady-state i/s + allocations/op
+#   rake performance:profile          # ruby-prof flat profiles (parse + dump)
+#   rake performance:oneshot          # fresh-process boot+parse-once medians
+desc "Performance probes for the model pipeline"
+namespace :performance do
+  desc "steady-state i/s and allocations per op (nested 200-item model)"
+  task :probe do
+    system({ "BENCH_DIR" => nil }, Gem.ruby, File.expand_path("performance_probe.rb", __dir__), "probe") || raise("probe failed")
+  end
+
+  desc "ruby-prof flat profiles for from_yaml and to_yaml"
+  task :profile do
+    system(Gem.ruby, File.expand_path("performance_probe.rb", __dir__), "profile") || raise("profile failed")
+  end
+
+  desc "one-shot (fresh process) boot+define and parse-once medians"
+  task :oneshot do
+    boots = []
+    parses = []
+    5.times do
+      out = `#{Gem.ruby} #{File.expand_path("performance_probe.rb", __dir__)} oneshot`
+      boots << Regexp.last_match(1).to_f if out =~ /boot\+define: ([\d.]+)ms/
+      parses << Regexp.last_match(1).to_f if out =~ /parse-once: ([\d.]+)ms/
+    end
+    med = ->(a) { a.sort[a.length / 2] }
+    puts format("boot+define median: %<boot>.1fms   parse-once median: %<parse>.1fms",
+                boot: med.call(boots), parse: med.call(parses)) + " (#{boots.length} runs)" 
+  end
+end

data/lib/tasks/performance_probe.rb

@@ -0,0 +1,106 @@
+# frozen_string_literal: true
+
+# Model-pipeline performance probe (TODO.perf/01). Run via
+# rake performance:probe / :profile / :oneshot, or directly:
+#   ruby lib/tasks/performance_probe.rb probe|profile|oneshot
+
+MODE = ARGV[0] || "probe"
+
+# One-shot mode times the require itself; every other mode needs it up front.
+require "lutaml/model" unless MODE == "oneshot"
+
+def define_models
+  item = Class.new(Lutaml::Model::Serializable) do
+    attribute :id, :integer
+    attribute :name, :string
+    attribute :tags, :string, collection: true
+
+    key_value do
+      map "id", to: :id
+      map "name", to: :name
+      map "tags", to: :tags
+    end
+  end
+  root = Class.new(Lutaml::Model::Serializable) do
+    attribute :item, item, collection: true
+
+    key_value { map "item", to: :item }
+  end
+  [item, root]
+end
+
+def build_root(item, root, count)
+  root.new(item: (0...count).map { |i| item.new(id: i, name: "Test #{i}", tags: %w[a b c]) })
+end
+
+def ips_of(seconds = 3)
+  require "benchmark/ips"
+  lambda do |label, &blk|
+    r = Benchmark.ips(time: seconds, quiet: true) { |x| x.report(label, &blk) }
+    r.entries.max_by(&:ips).ips.round(1)
+  end
+end
+
+def allocs_of(&blk)
+  GC.start
+  before = GC.stat(:total_allocated_objects)
+  50.times(&blk)
+  (GC.stat(:total_allocated_objects) - before) / 50.0
+end
+
+case MODE
+when "probe"
+  item, root = define_models
+  model = build_root(item, root, 200)
+  yaml_doc = model.to_yaml
+  json_doc = model.to_json
+  root.from_yaml(yaml_doc)
+
+  ips = ips_of
+  puts format("%<label>s: %<ips>8.1f i/s   allocs/op: %<allocs>8.1f",
+              label: "from_yaml",
+              ips: ips.call("fy") { root.from_yaml(yaml_doc) },
+              allocs: allocs_of { root.from_yaml(yaml_doc) })
+  puts format("%<label>s: %<ips>8.1f i/s   allocs/op: %<allocs>8.1f",
+              label: "to_yaml  ",
+              ips: ips.call("ty") { model.to_yaml },
+              allocs: allocs_of { model.to_yaml })
+  puts format("%<label>s: %<ips>8.1f i/s   allocs/op: %<allocs>8.1f",
+              label: "from_json",
+              ips: ips.call("fj") { root.from_json(json_doc) },
+              allocs: allocs_of { root.from_json(json_doc) })
+  puts format("%<label>s: %<ips>8.1f i/s   allocs/op: %<allocs>8.1f",
+              label: "to_json  ",
+              ips: ips.call("tj") { model.to_json },
+              allocs: allocs_of { model.to_json })
+when "profile"
+  item, root = define_models
+  model = build_root(item, root, 200)
+  yaml_doc = model.to_yaml
+  root.from_yaml(yaml_doc)
+
+  require "ruby-prof"
+  def print_profile(profile, label)
+    puts "===== #{label} (20 iterations, self-time) ====="
+    printer = RubyProf::FlatPrinter.new(profile)
+    begin
+      printer.print($stdout, {})
+    rescue ArgumentError
+      printer.print($stdout)
+    end
+  end
+
+  print_profile(RubyProf::Profile.profile { 20.times { root.from_yaml(yaml_doc) } }, "from_yaml")
+  print_profile(RubyProf::Profile.profile { 20.times { model.to_yaml } }, "to_yaml")
+when "oneshot"
+  # Fresh-process mode: this script IS the one-shot body; the rake task
+  # re-invokes it N times and reports medians.
+  t0 = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+  require "lutaml/model"
+  item, root = define_models
+  t1 = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+  yaml_doc = build_root(item, root, 200).to_yaml
+  root.from_yaml(yaml_doc)
+  t2 = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+  puts format("boot+define: %<boot>.1fms  parse-once: %<parse>.1fms", boot: (t1 - t0) * 1000, parse: (t2 - t1) * 1000)
+end

data/lib/tasks/performance_probe_xml.rb

@@ -0,0 +1,54 @@
+# frozen_string_literal: true
+
+# XML pipeline probe (mirrors performance_probe.rb's KV shape): quantifies
+# the lutaml-model XML layer over the moxml runtime-default engine.
+#   ruby lib/tasks/performance_probe.rb xml
+
+require "lutaml/model"
+
+item = Class.new(Lutaml::Model::Serializable) do
+  attribute :id, :integer
+  attribute :name, :string
+  attribute :tags, :string, collection: true
+
+  xml do
+    element "item"
+    map_attribute "id", to: :id
+    map_element "name", to: :name
+    map_element "tag", to: :tags
+  end
+end
+root = Class.new(Lutaml::Model::Serializable) do
+  attribute :item, item, collection: true
+
+  xml do
+    element "root"
+    map_element "item", to: :item
+  end
+end
+
+model = root.new(item: (0...200).map { |i| item.new(id: i, name: "Test #{i}", tags: %w[a b c]) })
+xml_doc = model.to_xml
+root.from_xml(xml_doc)
+
+ips = lambda do |label, &blk|
+  require "benchmark/ips"
+  r = Benchmark.ips(time: 3, quiet: true) { |x| x.report(label, &blk) }
+  r.entries.max_by(&:ips).ips.round(1)
+end
+
+allocs = lambda do |&blk|
+  GC.start
+  before = GC.stat(:total_allocated_objects)
+  50.times(&blk)
+  (GC.stat(:total_allocated_objects) - before) / 50.0
+end
+
+fy = ips.call("fx") { root.from_xml(xml_doc) }
+fa = allocs.call { root.from_xml(xml_doc) }
+ty = ips.call("tx") { model.to_xml }
+ta = allocs.call { model.to_xml }
+
+puts format("from_xml: %<ips>8.1f i/s   allocs/op: %<allocs>8.1f", ips: fy, allocs: fa)
+puts format("to_xml  : %<ips>8.1f i/s   allocs/op: %<allocs>8.1f", ips: ty, allocs: ta)
+puts "engine: #{Moxml::VERSION} / #{Leptris::VERSION}"

data/lutaml-model.gemspec

@@ -38,7 +38,7 @@ Gem::Specification.new do |spec|
   spec.add_dependency "canon"
   spec.add_dependency "concurrent-ruby"
   spec.add_dependency "liquid", ">= 4.0", "< 6.0"
-  spec.add_dependency "moxml", "~> 0.5.0"
+  spec.add_dependency "moxml", "~> 0.5.34"
   spec.add_dependency "ostruct"
   spec.add_dependency "rubyzip", "~> 2.3"
   spec.add_dependency "thor"