moxml 0.5.170 → 0.5.171

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 68f6b7acd8107269dc0e15246d3990ef57d3afaa0516896c43fa2db3acfc4cc5
-  data.tar.gz: b6511730c2af6f71b66b1a07b118260fc76c6069bd000be29539beb7462522b5
+  metadata.gz: dd5e790791e306829e87770a45424b006c9a535c95c825adfc7d0800816ceb7d
+  data.tar.gz: c3348f9fb7c6c0ccf00ab4bc16bba51b0812331d12d8478d2a77e09b8a600e58
 SHA512:
-  metadata.gz: b3c3f675bc7ecc526414d7cf045e33dbbcd14ff4b52794552a7ccd4d69b6efab0e3bf14cf5d56e05e3b48e7852795a6a9181ac15c98504233dac324c0c54a6ec
-  data.tar.gz: 47fdcc6d4e46766f75bf4927b89ae95931d8920e0fc5f8213a48167b2f5b19ded9f1807bbf13c2351e8735e71e3210f7829f913a7bbb2a82781ca88a68405729
+  metadata.gz: 2972a94dc0bf75896d29432c1856b949090cbd8547b60c402376f2d715c743c8e029af2181531fbd327d6615a3a6aef5cb83144c5ff2b6389f35bd3ab6dfea59
+  data.tar.gz: c89e1be189130b17f0a7f61c67c9caba0624f589c29a2407effba7fb50da72304d33db77001185cb7b079729a7a29140d32e8a492269a58cf748a8e99f0276a2

data/README.adoc

@@ -95,7 +95,8 @@ adapter refuses to load below its floor.
 
 |Ox
 |>= 2.14
