moxml 0.5.100 → 0.5.101

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: a421da0e82158a69de2d25328346153be526d74c6d2bc2bad732427763b175c1
-  data.tar.gz: c9d982a98b2ce4984b3ee8659e89f2a4d86484d7e39fec4c04221bd2767473eb
+  metadata.gz: 9109c62e1dc81916376846aa35756d02e7caa0caedbf96937c6c89fb99687389
+  data.tar.gz: cab100fc1e408a0c511d330c81bc5f2b71e8dc0f6fa30e2c1b7a7e094d1c81a1
 SHA512:
-  metadata.gz: 2a3c9a536530f058a8c0a7721a3f192d89be195df277e959d746f2b6360db2da3587c2467fc21222aff85b96c8c3483a6a59406554804e073b25336c6d5dfe17
-  data.tar.gz: 750f9751134a3c077bd103edb9b18b0de7ea179d0c27839f1dff22654d372d7eb989a55c154c09ee155ec64d386547885013320eefa4044cb7dccc994d309806
+  metadata.gz: d041b4af64d6fe7d0d87d129ce35053da5405ba23b866e7dd3ef8c7237a21b73ff60d9baefafacf39781d5691e44b95ec295fcfe9eb54fa5e2a091ed01ea6ab7
+  data.tar.gz: 2f21edaf882c65e3229c617eb5df04e49b0198de3133d968e898fa9ec9218d34b52c5f165791804aafb328bae55db20fddc80c0976d596c686e66630bbd0293d

data/lib/moxml/adapter/base.rb

@@ -146,6 +146,14 @@ module Moxml
           nil
         end
 
+        # Canonical node identity: adapters carrying more than one
+        # Ruby representation over one C node answer the representation
+        # the tree walk mints, so every wrap path resolves one wrapper
+        # per logical node (moxml#311). Default: the node is canonical.
+        def canonical_native(node)
+          node
+        end
+
         # Prefixed-attribute value fast path: adapters whose engine
         # resolves expanded-name (uri, local) lookups natively answer
         # the value here; others fall back to the resolver's

data/lib/moxml/adapter/leptris/document_parts.rb

@@ -48,7 +48,7 @@ module Moxml
           # equal?-based exclusion (canon's document-element skip)
           # silently breaks (issue #219). Mint-on-miss converges
           # both accessors on the same native object.
-          children.map! { |child| canonical_native(doc, child) } if NATIVE_READ_LAYER
+          children.map! { |child| native_twin(doc, child) } if NATIVE_READ_LAYER
           children
         end
 

data/lib/moxml/adapter/leptris.rb

@@ -168,6 +168,18 @@ module Moxml
       BINDING_OF_CAP = 8_192
 
       class << self
+        # WeakMap has no #clear — 0.5.100's valve crashed every parse
+        # crossing the cap on 3.4+ (NoMethodError). Replace the
+        # registry wholesale, type-preserving: the WeakMap flavor
+        # stays weak, the strong Hash keeps compare_by_identity.
+        def fresh_node_registry
+          if Context::WEAK_WRAPPERS
+            ObjectSpace::WeakMap.new
+          else
+            {}.compare_by_identity
+          end
+        end
+
         # native -> bridged binding node. The bridge object is
         # identity-stable for the native's lifetime (the binding's
         # per-document wrap cache), so repeat bridges — the write
@@ -187,7 +199,7 @@ module Moxml
           doc = doc_for(node)
           ptr = ::FFI::Pointer.new(node.address)
           bridged = ::Leptris::XML::Node.wrap(ptr, doc)
-          @binding_of.clear if @binding_of.size >= BINDING_OF_CAP
+          @binding_of = fresh_node_registry if @binding_of.size >= BINDING_OF_CAP
           @binding_of[node] = bridged unless bridged.nil?
           bridged
         end
@@ -428,7 +440,7 @@ module Moxml
           end
 
           def record_native_doc(root_native, doc)
-            @native_doc_roots.clear if @native_doc_roots.size >= NATIVE_DOC_ROOTS_CAP
+            @native_doc_roots = fresh_node_registry if @native_doc_roots.size >= NATIVE_DOC_ROOTS_CAP
             @native_doc_roots[root_native] = doc
           end
 
@@ -1511,7 +1523,7 @@ module Moxml
         # accessor converges on one native per node (issue #219).
         # Binding natives (Attribute/Attr, synthetic wrappers) and
         # docless nodes pass through unchanged.
