lutaml-model 0.8.36 → 0.8.38

data/lib/lutaml/xml/model_transform.rb

@@ -12,6 +12,25 @@ module Lutaml
     # - Used by model's serialization pipeline via Transform.for(:xml)
     #
     class ModelTransform < ::Lutaml::Model::Transform
+      require "cgi" unless Lutaml::Model.opal?
+
+      # Per (model class, register): compiled records for the mapping
+      # rules — attribute, derived/valid flags, and #765 group-skip —
+      # keyed on the mapping's finalize version so late changes rebuild.
+      # The loop body used to re-derive these per parsed instance.
+      # Concurrent::Map has no compare_by_identity; class identity is
+      # the key semantic here.
+      RULE_RECORDS = Concurrent::Map.new # rubocop:disable Lint/HashCompareByIdentity
+
+      # Namespaced rule name -> [local_name, rule_uri]. Pure string
+      # splitting, deterministic per spelling, shared across parses.
+      # Concurrent::Map under threaded MRI, plain Hash under Opal.
+      NAMESPACED_NAME_PARTS = if Lutaml::Model.opal?
+                                {}
+                              else
+                                Lutaml::Model::RuntimeCompatibility.require_native("concurrent")
+                                Concurrent::Map.new
+                              end
       include NestedCollectionAttribute
 
       # Performance: Frozen empty hash to reduce allocations
@@ -27,7 +46,19 @@ module Lutaml
 
         instance_is_serialize = model_class.include?(::Lutaml::Model::Serialize)
         if instance_is_serialize
+          # TODO.max-perf/17: the same child element was being re-hydrated
+          # per matching rule (593k instantiations for 12k elements on the
+          # ISO-13849 profile). Memoize one instance per (element, class)
+          # for the whole parse; the memo travels in the propagated
+          # deserialization options.
+          memo = options[:__lutaml_child_memo] ||= {}
+          memo_key = [data.object_id, model_class.object_id]
+          if (existing = memo[memo_key])
+            return existing
+          end
+
           instance = model_class.allocate_for_deserialization(child_register)
+          memo[memo_key] = instance
         else
           instance = model_class.new
           register_accessor_methods_for(instance, child_register)
@@ -272,24 +303,33 @@ module Lutaml
           effective_register,
         )
 
+        serializable = instance.class.include?(Lutaml::Model::Serialize)
+        records = if serializable
+                    compiled_rule_records(instance.class, effective_register,
+                                          grouped_plain_rules)
+                  end
         mappings.each do |rule|
-          # Performance: Cache rule properties accessed multiple times
-          rule.name
+          record = records&.[](rule)
           rule_to = rule.to
-          rule_namespace_set = rule.namespace_set?
-          rule_namespace_set ? rule.namespace_param : nil
 
-          attr = attribute_for_rule(rule)
-          next if attr&.derived?
+          if record
+            attr = record.attr
+            next if record.derived
+            next if record.group_skip
 
-          if (group = grouped_plain_rules[rule_to]) &&
-              group.size > 1 && attr&.collection? && !group.first.equal?(rule)
-            next
-          end
+            raise "Attribute '#{rule_to}' not found in #{context}" unless record.valid
+          else
+            attr = attribute_for_rule(rule)
+            next if attr&.derived?
 
-          raise "Attribute '#{rule_to}' not found in #{context}" unless valid_rule?(
-            rule, attr
-          )
+            group = grouped_plain_rules[rule_to]
+            next if group && group.size > 1 && attr&.collection? &&
+              !group.first.equal?(rule)
+
+            raise "Attribute '#{rule_to}' not found in #{context}" unless valid_rule?(
+              rule, attr
+            )
+          end
 
           # Performance: Use pre-computed frozen Hash for static namespace overrides.
           # Falls back to per-element hash only for the dynamic namespace_uri case.
@@ -362,6 +402,9 @@ module Lutaml
           value = apply_value_map(value, from_map, attr)
           value = normalize_xml_value(value, rule, attr, new_opts,
                                       effective_register)
+          value = decode_html_entities_value(value, decode_html_entities_for(
+                                                      instance, effective_register
+                                                    ))
           value = rule.transform_value(attr, value, :from, :xml)
           # An over-count is normally left for `.validate` to report. A mapped
           # PORO has no `.validate`, so deferring there would discard the