-|Tested against the 2.14 line.
+|DEPRECATED (#491) — warned at configuration; use :leptris (primary)
+or :nokogiri. Removal after the deprecation cycle.
 
 |Oga
 |3.4 / 3.5
@@ -105,8 +106,9 @@ moxml's customized generator and decoder overrides.
 
 |LibXML (libxml-ruby)
 |>= 5.0
-|6.x works and is the installed default on Ruby >= 3.2 (libxml-ruby
-6.0 itself requires Ruby >= 3.2); Ruby 3.1 resolves 5.x.
+|DEPRECATED (#491) — warned at configuration; use :nokogiri (the
+same libxml2 engine, governed by the consistency suite). Removal
+after the deprecation cycle.
 
 |Leptris (leptris-ruby)
 |>= 1.9.194.1
@@ -114,10 +116,7 @@ moxml's customized generator and decoder overrides.
 Raised from 1.9.32 (2026-09-20): every known consumer resolves a
 modern binding, and the sub-1.9.194 accommodation paths are deleted.
 Newer bindings unlock more native surface automatically:
-1.9.163.7+ single-result XPath seams, 1.9.174.4+ C-minted identity
-wrappers, 1.9.174.6+ one-dispatch subtree walks, 1.9.177+ first-class
-entity references (`entity_mode: :keep`), 1.9.193.4+ native plan rows
-(`Moxml::Plan`), 1.9.194.1+ hot-read aliases, 1.9.201.1+ the C struct
+1.9.194.1+ hot-read aliases, 1.9.201.1+ the C struct
 executor (`Moxml::StructPlan`; the floor is the varargs-mint fix),
 1.9.204+ native document-level parts (created DOCTYPEs as native
 nodes, document-PI removal, declaration clear), 1.9.240+ the bulk

data/lib/moxml/adapter/leptris.rb

@@ -41,8 +41,7 @@ module Moxml
       # leptris_node_digest shipped in bindings 1.9.99 (libleptris
       # 1.9.99, engine #869): on-demand Merkle subtree hash, zero
       # cost when unused. Below it, Node#digest answers nil.
-      DIGEST_SUPPORTED =
-        Gem::Version.new(::Leptris::VERSION) >= Gem::Version.new("1.9.99")
+      DIGEST_SUPPORTED = true
 
       # 1.9.163.7 added the XPath seams (TODO.perf/15+16):
       # Searchable#at_xpath materializes nodeset entry 0 and frees
@@ -52,8 +51,7 @@ module Moxml
       # raw pointers, skipping the per-call EvaluationContext
       # (~2us on every multi-result query).
       NATIVE_XPATH_SEAMS =
-        defined?(::Leptris::XML::Native) &&
-        Gem::Version.new(::Leptris::VERSION) >= Gem::Version.new("1.9.163.7")
+        defined?(::Leptris::XML::Native)
 
       # Opt-in native read layer (leptris-ruby#185, bindings >= 1.9.162.6):
       # TypedData node wrappers with C-bound hot reads and bulk
@@ -68,8 +66,7 @@ module Moxml
         nil
       end
       NATIVE_READ_LAYER =
-        defined?(::Leptris::XML::NativeNode) &&
-        Gem::Version.new(::Leptris::VERSION) >= Gem::Version.new("1.9.162.6")
+        defined?(::Leptris::XML::NativeNode)
 
       # leptris-ruby#529: the whole XPath node-set result as an Array
       # of registered natives in ONE C crossing (Document#
@@ -118,8 +115,7 @@ module Moxml
       # (1.9.162.x answered ASCII-8BIT — the reads retagged with a
       # dup+force_encoding per call).
       NATIVE_STRINGS_UTF8 =
-        defined?(::Leptris::XML::NativeNode) &&
-        Gem::Version.new(::Leptris::VERSION) >= Gem::Version.new("1.9.163.2")
+        defined?(::Leptris::XML::NativeNode)
 
       # 1.9.163.5 (leptris-ruby#204/#208): native mutations are
       # version-coherent with the binding (both surfaces' memos
@@ -127,8 +123,7 @@ module Moxml
       # add_child are adoptable end-to-end; NativeNode grew a
       # document accessor and line numbers.
       NATIVE_MUTATIONS_COHERENT =
-        defined?(::Leptris::XML::NativeNode) &&
-        Gem::Version.new(::Leptris::VERSION) >= Gem::Version.new("1.9.163.5")
+        defined?(::Leptris::XML::NativeNode)
 
       # Identity mode (#230 stage 2): the contract modules extended
       # onto natives shadow the C surface (Element#[] over
@@ -170,16 +165,14 @@ module Moxml
       # 1.9.181 (lockstep): Node#source_position — {line, col_start,
       # col_end} from the engine's source-position API (upstream
       # #1124); created nodes report zeros.
-      NATIVE_SOURCE_POSITION =
-        Gem::Version.new(::Leptris::VERSION) >= Gem::Version.new("1.9.181")
+      NATIVE_SOURCE_POSITION = true
 
       # Entity-reference preservation (leptris-ruby#212 / upstream
       # #1094): 1.9.177 ships ParseOptions.keep_entity_refs plus
       # first-class EntityReference nodes — the marker machinery
       # becomes bypassable when the Context's entity_mode is :keep.
       NATIVE_ENTITY_REFS =
-        defined?(::Leptris::XML::EntityReference) &&
-        Gem::Version.new(::Leptris::VERSION) >= Gem::Version.new("1.9.177")
+        defined?(::Leptris::XML::EntityReference)
 
       # 1.9.163.2 moved the native bulk children into C
       # (Native.bulk_children) and fixed the 512 truncation
@@ -189,8 +182,7 @@ module Moxml
       # C bulk path (version-memoized, cheaper than a per-call
       # count+copy).
       NATIVE_BULK_FIXED =
-        defined?(::Leptris::XML::NativeNode) &&
-        Gem::Version.new(::Leptris::VERSION) >= Gem::Version.new("1.9.163.2")
+        defined?(::Leptris::XML::NativeNode)
 
       # Bulk SAX record drain (leptris#1298): leptris_sax_records_parse
       # + Leptris::XML::SAX::Records — one crossing per document,
@@ -552,17 +544,13 @@ module Moxml
         # classes do not exist. NATIVE_MUTATIONS_COHERENT is false
         # without the native layer, so all three evaluate false
         # there.
-        NATIVE_IDENTITY =
-          NATIVE_MUTATIONS_COHERENT &&
-          Gem::Version.new(::Leptris::VERSION) >= Gem::Version.new("1.9.174.4")
+        NATIVE_IDENTITY = NATIVE_MUTATIONS_COHERENT
 
         NATIVE_C_MINT =
           NATIVE_IDENTITY &&
           Gem::Version.new(::Leptris::VERSION) >= Gem::Version.new("1.9.255.2")
 
-        NATIVE_KLASS_CHILDREN =
-          NATIVE_IDENTITY &&
-          Gem::Version.new(::Leptris::VERSION) >= Gem::Version.new("1.9.193.2")
+        NATIVE_KLASS_CHILDREN = NATIVE_IDENTITY
       end
 
       if NATIVE_READ_LAYER
@@ -870,8 +858,7 @@ module Moxml
           end
 
           NATIVE_C_WALK =
-            defined?(::Leptris::XML::NativeNode) &&
-            Gem::Version.new(::Leptris::VERSION) >= Gem::Version.new("1.9.174.6")
+            defined?(::Leptris::XML::NativeNode)
 
           # One C visit walk (TODO.perf/27: post-order/abort state in
           # the C callback, rb_yield direct — no FFI closure per
@@ -1109,8 +1096,7 @@ module Moxml
       # on released 1.9.37–1.9.39; 1.9.40 (engine 1.9.14+) restored
       # the fallback. Older bindings keep the Ruby-engine routing in
       # native_expression?.
-      PREFIXED_ATTR_PREDICATES_NATIVE =
-        Gem::Version.new(::Leptris::VERSION) >= Gem::Version.new("1.9.40")
+      PREFIXED_ATTR_PREDICATES_NATIVE = true
 
       # leptris/leptris#636 (leptris-ruby 1.9.42): libxml2-compatible
       # pretty-print — child-PI lines, DOCTYPE internal-subset layout,
@@ -1118,8 +1104,7 @@ module Moxml
       # unit (`to_xml`'s indent_text takes the unit string). Older
       # floor bindings treat indent_text as a display-form boolean, so
       # the passthrough and the parity pins gate on this.
-      LIBXML2_LAYOUT_PARITY =
-        Gem::Version.new(::Leptris::VERSION) >= Gem::Version.new("1.9.42")
+      LIBXML2_LAYOUT_PARITY = true
 
       # leptris-ruby#109 (1.9.45): Element#to_xml takes the
       # indent-unit string, so moxml's per-child document composition
@@ -1127,13 +1112,11 @@ module Moxml
       # emit spaces until the engine fix (leptris/leptris#658); the
       # boolean display form stays document-level and is never
       # forwarded (the element face raises on it).
-      INDENT_UNIT_SUPPORTED =
-        Gem::Version.new(::Leptris::VERSION) >= Gem::Version.new("1.9.45")
+      INDENT_UNIT_SUPPORTED = true
 
       # leptris-ruby#115 (fixed 1.9.50): the element unit path keeps
       # child comments.
-      ELEMENT_UNIT_COMMENTS =
-        Gem::Version.new(::Leptris::VERSION) >= Gem::Version.new("1.9.50")
+      ELEMENT_UNIT_COMMENTS = true
 
       # leptris/leptris#677: the engine's DROP_WS_TEXT trims boundary
       # whitespace of non-blank text nodes. Probed at load rather

data/lib/moxml/adapter/nokogiri.rb

@@ -800,11 +800,19 @@ module Moxml
           @handler.on_end_document
         end
 
-        def start_element(name, attributes = [])
-          attr_hash, ns_hash = split_attributes_and_namespaces(attributes) do |v|
-            Moxml::Adapter::Base.decode_entities(v)
+        # libxml hands over namespace declaration URIs already decoded,
+        # while attribute values still carry their entity references;
+        # decoding the URIs again corrupts "&" into "&".
+        def start_element_namespace(name, attrs = [], prefix = nil, _uri = nil,
+                                    namespaces = [])
+          attr_hash = {}
+          attrs.each do |attr|
+            key = attr.prefix ? "#{attr.prefix}:#{attr.localname}" : attr.localname
+            attr_hash[key] = Moxml::Adapter::Base.decode_entities(attr.value)
           end
-          @handler.on_start_element(name, attr_hash, ns_hash)
+          ns_hash = namespaces.empty? ? EMPTY_NAMESPACES : namespaces.to_h
+          qualified = prefix ? "#{prefix}:#{name}" : name
+          @handler.on_start_element(qualified, attr_hash, ns_hash)
         end
 
         def end_element(name)

data/lib/moxml/adapter.rb

@@ -25,7 +25,27 @@ module Moxml
       headed_ox: "HeadedOx",
     }.freeze
 