-        def canonical_native(doc, node)
+        def native_twin(doc, node)
           return node unless node.is_a?(::Leptris::XML::Element)
 
           cache = doc.native_cache
@@ -1625,7 +1637,7 @@ module Moxml
             # Through the same address-keyed cache as the children
             # path: NativeNode.from alone mints a fresh object per
             # call on 1.9.163.x, splitting the wrappers (issue #219).
-            native = canonical_native(document, r)
+            native = native_twin(document, r)
             record_native_doc(native, document)
             return native
           end
@@ -1686,8 +1698,8 @@ module Moxml
           # convergence (#219) hands every accessor — children
           # included — the SAME native, so the wrapper identity
           # holds across later traversals.
-          canonical_native(doc,
-                           ::Leptris::XML::Node.wrap(::FFI::Pointer.new(addr), doc))
+          native_twin(doc,
+                      ::Leptris::XML::Node.wrap(::FFI::Pointer.new(addr), doc))
         end
 
         def attributes(element)
@@ -1839,6 +1851,7 @@ module Moxml
             node = to_binding(node)
             new_node = to_binding(new_node)
           end
+          pin_foreign_owner_document(node, new_node)
           # A PI inserted before the root lives at document level in
           # libleptris's model, not in the element tree.
           if new_node.is_a?(::Leptris::XML::ProcessingInstruction) &&
@@ -1864,6 +1877,7 @@ module Moxml
             node = to_binding(node)
             new_node = to_binding(new_node)
           end
+          pin_foreign_owner_document(node, new_node)
           return node.add_next_sibling(new_node) if node.is_a?(::Leptris::XML::Element)
 
           # Non-element receivers (Text/Comment/CDATA): the binding's
@@ -2118,6 +2132,29 @@ module Moxml
           engine_xpath(node, expression, namespaces)
         end
 
+        # Canonical node identity (moxml#311): the native layer and
+        # the binding layer hold separate Ruby objects over one C
+        # node, and only the native cache carries the tree-walk
+        # identity the @parent_node invalidation chain rides on.
+        # Resolve binding-layer nodes (xpath results, engine results)
+        # to the walked instance when one exists — a memoized
+        # children holder implies a prior walk, so a cache miss means
+        # no holder exists and the binding node is safe as-is.
+        def canonical_native(node)
+          return node unless NATIVE_READ_LAYER
+          return node if node.is_a?(::Leptris::XML::NativeNode)
+          return node unless node.is_a?(::Leptris::XML::Node)
+
+          doc = node.document
+          return node if doc.nil?
+
+          # Only a contract-carrying hit is the walked canonical —
+          # plain NN twins (entity references, #219 miss-mints) have
+          # no Identity class and keep the binding representation.
+          hit = doc.native_cache[node.c_ptr.address]
+          hit.is_a?(::Moxml::Node) ? hit : node
+        end
+
         def at_xpath(node, expression, namespaces = {})
           native = native_xpath(node, expression, namespaces, first_only: true)
           return native unless native.nil?
@@ -2194,7 +2231,8 @@ module Moxml
             # and frees in one C dispatch — no NodeSet container, no
             # AutoPointer (leptris-ruby TODO.perf/16). The module
             # object back means a scalar, whose wrap (and free)
-            # stays with wrap_xpath_first_result.
+            # stays with wrap_xpath_first_result. Identity resolution
+            # happens at the at_xpath boundary (bridge_xpath_node).
             return ::Leptris::XML::Searchable.wrap_xpath_first_result(
               document, result_ptr
             )

data/lib/moxml/cdata.rb

@@ -19,5 +19,8 @@ module Moxml
     def name
       "#cdata-section"
     end
+
+    # Nokogiri-compatible: renaming non-element nodes is a no-op
+    def name=(_value); end
   end
 end

data/lib/moxml/comment.rb

@@ -21,5 +21,8 @@ module Moxml
     def name
       "comment"
     end
+
+    # Nokogiri-compatible: renaming non-element nodes is a no-op
+    def name=(_value); end
   end
 end

data/lib/moxml/context.rb

@@ -74,6 +74,18 @@ module Moxml
       end
     end
 
+    # Children-memo generation: bumped by every tree mutation so
+    # per-wrapper children memos can self-invalidate even when the
+    # same logical node is reachable through multiple wrapper
+    # representations (native vs binding duality).
+    def children_generation
+      @children_generation ||= 0
+    end
+
+    def bump_children_generation
+      @children_generation = children_generation + 1
+    end
+
     def namespace_scope_generation
       @namespace_scope_generation
     end

