lutaml-model 0.8.100 → 0.8.119

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

@@ -78,12 +78,21 @@ module Lutaml
 
       def add_xml_fragment_or_raw_content(parent, fragment_string)
         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.
+        fragment_doc = begin
+          Moxml.new.parse(fragment_string, fragment: true)
+        rescue Moxml::ParseError
+          # Engines that reject multi-root fragments outright
+          # (lutaml/moxml#188) — fall through to the synthetic root.
+          nil
+        end
+        # The fallback keys on the RESULT, not the exception: recover-mode
+        # engines return an empty document for multi-root fragments instead
+        # of raising, which used to leave the synthetic-root path dead and
+        # the fragment silently dropped.
+        if fragment_doc&.children&.any?(&:element?)
+          return add_fragment_children_to_parent(fragment_doc, parent)
+        end
+
         wrapped = Moxml.new.parse(
           "<lutaml-fragment>#{fragment_string}</lutaml-fragment>",
         )

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

@@ -40,6 +40,35 @@ module Lutaml
         end
         private_class_method :require_engine
 
+        # True where the yeptris engine loads (libyeptris present for
+        # this platform) AND answers a probe parse. A require alone
+        # does not prove the engine: a half-initialized Yeptris
+        # constant (the poison-process state the gem documents)
+        # passes const_defined? and require while every parse fails,
+        # and the native parse error then surfaces on valid input.
+        # Idempotent; a missing or broken install reports false
+        # instead of raising, so optional-engine callers (detection)
+        # can gate on it and fall back to the standard lane.
+        def self.available?
+          require_engine
+          native_ready?
+        rescue LoadError
+          false
+        end
+
+        def self.native_ready?
+          return @native_ready unless @native_ready.nil?
+
+          @native_ready = begin
+            # rubocop:disable-next Naming/VariableNumber -- upstream schema literal
+            ::Yeptris::YAML.load("native_probe: 1", schema: :compat_11)
+            true
+          rescue ::Yeptris::Error, LoadError, NoMemoryError
+            false
+          end
+        end
+        private_class_method :native_ready?
+
         # The parse-error contract is the standard adapter's: invalid
         # input raises Psych::SyntaxError regardless of the engine, so
         # consumers' rescue ladders (and this gem's own

data/lutaml-model.gemspec

@@ -33,7 +33,7 @@ Gem::Specification.new do |spec|
   spec.executables = spec.files.grep(%r{^exe/}) { |f| File.basename(f) }
 
   # required for liquid
-  spec.add_dependency "base64"
+  spec.add_dependency "base64", ">= 0.1.1"
   spec.add_dependency "bigdecimal"
   spec.add_dependency "canon"
   spec.add_dependency "concurrent-ruby"
@@ -41,10 +41,10 @@ Gem::Specification.new do |spec|
   # 0.5.84 always passes XML_PARSE_HUGE to libxml2: very large documents
   # parse completely instead of being silently truncated at the 10 MB
   # input-buffer cap (lutaml-model#871).
-  spec.add_dependency "moxml", "~> 0.5.84"
+  spec.add_dependency "moxml", "~> 0.5.139"
   spec.add_dependency "ostruct"
   spec.add_dependency "rubyzip", "~> 3.7"
-  spec.add_dependency "thor"
+  spec.add_dependency "thor", "~> 1.4"
 
   spec.metadata["rubygems_mfa_required"] = "true"
 end

data/spec/lutaml/json/yeptris_adapter_spec.rb

@@ -1,16 +1,9 @@
 # frozen_string_literal: true
 
-require "spec_helper"
-begin
-  require "lutaml/json/adapter/yeptris_adapter"
-rescue LoadError
-  # yeptris ships no platform gem here (e.g. Windows): every example skips.
-end
-
-YEPTRIS_AVAILABLE = defined?(Yeptris)
+require "lutaml/json/adapter/yeptris_adapter"
 