@@ -370,7 +413,8 @@ module Lutaml
               !rule.content_mapping?
             attr.valid_collection!(value, context)
           end
-          rule.deserialize(instance, value, attributes, context)
+          rule.deserialize(instance, value, attributes, context,
+                           options[:context])
 
           instance.value_set_for(rule_to)
         end
@@ -487,16 +531,11 @@ _effective_register)
         mapping = klass.mappings_for(:xml, effective_register)
         return true unless mapping
 
-        expected = Array(rule.name).map(&:to_s)
-        mapping.mappings.none? do |sib|
-          next false unless sib.attribute? && !sib.equal?(rule)
-
-          Array(sib.name).map(&:to_s) == expected
-        end
+        mapping.sole_local_attribute_claimant?(rule, effective_register)
       end
 
       def value_for_xml_attribute(doc, rule, rule_names,
-                                  flexible_local: false)
+                                  flexible_local: false, session: nil)
         # For attributes, rule_names may contain namespaced names, but find_attribute_value
         # expects prefix:name or just name, so we need to convert namespaced names to prefix format.
         #
@@ -508,11 +547,13 @@ _effective_register)
         # its result array entirely on that path.
         if rule_names.size == 1
           rn = rule_names[0]
-          converted = convert_rule_name_to_attribute_name(doc, rn)
+          converted = convert_rule_name_to_attribute_name(doc, rn,
+                                                          session: session)
           value = doc.root.find_attribute_value(converted || rn)
         else
           attribute_names = rule_names.map do |rn|
-            converted = convert_rule_name_to_attribute_name(doc, rn)
+            converted = convert_rule_name_to_attribute_name(doc, rn,
+                                                            session: session)
             converted || rn
           end
 
@@ -524,7 +565,8 @@ _effective_register)
         # (e.g., v:ext without xmlns:v="...").
         if value.nil? && rule_names.any? { |rn| rn.include?(":") }
           value = find_attribute_by_local_name(doc, rule_names,
-                                               flexible_local: flexible_local)
+                                               flexible_local: flexible_local,
+                                               session: session)
         end
 
         value = value&.split(rule.delimiter) if rule.delimiter
@@ -540,7 +582,7 @@ _effective_register)
       # @param doc [XmlElement] the parsed XML document root
       # @param rule_name [String] the rule name (e.g., "urn:...:ext", "http://.../ns:val", "my-ns:val")
       # @return [String, nil] the attribute name to look up, or nil if no conversion needed
-      def convert_rule_name_to_attribute_name(doc, rule_name)
+      def convert_rule_name_to_attribute_name(doc, rule_name, session: nil)
         return nil unless rule_name.include?(":")
 
         # URI-vs-prefix detection works on the whole rule name: the
@@ -559,13 +601,27 @@ _effective_register)
           # match, and unprefixed_name is not called per attribute
           # (it splits prefixed names and allocates).
           local_name = rule_name[(last_colon_index + 1)..]
-          doc.root.attributes.each_value.find do |attr|
-            ns = attr.namespace
-            next false if ns.nil? || ns.length > last_colon_index
-            next false unless rule_name.start_with?(ns) && rule_name[ns.length] == ":"
+          if session
+            candidates = session.element_local_attribute_index(doc.root)[local_name]
+            # No candidate carries this local name: nothing in the
+            # element can match, the scan is skipped entirely.
+            matched = candidates&.find do |attr|
+              ns = attr.namespace
+              next false if ns.nil? || ns.length > last_colon_index
+              next false unless rule_name.start_with?(ns) && rule_name[ns.length] == ":"
+
+              attr.unprefixed_name == local_name
+            end
+          else
+            matched = doc.root.attributes.each_value.find do |attr|
+              ns = attr.namespace
+              next false if ns.nil? || ns.length > last_colon_index
+              next false unless rule_name.start_with?(ns) && rule_name[ns.length] == ":"
 
-            attr.unprefixed_name == local_name
-          end&.name
+              attr.unprefixed_name == local_name
+            end
+          end
+          matched&.name
         else
           # Simple prefix format: look up the actual prefix from document's namespace declarations
           # The namespace_part is the namespace URI declared in the document (e.g., "my-ns").
