lutaml-model 0.8.56 → 0.8.106

data/lib/lutaml/model/render_policy.rb

@@ -12,6 +12,14 @@ module Lutaml
     # options are normalized into value_map entries at MappingRule construction
     # time, so downstream code never needs to re-interpret them.
     module RenderPolicy
+      # Isolated holder: host transformations freeze after compile; an
+      # ivar cache on them raises FrozenError (learned the hard way).
+      SKIP_PLANS = ::Class.new do
+        def self.cache
+          @cache ||= {}.compare_by_identity
+        end
+      end.cache
+
       def self.derived_attribute_for?(context_obj, attr_name)
         return false unless context_obj.is_a?(Lutaml::Model::Serialize) &&
           context_obj.class.is_a?(Class) &&
@@ -52,16 +60,26 @@ module Lutaml
       # @param context_obj [Object] The context object (model_instance or delegate_obj)
       # @return [Boolean] true if should skip
       def check_skip_logic?(value, rule, context_obj)
-        attr_name = extract_attribute_name(rule)
-
-        to_map = to_value_map(rule)
-
-        case value
-        when nil
+        # Rule-constant parts (attribute name, :to value map) are frozen
+        # per rule; recomputing them per value showed in the to_yaml
+        # wall profile. The host transformation freezes itself after
+        # compile, so the cache lives in an isolated holder (TypeProbeCache
+        # precedent): host object -> identity-keyed rule plans.
+        per_host = (SKIP_PLANS[self] ||= {}.compare_by_identity)
+        skip_plan = (per_host[rule] ||= [extract_attribute_name(rule), to_value_map(rule)])
+        attr_name, to_map = skip_plan
+
+        # Plain conditionals, not `when ->(v)` literals: each lambda
+        # literal in a case/when allocates on every call — two per
+        # value here, 16% of to_yaml's allocations in the object-mode
+        # profile.
+        if value.nil?
           return to_map[:nil] == :omitted
-        when ->(v) { Lutaml::Model::Utils.empty?(v) }
+        end
+        if Lutaml::Model::Utils.empty?(value)
           return to_map[:empty] == :omitted
-        when ->(v) { Lutaml::Model::Utils.uninitialized?(v) }
+        end
+        if Lutaml::Model::Utils.uninitialized?(value)
           return to_map[:omitted] == :omitted || to_map[:omitted].nil?
         end
 

data/lib/lutaml/model/schema/base_schema.rb

@@ -16,6 +16,21 @@ module Lutaml
 
             format_schema(schema, options)
           end
+
+          # Generate one schema document covering several model classes.
+          # The roots share a single $defs map and no top-level $ref is
+          # emitted; each root stays addressable under $defs by its class
+          # name. Use generate for a single root with a top-level $ref.
+          def generate_many(klasses, options = {})
+            schema = {
+              "$schema" => options[:schema],
+              "$id" => options[:id],
+              "description" => options[:description],
+              "$defs" => Generator::DefinitionsCollection.from_classes(klasses).to_schema,
+            }.compact
+
+            format_schema(schema, options)
+          end
         end
 
         attr_reader :schema, :klass

data/lib/lutaml/model/schema/generator/definition.rb

@@ -23,9 +23,23 @@ module Lutaml
               },
             }
 
-            # Add choice validation if present
+            # Choice validation follows the serializer's contract: unset
+            # or empty members are omitted from output, and instances that
+            # leave a whole group empty are accepted (#869). Members are
+            # therefore never `required`; a max:1 group contributes an
+            # at-most-one constraint over its members, and independent
+            # groups combine conjunctively under allOf. Groups whose range
+            # admits several members impose no serialization constraint.
             if type.choice_attributes.any?
-              @schema[name]["oneOf"] = generate_choice_attributes(type)
+              groups = type.choice_attributes
+                .select { |choice| choice.max == 1 }
+                .map { |choice| { "oneOf" => exclusive_branches(choice) } }
+
+              if groups.one?
+                @schema[name].merge!(groups.first)
+              elsif groups.any?
+                @schema[name]["allOf"] = groups
+              end
             end
 
             @schema