-RSpec.describe(YEPTRIS_AVAILABLE ? Lutaml::Json::Adapter::YeptrisAdapter : Object) do
-  before { skip "yeptris is not available on this platform" unless YEPTRIS_AVAILABLE }
+RSpec.describe Lutaml::Json::Adapter::YeptrisAdapter do
+  before { skip "yeptris is not available on this platform" unless described_class.available? }
 
   let(:attributes) { { "name" => "John", "age" => 30, "roles" => %w[admin dev] } }
 

data/spec/lutaml/model/adapter_resolver_configured_spec.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 require "spec_helper"
+require "open3"
 
 RSpec.describe Lutaml::Model::AdapterResolver, ".adapter_for with a configured type" do
   after do
@@ -22,17 +23,40 @@ RSpec.describe Lutaml::Model::AdapterResolver, ".adapter_for with a configured t
     expect(adapter.name).to include("Json::Standard")
   end
 
+  # Runs in a subprocess: whether the engine is already loaded is a
+  # process-global fact, so any in-process assertion would depend on
+  # spec file order (the yeptris adapter faces load it).
   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)
+    probe = <<~RUBY
+      require "lutaml/model"
 
-    Lutaml::Model::Config.configure do |config|
-      config.yaml_adapter_type = :standard
-      config.json_adapter_type = :standard
-    end
+      Lutaml::Model::Config.configure do |config|
+        config.yaml_adapter_type = :standard
+        config.json_adapter_type = :standard
+      end
+
+      adapter_yaml = Lutaml::Model::AdapterResolver.adapter_for(:yaml)
+      adapter_json = Lutaml::Model::AdapterResolver.adapter_for(:json)
 
-    described_class.adapter_for(:yaml)
-    described_class.adapter_for(:json)
+      # Parsing through the configured adapters must likewise stay on
+      # the standard engines.
+      adapter_yaml.parse("a: 1")
+      adapter_json.parse('{"a":1}')
 
-    expect(Object.const_defined?(:Yeptris)).to be(false)
+      exit(Object.const_defined?(:Yeptris) ? 1 : 0)
+    RUBY
+
+    _stdout, stderr, status = Open3.capture3(RbConfig.ruby, "-I", "lib", "-e", probe)
+    expect(status).to be_success, stderr
+  end
+
+  describe "plan lane defaults" do
+    it "ships the ordered plan lane on, floored to the memo-capable engine" do
+      # leptris#1743 (exponential flatten on diamond-shared plan
+      # graphs) shipped its identity-memo flatten_plan in 1.9.366.2;
+      # the MIN_LEPTRIS_VERSION floor keeps memo-less engines on the
+      # interpretive path, so the default-on lane is safe.
+      expect(Lutaml::Model::Config.instance.xml_plan_ordered_path).to be(true)
+    end
   end
 end

data/spec/lutaml/model/cast_element_form_spec.rb

@@ -0,0 +1,54 @@
+# frozen_string_literal: true
+
+require "spec_helper"
+
+# The scalar-cast diversion (#978) must not capture element-form input:
+# a type declaring its own .cast still receives parsed child elements
+# through the mapping lane, which builds the model from its XML
+# mapping. Diverting those into .cast raised IncorrectModelError
+# downstream (uniword shared-schemas round-trips on 0.8.116/0.8.117).
+RSpec.describe "cast routing for element-form input" do
+  let(:styled_class) do
+    Class.new(Lutaml::Model::Serializable) do
+      attribute :value, :string
+
+      xml do
+        element "style"
+        map_attribute "value", to: :value
+      end
+
+      key_value do
+        map "value", to: :value
+      end
+
+      def self.cast(value)
+        return value if value.is_a?(self)
+
+        new(value: value.to_s)
+      end
+    end
+  end
+
+  let(:host_class) do
+    Class.new(Lutaml::Model::Serializable) do
+      attribute :style, "CastStyled"
+
+      xml do
+        element "host"
+        map_element "style", to: :style
+      end
+    end
+  end
+
+  before do
+    stub_const("CastStyled", styled_class)
+    stub_const("CastHost", host_class)
+  end
+
+  it "builds element-form input through the mapping lane" do
+    model = CastHost.from_xml('<host><style value="normal"/></host>')
+
+    expect(model.style).to be_a(CastStyled)
+    expect(model.style.value).to eq("normal")
+  end
+end

