moxml 0.1.13 → 0.1.15

data/spec/moxml/node_set_cache_spec.rb

@@ -0,0 +1,90 @@
+# frozen_string_literal: true
+
+require "spec_helper"
+require "support/allocation_helper"
+
+# NodeSet wrap caching correctness tests — these run in CI by default.
+# Verifies that NodeSet per-index wrap caching works correctly across adapters.
+RSpec.describe "Moxml NodeSet wrap caching" do
+  shared_examples "cached NodeSet wraps" do |adapter_name|
+    let(:ctx) { Moxml::Context.new(adapter_name) }
+    let(:xml) { "<root><a/><b/><c/></root>" }
+    let(:doc) { ctx.parse(xml) }
+
+    describe "NodeSet#each caching" do
+      it "returns the same wrapper object on repeated iteration" do
+        root = doc.root
+        first_pass = root.children.to_a
+        second_pass = root.children.to_a
+        # Since children itself is cached, the same NodeSet is returned.
+        # Within that NodeSet, wrapped nodes should be cached.
+        first_pass.each_with_index do |node, i|
+          expect(node).to equal(second_pass[i])
+        end
+      end
+
+      it "returns consistent node names" do
+        children = doc.root.children
+        names = children.map(&:name)
+        expect(names).to eq(%w[a b c])
+      end
+    end
+
+    describe "NodeSet#[] caching" do
+      it "returns the same wrapper for the same index" do
+        children = doc.root.children
+        first = children[0]
+        second = children[0]
+        expect(first).to equal(second)
+      end
+
+      it "returns the same wrapper from #[] as from #each" do
+        children = doc.root.children
+        from_each = children.to_a[1]
+        from_index = children[1]
+        expect(from_each).to equal(from_index)
+      end
+    end
+
+    describe "NodeSet#first/#last caching" do
+      it "returns the same wrapper from #first as from #[0]" do
+        children = doc.root.children
+        expect(children.first).to equal(children[0])
+      end
+
+      it "returns the same wrapper from #last as from #[-1]" do
+        children = doc.root.children
+        last_idx = children.size - 1
+        expect(children.last).to equal(children[last_idx])
+      end
+    end
+
+    describe "NodeSet mutation" do
+      it "appends to cache correctly" do
+        ns = doc.root.children
+        initial_size = ns.size
+        ns << ctx.parse("<d/>").root
+        expect(ns.size).to eq(initial_size + 1)
+        expect(ns[initial_size].name).to eq("d")
+      end
+
+      it "deletes from cache correctly" do
+        ns = doc.root.children
+        first_child = ns[0]
+        ns.delete(first_child)
+        expect(ns.size).to eq(2)
+        expect(ns[0].name).to eq("b")
+      end
+    end
+  end
+
+  AllocationHelper::GUARDED_ADAPTERS.each do |adapter_name|
+    describe "#{adapter_name} adapter" do
+      before(:all) do
+        skip("#{adapter_name} adapter not available") unless AllocationHelper.adapter_available?(adapter_name)
+      end
+
+      it_behaves_like "cached NodeSet wraps", adapter_name
+    end
+  end
+end

data/spec/moxml/xml_utils_spec.rb

@@ -46,4 +46,36 @@ RSpec.describe Moxml::XmlUtils do
                          "Invalid XML element name: 123invalid")
     end
   end
+
+  describe "#validate_prefix" do
+    it "accepts valid NCName prefixes" do
+      expect { utils.validate_prefix("xs") }.not_to raise_error
+      expect { utils.validate_prefix("my-ns") }.not_to raise_error
+      expect { utils.validate_prefix("a1") }.not_to raise_error
+    end
+
+    it "accepts prefixes containing dots (valid NCName NameChar)" do
+      expect { utils.validate_prefix("abc_1.0") }.not_to raise_error
+      expect { utils.validate_prefix("xmlns_1.0") }.not_to raise_error
+      expect { utils.validate_prefix("v2.0.1") }.not_to raise_error
+    end
+
+    it "rejects prefixes starting with a digit" do
+      expect do
+        utils.validate_prefix("1abc")
+      end.to raise_error(Moxml::ValidationError, /Invalid namespace prefix/)
+    end
+
+    it "rejects prefixes containing colons" do
+      expect do
+        utils.validate_prefix("a:b")
+      end.to raise_error(Moxml::ValidationError, /Invalid namespace prefix/)
+    end
+
+    it "rejects empty prefixes" do
+      expect do
+        utils.validate_prefix("")
+      end.to raise_error(Moxml::ValidationError, /Invalid namespace prefix/)
+    end
+  end
 end

data/spec/support/allocation_helper.rb