@@ -33,15 +47,45 @@ module Lutaml
 
           private
 
-          def generate_choice_attributes(type)
-            type.choice_attributes.map do |choice|
+          # Leaves of the group (nested choices collapse into it), as
+          # [name, attribute] pairs.
+          def choice_leaves(choice)
+            choice.attributes.flat_map do |member|
+              if member.is_a?(Lutaml::Model::Choice)
+                choice_leaves(member)
+              else
+                [[member.name.to_s, member]]
+              end
+            end
+          end
+
+          # Exactly-one-present construction over the leaves: no leaf, or
+          # exactly one leaf present without the others. Accepts the
+          # all-empty document the serializer emits; rejects documents
+          # with two members of the group at once (max:1).
+          def exclusive_branches(choice)
+            leaves = choice_leaves(choice)
+            names = leaves.map(&:first)
+            none = {
+              "not" => {
+                "anyOf" => names.map { |n| { "required" => [n] } },
+              },
+            }
+            singles = leaves.map do |name, attribute|
+              others = names - [name]
               {
-                "type" => "object",
-                "properties" => PropertiesCollection.from_attributes(
-                  choice.attributes, extract_register_from(type)
-                ).to_schema,
+                "allOf" => (
+                  [{
+                    "type" => "object",
+                    "properties" => PropertiesCollection.from_attributes(
+                      [attribute], extract_register_from(type)
+                    ).to_schema,
+                    "required" => [name],
+                  }] + others.map { |o| { "not" => { "required" => [o] } } }
+                ),
               }
             end
+            [none] + singles
           end
 
           def properties_to_schema(type)

data/lib/lutaml/model/schema/generator/definitions_collection.rb

@@ -9,20 +9,28 @@ module Lutaml
             include SharedMethods
 
             def from_class(klass)
-              new.tap do |collection|
-                collection << Definition.new(klass)
+              collection = new
+              register_definition(collection, klass)
+              collection
+            end
 
-                process_attributes(collection, klass)
-              end
+            # Build one collection covering several roots. The seen-set
+            # is shared across roots so a class referenced by more than
+            # one of them registers once.
+            def from_classes(klasses)
+              collection = new
+              seen = {}
+              klasses.each { |klass| register_definition(collection, klass, seen) }
+              collection
             end
 
-            def process_attributes(collection, klass)
+            def process_attributes(collection, klass, seen = {})
               register = extract_register_from(klass)
               klass.attributes.each_value do |attribute|
                 if attribute.union?
-                  process_union_members(collection, attribute)
+                  process_union_members(collection, attribute, seen)
                 elsif attribute.serializable?(register)
-                  process_attribute(collection, attribute, register)
+                  process_attribute(collection, attribute, register, seen)
                 end
               end
             end
@@ -30,31 +38,44 @@ module Lutaml
             # A union attribute's type is Type::Union, not a model, so collect
             # definitions for each of its Serializable members directly (a
             # union schema emits a $ref per model member).
-            def process_union_members(collection, attribute)
+            def process_union_members(collection, attribute, seen = {})
               attribute.union_member_types.each do |member|
                 next unless member.is_a?(::Class) &&
                   member.include?(Lutaml::Model::Serialize)
 
-                collection.merge(DefinitionsCollection.from_class(member))
+                register_definition(collection, member, seen)
               end
             end
 
-            def process_attribute(collection, attribute, register)
+            def process_attribute(collection, attribute, register, seen = {})
               attr_type = Lutaml::Model::GlobalContext.resolve_type(
                 attribute.type, register
               )
-              collection.merge(DefinitionsCollection.from_class(attr_type))
+              register_definition(collection, attr_type, seen)
 
-              process_polymorphic_types(collection, attribute)
+              process_polymorphic_types(collection, attribute, seen)
             end
 