data/spec/lutaml/model/collection_strict_assignment_spec.rb

@@ -0,0 +1,55 @@
+# frozen_string_literal: true
+
+require "spec_helper"
+
+RSpec.describe "strict collection assignment" do
+  let(:node_class) do
+    Class.new(Lutaml::Model::Serializable) do
+      attribute :id, :string
+    end
+  end
+
+  let(:holder_class) do
+    Class.new(Lutaml::Model::Serializable) do
+      attribute :items, "Node", collection: true
+    end
+  end
+
+  before do
+    stub_const("Node", node_class)
+    stub_const("Holder", holder_class)
+  end
+
+  it "raises at the constructor boundary" do
+    expect do
+      Holder.new(items: [[Node.new(id: "a")], Node.new(id: "b")])
+    end.to raise_error(Lutaml::Model::TypeError, /item 0 is an Array/)
+  end
+
+  it "raises at the writer boundary" do
+    holder = Holder.new
+    expect do
+      holder.items = [Node.new, [Node.new]]
+    end.to raise_error(Lutaml::Model::TypeError, /item 1 is an Array/)
+  end
+
+  it "raises for a custom collection class" do
+    custom = Class.new(Lutaml::Model::Collection) do
+      instances :node, "Node"
+    end
+    stub_const("NodeBag", custom)
+    wrapper = Class.new(Lutaml::Model::Serializable) do
+      attribute :bag, "NodeBag"
+    end
+    stub_const("BagHolder", wrapper)
+
+    expect do
+      BagHolder.new(bag: [[Node.new]])
+    end.to raise_error(Lutaml::Model::TypeError, /nested arrays are not flattened/)
+  end
+
+  it "keeps flat assignment untouched" do
+    holder = Holder.new(items: [Node.new(id: "x")])
+    expect(holder.items.map(&:id)).to eq(["x"])
+  end
+end

data/spec/lutaml/model/from_json_scalar_cast_spec.rb

@@ -0,0 +1,70 @@
+# frozen_string_literal: true
+
+require "spec_helper"
+
+# #978: a JSON scalar handed to a mapped-model attribute crashed with
+# an internal NoMethodError (key? on String) wrapped as
+# InvalidFormatError. A type that declares its own .cast owns scalar
+# construction from that scalar; a cast-less type falls through to the
+# legacy conversion chain, whose parse error surfaces the offending
+# token — the remedy there is declaring .cast on the type.
+RSpec.describe "from_json scalar into a mapped-model attribute" do
+  let(:marked_class) do
+    Class.new(Lutaml::Model::Serializable) do
+      attribute :content, :string
+
+      key_value do
+        map "content", to: :content
+      end
+
+      def self.cast(value)
+        return value if value.is_a?(self)
+
+        new(content: value.to_s)
+      end
+    end
+  end
+
+  let(:plain_class) do
+    Class.new(Lutaml::Model::Serializable) do
+      attribute :content, :string
+
+      key_value do
+        map "content", to: :content
+      end
+    end
+  end
+
+  let(:holder_class) do
+    Class.new(Lutaml::Model::Serializable) do
+      attribute :description, "ScalarMarked"
+      attribute :plain_desc, "ScalarPlain"
+
+      key_value do
+        map "description", to: :description
+        map "plain_desc", to: :plain_desc
+      end
+    end
+  end
+
+  before do
+    stub_const("ScalarMarked", marked_class)
+    stub_const("ScalarPlain", plain_class)
+    stub_const("ScalarHolder", holder_class)
+  end
+
+  it "constructs the mapped value through the type's .cast" do
+    model = ScalarHolder.from_json('{"description": "text"}')
+
+    expect(model.description).to be_a(ScalarMarked)
+    expect(model.description.content).to eq("text")
+  end
+
+  it "falls through to the format parse error for a cast-less mapped type" do
+    expect { ScalarHolder.from_json('{"plain_desc": "text"}') }
+      .to raise_error(
+        Lutaml::Model::InvalidFormatError,
+        /unexpected token 'text'/,
+      )
+  end
+end

data/spec/lutaml/model/singular_tolerance_spec.rb