@@ -588,49 +644,127 @@ _effective_register)
       # @param rule_names [Array<String>] the rule names to match
       # @return [String, nil] the attribute value or nil
       def find_attribute_by_local_name(doc, rule_names,
-                                       flexible_local: false)
-        rule_names.each do |rn|
-          next unless rn.include?(":")
-
-          last_colon_index = rn.rindex(":")
-          local_name = rn[(last_colon_index + 1)..]
-          rule_uri = rn[0...last_colon_index]
-
-          matched_attr = doc.root.attributes.each_value.find do |attr|
-            # Local-name fallback serves two lenient cases only:
-            # - an attribute with an undeclared prefix (raw name keeps the
-            #   colon, namespace unresolvable), the historical purpose;
-            # - an attribute whose resolved namespace IS one of the rule's
-            #   namespace URIs (prefix rebinding, lutaml-model#744).
-            # Everything else — including a definitively namespace-less
-            # attribute and an attribute from a foreign namespace — must
-            # not satisfy the fallback, or a plain rule steals a
-            # namespaced sibling attribute (lutaml-model#758). An
-            # XmlAttribute with a resolved namespace has namespaced_name
-            # "URI:local", so this comparison is allocation-free.
-            if flexible_local
-              # Sole claimant: any qualification of the local name binds
-              # (element namespace, foreign extension namespace, none).
-              attr.unprefixed_name == local_name ||
-                ((colon = attr.name.rindex(":")) ? attr.name[(colon + 1)..] : attr.name) == local_name
-            elsif attr.namespace.nil?
-              next false if attr.namespace_prefix.nil? &&
-                !attr.name.include?(":")
-
-              attr.unprefixed_name == local_name ||
-                ((colon = attr.name.rindex(":")) ? attr.name[(colon + 1)..] : attr.name) == local_name
-            else
-              # Prefixed attributes carry namespaced_name "prefix:local",
-              # which a URI-form rule name can never equal — match by the
-              # attribute's resolved namespace instead.
-              attr.namespace == rule_uri && attr.unprefixed_name == local_name
-            end
-          end
-          return matched_attr&.value if matched_attr
+                                       flexible_local: false, session: nil)
+        root_index = session&.element_local_attribute_index(doc.root)
+
+        rule_names.each do |rule_name|
+          next unless rule_name.include?(":")
+
+          resolved = match_attribute_by_local_name(
+            doc, rule_name, root_index, flexible_local
+          )
+          return resolved if resolved
+        end
+        nil
+      end
+
+      def match_attribute_by_local_name(doc, rule_name, root_index, flexible_local)
+        # Splitting a namespaced rule name is pure string work repeated
+        # per element; memoized per spelling (bounded by the model's
+        # distinct rule names).
+        parts = NAMESPACED_NAME_PARTS[rule_name]
+        unless parts
+          last_colon_index = rule_name.rindex(":")
+          parts = [rule_name[(last_colon_index + 1)..], rule_name[0...last_colon_index]]
+          NAMESPACED_NAME_PARTS[rule_name] = parts
         end