data/lib/moxml/document.rb

@@ -113,6 +113,14 @@ module Moxml
       Wrappers::EntityReference.new(native, context)
     end
 
+    # Nokogiri-compatible: Document#name returns "document"
+    def name
+      "document"
+    end
+
+    # Nokogiri-compatible: renaming a document node is a no-op
+    def name=(_value); end
+
     def add_child(node)
       node = prepare_node(node)
 

data/lib/moxml/node.rb

@@ -74,6 +74,11 @@ module Moxml
     end
 
     def children
+      # Generation-checked memo: mutations bump the context counter, so
+      # this self-invalidates even when the same logical node is served
+      # by multiple wrapper representations (native vs binding duality).
+      @children = nil if @children_gen != context.children_generation
+      @children_gen = context.children_generation
       @children ||= begin
         # The wrapper's entity memo decides the marker split; the
         # adapter would otherwise re-derive it per call (a C parent
@@ -100,6 +105,7 @@ module Moxml
     end
 
     def add_child(node)
+      context.bump_children_generation
       node = prepare_node(node)
       adapter.add_child(@native, node.native)
       # Refresh native in case adapter changed identity (e.g., LibXML
@@ -116,20 +122,45 @@ module Moxml
     end
 
     def add_previous_sibling(node)
+      context.bump_children_generation
       node = prepare_node(node)
       adapter.add_previous_sibling(@native, node.native)
+      # Invalidate the parent's memoized children list. The wrapper-side
+      # @parent_node link is only set when this node was yielded through a
+      # parent-aware NodeSet; nodes obtained via at()/xpath() carry no such
+      # link, so resolve the parent wrapper from the adapter instead.
+      parent&.invalidate_children_cache!
       invalidate_parent_children_cache!
       self
     end
 
+    # Nokogiri-compatible assignment forms: node.next = / node.previous =.
+    # String operands are parsed as XML fragments, like Nokogiri.
+    def next=(node)
+      add_next_sibling(sibling_operand(node))
+    end
+
+    def previous=(node)
+      add_previous_sibling(sibling_operand(node))
+    end
+
+    def sibling_operand(node)
+      return node unless node.is_a?(String)
+
+      context.parse_fragment(node).first
+    end
+
     def add_next_sibling(node)
+      context.bump_children_generation
       node = prepare_node(node)
       adapter.add_next_sibling(@native, node.native)
+      parent&.invalidate_children_cache!
       invalidate_parent_children_cache!
       self
     end
 
     def remove
+      context.bump_children_generation
       invalidate_parent_children_cache!
       adapter.remove(@native)
       invalidate_children_cache!
@@ -143,6 +174,7 @@ module Moxml
     def invalidate_namespace_cache!; end
 
     def replace(node)
+      context.bump_children_generation
       node = prepare_node(node)
       invalidate_parent_children_cache!
       adapter.replace(@native, node.native)
@@ -215,6 +247,42 @@ module Moxml
                        context)
     end
 
+    # Nokogiri-compatible sugar: at/search/at_css/css. Nokogiri's
+    # at/search auto-detect XPath vs CSS; the XPath-first fallback
+    # covers the dominant caller shape (XPath expression strings)
+    # while css/at_css serve stylesheet-style selectors.
+    def at(expression, namespaces = {})
+      at_css_or_xpath(expression, namespaces)
+    end
+
+    def search(expression, namespaces = {})
+      xpath(expression, namespaces)
+    end
+
+    def css(_expression)
+      raise Moxml::NotImplementedError,
+            "CSS selectors are not supported; use search with XPath"
+    end
+
+    def at_css(_expression)
+      raise Moxml::NotImplementedError,
+            "CSS selectors are not supported; use at with XPath"
+    end
+
+    def at_css_or_xpath(expression, namespaces = {})
+      at_xpath(expression, namespaces)
+    end
+
+    # Nokogiri-compatible depth-first traversal: yields self, then
+    # children recursively (document-order visitor).
+    def traverse(&block)
+      return to_enum(:traverse) unless block
+
+      yield self
+      children.each { |child| child.traverse(&block) }
+      self
+    end
+
     # Convenience find methods (aliases for xpath methods)
     def find(xpath_expression, namespaces = {})
       at_xpath(xpath_expression, namespaces)
@@ -591,6 +659,13 @@ module Moxml
     def self.wrap_with(node, context, adapter)
       return nil if node.nil?
 