@@ -0,0 +1,159 @@
+# frozen_string_literal: true
+
+require "spec_helper"
+
+# #971: a singular attribute may ask ingest to keep the leading value
+# when the mapper collects more than one element (relaton's upstream
+# bibitems carry multiple <formattedref> elements). Default stays
+# strict: the over-count remains a CollectionTrueMissingError.
+RSpec.describe "singular_tolerance attribute option" do
+  let(:item_class) do
+    Class.new(Lutaml::Model::Serializable) do
+      attribute :content, :string
+    end
+  end
+
+  before do
+    stub_const("ToleranceItem", item_class)
+  end
+
+  describe "option validation" do
+    it "accepts :first" do
+      expect do
+        Lutaml::Model::Attribute.new(:ref, "ToleranceItem",
+                                     singular_tolerance: :first)
+      end.not_to raise_error
+    end
+
+    it "accepts omission (strict default)" do
+      expect do
+        Lutaml::Model::Attribute.new(:ref, "ToleranceItem")
+      end.not_to raise_error
+    end
+
+    it "rejects unsupported tolerances" do
+      expect do
+        Lutaml::Model::Attribute.new(:ref, "ToleranceItem",
+                                     singular_tolerance: :last)
+      end.to raise_error(ArgumentError, /singular_tolerance: :last/)
+    end
+  end
+
+  describe "#tolerates_singular_overflow?" do
+    let(:tolerant) do
+      Lutaml::Model::Attribute.new(:ref, "ToleranceItem",
+                                   singular_tolerance: :first)
+    end
+
+    let(:strict) { Lutaml::Model::Attribute.new(:ref, "ToleranceItem") }
+
+    let(:collection_attr) do
+      Lutaml::Model::Attribute.new(:refs, "ToleranceItem",
+                                   collection: true,
+                                   singular_tolerance: :first)
+    end
+
+    it "is true for an over-ingested collection on a tolerant singular" do
+      expect(tolerant.tolerates_singular_overflow?([1, 2])).to be(true)
+    end
+
+    it "is false without the option" do
+      expect(strict.tolerates_singular_overflow?([1, 2])).to be(false)
+    end
+
+    it "is false for a scalar on a tolerant singular" do
+      expect(tolerant.tolerates_singular_overflow?(1)).to be(false)
+    end
+
+    it "is false for a collection attribute — the option does not apply" do
+      expect(collection_attr.tolerates_singular_overflow?([1, 2])).to be(false)
+    end
+  end
+
+  describe "strict default" do
+    it "still raises CollectionTrueMissingError on over-ingest" do
+      attr = Lutaml::Model::Attribute.new(:ref, "ToleranceItem")
+
+      expect do
+        attr.valid_collection!([item_class.new, item_class.new], String)
+      end.to raise_error(Lutaml::Model::CollectionTrueMissingError)
+    end
+  end
+
+  describe "tolerant ingest" do
+    it "lets valid_collection! pass after the transform reduces to first" do
+      attr = Lutaml::Model::Attribute.new(:ref, "ToleranceItem",
+                                          singular_tolerance: :first)
+      value = [item_class.new, item_class.new]
+
+      reduced = value.first if attr.tolerates_singular_overflow?(value)
+      expect(attr.valid_collection!(reduced, String)).to be(true)
+      expect(reduced).to eq(value.first)
+    end
+  end
+
+  describe "on the KeyValue lane" do
+    let(:marked_class) do
+      Class.new(Lutaml::Model::Serializable) do
+        attribute :content, :string
+
+        key_value do
+          map "content", to: :content
+        end
+      end
+    end
+
+    let(:relation_class) do
+      Class.new(Lutaml::Model::Serializable) do
+        attribute :rel_type, :string
+        attribute :description, "ToleranceMarked", singular_tolerance: :first
+
+        key_value do
+          map "type", to: :rel_type
+          map "description", to: :description
+        end
+      end
+    end
+
+    before do
+      stub_const("ToleranceMarked", marked_class)
+      stub_const("ToleranceRelation", relation_class)
+    end
+
+    it "keeps the leading value on ingest instead of the whole array" do
+      model = ToleranceRelation.from_yaml(
+        "---\ntype: cites\ndescription:\n  - content: First\n  - content: Second\n",
+      )
+
+      expect(model.description).to be_a(ToleranceMarked)
+      expect(model.description.content).to eq("First")
+    end
+
+    it "round-trips the collapsed singular through to_yaml" do
+      model = ToleranceRelation.from_yaml(
+        "---\ntype: cites\ndescription:\n  - content: First\n  - content: Second\n",
+      )
+
+      yaml = model.to_yaml
+      expect(yaml).to include("First")
+      expect(yaml).not_to include("Second")
+      expect(ToleranceRelation.from_yaml(yaml).description.content).to eq("First")
+    end
+
+    it "collapses an over-assigned collection at serialization" do
+      model = ToleranceRelation.new(
+        rel_type: "cites",
+        description: [ToleranceMarked.new(content: "One"),
+                      ToleranceMarked.new(content: "Two")],
+      )
+
+      yaml = model.to_yaml
+      expect(yaml).to include("One")
+      expect(yaml).not_to include("Two")
+    end
+  end
+end
+
+# The KV mirror of the XML-lane cases: the YAML lane never consulted
+# the tolerance — ingest stored the whole array and re-serialization
+# raised the mapped-PORO type check.