+        local_name, rule_uri = parts
+
+        candidates = root_index&.[](local_name)
+        matched_attr = if candidates
+                         candidates.find do |attr|
+                           local_name_match?(attr, local_name, rule_uri,
+                                             flexible_local)
+                         end
+                       else
+                         doc.root.attributes.each_value.find do |attr|
+                           local_name_match?(attr, local_name, rule_uri,
+                                             flexible_local)
+                         end
+                       end
+        matched_attr&.value
+      end
+
+      # Namespace discipline of the lenient local-name fallback
+      # (#744/#758/#790): sole claimants bind any qualification; shared
+      # names must resolve to the rule's namespace.
+      def local_name_match?(attr, local_name, rule_uri, flexible_local)
+        if flexible_local
+          attr.unprefixed_name == local_name ||
+            attr_name_local(attr) == local_name
+        elsif attr.namespace.nil?
+          return false if attr.namespace_prefix.nil? && !attr.name.include?(":")
+
+          attr.unprefixed_name == local_name ||
+            attr_name_local(attr) == local_name
+        else
+          attr.namespace == rule_uri && attr.unprefixed_name == local_name
+        end
+      end
+
+      def attr_name_local(attr)
+        (colon = attr.name.rindex(":")) ? attr.name[(colon + 1)..] : attr.name
+      end
+
+      # lutaml-model#154: decode HTML entities for mappings that opted in
+      # (`html_entities` in the xml block). Values stay untouched
+      # otherwise — XML keeps undefined entities literal by design.
+      def decode_html_entities_value(value, enabled)
+        return value if value.nil? || !value.is_a?(String)
+        return value unless enabled
+        return value if Lutaml::Model.opal?
+
+        Lutaml::Xml::HtmlEntities.decode(value)
+      end
+
+      Record = Struct.new(:attr, :derived, :group_skip, :valid)
+
+      def compiled_rule_records(model_class, register, grouped_plain_rules)
+        return {}.compare_by_identity unless model_class.include?(Lutaml::Model::Serialize)
+
+        mapping = model_class.mappings_for(:xml, register)
+        version = mapping&.rule_records_version.to_i
+        per_class = RULE_RECORDS[model_class.object_id] || # rubocop:disable Lint/HashCompareByIdentity
+          (RULE_RECORDS[model_class.object_id] = Concurrent::Map.new) # rubocop:disable Lint/HashCompareByIdentity,Layout/MultilineAssignmentLayout
+        cached = per_class[register]
+        return cached.records if cached && cached.version == version
+
+        records = {}.compare_by_identity
+        mapping&.mappings(register)&.each do |rule| # rubocop:disable Style/SafeNavigationChain,Style/SafeNavigation
+          attr = attribute_for_rule_static(model_class, rule, register)
+          group = grouped_plain_rules[rule.to]
+          records[rule] = Record.new(
+            attr,
+            attr&.derived? || false,
+            !!(group && group.size > 1 && attr&.collection? &&
+               !group.first.equal?(rule)),
+            !!(attr || rule.custom_methods[:from]),
+          )
+        end
+        entry = Struct.new(:version, :records).new(version, records)
+        per_class[register] = entry
+        records
+      end
+
+      def attribute_for_rule_static(model_class, rule, register)
+        if rule.delegate
+          delegate_attr = model_class.attributes(register)[rule.delegate]
+          delegate_type = delegate_attr&.type(register)
+          delegate_type&.attributes(register)&.[](rule.to) # rubocop:disable Style/SafeNavigationChain
+        else
+          model_class.attributes(register)[rule.to]
+        end
+      rescue StandardError
         nil
       end
 
+      def decode_html_entities_for(instance, register)
+        klass = instance.class
+        return false unless klass.is_a?(Class) && klass.include?(Lutaml::Model::Serialize)
+
+        klass.mappings_for(:xml, register)&.decode_html_entities?
+      end
+
       def value_for_rule(session, rule, options, cached_attr = nil,
                          extra_rule_names = nil)
         doc = session.doc
@@ -665,12 +799,16 @@ _effective_register)
         rule_names = rule_names.concat(extra_rule_names).uniq if extra_rule_names
 
         if rule.attribute?
-          return value_for_xml_attribute(
+          value = value_for_xml_attribute(
             doc, rule, rule_names,
             flexible_local: attribute_rule_sole_local_claimant?(
               instance, rule, effective_register
-            )
+            ),
+            session: session
           )
+          return decode_html_entities_value(value, decode_html_entities_for(
+                                                     instance, effective_register
+                                                   ))
         end
 
         # Performance: Pre-compute type-related values used in the hot loop

data/lib/lutaml/xml/parse_session.rb

@@ -24,6 +24,38 @@ module Lutaml
         @instance_is_serialize ||= instance.is_a?(::Lutaml::Model::Serialize)
       end
 