-            def process_polymorphic_types(collection, attribute)
+            def process_polymorphic_types(collection, attribute, seen = {})
               return unless attribute.options&.[](:polymorphic)
 
               attribute.options[:polymorphic].each do |child|
-                collection.merge(DefinitionsCollection.from_class(child))
+                register_definition(collection, child, seen)
               end
             end
+
+            # Recursive models (Node#child → Node, or longer include
+            # cycles) are valid; the seen-set registers each class once
+            # and lets property references point at the shared $defs
+            # entry instead of recursing (#863).
+            def register_definition(collection, klass, seen = {})
+              return collection if seen[klass]
+
+              seen[klass] = true
+              collection << Definition.new(klass)
+              process_attributes(collection, klass, seen)
+              collection
+            end
           end
 
           attr_reader :definitions

data/lib/lutaml/model/schema.rb

@@ -52,11 +52,13 @@ module Lutaml
       end
 
       def self.to_json(klass, options = {})
-        JsonSchema.generate(klass, options)
+        # The generator signatures are keyword-only; splat so callers may
+        # pass an options hash positionally (#866).
+        JsonSchema.generate(klass, **options)
       end
 
       def self.to_yaml(klass, options = {})
-        YamlSchema.generate(klass, options)
+        YamlSchema.generate(klass, **options)
       end
 
       # XML-specific methods (to_xsd, to_relaxng, from_xml) are registered

data/lib/lutaml/model/serializable.rb

@@ -8,6 +8,39 @@ module Lutaml
       # model classes actually inherit from (lutaml-model#18).
       include Serialize
       extend ComparableModel::ClassMethods
+
+      # Ivars that must never take part in inspect output: they either
+      # walk the whole graph (@lutaml_parent climbs to the root, and
+      # parent-child mutual recursion never terminates under the
+      # default Object#inspect) or are bulky parse bookkeeping.
+      INSPECT_EXCLUDED_IVARS = %i[
+        @lutaml_parent @lutaml_root @lutaml_register @using_default
+        @element_order @attribute_order @encoding
+      ].freeze
+
+      # Bounded, Struct-like inspect: scalars by value, collections by
+      # size, child models by class name. The default Object#inspect
+      # recurses through @lutaml_parent and re-enters children forever
+      # on real parsed documents.
+      def inspect
+        parts = (instance_variables - INSPECT_EXCLUDED_IVARS).map do |iv|
+          "#{iv}=#{self.class.inspect_value(instance_variable_get(iv))}"
+        end
+        attrs = " #{parts.join(', ')}" unless parts.empty?
+        "#<#{self.class.name}#{attrs}>"
+      end
+
+      class << self
+        def inspect_value(value)
+          case value
+          when nil, true, false, Numeric, Symbol then value.inspect
+          when String then value.inspect.length > 48 ? "#{value.inspect[0, 45]}...".inspect : value.inspect
+          when Array then "(#{value.size} items)"
+          when Hash then "{#{value.size} keys}"
+          else "##{value.class.name}"
+          end
+        end
+      end
     end
   end
 end

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

@@ -8,6 +8,24 @@ module Lutaml
       # Extracted from serialize.rb to improve code organization.
       # Provides methods for defining and validating model attributes.
       module AttributeDefinition
+        # Whether the per-class accessors and the state-defaults seed are
+        # compiled from Ruby source with a String class_eval (the fast
+        # path). Opal has no runtime compiler unless opal-parser is
+        # bundled, so there every such method is defined from a block
+        # with define_method instead.
+        # Core dispatch for the block-form methods, bound per call so an
+        # attribute or method a model defines with one of these names
+        # (send, __send__, instance_variable_get, const_get, ...) is never invoked;
+        # the compiled form reads ivars and calls methods directly.
+        IVAR_GET = ::Kernel.instance_method(:instance_variable_get)
+        IVAR_SET = ::Kernel.instance_method(:instance_variable_set)
+        SEND = ::BasicObject.instance_method(:__send__)
+        CONST_GET = ::Module.instance_method(:const_get)
+
+        def self.source_compilation?
+          !Lutaml::Model.opal?
+        end
+
         # Define attribute methods on the model class
         #
         # @param attr [Attribute] The attribute to define methods for
