lutaml-model 0.8.56 → 0.8.106

data/spec/lutaml/key_value/transformation_spec.rb

@@ -60,9 +60,7 @@ RSpec.describe Lutaml::KeyValue::Transformation do
 
         result = transformation.transform(model)
 
-        expect(result).to be_a(Lutaml::KeyValue::DataModel::Element)
-        expect(result.key).to eq("__root__")
-        expect(result.children.length).to eq(3)
+        expect(result).to be_a(Hash)
       end
 
       it "creates proper key-value structure" do
@@ -71,7 +69,7 @@ RSpec.describe Lutaml::KeyValue::Transformation do
         transformation = described_class.new(KVSimpleModel, mapping, :json, nil)
 
         result = transformation.transform(model)
-        hash = result.to_hash
+        hash = { "__root__" => result }
 
         # Remove __root__ wrapper
         expect(hash["__root__"]).to eq({
@@ -87,7 +85,7 @@ RSpec.describe Lutaml::KeyValue::Transformation do
         transformation = described_class.new(KVSimpleModel, mapping, :json, nil)
 
         result = transformation.transform(model)
-        hash = result.to_hash
+        hash = { "__root__" => result }
 
         # nil values should be rendered by default
         expect(hash["__root__"]["age"]).to be_nil
@@ -103,7 +101,7 @@ RSpec.describe Lutaml::KeyValue::Transformation do
         transformation = described_class.new(KVPerson, mapping, :json, nil)
 
         result = transformation.transform(person)
-        hash = result.to_hash
+        hash = { "__root__" => result }
 
         expect(hash["__root__"]).to eq({
                                          "name" => "John",
@@ -121,7 +119,7 @@ RSpec.describe Lutaml::KeyValue::Transformation do
         transformation = described_class.new(KVPerson, mapping, :json, nil)
 
         result = transformation.transform(person)
-        hash = result.to_hash
+        hash = { "__root__" => result }
 
         # nil nested model should be in output (based on default render_nil)
         expect(hash["__root__"]["address"]).to be_nil
@@ -137,7 +135,7 @@ RSpec.describe Lutaml::KeyValue::Transformation do
         transformation = described_class.new(KVTeam, mapping, :json, nil)
 
         result = transformation.transform(team)
-        hash = result.to_hash
+        hash = { "__root__" => result }
 
         expect(hash["__root__"]).to eq({
                                          "name" => "Dev Team",
@@ -152,7 +150,7 @@ RSpec.describe Lutaml::KeyValue::Transformation do
         transformation = described_class.new(KVTeam, mapping, :json, nil)
 
         result = transformation.transform(team)
-        hash = result.to_hash
+        hash = { "__root__" => result }
 
         # Empty collections are not rendered by default (render_empty defaults to false)
         expect(hash["__root__"]["members"]).to be_nil
@@ -164,7 +162,7 @@ RSpec.describe Lutaml::KeyValue::Transformation do
         transformation = described_class.new(KVTeam, mapping, :json, nil)
 
         result = transformation.transform(team)
-        hash = result.to_hash
+        hash = { "__root__" => result }
 
         # nil collection should be nil by default
         expect(hash["__root__"]["members"]).to be_nil
@@ -190,7 +188,7 @@ RSpec.describe Lutaml::KeyValue::Transformation do
                                              nil)
 
         result = transformation.transform(model)
-        hash = result.to_hash
+        hash = { "__root__" => result }
 
         expect(hash["__root__"]["name"]).to eq("JOHN")
       end
@@ -213,7 +211,7 @@ RSpec.describe Lutaml::KeyValue::Transformation do
         transformation = described_class.new(KVRenderModel, mapping, :json, nil)
 
         result = transformation.transform(model)
-        hash = result.to_hash
+        hash = { "__root__" => result }
 
         # optional should be omitted
         expect(hash["__root__"].keys).not_to include("optional")
@@ -225,7 +223,7 @@ RSpec.describe Lutaml::KeyValue::Transformation do
         transformation = described_class.new(KVRenderModel, mapping, :json, nil)
 
         result = transformation.transform(model)
-        hash = result.to_hash
+        hash = { "__root__" => result }
 
         # defaulted should be omitted
         expect(hash["__root__"].keys).not_to include("defaulted")
@@ -234,22 +232,22 @@ RSpec.describe Lutaml::KeyValue::Transformation do
   end
 
   describe "architecture compliance" do
-    it "produces OOP data structures, not raw hashes" do
+    it "emits the presentation hash directly (TODO.perf 19)" do
       model = KVSimpleModel.new(name: "John", age: 30, active: true)
       mapping = KVSimpleModel.mappings_for(:json)
       transformation = described_class.new(KVSimpleModel, mapping, :json, nil)
 
       result = transformation.transform(model)
 
-      # Result should be KeyValueElement, not Hash
-      expect(result).to be_a(Lutaml::KeyValue::DataModel::Element)
-      expect(result).not_to be_a(Hash)
-
-      # Children should also be KeyValueElements
-      expect(result.children).to all(be_a(Lutaml::KeyValue::DataModel::Element))
+      # Hash-direct emission: the __root__ Element tree (write-only in
+      # production, immediately flattened by every consumer) is gone;
+      # transform produces the output hash itself.
+      expect(result).to be_a(Hash)
+      expect(result).to eq("name" => "John", "age" => 30, "active" => true)
     end
 
     it "separates content (KeyValueElement) from presentation (Hash)" do
+      skip "superseded by hash-direct emission (TODO.perf 19)"
       model = KVSimpleModel.new(name: "John", age: 30, active: true)
       mapping = KVSimpleModel.mappings_for(:json)
       transformation = described_class.new(KVSimpleModel, mapping, :json, nil)
@@ -259,7 +257,7 @@ RSpec.describe Lutaml::KeyValue::Transformation do
       expect(result).to be_a(Lutaml::KeyValue::DataModel::Element)
 
       # Presentation happens via to_hash, not during transformation
-      hash = result.to_hash
+      hash = { "__root__" => result }
       expect(hash).to be_a(Hash)
     end
   end
@@ -292,4 +290,72 @@ RSpec.describe Lutaml::KeyValue::Transformation do
       end.not_to raise_error
     end
   end
+
+  describe "custom to: methods under hash-direct emission (pubid regression)" do
+    before do
+      stub_const("PubidRegress", Module.new)
+      stub_const("PubidRegress::EmptyCustom", empty_custom_class)
+      stub_const("PubidRegress::ValueWriter", value_writer_class)
+      stub_const("PubidRegress::ReturnOnly", return_only_class)
+    end
+
+    let(:empty_custom_class) do
+      Class.new(Lutaml::Model::Serializable) do
+        attribute :code, :string
+        key_value do
+          map "code", to: :code, with: { to: :to_code }
+        end
+
+        # pubid 2.0's shape: inspects the doc and may return without
+        # writing anything — must not crash the emission.
+        def to_code(_model, doc); end
+      end
+    end
+
+    let(:value_writer_class) do
+      Class.new(Lutaml::Model::Serializable) do
+        attribute :code, :string
+        key_value do
+          map "code", to: :code, with: { to: :to_code }
+        end
+
+        def to_code(model, doc)
+          doc.value["code"] = model.code
+        end
+      end
+    end
+
+    let(:return_only_class) do
+      Class.new(Lutaml::Model::Serializable) do
+        attribute :code, :string
+        key_value do
+          map "code", to: :code, with: { to: :to_code }
+        end
+
+        # Returns its value without touching the doc — a shape the
+        # mutation-only contract must serialize as nothing (#892).
+        def to_code(_model, _doc)
+          { "code" => "RETURNED" }
+        end
+      end
+    end
+
+    it "tolerates a custom method that writes nothing to the doc" do
+      model = PubidRegress::EmptyCustom.new(code: "X")
+      expect(model.to_hash).to eq({})
+    end
+
+    it "merges a custom method writing through doc.value" do
+      model = PubidRegress::ValueWriter.new(code: "X")
+      expect(model.to_hash).to eq("code" => "X")
+    end
+
+    it "ignores a custom method's return value (mutation-only contract)" do
+      # A method returning a hash without touching the doc serializes
+      # as nothing — honoring returns merged child content at the
+      # wrong level (lutaml-model#892).
+      model = PubidRegress::ReturnOnly.new(code: "X")
+      expect(model.to_hash).to eq({})
+    end
+  end
 end

data/spec/lutaml/model/any_element_mapping_spec.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+require "spec_helper"
+
+class AnyElementNode < Lutaml::Model::Serializable
+  attribute :id, :string
+  attribute :children, "AnyElementNode", collection: true
+
+  xml do
+    element "root"
+    map_element "id", to: :id
+    map_any_element to: :children
+  end
+end
+
+RSpec.describe AnyElementNode do
+  it "routes unmapped child elements to the catch-all collection" do
+    doc = described_class.from_xml(<<~XML)
+      <root>
+        <id>r-1</id>
+        <semantic__p>hello</semantic__p>
+        <semantic__title>Nested</semantic__title>
+        <semantic__p><semantic__em>deep</semantic__em></semantic__p>
+      </root>
+    XML
+
+    expect(doc.id).to eq("r-1")
+    expect(doc.children.size).to eq(3)
+  end
+
+  it "keeps explicit rules ahead of the catch-all" do
+    doc = described_class.from_xml("<root><id>x</id></root>")
+    expect(doc.id).to eq("x")
+    expect(doc.children).to be_empty
+  end
+
+  it "nests catch-all children recursively" do
+    doc = described_class.from_xml("<root><semantic__p><semantic__em>deep</semantic__em></semantic__p></root>")
+    expect(doc.children.first.children.size).to eq(1)
+  end
+end

data/spec/lutaml/model/collection_validation_spec.rb

@@ -732,5 +732,270 @@ RSpec.describe Lutaml::Model::Collection do
         end
       end
     end
+
+    describe "Conditional validation chaining with context" do
+      context "with context sharing between validations" do
+        it "allows validations to read results from previous validations" do
+          chain_executed = []
+
+          chained_collection = Class.new(Lutaml::Model::Collection) do
+            instances :publications, CollectionValidationTests::Publication
+
+            validates_uniqueness_of :id
+
+            validate_collection do |_collection, _errors, ctx|
+              chain_executed << :first
+              ctx[:duplicates_found] = !ctx[:duplicates_of_id].nil? && ctx[:duplicates_of_id].any?
+            end
+
+            validate_collection do |_collection, errors, ctx|
+              chain_executed << :second
+              if ctx[:duplicates_found]
+                errors.add(:collection, "Cannot proceed with duplicates")
+              end
+            end
+          end
+
+          # Test with duplicates
+          collection = chained_collection.new([science_publication, duplicate_id_publication])
+          expect { collection.validate! }.to raise_error(Lutaml::Model::ValidationError) do |error|
+            expect(error.message).to include("Cannot proceed with duplicates")
+          end
+          expect(chain_executed).to eq(%i[first second])
+
+          # Test without duplicates
+          chain_executed.clear
+          collection = chained_collection.new([science_publication, fiction_publication])
+          expect { collection.validate! }.not_to raise_error
+          expect(chain_executed).to eq(%i[first second])
+        end
+
+        it "stores duplicate values in context for downstream validations" do
+          chained_collection = Class.new(Lutaml::Model::Collection) do
+            instances :publications, CollectionValidationTests::Publication
+
+            validates_uniqueness_of :id
+
+            validate_collection do |_collection, errors, ctx|
+              if ctx[:duplicates_of_id]&.include?("1")
+                errors.add(:collection, "Found duplicate ID: 1")
+              end
+            end
+          end
+
+          collection = chained_collection.new([science_publication, duplicate_id_publication])
+          expect { collection.validate! }.to raise_error(Lutaml::Model::ValidationError) do |error|
+            expect(error.message).to include("Found duplicate ID: 1")
+          end
+        end
+
+        it "stores missing count in context for validates_all_present" do
+          chained_collection = Class.new(Lutaml::Model::Collection) do
+            instances :publications, CollectionValidationTests::Publication
+
+            validates_all_present :author
+
+            validate_collection do |_collection, errors, ctx|
+              if ctx[:missing_author_count].to_i > 0
+                errors.add(:collection, "#{ctx[:missing_author_count]} items missing author")
+              end
+            end
+          end
+
+          collection = chained_collection.new([science_publication, publication_without_author])
+          expect { collection.validate! }.to raise_error(Lutaml::Model::ValidationError) do |error|
+            expect(error.message).to include("1 items missing author")
+          end
+        end
+      end
+
+      context "with conditional validation using :if_cond option" do
+        it "only runs validation when condition is met" do
+          chained_collection = Class.new(Lutaml::Model::Collection) do
+            instances :publications, CollectionValidationTests::Publication
+
+            validates_uniqueness_of :id
+
+            validate_collection(if_cond: ->(ctx) { ctx[:duplicates_of_id]&.any? }) do |_collection, errors, _ctx|
+              errors.add(:collection, "Validation ran because duplicates exist")
+            end
+          end
+
+          # With duplicates - conditional validation should run
+          collection = chained_collection.new([science_publication, duplicate_id_publication])
+          expect { collection.validate! }.to raise_error(Lutaml::Model::ValidationError) do |error|
+            expect(error.message).to include("Validation ran because duplicates exist")
+          end
+
+          # Without duplicates - conditional validation should not run
+          collection = chained_collection.new([science_publication, fiction_publication])
+          expect { collection.validate! }.not_to raise_error
+        end
+
+        it "can skip validation based on context state" do
+          expensive_validation_ran = false
+
+          chained_collection = Class.new(Lutaml::Model::Collection) do
+            instances :publications, CollectionValidationTests::Publication
+
+            validates_uniqueness_of :id
+
+            validate_collection(if_cond: ->(ctx) { !ctx[:duplicates_of_id]&.any? }) do |_collection, _errors, _ctx|
+              expensive_validation_ran = true
+            end
+          end
+
+          # With duplicates - the uniqueness error raises (landed
+          # semantics) AND the expensive validation still skipped
+          collection = chained_collection.new([science_publication, duplicate_id_publication])
+          expect { collection.validate! }.to raise_error(Lutaml::Model::ValidationError,
+                                                         /unique across collection/)
+          expect(expensive_validation_ran).to be false
+
+          # Without duplicates - expensive validation should run
+          expensive_validation_ran = false
+          collection = chained_collection.new([science_publication, fiction_publication])
+          collection.validate!
+          expect(expensive_validation_ran).to be true
+        end
+      end
+
+      context "with conditional validation using :unless_cond option" do
+        it "skips validation when condition is met" do
+          ran_count = 0
+
+          chained_collection = Class.new(Lutaml::Model::Collection) do
+            instances :publications, CollectionValidationTests::Publication
+
+            validates_uniqueness_of :id
+
+            validate_collection(unless_cond: ->(ctx) { ctx[:duplicates_of_id]&.any? }) do |_collection, _errors, _ctx|
+              ran_count += 1
+            end
+          end
+
+          # With duplicates - the uniqueness error raises (landed
+          # semantics) AND the conditional validation still skipped
+          collection = chained_collection.new([science_publication, duplicate_id_publication])
+          expect { collection.validate! }.to raise_error(Lutaml::Model::ValidationError,
+                                                         /unique across collection/)
+          expect(ran_count).to be 0
+
+          # Without duplicates - should run
+          collection = chained_collection.new([science_publication, fiction_publication])
+          collection.validate!
+          expect(ran_count).to be 1
+        end
+      end
+
+      context "with ctx.stop!" do
+        it "stops validation chain when ctx.stop! is called" do
+          chain_order = []
+
+          chained_collection = Class.new(Lutaml::Model::Collection) do
+            instances :publications, CollectionValidationTests::Publication
+
+            validate_collection do |_collection, _errors, ctx|
+              chain_order << :first
+              ctx.stop!
+            end
+
+            validate_collection do |_collection, _errors, ctx|
+              chain_order << :second
+              ctx.stop!
+            end
+
+            validate_collection do |_collection, _errors, _ctx|
+              chain_order << :third
+            end
+          end
+
+          collection = chained_collection.new([science_publication])
+          collection.validate!
+          expect(chain_order).to eq([:first])
+        end
+      end
+
+      context "with backwards compatible block signatures" do
+        it "works with 1-argument blocks" do
+          ran = false
+
+          collection_class = Class.new(Lutaml::Model::Collection) do
+            instances :publications, CollectionValidationTests::Publication
+
+            validate_collection do |collection|
+              ran = true if !collection.empty?
+            end
+          end
+
+          collection = collection_class.new([science_publication])
+          collection.validate!
+          expect(ran).to be true
+        end
+
+        it "works with 2-argument blocks (original signature)" do
+          ran_args = []
+
+          collection_class = Class.new(Lutaml::Model::Collection) do
+            instances :publications, CollectionValidationTests::Publication
+
+            validate_collection do |collection, errors|
+              ran_args << [collection.size, errors.class.name]
+              errors.add(:collection, "Test error") if !collection.empty?
+            end
+          end
+
+          collection = collection_class.new([science_publication])
+          errors = collection.validate
+          expect(ran_args.first.first).to eq 1
+          expect(ran_args.first.last).to include("Errors")
+          expect(errors.map(&:message).first).to include("Test error")
+        end
+
+        it "works with 3-argument blocks (new signature with context)" do
+          received_context = nil
+
+          collection_class = Class.new(Lutaml::Model::Collection) do
+            instances :publications, CollectionValidationTests::Publication
+
+            validate_collection do |_collection, _errors, ctx|
+              received_context = ctx
+              ctx[:test_value] = "from_validation"
+            end
+          end
+
+          collection = collection_class.new([science_publication])
+          collection.validate
+          expect(received_context).to be_a(Lutaml::Model::ValidationContext)
+          expect(received_context[:test_value]).to eq("from_validation")
+        end
+      end
+
+      context "with ctx.failed? helper" do
+        it "returns true when errors have been added" do
+          result = nil
+
+          chained_collection = Class.new(Lutaml::Model::Collection) do
+            instances :publications, CollectionValidationTests::Publication
+
+            validates_uniqueness_of :id
+
+            validate_collection do |_collection, _errors, ctx|
+              result = ctx.failed?
+            end
+          end
+
+          # Without errors
+          collection = chained_collection.new([science_publication, fiction_publication])
+          collection.validate
+          expect(result).to be false
+
+          # With errors
+          collection = chained_collection.new([science_publication, duplicate_id_publication])
+          collection.validate
+          expect(result).to be true
+        end
+      end
+    end
   end
 end

data/spec/lutaml/model/desc_spec.rb

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+require_relative "../../spec_helper"
+
+RSpec.describe "Documentation metadata (desc)" do
+  let(:widget_class) do
+    Class.new(Lutaml::Model::Serializable) do
+      desc "A widget."
+
+      attribute :name, :string, desc: "The widget name."
+      attribute :size, :integer
+    end
+  end
+
+  it "stores and reads the class-level description" do
+    expect(widget_class.desc).to eq("A widget.")
+  end
+
+  it "returns nil when no description is set" do
+    plain = Class.new(Lutaml::Model::Serializable)
+    expect(plain.desc).to be_nil
+  end
+
+  it "inherits the description on subclasses" do
+    child = Class.new(widget_class)
+    expect(child.desc).to eq("A widget.")
+  end
+
+  it "lets a subclass override the description" do
+    child = Class.new(widget_class) do
+      desc "A special widget."
+    end
+    expect(child.desc).to eq("A special widget.")
+  end
+
+  it "does not leak an override back to the superclass" do
+    Class.new(widget_class) { desc "Child only." }
+    expect(widget_class.desc).to eq("A widget.")
+  end
+
+  it "stores the attribute-level description" do
+    expect(widget_class.attributes[:name].desc).to eq("The widget name.")
+    expect(widget_class.attributes[:size].desc).to be_nil
+  end
+
+  it "keeps serialization untouched" do
+    widget = widget_class.new(name: "w", size: 3)
+    expect(widget.to_hash).to eq("name" => "w", "size" => 3)
+  end
+end

data/spec/lutaml/model/late_attribute_declaration_spec.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+require "spec_helper"
+
+# Attributes can be declared after the model has been instantiated
+# (forward references, post-hoc declarations). The interned writer
+# table built during the first instantiation must not outlive the
+# attribute set it was built from.
+RSpec.describe "attributes declared after first instantiation" do
+  it "initializes attributes added after an earlier instantiation" do
+    klass = Class.new(Lutaml::Model::Serializable) do
+      attribute :name, :string
+    end
+
+    klass.new(name: "first")
+
+    klass.attribute :size, :string
+    instance = klass.new(name: "second", size: "L")
+
+    expect(instance.name).to eq("second")
+    expect(instance.size).to eq("L")
+  end
+
+  it "keeps earlier instances unaffected" do
+    klass = Class.new(Lutaml::Model::Serializable) do
+      attribute :name, :string
+    end
+
+    first = klass.new(name: "first")
+    klass.attribute :size, :string
+
+    expect(first.name).to eq("first")
+    expect(first.respond_to?(:size)).to be(true)
+  end
+end

data/spec/lutaml/model/model_import_reentry_spec.rb

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+require "spec_helper"
+
+# Issue #938: a deferred (symbol-form) import that cannot resolve leaves
+# the import pass with all_resolved = false. record_import_attempt then
+# calls attributes(), which re-enters ensure_imports!; the completion
+# marker stored false before that call, so the re-entrant pass ran the
+# import loop again and recursed to SystemStackError. Consumers with
+# large mutually-referencing type graphs (uniword OOXML sets) hit this
+# on load.
+module ModelImportReentry938
+  class OrphanSource < Lutaml::Model::Serializable
+    attribute :label, :string
+  end
+
+  class PendingImporter < Lutaml::Model::Serializable
+    attribute :name, :string
+    import_model_attributes :NoSuchModelAnywhere938
+  end
+
+  class ResolvableImporter < Lutaml::Model::Serializable
+    attribute :name, :string
+  end
+
+  Lutaml::Model::GlobalRegister
+    .lookup(Lutaml::Model::Config.default_register)
+    .register_model(OrphanSource, id: :ModelImportReentry938OrphanSource)
+  ResolvableImporter
+    .import_model_attributes(:ModelImportReentry938OrphanSource)
+end
+
+RSpec.describe "deferred model import re-entry" do
+  it "does not recurse when a deferred import cannot resolve" do
+    expect { ModelImportReentry938::PendingImporter.attributes(:default) }
+      .not_to raise_error
+  end
+
+  it "resolves a deferred import without recursing on re-access" do
+    importer = ModelImportReentry938::ResolvableImporter
+    3.times { importer.attributes(:default) }
+
+    expect(importer.attributes(:default)).to have_key(:name)
+    expect(importer.attributes(:default)).to have_key(:label)
+  end
+end

data/spec/lutaml/model/opal_smoke_spec.rb

@@ -147,6 +147,23 @@ RSpec.describe "Opal compatibility", if: RUBY_ENGINE == "opal" do
     expect(instance.port).to eq(8080)
   end
 
+  # Opal has no TracePoint; a symbol import is resolved on first use.
+  it "resolves a deferred symbol import on first use" do
+    register = Lutaml::Model::GlobalRegister
+      .lookup(Lutaml::Model::Config.default_register)
+    importer = Class.new(Lutaml::Model::Serializable) do
+      import_model :opal_deferred_import
+    end
+    imported = Class.new(Lutaml::Model::Serializable) do
+      attribute :title, :string
+    end
+    register.register_model(imported, id: :opal_deferred_import)
+
+    instance = importer.from_json('{"title":"Deferred"}')
+    expect(instance.title).to eq("Deferred")
+    expect(instance.to_hash).to eq({ "title" => "Deferred" })
+  end
+
   it "RuntimeCompatibility detects Opal" do
     expect(Lutaml::Model::RuntimeCompatibility.opal?).to be true
   end