+      # (element, rule name) -> resolved attribute name / matched
+      # attribute VALUE for the lenient lookup paths. Both are pure
+      # functions of the element and the name; ISO-13849-shaped
+      # documents repeat the same resolutions per rule application, so
+      # the computed answer is memoized per element for the parse.
+      def rule_name_resolution
+        @rule_name_resolution ||= {}
+      end
+
+      # Local-name -> [attributes] index over one element's attributes,
+      # built on first lenient lookup (TODO.max-perf/08) and memoized per
+      # element for the life of the session. The URI-form attribute
+      # conversion and the lenient fallback used to rescan every
+      # attribute per rule per element (the ISO-13849 pathology);
+      # elements are parse-frozen, so each index builds at most once.
+      def element_local_attribute_index(element)
+        @element_local_attribute_index ||= {}.compare_by_identity
+        @element_local_attribute_index[element] ||= begin
+          # Plain hash: a miss must stay a nil lookup, not allocate an
+          # empty default array — misses dominate (the ISO-13849 shape
+          # resolves ~390k lenient lookups that match nothing).
+          index = {}
+          element.attributes.each_value do |attr|
+            local_names(attr).each do |key|
+              entries = (index[key] ||= [])
+              entries << attr unless entries.include?(attr)
+            end
+          end
+          index
+        end
+      end
+
       def model_class
         @model_class ||= instance.class
       end
@@ -57,3 +89,9 @@ module Lutaml
     end
   end
 end
+
+def local_names(attr)
+  colon = attr.name.rindex(":")
+  split_local = colon ? attr.name[(colon + 1)..] : attr.name
+  [attr.unprefixed_name, split_local].compact.uniq
+end

data/lib/lutaml/yaml/format.rb

@@ -24,6 +24,7 @@ Lutaml::Model::FormatRegistry.register(
     available: %i[standard standard_yaml yeptris],
     default: :standard,
   },
+  stream_methods: true,
 )
 
 require_relative "type/serializers"

data/spec/lutaml/model/adapter_resolver_configured_spec.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+require "spec_helper"
+
+RSpec.describe Lutaml::Model::AdapterResolver, ".adapter_for with a configured type" do
+  after do
+    Lutaml::Model::Config.configure do |config|
+      config.xml_adapter_type = :nokogiri
+      config.yaml_adapter_type = :standard
+      config.json_adapter_type = :standard
+    end
+  end
+
+  it "resolves the configured adapter without running auto-detection" do
+    Lutaml::Model::Config.configure do |config|
+      config.json_adapter_type = :standard
+    end
+
+    adapter = described_class.adapter_for(:json)
+
+    expect(described_class.configured_type(:json)).to eq(:standard)
+    expect(adapter.name).to include("Json::Standard")
+  end
+
+  it "does not load the optional yeptris engine when a standard adapter is configured" do
+    skip "yeptris already loaded by an earlier spec" if Object.const_defined?(:Yeptris)
+
+    Lutaml::Model::Config.configure do |config|
+      config.yaml_adapter_type = :standard
+      config.json_adapter_type = :standard
+    end
+
+    described_class.adapter_for(:yaml)
+    described_class.adapter_for(:json)
+
+    expect(Object.const_defined?(:Yeptris)).to be(false)
+  end
+end

data/spec/lutaml/model/custom_method_context_spec.rb

@@ -0,0 +1,62 @@
+# frozen_string_literal: true
+
+require "spec_helper"
+
+# lutaml-model#550: options passed to `from_*` / `to_*` flow to custom
+# methods that declare the extra context parameter (arity-aware; the
+# historical signatures keep working).
+RSpec.describe "Custom method context forwarding" do
+  let(:model_class) do
+    Class.new(Lutaml::Model::Serializable) do
+      attribute :name, :string
+
+      def name_from(model, value, ctx = nil)
+        model.name = "#{value} (#{ctx ? ctx[:schema] : 'none'})"
+      end
+
+      def name_to(model, hash, ctx = nil)
+        hash["name"] = "#{model.name} <#{ctx ? ctx[:schema] : 'none'}>"
+      end
+
+      key_value do
+        map "name", to: :name,
+                    with: { from: :name_from, to: :name_to }
+      end
+    end
+  end
+
+  it "passes context to custom methods on parse when accepted" do
+    parsed = model_class.from_yaml({ "name" => "Alpine" }.to_yaml,
+                                   context: { schema: "ISO" })
+    expect(parsed.name).to eq("Alpine (ISO)")
+  end
+
+  it "passes context to custom methods on serialize when accepted" do
+    instance = model_class.from_yaml({ "name" => "Alpine" }.to_yaml)
+    out = instance.to_yaml(context: { schema: "ISO" })
+    expect(out).to include("Alpine (none) <ISO>")
+  end
+
+  it "keeps two-parameter custom methods working without context" do
+    parsed = model_class.from_yaml({ "name" => "Alpine" }.to_yaml)
+    expect(parsed.name).to eq("Alpine (none)")
+
+    out = parsed.to_yaml
+    expect(out).to include("Alpine (none) <none>")
+  end
+
+  it "forwards context to with-lambdas of exact arity 2" do
+    klass = Class.new(Lutaml::Model::Serializable) do
+      attribute :code, :string
+
+      key_value do
+        map "code", to: :code,
+                    with: { from: ->(value, ctx) { "#{value}-#{ctx[:rev]}" } }
+      end
+    end
+
+    parsed = klass.from_yaml({ "code" => "A1" }.to_yaml,
+                              context: { rev: 7 })
+    expect(parsed.code).to eq("A1-7")
+  end
+end