@@ -44,6 +62,26 @@ module Lutaml
             return
           end
 
+          unless AttributeDefinition.source_compilation?
+            seeds = attrs.map do |name, attr|
+              sentinel = if attr.collection?
+                           Lutaml::Model::Serialize::LAZY_EMPTY_COLLECTION
+                         else
+                           Lutaml::Model::UninitializedClass.instance
+                         end
+              [:"@#{name}", sentinel]
+            end
+            # Raw readers for every attribute the register sees, as the
+            # compiled form below does (#933).
+            attrs.each_key { |name| define_raw_state_reader(name) }
+            define_method(method_name) do
+              # Returns the last seeded value, as the compiled form's final
+              # assignment does.
+              seeds.reduce(nil) { |_, (ivar, sentinel)| IVAR_SET.bind_call(self, ivar, sentinel) }
+            end
+            return
+          end
+
           lines = attrs.map do |name, attr|
             if attr.collection?
               "@#{name} = Lutaml::Model::Serialize::LAZY_EMPTY_COLLECTION"
@@ -62,6 +100,32 @@ module Lutaml
             #{lines}
             end
           RUBY
+
+          # Raw readers compiled alongside the seeding so every
+          # attribute the register can see — including late-merged
+          # imports that bypass define_attribute_methods — carries
+          # one (#933). Idempotent with the declaration-time
+          # definition.
+          raw_lines = attrs.filter_map do |name, _attr|
+            next unless name.to_s.match?(PLAIN_NAME)
+
+            <<~RUBY
+              def __lutaml_raw_#{name}
+                @#{name}
+              end
+            RUBY
+          end.join
+          class_eval(<<~RUBY, __FILE__, __LINE__ + 1) # rubocop:disable Style/DocumentDynamicEvalDefinition
+            #{raw_lines}
+          RUBY
+        end
+
+        # Block-form raw-state reader (no String eval), defined on self.
+        def define_raw_state_reader(name)
+          ivar = :"@#{name}"
+          define_method(:"__lutaml_raw_#{name}") do
+            IVAR_GET.bind_call(self, ivar)
+          end
         end
 
         # Historical getter shape for punctuation-named attributes and
@@ -104,12 +168,46 @@ module Lutaml
                           end
             remove_method(compiled) if defined_now
           end
+          # The names cache must go with the methods: the memoized
+          # lookup answers stale names for removed methods otherwise.
+          @state_defaults_names.clear
         end
 
         def define_attribute_methods(attr, register = nil)
           name = attr.name
           register_id = extract_register_id(register)
 