data/spec/lutaml/model/unregistered_context_resolution_spec.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+require "spec_helper"
+
+# Register ids and type-context ids are two namespaces that
+# GlobalContext#resolve_type bridges implicitly: an id present only in the
+# Register namespace (a flavor's `lutaml_default_register`) resolves to a
+# nil type context, and every resolution shape must treat that as a
+# legitimate "no namespace" input instead of crashing (metanorma-jis#531).
+RSpec.describe "type resolution through a register id with no registered type context" do
+  let(:collection_class) do
+    Class.new(Lutaml::Model::Collection) do
+      instances :entries, :string
+    end
+  end
+
+  it "resolves collection instance types under a nil context" do
+    collection = collection_class.new(["a"], lutaml_register: :jis_document)
+
+    expect(collection.entries).to eq(["a"])
+  end
+
+  it "resolves built-in symbol names under a nil context" do
+    resolved = Lutaml::Model::GlobalContext.resolve_type(:string, :jis_document)
+
+    expect(resolved).to eq(Lutaml::Model::Type::String)
+  end
+
+  it "raises UnknownTypeError for unknown names under a nil context" do
+    expect do
+      Lutaml::Model::GlobalContext.resolve_type(:no_such_type, :jis_document)
+    end.to raise_error(Lutaml::Model::UnknownTypeError)
+  end
+end

data/spec/lutaml/model/yeptris_native_detection_spec.rb