data/spec/lutaml/model/liquefiable_lazy_spec.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+require "spec_helper"
+
+# lutaml-model#800: `liquid do ... end` blocks survive a boot order in
+# which Liquid is required after lutaml-model; the drop class
+# materializes on first use instead of requiring Liquid at definition.
+RSpec.describe "Liquefiable lazy registration" do
+  it "materializes the drop class on first to_liquid" do
+    klass = Class.new(Lutaml::Model::Serializable) do
+      attribute :name, :string
+
+      liquid do
+        map "full_name", to: :name
+      end
+    end
+
+    # Mapping stored at definition; drop registration is lazy
+    expect(klass.liquid_mappings.mappings).not_to be_empty
+
+    drop = klass.new(name: "Apollo").to_liquid
+    expect(drop).to be_a(Liquid::Drop)
+    expect(drop.full_name).to eq("Apollo")
+  end
+
+  it "keeps ensure_liquid_registered! idempotent" do
+    klass = Class.new(Lutaml::Model::Serializable) do
+      attribute :name, :string
+    end
+
+    klass.ensure_liquid_registered!
+    first = klass.base_drop_class
+    klass.ensure_liquid_registered!
+    expect(klass.base_drop_class).to equal(first)
+  end
+end

data/spec/lutaml/model/mapping_type_validation_spec.rb

@@ -0,0 +1,61 @@
+# frozen_string_literal: true
+
+require "spec_helper"
+
+# lutaml-model#296: a mapped rule whose attribute type can never accept
+# the serialization shape fails at mapping definition, naming the
+# attribute and the type, instead of surfacing mid-parse.
+RSpec.describe "Mapping-time attribute type validation" do
+  it "raises InvalidAttributeTypeError at definition for a non-castable type" do
+    expect do
+      Class.new(Lutaml::Model::Serializable) do
+        attribute :ends, Object
+
+        xml do
+          element "doc"
+          map_element "ends", to: :ends
+        end
+      end
+    end.to raise_error(Lutaml::Model::InvalidAttributeTypeError) do |err|
+      expect(err.message).to include("attribute `ends`")
+      expect(err.message).to include("Object")
+    end
+  end
+
+  it "accepts Value, Serializable, and collection types" do
+    item = Class.new(Lutaml::Model::Serializable) do
+      attribute :name, :string
+      xml do 
+        element "item"
+        map_element "name", to: :name
+      end
+    end
+
+    expect do
+      Class.new(Lutaml::Model::Serializable) do
+        attribute :count, :integer
+        attribute :name, :string
+        attribute :items, item, collection: true
+
+        xml do
+          element "doc"
+          map_element "count", to: :count
+          map_element "items", to: :items
+        end
+      end
+    end.not_to raise_error
+  end
+
+  it "leaves undeclared (deferred) types to import resolution" do
+    expect do
+      Class.new(Lutaml::Model::Serializable) do
+        attribute :later, :missing_type_name
+
+        xml do
+          element "doc"
+          map_element "later", to: :later
+        end
+      end
+    end.not_to raise_error
+  end
+end