+    # Adapters in their deprecation cycle (#491): warned once per
+    # process at configuration, removed after the cycle. The value is
+    # the migration guidance shown in the warning.
+    DEPRECATED_ADAPTERS = {
+      headed_ox: "use :leptris (primary) or :nokogiri; headed_ox is a pure alias of :ox",
+      libxml: "use :nokogiri — the same libxml2 engine, governed by the consistency suite",
+      ox: "use :leptris (primary) or :nokogiri",
+    }.freeze
+
     class << self
+      # One-time deprecation notice per adapter per process (#491).
+      def warn_deprecated!(name)
+        guidance = DEPRECATED_ADAPTERS[name.to_sym]
+        return unless guidance
+        return if (@deprecation_warned ||= {})[name.to_sym]
+
+        @deprecation_warned[name.to_sym] = true
+        warn "moxml: the :#{name} adapter is deprecated and will be " \
+             "removed; #{guidance}"
+      end
+
       def load(name)
         validate_platform!(name)
         require_adapter(name)

data/lib/moxml/context.rb

@@ -26,6 +26,7 @@ module Moxml
     attr_reader :config
 
     def initialize(adapter = nil)
+      Adapter.warn_deprecated!(adapter) if adapter
       @config = Config.new(adapter)
       # Bumped on any namespace-scope mutation; Element scope caches
       # compare against it so every wrapper sees changes without