+          # lutaml-model#922: raw-state reader for the deserializer's
+          # unmatched-rule handling. A custom writer that assigns a
+          # *different* attribute mid-parse (relaton's ICS Isoics
+          # fallback; any derived-value pattern) is invisible to the
+          # value_set tracker -- public setters don't mark it -- so the
+          # tracked "still default" state lies. The deserializer needs
+          # the raw stored state to know whether an attribute was
+          # writer-populated: still holding the initialized marker
+          # (sentinel / lazy collection) means unset; anything else was
+          # written since init and must never be overwritten by an
+          # unmatched rule's default assignment. Declared here (not in
+          # the state-defaults compilation) so late declarations get it
+          # too -- XMI's extension loader declares attributes after
+          # first parse.
+          # Without a source compiler, compile_state_defaults! defines
+          # its raw readers from blocks; define one for every name here
+          # too (define_method takes any name, not only plain ones).
+          # Both forms define on self: a bare `model` receiver resolves
+          # through the host class's own namespace (omml's Base answers
+          # a Store model) and defined the reader on the wrong object
+          # (#933).
+          if !AttributeDefinition.source_compilation?
+            define_raw_state_reader(name)
+          elsif name.to_s.match?(PLAIN_NAME)
+            class_eval(<<~RUBY, __FILE__, __LINE__ + 1) # rubocop:disable Style/DocumentDynamicEvalDefinition
+              def __lutaml_raw_#{name}
+                @#{name}
+              end
+            RUBY
+          end
+
           if attr.enum?
             add_enum_methods_to_model(
               model,
@@ -216,7 +314,9 @@ module Lutaml
           # Array on EVERY read — the largest per-call allocation source
           # on instance-heavy parses (TODO.max-perf/06). The optional-arg
           # form allocates nothing, and the read is a direct @ivar.
-          if attr.collection?
+          if !AttributeDefinition.source_compilation?
+            define_block_attribute_getter(name, attr)
+          elsif attr.collection?
             # class_eval interpolates, e.g.:
             #   def items(arg = Lutaml::Model::Serialize::NO_ARG)
             #     if arg.equal?(Lutaml::Model::Serialize::NO_ARG)
@@ -272,7 +372,9 @@ module Lutaml
                            end
           define_method(attr_reader_method) { attr } unless reader_defined
 
-          if attr.collection?
+          if !AttributeDefinition.source_compilation?
+            define_block_attribute_setters(name, attr)
+          elsif attr.collection?
             # class_eval interpolates, e.g.:
             #   def items=(value)
             #     value_set_for(:items)
@@ -332,6 +434,93 @@ module Lutaml
           end
         end
 
+        # Block form of the compiled getter in define_regular_attribute_methods,
+        # for runtimes without a source compiler (see source_compilation?).
+        def define_block_attribute_getter(name, attr)
+          name = name.to_sym # the compiled form passes :name literals
+          ivar = :"@#{name}"
+          if attr.collection?
+            # The compiled getter resolves Array in the model class's scope.
+            scope = self
+            define_method(name) do |arg = Lutaml::Model::Serialize::NO_ARG|
+              if arg.equal?(Lutaml::Model::Serialize::NO_ARG)
+                materialize_lazy_collection(name)
+              else
+                current = IVAR_GET.bind_call(self, ivar) || []
+                new_value = current.is_a?(CONST_GET.bind_call(scope, :Array)) ? current + [arg] : arg
+                IVAR_SET.bind_call(self, ivar, new_value)
+                record_mutation(name, arg)
+                arg
+              end
+            end
+          else
+            define_method(name) do |arg = Lutaml::Model::Serialize::NO_ARG|
+              if arg.equal?(Lutaml::Model::Serialize::NO_ARG)
+                IVAR_GET.bind_call(self, ivar)
+              else
+                public_send(:"#{name}=", arg)
+                arg
+              end
+            end
+          end
+        end
+
+        # Block form of the compiled setters in define_regular_attribute_methods.
+        # The Attribute is read through the same hidden accessor the
+        # compiled form calls, not captured: a setter redefined over an
+        # enum shorthand keeps casting with the accessor's Attribute.
+        def define_block_attribute_setters(name, attr)
+          name = name.to_sym # the compiled form passes :name literals
+          ivar = :"@#{name}"
+          handle = :"__attribute_definition_#{name}"
+          if attr.collection?
+            assign = lambda do |model, value|
+              current = IVAR_GET.bind_call(model, ivar)
+              unless current.equal?(Lutaml::Model::Serialize::LAZY_EMPTY_COLLECTION) &&
+                  (value.nil? || Lutaml::Model::Utils.uninitialized?(value))
+                IVAR_SET.bind_call(model, ivar, value)
+              end
+              SEND.bind_call(model, :record_mutation_collection, name, value)
+            end
+            define_method(:"#{name}=") do |value|
+              value_set_for(name)
+              assign.call(self, SEND.bind_call(self, handle).cast_value(value, lutaml_register))
+            end
+            define_method(:"__assign_parsed_#{name}=") do |value|
+              value_set_for(name)
+              assign.call(self, value)
+            end
+          else
+            define_method(:"#{name}=") do |value|
+              value_set_for(name)
+              value = SEND.bind_call(self, handle).cast_value(value, lutaml_register)
+              IVAR_SET.bind_call(self, ivar, value)
+              record_mutation(name, value)
+            end
+            define_method(:"__assign_parsed_#{name}=") do |value|
+              value_set_for(name)
+              IVAR_SET.bind_call(self, ivar, value)
+              record_mutation(name, value)
+            end
+          end
+        end
+
+        # Class-level documentation metadata (#356): `desc "text"` on
+        # the model class; a zero-argument call reads it back.
+        # Subclasses inherit the nearest ancestor's description — an
+        # explicit `desc` overrides. Consumed by documentation and
+        # schema tooling; the serialization paths never read it.
+        def desc(text = nil)
+          return @lutaml_desc = text if text
+
+          return @lutaml_desc if defined?(@lutaml_desc)
+
+          if superclass.is_a?(::Class) &&
+              superclass < ::Lutaml::Model::Serializable
+            superclass.desc
+          end
+        end
+
         # Define an attribute for the model
         #
         # @param name [Symbol] The attribute name
@@ -354,6 +543,11 @@ module Lutaml
           attr = Attribute.new(name, type, options)
           @attributes[name] = attr
           @merged_attributes_cache = nil
+          # Attributes can be declared after the model has been
+          # instantiated (forward references, post-hoc declarations);
+          # the interned writer table from the first instantiation must
+          # not outlive the attribute set it was built from.
+          @instantiate_writers = nil
           invalidate_state_defaults!
           define_attribute_methods(attr)
 

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

@@ -84,6 +84,26 @@ module Lutaml
           @__order_tracking__ ? true : false
         end
 
+        # Whether any writer setter ran on this instance. Parsed
+        # instances start pristine — every set element value is covered
+        # by the parse-built element_order, so ordered serialization
+        # can skip order reconciliation; the first writer-set marks the
+        # instance and reconciliation engages (writer-added values sit
+        # outside the parse order).
+        # @return [Boolean]
+        def mutated_after_parse?
+          @__mutated_after_parse__ ? true : false
+        end
+
+        # Construction-time reset: hydration routes every attribute
+        # through the generated writers (which mark mutations); a
+        # freshly built instance is definitionally not
+        # mutated-after-parse.
+        # @return [void]
+        def clear_mutated_after_parse!
+          @__mutated_after_parse__ = false
+        end
+
         # Record a singular attribute mutation in element_order.
         #
         # No-op unless order tracking is enabled (i.e. the instance was
@@ -102,6 +122,7 @@ module Lutaml
         #   content for content-mapped attributes, ignored otherwise
         # @return [Object] the passed value
         def record_mutation(attribute_name, value = nil)
+          @__mutated_after_parse__ = true
           return value unless @__order_tracking__
 
           track_order(attribute_name, value, nil)
@@ -122,6 +143,7 @@ module Lutaml
         # @param value [Object, nil] The value assigned to the collection
         # @return [Object] the passed value
         def record_mutation_collection(attribute_name, value)
+          @__mutated_after_parse__ = true
           return value unless @__order_tracking__
           return value if value.nil? || Lutaml::Model::Utils.uninitialized?(value)
 

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

@@ -19,6 +19,11 @@ module Lutaml
       # not emit Instrumentation events — the work did not happen.
       #
       # Semantics (deliberate):
+      # - Growth is unbounded by default: every distinct input digs its
+      #   own entry, and nothing evicts until the store does. Bound the
+      #   store — lutaml-store's memory adapter accepts max_entries —
+      #   via Config.conversion_cache before enabling this in
+      #   long-lived batch processes.
       # - `from_*` hits return the same cached instance for identical
       #   input — across callers and threads. Treat results as read-only;
       #   classes whose callers mutate parse results must not opt in.