@@ -0,0 +1,165 @@
+# frozen_string_literal: true
+
+require "set"
+
+# Shared helper for allocation guard specs.
+#
+# Provides:
+# - Precise allocation counting via GC.stat
+# - Per-adapter threshold configuration
+# - Adapter availability checks
+# - Optional StackProf diagnostic on guard failure
+module AllocationHelper
+  # Adapters to guard in CI (ordered by importance).
+  # Skip REXML/LibXML — not used in production.
+  GUARDED_ADAPTERS = %i[nokogiri ox headed_ox oga].freeze
+
+  # Per-adapter allocation thresholds.
+  # Format: { operation => { adapter => max_allocations } }
+  #
+  # Thresholds calibrated at ~2x measured baseline (2026-04-18).
+  # All lazy-parse adapters (nokogiri, ox, headed_ox) share similar profiles.
+  # OGA is pure Ruby so naturally allocates more.
+  THRESHOLDS = {
+    # Parse a 100-element document (no subsequent access).
+    # Measured: nokogiri=299, ox=1003, headed_ox=1001, oga=8732
+    parse_100: {
+      nokogiri: 600,
+      ox: 2500,
+      headed_ox: 2500,
+      oga: 18_000,
+    },
+    # Parse a 50-element document.
+    # Measured: nokogiri=148, ox=501, headed_ox=501, oga=4365
+    parse_50: {
+      nokogiri: 300,
+      ox: 1200,
+      headed_ox: 1200,
+      oga: 9000,
+    },
+    # Access root.name after parse (lazy wrapping overhead).
+    # Measured: nokogiri=317, ox=1013, headed_ox=1009, oga=8673
+    parse_and_root: {
+      nokogiri: 700,
+      ox: 2500,
+      headed_ox: 2500,
+      oga: 18_000,
+    },
+    # First access to children (NodeSet construction).
+    first_children_access: {
+      nokogiri: 200,
+      ox: 200,
+      headed_ox: 200,
+      oga: 300,
+    },
+    # Second access to children (should be ~0 — cached).
+    # Measured: all adapters = 1-3
+    cached_children_access: {
+      nokogiri: 5,
+      ox: 5,
+      headed_ox: 5,
+      oga: 5,
+    },
+    # Second access to attributes (should be ~0 — cached).
+    # Measured: all adapters = 1
+    cached_attributes_access: {
+      nokogiri: 5,
+      ox: 5,
+      headed_ox: 5,
+      oga: 5,
+    },
+    # Second iteration of NodeSet (wrap cache hit).
+    # Measured: all adapters = 2
+    cached_iteration: {
+      nokogiri: 10,
+      ox: 10,
+      headed_ox: 10,
+      oga: 10,
+    },
+    # Parse + serialize round-trip (50 elements).
+    # Measured: nokogiri=222, ox=893, headed_ox=882, oga=9523
+    round_trip: {
+      nokogiri: 500,
+      ox: 2000,
+      headed_ox: 2000,
+      oga: 20_000,
+    },
+    # Ratio of allocations for 200-element vs 100-element parse.
+    # Must be <= max (linear growth). Quadratic would be > 4x.
+    # Measured: nokogiri=2.01, ox=2.0, headed_ox=2.0, oga=1.99
+    scalability_ratio: {
+      nokogiri: 2.5,
+      ox: 2.5,
+      headed_ox: 2.5,
+      oga: 2.5,
+    },
+  }.freeze
+
+  class << self
+    # Count object allocations during a block.
+    # Uses GC.stat[:total_allocated_objects] for precision.
+    def count_allocations
+      GC.start
+      GC.disable
+      before = GC.stat[:total_allocated_objects] || ObjectSpace.count_objects[:TOTAL]
+      result = yield
+      after = GC.stat[:total_allocated_objects] || ObjectSpace.count_objects[:TOTAL]
+      after - before
+    ensure
+      GC.enable
+      result
+    end
+
+    # Check if an adapter is available for testing.
+    def adapter_available?(adapter_name)
+      ctx = Moxml::Context.new(adapter_name)
+      ctx.parse("<root/>")
+      true
+    rescue StandardError
+      false
+    end
+
+    # Get the allocation threshold for an adapter + operation.
+    def threshold(adapter_name, operation)
+      THRESHOLDS.dig(operation, adapter_name) ||
+        raise(ArgumentError, "No threshold for #{adapter_name}/#{operation}")
+    end
+
+    # Run StackProf and return top hotspots as a diagnostic string.
+    # Tries :obj mode first (allocation profiling), falls back to :wall.
+    def profile_allocations(&block)
+      require "stackprof"
+
+      # :obj mode tracks object allocations but requires platform support.
+      # :wall mode tracks wall-clock time — less precise but always available.
+      result = begin
+        StackProf.run(mode: :obj, &block)
+      rescue ArgumentError
+        StackProf.run(mode: :wall, &block)
+      end
+      return nil unless result
+
+      frames = result[:frames]
+      total_samples = result[:samples]
+
+      hotspots = frames.sort_by { |_, f| -f[:samples] }.first(10)
+      lines = ["StackProf hotspot (#{total_samples} total samples):"]
+      hotspots.each do |name, frame|
+        pct = (frame[:samples].to_f / total_samples * 100).round(1)
+        lines << "  #{pct}% #{name} (#{frame[:samples]} samples)"
+      end
+      lines.join("\n")
+    rescue LoadError
+      "StackProf not available — add gem 'stackprof' to Gemfile"
+    end
+  end
+end
+
+# Generate a test XML document with N elements.
+# Each element has 2 attributes and nested text content.
+def generate_xml(element_count)
+  inner = Array.new(element_count) do |i|
+    "<elem#{i % 10} id=\"#{i}\" type=\"t#{i % 3}\">text#{i}</elem#{i % 10}>"
+  end.join
+  "<root>#{inner}</root>"
+end