+      # One C node may have several Ruby representations (leptris
+      # native/binding duality, moxml#311); every wrap resolves to
+      # the canonical one so memo holders share one invalidation
+      # chain. A hit-only lookup: a memoized holder implies a prior
+      # walk, which is what populates the canonical map.
+      node = adapter.canonical_native(node)
+
       # Cache-stable binding nodes carry their wrapper directly
       # (#312): the binding's document-owned cache hands the SAME
       # node object for the engine node's whole lifetime, so an

data/lib/moxml/text.rb

@@ -33,5 +33,8 @@ module Moxml
     def name
       "text"
     end
+
+    # Nokogiri-compatible: renaming non-element nodes is a no-op
+    def name=(_value); end
   end
 end

data/lib/moxml/version.rb

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

data/spec/moxml/adapter/leptris_binding_cap_spec.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+require "spec_helper"
+
+# 0.5.100's cap valves called .clear on the registry — an
+# ObjectSpace::WeakMap in weak-wrapper mode (Ruby 3.4+) has no
+# #clear, so the first parse crossing 8,192 bridges crashed with
+# NoMethodError. The valve replaces the registry wholesale now.
+RSpec.describe "leptris binding registry cap valve" do
+  let(:ctx) { Moxml.new(:leptris) }
+  let(:doc) do
+    ctx.parse("<r>#{Array.new(8_300) { |i| "<e#{i}/>" }.join}</r>")
+  end
+
+  it "bridges past the cap" do
+    children = doc.root.children.to_a
+    expect(children.size).to be > 8_192
+
+    bridged = children.map { |child| Moxml::Adapter::Leptris.to_binding(child.native) }
+    expect(bridged.compact.size).to eq(children.size)
+  end
+
+  it "bridges stay identity-stable across the valve" do
+    children = doc.root.children.to_a
+    first_pass = children.map { |child| Moxml::Adapter::Leptris.to_binding(child.native) }
+    second_pass = children.map { |child| Moxml::Adapter::Leptris.to_binding(child.native) }
+    expect(first_pass.zip(second_pass).all? { |one, other| one.equal?(other) }).to be(true)
+  end
+end

data/spec/moxml/adapter/leptris_xpath_identity_spec.rb

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+require "spec_helper"
+
+# moxml#311: the native and binding layers hold separate Ruby objects
+# over one C node. An xpath-resolved node that failed to resolve to
+# the tree-walk identity carried no parent link, so sibling inserts
+# through it never invalidated the memoized children of wrappers
+# handed out before the query — the insert serialized but stayed
+# invisible through parent.children.
+RSpec.describe "leptris xpath nodes resolve canonical identity" do
+  let(:ctx) { Moxml.new(:leptris) }
+  let(:doc) { ctx.parse("<r><a>t</a>\n<b/></r>") }
+
+  it "at_xpath returns the walked wrapper" do
+    root = doc.root
+    walked = root.children.first
+    expect(root.at_xpath("a")).to be(walked)
+  end
+
+  it "xpath list results resolve canonical identity" do
+    root = doc.root
+    walked = root.children.first
+    expect(root.xpath("a").first).to be(walked)
+  end
+
+  it "namespace-bound at_xpath resolves canonical identity" do
+    root = doc.root
+    walked = root.children.first
+    expect(root.at_xpath("a", "xmlns" => "http://x")).to be(walked)
+  end
+
+  it "sibling insert through at_xpath resolves in parent.children" do
+    root = doc.root
+    root.children
+    a = root.at_xpath("a")
+    a.add_next_sibling(ctx.parse_fragment("<x/>").first)
+    expect(root.children.map(&:name)).to eq(%w[a x text b])
+  end
+
+  it "sibling insert through the engine path resolves in parent.children" do
+    root = doc.root
+    root.children
+    walked = root.children.first
+    a = walked.at_xpath("self::a[parent::r]")
+    a.add_next_sibling(ctx.parse_fragment("<x/>").first)
+    expect(root.children.map(&:name)).to eq(%w[a x text b])
+  end
+end

data/spec/moxml/at_search_spec.rb

@@ -0,0 +1,85 @@
+# frozen_string_literal: true
+
+require "spec_helper"
+
+RSpec.describe "Nokogiri-compatible node sugar" do
+  describe "at/search" do
+    let(:doc) do
+      Moxml.parse(<<~XML)
+        <root xmlns="http://example.com/ns">
+          <item id="a"><name>one</name></item>
+          <item id="b"><name>two</name></item>
+        </root>
+      XML
+    end
+    let(:ns) { { "xmlns" => "http://example.com/ns" } }
+
+    it "at returns the first match like Nokogiri" do
+      node = doc.at("//xmlns:item", ns)
+      expect(node["id"]).to eq("a")
+    end
+
+    it "at on document delegates to root search" do
+      expect(doc.at("//xmlns:name", ns).text).to eq("one")
+    end
+
+    it "search returns all matches" do
+      expect(doc.search("//xmlns:item", ns).size).to eq(2)
+    end
+
+    it "at returns nil when nothing matches" do
+      expect(doc.at("//xmlns:missing", ns)).to be_nil
+    end
+
+    it "at works on element nodes" do
+      item = doc.at("//xmlns:item[@id='b']", ns)
+      expect(item.at("xmlns:name", ns).text).to eq("two")
+    end
+  end
+
+  describe "Node#traverse" do
+    it "yields depth-first in document order from an element" do
+      doc = Moxml.parse("<r><a><b/></a><c/></r>")
+      names = []
+      doc.root.traverse { |n| names << n.name }
+      expect(names).to eq(%w[r a b c])
+    end
+
+    it "yields the document first from a document traversal" do
+      doc = Moxml.parse("<r><a/></r>")
+      names = []
+      doc.traverse { |n| names << n.name }
+      expect(names).to eq(%w[document r a])
+    end
+  end
+
+  describe "Node#next=/previous=" do
+    it "insert a sibling after/before via assignment" do
+      doc = Moxml.parse("<r><a/><b/></r>")
+      a = doc.at("//a")
+      a.next = "<x/>"
+      expect(doc.root.children.map(&:name)).to eq(%w[a x b])
+      b = doc.at("//b")
+      b.previous = "<y/>"
+      expect(doc.root.children.map(&:name)).to eq(%w[a x y b])
+    end
+  end
+
+  describe "sibling inserts invalidate the parent children cache" do
+    it "next= is visible through parent.children when siblings are text" do
+      doc = Moxml.parse("<r><a/>\n<b/></r>")
+      doc.at("//a").next = "<x/>"
+      expect(doc.root.children.map(&:name)).to eq(%w[a x text b])
+      expect(doc.at("//x")).not_to be_nil
+    end
+
+    it "duality-proof: insert visible through a wrapper that memoized earlier" do
+      ctx = Moxml.new(:leptris)
+      doc = ctx.parse("<r><a/>\n<b/></r>")
+      doc.root.children.map(&:name)          # memoize on the root wrapper
+      a = doc.at("//a")                      # possibly a different wrapper instance
+      a.next = "<x/>"
+      expect(doc.root.children.map(&:name)).to eq(%w[a x text b])
+    end
+  end
+end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: moxml
 version: !ruby/object:Gem::Version
-  version: 0.5.100
+  version: 0.5.101
 platform: ruby
 authors:
 - Ribose Inc.
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2026-10-01 00:00:00.000000000 Z
+date: 2026-10-02 00:00:00.000000000 Z
 dependencies: []
 description: |
   Moxml is a unified XML manipulation library that provides a common API
@@ -441,12 +441,14 @@ files:
 - spec/moxml/adapter/entity_restoration_spec.rb
 - spec/moxml/adapter/headed_ox_spec.rb
 - spec/moxml/adapter/leptris_append_gc_spec.rb
+- spec/moxml/adapter/leptris_binding_cap_spec.rb
 - spec/moxml/adapter/leptris_doc_parts_spec.rb
 - spec/moxml/adapter/leptris_parse_skips_spec.rb
 - spec/moxml/adapter/leptris_record_driver_spec.rb
 - spec/moxml/adapter/leptris_sax_dup_attr_spec.rb
 - spec/moxml/adapter/leptris_sax_records_spec.rb
 - spec/moxml/adapter/leptris_spec.rb
+- spec/moxml/adapter/leptris_xpath_identity_spec.rb
 - spec/moxml/adapter/libxml_internals_spec.rb
 - spec/moxml/adapter/libxml_spec.rb
 - spec/moxml/adapter/nokogiri_spec.rb
@@ -459,6 +461,7 @@ files:
 - spec/moxml/adapter_spec.rb
 - spec/moxml/allocation_benchmark_spec.rb
 - spec/moxml/allocation_guard_spec.rb
+- spec/moxml/at_search_spec.rb
 - spec/moxml/attribute_resolver_spec.rb
 - spec/moxml/attribute_spec.rb
 - spec/moxml/builder_spec.rb