@@ -0,0 +1,83 @@
+# frozen_string_literal: true
+
+require "spec_helper"
+require "open3"
+require "lutaml/json/adapter/yeptris_adapter"
+
+# Surface 1 of #978: the yeptris lane was selected from a bare
+# constant check, so a process holding a half-initialized Yeptris
+# module (the poison-process state the gem documents) committed to
+# the native lane and failed pre-mapping on valid JSON — while other
+# processes fell back to the standard lane, flipping the adapter
+# choice across runs. Detection now probes the native engine; a
+# broken native deterministically rides the standard lane.
+RSpec.describe Lutaml::Model::AdapterResolver, ".adapter_for yeptris native detection" do
+  let(:parse_probe) do
+    <<~RUBY
+      require "lutaml/model"
+
+      klass = Class.new(Lutaml::Model::Serializable) do
+        attribute :v, :string
+        key_value { map "v", to: :v }
+      end
+
+      model = klass.from_json('{"v": "scalar"}')
+      adapter = Lutaml::Model::AdapterResolver.adapter_for(:json)
+      puts "ADAPTER=\#{adapter.name.split('::').last} PARSED=\#{model.v}"
+    RUBY
+  end
+
+  def subprocess_yeptris_capable?
+    probe = <<~RUBY
+      begin
+        require "yeptris"
+        exit(0)
+      rescue LoadError
+        exit(1)
+      end
+    RUBY
+    _out, _err, status = Open3.capture3(RbConfig.ruby, "-I", "lib", "-e", probe)
+    status.success?
+  end
+
+  it "resolves the yeptris lane when the native engine answers a probe" do
+    skip "optional yeptris engine not resolvable outside the bundle" unless subprocess_yeptris_capable?
+
+    stdout, stderr, status = Open3.capture3(RbConfig.ruby, "-I", "lib", "-e", parse_probe)
+    expect(status).to be_success, stderr
+    expect(stdout).to include("ADAPTER=YeptrisAdapter")
+    expect(stdout).to include("PARSED=scalar")
+  end
+
+  it "falls back to the standard lane when the native engine cannot parse" do
+    poison = <<~RUBY
+      require "lutaml/model"
+      require "yeptris"
+      require "lutaml/json/adapter/yeptris_adapter"
+
+      # The poison state: the module is defined and require succeeds,
+      # but every native parse fails. Whatever the cause (a stale
+      # libyeptris, a half-initialized load), the lane must not be
+      # selected.
+      Lutaml::Json::Adapter::YeptrisAdapter
+        .define_singleton_method(:native_ready?) { false }
+
+      #{parse_probe}
+    RUBY
+
+    stdout, stderr, status = Open3.capture3(RbConfig.ruby, "-I", "lib", "-e", poison)
+    expect(status).to be_success, stderr
+    expect(stdout).to include("ADAPTER=StandardAdapter")
+    expect(stdout).to include("PARSED=scalar")
+  end
+
+  it "reports the adapter unavailable when the native probe fails" do
+    allow(Lutaml::Json::Adapter::YeptrisAdapter)
+      .to receive(:native_ready?).and_return(false)
+
+    expect(Lutaml::Json::Adapter::YeptrisAdapter.available?).to be(false)
+  ensure
+    allow(Lutaml::Json::Adapter::YeptrisAdapter)
+      .to receive(:native_ready?).and_call_original
+  end
+end

data/spec/lutaml/xml/adapter/empty_document_diagnostics_spec.rb

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+require "spec_helper"
+require "lutaml/xml/adapter/leptris_adapter"
+require "lutaml/xml/adapter/nokogiri_adapter"
+
+# A failed parse reaches the empty-document guard as a document with no
+# root, indistinguishable from genuinely empty input. The engine's parse
+# diagnostics ride the document (moxml attachments :parse_errors) and
+# must surface in the raised message — otherwise the error names the
+# input's emptiness while the input is neither empty nor the problem
+# (lutaml-model#956).
+#
+# moxml#369 changed the recoverable-malformation contract: the leptris
+# adapter's non-strict parse now RECOVERS (the engine's recover mode,
+# leptris#1660) and returns the best-effort tree instead of failing —
+# a mismatched closer yields a document, not a raise. Only inputs with
+# nothing to recover into (whitespace-only) still reach the guard,
+# carrying the recovery diagnostic.
+RSpec.describe "empty-document errors surface engine parse diagnostics" do
+  describe Lutaml::Xml::Adapter::LeptrisAdapter do
+    it "returns a recovered tree for recoverable malformations (moxml#369)" do
+      version = Gem.loaded_specs.fetch("moxml").version
+      recovered = version >= Gem::Version.new("0.5.131")
+      unless recovered
+        skip "moxml predates the recover-mode wiring (0.5.131)"
+      end
+
+      doc = described_class.parse("<root><a>x</b></root>")
+      expect(doc.root.name).to eq("root")
+    end
+
+    it "reports the engine diagnostic for whitespace-only input" do
+      expect do
+        described_class.parse("   ")
+      end.to raise_error(Lutaml::Model::InvalidFormatError, /the XML engine reported:/)
+    end
+  end
+
+  describe Lutaml::Xml::Adapter::NokogiriAdapter do
+    it "keeps the plain empty-document message when the engine reported nothing" do
+      expect do
+        described_class.parse("")
+      end.to raise_error(Lutaml::Model::InvalidFormatError) do |error|
+        expect(error.message).to include("The XML may be empty")
+        expect(error.message).not_to include("the XML engine reported:")
+      end
+    end
+  end
+end