data/spec/support/w3c_namespace_helpers.rb

@@ -2,7 +2,8 @@
 
 require "rexml/document"
 
-W3C_NS_FIXTURES_DIR = File.expand_path("../fixtures/w3c/namespaces/1.0", __dir__)
+W3C_NS_FIXTURES_DIR = File.expand_path("../fixtures/w3c/namespaces/1.0",
+                                       __dir__)
 
 # Parse the test catalog to get test metadata
 def load_w3c_namespace_tests

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: moxml
 version: !ruby/object:Gem::Version
-  version: 0.1.13
+  version: 0.1.15
 platform: ruby
 authors:
 - Ribose Inc.
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2026-04-20 00:00:00.000000000 Z
+date: 2026-04-22 00:00:00.000000000 Z
 dependencies: []
 description: |
   Moxml is a unified XML manipulation library that provides a common API
@@ -99,18 +99,25 @@ files:
 - lib/moxml.rb
 - lib/moxml/adapter.rb
 - lib/moxml/adapter/base.rb
+- lib/moxml/adapter/customized_libxml.rb
 - lib/moxml/adapter/customized_libxml/cdata.rb
 - lib/moxml/adapter/customized_libxml/comment.rb
 - lib/moxml/adapter/customized_libxml/declaration.rb
 - lib/moxml/adapter/customized_libxml/element.rb
+- lib/moxml/adapter/customized_libxml/entity_reference.rb
 - lib/moxml/adapter/customized_libxml/node.rb
 - lib/moxml/adapter/customized_libxml/processing_instruction.rb
 - lib/moxml/adapter/customized_libxml/text.rb
+- lib/moxml/adapter/customized_oga.rb
 - lib/moxml/adapter/customized_oga/xml_declaration.rb
 - lib/moxml/adapter/customized_oga/xml_generator.rb
+- lib/moxml/adapter/customized_ox.rb
 - lib/moxml/adapter/customized_ox/attribute.rb
+- lib/moxml/adapter/customized_ox/entity_reference.rb
 - lib/moxml/adapter/customized_ox/namespace.rb
 - lib/moxml/adapter/customized_ox/text.rb
+- lib/moxml/adapter/customized_rexml.rb
+- lib/moxml/adapter/customized_rexml/entity_reference.rb
 - lib/moxml/adapter/customized_rexml/formatter.rb
 - lib/moxml/adapter/headed_ox.rb
 - lib/moxml/adapter/libxml.rb
@@ -290,6 +297,8 @@ files:
 - spec/moxml/adapter/shared_examples/.gitkeep
 - spec/moxml/adapter/shared_examples/adapter_contract.rb
 - spec/moxml/adapter_spec.rb
+- spec/moxml/allocation_benchmark_spec.rb
+- spec/moxml/allocation_guard_spec.rb
 - spec/moxml/attribute_spec.rb
 - spec/moxml/builder_spec.rb
 - spec/moxml/cdata_spec.rb
@@ -304,9 +313,12 @@ files:
 - spec/moxml/element_spec.rb
 - spec/moxml/entity_registry_spec.rb
 - spec/moxml/error_spec.rb
+- spec/moxml/lazy_parse_spec.rb
 - spec/moxml/moxml_spec.rb
 - spec/moxml/namespace_spec.rb
 - spec/moxml/namespace_uri_validation_spec.rb
+- spec/moxml/node_cache_spec.rb
+- spec/moxml/node_set_cache_spec.rb
 - spec/moxml/node_set_spec.rb
 - spec/moxml/node_spec.rb
 - spec/moxml/processing_instruction_spec.rb
@@ -342,6 +354,7 @@ files:
 - spec/performance/thread_safety_spec.rb
 - spec/performance/xpath_benchmark_spec.rb
 - spec/spec_helper.rb
+- spec/support/allocation_helper.rb
 - spec/support/w3c_namespace_helpers.rb
 - spec/support/xml_matchers.rb
 - spec/unit/rexml_isolated_test.rb