data/lib/moxml/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Moxml
-  VERSION = "0.5.170"
+  VERSION = "0.5.171"
 end

data/spec/moxml/adapter_deprecation_spec.rb

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+require "spec_helper"
+
+RSpec.describe Moxml::Adapter do
+  describe ".warn_deprecated!" do
+    # The once-per-process state is module-level; isolate each
+    # example from prior loads and from later suites.
+    around do |example|
+      described_class.instance_variable_set(:@deprecation_warned, {})
+      example.run
+      described_class.instance_variable_set(:@deprecation_warned, {})
+    end
+
+    it "warns once per deprecated adapter per process" do
+      expect do
+        Moxml.new(:headed_ox)
+      end.to output(%r{:headed_ox adapter is deprecated}).to_stderr
+      expect do
+        Moxml.new(:headed_ox)
+      end.not_to output.to_stderr
+    end
+
+    it "guides every deprecated adapter toward the governed matrix" do
+      described_class::DEPRECATED_ADAPTERS.each_value do |guidance|
+        expect(guidance).to match(/:nokogiri|:leptris/)
+      end
+    end
+
+    it "does not warn for the governed matrix" do
+      expect do
+        Moxml.new(:leptris)
+        Moxml.new(:nokogiri)
+      end.not_to output(/deprecated/).to_stderr
+    end
+
+    it "does not warn for unknown names" do
+      expect do
+        described_class.warn_deprecated!(:definitely_not_an_adapter)
+      end.not_to output.to_stderr
+    end
+
+    it "keeps the deprecated adapters loadable through the cycle" do
+      described_class::DEPRECATED_ADAPTERS.each_key do |name|
+        expect(described_class.available?(name)).to be(true)
+      end
+    end
+  end
+end

data/spec/moxml/sax_entity_parity_spec.rb

@@ -15,16 +15,18 @@ require "spec_helper"
 # the RSpec/* cops that forbid local-variable use inside examples.
 module SaxEntityParityFixtures
   class CaptureHandler < Moxml::SAX::ElementHandler
-    attr_reader :first_attrs, :text
+    attr_reader :first_attrs, :first_namespaces, :text
 
     def initialize
       super
       @first_attrs = nil
+      @first_namespaces = nil
       @text = +""
     end
 
-    def on_start_element(_name, attrs = {}, _namespaces = {})
+    def on_start_element(_name, attrs = {}, namespaces = {})
       @first_attrs = attrs.dup if @first_attrs.nil?
+      @first_namespaces = namespaces.dup if @first_namespaces.nil?
     end
 
     def on_characters(chunk)
@@ -51,6 +53,19 @@ module SaxEntityParityFixtures
     "no entities" => ['<doc x="plain"/>', "plain", "plain"],
   }.freeze
 
+  # Adapters whose SAX bridge reports namespace declarations in the
+  # handler's namespaces hash with the URI decoded exactly once.
+  SAX_NAMESPACE_ADAPTERS = %i[nokogiri ox rexml headed_ox].freeze
+
+  # Each row: [input XML, decoded namespace URI]. The parser decodes a
+  # declaration's URI exactly once; a decoded "&#38;" is data and must
+  # reach the handler as-is.
+  NAMESPACE_CASES = {
+    "wrapped amp + decimal ref" => ['<f:doc xmlns:f="http://f/?x=1&amp;#38;y"/>', "http://f/?x=1&#38;y"],
+    "wrapped amp + amp" => ['<f:doc xmlns:f="http://f/?x=&amp;amp;"/>', "http://f/?x=&amp;"],
+    "plain amp" => ['<f:doc xmlns:f="http://f/?x=1&amp;y=2"/>', "http://f/?x=1&y=2"],
+  }.freeze
+
   # Each row: [input XML, decoded text, expected text as it appears in
   # serialized XML].
   TEXT_CASES = {
@@ -138,6 +153,16 @@ RSpec.describe "SAX/DOM entity parity" do
         end
       end
 
+      if SaxEntityParityFixtures::SAX_NAMESPACE_ADAPTERS.include?(adapter)
+        SaxEntityParityFixtures::NAMESPACE_CASES.each do |label, (xml, expected)|
+          it "decodes namespace URI once via SAX: #{label}" do
+            handler = SaxEntityParityFixtures::CaptureHandler.new
+            ctx.sax_parse(xml, handler)
+            expect(handler.first_namespaces["f"]).to eq(expected)
+          end
+        end
+      end
+
       SaxEntityParityFixtures::TEXT_CASES.each do |label, (xml, expected, expected_serialized)|
         it "decodes text via SAX: #{label}" do
           handler = SaxEntityParityFixtures::CaptureHandler.new

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: moxml
 version: !ruby/object:Gem::Version
-  version: 0.5.170
+  version: 0.5.171
 platform: ruby
 authors:
 - Ribose Inc.
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2026-10-29 00:00:00.000000000 Z
+date: 2026-10-30 00:00:00.000000000 Z
 dependencies: []
 description: |
   Moxml is a unified XML manipulation library that provides a common API
@@ -512,6 +512,7 @@ files:
 - spec/moxml/adapter/rexml_spec.rb
 - spec/moxml/adapter/shared_examples/.gitkeep
 - spec/moxml/adapter/shared_examples/adapter_contract.rb
+- spec/moxml/adapter_deprecation_spec.rb
 - spec/moxml/adapter_spec.rb
 - spec/moxml/allocation_benchmark_spec.rb
 - spec/moxml/allocation_guard_spec.rb